@contractspec/example.integration-supabase 1.57.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@contractspec/example.integration-supabase",
+  "version": "1.57.0",
+  "description": "Integration example - Supabase vector store + Postgres database wiring.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./blueprint": "./dist/blueprint.js",
+    "./connection.sample": "./dist/connection.sample.js",
+    "./docs": "./dist/docs/index.js",
+    "./docs/integration-supabase.docblock": "./dist/docs/integration-supabase.docblock.js",
+    "./example": "./dist/example.js",
+    "./runtime.sample": "./dist/runtime.sample.js",
+    "./tenant": "./dist/tenant.js",
+    "./*": "./*"
+  },
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun build:types && bun build:bundle",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@contractspec/integration.providers-impls": "1.57.0",
+    "@contractspec/integration.runtime": "1.57.0",
+    "@contractspec/lib.contracts": "1.57.0"
+  },
+  "devDependencies": {
+    "@contractspec/tool.tsdown": "1.57.0",
+    "@contractspec/tool.typescript": "1.57.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./blueprint": "./dist/blueprint.js",
+      "./connection.sample": "./dist/connection.sample.js",
+      "./docs": "./dist/docs/index.js",
+      "./docs/integration-supabase.docblock": "./dist/docs/integration-supabase.docblock.js",
+      "./example": "./dist/example.js",
+      "./runtime.sample": "./dist/runtime.sample.js",
+      "./tenant": "./dist/tenant.js",
+      "./*": "./*"
+    },
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/examples/integration-supabase"
+  },
+  "homepage": "https://contractspec.io"
+}

package/src/blueprint.ts

@@ -0,0 +1,68 @@
+import type { AppBlueprintSpec } from '@contractspec/lib.contracts/app-config/spec';
+import {
+  OwnersEnum,
+  StabilityEnum,
+  TagsEnum,
+} from '@contractspec/lib.contracts/ownership';
+
+export const supabaseKnowledgeBlueprint: AppBlueprintSpec = {
+  meta: {
+    key: 'knowledge.supabase.dual-store',
+    version: '1.0.0',
+    appId: 'knowledge-assistant',
+    title: 'Knowledge Assistant - Supabase Dual Store',
+    description:
+      'Blueprint that uses Supabase for both vector retrieval and SQL-backed analytics.',
+    domain: 'knowledge',
+    owners: [OwnersEnum.PlatformCore],
+    tags: [
+      TagsEnum.Automation,
+      'knowledge',
+      'supabase',
+      'vector-db',
+      'database',
+    ],
+    stability: StabilityEnum.Experimental,
+  },
+  capabilities: {
+    enabled: [
+      { key: 'vector-db.search', version: '1.0.0' },
+      { key: 'vector-db.storage', version: '1.0.0' },
+      { key: 'database.sql', version: '1.0.0' },
+    ],
+  },
+  integrationSlots: [
+    {
+      slotId: 'primary-vector-db',
+      requiredCategory: 'vector-db',
+      allowedModes: ['managed', 'byok'],
+      requiredCapabilities: [
+        { key: 'vector-db.search', version: '1.0.0' },
+        { key: 'vector-db.storage', version: '1.0.0' },
+      ],
+      required: true,
+      description: 'Primary semantic retrieval store for knowledge chunks.',
+    },
+    {
+      slotId: 'primary-database',
+      requiredCategory: 'database',
+      allowedModes: ['managed', 'byok'],
+      requiredCapabilities: [{ key: 'database.sql', version: '1.0.0' }],
+      required: true,
+      description:
+        'Primary SQL database for analytics and transactional reads.',
+    },
+  ],
+  workflows: {
+    ingestKnowledge: {
+      key: 'knowledge.ingest.supabase',
+      version: '1.0.0',
+    },
+    refreshMetrics: {
+      key: 'knowledge.metrics.supabase',
+      version: '1.0.0',
+    },
+  },
+  notes:
+    'Bind both slots to Supabase connections when you want shared infra for embeddings and SQL operations.',
+};

package/src/connection.sample.ts

