@contractspec/lib.contracts 0.0.0-canary-20260113162409

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

@@ -0,0 +1,109 @@
+//#region src/integrations/providers/payments.d.ts
+interface Money {
+  /** Amount denominated in the smallest currency unit (e.g., cents). */
+  amount: number;
+  currency: string;
+}
+type PaymentIntentStatus = 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'succeeded' | 'canceled';
+interface PaymentCustomer {
+  id: string;
+  email?: string;
+  name?: string;
+  metadata?: Record<string, string>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+interface CreateCustomerInput {
+  email?: string;
+  name?: string;
+  description?: string;
+  metadata?: Record<string, string>;
+}
+interface PaymentIntent {
+  id: string;
+  amount: Money;
+  status: PaymentIntentStatus;
+  customerId?: string;
+  clientSecret?: string;
+  description?: string;
+  metadata?: Record<string, string>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+interface CreatePaymentIntentInput {
+  amount: Money;
+  customerId?: string;
+  confirmationMethod?: 'automatic' | 'manual';
+  captureMethod?: 'automatic' | 'manual';
+  description?: string;
+  metadata?: Record<string, string>;
+  statementDescriptor?: string;
+  returnUrl?: string;
+}
+interface CapturePaymentInput {
+  amount?: Money;
+  receiptEmail?: string;
+  metadata?: Record<string, string>;
+}
+interface PaymentRefund {
+  id: string;
+  paymentIntentId: string;
+  amount: Money;
+  status: 'pending' | 'succeeded' | 'failed' | 'canceled';
+  reason?: string;
+  metadata?: Record<string, string>;
+  createdAt?: Date;
+}
+interface RefundPaymentInput {
+  paymentIntentId: string;
+  amount?: Money;
+  reason?: string;
+  metadata?: Record<string, string>;
+}
+interface PaymentInvoice {
+  id: string;
+  number?: string;
+  status: 'draft' | 'open' | 'paid' | 'uncollectible' | 'void' | 'deleted';
+  amountDue: Money;
+  amountPaid?: Money;
+  customerId?: string;
+  dueDate?: Date;
+  hostedInvoiceUrl?: string;
+  metadata?: Record<string, string>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+interface ListInvoicesQuery {
+  customerId?: string;
+  status?: PaymentInvoice['status'][];
+  limit?: number;
+  startingAfter?: string;
+}
+interface PaymentTransaction {
+  id: string;
+  paymentIntentId?: string;
+  amount: Money;
+  type: 'capture' | 'refund' | 'payout';
+  status: 'pending' | 'succeeded' | 'failed';
+  description?: string;
+  createdAt: Date;
+  metadata?: Record<string, string>;
+}
+interface ListTransactionsQuery {
+  customerId?: string;
+  paymentIntentId?: string;
+  limit?: number;
+  startingAfter?: string;
+}
+interface PaymentsProvider {
+  createCustomer(input: CreateCustomerInput): Promise<PaymentCustomer>;
+  getCustomer(customerId: string): Promise<PaymentCustomer | null>;
+  createPaymentIntent(input: CreatePaymentIntentInput): Promise<PaymentIntent>;
+  capturePayment(paymentIntentId: string, input?: CapturePaymentInput): Promise<PaymentIntent>;
+  cancelPaymentIntent(paymentIntentId: string): Promise<PaymentIntent>;
+  refundPayment(input: RefundPaymentInput): Promise<PaymentRefund>;
+  listInvoices(query?: ListInvoicesQuery): Promise<PaymentInvoice[]>;
+  listTransactions(query?: ListTransactionsQuery): Promise<PaymentTransaction[]>;
+}
+//#endregion
+export { CapturePaymentInput, CreateCustomerInput, CreatePaymentIntentInput, ListInvoicesQuery, ListTransactionsQuery, Money, PaymentCustomer, PaymentIntent, PaymentIntentStatus, PaymentInvoice, PaymentRefund, PaymentTransaction, PaymentsProvider, RefundPaymentInput };

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

@@ -0,0 +1,8 @@
+import { IntegrationSpec, IntegrationSpecRegistry } from "../spec.js";
+import "../index.js";
+
+//#region src/integrations/providers/postmark.d.ts
+declare const postmarkIntegrationSpec: IntegrationSpec;
+declare function registerPostmarkIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;
+//#endregion
+export { postmarkIntegrationSpec, registerPostmarkIntegration };

package/dist/integrations/providers/postmark.js

@@ -0,0 +1,72 @@
+import { StabilityEnum } from "../../ownership.js";
+import { defineIntegration } from "../spec.js";
+
+//#region src/integrations/providers/postmark.ts
+const postmarkIntegrationSpec = defineIntegration({
+	meta: {
+		key: "email.postmark",
+		version: "1.0.0",
+		category: "email",
+		title: "Postmark Transactional Email",
+		description: "Postmark integration for transactional email delivery.",
+		domain: "communications",
+		owners: ["platform.messaging"],
+		tags: ["email", "transactional"],
+		stability: StabilityEnum.Stable
+	},
+	supportedModes: ["managed", "byok"],
+	capabilities: {
+		provides: [{
+			key: "email.transactional",
+			version: "1.0.0"
+		}],
+		requires: [{
+			key: "platform.webhooks",
+			optional: true,
+			reason: "Optional for inbound bounce handling"
+		}]
+	},
+	configSchema: {
+		schema: {
+			type: "object",
+			properties: {
+				messageStream: {
+					type: "string",
+					description: "Optional message stream identifier (e.g., transactional)."
+				},
+				fromEmail: {
+					type: "string",
+					description: "Default From address used for outbound messages."
+				}
+			}
+		},
+		example: {
+			messageStream: "outbound",
+			fromEmail: "notifications@example.com"
+		}
+	},
+	secretSchema: {
+		schema: {
+			type: "object",
+			required: ["serverToken"],
+			properties: { serverToken: {
+				type: "string",
+				description: "Server token for the Postmark account."
+			} }
+		},
+		example: { serverToken: "server-***" }
+	},
+	healthCheck: {
+		method: "ping",
+		timeoutMs: 3e3
+	},
+	docsUrl: "https://postmarkapp.com/developer",
+	constraints: { rateLimit: { rpm: 500 } },
+	byokSetup: { setupInstructions: "Create a Postmark server token with outbound send permissions and configure allowed from addresses." }
+});
+function registerPostmarkIntegration(registry) {
+	return registry.register(postmarkIntegrationSpec);
+}
+
+//#endregion
+export { postmarkIntegrationSpec, registerPostmarkIntegration };

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

@@ -0,0 +1,8 @@
+import { IntegrationSpec, IntegrationSpecRegistry } from "../spec.js";
+import "../index.js";
+
+//#region src/integrations/providers/powens.d.ts
+declare const powensIntegrationSpec: IntegrationSpec;
+declare function registerPowensIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;
+//#endregion
+export { powensIntegrationSpec, registerPowensIntegration };

package/dist/integrations/providers/powens.js

@@ -0,0 +1,120 @@
+import { StabilityEnum } from "../../ownership.js";
+import { defineIntegration } from "../spec.js";
+
+//#region src/integrations/providers/powens.ts
+const powensIntegrationSpec = defineIntegration({
+	meta: {
+		key: "openbanking.powens",
+		version: "1.0.0",
+		category: "open-banking",
+		title: "Powens Open Banking (Read)",
+		description: "Read-only Open Banking integration powered by Powens, exposing accounts, transactions, and balances.",
+		domain: "finance",
+		owners: ["platform.finance"],
+		tags: [
+			"open-banking",
+			"powens",
+			"finance"
+		],
+		stability: StabilityEnum.Experimental
+	},
+	supportedModes: ["byok"],
+	capabilities: { provides: [
+		{
+			key: "openbanking.accounts.read",
+			version: "1.0.0"
+		},
+		{
+			key: "openbanking.transactions.read",
+			version: "1.0.0"
+		},
+		{
+			key: "openbanking.balances.read",
+			version: "1.0.0"
+		}
+	] },
+	configSchema: {
+		schema: {
+			type: "object",
+			required: ["environment"],
+			properties: {
+				environment: {
+					type: "string",
+					enum: ["sandbox", "production"],
+					description: "Powens environment to target. Sandbox uses Powens test API base URL, production uses live endpoints."
+				},
+				baseUrl: {
+					type: "string",
+					description: "Optional override for the Powens API base URL. Defaults to Powens environment defaults."
+				},
+				region: {
+					type: "string",
+					description: "Optional Powens region identifier when targeting a specific data residency cluster."
+				},
+				pollingIntervalMs: {
+					type: "number",
+					description: "Optional custom polling interval in milliseconds for background sync jobs (defaults to platform standard)."
+				}
+			}
+		},
+		example: {
+			environment: "sandbox",
+			baseUrl: "https://api-sandbox.powens.com/v2",
+			region: "eu-west-1",
+			pollingIntervalMs: 3e5
+		}
+	},
+	secretSchema: {
+		schema: {
+			type: "object",
+			required: ["clientId", "clientSecret"],
+			properties: {
+				clientId: {
+					type: "string",
+					description: "Powens OAuth client identifier obtained from the Powens Console (BYOK project)."
+				},
+				clientSecret: {
+					type: "string",
+					description: "Powens OAuth client secret used to exchange for access tokens."
+				},
+				apiKey: {
+					type: "string",
+					description: "Optional Powens API key (if the tenant project exposes a dedicated API token)."
+				},
+				webhookSecret: {
+					type: "string",
+					description: "Optional webhook signing secret used to verify Powens webhook payloads."
+				}
+			}
+		},
+		example: {
+			clientId: "powens-client-id",
+			clientSecret: "powens-client-secret",
+			apiKey: "powens-api-key",
+			webhookSecret: "powens-webhook-secret"
+		}
+	},
+	healthCheck: {
+		method: "ping",
+		timeoutMs: 8e3
+	},
+	docsUrl: "https://docs.powens.com/",
+	constraints: { rateLimit: {
+		rph: 1e4,
+		rpm: 600
+	} },
+	byokSetup: {
+		setupInstructions: "Create a Powens BYOK project, generate OAuth credentials, and optionally configure webhook delivery for account/transaction updates.",
+		requiredScopes: [
+			"accounts:read",
+			"transactions:read",
+			"balances:read"
+		]
+	}
+});
+function registerPowensIntegration(registry) {
+	return registry.register(powensIntegrationSpec);
+}
+
+//#endregion
+export { powensIntegrationSpec, registerPowensIntegration };

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

@@ -0,0 +1,8 @@
+import { IntegrationSpec, IntegrationSpecRegistry } from "../spec.js";
+import "../index.js";
+
+//#region src/integrations/providers/qdrant.d.ts
+declare const qdrantIntegrationSpec: IntegrationSpec;
+declare function registerQdrantIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;
+//#endregion
+export { qdrantIntegrationSpec, registerQdrantIntegration };

package/dist/integrations/providers/qdrant.js

@@ -0,0 +1,77 @@
+import { StabilityEnum } from "../../ownership.js";
+import { defineIntegration } from "../spec.js";
+
+//#region src/integrations/providers/qdrant.ts
+const qdrantIntegrationSpec = defineIntegration({
+	meta: {
+		key: "vectordb.qdrant",
+		version: "1.0.0",
+		category: "vector-db",
+		title: "Qdrant Vector Database",
+		description: "Qdrant integration for vector search and embeddings storage.",
+		domain: "ai",
+		owners: ["platform.ai"],
+		tags: ["vector-db", "search"],
+		stability: StabilityEnum.Experimental
+	},
+	supportedModes: ["managed", "byok"],
+	capabilities: {
+		provides: [{
+			key: "vector-db.search",
+			version: "1.0.0"
+		}, {
+			key: "vector-db.storage",
+			version: "1.0.0"
+		}],
+		requires: [{
+			key: "ai.embeddings",
+			optional: true,
+			reason: "Required if vectors are generated via hosted embedding services"
+		}]
+	},
+	configSchema: {
+		schema: {
+			type: "object",
+			properties: {
+				apiUrl: {
+					type: "string",
+					description: "Base URL for the Qdrant instance (e.g., https://qdrant.example.com)."
+				},
+				collectionPrefix: {
+					type: "string",
+					description: "Prefix applied to all collection names for this tenant."
+				}
+			}
+		},
+		example: {
+			apiUrl: "https://qdrant.example.com",
+			collectionPrefix: "tenant_"
+		}
+	},
+	secretSchema: {
+		schema: {
+			type: "object",
+			properties: { apiKey: {
+				type: "string",
+				description: "API key or token when authentication is enabled."
+			} }
+		},
+		example: { apiKey: "qdrant-api-key" }
+	},
+	healthCheck: {
+		method: "ping",
+		timeoutMs: 4e3
+	},
+	docsUrl: "https://qdrant.tech/documentation/quick-start/",
+	constraints: { quotas: {
+		collections: 100,
+		pointsPerCollection: 1e6
+	} },
+	byokSetup: { setupInstructions: "Provide the HTTPS endpoint of your Qdrant cluster and generate an API key with read/write access to the collections that will be managed." }
+});
+function registerQdrantIntegration(registry) {
+	return registry.register(qdrantIntegrationSpec);
+}
+
+//#endregion
+export { qdrantIntegrationSpec, registerQdrantIntegration };

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

@@ -0,0 +1,11 @@
+import { IntegrationSpecRegistry } from "../spec.js";
+
+//#region src/integrations/providers/registry.d.ts
+
+/**
+ * Creates a registry containing all IntegrationSpec providers shipped by
+ * `@contractspec/lib.contracts`.
+ */
+declare function createDefaultIntegrationSpecRegistry(): IntegrationSpecRegistry;
+//#endregion
+export { createDefaultIntegrationSpecRegistry };

package/dist/integrations/providers/registry.js

@@ -0,0 +1,34 @@
+import { IntegrationSpecRegistry } from "../spec.js";
+import { registerStripeIntegration } from "./stripe.js";
+import { registerPostmarkIntegration } from "./postmark.js";
+import { registerQdrantIntegration } from "./qdrant.js";
+import { registerMistralIntegration } from "./mistral.js";
+import { registerElevenLabsIntegration } from "./elevenlabs.js";
+import { registerGmailIntegration } from "./gmail.js";
+import { registerGoogleCalendarIntegration } from "./google-calendar.js";
+import { registerTwilioSmsIntegration } from "./twilio-sms.js";
+import { registerGcsStorageIntegration } from "./gcs-storage.js";
+import { registerPowensIntegration } from "./powens.js";
+
+//#region src/integrations/providers/registry.ts
+/**
+* Creates a registry containing all IntegrationSpec providers shipped by
+* `@contractspec/lib.contracts`.
+*/
+function createDefaultIntegrationSpecRegistry() {
+	const registry = new IntegrationSpecRegistry();
+	registerStripeIntegration(registry);
+	registerPostmarkIntegration(registry);
+	registerQdrantIntegration(registry);
+	registerMistralIntegration(registry);
+	registerElevenLabsIntegration(registry);
+	registerGmailIntegration(registry);
+	registerGoogleCalendarIntegration(registry);
+	registerTwilioSmsIntegration(registry);
+	registerGcsStorageIntegration(registry);
+	registerPowensIntegration(registry);
+	return registry;
+}
+
+//#endregion
+export { createDefaultIntegrationSpecRegistry };

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

@@ -0,0 +1,34 @@
+//#region src/integrations/providers/sms.d.ts
+interface SmsMessage {
+  id: string;
+  to: string;
+  from: string;
+  body: string;
+  status: 'queued' | 'sending' | 'sent' | 'delivered' | 'undelivered' | 'failed';
+  providerMessageId?: string;
+  carrier?: string;
+  price?: number;
+  priceCurrency?: string;
+  sentAt?: Date;
+  deliveredAt?: Date;
+  errorCode?: string;
+  errorMessage?: string;
+}
+interface SendSmsInput {
+  to: string;
+  from?: string;
+  body: string;
+  metadata?: Record<string, string>;
+}
+interface SmsDeliveryStatus {
+  status: SmsMessage['status'];
+  errorCode?: string;
+  errorMessage?: string;
+  updatedAt: Date;
+}
+interface SmsProvider {
+  sendSms(input: SendSmsInput): Promise<SmsMessage>;
+  getDeliveryStatus(messageId: string): Promise<SmsDeliveryStatus>;
+}
+//#endregion
+export { SendSmsInput, SmsDeliveryStatus, SmsMessage, SmsProvider };

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

@@ -0,0 +1,60 @@
+//#region src/integrations/providers/storage.d.ts
+interface StorageObjectMetadata {
+  bucket: string;
+  key: string;
+  sizeBytes?: number;
+  contentType?: string;
+  etag?: string;
+  checksum?: string;
+  lastModified?: Date;
+  metadata?: Record<string, string>;
+}
+type StorageObjectBody = {
+  data: Uint8Array;
+  stream?: never;
+} | {
+  data?: never;
+  stream: AsyncIterable<Uint8Array>;
+};
+type GetObjectResult = StorageObjectMetadata & StorageObjectBody;
+interface PutObjectInput {
+  bucket: string;
+  key: string;
+  data: Uint8Array | ArrayBuffer;
+  contentType?: string;
+  metadata?: Record<string, string>;
+  makePublic?: boolean;
+}
+interface DeleteObjectInput {
+  bucket: string;
+  key: string;
+}
+interface SignedUrlOptions {
+  bucket: string;
+  key: string;
+  expiresInSeconds: number;
+  method?: 'GET' | 'PUT';
+  contentType?: string;
+}
+interface ListObjectsQuery {
+  bucket: string;
+  prefix?: string;
+  maxResults?: number;
+  pageToken?: string;
+}
+interface ListObjectsResult {
+  objects: StorageObjectMetadata[];
+  nextPageToken?: string;
+}
+interface ObjectStorageProvider {
+  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 { DeleteObjectInput, GetObjectResult, ListObjectsQuery, ListObjectsResult, ObjectStorageProvider, PutObjectInput, SignedUrlOptions, StorageObjectBody, StorageObjectMetadata };

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

@@ -0,0 +1,8 @@
+import { IntegrationSpec, IntegrationSpecRegistry } from "../spec.js";
+import "../index.js";
+
+//#region src/integrations/providers/stripe.d.ts
+declare const stripeIntegrationSpec: IntegrationSpec;
+declare function registerStripeIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;
+//#endregion
+export { registerStripeIntegration, stripeIntegrationSpec };

package/dist/integrations/providers/stripe.js

@@ -0,0 +1,87 @@
+import { StabilityEnum } from "../../ownership.js";
+import { defineIntegration } from "../spec.js";
+
+//#region src/integrations/providers/stripe.ts
+const stripeIntegrationSpec = defineIntegration({
+	meta: {
+		key: "payments.stripe",
+		version: "1.0.0",
+		category: "payments",
+		title: "Stripe Payments",
+		description: "Stripe integration for payment processing, charges, and payouts.",
+		domain: "payments",
+		owners: ["platform.payments"],
+		tags: ["payments", "psp"],
+		stability: StabilityEnum.Stable
+	},
+	supportedModes: ["managed", "byok"],
+	capabilities: {
+		provides: [{
+			key: "payments.psp",
+			version: "1.0.0"
+		}],
+		requires: [{
+			key: "platform.webhooks",
+			optional: true,
+			reason: "Recommended for reliable event ingestion"
+		}]
+	},
+	configSchema: {
+		schema: {
+			type: "object",
+			properties: {
+				accountId: {
+					type: "string",
+					description: "Connected account ID when using Stripe Connect (BYOK)."
+				},
+				region: {
+					type: "string",
+					description: "Optional Stripe region or data residency hint."
+				}
+			}
+		},
+		example: {
+			accountId: "acct_123",
+			region: "us-east-1"
+		}
+	},
+	secretSchema: {
+		schema: {
+			type: "object",
+			required: ["apiKey", "webhookSecret"],
+			properties: {
+				apiKey: {
+					type: "string",
+					description: "Stripe secret API key (sk_live_... or sk_test_...)."
+				},
+				webhookSecret: {
+					type: "string",
+					description: "Signing secret for webhook verification."
+				}
+			}
+		},
+		example: {
+			apiKey: "sk_live_***",
+			webhookSecret: "whsec_***"
+		}
+	},
+	healthCheck: {
+		method: "ping",
+		timeoutMs: 5e3
+	},
+	docsUrl: "https://stripe.com/docs/api",
+	constraints: { rateLimit: {
+		rpm: 1e3,
+		rph: 2e4
+	} },
+	byokSetup: {
+		setupInstructions: "Create a restricted Stripe API key with write access to Charges and provide a webhook signing secret.",
+		requiredScopes: ["charges:write", "customers:read"]
+	}
+});
+function registerStripeIntegration(registry) {
+	return registry.register(stripeIntegrationSpec);
+}
+
+//#endregion
+export { registerStripeIntegration, stripeIntegrationSpec };

package/dist/integrations/providers/twilio-sms.d.ts

@@ -0,0 +1,8 @@
+import { IntegrationSpec, IntegrationSpecRegistry } from "../spec.js";
+import "../index.js";
+
+//#region src/integrations/providers/twilio-sms.d.ts
+declare const twilioSmsIntegrationSpec: IntegrationSpec;
+declare function registerTwilioSmsIntegration(registry: IntegrationSpecRegistry): IntegrationSpecRegistry;
+//#endregion
+export { registerTwilioSmsIntegration, twilioSmsIntegrationSpec };