@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/dist/integrations/providers/impls/powens-openbanking.js

@@ -0,0 +1,218 @@
+import { PowensClient, PowensClientError } from "./powens-client.js";
+
+//#region src/integrations/providers/impls/powens-openbanking.ts
+var PowensOpenBankingProvider = class {
+	client;
+	logger;
+	constructor(options) {
+		this.client = new PowensClient(options);
+		this.logger = options.logger;
+	}
+	async listAccounts(params) {
+		if (!params.userId) throw new PowensClientError("Powens account listing requires the upstream userId mapped to Powens user UUID.", 400);
+		const context = this.toContext(params.tenantId, params.connectionId);
+		try {
+			const response = await this.client.listAccounts({
+				userUuid: params.userId,
+				cursor: params.cursor,
+				limit: params.pageSize,
+				includeBalances: params.includeBalances,
+				institutionUuid: params.institutionId
+			});
+			return {
+				accounts: response.accounts.map((account) => this.mapAccount(account, context)),
+				nextCursor: response.pagination?.nextCursor,
+				hasMore: response.pagination?.hasMore
+			};
+		} catch (error) {
+			this.handleError("listAccounts", error);
+		}
+	}
+	async getAccountDetails(params) {
+		const context = this.toContext(params.tenantId, params.connectionId);
+		try {
+			const account = await this.client.getAccount(params.accountId);
+			return this.mapAccountDetails(account, context);
+		} catch (error) {
+			this.handleError("getAccountDetails", error);
+		}
+	}
+	async listTransactions(params) {
+		const context = this.toContext(params.tenantId, params.connectionId);
+		try {
+			const response = await this.client.listTransactions({
+				accountUuid: params.accountId,
+				cursor: params.cursor,
+				limit: params.pageSize,
+				from: params.from,
+				to: params.to,
+				includePending: params.includePending
+			});
+			return {
+				transactions: response.transactions.map((transaction) => this.mapTransaction(transaction, context)),
+				nextCursor: response.pagination?.nextCursor,
+				hasMore: response.pagination?.hasMore
+			};
+		} catch (error) {
+			this.handleError("listTransactions", error);
+		}
+	}
+	async getBalances(params) {
+		const context = this.toContext(params.tenantId, params.connectionId);
+		try {
+			return (await this.client.getBalances(params.accountId)).filter((balance) => params.balanceTypes?.length ? params.balanceTypes.includes(balance.type) : true).map((balance) => this.mapBalance(balance, context));
+		} catch (error) {
+			this.handleError("getBalances", error);
+		}
+	}
+	async getConnectionStatus(params) {
+		try {
+			const status = await this.client.getConnectionStatus(params.connectionId);
+			return {
+				connectionId: params.connectionId,
+				tenantId: params.tenantId,
+				status: this.mapConnectionStatus(status.status),
+				lastCheckedAt: status.lastAttemptAt,
+				errorCode: status.errorCode,
+				errorMessage: status.errorMessage,
+				details: status.metadata
+			};
+		} catch (error) {
+			this.handleError("getConnectionStatus", error);
+		}
+	}
+	mapAccount(account, context) {
+		return {
+			id: account.uuid,
+			externalId: account.reference ?? account.uuid,
+			tenantId: context.tenantId,
+			connectionId: context.connectionId,
+			userId: account.userUuid,
+			displayName: account.name,
+			institutionId: account.institution.id,
+			institutionName: account.institution.name,
+			institutionLogoUrl: account.institution.logoUrl,
+			accountType: account.type ?? "unknown",
+			iban: account.iban,
+			bic: account.bic,
+			currency: account.currency ?? "EUR",
+			accountNumberMasked: account.metadata?.account_number_masked,
+			ownership: this.mapOwnership(account.metadata?.ownership),
+			status: this.mapAccountStatus(account.status),
+			lastSyncedAt: account.metadata?.last_sync_at,
+			metadata: account.metadata
+		};
+	}
+	mapAccountDetails(account, context) {
+		return {
+			...this.mapAccount(account, context),
+			productCode: account.metadata?.product_code,
+			openedAt: account.metadata?.opened_at,
+			closedAt: account.metadata?.closed_at,
+			availableBalance: account.availableBalance ?? void 0,
+			currentBalance: account.balance ?? void 0,
+			creditLimit: account.metadata?.credit_limit,
+			customFields: account.metadata
+		};
+	}
+	mapTransaction(transaction, context) {
+		return {
+			id: transaction.uuid,
+			externalId: transaction.uuid,
+			tenantId: context.tenantId,
+			accountId: transaction.accountUuid,
+			connectionId: context.connectionId,
+			amount: transaction.amount,
+			currency: transaction.currency,
+			direction: transaction.direction === "credit" ? "credit" : "debit",
+			description: transaction.description ?? transaction.rawLabel,
+			bookingDate: transaction.bookingDate,
+			valueDate: transaction.valueDate,
+			postedAt: transaction.bookingDate,
+			category: transaction.category,
+			rawCategory: transaction.rawLabel,
+			merchantName: transaction.merchantName,
+			merchantCategoryCode: transaction.merchantCategoryCode,
+			counterpartyName: transaction.counterpartyName,
+			counterpartyAccount: transaction.counterpartyAccount,
+			reference: transaction.metadata?.reference,
+			status: this.mapTransactionStatus(transaction.status),
+			metadata: transaction.metadata
+		};
+	}
+	mapBalance(balance, context) {
+		return {
+			accountId: balance.accountUuid,
+			connectionId: context.connectionId,
+			tenantId: context.tenantId,
+			type: balance.type ?? "current",
+			currency: balance.currency ?? "EUR",
+			amount: balance.amount,
+			lastUpdatedAt: balance.updatedAt,
+			metadata: balance.metadata
+		};
+	}
+	toContext(tenantId, connectionId) {
+		return {
+			tenantId,
+			connectionId
+		};
+	}
+	mapOwnership(value) {
+		switch (value?.toLowerCase()) {
+			case "individual":
+			case "personal": return "individual";
+			case "joint": return "joint";
+			case "business":
+			case "corporate": return "business";
+			default: return "unknown";
+		}
+	}
+	mapAccountStatus(status) {
+		switch (status?.toLowerCase()) {
+			case "active":
+			case "enabled": return "active";
+			case "disabled":
+			case "inactive": return "inactive";
+			case "closed": return "closed";
+			case "suspended": return "suspended";
+			default: return "active";
+		}
+	}
+	mapTransactionStatus(status) {
+		switch (status?.toLowerCase()) {
+			case "pending":
+			case "authorised": return "pending";
+			case "booked":
+			case "posted": return "booked";
+			case "cancelled":
+			case "rejected": return "cancelled";
+			default: return "booked";
+		}
+	}
+	mapConnectionStatus(status) {
+		switch (status) {
+			case "healthy": return "healthy";
+			case "pending": return "degraded";
+			case "error": return "error";
+			case "revoked": return "disconnected";
+			default: return "degraded";
+		}
+	}
+	handleError(operation, error) {
+		if (error instanceof PowensClientError) {
+			this.logger?.error?.(`[PowensOpenBankingProvider] ${operation} failed`, {
+				status: error.status,
+				code: error.code,
+				requestId: error.requestId,
+				message: error.message
+			});
+			throw error;
+		}
+		this.logger?.error?.(`[PowensOpenBankingProvider] ${operation} failed with unexpected error`, error);
+		throw error instanceof Error ? error : /* @__PURE__ */ new Error(`Powens operation "${operation}" failed`);
+	}
+};
+
+//#endregion
+export { PowensOpenBankingProvider };

