@prmichaelsen/agentbase-core 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @prmichaelsen/agentbase-core
 
-Shared service infrastructure for agentbase projects — BaseService, auth, Firebase wrappers, logging, and common utilities.
+Shared service infrastructure for agentbase projects — BaseService, auth, Firebase wrappers, logging, typed errors, Result type, client SDK, and common utilities.
 
 ## Installation
 
@@ -25,33 +25,40 @@ 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 type { ... } from '@prmichaelsen/agentbase-core/types' // AuthUser, ServerSession, AuthResult
+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 for all services. Provides config injection, structured logging, and lifecycle hooks.
+Abstract base class with config injection, structured logging, lifecycle hooks, and state tracking.
 
 ```ts
-import { BaseService, type Logger } from '@prmichaelsen/agentbase-core/services'
+import { BaseService, ServiceState, type Logger } from '@prmichaelsen/agentbase-core/services'
 
-interface MyConfig { dbUrl: string }
-
-class UserService extends BaseService<MyConfig> {
-  constructor(config: MyConfig, logger: Logger) {
+class UserService extends BaseService<{ dbUrl: string }> {
+  constructor(config: { dbUrl: string }, logger: Logger) {
     super(config, logger)
   }
 
   async initialize() {
-    this.logger.info('Connecting to database', { url: this.config.dbUrl })
+    await super.initialize() // sets state to Initialized
+    this.logger.info('Connected', { url: this.config.dbUrl })
   }
 
-  async shutdown() {
-    this.logger.info('Closing connections')
+  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
@@ -74,9 +81,76 @@ const token = confirmations.generateToken({
 
 // Step 2: Consume token (single-use)
 const action = confirmations.consumeToken(token, 'user-123')
-if (action) {
-  // Execute the confirmed action
+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
@@ -84,20 +158,23 @@ if (action) {
 ### Server-Side (requires `@prmichaelsen/firebase-admin-sdk-v8`)
 
 ```ts
-import { getServerSession, requireAuth, requireAdmin, isAdmin } from '@prmichaelsen/agentbase-core/lib/auth'
+import {
+  getServerSession, requireAuth, requireAdmin, isAdmin,
+  handleAuthError,
+} from '@prmichaelsen/agentbase-core/lib/auth'
 
 // Get session from request cookies
 const session = await getServerSession(request)
 
-// Guard: returns null if authorized, Response(401) if not
-const authError = await requireAuth(request)
-if (authError) return authError
-
-// Guard: returns null if admin, Response(401/403) if not
-const adminError = await requireAdmin(request, 'admin@example.com,other@example.com')
-if (adminError) return adminError
+// 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)
+}
 
-// Check admin status
+// Boolean check (does not throw)
 const admin = await isAdmin(request, 'admin@example.com')
 ```
 
@@ -109,22 +186,15 @@ import {
   upgradeAnonymousAccount, logout, onAuthChange, getIdToken,
 } from '@prmichaelsen/agentbase-core/lib'
 
-// Initialize once
 initializeFirebase({ apiKey: '...', authDomain: '...', projectId: '...' })
 
-// Auth flows
 await signIn('user@example.com', 'password')
 await signUp('user@example.com', 'password')
 await signInAnonymously()
 await upgradeAnonymousAccount('user@example.com', 'password')
 await logout()
 
-// Listen for auth changes
-const unsubscribe = onAuthChange((user) => {
-  console.log(user ? `Signed in: ${user.uid}` : 'Signed out')
-})
-
-// Get ID token for API calls
+const unsubscribe = onAuthChange((user) => { /* ... */ })
 const token = await getIdToken()
 ```
 
@@ -133,100 +203,147 @@ const token = await getIdToken()
 ```ts
 import { isRealUser, isRealUserServer } from '@prmichaelsen/agentbase-core/lib/auth'
 
-// Client-side: works with any { isAnonymous?: boolean }
 if (isRealUser(user)) { /* non-anonymous */ }
-
-// Server-side: typed for AuthUser
-if (isRealUserServer(authUser)) { /* non-anonymous */ }
+if (isRealUserServer(authUser)) { /* non-anonymous, typed for AuthUser */ }
 ```
 
-## Logger
+## Client SDK
 
