@atbas/m-mcp 0.1.0

package/dist/domain/amount.js

@@ -0,0 +1,275 @@
+import { JazzCashConfigError, JazzCashValidationError } from '../errors.js';
+/** Accepted exponents, kept in step with {@link DECIMAL_PLACES} and {@link MinorUnitExponent}. */
+const MINOR_UNIT_EXPONENTS = [0, 1, 2, 3, 4];
+/**
+ * The decimal-places phrase for each exponent.
+ *
+ * Spelled out per exponent so the message reads as a rule ("at most two decimal
+ * places") rather than as a number a merchant has to interpret, and so the
+ * singular case is not written "at most 1 decimal places".
+ */
+const DECIMAL_PLACES = [
+    'no decimal places',
+    'one decimal place',
+    'two decimal places',
+    'three decimal places',
+    'four decimal places',
+];
+/** Accepts any number of decimals; the exponent decides how many are too many. */
+const MAJOR_AMOUNT_PATTERN = /^(\d+)(?:\.(\d+))?$/;
+const MINOR_AMOUNT_PATTERN = /^\d+$/;
+/** One hundred major units, in minor units: the worked example in error messages. */
+const EXAMPLE_MAJOR_UNITS = 100n;
+function reject(message, details, docRefs) {
+    throw new JazzCashValidationError(message, { details, docRefs });
+}
+/**
+ * Validate a currency declaration and derive its scale.
+ *
+ * The checks run once per definition and are cheap, but a mistyped exponent is
+ * not a cosmetic fault: it multiplies or divides every amount in that currency
+ * by a power of ten, and no downstream check can detect the difference between a
+ * deliberate JPY 10,000 and a KWD 10,000 that should have been 10.000. A
+ * currency assembled from a configuration file — the obvious next step once a
+ * second provider ships — must fail here rather than at the gateway.
+ */
+export function defineCurrency(spec) {
+    if (!/^[A-Z]{3}$/.test(spec.code)) {
+        throw new JazzCashConfigError(`"${spec.code}" is not an ISO 4217 alphabetic currency code, which is three capital letters such as "PKR".`, { details: { code: spec.code } });
+    }
+    if (!MINOR_UNIT_EXPONENTS.includes(spec.exponent)) {
+        throw new JazzCashConfigError(`Minor-unit exponent ${String(spec.exponent)} for ${spec.code} is not one of the ISO 4217 exponents 0 to 4.`, { details: { code: spec.code, exponent: spec.exponent } });
+    }
+    if (spec.maxMajorUnits <= 0n) {
+        throw new JazzCashConfigError(`The ${spec.code} transaction ceiling must be greater than zero, or no amount at all is payable.`, { details: { code: spec.code, maxMajorUnits: spec.maxMajorUnits.toString() } });
+    }
+    const scale = 10n ** BigInt(spec.exponent);
+    return {
+        ...spec,
+        docRefs: spec.docRefs ?? [],
+        scale,
+        maxMinorUnits: spec.maxMajorUnits * scale,
+    };
+}
+/** The only currency JazzCash processes. No conversion is performed. */
+export const PKR = defineCurrency({
+    code: 'PKR',
+    exponent: 2,
+    encoding: 'minor-units',
+    // No guide states a gateway ceiling. PKR 100,000,000.00 is a local sanity
+    // guard against a unit-conversion bug reaching the gateway as a real debit,
+    // not a JazzCash rule.
+    maxMajorUnits: 100000000n,
+    docRefs: [{ docId: 'mwallet-rest-v2-0-cnic', sectionId: 'currency-and-amount-handling' }],
+});
+/** The ISO 4217 code of the only currency the JazzCash gateway processes. */
+export const SUPPORTED_CURRENCY = PKR.code;
+/**
+ * Upper bound on a single PKR transaction, in minor units (PKR 100,000,000.00).
+ *
+ * Derived from {@link PKR} rather than written out, so the ceiling cannot drift
+ * away from the currency it belongs to. Retained as a named export because
+ * callers and tests reason about the PKR ceiling directly.
+ */
+export const MAX_MINOR_UNITS = PKR.maxMinorUnits;
+/**
+ * Parse a major-unit figure into exact minor units.
+ *
+ * Returns `undefined` rather than throwing so that both the human-facing and the
+ * wire-facing caller can word the rejection for their own audience. Anything
+ * with more decimal places than the currency has is refused, because rounding a
+ * merchant's money silently is worse than refusing it.
+ */
+function parseMajorUnits(text, currency) {
+    const match = MAJOR_AMOUNT_PATTERN.exec(text);
+    if (match === null) {
+        return undefined;
+    }
+    /* v8 ignore next -- unreachable: group 1 is mandatory in MAJOR_AMOUNT_PATTERN */
+    const whole = match[1] ?? '0';
+    // Group 2 is genuinely optional: "100" has no fractional part.
+    const fraction = match[2] ?? '';
+    if (fraction.length > currency.exponent) {
+        return undefined;
+    }
+    const padded = fraction.padEnd(currency.exponent, '0');
+    return BigInt(whole) * currency.scale + (padded === '' ? 0n : BigInt(padded));
+}
+/** Describe the shape a major-unit amount must take in this currency. */
+function majorUnitsAdvice(currency) {
+    // A currency with no minor unit has no "decimal places" rule to state, and
+    // offering "100.50" as an example there would invite the very value that is
+    // being refused.
+    if (currency.exponent === 0) {
+        return `a positive whole number, because ${currency.code} has no minor unit. Pass a value such as "100"${minorUnitsAdvice(currency)}.`;
+    }
+    const example = `100.${'5'.padEnd(currency.exponent, '0')}`;
+    return `a positive decimal with at most ${DECIMAL_PLACES[currency.exponent]}. Pass a value such as "100" or "${example}"${minorUnitsAdvice(currency)}.`;
+}
+/** Only a minor-unit gateway accepts minor units, so only it may be offered them. */
+function minorUnitsAdvice(currency) {
+    return currency.encoding === 'minor-units' ? ', or pass minor units directly' : '';
+}
+/** Bounds every amount must satisfy, whichever form it arrived in. */
+function assertWithinBounds(minor, display, currency) {
+    if (minor === 0n) {
+        reject('Amount must be greater than zero.', { amount: display }, currency.docRefs);
+    }
+    if (minor > currency.maxMinorUnits) {
+        reject(`Amount ${display} exceeds the configured ceiling of ${fromMinorUnits(currency.maxMinorUnits.toString(), currency)} ${currency.code}. Raise maxMajorUnits on the ${currency.code} currency definition deliberately if this is a genuine transaction.`, { amount: display }, currency.docRefs);
+    }
+}
+/**
+ * Reject a wire value padded with whitespace rather than absorbing it.
+ *
+ * The payload transmits the value and the secure hash is computed over it
+ * verbatim, so approving `" 10000 "` approves a hash input the gateway never
+ * expects.
+ */
+function assertNoSurroundingWhitespace(value, currency) {
+    if (value !== value.trim()) {
+        reject(`pp_Amount "${value}" carries leading or trailing whitespace. The value is transmitted and hashed exactly as written, so the padding corrupts pp_SecureHash even when the digits are right. Remove the surrounding whitespace before building the payload.`, { amount: value }, currency.docRefs);
+    }
+}
+/**
+ * Convert a human-facing amount to the minor-unit string the gateway expects.
+ *
+ * Accepts `"100"`, `"100.5"`, `"100.50"` and the numeric equivalents in a
+ * two-decimal currency. Rejects anything with more decimal places than the
+ * currency has, because rounding a merchant's money silently is worse than
+ * refusing it.
+ */
+export function toMinorUnits(amount, currency = PKR) {
+    if (typeof amount === 'number') {
+        if (!Number.isFinite(amount)) {
+            reject('Amount must be a finite number.', { amount: String(amount) }, currency.docRefs);
+        }
+        // Round-tripping through a string keeps the decimal-places rule enforceable
+        // and surfaces float artefacts (0.1 + 0.2) as a validation error rather than
+        // a silently wrong debit.
+        return toMinorUnits(String(amount), currency);
+    }
+    const trimmed = amount.trim();
+    if (trimmed === '') {
+        reject('Amount is required.', { amount }, currency.docRefs);
+    }
+    const minor = parseMajorUnits(trimmed, currency);
+    if (minor === undefined) {
+        reject(`Amount "${trimmed}" is not ${majorUnitsAdvice(currency)}`, { amount: trimmed }, currency.docRefs);
+    }
+    assertWithinBounds(minor, trimmed, currency);
+    return minor.toString();
+}
+/**
+ * Validate a minor-unit string, throwing with an actionable message if it is wrong.
+ *
+ * Unlike {@link toMinorUnits}, which converts a human-facing figure, this checks
+ * a value that is already in wire form, so surrounding whitespace is rejected
+ * rather than absorbed.
+ */
+export function assertMinorUnits(value, currency = PKR) {
+    assertNoSurroundingWhitespace(value, currency);
+    if (!MINOR_AMOUNT_PATTERN.test(value)) {
+        const example = (EXAMPLE_MAJOR_UNITS * currency.scale).toString();
+        const hint = value.includes('.')
+            ? ` It contains a decimal point: pp_Amount is in minor units, so ${formatAmount(example, currency)} is sent as "${example}".`
+            : '';
+        reject(`pp_Amount "${value}" must be a whole number of minor units.${hint}`, { amount: value }, currency.docRefs);
+    }
+    const minor = BigInt(value);
+    if (minor === 0n) {
+        reject('pp_Amount must be greater than zero.', { amount: value }, currency.docRefs);
+    }
+    if (minor > currency.maxMinorUnits) {
+        reject(`pp_Amount ${value} exceeds the configured ceiling of ${currency.maxMinorUnits.toString()} minor units.`, { amount: value }, currency.docRefs);
+    }
+}
+/** Convert minor units back to a major-unit string, e.g. `"10000"` to `"100.00"`. */
+export function fromMinorUnits(minorUnits, currency = PKR) {
+    const trimmed = minorUnits.trim();
+    if (!MINOR_AMOUNT_PATTERN.test(trimmed)) {
+        reject(`Cannot interpret "${minorUnits}" as minor units: it must be a whole number.`, { minorUnits }, currency.docRefs);
+    }
+    const minor = BigInt(trimmed);
+    // A currency with no minor unit has no fractional part at all: JPY 100 is
+    // written "100", and a trailing "100." would be rejected by every consumer.
+    if (currency.exponent === 0) {
+        return minor.toString();
+    }
+    const whole = minor / currency.scale;
+    const fraction = (minor % currency.scale).toString().padStart(currency.exponent, '0');
+    return `${whole.toString()}.${fraction}`;
+}
+/** Format minor units for display to a merchant, e.g. `"PKR 100.00"`. */
+export function formatAmount(minorUnits, currency = PKR) {
+    return `${currency.code} ${fromMinorUnits(minorUnits, currency)}`;
+}
+/**
+ * Format minor units as PKR.
+ *
+ * Retained as a named function because it reads better at a JazzCash-only call
+ * site than {@link formatAmount} with a defaulted currency, and because removing
+ * it would churn callers for no behavioural gain.
+ */
+export function formatPkr(minorUnits) {
+    return formatAmount(minorUnits, PKR);
+}
+/**
+ * Encode a human-facing amount as the provider's gateway expects to receive it.
+ *
+ * The counterpart of {@link toMinorUnits} for a provider whose wire form is not
+ * minor units. Both go through the same exact integer parse, so a `major-units`
+ * gateway cannot receive a figure that a `minor-units` gateway would have
+ * refused.
+ */
+export function toWireAmount(amount, currency = PKR) {
+    const minor = toMinorUnits(amount, currency);
+    return currency.encoding === 'minor-units' ? minor : fromMinorUnits(minor, currency);
+}
+/**
+ * Validate a value already in wire form against the currency's encoding.
+ *
+ * A decimal point is a defect in a minor-unit payload and mandatory in a
+ * major-unit one, so the same string cannot be judged without knowing which
+ * gateway it is bound for.
+ */
+export function assertWireAmount(value, currency = PKR) {
+    if (currency.encoding === 'minor-units') {
+        assertMinorUnits(value, currency);
+        return;
+    }
+    assertNoSurroundingWhitespace(value, currency);
+    const minor = parseMajorUnits(value, currency);
+    if (minor === undefined) {
+        reject(`Amount "${value}" is not ${majorUnitsAdvice(currency)}`, { amount: value }, currency.docRefs);
+    }
+    assertWithinBounds(minor, value, currency);
+}
+/**
+ * Recover canonical minor units from a value in wire form.
+ *
+ * The inverse of {@link toWireAmount}. Response handling compares the amount the
+ * gateway echoed with the amount that was sent, and comparing `"100.00"` with
+ * `"10000"` as strings reports a mismatch between two identical sums.
+ */
+export function minorUnitsFromWire(value, currency = PKR) {
+    assertWireAmount(value, currency);
+    return currency.encoding === 'minor-units' ? value : toMinorUnits(value, currency);
+}
+/**
+ * Heuristic: does this look like a major-unit amount that was never scaled?
+ *
+ * Used by validation to turn the single most common integration mistake into a
+ * specific warning instead of an opaque gateway rejection. A decimal point is
+ * conclusive; a suspiciously small whole number is only a warning, because a
+ * PKR 1.00 test transaction (`"100"`) is both legitimate and common.
+ */
+export function looksLikeMajorUnits(value, currency = PKR) {
+    // Where major units are the wire form, a decimal point is correct. Flagging it
+    // would train a merchant to dismiss the warning that does matter.
+    if (currency.encoding === 'major-units') {
+        return false;
+    }
+    return value.includes('.');
+}
+//# sourceMappingURL=amount.js.map

