@contractspec/lib.contracts-integrations 2.0.0

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

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

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

@@ -0,0 +1,298 @@
+// @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/transactions.ts
+import { ScalarTypeEnum as ScalarTypeEnum2, SchemaModel as SchemaModel2 } from "@contractspec/lib.schema";
+import {
+  defineCommand,
+  defineQuery
+} from "@contractspec/lib.contracts-spec/operations";
+var OpenBankingListTransactionsInput = new SchemaModel2({
+  name: "OpenBankingListTransactionsInput",
+  description: "Parameters for listing bank transactions from the canonical ledger.",
+  fields: {
+    tenantId: { type: ScalarTypeEnum2.ID(), isOptional: false },
+    accountId: { type: ScalarTypeEnum2.ID(), isOptional: false },
+    from: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    to: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    cursor: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    pageSize: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true },
+    direction: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    minimumAmount: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: true },
+    maximumAmount: { type: ScalarTypeEnum2.Float_unsecure(), isOptional: true },
+    category: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true }
+  }
+});
+var OpenBankingListTransactionsOutput = new SchemaModel2({
+  name: "OpenBankingListTransactionsOutput",
+  description: "Paginated list of transactions for a bank account.",
+  fields: {
+    transactions: {
+      type: BankTransactionRecord,
+      isOptional: false,
+      isArray: true
+    },
+    nextCursor: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+    hasMore: { type: ScalarTypeEnum2.Boolean(), isOptional: true }
+  }
+});
+var OpenBankingSyncTransactionsInput = new SchemaModel2({
+  name: "OpenBankingSyncTransactionsInput",
+  description: "Command payload to synchronise transactions from the open banking provider into the canonical ledger.",
+  fields: {
+    tenantId: { type: ScalarTypeEnum2.ID(), isOptional: false },
+    accountId: { type: ScalarTypeEnum2.ID(), isOptional: false },
+    from: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    to: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    connectionId: { type: ScalarTypeEnum2.ID(), isOptional: true },
+    includePending: { type: ScalarTypeEnum2.Boolean(), isOptional: true },
+    backfillDays: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: true }
+  }
+});
+var OpenBankingSyncTransactionsOutput = new SchemaModel2({
+  name: "OpenBankingSyncTransactionsOutput",
+  description: "Result of a transaction synchronisation run.",
+  fields: {
+    synced: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    failed: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false },
+    earliestSyncedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    latestSyncedAt: { type: ScalarTypeEnum2.DateTime(), isOptional: true },
+    nextSinceToken: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isOptional: true
+    },
+    errors: {
+      type: ScalarTypeEnum2.String_unsecure(),
+      isArray: true,
+      isOptional: true
+    }
+  }
+});
+var 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"
+  }
+});
+var 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")
+        };
+      }
+    }
+  }
+});
+var openBankingTransactionContracts = {
+  OpenBankingListTransactions,
+  OpenBankingSyncTransactions
+};
+function registerOpenBankingTransactionContracts(registry) {
+  return registry.register(OpenBankingListTransactions).register(OpenBankingSyncTransactions);
+}
+export {
+  registerOpenBankingTransactionContracts,
+  openBankingTransactionContracts,
+  OpenBankingSyncTransactions,
+  OpenBankingListTransactions
+};

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

@@ -0,0 +1,8 @@
+import type { ResolvedAppConfig, ResolvedIntegration } from '@contractspec/lib.contracts-spec/app-config/runtime';
+export interface OpenBankingGuardResult {
+    ok: boolean;
+    integration?: ResolvedIntegration;
+    error?: string;
+}
+export declare function ensurePrimaryOpenBankingIntegration(config: ResolvedAppConfig): OpenBankingGuardResult;
+export declare function assertPrimaryOpenBankingReady(config: ResolvedAppConfig): ResolvedIntegration;

package/dist/integrations/openbanking/guards.js

@@ -0,0 +1,42 @@
+// @bun
+// src/integrations/openbanking/guards.ts
+var 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;
+}
+export {
+  ensurePrimaryOpenBankingIntegration,
+  assertPrimaryOpenBankingReady
+};

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

@@ -0,0 +1 @@
+export {};