@atbas/m-mcp 0.1.0

package/dist/core/registry.js

@@ -0,0 +1,13 @@
+/**
+ * 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 function applyRegistrars(server, deps, registrars) {
+    for (const register of registrars) {
+        register(server, deps);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":"AA4BA;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAI,MAAiB,EAAE,IAAO,EAAE,UAAsC;IACnG,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC;AACH,CAAC"}

package/dist/core/server.d.ts

@@ -0,0 +1,61 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CorpusSource } from '../knowledge/source.js';
+import type { CoreDependencies } from './dependencies.js';
+/**
+ * Composition root for the half of the server that reads no documentation
+ * corpus.
+ *
+ * `../server.js` builds on this to compose the whole surface; the published
+ * connector stops here. Keeping the two in separate modules is what makes that
+ * possible: `../server.js` imports the corpus loader, the search-index builder
+ * and the symptom base at module scope, so anything importing it inherits the
+ * entire knowledge half whether it registers a knowledge tool or not.
+ */
+/**
+ * Guidance sent to every client, whichever half of the surface it reached.
+ *
+ * Shared rather than trimmed per surface. A connector serving the credential
+ * tools locally proxies the rest to a hosted endpoint and presents one merged
+ * tool list, so a client that received abridged guidance from the local half
+ * would be told less about tools it can nevertheless call.
+ */
+export declare const SERVER_INSTRUCTIONS: string;
+export interface CoreDependencyOptions {
+    /**
+     * Where the flow specifications are read from.
+     *
+     * Required, not defaulted. `../server.js` passes the corpus directory that
+     * ships beside the code; the published connector passes a source backed by
+     * generated code, because it ships no corpus directory at all — see
+     * `memoryCorpusSource` in `../knowledge/source.js`. Making the caller say
+     * which is what keeps the package-root walk out of this module's graph.
+     */
+    readonly catalogue: CorpusSource | string;
+}
+/**
+ * Build the dependencies a corpus-free surface needs.
+ *
+ * Loads the flow catalogue and nothing else from the corpus: the documents, the
+ * search index and the symptom base are the knowledge half's, and a host that
+ * serves only the credential tools should neither pay to load them nor be able
+ * to reach them. `../server.js` calls this and adds the three.
+ *
+ * @param source - Environment to read configuration and credentials from.
+ * @param options - Where the flow catalogue is read from.
+ * @returns Dependencies for the credential tools, with logging already configured.
+ * @throws {import('../errors.js').JazzCashConfigError} If the environment is malformed or a flow specification is invalid.
+ */
+export declare function createCoreDependencies(source: NodeJS.ProcessEnv, options: CoreDependencyOptions): CoreDependencies;
+/**
+ * A server serving exactly the tools that need a merchant credential.
+ *
+ * No resources and no prompts: those are the corpus's, and are served by the
+ * hosted tier where they are metered. Registering them here as well would
+ * duplicate the whole knowledge surface on both sides of a connector's bridge
+ * and leave the de-duplication rule deciding which copy a merchant sees.
+ *
+ * @param deps - Dependencies built by {@link createCoreDependencies}.
+ * @returns A server with the four credential tools registered.
+ */
+export declare function createCredentialServer(deps: CoreDependencies): McpServer;
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/core/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAM1D;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,QAgBpB,CAAC;AAEb,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,CAAC;CAC3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,EAAE,qBAAqB,GAAG,gBAAgB,CAclH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAYxE"}

package/dist/core/server.js

