@atbas/m-mcp 0.1.0

package/dist/validation/rules/tool-argument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-argument.d.ts","sourceRoot":"","sources":["../../../src/validation/rules/tool-argument.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,EAAE,cA4B9B,CAAC"}

package/dist/validation/rules/tool-argument.js

@@ -0,0 +1,38 @@
+import { issue } from '../types.js';
+/**
+ * A parameter the flow marks `neverAcceptAsToolArgument` must not appear at all.
+ *
+ * Card flows carry the PAN, the expiry and the CVV. `safeHandler` scrubs tool
+ * OUTPUTS, not inputs, so a value supplied here was written to the conversation
+ * transcript — and to whatever the harness persists of it — before any server
+ * code ran. By the time this rule fires the disclosure has already happened, so
+ * the issue says so plainly instead of offering a correction that would repeat
+ * it: the only safe next step is to route the value around this server and to
+ * treat the one already sent as compromised.
+ *
+ * The value is never echoed back, for the same reason.
+ */
+export const toolArgumentRule = (context) => {
+    const issues = [];
+    for (const parameter of context.flow.parameters) {
+        if (!parameter.neverAcceptAsToolArgument) {
+            continue;
+        }
+        // Absent is the expected state, and an empty string carries nothing: the
+        // presence rule deliberately leaves such a parameter alone rather than
+        // asking the merchant to supply one, so neither case is a disclosure.
+        const value = context.parameters[parameter.name];
+        if (value === undefined || value === '') {
+            continue;
+        }
+        issues.push(issue(context, {
+            code: 'tool-argument.forbidden',
+            severity: 'error',
+            field: parameter.name,
+            message: `${parameter.name} must never be sent through this server. ${context.flow.title} declares it as data that cannot cross the tool boundary, and the value supplied here was already recorded in the conversation before validation ran.`,
+            fix: `Remove "${parameter.name}" from the payload and let your own server, or the provider's hosted field, supply it directly to the gateway. Treat the value already sent as compromised.`,
+        }));
+    }
+    return issues;
+};
+//# sourceMappingURL=tool-argument.js.map

package/dist/validation/rules/tool-argument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-argument.js","sourceRoot":"","sources":["../../../src/validation/rules/tool-argument.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAA6C,MAAM,aAAa,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAmB,CAAC,OAAO,EAA8B,EAAE;IACtF,MAAM,MAAM,GAAsB,EAAE,CAAC;IAErC,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,CAAC,SAAS,CAAC,yBAAyB,EAAE,CAAC;YACzC,SAAS;QACX,CAAC;QAED,yEAAyE;QACzE,uEAAuE;QACvE,sEAAsE;QACtE,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACxC,SAAS;QACX,CAAC;QAED,MAAM,CAAC,IAAI,CACT,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,yBAAyB;YAC/B,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,SAAS,CAAC,IAAI;YACrB,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,4CAA4C,OAAO,CAAC,IAAI,CAAC,KAAK,uJAAuJ;YAC/O,GAAG,EAAE,WAAW,SAAS,CAAC,IAAI,6JAA6J;SAC5L,CAAC,CACH,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/dist/validation/rules/txn-ref.d.ts

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

package/dist/validation/rules/txn-ref.d.ts.map

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

package/dist/validation/rules/txn-ref.js

