@contractspec/lib.contracts 0.0.0-canary-20260113162409

package/dist/integrations/openbanking/contracts/balances.js

@@ -0,0 +1,166 @@
+import { defineCommand, defineQuery } from "../../../operations/operation.js";
+import "../../../operations/index.js";
+import { AccountBalanceRecord } from "../models.js";
+import { OPENBANKING_TELEMETRY_EVENTS } from "../telemetry.js";
+import { ScalarTypeEnum, SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/integrations/openbanking/contracts/balances.ts
+const OpenBankingGetBalancesInput = new SchemaModel({
+	name: "OpenBankingGetBalancesInput",
+	description: "Parameters for retrieving bank account balances from the canonical ledger.",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		accountId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		balanceTypes: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isArray: true,
+			isOptional: true
+		}
+	}
+});
+const OpenBankingGetBalancesOutput = new SchemaModel({
+	name: "OpenBankingGetBalancesOutput",
+	description: "Canonical balances for a bank account.",
+	fields: {
+		balances: {
+			type: AccountBalanceRecord,
+			isOptional: false,
+			isArray: true
+		},
+		asOf: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		}
+	}
+});
+const OpenBankingRefreshBalancesInput = new SchemaModel({
+	name: "OpenBankingRefreshBalancesInput",
+	description: "Command payload to refresh balances for a bank account via the open banking provider.",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		accountId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		connectionId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: true
+		},
+		balanceTypes: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isArray: true,
+			isOptional: true
+		},
+		forceRefresh: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		}
+	}
+});
+const OpenBankingRefreshBalancesOutput = new SchemaModel({
+	name: "OpenBankingRefreshBalancesOutput",
+	description: "Result of a balance refresh against the open banking provider.",
+	fields: {
+		balances: {
+			type: AccountBalanceRecord,
+			isOptional: false,
+			isArray: true
+		},
+		refreshedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: false
+		},
+		errors: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isArray: true,
+			isOptional: true
+		}
+	}
+});
+const OpenBankingGetBalances = defineQuery({
+	meta: {
+		key: "openbanking.balances.get",
+		version: "1.0.0",
+		description: "Retrieve the latest cached balances for a bank account.",
+		goal: "Expose current and available balances required by dashboards and analytics.",
+		context: "Used by Pocket Family Office UI surfaces and automation steps that require balance totals prior to generating summaries.",
+		owners: ["@platform.finance"],
+		tags: [
+			"open-banking",
+			"powens",
+			"balances"
+		],
+		stability: "experimental"
+	},
+	io: {
+		input: OpenBankingGetBalancesInput,
+		output: OpenBankingGetBalancesOutput
+	},
+	policy: { auth: "user" }
+});
+const OpenBankingRefreshBalances = defineCommand({
+	meta: {
+		key: "openbanking.balances.refresh",
+		version: "1.0.0",
+		description: "Refresh balances for a bank account via the configured open banking provider.",
+		goal: "Ensure canonical balance records reflect the latest values from Powens.",
+		context: "Triggered by scheduled workflows before generating summaries or forecasting cashflow.",
+		owners: ["@platform.finance"],
+		tags: [
+			"open-banking",
+			"powens",
+			"balances"
+		],
+		stability: "experimental"
+	},
+	io: {
+		input: OpenBankingRefreshBalancesInput,
+		output: OpenBankingRefreshBalancesOutput
+	},
+	policy: { auth: "admin" },
+	telemetry: {
+		success: {
+			event: { key: OPENBANKING_TELEMETRY_EVENTS.balancesRefreshed },
+			properties: ({ input, output }) => {
+				const payload = input;
+				const result = output;
+				return {
+					tenantId: payload?.tenantId,
+					accountId: payload?.accountId,
+					refreshedAt: result?.refreshedAt,
+					balanceCount: Array.isArray(result?.balances) ? result?.balances.length : void 0
+				};
+			}
+		},
+		failure: {
+			event: { key: OPENBANKING_TELEMETRY_EVENTS.balancesRefreshFailed },
+			properties: ({ input, error }) => {
+				const payload = input;
+				return {
+					tenantId: payload?.tenantId,
+					accountId: payload?.accountId,
+					error: error instanceof Error ? error.message : String(error ?? "unknown")
+				};
+			}
+		}
+	}
+});
+const openBankingBalanceContracts = {
+	OpenBankingGetBalances,
+	OpenBankingRefreshBalances
+};
+function registerOpenBankingBalanceContracts(registry) {
+	return registry.register(OpenBankingGetBalances).register(OpenBankingRefreshBalances);
+}
+
+//#endregion
+export { OpenBankingGetBalances, OpenBankingRefreshBalances, openBankingBalanceContracts, registerOpenBankingBalanceContracts };

