@contractspec/lib.contracts-integrations 2.0.0

package/dist/integrations/providers/sms.d.ts

@@ -0,0 +1,31 @@
+export interface SmsMessage {
+    id: string;
+    to: string;
+    from: string;
+    body: string;
+    status: 'queued' | 'sending' | 'sent' | 'delivered' | 'undelivered' | 'failed';
+    providerMessageId?: string;
+    carrier?: string;
+    price?: number;
+    priceCurrency?: string;
+    sentAt?: Date;
+    deliveredAt?: Date;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface SendSmsInput {
+    to: string;
+    from?: string;
+    body: string;
+    metadata?: Record<string, string>;
+}
+export interface SmsDeliveryStatus {
+    status: SmsMessage['status'];
+    errorCode?: string;
+    errorMessage?: string;
+    updatedAt: Date;
+}
+export interface SmsProvider {
+    sendSms(input: SendSmsInput): Promise<SmsMessage>;
+    getDeliveryStatus(messageId: string): Promise<SmsDeliveryStatus>;
+}

package/dist/integrations/providers/sms.js

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

package/dist/integrations/providers/storage.d.ts

@@ -0,0 +1,57 @@
+export interface StorageObjectMetadata {
+    bucket: string;
+    key: string;
+    sizeBytes?: number;
+    contentType?: string;
+    etag?: string;
+    checksum?: string;
+    lastModified?: Date;
+    metadata?: Record<string, string>;
+}
+export type StorageObjectBody = {
+    data: Uint8Array;
+    stream?: never;
+} | {
+    data?: never;
+    stream: AsyncIterable<Uint8Array>;
+};
+export type GetObjectResult = StorageObjectMetadata & StorageObjectBody;
+export interface PutObjectInput {
+    bucket: string;
+    key: string;
+    data: Uint8Array | ArrayBuffer;
+    contentType?: string;
+    metadata?: Record<string, string>;
+    makePublic?: boolean;
+}
+export interface DeleteObjectInput {
+    bucket: string;
+    key: string;
+}
+export interface SignedUrlOptions {
+    bucket: string;
+    key: string;
+    expiresInSeconds: number;
+    method?: 'GET' | 'PUT';
+    contentType?: string;
+}
+export interface ListObjectsQuery {
+    bucket: string;
+    prefix?: string;
+    maxResults?: number;
+    pageToken?: string;
+}
+export interface ListObjectsResult {
+    objects: StorageObjectMetadata[];
+    nextPageToken?: string;
+}
+export interface ObjectStorageProvider {
+    putObject(input: PutObjectInput): Promise<StorageObjectMetadata>;
+    getObject(input: DeleteObjectInput): Promise<GetObjectResult | null>;
+    deleteObject(input: DeleteObjectInput): Promise<void>;
+    generateSignedUrl(options: SignedUrlOptions): Promise<{
+        url: string;
+        expiresAt: Date;
+    }>;
+    listObjects(query: ListObjectsQuery): Promise<ListObjectsResult>;
+}

package/dist/integrations/providers/storage.js

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

package/dist/integrations/providers/stripe.d.ts

@@ -0,0 +1,3 @@
+import { IntegrationSpecRegistry } from '../spec';
+export declare const stripeIntegrationSpec: import("..").IntegrationSpec;
+export declare function registerStripeIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;

package/dist/integrations/providers/stripe.js

@@ -0,0 +1,105 @@
+// @bun
+// src/integrations/spec.ts
+import { SpecContractRegistry } from "@contractspec/lib.contracts-spec/registry";
+var integrationKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class IntegrationSpecRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("integration", items);
+  }
+  getByCategory(category) {
+    return this.list().filter((spec) => spec.meta.category === category);
+  }
+}
+function makeIntegrationSpecKey(meta) {
+  return integrationKey(meta);
+}
+var defineIntegration = (spec) => spec;
+
+// src/integrations/providers/stripe.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var stripeIntegrationSpec = defineIntegration({
+  meta: {
+    key: "payments.stripe",
+    version: "1.0.0",
+    category: "payments",
+    title: "Stripe Payments",
+    description: "Stripe integration for payment processing, charges, and payouts.",
+    domain: "payments",
+    owners: ["platform.payments"],
+    tags: ["payments", "psp"],
+    stability: StabilityEnum.Stable
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "payments.psp", version: "1.0.0" }],
+    requires: [
+      {
+        key: "platform.webhooks",
+        optional: true,
+        reason: "Recommended for reliable event ingestion"
+      }
+    ]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        accountId: {
+          type: "string",
+          description: "Connected account ID when using Stripe Connect (BYOK)."
+        },
+        region: {
+          type: "string",
+          description: "Optional Stripe region or data residency hint."
+        }
+      }
+    },
+    example: {
+      accountId: "acct_123",
+      region: "us-east-1"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["apiKey", "webhookSecret"],
+      properties: {
+        apiKey: {
+          type: "string",
+          description: "Stripe secret API key (sk_live_... or sk_test_...)."
+        },
+        webhookSecret: {
+          type: "string",
+          description: "Signing secret for webhook verification."
+        }
+      }
+    },
+    example: {
+      apiKey: "sk_live_***",
+      webhookSecret: "whsec_***"
+    }
+  },
+  healthCheck: {
+    method: "ping",
+    timeoutMs: 5000
+  },
+  docsUrl: "https://stripe.com/docs/api",
+  constraints: {
+    rateLimit: {
+      rpm: 1000,
+      rph: 20000
+    }
+  },
+  byokSetup: {
+    setupInstructions: "Create a restricted Stripe API key with write access to Charges and provide a webhook signing secret.",
+    requiredScopes: ["charges:write", "customers:read"]
+  }
+});
+function registerStripeIntegration(registry) {
+  return registry.register(stripeIntegrationSpec);
+}
+export {
+  stripeIntegrationSpec,
+  registerStripeIntegration
+};

