@riocrypto/common 1.0.2720 → 1.0.2721

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

@@ -0,0 +1,84 @@
+import { Country } from "../types/country";
+import { Fiat } from "../types/fiat";
+import { Processor } from "../types/processor";
+import { ProcessorRoutingPurpose, ProcessorRoutingRule, ProcessorRoutingWindow } from "../types/processor-routing";
+export interface ResolvedRoutingPercentages {
+    percentages: {
+        [key in Processor]?: number;
+    };
+    /** The window the percentages came from, absent when the base split was used. */
+    matchedWindow?: ProcessorRoutingWindow;
+}
+export declare const ROUTING_TOTAL_TOLERANCE = 0.01;
+/**
+ * Whether one window is usable on its own terms, ignoring its neighbours.
+ *
+ * Shares are checked here rather than only in the settings validator because
+ * this is also what the resolver trusts at routing time. A window whose shares
+ * do not add up would quietly renormalize into a split nobody chose, which is
+ * worse than falling back to the base split.
+ */
+export declare const isWellFormedProcessorRoutingWindow: (window: ProcessorRoutingWindow, country: Country, fiat: Fiat, purpose: ProcessorRoutingPurpose) => boolean;
+/**
+ * The split a corridor runs on right now, according to configuration alone.
+ *
+ * Kept here rather than inside `resolveProcessor` so the settings page can show
+ * an operator which window is live without a round trip, and so the two cannot
+ * disagree about which minute belongs to which window. Knows nothing about
+ * eligibility, enablement or the roll between rails, all of which stay in
+ * routing where the customer's records are.
+ *
+ * Malformed configuration falls back to the rule's own percentages rather than
+ * throwing. This sits on the path that prices every order, so a bad hand-edit in
+ * Mongo should cost the schedule rather than the corridor.
+ */
+export declare const resolveProcessorRoutingPercentages: (rule: ProcessorRoutingRule | undefined, country: Country, fiat: Fiat, purpose: ProcessorRoutingPurpose, now?: Date) => ResolvedRoutingPercentages;
+/**
+ * The single statement of the window coverage rule, shared by the throwing
+ * validator on the `rio-settings` PATCH and by the dashboard editor's inline
+ * check, so the two cannot disagree about what a valid schedule is.
+ *
+ * Returns a human-readable description of the first problem, or null when the
+ * list is acceptable. An empty list is acceptable and means no schedule.
+ *
+ * Order is significant and the list is deliberately not sorted first. If an
+ * operator's rows are out of order, saying so is more useful than silently
+ * reinterpreting what they wrote as something that happens to be valid.
+ */
+export declare const findProcessorRoutingWindowCoverageIssue: (windows: ProcessorRoutingWindow[], country: Country, fiat: Fiat, purpose: ProcessorRoutingPurpose) => string | null;
+/**
+ * Builds the contiguous day that covers the common case of "run a different
+ * split for one stretch of the afternoon", so neither the operator nor the
+ * dashboard has to assemble the filler rows by hand. Returns a single full-day
+ * window when the stretch covers everything.
+ *
+ * Requiring full coverage is what makes a stored schedule unambiguous. It should
+ * not also make the routine edit tedious.
+ */
+export declare const buildContiguousProcessorRoutingWindows: (basePercentages: {
+    interbank?: number | undefined;
+    swift?: number | undefined;
+    spei?: number | undefined;
+    spid?: number | undefined;
+    ksr?: number | undefined;
+    bridge?: number | undefined;
+    "spei-stp"?: number | undefined;
+    "spei-nvio"?: number | undefined;
+    "spei-fintoc"?: number | undefined;
+    "binance-rfq"?: number | undefined;
+    coltefinanciera?: number | undefined;
+    alfin?: number | undefined;
+}, windowPercentages: {
+    interbank?: number | undefined;
+    swift?: number | undefined;
+    spei?: number | undefined;
+    spid?: number | undefined;
+    ksr?: number | undefined;
+    bridge?: number | undefined;
+    "spei-stp"?: number | undefined;
+    "spei-nvio"?: number | undefined;
+    "spei-fintoc"?: number | undefined;
+    "binance-rfq"?: number | undefined;
+    coltefinanciera?: number | undefined;
+    alfin?: number | undefined;
+}, startMinute: number, endMinute: number) => ProcessorRoutingWindow[];