package/dist/integrations/openbanking/contracts/index.d.ts

@@ -0,0 +1,10 @@
+import { OperationSpecRegistry } from "../../../operations/registry.js";
+import { OpenBankingGetAccount, OpenBankingListAccounts, OpenBankingSyncAccounts } from "./accounts.js";
+import { OpenBankingListTransactions, OpenBankingSyncTransactions } from "./transactions.js";
+import { OpenBankingGetBalances, OpenBankingRefreshBalances } from "./balances.js";
+import { OpenBankingFeature } from "../openbanking.feature.js";
+
+//#region src/integrations/openbanking/contracts/index.d.ts
+declare function registerOpenBankingContracts(registry: OperationSpecRegistry): OperationSpecRegistry;
+//#endregion
+export { OpenBankingFeature, OpenBankingGetAccount, OpenBankingGetBalances, OpenBankingListAccounts, OpenBankingListTransactions, OpenBankingRefreshBalances, OpenBankingSyncAccounts, OpenBankingSyncTransactions, registerOpenBankingContracts };

package/dist/integrations/openbanking/contracts/index.js

@@ -0,0 +1,12 @@
+import { OpenBankingGetAccount, OpenBankingListAccounts, OpenBankingSyncAccounts, registerOpenBankingAccountContracts } from "./accounts.js";
+import { OpenBankingListTransactions, OpenBankingSyncTransactions, registerOpenBankingTransactionContracts } from "./transactions.js";
+import { OpenBankingGetBalances, OpenBankingRefreshBalances, registerOpenBankingBalanceContracts } from "./balances.js";
+import { OpenBankingFeature } from "../openbanking.feature.js";
+
+//#region src/integrations/openbanking/contracts/index.ts
+function registerOpenBankingContracts(registry) {
+	return registerOpenBankingBalanceContracts(registerOpenBankingTransactionContracts(registerOpenBankingAccountContracts(registry)));
+}
+
+//#endregion
+export { OpenBankingFeature, OpenBankingGetAccount, OpenBankingGetBalances, OpenBankingListAccounts, OpenBankingListTransactions, OpenBankingRefreshBalances, OpenBankingSyncAccounts, OpenBankingSyncTransactions, registerOpenBankingContracts };

package/dist/integrations/openbanking/contracts/transactions.d.ts