@@ -0,0 +1,90 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { loadFlowCatalogue } from '../catalogue/flows.js';
+import { loadCredentialStore } from '../config/credentials.js';
+import { loadEnvironmentConfig } from '../config/environment.js';
+import { createLogger } from '../telemetry/logger.js';
+import { CREDENTIAL_TOOLS } from '../tools/credential-tools.js';
+import { SERVER_NAME, SERVER_VERSION } from '../version.js';
+// `./registry.js` is `src/core/registry.ts`, not `src/registry.ts`. The two
+// exist side by side and must never reach each other; see the note at the top of
+// `../registry.js`.
+import { applyRegistrars } from './registry.js';
+/**
+ * Composition root for the half of the server that reads no documentation
+ * corpus.
+ *
+ * `../server.js` builds on this to compose the whole surface; the published
+ * connector stops here. Keeping the two in separate modules is what makes that
+ * possible: `../server.js` imports the corpus loader, the search-index builder
+ * and the symptom base at module scope, so anything importing it inherits the
+ * entire knowledge half whether it registers a knowledge tool or not.
+ */
+/**
+ * Guidance sent to every client, whichever half of the surface it reached.
+ *
+ * Shared rather than trimmed per surface. A connector serving the credential
+ * tools locally proxies the rest to a hosted endpoint and presents one merged
+ * tool list, so a client that received abridged guidance from the local half
+ * would be told less about tools it can nevertheless call.
+ */
+export const SERVER_INSTRUCTIONS = [
+    'This server encodes the official JazzCash payment-gateway integration guides (2026 edition).',
+    '',
+    'Start with `jazzcash_list_integration_flows` to choose a flow, then',
+    '`jazzcash_get_onboarding_checklist` for the setup sequence.',
+    'Use `jazzcash_build_transaction_parameters` rather than assembling payloads by hand:',
+    'it fills constants, formats Pakistan-time timestamps, converts the amount to minor units,',
+    'validates the payload and computes `pp_SecureHash` in one step.',
+    '',
+    'Safety: sandbox and production share identical gateway URLs, so the environment is a',
+    'property of the credentials, not the endpoint. Every network tool requires an explicit',
+    '`environment` argument, and production money movement additionally requires the server to',
+    'be started with JAZZCASH_ALLOW_LIVE=true and the call to pass `confirmLiveEnvironment: true`.',
+    '',
+    'Answer merchant questions from `jazzcash_search_docs` results and cite the document,',
+    'rather than relying on general knowledge of payment gateways.',
+].join('\n');
+/**
+ * Build the dependencies a corpus-free surface needs.
+ *
+ * Loads the flow catalogue and nothing else from the corpus: the documents, the
+ * search index and the symptom base are the knowledge half's, and a host that
+ * serves only the credential tools should neither pay to load them nor be able
+ * to reach them. `../server.js` calls this and adds the three.
+ *
+ * @param source - Environment to read configuration and credentials from.
+ * @param options - Where the flow catalogue is read from.
+ * @returns Dependencies for the credential tools, with logging already configured.
+ * @throws {import('../errors.js').JazzCashConfigError} If the environment is malformed or a flow specification is invalid.
+ */
+export function createCoreDependencies(source, options) {
+    const config = loadEnvironmentConfig(source);
+    const logger = createLogger({ level: config.logLevel }).child({ server: SERVER_NAME });
+    const credentials = loadCredentialStore(config, source);
+    const catalogue = loadFlowCatalogue(options.catalogue);
+    logger.info('Configuration loaded', {
+        defaultEnvironment: config.defaultEnvironment,
+        allowLive: config.allowLive,
+        configuredEnvironments: credentials.configuredEnvironments(),
+        flows: catalogue.list().length,
+    });
+    return { config, logger, credentials, catalogue };
+}
+/**
+ * A server serving exactly the tools that need a merchant credential.
+ *
+ * No resources and no prompts: those are the corpus's, and are served by the
+ * hosted tier where they are metered. Registering them here as well would
+ * duplicate the whole knowledge surface on both sides of a connector's bridge
+ * and leave the de-duplication rule deciding which copy a merchant sees.
+ *
+ * @param deps - Dependencies built by {@link createCoreDependencies}.
+ * @returns A server with the four credential tools registered.
+ */
+export function createCredentialServer(deps) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { instructions: SERVER_INSTRUCTIONS });
+    applyRegistrars(server, deps, CREDENTIAL_TOOLS.map((descriptor) => descriptor.registrar));
+    deps.logger.debug('Credential tool surface registered', { tools: CREDENTIAL_TOOLS.length });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/core/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/core/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE5D,4EAA4E;AAC5E,iFAAiF;AACjF,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,8FAA8F;IAC9F,EAAE;IACF,qEAAqE;IACrE,6DAA6D;IAC7D,sFAAsF;IACtF,2FAA2F;IAC3F,iEAAiE;IACjE,EAAE;IACF,sFAAsF;IACtF,wFAAwF;IACxF,2FAA2F;IAC3F,+FAA+F;IAC/F,EAAE;IACF,sFAAsF;IACtF,+DAA+D;CAChE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAeb;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAyB,EAAE,OAA8B;IAC9F,MAAM,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IACvF,MAAM,WAAW,GAAG,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEvD,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE;QAClC,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,sBAAsB,EAAE,WAAW,CAAC,sBAAsB,EAAE;QAC5D,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM;KAC/B,CAAC,CAAC;IAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AACpD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAsB;IAC3D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,YAAY,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAEpH,eAAe,CACb,MAAM,EACN,IAAI,EACJ,gBAAgB,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAC3D,CAAC;IAEF,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,EAAE,EAAE,KAAK,EAAE,gBAAgB,CAAC,MAAM,EAAE,CAAC,CAAC;IAE5F,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/dependencies.d.ts

