@openora/core 0.4.0 → 0.4.1-canary.100

package/dist/compliance/service/kyc.service.d.ts

@@ -1,7 +1,9 @@
 import { DrizzleService, type EventBus } from '@openora/core/server';
-import type { KycAdapter, KycStatusWriter, KycVendorStatus, PlatformConfig } from '@openora/core/contracts';
-import type { SubmitKycInput, PlayerKycView } from '../contract/index.js';
+import { type KycAdapter, type KycCheckResult, type KycDocument, type KycRiskSignals, type KycStatusWriter, type KycVendorStatus, type PlatformConfig, type IdentityReader, type User, ClientMeta } from '@openora/core/contracts';
+import type { SubmitKycInput, PlayerKycView, KycOverrideStatus, BulkApproveKycResult } from '../contract/index.js';
 import { type ReKycTrigger } from './re-kyc-trigger.js';
+export declare const PlayerNotFoundError: new (id: string) => Error;
+export declare const KycVerificationNotFoundError: new (id: string) => Error;
 /**
  * Owns the append-only `kyc_verification` history and the submit/reconcile/re-KYC
  * lifecycle. All `player.kycStatus` writes go through the injected KycStatusWriter
@@ -12,6 +14,7 @@ export type KycVerificationDeps = {
     events: EventBus;
     kycAdapter: KycAdapter;
     statusWriter: KycStatusWriter;
+    identityReader: IdentityReader;
     platformConfig?: PlatformConfig;
     reKycTrigger?: ReKycTrigger;
 };
@@ -20,49 +23,194 @@ export declare class KycVerificationService {
     private readonly events;
     private readonly kycAdapter;
     private readonly statusWriter;
+    private readonly identityReader;
     private readonly platformConfig?;
     private readonly reKycTrigger;
     constructor(deps: KycVerificationDeps);
     private get provider();
-    submit(userId: string, input: SubmitKycInput): Promise<{
+    submit(userId: User['id'], input: SubmitKycInput, meta?: ClientMeta): Promise<{
+        verificationUrl: string | undefined;
+        status: "pending" | "not_started" | "approved" | "verified" | "rejected" | "resubmission_requested" | "manually_overridden";
         id: string;
         userId: string;
+        checks: {
+            step: string;
+            status: "expired" | "unknown" | "not_started" | "approved" | "in_progress" | "in_review" | "declined";
+        }[] | null;
         provider: string;
         referenceId: string;
-        status: "pending" | "not_started" | "verified" | "rejected" | "resubmission_requested" | "manually_overridden";
+        triggeredBy: "manual" | "submission" | "reverify_threshold";
         documentTypes: ("passport" | "drivers_license" | "national_id")[];
         decisionReason: string | null;
-        triggeredBy: "manual" | "submission" | "reverify_threshold";
-        submittedAt: string;
-        decidedAt: string | null;
+        riskSignals: KycRiskSignals | null;
+        triggerDeposits: string | null;
+        decisionReceivedAt: Date | null;
         createdAt: string;
         updatedAt: string;
+        submittedAt: string;
+        decidedAt: string;
     }>;
     /**
      * Idempotent vendor-decision apply (polling + webhook). No-op when the latest record
-     * already holds the mapped status.
+     * already holds the mapped status. `reason`/`documentTypes`/`riskSignals` are only
+     * overwritten when the caller supplies them, and `decidedAt` is stamped only on an
+     * actual decision, so a bare status reconcile never blanks out an earlier one. Emits
+     * `compliance.kyc.high_risk_signal_detected` when the supplied `riskSignals` (never a
+     * preserved prior value) trip `warrantsHighRiskTag`.
+     *
+     * `opts.receivedAt` (when the caller has it - the `kyc-decision-sync` job path always
+     * does, stamped at webhook-arrival time in the router, BEFORE the job queue can
+     * reorder anything) is a monotonicity guard: a decision older than the one already on
+     * file for this referenceId is refused, not applied. The job queue does not honour
+     * `orderingKey` (see bullmq-job-queue.ts), so two decisions for the same reference can
+     * reach here out of arrival order after a retry; without this guard the LATER-arriving
+     * (but actually OLDER) decision would win and silently overwrite a newer, correct one.
+     * A caller with no `receivedAt` (eg a direct `reconcile` call with no job path behind
+     * it) skips the guard entirely - always applies, exactly as before.
+     *
+     * A vendor `approved` is downgraded to `resubmission_requested` when the checks this
+     * call is about to persist (`opts.checks`, falling back to the existing row's `checks`
+     * when the caller supplies none - the SAME value written below, so the gate can never
+     * evaluate a different set of checks than the one that ends up on the row) contain any
+     * non-`approved` entry.
      */