@@ -0,0 +1,213 @@
+import { AnyOperationSpec, OperationSpec } from "../../../operations/operation.js";
+import { OperationSpecRegistry } from "../../../operations/registry.js";
+import "../../../operations/index.js";
+import "../../../index.js";
+import * as _contractspec_lib_schema408 from "@contractspec/lib.schema";
+import { SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/integrations/openbanking/contracts/transactions.d.ts
+declare const OpenBankingListTransactions: OperationSpec<SchemaModel<{
+  tenantId: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: false;
+  };
+  accountId: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: false;
+  };
+  from: {
+    type: _contractspec_lib_schema408.FieldType<Date, string>;
+    isOptional: true;
+  };
+  to: {
+    type: _contractspec_lib_schema408.FieldType<Date, string>;
+    isOptional: true;
+  };
+  cursor: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: true;
+  };
+  pageSize: {
+    type: _contractspec_lib_schema408.FieldType<number, number>;
+    isOptional: true;
+  };
+  direction: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: true;
+  };
+  minimumAmount: {
+    type: _contractspec_lib_schema408.FieldType<number, number>;
+    isOptional: true;
+  };
+  maximumAmount: {
+    type: _contractspec_lib_schema408.FieldType<number, number>;
+    isOptional: true;
+  };
+  category: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: true;
+  };
+}>, SchemaModel<{
+  transactions: {
+    type: SchemaModel<{
+      id: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: false;
+      };
+      accountId: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: false;
+      };
+      tenantId: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: false;
+      };
+      connectionId: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: false;
+      };
+      externalId: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: false;
+      };
+      amount: {
+        type: _contractspec_lib_schema408.FieldType<number, number>;
+        isOptional: false;
+      };
+      currency: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: false;
+      };
+      date: {
+        type: _contractspec_lib_schema408.FieldType<Date, string>;
+        isOptional: false;
+      };
+      bookingDate: {
+        type: _contractspec_lib_schema408.FieldType<Date, string>;
+        isOptional: true;
+      };
+      valueDate: {
+        type: _contractspec_lib_schema408.FieldType<Date, string>;
+        isOptional: true;
+      };
+      description: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: true;
+      };
+      counterpartyName: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: true;
+      };
+      counterpartyAccount: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: true;
+      };
+      merchantCategoryCode: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: true;
+      };
+      rawCategory: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: true;
+      };
+      standardizedCategory: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: true;
+      };
+      transactionType: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: false;
+      };
+      status: {
+        type: _contractspec_lib_schema408.FieldType<string, string>;
+        isOptional: false;
+      };
+      runningBalance: {
+        type: _contractspec_lib_schema408.FieldType<number, number>;
+        isOptional: true;
+      };
+      metadata: {
+        type: _contractspec_lib_schema408.FieldType<Record<string, unknown>, Record<string, unknown>>;
+        isOptional: true;
+      };
+      createdAt: {
+        type: _contractspec_lib_schema408.FieldType<Date, string>;
+        isOptional: false;
+      };
+      updatedAt: {
+        type: _contractspec_lib_schema408.FieldType<Date, string>;
+        isOptional: false;
+      };
+    }>;
+    isOptional: false;
+    isArray: true;
+  };
+  nextCursor: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: true;
+  };
+  hasMore: {
+    type: _contractspec_lib_schema408.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+}>, undefined>;
+declare const OpenBankingSyncTransactions: OperationSpec<SchemaModel<{
+  tenantId: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: false;
+  };
+  accountId: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: false;
+  };
+  from: {
+    type: _contractspec_lib_schema408.FieldType<Date, string>;
+    isOptional: true;
+  };
+  to: {
+    type: _contractspec_lib_schema408.FieldType<Date, string>;
+    isOptional: true;
+  };
+  connectionId: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: true;
+  };
+  includePending: {
+    type: _contractspec_lib_schema408.FieldType<boolean, boolean>;
+    isOptional: true;
+  };
+  backfillDays: {
+    type: _contractspec_lib_schema408.FieldType<number, number>;
+    isOptional: true;
+  };
+}>, SchemaModel<{
+  synced: {
+    type: _contractspec_lib_schema408.FieldType<number, number>;
+    isOptional: false;
+  };
+  failed: {
+    type: _contractspec_lib_schema408.FieldType<number, number>;
+    isOptional: false;
+  };
+  earliestSyncedAt: {
+    type: _contractspec_lib_schema408.FieldType<Date, string>;
+    isOptional: true;
+  };
+  latestSyncedAt: {
+    type: _contractspec_lib_schema408.FieldType<Date, string>;
+    isOptional: true;
+  };
+  nextSinceToken: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isOptional: true;
+  };
+  errors: {
+    type: _contractspec_lib_schema408.FieldType<string, string>;
+    isArray: true;
+    isOptional: true;
+  };
+}>, undefined>;
+declare const openBankingTransactionContracts: Record<string, AnyOperationSpec>;
+declare function registerOpenBankingTransactionContracts(registry: OperationSpecRegistry): OperationSpecRegistry;
+//#endregion
+export { OpenBankingListTransactions, OpenBankingSyncTransactions, openBankingTransactionContracts, registerOpenBankingTransactionContracts };