package/dist/integrations/providers/impls/provider-factory.d.ts

@@ -0,0 +1,26 @@
+import { PaymentsProvider } from "../payments.js";
+import { LLMProvider } from "../llm.js";
+import { EmbeddingProvider } from "../embedding.js";
+import { VectorStoreProvider } from "../vector-store.js";
+import { EmailOutboundProvider } from "../email.js";
+import { SmsProvider } from "../sms.js";
+import { VoiceProvider } from "../voice.js";
+import { ObjectStorageProvider } from "../storage.js";
+import { OpenBankingProvider } from "../openbanking.js";
+import { IntegrationContext } from "../../runtime.js";
+
+//#region src/integrations/providers/impls/provider-factory.d.ts
+declare class IntegrationProviderFactory {
+  createPaymentsProvider(context: IntegrationContext): Promise<PaymentsProvider>;
+  createEmailOutboundProvider(context: IntegrationContext): Promise<EmailOutboundProvider>;
+  createSmsProvider(context: IntegrationContext): Promise<SmsProvider>;
+  createVectorStoreProvider(context: IntegrationContext): Promise<VectorStoreProvider>;
+  createObjectStorageProvider(context: IntegrationContext): Promise<ObjectStorageProvider>;
+  createVoiceProvider(context: IntegrationContext): Promise<VoiceProvider>;
+  createLlmProvider(context: IntegrationContext): Promise<LLMProvider>;
+  createEmbeddingProvider(context: IntegrationContext): Promise<EmbeddingProvider>;
+  createOpenBankingProvider(context: IntegrationContext): Promise<OpenBankingProvider>;
+  private loadSecrets;
+}
+//#endregion
+export { IntegrationProviderFactory };

