@atbas/m-mcp 0.1.0

package/dist/tools/onboarding-checklist.js

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+import { PORTAL_URLS } from '../catalogue/endpoints.js';
+import { citations, safeHandler, toolResult } from './tool-kit.js';
+/**
+ * The onboarding sequence a resident engineer walks every merchant through.
+ *
+ * Assembled from the "Create a Sandbox Account", "Mandatory API Integrations"
+ * and "Testing" sections that repeat across the guides, plus the platform
+ * specifics from the WooCommerce and Shopify guides.
+ */
+const PLATFORMS = ['custom', 'woocommerce', 'shopify'];
+/** Screenshot evidence JazzCash asks for, from the card redirection guide. */
+const TEST_EVIDENCE = [
+    'Merchant checkout page',
+    'JazzCash landing page',
+    'Payment method selection',
+    'Payment step',
+    'Payment response received on the merchant Callback URL',
+    'Order status in the merchant admin panel',
+];
+function accountSteps(flow) {
+    const steps = [
+        `Sign up for a sandbox account at ${PORTAL_URLS.sandboxSignup}.`,
+        'Send your Merchant ID to JazzCash and ask them to enable the payment options you need. Until they do, the method will not appear.',
+        'In the sandbox portal, open Integration → Credentials and record the Merchant ID, Password and Integrity Salt.',
+        'Enter your Return URL / Callback URL in the same screen. It becomes part of your merchant profile and must then be used unchanged in every request.',
+        'Enter your IPN URL in the IPN field.',
+        // Assumption A5, docs/mcp/JAZZCASH-CLARIFICATIONS.md item 6. The guides
+        // instruct merchants to test with "the sandbox testing numbers" and then
+        // publish none of them, so the first sandbox transaction fails for a reason
+        // no document explains. Stated here, in the steps every flow shares, rather
+        // than only in the WooCommerce path where it used to live: a merchant who
+        // learns this after the failure has already spent the afternoon on it.
+        'Ask JazzCash for the sandbox test MSISDNs and CNICs, and for any that deliberately trigger failure codes. They are NOT published in any guide, and no sandbox transaction can be completed without them. Request them at the same time as your credentials, because nothing else in this checklist can be verified until they arrive.',
+    ];
+    if (flow.product === 'refund' || flow.companionFlows.some((id) => id.startsWith('refund'))) {
+        steps.push('Save your Merchant MPIN in the merchant portal. Refunds fail until it is stored there, not merely sent in the request.');
+    }
+    if (flow.id === 'bnpl-page-redirection-v1.1' || flow.id === 'refund-bnpl') {
+        steps.push('BNPL is tested with PRODUCTION credentials, not sandbox. Every BNPL test is a real transaction: use the smallest possible amount and refund it afterwards.');
+    }
+    return steps;
+}
+function platformSteps(platform) {
+    if (platform === 'woocommerce') {
+        return [
+            'Confirm WooCommerce is installed and active.',
+            'Obtain the JazzCash plugin .zip from JazzCash, upload it under Plugins → Add New → Upload, and activate it.',
+            'Enter your credentials under WooCommerce → Settings → Payments → JazzCash → Manage, and save.',
+            'Register Return URL `{yourBaseURL}/wc-api/result/` in the portal Credentials tab. The trailing slash matters.',
+            'Register IPN URL `{yourBaseURL}/jazzcash_ipn_v2` in the portal Credentials tab.',
+            'Add two test products, one at PKR 10 and one at PKR 1, for card and wallet testing.',
+            'Confirm you have the sandbox test numbers from JazzCash before testing — see the account steps above; they are published in no guide.',
+            'Process refunds from the JazzCash Transaction tab.',
+        ];
+    }
+    if (platform === 'shopify') {
+        return [
+            'Settle, capture or refund every pending transaction in the old JazzCash app, and export any reports you need.',
+            'Shopify Admin → Settings → Payments → the existing JazzCash method → Manage → Deactivate. Do NOT uninstall the old app yet.',
+            'Install the new app from https://apps.shopify.com/jazzcash and approve the permissions.',
+            'Enter Merchant ID, Integrity Salt and Password on the onboarding screen and save.',
+            'Settings → Payments → the new JazzCash method → Activate.',
+            'Open App, confirm the credentials, and check the Transactions tab.',
+            'Place a small-value test order and confirm redirection, status update and that the order is marked Paid.',
+            'Only once everything is settled and tested, uninstall the old app from Settings → Apps and Sales Channels.',
+            'Save the Merchant MPIN in the merchant portal before attempting a refund from the order details page.',
+        ];
+    }
+    return [
+        'Generate pp_SecureHash server-side. Never compute it in browser JavaScript: the Integrity Salt is the HMAC key and would be published in your page source.',
+        'Build the payload with jazzcash_build_transaction_parameters so constants, timestamps, minor units and the hash are all correct by construction.',
+        'Implement the Status Inquiry API. It is mandatory, and it is how you resolve any transaction whose outcome you did not see.',
+        'Implement an IPN listener. It is mandatory. Verify pp_SecureHash before acting, make it idempotent against the documented 2 retries, and respond with pp_ResponseCode "000" within 60 seconds.',
+        'Implement the Refund API if you need refunds. It is optional.',
+    ];
+}
+export const registerOnboardingChecklist = (server, deps) => {
+    server.registerTool('jazzcash_get_onboarding_checklist', {
+        title: 'Get the JazzCash onboarding checklist',
+        description: 'The full setup sequence for a flow: sandbox account, credentials, URL registration, mandatory companion APIs, the test evidence JazzCash requires, and go-live steps. Platform-specific steps for WooCommerce and Shopify.',
+        inputSchema: {
+            flowId: z.string().describe('Flow you are integrating, e.g. "card-page-redirection-v1.1".'),
+            platform: z
+                .enum(PLATFORMS)
+                .optional()
+                .describe('"woocommerce" or "shopify" for plugin steps; "custom" (default) for a bespoke integration.'),
+        },
+    }, safeHandler(deps, 'jazzcash_get_onboarding_checklist', ({ flowId, platform }) => {
+        const flow = deps.catalogue.get(flowId);
+        const resolvedPlatform = platform ?? 'custom';
+        const account = accountSteps(flow);
+        const implementation = platformSteps(resolvedPlatform);
+        const mandatory = flow.companionFlows.length > 0 ? flow.companionFlows : ['status-inquiry-v1.1'];
+        const numbered = (steps, offset = 0) => steps.map((step, index) => `${String(index + 1 + offset)}. ${step}`).join('\n');
+        const text = [
+            `# Onboarding checklist — ${flow.title}`,
+            resolvedPlatform === 'custom' ? '' : `Platform: ${resolvedPlatform}`,
+            '',
+            '## 1. Account and credentials',
+            numbered(account),
+            '',
+            `## 2. Implementation (${resolvedPlatform})`,
+            numbered(implementation),
+            '',
+            '## 3. Mandatory companion integrations',
+            'The guides mark these as mandatory, not optional:',
+            mandatory.map((id) => `- ${id}`).join('\n'),
+            '- An IPN listener (see jazzcash://docs/ipn-implementation)',
+            '',
+            '## 4. Test evidence JazzCash requires',
+            'This step needs the sandbox test MSISDNs and CNICs, which no guide publishes. If you have not received them from JazzCash yet, stop here and ask: the transactions below cannot be completed without them.',
+            'Perform test transactions for each payment method you have enabled — mobile account, voucher and credit/debit card — and capture, for each:',
+            TEST_EVIDENCE.map((item) => `- ${item}`).join('\n'),
+            'Paste the screenshots into the template JazzCash supplied and reply on the same email thread.',
+            '',
+            '## 5. Before go-live',
+            '1. Confirm pp_ReturnURL registered in the portal is byte-identical to the one you send.',
+            '2. Confirm pp_Amount is multiplied by 100 everywhere, including refunds.',
+            '3. Confirm pp_TxnRefNo is unique per transaction. A timestamp alone collides whenever two orders are placed in the same second, so append random characters inside the 20-character limit.',
+            '4. Confirm your IPN listener verifies pp_SecureHash and is idempotent.',
+            '5. Confirm the Integrity Salt exists only on your server, never in client-side code or version control.',
+            '6. Swap sandbox credentials for production credentials. The endpoint does not change, so this credential swap IS the go-live switch.',
+            '7. Run one small live transaction and refund it.',
+            citations(flow.docRefs),
+        ]
+            .filter((line) => line !== '')
+            .join('\n');
+        return toolResult(text, {
+            structuredContent: {
+                flowId: flow.id,
+                platform: resolvedPlatform,
+                accountSteps: account,
+                implementationSteps: implementation,
+                mandatoryCompanions: mandatory,
+                testEvidence: TEST_EVIDENCE,
+            },
+        });
+    }));
+};
+//# sourceMappingURL=onboarding-checklist.js.map

