foundation-sdk 0.1.14 → 0.2.0

package/README.md

@@ -1,89 +1,194 @@
 # foundation-sdk
 
-SDK for building applications that embed within the Foundation container.
+SDK for building applications on the Foundation platform. Works in two modes:
 
-> **Future Migration:** This package will be renamed to `@foundation/iframe-sdk` when the npm organization is set up.
+- **Iframe mode** — app embeds inside the Foundation container, communicates via postMessage
+- **Standalone mode** — app runs independently, communicates directly with the API via HTTP
+
+Same API surface in both modes. Your code doesn't change.
 
 ## Installation
 
+### npm / yarn / pnpm
+
 ```bash
 npm install foundation-sdk
 ```
 
-Vue is an optional peer dependency - only required if using the `/vue` entry point:
+Vue is an optional peer dependency — only needed if using the `/vue` entry point:
 
 ```bash
 npm install foundation-sdk vue
 ```
 
+### CDN / Script Tag
+
+For apps that don't use a bundler, load the SDK directly via a script tag. This exposes `window.FoundationSDK`.
+
+```html
+<script src="https://unpkg.com/foundation-sdk/dist/foundation-sdk.browser.js"></script>
+<script>
+  const sdk = FoundationSDK.createFoundationClient()
+
+  sdk.ready.then(function() {
+    console.log('SDK ready, user:', sdk.auth.user)
+  })
+</script>
+```
+
 ## Quick Start
 
-### Vanilla TypeScript/JavaScript
+### Iframe Mode (embedded in container)
 
 ```typescript
 import { createFoundationClient } from 'foundation-sdk'
 
 const sdk = createFoundationClient()
-
-// Wait for SDK to be ready (receives initial state from container)
 await sdk.ready
 
-// Access current user
-console.log(sdk.auth.user)
-
-// Fetch data
 const { items } = await sdk.db.list('projects', { limit: 10 })
-
-// Show a toast notification
 await sdk.ui.toast('Hello from embedded app!', 'success')
 ```
 
+### Standalone Mode (your own app)
+
+```typescript
+import { createFoundationClient } from 'foundation-sdk'
+import { createAuth0Client } from '@auth0/auth0-spa-js'
+
+// Set up your auth provider
+const auth0 = await createAuth0Client({
+  domain: 'your-domain.auth0.com',
+  clientId: 'your-client-id',
+  authorizationParams: { audience: 'your-api' }
+})
+
+// Create the SDK with your config
+const sdk = createFoundationClient({
+  configUrl: 'https://api.your-app.com',
+  tenantId: 'your-tenant-id',
+  appId: 'your-app-id',
+  auth: auth0  // Auth0 client satisfies MinimalAuthClient
+})
+
+await sdk.ready
+
+const { items } = await sdk.db.list('projects', { limit: 10 })
+```
+
+You own auth completely — provider choice, login pages, token refresh. The SDK just needs an auth client that can provide tokens.
+
 ### Vue 3
 
 ```typescript
+// Iframe mode
 import { useFoundation } from 'foundation-sdk/vue'
-
-// In your component setup
 const { isReady, user, isDark, db, ui } = useFoundation()
+```
 