@@ -0,0 +1,28 @@
+import type { CoreDependencies } from './core/dependencies.js';
+import type { SymptomKnowledgeBase } from './diagnostics/diagnose.js';
+import type { KnowledgeCorpus } from './knowledge/corpus.js';
+import type { KnowledgeSearchIndex } from './knowledge/search.js';
+export type { CoreDependencies } from './core/dependencies.js';
+/**
+ * Everything a tool, resource or prompt registrar may depend on.
+ *
+ * Passed explicitly rather than reached for through module-level state, so that
+ * no singleton is introduced and every unit is testable in isolation
+ * (CLAUDE.md, Implementation Protocols §3).
+ *
+ * Split across two files rather than two interfaces in one: the three fields
+ * added here are the corpus-backed half, and their type imports are what pull
+ * the corpus loader, the search index and the symptom base into any module graph
+ * that reaches this file. `./core/dependencies.js` carries the rest, and is what
+ * the credential tools and the published connector are built against. See that
+ * module for the full reasoning.
+ */
+export interface ServerDependencies extends CoreDependencies {
+    /** Curated documentation, loaded once at start-up. */
+    readonly corpus: KnowledgeCorpus;
+    /** Offline lexical index over the corpus. */
+    readonly search: KnowledgeSearchIndex;
+    /** Documented failure modes, loaded once at start-up. */
+    readonly symptoms: SymptomKnowledgeBase;
+}
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../src/dependencies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;CACzC"}

package/dist/dependencies.js

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

package/dist/dependencies.js.map

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

