@prmichaelsen/agentbase-core 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,351 @@
+# @prmichaelsen/agentbase-core
+
+Shared service infrastructure for agentbase projects — BaseService, auth, Firebase wrappers, logging, typed errors, Result type, client SDK, and common utilities.
+
+## Installation
+
+```bash
+npm install @prmichaelsen/agentbase-core
+```
+
+### Peer Dependencies
+
+All peer dependencies are **optional** — install only what you use:
+
+| Package | When needed |
+|---------|-------------|
+| `@prmichaelsen/firebase-admin-sdk-v8` | Server-side auth (`getServerSession`, `requireAuth`, `createSessionCookie`) |
+| `firebase` | Client-side auth (`signIn`, `signUp`, `initializeFirebase`) |
+| `jsonwebtoken` | JWT handling (if used directly) |
+
+## Export Entry Points
+
+```ts
+import { ... } from '@prmichaelsen/agentbase-core'          // everything
+import { ... } from '@prmichaelsen/agentbase-core/services'  // BaseService, ConfirmationTokenService
+import { ... } from '@prmichaelsen/agentbase-core/lib'       // logger, firebase, utilities
+import { ... } from '@prmichaelsen/agentbase-core/lib/auth'  // server auth guards
+import { ... } from '@prmichaelsen/agentbase-core/types'     // AuthUser, Result, branded types
+import { ... } from '@prmichaelsen/agentbase-core/client'    // HTTP client, SvcClient, AppClient, OAuth
+import { ... } from '@prmichaelsen/agentbase-core/config'    // loadConfig, validateConfig
+```
+
+## Services
+
+### BaseService
+
+Abstract base class with config injection, structured logging, lifecycle hooks, and state tracking.
+
+```ts
+import { BaseService, ServiceState, type Logger } from '@prmichaelsen/agentbase-core/services'
+
+class UserService extends BaseService<{ dbUrl: string }> {
+  constructor(config: { dbUrl: string }, logger: Logger) {
+    super(config, logger)
+  }
+
+  async initialize() {
+    await super.initialize() // sets state to Initialized
+    this.logger.info('Connected', { url: this.config.dbUrl })
+  }
+
+  async findUser(id: string) {
+    this.ensureInitialized() // throws if not initialized
+    // ...
+  }
+}
+
+const svc = new UserService({ dbUrl: '...' }, logger)
+svc.getState() // ServiceState.Uninitialized
+await svc.initialize()
+svc.getState() // ServiceState.Initialized
+```
+
+### ConfirmationTokenService
+
+In-memory token store for two-step confirmation flows. Tokens are single-use, user-scoped, and expire after TTL.
+
+```ts
+import { ConfirmationTokenService } from '@prmichaelsen/agentbase-core/services'
+
+const confirmations = new ConfirmationTokenService(5 * 60 * 1000) // 5 min TTL
+
+// Step 1: Generate token
+const token = confirmations.generateToken({
+  type: 'delete-account',
+  userId: 'user-123',
+  params: { accountId: 'abc' },
+  summary: 'Delete account abc',
+  createdAt: Date.now(),
+})
+
+// Step 2: Consume token (single-use)
+const action = confirmations.consumeToken(token, 'user-123')
+if (action) { /* execute */ }
+```
+
+## Error Types
+
+Typed error hierarchy with discriminated `kind` field and HTTP status mapping.
+
+```ts
+import {
+  UnauthorizedError, ForbiddenError, ValidationError, NotFoundError,
+  ConflictError, RateLimitError, ExternalError, InternalError,
+  isAppError, errorToStatusCode,
+} from '@prmichaelsen/agentbase-core'
+
+// Throw typed errors
+throw new ValidationError('Email is required', { field: 'email' })
+throw new NotFoundError('User not found')
+
+// Type guard
+try {
+  await doSomething()
+} catch (err) {
+  if (isAppError(err)) {
+    console.log(err.kind)       // 'VALIDATION' | 'NOT_FOUND' | ...
+    console.log(err.statusCode) // 400, 404, ...
+    console.log(err.context)    // { field: 'email' }
+  }
+}
+
+// Map to HTTP status
+const status = errorToStatusCode(err) // 400 for ValidationError, 500 for unknown
+```
+
+| Error | Kind | Status |
+|-------|------|--------|
+| `ValidationError` | `VALIDATION` | 400 |
+| `UnauthorizedError` | `UNAUTHORIZED` | 401 |
+| `ForbiddenError` | `FORBIDDEN` | 403 |
+| `NotFoundError` | `NOT_FOUND` | 404 |
+| `ConflictError` | `CONFLICT` | 409 |
+| `RateLimitError` | `RATE_LIMIT` | 429 |
+| `ExternalError` | `EXTERNAL` | 502 |
+| `InternalError` | `INTERNAL` | 500 |
+
+## Result Type
+
+Discriminated `Result<T, E>` for operations where failure is expected.
+
+```ts
+import { ok, err, isOk, isErr, mapOk, andThen, getOrElse, tryCatchAsync } from '@prmichaelsen/agentbase-core'
+import type { Result } from '@prmichaelsen/agentbase-core'
+
+// Create results
+const success: Result<number> = ok(42)
+const failure: Result<number, string> = err('not found')
+
+// Type guards
+if (isOk(success)) console.log(success.value)  // 42
+if (isErr(failure)) console.log(failure.error)  // 'not found'
+
+// Combinators
+const doubled = mapOk(ok(5), x => x * 2)              // Ok(10)
+const chained = andThen(ok(5), x => x > 0 ? ok(x) : err('negative'))
+const value = getOrElse(err('fail'), 0)                // 0
+
+// Wrap async functions
+const result = await tryCatchAsync(
+  () => fetchUser(id),
+  (e) => new NotFoundError('User not found')
+)
+```
+
+## Auth
+
+### Server-Side (requires `@prmichaelsen/firebase-admin-sdk-v8`)
+
+```ts
+import {
+  getServerSession, requireAuth, requireAdmin, isAdmin,
+  handleAuthError,
+} from '@prmichaelsen/agentbase-core/lib/auth'
+
+// Get session from request cookies
+const session = await getServerSession(request)
+
+// Guards throw typed errors — use try-catch
+try {
+  await requireAuth(request)        // throws UnauthorizedError
+  await requireAdmin(request, 'admin@example.com') // throws Unauthorized or Forbidden
+} catch (error) {
+  return handleAuthError(error)     // converts to Response(401/403/500)
+}
+
+// Boolean check (does not throw)
+const admin = await isAdmin(request, 'admin@example.com')
+```
+
+### Client-Side (requires `firebase`)
+
+```ts
+import {
+  initializeFirebase, signIn, signUp, signInAnonymously,
+  upgradeAnonymousAccount, logout, onAuthChange, getIdToken,
+} from '@prmichaelsen/agentbase-core/lib'
+
+initializeFirebase({ apiKey: '...', authDomain: '...', projectId: '...' })
+
+await signIn('user@example.com', 'password')
+await signUp('user@example.com', 'password')
+await signInAnonymously()
+await upgradeAnonymousAccount('user@example.com', 'password')
+await logout()
+
+const unsubscribe = onAuthChange((user) => { /* ... */ })
+const token = await getIdToken()
+```
+
+### Helpers
+
+```ts
+import { isRealUser, isRealUserServer } from '@prmichaelsen/agentbase-core/lib/auth'
+
+if (isRealUser(user)) { /* non-anonymous */ }
+if (isRealUserServer(authUser)) { /* non-anonymous, typed for AuthUser */ }
+```
+
+## Client SDK
+
+Full REST client for agentbase.me with 17 service classes, compound workflows, and OAuth support.
+
+### Setup
+
+```ts
+import { HttpClient, AuthSvc, MemoriesSvc, OAuthClient } from '@prmichaelsen/agentbase-core/client'
+
+// With API key
+const http = new HttpClient({
+  baseUrl: 'https://agentbase.me',
+  auth: { type: 'apiKey', key: 'your-api-key' },
+})
+
+// With OAuth bearer token
+const http = new HttpClient({
+  baseUrl: 'https://agentbase.me',
+  auth: { type: 'bearer', token: () => oauthClient.getValidToken() },
+})
+
+// With session cookie (browser)
+const http = new HttpClient({
+  baseUrl: 'https://agentbase.me',
+  auth: { type: 'cookie' },
+})
+```
+
+### SvcClient (1:1 REST mirror)
+
+```ts
+const memories = new MemoriesSvc(http)
+
+// All methods return SdkResponse<T> — never throws
+const result = await memories.search({ query: 'vacation photos', mode: 'semantic' })
+if (result.error) {
+  console.error(result.error.message)
+} else {
+  console.log(result.data) // { data: Memory[], total: number }
+}
+
+// Or use throwOnError() for cleaner async/await
+const { data } = await memories.feed({ limit: 10 }).then(r => r.throwOnError())
+```
+
+Available services: `AuthSvc`, `OAuthSvc`, `MemoriesSvc`, `ConversationsSvc`, `ProfilesSvc`, `GroupsSvc`, `DmsSvc`, `SearchSvc`, `NotificationsSvc`, `RelationshipsSvc`, `BoardsSvc`, `TokensSvc`, `IntegrationsSvc`, `SettingsSvc`, `PaymentsSvc`, `UsageSvc`, `JobsSvc`
+
+### AppClient (compound workflows)
+
+```ts
+import { AppClient } from '@prmichaelsen/agentbase-core/client'
+
+const app = new AppClient({ auth, memories, conversations, profiles, groups, dms, search, notifications })
+
+await app.loginAndGetSession(idToken)
+await app.searchAndFetchMemories('vacation', 5)
+await app.createGroupAndInvite('Book Club', 'Monthly reads', ['user-1', 'user-2'])
+await app.getFullProfile('user-123') // profile + memory count
+await app.startDm('user-456')       // find existing or create new
+```
+
+### OAuth Integration
+
+```ts
+import {
+  OAuthClient, generateCodeVerifier, generateCodeChallenge,
+  buildAuthorizationUrl,
+} from '@prmichaelsen/agentbase-core/client'
+
+// 1. Generate PKCE params
+const verifier = generateCodeVerifier()
+const challenge = await generateCodeChallenge(verifier)
+
+// 2. Build authorization URL
+const url = buildAuthorizationUrl('https://agentbase.me', {
+  clientId: 'your-client-id',
+  redirectUri: 'http://localhost:3000/callback',
+  scope: 'read write',
+  codeChallenge: challenge,
+})
+
+// 3. After redirect, exchange code for tokens
+const oauth = new OAuthClient(http, { clientId: 'your-client-id' })
+await oauth.exchangeCode(code, redirectUri, verifier)
+
+// 4. Get valid token (auto-refreshes if expired)
+const token = await oauth.getValidToken()
+
+// API token shortcut
+await oauth.exchangeApiToken('your-api-token')
+```
+
+## Configuration
+
+Centralized environment variable loading and validation.
+
+```ts
+import { loadConfig, validateConfig } from '@prmichaelsen/agentbase-core/config'
+
+const config = loadConfig() // reads from process.env
+validateConfig(config, { requireFirebaseAdmin: true }) // throws ValidationError if missing
+
+// Or pass custom env
+const config = loadConfig({ FIREBASE_PROJECT_ID: 'my-project', ... })
+```
+
+## Logger
+
+Structured logger with automatic sensitive data redaction.
+
+```ts
+import { createLogger, authLogger, apiLogger } from '@prmichaelsen/agentbase-core/lib'
+
+const logger = createLogger('MyService')
+logger.info('Request', { userId: 'abc', apiKey: 'secret' })
+// Output: [MyService] Request { userId: 'abc', apiKey: '[REDACTED]' }
+```
+
+### Sanitization Utilities
+
+```ts
+import { sanitizeToken, sanitizeEmail, sanitizeUserId, sanitizeObject } from '@prmichaelsen/agentbase-core/lib'
+
+sanitizeToken('abc123...')    // "a1b2c3d4..."
+sanitizeEmail('john@x.com')  // "jo***@x.com"
+sanitizeObject({ password: 'secret', name: 'ok' })  // { password: '[REDACTED]', name: 'ok' }
+```
+
+## Types
+
+```ts
+import type { AuthUser, ServerSession, Result, UserId, EmailAddress } from '@prmichaelsen/agentbase-core/types'
+import { toUserId, toEmailAddress, toTimestamp } from '@prmichaelsen/agentbase-core/types'
+
+// Branded primitives prevent mixing IDs
+const uid: UserId = toUserId('firebase-uid')
+const email: EmailAddress = toEmailAddress('user@example.com')
+```
+
+## License
+
+MIT