@lssm/lib.contracts 1.41.1 → 1.42.1

package/dist/integrations/providers/twilio-sms.js

@@ -1 +1,64 @@
-import{StabilityEnum as e}from"../../ownership.js";const t={meta:{key:`sms.twilio`,version:1,category:`sms`,displayName:`Twilio SMS`,title:`Twilio Messaging`,description:`Twilio SMS integration for transactional and notification messaging.`,domain:`communications`,owners:[`platform.messaging`],tags:[`sms`,`messaging`],stability:e.Stable},supportedModes:[`managed`,`byok`],capabilities:{provides:[{key:`sms.outbound`,version:1}]},configSchema:{schema:{type:`object`,properties:{fromNumber:{type:`string`,description:`Default Twilio phone number used as sender.`}}},example:{fromNumber:`+15551234567`}},secretSchema:{schema:{type:`object`,required:[`accountSid`,`authToken`],properties:{accountSid:{type:`string`,description:`Twilio Account SID.`},authToken:{type:`string`,description:`Twilio Auth Token.`}}},example:{accountSid:`ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`,authToken:`auth-token`}},healthCheck:{method:`custom`,timeoutMs:3e3},docsUrl:`https://www.twilio.com/docs/sms/api`,constraints:{rateLimit:{rpm:200}},byokSetup:{setupInstructions:`Provide a Twilio account SID, auth token, and verify the outbound sending numbers used by the integration.`}};function n(e){return e.register(t)}export{n as registerTwilioSmsIntegration,t as twilioSmsIntegrationSpec};
+import { StabilityEnum } from "../../ownership.js";
+
+//#region src/integrations/providers/twilio-sms.ts
+const twilioSmsIntegrationSpec = {
+	meta: {
+		key: "sms.twilio",
+		version: 1,
+		category: "sms",
+		title: "Twilio Messaging",
+		description: "Twilio SMS integration for transactional and notification messaging.",
+		domain: "communications",
+		owners: ["platform.messaging"],
+		tags: ["sms", "messaging"],
+		stability: StabilityEnum.Stable
+	},
+	supportedModes: ["managed", "byok"],
+	capabilities: { provides: [{
+		key: "sms.outbound",
+		version: 1
+	}] },
+	configSchema: {
+		schema: {
+			type: "object",
+			properties: { fromNumber: {
+				type: "string",
+				description: "Default Twilio phone number used as sender."
+			} }
+		},
+		example: { fromNumber: "+15551234567" }
+	},
+	secretSchema: {
+		schema: {
+			type: "object",
+			required: ["accountSid", "authToken"],
+			properties: {
+				accountSid: {
+					type: "string",
+					description: "Twilio Account SID."
+				},
+				authToken: {
+					type: "string",
+					description: "Twilio Auth Token."
+				}
+			}
+		},
+		example: {
+			accountSid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+			authToken: "auth-token"
+		}
+	},
+	healthCheck: {
+		method: "custom",
+		timeoutMs: 3e3
+	},
+	docsUrl: "https://www.twilio.com/docs/sms/api",
+	constraints: { rateLimit: { rpm: 200 } },
+	byokSetup: { setupInstructions: "Provide a Twilio account SID, auth token, and verify the outbound sending numbers used by the integration." }
+};
+function registerTwilioSmsIntegration(registry) {
+	return registry.register(twilioSmsIntegrationSpec);
+}
+
+//#endregion
+export { registerTwilioSmsIntegration, twilioSmsIntegrationSpec };

package/dist/integrations/providers/vector-store.d.ts

