@contractspec/lib.contracts 1.44.0

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

@@ -0,0 +1,78 @@
+import { StabilityEnum } from "../../ownership.js";
+
+//#region src/integrations/providers/gcs-storage.ts
+const gcsStorageIntegrationSpec = {
+	meta: {
+		key: "storage.gcs",
+		version: 1,
+		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
+	}] },
+	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: 4e3
+	},
+	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);
+}
+
+//#endregion
+export { gcsStorageIntegrationSpec, registerGcsStorageIntegration };

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

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

package/dist/integrations/providers/gmail.js

@@ -0,0 +1,90 @@
+import { StabilityEnum } from "../../ownership.js";
+
+//#region src/integrations/providers/gmail.ts
+const gmailIntegrationSpec = {
+	meta: {
+		key: "email.gmail",
+		version: 1,
+		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
+	}, {
+		key: "email.outbound",
+		version: 1
+	}] },
+	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: 4e3
+	},
+	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);
+}
+
+//#endregion
+export { gmailIntegrationSpec, registerGmailIntegration };

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

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

package/dist/integrations/providers/google-calendar.js

@@ -0,0 +1,69 @@
+import { StabilityEnum } from "../../ownership.js";
+
+//#region src/integrations/providers/google-calendar.ts
+const googleCalendarIntegrationSpec = {
+	meta: {
+		key: "calendar.google",
+		version: 1,
+		category: "calendar",
+		title: "Google Calendar API",
+		description: "Google Calendar integration for event creation, updates, and scheduling automations.",
+		domain: "productivity",
+		owners: ["platform.messaging"],
+		tags: ["calendar", "google"],
+		stability: StabilityEnum.Beta
+	},
+	supportedModes: ["managed", "byok"],
+	capabilities: { provides: [{
+		key: "calendar.events",
+		version: 1
+	}] },
+	configSchema: {
+		schema: {
+			type: "object",
+			properties: { calendarId: {
+				type: "string",
+				description: "Default calendar identifier (defaults to primary)."
+			} }
+		},
+		example: { calendarId: "primary" }
+	},
+	secretSchema: {
+		schema: {
+			type: "object",
+			required: ["clientEmail", "privateKey"],
+			properties: {
+				clientEmail: {
+					type: "string",
+					description: "Service account client email."
+				},
+				privateKey: {
+					type: "string",
+					description: "Service account private key."
+				},
+				projectId: {
+					type: "string",
+					description: "Google Cloud project ID."
+				}
+			}
+		},
+		example: {
+			clientEmail: "svc-calendar@example.iam.gserviceaccount.com",
+			privateKey: "-----BEGIN PRIVATE KEY-----...",
+			projectId: "calendar-project"
+		}
+	},
+	healthCheck: {
+		method: "custom",
+		timeoutMs: 4e3
+	},
+	docsUrl: "https://developers.google.com/calendar/api",
+	constraints: {},
+	byokSetup: { setupInstructions: "Create a Google service account with Calendar access and share the target calendars with the service account email." }
+};
+function registerGoogleCalendarIntegration(registry) {
+	return registry.register(googleCalendarIntegrationSpec);
+}
+
+//#endregion
+export { googleCalendarIntegrationSpec, registerGoogleCalendarIntegration };

package/dist/integrations/providers/impls/elevenlabs-voice.d.ts

@@ -0,0 +1,20 @@
+import { Voice, VoiceProvider, VoiceSynthesisInput, VoiceSynthesisResult } from "../voice.js";
+import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
+
+//#region src/integrations/providers/impls/elevenlabs-voice.d.ts
+interface ElevenLabsVoiceProviderOptions {
+  apiKey: string;
+  defaultVoiceId?: string;
+  modelId?: string;
+  client?: ElevenLabsClient;
+}
+declare class ElevenLabsVoiceProvider implements VoiceProvider {
+  private readonly client;
+  private readonly defaultVoiceId?;
+  private readonly modelId?;
+  constructor(options: ElevenLabsVoiceProviderOptions);
+  listVoices(): Promise<Voice[]>;
+  synthesize(input: VoiceSynthesisInput): Promise<VoiceSynthesisResult>;
+}
+//#endregion
+export { ElevenLabsVoiceProvider, ElevenLabsVoiceProviderOptions };

package/dist/integrations/providers/impls/elevenlabs-voice.js

