@openora/core 0.4.1-canary.93 → 0.4.1-canary.95

package/dist/wallet/service/reconciliation-finding.service.d.ts

@@ -0,0 +1,39 @@
+import type { DrizzleDb, DrizzleTx } from '@openora/core/server';
+import type { WalletReconciliationFindingKind } from '@openora/core/contracts';
+/**
+ * Sentinel `runId` for a finding produced OUTSIDE any reconciliation job cycle - the
+ * live webhook path (`WalletService.creditDepositByAddress`) hits an unattributable
+ * deposit in real time, not on a poll. `runId` is NOT NULL on the table, so this fixed
+ * zero-uuid documents "no job run owns this row", mirroring the audit plugin's
+ * SYSTEM_ACTOR sentinel for "no admin acted here".
+ */
+export declare const LIVE_WEBHOOK_RUN_ID = "00000000-0000-0000-0000-000000000000";
+export type ReconciliationFindingInput = {
+    runId: string;
+    providerName: string;
+    kind: WalletReconciliationFindingKind;
+    currency?: string | null;
+    network?: string | null;
+    amount?: string | null;
+    address?: string | null;
+    tag?: string | null;
+    txHash?: string | null;
+    /**
+     * The dedup key: a partial unique index on (kind, externalId) makes a duplicate
+     * insert for the same underlying vendor event or job re-run a silent no-op. Pass a
+     * stable stand-in (eg the source row's own id) when no vendor externalId exists, so
+     * a finding with no natural external reference still dedupes across re-runs.
+     */
+    externalId?: string | null;
+    transactionId?: string | null;
+    detail?: string | null;
+};
+/**
+ * The single write path for a reconciliation finding - never a raw `insert` scattered
+ * across WalletService and ReconciliationService (both import this, neither imports the
+ * other, so there is no cycle). A finding is a report, never a credit instruction (see
+ * the schema's own comment): this never touches a balance or a transaction row, only
+ * records that something needs a human look.
+ */
+export declare function recordReconciliationFinding(db: DrizzleDb | DrizzleTx, input: ReconciliationFindingInput): Promise<void>;
+//# sourceMappingURL=reconciliation-finding.service.d.ts.map

package/dist/wallet/service/reconciliation-finding.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliation-finding.service.d.ts","sourceRoot":"","sources":["../../../src/wallet/service/reconciliation-finding.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,yBAAyB,CAAC;AAG/E;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,yCAAyC,CAAC;AAE1E,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,+BAA+B,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,EAAE,EAAE,SAAS,GAAG,SAAS,EACzB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,IAAI,CAAC,CAkBf"}

package/dist/wallet/service/reconciliation-finding.service.js

@@ -0,0 +1,36 @@
+import { walletReconciliationFinding } from '../schema/index.js';
+/**
+ * Sentinel `runId` for a finding produced OUTSIDE any reconciliation job cycle - the
+ * live webhook path (`WalletService.creditDepositByAddress`) hits an unattributable
+ * deposit in real time, not on a poll. `runId` is NOT NULL on the table, so this fixed
+ * zero-uuid documents "no job run owns this row", mirroring the audit plugin's
+ * SYSTEM_ACTOR sentinel for "no admin acted here".
+ */
+export const LIVE_WEBHOOK_RUN_ID = '00000000-0000-0000-0000-000000000000';
+/**
+ * The single write path for a reconciliation finding - never a raw `insert` scattered
+ * across WalletService and ReconciliationService (both import this, neither imports the
+ * other, so there is no cycle). A finding is a report, never a credit instruction (see
+ * the schema's own comment): this never touches a balance or a transaction row, only
+ * records that something needs a human look.
+ */
+export async function recordReconciliationFinding(db, input) {
+    await db
+        .insert(walletReconciliationFinding)
+        .values({
+        runId: input.runId,
+        providerName: input.providerName,
+        kind: input.kind,
+        currency: input.currency ?? null,
+        network: input.network ?? null,
+        amount: input.amount ?? null,
+        address: input.address ?? null,
+        tag: input.tag ?? null,
+        txHash: input.txHash ?? null,
+        externalId: input.externalId ?? null,
+        transactionId: input.transactionId ?? null,
+        detail: input.detail ?? null,
+    })
+        .onConflictDoNothing();
+}
+//# sourceMappingURL=reconciliation-finding.service.js.map