@@ -0,0 +1,43 @@
+import { EmbeddingVector } from "./embedding.js";
+
+//#region src/integrations/providers/vector-store.d.ts
+interface VectorDocument {
+  id: string;
+  vector: EmbeddingVector;
+  payload?: Record<string, unknown>;
+  namespace?: string;
+  expiresAt?: Date;
+}
+interface VectorUpsertRequest {
+  collection: string;
+  documents: VectorDocument[];
+  waitForSync?: boolean;
+}
+interface VectorDeleteRequest {
+  collection: string;
+  ids: string[];
+  namespace?: string;
+}
+interface VectorSearchQuery {
+  collection: string;
+  vector: EmbeddingVector;
+  topK: number;
+  namespace?: string;
+  filter?: Record<string, unknown>;
+  scoreThreshold?: number;
+  consistent?: boolean;
+}
+interface VectorSearchResult {
+  id: string;
+  score: number;
+  payload?: Record<string, unknown>;
+  vector?: EmbeddingVector;
+  namespace?: string;
+}
+interface VectorStoreProvider {
+  upsert(request: VectorUpsertRequest): Promise<void>;
+  search(query: VectorSearchQuery): Promise<VectorSearchResult[]>;
+  delete(request: VectorDeleteRequest): Promise<void>;
+}
+//#endregion
+export { VectorDeleteRequest, VectorDocument, VectorSearchQuery, VectorSearchResult, VectorStoreProvider, VectorUpsertRequest };

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

@@ -0,0 +1,34 @@
+//#region src/integrations/providers/voice.d.ts
+interface Voice {
+  id: string;
+  name: string;
+  description?: string;
+  language?: string;
+  gender?: 'male' | 'female' | 'neutral';
+  previewUrl?: string;
+  metadata?: Record<string, string>;
+}
+interface VoiceSynthesisInput {
+  text: string;
+  voiceId?: string;
+  language?: string;
+  style?: number;
+  stability?: number;
+  similarityBoost?: number;
+  format?: 'mp3' | 'wav' | 'ogg' | 'pcm';
+  sampleRateHz?: number;
+  metadata?: Record<string, string>;
+}
+interface VoiceSynthesisResult {
+  audio: Uint8Array;
+  format: string;
+  sampleRateHz: number;
+  durationSeconds?: number;
+  url?: string;
+}
+interface VoiceProvider {
+  listVoices(): Promise<Voice[]>;
+  synthesize(input: VoiceSynthesisInput): Promise<VoiceSynthesisResult>;
+}
+//#endregion
+export { Voice, VoiceProvider, VoiceSynthesisInput, VoiceSynthesisResult };

package/dist/integrations/runtime.d.ts

