@contractspec/lib.contracts-integrations 2.0.0

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

@@ -0,0 +1,83 @@
+export interface EmailAddress {
+    email: string;
+    name?: string;
+}
+export interface EmailAttachment {
+    id: string;
+    filename: string;
+    contentType: string;
+    sizeBytes?: number;
+    data?: Uint8Array;
+    downloadUrl?: string;
+}
+export interface EmailOutboundMessage {
+    from: EmailAddress;
+    to: EmailAddress[];
+    cc?: EmailAddress[];
+    bcc?: EmailAddress[];
+    replyTo?: EmailAddress;
+    subject: string;
+    textBody?: string;
+    htmlBody?: string;
+    headers?: Record<string, string>;
+    attachments?: EmailAttachment[];
+    metadata?: Record<string, string>;
+}
+export interface EmailOutboundResult {
+    id: string;
+    providerMessageId?: string;
+    queuedAt?: Date;
+    deliveredAt?: Date;
+}
+export interface EmailThread {
+    id: string;
+    subject?: string;
+    snippet?: string;
+    participants: EmailAddress[];
+    messages: EmailMessage[];
+    updatedAt: Date;
+    labels?: string[];
+    metadata?: Record<string, string>;
+}
+export interface EmailMessage {
+    id: string;
+    threadId: string;
+    subject?: string;
+    from: EmailAddress;
+    to: EmailAddress[];
+    cc?: EmailAddress[];
+    bcc?: EmailAddress[];
+    replyTo?: EmailAddress;
+    sentAt: Date;
+    receivedAt?: Date;
+    textBody?: string;
+    htmlBody?: string;
+    attachments?: EmailAttachment[];
+    headers?: Record<string, string>;
+    metadata?: Record<string, string>;
+}
+export interface EmailThreadListQuery {
+    label?: string;
+    query?: string;
+    pageSize?: number;
+    pageToken?: string;
+    includeArchived?: boolean;
+    updatedSince?: Date;
+}
+export interface EmailMessagesSinceQuery {
+    label?: string;
+    since?: Date;
+    pageSize?: number;
+    pageToken?: string;
+}
+export interface EmailOutboundProvider {
+    sendEmail(message: EmailOutboundMessage): Promise<EmailOutboundResult>;
+}
+export interface EmailInboundProvider {
+    listThreads(query?: EmailThreadListQuery): Promise<EmailThread[]>;
+    getThread(threadId: string): Promise<EmailThread | null>;
+    listMessagesSince(query: EmailMessagesSinceQuery): Promise<{
+        messages: EmailMessage[];
+        nextPageToken?: string;
+    }>;
+}

package/dist/integrations/providers/email.js

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

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

@@ -0,0 +1,21 @@
+export type EmbeddingVector = number[];
+export interface EmbeddingDocument {
+    id: string;
+    text: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+export interface EmbeddingResult {
+    id: string;
+    vector: EmbeddingVector;
+    dimensions: number;
+    model: string;
+    metadata?: Record<string, string>;
+}
+export interface EmbeddingProvider {
+    embedDocuments(documents: EmbeddingDocument[], options?: {
+        model?: string;
+    }): Promise<EmbeddingResult[]>;
+    embedQuery(query: string, options?: {
+        model?: string;
+    }): Promise<EmbeddingResult>;
+}

package/dist/integrations/providers/embedding.js

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

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

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

package/dist/integrations/providers/fal.js

@@ -0,0 +1,112 @@
+// @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/fal.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var falIntegrationSpec = defineIntegration({
+  meta: {
+    key: "ai-voice.fal",
+    version: "1.0.0",
+    category: "ai-voice",
+    title: "Fal Chatterbox Text-to-Speech",
+    description: "Fal integration for voice synthesis using Chatterbox text-to-speech models.",
+    domain: "ai",
+    owners: ["platform.ai"],
+    tags: ["voice", "tts", "chatterbox"],
+    stability: StabilityEnum.Experimental
+  },
+  supportedModes: ["byok"],
+  capabilities: {
+    provides: [{ key: "ai.voice.synthesis", version: "1.0.0" }]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        modelId: {
+          type: "string",
+          description: "Fal model endpoint identifier (e.g. fal-ai/chatterbox/text-to-speech)."
+        },
+        defaultVoiceUrl: {
+          type: "string",
+          description: "Optional reference audio URL used as default voice conditioning input."
+        },
+        defaultExaggeration: {
+          type: "number",
+          minimum: 0,
+          maximum: 1,
+          description: "Optional default exaggeration value for speech output."
+        },
+        defaultTemperature: {
+          type: "number",
+          minimum: 0.05,
+          maximum: 2,
+          description: "Optional default temperature for synthesis requests."
+        },
+        defaultCfg: {
+          type: "number",
+          minimum: 0.1,
+          maximum: 1,
+          description: "Optional default cfg value for synthesis requests."
+        },
+        pollIntervalMs: {
+          type: "number",
+          description: "Optional queue polling interval in milliseconds."
+        }
+      }
+    },
+    example: {
+      modelId: "fal-ai/chatterbox/text-to-speech",
+      defaultVoiceUrl: "https://storage.googleapis.com/chatterbox-demo-samples/prompts/male_rickmorty.mp3",
+      defaultExaggeration: 0.25,
+      defaultTemperature: 0.7,
+      defaultCfg: 0.5,
+      pollIntervalMs: 1000
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["apiKey"],
+      properties: {
+        apiKey: {
+          type: "string",
+          description: "Fal API key (FAL_KEY)."
+        }
+      }
+    },
+    example: {
+      apiKey: "key-id:key-secret"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 7000
+  },
+  docsUrl: "https://fal.ai/models/fal-ai/chatterbox/text-to-speech/api",
+  byokSetup: {
+    setupInstructions: "Create a Fal API key and configure the desired voice model endpoint before connecting tenants."
+  }
+});
+function registerFalIntegration(registry) {
+  return registry.register(falIntegrationSpec);
+}
+export {
+  registerFalIntegration,
+  falIntegrationSpec
+};

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

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

