@lssm/lib.contracts 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217073102

package/dist/integrations/contracts.js

@@ -1 +1,388 @@
-import{l as e}from"../schema/dist/ScalarTypeEnum.js";import{t}from"../schema/dist/SchemaModel.js";import"../schema/dist/index.js";import{defineCommand as n,defineQuery as r}from"../spec.js";const i=new t({name:`IntegrationConnectionRecord`,fields:{id:{type:e.ID(),isOptional:!1},tenantId:{type:e.ID(),isOptional:!1},integrationKey:{type:e.NonEmptyString(),isOptional:!1},integrationVersion:{type:e.Int_unsecure(),isOptional:!1},label:{type:e.String_unsecure(),isOptional:!1},ownershipMode:{type:e.String_unsecure(),isOptional:!1},externalAccountId:{type:e.String_unsecure(),isOptional:!0},secretProvider:{type:e.String_unsecure(),isOptional:!1},secretRef:{type:e.String_unsecure(),isOptional:!1},status:{type:e.String_unsecure(),isOptional:!1},environment:{type:e.String_unsecure(),isOptional:!0},healthStatus:{type:e.String_unsecure(),isOptional:!0},healthCheckedAt:{type:e.DateTime(),isOptional:!0},healthLatencyMs:{type:e.Float_unsecure(),isOptional:!0},healthErrorCode:{type:e.String_unsecure(),isOptional:!0},healthErrorMessage:{type:e.String_unsecure(),isOptional:!0},usageRequestCount:{type:e.Int_unsecure(),isOptional:!0},usageSuccessCount:{type:e.Int_unsecure(),isOptional:!0},usageErrorCount:{type:e.Int_unsecure(),isOptional:!0},usageLastUsedAt:{type:e.DateTime(),isOptional:!0},usageLastErrorAt:{type:e.DateTime(),isOptional:!0},usageLastErrorCode:{type:e.String_unsecure(),isOptional:!0},createdAt:{type:e.DateTime(),isOptional:!0},updatedAt:{type:e.DateTime(),isOptional:!0}}}),a=new t({name:`CreateIntegrationConnectionInput`,fields:{tenantId:{type:e.ID(),isOptional:!1},integrationKey:{type:e.NonEmptyString(),isOptional:!1},integrationVersion:{type:e.Int_unsecure(),isOptional:!1},label:{type:e.String_unsecure(),isOptional:!1},ownershipMode:{type:e.String_unsecure(),isOptional:!1},externalAccountId:{type:e.String_unsecure(),isOptional:!0},secretProvider:{type:e.String_unsecure(),isOptional:!1},secretRef:{type:e.String_unsecure(),isOptional:!1},environment:{type:e.String_unsecure(),isOptional:!0},config:{type:e.JSONObject(),isOptional:!1}}}),o=new t({name:`UpdateIntegrationConnectionInput`,fields:{connectionId:{type:e.ID(),isOptional:!1},label:{type:e.String_unsecure(),isOptional:!0},status:{type:e.String_unsecure(),isOptional:!0},ownershipMode:{type:e.String_unsecure(),isOptional:!0},externalAccountId:{type:e.String_unsecure(),isOptional:!0},secretProvider:{type:e.String_unsecure(),isOptional:!0},secretRef:{type:e.String_unsecure(),isOptional:!0},config:{type:e.JSONObject(),isOptional:!0}}}),s=new t({name:`DeleteIntegrationConnectionInput`,fields:{connectionId:{type:e.ID(),isOptional:!1}}}),c=new t({name:`ListIntegrationConnectionsInput`,fields:{tenantId:{type:e.ID(),isOptional:!1},category:{type:e.String_unsecure(),isOptional:!0},status:{type:e.String_unsecure(),isOptional:!0}}}),l=new t({name:`ListIntegrationConnectionsOutput`,fields:{connections:{type:i,isOptional:!1,isArray:!0}}}),u=new t({name:`TestIntegrationConnectionInput`,fields:{connectionId:{type:e.ID(),isOptional:!1}}}),d=new t({name:`TestIntegrationConnectionOutput`,fields:{success:{type:e.Boolean(),isOptional:!1},status:{type:e.String_unsecure(),isOptional:!0},latencyMs:{type:e.Float_unsecure(),isOptional:!0},error:{type:e.String_unsecure(),isOptional:!0},errorCode:{type:e.String_unsecure(),isOptional:!0}}}),f=new t({name:`DeleteIntegrationConnectionOutput`,fields:{success:{type:e.Boolean(),isOptional:!1}}}),p=n({meta:{name:`integrations.connection.create`,version:1,description:`Create a new integration connection for a tenant.`,goal:`Provision a tenant-scoped connection to an external provider.`,context:`Used by Ops or the App Studio to configure external integrations such as Stripe or Qdrant.`,owners:[`platform.integrations`],tags:[`integration`,`connections`],stability:`experimental`},io:{input:a,output:i},policy:{auth:`admin`,policies:[{name:`platform.integration.manage`,version:1}]}}),m=n({meta:{name:`integrations.connection.update`,version:1,description:`Update metadata or credentials for an integration connection.`,goal:`Allow secure rotation of credentials and metadata adjustments.`,context:`Supports rotating API keys, toggling status, or updating labels for tenant integrations.`,owners:[`platform.integrations`],tags:[`integration`,`connections`],stability:`experimental`},io:{input:o,output:i},policy:{auth:`admin`,policies:[{name:`platform.integration.manage`,version:1}]}}),h=n({meta:{name:`integrations.connection.delete`,version:1,description:`Delete an integration connection for a tenant.`,goal:`Safely remove credentials and disable connector usage.`,context:`Ensures connections are de-provisioned when no longer needed or breached.`,owners:[`platform.integrations`],tags:[`integration`,`connections`],stability:`experimental`},io:{input:s,output:f},policy:{auth:`admin`,policies:[{name:`platform.integration.manage`,version:1}]}}),g=r({meta:{name:`integrations.connection.list`,version:1,description:`List integration connections for a tenant.`,goal:`Provide visibility into configured integrations and their status.`,context:`Used by the App Studio and Ops flows to show bindings and health.`,owners:[`platform.integrations`],tags:[`integration`,`connections`],stability:`experimental`},io:{input:c,output:l},policy:{auth:`admin`,policies:[{name:`platform.integration.read`,version:1}]}}),_=n({meta:{name:`integrations.connection.test`,version:1,description:`Run a health check against a configured integration connection.`,goal:`Validate credentials and connectivity for external providers.`,context:`Triggered manually or by background monitors to confirm provider availability.`,owners:[`platform.integrations`],tags:[`integration`,`connections`],stability:`experimental`},io:{input:u,output:d},policy:{auth:`admin`,policies:[{name:`platform.integration.manage`,version:1}]}}),v={CreateIntegrationConnection:p,UpdateIntegrationConnection:m,DeleteIntegrationConnection:h,ListIntegrationConnections:g,TestIntegrationConnection:_};function y(e){return e.register(p).register(m).register(h).register(g).register(_)}export{p as CreateIntegrationConnection,h as DeleteIntegrationConnection,g as ListIntegrationConnections,_ as TestIntegrationConnection,m as UpdateIntegrationConnection,v as integrationContracts,y as registerIntegrationContracts};
+import { ScalarTypeEnum } from "../schema/dist/ScalarTypeEnum.js";
+import { SchemaModel } from "../schema/dist/SchemaModel.js";
+import "../schema/dist/index.js";
+import { defineCommand, defineQuery } from "../spec.js";
+
+//#region src/integrations/contracts.ts
+const IntegrationConnectionRecord = new SchemaModel({
+	name: "IntegrationConnectionRecord",
+	fields: {
+		id: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		integrationKey: {
+			type: ScalarTypeEnum.NonEmptyString(),
+			isOptional: false
+		},
+		integrationVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		label: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		ownershipMode: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		externalAccountId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		secretProvider: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		secretRef: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		environment: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		healthStatus: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		healthCheckedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		healthLatencyMs: {
+			type: ScalarTypeEnum.Float_unsecure(),
+			isOptional: true
+		},
+		healthErrorCode: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		healthErrorMessage: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		usageRequestCount: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		usageSuccessCount: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		usageErrorCount: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		usageLastUsedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		usageLastErrorAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		usageLastErrorCode: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		createdAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		updatedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		}
+	}
+});
+const CreateIntegrationConnectionInput = new SchemaModel({
+	name: "CreateIntegrationConnectionInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		integrationKey: {
+			type: ScalarTypeEnum.NonEmptyString(),
+			isOptional: false
+		},
+		integrationVersion: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		label: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		ownershipMode: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		externalAccountId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		secretProvider: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		secretRef: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: false
+		},
+		environment: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		config: {
+			type: ScalarTypeEnum.JSONObject(),
+			isOptional: false
+		}
+	}
+});
+const UpdateIntegrationConnectionInput = new SchemaModel({
+	name: "UpdateIntegrationConnectionInput",
+	fields: {
+		connectionId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		label: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		ownershipMode: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		externalAccountId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		secretProvider: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		secretRef: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		config: {
+			type: ScalarTypeEnum.JSONObject(),
+			isOptional: true
+		}
+	}
+});
+const DeleteIntegrationConnectionInput = new SchemaModel({
+	name: "DeleteIntegrationConnectionInput",
+	fields: { connectionId: {
+		type: ScalarTypeEnum.ID(),
+		isOptional: false
+	} }
+});
+const ListIntegrationConnectionsInput = new SchemaModel({
+	name: "ListIntegrationConnectionsInput",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		category: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const ListIntegrationConnectionsOutput = new SchemaModel({
+	name: "ListIntegrationConnectionsOutput",
+	fields: { connections: {
+		type: IntegrationConnectionRecord,
+		isOptional: false,
+		isArray: true
+	} }
+});
+const TestIntegrationConnectionInput = new SchemaModel({
+	name: "TestIntegrationConnectionInput",
+	fields: { connectionId: {
+		type: ScalarTypeEnum.ID(),
+		isOptional: false
+	} }
+});
+const TestIntegrationConnectionOutput = new SchemaModel({
+	name: "TestIntegrationConnectionOutput",
+	fields: {
+		success: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: false
+		},
+		status: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		latencyMs: {
+			type: ScalarTypeEnum.Float_unsecure(),
+			isOptional: true
+		},
+		error: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		errorCode: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const DeleteIntegrationConnectionOutput = new SchemaModel({
+	name: "DeleteIntegrationConnectionOutput",
+	fields: { success: {
+		type: ScalarTypeEnum.Boolean(),
+		isOptional: false
+	} }
+});
+const CreateIntegrationConnection = defineCommand({
+	meta: {
+		name: "integrations.connection.create",
+		version: 1,
+		description: "Create a new integration connection for a tenant.",
+		goal: "Provision a tenant-scoped connection to an external provider.",
+		context: "Used by Ops or the App Studio to configure external integrations such as Stripe or Qdrant.",
+		owners: ["platform.integrations"],
+		tags: ["integration", "connections"],
+		stability: "experimental"
+	},
+	io: {
+		input: CreateIntegrationConnectionInput,
+		output: IntegrationConnectionRecord
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.integration.manage",
+			version: 1
+		}]
+	}
+});
+const UpdateIntegrationConnection = defineCommand({
+	meta: {
+		name: "integrations.connection.update",
+		version: 1,
+		description: "Update metadata or credentials for an integration connection.",
+		goal: "Allow secure rotation of credentials and metadata adjustments.",
+		context: "Supports rotating API keys, toggling status, or updating labels for tenant integrations.",
+		owners: ["platform.integrations"],
+		tags: ["integration", "connections"],
+		stability: "experimental"
+	},
+	io: {
+		input: UpdateIntegrationConnectionInput,
+		output: IntegrationConnectionRecord
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.integration.manage",
+			version: 1
+		}]
+	}
+});
+const DeleteIntegrationConnection = defineCommand({
+	meta: {
+		name: "integrations.connection.delete",
+		version: 1,
+		description: "Delete an integration connection for a tenant.",
+		goal: "Safely remove credentials and disable connector usage.",
+		context: "Ensures connections are de-provisioned when no longer needed or breached.",
+		owners: ["platform.integrations"],
+		tags: ["integration", "connections"],
+		stability: "experimental"
+	},
+	io: {
+		input: DeleteIntegrationConnectionInput,
+		output: DeleteIntegrationConnectionOutput
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.integration.manage",
+			version: 1
+		}]
+	}
+});
+const ListIntegrationConnections = defineQuery({
+	meta: {
+		name: "integrations.connection.list",
+		version: 1,
+		description: "List integration connections for a tenant.",
+		goal: "Provide visibility into configured integrations and their status.",
+		context: "Used by the App Studio and Ops flows to show bindings and health.",
+		owners: ["platform.integrations"],
+		tags: ["integration", "connections"],
+		stability: "experimental"
+	},
+	io: {
+		input: ListIntegrationConnectionsInput,
+		output: ListIntegrationConnectionsOutput
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.integration.read",
+			version: 1
+		}]
+	}
+});
+const TestIntegrationConnection = defineCommand({
+	meta: {
+		name: "integrations.connection.test",
+		version: 1,
+		description: "Run a health check against a configured integration connection.",
+		goal: "Validate credentials and connectivity for external providers.",
+		context: "Triggered manually or by background monitors to confirm provider availability.",
+		owners: ["platform.integrations"],
+		tags: ["integration", "connections"],
+		stability: "experimental"
+	},
+	io: {
+		input: TestIntegrationConnectionInput,
+		output: TestIntegrationConnectionOutput
+	},
+	policy: {
+		auth: "admin",
+		policies: [{
+			name: "platform.integration.manage",
+			version: 1
+		}]
+	}
+});
+const integrationContracts = {
+	CreateIntegrationConnection,
+	UpdateIntegrationConnection,
+	DeleteIntegrationConnection,
+	ListIntegrationConnections,
+	TestIntegrationConnection
+};
+function registerIntegrationContracts(registry) {
+	return registry.register(CreateIntegrationConnection).register(UpdateIntegrationConnection).register(DeleteIntegrationConnection).register(ListIntegrationConnections).register(TestIntegrationConnection);
+}
+
+//#endregion
+export { CreateIntegrationConnection, DeleteIntegrationConnection, ListIntegrationConnections, TestIntegrationConnection, UpdateIntegrationConnection, integrationContracts, registerIntegrationContracts };

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

