@contractspec/lib.contracts 1.44.0

package/dist/integrations/providers/impls/mistral-llm.js

@@ -0,0 +1,247 @@
+import { Mistral } from "@mistralai/mistralai";
+
+//#region src/integrations/providers/impls/mistral-llm.ts
+var MistralLLMProvider = class {
+	client;
+	defaultModel;
+	constructor(options) {
+		if (!options.apiKey) throw new Error("MistralLLMProvider requires an apiKey");
+		this.client = options.client ?? new Mistral({
+			apiKey: options.apiKey,
+			serverURL: options.serverURL,
+			userAgent: options.userAgentSuffix ? `${options.userAgentSuffix}` : void 0
+		});
+		this.defaultModel = options.defaultModel ?? "mistral-large-latest";
+	}
+	async chat(messages, options = {}) {
+		const request = this.buildChatRequest(messages, options);
+		const response = await this.client.chat.complete(request);
+		return this.buildLLMResponse(response);
+	}
+	async *stream(messages, options = {}) {
+		const request = this.buildChatRequest(messages, options);
+		request.stream = true;
+		const stream = await this.client.chat.stream(request);
+		const aggregatedParts = [];
+		const aggregatedToolCalls = [];
+		let usage;
+		let finishReason;
+		for await (const event of stream) {
+			for (const choice of event.data.choices) {
+				const delta = choice.delta;
+				if (typeof delta.content === "string") {
+					if (delta.content.length > 0) {
+						aggregatedParts.push({
+							type: "text",
+							text: delta.content
+						});
+						yield {
+							type: "message_delta",
+							delta: {
+								type: "text",
+								text: delta.content
+							},
+							index: choice.index
+						};
+					}
+				} else if (Array.isArray(delta.content)) {
+					for (const chunk of delta.content) if (chunk.type === "text" && "text" in chunk) {
+						aggregatedParts.push({
+							type: "text",
+							text: chunk.text
+						});
+						yield {
+							type: "message_delta",
+							delta: {
+								type: "text",
+								text: chunk.text
+							},
+							index: choice.index
+						};
+					}
+				}
+				if (delta.toolCalls) {
+					let localIndex = 0;
+					for (const call of delta.toolCalls) {
+						const toolCall = this.fromMistralToolCall(call, localIndex);
+						aggregatedToolCalls.push(toolCall);
+						yield {
+							type: "tool_call",
+							call: toolCall,
+							index: choice.index
+						};
+						localIndex += 1;
+					}
+				}
+				if (choice.finishReason && choice.finishReason !== "null") finishReason = choice.finishReason;
+			}
+			if (event.data.usage) {
+				const usageEntry = this.fromUsage(event.data.usage);
+				if (usageEntry) {
+					usage = usageEntry;
+					yield {
+						type: "usage",
+						usage: usageEntry
+					};
+				}
+			}
+		}
+		const message = {
+			role: "assistant",
+			content: aggregatedParts.length ? aggregatedParts : [{
+				type: "text",
+				text: ""
+			}]
+		};
+		if (aggregatedToolCalls.length > 0) message.content = [...aggregatedToolCalls, ...aggregatedParts.length ? aggregatedParts : []];
+		yield {
+			type: "end",
+			response: {
+				message,
+				usage,
+				finishReason: mapFinishReason(finishReason)
+			}
+		};
+	}
+	async countTokens(_messages) {
+		throw new Error("Mistral API does not currently support token counting");
+	}
+	buildChatRequest(messages, options) {
+		const request = {
+			model: options.model ?? this.defaultModel,
+			messages: messages.map((message) => this.toMistralMessage(message))
+		};
+		if (options.temperature != null) request.temperature = options.temperature;
+		if (options.topP != null) request.topP = options.topP;
+		if (options.maxOutputTokens != null) request.maxTokens = options.maxOutputTokens;
+		if (options.stopSequences?.length) request.stop = options.stopSequences.length === 1 ? options.stopSequences[0] : options.stopSequences;
+		if (options.tools?.length) request.tools = options.tools.map((tool) => ({
+			type: "function",
+			function: {
+				name: tool.name,
+				description: tool.description,
+				parameters: typeof tool.inputSchema === "object" && tool.inputSchema !== null ? tool.inputSchema : {}
+			}
+		}));
+		if (options.responseFormat === "json") request.responseFormat = { type: "json_object" };
+		return request;
+	}
+	buildLLMResponse(response) {
+		const firstChoice = response.choices[0];
+		if (!firstChoice) return {
+			message: {
+				role: "assistant",
+				content: [{
+					type: "text",
+					text: ""
+				}]
+			},
+			usage: this.fromUsage(response.usage),
+			raw: response
+		};
+		return {
+			message: this.fromAssistantMessage(firstChoice.message),
+			usage: this.fromUsage(response.usage),
+			finishReason: mapFinishReason(firstChoice.finishReason),
+			raw: response
+		};
+	}
+	fromUsage(usage) {
+		if (!usage) return void 0;
+		return {
+			promptTokens: usage.promptTokens ?? 0,
+			completionTokens: usage.completionTokens ?? 0,
+			totalTokens: usage.totalTokens ?? 0
+		};
+	}
+	fromAssistantMessage(message) {
+		const parts = [];
+		if (typeof message.content === "string") parts.push({
+			type: "text",
+			text: message.content
+		});
+		else if (Array.isArray(message.content)) message.content.forEach((chunk) => {
+			if (chunk.type === "text" && "text" in chunk) parts.push({
+				type: "text",
+				text: chunk.text
+			});
+		});
+		const toolCalls = message.toolCalls?.map((call, index) => this.fromMistralToolCall(call, index)) ?? [];
+		if (toolCalls.length > 0) parts.splice(0, 0, ...toolCalls);
+		if (parts.length === 0) parts.push({
+			type: "text",
+			text: ""
+		});
+		return {
+			role: "assistant",
+			content: parts
+		};
+	}
+	fromMistralToolCall(call, index) {
+		const args = typeof call.function.arguments === "string" ? call.function.arguments : JSON.stringify(call.function.arguments);
+		return {
+			type: "tool-call",
+			id: call.id ?? `tool-call-${index}`,
+			name: call.function.name,
+			arguments: args
+		};
+	}
+	toMistralMessage(message) {
+		const textContent = this.extractText(message.content);
+		const toolCalls = this.extractToolCalls(message);
+		switch (message.role) {
+			case "system": return {
+				role: "system",
+				content: textContent ?? ""
+			};
+			case "user": return {
+				role: "user",
+				content: textContent ?? ""
+			};
+			case "assistant": return {
+				role: "assistant",
+				content: toolCalls.length > 0 ? null : textContent ?? "",
+				toolCalls: toolCalls.length > 0 ? toolCalls : void 0
+			};
+			case "tool": return {
+				role: "tool",
+				content: textContent ?? "",
+				toolCallId: message.toolCallId ?? toolCalls[0]?.id
+			};
+			default: return {
+				role: "user",
+				content: textContent ?? ""
+			};
+		}
+	}
+	extractText(parts) {
+		const textParts = parts.filter((part) => part.type === "text").map((part) => part.text);
+		if (textParts.length === 0) return null;
+		return textParts.join("");
+	}
+	extractToolCalls(message) {
+		return message.content.filter((part) => part.type === "tool-call").map((call, index) => ({
+			id: call.id ?? `call_${index}`,
+			type: "function",
+			index,
+			function: {
+				name: call.name,
+				arguments: call.arguments
+			}
+		}));
+	}
+};
+function mapFinishReason(reason) {
+	if (!reason) return void 0;
+	switch (reason.toLowerCase()) {
+		case "stop": return "stop";
+		case "length": return "length";
+		case "tool_call":
+		case "tool_calls": return "tool_call";
+		case "content_filter": return "content_filter";
+		default: return;
+	}
+}
+
+//#endregion
+export { MistralLLMProvider };