package/dist/diagnostics/diagnose.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { type DocRef } from '../errors.js';
+import { type CorpusSource } from '../knowledge/source.js';
+declare const causeSchema: z.ZodObject<{
+    cause: z.ZodString;
+    check: z.ZodString;
+    fix: z.ZodString;
+    docRefs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        docId: z.ZodString;
+        sectionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+declare const symptomSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    keywords: z.ZodArray<z.ZodString>;
+    causes: z.ZodArray<z.ZodObject<{
+        cause: z.ZodString;
+        check: z.ZodString;
+        fix: z.ZodString;
+        docRefs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            docId: z.ZodString;
+            sectionId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DiagnosticCause = z.infer<typeof causeSchema>;
+export type DiagnosticSymptom = z.infer<typeof symptomSchema>;
+export interface SymptomMatch {
+    readonly symptom: DiagnosticSymptom;
+    readonly score: number;
+}
+export interface SymptomKnowledgeBase {
+    readonly version: string;
+    symptoms(): readonly DiagnosticSymptom[];
+    find(id: string): DiagnosticSymptom | undefined;
+    /** Rank symptoms against free-text describing what the merchant sees. */
+    match(description: string, limit?: number): readonly SymptomMatch[];
+    docRefsFor(symptom: DiagnosticSymptom): readonly DocRef[];
+}
+export declare function loadSymptomKnowledgeBase(source?: CorpusSource | string): SymptomKnowledgeBase;
+export {};
+//# sourceMappingURL=diagnose.d.ts.map

package/dist/diagnostics/diagnose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/diagnostics/diagnose.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAGhE,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAiB9E,QAAA,MAAM,WAAW;;;;;;;;iBAKf,CAAC;AAEH,QAAA,MAAM,aAAa;;;;;;;;;;;;;iBAKjB,CAAC;AAQH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAC1D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,IAAI,SAAS,iBAAiB,EAAE,CAAC;IACzC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAChD,yEAAyE;IACzE,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,YAAY,EAAE,CAAC;IACpE,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,MAAM,EAAE,CAAC;CAC3D;AAkBD,wBAAgB,wBAAwB,CACtC,MAAM,GAAE,YAAY,GAAG,MAAqD,GAC3E,oBAAoB,CA8EtB"}

package/dist/diagnostics/diagnose.js

@@ -0,0 +1,121 @@
+import { basename, dirname } from 'node:path';
+import { z } from 'zod';
+import { JazzCashConfigError } from '../errors.js';
+import { knowledgePath } from '../paths.js';
+import { tokenise } from '../knowledge/search.js';
+import { localCorpusSource } from '../knowledge/source.js';
+/**
+ * Symptom knowledge base.
+ *
+ * The questions the resident engineers answer repeatedly, keyed by what the
+ * merchant actually observes rather than by what the cause turns out to be.
+ * Every cause carries a check and a fix, because a diagnosis without a next
+ * action is another support ticket.
+ *
+ * The file arrives through a `CorpusSource`, so the same loader reads a
+ * knowledge base that is not a file on this machine.
+ */
+/** The knowledge base's name within the diagnostics part of the corpus. */
+const SYMPTOMS_ENTRY = 'symptoms.json';
+const causeSchema = z.object({
+    cause: z.string().min(1),
+    check: z.string().min(1),
+    fix: z.string().min(1),
+    docRefs: z.array(z.object({ docId: z.string().min(1), sectionId: z.string().min(1).optional() })).default([]),
+});
+const symptomSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    keywords: z.array(z.string()).min(1),
+    causes: z.array(causeSchema).min(1),
+});
+const knowledgeBaseSchema = z.strictObject({
+    version: z.string().min(1),
+    note: z.string().optional(),
+    symptoms: z.array(symptomSchema).min(1),
+});
+/**
+ * Resolve the parameter to a source and the entry to read from it.
+ *
+ * A string is the path of the knowledge-base file itself, which is the shape
+ * this loader has always taken and what lets a caller point at a one-off file
+ * without constructing a source. A source is rooted at the directory holding the
+ * knowledge base, so the file is addressed by the name it carries inside the
+ * corpus rather than by a path this process can resolve.
+ */
+function resolveKnowledgeBase(source) {
+    if (typeof source === 'string') {
+        return { files: localCorpusSource(dirname(source)), entry: basename(source) };
+    }
+    return { files: source, entry: SYMPTOMS_ENTRY };
+}
+export function loadSymptomKnowledgeBase(source = knowledgePath('diagnostics', SYMPTOMS_ENTRY)) {
+    const { files, entry } = resolveKnowledgeBase(source);
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(files.readText(entry));
+    }
+    catch (cause) {
+        throw new JazzCashConfigError(`Unable to read the diagnostics knowledge base at ${files.locate(entry)}.`, {
+            cause,
+        });
+    }
+    const parsed = knowledgeBaseSchema.safeParse(parsedJson);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new JazzCashConfigError(`The diagnostics knowledge base is invalid. ${issues}`);
+    }
+    const { symptoms, version } = parsed.data;
+    const byId = new Map(symptoms.map((symptom) => [symptom.id, symptom]));
+    // Pre-tokenise once: the keyword list plus the title and the cause text, so a
+    // merchant's own wording matches even when it does not use a keyword verbatim.
+    const indexed = symptoms.map((symptom) => ({
+        symptom,
+        keywordTokens: new Set(symptom.keywords.flatMap((keyword) => tokenise(keyword))),
+        bodyTokens: new Set(tokenise([symptom.title, ...symptom.causes.map((entry) => `${entry.cause} ${entry.check}`)].join(' '))),
+    }));
+    return {
+        version,
+        symptoms: () => symptoms,
+        find: (id) => byId.get(id),
+        match(description, limit = 3) {
+            const tokens = tokenise(description);
+            if (tokens.length === 0) {
+                return [];
+            }
+            return indexed
+                .map((entry) => {
+                let score = 0;
+                for (const token of new Set(tokens)) {
+                    // A keyword hit is stronger evidence than an incidental word in the
+                    // explanatory prose.
+                    if (entry.keywordTokens.has(token)) {
+                        score += 3;
+                    }
+                    else if (entry.bodyTokens.has(token)) {
+                        score += 1;
+                    }
+                }
+                return { symptom: entry.symptom, score };
+            })
+                .filter((entry) => entry.score > 0)
+                .sort((left, right) => right.score - left.score)
+                .slice(0, limit);
+        },
+        docRefsFor(symptom) {
+            const seen = new Set();
+            const refs = [];
+            for (const cause of symptom.causes) {
+                for (const ref of cause.docRefs) {
+                    const key = `${ref.docId}#${ref.sectionId ?? ''}`;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        refs.push(ref);
+                    }
+                }
+            }
+            return refs;
+        },
+    };
+}
+//# sourceMappingURL=diagnose.js.map