package/dist/tools/onboarding-checklist.js.map

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

package/dist/tools/register.d.ts

@@ -0,0 +1,60 @@
+import type { Registrar } from '../registry.js';
+import { type ToolFacts } from './descriptor.js';
+/**
+ * The tool surface, described once.
+ *
+ * Each tool lives in its own module and exports a single registrar. Describing
+ * them here keeps `createServer` from growing into a god object and makes the
+ * tool surface auditable at a glance.
+ *
+ * The four credential-requiring descriptors are imported from
+ * `./credential-tools.js` rather than declared here, and this module re-exports
+ * that list unchanged. The direction matters: a consumer that needs only those
+ * four — the published connector — imports the narrow module and never reaches
+ * this one, so it never pulls the corpus loader, the search index, the code
+ * generators or the diagnostics into its build. A consumer that needs the whole
+ * surface imports this module and gets both halves in the order below.
+ */
+export type { CoreToolDescriptor, ToolFacts, ToolGroup } from './descriptor.js';
+export { CREDENTIAL_TOOLS } from './credential-tools.js';
+export interface ToolDescriptor extends ToolFacts {
+    readonly registrar: Registrar;
+}
+/**
+ * Every tool, with the two facts no consumer can derive for itself.
+ *
+ * `requiresCredentials` is an explicit per-tool flag rather than a property of
+ * `group`, because the two genuinely disagree and always will. Inferring the
+ * split from the group would put `jazzcash_build_transaction_parameters` — which
+ * sits in the hash group but resolves a credential profile unconditionally, and
+ * signs a payload with the merchant's Integrity Salt — on a public hosted
+ * endpoint, where it would either fail on every call or run against whatever
+ * credentials that host happens to hold. The same inference would withhold
+ * `jazzcash_verify_ipn_notification` from the hosted tier although it takes its
+ * salt as a call argument and needs no configured credential at all.
+ *
+ * The flag says only what the handler does: a tool is marked `true` when it
+ * resolves a `CredentialProfile` on every path (directly through
+ * `deps.credentials.get`, or through `guardGatewayCall`), and `false` when the
+ * value can be supplied per call or is optional enrichment guarded by
+ * `deps.credentials.has`. Determined by reading each handler; a tool whose
+ * handler starts resolving credentials must move to `./credential-tools.js` in
+ * the same change. `tests/tools/register.test.ts` fails on a tool with no
+ * descriptor at all, on a `true` flag declared outside that module, and on a
+ * descriptor duplicated rather than shared between the two lists. A handler that
+ * cannot be typed as a `CoreRegistrar` is caught earlier still, by the compiler,
+ * and `scripts/closure.mjs` fails the build if what it reaches widens.
+ *
+ * Listed in group order, so `ALL_TOOLS` keeps the registration order it had
+ * before the descriptors existed.
+ */
+export declare const TOOL_DESCRIPTORS: readonly ToolDescriptor[];
+export declare const KNOWLEDGE_TOOLS: readonly Registrar[];
+export declare const HASH_TOOLS: readonly Registrar[];
+export declare const CODEGEN_TOOLS: readonly Registrar[];
+export declare const GATEWAY_TOOLS: readonly Registrar[];
+export declare const DIAGNOSTIC_TOOLS: readonly Registrar[];
+export declare const ALL_TOOLS: readonly Registrar[];
+/** Tools that need no configured credential, and are safe to serve from a host that holds none. */
+export declare const CREDENTIAL_FREE_TOOLS: readonly ToolDescriptor[];
+//# sourceMappingURL=register.d.ts.map

