@atbas/m-mcp 0.1.0

package/dist/codegen/renderer.d.ts

@@ -0,0 +1,24 @@
+import { type CorpusSource } from '../knowledge/source.js';
+import type { Language, TemplateKind, TemplateValues } from './types.js';
+/**
+ * Substitute `{{NAME}}` placeholders.
+ *
+ * A placeholder the caller did not supply is an error rather than an empty
+ * string: a silently blank credential or endpoint in generated payment code is
+ * far worse than a failed generation.
+ */
+export declare function render(template: string, values: TemplateValues): string;
+/** Placeholder names a template requires. Used to verify templates in tests. */
+export declare function requiredPlaceholders(template: string): readonly string[];
+/**
+ * Read `{language}/{kind}.tmpl` from the template source, `knowledge/templates/`
+ * by default.
+ *
+ * Deliberately uncached, and the source is consulted on every call. The
+ * alternative — a module-level `Map` — is global mutable state with no
+ * invalidation, which means an edited template is served stale until the process
+ * restarts. Twelve templates of a few kilobytes each, read once per generation,
+ * is not a cost worth that.
+ */
+export declare function loadTemplate(language: Language, kind: TemplateKind, templates?: CorpusSource | string): string;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/codegen/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/codegen/renderer.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3E,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAazE;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAmBvE;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,YAAY,EAClB,SAAS,GAAE,YAAY,GAAG,MAAmC,GAC5D,MAAM,CAYR"}

package/dist/codegen/renderer.js

@@ -0,0 +1,59 @@
+import { JazzCashConfigError } from '../errors.js';
+import { toCorpusSource } from '../knowledge/source.js';
+import { knowledgePath } from '../paths.js';
+/**
+ * Minimal, escaping-aware template renderer.
+ *
+ * Deliberately not an expression evaluator. A template can substitute named
+ * values and nothing else, so a template cannot execute logic and a malformed
+ * template cannot silently emit something surprising into code that will handle
+ * money.
+ */
+const PLACEHOLDER = /\{\{([A-Z0-9_]+)\}\}/g;
+/**
+ * Substitute `{{NAME}}` placeholders.
+ *
+ * A placeholder the caller did not supply is an error rather than an empty
+ * string: a silently blank credential or endpoint in generated payment code is
+ * far worse than a failed generation.
+ */
+export function render(template, values) {
+    const missing = new Set();
+    const output = template.replace(PLACEHOLDER, (_match, name) => {
+        const value = values[name];
+        if (value === undefined) {
+            missing.add(name);
+            return '';
+        }
+        return value;
+    });
+    if (missing.size > 0) {
+        throw new JazzCashConfigError(`Template is missing value(s) for: ${[...missing].sort().join(', ')}. This is a bug in the generator, not in your configuration.`);
+    }
+    return output;
+}
+/** Placeholder names a template requires. Used to verify templates in tests. */
+export function requiredPlaceholders(template) {
+    return [...new Set([...template.matchAll(PLACEHOLDER)].map((match) => match[1] ?? ''))].sort();
+}
+/**
+ * Read `{language}/{kind}.tmpl` from the template source, `knowledge/templates/`
+ * by default.
+ *
+ * Deliberately uncached, and the source is consulted on every call. The
+ * alternative — a module-level `Map` — is global mutable state with no
+ * invalidation, which means an edited template is served stale until the process
+ * restarts. Twelve templates of a few kilobytes each, read once per generation,
+ * is not a cost worth that.
+ */
+export function loadTemplate(language, kind, templates = knowledgePath('templates')) {
+    const files = toCorpusSource(templates);
+    const entry = `${kind}.tmpl`;
+    try {
+        return files.readText(language, entry);
+    }
+    catch (cause) {
+        throw new JazzCashConfigError(`No ${language} template for "${kind}". Expected it at ${files.locate(language, entry)}.`, { cause });
+    }
+}
+//# sourceMappingURL=renderer.js.map

package/dist/codegen/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../src/codegen/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,cAAc,EAAqB,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;;;GAOG;AAEH,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,QAAgB,EAAE,MAAsB;IAC7D,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,EAAE;QACpE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,mBAAmB,CAC3B,qCAAqC,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,8DAA8D,CAClI,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACjG,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAkB,EAClB,IAAkB,EAClB,YAAmC,aAAa,CAAC,WAAW,CAAC;IAE7D,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,KAAK,GAAG,GAAG,IAAI,OAAO,CAAC;IAE7B,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,mBAAmB,CAC3B,MAAM,QAAQ,kBAAkB,IAAI,qBAAqB,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,EACzF,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/codegen/types.d.ts