@@ -0,0 +1,95 @@
+import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
+
+//#region src/integrations/providers/impls/elevenlabs-voice.ts
+const FORMAT_MAP = {
+	mp3: "mp3_44100_128",
+	wav: "pcm_44100",
+	ogg: "mp3_44100_128",
+	pcm: "pcm_16000"
+};
+const SAMPLE_RATE = {
+	mp3_22050_32: 22050,
+	mp3_44100_32: 44100,
+	mp3_44100_64: 44100,
+	mp3_44100_96: 44100,
+	mp3_44100_128: 44100,
+	mp3_44100_192: 44100,
+	pcm_16000: 16e3,
+	pcm_22050: 22050,
+	pcm_24000: 24e3,
+	pcm_44100: 44100,
+	ulaw_8000: 8e3
+};
+var ElevenLabsVoiceProvider = class {
+	client;
+	defaultVoiceId;
+	modelId;
+	constructor(options) {
+		this.client = options.client ?? new ElevenLabsClient({ apiKey: options.apiKey });
+		this.defaultVoiceId = options.defaultVoiceId;
+		this.modelId = options.modelId;
+	}
+	async listVoices() {
+		return ((await this.client.voices.getAll()).voices ?? []).map((voice) => ({
+			id: voice.voiceId ?? "",
+			name: voice.name ?? voice.voiceId ?? "",
+			description: voice.description ?? void 0,
+			language: voice.labels?.language ?? void 0,
+			gender: normalizeGender(voice.labels?.gender),
+			previewUrl: voice.previewUrl ?? void 0,
+			metadata: {
+				category: voice.category ?? "",
+				...voice.labels
+			}
+		}));
+	}
+	async synthesize(input) {
+		const voiceId = input.voiceId ?? this.defaultVoiceId;
+		if (!voiceId) throw new Error("Voice ID is required for ElevenLabs synthesis.");
+		const formatKey = input.format ?? "mp3";
+		const outputFormat = FORMAT_MAP[formatKey] ?? FORMAT_MAP.mp3;
+		const sampleRate = input.sampleRateHz ?? SAMPLE_RATE[outputFormat] ?? SAMPLE_RATE.mp3_44100_128 ?? 44100;
+		const voiceSettings = input.stability != null || input.similarityBoost != null || input.style != null ? {
+			...input.stability != null ? { stability: input.stability } : {},
+			...input.similarityBoost != null ? { similarityBoost: input.similarityBoost } : {},
+			...input.style != null ? { style: input.style } : {}
+		} : void 0;
+		return {
+			audio: await readWebStream(await this.client.textToSpeech.convert(voiceId, {
+				text: input.text,
+				modelId: this.modelId,
+				outputFormat,
+				voiceSettings
+			})),
+			format: formatKey,
+			sampleRateHz: sampleRate,
+			durationSeconds: void 0,
+			url: void 0
+		};
+	}
+};
+function normalizeGender(value) {
+	if (!value) return void 0;
+	const normalized = value.toLowerCase();
+	if (normalized === "male" || normalized === "female" || normalized === "neutral") return normalized;
+}
+async function readWebStream(stream) {
+	const reader = stream.getReader();
+	const chunks = [];
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (value) chunks.push(value);
+	}
+	const length = chunks.reduce((total, chunk) => total + chunk.length, 0);
+	const result = new Uint8Array(length);
+	let offset = 0;
+	for (const chunk of chunks) {
+		result.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return result;
+}
+
+//#endregion
+export { ElevenLabsVoiceProvider };

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

@@ -0,0 +1,24 @@
+import { DeleteObjectInput, GetObjectResult, ListObjectsQuery, ListObjectsResult, ObjectStorageProvider, PutObjectInput, SignedUrlOptions, StorageObjectMetadata } from "../storage.js";
+import { Storage, StorageOptions } from "@google-cloud/storage";
+
+//#region src/integrations/providers/impls/gcs-storage.d.ts
+interface GoogleCloudStorageProviderOptions {
+  bucket: string;
+  storage?: Storage;
+  clientOptions?: StorageOptions;
+}
+declare class GoogleCloudStorageProvider implements ObjectStorageProvider {
+  private readonly storage;
+  private readonly bucketName;
+  constructor(options: GoogleCloudStorageProviderOptions);
+  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>;
+}
+//#endregion
+export { GoogleCloudStorageProvider, GoogleCloudStorageProviderOptions };

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

