# Getting Started

This guide shows the common setup and first-use patterns for consuming CapyKit from a .NET 8 project.

## Install

Add CapyKit to your project from NuGet:

```bash
dotnet add package CapyKit
```

If you are working from a local checkout instead, reference the project directly:

```bash
dotnet add reference ../CapyKit/CapyKit.csproj
```

## Add Namespaces

Most APIs live in one of three namespaces:

```csharp
using CapyKit;
using CapyKit.Extensions;
using CapyKit.Helpers;
```

Use `CapyKit` for core types such as `Password`, `Pool<T>`, and `CapyEventReporter`. Use `CapyKit.Extensions` for extension methods. Use `CapyKit.Helpers` for serialization, compression, security, keys, language, and calculation helpers.

## Work With Strings

```csharp
using CapyKit.Extensions;

string? suppliedName = "";
string name = suppliedName.IfNullOrWhiteSpace("Guest");
```

`IfNullOrEmpty` and `IfNullOrWhiteSpace` return the original value when it is usable and return your replacement value when it is not.

## Page And Filter Collections

```csharp
using CapyKit.Extensions;

var activeUsers = users.Filter(user => user.Disabled);
var secondPage = activeUsers.Page(pageNumber: 2, pageSize: 25);
int pageCount = activeUsers.PageCount(pageSize: 25);
```

`Filter` removes items that match the predicate. `Page` uses natural page numbering, so the first page is `1`.

## Serialize And Compress Data

```csharp
using CapyKit.Helpers;

var json = SerializationHelper.SerializeToString(order);
var copy = SerializationHelper.Deserialize<Order>(json);

var compressed = CompressionHelper.CompressToString(order);
var restored = CompressionHelper.Decompress<Order>(compressed);
```

Serialization uses `System.Text.Json`. Compression stores the serialized JSON payload using gzip; `CompressToString` returns a Base64 representation for easier storage or transport.

## Hash And Verify Passwords

```csharp
using CapyKit;
using CapyKit.Helpers;

Password storedPassword = SecurityHelper.Pbkdf2("correct horse battery staple");

bool passwordMatches = SecurityHelper.CompareHashedPassword(
    storedPassword,
    "correct horse battery staple",
    storedPassword.Salt,
    Password.Pbkdf2Algorithm);
```

`SecurityHelper.Pbkdf2` creates a `Password` with a random salt. Store the hash, salt, and algorithm information required by your application, then compare future password attempts using the same salt and algorithm.

## Generate Random Values

```csharp
using CapyKit.Helpers;

string token = SecurityHelper.GetRandomString(32);
string password = SecurityHelper.GetRandomPassword(
    20,
    ValidCharacterCollection.Lowercase,
    ValidCharacterCollection.Uppercase,
    ValidCharacterCollection.Numbers,
    ValidCharacterCollection.Special);
```

Random string and password generation use .NET cryptographic random number generation.

## Create And Validate Keys

```csharp
using System.Text;
using CapyKit.Helpers;

var keyHelper = new KeyHelper();
keyHelper.SetMasterKeyAccessor(() => Encoding.UTF8.GetBytes("replace-with-your-master-key"));
keyHelper.SetSaltSizeAccessor(() => 8);
keyHelper.SetNumPartsAccessor(() => 4);

string key = keyHelper.GenerateKey();
bool valid = keyHelper.ValidateKey(key);
```

`KeyHelper` uses an application-provided master key to sign generated key material. Keep the master key secret and stable for keys that must remain valid over time.

## Subscribe To CapyKit Events

```csharp
using CapyKit;

CapyEventReporter.Subscribe(
    e => Console.WriteLine($"[{e.Level}] {e.MethodName}: {e.Message}"),
    EventLevel.Warning);
```

CapyKit does not require a logging framework. Subscribe to events and forward them to whatever logging or telemetry system your application already uses.

## Browse The API

For the full list of namespaces, types, overloads, and member signatures, open the generated [API Reference](api/toc.yml).