@contractspec/lib.contracts-integrations 2.0.0

package/dist/integrations/operations.js

@@ -0,0 +1,297 @@
+// @bun
+// 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/integrations/operations.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/integrations/providers/analytics-reader.d.ts

@@ -0,0 +1,103 @@
+import type { AnalyticsQueryInput, AnalyticsQueryResult } from './analytics';
+export type AnalyticsPropertyFilter = Record<string, string | number | boolean | null>;
+export interface DateRangeInput {
+    from?: string | Date;
+    to?: string | Date;
+    timezone?: string;
+}
+export interface PaginationInput {
+    limit?: number;
+    offset?: number;
+}
+export interface GetEventsInput extends PaginationInput {
+    projectId?: string | number;
+    event?: string;
+    events?: string[];
+    distinctId?: string;
+    properties?: AnalyticsPropertyFilter;
+    dateRange?: DateRangeInput;
+    orderBy?: 'timestamp' | '-timestamp';
+}
+export interface GetPersonsInput extends PaginationInput {
+    projectId?: string | number;
+    cohortId?: string | number;
+    properties?: AnalyticsPropertyFilter;
+    search?: string;
+}
+export type AnalyticsInsightType = 'TRENDS' | 'FUNNELS' | 'RETENTION' | 'PATHS' | 'STICKINESS' | 'LIFECYCLE' | 'SESSIONS' | 'CUSTOM';
+export interface GetInsightsInput extends PaginationInput {
+    projectId?: string | number;
+    insightType?: AnalyticsInsightType;
+}
+export interface GetInsightResultInput {
+    projectId?: string | number;
+    insightId: string | number;
+}
+export interface GetCohortsInput extends PaginationInput {
+    projectId?: string | number;
+}
+export interface GetFeatureFlagsInput extends PaginationInput {
+    projectId?: string | number;
+    active?: boolean;
+}
+export interface GetAnnotationsInput extends PaginationInput {
+    projectId?: string | number;
+    dateRange?: DateRangeInput;
+}
+export interface AnalyticsEvent {
+    id?: string | number;
+    event: string;
+    distinctId: string;
+    properties?: Record<string, unknown>;
+    timestamp: string;
+}
+export interface AnalyticsPerson {
+    id?: string | number;
+    distinctId?: string;
+    properties?: Record<string, unknown>;
+    createdAt?: string;
+}
+export interface AnalyticsInsight {
+    id?: string | number;
+    name?: string;
+    type?: AnalyticsInsightType | string;
+    filters?: Record<string, unknown>;
+    result?: unknown;
+}
+export interface AnalyticsCohort {
+    id?: string | number;
+    name?: string;
+    groups?: unknown;
+    count?: number;
+}
+export interface AnalyticsFeatureFlag {
+    id?: string | number;
+    key?: string;
+    name?: string;
+    active?: boolean;
+    filters?: Record<string, unknown>;
+    rolloutPercentage?: number;
+}
+export interface AnalyticsAnnotation {
+    id?: string | number;
+    content?: string;
+    dateMarker?: string;
+    scope?: string;
+    createdAt?: string;
+}
+export interface PaginatedResponse<T> {
+    count: number;
+    next?: string | null;
+    previous?: string | null;
+    results: T[];
+}
+export interface AnalyticsReader {
+    queryHogQL?(input: AnalyticsQueryInput): Promise<AnalyticsQueryResult>;
+    getEvents?(input: GetEventsInput): Promise<PaginatedResponse<AnalyticsEvent>>;
+    getPersons?(input: GetPersonsInput): Promise<PaginatedResponse<AnalyticsPerson>>;
+    getInsights?(input: GetInsightsInput): Promise<PaginatedResponse<AnalyticsInsight>>;
+    getInsightResult?(input: GetInsightResultInput): Promise<AnalyticsInsight>;
+    getCohorts?(input: GetCohortsInput): Promise<PaginatedResponse<AnalyticsCohort>>;
+    getFeatureFlags?(input: GetFeatureFlagsInput): Promise<PaginatedResponse<AnalyticsFeatureFlag>>;
+    getAnnotations?(input: GetAnnotationsInput): Promise<PaginatedResponse<AnalyticsAnnotation>>;
+}

package/dist/integrations/providers/analytics-reader.js

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

package/dist/integrations/providers/analytics-writer.d.ts

@@ -0,0 +1,6 @@
+import type { AnalyticsEventInput, AnalyticsIdentifyInput, AnalyticsMcpToolCall } from './analytics';
+export interface AnalyticsWriter {
+    capture(event: AnalyticsEventInput): Promise<void>;
+    identify?(input: AnalyticsIdentifyInput): Promise<void>;
+    callMcpTool?(call: AnalyticsMcpToolCall): Promise<unknown>;
+}