package/build/helpers/resolve-processor-routing-percentages.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildContiguousProcessorRoutingWindows = exports.findProcessorRoutingWindowCoverageIssue = exports.resolveProcessorRoutingPercentages = exports.isWellFormedProcessorRoutingWindow = exports.ROUTING_TOTAL_TOLERANCE = void 0;
+const fx_price_source_policy_1 = require("../types/fx-price-source-policy");
+const processor_routing_1 = require("../types/processor-routing");
+const get_country_timezone_1 = require("./get-country-timezone");
+const get_minute_of_day_in_timezone_1 = require("./get-minute-of-day-in-timezone");
+const get_processors_for_corridor_1 = require("./get-processors-for-corridor");
+// Entered by hand and allowed a decimal, so totals are compared with a tolerance
+// rather than exactly. Shared with the rule's own total so a window is held to
+// the same standard as the split it is standing in for.
+exports.ROUTING_TOTAL_TOLERANCE = 0.01;
+const isWholeMinute = (value) => typeof value === "number" && Number.isInteger(value);
+const sumPercentages = (percentages) => Object.values(percentages || {}).reduce((total, percentage) => total + (Number(percentage) || 0), 0);
+/**
+ * Whether one window is usable on its own terms, ignoring its neighbours.
+ *
+ * Shares are checked here rather than only in the settings validator because
+ * this is also what the resolver trusts at routing time. A window whose shares
+ * do not add up would quietly renormalize into a split nobody chose, which is
+ * worse than falling back to the base split.
+ */
+const isWellFormedProcessorRoutingWindow = (window, country, fiat, purpose) => {
+    if (!window || typeof window !== "object") {
+        return false;
+    }
+    const { startMinute, endMinute, percentages } = window;
+    if (!isWholeMinute(startMinute) || !isWholeMinute(endMinute)) {
+        return false;
+    }
+    if (startMinute < 0 || endMinute > fx_price_source_policy_1.MINUTES_IN_DAY) {
+        return false;
+    }
+    if (startMinute >= endMinute) {
+        return false;
+    }
+    if (typeof percentages !== "object" || percentages === null) {
+        return false;
+    }
+    const allowed = (0, get_processors_for_corridor_1.getProcessorsForCorridor)(country, fiat, purpose);
+    for (const [processor, percentage] of Object.entries(percentages)) {
+        if (!allowed.includes(processor)) {
+            return false;
+        }
+        if (typeof percentage !== "number" ||
+            !Number.isFinite(percentage) ||
+            percentage < 0 ||
+            percentage > 100) {
+            return false;
+        }
+    }
+    return (Math.abs(sumPercentages(percentages) - 100) <= exports.ROUTING_TOTAL_TOLERANCE);
+};
+exports.isWellFormedProcessorRoutingWindow = isWellFormedProcessorRoutingWindow;
+const windowMatchesMinute = (window, minuteOfDay) => minuteOfDay >= window.startMinute && minuteOfDay < window.endMinute;
+/**
+ * The split a corridor runs on right now, according to configuration alone.
+ *
+ * Kept here rather than inside `resolveProcessor` so the settings page can show
+ * an operator which window is live without a round trip, and so the two cannot
+ * disagree about which minute belongs to which window. Knows nothing about
+ * eligibility, enablement or the roll between rails, all of which stay in
+ * routing where the customer's records are.
+ *
+ * Malformed configuration falls back to the rule's own percentages rather than
+ * throwing. This sits on the path that prices every order, so a bad hand-edit in
+ * Mongo should cost the schedule rather than the corridor.
+ */
+const resolveProcessorRoutingPercentages = (rule, country, fiat, purpose, now = new Date()) => {
+    var _a;
+    const percentages = (rule === null || rule === void 0 ? void 0 : rule.percentages) || {};
+    if ((rule === null || rule === void 0 ? void 0 : rule.mode) !== processor_routing_1.ProcessorRoutingMode.Scheduled) {
+        return { percentages };
+    }
+    const windows = (_a = rule.windows) !== null && _a !== void 0 ? _a : [];
+    if (!Array.isArray(windows) || windows.length === 0) {
+        return { percentages };
+    }
+    const minuteOfDay = (0, get_minute_of_day_in_timezone_1.getMinuteOfDayInTimezone)(now, (0, get_country_timezone_1.getCountryTimezone)(country));
+    const matchedWindow = windows.find((window) => (0, exports.isWellFormedProcessorRoutingWindow)(window, country, fiat, purpose) &&
+        windowMatchesMinute(window, minuteOfDay));
+    // Validated windows cover the whole day, so a miss means the stored schedule
+    // is malformed or was written for a corridor that has since lost a rail.
+    if (!matchedWindow) {
+        return { percentages };
+    }
+    return { percentages: matchedWindow.percentages, matchedWindow };
+};
+exports.resolveProcessorRoutingPercentages = resolveProcessorRoutingPercentages;
+/**
+ * The single statement of the window coverage rule, shared by the throwing
+ * validator on the `rio-settings` PATCH and by the dashboard editor's inline
+ * check, so the two cannot disagree about what a valid schedule is.
+ *
+ * Returns a human-readable description of the first problem, or null when the
+ * list is acceptable. An empty list is acceptable and means no schedule.
+ *
+ * Order is significant and the list is deliberately not sorted first. If an
+ * operator's rows are out of order, saying so is more useful than silently
+ * reinterpreting what they wrote as something that happens to be valid.
+ */
+const findProcessorRoutingWindowCoverageIssue = (windows, country, fiat, purpose) => {
+    var _a;
+    if (!Array.isArray(windows)) {
+        return "windows must be an array";
+    }
+    if (windows.length === 0) {
+        return null;
+    }
+    for (let i = 0; i < windows.length; i += 1) {
+        if (!(0, exports.isWellFormedProcessorRoutingWindow)(windows[i], country, fiat, purpose)) {
+            const total = sumPercentages(((_a = windows[i]) === null || _a === void 0 ? void 0 : _a.percentages) || {});
+            return `window[${i}] needs whole-minute startMinute < endMinute within 0..${fx_price_source_policy_1.MINUTES_IN_DAY} and percentages adding up to 100 over ${(0, get_processors_for_corridor_1.getProcessorsForCorridor)(country, fiat, purpose).join(", ")}, got ${total}`;
+        }
+    }
+    if (windows[0].startMinute !== 0) {
+        return `window[0].startMinute must be 0`;
+    }
+    for (let i = 0; i < windows.length - 1; i += 1) {
+        if (windows[i + 1].startMinute !== windows[i].endMinute) {
+            return `windows must be contiguous: window[${i}].endMinute (${windows[i].endMinute}) must equal window[${i + 1}].startMinute (${windows[i + 1].startMinute})`;
+        }
+    }
+    const last = windows[windows.length - 1];
+    if (last.endMinute !== fx_price_source_policy_1.MINUTES_IN_DAY) {
+        return `window[${windows.length - 1}].endMinute must be ${fx_price_source_policy_1.MINUTES_IN_DAY} so the windows cover the full day`;
+    }
+    return null;
+};
+exports.findProcessorRoutingWindowCoverageIssue = findProcessorRoutingWindowCoverageIssue;
+/**
+ * Builds the contiguous day that covers the common case of "run a different
+ * split for one stretch of the afternoon", so neither the operator nor the
+ * dashboard has to assemble the filler rows by hand. Returns a single full-day
+ * window when the stretch covers everything.
+ *
+ * Requiring full coverage is what makes a stored schedule unambiguous. It should
+ * not also make the routine edit tedious.
+ */
+const buildContiguousProcessorRoutingWindows = (basePercentages, windowPercentages, startMinute, endMinute) => {
+    const windows = [];
+    if (startMinute > 0) {
+        windows.push({
+            startMinute: 0,
+            endMinute: startMinute,
+            percentages: Object.assign({}, basePercentages),
+        });
+    }
+    windows.push({
+        startMinute,
+        endMinute,
+        percentages: Object.assign({}, windowPercentages),
+    });
+    if (endMinute < fx_price_source_policy_1.MINUTES_IN_DAY) {
+        windows.push({
+            startMinute: endMinute,
+            endMinute: fx_price_source_policy_1.MINUTES_IN_DAY,
+            percentages: Object.assign({}, basePercentages),
+        });
+    }
+    return windows;
+};
+exports.buildContiguousProcessorRoutingWindows = buildContiguousProcessorRoutingWindows;