@@ -0,0 +1,99 @@
+import { IntegrationSpec } from "./spec.js";
+import { ConnectionStatus, IntegrationConnection } from "./connection.js";
+import { ResolvedAppConfig, ResolvedIntegration } from "../app-config/runtime.js";
+import { SecretProvider } from "./secrets/provider.js";
+
+//#region src/integrations/runtime.d.ts
+interface IntegrationTraceMetadata {
+  blueprintName: string;
+  blueprintVersion: number;
+  configVersion: number;
+}
+interface IntegrationTelemetryEvent {
+  tenantId: string;
+  appId: string;
+  environment?: string;
+  slotId?: string;
+  integrationKey: string;
+  integrationVersion: number;
+  connectionId: string;
+  status: 'success' | 'error';
+  durationMs?: number;
+  errorCode?: string;
+  errorMessage?: string;
+  occurredAt: Date;
+  metadata?: Record<string, string | number | boolean>;
+}
+interface IntegrationTelemetryEmitter {
+  record(event: IntegrationTelemetryEvent): Promise<void> | void;
+}
+type IntegrationInvocationStatus = 'success' | 'error';
+interface IntegrationContext {
+  tenantId: string;
+  appId: string;
+  environment?: string;
+  slotId?: string;
+  spec: IntegrationSpec;
+  connection: IntegrationConnection;
+  secretProvider: SecretProvider;
+  secretReference: string;
+  trace: IntegrationTraceMetadata;
+  config?: Record<string, unknown>;
+}
+interface IntegrationCallContext {
+  tenantId: string;
+  appId: string;
+  environment?: string;
+  blueprintName: string;
+  blueprintVersion: number;
+  configVersion: number;
+  slotId: string;
+  operation: string;
+}
+interface IntegrationCallError {
+  code: string;
+  message: string;
+  retryable: boolean;
+  cause?: unknown;
+}
+interface IntegrationCallResult<T> {
+  success: boolean;
+  data?: T;
+  error?: IntegrationCallError;
+  metadata: {
+    latencyMs: number;
+    connectionId: string;
+    ownershipMode: IntegrationConnection['ownershipMode'];
+    attempts: number;
+  };
+}
+interface IntegrationCallGuardOptions {
+  telemetry?: IntegrationTelemetryEmitter;
+  maxAttempts?: number;
+  backoffMs?: number;
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => Date;
+}
+declare class IntegrationCallGuard {
+  private readonly secretProvider;
+  private readonly telemetry?;
+  private readonly maxAttempts;
+  private readonly backoffMs;
+  private readonly shouldRetry;
+  private readonly sleep;
+  private readonly now;
+  constructor(secretProvider: SecretProvider, options?: IntegrationCallGuardOptions);
+  executeWithGuards<T>(slotId: string, operation: string, _input: unknown, resolvedConfig: ResolvedAppConfig, executor: (connection: IntegrationConnection, secrets: Record<string, string>) => Promise<T>): Promise<IntegrationCallResult<T>>;
+  private findIntegration;
+  private fetchSecrets;
+  private parseSecret;
+  private emitTelemetry;
+  private failure;
+  private makeContext;
+  private errorCodeFor;
+}
+declare function ensureConnectionReady(integration: ResolvedIntegration): void;
+declare function connectionStatusLabel(status: ConnectionStatus): string;
+//#endregion
+export { IntegrationCallContext, IntegrationCallError, IntegrationCallGuard, IntegrationCallGuardOptions, IntegrationCallResult, IntegrationContext, IntegrationInvocationStatus, IntegrationTelemetryEmitter, IntegrationTelemetryEvent, IntegrationTraceMetadata, connectionStatusLabel, ensureConnectionReady };

package/dist/integrations/runtime.js

