@contractspec/lib.contracts-integrations 2.0.0

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

@@ -0,0 +1,292 @@
+// @bun
+// src/integrations/openbanking/models.ts
+import { ScalarTypeEnum, SchemaModel } from "@contractspec/lib.schema";
+var BankAccountRecord = new SchemaModel({
+  name: "BankAccountRecord",
+  description: "Canonical representation of a bank account synced from an open banking provider.",
+  fields: {
+    id: { type: ScalarTypeEnum.ID(), isOptional: false },
+    tenantId: { type: ScalarTypeEnum.ID(), isOptional: false },
+    userId: { type: ScalarTypeEnum.ID(), isOptional: false },
+    connectionId: { type: ScalarTypeEnum.ID(), isOptional: false },
+    externalId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    institutionId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    institutionName: {
+      type: ScalarTypeEnum.NonEmptyString(),
+      isOptional: false
+    },
+    institutionLogoUrl: { type: ScalarTypeEnum.URL(), isOptional: true },
+    iban: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    bic: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    accountType: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    currency: { type: ScalarTypeEnum.Currency(), isOptional: false },
+    displayName: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    accountNumberMasked: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    productCode: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    balance: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true },
+    availableBalance: {
+      type: ScalarTypeEnum.Float_unsecure(),
+      isOptional: true
+    },
+    lastSyncedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    metadata: { type: ScalarTypeEnum.JSONObject(), isOptional: true }
+  }
+});
+var BankTransactionRecord = new SchemaModel({
+  name: "BankTransactionRecord",
+  description: "Canonical transaction entry mapped from Powens into the open banking ledger.",
+  fields: {
+    id: { type: ScalarTypeEnum.ID(), isOptional: false },
+    accountId: { type: ScalarTypeEnum.ID(), isOptional: false },
+    tenantId: { type: ScalarTypeEnum.ID(), isOptional: false },
+    connectionId: { type: ScalarTypeEnum.ID(), isOptional: false },
+    externalId: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    amount: { type: ScalarTypeEnum.Float_unsecure(), isOptional: false },
+    currency: { type: ScalarTypeEnum.Currency(), isOptional: false },
+    date: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    bookingDate: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    valueDate: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    counterpartyName: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    counterpartyAccount: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    merchantCategoryCode: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    rawCategory: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    standardizedCategory: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    transactionType: {
+      type: ScalarTypeEnum.NonEmptyString(),
+      isOptional: false
+    },
+    status: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    runningBalance: { type: ScalarTypeEnum.Float_unsecure(), isOptional: true },
+    metadata: { type: ScalarTypeEnum.JSONObject(), isOptional: true },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    updatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var AccountBalanceRecord = new SchemaModel({
+  name: "AccountBalanceRecord",
+  description: "Canonical balance snapshot computed from Powens balance payloads.",
+  fields: {
+    id: { type: ScalarTypeEnum.ID(), isOptional: false },
+    accountId: { type: ScalarTypeEnum.ID(), isOptional: false },
+    tenantId: { type: ScalarTypeEnum.ID(), isOptional: false },
+    connectionId: { type: ScalarTypeEnum.ID(), isOptional: false },
+    balanceType: { type: ScalarTypeEnum.NonEmptyString(), isOptional: false },
+    currentBalance: {
+      type: ScalarTypeEnum.Float_unsecure(),
+      isOptional: false
+    },
+    availableBalance: {
+      type: ScalarTypeEnum.Float_unsecure(),
+      isOptional: true
+    },
+    currency: { type: ScalarTypeEnum.Currency(), isOptional: false },
+    lastUpdatedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    createdAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    metadata: { type: ScalarTypeEnum.JSONObject(), isOptional: true }
+  }
+});
+
+// src/integrations/openbanking/telemetry.ts
+var OPENBANKING_PII_FIELDS = [
+  "iban",
+  "bic",
+  "accountNumberMasked",
+  "accountNumber",
+  "counterpartyName",
+  "counterpartyAccount",
+  "description",
+  "merchantName",
+  "merchantCategoryCode",
+  "reference"
+];
+var OPENBANKING_TELEMETRY_EVENTS = {
+  accountsSynced: "openbanking.accounts.synced",
+  accountsSyncFailed: "openbanking.accounts.sync_failed",
+  transactionsSynced: "openbanking.transactions.synced",
+  transactionsSyncFailed: "openbanking.transactions.sync_failed",
+  balancesRefreshed: "openbanking.balances.refreshed",
+  balancesRefreshFailed: "openbanking.balances.refresh_failed",
+  overviewGenerated: "openbanking.overview.generated"
+};
+function redactOpenBankingTelemetryPayload(payload) {
+  const redacted = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (OPENBANKING_PII_FIELDS.includes(key)) {
+      redacted[key] = maskValue(value);
+    } else if (Array.isArray(value)) {
+      redacted[key] = value.map((item) => typeof item === "object" && item !== null ? redactOpenBankingTelemetryPayload(item) : item);
+    } else if (typeof value === "object" && value !== null) {
+      redacted[key] = redactOpenBankingTelemetryPayload(value);
+    } else {
+      redacted[key] = value;
+    }
+  }
+  return redacted;
+}
+function maskValue(value) {
+  if (value == null)
+    return "";
+  const str = String(value);
+  if (str.length <= 4)
+    return "*".repeat(str.length);
+  return `${"*".repeat(Math.max(str.length - 4, 0))}${str.slice(-4)}`;
+}
+
+// src/integrations/openbanking/contracts/balances.ts
+import { ScalarTypeEnum as ScalarTypeEnum2, SchemaModel as SchemaModel2 } from "@contractspec/lib.schema";
+import {
+  defineCommand,
+  defineQuery
+} from "@contractspec/lib.contracts-spec/operations";
+var OpenBankingGetBalancesInput = new SchemaModel2({
+  name: "OpenBankingGetBalancesInput",
+  description: "Parameters for retrieving bank account balances from the canonical ledger.",
+  fields: {
+    tenantId: { type: ScalarTypeEnum2.ID(), isOptional: false },
+    accountId: { type: ScalarTypeEnum2.ID(), isOptional: false },
+    balanceTypes: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isArray: true,
+      isOptional: true
+    }
+  }
+});
+var OpenBankingGetBalancesOutput = new SchemaModel2({
+  name: "OpenBankingGetBalancesOutput",
+  description: "Canonical balances for a bank account.",
+  fields: {
+    balances: {
+      type: AccountBalanceRecord,
+      isOptional: false,
+      isArray: true
+    },
+    asOf: { type: ScalarTypeEnum2.DateTime(), isOptional: true }
+  }
+});
+var OpenBankingRefreshBalancesInput = new SchemaModel2({
+  name: "OpenBankingRefreshBalancesInput",
+  description: "Command payload to refresh balances for a bank account via the open banking provider.",
+  fields: {
+    tenantId: { type: ScalarTypeEnum2.ID(), isOptional: false },
+    accountId: { type: ScalarTypeEnum2.ID(), isOptional: false },
+    connectionId: { type: ScalarTypeEnum2.ID(), isOptional: true },
+    balanceTypes: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isArray: true,
+      isOptional: true
+    },
+    forceRefresh: { type: ScalarTypeEnum2.Boolean(), isOptional: true }
+  }
+});
+var OpenBankingRefreshBalancesOutput = new SchemaModel2({
+  name: "OpenBankingRefreshBalancesOutput",
+  description: "Result of a balance refresh against the open banking provider.",
+  fields: {
+    balances: {
+      type: AccountBalanceRecord,
+      isOptional: false,
+      isArray: true
+    },
+    refreshedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: false },
+    errors: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isArray: true,
+      isOptional: true
+    }
+  }
+});
+var 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"
+  }
+});
+var 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 : undefined
+        };
+      }
+    },
+    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")
+        };
+      }
+    }
+  }
+});
+var openBankingBalanceContracts = {
+  OpenBankingGetBalances,
+  OpenBankingRefreshBalances
+};
+function registerOpenBankingBalanceContracts(registry) {
+  return registry.register(OpenBankingGetBalances).register(OpenBankingRefreshBalances);
+}
+export {
+  registerOpenBankingBalanceContracts,
+  openBankingBalanceContracts,
+  OpenBankingRefreshBalances,
+  OpenBankingGetBalances
+};

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

@@ -0,0 +1,7 @@
+import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
+import { OpenBankingGetAccount, OpenBankingListAccounts, OpenBankingSyncAccounts } from './accounts';
+import { OpenBankingListTransactions, OpenBankingSyncTransactions } from './transactions';
+import { OpenBankingGetBalances, OpenBankingRefreshBalances } from './balances';
+export { OpenBankingGetAccount, OpenBankingListAccounts, OpenBankingSyncAccounts, OpenBankingListTransactions, OpenBankingSyncTransactions, OpenBankingGetBalances, OpenBankingRefreshBalances, };
+export * from '../openbanking.feature';
+export declare function registerOpenBankingContracts(registry: OperationSpecRegistry): OperationSpecRegistry;