package/dist/integrations/providers/analytics-writer.js

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

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

@@ -0,0 +1,47 @@
+import type { AnalyticsReader } from './analytics-reader';
+import type { AnalyticsWriter } from './analytics-writer';
+export type AnalyticsRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface AnalyticsRequest {
+    method: AnalyticsRequestMethod;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+export interface AnalyticsResponse<T = unknown> {
+    status: number;
+    data: T;
+    headers?: Record<string, string>;
+}
+export interface AnalyticsEventInput {
+    distinctId: string;
+    event: string;
+    properties?: Record<string, unknown>;
+    timestamp?: Date;
+    groups?: Record<string, string>;
+}
+export interface AnalyticsIdentifyInput {
+    distinctId: string;
+    properties?: Record<string, unknown>;
+    setOnce?: Record<string, unknown>;
+}
+export interface AnalyticsQueryInput {
+    query: string;
+    values?: Record<string, unknown>;
+}
+export interface AnalyticsQueryResult {
+    results: unknown;
+    columns?: string[];
+    types?: string[];
+    hogql?: string;
+    timings?: unknown;
+}
+export interface AnalyticsMcpToolCall {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+export type AnalyticsProvider = AnalyticsWriter & AnalyticsReader & {
+    request<T = unknown>(request: AnalyticsRequest): Promise<AnalyticsResponse<T>>;
+};
+export * from './analytics-reader';
+export * from './analytics-writer';

package/dist/integrations/providers/analytics.js

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

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

@@ -0,0 +1,75 @@
+export interface CalendarAttendee {
+    email: string;
+    name?: string;
+    optional?: boolean;
+    responseStatus?: 'needsAction' | 'declined' | 'tentative' | 'accepted';
+}
+export interface CalendarReminder {
+    method: 'email' | 'popup';
+    minutesBeforeStart: number;
+}
+export interface CalendarEvent {
+    id: string;
+    calendarId: string;
+    title: string;
+    description?: string;
+    location?: string;
+    start: Date;
+    end: Date;
+    allDay?: boolean;
+    attendees?: CalendarAttendee[];
+    reminders?: CalendarReminder[];
+    conferenceLink?: string;
+    metadata?: Record<string, string>;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export interface CalendarEventInput {
+    calendarId: string;
+    title: string;
+    description?: string;
+    location?: string;
+    start: Date;
+    end: Date;
+    allDay?: boolean;
+    attendees?: CalendarAttendee[];
+    reminders?: CalendarReminder[];
+    conference?: {
+        create: boolean;
+        type?: 'google_meet' | 'zoom' | 'custom';
+    };
+    metadata?: Record<string, string>;
+}
+export interface CalendarEventUpdateInput {
+    title?: string;
+    description?: string;
+    location?: string;
+    start?: Date;
+    end?: Date;
+    allDay?: boolean;
+    attendees?: CalendarAttendee[];
+    reminders?: CalendarReminder[];
+    conference?: {
+        create?: boolean;
+        type?: 'google_meet' | 'zoom' | 'custom';
+    };
+    metadata?: Record<string, string>;
+}
+export interface CalendarListEventsQuery {
+    calendarId: string;
+    timeMin?: Date;
+    timeMax?: Date;
+    maxResults?: number;
+    pageToken?: string;
+    includeCancelled?: boolean;
+}
+export interface CalendarListEventsResult {
+    events: CalendarEvent[];
+    nextPageToken?: string;
+}
+export interface CalendarProvider {
+    listEvents(query: CalendarListEventsQuery): Promise<CalendarListEventsResult>;
+    createEvent(input: CalendarEventInput): Promise<CalendarEvent>;
+    updateEvent(calendarId: string, eventId: string, input: CalendarEventUpdateInput): Promise<CalendarEvent>;
+    deleteEvent(calendarId: string, eventId: string): Promise<void>;
+}

package/dist/integrations/providers/calendar.js

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

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

@@ -0,0 +1,12 @@
+export type DatabaseStatementParam = string | number | boolean | bigint | Date | Uint8Array | null | Record<string, unknown> | readonly unknown[];
+export type DatabaseRow = Record<string, unknown>;
+export interface DatabaseQueryResult<TRow extends DatabaseRow = DatabaseRow> {
+    rows: TRow[];
+    rowCount: number;
+}
+export interface DatabaseProvider {
+    query<TRow extends DatabaseRow = DatabaseRow>(statement: string, params?: readonly DatabaseStatementParam[]): Promise<DatabaseQueryResult<TRow>>;
+    execute(statement: string, params?: readonly DatabaseStatementParam[]): Promise<void>;
+    transaction<T>(run: (database: DatabaseProvider) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}

package/dist/integrations/providers/database.js

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

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

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

package/dist/integrations/providers/elevenlabs.js

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