@classytic/primitives 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.2] - 2026-05-30
+
+### Added — `BankTransaction` per-account routing + pending lifecycle fields
+
+Three additive optional fields on `BankTransaction` (`/bank-transaction`):
+
+- **`sourceAccountId?: string`** — the vendor-side account this row belongs to
+  (Plaid `account_id`, Xero `BankAccount.AccountID`). Sync feeds return
+  transactions spanning multiple accounts in one batch; this lets consumers
+  route each row to the right account per-transaction (multi-account sync)
+  instead of forcing the whole batch onto one account. Statement formats
+  (single-account files) leave it undefined — the account lives on
+  `BankStatement.account`.
+- **`pending?: boolean`** — the entry hasn't posted/cleared yet (real-time
+  feeds like Plaid `pending: true`; statement formats leave it undefined).
+  Consumers must treat pending rows as provisional — don't reconcile/post
+  them as final.
+- **`supersedesExternalId?: string`** — set on a POSTED row that replaces an
+  earlier PENDING one, carrying the pending row's `externalId` (Plaid
+  `pending_transaction_id`). Pending and posted rows have different
+  `externalId`s, so consumers MUST use this back-pointer to drop/replace the
+  superseded pending row on ingest — otherwise both persist as duplicates.
+
+Backward-compatible (both optional). Closes a fidelity gap where Plaid's
+pending state was dropped at the canonical boundary, so downstream consumers
+(`@classytic/fin-io` Plaid mapper, `@classytic/revenue` import) couldn't
+distinguish provisional rows or dedupe pending→posted.
+
 ## [0.7.1] - 2026-05-26
 
 ### Added — workflow + scheduling + composition primitives

package/dist/bank-transaction.d.mts

@@ -96,6 +96,41 @@ interface BankTransaction {
   balanceAfter?: Money;
   /** Format-specific entry-type code (`'DEBIT'`, `'CREDIT'`, `'CHECK'`, …). */
   type?: string;
+  /**
+   * Vendor-side identifier of the account this row belongs to — Plaid
+   * `account_id`, Xero `BankAccount.AccountID`. Sync feeds return transactions
+   * spanning MULTIPLE accounts in one batch, so this lets a consumer route
+   * each row to the right destination account per-transaction (multi-account
+   * sync) instead of forcing the whole batch onto one account.
+   *
+   * Statement formats (OFX / CAMT.053 / MT940 / CSV / IIF) are single-account
+   * files — they carry the account on `BankStatement.account` and leave this
+   * `undefined`. Distinct from any consumer-side account id (e.g. the host's
+   * own `bankAccountId` used in the import unique index).
+   */
+  sourceAccountId?: string;
+  /**
+   * The entry has not yet posted / cleared — the bank may still change its
+   * amount, description, or drop it entirely. Real-time feeds populate this
+   * (Plaid `pending: true`); statement formats (OFX / CAMT.053 / MT940 / CSV)
+   * only ever carry settled rows and leave it `undefined`.
+   *
+   * Consumers MUST treat `pending: true` rows as provisional — do not
+   * reconcile or post them as final, and expect a superseding posted row to
+   * arrive later (linked via `supersedesExternalId`).
+   */
+  pending?: boolean;
+  /**
+   * Set on a POSTED row that replaces an earlier PENDING one: the
+   * `externalId` of the pending row this entry supersedes (Plaid
+   * `pending_transaction_id`).
+   *
+   * The pending and posted rows carry DIFFERENT `externalId`s, so dedup on
+   * `externalId` alone can't collapse them — consumers MUST use this
+   * back-pointer to drop / replace the superseded pending row on ingest, or
+   * both versions persist as duplicates.
+   */
+  supersedesExternalId?: string;
   /**
    * Format-specific raw record. Pass-through for audit / debugging.
    * Consumers MUST NOT rely on this — schema may change between fin-io

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",