package/dist/tools/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/tools/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQhD,OAAO,EAAE,KAAK,SAAS,EAAkB,MAAM,iBAAiB,CAAC;AAajE;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EAAE,kBAAkB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EA+FrD,CAAC;AAMF,eAAO,MAAM,eAAe,EAAE,SAAS,SAAS,EAAmC,CAAC;AAEpF,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EAA8B,CAAC;AAE1E,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAAiC,CAAC;AAEhF,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAAiC,CAAC;AAEhF,eAAO,MAAM,gBAAgB,EAAE,SAAS,SAAS,EAAqC,CAAC;AAEvF,eAAO,MAAM,SAAS,EAAE,SAAS,SAAS,EAA+D,CAAC;AAE1G,mGAAmG;AACnG,eAAO,MAAM,qBAAqB,EAAE,SAAS,cAAc,EAE1D,CAAC"}

package/dist/tools/register.js

@@ -0,0 +1,145 @@
+import { registerGenerateIntegrationCode, registerGenerateIpnHandler } from './codegen-tools.js';
+import { BUILD_CHECKOUT_FORM, BUILD_TRANSACTION_PARAMETERS, RUN_SANDBOX_SMOKE_TEST, SEND_GATEWAY_REQUEST, } from './credential-tools.js';
+import {} from './descriptor.js';
+import { registerDiagnoseIntegrationIssue } from './diagnostic-tools.js';
+import { registerVerifyIpnNotification } from './gateway-tools.js';
+import { registerBuildSecureHash, registerValidatePayload, registerVerifySecureHash } from './hash-tools.js';
+import { registerExplainResponseCode, registerGetDocSection, registerGetIntegrationFlow, registerListIntegrationFlows, registerSearchDocs, } from './knowledge-tools.js';
+import { registerOnboardingChecklist } from './onboarding-checklist.js';
+export { CREDENTIAL_TOOLS } from './credential-tools.js';
+/**
+ * Every tool, with the two facts no consumer can derive for itself.
+ *
+ * `requiresCredentials` is an explicit per-tool flag rather than a property of
+ * `group`, because the two genuinely disagree and always will. Inferring the
+ * split from the group would put `jazzcash_build_transaction_parameters` — which
+ * sits in the hash group but resolves a credential profile unconditionally, and
+ * signs a payload with the merchant's Integrity Salt — on a public hosted
+ * endpoint, where it would either fail on every call or run against whatever
+ * credentials that host happens to hold. The same inference would withhold
+ * `jazzcash_verify_ipn_notification` from the hosted tier although it takes its
+ * salt as a call argument and needs no configured credential at all.
+ *
+ * The flag says only what the handler does: a tool is marked `true` when it
+ * resolves a `CredentialProfile` on every path (directly through
+ * `deps.credentials.get`, or through `guardGatewayCall`), and `false` when the
+ * value can be supplied per call or is optional enrichment guarded by
+ * `deps.credentials.has`. Determined by reading each handler; a tool whose
+ * handler starts resolving credentials must move to `./credential-tools.js` in
+ * the same change. `tests/tools/register.test.ts` fails on a tool with no
+ * descriptor at all, on a `true` flag declared outside that module, and on a
+ * descriptor duplicated rather than shared between the two lists. A handler that
+ * cannot be typed as a `CoreRegistrar` is caught earlier still, by the compiler,
+ * and `scripts/closure.mjs` fails the build if what it reaches widens.
+ *
+ * Listed in group order, so `ALL_TOOLS` keeps the registration order it had
+ * before the descriptors existed.
+ */
+export const TOOL_DESCRIPTORS = [
+    {
+        name: 'jazzcash_list_integration_flows',
+        registrar: registerListIntegrationFlows,
+        group: 'knowledge',
+        requiresCredentials: false,
+    },
+    {
+        name: 'jazzcash_get_integration_flow',
+        registrar: registerGetIntegrationFlow,
+        group: 'knowledge',
+        requiresCredentials: false,
+    },
+    {
+        name: 'jazzcash_search_docs',
+        registrar: registerSearchDocs,
+        group: 'knowledge',
+        requiresCredentials: false,
+    },
+    {
+        name: 'jazzcash_get_doc_section',
+        registrar: registerGetDocSection,
+        group: 'knowledge',
+        requiresCredentials: false,
+    },
+    {
+        // The documented JazzCash code tables, keyed by JazzCash field names.
+        name: 'jazzcash_explain_response_code',
+        registrar: registerExplainResponseCode,
+        group: 'knowledge',
+        requiresCredentials: false,
+    },
+    {
+        // JazzCash portal steps, the evidence JazzCash asks for, and go-live checks
+        // written against `pp_` field names.
+        name: 'jazzcash_get_onboarding_checklist',
+        registrar: registerOnboardingChecklist,
+        group: 'knowledge',
+        requiresCredentials: false,
+    },
+    BUILD_TRANSACTION_PARAMETERS,
+    {
+        // `resolveIntegritySalt` prefers an explicitly supplied salt, so a caller
+        // debugging their own value never touches the credential store.
+        name: 'jazzcash_build_secure_hash',
+        registrar: registerBuildSecureHash,
+        group: 'hash',
+        requiresCredentials: false,
+    },
+    {
+        name: 'jazzcash_verify_secure_hash',
+        registrar: registerVerifySecureHash,
+        group: 'hash',
+        requiresCredentials: false,
+    },
+    {
+        // Reads the registered Return URL only when a profile exists
+        // (`deps.credentials.has`), and validates the payload either way.
+        name: 'jazzcash_validate_payload',
+        registrar: registerValidatePayload,
+        group: 'hash',
+        requiresCredentials: false,
+    },
+    {
+        name: 'jazzcash_generate_integration_code',
+        registrar: registerGenerateIntegrationCode,
+        group: 'codegen',
+        requiresCredentials: false,
+    },
+    {
+        // Generates from the flow specification, but defaults to a JazzCash flow and
+        // appends JazzCash portal registration steps to every result.
+        name: 'jazzcash_generate_ipn_handler',
+        registrar: registerGenerateIpnHandler,
+        group: 'codegen',
+        requiresCredentials: false,
+    },
+    SEND_GATEWAY_REQUEST,
+    RUN_SANDBOX_SMOKE_TEST,
+    BUILD_CHECKOUT_FORM,
+    {
+        // Takes its salt as a call argument, and only falls back to the configured
+        // profile when none is supplied. In the gateway group because it answers an
+        // inbound notification, not because it holds a credential.
+        name: 'jazzcash_verify_ipn_notification',
+        registrar: registerVerifyIpnNotification,
+        group: 'gateway',
+        requiresCredentials: false,
+    },
+    {
+        name: 'jazzcash_diagnose_integration_issue',
+        registrar: registerDiagnoseIntegrationIssue,
+        group: 'diagnostics',
+        requiresCredentials: false,
+    },
+];
+function registrarsInGroup(group) {
+    return TOOL_DESCRIPTORS.filter((descriptor) => descriptor.group === group).map((descriptor) => descriptor.registrar);
+}
+export const KNOWLEDGE_TOOLS = registrarsInGroup('knowledge');
+export const HASH_TOOLS = registrarsInGroup('hash');
+export const CODEGEN_TOOLS = registrarsInGroup('codegen');
+export const GATEWAY_TOOLS = registrarsInGroup('gateway');
+export const DIAGNOSTIC_TOOLS = registrarsInGroup('diagnostics');
+export const ALL_TOOLS = TOOL_DESCRIPTORS.map((descriptor) => descriptor.registrar);
+/** Tools that need no configured credential, and are safe to serve from a host that holds none. */
+export const CREDENTIAL_FREE_TOOLS = TOOL_DESCRIPTORS.filter((descriptor) => !descriptor.requiresCredentials);
+//# sourceMappingURL=register.js.map