package/dist/integrations/providers/impls/provider-factory.js

@@ -0,0 +1,146 @@
+import { ElevenLabsVoiceProvider } from "./elevenlabs-voice.js";
+import { GoogleCloudStorageProvider } from "./gcs-storage.js";
+import { MistralLLMProvider } from "./mistral-llm.js";
+import { MistralEmbeddingProvider } from "./mistral-embedding.js";
+import { QdrantVectorProvider } from "./qdrant-vector.js";
+import { StripePaymentsProvider } from "./stripe-payments.js";
+import { PostmarkEmailProvider } from "./postmark-email.js";
+import { TwilioSmsProvider } from "./twilio-sms.js";
+import { PowensOpenBankingProvider } from "./powens-openbanking.js";
+import { Buffer } from "node:buffer";
+
+//#region src/integrations/providers/impls/provider-factory.ts
+const SECRET_CACHE = /* @__PURE__ */ new Map();
+var IntegrationProviderFactory = class {
+	async createPaymentsProvider(context) {
+		const secrets = await this.loadSecrets(context);
+		switch (context.spec.meta.key) {
+			case "payments.stripe": return new StripePaymentsProvider({ apiKey: requireSecret(secrets, "apiKey", "Stripe API key is required") });
+			default: throw new Error(`Unsupported payments integration: ${context.spec.meta.key}`);
+		}
+	}
+	async createEmailOutboundProvider(context) {
+		const secrets = await this.loadSecrets(context);
+		switch (context.spec.meta.key) {
+			case "email.postmark": return new PostmarkEmailProvider({
+				serverToken: requireSecret(secrets, "serverToken", "Postmark server token is required"),
+				defaultFromEmail: context.config.fromEmail,
+				messageStream: context.config.messageStream
+			});
+			default: throw new Error(`Unsupported email integration: ${context.spec.meta.key}`);
+		}
+	}
+	async createSmsProvider(context) {
+		const secrets = await this.loadSecrets(context);
+		switch (context.spec.meta.key) {
+			case "sms.twilio": return new TwilioSmsProvider({
+				accountSid: requireSecret(secrets, "accountSid", "Twilio account SID is required"),
+				authToken: requireSecret(secrets, "authToken", "Twilio auth token is required"),
+				fromNumber: context.config.fromNumber
+			});
+			default: throw new Error(`Unsupported SMS integration: ${context.spec.meta.key}`);
+		}
+	}
+	async createVectorStoreProvider(context) {
+		const secrets = await this.loadSecrets(context);
+		switch (context.spec.meta.key) {
+			case "vectordb.qdrant": return new QdrantVectorProvider({
+				url: requireConfig(context, "apiUrl", "Qdrant apiUrl config is required"),
+				apiKey: secrets.apiKey,
+				clientParams: context.config
+			});
+			default: throw new Error(`Unsupported vector store integration: ${context.spec.meta.key}`);
+		}
+	}
+	async createObjectStorageProvider(context) {
+		const secrets = await this.loadSecrets(context);
+		switch (context.spec.meta.key) {
+			case "storage.s3":
+			case "storage.gcs": return new GoogleCloudStorageProvider({
+				bucket: requireConfig(context, "bucket", "Storage bucket is required"),
+				clientOptions: secrets.type === "service_account" ? { credentials: secrets } : void 0
+			});
+			default: throw new Error(`Unsupported storage integration: ${context.spec.meta.key}`);
+		}
+	}
+	async createVoiceProvider(context) {
+		const secrets = await this.loadSecrets(context);
+		switch (context.spec.meta.key) {
+			case "ai-voice.elevenlabs": return new ElevenLabsVoiceProvider({
+				apiKey: requireSecret(secrets, "apiKey", "ElevenLabs API key is required"),
+				defaultVoiceId: context.config.defaultVoiceId
+			});
+			default: throw new Error(`Unsupported voice integration: ${context.spec.meta.key}`);
+		}
+	}
+	async createLlmProvider(context) {
+		const secrets = await this.loadSecrets(context);
+		switch (context.spec.meta.key) {
+			case "ai-llm.mistral": return new MistralLLMProvider({
+				apiKey: requireSecret(secrets, "apiKey", "Mistral API key is required"),
+				defaultModel: context.config.model
+			});
+			default: throw new Error(`Unsupported LLM integration: ${context.spec.meta.key}`);
+		}
+	}
+	async createEmbeddingProvider(context) {
+		const secrets = await this.loadSecrets(context);
+		switch (context.spec.meta.key) {
+			case "ai-llm.mistral": return new MistralEmbeddingProvider({
+				apiKey: requireSecret(secrets, "apiKey", "Mistral API key is required"),
+				defaultModel: context.config.embeddingModel
+			});
+			default: throw new Error(`Unsupported embeddings integration: ${context.spec.meta.key}`);
+		}
+	}
+	async createOpenBankingProvider(context) {
+		const secrets = await this.loadSecrets(context);
+		const config = context.config;
+		switch (context.spec.meta.key) {
+			case "openbanking.powens": {
+				const environmentValue = requireConfig(context, "environment", "Powens environment (sandbox | production) must be specified in integration config.");
+				if (environmentValue !== "sandbox" && environmentValue !== "production") throw new Error(`Powens environment "${environmentValue}" is invalid. Expected "sandbox" or "production".`);
+				return new PowensOpenBankingProvider({
+					clientId: requireSecret(secrets, "clientId", "Powens clientId is required"),
+					clientSecret: requireSecret(secrets, "clientSecret", "Powens clientSecret is required"),
+					apiKey: secrets.apiKey,
+					environment: environmentValue,
+					baseUrl: config?.baseUrl
+				});
+			}
+			default: throw new Error(`Unsupported open banking integration: ${context.spec.meta.key}`);
+		}
+	}
+	async loadSecrets(context) {
+		const cacheKey = context.connection.meta.id;
+		if (SECRET_CACHE.has(cacheKey)) {
+			const cached = SECRET_CACHE.get(cacheKey);
+			if (cached) return cached;
+		}
+		const value = parseSecret(await context.secretProvider.getSecret(context.secretReference));
+		SECRET_CACHE.set(cacheKey, value);
+		return value;
+	}
+};
+function parseSecret(secret) {
+	const text = Buffer.from(secret.data).toString("utf-8").trim();
+	if (!text) return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		return { apiKey: text };
+	}
+}
+function requireSecret(secrets, key, message) {
+	const value = secrets[key];
+	if (value == null || value === "") throw new Error(message);
+	return value;
+}
+function requireConfig(context, key, message) {
+	const value = context.config?.[key];
+	if (value == null) throw new Error(message);
+	return value;
+}
+
+//#endregion
+export { IntegrationProviderFactory };