-// Reactive state is automatically updated
-watch(isReady, (ready) => {
-  if (ready) {
-    console.log('SDK ready, user:', user.value)
-  }
+```typescript
+// Standalone mode — configure once at app startup
+import { configureFoundation, useFoundation } from 'foundation-sdk/vue'
+
+configureFoundation({
+  configUrl: 'https://api.your-app.com',
+  tenantId: 'your-tenant-id',
+  appId: 'your-app-id',
+  auth: auth0Client
 })
 
-// Use services directly
-const { items } = await db.list('projects', { limit: 10 })
-await ui.toast('Hello!', 'success')
+// Then useFoundation() in any component as normal
+const { isReady, db, ui } = useFoundation()
 ```
 
+## How It Works
+
+### Iframe Mode
+
+The SDK communicates with the Foundation container via `postMessage`. On initialization, a three-step handshake establishes a secure session:
+
+1. SDK sends `SDK_HELLO` to the container (retries with exponential backoff)
+2. Container responds with `SDK_READY` containing initial state and a session nonce
+3. SDK sends `SDK_ACK` to confirm — container flushes any buffered events
+
+All subsequent messages include the session nonce for authentication. The container validates every message against the nonce and the iframe's origin.
+
+### Standalone Mode
+
+The SDK makes HTTP calls directly to the Foundation API. On initialization:
+
+1. SDK calls `auth.getTokenSilently()` to get a JWT
+2. JWT is parsed to extract API URLs (`apiBaseUrl`, `accountBaseUrl`)
+3. SDK fetches config from `{configUrl}/api/v1/config/init`
+4. `sdk.ready` resolves — all services are available
+
+Every request includes `Authorization`, `X-Foundation-Mvp-Application-Id`, and `X-Foundation-Mvp-Tenant-Id` headers. Tokens are refreshed automatically via the auth client on each request.
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for protocol details.
+
+---
+
 ## API Reference
 
 ### Initialization
 
-#### `createFoundationClient(): FoundationClient`
+#### `createFoundationClient(): FoundationClient` (iframe mode)
 
-Creates or returns the singleton SDK client instance.
+Creates or returns the singleton SDK client instance. Immediately begins the handshake with the container.
 
 ```typescript
 const sdk = createFoundationClient()
+await sdk.ready
+```
 
-// Check if ready
-if (sdk.isReady) {
-  // SDK has received initial state
-}
+If the container does not respond after ~6 seconds of retries, `sdk.ready` rejects with an error.
 
-// Wait for ready
+#### `createFoundationClient(options: StandaloneOptions): FoundationClient` (standalone mode)
+
+Creates a standalone SDK client that communicates directly with the API via HTTP.
+
+```typescript
+import { createFoundationClient } from 'foundation-sdk'
+import type { StandaloneOptions, MinimalAuthClient } from 'foundation-sdk'
+
+const sdk = createFoundationClient({
+  configUrl: 'https://api.your-app.com',  // base URL for /api/v1/config/init
+  tenantId: 'your-tenant-id',
+  appId: 'your-app-id',
+  auth: yourAuthClient,                    // implements MinimalAuthClient
+  version: '1.0.0'                         // optional, defaults to '0.0.0'
+})
 await sdk.ready
+```
 
-// Access available entity definitions
-console.log(sdk.entities) // EntityDefinition[]
+The `auth` parameter must implement `MinimalAuthClient`:
+
+```typescript
+interface MinimalAuthClient {
+  loginWithRedirect(options?: Record<string, unknown>): Promise<void>
+  logout(options?: Record<string, unknown>): void | Promise<void>
+  getUser(): Promise<{ id: string; email: string; name?: string; picture?: string } | undefined>
+  getTokenSilently(options?: Record<string, unknown>): Promise<string>
+  isAuthenticated(): Promise<boolean>
+  handleRedirectCallback(url?: string): Promise<unknown>
+}
 ```
 
+Auth0 (`@auth0/auth0-spa-js`) and Cognito client instances satisfy this interface natively.
+
+**Standalone mode differences:**
+- `sdk.router` — no-op (manage your own routing)
+- `sdk.ui.toast` — logs to console
+- `sdk.ui.confirm` — uses `window.confirm()`
+- `sdk.ui.loading` / `sdk.ui.banner` — no-ops
+- `sdk.theme` — manages local state (persisted to localStorage)
+- `sdk.integration.connect()` — throws (requires platform UI)
+- `sdk.log` — outputs to console
+- `sdk.onEntityChange` — does not receive WebSocket push events
+
 #### `resetFoundationClient(): void`
 
-Resets the singleton instance. Useful for testing or re-initialization.
+Resets the singleton instance, cleans up transport and all state. Useful for testing or re-initialization.
 
 ```typescript
 import { resetFoundationClient } from 'foundation-sdk'
@@ -97,17 +202,15 @@ resetFoundationClient()
 
 ```typescript
 interface AuthService {
-  readonly user: User | null        // Current user
-  readonly isAuthenticated: boolean // Is user logged in
-  getToken(): Promise<string>       // Get auth token
-  login(): Promise<void>            // Trigger login flow
-  logout(): Promise<void>           // Trigger logout
-  onChange(callback): () => void    // Subscribe to auth changes
+  readonly user: User | null
+  readonly isAuthenticated: boolean
+  getToken(): Promise<string>
+  login(): Promise<void>
+  logout(): Promise<void>
+  onChange(callback: (user: User | null) => void): () => void
 }
 ```
 
-**Example:**
-
 ```typescript
 // Get current user
 const user = sdk.auth.user
@@ -126,12 +229,15 @@ const unsubscribe = sdk.auth.onChange((user) => {
 
 ### Database (`sdk.db`)
 
+All database operations are scoped to entities defined in the app configuration. The container rejects requests for entities or methods not in the app's entity definitions.
+
 ```typescript
 interface DbService {
   list<T>(entity: string, options?: ListOptions): Promise<{ items: T[]; nextCursor?: string }>
   get<T>(entity: string, id: string): Promise<T>
   create<T>(entity: string, data: Partial<T>): Promise<T>
   update<T>(entity: string, id: string, updates: Partial<T>): Promise<T>
+  save<T>(entity: string, data: Partial<T>): Promise<T>
   delete(entity: string, id: string): Promise<void>
 }
 
@@ -144,8 +250,6 @@ interface ListOptions {
 }
 ```
 
-**Example:**
-
 ```typescript
 // List with filters and pagination
 const { items, nextCursor } = await sdk.db.list('projects', {
@@ -169,6 +273,9 @@ const updated = await sdk.db.update('projects', 'project-123', {
   name: 'Updated Name'
 })
 
+// Save (create or update — tries update first, falls back to create)
+await sdk.db.save('projects', { key: 'settings', value: '...' })
+
 // Delete
 await sdk.db.delete('projects', 'project-123')
 ```
@@ -192,8 +299,6 @@ interface UIService {
 }
 ```
 
-**Example:**
-
 ```typescript
 // Toast notifications
 await sdk.ui.toast('Operation successful', 'success')
@@ -206,19 +311,18 @@ if (confirmed) {
 }
 
 // Loading overlay
-sdk.ui.loading.show('Processing...')
+await sdk.ui.loading.show('Processing...')
 try {
   await doSomething()
 } finally {
-  sdk.ui.loading.hide()
+  await sdk.ui.loading.hide()
 }
 
-// Banners
+// Banners (persistent messages at the top of the container)
 const { bannerId } = await sdk.ui.banner.show('New feature available!', {
   type: 'info',
   dismissible: true
 })
-// Later...
 await sdk.ui.banner.hide(bannerId)
 ```
 
@@ -226,20 +330,20 @@ await sdk.ui.banner.hide(bannerId)
 
 ### Router (`sdk.router`)
 
+The container owns the URL bar. Your app reads and writes the route through the SDK, which proxies to the container's Vue Router.
+
 ```typescript
 interface RouterService {
   readonly path: string
   readonly query: Record<string, string>
   readonly hash: string
-  push(path: string, options?: NavOptions): Promise<void>
-  replace(path: string, options?: NavOptions): Promise<void>
+  push(path: string, options?: { query?: Record<string, string>; hash?: string }): Promise<void>
+  replace(path: string, options?: { query?: Record<string, string>; hash?: string }): Promise<void>
   setQuery(params: Record<string, string>, options?: { replace?: boolean }): Promise<void>
   onChange(callback: (route: RouterState) => void): () => void
 }
 ```
 
-**Example:**
-
 ```typescript
 // Navigate
 await sdk.router.push('/dashboard')
@@ -248,7 +352,7 @@ await sdk.router.push('/projects', { query: { filter: 'active' } })
 // Replace (no history entry)
 await sdk.router.replace('/login')
 
-// Update query params
+// Update query params (null removes a param)
 await sdk.router.setQuery({ page: '2', sort: 'name' })
 
 // Subscribe to route changes
@@ -271,22 +375,14 @@ interface ThemeService {
 }
 ```
 
-**Example:**
-
 ```typescript
-// Check current theme
 if (sdk.theme.isDark) {
   // Apply dark styles
 }
 
-// Set specific theme mode
 await sdk.theme.setTheme('dark')
-await sdk.theme.setTheme('system')
-
-// Toggle between light/dark
 await sdk.theme.toggle()
 
-// Subscribe to theme changes
 const unsubscribe = sdk.theme.onChange((theme) => {
   document.body.classList.toggle('dark', theme.isDark)
 })
@@ -294,100 +390,168 @@ const unsubscribe = sdk.theme.onChange((theme) => {
 
 ---
 
-### Storage (`sdk.storage`)
+### Files (`sdk.files`)
+
+Two approaches for file uploads: `upload()` sends the file through the container (simpler, handles CORS), `initiate()` returns a presigned URL for direct-to-S3 upload (better for large files).
 
 ```typescript
-interface StorageService {
-  upload(options: UploadOptions): Promise<{ id: string; url: string; name: string }>
+interface FilesService {
+  upload(options: {
+    name: string
+    contentType: string
+    file: ArrayBuffer | Blob | File
+    sha256: string
+  }): Promise<{ id: string; name: string; status: string; s3UploadComplete: boolean }>
+
+  initiate(options: {
+    name: string
+    contentType: string
+    contentLength: number
+    sha256: string
+    metadata?: Record<string, unknown>
+  }): Promise<{ id: string; name: string; signedUrl: string; signedData: Record<string, string> }>
+
   get(fileId: string): Promise<FileMetadata>
   delete(fileId: string): Promise<void>
-  list(options?: ListOptions): Promise<{ items: FileMetadata[]; nextCursor?: string }>
+  list(options?: { limit?: number; cursor?: string }): Promise<{ items: FileMetadata[]; nextCursor?: string }>
 }
 ```
 
-**Example:**
-
 ```typescript
-// Upload a file (base64 encoded)
-const file = await sdk.storage.upload({
-  name: 'document.pdf',
-  type: 'application/pdf',
-  size: fileBuffer.byteLength,
-  data: btoa(String.fromCharCode(...new Uint8Array(fileBuffer))),
-  folder: 'documents'
+// Simple upload (file goes through the container)
+const result = await sdk.files.upload({
+  name: 'report.pdf',
+  contentType: 'application/pdf',
+  file: fileInput.files[0],
+  sha256: await computeSha256(fileInput.files[0])
 })
 
-console.log(file.url) // URL to access the file
+// Presigned upload (direct to S3, better for large files)
+const { signedUrl, signedData } = await sdk.files.initiate({
+  name: 'large-video.mp4',
+  contentType: 'video/mp4',
+  contentLength: file.size,
+  sha256: await computeSha256(file)
+})
 
-// List files
-const { items } = await sdk.storage.list({ folder: 'documents' })
+const formData = new FormData()
+Object.entries(signedData).forEach(([key, value]) => formData.append(key, value))
+formData.append('file', file)
+await fetch(signedUrl, { method: 'POST', body: formData })
+
+// List and manage files
+const { items } = await sdk.files.list({ limit: 20 })
+const metadata = await sdk.files.get('file-123')
+await sdk.files.delete('file-123')
 ```
 
 ---
 
-### Files (`sdk.files`)
+### Account (`sdk.account`)
 
-For large file uploads using presigned URLs:
+Manage the current user's account.
 
 ```typescript
-interface FilesService {
-  initiate(options: InitiateOptions): Promise<{
-    id: string
-    name: string
-    signedUrl: string
-    signedData: Record<string, string>
-  }>
-  get(fileId: string): Promise<FileMetadata>
-  delete(fileId: string): Promise<void>
-  list(options?: ListOptions): Promise<{ items: FileMetadata[]; nextCursor?: string }>
+interface AccountService {
+  get(): Promise<{ user: User; account: Record<string, unknown> }>
+  update(data: Record<string, unknown>): Promise<void>
+  usage(): Promise<Record<string, unknown>>
+  resendVerification(): Promise<void>
 }
 ```
 
-**Example:**
+```typescript
+// Get account details
+const { user, account } = await sdk.account.get()
+
+// Update profile
+await sdk.account.update({ name: 'New Name' })
+
+// Check usage/limits
+const usage = await sdk.account.usage()
+
+// Resend email verification
+await sdk.account.resendVerification()
+```
+
+---
+
+### Integrations (`sdk.integration`)
+
+Connect to third-party services. The `connect()` method opens the container's integration modal for OAuth flows.
 
 ```typescript
-// Initiate upload to get presigned URL
-const { signedUrl, signedData, id } = await sdk.files.initiate({
-  name: 'large-video.mp4',
-  contentType: 'video/mp4',
-  contentLength: file.size
-})
+interface IntegrationService {
+  list(): Promise<Integration[]>
+  connections(): Promise<IntegrationConfiguration[]>
+  status(source: string): Promise<{ connected: boolean; connections: unknown[] }>
+  connect(source: string): Promise<{ success: boolean; configuration?: unknown; message?: string }>
+  disconnect(source: string, configurationId: string): Promise<void>
+}
+```
 
-// Upload directly to storage
-const formData = new FormData()
-Object.entries(signedData).forEach(([key, value]) => {
-  formData.append(key, value)
-})
-formData.append('file', file)
+```typescript
+// List available integrations
+const integrations = await sdk.integration.list()
 
-await fetch(signedUrl, { method: 'POST', body: formData })
+// Check connection status
+const { connected, connections } = await sdk.integration.status('google-calendar')
+
+// Connect (opens OAuth modal in container)
+const result = await sdk.integration.connect('google-calendar')
+if (result.success) {
+  console.log('Connected!', result.configuration)
+}
+
+// List all active connections
+const allConnections = await sdk.integration.connections()
+
+// Disconnect
+await sdk.integration.disconnect('google-calendar', connectionId)
+```
+
+---
+
+### OpenAPI (`sdk.openapi`)
+
+Fetch the app's OpenAPI specification.
+
+```typescript
+interface OpenApiService {
+  get(): Promise<Record<string, unknown>>
+}
+```
+
+```typescript
+const spec = await sdk.openapi.get()
 ```
 
 ---
 
 ### Logging (`sdk.log`)
 
+Log messages and analytics events through the container's logging infrastructure.
+
 ```typescript
 interface LogService {
-  info(message: string, data?: Record<string, unknown>): void
-  warn(message: string, data?: Record<string, unknown>): void
-  error(message: string, data?: Record<string, unknown>): void
-  event(name: string, properties?: Record<string, unknown>): void
+  info(message: string, context?: Record<string, unknown>): void
+  warn(message: string, context?: Record<string, unknown>): void
+  error(message: string, context?: Record<string, unknown>): void
+  event(event: string, data?: Record<string, unknown>): void
 }
 ```
 
-**Example:**
-
 ```typescript
-// Log messages
 sdk.log.info('User completed onboarding', { userId: user.id })
 sdk.log.warn('API rate limit approaching', { remaining: 10 })
 sdk.log.error('Failed to save', { error: err.message })
 
-// Track analytics events
+// Analytics events
 sdk.log.event('button_clicked', { buttonId: 'submit', page: 'checkout' })
 ```
 
+Log methods are fire-and-forget — they don't return promises and won't throw.
+
 ---
 
 ### Config (`sdk.config`)
@@ -400,18 +564,13 @@ interface ConfigService {
 }
 ```
 
-**Example:**
-
 ```typescript
-// Check feature flags
 if (sdk.config.features.newDashboard) {
   // Show new dashboard
 }
 
-// Get app info
 console.log(sdk.config.app.environment) // 'production' | 'staging' | 'development'
 
-// Get specific config value
 const apiUrl = await sdk.config.get('apiBaseUrl')
 ```
 
@@ -419,16 +578,14 @@ const apiUrl = await sdk.config.get('apiBaseUrl')
 
 ### Entity Changes
 
-Subscribe to real-time entity changes for cache invalidation:
+Subscribe to real-time entity changes pushed from the container via WebSocket. Useful for cache invalidation.
 
 ```typescript
 const unsubscribe = sdk.onEntityChange((event) => {
-  console.log('Entity changed:', event)
-  // event.changeType: 'entity.created' | 'entity.updated' | 'entity.deleted'
-  // event.entityId: 'projects'
-  // event.id: 'project-123'
+  // event.changeType: 'entity.created' | 'entity.modified' | 'entity.deleted'
+  // event.entityId: 'projects' (entity type)
+  // event.id: 'project-123' (instance id)
 
-  // Invalidate your cache
   if (event.entityId === 'projects') {
     refetchProjects()
   }
@@ -439,15 +596,17 @@ const unsubscribe = sdk.onEntityChange((event) => {
 
 ## Vue Integration
 
-The SDK provides a Vue 3 composable for reactive state management:
-
 ```typescript
 import { useFoundation } from 'foundation-sdk/vue'
+
+// For standalone mode, call configureFoundation once at app startup:
+import { configureFoundation } from 'foundation-sdk/vue'
+configureFoundation({ configUrl: '...', tenantId: '...', appId: '...', auth: yourAuthClient })
 ```
 
 ### `useFoundation()`
 
-Returns reactive state and direct service access:
+Returns reactive state and direct service access. Entity change subscriptions are automatically cleaned up when the component unmounts. Works identically in both iframe and standalone modes.
 
 ```typescript
 interface UseFoundationReturn {
@@ -473,43 +632,37 @@ interface UseFoundationReturn {
   router: RouterService
   config: ConfigService
   files: FilesService
-  storage: StorageService
   log: LogService
   theme: ThemeService
+  account: AccountService
+  integration: IntegrationService
+  openapi: OpenApiService
 
-  // Theme control shortcuts
+  // Shortcuts
   setTheme(mode: 'light' | 'dark' | 'system'): Promise<void>
   toggleTheme(): Promise<void>
-
-  // Entity change subscription
   onEntityChange(callback: (event: EntityChangeEvent) => void): () => void
 }
 ```
 
-**Example:**
-
 ```vue
 <script setup lang="ts">
 import { useFoundation } from 'foundation-sdk/vue'
 import { watch } from 'vue'
 
-const { isReady, user, isDark, db, ui, toggleTheme } = useFoundation()
+const { isReady, user, isDark, db, ui, toggleTheme, onEntityChange } = useFoundation()
 
-// Reactive state updates automatically
 watch(user, (newUser) => {
   console.log('User changed:', newUser?.email)
 })
 
-// Theme reactivity
-watch(isDark, (dark) => {
-  document.body.classList.toggle('dark-mode', dark)
+// Auto-cleaned on component unmount
+onEntityChange((event) => {
+  if (event.entityId === 'tasks') {
+    refetchTasks()
+  }
 })
 
-async function loadProjects() {
-  const { items } = await db.list('projects', { limit: 10 })
-  return items
-}
-
 async function handleClick() {
   await toggleTheme()
   await ui.toast('Theme toggled!', 'success')
@@ -525,6 +678,18 @@ async function handleClick() {
 </template>
 ```
 
+### `resetFoundation()`
+
+Resets the Vue composable state and cleans up all subscriptions. Call alongside `resetFoundationClient()`.
+
+```typescript
+import { resetFoundation } from 'foundation-sdk/vue'
+import { resetFoundationClient } from 'foundation-sdk'
+
+resetFoundation()
+resetFoundationClient()
+```
+
 ---
 
 ## TypeScript
@@ -544,11 +709,18 @@ import type {
   RouterService,
   DbService,
   UIService,
-  StorageService,
   FilesService,
   FileMetadata,
   LogService,
-  ConfigService
+  ConfigService,
+  AccountService,
+  IntegrationService,
+  OpenApiService,
+  SDKReadyPayload,
+  SDKMessage,
+  SDKResponse,
+  StandaloneOptions,
+  MinimalAuthClient
 } from 'foundation-sdk'
 ```
 
@@ -556,7 +728,7 @@ import type {
 
 ## Architecture
 
-See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed diagrams of how the SDK communicates with the container.
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for protocol details, security model, and message flow diagrams.
 
 ## License