package/dist/tools/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/tools/register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,+BAA+B,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AACjG,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAkC,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,gCAAgC,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC7G,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,0BAA0B,EAC1B,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAmBxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAMzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA8B;IACzD;QACE,IAAI,EAAE,iCAAiC;QACvC,SAAS,EAAE,4BAA4B;QACvC,KAAK,EAAE,WAAW;QAClB,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,IAAI,EAAE,+BAA+B;QACrC,SAAS,EAAE,0BAA0B;QACrC,KAAK,EAAE,WAAW;QAClB,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,IAAI,EAAE,sBAAsB;QAC5B,SAAS,EAAE,kBAAkB;QAC7B,KAAK,EAAE,WAAW;QAClB,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,IAAI,EAAE,0BAA0B;QAChC,SAAS,EAAE,qBAAqB;QAChC,KAAK,EAAE,WAAW;QAClB,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,sEAAsE;QACtE,IAAI,EAAE,gCAAgC;QACtC,SAAS,EAAE,2BAA2B;QACtC,KAAK,EAAE,WAAW;QAClB,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,4EAA4E;QAC5E,qCAAqC;QACrC,IAAI,EAAE,mCAAmC;QACzC,SAAS,EAAE,2BAA2B;QACtC,KAAK,EAAE,WAAW;QAClB,mBAAmB,EAAE,KAAK;KAC3B;IACD,4BAA4B;IAC5B;QACE,0EAA0E;QAC1E,gEAAgE;QAChE,IAAI,EAAE,4BAA4B;QAClC,SAAS,EAAE,uBAAuB;QAClC,KAAK,EAAE,MAAM;QACb,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,IAAI,EAAE,6BAA6B;QACnC,SAAS,EAAE,wBAAwB;QACnC,KAAK,EAAE,MAAM;QACb,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,6DAA6D;QAC7D,kEAAkE;QAClE,IAAI,EAAE,2BAA2B;QACjC,SAAS,EAAE,uBAAuB;QAClC,KAAK,EAAE,MAAM;QACb,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,IAAI,EAAE,oCAAoC;QAC1C,SAAS,EAAE,+BAA+B;QAC1C,KAAK,EAAE,SAAS;QAChB,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,6EAA6E;QAC7E,8DAA8D;QAC9D,IAAI,EAAE,+BAA+B;QACrC,SAAS,EAAE,0BAA0B;QACrC,KAAK,EAAE,SAAS;QAChB,mBAAmB,EAAE,KAAK;KAC3B;IACD,oBAAoB;IACpB,sBAAsB;IACtB,mBAAmB;IACnB;QACE,2EAA2E;QAC3E,4EAA4E;QAC5E,2DAA2D;QAC3D,IAAI,EAAE,kCAAkC;QACxC,SAAS,EAAE,6BAA6B;QACxC,KAAK,EAAE,SAAS;QAChB,mBAAmB,EAAE,KAAK;KAC3B;IACD;QACE,IAAI,EAAE,qCAAqC;QAC3C,SAAS,EAAE,gCAAgC;QAC3C,KAAK,EAAE,aAAa;QACpB,mBAAmB,EAAE,KAAK;KAC3B;CACF,CAAC;AAEF,SAAS,iBAAiB,CAAC,KAAgB;IACzC,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AACvH,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAyB,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAEpF,MAAM,CAAC,MAAM,UAAU,GAAyB,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAE1E,MAAM,CAAC,MAAM,aAAa,GAAyB,iBAAiB,CAAC,SAAS,CAAC,CAAC;AAEhF,MAAM,CAAC,MAAM,aAAa,GAAyB,iBAAiB,CAAC,SAAS,CAAC,CAAC;AAEhF,MAAM,CAAC,MAAM,gBAAgB,GAAyB,iBAAiB,CAAC,aAAa,CAAC,CAAC;AAEvF,MAAM,CAAC,MAAM,SAAS,GAAyB,gBAAgB,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AAE1G,mGAAmG;AACnG,MAAM,CAAC,MAAM,qBAAqB,GAA8B,gBAAgB,CAAC,MAAM,CACrF,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,mBAAmB,CAChD,CAAC"}