package/dist/integrations/providers/supabase-postgres.d.ts

@@ -0,0 +1,3 @@
+import { IntegrationSpecRegistry } from '../spec';
+export declare const supabasePostgresIntegrationSpec: import("..").IntegrationSpec;
+export declare function registerSupabasePostgresIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;

package/dist/integrations/providers/supabase-postgres.js

@@ -0,0 +1,87 @@
+// @bun
+// src/integrations/spec.ts
+import { SpecContractRegistry } from "@contractspec/lib.contracts-spec/registry";
+var integrationKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class IntegrationSpecRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("integration", items);
+  }
+  getByCategory(category) {
+    return this.list().filter((spec) => spec.meta.category === category);
+  }
+}
+function makeIntegrationSpecKey(meta) {
+  return integrationKey(meta);
+}
+var defineIntegration = (spec) => spec;
+
+// src/integrations/providers/supabase-postgres.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var supabasePostgresIntegrationSpec = defineIntegration({
+  meta: {
+    key: "database.supabase",
+    version: "1.0.0",
+    category: "database",
+    title: "Supabase Postgres",
+    description: "Supabase Postgres integration for SQL query execution and transactional workloads.",
+    domain: "infrastructure",
+    owners: ["platform.infrastructure"],
+    tags: ["database", "postgres", "supabase"],
+    stability: StabilityEnum.Beta
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "database.sql", version: "1.0.0" }]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        maxConnections: {
+          type: "number",
+          description: "Optional connection pool size when opening a Postgres client to Supabase."
+        },
+        sslMode: {
+          type: "string",
+          enum: ["require", "allow", "prefer"],
+          description: "TLS mode used by the Postgres client."
+        }
+      }
+    },
+    example: {
+      maxConnections: 10,
+      sslMode: "require"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["databaseUrl"],
+      properties: {
+        databaseUrl: {
+          type: "string",
+          description: "Supabase Postgres connection string (transaction or session pooler endpoint)."
+        }
+      }
+    },
+    example: {
+      databaseUrl: "postgresql://postgres.[project-ref]:password@aws-0-region.pooler.supabase.com:6543/postgres"
+    }
+  },
+  healthCheck: {
+    method: "ping",
+    timeoutMs: 5000
+  },
+  docsUrl: "https://supabase.com/docs/guides/database/connecting-to-postgres",
+  byokSetup: {
+    setupInstructions: "Create or reuse a Supabase project and provide a Postgres connection string with permissions aligned to your workload."
+  }
+});
+function registerSupabasePostgresIntegration(registry) {
+  return registry.register(supabasePostgresIntegrationSpec);
+}
+export {
+  supabasePostgresIntegrationSpec,
+  registerSupabasePostgresIntegration
+};

