@lssm/example.saas-boilerplate 0.0.0-canary-20251217060834 → 0.0.0-canary-20251217072406

package/dist/libs/identity-rbac/dist/contracts/dist/integrations/openbanking/contracts/accounts.js

@@ -0,0 +1,228 @@
+import { SchemaModel } from "../../../schema/dist/SchemaModel.js";
+import { ScalarTypeEnum } from "../../../schema/dist/ScalarTypeEnum.js";
+import "../../../schema/dist/index.js";
+import { defineCommand, defineQuery } from "../../../spec.js";
+import { BankAccountRecord } from "../models.js";
+import { OPENBANKING_TELEMETRY_EVENTS } from "../telemetry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/integrations/openbanking/contracts/accounts.js
+const OpenBankingListAccountsInput = new SchemaModel({
+	name: "OpenBankingListAccountsInput",
+	description: "Parameters for listing bank accounts through the open banking provider.",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		userId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		connectionId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: true
+		},
+		includeBalances: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		institutionId: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		cursor: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		pageSize: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: true
+		}
+	}
+});
+const OpenBankingListAccountsOutput = new SchemaModel({
+	name: "OpenBankingListAccountsOutput",
+	description: "Paginated list of bank accounts available to the tenant and user.",
+	fields: {
+		accounts: {
+			type: BankAccountRecord,
+			isOptional: false,
+			isArray: true
+		},
+		nextCursor: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isOptional: true
+		},
+		hasMore: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		}
+	}
+});
+const OpenBankingGetAccountInput = new SchemaModel({
+	name: "OpenBankingGetAccountInput",
+	description: "Parameters for retrieving a specific bank account.",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		accountId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		includeBalances: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		includeLatestTransactions: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		}
+	}
+});
+const OpenBankingSyncAccountsInput = new SchemaModel({
+	name: "OpenBankingSyncAccountsInput",
+	description: "Command payload to trigger an account synchronisation against the open banking provider.",
+	fields: {
+		tenantId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		userId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: true
+		},
+		connectionId: {
+			type: ScalarTypeEnum.ID(),
+			isOptional: false
+		},
+		accountIds: {
+			type: ScalarTypeEnum.ID(),
+			isArray: true,
+			isOptional: true
+		},
+		forceFullRefresh: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		},
+		triggerWorkflows: {
+			type: ScalarTypeEnum.Boolean(),
+			isOptional: true
+		}
+	}
+});
+const OpenBankingSyncAccountsOutput = new SchemaModel({
+	name: "OpenBankingSyncAccountsOutput",
+	description: "Result of a bank account synchronisation run.",
+	fields: {
+		synced: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		failed: {
+			type: ScalarTypeEnum.Int_unsecure(),
+			isOptional: false
+		},
+		errors: {
+			type: ScalarTypeEnum.String_unsecure(),
+			isArray: true,
+			isOptional: true
+		},
+		nextSyncSuggestedAt: {
+			type: ScalarTypeEnum.DateTime(),
+			isOptional: true
+		}
+	}
+});
+defineQuery({
+	meta: {
+		name: "openbanking.accounts.list",
+		version: 1,
+		description: "List bank accounts available to a tenant/user via Powens Open Banking.",
+		goal: "Provide downstream workflows with the set of accounts accessible via the configured open banking connection.",
+		context: "Used by Pocket Family Office dashboards and sync workflows to enumerate bank accounts prior to syncing balances or transactions.",
+		owners: ["platform.finance"],
+		tags: [
+			"open-banking",
+			"powens",
+			"accounts"
+		],
+		stability: "experimental"
+	},
+	io: {
+		input: OpenBankingListAccountsInput,
+		output: OpenBankingListAccountsOutput
+	},
+	policy: { auth: "user" }
+});
+defineQuery({
+	meta: {
+		name: "openbanking.accounts.get",
+		version: 1,
+		description: "Retrieve the canonical bank account record for the given account identifier.",
+		goal: "Allow user-facing experiences and automations to display up-to-date account metadata.",
+		context: "Invoked by UI surfaces and workflow automation steps that require detailed metadata for a specific bank account.",
+		owners: ["platform.finance"],
+		tags: [
+			"open-banking",
+			"powens",
+			"accounts"
+		],
+		stability: "experimental"
+	},
+	io: {
+		input: OpenBankingGetAccountInput,
+		output: BankAccountRecord
+	},
+	policy: { auth: "user" }
+});
+defineCommand({
+	meta: {
+		name: "openbanking.accounts.sync",
+		version: 1,
+		description: "Initiate a synchronisation run to refresh bank account metadata from Powens.",
+		goal: "Keep canonical bank account records aligned with the external open banking provider.",
+		context: "Triggered by scheduled workflows or manual operator actions to reconcile account metadata prior to transaction/balance syncs.",
+		owners: ["platform.finance"],
+		tags: [
+			"open-banking",
+			"powens",
+			"accounts"
+		],
+		stability: "experimental"
+	},
+	io: {
+		input: OpenBankingSyncAccountsInput,
+		output: OpenBankingSyncAccountsOutput
+	},
+	policy: { auth: "admin" },
+	telemetry: {
+		success: {
+			event: { name: OPENBANKING_TELEMETRY_EVENTS.accountsSynced },
+			properties: ({ input, output }) => {
+				const payload = input;
+				const result = output;
+				return {
+					tenantId: payload?.tenantId,
+					connectionId: payload?.connectionId,
+					synced: result?.synced,
+					failed: result?.failed
+				};
+			}
+		},
+		failure: {
+			event: { name: OPENBANKING_TELEMETRY_EVENTS.accountsSyncFailed },
+			properties: ({ input, error }) => {
+				const payload = input;
+				return {
+					tenantId: payload?.tenantId,
+					connectionId: payload?.connectionId,
+					error: error instanceof Error ? error.message : String(error ?? "unknown")
+				};
+			}
+		}
+	}
+});
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/integrations/openbanking/contracts/balances.js

