@contractspec/lib.contracts-integrations 2.0.0

package/dist/node/integrations/operations.js

@@ -0,0 +1,296 @@
+// src/integrations/operations.ts
+import { ScalarTypeEnum, SchemaModel } from "@contractspec/lib.schema";
+import {
+  defineCommand,
+  defineQuery
+} from "@contractspec/lib.contracts-spec/operations";
+var 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 }
+  }
+});
+var 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 }
+  }
+});
+var 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 }
+  }
+});
+var DeleteIntegrationConnectionInput = new SchemaModel({
+  name: "DeleteIntegrationConnectionInput",
+  fields: {
+    connectionId: { type: ScalarTypeEnum.ID(), isOptional: false }
+  }
+});
+var 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 }
+  }
+});
+var ListIntegrationConnectionsOutput = new SchemaModel({
+  name: "ListIntegrationConnectionsOutput",
+  fields: {
+    connections: {
+      type: IntegrationConnectionRecord,
+      isOptional: false,
+      isArray: true
+    }
+  }
+});
+var TestIntegrationConnectionInput = new SchemaModel({
+  name: "TestIntegrationConnectionInput",
+  fields: {
+    connectionId: { type: ScalarTypeEnum.ID(), isOptional: false }
+  }
+});
+var 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 }
+  }
+});
+var DeleteIntegrationConnectionOutput = new SchemaModel({
+  name: "DeleteIntegrationConnectionOutput",
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false }
+  }
+});
+var CreateIntegrationConnection = defineCommand({
+  meta: {
+    key: "integrations.connection.create",
+    title: "Create Integration Connection",
+    version: "1.0.0",
+    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: [{ key: "platform.integration.manage", version: "1.0.0" }]
+  }
+});
+var UpdateIntegrationConnection = defineCommand({
+  meta: {
+    key: "integrations.connection.update",
+    title: "Update Integration Connection",
+    version: "1.0.0",
+    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: [{ key: "platform.integration.manage", version: "1.0.0" }]
+  }
+});
+var DeleteIntegrationConnection = defineCommand({
+  meta: {
+    key: "integrations.connection.delete",
+    title: "Delete Integration Connection",
+    version: "1.0.0",
+    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: [{ key: "platform.integration.manage", version: "1.0.0" }]
+  }
+});
+var ListIntegrationConnections = defineQuery({
+  meta: {
+    key: "integrations.connection.list",
+    title: "List Integration Connections",
+    version: "1.0.0",
+    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: [{ key: "platform.integration.read", version: "1.0.0" }]
+  }
+});
+var TestIntegrationConnection = defineCommand({
+  meta: {
+    key: "integrations.connection.test",
+    title: "Test Integration Connection",
+    version: "1.0.0",
+    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: [{ key: "platform.integration.manage", version: "1.0.0" }]
+  }
+});
+var integrationContracts = {
+  CreateIntegrationConnection,
+  UpdateIntegrationConnection,
+  DeleteIntegrationConnection,
+  ListIntegrationConnections,
+  TestIntegrationConnection
+};
+function registerIntegrationContracts(registry) {
+  return registry.register(CreateIntegrationConnection).register(UpdateIntegrationConnection).register(DeleteIntegrationConnection).register(ListIntegrationConnections).register(TestIntegrationConnection);
+}
+export {
+  registerIntegrationContracts,
+  integrationContracts,
+  UpdateIntegrationConnection,
+  TestIntegrationConnection,
+  ListIntegrationConnections,
+  DeleteIntegrationConnection,
+  CreateIntegrationConnection
+};

package/dist/node/integrations/providers/elevenlabs.js

@@ -0,0 +1,85 @@
+// 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/elevenlabs.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var elevenLabsIntegrationSpec = defineIntegration({
+  meta: {
+    key: "ai-voice.elevenlabs",
+    version: "1.0.0",
+    category: "ai-voice",
+    title: "ElevenLabs Text-to-Speech",
+    description: "ElevenLabs integration for neural voice synthesis and voice catalog access.",
+    domain: "ai",
+    owners: ["platform.ai"],
+    tags: ["voice", "tts"],
+    stability: StabilityEnum.Beta
+  },
+  supportedModes: ["managed", "byok"],
+  capabilities: {
+    provides: [{ key: "ai.voice.synthesis", version: "1.0.0" }]
+  },
+  configSchema: {
+    schema: {
+      type: "object",
+      properties: {
+        defaultVoiceId: {
+          type: "string",
+          description: "Optional default voice identifier for synthesis requests."
+        }
+      }
+    },
+    example: {
+      defaultVoiceId: "pNInz6obpgDQGcFmaJgB"
+    }
+  },
+  secretSchema: {
+    schema: {
+      type: "object",
+      required: ["apiKey"],
+      properties: {
+        apiKey: {
+          type: "string",
+          description: "ElevenLabs API key with text-to-speech permissions."
+        }
+      }
+    },
+    example: {
+      apiKey: "eleven-***"
+    }
+  },
+  healthCheck: {
+    method: "custom",
+    timeoutMs: 4000
+  },
+  docsUrl: "https://elevenlabs.io/docs/api-reference/text-to-speech",
+  constraints: {
+    rateLimit: {
+      rpm: 120
+    }
+  },
+  byokSetup: {
+    setupInstructions: "Create an ElevenLabs API key and ensure the desired voices are accessible to the key scope."
+  }
+});
+function registerElevenLabsIntegration(registry) {
+  return registry.register(elevenLabsIntegrationSpec);
+}
+export {
+  registerElevenLabsIntegration,
+  elevenLabsIntegrationSpec
+};

package/dist/node/integrations/providers/fal.js

@@ -0,0 +1,111 @@
+// 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/node/integrations/providers/fathom.js

@@ -0,0 +1,125 @@
+// 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
+};