@@ -0,0 +1,50 @@
+import type { IntegrationFlow } from '../catalogue/types.js';
+import type { JazzCashEnvironment } from '../config/environment.js';
+/** Languages the generator emits. */
+export declare const LANGUAGES: readonly ["php", "node", "python"];
+export type Language = (typeof LANGUAGES)[number];
+/** What kind of artefact to generate. */
+export declare const TEMPLATE_KINDS: readonly ["checkout-redirect", "rest-client", "ipn-handler", "wallet-linking"];
+export type TemplateKind = (typeof TEMPLATE_KINDS)[number];
+export interface GeneratedFile {
+    /** Suggested path relative to the merchant's project root. */
+    readonly path: string;
+    readonly language: Language;
+    readonly contents: string;
+}
+export interface CodegenResult {
+    readonly flowId: string;
+    readonly language: Language;
+    readonly kind: TemplateKind;
+    readonly files: readonly GeneratedFile[];
+    /** What the merchant must still do: register URLs, set variables, run tests. */
+    readonly followUp: readonly string[];
+    /**
+     * `.env` fragment for the MERCHANT'S OWN application.
+     *
+     * The generated code reads these at runtime. This is unrelated to how the MCP
+     * server itself is configured — the server never reads a `.env`.
+     */
+    readonly envExample: string;
+}
+/** Values a language adapter substitutes into a template. */
+export type TemplateValues = Readonly<Record<string, string>>;
+export interface LanguageAdapter {
+    readonly id: Language;
+    readonly label: string;
+    /** Render a parameter map as a literal in this language. */
+    literal(parameters: ReadonlyMap<string, string>, indent: string): string;
+    /** Escape a value for a single-quoted string in this language. */
+    escape(value: string): string;
+    /** Suggested file name for one artefact kind. */
+    fileName(kind: TemplateKind, flow: IntegrationFlow): string;
+}
+export interface CodegenRequest {
+    readonly flow: IntegrationFlow;
+    readonly language: Language;
+    readonly kind: TemplateKind;
+    readonly environment: JazzCashEnvironment;
+    /** Optional web framework hint, used for the IPN handler. */
+    readonly framework?: string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/codegen/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,qCAAqC;AACrC,eAAO,MAAM,SAAS,oCAAqC,CAAC;AAE5D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAElD,yCAAyC;AACzC,eAAO,MAAM,cAAc,gFAAiF,CAAC;AAE7G,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACzE,kEAAkE;IAClE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC;CAC7D;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC"}

package/dist/codegen/types.js

@@ -0,0 +1,5 @@
+/** Languages the generator emits. */
+export const LANGUAGES = ['php', 'node', 'python'];
+/** What kind of artefact to generate. */
+export const TEMPLATE_KINDS = ['checkout-redirect', 'rest-client', 'ipn-handler', 'wallet-linking'];
+//# sourceMappingURL=types.js.map

package/dist/codegen/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/codegen/types.ts"],"names":[],"mappings":"AAGA,qCAAqC;AACrC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAI5D,yCAAyC;AACzC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,CAAU,CAAC"}

package/dist/config/credentials.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { type EnvironmentConfig, type JazzCashEnvironment } from './environment.js';
+declare const profileSchema: z.ZodObject<{
+    merchantId: z.ZodString;
+    password: z.ZodString;
+    integritySalt: z.ZodString;
+    merchantMpin: z.ZodOptional<z.ZodString>;
+    returnUrl: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodURL>>;
+    ipnUrl: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodURL>>;
+}, z.core.$strip>;
+export type CredentialProfileData = z.infer<typeof profileSchema>;
+/**
+ * A resolved merchant credential set.
+ *
+ * `toJSON` and `toString` are overridden so that an accidental interpolation or
+ * `JSON.stringify` in a log line, an error message, or a tool result cannot leak
+ * the password, salt or MPIN.
+ */
+/**
+ * Map a payload parameter to the profile field that supplies it.
+ *
+ * Returns `undefined` for every other name, and for a credential the profile
+ * does not carry. Both the builder, which fills a payload from scratch, and the
+ * send path, which refills one whose credentials were masked for the transcript,
+ * resolve credentials through here so the two cannot drift apart — a payload
+ * signed with one profile's salt while carrying another's merchant ID is exactly
+ * the failure this single source of truth prevents.
+ */
+export declare function credentialParameterValue(name: string, profile: CredentialProfile): string | undefined;
+export declare class CredentialProfile {
+    readonly environment: JazzCashEnvironment;
+    readonly merchantId: string;
+    readonly password: string;
+    readonly integritySalt: string;
+    readonly merchantMpin: string | undefined;
+    readonly returnUrl: string | undefined;
+    readonly ipnUrl: string | undefined;
+    constructor(environment: JazzCashEnvironment, data: CredentialProfileData);
+    /** Every literal that must be scrubbed from free text before it is returned. */
+    secrets(): readonly string[];
+    /** True when this profile can be used for refunds, which require the MPIN. */
+    supportsRefunds(): boolean;
+    /** Non-sensitive description, safe to show a merchant to confirm which profile is active. */
+    describe(): Record<string, string>;
+    toJSON(): Record<string, string>;
+    toString(): string;
+}
+export interface CredentialStore {
+    /** Resolve a profile, or throw a {@link JazzCashConfigError} naming what is missing. */
+    get(environment: JazzCashEnvironment): CredentialProfile;
+    has(environment: JazzCashEnvironment): boolean;
+    /** All secret literals across all configured profiles, for text redaction. */
+    allSecrets(): readonly string[];
+    configuredEnvironments(): readonly JazzCashEnvironment[];
+}
+/**
+ * Build the credential store.
+ *
+ * Environment variables take precedence over the credentials file for individual
+ * fields, so a shared file can be overridden per process without editing it.
+ */
+export declare function loadCredentialStore(config: EnvironmentConfig, source?: NodeJS.ProcessEnv): CredentialStore;
+export {};
+//# sourceMappingURL=credentials.d.ts.map

package/dist/config/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/config/credentials.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAyB,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAyB3G,QAAA,MAAM,aAAa;;;;;;;iBAOjB,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAOlE;;;;;;GAMG;AACH;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAarG;AAED,qBAAa,iBAAiB;IAC5B,SAAgB,WAAW,EAAE,mBAAmB,CAAC;IAEjD,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,SAAgB,aAAa,EAAE,MAAM,CAAC;IAEtC,SAAgB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IAEjD,SAAgB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAE9C,SAAgB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;gBAExB,WAAW,EAAE,mBAAmB,EAAE,IAAI,EAAE,qBAAqB;IAUhF,gFAAgF;IACzE,OAAO,IAAI,SAAS,MAAM,EAAE;IAInC,8EAA8E;IACvE,eAAe,IAAI,OAAO;IAIjC,6FAA6F;IACtF,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAYlC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIhC,QAAQ,IAAI,MAAM;CAG1B;AAED,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,GAAG,CAAC,WAAW,EAAE,mBAAmB,GAAG,iBAAiB,CAAC;IACzD,GAAG,CAAC,WAAW,EAAE,mBAAmB,GAAG,OAAO,CAAC;IAC/C,8EAA8E;IAC9E,UAAU,IAAI,SAAS,MAAM,EAAE,CAAC;IAChC,sBAAsB,IAAI,SAAS,mBAAmB,EAAE,CAAC;CAC1D;AAuED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,EACzB,MAAM,GAAE,MAAM,CAAC,UAAwB,GACtC,eAAe,CAgDjB"}

package/dist/config/credentials.js

@@ -0,0 +1,216 @@
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { JazzCashConfigError } from '../errors.js';
+import { maskTail, REDACTED } from '../telemetry/redaction.js';
+import { JAZZCASH_ENVIRONMENTS } from './environment.js';
+/**
+ * Merchant credential resolution.
+ *
+ * Credentials come from the process environment or from a JSON file kept outside
+ * the repository. They are never accepted as ordinary tool arguments except for
+ * the stateless hash and validation helpers, where a merchant may legitimately
+ * want to check a salt they are holding in front of them.
+ */
+/**
+ * A credential literal that is used byte for byte.
+ *
+ * Deliberately not trimmed, unlike `merchantId`: the salt is the HMAC key and
+ * the password is hashed alongside the other values, so a leading space that the
+ * portal really issued must survive intact. A value that is *only* whitespace is
+ * rejected instead of trimmed, because it can produce nothing but a hash the
+ * gateway rejects as a mismatch — the least diagnosable failure this server has.
+ */
+const secretSchema = z
+    .string()
+    .min(1)
+    .refine((value) => value.trim() !== '', 'must not consist only of whitespace');
+const profileSchema = z.object({
+    merchantId: z.string().trim().min(1),
+    password: secretSchema,
+    integritySalt: secretSchema,
+    merchantMpin: secretSchema.optional(),
+    returnUrl: z.string().trim().pipe(z.url()).optional(),
+    ipnUrl: z.string().trim().pipe(z.url()).optional(),
+});
+const credentialsFileSchema = z.strictObject({
+    sandbox: profileSchema.optional(),
+    production: profileSchema.optional(),
+});
+/**
+ * A resolved merchant credential set.
+ *
+ * `toJSON` and `toString` are overridden so that an accidental interpolation or
+ * `JSON.stringify` in a log line, an error message, or a tool result cannot leak
+ * the password, salt or MPIN.
+ */
+/**
+ * Map a payload parameter to the profile field that supplies it.
+ *
+ * Returns `undefined` for every other name, and for a credential the profile
+ * does not carry. Both the builder, which fills a payload from scratch, and the
+ * send path, which refills one whose credentials were masked for the transcript,
+ * resolve credentials through here so the two cannot drift apart — a payload
+ * signed with one profile's salt while carrying another's merchant ID is exactly
+ * the failure this single source of truth prevents.
+ */
+export function credentialParameterValue(name, profile) {
+    switch (name) {
+        case 'pp_MerchantID':
+            return profile.merchantId;
+        case 'pp_Password':
+            return profile.password;
+        case 'pp_MerchantMPIN':
+            return profile.merchantMpin;
+        case 'pp_ReturnURL':
+            return profile.returnUrl;
+        default:
+            return undefined;
+    }
+}
+export class CredentialProfile {
+    environment;
+    merchantId;
+    password;
+    integritySalt;
+    merchantMpin;
+    returnUrl;
+    ipnUrl;
+    constructor(environment, data) {
+        this.environment = environment;
+        this.merchantId = data.merchantId;
+        this.password = data.password;
+        this.integritySalt = data.integritySalt;
+        this.merchantMpin = data.merchantMpin;
+        this.returnUrl = data.returnUrl;
+        this.ipnUrl = data.ipnUrl;
+    }
+    /** Every literal that must be scrubbed from free text before it is returned. */
+    secrets() {
+        return [this.password, this.integritySalt, ...(this.merchantMpin === undefined ? [] : [this.merchantMpin])];
+    }
+    /** True when this profile can be used for refunds, which require the MPIN. */
+    supportsRefunds() {
+        return this.merchantMpin !== undefined;
+    }
+    /** Non-sensitive description, safe to show a merchant to confirm which profile is active. */
+    describe() {
+        return {
+            environment: this.environment,
+            merchantId: this.merchantId,
+            password: maskTail(this.password),
+            integritySalt: maskTail(this.integritySalt),
+            merchantMpin: this.merchantMpin === undefined ? '(not configured)' : REDACTED,
+            returnUrl: this.returnUrl ?? '(not configured)',
+            ipnUrl: this.ipnUrl ?? '(not configured)',
+        };
+    }
+    toJSON() {
+        return this.describe();
+    }
+    toString() {
+        return `CredentialProfile(${this.environment}, merchantId=${this.merchantId}, secrets=${REDACTED})`;
+    }
+}
+const ENV_VARIABLE_PREFIX = {
+    sandbox: 'JAZZCASH_SANDBOX',
+    production: 'JAZZCASH_PRODUCTION',
+};
+const ENV_VARIABLE_SUFFIX = {
+    merchantId: 'MERCHANT_ID',
+    password: 'PASSWORD',
+    integritySalt: 'INTEGRITY_SALT',
+    merchantMpin: 'MERCHANT_MPIN',
+    returnUrl: 'RETURN_URL',
+    ipnUrl: 'IPN_URL',
+};
+function readProfileFromEnv(environment, source) {
+    const prefix = ENV_VARIABLE_PREFIX[environment];
+    const result = {};
+    for (const field of Object.keys(ENV_VARIABLE_SUFFIX)) {
+        const raw = source[`${prefix}_${ENV_VARIABLE_SUFFIX[field]}`];
+        if (typeof raw === 'string' && raw !== '') {
+            // Preserve the source value here. `profileSchema` owns field-specific
+            // normalisation: identifiers and URLs are trimmed, while secrets remain
+            // byte-for-byte and its refinement rejects whitespace-only literals.
+            result[field] = raw;
+        }
+    }
+    return result;
+}
+function readProfilesFromFile(path) {
+    let contents;
+    try {
+        contents = readFileSync(path, 'utf8');
+    }
+    catch (cause) {
+        throw new JazzCashConfigError(`Unable to read JAZZCASH_CREDENTIALS_FILE at ${path}.`, { cause });
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(contents);
+    }
+    catch (cause) {
+        throw new JazzCashConfigError(`JAZZCASH_CREDENTIALS_FILE at ${path} is not valid JSON.`, { cause });
+    }
+    const parsed = credentialsFileSchema.safeParse(parsedJson);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new JazzCashConfigError(`JAZZCASH_CREDENTIALS_FILE at ${path} has an invalid shape. ${issues}`);
+    }
+    return parsed.data;
+}
+function describeMissingFields(environment, issuePaths) {
+    const prefix = ENV_VARIABLE_PREFIX[environment];
+    const variables = issuePaths
+        .map((path) => ENV_VARIABLE_SUFFIX[path])
+        .filter((suffix) => suffix !== undefined)
+        .map((suffix) => `${prefix}_${suffix}`);
+    return variables.length > 0 ? variables.join(', ') : 'unknown fields';
+}
+/**
+ * Build the credential store.
+ *
+ * Environment variables take precedence over the credentials file for individual
+ * fields, so a shared file can be overridden per process without editing it.
+ */
+export function loadCredentialStore(config, source = process.env) {
+    const fromFile = config.credentialsFile === undefined ? {} : readProfilesFromFile(config.credentialsFile);
+    const profiles = new Map();
+    const incomplete = new Map();
+    for (const environment of JAZZCASH_ENVIRONMENTS) {
+        const merged = { ...fromFile[environment], ...readProfileFromEnv(environment, source) };
+        if (Object.keys(merged).length === 0) {
+            continue;
+        }
+        const parsed = profileSchema.safeParse(merged);
+        if (parsed.success) {
+            profiles.set(environment, new CredentialProfile(environment, parsed.data));
+        }
+        else {
+            incomplete.set(environment, describeMissingFields(environment, parsed.error.issues.map((issue) => String(issue.path[0]))));
+        }
+    }
+    return {
+        get(environment) {
+            const profile = profiles.get(environment);
+            if (profile !== undefined) {
+                return profile;
+            }
+            const missing = incomplete.get(environment);
+            const detail = missing === undefined
+                ? `Set ${ENV_VARIABLE_PREFIX[environment]}_MERCHANT_ID, _PASSWORD and _INTEGRITY_SALT, or configure JAZZCASH_CREDENTIALS_FILE.`
+                : `The following are missing or invalid: ${missing}.`;
+            throw new JazzCashConfigError(`No usable ${environment} credentials are configured. ${detail}`);
+        },
+        has(environment) {
+            return profiles.has(environment);
+        },
+        allSecrets() {
+            return [...profiles.values()].flatMap((profile) => profile.secrets());
+        },
+        configuredEnvironments() {
+            return [...profiles.keys()];
+        },
+    };
+}
+//# sourceMappingURL=credentials.js.map