package/dist/diagnostics/diagnose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.js","sourceRoot":"","sources":["../../src/diagnostics/diagnose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,mBAAmB,EAAe,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAqB,MAAM,wBAAwB,CAAC;AAE9E;;;;;;;;;;GAUG;AAEH,2EAA2E;AAC3E,MAAM,cAAc,GAAG,eAAe,CAAC;AAEvC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC9G,CAAC,CAAC;AAEH,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACpC,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAG,CAAC,CAAC,YAAY,CAAC;IACzC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACxC,CAAC,CAAC;AAmBH;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAAC,MAA6B;IACzD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,EAAE,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;IAChF,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,SAAgC,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC;IAE5E,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAEtD,IAAI,UAAmB,CAAC;IACxB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,mBAAmB,CAAC,oDAAoD,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;YACxG,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IACzD,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,8CAA8C,MAAM,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEvE,8EAA8E;IAC9E,+EAA+E;IAC/E,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACzC,OAAO;QACP,aAAa,EAAE,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QAChF,UAAU,EAAE,IAAI,GAAG,CACjB,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CACvG;KACF,CAAC,CAAC,CAAC;IAEJ,OAAO;QACL,OAAO;QACP,QAAQ,EAAE,GAAiC,EAAE,CAAC,QAAQ;QACtD,IAAI,EAAE,CAAC,EAAU,EAAiC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAEjE,KAAK,CAAC,WAAmB,EAAE,KAAK,GAAG,CAAC;YAClC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;YACrC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxB,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,OAAO,OAAO;iBACX,GAAG,CAAC,CAAC,KAAK,EAAgB,EAAE;gBAC3B,IAAI,KAAK,GAAG,CAAC,CAAC;gBACd,KAAK,MAAM,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACpC,oEAAoE;oBACpE,qBAAqB;oBACrB,IAAI,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;wBACnC,KAAK,IAAI,CAAC,CAAC;oBACb,CAAC;yBAAM,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;wBACvC,KAAK,IAAI,CAAC,CAAC;oBACb,CAAC;gBACH,CAAC;gBACD,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;YAC3C,CAAC,CAAC;iBACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;iBAClC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;iBAC/C,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACrB,CAAC;QAED,UAAU,CAAC,OAA0B;YACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,MAAM,IAAI,GAAa,EAAE,CAAC;YAE1B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACnC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;oBAChC,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;oBAClD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;wBACnB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;wBACd,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;oBACjB,CAAC;gBACH,CAAC;YACH,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/domain/amount.d.ts