package/dist/integrations/openbanking/contracts/transactions.js

@@ -0,0 +1,217 @@
+import { defineCommand, defineQuery } from "../../../operations/operation.js";
+import "../../../operations/index.js";
+import { BankTransactionRecord } from "../models.js";
+import { OPENBANKING_TELEMETRY_EVENTS } from "../telemetry.js";
+import { ScalarTypeEnum, SchemaModel } from "@contractspec/lib.schema";
+
+//#region src/integrations/openbanking/contracts/transactions.ts
+const OpenBankingListTransactionsInput = new SchemaModel({
+	name: "OpenBankingListTransactionsInput",
+	description: "Parameters for listing bank transactions from the canonical ledger.",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		accountId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		from: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		to: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		cursor: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		pageSize: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		},
+		direction: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		minimumAmount: {
+			type: ScalarTypeEnum.Float_unsecure(),
+			isOptional: true
+		},
+		maximumAmount: {
+			type: ScalarTypeEnum.Float_unsecure(),
+			isOptional: true
+		},
+		category: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const OpenBankingListTransactionsOutput = new SchemaModel({
+	name: "OpenBankingListTransactionsOutput",
+	description: "Paginated list of transactions for a bank account.",
+	fields: {
+		transactions: {
+			type: BankTransactionRecord,
+			isOptional: false,
+			isArray: true
+		},
+		nextCursor: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		hasMore: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		}
+	}
+});
+const OpenBankingSyncTransactionsInput = new SchemaModel({
+	name: "OpenBankingSyncTransactionsInput",
+	description: "Command payload to synchronise transactions from the open banking provider into the canonical ledger.",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		accountId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		from: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		to: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		connectionId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: true
+		},
+		includePending: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		backfillDays: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const OpenBankingSyncTransactionsOutput = new SchemaModel({
+	name: "OpenBankingSyncTransactionsOutput",
+	description: "Result of a transaction synchronisation run.",
+	fields: {
+		synced: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		failed: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		earliestSyncedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		latestSyncedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		},
+		nextSinceToken: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		errors: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isArray: true,
+			isOptional: true
+		}
+	}
+});
+const OpenBankingListTransactions = defineQuery({
+	meta: {
+		key: "openbanking.transactions.list",
+		version: "1.0.0",
+		description: "List bank transactions that have been normalised into the canonical ledger.",
+		goal: "Allow downstream analytics and UI surfaces to page through canonical bank transactions.",
+		context: "Used by Pocket Family Office dashboards, reconciliation workflows, and analytics data views.",
+		owners: ["@platform.finance"],
+		tags: [
+			"open-banking",
+			"powens",
+			"transactions"
+		],
+		stability: "experimental"
+	},
+	io: {
+		input: OpenBankingListTransactionsInput,
+		output: OpenBankingListTransactionsOutput
+	},
+	policy: { auth: "user" }
+});
+const OpenBankingSyncTransactions = defineCommand({
+	meta: {
+		key: "openbanking.transactions.sync",
+		version: "1.0.0",
+		description: "Synchronise transactions for a bank account by calling the configured open banking provider.",
+		goal: "Ensure the canonical transaction ledger stays aligned with the external provider.",
+		context: "Triggered by scheduled workflows or on-demand actions when activity is expected on an account.",
+		owners: ["@platform.finance"],
+		tags: [
+			"open-banking",
+			"powens",
+			"transactions"
+		],
+		stability: "experimental"
+	},
+	io: {
+		input: OpenBankingSyncTransactionsInput,
+		output: OpenBankingSyncTransactionsOutput
+	},
+	policy: { auth: "admin" },
+	telemetry: {
+		success: {
+			event: { key: OPENBANKING_TELEMETRY_EVENTS.transactionsSynced },
+			properties: ({ input, output }) => {
+				const payload = input;
+				const result = output;
+				return {
+					tenantId: payload?.tenantId,
+					accountId: payload?.accountId,
+					synced: result?.synced,
+					failed: result?.failed,
+					earliestSyncedAt: result?.earliestSyncedAt,
+					latestSyncedAt: result?.latestSyncedAt
+				};
+			}
+		},
+		failure: {
+			event: { key: OPENBANKING_TELEMETRY_EVENTS.transactionsSyncFailed },
+			properties: ({ input, error }) => {
+				const payload = input;
+				return {
+					tenantId: payload?.tenantId,
+					accountId: payload?.accountId,
+					error: error instanceof Error ? error.message : String(error ?? "unknown")
+				};
+			}
+		}
+	}
+});
+const openBankingTransactionContracts = {
+	OpenBankingListTransactions,
+	OpenBankingSyncTransactions
+};
+function registerOpenBankingTransactionContracts(registry) {
+	return registry.register(OpenBankingListTransactions).register(OpenBankingSyncTransactions);
+}
+
+//#endregion
+export { OpenBankingListTransactions, OpenBankingSyncTransactions, openBankingTransactionContracts, registerOpenBankingTransactionContracts };