package/dist/integrations/providers/impls/postmark-email.d.ts

@@ -0,0 +1,19 @@
+import { EmailOutboundMessage, EmailOutboundProvider, EmailOutboundResult } from "../email.js";
+import { ServerClient } from "postmark";
+
+//#region src/integrations/providers/impls/postmark-email.d.ts
+interface PostmarkEmailProviderOptions {
+  serverToken: string;
+  defaultFromEmail?: string;
+  messageStream?: string;
+  client?: ServerClient;
+}
+declare class PostmarkEmailProvider implements EmailOutboundProvider {
+  private readonly client;
+  private readonly defaultFromEmail?;
+  private readonly messageStream?;
+  constructor(options: PostmarkEmailProviderOptions);
+  sendEmail(message: EmailOutboundMessage): Promise<EmailOutboundResult>;
+}
+//#endregion
+export { PostmarkEmailProvider, PostmarkEmailProviderOptions };

package/dist/integrations/providers/impls/postmark-email.js

@@ -0,0 +1,55 @@
+import { ServerClient } from "postmark";
+
+//#region src/integrations/providers/impls/postmark-email.ts
+var PostmarkEmailProvider = class {
+	client;
+	defaultFromEmail;
+	messageStream;
+	constructor(options) {
+		this.client = options.client ?? new ServerClient(options.serverToken, { useHttps: true });
+		this.defaultFromEmail = options.defaultFromEmail;
+		this.messageStream = options.messageStream;
+	}
+	async sendEmail(message) {
+		const request = {
+			From: formatAddress(message.from) ?? this.defaultFromEmail,
+			To: message.to.map((addr) => formatAddress(addr)).join(", "),
+			Cc: message.cc?.map((addr) => formatAddress(addr)).join(", ") || void 0,
+			Bcc: message.bcc?.map((addr) => formatAddress(addr)).join(", ") || void 0,
+			ReplyTo: message.replyTo ? formatAddress(message.replyTo) : void 0,
+			Subject: message.subject,
+			TextBody: message.textBody,
+			HtmlBody: message.htmlBody,
+			Headers: message.headers ? Object.entries(message.headers).map(([name, value]) => ({
+				Name: name,
+				Value: value
+			})) : void 0,
+			MessageStream: this.messageStream,
+			Attachments: buildAttachments(message)
+		};
+		const response = await this.client.sendEmail(request);
+		return {
+			id: response.MessageID,
+			providerMessageId: response.MessageID,
+			queuedAt: new Date(response.SubmittedAt ?? (/* @__PURE__ */ new Date()).toISOString())
+		};
+	}
+};
+function formatAddress(address) {
+	if (address.name) return `"${address.name}" <${address.email}>`;
+	return address.email;
+}
+function buildAttachments(message) {
+	if (!message.attachments?.length) return void 0;
+	return message.attachments.filter((attachment) => attachment.data).map((attachment) => ({
+		Name: attachment.filename,
+		Content: Buffer.from(attachment.data ?? new Uint8Array()).toString("base64"),
+		ContentType: attachment.contentType,
+		ContentID: null,
+		ContentLength: attachment.sizeBytes,
+		Disposition: "attachment"
+	}));
+}
+
+//#endregion
+export { PostmarkEmailProvider };