@@ -1 +1,186 @@
-import{performance as e}from"node:perf_hooks";var t=class{telemetry;maxAttempts;backoffMs;shouldRetry;sleep;now;constructor(e,t={}){this.secretProvider=e,this.telemetry=t.telemetry,this.maxAttempts=Math.max(1,t.maxAttempts??3),this.backoffMs=t.backoffMs??250,this.shouldRetry=t.shouldRetry??(e=>typeof e==`object`&&!!e&&`retryable`in e&&!!e.retryable),this.sleep=t.sleep??(e=>e<=0?Promise.resolve():new Promise(t=>setTimeout(t,e))),this.now=t.now??(()=>new Date)}async executeWithGuards(t,n,r,i,a){let o=this.findIntegration(t,i);if(!o)return this.failure({tenantId:i.tenantId,appId:i.appId,environment:i.environment,blueprintName:i.blueprintName,blueprintVersion:i.blueprintVersion,configVersion:i.configVersion,slotId:t,operation:n},void 0,{code:`SLOT_NOT_BOUND`,message:`Integration slot "${t}" is not bound for tenant "${i.tenantId}".`,retryable:!1},0);let s=o.connection.status;if(s===`disconnected`||s===`error`)return this.failure(this.makeContext(t,n,i),o,{code:`CONNECTION_NOT_READY`,message:`Integration connection "${o.connection.meta.label}" is in status "${s}".`,retryable:!1},0);let c=await this.fetchSecrets(o.connection),l=0,u=e.now();for(;l<this.maxAttempts;){l+=1;try{let r=await a(o.connection,c),s=e.now()-u;return this.emitTelemetry(this.makeContext(t,n,i),o,`success`,s),{success:!0,data:r,metadata:{latencyMs:s,connectionId:o.connection.meta.id,ownershipMode:o.connection.ownershipMode,attempts:l}}}catch(r){let a=e.now()-u;this.emitTelemetry(this.makeContext(t,n,i),o,`error`,a,this.errorCodeFor(r),r instanceof Error?r.message:String(r));let s=this.shouldRetry(r,l);if(!s||l>=this.maxAttempts)return{success:!1,error:{code:this.errorCodeFor(r),message:r instanceof Error?r.message:String(r),retryable:s,cause:r},metadata:{latencyMs:a,connectionId:o.connection.meta.id,ownershipMode:o.connection.ownershipMode,attempts:l}};await this.sleep(this.backoffMs)}}return{success:!1,error:{code:`UNKNOWN_ERROR`,message:`Integration call failed after retries.`,retryable:!1},metadata:{latencyMs:e.now()-u,connectionId:o.connection.meta.id,ownershipMode:o.connection.ownershipMode,attempts:this.maxAttempts}}}findIntegration(e,t){return t.integrations.find(t=>t.slot.slotId===e)}async fetchSecrets(e){if(!this.secretProvider.canHandle(e.secretRef))throw Error(`Secret provider "${this.secretProvider.id}" cannot handle reference "${e.secretRef}".`);let t=await this.secretProvider.getSecret(e.secretRef);return this.parseSecret(t)}parseSecret(e){let t=new TextDecoder().decode(e.data);try{let e=JSON.parse(t);if(e&&typeof e==`object`&&!Array.isArray(e)){let t=Object.entries(e).filter(([,e])=>typeof e==`string`||typeof e==`number`||typeof e==`boolean`);return Object.fromEntries(t.map(([e,t])=>[e,String(t)]))}}catch{}return{secret:t}}emitTelemetry(e,t,n,r,i,a){!this.telemetry||!t||this.telemetry.record({tenantId:e.tenantId,appId:e.appId,environment:e.environment,slotId:e.slotId,integrationKey:t.connection.meta.integrationKey,integrationVersion:t.connection.meta.integrationVersion,connectionId:t.connection.meta.id,status:n,durationMs:r,errorCode:i,errorMessage:a,occurredAt:this.now(),metadata:{blueprint:`${e.blueprintName}.v${e.blueprintVersion}`,configVersion:e.configVersion,operation:e.operation}})}failure(e,t,n,r){return t&&this.emitTelemetry(e,t,`error`,0,n.code,n.message),{success:!1,error:n,metadata:{latencyMs:0,connectionId:t?.connection.meta.id??`unknown`,ownershipMode:t?.connection.ownershipMode??`managed`,attempts:r}}}makeContext(e,t,n){return{tenantId:n.tenantId,appId:n.appId,environment:n.environment,blueprintName:n.blueprintName,blueprintVersion:n.blueprintVersion,configVersion:n.configVersion,slotId:e,operation:t}}errorCodeFor(e){return typeof e==`object`&&e&&`code`in e&&typeof e.code==`string`?e.code:`PROVIDER_ERROR`}};function n(e){let t=e.connection.status;if(t===`disconnected`||t===`error`)throw Error(`Integration connection "${e.connection.meta.label}" is in status "${t}".`)}function r(e){switch(e){case`connected`:return`connected`;case`disconnected`:return`disconnected`;case`error`:return`error`;case`unknown`:default:return`unknown`}}export{t as IntegrationCallGuard,r as connectionStatusLabel,n as ensureConnectionReady};
+import { performance } from "node:perf_hooks";
+
+//#region src/integrations/runtime.ts
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BACKOFF_MS = 250;
+var IntegrationCallGuard = class {
+	telemetry;
+	maxAttempts;
+	backoffMs;
+	shouldRetry;
+	sleep;
+	now;
+	constructor(secretProvider, options = {}) {
+		this.secretProvider = secretProvider;
+		this.telemetry = options.telemetry;
+		this.maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+		this.backoffMs = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+		this.shouldRetry = options.shouldRetry ?? ((error) => typeof error === "object" && error !== null && "retryable" in error && Boolean(error.retryable));
+		this.sleep = options.sleep ?? ((ms) => ms <= 0 ? Promise.resolve() : new Promise((resolve) => setTimeout(resolve, ms)));
+		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+	}
+	async executeWithGuards(slotId, operation, _input, resolvedConfig, executor) {
+		const integration = this.findIntegration(slotId, resolvedConfig);
+		if (!integration) return this.failure({
+			tenantId: resolvedConfig.tenantId,
+			appId: resolvedConfig.appId,
+			environment: resolvedConfig.environment,
+			blueprintName: resolvedConfig.blueprintName,
+			blueprintVersion: resolvedConfig.blueprintVersion,
+			configVersion: resolvedConfig.configVersion,
+			slotId,
+			operation
+		}, void 0, {
+			code: "SLOT_NOT_BOUND",
+			message: `Integration slot "${slotId}" is not bound for tenant "${resolvedConfig.tenantId}".`,
+			retryable: false
+		}, 0);
+		const status = integration.connection.status;
+		if (status === "disconnected" || status === "error") return this.failure(this.makeContext(slotId, operation, resolvedConfig), integration, {
+			code: "CONNECTION_NOT_READY",
+			message: `Integration connection "${integration.connection.meta.label}" is in status "${status}".`,
+			retryable: false
+		}, 0);
+		const secrets = await this.fetchSecrets(integration.connection);
+		let attempt = 0;
+		const started = performance.now();
+		while (attempt < this.maxAttempts) {
+			attempt += 1;
+			try {
+				const data = await executor(integration.connection, secrets);
+				const duration = performance.now() - started;
+				this.emitTelemetry(this.makeContext(slotId, operation, resolvedConfig), integration, "success", duration);
+				return {
+					success: true,
+					data,
+					metadata: {
+						latencyMs: duration,
+						connectionId: integration.connection.meta.id,
+						ownershipMode: integration.connection.ownershipMode,
+						attempts: attempt
+					}
+				};
+			} catch (error) {
+				const duration = performance.now() - started;
+				this.emitTelemetry(this.makeContext(slotId, operation, resolvedConfig), integration, "error", duration, this.errorCodeFor(error), error instanceof Error ? error.message : String(error));
+				const retryable = this.shouldRetry(error, attempt);
+				if (!retryable || attempt >= this.maxAttempts) return {
+					success: false,
+					error: {
+						code: this.errorCodeFor(error),
+						message: error instanceof Error ? error.message : String(error),
+						retryable,
+						cause: error
+					},
+					metadata: {
+						latencyMs: duration,
+						connectionId: integration.connection.meta.id,
+						ownershipMode: integration.connection.ownershipMode,
+						attempts: attempt
+					}
+				};
+				await this.sleep(this.backoffMs);
+			}
+		}
+		return {
+			success: false,
+			error: {
+				code: "UNKNOWN_ERROR",
+				message: "Integration call failed after retries.",
+				retryable: false
+			},
+			metadata: {
+				latencyMs: performance.now() - started,
+				connectionId: integration.connection.meta.id,
+				ownershipMode: integration.connection.ownershipMode,
+				attempts: this.maxAttempts
+			}
+		};
+	}
+	findIntegration(slotId, config) {
+		return config.integrations.find((integration) => integration.slot.slotId === slotId);
+	}
+	async fetchSecrets(connection) {
+		if (!this.secretProvider.canHandle(connection.secretRef)) throw new Error(`Secret provider "${this.secretProvider.id}" cannot handle reference "${connection.secretRef}".`);
+		const secret = await this.secretProvider.getSecret(connection.secretRef);
+		return this.parseSecret(secret);
+	}
+	parseSecret(secret) {
+		const text = new TextDecoder().decode(secret.data);
+		try {
+			const parsed = JSON.parse(text);
+			if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+				const entries = Object.entries(parsed).filter(([, value]) => typeof value === "string" || typeof value === "number" || typeof value === "boolean");
+				return Object.fromEntries(entries.map(([key, value]) => [key, String(value)]));
+			}
+		} catch {}
+		return { secret: text };
+	}
+	emitTelemetry(context, integration, status, durationMs, errorCode, errorMessage) {
+		if (!this.telemetry || !integration) return;
+		this.telemetry.record({
+			tenantId: context.tenantId,
+			appId: context.appId,
+			environment: context.environment,
+			slotId: context.slotId,
+			integrationKey: integration.connection.meta.integrationKey,
+			integrationVersion: integration.connection.meta.integrationVersion,
+			connectionId: integration.connection.meta.id,
+			status,
+			durationMs,
+			errorCode,
+			errorMessage,
+			occurredAt: this.now(),
+			metadata: {
+				blueprint: `${context.blueprintName}.v${context.blueprintVersion}`,
+				configVersion: context.configVersion,
+				operation: context.operation
+			}
+		});
+	}
+	failure(context, integration, error, attempts) {
+		if (integration) this.emitTelemetry(context, integration, "error", 0, error.code, error.message);
+		return {
+			success: false,
+			error,
+			metadata: {
+				latencyMs: 0,
+				connectionId: integration?.connection.meta.id ?? "unknown",
+				ownershipMode: integration?.connection.ownershipMode ?? "managed",
+				attempts
+			}
+		};
+	}
+	makeContext(slotId, operation, config) {
+		return {
+			tenantId: config.tenantId,
+			appId: config.appId,
+			environment: config.environment,
+			blueprintName: config.blueprintName,
+			blueprintVersion: config.blueprintVersion,
+			configVersion: config.configVersion,
+			slotId,
+			operation
+		};
+	}
+	errorCodeFor(error) {
+		if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") return error.code;
+		return "PROVIDER_ERROR";
+	}
+};
+function ensureConnectionReady(integration) {
+	const status = integration.connection.status;
+	if (status === "disconnected" || status === "error") throw new Error(`Integration connection "${integration.connection.meta.label}" is in status "${status}".`);
+}
+function connectionStatusLabel(status) {
+	switch (status) {
+		case "connected": return "connected";
+		case "disconnected": return "disconnected";
+		case "error": return "error";
+		case "unknown":
+		default: return "unknown";
+	}
+}
+
+//#endregion
+export { IntegrationCallGuard, connectionStatusLabel, ensureConnectionReady };