package/dist/integrations/providers/fathom.js

@@ -0,0 +1,126 @@
+// @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/fathom.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var fathomIntegrationSpec = defineIntegration({
+  meta: {
+    key: "meeting-recorder.fathom",
+    version: "1.0.0",
+    category: "meeting-recorder",
+    title: "Fathom Meeting Recorder",
+    description: "Fathom External API for meetings, transcripts, and webhook events.",
+    domain: "productivity",
+    owners: ["platform.integrations"],
+    tags: ["meeting-recorder", "fathom", "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 Fathom API base URL. Defaults to https://api.fathom.ai/external/v1."
+        },
+        webhookUrl: {
+          type: "string",
+          description: "Webhook destination URL used when registering Fathom webhooks."
+        },
+        includeTranscript: {
+          type: "boolean",
+          description: "Include transcript data in Fathom webhook payloads."
+        },
+        includeSummary: {
+          type: "boolean",
+          description: "Include summary data in Fathom webhook payloads."
+        },
+        includeActionItems: {
+          type: "boolean",
+          description: "Include action items in Fathom webhook payloads."
+        },
+        includeCrmMatches: {
+          type: "boolean",
+          description: "Include CRM matches in Fathom webhook payloads."
+        },
+        triggeredFor: {
+          type: "array",
+          items: { type: "string" },
+          description: "Recording scopes to trigger webhooks for (e.g., my_recordings)."
+        }
+      }
+    },
+    example: {
+      baseUrl: "https://api.fathom.ai/external/v1",
+      webhookUrl: "https://example.com/webhooks/fathom",
+      includeTranscript: true,
+      includeSummary: true,
+      includeActionItems: false,
+      includeCrmMatches: false,
+      triggeredFor: ["my_recordings"]
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["apiKey"],
+      properties: {
+        apiKey: {
+          type: "string",
+          description: "Fathom API key used in the X-Api-Key header."
+        },
+        webhookSecret: {
+          type: "string",
+          description: "Optional webhook secret used to verify Fathom webhook signatures."
+        }
+      }
+    },
+    example: {
+      apiKey: "fathom-***",
+      webhookSecret: "whsec_***"
+    }
+  },
+  healthCheck: {
+    method: "list",
+    timeoutMs: 8000
+  },
+  docsUrl: "https://developers.fathom.ai/",
+  constraints: {
+    rateLimit: {
+      rpm: 60
+    }
+  },
+  byokSetup: {
+    setupInstructions: "Generate an API key in Fathom settings and optionally configure webhooks for meeting content readiness."
+  }
+});
+function registerFathomIntegration(registry) {
+  return registry.register(fathomIntegrationSpec);
+}
+export {
+  registerFathomIntegration,
+  fathomIntegrationSpec
+};

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

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

package/dist/integrations/providers/fireflies.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/fireflies.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var firefliesIntegrationSpec = defineIntegration({
+  meta: {
+    key: "meeting-recorder.fireflies",
+    version: "1.0.0",
+    category: "meeting-recorder",
+    title: "Fireflies.ai Meeting Recorder",
+    description: "Fireflies GraphQL API for meeting transcripts, metadata, and webhook events.",
+    domain: "productivity",
+    owners: ["platform.integrations"],
+    tags: ["meeting-recorder", "fireflies", "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 Fireflies GraphQL endpoint. Defaults to https://api.fireflies.ai/graphql."
+        },
+        webhookUrl: {
+          type: "string",
+          description: "Webhook destination URL configured in Fireflies developer settings."
+        },
+        webhookEvents: {
+          type: "array",
+          items: { type: "string" },
+          description: "Webhook events to subscribe to (e.g., Transcription completed)."
+        },
+        transcriptsPageSize: {
+          type: "number",
+          description: "Number of transcripts to request per GraphQL query."
+        }
+      }
+    },
+    example: {
+      baseUrl: "https://api.fireflies.ai/graphql",
+      webhookUrl: "https://example.com/webhooks/fireflies",
+      webhookEvents: ["Transcription completed"],
+      transcriptsPageSize: 25
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["apiKey"],
+      properties: {
+        apiKey: {
+          type: "string",
+          description: "Fireflies API key for GraphQL requests."
+        },
+        webhookSecret: {
+          type: "string",
+          description: "Optional webhook secret used to verify x-hub-signature HMAC payloads."
+        }
+      }
+    },
+    example: {
+      apiKey: "fireflies-***",
+      webhookSecret: "fireflies-webhook-secret"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 6000
+  },
+  docsUrl: "https://docs.fireflies.ai/getting-started/introduction",
+  byokSetup: {
+    setupInstructions: "Create a Fireflies API key and optionally configure webhook settings in Developer Settings."
+  }
+});
+function registerFirefliesIntegration(registry) {
+  return registry.register(firefliesIntegrationSpec);
+}
+export {
+  registerFirefliesIntegration,
+  firefliesIntegrationSpec
+};

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

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