package/dist/integrations/providers/impls/powens-client.d.ts

@@ -0,0 +1,124 @@
+//#region src/integrations/providers/impls/powens-client.d.ts
+type PowensEnvironment = 'sandbox' | 'production';
+interface PowensClientOptions {
+  clientId: string;
+  clientSecret: string;
+  apiKey?: string;
+  environment: PowensEnvironment;
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  defaultTimeoutMs?: number;
+  logger?: {
+    debug?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+  };
+}
+interface PowensAccount {
+  uuid: string;
+  reference: string;
+  userUuid: string;
+  institution: {
+    id: string;
+    name: string;
+    logoUrl?: string;
+  };
+  name: string;
+  iban?: string;
+  bic?: string;
+  currency?: string;
+  balance?: number;
+  availableBalance?: number;
+  type?: string;
+  status?: string;
+  metadata?: Record<string, unknown>;
+}
+interface PowensAccountListResponse {
+  accounts: PowensAccount[];
+  pagination?: {
+    nextCursor?: string;
+    hasMore?: boolean;
+  };
+}
+interface PowensTransaction {
+  uuid: string;
+  accountUuid: string;
+  amount: number;
+  currency: string;
+  direction: 'credit' | 'debit';
+  description?: string;
+  category?: string;
+  rawLabel?: string;
+  bookingDate?: string;
+  valueDate?: string;
+  status?: string;
+  merchantName?: string;
+  merchantCategoryCode?: string;
+  counterpartyName?: string;
+  counterpartyAccount?: string;
+  metadata?: Record<string, unknown>;
+}
+interface PowensTransactionListResponse {
+  transactions: PowensTransaction[];
+  pagination?: {
+    nextCursor?: string;
+    hasMore?: boolean;
+  };
+}
+interface PowensBalance {
+  accountUuid: string;
+  type: string;
+  amount: number;
+  currency: string;
+  updatedAt: string;
+  metadata?: Record<string, unknown>;
+}
+interface PowensConnectionStatusResponse {
+  connectionUuid: string;
+  status: 'healthy' | 'error' | 'revoked' | 'pending';
+  lastAttemptAt?: string;
+  errorCode?: string;
+  errorMessage?: string;
+  metadata?: Record<string, unknown>;
+}
+declare class PowensClientError extends Error {
+  readonly status: number;
+  readonly code?: string;
+  readonly requestId?: string;
+  readonly response?: unknown;
+  constructor(message: string, status: number, code?: string, requestId?: string, response?: unknown);
+}
+declare class PowensClient {
+  private readonly clientId;
+  private readonly clientSecret;
+  private readonly apiKey?;
+  private readonly fetchImpl;
+  private readonly logger?;
+  private readonly defaultTimeoutMs;
+  private token?;
+  private readonly baseUrl;
+  constructor(options: PowensClientOptions);
+  listAccounts(params: {
+    userUuid: string;
+    cursor?: string;
+    limit?: number;
+    includeBalances?: boolean;
+    institutionUuid?: string;
+  }): Promise<PowensAccountListResponse>;
+  getAccount(accountUuid: string): Promise<PowensAccount>;
+  listTransactions(params: {
+    accountUuid: string;
+    cursor?: string;
+    limit?: number;
+    from?: string;
+    to?: string;
+    includePending?: boolean;
+  }): Promise<PowensTransactionListResponse>;
+  getBalances(accountUuid: string): Promise<PowensBalance[]>;
+  getConnectionStatus(connectionUuid: string): Promise<PowensConnectionStatusResponse>;
+  private request;
+  private ensureAccessToken;
+  private fetchAccessToken;
+}
+//#endregion
+export { PowensAccount, PowensAccountListResponse, PowensBalance, PowensClient, PowensClientError, PowensClientOptions, PowensConnectionStatusResponse, PowensEnvironment, PowensTransaction, PowensTransactionListResponse };

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