@@ -0,0 +1,47 @@
+import { MAX_TXN_REF_LENGTH, validateRequestId, validateTxnRefNo } from '../../domain/txn-ref.js';
+import { issue } from '../types.js';
+/**
+ * `pp_TxnRefNo` and `pp_RequestID` must be unique alphanumeric identifiers.
+ *
+ * Uniqueness cannot be checked from a single payload, so it is surfaced as a
+ * standing reminder whenever the value looks like it could have been reused —
+ * specifically when it carries no time component.
+ */
+const CONTAINS_TIMESTAMP = /\d{14}/;
+export const txnRefRule = (context) => {
+    const issues = [];
+    for (const parameter of context.flow.parameters) {
+        if (parameter.valueType !== 'txn-ref' && parameter.valueType !== 'request-id') {
+            continue;
+        }
+        const value = context.parameters[parameter.name];
+        if (value === undefined || value === '') {
+            continue;
+        }
+        // The flow's own declared maximum wins over the documented default, so a
+        // correction from JazzCash stays a data change rather than a code change.
+        const check = parameter.valueType === 'txn-ref'
+            ? validateTxnRefNo(value, parameter.maxLength)
+            : validateRequestId(value, parameter.maxLength);
+        for (const problem of check.issues) {
+            issues.push(issue(context, {
+                code: 'txn-ref.invalid',
+                severity: 'error',
+                field: parameter.name,
+                message: problem.replace(/^pp_\w+/, parameter.name),
+                fix: `Use up to ${String(parameter.maxLength ?? MAX_TXN_REF_LENGTH)} letters and digits. The documented shape is a three-letter merchant prefix followed by YYYYMMDDHHMMSS, for example "Goo20230208115409".`,
+            }));
+        }
+        if (check.valid && !CONTAINS_TIMESTAMP.test(value)) {
+            issues.push(issue(context, {
+                code: 'txn-ref.uniqueness-unverifiable',
+                severity: 'warning',
+                field: parameter.name,
+                message: `${parameter.name} ("${value}") carries no timestamp, so uniqueness across transactions cannot be inferred. The gateway rejects a reference it has already seen.`,
+                fix: 'Append a YYYYMMDDHHMMSS stamp, plus a few random alphanumeric characters if you may create more than one transaction per second. A clock alone cannot separate two references generated in the same instant.',
+            }));
+        }
+    }
+    return issues;
+};
+//# sourceMappingURL=txn-ref.js.map