package/dist/integrations/providers/supabase-vector.d.ts

@@ -0,0 +1,3 @@
+import { IntegrationSpecRegistry } from '../spec';
+export declare const supabaseVectorIntegrationSpec: import("..").IntegrationSpec;
+export declare function registerSupabaseVectorIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;

package/dist/integrations/providers/supabase-vector.js

@@ -0,0 +1,107 @@
+// @bun
+// src/integrations/spec.ts
+import { SpecContractRegistry } from "@contractspec/lib.contracts-spec/registry";
+var integrationKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class IntegrationSpecRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("integration", items);
+  }
+  getByCategory(category) {
+    return this.list().filter((spec) => spec.meta.category === category);
+  }
+}
+function makeIntegrationSpecKey(meta) {
+  return integrationKey(meta);
+}
+var defineIntegration = (spec) => spec;
+
+// src/integrations/providers/supabase-vector.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var supabaseVectorIntegrationSpec = defineIntegration({
+  meta: {
+    key: "vectordb.supabase",
+    version: "1.0.0",
+    category: "vector-db",
+    title: "Supabase Vector Database (pgvector)",
+    description: "Supabase integration for embedding storage and vector similarity search using pgvector.",
+    domain: "ai",
+    owners: ["platform.ai"],
+    tags: ["vector-db", "supabase", "pgvector"],
+    stability: StabilityEnum.Beta
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [
+      { key: "vector-db.search", version: "1.0.0" },
+      { key: "vector-db.storage", version: "1.0.0" }
+    ],
+    requires: [
+      {
+        key: "ai.embeddings",
+        optional: true,
+        reason: "Required when vectors are generated by a hosted embedding provider."
+      }
+    ]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        schema: {
+          type: "string",
+          description: "Schema name containing the pgvector table (default: public)."
+        },
+        table: {
+          type: "string",
+          description: "Table used to store vectors and metadata (default: contractspec_vectors)."
+        },
+        createTableIfMissing: {
+          type: "boolean",
+          description: "Automatically create pgvector extension and table when first writing vectors."
+        },
+        distanceMetric: {
+          type: "string",
+          enum: ["cosine", "l2", "inner_product"],
+          description: "Distance metric used for nearest-neighbor search."
+        }
+      }
+    },
+    example: {
+      schema: "public",
+      table: "contractspec_vectors",
+      createTableIfMissing: true,
+      distanceMetric: "cosine"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["databaseUrl"],
+      properties: {
+        databaseUrl: {
+          type: "string",
+          description: "Supabase Postgres connection string with privileges to read/write vector rows."
+        }
+      }
+    },
+    example: {
+      databaseUrl: "postgresql://postgres.[project-ref]:password@aws-0-region.pooler.supabase.com:6543/postgres"
+    }
+  },
+  healthCheck: {
+    method: "ping",
+    timeoutMs: 5000
+  },
+  docsUrl: "https://supabase.com/docs/guides/ai/vector-columns",
+  byokSetup: {
+    setupInstructions: "Create or reuse a Supabase project, enable pgvector, and provide a Postgres connection string with read/write access to the target vector table."
+  }
+});
+function registerSupabaseVectorIntegration(registry) {
+  return registry.register(supabaseVectorIntegrationSpec);
+}
+export {
+  supabaseVectorIntegrationSpec,
+  registerSupabaseVectorIntegration
+};

package/dist/integrations/providers/tldv.d.ts

@@ -0,0 +1,3 @@
+import { IntegrationSpecRegistry } from '../spec';
+export declare const tldvIntegrationSpec: import("..").IntegrationSpec;
+export declare function registerTldvIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;