@@ -0,0 +1,171 @@
+import { URL } from "node:url";
+
+//#region src/integrations/providers/impls/powens-client.ts
+const POWENS_BASE_URL = {
+	sandbox: "https://api-sandbox.powens.com/v2",
+	production: "https://api.powens.com/v2"
+};
+var PowensClientError = class extends Error {
+	status;
+	code;
+	requestId;
+	response;
+	constructor(message, status, code, requestId, response) {
+		super(message);
+		this.name = "PowensClientError";
+		this.status = status;
+		this.code = code;
+		this.requestId = requestId;
+		this.response = response;
+	}
+};
+var PowensClient = class {
+	clientId;
+	clientSecret;
+	apiKey;
+	fetchImpl;
+	logger;
+	defaultTimeoutMs;
+	token;
+	baseUrl;
+	constructor(options) {
+		this.clientId = options.clientId;
+		this.clientSecret = options.clientSecret;
+		this.apiKey = options.apiKey;
+		this.fetchImpl = options.fetchImpl ?? fetch;
+		this.logger = options.logger;
+		this.defaultTimeoutMs = options.defaultTimeoutMs ?? 15e3;
+		this.baseUrl = options.baseUrl ?? POWENS_BASE_URL[options.environment] ?? POWENS_BASE_URL.production;
+	}
+	async listAccounts(params) {
+		const searchParams = {
+			cursor: params.cursor,
+			limit: params.limit,
+			include_balances: params.includeBalances,
+			institution_uuid: params.institutionUuid
+		};
+		return await this.request({
+			method: "GET",
+			path: `/users/${encodeURIComponent(params.userUuid)}/accounts`,
+			searchParams
+		});
+	}
+	async getAccount(accountUuid) {
+		return this.request({
+			method: "GET",
+			path: `/accounts/${encodeURIComponent(accountUuid)}`
+		});
+	}
+	async listTransactions(params) {
+		const searchParams = {
+			cursor: params.cursor,
+			limit: params.limit,
+			from: params.from,
+			to: params.to,
+			include_pending: params.includePending
+		};
+		return this.request({
+			method: "GET",
+			path: `/accounts/${encodeURIComponent(params.accountUuid)}/transactions`,
+			searchParams
+		});
+	}
+	async getBalances(accountUuid) {
+		return this.request({
+			method: "GET",
+			path: `/accounts/${encodeURIComponent(accountUuid)}/balances`
+		});
+	}
+	async getConnectionStatus(connectionUuid) {
+		return this.request({
+			method: "GET",
+			path: `/connections/${encodeURIComponent(connectionUuid)}`
+		});
+	}
+	async request(options) {
+		const url = new URL(options.path, this.baseUrl);
+		if (options.searchParams) for (const [key, value] of Object.entries(options.searchParams)) {
+			if (value === void 0 || value === null) continue;
+			url.searchParams.set(key, String(value));
+		}
+		const headers = {
+			Accept: "application/json",
+			"Content-Type": "application/json",
+			...options.headers
+		};
+		if (this.apiKey) headers["x-api-key"] = this.apiKey;
+		if (!options.skipAuth) headers.Authorization = `Bearer ${await this.ensureAccessToken()}`;
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? this.defaultTimeoutMs);
+		try {
+			const response = await this.fetchImpl(url, {
+				method: options.method,
+				headers,
+				body: options.body ? JSON.stringify(options.body) : void 0,
+				signal: controller.signal
+			});
+			const requestId = response.headers.get("x-request-id") ?? void 0;
+			if (!response.ok) {
+				let errorBody;
+				try {
+					errorBody = await response.json();
+				} catch {}
+				const errorObject = typeof errorBody === "object" && errorBody !== null ? errorBody : void 0;
+				const message = typeof errorObject?.message === "string" ? errorObject.message : `Powens API request failed with status ${response.status}`;
+				const code = typeof errorObject?.code === "string" ? errorObject.code : void 0;
+				throw new PowensClientError(message, response.status, code, requestId, errorBody);
+			}
+			if (response.status === 204) return;
+			try {
+				return await response.json();
+			} catch (error) {
+				this.logger?.error?.("[PowensClient] Failed to parse JSON response", error);
+				throw new PowensClientError("Failed to parse Powens response payload as JSON", response.status, void 0, requestId);
+			}
+		} catch (error) {
+			if (error instanceof PowensClientError) throw error;
+			if (error.name === "AbortError") throw new PowensClientError(`Powens API request timed out after ${options.timeoutMs ?? this.defaultTimeoutMs}ms`, 408);
+			this.logger?.error?.("[PowensClient] Request failed", error);
+			throw new PowensClientError(error.message ?? "Powens API request failed", 500);
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+	async ensureAccessToken() {
+		if (this.token && Date.now() < this.token.expiresAt - 5e3) return this.token.accessToken;
+		this.token = await this.fetchAccessToken();
+		return this.token.accessToken;
+	}
+	async fetchAccessToken() {
+		const url = new URL("/oauth/token", this.baseUrl);
+		const basicAuth = Buffer.from(`${this.clientId}:${this.clientSecret}`, "utf-8").toString("base64");
+		const response = await this.fetchImpl(url, {
+			method: "POST",
+			headers: {
+				Authorization: `Basic ${basicAuth}`,
+				"Content-Type": "application/x-www-form-urlencoded",
+				Accept: "application/json"
+			},
+			body: new URLSearchParams({ grant_type: "client_credentials" }).toString()
+		});
+		if (!response.ok) {
+			let errorBody;
+			try {
+				errorBody = await response.json();
+			} catch {}
+			const errorObject = typeof errorBody === "object" && errorBody !== null ? errorBody : void 0;
+			throw new PowensClientError(typeof errorObject?.error_description === "string" ? errorObject.error_description : "Failed to obtain Powens access token", response.status, void 0, void 0, errorBody);
+		}
+		const payload = await response.json();
+		const expiresAt = Date.now() + payload.expires_in * 1e3;
+		this.logger?.debug?.("[PowensClient] Received access token", { expiresIn: payload.expires_in });
+		return {
+			accessToken: payload.access_token,
+			expiresAt,
+			scope: payload.scope
+		};
+	}
+};
+
+//#endregion
+export { PowensClient, PowensClientError };

package/dist/integrations/providers/impls/powens-openbanking.d.ts

@@ -0,0 +1,27 @@
+import { OpenBankingAccountBalance, OpenBankingAccountDetails, OpenBankingConnectionStatus, OpenBankingGetAccountDetailsParams, OpenBankingGetBalancesParams, OpenBankingGetConnectionStatusParams, OpenBankingListAccountsParams, OpenBankingListAccountsResult, OpenBankingListTransactionsParams, OpenBankingListTransactionsResult, OpenBankingProvider } from "../openbanking.js";
+import { PowensClientOptions } from "./powens-client.js";
+
+//#region src/integrations/providers/impls/powens-openbanking.d.ts
+type PowensOpenBankingProviderOptions = PowensClientOptions;
+declare class PowensOpenBankingProvider implements OpenBankingProvider {
+  private readonly client;
+  private readonly logger?;
+  constructor(options: PowensOpenBankingProviderOptions);
+  listAccounts(params: OpenBankingListAccountsParams): Promise<OpenBankingListAccountsResult>;
+  getAccountDetails(params: OpenBankingGetAccountDetailsParams): Promise<OpenBankingAccountDetails>;
+  listTransactions(params: OpenBankingListTransactionsParams): Promise<OpenBankingListTransactionsResult>;
+  getBalances(params: OpenBankingGetBalancesParams): Promise<OpenBankingAccountBalance[]>;
+  getConnectionStatus(params: OpenBankingGetConnectionStatusParams): Promise<OpenBankingConnectionStatus>;
+  private mapAccount;
+  private mapAccountDetails;
+  private mapTransaction;
+  private mapBalance;
+  private toContext;
+  private mapOwnership;
+  private mapAccountStatus;
+  private mapTransactionStatus;
+  private mapConnectionStatus;
+  private handleError;
+}
+//#endregion
+export { PowensOpenBankingProvider, PowensOpenBankingProviderOptions };