@@ -0,0 +1,52 @@
+import type { IntegrationConnection } from '@contractspec/lib.contracts/integrations/connection';
+
+export const supabaseVectorConnection: IntegrationConnection = {
+  meta: {
+    id: 'conn-supabase-vector',
+    tenantId: 'acme-knowledge',
+    integrationKey: 'vectordb.supabase',
+    integrationVersion: '1.0.0',
+    label: 'Supabase Vector Store',
+    environment: 'production',
+    createdAt: '2026-02-06T00:00:00.000Z',
+    updatedAt: '2026-02-06T00:00:00.000Z',
+  },
+  ownershipMode: 'managed',
+  config: {
+    schema: 'public',
+    table: 'contractspec_vectors',
+    createTableIfMissing: true,
+    distanceMetric: 'cosine',
+    maxConnections: 5,
+    sslMode: 'require',
+  },
+  secretProvider: 'vault',
+  secretRef: 'vault://integrations/acme-knowledge/conn-supabase-vector',
+  status: 'connected',
+};
+
+export const supabaseDatabaseConnection: IntegrationConnection = {
+  meta: {
+    id: 'conn-supabase-db',
+    tenantId: 'acme-knowledge',
+    integrationKey: 'database.supabase',
+    integrationVersion: '1.0.0',
+    label: 'Supabase Postgres',
+    environment: 'production',
+    createdAt: '2026-02-06T00:00:00.000Z',
+    updatedAt: '2026-02-06T00:00:00.000Z',
+  },
+  ownershipMode: 'managed',
+  config: {
+    maxConnections: 10,
+    sslMode: 'require',
+  },
+  secretProvider: 'vault',
+  secretRef: 'vault://integrations/acme-knowledge/conn-supabase-db',
+  status: 'connected',
+};
+
+export const supabaseConnectionSamples: IntegrationConnection[] = [
+  supabaseVectorConnection,
+  supabaseDatabaseConnection,
+];

package/src/docs/index.ts

@@ -0,0 +1 @@
+import './integration-supabase.docblock';

package/src/docs/integration-supabase.docblock.ts

@@ -0,0 +1,58 @@
+import type { DocBlock } from '@contractspec/lib.contracts/docs';
+import { registerDocBlocks } from '@contractspec/lib.contracts/docs';
+
+const blocks: DocBlock[] = [
+  {
+    id: 'docs.examples.integration-supabase',
+    title: 'Integration Example - Supabase Vector + Postgres',
+    summary:
+      'Reference example wiring Supabase vector and SQL integrations in one tenant configuration.',
+    kind: 'reference',
+    visibility: 'public',
+    route: '/docs/examples/integration-supabase',
+    tags: ['supabase', 'vector-db', 'database', 'integration', 'example'],
+    body: `## What this example includes
+- A blueprint declaring two required integration slots:
+  - \`primary-vector-db\` bound to \`vectordb.supabase\`
+  - \`primary-database\` bound to \`database.supabase\`
+- A tenant config binding both slots.
+- Connection samples with clear \`config\` vs \`secretRef\` separation.
+- A runtime sample that upserts/searches vectors and executes SQL queries.
+
+## Why this pattern
+- Keeps integration concerns explicit and auditable in app-config.
+- Enables shared Supabase infrastructure for retrieval + analytics.
+- Preserves secret management boundaries (no credentials in config/spec).`,
+  },
+  {
+    id: 'docs.examples.integration-supabase.usage',
+    title: 'Supabase Integration Example - Usage',
+    summary:
+      'Step-by-step usage of the Supabase dual-store integration example.',
+    kind: 'usage',
+    visibility: 'public',
+    route: '/docs/examples/integration-supabase/usage',
+    tags: ['supabase', 'usage'],
+    body: `## Usage
+1) Register integration specs from \`createDefaultIntegrationSpecRegistry()\`.
+2) Persist both sample connections from \`connection.sample.ts\`.
+3) Publish the tenant config from \`tenant.ts\` with matching \`connectionId\` values.
+4) Use \`runSupabaseKnowledgeRuntime(...)\` to execute vector and SQL calls through \`IntegrationProviderFactory\`.
+
+## Secret payload
+Store the following payload in your secret provider target for each connection:
+
+\`\`\`json
+{
+  "databaseUrl": "postgresql://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:6543/postgres"
+}
+\`\`\`
+
+## Guardrails
+- Never place credentials in \`config\` or source control.
+- Keep operational SQL behind explicit workflows/operations.
+- Restrict DB credentials to least-privilege roles whenever possible.`,
+  },
+];
+
+registerDocBlocks(blocks);

package/src/example.ts

