@contractspec/lib.contracts 1.44.0

package/dist/integrations/operations.js

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

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

@@ -0,0 +1,78 @@
+//#region src/integrations/providers/calendar.d.ts
+interface CalendarAttendee {
+  email: string;
+  name?: string;
+  optional?: boolean;
+  responseStatus?: 'needsAction' | 'declined' | 'tentative' | 'accepted';
+}
+interface CalendarReminder {
+  method: 'email' | 'popup';
+  minutesBeforeStart: number;
+}
+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;
+}
+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>;
+}
+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>;
+}
+interface CalendarListEventsQuery {
+  calendarId: string;
+  timeMin?: Date;
+  timeMax?: Date;
+  maxResults?: number;
+  pageToken?: string;
+  includeCancelled?: boolean;
+}
+interface CalendarListEventsResult {
+  events: CalendarEvent[];
+  nextPageToken?: string;
+}
+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>;
+}
+//#endregion
+export { CalendarAttendee, CalendarEvent, CalendarEventInput, CalendarEventUpdateInput, CalendarListEventsQuery, CalendarListEventsResult, CalendarProvider, CalendarReminder };

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

@@ -0,0 +1,7 @@
+import { IntegrationSpec, IntegrationSpecRegistry } from "../spec.js";
+
+//#region src/integrations/providers/elevenlabs.d.ts
+declare const elevenLabsIntegrationSpec: IntegrationSpec;
+declare function registerElevenLabsIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;
+//#endregion
+export { elevenLabsIntegrationSpec, registerElevenLabsIntegration };

package/dist/integrations/providers/elevenlabs.js

@@ -0,0 +1,55 @@
+import { StabilityEnum } from "../../ownership.js";
+
+//#region src/integrations/providers/elevenlabs.ts
+const elevenLabsIntegrationSpec = {
+	meta: {
+		key: "ai-voice.elevenlabs",
+		version: 1,
+		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
+	}] },
+	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: 4e3
+	},
+	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);
+}
+
+//#endregion
+export { elevenLabsIntegrationSpec, registerElevenLabsIntegration };

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

@@ -0,0 +1,86 @@
+//#region src/integrations/providers/email.d.ts
+interface EmailAddress {
+  email: string;
+  name?: string;
+}
+interface EmailAttachment {
+  id: string;
+  filename: string;
+  contentType: string;
+  sizeBytes?: number;
+  data?: Uint8Array;
+  downloadUrl?: string;
+}
+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>;
+}
+interface EmailOutboundResult {
+  id: string;
+  providerMessageId?: string;
+  queuedAt?: Date;
+  deliveredAt?: Date;
+}
+interface EmailThread {
+  id: string;
+  subject?: string;
+  snippet?: string;
+  participants: EmailAddress[];
+  messages: EmailMessage[];
+  updatedAt: Date;
+  labels?: string[];
+  metadata?: Record<string, string>;
+}
+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>;
+}
+interface EmailThreadListQuery {
+  label?: string;
+  query?: string;
+  pageSize?: number;
+  pageToken?: string;
+  includeArchived?: boolean;
+  updatedSince?: Date;
+}
+interface EmailMessagesSinceQuery {
+  label?: string;
+  since?: Date;
+  pageSize?: number;
+  pageToken?: string;
+}
+interface EmailOutboundProvider {
+  sendEmail(message: EmailOutboundMessage): Promise<EmailOutboundResult>;
+}
+interface EmailInboundProvider {
+  listThreads(query?: EmailThreadListQuery): Promise<EmailThread[]>;
+  getThread(threadId: string): Promise<EmailThread | null>;
+  listMessagesSince(query: EmailMessagesSinceQuery): Promise<{
+    messages: EmailMessage[];
+    nextPageToken?: string;
+  }>;
+}
+//#endregion
+export { EmailAddress, EmailAttachment, EmailInboundProvider, EmailMessage, EmailMessagesSinceQuery, EmailOutboundMessage, EmailOutboundProvider, EmailOutboundResult, EmailThread, EmailThreadListQuery };

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

@@ -0,0 +1,24 @@
+//#region src/integrations/providers/embedding.d.ts
+type EmbeddingVector = number[];
+interface EmbeddingDocument {
+  id: string;
+  text: string;
+  metadata?: Record<string, string | number | boolean>;
+}
+interface EmbeddingResult {
+  id: string;
+  vector: EmbeddingVector;
+  dimensions: number;
+  model: string;
+  metadata?: Record<string, string>;
+}
+interface EmbeddingProvider {
+  embedDocuments(documents: EmbeddingDocument[], options?: {
+    model?: string;
+  }): Promise<EmbeddingResult[]>;
+  embedQuery(query: string, options?: {
+    model?: string;
+  }): Promise<EmbeddingResult>;
+}
+//#endregion
+export { EmbeddingDocument, EmbeddingProvider, EmbeddingResult, EmbeddingVector };

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

@@ -0,0 +1,7 @@
+import { IntegrationSpec, IntegrationSpecRegistry } from "../spec.js";
+
+//#region src/integrations/providers/gcs-storage.d.ts
+declare const gcsStorageIntegrationSpec: IntegrationSpec;
+declare function registerGcsStorageIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;
+//#endregion
+export { gcsStorageIntegrationSpec, registerGcsStorageIntegration };