@@ -0,0 +1,88 @@
+import { Storage } from "@google-cloud/storage";
+
+//#region src/integrations/providers/impls/gcs-storage.ts
+var GoogleCloudStorageProvider = class {
+	storage;
+	bucketName;
+	constructor(options) {
+		this.storage = options.storage ?? new Storage(options.clientOptions ?? void 0);
+		this.bucketName = options.bucket;
+	}
+	async putObject(input) {
+		const bucketName = input.bucket ?? this.bucketName;
+		const file = this.storage.bucket(bucketName).file(input.key);
+		const buffer = toBuffer(input.data);
+		await file.save(buffer, {
+			resumable: false,
+			contentType: input.contentType,
+			metadata: input.metadata
+		});
+		if (input.makePublic) await file.makePublic();
+		const [metadata] = await file.getMetadata();
+		return toMetadata(metadata);
+	}
+	async getObject(input) {
+		const bucketName = input.bucket ?? this.bucketName;
+		const file = this.storage.bucket(bucketName).file(input.key);
+		const [exists] = await file.exists();
+		if (!exists) return null;
+		const [contents] = await file.download();
+		const [metadata] = await file.getMetadata();
+		return {
+			...toMetadata(metadata),
+			data: new Uint8Array(contents)
+		};
+	}
+	async deleteObject(input) {
+		const bucketName = input.bucket ?? this.bucketName;
+		await this.storage.bucket(bucketName).file(input.key).delete({ ignoreNotFound: true });
+	}
+	async generateSignedUrl(options) {
+		const bucketName = options.bucket ?? this.bucketName;
+		const file = this.storage.bucket(bucketName).file(options.key);
+		const action = options.method === "PUT" ? "write" : "read";
+		const expires = Date.now() + options.expiresInSeconds * 1e3;
+		const [url] = await file.getSignedUrl({
+			action,
+			expires,
+			contentType: options.contentType
+		});
+		return {
+			url,
+			expiresAt: new Date(expires)
+		};
+	}
+	async listObjects(query) {
+		const bucketName = query.bucket ?? this.bucketName;
+		const [files, nextQuery, response] = await this.storage.bucket(bucketName).getFiles({
+			prefix: query.prefix,
+			maxResults: query.maxResults,
+			pageToken: query.pageToken
+		});
+		const nextTokenFromQuery = typeof nextQuery === "object" && nextQuery !== null && "pageToken" in nextQuery ? nextQuery.pageToken : void 0;
+		const nextTokenFromResponse = response && typeof response === "object" && "nextPageToken" in response ? response.nextPageToken : void 0;
+		return {
+			objects: files.map((file) => toMetadata(file.metadata)),
+			nextPageToken: nextTokenFromQuery ?? nextTokenFromResponse ?? void 0
+		};
+	}
+};
+function toBuffer(data) {
+	if (data instanceof Uint8Array) return Buffer.from(data);
+	return Buffer.from(data);
+}
+function toMetadata(metadata) {
+	return {
+		bucket: metadata.bucket ?? "",
+		key: metadata.name ?? "",
+		sizeBytes: metadata.size ? Number(metadata.size) : void 0,
+		contentType: metadata.contentType ?? void 0,
+		etag: metadata.etag ?? void 0,
+		checksum: metadata.md5Hash ?? void 0,
+		lastModified: metadata.updated ? new Date(metadata.updated) : void 0,
+		metadata: metadata.metadata
+	};
+}
+
+//#endregion
+export { GoogleCloudStorageProvider };

package/dist/integrations/providers/impls/gmail-inbound.d.ts

@@ -0,0 +1,26 @@
+import { EmailInboundProvider, EmailMessage, EmailMessagesSinceQuery, EmailThread, EmailThreadListQuery } from "../email.js";
+import { gmail_v1 } from "googleapis";
+
+//#region src/integrations/providers/impls/gmail-inbound.d.ts
+interface GmailInboundProviderOptions {
+  auth: gmail_v1.Options['auth'];
+  userId?: string;
+  gmail?: gmail_v1.Gmail;
+  includeSpamTrash?: boolean;
+}
+declare class GmailInboundProvider implements EmailInboundProvider {
+  private readonly gmail;
+  private readonly userId;
+  private readonly includeSpamTrash;
+  private readonly auth;
+  constructor(options: GmailInboundProviderOptions);
+  listThreads(query?: EmailThreadListQuery): Promise<EmailThread[]>;
+  getThread(threadId: string): Promise<EmailThread | null>;
+  listMessagesSince(query: EmailMessagesSinceQuery): Promise<{
+    messages: EmailMessage[];
+    nextPageToken: string | undefined;
+  }>;
+  private transformMessage;
+}
+//#endregion
+export { GmailInboundProvider, GmailInboundProviderOptions };