@atbas/m-mcp 0.1.0

package/dist/domain/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared domain vocabulary.
+ *
+ * JazzCash transmits every parameter as a string. Numbers are accepted at the
+ * boundary for ergonomics and normalised immediately, because the gateway's
+ * documented rule — "all parameter values must be passed as strings and enclosed
+ * in double quotes" — admits no exceptions.
+ */
+/** A raw parameter value as a caller may supply it. */
+export type ParameterValue = string | number | null | undefined;
+/** A payload as supplied by a caller, before normalisation. */
+export type RawParameters = Readonly<Record<string, ParameterValue>>;
+/** A payload after normalisation: every value is a string, empties are `''`. */
+export type NormalisedParameters = Readonly<Record<string, string>>;
+/**
+ * Normalise a single value to its wire representation.
+ *
+ * `null` and `undefined` collapse to `''`, which is what the guides require for
+ * unused parameters ("do not replace them with null and do not remove them").
+ */
+export declare function normaliseValue(value: ParameterValue): string;
+/** Normalise every value in a payload, preserving key order. */
+export declare function normaliseParameters(parameters: RawParameters): NormalisedParameters;
+/**
+ * Coerce an arbitrary decoded JSON object into hashable parameters.
+ *
+ * Every documented JazzCash response is a flat map of strings and nulls. A
+ * nested object or array is therefore not something the hash rules cover, and it
+ * is dropped rather than stringified: `[object Object]` in a hash string would be
+ * a silent corruption. Response hash verification already reports `unverified`
+ * rather than `failed` (assumption A2), so a dropped field cannot be mistaken for
+ * a broken integration.
+ */
+export declare function toParameters(record: Readonly<Record<string, unknown>>): NormalisedParameters;
+/**
+ * Compare two parameter names by ASCII code unit, ascending.
+ *
+ * `String.prototype.localeCompare` is deliberately avoided: it is locale
+ * sensitive and would order `pp_MerchantID` and `pp_merchantid` differently on
+ * different machines, producing a hash that works on one host and fails on
+ * another. JavaScript's default string comparison is code-unit order, which is
+ * ASCII order for every parameter name JazzCash defines.
+ */
+export declare function compareParameterNames(left: string, right: string): number;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/domain/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAEhE,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAErE,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAK5D;AAED,gEAAgE;AAChE,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,aAAa,GAAG,oBAAoB,CAMnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,oBAAoB,CAa5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQzE"}

package/dist/domain/types.js

@@ -0,0 +1,70 @@
+/**
+ * Shared domain vocabulary.
+ *
+ * JazzCash transmits every parameter as a string. Numbers are accepted at the
+ * boundary for ergonomics and normalised immediately, because the gateway's
+ * documented rule — "all parameter values must be passed as strings and enclosed
+ * in double quotes" — admits no exceptions.
+ */
+/**
+ * Normalise a single value to its wire representation.
+ *
+ * `null` and `undefined` collapse to `''`, which is what the guides require for
+ * unused parameters ("do not replace them with null and do not remove them").
+ */
+export function normaliseValue(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    return typeof value === 'string' ? value : String(value);
+}
+/** Normalise every value in a payload, preserving key order. */
+export function normaliseParameters(parameters) {
+    const result = {};
+    for (const key of Object.keys(parameters)) {
+        result[key] = normaliseValue(parameters[key]);
+    }
+    return result;
+}
+/**
+ * Coerce an arbitrary decoded JSON object into hashable parameters.
+ *
+ * Every documented JazzCash response is a flat map of strings and nulls. A
+ * nested object or array is therefore not something the hash rules cover, and it
+ * is dropped rather than stringified: `[object Object]` in a hash string would be
+ * a silent corruption. Response hash verification already reports `unverified`
+ * rather than `failed` (assumption A2), so a dropped field cannot be mistaken for
+ * a broken integration.
+ */
+export function toParameters(record) {
+    const result = {};
+    for (const key of Object.keys(record)) {
+        const value = record[key];
+        if (value === null || value === undefined) {
+            result[key] = '';
+        }
+        else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            result[key] = String(value);
+        }
+    }
+    return result;
+}
+/**
+ * Compare two parameter names by ASCII code unit, ascending.
+ *
+ * `String.prototype.localeCompare` is deliberately avoided: it is locale
+ * sensitive and would order `pp_MerchantID` and `pp_merchantid` differently on
+ * different machines, producing a hash that works on one host and fails on
+ * another. JavaScript's default string comparison is code-unit order, which is
+ * ASCII order for every parameter name JazzCash defines.
+ */
+export function compareParameterNames(left, right) {
+    if (left < right) {
+        return -1;
+    }
+    if (left > right) {
+        return 1;
+    }
+    return 0;
+}
+//# sourceMappingURL=types.js.map