package/build/index.d.ts

@@ -591,6 +591,7 @@ export * from "./helpers/get-country-for-fiat";
 export * from "./helpers/get-minute-of-day-in-timezone";
 export * from "./helpers/resolve-fx-price-source";
 export * from "./helpers/get-processors-for-corridor";
+export * from "./helpers/resolve-processor-routing-percentages";
 export * from "./helpers/get-default-processor";
 export * from "./helpers/get-routing-candidates";
 export * from "./helpers/verifiable-payin-processors";

package/build/index.js

@@ -607,6 +607,7 @@ __exportStar(require("./helpers/get-country-for-fiat"), exports);
 __exportStar(require("./helpers/get-minute-of-day-in-timezone"), exports);
 __exportStar(require("./helpers/resolve-fx-price-source"), exports);
 __exportStar(require("./helpers/get-processors-for-corridor"), exports);
+__exportStar(require("./helpers/resolve-processor-routing-percentages"), exports);
 __exportStar(require("./helpers/get-default-processor"), exports);
 __exportStar(require("./helpers/get-routing-candidates"), exports);
 __exportStar(require("./helpers/verifiable-payin-processors"), exports);

package/build/types/processor-routing.d.ts

@@ -6,7 +6,54 @@ export declare enum ProcessorRoutingPurpose {
     Sell = "sell",
     BankAccountVerification = "bankAccountVerification"
 }