package/dist/integrations/providers/tldv.js

@@ -0,0 +1,106 @@
+// @bun
+// src/integrations/spec.ts
+import { SpecContractRegistry } from "@contractspec/lib.contracts-spec/registry";
+var integrationKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class IntegrationSpecRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("integration", items);
+  }
+  getByCategory(category) {
+    return this.list().filter((spec) => spec.meta.category === category);
+  }
+}
+function makeIntegrationSpecKey(meta) {
+  return integrationKey(meta);
+}
+var defineIntegration = (spec) => spec;
+
+// src/integrations/providers/tldv.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var tldvIntegrationSpec = defineIntegration({
+  meta: {
+    key: "meeting-recorder.tldv",
+    version: "1.0.0",
+    category: "meeting-recorder",
+    title: "tl;dv Meeting Recorder",
+    description: "tl;dv Public API for meeting recordings, transcripts, and webhook events.",
+    domain: "productivity",
+    owners: ["platform.integrations"],
+    tags: ["meeting-recorder", "tldv", "transcripts"],
+    stability: StabilityEnum.Experimental
+  },
+  supportedModes: ["byok"],
+  capabilities: {
+    provides: [
+      { key: "meeting-recorder.meetings.read", version: "1.0.0" },
+      { key: "meeting-recorder.transcripts.read", version: "1.0.0" },
+      { key: "meeting-recorder.webhooks", version: "1.0.0" }
+    ]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        baseUrl: {
+          type: "string",
+          description: "Optional override for the tl;dv API base URL. Defaults to https://pasta.tldv.io/v1alpha1."
+        },
+        webhookUrl: {
+          type: "string",
+          description: "Webhook destination URL configured in tl;dv settings (MeetingReady/TranscriptReady)."
+        },
+        webhookEvents: {
+          type: "array",
+          items: { type: "string" },
+          description: "Webhook triggers to enable (MeetingReady, TranscriptReady)."
+        },
+        webhookScope: {
+          type: "string",
+          description: "Webhook scope to configure (user, team, or organization)."
+        }
+      }
+    },
+    example: {
+      baseUrl: "https://pasta.tldv.io/v1alpha1",
+      webhookUrl: "https://example.com/webhooks/tldv",
+      webhookEvents: ["MeetingReady", "TranscriptReady"],
+      webhookScope: "team"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["apiKey"],
+      properties: {
+        apiKey: {
+          type: "string",
+          description: "tl;dv API key used in the x-api-key header for API requests."
+        },
+        webhookSecret: {
+          type: "string",
+          description: "Optional shared secret for webhook verification if configured in your environment."
+        }
+      }
+    },
+    example: {
+      apiKey: "tldv-***",
+      webhookSecret: "tldv-webhook-secret"
+    }
+  },
+  healthCheck: {
+    method: "ping",
+    timeoutMs: 6000
+  },
+  docsUrl: "https://doc.tldv.io/index.html",
+  byokSetup: {
+    setupInstructions: "Generate a tl;dv API key and optionally configure MeetingReady/TranscriptReady webhooks."
+  }
+});
+function registerTldvIntegration(registry) {
+  return registry.register(tldvIntegrationSpec);
+}
+export {
+  tldvIntegrationSpec,
+  registerTldvIntegration
+};

package/dist/integrations/providers/twilio-sms.d.ts

@@ -0,0 +1,3 @@
+import { IntegrationSpecRegistry } from '../spec';
+export declare const twilioSmsIntegrationSpec: import("..").IntegrationSpec;
+export declare function registerTwilioSmsIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;

package/dist/integrations/providers/twilio-sms.js

