docs

Author: izadoesdev

docs/.gitignore

@@ -0,0 +1,19 @@
+node_modules
+
+.DS_Store
+.cache
+.vercel
+.output
+.nitro
+/build/
+/api/
+/server/build
+/public/build
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+.tanstack
+
+src/routeTree.gen.ts
+.source

docs/README.md

@@ -0,0 +1,14 @@
+# docs
+
+This is a Tanstack Start application generated with
+[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+
+Run development server:
+
+```bash
+npm run dev
+# or
+pnpm dev
+# or
+yarn dev
+```

docs/bun.lock

@@ -0,0 +1,126 @@
+---
+title: Audit Logs
+description: Query and manage audit logs
+icon: FileSearch
+---
+
+# Audit Logs
+
+Methods for querying and managing audit logs (requires `auditLogs: true` in configuration).
+
+## getLogs()
+
+Query audit logs.
+
+```typescript
+// Get logs for a specific key
+const logs = await keys.getLogs({
+  keyId: 'key_123',
+  limit: 100,
+})
+
+// Get logs by action
+const revokedLogs = await keys.getLogs({
+  action: 'revoked',
+  startDate: '2025-01-01',
+})
+
+// Get logs for an owner
+const ownerLogs = await keys.getLogs({
+  ownerId: 'user_123',
+  limit: 50,
+  offset: 0,
+})
+```
+
+**Returns**: `Promise<AuditLog[]>`
+
+### AuditLogQuery Options
+
+```typescript
+{
+  keyId?: string          // Filter by key ID
+  ownerId?: string       // Filter by owner ID
+  action?: AuditAction   // Filter by action
+  startDate?: string     // Filter by start date (ISO timestamp)
+  endDate?: string       // Filter by end date (ISO timestamp)
+  limit?: number         // Maximum results (default: 100)
+  offset?: number        // Pagination offset (default: 0)
+}
+```
+
+## countLogs()
+
+Count audit logs matching a query.
+
+```typescript
+const count = await keys.countLogs({
+  action: 'created',
+  startDate: '2025-01-01',
+})
+```
+
+**Returns**: `Promise<number>`
+
+## deleteLogs()
+
+Delete audit logs matching a query.
+
+```typescript
+// Delete old logs
+const deleted = await keys.deleteLogs({
+  endDate: '2024-01-01',
+})
+```
+
+**Returns**: `Promise<number>` (number of logs deleted)
+
+## clearLogs()
+
+Clear all logs for a specific key.
+
+```typescript
+await keys.clearLogs('key_123')
+```
+
+**Returns**: `Promise<number>` (number of logs deleted)
+
+## getLogStats()
+
+Get statistics about audit logs for an owner.
+
+```typescript
+const stats = await keys.getLogStats('user_123')
+
+console.log(stats.total)              // Total number of logs
+console.log(stats.byAction.created)   // Number of created actions
+console.log(stats.byAction.revoked)   // Number of revoked actions
+console.log(stats.lastActivity)      // Last activity timestamp
+```
+
+**Returns**: `Promise<AuditLogStats>`
+
+### AuditLogStats Structure
+
+```typescript
+{
+  total: number
+  byAction: {
+    created?: number
+    revoked?: number
+    rotated?: number
+    enabled?: number
+    disabled?: number
+  }
+  lastActivity: string | null
+}
+```
+
+## Audit Actions
+
+- `'created'` - Key was created
+- `'revoked'` - Key was revoked
+- `'rotated'` - Key was rotated
+- `'enabled'` - Key was enabled
+- `'disabled'` - Key was disabled
+

docs/content/docs/api-reference/audit-logs.mdx

@@ -0,0 +1,72 @@
+---
+title: createKeys()
+description: Create a new API key manager instance
+icon: KeyRound
+---
+
+# createKeys()
+
+Creates a new API key manager instance.
+
+## Signature
+
+```typescript
+function createKeys(config?: ConfigInput): ApiKeyManager
+```
+
+## Parameters
+
+- **`config`** (ConfigInput, optional): Configuration options
+
+## Returns
+
+An `ApiKeyManager` instance for creating and verifying keys.
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { createKeys } from 'keypal'
+
+const keys = createKeys({
+  prefix: 'sk_',
+})
+```
+
+### With Redis Storage
+
+```typescript
+import Redis from 'ioredis'
+
+const redis = new Redis()
+
+const keys = createKeys({
+  prefix: 'sk_live_',
+  storage: 'redis',
+  redis,
+  cache: true,
+  cacheTtl: 300,
+})
+```
+
+### With Custom Storage
+
+```typescript
+import { createKeys, type Storage } from 'keypal'
+
+const customStorage: Storage = {
+  save: async (record) => { /* ... */ },
+  findByHash: async (keyHash) => { /* ... */ },
+  // ... other methods
+}
+
+const keys = createKeys({
+  storage: customStorage,
+})
+```
+
+## Configuration Options
+
+See the [Configuration](/docs/getting-started/configuration) guide for all available options.
+

docs/content/docs/api-reference/create-keys.mdx

@@ -0,0 +1,157 @@
+---
+title: Key Management
+description: Create, list, find, and manage API keys
+icon: KeyRound
+---
+
+# Key Management
+
+Methods for creating, listing, finding, and managing API keys.
+
+## create()
+
+Create a new API key.
+
+```typescript
+const { key, record } = await keys.create({
+  ownerId: 'user_123',
+  name: 'Production Key',
+  description: 'Key for production API access',
+  scopes: ['read', 'write'],
+  tags: ['production', 'api'],
+  resources: {
+    'project:123': ['read', 'write'],
+  },
+  expiresAt: '2025-12-31',
+  enabled: true,
+})
+```
+
+**Returns**: `{ key: string, record: ApiKeyRecord }`
+
+> **Important**: The `key` is only returned once during creation. Store it securely!
+
+## list()
+
+List all keys for an owner.
+
+```typescript
+const userKeys = await keys.list('user_123')
+```
+
+**Returns**: `Promise<ApiKeyRecord[]>`
+
+## findById()
+
+Find a key by its ID.
+
+```typescript
+const keyRecord = await keys.findById('key_123')
+```
+
+**Returns**: `Promise<ApiKeyRecord | null>`
+
+## findByHash()
+
+Find a key by its hash.
+
+```typescript
+const keyByHash = await keys.findByHash('hashed_key_value')
+```
+
+**Returns**: `Promise<ApiKeyRecord | null>`
+
+## findByTag()
+
+Find keys with a specific tag.
+
+```typescript
+const taggedKeys = await keys.findByTag('production')
+const userTaggedKeys = await keys.findByTag('production', 'user_123')
+```
+
+**Returns**: `Promise<ApiKeyRecord[]>`
+
+## findByTags()
+
+Find keys with any of the specified tags.
+
+```typescript
+const taggedKeys = await keys.findByTags(['production', 'staging'])
+const userTaggedKeys = await keys.findByTags(['production', 'staging'], 'user_123')
+```
+
+**Returns**: `Promise<ApiKeyRecord[]>`
+
+## revoke()
+
+Revoke (soft delete) a key.
+
+```typescript
+await keys.revoke('key_123', {
+  userId: 'admin_456',
+  metadata: { reason: 'Security breach' },
+})
+```
+
+**Returns**: `Promise<void>`
+
+## revokeAll()
+
+Revoke all keys for an owner.
+
+```typescript
+await keys.revokeAll('user_123')
+```
+
+**Returns**: `Promise<void>`
+
+## enable()
+
+Enable a disabled key.
+
+```typescript
+await keys.enable('key_123', {
+  userId: 'admin_456',
+})
+```
+
+**Returns**: `Promise<void>`
+
+## disable()
+
+Disable a key.
+
+```typescript
+await keys.disable('key_123', {
+  userId: 'admin_456',
+})
+```
+
+**Returns**: `Promise<void>`
+
+## rotate()
+
+Rotate a key (create new, mark old as revoked).
+
+```typescript
+const { key: newKey, record: newRecord, oldRecord } = await keys.rotate('key_123', {
+  name: 'Updated Key',
+  scopes: ['read', 'write', 'admin'],
+})
+```
+
+**Returns**: `Promise<{ key: string, record: ApiKeyRecord, oldRecord: ApiKeyRecord }>`
+
+## updateLastUsed()
+
+Manually update the last used timestamp.
+
+```typescript
+await keys.updateLastUsed('key_123')
+```
+
+**Returns**: `Promise<void>`
+
+> **Note**: This is automatically called when `autoTrackUsage` is enabled and `skipTracking` is not set.
+