@@ -0,0 +1,32 @@
+import { defineExample } from '@contractspec/lib.contracts';
+
+const example = defineExample({
+  meta: {
+    key: 'integration-supabase',
+    version: '1.0.0',
+    title: 'Integration - Supabase Vector + Postgres',
+    description:
+      'Wire AppBlueprint and TenantAppConfig to use Supabase for both vector retrieval and SQL workloads.',
+    kind: 'integration',
+    visibility: 'public',
+    stability: 'experimental',
+    owners: ['@platform.core'],
+    tags: ['supabase', 'pgvector', 'postgres', 'integration', 'knowledge'],
+  },
+  docs: {
+    rootDocId: 'docs.examples.integration-supabase',
+    usageDocId: 'docs.examples.integration-supabase.usage',
+  },
+  entrypoints: {
+    packageName: '@contractspec/example.integration-supabase',
+    docs: './docs',
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true },
+  },
+});
+
+export default example;

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './blueprint';
+export * from './tenant';
+export * from './connection.sample';
+export * from './runtime.sample';
+export { default as example } from './example';
+import './docs';

package/src/runtime.sample.ts

@@ -0,0 +1,53 @@
+import type { VectorSearchResult } from '@contractspec/integration.providers-impls/vector-store';
+import { IntegrationProviderFactory } from '@contractspec/integration.providers-impls/impls/provider-factory';
+import type { IntegrationContext } from '@contractspec/integration.runtime/runtime';
+
+export interface SupabaseKnowledgeRuntimeParams {
+  vectorContext: IntegrationContext;
+  databaseContext: IntegrationContext;
+}
+
+export interface SupabaseKnowledgeRuntimeResult {
+  matches: VectorSearchResult[];
+  indexedDocumentCount: number;
+}
+
+export async function runSupabaseKnowledgeRuntime(
+  params: SupabaseKnowledgeRuntimeParams
+): Promise<SupabaseKnowledgeRuntimeResult> {
+  const factory = new IntegrationProviderFactory();
+
+  const vectorStore = await factory.createVectorStoreProvider(
+    params.vectorContext
+  );
+  const database = await factory.createDatabaseProvider(params.databaseContext);
+
+  await vectorStore.upsert({
+    collection: 'knowledge_chunks',
+    documents: [
+      {
+        id: 'chunk-1',
+        vector: [0.11, 0.23, 0.45],
+        payload: { source: 'faq', locale: 'en' },
+      },
+    ],
+  });
+
+  const matches = await vectorStore.search({
+    collection: 'knowledge_chunks',
+    vector: [0.12, 0.22, 0.44],
+    topK: 5,
+    filter: { source: 'faq' },
+  });
+
+  const count = await database.query<{ total: number }>(
+    'SELECT COUNT(*)::int AS total FROM knowledge_chunks;'
+  );
+
+  await database.close();
+
+  return {
+    matches,
+    indexedDocumentCount: count.rows[0]?.total ?? 0,
+  };
+}

package/src/tenant.ts

@@ -0,0 +1,41 @@
+import type { TenantAppConfig } from '@contractspec/lib.contracts/app-config/spec';
+
+export const supabaseKnowledgeTenantConfig: TenantAppConfig = {
+  meta: {
+    id: 'tenant-config-knowledge-supabase',
+    tenantId: 'acme-knowledge',
+    appId: 'knowledge-assistant',
+    blueprintName: 'knowledge.supabase.dual-store',
+    blueprintVersion: '1.0.0',
+    environment: 'production',
+    version: '1.0.0',
+    status: 'published',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  },
+  integrations: [
+    {
+      slotId: 'primary-vector-db',
+      connectionId: 'conn-supabase-vector',
+      scope: {
+        workflows: ['ingestKnowledge'],
+        operations: ['knowledge.indexChunks', 'knowledge.semanticSearch'],
+      },
+    },
+    {
+      slotId: 'primary-database',
+      connectionId: 'conn-supabase-db',
+      scope: {
+        workflows: ['refreshMetrics'],
+        operations: ['knowledge.metrics.refresh', 'knowledge.metrics.query'],
+      },
+    },
+  ],
+  knowledge: [],
+  locales: {
+    defaultLocale: 'en',
+    enabledLocales: ['en'],
+  },
+  notes:
+    'Supabase vector + SQL connections bound for production knowledge flows.',
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@contractspec/tool.typescript/react-library.json",
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"],
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  }
+}