-Structured logger with automatic sensitive data redaction.
+Full REST client for agentbase.me with 17 service classes, compound workflows, and OAuth support.
+
+### Setup
 
 ```ts
-import { createLogger, authLogger, apiLogger, dbLogger, chatLogger } from '@prmichaelsen/agentbase-core/lib'
+import { HttpClient, AuthSvc, MemoriesSvc, OAuthClient } from '@prmichaelsen/agentbase-core/client'
 
-const logger = createLogger('MyService')
-logger.info('Processing request', { userId: 'abc', apiKey: 'secret' })
-// Output: [MyService] Processing request { userId: 'abc', apiKey: '[REDACTED]' }
+// With API key
+const http = new HttpClient({
+  baseUrl: 'https://agentbase.me',
+  auth: { type: 'apiKey', key: 'your-api-key' },
+})
 
-logger.debug('Only in development')  // Only logs when NODE_ENV=development
-logger.error('Failed', new Error('boom'))
+// 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' },
+})
 ```
 
-### Sanitization Utilities
+### SvcClient (1:1 REST mirror)
 
 ```ts
-import { sanitizeToken, sanitizeEmail, sanitizeUserId, sanitizeObject } from '@prmichaelsen/agentbase-core/lib'
+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 }
+}
 
-sanitizeToken('abc123...')     // "a1b2c3d4..."
-sanitizeEmail('john@x.com')   // "jo***@x.com"
-sanitizeUserId('user-12345')  // "user_user-123"
-sanitizeObject({ password: 'secret', name: 'ok' })  // { password: '[REDACTED]', name: 'ok' }
+// 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
 ```
 
-## Firebase Admin
+### OAuth Integration
 
 ```ts
-import { initFirebaseAdmin } from '@prmichaelsen/agentbase-core/lib'
+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,
+})
 
-// Reads FIREBASE_ADMIN_SERVICE_ACCOUNT_KEY and FIREBASE_PROJECT_ID from env
-initFirebaseAdmin()
+// 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')
 ```
 
-## Rate Limiter
+## Configuration
 
-Works with Cloudflare Workers Rate Limiting API.
+Centralized environment variable loading and validation.
 
 ```ts
-import { checkRateLimit, createRateLimitResponse, getRateLimitIdentifier } from '@prmichaelsen/agentbase-core/lib'
+import { loadConfig, validateConfig } from '@prmichaelsen/agentbase-core/config'
 
-const identifier = getRateLimitIdentifier(request, userId)
-const result = await checkRateLimit(rateLimiter, identifier, {
-  limit: 100,
-  period: 60,
-  keyPrefix: 'api',
-})
+const config = loadConfig() // reads from process.env
+validateConfig(config, { requireFirebaseAdmin: true }) // throws ValidationError if missing
 
-if (!result.success) {
-  return createRateLimitResponse(result) // 429 with proper headers
-}
+// Or pass custom env
+const config = loadConfig({ FIREBASE_PROJECT_ID: 'my-project', ... })
 ```
 
-## Utilities
+## Logger
+
+Structured logger with automatic sensitive data redaction.
 
 ```ts
-import { formatExactTime, getRelativeTime, linkifyText, generateUUID } from '@prmichaelsen/agentbase-core/lib'
+import { createLogger, authLogger, apiLogger } from '@prmichaelsen/agentbase-core/lib'
 
-formatExactTime('2026-03-15T14:30:00Z')  // "2:30 PM Sat 3/15/26"
-getRelativeTime('2026-03-15T14:00:00Z')  // "30m ago"
-linkifyText('Visit https://example.com')  // "Visit [https://example.com](https://example.com)"
-generateUUID()                             // "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5"
+const logger = createLogger('MyService')
+logger.info('Request', { userId: 'abc', apiKey: 'secret' })
+// Output: [MyService] Request { userId: 'abc', apiKey: '[REDACTED]' }
 ```
 
-## Types
+### Sanitization Utilities
 
 ```ts
-import type { AuthUser, ServerSession, AuthResult } from '@prmichaelsen/agentbase-core/types'
+import { sanitizeToken, sanitizeEmail, sanitizeUserId, sanitizeObject } from '@prmichaelsen/agentbase-core/lib'
 
-interface AuthUser {
-  uid: string
-  email: string | null
-  displayName: string | null
-  photoURL: string | null
-  emailVerified: boolean
-  isAnonymous: boolean
-}
+sanitizeToken('abc123...')    // "a1b2c3d4..."
+sanitizeEmail('john@x.com')  // "jo***@x.com"
+sanitizeObject({ password: 'secret', name: 'ok' })  // { password: '[REDACTED]', name: 'ok' }
+```
 
-interface ServerSession {
-  user: AuthUser
-}
+## Types
 
-interface AuthResult {
-  success: boolean
-  error?: string
-}
+```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