@contractspec/lib.contracts-spec 2.0.0

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

@@ -0,0 +1,121 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// 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/twilio-sms.ts
+import { StabilityEnum } from "@contractspec/lib.contracts-spec/ownership";
+var twilioSmsIntegrationSpec = defineIntegration({
+  meta: {
+    key: "sms.twilio",
+    version: "1.0.0",
+    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.0.0" }]
+  },
+  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: 3000
+  },
+  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);
+}
+export {
+  twilioSmsIntegrationSpec,
+  registerTwilioSmsIntegration
+};

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

@@ -0,0 +1,39 @@
+import type { EmbeddingVector } from './embedding';
+export interface VectorDocument {
+    id: string;
+    vector: EmbeddingVector;
+    payload?: Record<string, unknown>;
+    namespace?: string;
+    expiresAt?: Date;
+}
+export interface VectorUpsertRequest {
+    collection: string;
+    documents: VectorDocument[];
+    waitForSync?: boolean;
+}
+export interface VectorDeleteRequest {
+    collection: string;
+    ids: string[];
+    namespace?: string;
+}
+export interface VectorSearchQuery {
+    collection: string;
+    vector: EmbeddingVector;
+    topK: number;
+    namespace?: string;
+    filter?: Record<string, unknown>;
+    scoreThreshold?: number;
+    consistent?: boolean;
+}
+export interface VectorSearchResult {
+    id: string;
+    score: number;
+    payload?: Record<string, unknown>;
+    vector?: EmbeddingVector;
+    namespace?: string;
+}
+export interface VectorStoreProvider {
+    upsert(request: VectorUpsertRequest): Promise<void>;
+    search(query: VectorSearchQuery): Promise<VectorSearchResult[]>;
+    delete(request: VectorDeleteRequest): Promise<void>;
+}

package/dist/integrations/providers/vector-store.js

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

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

@@ -0,0 +1,31 @@
+export interface Voice {
+    id: string;
+    name: string;
+    description?: string;
+    language?: string;
+    gender?: 'male' | 'female' | 'neutral';
+    previewUrl?: string;
+    metadata?: Record<string, string>;
+}
+export 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>;
+}
+export interface VoiceSynthesisResult {
+    audio: Uint8Array;
+    format: string;
+    sampleRateHz: number;
+    durationSeconds?: number;
+    url?: string;
+}
+export interface VoiceProvider {
+    listVoices(): Promise<Voice[]>;
+    synthesize(input: VoiceSynthesisInput): Promise<VoiceSynthesisResult>;
+}

package/dist/integrations/providers/voice.js

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

package/dist/integrations/runtime.d.ts

@@ -0,0 +1,95 @@
+import type { ResolvedAppConfig, ResolvedIntegration } from '@contractspec/lib.contracts-spec/app-config/runtime';
+import type { ConnectionStatus, IntegrationConnection } from './connection';
+import type { IntegrationSpec } from './spec';
+import type { SecretProvider } from './secrets/provider';
+export interface IntegrationTraceMetadata {
+    blueprintName: string;
+    blueprintVersion: string;
+    configVersion: string;
+}
+export interface IntegrationTelemetryEvent {
+    tenantId: string;
+    appId: string;
+    environment?: string;
+    slotId?: string;
+    integrationKey: string;
+    integrationVersion: string;
+    connectionId: string;
+    status: 'success' | 'error';
+    durationMs?: number;
+    errorCode?: string;
+    errorMessage?: string;
+    occurredAt: Date;
+    metadata?: Record<string, string | number | boolean>;
+}
+export interface IntegrationTelemetryEmitter {
+    record(event: IntegrationTelemetryEvent): Promise<void> | void;
+}
+export type IntegrationInvocationStatus = 'success' | 'error';
+export interface IntegrationContext {
+    tenantId: string;
+    appId: string;
+    environment?: string;
+    slotId?: string;
+    spec: IntegrationSpec;
+    connection: IntegrationConnection;
+    secretProvider: SecretProvider;
+    secretReference: string;
+    trace: IntegrationTraceMetadata;
+    config?: Record<string, unknown>;
+}
+export interface IntegrationCallContext {
+    tenantId: string;
+    appId: string;
+    environment?: string;
+    blueprintName: string;
+    blueprintVersion: string;
+    configVersion: string;
+    slotId: string;
+    operation: string;
+}
+export interface IntegrationCallError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    cause?: unknown;
+}
+export interface IntegrationCallResult<T> {
+    success: boolean;
+    data?: T;
+    error?: IntegrationCallError;
+    metadata: {
+        latencyMs: number;
+        connectionId: string;
+        ownershipMode: IntegrationConnection['ownershipMode'];
+        attempts: number;
+    };
+}
+export interface IntegrationCallGuardOptions {
+    telemetry?: IntegrationTelemetryEmitter;
+    maxAttempts?: number;
+    backoffMs?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => Date;
+}
+export 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;
+}
+export declare function ensureConnectionReady(integration: ResolvedIntegration): void;
+export declare function connectionStatusLabel(status: ConnectionStatus): string;

package/dist/integrations/runtime.js

@@ -0,0 +1,239 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// src/integrations/runtime.ts
+import { performance } from "perf_hooks";
+var DEFAULT_MAX_ATTEMPTS = 3;
+var DEFAULT_BACKOFF_MS = 250;
+
+class IntegrationCallGuard {
+  secretProvider;
+  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 ?? (() => 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
+      }, undefined, {
+        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";
+  }
+}
+export {
+  ensureConnectionReady,
+  connectionStatusLabel,
+  IntegrationCallGuard
+};

package/dist/integrations/runtime.test.d.ts

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

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

@@ -0,0 +1,28 @@
+import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+import type { SecretFetchOptions, SecretProvider, SecretReference, SecretRotationResult, SecretValue, SecretWritePayload } from './provider';
+type AwsSecretsManagerClient = Pick<SecretsManagerClient, 'send'>;
+type AwsSecretsManagerClientConfig = ConstructorParameters<typeof SecretsManagerClient>[0];
+interface AwsSecretsManagerProviderOptions {
+    region?: string;
+    client?: AwsSecretsManagerClient;
+    clientConfig?: AwsSecretsManagerClientConfig;
+}
+export 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;
+}
+export {};