package/dist/wallet/service/reconciliation-finding.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliation-finding.service.js","sourceRoot":"","sources":["../../../src/wallet/service/reconciliation-finding.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,sCAAsC,CAAC;AAuB1E;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,EAAyB,EACzB,KAAiC;IAEjC,MAAM,EAAE;SACL,MAAM,CAAC,2BAA2B,CAAC;SACnC,MAAM,CAAC;QACN,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,IAAI;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;QAC1C,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;KAC7B,CAAC;SACD,mBAAmB,EAAE,CAAC;AAC3B,CAAC"}

package/dist/wallet/service/reconciliation.service.d.ts

@@ -0,0 +1,112 @@
+import { type DrizzleService, type EventBus } from '@openora/core/server';
+import { type AuditWritePort, type ClientMeta, type PaymentProviderRegistry, type PaymentWebhookEvent, type PlatformConfig, type User } from '@openora/core/contracts';
+import { type WalletJobRun, type WalletReconciliationFinding as WalletReconciliationFindingRow, type WalletTransaction } from '../schema/index.js';
+import type { ListReconciliationFindingsInput, ReconciliationResolution, WalletReconciliationFinding as WalletReconciliationFindingDto } from '../contract/index.js';
+import type { WalletService } from './wallet.service.js';
+export declare const ReconciliationFindingNotFoundError: new (id: string) => Error;
+export declare const ReconciliationCreditTransactionNotFoundError: new (id: string) => Error;
+export declare const ReconciliationCreditMismatchError: new () => Error;
+type LedgerMatch = Pick<WalletTransaction, 'id' | 'currency' | 'amount' | 'network'>;
+/**
+ * Pure diff of one vendor deposit event against its (maybe absent) ledger row - the
+ * whole decision reconciliation makes for a deposit, extracted so it is unit-testable
+ * without a database. Never routes through moneyToNumber (see money.md): an exact
+ * decimal compare, not a float one.
+ */
+export declare function diffDeposit(event: Extract<PaymentWebhookEvent, {
+    kind: 'deposit';
+}>, tx: LedgerMatch | undefined): 'missing_deposit' | 'currency_mismatch' | 'amount_mismatch' | null;
+export type ReconciliationServiceDeps = {
+    drizzle: DrizzleService;
+    events: EventBus;
+    wallet: WalletService;
+    paymentProviders: PaymentProviderRegistry;
+    audit: AuditWritePort;
+    platformConfig?: PlatformConfig;
+};
+/**
+ * Owns the reconciliation job cycle (claim -> per-provider diff -> stuck-withdrawal /
+ * stuck-sweep sweep -> finish + audit + alert) and the admin surface over its findings
+ * (list/resolve). Never credits or moves money itself - every finding is a report; the
+ * only paths that touch a balance are `WalletService.reconcileWithdrawalStatus` (already
+ * idempotent) and the pre-existing manual-adjustment path a `credited` resolution merely
+ * references.
+ */
+export declare class ReconciliationService {
+    private readonly drizzle;
+    private readonly events;
+    private readonly wallet;
+    private readonly paymentProviders;
+    private readonly audit;
+    private readonly platformConfig?;
+    constructor({ drizzle, events, wallet, paymentProviders, audit, platformConfig, }: ReconciliationServiceDeps);
+    listFindings(filter: ListReconciliationFindingsInput): Promise<{
+        items: {
+            id: string;
+            runId: string;
+            providerName: string;
+            kind: "missing_deposit" | "unattributed_deposit" | "amount_mismatch" | "currency_mismatch" | "status_mismatch" | "unknown_at_provider" | "unconfigured_asset" | "stuck_sweep";
+            currency: string | null;
+            network: string | null;
+            amount: string | null;
+            address: string | null;
+            tag: string | null;
+            txHash: string | null;
+            externalId: string | null;
+            transactionId: string | null;
+            detail: string | null;
+            status: "open" | "resolved";
+            resolvedBy: string | null;
+            resolvedAt: string | null;
+            resolutionNote: string | null;
+            createdAt: string;
+        }[];
+        total: number;
+        page: number;
+        limit: number;
+    }>;
+    /**
+     * Conditional `UPDATE ... WHERE status = 'open'` is the whole double-resolve guard -
+     * a second resolve of an already-resolved finding matches zero rows and returns the
+     * row unchanged, with no second audit entry. `credited` requires the referenced
+     * transaction to already exist (the manual-adjustment path creates it - this never
+     * credits anything itself) and match the finding's currency/amount exactly.
+     */
+    resolveFinding(adminId: User['id'], id: WalletReconciliationFindingRow['id'], resolution: ReconciliationResolution, meta?: ClientMeta): Promise<WalletReconciliationFindingDto>;
+    /**
+     * The window is anchored to the last completed run, not to the wall clock. BullMQ
+     * repeatable jobs are delayed jobs: a tick missed while no worker was running is
+     * skipped, never backfilled. Against a fixed `now - lookbackHours` window that means
+     * any outage longer than `lookbackHours` leaves a span nothing ever reconciles and
+     * nothing ever reports - the worst possible failure mode for a compensating control.
+     * Catching up is capped, and a capped window is reported rather than passed over.
+     */
+    private resolveWindow;
+    /**
+     * Claim -> per-provider deposit/withdrawal diff -> stuck-withdrawal / stuck-sweep
+     * sweep -> finish + one audit entry + an alert past threshold. Returns null without
+     * doing any work when another cycle already owns the claim - the caller (cron tick or
+     * the on-demand route's worker) treats that as a normal, expected outcome.
+     */
+    runCycle(runId?: WalletJobRun['runId']): Promise<{
+        runId: WalletJobRun['runId'];
+    } | null>;
+    private reconcileProvider;
+    private sweptExternalIds;
+    private reconcileDeposits;
+    private batchLookupByProviderRefId;
+    private reconcileStuckWithdrawals;
+    private reconcileStuckSweeps;
+    private countOpenFindings;
+    /**
+     * The claim IS the insert - a partial unique index on (jobName) WHERE finishedAt IS
+     * NULL makes a conflicting insert the concurrency guard. A stale in-flight run (older
+     * than the configured staleness window - presumed crashed) is marked `abandoned` and its slot freed
+     * for this call to retry the claim once.
+     */
+    private claimRun;
+    private retryClaim;
+    private finishRun;
+}
+export {};
+//# sourceMappingURL=reconciliation.service.d.ts.map