@@ -0,0 +1,159 @@
+import { SchemaModel } from "../../../schema/dist/SchemaModel.js";
+import { ScalarTypeEnum } from "../../../schema/dist/ScalarTypeEnum.js";
+import "../../../schema/dist/index.js";
+import { defineCommand, defineQuery } from "../../../spec.js";
+import { AccountBalanceRecord } from "../models.js";
+import { OPENBANKING_TELEMETRY_EVENTS } from "../telemetry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/integrations/openbanking/contracts/balances.js
+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
+		}
+	}
+});
+defineQuery({
+	meta: {
+		name: "openbanking.balances.get",
+		version: 1,
+		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" }
+});
+defineCommand({
+	meta: {
+		name: "openbanking.balances.refresh",
+		version: 1,
+		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: { name: 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: { name: 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")
+				};
+			}
+		}
+	}
+});
+
+//#endregion

package/dist/libs/identity-rbac/dist/contracts/dist/integrations/openbanking/contracts/index.js

@@ -0,0 +1,3 @@
+import "./accounts.js";
+import "./transactions.js";
+import "./balances.js";

package/dist/libs/identity-rbac/dist/contracts/dist/integrations/openbanking/contracts/transactions.js

@@ -0,0 +1,210 @@
+import { SchemaModel } from "../../../schema/dist/SchemaModel.js";
+import { ScalarTypeEnum } from "../../../schema/dist/ScalarTypeEnum.js";
+import "../../../schema/dist/index.js";
+import { defineCommand, defineQuery } from "../../../spec.js";
+import { BankTransactionRecord } from "../models.js";
+import { OPENBANKING_TELEMETRY_EVENTS } from "../telemetry.js";
+
+//#region ../../libs/identity-rbac/dist/contracts/dist/integrations/openbanking/contracts/transactions.js
+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
+		}
+	}
+});
+defineQuery({
+	meta: {
+		name: "openbanking.transactions.list",
+		version: 1,
+		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" }
+});
+defineCommand({
+	meta: {
+		name: "openbanking.transactions.sync",
+		version: 1,
+		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: { name: 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: { name: 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")
+				};
+			}
+		}
+	}
+});
+
+//#endregion