package/dist/tools/tool-kit.d.ts

@@ -0,0 +1,88 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { JazzCashEnvironment } from '../config/environment.js';
+import type { CoreDependencies } from '../core/dependencies.js';
+import type { CallContext } from './call-context.js';
+/**
+ * Shared plumbing for tool handlers.
+ *
+ * Three invariants are enforced here rather than repeated in every tool:
+ *
+ *  - A thrown error becomes an `isError` result rather than escaping across the
+ *    protocol boundary, so a merchant sees an explanation instead of a
+ *    transport-level failure.
+ *  - Every string a tool returns is scrubbed of known credential literals and of
+ *    the values of known credential fields. A tool result is transcript content;
+ *    a password that reaches it is disclosed. Text and `structuredContent` are
+ *    scrubbed to the same policy, so no tool can leak through one by embedding a
+ *    payload in the other.
+ *  - Every call is given a {@link CallContext}, so a log record can be traced to
+ *    the call that produced it rather than only to the server as a whole.
+ *
+ * A fourth rule lives here and the wrapper applies it for every tool that
+ * declares which of its arguments carry caller-chosen field names: a parameter
+ * the flow marks `neverAcceptAsToolArgument` is refused before the handler runs.
+ * See {@link PayloadArgumentDeclaration} for why the declaration has to be
+ * written down rather than inferred.
+ */
+export interface ToolTextOptions {
+    readonly structuredContent?: Record<string, unknown>;
+    readonly isError?: boolean;
+}
+/** Build a tool result carrying both human-readable text and structured data. */
+export declare function toolResult(text: string, options?: ToolTextOptions): CallToolResult;
+/** Build a failure result, naming the stable error code when there is one. */
+export declare function toolError(error: unknown, secrets?: readonly string[]): CallToolResult;
+/**
+ * Which of a tool's arguments carry field names the caller chooses.
+ *
+ * Declared at registration rather than restated as a branch in the handler
+ * body. The wrapper is generic over `Args` and so cannot work the names out for
+ * itself — a check that guessed would miss a key it had not been told about and
+ * accept a PAN in silence — but a tool that names them turns that guess into a
+ * statement, and a tool that names none is opting out visibly rather than by
+ * forgetting a line. `flowFrom` names the argument holding the flow id, which
+ * chooses the explanatory sentence only; the list of refused names is the
+ * catalogue-wide union either way.
+ */
+export interface PayloadArgumentDeclaration<Args> {
+    /** Arguments whose keys are the caller's, e.g. `extras`, `parameters`. */
+    readonly payloadArguments: readonly (keyof Args & string)[];
+    /** Argument naming the flow, for tools that take one. */
+    readonly flowFrom?: keyof Args & string;
+}
+/**
+ * Wrap a handler so failures surface as tool errors and secrets never leak.
+ *
+ * Redaction covers every configured profile, not only the one in play, because a
+ * caller can pass an explicit salt for one environment while another is active.
+ *
+ * The handler receives a {@link CallContext} built for this invocation. It is
+ * built from `deps` rather than from the SDK's `extra` argument, and the second
+ * parameter below is the reason that distinction has to be written down.
+ *
+ * A `declaration` makes the wrapper refuse forbidden arguments before the
+ * handler runs at all, so the flagged value is never read, built into a payload
+ * or written to a log. The refusal is returned through the same scrubbing path
+ * as any other result.
+ */
+export declare function safeHandler<Args>(deps: CoreDependencies, toolName: string, handler: (args: Args, context: CallContext) => CallToolResult | Promise<CallToolResult>, declaration?: PayloadArgumentDeclaration<Args>): (args: Args, extra?: unknown) => Promise<CallToolResult>;
+/** Resolve the environment a tool should act in, defaulting to the configured one. */
+export declare function resolveEnvironment(deps: CoreDependencies, requested: JazzCashEnvironment | undefined): JazzCashEnvironment;
+/**
+ * Resolve the Integrity Salt for a hash operation.
+ *
+ * An explicit salt is accepted because a merchant debugging a mismatch usually
+ * has the value in front of them and may not have configured the server yet.
+ */
+export declare function resolveIntegritySalt(deps: CoreDependencies, explicitSalt: string | undefined, environment: JazzCashEnvironment): {
+    salt: string;
+    source: string;
+};
+/** Render a bullet list, or a placeholder when there is nothing to list. */
+export declare function bulletList(items: readonly string[], empty?: string): string;
+/** Render a citation line for a set of documentation references. */
+export declare function citations(refs: readonly {
+    docId: string;
+    sectionId?: string | undefined;
+}[]): string;
+//# sourceMappingURL=tool-kit.d.ts.map

package/dist/tools/tool-kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-kit.d.ts","sourceRoot":"","sources":["../../src/tools/tool-kit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAKzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CAMtF;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,SAAS,MAAM,EAAO,GAAG,cAAc,CAQzF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,0BAA0B,CAAC,IAAI;IAC9C,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC;IAC5D,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,MAAM,CAAC;CACzC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAC9B,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,KAAK,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACvF,WAAW,CAAC,EAAE,0BAA0B,CAAC,IAAI,CAAC,GAC7C,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CA4C1D;AAkOD,sFAAsF;AACtF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,mBAAmB,GAAG,SAAS,GACzC,mBAAmB,CAErB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,WAAW,EAAE,mBAAmB,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAMlC;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,SAAW,GAAG,MAAM,CAE7E;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAAE,GAAG,MAAM,CAUpG"}