@@ -0,0 +1,157 @@
+import type { DocRef } from '../errors.js';
+/**
+ * Amount handling.
+ *
+ * Every JazzCash guide states the same rule: `pp_Amount` is in minor units. The
+ * value is multiplied by 100 before sending and the gateway treats the final two
+ * digits as decimals, so PKR 100.00 is transmitted as `"10000"`.
+ *
+ * That ×100 is a property of PKR, not of money. The ISO 4217 minor-unit exponent
+ * is 2 for PKR and TRY, 0 for JPY and 3 for KWD, so a hard-coded ×100 would debit
+ * a JPY merchant one hundred times the intended sum and a KWD merchant one tenth
+ * of it — and the digits that reach the gateway look entirely ordinary in both
+ * cases. The scale, the ceiling, the display code, the citation and the wire
+ * encoding are therefore all carried by a {@link Currency}, and every function
+ * defaults to {@link PKR} so that a JazzCash caller never has to name one.
+ *
+ * All arithmetic here is integer arithmetic on `bigint`. Floating point is never
+ * used: `0.1 + 0.2` is not 0.3, and money must not be represented by a type that
+ * cannot hold it exactly.
+ */
+/**
+ * How a gateway expects an amount to appear on the wire.
+ *
+ * `minor-units` is JazzCash: PKR 100.00 is `"10000"`. `major-units` is the same
+ * sum as a decimal string, `"100.00"`, which some gateways take instead.
+ *
+ * Declared per currency rather than decided here, so that a gateway expecting
+ * the other encoding is a one-line change to a currency definition instead of an
+ * inversion of the whole amount pipeline.
+ */
+export type AmountEncoding = 'minor-units' | 'major-units';
+/**
+ * ISO 4217 minor-unit exponent: minor units per major unit is 10 to this power.
+ *
+ * A literal union rather than `number`, so an unlisted exponent is a compile
+ * error instead of a silently wrong multiplier. ISO 4217 defines none above 4.
+ */
+export type MinorUnitExponent = 0 | 1 | 2 | 3 | 4;
+/** A currency declaration as a caller writes it; {@link defineCurrency} completes it. */
+export interface CurrencySpec {
+    /** ISO 4217 alphabetic code, reproduced verbatim in merchant-facing messages. */
+    readonly code: string;
+    readonly exponent: MinorUnitExponent;
+    readonly encoding: AmountEncoding;
+    /**
+     * Local sanity ceiling on a single transaction, in MAJOR units.
+     *
+     * Stated in major units because that is the figure a human recognises as far
+     * too large. The same count of minor units means a thousand times more money
+     * in KWD than in JPY, so a ceiling copied between currencies as minor units
+     * would quietly stop guarding anything.
+     */
+    readonly maxMajorUnits: bigint;
+    /** Documentation explaining this currency's amount rules, cited in every rejection. */
+    readonly docRefs?: readonly DocRef[] | undefined;
+}
+/**
+ * A validated currency with its derived scale.
+ *
+ * Build one with {@link defineCurrency} rather than as an object literal: the
+ * derived members must agree with the exponent, and an assembled-by-hand pair
+ * that disagrees would mis-scale every amount in that currency.
+ */
+export interface Currency extends CurrencySpec {
+    readonly docRefs: readonly DocRef[];
+    /** 10^exponent: minor units in one major unit. */
+    readonly scale: bigint;
+    /** {@link CurrencySpec.maxMajorUnits} expressed in minor units. */
+    readonly maxMinorUnits: bigint;
+}
+/**
+ * Validate a currency declaration and derive its scale.
+ *
+ * The checks run once per definition and are cheap, but a mistyped exponent is
+ * not a cosmetic fault: it multiplies or divides every amount in that currency
+ * by a power of ten, and no downstream check can detect the difference between a
+ * deliberate JPY 10,000 and a KWD 10,000 that should have been 10.000. A
+ * currency assembled from a configuration file — the obvious next step once a
+ * second provider ships — must fail here rather than at the gateway.
+ */
+export declare function defineCurrency(spec: CurrencySpec): Currency;
+/** The only currency JazzCash processes. No conversion is performed. */
+export declare const PKR: Currency;
+/** The ISO 4217 code of the only currency the JazzCash gateway processes. */
+export declare const SUPPORTED_CURRENCY: string;
+/**
+ * Upper bound on a single PKR transaction, in minor units (PKR 100,000,000.00).
+ *
+ * Derived from {@link PKR} rather than written out, so the ceiling cannot drift
+ * away from the currency it belongs to. Retained as a named export because
+ * callers and tests reason about the PKR ceiling directly.
+ */
+export declare const MAX_MINOR_UNITS: bigint;
+/**
+ * Convert a human-facing amount to the minor-unit string the gateway expects.
+ *
+ * Accepts `"100"`, `"100.5"`, `"100.50"` and the numeric equivalents in a
+ * two-decimal currency. Rejects anything with more decimal places than the
+ * currency has, because rounding a merchant's money silently is worse than
+ * refusing it.
+ */
+export declare function toMinorUnits(amount: string | number, currency?: Currency): string;
+/**
+ * Validate a minor-unit string, throwing with an actionable message if it is wrong.
+ *
+ * Unlike {@link toMinorUnits}, which converts a human-facing figure, this checks
+ * a value that is already in wire form, so surrounding whitespace is rejected
+ * rather than absorbed.
+ */
+export declare function assertMinorUnits(value: string, currency?: Currency): void;
+/** Convert minor units back to a major-unit string, e.g. `"10000"` to `"100.00"`. */
+export declare function fromMinorUnits(minorUnits: string, currency?: Currency): string;
+/** Format minor units for display to a merchant, e.g. `"PKR 100.00"`. */
+export declare function formatAmount(minorUnits: string, currency?: Currency): string;
+/**
+ * Format minor units as PKR.
+ *
+ * Retained as a named function because it reads better at a JazzCash-only call
+ * site than {@link formatAmount} with a defaulted currency, and because removing
+ * it would churn callers for no behavioural gain.
+ */
+export declare function formatPkr(minorUnits: string): string;
+/**
+ * Encode a human-facing amount as the provider's gateway expects to receive it.
+ *
+ * The counterpart of {@link toMinorUnits} for a provider whose wire form is not
+ * minor units. Both go through the same exact integer parse, so a `major-units`
+ * gateway cannot receive a figure that a `minor-units` gateway would have
+ * refused.
+ */
+export declare function toWireAmount(amount: string | number, currency?: Currency): string;
+/**
+ * Validate a value already in wire form against the currency's encoding.
+ *
+ * A decimal point is a defect in a minor-unit payload and mandatory in a
+ * major-unit one, so the same string cannot be judged without knowing which
+ * gateway it is bound for.
+ */
+export declare function assertWireAmount(value: string, currency?: Currency): void;
+/**
+ * Recover canonical minor units from a value in wire form.
+ *
+ * The inverse of {@link toWireAmount}. Response handling compares the amount the
+ * gateway echoed with the amount that was sent, and comparing `"100.00"` with
+ * `"10000"` as strings reports a mismatch between two identical sums.
+ */
+export declare function minorUnitsFromWire(value: string, currency?: Currency): string;
+/**
+ * Heuristic: does this look like a major-unit amount that was never scaled?
+ *
+ * Used by validation to turn the single most common integration mistake into a
+ * specific warning instead of an opaque gateway rejection. A decimal point is
+ * conclusive; a suspiciously small whole number is only a warning, because a
+ * PKR 1.00 test transaction (`"100"`) is both legitimate and common.
+ */
+export declare function looksLikeMajorUnits(value: string, currency?: Currency): boolean;
+//# sourceMappingURL=amount.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../../src/domain/amount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG3C;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,aAAa,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAElD,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAClD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AA+BD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,QAAQ,CA2B3D;AAED,wEAAwE;AACxE,eAAO,MAAM,GAAG,EAAE,QAShB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,QAAW,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAoB,CAAC;AA4EjD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,GAAE,QAAc,GAAG,MAAM,CAuBtF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAc,GAAG,IAAI,CAqB9E;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAc,GAAG,MAAM,CAoBnF;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAc,GAAG,MAAM,CAEjF;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,GAAE,QAAc,GAAG,MAAM,CAGtF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAc,GAAG,IAAI,CAY9E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAc,GAAG,MAAM,CAGlF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAc,GAAG,OAAO,CAOpF"}