@contractspec/lib.contracts-integrations 2.0.0

package/dist/integrations/binding.d.ts

@@ -0,0 +1,14 @@
+export interface AppIntegrationBinding {
+    /** Which slot this binding satisfies. */
+    slotId: string;
+    /** Which IntegrationConnection to use. */
+    connectionId: string;
+    /** Optional: scope to specific workflows/features. */
+    scope?: {
+        workflows?: string[];
+        features?: string[];
+        operations?: string[];
+    };
+    /** Priority when multiple connections provide same capability. */
+    priority?: number;
+}

package/dist/integrations/binding.js

@@ -0,0 +1 @@
+// @bun

package/dist/integrations/connection.d.ts

@@ -0,0 +1,47 @@
+import type { IntegrationOwnershipMode } from './spec';
+export type ConnectionStatus = 'connected' | 'disconnected' | 'error' | 'unknown';
+export interface IntegrationConnectionHealth {
+    status: ConnectionStatus;
+    checkedAt?: Date;
+    latencyMs?: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface IntegrationUsageMetrics {
+    requestCount?: number;
+    successCount?: number;
+    errorCount?: number;
+    lastUsed?: Date;
+    lastSuccessAt?: Date;
+    lastErrorAt?: Date;
+    lastErrorCode?: string;
+}
+export interface IntegrationConnectionMeta {
+    id: string;
+    tenantId: string;
+    /** Reference to IntegrationSpec. */
+    integrationKey: string;
+    integrationVersion: string;
+    /** Human-readable label (e.g., "Production Stripe"). */
+    label: string;
+    environment?: string;
+    createdAt: string | Date;
+    updatedAt: string | Date;
+}
+export interface IntegrationConnection {
+    meta: IntegrationConnectionMeta;
+    /** Ownership mode indicating who controls credentials. */
+    ownershipMode: IntegrationOwnershipMode;
+    /** External provider account/project identifier (BYOK scenarios). */
+    externalAccountId?: string;
+    /** Encrypted configuration matching IntegrationSpec.configSchema. */
+    config: Record<string, unknown>;
+    /** Reference to external secret store entry containing credentials. */
+    secretProvider: string;
+    secretRef: string;
+    status: ConnectionStatus;
+    /** Last health check result. */
+    health?: IntegrationConnectionHealth;
+    /** Usage tracking. */
+    usage?: IntegrationUsageMetrics;
+}

package/dist/integrations/connection.js

@@ -0,0 +1 @@
+// @bun

package/dist/integrations/docs/integrations.docblock.d.ts

@@ -0,0 +1,2 @@
+import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
+export declare const tech_contracts_integrations_DocBlocks: DocBlock[];

package/dist/integrations/docs/integrations.docblock.js

@@ -0,0 +1,110 @@
+// @bun
+// src/integrations/docs/integrations.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts-spec/docs/registry";
+var tech_contracts_integrations_DocBlocks = [
+  {
+    id: "docs.tech.contracts.integrations",
+    title: "ContractSpec Integrations",
+    summary: "Provider-agnostic integration contracts: specs, connections, secrets, health checks, and runtime guards.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/tech/contracts/integrations",
+    tags: ["tech", "contracts", "integrations"],
+    body: `# ContractSpec Integrations
+
+This document describes the integration architecture that powers ContractSpec-based apps. It focuses on provider-agnostic contracts, secret management, health checks, and runtime guards.
+
+## Core Concepts
+
+- **IntegrationSpec** \u2013 declarative description of a provider that lists supported ownership modes, capability mappings, configuration schema, secret schema, health check policy, and documentation metadata.
+- **IntegrationConnection** \u2013 tenant/environment binding to a provider (\`meta\` + ownership mode + config + \`secretRef\`). Secrets are never embedded in specs or configs.
+- **AppIntegrationSlot** \u2013 blueprint-level requirement that declares which integration categories/capabilities must be satisfied at runtime (e.g. \`primaryLLM\`, \`primaryVectorDb\`).
+- **AppIntegrationBinding** \u2013 tenant-level slot \u2192 connection mapping.
+- **ResolvedIntegration** \u2013 runtime view containing slot metadata, connection details, and the resolved IntegrationSpec.
+
+## Registered Providers
+
+The contracts library ships twenty-two priority providers in \`packages/libs/contracts/src/integrations/providers\`:
+
+| Category      | Provider         | Key                         | Notes                                             |
+| ------------- | ---------------- | --------------------------- | ------------------------------------------------- |
+| payments      | Stripe           | \`payments.stripe\`          | Card + invoice flows, managed or BYOK credentials |
+| email (out)   | Postmark         | \`email.postmark\`           | Transactional email delivery                      |
+| email (in)    | Gmail API        | \`email.gmail\`              | Thread ingestion (OAuth BYOK or service account)  |
+| calendar      | Google Calendar  | \`calendar.google\`          | Event scheduling via service account              |
+| analytics     | PostHog          | \`analytics.posthog\`         | Product analytics, flags, and HogQL queries       |
+| vector-db     | Qdrant           | \`vectordb.qdrant\`          | Embedding storage & search                        |
+| vector-db     | Supabase pgvector| \`vectordb.supabase\`        | Embedding storage & search on Supabase Postgres   |
+| database      | Supabase Postgres| \`database.supabase\`        | SQL queries and transactions on Supabase Postgres |
+| storage       | Google Cloud     | \`storage.gcs\`              | Object storage                                    |
+| ai-llm        | Mistral          | \`ai-llm.mistral\`           | Primary chat + embedding provider                 |
+| ai-voice      | ElevenLabs       | \`ai-voice.elevenlabs\`      | Text-to-speech synthesis                          |
+| ai-voice      | Gradium          | \`ai-voice.gradium\`         | Low-latency text-to-speech synthesis              |
+| ai-voice      | Fal Chatterbox   | \`ai-voice.fal\`             | Chatterbox text-to-speech via queue API           |
+| sms           | Twilio SMS       | \`sms.twilio\`               | Urgent and fallback reminders                     |
+| open-banking  | Powens           | \`openbanking.powens\`       | Read-only account, transaction, and balance sync  |
+| project-management | Linear       | \`project-management.linear\` | Issues, project tracking, and team tasks          |
+| project-management | Jira Cloud   | \`project-management.jira\`   | Work item sync for Jira Cloud                     |
+| project-management | Notion       | \`project-management.notion\` | Shared summaries and task databases               |
+| meeting-recorder | Granola       | \`meeting-recorder.granola\`  | Meeting notes + transcripts via API or MCP        |
+| meeting-recorder | tl;dv         | \`meeting-recorder.tldv\`     | Meeting recordings, transcripts, and webhooks     |
+| meeting-recorder | Fireflies     | \`meeting-recorder.fireflies\` | GraphQL transcripts + webhook events              |
+| meeting-recorder | Fathom        | \`meeting-recorder.fathom\`   | External API meetings + webhook registration      |
+
+PostHog adapters also support read access (events, persons, insights, cohorts, annotations) via analytics providers.
+
+Each provider ships with:
+
+- Strongly typed adapter interfaces (\`payments.ts\`, \`llm.ts\`, etc.)
+- A concrete SDK-backed implementation under \`providers/impls\`
+- Unit tests validating adapter behaviour and health checks
+
+### Example package
+
+- Supabase dual-store example (vector + SQL): \`@contractspec/example.integration-supabase\`
+
+### Canonical registry builder
+
+To list all shipped specs at runtime, use:
+
+- \`createDefaultIntegrationSpecRegistry()\` from \`@contractspec/lib.contracts-integrations\`
+
+## Secret Management
+
+All integrations rely on the \`SecretProvider\` abstraction defined in \`integrations/secrets\`. Providers ship with the contracts library and are orchestrated by the \`SecretProviderManager\` composite:
+
+- **EnvSecretProvider** (\`env-secret-provider.ts\`) \u2013 high-priority, read-only overrides backed by environment variables.
+  - Supports the \`env://VARIABLE_NAME\` scheme
+  - Supports overrides for other schemes via \`?env=ALIAS\` or derived uppercase keys
+- **GcpSecretManagerProvider** (\`gcp-secret-manager.ts\`) \u2013 versioned secrets stored in Google Cloud Secret Manager.
+  - Example: \`gcp://projects/demo/secrets/stripe-key/versions/latest\`
+- **AwsSecretsManagerProvider** (\`aws-secret-manager.ts\`) \u2013 AWS Secrets Manager backend.
+  - Example: \`aws://secretsmanager/eu-west-1/my-secret?version=AWSCURRENT\`
+  - Region may be in the reference or provided via \`AWS_REGION\` / \`AWS_DEFAULT_REGION\`
+- **ScalewaySecretManagerProvider** (\`scaleway-secret-manager.ts\`) \u2013 Scaleway Secret Manager backend.
+  - Example (id): \`scw://secret-manager/fr-par/1234...-uuid?version=latest\`
+  - Example (name, create+write): \`scw://secret-manager/fr-par/my-secret-name\`
+  - Requires \`SCW_SECRET_KEY\` (token) and \`SCW_DEFAULT_PROJECT_ID\` when creating secrets by name
+
+The manager attempts providers in priority order (environment first, then cloud providers). Key points:
+
+- \`secretRef\` is a URI-like reference; raw secrets are never returned.
+- \`IntegrationCallGuard\` fetches and parses secrets before executing a provider adapter.
+- Local development can rely on \`.env\` files, while staging/production reference cloud secret stores.
+
+## Health Checks & Telemetry
+
+- Each IntegrationSpec optionally declares \`healthCheck.method\` and timeouts.
+- \`IntegrationCallGuard\` enforces connection status, wraps retries with exponential back-off, and emits telemetry events tagged with tenant/app/slot metadata.
+- Validation rules (\`app-config/validation.ts\`) surface issues at publish time (slot mismatch, unsupported ownership modes, missing capabilities, etc.).
+
+## Studio persistence (ContractSpec Studio)
+
+ContractSpec Studio persists tenant \`IntegrationConnection\` records in Postgres (Prisma model \`IntegrationConnection\` in \`@contractspec/lib.database-studio\`) and exposes a platform-admin management surface (see the Studio platform admin panel).
+`
+  }
+];
+registerDocBlocks(tech_contracts_integrations_DocBlocks);
+export {
+  tech_contracts_integrations_DocBlocks
+};

package/dist/integrations/health.d.ts

@@ -0,0 +1,17 @@
+import type { IntegrationConnectionHealth } from './connection';
+import type { IntegrationContext, IntegrationTelemetryEmitter } from './runtime';
+export interface IntegrationHealthCheckResult extends IntegrationConnectionHealth {
+    metadata?: Record<string, string>;
+}
+export type IntegrationHealthCheckExecutor = (context: IntegrationContext) => Promise<void>;
+export interface IntegrationHealthServiceOptions {
+    telemetry?: IntegrationTelemetryEmitter;
+    now?: () => Date;
+}
+export declare class IntegrationHealthService {
+    private readonly telemetry?;
+    private readonly nowFn;
+    constructor(options?: IntegrationHealthServiceOptions);
+    check(context: IntegrationContext, executor: IntegrationHealthCheckExecutor): Promise<IntegrationHealthCheckResult>;
+    private emitTelemetry;
+}

package/dist/integrations/health.js

@@ -0,0 +1,73 @@
+// @bun
+// src/integrations/health.ts
+class IntegrationHealthService {
+  telemetry;
+  nowFn;
+  constructor(options = {}) {
+    this.telemetry = options.telemetry;
+    this.nowFn = options.now ?? (() => new Date);
+  }
+  async check(context, executor) {
+    const start = this.nowFn();
+    try {
+      await executor(context);
+      const end = this.nowFn();
+      const result = {
+        status: "connected",
+        checkedAt: end,
+        latencyMs: end.getTime() - start.getTime()
+      };
+      this.emitTelemetry(context, result, "success");
+      return result;
+    } catch (error) {
+      const end = this.nowFn();
+      const message = error instanceof Error ? error.message : "Unknown error";
+      const code = extractErrorCode(error);
+      const result = {
+        status: "error",
+        checkedAt: end,
+        latencyMs: end.getTime() - start.getTime(),
+        errorMessage: message,
+        errorCode: code
+      };
+      this.emitTelemetry(context, result, "error", code, message);
+      return result;
+    }
+  }
+  emitTelemetry(context, result, status, errorCode, errorMessage) {
+    if (!this.telemetry)
+      return;
+    this.telemetry.record({
+      tenantId: context.tenantId,
+      appId: context.appId,
+      environment: context.environment,
+      slotId: context.slotId,
+      integrationKey: context.spec.meta.key,
+      integrationVersion: context.spec.meta.version,
+      connectionId: context.connection.meta.id,
+      status,
+      durationMs: result.latencyMs,
+      errorCode,
+      errorMessage,
+      occurredAt: result.checkedAt ?? this.nowFn(),
+      metadata: {
+        ...context.trace ? {
+          blueprint: `${context.trace.blueprintName}.v${context.trace.blueprintVersion}`,
+          configVersion: context.trace.configVersion
+        } : {},
+        status: result.status
+      }
+    });
+  }
+}
+function extractErrorCode(error) {
+  if (!error || typeof error !== "object")
+    return;
+  const candidate = error;
+  if (candidate.code == null)
+    return;
+  return String(candidate.code);
+}
+export {
+  IntegrationHealthService
+};

package/dist/integrations/health.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/integrations/index.d.ts

@@ -0,0 +1,11 @@
+export * from './spec';
+export * from './connection';
+export * from './binding';
+export * from './providers';
+export * from './openbanking/models';
+export * from './openbanking/contracts';
+export * from './openbanking/guards';
+export * from './openbanking/telemetry';
+export { MeetingParticipantRecord, MeetingTranscriptSegmentRecord, MeetingRecorderWebhookEventRecord, MeetingRecord as MeetingRecordModel, MeetingTranscriptRecord as MeetingTranscriptRecordModel, } from './meeting-recorder/models';
+export * from './meeting-recorder/contracts';
+export * from './meeting-recorder/telemetry';