@riocrypto/common-server 1.0.2879 → 1.0.2881

package/build/helpers/get-processor.js

@@ -31,8 +31,11 @@ const getProcessor = ({ country, fiat, side, isBinanceRFQ, routingConfig, disabl
     ];
     // Applied only inside the branches that genuinely have more than one rail, so
     // a stray rule cannot hijack structural routing (COP, USD in the US or Mexico)
-    // or bypass the country checks below. Returns undefined when no rule is
-    // configured, leaving the corridor's structural default in charge.
+    // or bypass the country checks below. Answers even when no rule is configured,
+    // because the corridor default is only safe to use once the rails the customer
+    // has switched off are out of the running. Undefined is left for the one case
+    // that genuinely belongs to structural routing: a custom Rio bank account whose
+    // rail we do not know.
     const trySplit = () => {
         const routed = (0, resolve_processor_1.resolveProcessor)({
             country,
@@ -62,10 +65,11 @@ const getProcessor = ({ country, fiat, side, isBinanceRFQ, routingConfig, disabl
         }
         return undefined;
     };
-    // The rail this corridor runs on when no split decides it, from the one table
-    // the routing editor reads as well - so the page can name the rail an empty
-    // split leaves in charge. Throwing on a missing entry keeps the two honest: a
-    // corridor that gets this far has to have a default.
+    // The rail a corridor with nothing to decide runs on, from the one table the
+    // routing editor reads as well, so the page can name it. Reached by corridors
+    // with a single rail, and by the unknown-rail custom account case. Throwing on
+    // a missing entry keeps the two honest: a corridor that gets this far has to
+    // have a default.
     const structural = () => {
         const fallback = (0, common_1.getDefaultProcessor)(country, fiat, purpose, excludedProcessors);
         if (!fallback) {

package/build/helpers/payin-destinations.d.ts

@@ -13,6 +13,17 @@ export interface PayinBankDetails {
     NIT?: string;
 }
 export declare const PER_USER_PAYIN_PROCESSORS: Processor[];
+export declare const normalizeCci: (cci: string) => string;
+/**
+ * Whether a CCI is one of Rio's own Peru accounts.
+ *
+ * Rio funds Alfin from its Interbank accounts, so those transfers appear on the
+ * Alfin statement as ordinary interbank credits carrying Rio's own account as
+ * the payer. Anything reading the statement to attribute customer payments has
+ * to exclude them, or a treasury top-up would be credited to whichever customer
+ * order happened to be awaiting the same amount.
+ */
+export declare const isRioOwnPeruAccountCci: (cci?: string) => boolean;
 export declare const getPayinBankDetails: ({ mongoose, processor, fiat, country, user, }: {
     mongoose: Mongoose;
     processor: Processor;

package/build/helpers/payin-destinations.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getPayinDestinations = exports.getPayinBankDetails = exports.PER_USER_PAYIN_PROCESSORS = void 0;
+exports.getPayinDestinations = exports.getPayinBankDetails = exports.isRioOwnPeruAccountCci = exports.normalizeCci = exports.PER_USER_PAYIN_PROCESSORS = void 0;
 const common_1 = require("@riocrypto/common");
 const rio_bank_account_1 = require("../models/rio-bank-account");
 const STP_deposit_CLABE_1 = require("../models/STP-deposit-CLABE");
@@ -40,6 +40,34 @@ const ALFIN_ACCOUNT_NUMBER_BY_FIAT = {
     [common_1.Fiat.PEN]: "01818233900001",
     [common_1.Fiat.USD]: "01818233900002",
 };
+const INTERBANK_PERU_CCI_BY_FIAT = {
+    [common_1.Fiat.PEN]: "003-200-003004741070-36",
+    [common_1.Fiat.USD]: "003-200-003004741088-38",
+};
+// Digits-only form of a Peruvian CCI. Banks present them either grouped with
+// dashes or bare, and Alfin reports the bare form inside a statement line's
+// referencia, so both have to reduce to the same string to be comparable.
+const normalizeCci = (cci) => cci.replace(/\D/g, "");
+exports.normalizeCci = normalizeCci;
+const RIO_PERU_OWN_CCIS = Object.values(INTERBANK_PERU_CCI_BY_FIAT)
+    .filter((cci) => Boolean(cci))
+    .map(exports.normalizeCci);
+/**
+ * Whether a CCI is one of Rio's own Peru accounts.
+ *
+ * Rio funds Alfin from its Interbank accounts, so those transfers appear on the
+ * Alfin statement as ordinary interbank credits carrying Rio's own account as
+ * the payer. Anything reading the statement to attribute customer payments has
+ * to exclude them, or a treasury top-up would be credited to whichever customer
+ * order happened to be awaiting the same amount.
+ */
+const isRioOwnPeruAccountCci = (cci) => {
+    if (!cci) {
+        return false;
+    }
+    return RIO_PERU_OWN_CCIS.includes((0, exports.normalizeCci)(cci));
+};
+exports.isRioOwnPeruAccountCci = isRioOwnPeruAccountCci;
 // Shared house accounts. Kept here rather than in the order-payment path so the
 // customer-facing whitelisting list and the payment instructions on an order can
 // never drift apart.
@@ -78,7 +106,7 @@ const getStaticPayinBankDetails = (processor, fiat) => {
                 companyName: PERU_COMPANY_NAME,
                 companyAddress: PERU_COMPANY_ADDRESS,
                 accountNumber: "200-3004741070",
-                CCI: "003-200-003004741070-36",
+                CCI: INTERBANK_PERU_CCI_BY_FIAT[common_1.Fiat.PEN],
                 RUC: PERU_RUC,
             };
         }
@@ -88,7 +116,7 @@ const getStaticPayinBankDetails = (processor, fiat) => {
                 companyName: PERU_COMPANY_NAME,
                 companyAddress: PERU_COMPANY_ADDRESS,
                 accountNumber: "200-3004741088",
-                CCI: "003-200-003004741088-38",
+                CCI: INTERBANK_PERU_CCI_BY_FIAT[common_1.Fiat.USD],
                 RUC: PERU_RUC,
             };
         }

package/build/helpers/resolve-processor.d.ts

@@ -13,6 +13,6 @@ export interface ResolveProcessorParams {
 }
 export interface ResolveProcessorResult {
     processor?: Processor;
-    reason: "customRioBankAccount" | "customRioBankAccountWithoutRail" | "split" | "onlyCandidate" | "enabledRailWithoutShare" | "noRuleConfigured" | "noEligibleCandidate" | "noEnabledCandidate";
+    reason: "customRioBankAccount" | "customRioBankAccountWithoutRail" | "split" | "onlyCandidate" | "enabledRailWithoutShare" | "noEligibleCandidate" | "noEnabledCandidate";
 }
 export declare const resolveProcessor: ({ country, fiat, purpose, routingConfig, excludedProcessors, disabledProcessors, customRioBankAccount, randomSeed, }: ResolveProcessorParams) => ResolveProcessorResult;

package/build/helpers/resolve-processor.js

@@ -23,11 +23,11 @@ const pickByShare = (candidates, position) => {
 // from the configured split.
 //
 // A percentage divides volume between the rails that are actually available to
-// the customer; it is not a switch. A rail left at zero, or left out of the rule
-// altogether, still takes their orders when it is the only one they have left
-// enabled, which is why the candidate set comes from the corridor rather than
-// from the rule. Switching a rail off is the only way to keep an order away from
-// it.
+// the customer; it is not a switch. A rail left at zero, left out of the rule, or
+// belonging to a corridor with no rule at all still takes their orders when it is
+// the only one they have left enabled, which is why the candidate set comes from
+// the corridor rather than from the rule. Switching a rail off is the only way to
+// keep an order away from it.
 //
 // Does no IO of its own - the routing config and the user's readiness are passed
 // in - and the only nondeterminism is the per-order roll, which a caller can
@@ -73,10 +73,12 @@ const resolveProcessor = ({ country, fiat, purpose, routingConfig, excludedProce
         }
         return { processor, reason: "customRioBankAccount" };
     }
+    // An absent rule is read as every rail at zero rather than as a reason to stop.
+    // Bailing out here would hand the decision to the structural default, which
+    // knows nothing about which rails the customer accepts, and every corridor is
+    // ruleless until an admin first saves one - as is any corridor whose shares
+    // were all cleared, since the settings page stores that as no rule at all.
     const rule = getRule(routingConfig, country, fiat, purpose);
-    if (!rule) {
-        return { reason: "noRuleConfigured" };
-    }
     // Starts from the corridor's rails rather than from the rails the rule names,
     // because a percentage decides how volume is divided between the rails a
     // customer can use - it is not what makes a rail usable. Also drops any share
@@ -91,16 +93,20 @@ const resolveProcessor = ({ country, fiat, purpose, routingConfig, excludedProce
         return { reason: "noEnabledCandidate" };
     }
     const shares = candidates
-        .map((processor) => ({
-        processor,
-        percentage: Number(rule.percentages[processor]) || 0,
-    }))
+        .map((processor) => {
+        var _a;
+        return ({
+            processor,
+            percentage: Number((_a = rule === null || rule === void 0 ? void 0 : rule.percentages) === null || _a === void 0 ? void 0 : _a[processor]) || 0,
+        });
+    })
         .filter((candidate) => candidate.percentage > 0);
-    // None of the rails this customer can use carries a share, so there is no split
-    // to draw from. Refusing the order would read a zero as "never use this rail",
-    // when all it says is where volume goes while there is somewhere else to send
-    // it. Prefers the corridor default and otherwise the corridor's own order, so
-    // the rail a customer in this position gets is predictable rather than rolled.
+    // None of the rails this customer can use carries a share - or no rule is
+    // configured at all - so there is no split to draw from. Refusing the order
+    // would read a zero as "never use this rail", when all it says is where volume
+    // goes while there is somewhere else to send it. Prefers the corridor default
+    // and otherwise the corridor's own order, so the rail a customer in this
+    // position gets is predictable rather than rolled.
     if (!shares.length) {
         const fallback = (0, common_1.getDefaultProcessor)(country, fiat, purpose, excludedProcessors);
         return {

package/build/index.d.ts

@@ -95,6 +95,8 @@ export * from "./models/alfin-virtual-cci";
 export * from "./models/alfin-settings";
 export * from "./models/alfin-withdrawal";
 export * from "./models/alfin-payin-notification";
+export * from "./models/alfin-payin-origin";
+export * from "./models/alfin-statement-credit";
 export * from "./models/alfin-webhook-token";
 export * from "./models/dashboard-push-notification-subscription";
 export * from "./models/webauthn-credential";

package/build/index.js

@@ -111,6 +111,8 @@ __exportStar(require("./models/alfin-virtual-cci"), exports);
 __exportStar(require("./models/alfin-settings"), exports);
 __exportStar(require("./models/alfin-withdrawal"), exports);
 __exportStar(require("./models/alfin-payin-notification"), exports);
+__exportStar(require("./models/alfin-payin-origin"), exports);
+__exportStar(require("./models/alfin-statement-credit"), exports);
 __exportStar(require("./models/alfin-webhook-token"), exports);
 __exportStar(require("./models/dashboard-push-notification-subscription"), exports);
 __exportStar(require("./models/webauthn-credential"), exports);

package/build/models/alfin-payin-notification.d.ts

@@ -19,6 +19,8 @@ interface AlfinPayinNotificationDoc extends Document {
     amount: number;
     processedAt: Date;
     payload: Record<string, any>;
+    processingCompletedAt?: Date | null;
+    reconciledStatementCreditKey?: string;
 }
 interface AlfinPayinNotificationModel extends Model<AlfinPayinNotificationDoc> {
     build(attrs: AlfinPayinNotificationAttrs): HydratedDocument<AlfinPayinNotificationDoc>;

package/build/models/alfin-payin-notification.js

@@ -37,6 +37,17 @@ const buildAlfinPayinNotification = (mongoose) => {
         payload: {
             type: mongoose.Schema.Types.Mixed,
         },
+        // Defaulted so every new notification carries the field explicitly, which
+        // is what separates one that has not finished from one written before this
+        // existed. A query that cannot tell those apart either credits a payin
+        // twice or not at all.
+        processingCompletedAt: {
+            type: mongoose.Schema.Types.Date,
+            default: null,
+        },
+        reconciledStatementCreditKey: {
+            type: String,
+        },
     }, {
         toJSON: {
             transform(doc, ret) {
@@ -46,6 +57,12 @@ const buildAlfinPayinNotification = (mongoose) => {
             },
         },
     });
+    // Supports the claim lookup, which searches unclaimed notifications by
+    // currency and amount within a few days of a statement line.
+    AlfinPayinNotificationSchema.index({ fiat: 1, amount: 1, processedAt: 1 });
+    // One statement line can only ever be the same money as one notification.
+    // Sparse so the unclaimed majority are not indexed as duplicate nulls.
+    AlfinPayinNotificationSchema.index({ reconciledStatementCreditKey: 1 }, { unique: true, sparse: true });
     AlfinPayinNotificationSchema.statics.build = (attrs) => {
         return new AlfinPayinNotification(attrs);
     };

package/build/models/alfin-payin-origin.d.ts

@@ -0,0 +1,39 @@
+import { Mongoose, Model, Document, HydratedDocument } from "mongoose";
+type AlfinPayinOriginSource = "payinWebhook" | "payinVerification";
+interface AlfinPayinOriginAttrs {
+    CCI: string;
+    userId: string;
+    source: AlfinPayinOriginSource;
+    accountHolderName?: string;
+    firstSeenAt: Date;
+    lastSeenAt: Date;
+}
+interface AlfinPayinOriginDoc extends Document {
+    CCI: string;
+    userId: string;
+    source: AlfinPayinOriginSource;
+    accountHolderName?: string;
+    firstSeenAt: Date;
+    lastSeenAt: Date;
+}
+interface AlfinPayinOriginModel extends Model<AlfinPayinOriginDoc> {
+    build(attrs: AlfinPayinOriginAttrs): HydratedDocument<AlfinPayinOriginDoc>;
+}
+/**
+ * Accounts customers have paid us from at Alfin, learned as they pay.
+ *
+ * A payment that lands on a user's virtual CCI identifies its owner outright, so
+ * nothing here is needed to process it. It exists for payments that cannot use a
+ * virtual CCI at all - anything over the CCE immediate-transfer ceiling, which
+ * the CCIV rejects - because those land on the principal account, raise no
+ * notification, and are only visible as an account-statement credit. The
+ * statement carries the payer's CCI, so a customer's first small payment through
+ * their CCIV is what teaches us where their large ones will come from.
+ *
+ * One document per account/user pair rather than one per account: a shared
+ * corporate account can legitimately belong to more than one user, and a
+ * statement credit from an account claimed by two users cannot be attributed to
+ * either, which the matcher detects by finding more than one document.
+ */
+declare const buildAlfinPayinOrigin: (mongoose: Mongoose) => AlfinPayinOriginModel;
+export { buildAlfinPayinOrigin, AlfinPayinOriginDoc, AlfinPayinOriginAttrs, AlfinPayinOriginSource, };

package/build/models/alfin-payin-origin.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAlfinPayinOrigin = void 0;
+/**
+ * Accounts customers have paid us from at Alfin, learned as they pay.
+ *
+ * A payment that lands on a user's virtual CCI identifies its owner outright, so
+ * nothing here is needed to process it. It exists for payments that cannot use a
+ * virtual CCI at all - anything over the CCE immediate-transfer ceiling, which
+ * the CCIV rejects - because those land on the principal account, raise no
+ * notification, and are only visible as an account-statement credit. The
+ * statement carries the payer's CCI, so a customer's first small payment through
+ * their CCIV is what teaches us where their large ones will come from.
+ *
+ * One document per account/user pair rather than one per account: a shared
+ * corporate account can legitimately belong to more than one user, and a
+ * statement credit from an account claimed by two users cannot be attributed to
+ * either, which the matcher detects by finding more than one document.
+ */
+const buildAlfinPayinOrigin = (mongoose) => {
+    if (mongoose.models.AlfinPayinOrigin) {
+        return mongoose.model("AlfinPayinOrigin");
+    }
+    const AlfinPayinOriginSchema = new mongoose.Schema({
+        CCI: {
+            type: String,
+            required: true,
+        },
+        userId: {
+            type: String,
+            required: true,
+            index: true,
+        },
+        source: {
+            type: String,
+            required: true,
+        },
+        accountHolderName: {
+            type: String,
+        },
+        firstSeenAt: {
+            type: mongoose.Schema.Types.Date,
+            required: true,
+        },
+        lastSeenAt: {
+            type: mongoose.Schema.Types.Date,
+            required: true,
+        },
+    }, {
+        toJSON: {
+            transform(doc, ret) {
+                ret.id = ret._id.valueOf();
+                delete ret._id;
+                delete ret.__v;
+            },
+        },
+    });
+    AlfinPayinOriginSchema.index({ CCI: 1, userId: 1 }, { unique: true });
+    AlfinPayinOriginSchema.statics.build = (attrs) => {
+        return new AlfinPayinOrigin(attrs);
+    };
+    const AlfinPayinOrigin = mongoose.model("AlfinPayinOrigin", AlfinPayinOriginSchema);
+    return AlfinPayinOrigin;
+};
+exports.buildAlfinPayinOrigin = buildAlfinPayinOrigin;

package/build/models/alfin-statement-credit.d.ts

@@ -0,0 +1,55 @@
+import { Fiat } from "@riocrypto/common";
+import { Mongoose, Model, Document, HydratedDocument } from "mongoose";
+type AlfinStatementCreditStatus = "matched" | "attributedToWebhook" | "ignored" | "awaitingApproval" | "unmatched";
+interface AlfinStatementCreditAttrs {
+    uniqueCompositeKey: string;
+    movimientoUId: string;
+    ordinal?: number;
+    fiat: Fiat;
+    amount: number;
+    postedAt: Date;
+    concepto?: string;
+    referencia?: string;
+    originCCI?: string;
+    originName?: string;
+    status: AlfinStatementCreditStatus;
+    reason?: string;
+    userId?: string;
+    orderId?: string;
+    bulkBankPaymentId?: string;
+    evaluatedAt: Date;
+}
+interface AlfinStatementCreditDoc extends Document {
+    uniqueCompositeKey: string;
+    movimientoUId: string;
+    ordinal?: number;
+    fiat: Fiat;
+    amount: number;
+    postedAt: Date;
+    concepto?: string;
+    referencia?: string;
+    originCCI?: string;
+    originName?: string;
+    status: AlfinStatementCreditStatus;
+    reason?: string;
+    userId?: string;
+    orderId?: string;
+    bulkBankPaymentId?: string;
+    evaluatedAt: Date;
+}
+interface AlfinStatementCreditModel extends Model<AlfinStatementCreditDoc> {
+    build(attrs: AlfinStatementCreditAttrs): HydratedDocument<AlfinStatementCreditDoc>;
+}
+/**
+ * One record per account-statement credit we have evaluated for payment
+ * matching, and the decision we reached.
+ *
+ * The statement is re-read on every poll over a 30-day window, so this is what
+ * stops a credit from being attributed twice: the key is inserted before any
+ * matching happens, and a duplicate-key error means another run already owns
+ * this line. It doubles as the audit trail for why a credit was or was not
+ * attributed, which is the only record of that reasoning - the credit itself
+ * arrives with no notification behind it.
+ */
+declare const buildAlfinStatementCredit: (mongoose: Mongoose) => AlfinStatementCreditModel;
+export { buildAlfinStatementCredit, AlfinStatementCreditDoc, AlfinStatementCreditAttrs, AlfinStatementCreditStatus, };

package/build/models/alfin-statement-credit.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAlfinStatementCredit = void 0;
+/**
+ * One record per account-statement credit we have evaluated for payment
+ * matching, and the decision we reached.
+ *
+ * The statement is re-read on every poll over a 30-day window, so this is what
+ * stops a credit from being attributed twice: the key is inserted before any
+ * matching happens, and a duplicate-key error means another run already owns
+ * this line. It doubles as the audit trail for why a credit was or was not
+ * attributed, which is the only record of that reasoning - the credit itself
+ * arrives with no notification behind it.
+ */
+const buildAlfinStatementCredit = (mongoose) => {
+    if (mongoose.models.AlfinStatementCredit) {
+        return mongoose.model("AlfinStatementCredit");
+    }
+    const AlfinStatementCreditSchema = new mongoose.Schema({
+        uniqueCompositeKey: {
+            type: String,
+            required: true,
+            unique: true,
+        },
+        movimientoUId: {
+            type: String,
+            required: true,
+        },
+        ordinal: {
+            type: Number,
+        },
+        fiat: {
+            type: String,
+            required: true,
+        },
+        amount: {
+            type: Number,
+            required: true,
+        },
+        postedAt: {
+            type: mongoose.Schema.Types.Date,
+            required: true,
+        },
+        concepto: {
+            type: String,
+        },
+        referencia: {
+            type: String,
+        },
+        originCCI: {
+            type: String,
+        },
+        originName: {
+            type: String,
+        },
+        status: {
+            type: String,
+            required: true,
+        },
+        reason: {
+            type: String,
+        },
+        userId: {
+            type: String,
+        },
+        orderId: {
+            type: String,
+        },
+        bulkBankPaymentId: {
+            type: String,
+        },
+        evaluatedAt: {
+            type: mongoose.Schema.Types.Date,
+            required: true,
+        },
+    }, {
+        toJSON: {
+            transform(doc, ret) {
+                ret.id = ret._id.valueOf();
+                delete ret._id;
+                delete ret.__v;
+            },
+        },
+    });
+    AlfinStatementCreditSchema.statics.build = (attrs) => {
+        return new AlfinStatementCredit(attrs);
+    };
+    const AlfinStatementCredit = mongoose.model("AlfinStatementCredit", AlfinStatementCreditSchema);
+    return AlfinStatementCredit;
+};
+exports.buildAlfinStatementCredit = buildAlfinStatementCredit;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riocrypto/common-server",
-  "version": "1.0.2879",
+  "version": "1.0.2881",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -28,7 +28,7 @@
     "@google-cloud/secret-manager": "^5.6.0",
     "@google-cloud/storage": "^7.19.0",
     "@hyperdx/node-opentelemetry": "^0.10.3",
-    "@riocrypto/common": "1.0.2699",
+    "@riocrypto/common": "1.0.2702",
     "@slack/web-api": "^7.15.0",
     "@types/express": "^4.17.25",
     "axios": "1.18.1",