package/dist/integrations/providers/impls/qdrant-vector.d.ts

@@ -0,0 +1,24 @@
+import { VectorDeleteRequest, VectorSearchQuery, VectorSearchResult, VectorStoreProvider, VectorUpsertRequest } from "../vector-store.js";
+import { QdrantClient, QdrantClientParams } from "@qdrant/js-client-rest";
+
+//#region src/integrations/providers/impls/qdrant-vector.d.ts
+interface QdrantVectorProviderOptions {
+  url: string;
+  apiKey?: string;
+  client?: QdrantClient;
+  createCollectionIfMissing?: boolean;
+  distance?: 'Cosine' | 'Euclid' | 'Dot' | 'Manhattan';
+  clientParams?: Omit<QdrantClientParams, 'url' | 'apiKey'>;
+}
+declare class QdrantVectorProvider implements VectorStoreProvider {
+  private readonly client;
+  private readonly createCollectionIfMissing;
+  private readonly distance;
+  constructor(options: QdrantVectorProviderOptions);
+  upsert(request: VectorUpsertRequest): Promise<void>;
+  search(query: VectorSearchQuery): Promise<VectorSearchResult[]>;
+  delete(request: VectorDeleteRequest): Promise<void>;
+  private ensureCollection;
+}
+//#endregion
+export { QdrantVectorProvider, QdrantVectorProviderOptions };