package/dist/domain/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/domain/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,mBAAmB,CAAC,UAAyB;IAC3D,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,MAAyC;IACpE,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC1C,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACnB,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YAChG,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,KAAa;IAC/D,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;IACD,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Error taxonomy for the JazzCash MCP server.
+ *
+ * Every error carries a stable machine-readable `code` and, where the failure is
+ * traceable to official JazzCash documentation, the references that explain it.
+ * Tool handlers convert these into `isError` results rather than letting them
+ * escape across the protocol boundary.
+ */
+/**
+ * Pointer into the curated knowledge corpus.
+ *
+ * The optional members are declared as `?: T | undefined` so the type stays
+ * assignable from zod-inferred flow specifications under
+ * `exactOptionalPropertyTypes`.
+ */
+export interface DocRef {
+    /** Document identifier, e.g. `hmac-sha256-calculation`. */
+    readonly docId: string;
+    /** Optional section anchor within that document. */
+    readonly sectionId?: string | undefined;
+    /** Human-readable label for display alongside the citation. */
+    readonly label?: string | undefined;
+}
+export interface JazzCashErrorOptions {
+    readonly docRefs?: readonly DocRef[];
+    readonly cause?: unknown;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/** Base class for every error this server raises deliberately. */
+export declare abstract class JazzCashError extends Error {
+    /** Stable identifier, safe to branch on and to show to a merchant. */
+    abstract readonly code: string;
+    readonly docRefs: readonly DocRef[];
+    readonly details: Readonly<Record<string, unknown>>;
+    protected constructor(message: string, options?: JazzCashErrorOptions);
+}
+/** Server configuration or credential resolution failed. */
+export declare class JazzCashConfigError extends JazzCashError {
+    readonly code = "JAZZCASH_CONFIG_ERROR";
+    constructor(message: string, options?: JazzCashErrorOptions);
+}
+/** A payload failed the documented parameter rules for its flow. */
+export declare class JazzCashValidationError extends JazzCashError {
+    readonly code = "JAZZCASH_VALIDATION_ERROR";
+    constructor(message: string, options?: JazzCashErrorOptions);
+}
+/**
+ * Request signature construction or verification failed.
+ *
+ * Named for the operation rather than for a gateway: one engine signs and
+ * diagnoses every registered scheme, so naming this error after a single gateway
+ * renders every signature failure under that gateway's name — including one
+ * raised for a scheme it has nothing to do with. A merchant told to check a
+ * credential their gateway does not issue checks nothing.
+ */
+export declare class SignatureError extends JazzCashError {
+    readonly code = "SIGNATURE_ERROR";
+    constructor(message: string, options?: JazzCashErrorOptions);
+}
+/** The gateway was unreachable, timed out, or returned something unparseable. */
+export declare class JazzCashGatewayError extends JazzCashError {
+    readonly code = "JAZZCASH_GATEWAY_ERROR";
+    constructor(message: string, options?: JazzCashErrorOptions);
+}
+/**
+ * A safety guard refused the request.
+ *
+ * Raised when a caller attempts production money movement without the required
+ * dual opt-in, or when the declared environment disagrees with the credential
+ * profile in use. Sandbox and production share identical gateway URLs, so this
+ * guard cannot be inferred away.
+ */
+export declare class JazzCashSafetyError extends JazzCashError {
+    readonly code = "JAZZCASH_SAFETY_ERROR";
+    constructor(message: string, options?: JazzCashErrorOptions);
+}
+/** A requested flow, document or knowledge entry does not exist. */
+export declare class JazzCashNotFoundError extends JazzCashError {
+    readonly code = "JAZZCASH_NOT_FOUND";
+    constructor(message: string, options?: JazzCashErrorOptions);
+}
+/** Narrow an unknown thrown value to a readable message without leaking internals. */
+export declare function describeError(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD;AAED,kEAAkE;AAClE,8BAAsB,aAAc,SAAQ,KAAK;IAC/C,sEAAsE;IACtE,kBAAyB,IAAI,EAAE,MAAM,CAAC;IAEtC,SAAgB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAE3C,SAAgB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAE3D,SAAS,aAAa,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB;CAM1E;AAED,4DAA4D;AAC5D,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,SAAyB,IAAI,2BAA2B;gBAErC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB;CAGnE;AAED,oEAAoE;AACpE,qBAAa,uBAAwB,SAAQ,aAAa;IACxD,SAAyB,IAAI,+BAA+B;gBAEzC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB;CAGnE;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,aAAa;IAC/C,SAAyB,IAAI,qBAAqB;gBAE/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB;CAGnE;AAED,iFAAiF;AACjF,qBAAa,oBAAqB,SAAQ,aAAa;IACrD,SAAyB,IAAI,4BAA4B;gBAEtC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB;CAGnE;AAED;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,SAAyB,IAAI,2BAA2B;gBAErC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB;CAGnE;AAED,oEAAoE;AACpE,qBAAa,qBAAsB,SAAQ,aAAa;IACtD,SAAyB,IAAI,wBAAwB;gBAElC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB;CAGnE;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQpD"}

package/dist/errors.js

@@ -0,0 +1,87 @@
+/**
+ * Error taxonomy for the JazzCash MCP server.
+ *
+ * Every error carries a stable machine-readable `code` and, where the failure is
+ * traceable to official JazzCash documentation, the references that explain it.
+ * Tool handlers convert these into `isError` results rather than letting them
+ * escape across the protocol boundary.
+ */
+/** Base class for every error this server raises deliberately. */
+export class JazzCashError extends Error {
+    docRefs;
+    details;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = new.target.name;
+        this.docRefs = options.docRefs ?? [];
+        this.details = options.details ?? {};
+    }
+}
+/** Server configuration or credential resolution failed. */
+export class JazzCashConfigError extends JazzCashError {
+    code = 'JAZZCASH_CONFIG_ERROR';
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** A payload failed the documented parameter rules for its flow. */
+export class JazzCashValidationError extends JazzCashError {
+    code = 'JAZZCASH_VALIDATION_ERROR';
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/**
+ * Request signature construction or verification failed.
+ *
+ * Named for the operation rather than for a gateway: one engine signs and
+ * diagnoses every registered scheme, so naming this error after a single gateway
+ * renders every signature failure under that gateway's name — including one
+ * raised for a scheme it has nothing to do with. A merchant told to check a
+ * credential their gateway does not issue checks nothing.
+ */
+export class SignatureError extends JazzCashError {
+    code = 'SIGNATURE_ERROR';
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** The gateway was unreachable, timed out, or returned something unparseable. */
+export class JazzCashGatewayError extends JazzCashError {
+    code = 'JAZZCASH_GATEWAY_ERROR';
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/**
+ * A safety guard refused the request.
+ *
+ * Raised when a caller attempts production money movement without the required
+ * dual opt-in, or when the declared environment disagrees with the credential
+ * profile in use. Sandbox and production share identical gateway URLs, so this
+ * guard cannot be inferred away.
+ */
+export class JazzCashSafetyError extends JazzCashError {
+    code = 'JAZZCASH_SAFETY_ERROR';
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** A requested flow, document or knowledge entry does not exist. */
+export class JazzCashNotFoundError extends JazzCashError {
+    code = 'JAZZCASH_NOT_FOUND';
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** Narrow an unknown thrown value to a readable message without leaking internals. */
+export function describeError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'An unknown error occurred.';
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwBH,kEAAkE;AAClE,MAAM,OAAgB,aAAc,SAAQ,KAAK;IAI/B,OAAO,CAAoB;IAE3B,OAAO,CAAoC;IAE3D,YAAsB,OAAe,EAAE,UAAgC,EAAE;QACvE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACnF,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACvC,CAAC;CACF;AAED,4DAA4D;AAC5D,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IAC3B,IAAI,GAAG,uBAAuB,CAAC;IAExD,YAAmB,OAAe,EAAE,OAA8B;QAChE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,OAAO,uBAAwB,SAAQ,aAAa;IAC/B,IAAI,GAAG,2BAA2B,CAAC;IAE5D,YAAmB,OAAe,EAAE,OAA8B;QAChE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAe,SAAQ,aAAa;IACtB,IAAI,GAAG,iBAAiB,CAAC;IAElD,YAAmB,OAAe,EAAE,OAA8B;QAChE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,OAAO,oBAAqB,SAAQ,aAAa;IAC5B,IAAI,GAAG,wBAAwB,CAAC;IAEzD,YAAmB,OAAe,EAAE,OAA8B;QAChE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IAC3B,IAAI,GAAG,uBAAuB,CAAC;IAExD,YAAmB,OAAe,EAAE,OAA8B;QAChE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IAC7B,IAAI,GAAG,oBAAoB,CAAC;IAErD,YAAmB,OAAe,EAAE,OAA8B;QAChE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF;AAED,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,4BAA4B,CAAC;AACtC,CAAC"}

package/dist/gateway/checkout-form.d.ts

@@ -0,0 +1,16 @@
+import type { IntegrationFlow } from '../catalogue/types.js';
+import type { JazzCashEnvironment } from '../config/environment.js';
+import type { NormalisedParameters } from '../domain/types.js';
+export interface CheckoutFormOptions {
+    readonly flow: IntegrationFlow;
+    readonly environment: JazzCashEnvironment;
+    readonly parameters: NormalisedParameters;
+}
+/**
+ * Render a self-contained page that posts the signed parameters to JazzCash.
+ *
+ * The form is NOT auto-submitting: the page is a deliberate manual test step, and
+ * an auto-submit would make it easy to fire a real transaction by opening a file.
+ */
+export declare function renderCheckoutForm(options: CheckoutFormOptions): string;
+//# sourceMappingURL=checkout-form.d.ts.map

package/dist/gateway/checkout-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-form.d.ts","sourceRoot":"","sources":["../../src/gateway/checkout-form.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAuB/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAqFvE"}

package/dist/gateway/checkout-form.js

@@ -0,0 +1,103 @@
+import { endpointIsAmbiguous, resolveEndpoint } from '../catalogue/endpoints.js';
+/**
+ * Signed HTML form for the browser flows.
+ *
+ * Card checkout, BNPL checkout and wallet linking cannot be driven headlessly:
+ * the customer completes them in a browser, entering card details or an MPIN.
+ * The server therefore produces a ready-to-submit local page and hands the human
+ * explicit instructions, rather than pretending to automate the payment page.
+ */
+const HTML_ESCAPES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => HTML_ESCAPES[character] ?? character);
+}
+/**
+ * Render a self-contained page that posts the signed parameters to JazzCash.
+ *
+ * The form is NOT auto-submitting: the page is a deliberate manual test step, and
+ * an auto-submit would make it easy to fire a real transaction by opening a file.
+ */
+export function renderCheckoutForm(options) {
+    const { flow, environment, parameters } = options;
+    const endpoint = resolveEndpoint(flow, environment);
+    const isLive = environment === 'production';
+    const rows = Object.entries(parameters)
+        .map(([name, value]) => `      <tr><th>${escapeHtml(name)}</th><td>${value === '' ? '<em>(empty)</em>' : escapeHtml(value)}</td></tr>`)
+        .join('\n');
+    const inputs = Object.entries(parameters)
+        .map(([name, value]) => `      <input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
+        .join('\n');
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>JazzCash test — ${escapeHtml(flow.title)}</title>
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 60rem; margin: 2rem auto; padding: 0 1rem; }
+    table { border-collapse: collapse; width: 100%; font-family: ui-monospace, monospace; font-size: 0.85rem; }
+    th, td { border: 1px solid #ddd; padding: 0.4rem 0.6rem; text-align: left; vertical-align: top; }
+    th { width: 16rem; background: #fafafa; }
+    .banner { padding: 1rem; border-radius: 6px; margin-bottom: 1.5rem; }
+    .live { background: #fdecea; border: 2px solid #d32f2f; }
+    .sandbox { background: #e8f5e9; border: 1px solid #2e7d32; }
+    button { font-size: 1rem; padding: 0.6rem 1.4rem; margin-top: 1rem; }
+  </style>
+</head>
+<body>
+  <h1>${escapeHtml(flow.title)}</h1>
+
+  <div class="banner ${isLive ? 'live' : 'sandbox'}">
+    <strong>Environment: ${escapeHtml(environment.toUpperCase())}</strong>
+    <p>
+      ${isLive
+        ? 'These are PRODUCTION credentials. Submitting this form starts a real transaction against a real account.'
+        : 'These are sandbox credentials. Submitting this form starts a sandbox transaction.'}
+    </p>
+    <p>
+      ${
+    // Computed from the URLs actually rendered below rather than from the
+    // declared flag, so the page cannot assert something the form contradicts.
+    endpointIsAmbiguous(flow)
+        ? 'The endpoint below is identical for sandbox and production. The environment above reflects the credentials embedded in this form, not the URL.'
+        : `The endpoint below belongs to the ${escapeHtml(environment)} environment, as do the credentials embedded in this form. Submitting it reaches ${escapeHtml(environment)}.`}
+    </p>
+  </div>
+
+  <p>Posting to: <code>${escapeHtml(endpoint)}</code></p>
+
+  <h2>Parameters</h2>
+  <table>
+${rows}
+  </table>
+
+  <form method="post" action="${escapeHtml(endpoint)}">
+${inputs}
+    <button type="submit">Submit to JazzCash</button>
+  </form>
+
+  <h2>After you submit</h2>
+  <ol>
+    <li>Complete the payment on the JazzCash page.</li>
+    <li>Confirm the result is posted back to your registered Return URL.</li>
+    <li>Wait at least ten minutes, then call the Status Inquiry API with
+        <code>${escapeHtml(parameters['pp_TxnRefNo'] ?? parameters['pp_RequestID'] ?? '')}</code>
+        to confirm the outcome independently.</li>
+    <li>Capture the screenshots JazzCash requires: checkout page, landing page,
+        method selection, payment, callback response, and order status.</li>
+  </ol>
+
+  <p><small>
+    Generated by the JazzCash MCP server. This file contains a valid signed payload
+    for your merchant account — delete it after testing and never commit it.
+  </small></p>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=checkout-form.js.map

package/dist/gateway/checkout-form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-form.js","sourceRoot":"","sources":["../../src/gateway/checkout-form.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAKjF;;;;;;;GAOG;AAEH,MAAM,YAAY,GAAqC;IACrD,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,OAAO;CACb,CAAC;AAEF,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,CAAC;AACxF,CAAC;AAQD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC7D,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAClD,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,WAAW,KAAK,YAAY,CAAC;IAE5C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;SACpC,GAAG,CACF,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAChB,iBAAiB,UAAU,CAAC,IAAI,CAAC,YAAY,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,YAAY,CACjH;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,oCAAoC,UAAU,CAAC,IAAI,CAAC,YAAY,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;SAC7G,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO;;;;2BAIkB,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;;;;;;;;;;;;;QAazC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;;uBAEP,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;2BACvB,UAAU,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;;QAGxD,MAAM;QACJ,CAAC,CAAC,0GAA0G;QAC5G,CAAC,CAAC,mFACN;;;QAGE;IACA,sEAAsE;IACtE,2EAA2E;IAC3E,mBAAmB,CAAC,IAAI,CAAC;QACvB,CAAC,CAAC,gJAAgJ;QAClJ,CAAC,CAAC,qCAAqC,UAAU,CAAC,WAAW,CAAC,oFAAoF,UAAU,CAAC,WAAW,CAAC,GAC7K;;;;yBAImB,UAAU,CAAC,QAAQ,CAAC;;;;EAI3C,IAAI;;;gCAG0B,UAAU,CAAC,QAAQ,CAAC;EAClD,MAAM;;;;;;;;;gBASQ,UAAU,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,UAAU,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;;;;;;;;;;;;CAYxF,CAAC;AACF,CAAC"}

package/dist/gateway/checkout-output.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Directory generated forms land in when the operator has named none.
+ *
+ * Deliberately NOT derived from the package root. This server is installed with
+ * `npx`, which unpacks it into a cache directory npm garbage-collects without
+ * warning: a default under the package would scatter pages embedding the
+ * merchant's password and a valid pp_SecureHash across `~/.npm/_npx/<hash>/`,
+ * where the operator neither expects them nor knows to delete them, and where a
+ * reinstall silently moves the directory out from under them.
+ *
+ * A per-user state directory is the right home instead. It is stable across
+ * reinstalls, it belongs to the operator rather than to a package manager, and
+ * `XDG_STATE_HOME` is the variable a user has already set if they keep such
+ * state somewhere other than `~/.local/state`.
+ *
+ * An empty, whitespace-only or relative `XDG_STATE_HOME` falls back rather than
+ * being used. A blank variable is an unset one, which is the same treatment
+ * {@link CHECKOUT_OUTPUT_DIRECTORY_VARIABLE} gets below. A relative one is
+ * ignored because the XDG specification says it must be, and because joining it
+ * would produce a relative path that {@link canonicalPath} anchors to
+ * `process.cwd()` — for a stdio server that is whatever the AI client chose,
+ * routinely the merchant's own project directory, which is exactly where a page
+ * carrying live credentials must never be written.
+ *
+ * Exported so the default can be asserted directly. Every suite that exercises
+ * the tool pins {@link CHECKOUT_OUTPUT_DIRECTORY_VARIABLE} to a temporary
+ * directory, so without this the default is the one path in this module no test
+ * would ever execute.
+ */
+export declare function defaultCheckoutRoot(): string;
+export interface CheckoutTarget {
+    /** Directory every generated form is confined to. */
+    readonly root: string;
+    /** Absolute file the form will be written to. */
+    readonly path: string;
+}
+/**
+ * Decide where a checkout form may be written, refusing anything outside the
+ * server's own output directory.
+ *
+ * An escaping path is refused rather than silently rewritten: quietly relocating
+ * live credentials would hide where they actually landed.
+ */
+export declare function resolveCheckoutTarget(outputPath: string | undefined, defaultFileName: string): CheckoutTarget;
+/**
+ * Write the page, re-checking containment once the directory exists.
+ *
+ * `resolveCheckoutTarget` could only resolve the symlinks present when it ran,
+ * and the write is what actually discloses the credentials, so the check is made
+ * again against the directory that now exists on disk.
+ *
+ * The directory is created 0700 because every file in it embeds the merchant's
+ * password and a valid pp_SecureHash. On a shared host the process umask alone
+ * would commonly leave it world-readable, and the mode is only applied to
+ * directories this call actually creates — an operator who pointed
+ * `JAZZCASH_CHECKOUT_OUTPUT_DIR` at an existing directory keeps their own
+ * permissions.
+ *
+ * The file is opened rather than handed to `writeFileSync` for two reasons that
+ * `writeFileSync` cannot serve at once. `O_NOFOLLOW` makes the open fail rather
+ * than follow a symbolic link at the target name, which is the one component no
+ * containment check could resolve, and it does so atomically — there is no
+ * window between the check and the write for a link to appear in. And `O_CREAT`
+ * carries the mode, so the page is 0600 from the moment it exists rather than
+ * whatever the umask allows. `chmodSync` follows because a mode passed to
+ * `open` is ignored for a file that already exists, and overwriting yesterday's
+ * world-readable page must tighten it rather than inherit it.
+ */
+export declare function writeCheckoutForm(target: CheckoutTarget, html: string): void;
+//# sourceMappingURL=checkout-output.d.ts.map

package/dist/gateway/checkout-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-output.d.ts","sourceRoot":"","sources":["../../src/gateway/checkout-output.ts"],"names":[],"mappings":"AAwDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AA0ED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,eAAe,EAAE,MAAM,GAAG,cAAc,CAqB7G;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAsB5E"}