@newhomestar/sdk 0.8.3 → 0.8.5

package/README.md

@@ -0,0 +1,1187 @@
+# @newhomestar/sdk
+
+> Type-safe SDK for building Nova integrations, workers, and services.  
+> Code-first: TypeScript + Zod is the **single source of truth**.  
+> Build: `nova integrations build` → `dist/` + `nova-integration.yaml` + JSON schemas.  
+> Push: `nova integrations push` → Docker image + full config sync to platform DB.
+
+**Version:** 0.8.3  
+**Runtime:** Node 20 + esbuild CJS bundle  
+**Schema system:** Zod v4 → JSON Schema at build time  
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Export Paths](#export-paths)
+- [Core Concepts](#core-concepts)
+  - [`defineIntegration()`](#defineintegration)
+  - [`schema()`](#schema)
+  - [`event()`](#event)
+  - [`action()`](#action)
+  - [`ActionCtx`](#actionctx)
+- [Running the Integration](#running-the-integration)
+  - [`runHttpServer()`](#runhttpserver)
+  - [`runDualMode()`](#rundualmode)
+  - [`runWorker()`](#runworker)
+  - [Which runtime mode to use](#which-runtime-mode-to-use)
+- [Events System (`@newhomestar/sdk/events`)](#events-system)
+  - [Outbound Events (Producer)](#outbound-events-producer)
+  - [Inbound Events (Consumer)](#inbound-events-consumer)
+  - [Webhook ACID Processing](#webhook-acid-processing)
+  - [Outbox Relay](#outbox-relay)
+  - [Echo Loop Prevention](#echo-loop-prevention)
+  - [Topic Format Convention](#topic-format-convention)
+- [Credential Resolution](#credential-resolution)
+  - [HTTP Callback Strategy](#http-callback-strategy)
+  - [`ctx.resolveCredentials()` and `ctx.fetch()`](#ctxresolvecredentials-and-ctxfetch)
+  - [`createIntegrationClient()`](#createintegrationclient)
+  - [`emitPlatformEvent()`](#emitplatformevent)
+- [Parameter Metadata (`ParamMeta`)](#parameter-metadata-parammeta)
+- [Sync Mappings](#sync-mappings)
+- [Webhook Configuration](#webhook-configuration)
+- [Dual Database Pattern](#dual-database-pattern)
+- [`nova-integration.yaml` Spec](#nova-integrationyaml-spec)
+- [CLI Reference (`nova integrations`)](#cli-reference)
+  - [`nova integrations new`](#nova-integrations-new)
+  - [`nova integrations build`](#nova-integrations-build)
+  - [`nova integrations push`](#nova-integrations-push)
+- [Environment Variables](#environment-variables)
+- [Validation Rules](#validation-rules)
+
+---
+
+## Installation
+
+```bash
+yarn add @newhomestar/sdk zod
+# or
+npm install @newhomestar/sdk zod
+```
+
+Peer dependency: `zod >= 4.0.0`
+
+---
+
+## Quick Start
+
+```typescript
+import { defineIntegration, schema, event, action, runHttpServer } from "@newhomestar/sdk";
+import { z } from "zod";
+
+const Employee = schema("entity", z.object({
+  id:    z.string(),
+  email: z.string().email(),
+  name:  z.string(),
+}));
+
+const integration = defineIntegration({
+  slug: "my_provider",
+  name: "My Provider",
+  integrationType: "oauth2",
+  queue: "my_provider_queue",
+  baseUrl: "https://api.provider.com",
+  authorizationEndpoint: "https://provider.com/authorize",
+  tokenEndpoint: "https://provider.com/token",
+  scopes: ["openid", "profile"],
+
+  schemas: { employee: Employee },
+  events: {
+    employee_synced: event("outbound", { payload: Employee, category: "sync" }),
+  },
+  actions: {
+    health: action({
+      method: "GET", path: "/health",
+      input: z.object({}),
+      output: z.object({ ok: z.boolean() }),
+      handler: async () => ({ ok: true }),
+    }),
+    listEmployees: action({
+      method: "GET", path: "/employees",
+      scopes: ["employee:read"],
+      input: z.object({ limit: z.number().default(100) }),
+      output: z.object({ employees: z.array(z.any()), total: z.number() }),
+      handler: async (input, ctx) => {
+        const creds = await ctx.resolveCredentials();
+        const res = await ctx.fetch("https://api.provider.com/employees");
+        const data = await res.json();
+        return { employees: data.items, total: data.total };
+      },
+    }),
+  },
+});
+
+export default integration;
+
+// Runtime
+runHttpServer(integration as any, { port: 8000 });
+```
+
+---
+
+## Export Paths
+
+The SDK exposes three subpath exports:
+
+| Import Path | Description |
+|---|---|
+| `@newhomestar/sdk` | Core: `defineIntegration`, `action`, `schema`, `event`, `runHttpServer`, `runDualMode`, `runWorker`, credential helpers |
+| `@newhomestar/sdk/events` | Events system: `withServiceEventOutbox`, `startPollConsumer`, `startInboundConsumer`, `queueEvent`, `logEvent`, `isIntegrationSync` |
+| `@newhomestar/sdk/next` | Next.js helpers (for service projects) |
+
+---
+
+## Core Concepts
+
+### `defineIntegration()`
+
+The central function that registers an integration definition — the **single source of truth** for both the containerized runtime AND the platform configuration.
+
+```typescript
+import { defineIntegration } from "@newhomestar/sdk";
+
+export default defineIntegration({
+  // ── Identity ──
+  slug: "bamboohr",              // snake_case, unique across platform
+  name: "BambooHR",
+  displayName: "BambooHR HRIS",  // shown in admin UI
+  description: "...",
+
+  // ── Classification ──
+  integrationType: "oauth2",     // "oidc" | "oauth2" | "api_key"
+  category: "hris",
+  tags: ["hr", "employee-sync"],
+
+  // ── Branding ──
+  logoUrl: "https://...",
+  color: "#73C41D",
+  icon: "https://...",
+
+  // ── OAuth/OIDC Endpoints ──
+  authorizationEndpoint: "https://...",
+  tokenEndpoint: "https://...",
+  userinfoEndpoint: "https://...",       // optional
+  revocationEndpoint: "https://...",     // optional
+  jwksUri: "https://...",                // OIDC only
+  baseUrl: "https://api.bamboohr.com/",
+  scopes: ["openid", "profile"],
+
+  // ── Container Runtime ──
+  queue: "bamboohr_queue",
+  resources: { cpu: "500m", memory: "512Mi" },
+  envSpec: [
+    { name: "NOVA_EVENTS_SERVICE_URL", secret: false },
+    { name: "NOVA_SERVICE_TOKEN", secret: true },
+    // ...
+  ],
+
+  // ── Configuration ──
+  schemas:      { /* ... */ },
+  events:       { /* ... */ },
+  actions:      { /* ... */ },
+  syncMappings: { /* ... */ },   // optional
+  webhooks:     { /* ... */ },   // optional
+});
+```
+
+#### 7-Phase Normalization Pipeline
+
+When `defineIntegration()` is called, it runs these phases in order:
+
+| Phase | Description |
+|---|---|
+| **1. Normalize schemas** | Fills `slug` and `name` on lean `schema()` results from their dictionary key (e.g., key `employee` → slug: `"employee"`, name: `"Employee"`) |
+| **2. Normalize events** | Fills `slug`/`name` on lean `event()` results; resolves direct payload schema object references → string slugs for `payloadSchema` |
+| **3. Auto-extract functions** | Every action is promoted to an `IntegrationFunctionDef`. HTTP method, path, scopes, capabilities are copied. `__inputZod`, `__outputZod`, `__paramsMeta` stored as non-enumerable props for the build step to convert to JSON Schema |
+| **4. Zod validation** | Runs `IntegrationDefSchema.parse(def)` — structural validation of all fields |
+| **5. Cross-validate event schemas** | Checks that every `event.payloadSchema` string reference exists in `schemas` |
+| **6. Cross-validate function schemas** | Checks that `requestSchema` / `responseSchema` references exist in `schemas` |
+| **7. Validate webhook handler** | Checks that `webhooks.handler` references an existing action |
+
+#### `IntegrationDef` Field Reference
+
+| Field | Required | Type | Description |
+|---|---|---|---|
+| `slug` | ✅ | `string` | Unique snake_case identifier (e.g., `"bamboohr"`) |
+| `name` | ✅ | `string` | Human-readable name |
+| `integrationType` | ✅ | `"oidc" \| "oauth2" \| "api_key"` | Auth type |
+| `queue` | ✅ | `string` | PGMQ queue name for async processing |
+| `baseUrl` | ✅ | `string` | Base URL for external API calls |
+| `actions` | ✅ | `Record<string, ActionDef>` | Runtime action handlers |
+| `schemas` | ✅ | `Record<string, IntegrationSchemaDef>` | Zod schemas → JSON Schema on build |
+| `events` | ✅ | `Record<string, IntegrationEventDef>` | Event definitions |
+| `description` | | `string` | Short description |
+| `category` | | `string` | Grouping (e.g., `"hris"`, `"crm"`) |
+| `logoUrl` | | `string` | Logo for admin dashboard |
+| `color` | | `string` | Brand color hex code |
+| `displayName` | | `string` | Admin UI display name |
+| `tags` | | `string[]` | Discovery/filtering tags |
+| `authorizationEndpoint` | OAuth2/OIDC | `string` | OAuth authorize URL |
+| `tokenEndpoint` | OAuth2/OIDC | `string` | OAuth token URL |
+| `userinfoEndpoint` | | `string` | OIDC userinfo URL |
+| `revocationEndpoint` | | `string` | Token revocation URL |
+| `jwksUri` | OIDC recommended | `string` | JWKS URI for token verification |
+| `scopes` | | `string[]` | OAuth scopes to request |
+| `resources` | | `{ cpu, memory }` | Container resource limits |
+| `envSpec` | | `Array<{ name, secret, default? }>` | Environment variable spec |
+| `syncMappings` | | `Record<string, SyncMappingDef>` | Field mapping rules |
+| `webhooks` | | `WebhookConfig` | Inbound webhook types |
+| `functions` | Auto-generated | `Record<string, IntegrationFunctionDef>` | Auto-extracted from actions (Phase 3) |
+
+---
+
+### `schema()`
+
+Lean helper to define Zod schemas. Slug and name are inferred from the key in `schemas: {}`.
+
+```typescript
+import { schema } from "@newhomestar/sdk";
+import { z } from "zod";
+
+// slug = "employee", name = "Employee", schemaType = "entity"
+const Employee = schema("entity", z.object({
+  id:        z.string(),
+  email:     z.string().email(),
+  firstName: z.string(),
+  lastName:  z.string(),
+  status:    z.enum(["active", "inactive", "terminated"]),
+}), {
+  version: "1.0.0",
+  description: "BambooHR employee record",
+});
+```
+
+#### Schema Types
+
+| Type | Use for |
+|---|---|
+| `entity` | Domain objects (employees, contacts, issues) |
+| `request` | API request body shapes |
+| `response` | API response shapes |
+| `webhook_payload` | Inbound webhook payload shapes |
+| `configuration` | Integration settings/config |
+
+#### Verbose Alternative
+
+```typescript
+import { integrationSchema } from "@newhomestar/sdk";
+
+const Employee = integrationSchema({
+  name: "Employee",
+  slug: "employee",
+  schemaType: "entity",
+  schema: z.object({ /* ... */ }),
+  version: "1.0.0",
+});
+```
+
+---
+
+### `event()`
+
+Lean helper to define integration events. Slug and name are inferred from the key.
+
+```typescript
+import { event } from "@newhomestar/sdk";
+
+const events = {
+  // slug = "employee_synced", name = "Employee Synced"
+  employee_synced: event("outbound", {
+    payload: Employee,      // direct ref to schema() result (type-safe!)
+    category: "sync",
+    severity: "info",       // "info" | "warning" | "error" | "critical"
+  }),
+  
+  webhook_received: event("inbound", {
+    payload: WebhookPayload,
+    category: "webhook",
+  }),
+  
+  sync_failed: event("outbound", {
+    severity: "error",
+    category: "sync",
+  }),
+};
+```
+
+#### Event Directions
+
+| Direction | Meaning |
+|---|---|
+| `outbound` | Integration → Platform (e.g., sync completed, data changed) |
+| `inbound` | Platform → Integration (e.g., webhook received) |
+| `bidirectional` | Both directions |
+
+Outbound events are **auto-registered** in the platform `event_types` table when you run `nova integrations push`.
+
+---
+
+### `action()`
+
+The universal action builder. Every action is also auto-registered as a function in the platform DB.
+
+```typescript
+import { action } from "@newhomestar/sdk";
+import { z } from "zod";
+
+const syncEmployees = action({
+  // ── HTTP Routing ──
+  method: "POST",                     // GET | POST | PUT | DELETE | PATCH
+  path: "/employees/sync",
+
+  // ── Zod I/O ──
+  input: z.object({
+    tenantId: z.string().uuid(),
+    since: z.string().datetime().optional(),
+  }),
+  output: z.object({
+    synced: z.number(),
+    errors: z.number(),
+  }),
+
+  // ── Function Metadata ──
+  name: "syncEmployees",              // optional, defaults to key name
+  description: "Full employee sync",
+  scopes: ["employee:read"],          // presence → auto-register as function
+  category: "employees",
+
+  // ── Parameter Metadata (for admin UI form builder) ──
+  params: {
+    tenantId: { in: "body", uiType: "uuid", label: "Tenant ID", required: true },
+    since:    { in: "body", uiType: "datetime", label: "Since" },
+  },
+
+  // ── Triggers ──
+  triggers: [
+    { type: "schedule", cron: "0 */6 * * *", timezone: "UTC", description: "Every 6 hours" },
+    { type: "event", events: ["hris.employee_updated"] },
+  ],
+
+  // ── Sync Metadata (for DataSync UI tab) ──
+  sync: {
+    entityType: "employee",
+    direction: "to_nova",             // "to_nova" | "from_nova" | "bidirectional"
+    label: "BambooHR Employees",
+    description: "Import all employees from BambooHR",
+  },
+
+  // ── Expandable Relations (batch foreign-key resolution) ──
+  expandable: {
+    supervisor: {
+      model: "employee",
+      resolver: async (ids, ctx) => {
+        // Batch-fetch supervisors by ID → Map<id, fullObject>
+      },
+    },
+  },
+
+  // ── Handler ──
+  async handler(input, ctx) {
+    ctx.progress(10, { status: "starting" });
+    const res = await ctx.fetch("https://api.bamboohr.com/v1/employees/directory");
+    const data = await res.json();
+    ctx.progress(100, { status: "complete" });
+    return { synced: data.employees.length, errors: 0 };
+  },
+});
+```
+
+#### `action()` Full Field Reference
+
+| Field | Type | Description |
+|---|---|---|
+| `method` | `string` | HTTP method (default: `"POST"`) |
+| `path` | `string` | Route path (default: `/{workerName}/{actionName}`) |
+| `input` | `ZodType` | Zod schema for input validation |
+| `output` | `ZodType` | Zod schema for output validation |
+| `handler` | `(input, ctx) => Promise<output>` | Action implementation |
+| `name` | `string` | Display name (default: key name) |
+| `description` | `string` | Human-readable description |
+| `scopes` | `string[]` | OAuth scopes → auto-registers as a platform function |
+| `category` | `string` | Grouping in the admin UI |
+| `params` | `Record<string, ParamMeta>` | Per-field metadata for path/query/body routing + UI hints |
+| `triggers` | `Array<EventTrigger \| ScheduleTrigger>` | Event subscriptions and cron schedules |
+| `sync` | `{ entityType, direction, label, description? }` | DataSync tab metadata |
+| `expandable` | `Record<string, { model, resolver }>` | `?expand=field1,field2` batch resolvers |
+| `capabilities` | `Array<Capability>` | Legacy: webhook, scheduled, queue, stream triggers |
+| `fga` | `{ resourceType, relation, resourceIdKey? }` | OpenFGA authorization hints |
+| `events` | `string \| string[]` | Shorthand for `triggers: [{ type: 'event', events: [...] }]` |
+
+---
+
+### `ActionCtx`
+
+Every action handler receives a context object (`ctx`) with these methods:
+
+```typescript
+async handler(input: Input, ctx: ActionCtx) {
+  // ── Job tracking ──
+  ctx.jobId;                          // unique job ID (e.g., "http-1234567890")
+  ctx.progress(50, { step: "fetching" });  // report progress to platform
+
+  // ── Authentication ──
+  ctx.authToken;                      // raw Bearer token from inbound request
+  ctx.auth;                           // validated JWT payload (sub, iss, exp, aud, etc.)
+
+  // ── Credential Resolution ──
+  const creds = await ctx.resolveCredentials();
+  // OR: const creds = await ctx.resolveCredentials("other_integration", userId);
+
+  // ── mTLS-aware Fetch (with 401 auto-retry) ──
+  const res = await ctx.fetch("https://api.provider.com/data");
+  // OR: const res = await ctx.fetch(url, { method: "POST", body: "..." }, creds);
+
+  // ── HTTP headers (HTTP mode only) ──
+  ctx.headers;                        // raw request headers
+
+  // ── SSE worker mode only ──
+  ctx.read_ct;                        // message delivery count
+  await ctx.heartbeat?.(30);          // extend visibility timeout by 30s
+}
+```
+
+#### `ctx.resolveCredentials()` Flow
+
+1. Calls `GET {AUTH_ISSUER_BASE_URL}/api/integrations/{slug}/credentials` with the inbound JWT
+2. Auth server decrypts credentials from Vault and returns them
+3. SDK performs OAuth token exchange locally (`client_credentials` or `mTLS`)
+4. Returns `ResolvedCredentials` with `accessToken`, `expiresAt`, `authMode`, `httpsAgent`
+
+#### `ctx.fetch()` 401 Auto-Retry
+
+1. Makes the request with current `accessToken`
+2. If 401 → sends `X-Nova-Token-Invalid: true` to auth server → gets fresh credentials
+3. If the new token is different → retries once automatically
+4. If same token → returns original 401 (prevents infinite loops)
+
+---
+
+## Running the Integration
+
+### `runHttpServer()`
+
+Starts an Express HTTP server with one route per action.
+
+```typescript
+import { runHttpServer } from "@newhomestar/sdk";
+
+runHttpServer(integration as any, {
+  port: 8000,
+  issuerBaseURL: "https://auth.newhomeconnect.dev",
+  audience: "starfleet",
+  publicPaths: ["/webhooks"],   // exempt from JWKS auth
+  skipAuth: false,              // or set NOVA_SKIP_AUTH=true
+});
+```
+
+**Features:**
+- **JWKS JWT authentication** via `express-oauth2-jwt-bearer` (RS256)
+- `/health` and `/healthcheck` are auto-exempted from auth
+- **Smart input extraction**: params metadata → path/query/body/header; type coercion for query strings
+- **`?expand=field1,field2`** — batch foreign-key resolution via `expandable` config
+
+### `runDualMode()`
+
+Starts both HTTP server and queue consumer concurrently.
+
+```typescript
+import { runDualMode } from "@newhomestar/sdk";
+
+runDualMode(integration as any, { port: 8000 });
+// HTTP API + SSE/pgmq queue consumer in background
+```
+
+> **⚠️ Warning:** If you also use `startPollConsumer()` for inbound event processing, use `runHttpServer()` instead of `runDualMode()` to avoid competing consumers on the same queue.
+
+### `runWorker()`
+
+Queue-only mode. Automatically selects:
+- **SSE mode** (preferred): when `NOVA_EVENTS_SERVICE_URL` + `NOVA_SERVICE_TOKEN` are set
+- **Legacy pgmq mode**: when `RUNTIME_SUPABASE_*` env vars are set
+
+### Which Runtime Mode to Use
+
+| Scenario | Recommended Mode |
+|---|---|
+| Integration with HTTP API + separate poll consumer | `runHttpServer()` + `startPollConsumer()` |
+| Integration with HTTP API + built-in SSE consumer | `runDualMode()` |
+| Pure queue worker (no HTTP) | `runWorker()` |
+| Background/headless sync loops | `createIntegrationClient()` + `setImmediate(processLoop)` |
+
+---
+
+## Events System
+
+Import from `@newhomestar/sdk/events`:
+
+```typescript
+import {
+  withServiceEventOutbox,
+  withEventOutbox,
+  withWebhookEvent,
+  queueEvent,
+  logEvent,
+  startOutboxRelay,
+  startInboundConsumer,
+  startPollConsumer,
+  isIntegrationSync,
+  NovaEventsClient,
+} from "@newhomestar/sdk/events";
+```
+
+### Outbound Events (Producer)
+
+#### `withServiceEventOutbox()` — Preferred
+
+Atomic: data write + outbox row in one Prisma `$transaction`, then best-effort relay. Auto-stamps `x-source`/`x-integration-id` from request headers.
+
+```typescript
+const employee = await withServiceEventOutbox(db, req, async (tx, emit) => {
+  const row = await tx.hrisEmployee.update({ where: { id }, data });
+  emit("employee.updated", { id: row.id, firstName: row.firstName });
+  return row;
+});
+```
+
+#### `withEventOutbox()` — Legacy
+
+Same atomicity but with a `{ events, result }` return shape:
+
+```typescript
+const employee = await withEventOutbox(db, async (tx) => {
+  const row = await tx.hrisEmployee.update({ where: { id }, data });
+  return {
+    events: [{ entity_type: "employee", action: "updated", entity_id: id }],
+    result: row,
+  };
+});
+```
+
+#### `queueEvent()` — Stateless
+
+No transaction context. Directly POSTs to the Events Service.
+
+```typescript
+await queueEvent({
+  event_slug: "bamboohr.employee_synced",
+  source_service: "bamboohr",
+  attributes: { synced: 150, errors: 0 },
+});
+```
+
+#### `logEvent()` — Audit Only
+
+Records an event in the audit log **without** queue fan-out.
+
+```typescript
+await logEvent({
+  event_slug: "bamboohr.employee_viewed",
+  entity_id: employeeId,
+  performed_by_id: userId,
+});
+```
+
+### Inbound Events (Consumer)
+
+#### `startPollConsumer()` — Recommended for DO App Platform
+
+HTTP pull-based consumer. No persistent connections or proxy timeout issues.
+
+```typescript
+const consumer = startPollConsumer(db, {
+  queueName: "bamboohr_queue",
+  batch: 5,         // messages per poll
+  vt: 60,           // visibility timeout (seconds)
+  idleDelayMs: 2000, // sleep when queue is empty
+  handlers: {
+    "hris.employee_created": async (tx, event) => {
+      if (isIntegrationSync(event.payload)) return { status: "skipped" };
+      await tx.bambooEmployee.upsert({ /* ... */ });
+      return { status: "processed" };
+    },
+    "hris.employee_updated": async (tx, event) => {
+      // ...
+      return { status: "processed" };
+    },
+  },
+  defaultHandler: async (_tx, event) => {
+    console.warn(`Unhandled event: ${(event.payload as any).topic}`);
+    return { status: "skipped" };
+  },
+});
+
+// Graceful shutdown
+process.on("SIGTERM", () => consumer.abort());
+```
+
+#### `startInboundConsumer()` — SSE-Based
+
+Long-lived SSE connection. Best for non-DO deployments.
+
+```typescript
+const consumer = startInboundConsumer(db, {
+  queueName: "bamboohr_queue",
+  handlers: { /* same as poll consumer */ },
+  vt: 30,
+  maxReconnectDelay: 30_000,
+});
+```
+
+### Webhook ACID Processing
+
+#### `withWebhookEvent()`
+
+Atomically processes inbound webhooks with idempotency:
+
+```typescript
+const { status } = await withWebhookEvent(db, {
+  idempotencyKey: `bamboohr:${webhookId}:${timestamp}`,
+  eventType: "bamboohr.employee.updated",
+  queueName: "bamboohr_webhooks",
+  payload: rawBody,
+}, async (tx, emit) => {
+  await tx.bambooEmployee.upsert({ /* ... */ });
+  emit("employee.upserted", { id: employee.id });
+});
+// Returns { status: "processed" } or { status: "duplicate" }
+```
+
+**ACID guarantee**: idempotency check → inbound_events INSERT → handler → outbox rows → mark processed — all in one `$transaction`. Rolls back entirely on failure.
+
+### Outbox Relay
+
+Start once at service boot:
+
+```typescript
+startOutboxRelay(db, {
+  intervalMs: 60_000,   // poll every 60s
+  maxAttempts: 5,       // give up after 5 attempts
+});
+```
+
+Retry schedule (exponential backoff): `2^attempts × 5s` → 5s, 10s, 20s, 40s, 80s.
+
+### Echo Loop Prevention
+
+```typescript
+import { isIntegrationSync } from "@newhomestar/sdk/events";
+
+// In a consumer handler:
+if (isIntegrationSync(event.payload)) {
+  return { status: "skipped" }; // Don't write back to the system that caused this event
+}
+```
+
+Checks for `x-source: integration_sync` in headers or `metadata.source === "integration_sync"` in event payloads.
+
+### Topic Format Convention
+
+```
+{source_service}.{entity}_{action}
+```
+
+Examples:
+- `hris.employee_created`
+- `bamboohr.user_synced`
+- `nova_ticketing_service.ticket_updated`
+
+---
+
+## Credential Resolution
+
+### HTTP Callback Strategy
+
+The **only** credential resolution strategy. No direct database access needed.
+
+```
+Container ──JWT──> Auth Server ──Vault──> Decrypted Credentials
+                   (AUTH_ISSUER_BASE_URL)
+```
+
+**Flow:**
+1. Container receives request with JWT (validated by JWKS middleware)
+2. Action calls `ctx.resolveCredentials()`
+3. SDK calls `GET {AUTH_ISSUER_BASE_URL}/api/integrations/{slug}/credentials` with `Authorization: Bearer {jwt}`
+4. Auth server verifies JWT, decrypts credentials from Vault, returns them
+5. SDK performs local OAuth token exchange (`client_credentials` / `mTLS`)
+6. Container uses the `accessToken` to call the integration API
+
+### `ctx.resolveCredentials()` and `ctx.fetch()`
+
+```typescript
+// Auto-resolve for the current integration
+const creds = await ctx.resolveCredentials();
+
+// Resolve for a different integration
+const creds = await ctx.resolveCredentials("other_integration", userId);
+
+// ctx.fetch() — resolves credentials automatically + 401 auto-retry
+const res = await ctx.fetch("https://api.provider.com/employees");
+
+// ctx.fetch() with explicit credentials
+const res = await ctx.fetch(url, { method: "POST", body: "..." }, creds);
+```
+
+**Auth modes** returned by `ResolvedCredentials`:
+- `standard` — authorization_code (per-user, pre-resolved access token)
+- `client_credentials` — server-to-server OAuth (SDK performs token exchange)
+- `mtls` — client_credentials + mTLS cert/key (SDK uses `node:https` agent)
+
+### `createIntegrationClient()`
+
+For background/headless sync loops that don't have an inbound JWT:
+
+```typescript
+import { createIntegrationClient } from "@newhomestar/sdk";
+
+const client = createIntegrationClient("bamboohr");
+// Resolves via NOVA_SERVICE_TOKEN (not user JWT)
+
+const res = await client.fetch("https://api.bamboohr.com/v1/employees/directory");
+const data = await res.json();
+
+// Auto-refreshes credentials when they expire (60s buffer)
+// Auto-retries on 401 with fresh credentials
+```
+
+### `emitPlatformEvent()`
+
+Emit PGMQ events to the platform database for cross-service communication:
+
+```typescript
+import { createPlatformClient, emitPlatformEvent } from "@newhomestar/sdk";
+
+const platformDB = createPlatformClient();
+await emitPlatformEvent(platformDB, "employee.sync_complete", "bamboohr", {
+  tenantId, synced: 150, errors: 0,
+});
+```
+
+---
+
+## Parameter Metadata (`ParamMeta`)
+
+Per-field metadata that tells the platform where each input field goes (path, query, body, header) and what UI widget the admin dashboard should render.
+
+```typescript
+params: {
+  id:       { in: "path",  uiType: "text",   label: "Employee ID", required: true },
+  asOfDate: { in: "query", uiType: "date",   label: "As-of Date", placeholder: "YYYY-MM-DD" },
+  syncType: { in: "body",  uiType: "select", label: "Sync Type", options: [
+    { label: "Full", value: "full" },
+    { label: "Incremental", value: "incremental" },
+  ]},
+  limit:    { in: "query", uiType: "number", label: "Limit", defaultValue: 100, min: 1, max: 500 },
+}
+```
+
+#### `ParamMeta` Field Reference
+
+| Field | Type | Description |
+|---|---|---|
+| `in` | `"path" \| "query" \| "body" \| "header"` | Where the parameter goes in the HTTP request |
+| `uiType` | `ParamUiType` | UI widget: `text`, `textarea`, `number`, `integer`, `boolean`, `date`, `datetime`, `select`, `multiselect`, `password`, `email`, `url`, `uuid`, `json`, `hidden` |
+| `label` | `string` | Human-readable label |
+| `description` | `string` | Help text below the input |
+| `placeholder` | `string` | Placeholder text |
+| `required` | `boolean` | Overrides Zod's optional/required |
+| `defaultValue` | `unknown` | Default value in UI |
+| `options` | `Array<{ label, value }>` | For select/multiselect |
+| `min` / `max` | `number` | Range for numbers, length for strings |
+| `step` | `number` | Increment for number inputs |
+| `pattern` | `string` | Regex for frontend validation |
+| `order` | `number` | Display priority (lower = higher) |
+| `group` | `string` | Visual grouping (e.g., `"Identity"`, `"Options"`) |
+
+**Convention fallback** (when `params` not provided):
+- Fields matching `:param` in path → path params
+- Remaining fields for GET → query params
+- Remaining fields for POST/PUT/PATCH → body params
+- UI type inferred from Zod type (string→text, number→number, boolean→boolean, enum→select)
+
+---
+
+## Sync Mappings
+
+Declare how integration entities map to Nova service schemas. Seeded into `integration_sync_pairs` + `integration_field_mappings` on push.
+
+```typescript
+syncMappings: {
+  employee: {
+    service: "hris",
+    targetSchema: "employee",
+    direction: "integration_to_service",
+    fields: [
+      { source: "workEmail",  target: "work_email" },
+      { source: "firstName",  target: "first_name" },
+      { source: "lastName",   target: "last_name" },
+      { source: "status", target: "employment_status",
+        transform: "status = 'Active' ? 'ACTIVE' : 'INACTIVE'" },  // JSONata
+      { source: "supervisor", sourcePath: ["supervisor", "id"], target: "manager_id" },
+    ],
+  },
+  time_off_request: {
+    service: "hris",
+    targetSchema: "time_off_request",
+    direction: "integration_to_service",
+    fields: [ /* ... */ ],
+  },
+},
+```
+
+---
+
+## Webhook Configuration
+
+Declares inbound webhook types the provider supports:
+
+```typescript
+webhooks: {
+  handler: "handleWebhook",   // must reference an existing action key
+  types: {
+    employee_changes: {
+      label: "Employee Changes",
+      description: "Fires when employee records are created, updated, or deleted",
+      produces: ["bamboohr.employee.created", "bamboohr.employee.updated", "bamboohr.employee.deleted"],
+      authentication: {
+        method: "hmac_sha256",
+        signatureHeader: "X-BambooHR-Signature",
+        secretSource: "platform_generated",
+      },
+      fields: [
+        { name: "events", label: "Event Types", type: "multiselect", required: true,
+          options: [
+            { label: "Created", value: "created" },
+            { label: "Updated", value: "updated" },
+            { label: "Deleted", value: "deleted" },
+          ]},
+      ],
+    },
+  },
+},
+```
+
+Synced to `app_webhook_types` on push. The Odyssey UI renders configuration forms from the `fields` array.
+
+---
+
+## Dual Database Pattern
+
+Each integration connects to **two** databases:
+
+```
+┌─────────────────────────┐     ┌────────────────────────────┐
+│   Platform DB            │     │   Integration DB             │
+│   (read-only)            │     │   (read-write)               │
+│                          │     │                              │
+│  • OAuth tokens          │     │  • domain tables             │
+│  • Tenant config         │     │  • sync jobs                 │
+│  • PGMQ queues           │     │  • webhook events            │
+│                          │     │  • inbound/outbound events   │
+│  PLATFORM_SUPABASE_URL   │     │  INTEGRATION_SUPABASE_URL    │
+│  getPlatformClient()     │     │  getIntegrationClient()      │
+└─────────────────────────┘     └────────────────────────────┘
+```
+
+```typescript
+import { createClient, type SupabaseClient } from "@supabase/supabase-js";
+
+function getPlatformClient(): SupabaseClient {
+  return createClient(
+    process.env.PLATFORM_SUPABASE_URL!,
+    process.env.PLATFORM_SUPABASE_SERVICE_ROLE_KEY!,
+    { auth: { autoRefreshToken: false, persistSession: false } }
+  );
+}
+
+function getIntegrationClient(): SupabaseClient {
+  return createClient(
+    process.env.INTEGRATION_SUPABASE_URL!,
+    process.env.INTEGRATION_SUPABASE_SERVICE_ROLE_KEY!,
+    { auth: { autoRefreshToken: false, persistSession: false } }
+  );
+}
+```
+
+---
+
+## `nova-integration.yaml` Spec
+
+Generated by `nova integrations build`. Full annotated example:
+
+```yaml
+apiVersion: nova.dev/v1
+kind: Integration
+metadata:
+  slug: bamboohr
+  name: BambooHR
+  displayName: BambooHR HRIS
+  description: Connects BambooHR HRIS to Nova
+  category: hris
+  tags: [hr, employee-sync]
+  logoUrl: https://...
+  color: "#73C41D"
+spec:
+  type: oauth2                          # oidc | oauth2 | api_key
+  endpoints:
+    authorization: https://bamboohr.com/authorize.php
+    token: https://bamboohr.com/token.php
+    baseUrl: https://api.bamboohr.com/api/gateway.php/newhomestar
+  scopes: [employee, time_off, time_tracking]   # merged from all action scopes
+  runtime:
+    type: integration
+    image: registry.digitalocean.com/nhc/bamboohr:main
+    queue: bamboohr_queue
+    command: [node, dist/index.cjs]
+    resources: { cpu: 500m, memory: 512Mi }
+    envSpec:
+      - { name: NOVA_EVENTS_SERVICE_URL, secret: false }
+      - { name: NOVA_SERVICE_TOKEN, secret: true }
+  actions:
+    - name: syncEmployees
+      async: true
+      triggers:
+        - { type: schedule, cron: "0 */6 * * *", timezone: UTC }
+      scopes: [employee:read]
+      sync:
+        entityType: employee
+        direction: to_nova
+        label: BambooHR Employees
+      input: { ... }     # JSON Schema (converted from Zod)
+      output: { ... }
+      schema:
+        input: ./schemas/syncEmployees.input.json
+        output: ./schemas/syncEmployees.output.json
+  schemas:
+    - slug: employee
+      name: Employee
+      type: entity
+      schema: { type: object, properties: { ... } }
+      version: "1.0.0"
+      fieldCount: 42
+  events:
+    - slug: employee_synced
+      name: Employee Synced
+      direction: outbound
+      category: sync
+      severity: info
+      payloadSchema: employee
+  functions:                            # auto-extracted from actions
+    - slug: sync_employees
+      name: Sync Employees
+      httpMethod: POST
+      endpointPath: /employees/sync
+      requiredScopes: [employee:read]
+      category: employees
+  syncMappings:
+    - sourceEntity: employee
+      service: hris
+      targetSchema: employee
+      direction: integration_to_service
+      fields:
+        - { source: workEmail, target: work_email }
+        - { source: status, target: employment_status,
+            transform: "status = 'Active' ? 'ACTIVE' : 'INACTIVE'" }
+  webhookTypes:
+    - slug: employee_changes
+      label: Employee Changes
+      produces: [bamboohr.employee.created, bamboohr.employee.updated]
+      handler: handle_webhook
+build:
+  dockerfile: ./Dockerfile
+  context: .
+ui:
+  category: hris
+  color: "#73C41D"
+```
+
+---
+
+## CLI Reference
+
+### `nova integrations new`
+
+Scaffolds a new integration project.
+
+```bash
+nova integrations new [directory]
+```
+
+**Interactive prompts:**
+1. Integration slug (snake_case) — if no directory arg
+2. Integration type: OIDC, OAuth2, or API Key
+
+**Generates:**
+| File | Purpose |
+|---|---|
+| `src/index.ts` | Full starter integration with `defineIntegration()`, schemas, events, actions, poll consumer |
+| `src/lib/db.ts` | Prisma singleton client |
+| `package.json` | `@newhomestar/sdk@0.6.0`, `zod`, `prisma` |
+| `prisma/schema.prisma` | Baseline Prisma schema with outbox models |
+| `Dockerfile` | Distroless Node 20 container |
+| `tsconfig.json` | TypeScript configuration |
+| `Agents.md` | LLM agent instructions |
+| `supabase/` | Local Supabase config + migrations directory |
+
+**Post-scaffold:** runs `git init`, `corepack enable`, `yarn install`
+
+**Optional AI assist:** generates starter schemas/events from a plain-English description using OpenAI.
+
+### `nova integrations build`
+
+Bundles the integration and generates all build artifacts.
+
+```bash
+nova integrations build [-o dist] [--dry-run] [--skip-bundle]
+```
+
+**8-Step Pipeline:**
+
+| Step | What happens |
+|---|---|
+| 1. **Pass 1 esbuild** | Bundles `src/index.ts` → `dist/index.build.cjs` with `zod` **external** (so the CLI can use the integration's Zod for `instanceof` checks) |
+| 2. **Dynamic import** | Loads the build-time bundle, finds `export default defineIntegration({...})` |
+| 3. **Validate** | Runs `validateIntegration()` — checks slug, name, schemas, baseUrl, actions |
+| 4. **Load Zod v4** | From integration's `node_modules`; uses `z.toJSONSchema()` for schema conversion |
+| 5. **Convert schemas** | Each `schemas.*` entry → JSON Schema file at `dist/schemas/{slug}.json` |
+| 6. **Convert events + functions** | Extracts metadata; converts `__inputZod`/`__outputZod` → `inputSchema`/`outputSchema` JSON |
+| 7. **Convert actions** | Zod I/O → JSON Schema; serializes `triggers`, `scopes`, `sync` blocks |
+| 8. **Pass 2 esbuild** | Production bundle with `ignoreAnnotations: true` (zod fully inlined, zero node_modules at runtime) |
+
+**Scope rollup:** auto-collects all `scopes` from all actions, extracts base names (`employee:read` → `employee`), merges with top-level `def.scopes`.
+
+**Output:**
+- `dist/index.cjs` — production bundle (~50MB image in distroless Docker)
+- `dist/schemas/*.json` — JSON Schema files per entity and action I/O
+- `nova-integration.yaml` — the full spec document
+
+### `nova integrations push`
+
+Builds, pushes Docker image, and syncs all configuration to the platform.
+
+```bash
+nova integrations push [--skip-build] [--skip-secrets-fetch] [-d|--destructive] [--tag <t>] [--registry <r>]
+```
+
+**11-Step Pipeline:**
+
+| Step | Description |
+|---|---|
+| 1. **Fetch secrets** | `POST {odysseyUrl}/api/secrets` using stored CLI session token |
+| 2. **Build integration** | Runs `buildIntegration()` → spec + `nova-integration.yaml` |
+| 3. **Docker registry login** | `doctl registry login` (for DigitalOcean registry) |
+| 4. **Docker build** | `docker build --platform linux/amd64 -t {registry}/{slug}:{tag} .` |
+| 5. **Docker push** | `docker push {image}` |
+| 6. **Register container** | `POST /api/integrations` — metadata, image, queue, actions |
+| 7. **Sync config** | `POST /api/integrations/config` — upsert schemas, events, functions |
+| 8. **Seed sync mappings** | `POST /api/integrations/sync-mappings` — `integration_sync_pairs` + `integration_field_mappings` |
+| 8b. **Sync entity types** | `POST /api/integrations/sync-entities` — DataSync tab entries from `action.sync` blocks |
+| 8c. **Sync webhook types** | `POST /api/integrations/webhook-types` — `app_webhook_types` rows |
+| 9. **Register outbound events** | `POST /api/integration-events/sync` + `POST {NOVA_EVENTS_SERVICE_URL}/event-types` |
+| 10. **Register triggers** | Ensure PGMQ queue exists; upsert `event_subscriptions` for each trigger topic |
+| 11. **Sync trigger registry** | `POST /api/event-triggers/sync` — platform DB for UI display |
+
+**Tag defaulting:** current git branch name (sanitized to `[a-z0-9.-]`)
+
+**`--destructive` flag:** deletes all existing endpoints/schemas/events before upserting (guarantees clean slate).
+
+---
+
+## Environment Variables
+
+### Runtime (Container)
+
+| Variable | Secret | Required By |
+|---|---|---|
+| `NOVA_EVENTS_SERVICE_URL` | No | `startPollConsumer`, `queueEvent`, `withEventOutbox` |
+| `NOVA_SERVICE_TOKEN` | Yes | Events Service auth, `createIntegrationClient()` |
+| `AUTH_ISSUER_BASE_URL` | No | `ctx.resolveCredentials()` — auth server URL |
+| `AUTH_AUDIENCE` | No | JWKS audience claim (default: `"starfleet"`) |
+| `PLATFORM_SUPABASE_URL` | No | `createPlatformClient()`, `emitPlatformEvent()` |
+| `PLATFORM_SUPABASE_SERVICE_ROLE_KEY` | Yes | Platform DB service role |
+| `INTEGRATION_SUPABASE_URL` | No | Integration's own database |
+| `INTEGRATION_SUPABASE_SERVICE_ROLE_KEY` | Yes | Integration DB service role |
+| `NOVA_SERVICE_SLUG` | No | Stamped as `source_service` on outbox events |
+| `PORT` | No | HTTP server port (default: `8000`) |
+| `NOVA_SKIP_AUTH` | No | Set `"true"` to disable JWKS auth (dev only) |
+| `DATABASE_URL` | Yes | Prisma connection string |
+
+### CLI / Build
+
+| Variable | Secret | Used By |
+|---|---|---|
+| `DIGITALOCEAN_ACCESS_TOKEN` | Yes | Docker registry login (`nova integrations push`) |
+| `NPM_TOKEN` | Yes | Docker build arg for private npm packages |
+| `GIT_SHA` | No | Docker image tag fallback |
+| `NOVA_DOCKER_REGISTRY` | No | Override registry prefix (default: `registry.digitalocean.com/nhc`) |
+| `ODYSSEY_UI_URL` | No | Override Odyssey UI URL (default from CLI config) |
+| `OPENAI_API_KEY` | Yes | AI-assisted scaffolding (`nova integrations new`) |
+
+---
+
+## Validation Rules
+
+`validateIntegration()` runs automatically during `nova integrations build`. Here's what it checks:
+
+### Errors (block build/push)
+
+| Check | Condition |
+|---|---|
+| `slug` required | Must be present and non-empty |
+| `name` required | Must be present and non-empty |
+| `queue` required | Must be present and non-empty |
+| `baseUrl` required | Must be present and non-empty |
+| At least 1 action | `actions` must have ≥1 entry |
+| OAuth endpoints | `authorizationEndpoint` + `tokenEndpoint` required for oauth2/oidc |
+
+### Warnings (non-blocking)
+
+| Check | Condition |
+|---|---|
+| No scopes | OAuth2/OIDC should have ≥1 scope |
+| Missing OIDC fields | `jwksUri`, `userinfoEndpoint` recommended for OIDC |
+| Non-HTTPS URLs | All endpoint URLs should use HTTPS (except localhost) |
+| No schemas | At least one entity schema recommended |
+| No health action | `health` or `healthCheck` action recommended |
+| No envSpec | Environment variables won't be validated at deploy time |
+
+---
+
+## Architecture Diagram
+
+```
+src/index.ts
+  └─ defineIntegration({
+        schemas: { employee: schema("entity", EmployeeZod) }
+        events:  { employee_synced: event("outbound", ...) }
+        actions: { syncEmployees: action({ scopes, triggers, sync, handler }) }
+     })
+        │
+        │  nova integrations build
+        ▼
+  dist/index.cjs       (production bundle — runs in distroless Docker)
+  dist/schemas/        (JSON Schema files)
+  nova-integration.yaml (spec document)
+        │
+        │  nova integrations push
+        ▼
+  ┌─────────────────────────────────────────────────────────────────┐
+  │  Docker Registry    registry.digitalocean.com/nhc/{slug}:{tag}  │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  Platform DB        app_integrations                            │
+  │                     app_integration_schemas                     │
+  │                     app_integration_events                      │
+  │                     app_integration_functions                   │
+  │                     integration_sync_pairs                      │
+  │                     integration_field_mappings                  │
+  │                     app_webhook_types                           │
+  │                     app_integration_sync_entities               │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  Events Service     event_types (outbound event registration)   │
+  │                     event_subscriptions (PGMQ queue routing)    │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  Orchestrator       Container registered, queue ensured         │
+  └─────────────────────────────────────────────────────────────────┘
+```