@riocrypto/common-server 1.0.2880 → 1.0.2881

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/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.2880",
+  "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",