-    reconcile(referenceId: string, vendorStatus: KycVendorStatus, reason?: string): Promise<{
+    reconcile(referenceId: string, vendorStatus: KycVendorStatus, opts?: {
+        reason?: string;
+        documentTypes?: KycDocument['type'][];
+        riskSignals?: KycRiskSignals;
+        checks?: KycCheckResult[];
+        receivedAt?: Date;
+    }): Promise<import("@openora/core/server").SerializedRow<{
+        status: "pending" | "not_started" | "approved" | "verified" | "rejected" | "resubmission_requested" | "manually_overridden";
         id: string;
         userId: string;
+        checks: {
+            step: string;
+            status: "expired" | "unknown" | "not_started" | "approved" | "in_progress" | "in_review" | "declined";
+        }[] | null;
+        createdAt: Date;
+        updatedAt: Date;
         provider: string;
         referenceId: string;
-        status: "pending" | "not_started" | "verified" | "rejected" | "resubmission_requested" | "manually_overridden";
+        triggeredBy: "manual" | "submission" | "reverify_threshold";
+        submittedAt: Date;
         documentTypes: ("passport" | "drivers_license" | "national_id")[];
         decisionReason: string | null;
+        riskSignals: KycRiskSignals | null;
+        decidedAt: Date | null;
+        triggerDeposits: string | null;
+        decisionReceivedAt: Date | null;
+    }, "createdAt" | "updatedAt" | "submittedAt" | "decidedAt"> | null>;
+    /**
+     * `kyc-decision-sync` job handler, run off the webhook request path. Enriches the
+     * reconcile through `resolveDecision`/`resolveRiskSignals` when the bound adapter
+     * implements them, falling back to a status-only reconcile when it does not. Errors
+     * (notably `PlayerNotFoundError`) propagate so the job queue retries the decision.
+     * `receivedAt` is the webhook's
+     * arrival time (stamped by the router before enqueue, carried on the job payload) -
+     * passed through to `reconcile` as the monotonicity watermark so a job that runs
+     * out of arrival order (the driver ignores `orderingKey`) can't overwrite a newer
+     * decision with a stale one.
+     */
+    syncDecision(referenceId: string, status: KycVendorStatus, receivedAt?: Date): Promise<import("@openora/core/server").SerializedRow<{
+        status: "pending" | "not_started" | "approved" | "verified" | "rejected" | "resubmission_requested" | "manually_overridden";
+        id: string;
+        userId: string;
+        checks: {
+            step: string;
+            status: "expired" | "unknown" | "not_started" | "approved" | "in_progress" | "in_review" | "declined";
+        }[] | null;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: string;
+        referenceId: string;
         triggeredBy: "manual" | "submission" | "reverify_threshold";
-        submittedAt: string;
-        decidedAt: string | null;
-        createdAt: string;
-        updatedAt: string;
-    } | null>;
-    getForPlayer(userId: string): Promise<PlayerKycView>;
+        submittedAt: Date;
+        documentTypes: ("passport" | "drivers_license" | "national_id")[];
+        decisionReason: string | null;
+        riskSignals: KycRiskSignals | null;
+        decidedAt: Date | null;
+        triggerDeposits: string | null;
+        decisionReceivedAt: Date | null;
+    }, "createdAt" | "updatedAt" | "submittedAt" | "decidedAt"> | null>;
+    getForPlayer(userId: User['id']): Promise<PlayerKycView>;
     /**
-     * Deposit-event hook: flips a currently-verified player to `resubmission_requested`
+     * Deposit-event hook: flips a currently-approved player to `resubmission_requested`
      * once cumulative deposits cross a fresh per-currency threshold band. Idempotent twice
-     * over: skips unless presently `verified`, and the watermark stops a re-verified
+     * over: skips unless presently approved, and the watermark stops a re-approved
      * high-roller re-firing on every later deposit.
      */