@@ -1 +1,95 @@
-import{registerDocBlocks as e}from"../../docs/registry.js";import"../../registry.js";const t=[{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\n\nThis document describes the integration architecture that powers ContractSpec-based apps. It focuses on provider-agnostic contracts, secret management, health checks, and runtime guards.\n\n## Core Concepts\n\n- **IntegrationSpec** – declarative description of a provider that lists supported ownership modes, capability mappings, configuration schema, secret schema, health check policy, and documentation metadata.\n- **IntegrationConnection** – tenant/environment binding to a provider (`meta` + ownership mode + config + `secretRef`). Secrets are never embedded in specs or configs.\n- **AppIntegrationSlot** – blueprint-level requirement that declares which integration categories/capabilities must be satisfied at runtime (e.g. `primaryLLM`, `primaryVectorDb`).\n- **AppIntegrationBinding** – tenant-level slot → connection mapping.\n- **ResolvedIntegration** – runtime view containing slot metadata, connection details, and the resolved IntegrationSpec.\n\n## Registered Providers\n\nThe contracts library ships ten priority providers in `packages/libs/contracts/src/integrations/providers`:\n\n| Category      | Provider         | Key                         | Notes                                             |\n| ------------- | ---------------- | --------------------------- | ------------------------------------------------- |\n| payments      | Stripe           | `payments.stripe`          | Card + invoice flows, managed or BYOK credentials |\n| email (out)   | Postmark         | `email.postmark`           | Transactional email delivery                      |\n| email (in)    | Gmail API        | `email.gmail`              | Thread ingestion (OAuth BYOK or service account)  |\n| calendar      | Google Calendar  | `calendar.google`          | Event scheduling via service account              |\n| vector-db     | Qdrant           | `vectordb.qdrant`          | Embedding storage & search                        |\n| storage       | Google Cloud     | `storage.gcs`              | Object storage                                    |\n| ai-llm        | Mistral          | `ai-llm.mistral`           | Primary chat + embedding provider                 |\n| ai-voice      | ElevenLabs       | `ai-voice.elevenlabs`      | Text-to-speech synthesis                          |\n| sms           | Twilio SMS       | `sms.twilio`               | Urgent and fallback reminders                     |\n| open-banking  | Powens           | `openbanking.powens`       | Read-only account, transaction, and balance sync  |\n\nEach provider ships with:\n\n- Strongly typed adapter interfaces (`payments.ts`, `llm.ts`, etc.)\n- A concrete SDK-backed implementation under `providers/impls`\n- Unit tests validating adapter behaviour and health checks\n\n### Canonical registry builder\n\nTo list all shipped specs at runtime, use:\n\n- `createDefaultIntegrationSpecRegistry()` from `@lssm/lib.contracts/integrations/providers/registry`\n\n## Secret Management\n\nAll integrations rely on the `SecretProvider` abstraction defined in `integrations/secrets`. Providers ship with the contracts library and are orchestrated by the `SecretProviderManager` composite:\n\n- **EnvSecretProvider** (`env-secret-provider.ts`) – high-priority, read-only overrides backed by environment variables.\n  - Supports the `env://VARIABLE_NAME` scheme\n  - Supports overrides for other schemes via `?env=ALIAS` or derived uppercase keys\n- **GcpSecretManagerProvider** (`gcp-secret-manager.ts`) – versioned secrets stored in Google Cloud Secret Manager.\n  - Example: `gcp://projects/demo/secrets/stripe-key/versions/latest`\n- **AwsSecretsManagerProvider** (`aws-secret-manager.ts`) – AWS Secrets Manager backend.\n  - Example: `aws://secretsmanager/eu-west-1/my-secret?version=AWSCURRENT`\n  - Region may be in the reference or provided via `AWS_REGION` / `AWS_DEFAULT_REGION`\n- **ScalewaySecretManagerProvider** (`scaleway-secret-manager.ts`) – Scaleway Secret Manager backend.\n  - Example (id): `scw://secret-manager/fr-par/1234...-uuid?version=latest`\n  - Example (name, create+write): `scw://secret-manager/fr-par/my-secret-name`\n  - Requires `SCW_SECRET_KEY` (token) and `SCW_DEFAULT_PROJECT_ID` when creating secrets by name\n\nThe manager attempts providers in priority order (environment first, then cloud providers). Key points:\n\n- `secretRef` is a URI-like reference; raw secrets are never returned.\n- `IntegrationCallGuard` fetches and parses secrets before executing a provider adapter.\n- Local development can rely on `.env` files, while staging/production reference cloud secret stores.\n\n## Health Checks & Telemetry\n\n- Each IntegrationSpec optionally declares `healthCheck.method` and timeouts.\n- `IntegrationCallGuard` enforces connection status, wraps retries with exponential back-off, and emits telemetry events tagged with tenant/app/slot metadata.\n- Validation rules (`app-config/validation.ts`) surface issues at publish time (slot mismatch, unsupported ownership modes, missing capabilities, etc.).\n\n## Studio persistence (ContractSpec Studio)\n\nContractSpec Studio persists tenant `IntegrationConnection` records in Postgres (Prisma model `IntegrationConnection` in `@lssm/lib.database-contractspec-studio`) and exposes a platform-admin management surface (see the Studio platform admin panel).\n"}];e(t);export{t as tech_contracts_integrations_DocBlocks};
+import { registerDocBlocks } from "../../docs/registry.js";
+import "../../registry.js";
+
+//#region src/integrations/docs/integrations.docblock.ts
+const 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** – declarative description of a provider that lists supported ownership modes, capability mappings, configuration schema, secret schema, health check policy, and documentation metadata.
+- **IntegrationConnection** – tenant/environment binding to a provider (\`meta\` + ownership mode + config + \`secretRef\`). Secrets are never embedded in specs or configs.
+- **AppIntegrationSlot** – blueprint-level requirement that declares which integration categories/capabilities must be satisfied at runtime (e.g. \`primaryLLM\`, \`primaryVectorDb\`).
+- **AppIntegrationBinding** – tenant-level slot → connection mapping.
+- **ResolvedIntegration** – runtime view containing slot metadata, connection details, and the resolved IntegrationSpec.
+
+## Registered Providers
+
+The contracts library ships ten 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              |
+| vector-db     | Qdrant           | \`vectordb.qdrant\`          | Embedding storage & search                        |
+| 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                          |
+| sms           | Twilio SMS       | \`sms.twilio\`               | Urgent and fallback reminders                     |
+| open-banking  | Powens           | \`openbanking.powens\`       | Read-only account, transaction, and balance sync  |
+
+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
+
+### Canonical registry builder
+
+To list all shipped specs at runtime, use:
+
+- \`createDefaultIntegrationSpecRegistry()\` from \`@lssm/lib.contracts/integrations/providers/registry\`
+
+## 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\`) – 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\`) – versioned secrets stored in Google Cloud Secret Manager.
+  - Example: \`gcp://projects/demo/secrets/stripe-key/versions/latest\`
+- **AwsSecretsManagerProvider** (\`aws-secret-manager.ts\`) – 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\`) – 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 \`@lssm/lib.database-contractspec-studio\`) and exposes a platform-admin management surface (see the Studio platform admin panel).
+`
+}];
+registerDocBlocks(tech_contracts_integrations_DocBlocks);
+
+//#endregion
+export { tech_contracts_integrations_DocBlocks };

package/dist/integrations/health.js

@@ -1 +1,69 @@
-var e=class{telemetry;nowFn;constructor(e={}){this.telemetry=e.telemetry,this.nowFn=e.now??(()=>new Date)}async check(e,n){let r=this.nowFn();try{await n(e);let t=this.nowFn(),i={status:`connected`,checkedAt:t,latencyMs:t.getTime()-r.getTime()};return this.emitTelemetry(e,i,`success`),i}catch(n){let i=this.nowFn(),a=n instanceof Error?n.message:`Unknown error`,o=t(n),s={status:`error`,checkedAt:i,latencyMs:i.getTime()-r.getTime(),errorMessage:a,errorCode:o};return this.emitTelemetry(e,s,`error`,o,a),s}}emitTelemetry(e,t,n,r,i){this.telemetry&&this.telemetry.record({tenantId:e.tenantId,appId:e.appId,environment:e.environment,slotId:e.slotId,integrationKey:e.spec.meta.key,integrationVersion:e.spec.meta.version,connectionId:e.connection.meta.id,status:n,durationMs:t.latencyMs,errorCode:r,errorMessage:i,occurredAt:t.checkedAt??this.nowFn(),metadata:{...e.trace?{blueprint:`${e.trace.blueprintName}.v${e.trace.blueprintVersion}`,configVersion:e.trace.configVersion}:{},status:t.status}})}};function t(e){if(!e||typeof e!=`object`)return;let t=e;if(t.code!=null)return String(t.code)}export{e as IntegrationHealthService};
+//#region src/integrations/health.ts
+var IntegrationHealthService = class {
+	telemetry;
+	nowFn;
+	constructor(options = {}) {
+		this.telemetry = options.telemetry;
+		this.nowFn = options.now ?? (() => /* @__PURE__ */ 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 void 0;
+	const candidate = error;
+	if (candidate.code == null) return void 0;
+	return String(candidate.code);
+}
+
+//#endregion
+export { IntegrationHealthService };

package/dist/integrations/index.js

@@ -1 +1,23 @@
-import{IntegrationSpecRegistry as e,makeIntegrationSpecKey as t}from"./spec.js";import{registerStripeIntegration as n,stripeIntegrationSpec as r}from"./providers/stripe.js";import{postmarkIntegrationSpec as i,registerPostmarkIntegration as a}from"./providers/postmark.js";import{qdrantIntegrationSpec as o,registerQdrantIntegration as s}from"./providers/qdrant.js";import{mistralIntegrationSpec as c,registerMistralIntegration as l}from"./providers/mistral.js";import{elevenLabsIntegrationSpec as u,registerElevenLabsIntegration as d}from"./providers/elevenlabs.js";import{gmailIntegrationSpec as f,registerGmailIntegration as p}from"./providers/gmail.js";import{googleCalendarIntegrationSpec as m,registerGoogleCalendarIntegration as h}from"./providers/google-calendar.js";import{registerTwilioSmsIntegration as g,twilioSmsIntegrationSpec as _}from"./providers/twilio-sms.js";import{gcsStorageIntegrationSpec as v,registerGcsStorageIntegration as y}from"./providers/gcs-storage.js";import{powensIntegrationSpec as b,registerPowensIntegration as x}from"./providers/powens.js";import{createDefaultIntegrationSpecRegistry as S}from"./providers/registry.js";import"./providers/index.js";import{AccountBalanceRecord as C,BankAccountRecord as w,BankTransactionRecord as T}from"./openbanking/models.js";import{OPENBANKING_PII_FIELDS as E,OPENBANKING_TELEMETRY_EVENTS as D,redactOpenBankingTelemetryPayload as O}from"./openbanking/telemetry.js";import{OpenBankingGetAccount as k,OpenBankingListAccounts as A,OpenBankingSyncAccounts as j}from"./openbanking/contracts/accounts.js";import{OpenBankingListTransactions as M,OpenBankingSyncTransactions as N}from"./openbanking/contracts/transactions.js";import{OpenBankingGetBalances as P,OpenBankingRefreshBalances as F}from"./openbanking/contracts/balances.js";import{OpenBankingFeature as I}from"./openbanking/openbanking.feature.js";import{registerOpenBankingContracts as L}from"./openbanking/contracts/index.js";import{assertPrimaryOpenBankingReady as R,ensurePrimaryOpenBankingIntegration as z}from"./openbanking/guards.js";export{C as AccountBalanceRecord,w as BankAccountRecord,T as BankTransactionRecord,e as IntegrationSpecRegistry,E as OPENBANKING_PII_FIELDS,D as OPENBANKING_TELEMETRY_EVENTS,I as OpenBankingFeature,k as OpenBankingGetAccount,P as OpenBankingGetBalances,A as OpenBankingListAccounts,M as OpenBankingListTransactions,F as OpenBankingRefreshBalances,j as OpenBankingSyncAccounts,N as OpenBankingSyncTransactions,R as assertPrimaryOpenBankingReady,S as createDefaultIntegrationSpecRegistry,u as elevenLabsIntegrationSpec,z as ensurePrimaryOpenBankingIntegration,v as gcsStorageIntegrationSpec,f as gmailIntegrationSpec,m as googleCalendarIntegrationSpec,t as makeIntegrationSpecKey,c as mistralIntegrationSpec,i as postmarkIntegrationSpec,b as powensIntegrationSpec,o as qdrantIntegrationSpec,O as redactOpenBankingTelemetryPayload,d as registerElevenLabsIntegration,y as registerGcsStorageIntegration,p as registerGmailIntegration,h as registerGoogleCalendarIntegration,l as registerMistralIntegration,L as registerOpenBankingContracts,a as registerPostmarkIntegration,x as registerPowensIntegration,s as registerQdrantIntegration,n as registerStripeIntegration,g as registerTwilioSmsIntegration,r as stripeIntegrationSpec,_ as twilioSmsIntegrationSpec};
+import { IntegrationSpecRegistry, makeIntegrationSpecKey } from "./spec.js";
+import { registerStripeIntegration, stripeIntegrationSpec } from "./providers/stripe.js";
+import { postmarkIntegrationSpec, registerPostmarkIntegration } from "./providers/postmark.js";
+import { qdrantIntegrationSpec, registerQdrantIntegration } from "./providers/qdrant.js";
+import { mistralIntegrationSpec, registerMistralIntegration } from "./providers/mistral.js";
+import { elevenLabsIntegrationSpec, registerElevenLabsIntegration } from "./providers/elevenlabs.js";
+import { gmailIntegrationSpec, registerGmailIntegration } from "./providers/gmail.js";
+import { googleCalendarIntegrationSpec, registerGoogleCalendarIntegration } from "./providers/google-calendar.js";
+import { registerTwilioSmsIntegration, twilioSmsIntegrationSpec } from "./providers/twilio-sms.js";
+import { gcsStorageIntegrationSpec, registerGcsStorageIntegration } from "./providers/gcs-storage.js";
+import { powensIntegrationSpec, registerPowensIntegration } from "./providers/powens.js";
+import { createDefaultIntegrationSpecRegistry } from "./providers/registry.js";
+import "./providers/index.js";
+import { AccountBalanceRecord, BankAccountRecord, BankTransactionRecord } from "./openbanking/models.js";
+import { OPENBANKING_PII_FIELDS, OPENBANKING_TELEMETRY_EVENTS, redactOpenBankingTelemetryPayload } from "./openbanking/telemetry.js";
+import { OpenBankingGetAccount, OpenBankingListAccounts, OpenBankingSyncAccounts } from "./openbanking/contracts/accounts.js";
+import { OpenBankingListTransactions, OpenBankingSyncTransactions } from "./openbanking/contracts/transactions.js";
+import { OpenBankingGetBalances, OpenBankingRefreshBalances } from "./openbanking/contracts/balances.js";
+import { OpenBankingFeature } from "./openbanking/openbanking.feature.js";
+import { registerOpenBankingContracts } from "./openbanking/contracts/index.js";
+import { assertPrimaryOpenBankingReady, ensurePrimaryOpenBankingIntegration } from "./openbanking/guards.js";
+
+export { AccountBalanceRecord, BankAccountRecord, BankTransactionRecord, IntegrationSpecRegistry, OPENBANKING_PII_FIELDS, OPENBANKING_TELEMETRY_EVENTS, OpenBankingFeature, OpenBankingGetAccount, OpenBankingGetBalances, OpenBankingListAccounts, OpenBankingListTransactions, OpenBankingRefreshBalances, OpenBankingSyncAccounts, OpenBankingSyncTransactions, assertPrimaryOpenBankingReady, createDefaultIntegrationSpecRegistry, elevenLabsIntegrationSpec, ensurePrimaryOpenBankingIntegration, gcsStorageIntegrationSpec, gmailIntegrationSpec, googleCalendarIntegrationSpec, makeIntegrationSpecKey, mistralIntegrationSpec, postmarkIntegrationSpec, powensIntegrationSpec, qdrantIntegrationSpec, redactOpenBankingTelemetryPayload, registerElevenLabsIntegration, registerGcsStorageIntegration, registerGmailIntegration, registerGoogleCalendarIntegration, registerMistralIntegration, registerOpenBankingContracts, registerPostmarkIntegration, registerPowensIntegration, registerQdrantIntegration, registerStripeIntegration, registerTwilioSmsIntegration, stripeIntegrationSpec, twilioSmsIntegrationSpec };