+export declare enum ProcessorRoutingMode {
+    /** Always use `percentages`. Windows are ignored. */
+    Manual = "manual",
+    /** Use the window covering the current local minute. */
+    Scheduled = "scheduled"
+}
+/**
+ * One time-of-day window naming the split a corridor runs on while it is
+ * active.
+ *
+ * Minutes are from midnight in the corridor country's local timezone and the
+ * window is `[startMinute, endMinute)`. Local time because the reason to schedule
+ * a split at all is somebody else's working day: a provider's support desk, a
+ * bank's clearing window, a treasury team arriving at their desks.
+ *
+ * Windows follow the same coverage rule as `FXPriceSourceWindow`, being ordered,
+ * strictly contiguous, first starting at 0 and last ending at 1440, so every
+ * minute of the day maps to exactly one window. Each window's percentages carry
+ * the same obligation as the rule's own, summing to 100 over rails the corridor
+ * serves, so there is never a stretch of the day whose split is partly stated.
+ *
+ * The cost is that moving one afternoon onto Fintoc takes three rows rather than
+ * one, each restating every rail. The benefit is that the configuration says what
+ * it means at every minute, an operator reading it back at 3am does not have to
+ * hold "and the rest of the day is the base split" in their head, and the editor
+ * can draw one unbroken day they can check at a glance. A window spanning
+ * midnight is written as two rows rather than wrapping.
+ */
+export interface ProcessorRoutingWindow {
+    startMinute: number;
+    endMinute: number;
+    percentages: {
+        [key in Processor]?: number;
+    };
+}
 export interface ProcessorRoutingRule {
+    /**
+     * Whether this corridor runs one split all day or a scheduled one.
+     *
+     * Absent means `Manual`, so every rule saved before scheduling existed keeps
+     * behaving exactly as it did.
+     */
+    mode?: ProcessorRoutingMode;
+    /**
+     * Ordered, contiguous windows covering `[0, 1440)`. Only consulted in
+     * `Scheduled` mode. Empty means no schedule.
+     */
+    windows?: ProcessorRoutingWindow[];
     percentages: {
         [key in Processor]?: number;
     };

package/build/types/processor-routing.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProcessorRoutingPurpose = void 0;
+exports.ProcessorRoutingMode = exports.ProcessorRoutingPurpose = void 0;
 // What a rule routes. Buy and Sell deliberately carry the same values as the
 // Side enum, so a config written when rules were keyed by side needs no
 // migration. Bank account verifications route through the same machinery rather
@@ -12,3 +12,10 @@ var ProcessorRoutingPurpose;
     ProcessorRoutingPurpose["Sell"] = "sell";
     ProcessorRoutingPurpose["BankAccountVerification"] = "bankAccountVerification";
 })(ProcessorRoutingPurpose = exports.ProcessorRoutingPurpose || (exports.ProcessorRoutingPurpose = {}));
+var ProcessorRoutingMode;
+(function (ProcessorRoutingMode) {
+    /** Always use `percentages`. Windows are ignored. */
+    ProcessorRoutingMode["Manual"] = "manual";
+    /** Use the window covering the current local minute. */
+    ProcessorRoutingMode["Scheduled"] = "scheduled";
+})(ProcessorRoutingMode = exports.ProcessorRoutingMode || (exports.ProcessorRoutingMode = {}));

package/build/types/routing-decision.d.ts

@@ -21,6 +21,10 @@ export interface RoutingDecision {
     percentages?: {
         [processor in Processor]?: number;
     };
+    window?: {
+        startMinute: number;
+        endMinute: number;
+    };
     seed?: number;
     decidedAt: Date;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riocrypto/common",
-  "version": "1.0.2720",
+  "version": "1.0.2721",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",