-    handleDeposit(userId: string): Promise<void>;
+    handleDeposit(userId: User['id']): Promise<void>;
+    /**
+     * Shared transaction body for `requestResubmission`/`overrideStatus`: inserts the
+     * manual `kyc_verification` history row and calls `KYC_STATUS_WRITER.setStatus` in
+     * the SAME transaction so the locking and idempotency rules cannot diverge between
+     * the two call sites. Caller has already run the idempotency pre-check
+     * (`requirePlayerRowForUpdate` + a status compare) before calling this.
+     */
+    private applyManualDecision;
+    /**
+     * Admin-initiated: requests the player resubmit documents. Idempotent on a repeat
+     * call while the player is already at `resubmission_requested` - no duplicate history
+     * row or `compliance.kyc.updated` emit.
+     */
+    requestResubmission(userId: User['id'], reason: string, actorId: User['id']): Promise<import("@openora/core/server").SerializedRow<{
+        status: "pending" | "not_started" | "approved" | "verified" | "rejected" | "resubmission_requested" | "manually_overridden";
+        id: string;
+        userId: string;
+        checks: {
+            step: string;
+            status: "expired" | "unknown" | "not_started" | "approved" | "in_progress" | "in_review" | "declined";
+        }[] | null;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: string;
+        referenceId: string;
+        triggeredBy: "manual" | "submission" | "reverify_threshold";
+        submittedAt: Date;
+        documentTypes: ("passport" | "drivers_license" | "national_id")[];
+        decisionReason: string | null;
+        riskSignals: KycRiskSignals | null;
+        decidedAt: Date | null;
+        triggerDeposits: string | null;
+        decisionReceivedAt: Date | null;
+    }, "createdAt" | "updatedAt" | "submittedAt" | "decidedAt">>;
+    /**
+     * Admin-initiated: forces the player to an operator-chosen status, guarded by the
+     * router's `compliance:override-limit`. `resolveManualStatus` remaps an `approved`
+     * choice to `manually_overridden`; every other choice is written verbatim. Idempotent
+     * on a repeat call resolving to the status the player already holds.
+     */
+    overrideStatus(userId: User['id'], status: KycOverrideStatus, reason: string, actorId: User['id']): Promise<import("@openora/core/server").SerializedRow<{
+        status: "pending" | "not_started" | "approved" | "verified" | "rejected" | "resubmission_requested" | "manually_overridden";
+        id: string;
+        userId: string;
+        checks: {
+            step: string;
+            status: "expired" | "unknown" | "not_started" | "approved" | "in_progress" | "in_review" | "declined";
+        }[] | null;
+        createdAt: Date;
+        updatedAt: Date;
+        provider: string;
+        referenceId: string;
+        triggeredBy: "manual" | "submission" | "reverify_threshold";
+        submittedAt: Date;
+        documentTypes: ("passport" | "drivers_license" | "national_id")[];
+        decisionReason: string | null;
+        riskSignals: KycRiskSignals | null;
+        decidedAt: Date | null;
+        triggerDeposits: string | null;
+        decisionReceivedAt: Date | null;
+    }, "createdAt" | "updatedAt" | "submittedAt" | "decidedAt">>;
+    /**
+     * Admin-initiated: approves every listed player through the same
+     * `overrideStatus('approved', ...)` path, so a bulk approval is recorded identically
+     * to a single one. Bounded fan-out with per-player error isolation - one failure is
+     * captured as a result row rather than aborting the batch, and the returned message
+     * is a fixed string, never the raw exception text.
+     */
+    bulkApprove(userIds: User['id'][], reason: string, actorId: User['id']): Promise<BulkApproveKycResult[]>;
+    private requirePlayerRowForUpdate;
+    private latestVerificationOrThrow;
 }
 //# sourceMappingURL=kyc.service.d.ts.map

package/dist/compliance/service/kyc.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kyc.service.d.ts","sourceRoot":"","sources":["../../../src/compliance/service/kyc.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,eAAe,EAEf,cAAc,EACf,MAAM,yBAAyB,CAAC;AAOjC,OAAO,KAAK,EAEV,cAAc,EACd,aAAa,EACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAiC,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAsCvF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,QAAQ,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,eAAe,CAAC;IAC9B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;IAC/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAEhC,IAAI,EAAE,mBAAmB;IASrC,OAAO,KAAK,QAAQ,GAEnB;IAEK,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc;;;;;;;;;;;;;;IA4BlD;;;OAGG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;;;;;;;;;;IA2B7E,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAS1D;;;;;OAKG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM;CA2DnC"}
+{"version":3,"file":"kyc.service.d.ts","sourceRoot":"","sources":["../../../src/compliance/service/kyc.service.ts"],"names":[],"mappings":"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"}