@@ -0,0 +1,91 @@
+// @bun
+// src/integrations/spec.ts
+import { SpecContractRegistry } from "@contractspec/lib.contracts-spec/registry";
+var integrationKey = (meta) => `${meta.key}.v${meta.version}`;
+
+class IntegrationSpecRegistry extends SpecContractRegistry {
+  constructor(items) {
+    super("integration", items);
+  }
+  getByCategory(category) {
+    return this.list().filter((spec) => spec.meta.category === category);
+  }
+}
+function makeIntegrationSpecKey(meta) {
+  return integrationKey(meta);
+}
+var defineIntegration = (spec) => spec;
+
+// src/integrations/providers/twilio-sms.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var twilioSmsIntegrationSpec = defineIntegration({
+  meta: {
+    key: "sms.twilio",
+    version: "1.0.0",
+    category: "sms",
+    title: "Twilio Messaging",
+    description: "Twilio SMS integration for transactional and notification messaging.",
+    domain: "communications",
+    owners: ["platform.messaging"],
+    tags: ["sms", "messaging"],
+    stability: StabilityEnum.Stable
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "sms.outbound", version: "1.0.0" }]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        fromNumber: {
+          type: "string",
+          description: "Default Twilio phone number used as sender."
+        }
+      }
+    },
+    example: {
+      fromNumber: "+15551234567"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["accountSid", "authToken"],
+      properties: {
+        accountSid: {
+          type: "string",
+          description: "Twilio Account SID."
+        },
+        authToken: {
+          type: "string",
+          description: "Twilio Auth Token."
+        }
+      }
+    },
+    example: {
+      accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+      authToken: "auth-token"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 3000
+  },
+  docsUrl: "https://www.twilio.com/docs/sms/api",
+  constraints: {
+    rateLimit: {
+      rpm: 200
+    }
+  },
+  byokSetup: {
+    setupInstructions: "Provide a Twilio account SID, auth token, and verify the outbound sending numbers used by the integration."
+  }
+});
+function registerTwilioSmsIntegration(registry) {
+  return registry.register(twilioSmsIntegrationSpec);
+}
+export {
+  twilioSmsIntegrationSpec,
+  registerTwilioSmsIntegration
+};

package/dist/integrations/providers/vector-store.d.ts

@@ -0,0 +1,39 @@
+import type { EmbeddingVector } from './embedding';
+export interface VectorDocument {
+    id: string;
+    vector: EmbeddingVector;
+    payload?: Record<string, unknown>;
+    namespace?: string;
+    expiresAt?: Date;
+}
+export interface VectorUpsertRequest {
+    collection: string;
+    documents: VectorDocument[];
+    waitForSync?: boolean;
+}
+export interface VectorDeleteRequest {
+    collection: string;
+    ids: string[];
+    namespace?: string;
+}
+export interface VectorSearchQuery {
+    collection: string;
+    vector: EmbeddingVector;
+    topK: number;
+    namespace?: string;
+    filter?: Record<string, unknown>;
+    scoreThreshold?: number;
+    consistent?: boolean;
+}
+export interface VectorSearchResult {
+    id: string;
+    score: number;
+    payload?: Record<string, unknown>;
+    vector?: EmbeddingVector;
+    namespace?: string;
+}
+export interface VectorStoreProvider {
+    upsert(request: VectorUpsertRequest): Promise<void>;
+    search(query: VectorSearchQuery): Promise<VectorSearchResult[]>;
+    delete(request: VectorDeleteRequest): Promise<void>;
+}

package/dist/integrations/providers/vector-store.js

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

package/dist/integrations/providers/voice.d.ts

@@ -0,0 +1,31 @@
+export interface Voice {
+    id: string;
+    name: string;
+    description?: string;
+    language?: string;
+    gender?: 'male' | 'female' | 'neutral';
+    previewUrl?: string;
+    metadata?: Record<string, string>;
+}
+export interface VoiceSynthesisInput {
+    text: string;
+    voiceId?: string;
+    language?: string;
+    style?: number;
+    stability?: number;
+    similarityBoost?: number;
+    format?: 'mp3' | 'wav' | 'ogg' | 'pcm';
+    sampleRateHz?: number;
+    metadata?: Record<string, string>;
+}
+export interface VoiceSynthesisResult {
+    audio: Uint8Array;
+    format: string;
+    sampleRateHz: number;
+    durationSeconds?: number;
+    url?: string;
+}
+export interface VoiceProvider {
+    listVoices(): Promise<Voice[]>;
+    synthesize(input: VoiceSynthesisInput): Promise<VoiceSynthesisResult>;
+}