package/dist/integrations/providers/gcs-storage.js

@@ -0,0 +1,97 @@
+// @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/gcs-storage.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var gcsStorageIntegrationSpec = defineIntegration({
+  meta: {
+    key: "storage.gcs",
+    version: "1.0.0",
+    category: "storage",
+    title: "Google Cloud Storage Buckets",
+    description: "Google Cloud Storage integration for object storage and retrieval.",
+    domain: "infrastructure",
+    owners: ["platform.infrastructure"],
+    tags: ["storage", "gcs", "google-cloud"],
+    stability: StabilityEnum.Beta
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "storage.objects", version: "1.0.0" }]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      required: ["bucket"],
+      properties: {
+        bucket: {
+          type: "string",
+          description: "Primary bucket name used for storing objects."
+        },
+        prefix: {
+          type: "string",
+          description: "Optional prefix applied to object keys."
+        }
+      }
+    },
+    example: {
+      bucket: "pfo-tenant-assets",
+      prefix: "documents/"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          description: "Service account type field from Google credentials JSON (if provided)."
+        },
+        client_email: { type: "string" },
+        private_key: { type: "string" },
+        project_id: { type: "string" }
+      }
+    },
+    example: {
+      type: "service_account",
+      client_email: "svc-account@example.iam.gserviceaccount.com",
+      private_key: "-----BEGIN PRIVATE KEY-----...",
+      project_id: "example-project"
+    }
+  },
+  healthCheck: {
+    method: "ping",
+    timeoutMs: 4000
+  },
+  docsUrl: "https://cloud.google.com/storage/docs/apis",
+  constraints: {
+    quotas: {
+      storageGb: 5120
+    }
+  },
+  byokSetup: {
+    setupInstructions: "Create a Google Cloud service account with Storage Object Admin role and upload the JSON credentials to the secret store."
+  }
+});
+function registerGcsStorageIntegration(registry) {
+  return registry.register(gcsStorageIntegrationSpec);
+}
+export {
+  registerGcsStorageIntegration,
+  gcsStorageIntegrationSpec
+};

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

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

package/dist/integrations/providers/gmail.js

@@ -0,0 +1,109 @@
+// @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/gmail.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var gmailIntegrationSpec = defineIntegration({
+  meta: {
+    key: "email.gmail",
+    version: "1.0.0",
+    category: "email",
+    title: "Google Gmail API",
+    description: "Gmail integration supporting inbound thread ingestion and outbound transactional email.",
+    domain: "communications",
+    owners: ["platform.messaging"],
+    tags: ["email", "gmail"],
+    stability: StabilityEnum.Beta
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [
+      { key: "email.inbound", version: "1.0.0" },
+      { key: "email.outbound", version: "1.0.0" }
+    ]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        labelIds: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional list of label IDs to scope inbound sync."
+        },
+        includeSpamTrash: {
+          type: "boolean",
+          description: "Whether to include spam or trash messages during sync."
+        }
+      }
+    },
+    example: {
+      labelIds: ["INBOX"],
+      includeSpamTrash: false
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["clientId", "clientSecret", "refreshToken"],
+      properties: {
+        clientId: {
+          type: "string",
+          description: "OAuth client ID for the Google Cloud project."
+        },
+        clientSecret: {
+          type: "string",
+          description: "OAuth client secret for the Google Cloud project."
+        },
+        refreshToken: {
+          type: "string",
+          description: "OAuth refresh token for delegated Gmail access."
+        },
+        redirectUri: {
+          type: "string",
+          description: "Optional redirect URI used when issuing the refresh token."
+        }
+      }
+    },
+    example: {
+      clientId: "xxx.apps.googleusercontent.com",
+      clientSecret: "secret",
+      refreshToken: "refresh-token"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 4000
+  },
+  docsUrl: "https://developers.google.com/gmail/api",
+  constraints: {
+    rateLimit: {
+      rpm: 600
+    }
+  },
+  byokSetup: {
+    setupInstructions: "Create an OAuth consent screen and credentials within Google Cloud Console, then authorize the Gmail scopes and store the resulting refresh token."
+  }
+});
+function registerGmailIntegration(registry) {
+  return registry.register(gmailIntegrationSpec);
+}
+export {
+  registerGmailIntegration,
+  gmailIntegrationSpec
+};

package/dist/integrations/providers/google-calendar.d.ts

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