package/dist/integrations/secrets/aws-secret-manager.d.ts

@@ -0,0 +1,31 @@
+import { SecretFetchOptions, SecretProvider, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload } from "./provider.js";
+import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
+
+//#region src/integrations/secrets/aws-secret-manager.d.ts
+type AwsSecretsManagerClient = Pick<SecretsManagerClient, 'send'>;
+type AwsSecretsManagerClientConfig = ConstructorParameters<typeof SecretsManagerClient>[0];
+interface AwsSecretsManagerProviderOptions {
+  region?: string;
+  client?: AwsSecretsManagerClient;
+  clientConfig?: AwsSecretsManagerClientConfig;
+}
+declare class AwsSecretsManagerProvider implements SecretProvider {
+  readonly id = "aws-secrets-manager";
+  private readonly explicitRegion?;
+  private readonly injectedClient?;
+  private readonly clientConfig?;
+  private readonly clientsByRegion;
+  constructor(options?: AwsSecretsManagerProviderOptions);
+  canHandle(reference: SecretReference): boolean;
+  getSecret(reference: SecretReference, options?: SecretFetchOptions): Promise<SecretValue>;
+  setSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  rotateSecret(reference: SecretReference, payload: SecretWritePayload): Promise<SecretRotationResult>;
+  deleteSecret(reference: SecretReference): Promise<void>;
+  private getClient;
+  private parseReference;
+  private resolveRegion;
+  private buildVersionSelector;
+  private buildReference;
+}
+//#endregion
+export { AwsSecretsManagerProvider };