package/dist/wallet/service/reconciliation.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliation.service.d.ts","sourceRoot":"","sources":["../../../src/wallet/service/reconciliation.service.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,QAAQ,EAQd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,IAAI,EAEV,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,2BAA2B,IAAI,8BAA8B,EAClE,KAAK,iBAAiB,EACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,+BAA+B,EAC/B,wBAAwB,EACxB,2BAA2B,IAAI,8BAA8B,EAC9D,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAKzD,eAAO,MAAM,kCAAkC,2BAA6C,CAAC;AAE7F,eAAO,MAAM,4CAA4C,2BAExD,CAAC;AAEF,eAAO,MAAM,iCAAiC,iBAG7C,CAAC;AAEF,KAAK,WAAW,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC;AAErF;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,CAAC,mBAAmB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,EACxD,EAAE,EAAE,WAAW,GAAG,SAAS,GAC1B,iBAAiB,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,IAAI,CAWpE;AAmCD,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,aAAa,CAAC;IACtB,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,KAAK,EAAE,cAAc,CAAC;IACtB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA0B;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;gBAErC,EACV,OAAO,EACP,MAAM,EACN,MAAM,EACN,gBAAgB,EAChB,KAAK,EACL,cAAc,GACf,EAAE,yBAAyB;IAStB,YAAY,CAAC,MAAM,EAAE,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;IAiC1D;;;;;;OAMG;IACG,cAAc,CAClB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,EACnB,EAAE,EAAE,8BAA8B,CAAC,IAAI,CAAC,EACxC,UAAU,EAAE,wBAAwB,EACpC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,8BAA8B,CAAC;IAkF1C;;;;;;;OAOG;YACW,aAAa;IAyB3B;;;;;OAKG;IACG,QAAQ,CACZ,KAAK,GAAE,YAAY,CAAC,OAAO,CAAgB,GAC1C,OAAO,CAAC;QAAE,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;YAqFrC,iBAAiB;YA2CjB,gBAAgB;YAahB,iBAAiB;YAgDjB,0BAA0B;YAoB1B,yBAAyB;YAmEzB,oBAAoB;YAsCpB,iBAAiB;IAQ/B;;;;;OAKG;YACW,QAAQ;YAkCR,UAAU;YAaV,SAAS;CAUxB"}