package/dist/integrations/providers/impls/qdrant-vector.js

@@ -0,0 +1,69 @@
+import { QdrantClient } from "@qdrant/js-client-rest";
+
+//#region src/integrations/providers/impls/qdrant-vector.ts
+var QdrantVectorProvider = class {
+	client;
+	createCollectionIfMissing;
+	distance;
+	constructor(options) {
+		this.client = options.client ?? new QdrantClient({
+			url: options.url,
+			apiKey: options.apiKey,
+			...options.clientParams
+		});
+		this.createCollectionIfMissing = options.createCollectionIfMissing ?? true;
+		this.distance = options.distance ?? "Cosine";
+	}
+	async upsert(request) {
+		if (request.documents.length === 0) return;
+		const vectorSize = request.documents[0]?.vector.length ?? 0;
+		if (this.createCollectionIfMissing) await this.ensureCollection(request.collection, vectorSize);
+		const points = request.documents.map((document) => ({
+			id: document.id,
+			vector: document.vector,
+			payload: {
+				...document.payload,
+				...document.namespace ? { namespace: document.namespace } : {},
+				...document.expiresAt ? { expiresAt: document.expiresAt.toISOString() } : {}
+			}
+		}));
+		await this.client.upsert(request.collection, {
+			wait: true,
+			points
+		});
+	}
+	async search(query) {
+		return (await this.client.search(query.collection, {
+			vector: query.vector,
+			limit: query.topK,
+			filter: query.filter,
+			score_threshold: query.scoreThreshold,
+			with_payload: true,
+			with_vector: false
+		})).map((item) => ({
+			id: String(item.id),
+			score: item.score,
+			payload: item.payload ?? void 0,
+			namespace: typeof item.payload === "object" && item.payload !== null ? item.payload.namespace : void 0
+		}));
+	}
+	async delete(request) {
+		await this.client.delete(request.collection, {
+			wait: true,
+			points: request.ids
+		});
+	}
+	async ensureCollection(collectionName, vectorSize) {
+		try {
+			await this.client.getCollection(collectionName);
+		} catch {
+			await this.client.createCollection(collectionName, { vectors: {
+				size: vectorSize,
+				distance: this.distance
+			} });
+		}
+	}
+};
+
+//#endregion
+export { QdrantVectorProvider };

package/dist/integrations/providers/impls/stripe-payments.d.ts

@@ -0,0 +1,28 @@
+import { CapturePaymentInput, CreateCustomerInput, CreatePaymentIntentInput, ListInvoicesQuery, ListTransactionsQuery, PaymentCustomer, PaymentIntent, PaymentInvoice, PaymentRefund, PaymentTransaction, PaymentsProvider, RefundPaymentInput } from "../payments.js";
+import Stripe from "stripe";
+
+//#region src/integrations/providers/impls/stripe-payments.d.ts
+interface StripePaymentsProviderOptions {
+  apiKey: string;
+  stripe?: Stripe;
+}
+declare class StripePaymentsProvider implements PaymentsProvider {
+  private readonly stripe;
+  constructor(options: StripePaymentsProviderOptions);
+  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[]>;
+  private toCustomer;
+  private toPaymentIntent;
+  private toInvoice;
+  private toMoney;
+  private toMetadata;
+  private mergeMetadata;
+}
+//#endregion
+export { StripePaymentsProvider, StripePaymentsProviderOptions };