package/dist/domain/amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.js","sourceRoot":"","sources":["../../src/domain/amount.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AA4E5E,kGAAkG;AAClG,MAAM,oBAAoB,GAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,cAAc,GAAG;IACrB,mBAAmB;IACnB,mBAAmB;IACnB,oBAAoB;IACpB,sBAAsB;IACtB,qBAAqB;CACb,CAAC;AAEX,kFAAkF;AAClF,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AACnD,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAErC,qFAAqF;AACrF,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC,SAAS,MAAM,CAAC,OAAe,EAAE,OAA0C,EAAE,OAA0B;IACrG,MAAM,IAAI,uBAAuB,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAkB;IAC/C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,mBAAmB,CAC3B,IAAI,IAAI,CAAC,IAAI,8FAA8F,EAC3G,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CACjC,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,mBAAmB,CAC3B,uBAAuB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,CAAC,IAAI,+CAA+C,EAC5G,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,CAC1D,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC;QAC7B,MAAM,IAAI,mBAAmB,CAC3B,OAAO,IAAI,CAAC,IAAI,iFAAiF,EACjG,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,EAAE,EAAE,CAC/E,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3C,OAAO;QACL,GAAG,IAAI;QACP,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE;QAC3B,KAAK;QACL,aAAa,EAAE,IAAI,CAAC,aAAa,GAAG,KAAK;KAC1C,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,GAAG,GAAa,cAAc,CAAC;IAC1C,IAAI,EAAE,KAAK;IACX,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,aAAa;IACvB,0EAA0E;IAC1E,4EAA4E;IAC5E,uBAAuB;IACvB,aAAa,EAAE,UAAY;IAC3B,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,wBAAwB,EAAE,SAAS,EAAE,8BAA8B,EAAE,CAAC;CAC1F,CAAC,CAAC;AAEH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC,IAAI,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC,aAAa,CAAC;AAEjD;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,IAAY,EAAE,QAAkB;IACvD,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,iFAAiF;IACjF,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;IAC9B,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACxC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvD,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,KAAK,GAAG,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,yEAAyE;AACzE,SAAS,gBAAgB,CAAC,QAAkB;IAC1C,2EAA2E;IAC3E,4EAA4E;IAC5E,iBAAiB;IACjB,IAAI,QAAQ,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,oCAAoC,QAAQ,CAAC,IAAI,iDAAiD,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC;IACzI,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC;IAC5D,OAAO,mCAAmC,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,oCAAoC,OAAO,IAAI,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC;AAC1J,CAAC;AAED,qFAAqF;AACrF,SAAS,gBAAgB,CAAC,QAAkB;IAC1C,OAAO,QAAQ,CAAC,QAAQ,KAAK,aAAa,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC,CAAC,EAAE,CAAC;AACrF,CAAC;AAED,sEAAsE;AACtE,SAAS,kBAAkB,CAAC,KAAa,EAAE,OAAe,EAAE,QAAkB;IAC5E,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,MAAM,CAAC,mCAAmC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,KAAK,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC;QACnC,MAAM,CACJ,UAAU,OAAO,sCAAsC,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,QAAQ,EAAE,EAAE,QAAQ,CAAC,IAAI,QAAQ,CAAC,IAAI,gCAAgC,QAAQ,CAAC,IAAI,qEAAqE,EACrP,EAAE,MAAM,EAAE,OAAO,EAAE,EACnB,QAAQ,CAAC,OAAO,CACjB,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,6BAA6B,CAAC,KAAa,EAAE,QAAkB;IACtE,IAAI,KAAK,KAAK,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC3B,MAAM,CACJ,cAAc,KAAK,wOAAwO,EAC3P,EAAE,MAAM,EAAE,KAAK,EAAE,EACjB,QAAQ,CAAC,OAAO,CACjB,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB,EAAE,WAAqB,GAAG;IAC5E,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,MAAM,CAAC,iCAAiC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC1F,CAAC;QACD,4EAA4E;QAC5E,6EAA6E;QAC7E,0BAA0B;QAC1B,OAAO,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACnB,MAAM,CAAC,qBAAqB,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACjD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,CAAC,WAAW,OAAO,YAAY,gBAAgB,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC5G,CAAC;IACD,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAE7C,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,WAAqB,GAAG;IACtE,6BAA6B,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE/C,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,CAAC,mBAAmB,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;QAClE,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;YAC9B,CAAC,CAAC,iEAAiE,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,OAAO,IAAI;YAC7H,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,CAAC,cAAc,KAAK,2CAA2C,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpH,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,MAAM,CAAC,sCAAsC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,KAAK,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC;QACnC,MAAM,CACJ,aAAa,KAAK,sCAAsC,QAAQ,CAAC,aAAa,CAAC,QAAQ,EAAE,eAAe,EACxG,EAAE,MAAM,EAAE,KAAK,EAAE,EACjB,QAAQ,CAAC,OAAO,CACjB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,cAAc,CAAC,UAAkB,EAAE,WAAqB,GAAG;IACzE,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IAClC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACxC,MAAM,CACJ,qBAAqB,UAAU,8CAA8C,EAC7E,EAAE,UAAU,EAAE,EACd,QAAQ,CAAC,OAAO,CACjB,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9B,0EAA0E;IAC1E,4EAA4E;IAC5E,IAAI,QAAQ,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC1B,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IACrC,MAAM,QAAQ,GAAG,CAAC,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACtF,OAAO,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,QAAQ,EAAE,CAAC;AAC3C,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,WAAqB,GAAG;IACvE,OAAO,GAAG,QAAQ,CAAC,IAAI,IAAI,cAAc,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,OAAO,YAAY,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB,EAAE,WAAqB,GAAG;IAC5E,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC7C,OAAO,QAAQ,CAAC,QAAQ,KAAK,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,WAAqB,GAAG;IACtE,IAAI,QAAQ,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QACxC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QAClC,OAAO;IACT,CAAC;IAED,6BAA6B,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC/C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,CAAC,WAAW,KAAK,YAAY,gBAAgB,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IACxG,CAAC;IACD,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAE,WAAqB,GAAG;IACxE,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAClC,OAAO,QAAQ,CAAC,QAAQ,KAAK,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,WAAqB,GAAG;IACzE,+EAA+E;IAC/E,kEAAkE;IAClE,IAAI,QAAQ,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/dist/domain/datetime.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Wall-clock timestamp handling.
+ *
+ * Every guide states that `pp_TxnDateTime` and `pp_TxnExpiryDateTime` are
+ * `YYYYMMDDHHMMSS` in Pakistan Standard Time, and the PHP samples open with
+ * `date_default_timezone_set("Asia/karachi")`. Pakistan Standard Time is
+ * therefore the default of every function here, and no existing caller has to
+ * name it.
+ *
+ * The zone is a parameter rather than a module constant. It used to be an
+ * `Intl.DateTimeFormat` built at import time — a process-wide singleton fixed
+ * before any flow was known, so a provider settling in another zone could not be
+ * expressed at all, only worked around by changing the host's clock.
+ *
+ * Formatting goes through `Intl.DateTimeFormat` with an explicit time zone, so
+ * the output is correct no matter what the host clock is set to. A merchant
+ * server in UTC and one in New York must produce the same stamp for the same
+ * instant, and a wrong stamp fails gateway validation with an unhelpful error.
+ *
+ * Pakistan has observed no daylight saving since 2009 and Turkey none since
+ * 2016, so both zones in use have a fixed offset — which is exactly why the
+ * arithmetic below must not assume one. A stamp names a wall clock, and in a
+ * zone that observes daylight saving the gap between two wall clocks is not the
+ * time that elapsed between them: on a spring-forward morning 01:59 and 03:10
+ * are eleven minutes apart, not seventy-one. Every comparison therefore resolves
+ * a stamp to the instant it names in its zone before subtracting, so that the
+ * Status Inquiry wait and the expiry window stay true durations.
+ */
+export declare const PAKISTAN_TIME_ZONE = "Asia/Karachi";
+export declare const TXN_DATE_TIME_FORMAT = "YYYYMMDDHHMMSS";
+export interface TxnDateTimeParts {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+}
+/** Format an instant as `YYYYMMDDHHMMSS`, in Pakistan Standard Time unless told otherwise. */
+export declare function formatTxnDateTime(date: Date, timeZone?: string): string;
+/** Current transaction stamp in the provider's zone. The clock is injectable for testing. */
+export declare function nowTxnDateTime(now?: Date, timeZone?: string): string;
+/**
+ * Add whole days to an instant.
+ *
+ * Elapsed days, not wall-clock days: the result is exactly 24 hours per day
+ * later, so an expiry window is the length the merchant asked for even when the
+ * zone gains or loses an hour in between. The wall clock the stamp then shows
+ * moves by that hour, which is the correct rendering of that instant.
+ */
+export declare function addDays(date: Date, days: number): Date;
+/**
+ * Expiry stamp for a transaction, one day after it, as every guide specifies.
+ */
+export declare function txnExpiryDateTime(date?: Date, days?: number, timeZone?: string): string;
+/** True when a string is a structurally and calendrically valid stamp. */
+export declare function isValidTxnDateTime(value: string): boolean;
+/** Parse a stamp into its components, or throw with the expected format named. */
+export declare function parseTxnDateTime(value: string): TxnDateTimeParts;
+/**
+ * The instant a stamp names in a zone.
+ *
+ * Resolved in two passes. The first offset is looked up from the wall clock read
+ * as though it were UTC, which lands on the correct side of a daylight-saving
+ * transition for every stamp except those within an offset's distance of it; the
+ * second lookup, from the instant that first offset implies, corrects those.
+ * A single pass would put a stamp taken minutes after a spring-forward an hour
+ * out, and the error is invisible in the digits.
+ *
+ * A wall clock is not always one instant. A stamp inside the hour a
+ * spring-forward skips names no instant at all, and one inside the hour an
+ * autumn fall-back repeats names two. Both resolve deterministically rather than
+ * meaningfully: a repeated wall clock resolves to its first occurrence, and a
+ * skipped one to the hour before the reading its own offset implies. A stamp
+ * that needs either rule is one the system that emitted it got wrong, and both
+ * resolutions are pinned by tests so neither can drift unnoticed.
+ */
+export declare function txnDateTimeToInstant(value: string, timeZone?: string): Date;
+/** Whole and fractional days from `from` to `to`. Negative when `to` precedes `from`. */
+export declare function daysBetweenTxnDateTimes(from: string, to: string, timeZone?: string): number;
+/** True when `expiry` is strictly after `txnDateTime`. */
+export declare function isExpiryAfterTransaction(txnDateTime: string, expiry: string, timeZone?: string): boolean;
+/**
+ * Minutes elapsed between a transaction stamp and an instant.
+ *
+ * Used to enforce the Status Inquiry guidance that the API should not be called
+ * until at least ten minutes after the transaction was initiated. The stamp is
+ * resolved to its instant rather than the instant reduced to a stamp, so that a
+ * daylight-saving transition between the two cannot report seventy-one minutes
+ * where eleven have passed and wave through a call the gateway will refuse.
+ */
+export declare function minutesSinceTxnDateTime(txnDateTime: string, now?: Date, timeZone?: string): number;
+/** Documented minimum wait before calling Status Inquiry. */
+export declare const STATUS_INQUIRY_MINIMUM_WAIT_MINUTES = 10;
+//# sourceMappingURL=datetime.d.ts.map