package/dist/config/credentials.js.map

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

package/dist/config/environment.d.ts

@@ -0,0 +1,23 @@
+import { type LogLevel } from '../telemetry/logger.js';
+/**
+ * Server-level configuration, read once at start-up from the process environment.
+ *
+ * Failures are fatal and reported with the offending variable named, because a
+ * half-configured payment tool is more dangerous than one that refuses to start.
+ */
+export declare const JAZZCASH_ENVIRONMENTS: readonly ["sandbox", "production"];
+export type JazzCashEnvironment = (typeof JAZZCASH_ENVIRONMENTS)[number];
+export interface EnvironmentConfig {
+    /** Default environment for tools that do not receive an explicit one. */
+    readonly defaultEnvironment: JazzCashEnvironment;
+    /**
+     * Master switch for production money movement. Even when true, each such tool
+     * call must additionally pass `confirmLiveEnvironment: true`.
+     */
+    readonly allowLive: boolean;
+    readonly httpTimeoutMs: number;
+    readonly logLevel: LogLevel;
+    readonly credentialsFile: string | undefined;
+}
+export declare function loadEnvironmentConfig(source?: NodeJS.ProcessEnv): EnvironmentConfig;
+//# sourceMappingURL=environment.d.ts.map

package/dist/config/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/config/environment.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;;;GAKG;AAEH,eAAO,MAAM,qBAAqB,oCAAqC,CAAC;AAExE,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,EAAE,mBAAmB,CAAC;IACjD;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AAiCD,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,MAAM,CAAC,UAAwB,GAAG,iBAAiB,CAiBhG"}