package/dist/validation/rules/txn-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"txn-ref.js","sourceRoot":"","sources":["../../../src/validation/rules/txn-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAClG,OAAO,EAAE,KAAK,EAA6C,MAAM,aAAa,CAAC;AAE/E;;;;;;GAMG;AAEH,MAAM,kBAAkB,GAAG,QAAQ,CAAC;AAEpC,MAAM,CAAC,MAAM,UAAU,GAAmB,CAAC,OAAO,EAA8B,EAAE;IAChF,MAAM,MAAM,GAAsB,EAAE,CAAC;IAErC,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,SAAS,CAAC,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,SAAS,KAAK,YAAY,EAAE,CAAC;YAC9E,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACxC,SAAS;QACX,CAAC;QAED,yEAAyE;QACzE,0EAA0E;QAC1E,MAAM,KAAK,GACT,SAAS,CAAC,SAAS,KAAK,SAAS;YAC/B,CAAC,CAAC,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC;YAC9C,CAAC,CAAC,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;QAEpD,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACnC,MAAM,CAAC,IAAI,CACT,KAAK,CAAC,OAAO,EAAE;gBACb,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,OAAO;gBACjB,KAAK,EAAE,SAAS,CAAC,IAAI;gBACrB,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC;gBACnD,GAAG,EAAE,aAAa,MAAM,CAAC,SAAS,CAAC,SAAS,IAAI,kBAAkB,CAAC,0IAA0I;aAC9M,CAAC,CACH,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnD,MAAM,CAAC,IAAI,CACT,KAAK,CAAC,OAAO,EAAE;gBACb,IAAI,EAAE,iCAAiC;gBACvC,QAAQ,EAAE,SAAS;gBACnB,KAAK,EAAE,SAAS,CAAC,IAAI;gBACrB,OAAO,EAAE,GAAG,SAAS,CAAC,IAAI,MAAM,KAAK,qIAAqI;gBAC1K,GAAG,EAAE,8MAA8M;aACpN,CAAC,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/dist/validation/rules/unknown-fields.d.ts

@@ -0,0 +1,10 @@
+import { type ValidationRule } from '../types.js';
+/**
+ * No parameter may be added that the flow does not declare.
+ *
+ * "No parameters may be added or removed from the request payload." An extra
+ * field with a non-empty value silently changes the secure hash, which surfaces
+ * to the merchant as an unexplained mismatch rather than as a rejected field.
+ */
+export declare const unknownFieldsRule: ValidationRule;
+//# sourceMappingURL=unknown-fields.d.ts.map

package/dist/validation/rules/unknown-fields.d.ts.map

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

package/dist/validation/rules/unknown-fields.js

@@ -0,0 +1,29 @@
+import { parameterNames } from '../../catalogue/types.js';
+import { issue } from '../types.js';
+/**
+ * No parameter may be added that the flow does not declare.
+ *
+ * "No parameters may be added or removed from the request payload." An extra
+ * field with a non-empty value silently changes the secure hash, which surfaces
+ * to the merchant as an unexplained mismatch rather than as a rejected field.
+ */
+export const unknownFieldsRule = (context) => {
+    const declared = new Set(parameterNames(context.flow));
+    const issues = [];
+    for (const name of Object.keys(context.parameters)) {
+        if (declared.has(name)) {
+            continue;
+        }
+        const value = context.parameters[name] ?? '';
+        const affectsHash = value !== '' && context.flow.hash.includeFieldPrefixes.some((prefix) => name.startsWith(prefix));
+        issues.push(issue(context, {
+            code: 'unknown-fields.not-declared',
+            severity: 'error',
+            field: name,
+            message: `${name} is not part of ${context.flow.title}.${affectsHash ? ' It is non-empty and matches a hashed prefix, so it is also corrupting your secure hash.' : ''}`,
+            fix: `Remove "${name}" from the payload. The documented field set for this flow is: ${parameterNames(context.flow).join(', ')}.`,
+        }));
+    }
+    return issues;
+};
+//# sourceMappingURL=unknown-fields.js.map

package/dist/validation/rules/unknown-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-fields.js","sourceRoot":"","sources":["../../../src/validation/rules/unknown-fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,KAAK,EAA6C,MAAM,aAAa,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAmB,CAAC,OAAO,EAA8B,EAAE;IACvF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,MAAM,MAAM,GAAsB,EAAE,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACnD,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC7C,MAAM,WAAW,GACf,KAAK,KAAK,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QAEnG,MAAM,CAAC,IAAI,CACT,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,6BAA6B;YACnC,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,IAAI;YACX,OAAO,EAAE,GAAG,IAAI,mBAAmB,OAAO,CAAC,IAAI,CAAC,KAAK,IACnD,WAAW,CAAC,CAAC,CAAC,0FAA0F,CAAC,CAAC,CAAC,EAC7G,EAAE;YACF,GAAG,EAAE,WAAW,IAAI,kEAAkE,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;SACjI,CAAC,CACH,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/dist/validation/types.d.ts

@@ -0,0 +1,36 @@
+import type { IntegrationFlow } from '../catalogue/types.js';
+import type { NormalisedParameters } from '../domain/types.js';
+import type { DocRef } from '../errors.js';
+/**
+ * Validation vocabulary.
+ *
+ * Every issue is structured rather than a bare string, so a tool result can be
+ * rendered for a human and consumed by a model without re-parsing prose. The
+ * `fix` field is mandatory: an error that does not say what to do instead is an
+ * error the merchant will bring straight back to a support engineer.
+ */
+export type IssueSeverity = 'error' | 'warning';
+export interface ValidationIssue {
+    /** Stable machine-readable identifier, e.g. `amount.not-minor-units`. */
+    readonly code: string;
+    readonly severity: IssueSeverity;
+    /** Parameter this concerns, or `undefined` for payload-level issues. */
+    readonly field: string | undefined;
+    readonly message: string;
+    readonly fix: string;
+    readonly docRefs: readonly DocRef[];
+}
+export interface RuleContext {
+    readonly flow: IntegrationFlow;
+    readonly parameters: NormalisedParameters;
+    /** The `pp_ReturnURL` registered against the merchant profile, when known. */
+    readonly registeredReturnUrl: string | undefined;
+    /** Injectable clock so plausibility checks are deterministic under test. */
+    readonly now: Date;
+}
+export type ValidationRule = (context: RuleContext) => readonly ValidationIssue[];
+/** Build an issue, defaulting the citations to the flow's own documentation. */
+export declare function issue(context: RuleContext, partial: Omit<ValidationIssue, 'docRefs'> & {
+    docRefs?: readonly DocRef[];
+}): ValidationIssue;
+//# sourceMappingURL=types.d.ts.map

package/dist/validation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/validation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;;;GAOG;AAEH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,8EAA8E;IAC9E,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;IACjD,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,SAAS,eAAe,EAAE,CAAC;AAElF,gFAAgF;AAChF,wBAAgB,KAAK,CACnB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC1E,eAAe,CASjB"}

package/dist/validation/types.js

@@ -0,0 +1,12 @@
+/** Build an issue, defaulting the citations to the flow's own documentation. */
+export function issue(context, partial) {
+    return {
+        code: partial.code,
+        severity: partial.severity,
+        field: partial.field,
+        message: partial.message,
+        fix: partial.fix,
+        docRefs: partial.docRefs ?? context.flow.docRefs,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/validation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/validation/types.ts"],"names":[],"mappings":"AAqCA,gFAAgF;AAChF,MAAM,UAAU,KAAK,CACnB,OAAoB,EACpB,OAA2E;IAE3E,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO;KACjD,CAAC;AACJ,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Server name and version reported to MCP clients.
+ *
+ * Kept as source rather than imported from `package.json`, which lives outside
+ * `rootDir`. `tests/version.test.ts` asserts the two stay in step, so this
+ * cannot drift silently.
+ *
+ * The npm package is scoped — `@atbas/m-mcp` — and this is deliberately not.
+ * It is also the key an install writes into a harness config file, and a scope
+ * there buys nothing while costing a quoted TOML key and a `/` in every
+ * merchant's configuration. The parity test compares this against the package
+ * name with its scope removed, so the two still cannot drift apart.
+ */
+export declare const SERVER_NAME = "m-mcp";
+export declare const SERVER_VERSION = "0.1.0";
+/**
+ * Version stamp of the JazzCash documentation corpus this build encodes.
+ *
+ * Every guide under `docs/integration_documents/` is marked "VERSION: 2026".
+ * When a newer set of guides arrives, regenerate the corpus and bump this.
+ */
+export declare const CORPUS_VERSION = "2026";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,SAAS,CAAC"}

package/dist/version.js

@@ -0,0 +1,23 @@
+/**
+ * Server name and version reported to MCP clients.
+ *
+ * Kept as source rather than imported from `package.json`, which lives outside
+ * `rootDir`. `tests/version.test.ts` asserts the two stay in step, so this
+ * cannot drift silently.
+ *
+ * The npm package is scoped — `@atbas/m-mcp` — and this is deliberately not.
+ * It is also the key an install writes into a harness config file, and a scope
+ * there buys nothing while costing a quoted TOML key and a `/` in every
+ * merchant's configuration. The parity test compares this against the package
+ * name with its scope removed, so the two still cannot drift apart.
+ */
+export const SERVER_NAME = 'm-mcp';
+export const SERVER_VERSION = '0.1.0';
+/**
+ * Version stamp of the JazzCash documentation corpus this build encodes.
+ *
+ * Every guide under `docs/integration_documents/` is marked "VERSION: 2026".
+ * When a newer set of guides arrives, regenerate the corpus and bump this.
+ */
+export const CORPUS_VERSION = '2026';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC"}

package/knowledge/diagnostics/symptoms.json

@@ -0,0 +1,321 @@
+{
+  "version": "2026",
+  "note": "Symptom knowledge base. Every entry is traceable to the 2026 guides or to a defect found in their own samples. Causes are ordered most-likely-first.",
+  "symptoms": [
+    {
+      "id": "hash-mismatch",
+      "title": "Secure hash mismatch (HASH_MISMATCH)",
+      "keywords": ["hash", "mismatch", "securehash", "signature", "invalid hash", "hash_mismatch", "integrity"],
+      "causes": [
+        {
+          "cause": "The Integrity Salt is prepended to the message AND used as the HMAC key. One of the two is usually missing.",
+          "check": "Print the exact string you hash. It must start with your salt followed by '&'.",
+          "fix": "Build `salt & value1 & value2 …` and pass the same salt as the HMAC key.",
+          "docRefs": [{ "docId": "hmac-sha256-calculation", "sectionId": "how-is-hmac-sha256-calculated" }]
+        },
+        {
+          "cause": "Empty parameters were included in the hash string.",
+          "check": "Count the values in your hash string against the non-empty fields in your payload.",
+          "fix": "Skip values that are the empty string when hashing. Keep sending those fields as \"\".",
+          "docRefs": [{ "docId": "hmac-sha256-calculation", "sectionId": "rules-that-are-easy-to-miss" }]
+        },
+        {
+          "cause": "Parameters were not sorted by name, or were sorted with a locale-aware comparator.",
+          "check": "Confirm the sort is a plain ASCII comparison of the raw parameter names.",
+          "fix": "In PHP use `ksort($params, SORT_STRING)`. In JavaScript use `.sort()` without `localeCompare`.",
+          "docRefs": [{ "docId": "hmac-sha256-calculation", "sectionId": "php-sample-divergences" }]
+        },
+        {
+          "cause": "A stale pp_SecureHash was left in the payload and fed back into its own calculation.",
+          "check": "Confirm pp_SecureHash is removed before hashing, particularly on a retry.",
+          "fix": "Delete pp_SecureHash from the parameter set, hash, then add the result back.",
+          "docRefs": [{ "docId": "hmac-sha256-calculation", "sectionId": "rules-that-are-easy-to-miss" }]
+        },
+        {
+          "cause": "ppmpf_* fields were excluded from the hash while carrying values (assumption A1).",
+          "check": "If any ppmpf_1..5 is non-empty, confirm it participates in the hash.",
+          "fix": "Include non-empty ppmpf_* fields, matching the official PHP samples. Note that the official JavaScript sample disagrees; JazzCash has not resolved this.",
+          "docRefs": [{ "docId": "mwallet-rest-v1-1", "sectionId": "common-failures" }]
+        },
+        {
+          "cause": "The payload was modified after the hash was computed.",
+          "check": "Confirm nothing regenerates a timestamp or reference between hashing and sending.",
+          "fix": "Compute the hash as the last step, from exactly the map you transmit.",
+          "docRefs": [{ "docId": "hmac-sha256-calculation", "sectionId": "common-failures" }]
+        },
+        {
+          "cause": "The salt belongs to a different environment or merchant.",
+          "check": "Re-copy the Integrity Salt from Integration > Credentials for the environment you are calling.",
+          "fix": "Confirm the salt and the Merchant ID come from the same portal account.",
+          "docRefs": [{ "docId": "portal-guide", "sectionId": "credentials" }]
+        }
+      ]
+    },
+    {
+      "id": "return-url-validation-failure",
+      "title": "Request rejected although the data looks correct",
+      "keywords": ["return url", "returnurl", "validation failed", "authentication", "rejected", "callback url"],
+      "causes": [
+        {
+          "cause": "pp_ReturnURL differs from the URL registered against the merchant profile.",
+          "check": "Compare the transmitted URL with the registered one character by character, including any trailing slash.",
+          "fix": "Send the registered URL exactly, or update it under Integration > Credentials. It is part of merchant authentication, so any difference fails validation.",
+          "docRefs": [{ "docId": "card-page-redirection", "sectionId": "important-notes" }]
+        },
+        {
+          "cause": "A parameter was added to or removed from the documented field set.",
+          "check": "Compare your payload against the flow specification.",
+          "fix": "Send exactly the documented fields: no additions, no removals, unused ones as \"\".",
+          "docRefs": [{ "docId": "mwallet-rest-v1-1", "sectionId": "request-payload-rules" }]
+        },
+        {
+          "cause": "A field was sent as JSON null rather than an empty string.",
+          "check": "Search the payload for null values.",
+          "fix": "Replace every null with \"\".",
+          "docRefs": [{ "docId": "mwallet-rest-v1-1", "sectionId": "request-payload-rules" }]
+        }
+      ]
+    },
+    {
+      "id": "wrong-amount",
+      "title": "Customer charged the wrong amount",
+      "keywords": ["amount", "wrong amount", "100 times", "minor units", "decimal", "too much", "too little"],
+      "causes": [
+        {
+          "cause": "pp_Amount was sent in major units rather than minor units.",
+          "check": "PKR 100.00 must be transmitted as \"10000\".",
+          "fix": "Multiply by 100 before sending and divide by 100 when reading a response. Use integer or decimal arithmetic, never floating point.",
+          "docRefs": [{ "docId": "mwallet-rest-v1-1", "sectionId": "currency-and-amount-handling" }]
+        },
+        {
+          "cause": "A refund amount was converted differently from the payment amount.",
+          "check": "Confirm the refund path applies the same ×100 conversion.",
+          "fix": "Share one conversion helper between payment and refund code.",
+          "docRefs": [{ "docId": "card-refund", "sectionId": "common-failures" }]
+        }
+      ]
+    },
+    {
+      "id": "duplicate-transaction-reference",
+      "title": "Transaction rejected as a duplicate",
+      "keywords": ["duplicate", "txnrefno", "already exists", "reference", "unique"],
+      "causes": [
+        {
+          "cause": "pp_TxnRefNo was reused.",
+          "check": "Confirm a fresh reference is generated for every attempt, including retries.",
+          "fix": "Use a prefix plus YYYYMMDDHHMMSS plus milliseconds, so two orders in the same second cannot collide.",
+          "docRefs": [{ "docId": "mwallet-rest-v1-1", "sectionId": "transaction-reference-requirements" }]
+        },
+        {
+          "cause": "A failed request was retried with the same reference.",
+          "check": "Confirm the retry path resolves the outcome before resending.",
+          "fix": "Call Status Inquiry to establish whether the first attempt succeeded, rather than resending blindly.",
+          "docRefs": [{ "docId": "status-inquiry", "sectionId": "introduction" }]
+        }
+      ]
+    },
+    {
+      "id": "bill-reference-rejected",
+      "title": "pp_BillReference rejected",
+      "keywords": ["billreference", "bill reference", "alphanumeric", "special character", "order number"],
+      "causes": [
+        {
+          "cause": "The value contains spaces or punctuation.",
+          "check": "pp_BillReference must contain only A-Z, a-z and 0-9.",
+          "fix": "Strip punctuation from your order number, e.g. ORD-1024/A becomes ORD1024A. The value may repeat across transactions.",
+          "docRefs": [{ "docId": "mwallet-rest-v1-1", "sectionId": "transaction-reference-requirements" }]
+        }
+      ]
+    },
+    {
+      "id": "timestamp-rejected",
+      "title": "Timestamp or expiry rejected",
+      "keywords": ["timestamp", "datetime", "expiry", "expired", "timezone", "txndatetime", "pkt"],
+      "causes": [
+        {
+          "cause": "The timestamp was generated in the host time zone rather than Pakistan Standard Time.",
+          "check": "Compare your stamp against the current time in Asia/Karachi.",
+          "fix": "Set the time zone explicitly: `date_default_timezone_set('Asia/Karachi')`, `ZoneInfo('Asia/Karachi')`, or an Intl formatter with `timeZone: 'Asia/Karachi'`.",
+          "docRefs": [{ "docId": "mwallet-rest-v1-1", "sectionId": "date-and-time-parameters" }]
+        },
+        {
+          "cause": "pp_TxnExpiryDateTime is not one day after pp_TxnDateTime.",
+          "check": "Confirm the expiry follows the transaction by one day.",
+          "fix": "Derive the expiry from the transaction time rather than computing it separately. Note that the token payment sample in the recurring guide has an expiry two months BEFORE its transaction time; do not copy it.",
+          "docRefs": [{ "docId": "mwallet-recurring", "sectionId": "mwallet-pay-via-token" }]
+        }
+      ]
+    },
+    {
+      "id": "ipn-not-received",
+      "title": "IPN notifications never arrive",
+      "keywords": ["ipn", "webhook", "notification", "callback", "not received", "never arrives"],
+      "causes": [
+        {
+          "cause": "The IPN URL is not registered.",
+          "check": "Open Integration > Credentials and confirm the IPN field is populated.",
+          "fix": "Register the public URL of your listener. For WooCommerce the path is {base}/jazzcash_ipn_v2.",
+          "docRefs": [{ "docId": "wordpress-guide", "sectionId": "return-and-ipn-urls" }]
+        },
+        {
+          "cause": "The listener is not reachable from the internet, or does not answer within 60 seconds.",
+          "check": "Post a sample notification to your own URL from outside your network.",
+          "fix": "Acknowledge first and process asynchronously. JazzCash retries twice, then stops.",
+          "docRefs": [{ "docId": "ipn-implementation", "sectionId": "retry-behaviour" }]
+        },
+        {
+          "cause": "The listener returns a non-000 response, so JazzCash treats delivery as failed.",
+          "check": "Confirm the handler returns pp_ResponseCode \"000\" on success.",
+          "fix": "Return the documented acknowledgement body, including your own pp_SecureHash.",
+          "docRefs": [{ "docId": "ipn-implementation", "sectionId": "expected-ipn-response" }]
+        }
+      ]
+    },
+    {
+      "id": "orders-fulfilled-twice",
+      "title": "Orders fulfilled or counted twice",
+      "keywords": ["duplicate order", "twice", "retry", "idempotent", "double", "fulfilled twice"],
+      "causes": [
+        {
+          "cause": "The IPN handler is not idempotent and JazzCash retried.",
+          "check": "A failed or slow acknowledgement causes two more deliveries of the same notification.",
+          "fix": "Key on pp_TxnRefNo. If the order is already paid, acknowledge and stop.",
+          "docRefs": [{ "docId": "ipn-implementation", "sectionId": "retry-behaviour" }]
+        }
+      ]
+    },
+    {
+      "id": "refund-fails",
+      "title": "Refund is rejected",
+      "keywords": ["refund", "mpin", "reversal", "refund failed", "cannot refund"],
+      "causes": [
+        {
+          "cause": "The Merchant MPIN is not saved in the merchant portal.",
+          "check": "Sending the MPIN in the request is not sufficient: it must also be stored in the portal.",
+          "fix": "Save the MPIN in the merchant portal, then retry.",
+          "docRefs": [{ "docId": "shopify-guide", "sectionId": "step-8-refunds" }]
+        },
+        {
+          "cause": "The original transaction did not complete.",
+          "check": "Run Status Inquiry against the original pp_TxnRefNo and confirm pp_PaymentResponseCode is 121.",
+          "fix": "Only completed transactions can be refunded.",
+          "docRefs": [{ "docId": "status-inquiry", "sectionId": "reading-the-codes" }]
+        },
+        {
+          "cause": "A new pp_TxnRefNo was generated instead of referencing the original transaction.",
+          "check": "The refund payload must carry the ORIGINAL transaction's reference.",
+          "fix": "Send the reference of the transaction being refunded.",
+          "docRefs": [{ "docId": "mwallet-refund", "sectionId": "sample-request" }]
+        },
+        {
+          "cause": "Cumulative refunds would exceed the original amount.",
+          "check": "Compare TotalRefundAmount from the previous refund against the original amount.",
+          "fix": "Track the cumulative total before issuing another partial refund.",
+          "docRefs": [{ "docId": "card-refund", "sectionId": "unprefixed-response-fields" }]
+        }
+      ]
+    },
+    {
+      "id": "response-fields-not-found",
+      "title": "Response fields are missing or undefined",
+      "keywords": ["undefined", "missing field", "responsecode", "securehash", "not found", "null response"],
+      "causes": [
+        {
+          "cause": "Card and BNPL refund responses use unprefixed field names.",
+          "check": "Those responses carry ResponseCode, ResponseMessage and SecureHash, with no pp_ prefix.",
+          "fix": "Read both spellings, or branch on the flow.",
+          "docRefs": [{ "docId": "card-refund", "sectionId": "unprefixed-response-fields" }]
+        },
+        {
+          "cause": "The retrieval reference is spelled differently across APIs.",
+          "check": "MWallet payment responses return pp_RetreivalReferenceNo; Status Inquiry returns pp_RetrievalReferenceNo.",
+          "fix": "Match the gateway's spelling for the API you called.",
+          "docRefs": [{ "docId": "status-inquiry", "sectionId": "reading-the-codes" }]
+        }
+      ]
+    },
+    {
+      "id": "payment-method-missing",
+      "title": "The payment method does not appear",
+      "keywords": ["not showing", "missing method", "not enabled", "no option", "payment method"],
+      "causes": [
+        {
+          "cause": "JazzCash has not enabled the payment option against your Merchant ID.",
+          "check": "Every guide asks you to share your Merchant ID so the team can enable the option.",
+          "fix": "Send your Merchant ID to JazzCash and ask for the specific method to be enabled.",
+          "docRefs": [{ "docId": "card-page-redirection", "sectionId": "create-a-sandbox-account" }]
+        },
+        {
+          "cause": "In Shopify, the old JazzCash payment method is still active.",
+          "check": "Settings > Payments may show two JazzCash methods.",
+          "fix": "Deactivate the old method, but do not uninstall the old app until outstanding transactions are settled.",
+          "docRefs": [{ "docId": "shopify-guide", "sectionId": "step-1-deactivate" }]
+        }
+      ]
+    },
+    {
+      "id": "unknown-response-code",
+      "title": "An unrecognised response code",
+      "keywords": ["unknown code", "response code", "what does", "undocumented", "157", "124"],
+      "causes": [
+        {
+          "cause": "The 2026 corpus documents only 000, 121, 199 and 999.",
+          "check": "Read the accompanying message field, which carries the gateway's own description.",
+          "fix": "Treat the transaction as UNRESOLVED, not failed. Run Status Inquiry, and escalate to JazzCash with the pp_TxnRefNo and retrieval reference if it stays unclear. Do not refund or re-charge on an unrecognised code.",
+          "docRefs": [{ "docId": "status-inquiry", "sectionId": "reading-the-codes" }]
+        }
+      ]
+    },
+    {
+      "id": "paid-but-not-marked-paid",
+      "title": "Money was taken but the order is not marked paid",
+      "keywords": ["not marked paid", "money taken", "debited", "pending order", "stuck pending"],
+      "causes": [
+        {
+          "cause": "pp_ResponseCode 000 was read as proof of payment on a Status Inquiry.",
+          "check": "On Status Inquiry, 000 means only that the enquiry itself worked.",
+          "fix": "Read pp_PaymentResponseCode: 121 means the money moved.",
+          "docRefs": [{ "docId": "status-inquiry", "sectionId": "introduction" }]
+        },
+        {
+          "cause": "The IPN did not arrive and no reconciliation runs.",
+          "check": "Look for transactions with no terminal state older than ten minutes.",
+          "fix": "Run Status Inquiry on a schedule for any transaction without a terminal outcome. Status Inquiry is a mandatory integration precisely for this.",
+          "docRefs": [{ "docId": "status-inquiry", "sectionId": "introduction" }]
+        }
+      ]
+    },
+    {
+      "id": "credentials-exposed",
+      "title": "Integrity Salt or credentials exposed",
+      "keywords": ["salt", "exposed", "browser", "client side", "leak", "public", "javascript"],
+      "causes": [
+        {
+          "cause": "The hash is computed in browser JavaScript, as the official wallet-linking sample does.",
+          "check": "View source on your linking or checkout page and search for the salt.",
+          "fix": "Compute pp_SecureHash on your server and render only the finished hash. The salt is the HMAC key: anyone who has it can forge a valid request for your merchant account. Rotate the salt with JazzCash if it has been published.",
+          "docRefs": [{ "docId": "mwallet-recurring", "sectionId": "sample-defects" }]
+        },
+        {
+          "cause": "Credentials are committed to version control.",
+          "check": "Search your repository history for the Merchant ID, password and salt.",
+          "fix": "Move them to environment variables, gitignore the file, and ask JazzCash to rotate anything that was committed.",
+          "docRefs": [{ "docId": "portal-guide", "sectionId": "credentials" }]
+        }
+      ]
+    },
+    {
+      "id": "wrong-environment",
+      "title": "Unsure which environment a request reached",
+      "keywords": ["environment", "sandbox", "production", "live", "which endpoint", "same url"],
+      "causes": [
+        {
+          "cause": "Sandbox and production use identical URLs in every documented flow.",
+          "check": "The endpoint tells you nothing. Only the credentials decide which environment you reached.",
+          "fix": "Track the environment alongside the credentials, log which profile was loaded, and treat going live as a credential swap rather than a URL change.",
+          "docRefs": [{ "docId": "card-page-redirection", "sectionId": "endpoint" }]
+        }
+      ]
+    }
+  ]
+}