package/dist/integrations/openbanking/guards.d.ts

@@ -0,0 +1,12 @@
+import { ResolvedAppConfig, ResolvedIntegration } from "../../app-config/runtime.js";
+
+//#region src/integrations/openbanking/guards.d.ts
+interface OpenBankingGuardResult {
+  ok: boolean;
+  integration?: ResolvedIntegration;
+  error?: string;
+}
+declare function ensurePrimaryOpenBankingIntegration(config: ResolvedAppConfig): OpenBankingGuardResult;
+declare function assertPrimaryOpenBankingReady(config: ResolvedAppConfig): ResolvedIntegration;
+//#endregion
+export { OpenBankingGuardResult, assertPrimaryOpenBankingReady, ensurePrimaryOpenBankingIntegration };

package/dist/integrations/openbanking/guards.js

@@ -0,0 +1,33 @@
+//#region src/integrations/openbanking/guards.ts
+const PRIMARY_SLOT_ID = "primaryOpenBanking";
+function ensurePrimaryOpenBankingIntegration(config) {
+	const integration = config.integrations.find((item) => item.slot.slotId === PRIMARY_SLOT_ID);
+	if (!integration) return {
+		ok: false,
+		error: "primaryOpenBanking slot is not bound in the resolved app config."
+	};
+	const status = integration.connection.status;
+	if (status === "error" || status === "disconnected") return {
+		ok: false,
+		integration,
+		error: `primaryOpenBanking connection is in status "${status}".`
+	};
+	if (status === "unknown") return {
+		ok: false,
+		integration,
+		error: "primaryOpenBanking connection health is unknown."
+	};
+	return {
+		ok: true,
+		integration
+	};
+}
+function assertPrimaryOpenBankingReady(config) {
+	const result = ensurePrimaryOpenBankingIntegration(config);
+	if (!result.ok) throw new Error(result.error ?? "Open banking integration not available.");
+	if (!result.integration) throw new Error(result.error ?? "Open banking integration not available.");
+	return result.integration;
+}
+
+//#endregion
+export { assertPrimaryOpenBankingReady, ensurePrimaryOpenBankingIntegration };