package/dist/domain/datetime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.d.ts","sourceRoot":"","sources":["../../src/domain/datetime.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAEjD,eAAO,MAAM,oBAAoB,mBAAmB,CAAC;AAkDrD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAuCD,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAE,MAA2B,GAAG,MAAM,CAI3F;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,GAAG,GAAE,IAAiB,EAAE,QAAQ,GAAE,MAA2B,GAAG,MAAM,CAEpG;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,IAAiB,EAAE,IAAI,SAAI,EAAE,QAAQ,GAAE,MAA2B,GAAG,MAAM,CAElH;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAuBzD;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAqBhE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAA2B,GAAG,IAAI,CAK/F;AAED,yFAAyF;AACzF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,GAAE,MAA2B,GAAG,MAAM,CAG/G;AAED,0DAA0D;AAC1D,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAA2B,GACpC,OAAO,CAET;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,GAAG,GAAE,IAAiB,EACtB,QAAQ,GAAE,MAA2B,GACpC,MAAM,CAOR;AAED,6DAA6D;AAC7D,eAAO,MAAM,mCAAmC,KAAK,CAAC"}

package/dist/domain/datetime.js

@@ -0,0 +1,211 @@
+import { JazzCashConfigError, JazzCashValidationError } from '../errors.js';
+/**
+ * Wall-clock timestamp handling.
+ *
+ * Every guide states that `pp_TxnDateTime` and `pp_TxnExpiryDateTime` are
+ * `YYYYMMDDHHMMSS` in Pakistan Standard Time, and the PHP samples open with
+ * `date_default_timezone_set("Asia/karachi")`. Pakistan Standard Time is
+ * therefore the default of every function here, and no existing caller has to
+ * name it.
+ *
+ * The zone is a parameter rather than a module constant. It used to be an
+ * `Intl.DateTimeFormat` built at import time — a process-wide singleton fixed
+ * before any flow was known, so a provider settling in another zone could not be
+ * expressed at all, only worked around by changing the host's clock.
+ *
+ * Formatting goes through `Intl.DateTimeFormat` with an explicit time zone, so
+ * the output is correct no matter what the host clock is set to. A merchant
+ * server in UTC and one in New York must produce the same stamp for the same
+ * instant, and a wrong stamp fails gateway validation with an unhelpful error.
+ *
+ * Pakistan has observed no daylight saving since 2009 and Turkey none since
+ * 2016, so both zones in use have a fixed offset — which is exactly why the
+ * arithmetic below must not assume one. A stamp names a wall clock, and in a
+ * zone that observes daylight saving the gap between two wall clocks is not the
+ * time that elapsed between them: on a spring-forward morning 01:59 and 03:10
+ * are eleven minutes apart, not seventy-one. Every comparison therefore resolves
+ * a stamp to the instant it names in its zone before subtracting, so that the
+ * Status Inquiry wait and the expiry window stay true durations.
+ */
+export const PAKISTAN_TIME_ZONE = 'Asia/Karachi';
+export const TXN_DATE_TIME_FORMAT = 'YYYYMMDDHHMMSS';
+const TXN_DATE_TIME_PATTERN = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/;
+const MILLISECONDS_PER_DAY = 86_400_000;
+const MILLISECONDS_PER_MINUTE = 60_000;
+const MILLISECONDS_PER_SECOND = 1_000;
+/**
+ * Formatters, memoised by zone.
+ *
+ * A memo of a pure function, not mutable state: constructing an
+ * `Intl.DateTimeFormat` costs far more than formatting with one, and a single
+ * payload formats two stamps, so rebuilding per call would be paid on every
+ * transaction. Only zones the runtime accepted are inserted and the IANA
+ * database is finite, so the map cannot grow without bound.
+ */
+const formatters = new Map();
+function formatterFor(timeZone) {
+    const memoised = formatters.get(timeZone);
+    if (memoised !== undefined) {
+        return memoised;
+    }
+    let formatter;
+    try {
+        formatter = new Intl.DateTimeFormat('en-GB', {
+            timeZone,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hourCycle: 'h23',
+        });
+    }
+    catch (cause) {
+        // A mistyped zone otherwise surfaces as a bare RangeError from inside a
+        // payload build, naming neither the setting at fault nor the provider.
+        throw new JazzCashConfigError(`"${timeZone}" is not an IANA time zone this runtime recognises. Use an identifier such as "${PAKISTAN_TIME_ZONE}" or "Europe/Istanbul".`, { cause, details: { timeZone } });
+    }
+    formatters.set(timeZone, formatter);
+    return formatter;
+}
+function partsOf(date, timeZone) {
+    const result = {};
+    for (const part of formatterFor(timeZone).formatToParts(date)) {
+        if (part.type !== 'literal') {
+            result[part.type] = part.value;
+        }
+    }
+    return result;
+}
+/** Reject an instant that is not one, rather than emitting `NaN` into a payload. */
+function assertRealInstant(date) {
+    if (Number.isNaN(date.getTime())) {
+        throw new JazzCashValidationError('Cannot format an invalid Date as a JazzCash timestamp.');
+    }
+}
+/** The wall clock an instant shows in a zone, expressed as though it were UTC. */
+function wallClockOf(instant, timeZone) {
+    const parts = partsOf(new Date(instant), timeZone);
+    return Date.UTC(Number(parts['year']), Number(parts['month']) - 1, Number(parts['day']), Number(parts['hour']), Number(parts['minute']), Number(parts['second']));
+}
+/** A zone's offset from UTC at an instant, in milliseconds. */
+function offsetAt(instant, timeZone) {
+    // The formatter resolves to the second, so the instant is compared at the same
+    // resolution; a millisecond component would otherwise be read as offset.
+    return wallClockOf(instant, timeZone) - Math.floor(instant / MILLISECONDS_PER_SECOND) * MILLISECONDS_PER_SECOND;
+}
+/** Format an instant as `YYYYMMDDHHMMSS`, in Pakistan Standard Time unless told otherwise. */
+export function formatTxnDateTime(date, timeZone = PAKISTAN_TIME_ZONE) {
+    assertRealInstant(date);
+    const parts = partsOf(date, timeZone);
+    return [parts['year'], parts['month'], parts['day'], parts['hour'], parts['minute'], parts['second']].join('');
+}
+/** Current transaction stamp in the provider's zone. The clock is injectable for testing. */
+export function nowTxnDateTime(now = new Date(), timeZone = PAKISTAN_TIME_ZONE) {
+    return formatTxnDateTime(now, timeZone);
+}
+/**
+ * Add whole days to an instant.
+ *
+ * Elapsed days, not wall-clock days: the result is exactly 24 hours per day
+ * later, so an expiry window is the length the merchant asked for even when the
+ * zone gains or loses an hour in between. The wall clock the stamp then shows
+ * moves by that hour, which is the correct rendering of that instant.
+ */
+export function addDays(date, days) {
+    return new Date(date.getTime() + days * MILLISECONDS_PER_DAY);
+}
+/**
+ * Expiry stamp for a transaction, one day after it, as every guide specifies.
+ */
+export function txnExpiryDateTime(date = new Date(), days = 1, timeZone = PAKISTAN_TIME_ZONE) {
+    return formatTxnDateTime(addDays(date, days), timeZone);
+}
+/** True when a string is a structurally and calendrically valid stamp. */
+export function isValidTxnDateTime(value) {
+    const match = TXN_DATE_TIME_PATTERN.exec(value);
+    if (match === null) {
+        return false;
+    }
+    const [, year, month, day, hour, minute, second] = match.map(Number);
+    if (month < 1 || month > 12 || day < 1 || hour > 23 || minute > 59 || second > 59) {
+        return false;
+    }
+    // Reject 31 April and 29 February in a common year, which pass a range check
+    // but are not real dates and are rejected by the gateway.
+    const asUtc = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+    return asUtc.getUTCFullYear() === year && asUtc.getUTCMonth() === month - 1 && asUtc.getUTCDate() === day;
+}
+/** Parse a stamp into its components, or throw with the expected format named. */
+export function parseTxnDateTime(value) {
+    if (!isValidTxnDateTime(value)) {
+        throw new JazzCashValidationError(`"${value}" is not a valid ${TXN_DATE_TIME_FORMAT} timestamp in Pakistan Standard Time. Example: 20260114153733.`, { details: { value }, docRefs: [{ docId: 'mwallet-rest-v2-0-cnic', sectionId: 'date-and-time-parameters' }] });
+    }
+    const match = TXN_DATE_TIME_PATTERN.exec(value);
+    /* c8 ignore next 3 -- unreachable: isValidTxnDateTime already matched this pattern */
+    if (match === null) {
+        throw new JazzCashValidationError(`"${value}" is not a valid ${TXN_DATE_TIME_FORMAT} timestamp.`);
+    }
+    return {
+        year: Number(match[1]),
+        month: Number(match[2]),
+        day: Number(match[3]),
+        hour: Number(match[4]),
+        minute: Number(match[5]),
+        second: Number(match[6]),
+    };
+}
+/**
+ * The instant a stamp names in a zone.
+ *
+ * Resolved in two passes. The first offset is looked up from the wall clock read
+ * as though it were UTC, which lands on the correct side of a daylight-saving
+ * transition for every stamp except those within an offset's distance of it; the
+ * second lookup, from the instant that first offset implies, corrects those.
+ * A single pass would put a stamp taken minutes after a spring-forward an hour
+ * out, and the error is invisible in the digits.
+ *
+ * A wall clock is not always one instant. A stamp inside the hour a
+ * spring-forward skips names no instant at all, and one inside the hour an
+ * autumn fall-back repeats names two. Both resolve deterministically rather than
+ * meaningfully: a repeated wall clock resolves to its first occurrence, and a
+ * skipped one to the hour before the reading its own offset implies. A stamp
+ * that needs either rule is one the system that emitted it got wrong, and both
+ * resolutions are pinned by tests so neither can drift unnoticed.
+ */
+export function txnDateTimeToInstant(value, timeZone = PAKISTAN_TIME_ZONE) {
+    const parts = parseTxnDateTime(value);
+    const wallClock = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+    const firstPass = offsetAt(wallClock, timeZone);
+    return new Date(wallClock - offsetAt(wallClock - firstPass, timeZone));
+}
+/** Whole and fractional days from `from` to `to`. Negative when `to` precedes `from`. */
+export function daysBetweenTxnDateTimes(from, to, timeZone = PAKISTAN_TIME_ZONE) {
+    const elapsed = txnDateTimeToInstant(to, timeZone).getTime() - txnDateTimeToInstant(from, timeZone).getTime();
+    return elapsed / MILLISECONDS_PER_DAY;
+}
+/** True when `expiry` is strictly after `txnDateTime`. */
+export function isExpiryAfterTransaction(txnDateTime, expiry, timeZone = PAKISTAN_TIME_ZONE) {
+    return txnDateTimeToInstant(expiry, timeZone).getTime() > txnDateTimeToInstant(txnDateTime, timeZone).getTime();
+}
+/**
+ * Minutes elapsed between a transaction stamp and an instant.
+ *
+ * Used to enforce the Status Inquiry guidance that the API should not be called
+ * until at least ten minutes after the transaction was initiated. The stamp is
+ * resolved to its instant rather than the instant reduced to a stamp, so that a
+ * daylight-saving transition between the two cannot report seventy-one minutes
+ * where eleven have passed and wave through a call the gateway will refuse.
+ */
+export function minutesSinceTxnDateTime(txnDateTime, now = new Date(), timeZone = PAKISTAN_TIME_ZONE) {
+    assertRealInstant(now);
+    // Truncated to the second because a stamp carries no sub-second component:
+    // reporting 10.008 minutes where the gateway's own clock reads 10 would make
+    // this guard disagree with the rule it exists to enforce.
+    const nowSeconds = Math.floor(now.getTime() / MILLISECONDS_PER_SECOND) * MILLISECONDS_PER_SECOND;
+    return (nowSeconds - txnDateTimeToInstant(txnDateTime, timeZone).getTime()) / MILLISECONDS_PER_MINUTE;
+}
+/** Documented minimum wait before calling Status Inquiry. */
+export const STATUS_INQUIRY_MINIMUM_WAIT_MINUTES = 10;
+//# sourceMappingURL=datetime.js.map

package/dist/domain/datetime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datetime.js","sourceRoot":"","sources":["../../src/domain/datetime.ts"],"names":[],"mappings":"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"}