@atbas/m-mcp 0.1.0

package/dist/tools/tool-kit.js

@@ -0,0 +1,297 @@
+import { describeError, JazzCashError } from '../errors.js';
+import { maskSecretsDeep, scrubTextForTranscript } from '../telemetry/redaction.js';
+import { createCallContext } from './call-context.js';
+/** Build a tool result carrying both human-readable text and structured data. */
+export function toolResult(text, options = {}) {
+    return {
+        content: [{ type: 'text', text }],
+        ...(options.structuredContent === undefined ? {} : { structuredContent: options.structuredContent }),
+        ...(options.isError === true ? { isError: true } : {}),
+    };
+}
+/** Build a failure result, naming the stable error code when there is one. */
+export function toolError(error, secrets = []) {
+    const code = error instanceof JazzCashError ? `[${error.code}] ` : '';
+    const docRefs = error instanceof JazzCashError && error.docRefs.length > 0
+        ? `\n\nSee: ${error.docRefs.map((ref) => `jazzcash://docs/${ref.docId}${ref.sectionId === undefined ? '' : `#${ref.sectionId}`}`).join(', ')}`
+        : '';
+    return toolResult(scrubTextForTranscript(`${code}${describeError(error)}${docRefs}`, secrets), { isError: true });
+}
+/**
+ * Wrap a handler so failures surface as tool errors and secrets never leak.
+ *
+ * Redaction covers every configured profile, not only the one in play, because a
+ * caller can pass an explicit salt for one environment while another is active.
+ *
+ * The handler receives a {@link CallContext} built for this invocation. It is
+ * built from `deps` rather than from the SDK's `extra` argument, and the second
+ * parameter below is the reason that distinction has to be written down.
+ *
+ * A `declaration` makes the wrapper refuse forbidden arguments before the
+ * handler runs at all, so the flagged value is never read, built into a payload
+ * or written to a log. The refusal is returned through the same scrubbing path
+ * as any other result.
+ */
+export function safeHandler(deps, toolName, handler, declaration) {
+    // `_extra` is where the SDK passes its `RequestHandlerExtra`. It is accepted
+    // and deliberately ignored: `extra.authInfo` is populated only by the HTTP
+    // transports' auth middleware, and this server connects a
+    // `StdioServerTransport` (src/index.ts), so `extra.authInfo` is permanently
+    // empty here and must never be read as an authorisation source — a check
+    // written against it would pass for every caller. `CoreDependencies` is the
+    // same object on every transport, so the call identity is derived from there.
+    return async (args, _extra) => {
+        // Declared out here and assigned inside the try, so that building the
+        // context or reading the credentials is covered by the wrapper as well.
+        // Neither throws today, but the promise this module makes is unconditional:
+        // a statement above the `try` is one whose failure crosses the protocol
+        // boundary raw, and the scrub list would not exist to redact it.
+        let context;
+        let secrets = [];
+        try {
+            context = createCallContext(deps, toolName);
+            secrets = deps.credentials.allSecrets();
+            // Refused ahead of the handler, so a flagged value never reaches the
+            // builder, the signer or the transport. `??` rather than an early return
+            // because a refusal is transcript content like any other result and must
+            // go through the same scrubbing below.
+            const refusal = declaration === undefined ? undefined : refuseDeclaredArguments(deps, context, args, declaration);
+            const result = refusal ?? (await handler(args, context));
+            return {
+                ...result,
+                // A text block often embeds a payload as JSON, so it needs the same
+                // name-based masking as structuredContent: literal masking alone cannot
+                // remove a four-digit MPIN without corrupting unrelated values.
+                content: result.content.map((block) => block.type === 'text' ? { ...block, text: scrubTextForTranscript(block.text, secrets) } : block),
+                // structuredContent is transcript content too. A payload echoed back to
+                // the caller carries pp_Password, so it must be scrubbed as well.
+                ...(result.structuredContent === undefined
+                    ? {}
+                    : { structuredContent: maskSecretsDeep(result.structuredContent, secrets) }),
+            };
+        }
+        catch (error) {
+            logCallFailure(context, error);
+            return toolError(error, secrets);
+        }
+    };
+}
+/**
+ * Record a failed call, without the record becoming the failure.
+ *
+ * Logged through the context, so the record carries the `requestId` as well as
+ * the `tool` binding it already had. Without it, two concurrent calls to the
+ * same tool produce indistinguishable failure records.
+ *
+ * Both defences here exist because this runs on the failure path, where the
+ * caller is owed the scrubbed tool error and nothing else. The context is
+ * absent only when its own construction threw, and the logger writes to stderr,
+ * which can fail — EPIPE once the client has gone. Either would otherwise
+ * replace an explained payment failure with a raw logging one.
+ */
+function logCallFailure(context, error) {
+    try {
+        context?.logger.warn('Tool call failed', { error: describeError(error) });
+    }
+    catch {
+        // Deliberately swallowed: the scrubbed error below is the result that matters.
+    }
+}
+/** Parameter names one flow refuses to accept as a tool argument. */
+function flowForbiddenNames(flow) {
+    return flow.parameters.filter((parameter) => parameter.neverAcceptAsToolArgument).map((parameter) => parameter.name);
+}
+/**
+ * Every flagged name in the catalogue, whatever flow the call names.
+ *
+ * Deliberately the whole union rather than one flow's list: a name one flow
+ * calls a PAN is a PAN wherever it appears, and naming a flow must not be a way
+ * to *narrow* what this server refuses — that would make the refusal weakest for
+ * the caller who told it the most. The tools that take a payload without a
+ * `flowId` — hash debugging, diagnosis, IPN verification — have nothing else to
+ * go on in any case. The stricter reading costs a caller one refusal on a field
+ * named after card data; the looser one accepts a card number that no later
+ * redaction can recall.
+ */
+function catalogueForbiddenNames(catalogue) {
+    return [...new Set(catalogue.list().flatMap(flowForbiddenNames))];
+}
+/**
+ * Fold a field name to the form the refusal compares on.
+ *
+ * Three foldings, each closing a way of writing the same field that this server
+ * would otherwise read as a different one:
+ *
+ *  - NFKC, because `ｖｐ＿Ｐａｎ` in fullwidth forms is `vp_Pan` to every reader
+ *    and to the gateway, and matching raw code points accepts a PAN from anyone
+ *    who typed it that way.
+ *  - Format characters removed, because NFKC leaves them in place: a single
+ *    zero-width space suffixed to `vp_Pan` survives normalisation and the key
+ *    still looks identical in the transcript.
+ *  - Case folded and surrounding whitespace trimmed last, because the point is
+ *    to stop the value being processed, not to grade the caller's spelling.
+ */
+function foldForMatching(name) {
+    // Built per call rather than held at module scope: a `g`-flagged pattern is
+    // mutable state, and this module has no reason to carry any.
+    return name
+        .normalize('NFKC')
+        .replace(/\p{Cf}/gu, '')
+        .trim()
+        .toLowerCase();
+}
+/**
+ * True when `supplied` carries a usable value for `name`, however it is written.
+ *
+ * Absent, null and empty are all treated as nothing supplied, which is the same
+ * line the `tool-argument.forbidden` validation rule draws.
+ */
+function carriesValue(supplied, name) {
+    if (supplied === undefined) {
+        return false;
+    }
+    const wanted = foldForMatching(name);
+    return Object.entries(supplied).some(([key, value]) => foldForMatching(key) === wanted && value !== undefined && value !== null && value !== '');
+}
+/**
+ * Say whose flow flagged the refused names.
+ *
+ * A refusal can name a field the flow in play never declares, because the list
+ * is catalogue-wide. Saying so is the difference between "you sent card data"
+ * and an apparently arbitrary rejection of a field the merchant's own flow
+ * specification does not mention.
+ */
+function attributionSentences(names, flow) {
+    const declared = flowForbiddenNames(flow);
+    const own = names.filter((name) => declared.includes(name));
+    const foreign = names.filter((name) => !declared.includes(name));
+    const sentences = [];
+    if (own.length > 0) {
+        sentences.push(foreign.length === 0
+            ? `${flow.title} declares ${own.length === 1 ? 'this field' : 'these fields'} as data that cannot cross the tool boundary.`
+            : `${flow.title} declares ${own.join(', ')} as data that cannot cross the tool boundary.`);
+    }
+    if (foreign.length > 0) {
+        sentences.push(`${foreign.join(', ')} ${foreign.length === 1 ? 'is' : 'are'} flagged by another flow in this catalogue rather than by ${flow.title}, and a name one flow uses for card data is card data wherever it appears, so it is refused here too.`);
+    }
+    return sentences.join(' ');
+}
+/** Explain the refusal, naming the fields and nothing else. */
+function forbiddenArgumentText(names, flow) {
+    const single = names.length === 1;
+    return [
+        `Refused: this call carries ${single ? 'a field' : 'fields'} that must never reach this server as a tool argument. Nothing was built, signed, sent or verified.`,
+        '',
+        '## Refused',
+        bulletList(names),
+        '',
+        'Only the names are listed above. The values are repeated nowhere in this result, and this server has neither processed nor stored them.',
+        '',
+        flow === undefined
+            ? // Both ways of arriving here, because the wrapper's lookup is tolerant:
+                // a mistyped id must not turn a call carrying card data into "no such
+                // flow", which would report nothing about the field that was sent.
+                'No flowId was supplied, or the one supplied names no flow in this catalogue, so every field any flow in the catalogue marks as unacceptable is refused.'
+            : attributionSentences(names, flow),
+        '',
+        '## What to do instead',
+        `${single ? 'This field belongs' : 'These fields belong'} in the integration code that runs on your own server, never in a tool call. Generate that code with jazzcash_generate_integration_code — it emits every field, including ${single ? 'this one' : 'these'} — and supply the value there, or use the provider's hosted page or hosted fields so it travels from the customer's browser to the gateway without passing through you.`,
+        '',
+        'A tool argument is written to the conversation before this server runs, so refusing it here cannot recall it. Treat the value already sent as compromised.',
+    ].join('\n');
+}
+/**
+ * Refuse a call carrying a parameter a flow forbids as a tool argument.
+ *
+ * Module-private: every tool reaches it through a
+ * {@link PayloadArgumentDeclaration}, so the check is a property of the
+ * registration rather than a line each handler has to remember to write. A
+ * handler that called it directly could also decide not to.
+ *
+ * `flow` chooses the wording only. The names refused are the catalogue-wide
+ * union in every case, so naming a flow can never narrow what is refused; see
+ * {@link catalogueForbiddenNames}.
+ *
+ * The `tool-argument.forbidden` validation rule still stands behind this and is
+ * not made redundant by it: the rule also fires for a payload assembled inside
+ * the server, and it is the last line for any caller path added later.
+ *
+ * Returns `undefined` when there is nothing to refuse, so the handler proceeds
+ * unchanged for every payload that carries no flagged field.
+ */
+function refuseForbiddenArguments(deps, context, flow, ...supplied) {
+    const forbidden = catalogueForbiddenNames(deps.catalogue);
+    const refused = forbidden.filter((name) => supplied.some((object) => carriesValue(object, name)));
+    if (refused.length === 0) {
+        return undefined;
+    }
+    // The catalogue's spelling of each name is recorded, never the caller's key
+    // and never the value: a log record is exactly the durable artefact this
+    // refusal exists to keep card data out of.
+    context.logger.warn('Refused a tool argument the flow forbids', { fields: refused });
+    return toolResult(forbiddenArgumentText(refused, flow), {
+        isError: true,
+        structuredContent: {
+            refused: true,
+            flowId: flow?.id ?? null,
+            refusedFields: refused,
+        },
+    });
+}
+/**
+ * Read an argument as a payload map, or as nothing at all.
+ *
+ * An argument the caller omitted, or sent as an array or a scalar, addresses no
+ * field by name and so can carry no flagged one. Narrowed rather than cast: a
+ * declaration naming an argument that is not a map must degrade to "nothing
+ * supplied" instead of throwing inside the refusal check.
+ */
+function payloadRecordOf(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Apply a registered {@link PayloadArgumentDeclaration} to one call's arguments. */
+function refuseDeclaredArguments(deps, context, args, declaration) {
+    const supplied = payloadRecordOf(args) ?? {};
+    const flowId = declaration.flowFrom === undefined ? undefined : supplied[declaration.flowFrom];
+    // `find` rather than `get`: the flow chooses the wording of the refusal and
+    // nothing else, so a lookup that threw would make the wrapper decide what an
+    // unknown flow id means — a decision each tool already makes for itself, and
+    // differently. It would also answer a call carrying a PAN with "no such flow",
+    // leaving the field neither refused nor reported.
+    const flow = typeof flowId === 'string' ? deps.catalogue.find(flowId) : undefined;
+    return refuseForbiddenArguments(deps, context, flow, ...declaration.payloadArguments.map((name) => payloadRecordOf(supplied[name])));
+}
+/** Resolve the environment a tool should act in, defaulting to the configured one. */
+export function resolveEnvironment(deps, requested) {
+    return requested ?? deps.config.defaultEnvironment;
+}
+/**
+ * Resolve the Integrity Salt for a hash operation.
+ *
+ * An explicit salt is accepted because a merchant debugging a mismatch usually
+ * has the value in front of them and may not have configured the server yet.
+ */
+export function resolveIntegritySalt(deps, explicitSalt, environment) {
+    if (explicitSalt !== undefined && explicitSalt !== '') {
+        return { salt: explicitSalt, source: 'supplied in the tool call' };
+    }
+    const profile = deps.credentials.get(environment);
+    return { salt: profile.integritySalt, source: `the configured ${environment} credentials` };
+}
+/** Render a bullet list, or a placeholder when there is nothing to list. */
+export function bulletList(items, empty = '(none)') {
+    return items.length === 0 ? empty : items.map((item) => `- ${item}`).join('\n');
+}
+/** Render a citation line for a set of documentation references. */
+export function citations(refs) {
+    if (refs.length === 0) {
+        return '';
+    }
+    const unique = [
+        ...new Set(refs.map((ref) => `jazzcash://docs/${ref.docId}${ref.sectionId === undefined ? '' : `#${ref.sectionId}`}`)),
+    ];
+    return `\n\nSources: ${unique.join(', ')}`;
+}
+//# sourceMappingURL=tool-kit.js.map

package/dist/tools/tool-kit.js.map

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

package/dist/validation/payload-validator.d.ts

@@ -0,0 +1,29 @@
+import type { IntegrationFlow } from '../catalogue/types.js';
+import { type NormalisedParameters, type RawParameters } from '../domain/types.js';
+import type { ValidationIssue, ValidationRule } from './types.js';
+/**
+ * Payload validation.
+ *
+ * Composes the independent rule modules. Each rule owns exactly one concern and
+ * is responsible for not duplicating another rule's diagnosis, so a single
+ * mistake yields a single actionable issue rather than a wall of noise.
+ */
+export declare const VALIDATION_RULES: readonly ValidationRule[];
+export interface ValidationOptions {
+    /** The `pp_ReturnURL` registered against the merchant profile, when known. */
+    readonly registeredReturnUrl?: string | undefined;
+    readonly now?: Date | undefined;
+}
+export interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationIssue[];
+    readonly warnings: readonly ValidationIssue[];
+    /** Every value coerced to its wire representation, ready to hash and send. */
+    readonly normalisedPayload: NormalisedParameters;
+    readonly flowId: string;
+}
+/** Validate a payload against its flow specification. */
+export declare function validatePayload(flow: IntegrationFlow, parameters: RawParameters, options?: ValidationOptions): ValidationResult;
+/** Render a validation result as text for a merchant or an AI harness. */
+export declare function formatValidationResult(result: ValidationResult): string;
+//# sourceMappingURL=payload-validator.d.ts.map

package/dist/validation/payload-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-validator.d.ts","sourceRoot":"","sources":["../../src/validation/payload-validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAuB,KAAK,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAexG,OAAO,KAAK,EAAe,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE/E;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAoBrD,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,8EAA8E;IAC9E,QAAQ,CAAC,iBAAiB,EAAE,oBAAoB,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,aAAa,EACzB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAkBlB;AAED,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAqBvE"}

package/dist/validation/payload-validator.js

@@ -0,0 +1,79 @@
+import { normaliseParameters } from '../domain/types.js';
+import { amountRule } from './rules/amount.js';
+import { billReferenceRule } from './rules/bill-reference.js';
+import { cnicRule } from './rules/cnic.js';
+import { constantsRule } from './rules/constants.js';
+import { constraintsRule } from './rules/constraints.js';
+import { dateTimeRule } from './rules/datetime.js';
+import { emptyStringRule } from './rules/empty-string.js';
+import { expiryRule } from './rules/expiry.js';
+import { msisdnRule } from './rules/msisdn.js';
+import { presenceRule } from './rules/presence.js';
+import { returnUrlRule } from './rules/return-url.js';
+import { toolArgumentRule } from './rules/tool-argument.js';
+import { txnRefRule } from './rules/txn-ref.js';
+import { unknownFieldsRule } from './rules/unknown-fields.js';
+/**
+ * Payload validation.
+ *
+ * Composes the independent rule modules. Each rule owns exactly one concern and
+ * is responsible for not duplicating another rule's diagnosis, so a single
+ * mistake yields a single actionable issue rather than a wall of noise.
+ */
+export const VALIDATION_RULES = [
+    // First: every other rule describes a payload the merchant is expected to
+    // correct, whereas this one reports data that should never have reached the
+    // server at all. Reported ahead of them so it cannot be lost in the list.
+    toolArgumentRule,
+    presenceRule,
+    unknownFieldsRule,
+    emptyStringRule,
+    constantsRule,
+    amountRule,
+    dateTimeRule,
+    expiryRule,
+    txnRefRule,
+    billReferenceRule,
+    returnUrlRule,
+    msisdnRule,
+    cnicRule,
+    // Last: the generic constraint check reports what the specific rules above do
+    // not express, so their more precise diagnosis comes first.
+    constraintsRule,
+];
+/** Validate a payload against its flow specification. */
+export function validatePayload(flow, parameters, options = {}) {
+    const context = {
+        flow,
+        parameters: normaliseParameters(parameters),
+        registeredReturnUrl: options.registeredReturnUrl,
+        now: options.now ?? new Date(),
+    };
+    const issues = VALIDATION_RULES.flatMap((rule) => rule(context));
+    const errors = issues.filter((entry) => entry.severity === 'error');
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings: issues.filter((entry) => entry.severity === 'warning'),
+        normalisedPayload: context.parameters,
+        flowId: flow.id,
+    };
+}
+/** Render a validation result as text for a merchant or an AI harness. */
+export function formatValidationResult(result) {
+    if (result.valid && result.warnings.length === 0) {
+        return `The payload is valid for ${result.flowId}. No issues found.`;
+    }
+    const lines = [];
+    lines.push(result.valid
+        ? `The payload is valid for ${result.flowId}, with ${String(result.warnings.length)} warning(s).`
+        : `The payload is NOT valid for ${result.flowId}: ${String(result.errors.length)} error(s), ${String(result.warnings.length)} warning(s).`);
+    for (const entry of [...result.errors, ...result.warnings]) {
+        const label = entry.severity === 'error' ? 'ERROR' : 'WARN ';
+        lines.push('', `${label} [${entry.code}]${entry.field === undefined ? '' : ` ${entry.field}`}`);
+        lines.push(`  ${entry.message}`);
+        lines.push(`  Fix: ${entry.fix}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=payload-validator.js.map

package/dist/validation/payload-validator.js.map

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

package/dist/validation/rules/amount.d.ts

@@ -0,0 +1,3 @@
+import { type ValidationRule } from '../types.js';
+export declare const amountRule: ValidationRule;
+//# sourceMappingURL=amount.d.ts.map

package/dist/validation/rules/amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../../../src/validation/rules/amount.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AA2B/E,eAAO,MAAM,UAAU,EAAE,cA0DxB,CAAC"}

package/dist/validation/rules/amount.js

@@ -0,0 +1,77 @@
+import { assertMinorUnits, fromMinorUnits, looksLikeMajorUnits, toMinorUnits } from '../../domain/amount.js';
+import { describeError } from '../../errors.js';
+import { issue } from '../types.js';
+/**
+ * `pp_Amount` must be a positive whole number of minor units.
+ *
+ * Forgetting the ×100 conversion is the most common integration error after the
+ * secure hash, so the failure message names the conversion explicitly rather
+ * than reporting a generic format problem.
+ */
+/**
+ * Suggest the exact minor-unit value, or no value at all.
+ *
+ * `fix` is documented as the machine-actionable remedy, so an agent may apply it
+ * verbatim to a payment: a number that is approximately right is worse than no
+ * number. The exact converter is reused rather than the digits rearranged by
+ * hand, and when it refuses the value the advice stays deliberately general.
+ */
+function conversionAdvice(value) {
+    let minorUnits;
+    try {
+        minorUnits = toMinorUnits(value);
+    }
+    catch {
+        return 'Multiply by 100 and send a whole number of minor units, with no decimal point. PKR 100.00 is sent as "10000".';
+    }
+    return `Multiply by 100 and send a whole number: PKR ${value} becomes "${minorUnits}". PKR 100.00 is sent as "10000".`;
+}
+export const amountRule = (context) => {
+    const parameter = context.flow.parameters.find((entry) => entry.valueType === 'minor-units');
+    if (parameter === undefined) {
+        return [];
+    }
+    const value = context.parameters[parameter.name];
+    if (value === undefined || value === '') {
+        // Absence and emptiness are both reported by the presence rule; do not
+        // report either twice.
+        return [];
+    }
+    const issues = [];
+    if (looksLikeMajorUnits(value)) {
+        issues.push(issue(context, {
+            code: 'amount.not-minor-units',
+            severity: 'error',
+            field: parameter.name,
+            message: `${parameter.name} is "${value}", which contains a decimal point. The gateway reads the last two digits as decimals, so amounts are transmitted as whole minor units.`,
+            fix: conversionAdvice(value),
+        }));
+        return issues;
+    }
+    try {
+        assertMinorUnits(value);
+    }
+    catch (error) {
+        issues.push(issue(context, {
+            code: 'amount.invalid',
+            severity: 'error',
+            field: parameter.name,
+            message: describeError(error),
+            fix: 'Send pp_Amount as a positive whole number of minor units, for example "100" for PKR 1.00.',
+        }));
+        return issues;
+    }
+    // A PKR 1.00 test transaction is "100" and entirely legitimate, so a small
+    // value is only worth a note, never an error.
+    if (Number(value) < 100) {
+        issues.push(issue(context, {
+            code: 'amount.suspiciously-small',
+            severity: 'warning',
+            field: parameter.name,
+            message: `${parameter.name} is "${value}", which the gateway reads as PKR ${fromMinorUnits(value)}.`,
+            fix: `Confirm this is intended. If you meant PKR ${value}.00, send "${value}00" instead.`,
+        }));
+    }
+    return issues;
+};
+//# sourceMappingURL=amount.js.map

package/dist/validation/rules/amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.js","sourceRoot":"","sources":["../../../src/validation/rules/amount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC7G,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,EAA6C,MAAM,aAAa,CAAC;AAE/E;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,+GAA+G,CAAC;IACzH,CAAC;IACD,OAAO,gDAAgD,KAAK,aAAa,UAAU,mCAAmC,CAAC;AACzH,CAAC;AACD,MAAM,CAAC,MAAM,UAAU,GAAmB,CAAC,OAAO,EAA8B,EAAE;IAChF,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,aAAa,CAAC,CAAC;IAC7F,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACxC,uEAAuE;QACvE,uBAAuB;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAsB,EAAE,CAAC;IAErC,IAAI,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,CACT,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,wBAAwB;YAC9B,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,SAAS,CAAC,IAAI;YACrB,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,QAAQ,KAAK,wIAAwI;YAC/K,GAAG,EAAE,gBAAgB,CAAC,KAAK,CAAC;SAC7B,CAAC,CACH,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,CAAC;QACH,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CACT,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,gBAAgB;YACtB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,SAAS,CAAC,IAAI;YACrB,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC;YAC7B,GAAG,EAAE,2FAA2F;SACjG,CAAC,CACH,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,2EAA2E;IAC3E,8CAA8C;IAC9C,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CACT,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,2BAA2B;YACjC,QAAQ,EAAE,SAAS;YACnB,KAAK,EAAE,SAAS,CAAC,IAAI;YACrB,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,QAAQ,KAAK,qCAAqC,cAAc,CAAC,KAAK,CAAC,GAAG;YACpG,GAAG,EAAE,8CAA8C,KAAK,cAAc,KAAK,cAAc;SAC1F,CAAC,CACH,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/dist/validation/rules/bill-reference.d.ts

@@ -0,0 +1,10 @@
+import { type ValidationRule } from '../types.js';
+/**
+ * `pp_BillReference` must be alphanumeric.
+ *
+ * "Must contain only alphanumeric characters. Spaces and special characters are
+ * not allowed." Order numbers such as `ORD-1024` and `INV/2026/01` are the usual
+ * offenders, so the fix suggests the stripped form rather than restating the rule.
+ */
+export declare const billReferenceRule: ValidationRule;
+//# sourceMappingURL=bill-reference.d.ts.map

package/dist/validation/rules/bill-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bill-reference.d.ts","sourceRoot":"","sources":["../../../src/validation/rules/bill-reference.ts"],"names":[],"mappings":"AACA,OAAO,EAA+B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,cA8B/B,CAAC"}

package/dist/validation/rules/bill-reference.js

@@ -0,0 +1,34 @@
+import { validateBillReference } from '../../domain/txn-ref.js';
+import { issue } from '../types.js';
+/**
+ * `pp_BillReference` must be alphanumeric.
+ *
+ * "Must contain only alphanumeric characters. Spaces and special characters are
+ * not allowed." Order numbers such as `ORD-1024` and `INV/2026/01` are the usual
+ * offenders, so the fix suggests the stripped form rather than restating the rule.
+ */
+export const billReferenceRule = (context) => {
+    const parameter = context.flow.parameters.find((entry) => entry.valueType === 'bill-reference');
+    if (parameter === undefined) {
+        return [];
+    }
+    const value = context.parameters[parameter.name];
+    if (value === undefined || value === '') {
+        return [];
+    }
+    const check = validateBillReference(value);
+    if (check.valid) {
+        return [];
+    }
+    const suggestion = value.replace(/[^A-Za-z0-9]/g, '');
+    return check.issues.map((problem) => issue(context, {
+        code: 'bill-reference.invalid',
+        severity: 'error',
+        field: parameter.name,
+        message: problem.replace(/^pp_\w+/, parameter.name),
+        fix: suggestion === ''
+            ? `Supply an alphanumeric ${parameter.name}, for example "billRef185".`
+            : `Strip the punctuation, for example "${suggestion}". The value may repeat across transactions, so it does not need to be unique.`,
+    }));
+};
+//# sourceMappingURL=bill-reference.js.map

package/dist/validation/rules/bill-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bill-reference.js","sourceRoot":"","sources":["../../../src/validation/rules/bill-reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,KAAK,EAA6C,MAAM,aAAa,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAmB,CAAC,OAAO,EAA8B,EAAE;IACvF,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,gBAAgB,CAAC,CAAC;IAChG,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACxC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;IAEtD,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,EAAmB,EAAE,CACnD,KAAK,CAAC,OAAO,EAAE;QACb,IAAI,EAAE,wBAAwB;QAC9B,QAAQ,EAAE,OAAO;QACjB,KAAK,EAAE,SAAS,CAAC,IAAI;QACrB,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC;QACnD,GAAG,EACD,UAAU,KAAK,EAAE;YACf,CAAC,CAAC,0BAA0B,SAAS,CAAC,IAAI,6BAA6B;YACvE,CAAC,CAAC,uCAAuC,UAAU,gFAAgF;KACxI,CAAC,CACH,CAAC;AACJ,CAAC,CAAC"}

package/dist/validation/rules/cnic.d.ts

@@ -0,0 +1,3 @@
+import { type ValidationRule } from '../types.js';
+export declare const cnicRule: ValidationRule;
+//# sourceMappingURL=cnic.d.ts.map

package/dist/validation/rules/cnic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cnic.d.ts","sourceRoot":"","sources":["../../../src/validation/rules/cnic.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAa/E,eAAO,MAAM,QAAQ,EAAE,cAkCtB,CAAC"}

package/dist/validation/rules/cnic.js

@@ -0,0 +1,42 @@
+import { issue } from '../types.js';
+/**
+ * `pp_CNIC` carries the LAST SIX DIGITS of the customer's CNIC, not the whole number.
+ *
+ * The MWallet v2.0 guide annotates the field as `{{Last 6-digits}}`. Sending the
+ * full 13-digit CNIC is both a validation failure and an unnecessary disclosure
+ * of personal data, so it is called out specifically.
+ */
+const LAST_SIX_DIGITS = /^\d{6}$/;
+const FULL_CNIC = /^\d{5}-?\d{7}-?\d$/;
+export const cnicRule = (context) => {
+    const parameter = context.flow.parameters.find((entry) => entry.valueType === 'cnic');
+    if (parameter === undefined) {
+        return [];
+    }
+    const value = context.parameters[parameter.name];
+    if (value === undefined || value === '' || LAST_SIX_DIGITS.test(value)) {
+        return [];
+    }
+    const digits = value.replace(/\D/g, '');
+    if (FULL_CNIC.test(value)) {
+        return [
+            issue(context, {
+                code: 'cnic.full-number-supplied',
+                severity: 'error',
+                field: parameter.name,
+                message: `${parameter.name} appears to be a full CNIC. The gateway expects only the last six digits, and sending the whole number discloses more personal data than the integration requires.`,
+                fix: `Send only the last six digits: "${digits.slice(-6)}".`,
+            }),
+        ];
+    }
+    return [
+        issue(context, {
+            code: 'cnic.invalid',
+            severity: 'error',
+            field: parameter.name,
+            message: `${parameter.name} is not six digits.`,
+            fix: 'Send exactly the last six digits of the customer CNIC, with no dashes or spaces.',
+        }),
+    ];
+};
+//# sourceMappingURL=cnic.js.map

package/dist/validation/rules/cnic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cnic.js","sourceRoot":"","sources":["../../../src/validation/rules/cnic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA6C,MAAM,aAAa,CAAC;AAE/E;;;;;;GAMG;AAEH,MAAM,eAAe,GAAG,SAAS,CAAC;AAClC,MAAM,SAAS,GAAG,oBAAoB,CAAC;AAEvC,MAAM,CAAC,MAAM,QAAQ,GAAmB,CAAC,OAAO,EAA8B,EAAE;IAC9E,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC;IACtF,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvE,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAExC,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,KAAK,CAAC,OAAO,EAAE;gBACb,IAAI,EAAE,2BAA2B;gBACjC,QAAQ,EAAE,OAAO;gBACjB,KAAK,EAAE,SAAS,CAAC,IAAI;gBACrB,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,oKAAoK;gBAC9L,GAAG,EAAE,mCAAmC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;aAC7D,CAAC;SACH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,cAAc;YACpB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,SAAS,CAAC,IAAI;YACrB,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,qBAAqB;YAC/C,GAAG,EAAE,kFAAkF;SACxF,CAAC;KACH,CAAC;AACJ,CAAC,CAAC"}