package/dist/config/environment.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { JazzCashConfigError } from '../errors.js';
+import { LOG_LEVELS } from '../telemetry/logger.js';
+/**
+ * Server-level configuration, read once at start-up from the process environment.
+ *
+ * Failures are fatal and reported with the offending variable named, because a
+ * half-configured payment tool is more dangerous than one that refuses to start.
+ */
+export const JAZZCASH_ENVIRONMENTS = ['sandbox', 'production'];
+const booleanFromString = z
+    .string()
+    .trim()
+    .toLowerCase()
+    .refine((value) => ['true', 'false', '1', '0', 'yes', 'no'].includes(value), {
+    message: 'must be one of: true, false, 1, 0, yes, no',
+})
+    .transform((value) => ['true', '1', 'yes'].includes(value));
+const defaultAllowLive = false;
+const environmentSchema = z.object({
+    JAZZCASH_ENVIRONMENT: z.enum(JAZZCASH_ENVIRONMENTS).default('sandbox'),
+    JAZZCASH_ALLOW_LIVE: booleanFromString.default(defaultAllowLive),
+    JAZZCASH_HTTP_TIMEOUT_MS: z.coerce.number().int().positive().max(600_000).default(30_000),
+    JAZZCASH_LOG_LEVEL: z.enum(LOG_LEVELS).default('info'),
+    JAZZCASH_CREDENTIALS_FILE: z.string().trim().min(1).optional(),
+});
+/** Treat empty-string variables as unset; harness `env` blocks routinely contain blanks. */
+function compact(source) {
+    const result = {};
+    for (const key of Object.keys(source)) {
+        const value = source[key];
+        if (typeof value === 'string' && value.trim() !== '') {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+export function loadEnvironmentConfig(source = process.env) {
+    const input = compact(source);
+    const parsed = environmentSchema.safeParse(input);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new JazzCashConfigError(`Invalid server configuration. ${issues}`);
+    }
+    const output = parsed.data;
+    return {
+        defaultEnvironment: output.JAZZCASH_ENVIRONMENT,
+        allowLive: output.JAZZCASH_ALLOW_LIVE,
+        httpTimeoutMs: output.JAZZCASH_HTTP_TIMEOUT_MS,
+        logLevel: output.JAZZCASH_LOG_LEVEL,
+        credentialsFile: output.JAZZCASH_CREDENTIALS_FILE,
+    };
+}
+//# sourceMappingURL=environment.js.map

package/dist/config/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/config/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,UAAU,EAAiB,MAAM,wBAAwB,CAAC;AAEnE;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,SAAS,EAAE,YAAY,CAAU,CAAC;AAiBxE,MAAM,iBAAiB,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,IAAI,EAAE;KACN,WAAW,EAAE;KACb,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE;IAC3E,OAAO,EAAE,4CAA4C;CACtD,CAAC;KACD,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AAE9D,MAAM,gBAAgB,GAAuC,KAAK,CAAC;AAEnE,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,oBAAoB,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACtE,mBAAmB,EAAE,iBAAiB,CAAC,OAAO,CAAC,gBAAgB,CAAC;IAChE,wBAAwB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACzF,kBAAkB,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACtD,yBAAyB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC/D,CAAC,CAAC;AAEH,4FAA4F;AAC5F,SAAS,OAAO,CAAC,MAAyB;IACxC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACrD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,SAA4B,OAAO,CAAC,GAAG;IAC3E,MAAM,KAAK,GAAsC,OAAO,CAAC,MAAM,CAAC,CAAC;IACjE,MAAM,MAAM,GAAG,iBAAiB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAElD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1G,MAAM,IAAI,mBAAmB,CAAC,iCAAiC,MAAM,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,MAAM,GAAuC,MAAM,CAAC,IAAI,CAAC;IAC/D,OAAO;QACL,kBAAkB,EAAE,MAAM,CAAC,oBAAoB;QAC/C,SAAS,EAAE,MAAM,CAAC,mBAAmB;QACrC,aAAa,EAAE,MAAM,CAAC,wBAAwB;QAC9C,QAAQ,EAAE,MAAM,CAAC,kBAAkB;QACnC,eAAe,EAAE,MAAM,CAAC,yBAAyB;KAClD,CAAC;AACJ,CAAC"}

package/dist/core/dependencies.d.ts

@@ -0,0 +1,43 @@
+import type { FlowCatalogue } from '../catalogue/flows.js';
+import type { CredentialStore } from '../config/credentials.js';
+import type { EnvironmentConfig } from '../config/environment.js';
+import type { HttpClient } from '../gateway/http-client.js';
+import type { Logger } from '../telemetry/logger.js';
+/**
+ * Everything a tool may depend on without reading the documentation corpus.
+ *
+ * This is the smaller half of {@link import('../dependencies.js').ServerDependencies},
+ * and it exists as its own module for two reasons that are not stylistic:
+ *
+ *  1. **It is the credential half's whole world.** The four tools that cannot
+ *     run without a merchant credential read exactly one knowledge dependency —
+ *     the flow catalogue — and never touch the transcribed documents, the search
+ *     index or the symptom base. Typing their registrars against this interface
+ *     turns that from a fact somebody checked once into one the compiler
+ *     rechecks on every build: reaching for `deps.corpus` inside a credential
+ *     tool stops being a review comment and becomes an error.
+ *  2. **It bounds what has to travel.** The connector is published as a
+ *     self-contained package built from the module graph reachable from here, so
+ *     anything this interface names is code that ships to merchants. Splitting
+ *     the file rather than merely splitting the interface is what keeps that
+ *     graph honest: `../dependencies.js` type-imports the corpus, the search
+ *     index and the symptom base, and a type-only import still drags its module
+ *     into the graph that a build has to typecheck.
+ */
+export interface CoreDependencies {
+    readonly logger: Logger;
+    readonly config: EnvironmentConfig;
+    readonly credentials: CredentialStore;
+    /** Flow specifications, loaded and validated once at start-up. */
+    readonly catalogue: FlowCatalogue;
+    /**
+     * Transport for gateway calls.
+     *
+     * Optional and normally absent, in which case a client is built per call from
+     * the configured timeout. Present so that every tool which reaches the network
+     * — including orchestration tools that do not expose a transport argument of
+     * their own — can be exercised against a stub instead of the live gateway.
+     */
+    readonly httpClient?: HttpClient | undefined;
+}
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/core/dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../src/core/dependencies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC9C"}

package/dist/core/dependencies.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dependencies.js.map

package/dist/core/dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../../src/core/dependencies.ts"],"names":[],"mappings":""}

package/dist/core/registry.d.ts

@@ -0,0 +1,33 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CoreDependencies } from './dependencies.js';
+/**
+ * Uniform registration signature, parameterised by what the registrar needs.
+ *
+ * Holding all registrations behind one shape keeps `createServer` free of
+ * per-feature knowledge, and isolates the SDK surface that changes between major
+ * versions: migrating to SDK v2 means editing these modules and nothing else.
+ *
+ * The type parameter is what lets a registrar declare the *smaller* dependency
+ * set it actually uses. Under `strictFunctionTypes`, parameter contravariance
+ * makes every `RegistrarFor<CoreDependencies>` assignable to a
+ * `RegistrarFor<ServerDependencies>`, so the full server still composes one
+ * homogeneous list while the credential tools carry a narrower, checkable claim
+ * about what they read.
+ */
+export type RegistrarFor<D> = (server: McpServer, deps: D) => void;
+/**
+ * A registrar that reads no part of the documentation corpus.
+ *
+ * See {@link CoreDependencies} for why that restriction is expressed in the type
+ * system rather than in a comment.
+ */
+export type CoreRegistrar = RegistrarFor<CoreDependencies>;
+/**
+ * Apply a list of registrars to a server instance.
+ *
+ * Generic in the dependency set so that a host serving only the credential tools
+ * can apply them with only {@link CoreDependencies} in hand — it holds no corpus
+ * to pass, which is the point.
+ */
+export declare function applyRegistrars<D>(server: McpServer, deps: D, registrars: readonly RegistrarFor<D>[]): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,gBAAgB,CAAC,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAI3G"}