# @atpkeyserver/client Examples

This directory contains examples demonstrating how to use the ATP Keyserver client library.

## Available Examples

### basic-usage.ts

A comprehensive example showing all major features of the library:

1. **Crypto Functions Only** - Direct encrypt/decrypt without keyserver
2. **KeyserverClient Encryption** - Full flow with service auth
3. **KeyserverClient Decryption** - Retrieving and decrypting content
4. **Error Handling** - Proper error handling for all error types
5. **Cache Management** - Understanding and managing the cache
6. **Batch Decryption** - Processing multiple encrypted posts efficiently

## Prerequisites

### Node.js

Requires Node.js 22+ or Bun:

```bash
node --version  # Should be v22.0.0 or higher
```

### Dependencies

The example requires these packages:

```bash
# In the client directory
cd packages/client

# Install dependencies
bun install  # or npm install
```

**Required packages:**
- `@atpkeyserver/client` (this library)
- `@atproto/api` (for PDS integration)

## Running the Example

### Using Bun (Recommended)

```bash
bun run examples/basic-usage.ts
```

### Using Node.js

First, build the library:

```bash
npm run build
```

Then run with tsx or ts-node:

```bash
npx tsx examples/basic-usage.ts
```

## Expected Output

The example will run through all 6 examples sequentially, demonstrating:

- ✅ Successful crypto operations
- ⚠️ Expected failures in mock environment (keyserver not running)
- 📖 Educational comments about each operation
- 🎨 Colored output showing success/error states

**Note:** Examples 2-6 use mock data and will show expected errors since no actual keyserver is running. This is intentional and demonstrates error handling.

## Adapting for Production

To use in production, replace mock values with real ones:

### 1. Authenticate with PDS

```typescript
const agent = new AtpAgent({ service: 'https://bsky.social' })
await agent.login({
  identifier: 'your-handle.bsky.social',
  password: 'your-app-password'
})
```

### 2. Use Real Keyserver

```typescript
const keyserver = new KeyserverClient({
  keyserverDid: 'did:web:your-keyserver.com',  // Real keyserver DID
  getServiceAuthToken: async (aud, lxm) => {
    const { data } = await agent.com.atproto.server.getServiceAuth({
      aud,
      lxm,
      exp: Math.floor(Date.now() / 1000) + 60
    })
    return data.token
  }
})
```

### 3. Store/Retrieve Real Posts

Replace mock data with actual PDS operations:

```typescript
// Create encrypted post
const record = await agent.com.atproto.repo.putRecord({
  repo: agent.session.did,
  collection: 'app.bsky.feed.post',
  record: {
    encrypted_content: ciphertext,
    key_version: version,
    encrypted_at: new Date().toISOString(),
    visibility: 'followers'
  }
})

// Retrieve and decrypt
const post = await agent.getPost(postUri)
const plaintext = await keyserver.decrypt(
  postUri,
  groupId,
  post.encrypted_content,
  post.key_version
)
```

## Understanding the Output

### Successful Operations

```
✅ Crypto round-trip successful!
✅ Encrypted successfully!
```

These indicate operations completed without errors.

### Expected Errors (Mock Environment)

```
❌ Decryption failed (expected in mock environment)
```

Since no real keyserver is running, these errors are expected and demonstrate proper error handling.

### Error Types Demonstrated

The examples show how to handle:

- 🚫 **ForbiddenError** - User lost access
- 🔍 **NotFoundError** - Resource deleted
- 🔐 **DecryptionError** - Cannot decrypt (permanent)
- 🌐 **NetworkError** - Temporary network issue (can retry)

## Common Issues

### Import Errors

If you see module resolution errors:

```bash
# Ensure library is built
bun run build

# Check TypeScript paths are correct
cat tsconfig.json
```

### Runtime Errors

If crypto operations fail:

- Ensure Node.js 22+ (native crypto support)
- Check that `@noble/ciphers` is installed
- Verify hex-encoded keys are exactly 64 characters

## Next Steps

After understanding the examples:

1. Read [../README.md](../README.md) for complete API reference
2. Review [../../docs/ENCRYPTION_PROTOCOL.md](../../docs/ENCRYPTION_PROTOCOL.md) for protocol details
3. Check [../../docs/SECURITY.md](../../docs/SECURITY.md) for security best practices
4. Build your application using the patterns demonstrated

## Questions?

- Open an issue: https://codeberg.org/juandjara/atp-keyserver/issues
- Read the docs: [../../docs/](../../docs/)