@palpluss/mcp 0.0.0-stage → 0.2.0

package/dist/tools/guide.js

@@ -0,0 +1,146 @@
+/**
+ * Static integration guidance served to coding assistants. Kept short and
+ * factual; the full reference is docs.palpluss.com.
+ */
+export const GUIDE_TOPICS = [
+    'overview',
+    'stk-push',
+    'webhooks',
+    'b2c-payouts',
+    'channels',
+    'wallets',
+    'payment-links',
+    'test-mode',
+    'mcp-keys',
+    'errors',
+    'go-live',
+];
+const BASE = 'https://api.palpluss.com/v1';
+const TOPICS = {
+    overview: `# PalPluss — overview
+PalPluss is an M-Pesa payments API for Kenya: collect with STK Push, pay out with B2C, and manage the Paybills/Tills money is collected into.
+
+- Base URL: ${BASE}
+- Auth: \`Authorization: Basic <API key>\` (keys from console.palpluss.com → API Keys). Server-side only — never ship a key to a browser or mobile app.
+- Responses: \`{ success: true, data, requestId }\`; errors \`{ success: false, error: { code, message, details } }\`. \`error.code\` is \`HTTP_<status>\`; the specific reason (e.g. \`KYC_NOT_VERIFIED\`) is in \`error.details.code\` when there is one.
+- Phones: send 07XXXXXXXX, 01XXXXXXXX, +254… or 254…; PalPluss normalises to 254XXXXXXXXX.
+- Amounts: whole Kenyan shillings.
+- Two wallets: the **service wallet** pays PalPluss fees (STK Push is a flat KES 3 for KES 10 and above; KES 1–9 is free); the **B2C wallet** is the float payouts are sent from.
+- Docs: https://docs.palpluss.com`,
+    'stk-push': `# STK Push (collect a payment)
+POST ${BASE}/payments/stk
+\`\`\`json
+{ "amount": 500, "phone": "0712345678", "accountReference": "ORDER-1042",
+  "transactionDesc": "Order 1042", "callbackUrl": "https://yourapp.com/webhooks/palpluss" }
+\`\`\`
+- Optional \`channelId\` picks the Paybill/Till; otherwise the default channel is used.
+- Keep \`accountReference\` ≤ 12 and \`transactionDesc\` ≤ 13 characters (shown on the M-Pesa prompt).
+- The response is immediate with \`status: "PENDING"\` and a \`transactionId\` — store it against your order.
+- The result arrives by webhook (see "webhooks") or by polling GET ${BASE}/transactions/{id}.
+- Compute the amount on your server from the order. Never trust an amount sent by the browser.
+- Limits: 2 STK requests per phone number per minute (429 STK_RATE_LIMITED); 60 requests per minute per API key; if fewer than 30% of the last 100 STK payments succeed, STK is paused for 30 minutes (429 TRANSACTION_HEALTH_BLOCKED).
+- To collect straight into a bank account, add the bank's Paybill and your account number as a PAYBILL channel.`,
+    webhooks: `# Webhooks
+PalPluss POSTs to your \`callbackUrl\` when a transaction reaches a final state:
+\`\`\`json
+{ "event": "transaction.updated", "event_type": "transaction.success",
+  "transaction": { "id": "…", "type": "STK", "status": "SUCCESS", "amount": 1000,
+    "external_reference": "ORDER-1042", "mpesa_receipt": "NLJ7RT61SV", "result_desc": "…" } }
+\`\`\`
+- Fulfil only when \`status\` is SUCCESS. \`external_reference\` is your accountReference/reference.
+- Make the handler idempotent (key on transaction.id) — a callback can arrive more than once.
+- Don't trust the body alone: re-fetch GET ${BASE}/transactions/{id} with your API key before fulfilling.
+- Respond 2xx quickly; do slow work after acknowledging.
+- Store \`mpesa_receipt\` for reconciliation.`,
+    'b2c-payouts': `# B2C payouts (send money to an M-Pesa number)
+POST ${BASE}/b2c/payouts  (header \`Idempotency-Key\` strongly recommended)
+\`\`\`json
+{ "amount": 500, "phone": "0712345678", "reference": "PAYOUT-1001",
+  "description": "Partner payout", "callbackUrl": "https://yourapp.com/webhooks/palpluss" }
+\`\`\`
+- Requires an ACTIVE account with APPROVED KYC (403 otherwise).
+- Minimum KES 10. Paid from the B2C wallet — top it up first (POST ${BASE}/wallets/b2c/topups).
+- Fees are tiered by amount (from KES 6) and charged from the service wallet.
+- The response returns \`status: "PROCESSING"\`; the final SUCCESS/FAILED arrives by webhook. A FAILED payout is refunded to the B2C wallet automatically.
+- Use one Idempotency-Key per intended payout so retries never pay twice.
+- Limit: 1 payout per phone number per minute (429, details.code \`B2C_PAYOUT_COOLDOWN\`). Not enough float: details.code \`INSUFFICIENT_FUNDS\`.`,
+    channels: `# Payment channels
+Channels are the Paybills and Tills customer money is collected into.
+- List: GET ${BASE}/payment-wallet/channels (default first)
+- Create: POST ${BASE}/payment-wallet/channels
+\`\`\`json
+{ "name": "Main Paybill", "type": "PAYBILL", "shortcode": "247247", "accountNumber": "0123456789", "isDefault": true }
+\`\`\`
+- Types: PAYBILL (with the accountNumber customers pay into), TILL, SHORTCODE.
+- The same Paybill can be added more than once with different account numbers (e.g. several bank accounts).
+- Update: PATCH …/channels/{id}; Delete: DELETE …/channels/{id} (soft delete; the default moves to another channel).
+- Changing channels changes where future payments land — treat it as sensitive.`,
+    wallets: `# Wallets
+- Service wallet (fees): GET ${BASE}/wallets/service/balance; top up with POST ${BASE}/wallets/service/topups.
+- B2C wallet (payout float): GET ${BASE}/wallets/b2c/balance; top up with POST ${BASE}/wallets/b2c/topups.
+- Top-ups are STK pushes to the phone that pays; the wallet is credited once M-Pesa confirms.
+- Send an \`Idempotency-Key\` header so a retried top-up isn't charged twice.
+- Requests fail with 402 INSUFFICIENT_SERVICE_BALANCE when the service wallet can't cover a fee.
+- Limit: 2 top-ups per phone number per minute.
+- History: GET ${BASE}/wallets/history?wallet=service|b2c&category=charge|topup|refund|payout — every entry with the balance after it.
+- Fees: GET ${BASE}/fees/estimate?service=STK|B2C&amount=500 returns what this account's plan charges.`,
+    'payment-links': `# Payment links
+A payment link is a hosted page where the customer enters their number and pays by STK Push — no checkout code needed.
+- Create: POST ${BASE}/payment-links
+\`\`\`json
+{ "amount": 1500, "external_reference": "INV-2041", "customer_name": "Jane", "expiry": "72h",
+  "callbackUrl": "https://yourapp.com/webhooks/palpluss" }
+\`\`\`
+- Omit \`amount\` to let the customer type it. \`phone_number\` pre-fills their number; \`channel_id\` picks the Paybill/Till (default channel otherwise).
+- \`expiry\`: 1h, 6h, 24h, 72h, 168h, 720h or never (default).
+- The response has \`url\` — share it. Payments appear as STK transactions and fire your callback like any STK push.
+- List: GET ${BASE}/payment-links; one: GET ${BASE}/payment-links/{id}; disable: DELETE ${BASE}/payment-links/{id}.`,
+    'test-mode': `# Test mode
+Create a **test** key in the console (API Keys → mode: Test). Test keys use the same endpoints and response shapes with simulated money:
+- Nothing reaches M-Pesa. Every response and callback has \`livemode: false\`.
+- Each account gets test wallets with KES 10,000 in the service wallet and KES 10,000 in the B2C wallet.
+- STK pushes, payouts and top-ups settle about 5 seconds later and send your callback.
+- How it ends depends on the phone number: 0700000001 → FAILED (insufficient balance), 0700000002 → CANCELLED (customer cancelled), 0700000003 → FAILED (customer unreachable), any other valid number → SUCCESS.
+- Payouts work without KYC in test mode. Fees follow your real pricing plan.
+- Payment channels and payment links are live settings: test keys can read them but not change them (403 NOT_AVAILABLE_IN_TEST_MODE).
+- A key can be switched between test and live in the console (API Keys → Edit); it applies from the next request and the key string stays the same. Check GET ${BASE}/api-key for the current mode.`,
+    'mcp-keys': `# MCP keys (for AI tools)
+In the console (API Keys) choose **MCP** as the key type to give an AI tool limited access:
+- Permissions: only what you tick works — transactions:read, wallets:read, wallets:topup, payments:stk, paylinks:read, paylinks:write, channels:read, channels:write, payouts:write. Anything else returns 403 INSUFFICIENT_SCOPE.
+- Payout limits enforced by PalPluss: per payout, per day (total and count, Nairobi time) and an optional allowlist of numbers.
+- Approvals: payouts and channel changes can be held until you approve them in the console. The API then answers 202 with \`status: "PENDING_APPROVAL"\` and an \`approvalId\`; follow it with GET ${BASE}/approvals/{id} (EXECUTED, REJECTED, EXPIRED or FAILED). Requests expire after 15 minutes.
+- Optional expiry date and IP allowlist (exact IPs or CIDR ranges).
+- GET ${BASE}/api-key shows the key's kind, mode, permissions, limits and today's payout usage.
+- Standard keys keep full access and none of these limits.`,
+    errors: `# Common errors
+Error responses carry \`error.code\` as \`HTTP_<status>\`; read \`error.details.code\` for the specific reason.
+| HTTP | details.code | Meaning | What to do |
+|---|---|---|---|
+| 401 | INVALID_API_KEY / AUTH_HEADER_INVALID | Key missing or wrong | Send \`Authorization: Basic <key>\` |
+| 400 | INVALID_PHONE | Not a Kenyan mobile number | Validate before calling |
+| 400 | NO_PAYMENT_CHANNELS / NO_DEFAULT_CHANNEL | No channel to collect into | Add one, or set a default |
+| 402 | INSUFFICIENT_SERVICE_BALANCE | Can't cover the fee | Top up the service wallet |
+| 403 | KYC_NOT_VERIFIED | Payouts need approved KYC | Finish KYC in the console |
+| 401 | API_KEY_EXPIRED | The key's expiry date passed | Create a new key |
+| 403 | INSUFFICIENT_SCOPE | MCP key lacks that permission | Grant it in the console |
+| 403 | IP_NOT_ALLOWED | Request from an IP not on the key's allowlist | Update the allowlist |
+| 403 | NOT_AVAILABLE_IN_TEST_MODE | Test key on a live-only endpoint | Use a live key |
+| 403 | PAYOUT_ABOVE_KEY_LIMIT / PAYOUT_DAILY_TOTAL_REACHED / PAYOUT_DAILY_COUNT_REACHED / PAYOUT_RECIPIENT_NOT_ALLOWED | MCP key payout limits | Change them in the console |
+| 429 | STK_RATE_LIMITED / WALLET_TOPUP_RATE_LIMITED | >2 prompts per minute to one number | Wait error.details.details.retryAfterSeconds |
+| 429 | B2C_PAYOUT_COOLDOWN | >1 payout per minute to one number | Wait a minute |
+| 429 | TRANSACTION_HEALTH_BLOCKED | Too many failed prompts recently | Wait until error.details.details.blockedUntil |
+| 429 | RATE_LIMIT_EXCEEDED | API key over 60 requests per minute | Slow down |
+`,
+    'go-live': `# Go-live checklist
+1. API key stored server-side only (environment variable / secret manager).
+2. Amounts computed on the server from your own records.
+3. Webhook handler idempotent, re-fetches the transaction, fulfils only on SUCCESS.
+4. Store transactionId and mpesa_receipt for every payment.
+5. Handle 429s (rate limits, transaction health) with a friendly "try again shortly".
+6. Keep the service wallet funded; alert when it runs low.
+7. For payouts: Idempotency-Key per payout, KYC approved, B2C wallet funded.
+8. Make one real small payment end to end before launch.`,
+};
+export function guide(topic) {
+    return `${TOPICS[topic]}\n\n(Full reference: https://docs.palpluss.com)`;
+}

package/dist/tools/money.d.ts

@@ -0,0 +1,13 @@
+import { type ToolContext } from './common.js';
+/** Wallet top-ups: STK push to the payer's own phone, credited once M-Pesa confirms. */
+export declare function registerWalletTools(ctx: ToolContext): void;
+/** Collections: STK push to a customer, and waiting for the result. */
+export declare function registerCollectTools(ctx: ToolContext): void;
+/** B2C payouts — the strictest tool: limits, allowlist, approval, idempotency. */
+export declare function registerPayoutTools(ctx: ToolContext): void;
+/** Payment channels — every change needs approval: channels decide where money lands. */
+export declare function registerChannelTools(ctx: ToolContext): void;
+/** Payment links: hosted pages where a customer enters their number and pays. Live keys only. */
+export declare function registerPaymentLinkTools(ctx: ToolContext): void;
+/** Follow a request PalPluss is holding for the merchant's approval. */
+export declare function registerApprovalTools(ctx: ToolContext): void;

package/dist/tools/money.js

@@ -0,0 +1,360 @@
+import { z } from 'zod';
+import { assertAmount, guarded, idempotencyKey, kes, ok, okOrPending, requireApproval, requirePhone, ToolRefusal, } from './common.js';
+import { maskPhone } from '../safety/redact.js';
+const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+const FINAL = new Set(['SUCCESS', 'FAILED', 'CANCELLED', 'REVERSED']);
+const amountSchema = z.number().int().positive().describe('Whole Kenyan shillings.');
+const phoneSchema = z.string().min(9).max(16).describe('Kenyan mobile number: 07XXXXXXXX, 01XXXXXXXX or 2547XXXXXXXX.');
+const callbackSchema = z.string().url().max(500).optional().describe('HTTPS URL PalPluss POSTs the final result to.');
+/** Wallet top-ups: STK push to the payer's own phone, credited once M-Pesa confirms. */
+export function registerWalletTools(ctx) {
+    const { server, client, config } = ctx;
+    for (const wallet of ['service', 'b2c']) {
+        const name = wallet === 'service' ? 'palpluss_topup_service_wallet' : 'palpluss_topup_b2c_wallet';
+        const label = wallet === 'service' ? 'service wallet (fees)' : 'B2C wallet (payout float)';
+        server.registerTool(name, {
+            title: wallet === 'service' ? 'Top up service wallet' : 'Top up B2C wallet',
+            description: wallet === 'service'
+                ? 'Top up the service wallet, which pays PalPluss fees. Sends an M-Pesa PIN prompt to the given phone; the wallet is credited once it is paid. Needs the person\'s approval first.'
+                : 'Top up the B2C wallet, the float payouts are sent from. Sends an M-Pesa PIN prompt to the given phone; the wallet is credited once it is paid. Needs the person\'s approval first.',
+            inputSchema: {
+                amount: amountSchema,
+                phone: phoneSchema.describe('The phone that will pay (gets the PIN prompt).'),
+                reference: z.string().max(12).optional().describe('Your reference, ≤12 chars. Use a new one for each separate top-up.'),
+                callbackUrl: callbackSchema,
+            },
+            annotations: { title: `Top up ${label}`, ...WRITE },
+        }, guarded(ctx, name, async ({ amount, phone, reference, callbackUrl }) => {
+            assertAmount(amount, { min: 1, max: config.limits.maxTopup, label: 'Top-up' });
+            const msisdn = requirePhone(phone);
+            const approval = await requireApproval(ctx, {
+                action: `${wallet}_wallet_topup`,
+                title: `Top up the ${label} with ${kes(amount)}`,
+                details: { Amount: kes(amount), 'PIN prompt goes to': maskPhone(msisdn) ?? '', Wallet: label },
+                consequence: `An M-Pesa prompt for ${kes(amount)} will be sent to ${maskPhone(msisdn)}. The wallet is credited only after that phone pays.`,
+            }, 'topup');
+            const body = {
+                amount,
+                phone: msisdn,
+                accountReference: reference ?? (wallet === 'service' ? 'MCP-TOPUP' : 'MCP-B2CTOP'),
+                transactionDesc: wallet === 'service' ? 'Service topup' : 'B2C topup',
+                ...(callbackUrl ? { callbackUrl } : {}),
+            };
+            const key = idempotencyKey(config.apiKey, [`topup-${wallet}`, amount, msisdn], reference);
+            const res = wallet === 'service' ? await client.topupServiceWallet(body, key) : await client.topupB2cWallet(body, key);
+            return ok(res, {
+                note: `Cleared (${approval}). The PIN prompt was sent.`,
+                next: 'Use palpluss_get_transaction with the transactionId to see when it is paid, then palpluss_get_wallet_balances.',
+            });
+        }));
+    }
+}
+/** Collections: STK push to a customer, and waiting for the result. */
+export function registerCollectTools(ctx) {
+    const { server, client, config } = ctx;
+    server.registerTool('palpluss_send_stk_push', {
+        title: 'Send an STK push',
+        description: 'Ask a customer to pay by sending an M-Pesa PIN prompt to their phone. Money goes to the default payment channel unless channelId is given. Needs the person\'s approval first. Returns a PENDING transaction — follow it with palpluss_wait_for_payment.',
+        inputSchema: {
+            amount: amountSchema,
+            phone: phoneSchema.describe('The customer\'s phone (gets the PIN prompt).'),
+            accountReference: z.string().max(12).optional().describe('Your order/invoice reference, ≤12 chars.'),
+            description: z.string().max(13).optional().describe('Shown on the prompt, ≤13 chars.'),
+            channelId: z.string().uuid().optional().describe('Payment channel to collect into (default channel if omitted).'),
+            callbackUrl: callbackSchema,
+        },
+        annotations: { title: 'Send an STK push', ...WRITE },
+    }, guarded(ctx, 'palpluss_send_stk_push', async ({ amount, phone, accountReference, description, channelId, callbackUrl }) => {
+        assertAmount(amount, { min: 1, max: config.limits.maxStk, label: 'STK push' });
+        const msisdn = requirePhone(phone);
+        let channelLabel = channelId ? `Channel ${channelId}` : 'Default channel';
+        if (channelId) {
+            try {
+                const ch = (await client.getChannel(channelId));
+                channelLabel = `${ch.name ?? 'Channel'} (${ch.shortcode ?? '?'})`;
+            }
+            catch {
+                // The key may not be allowed to read channels; the ID is enough for the prompt.
+            }
+        }
+        const approval = await requireApproval(ctx, {
+            action: 'stk_push',
+            title: `Request ${kes(amount)} from ${maskPhone(msisdn)}`,
+            details: {
+                Amount: kes(amount),
+                'Customer phone': maskPhone(msisdn) ?? '',
+                'Collect into': channelLabel,
+                ...(accountReference ? { Reference: accountReference } : {}),
+            },
+            consequence: `The customer at ${maskPhone(msisdn)} gets an M-Pesa prompt to pay ${kes(amount)}.`,
+        }, 'collect');
+        const res = await client.stkPush({
+            amount,
+            phone: msisdn,
+            ...(accountReference ? { accountReference } : {}),
+            ...(description ? { transactionDesc: description } : {}),
+            ...(channelId ? { channelId } : {}),
+            ...(callbackUrl ? { callbackUrl } : {}),
+        });
+        return ok(res, {
+            note: `Cleared (${approval}). The prompt was sent; the customer has about a minute to enter their PIN.`,
+            next: 'Call palpluss_wait_for_payment with the transactionId.',
+        });
+    }));
+    server.registerTool('palpluss_wait_for_payment', {
+        title: 'Wait for a payment result',
+        description: 'Wait (up to 90 seconds) for an STK push, top-up or payout to reach a final status — SUCCESS, FAILED, CANCELLED or REVERSED — then return it. Returns the current status if it is still pending when time runs out.',
+        inputSchema: {
+            transactionId: z.string().uuid(),
+            timeoutSeconds: z.number().int().min(5).max(90).optional().describe('How long to wait (default 60).'),
+        },
+        annotations: { title: 'Wait for a payment result', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guarded(ctx, 'palpluss_wait_for_payment', async ({ transactionId, timeoutSeconds }) => {
+        const deadline = Date.now() + (timeoutSeconds ?? 60) * 1000;
+        let tx = (await client.getTransaction(transactionId));
+        while (!FINAL.has(String(tx.status)) && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 3000));
+            tx = (await client.getTransaction(transactionId));
+        }
+        const final = FINAL.has(String(tx.status));
+        return ok(tx, {
+            note: final ? `Final status: ${tx.status}.` : `Still ${tx.status ?? 'pending'} — check again shortly.`,
+        });
+    }));
+}
+/** B2C payouts — the strictest tool: limits, allowlist, approval, idempotency. */
+export function registerPayoutTools(ctx) {
+    const { server, client, config, limiter } = ctx;
+    server.registerTool('palpluss_send_payout', {
+        title: 'Send a B2C payout',
+        description: 'Send money from the B2C wallet to an M-Pesa number (refunds, commissions, salaries). Needs the person\'s approval and is capped by this server\'s payout limits — check palpluss_get_guardrails first. Give each separate payout its own reference; repeating the same request with the same reference never pays twice.',
+        inputSchema: {
+            amount: amountSchema.describe('Whole Kenyan shillings, minimum 10.'),
+            phone: phoneSchema.describe('The recipient\'s M-Pesa number.'),
+            reference: z.string().max(120).optional().describe('Unique reference for this payout (recommended).'),
+            description: z.string().max(255).optional().describe('What the payout is for.'),
+            channelId: z.string().uuid().optional(),
+            callbackUrl: callbackSchema,
+        },
+        annotations: { title: 'Send a B2C payout', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, guarded(ctx, 'palpluss_send_payout', async ({ amount, phone, reference, description, channelId, callbackUrl }) => {
+        assertAmount(amount, { min: 10, max: Math.max(10, config.limits.maxPayout), label: 'Payout' });
+        const msisdn = requirePhone(phone);
+        limiter.check(amount, msisdn); // fail fast before bothering the person
+        const left = limiter.remaining();
+        const approval = await requireApproval(ctx, {
+            action: 'b2c_payout',
+            title: `Send ${kes(amount)} to ${maskPhone(msisdn)}`,
+            details: {
+                Amount: kes(amount),
+                Recipient: maskPhone(msisdn) ?? '',
+                ...(reference ? { Reference: reference } : {}),
+                ...(description ? { For: description } : {}),
+                'Left today after this': `${kes(Math.max(0, left.remainingTotal - amount))} · ${Math.max(0, left.remainingCount - 1)} payouts`,
+            },
+            consequence: `${kes(amount)} will leave your B2C wallet and be sent to ${maskPhone(msisdn)}. This can't be undone once M-Pesa pays it.`,
+        }, 'payout');
+        const release = limiter.reserve(amount, msisdn); // re-checks: limits may have moved while waiting
+        try {
+            const res = await client.b2cPayout({
+                amount,
+                phone: msisdn,
+                currency: 'KES',
+                ...(reference ? { reference } : {}),
+                ...(description ? { description } : {}),
+                ...(channelId ? { channelId } : {}),
+                ...(callbackUrl ? { callbackUrl } : {}),
+            }, idempotencyKey(config.apiKey, ['payout', amount, msisdn], reference));
+            const status = String(res.status ?? '');
+            if (status === 'FAILED')
+                release();
+            return okOrPending(res, {
+                note: `Cleared (${approval}). Payout submitted with status ${status || 'unknown'}.`,
+                next: 'Call palpluss_wait_for_payment with the transactionId to confirm it was paid.',
+            });
+        }
+        catch (err) {
+            release();
+            throw err;
+        }
+    }));
+}
+/** Payment channels — every change needs approval: channels decide where money lands. */
+export function registerChannelTools(ctx) {
+    const { server, client } = ctx;
+    const CHANNEL_TYPES = ['PAYBILL', 'TILL', 'SHORTCODE'];
+    const describe = (c) => `${c.name ?? 'Unnamed'} — ${c.type ?? '?'} ${c.shortcode ?? '?'}${c.accountNumber ? ` / account ${c.accountNumber}` : ''}`;
+    server.registerTool('palpluss_create_payment_channel', {
+        title: 'Add a payment channel',
+        description: 'Add a Paybill or Till that customer payments can be collected into. For a bank account, use the bank\'s M-Pesa Paybill as shortcode and the bank account number as accountNumber. Needs the person\'s approval.',
+        inputSchema: {
+            name: z.string().min(1).max(80),
+            type: z.enum(CHANNEL_TYPES).describe('PAYBILL needs accountNumber; TILL and SHORTCODE must not have one.'),
+            shortcode: z.string().regex(/^\d{4,10}$/).describe('The Paybill or Till number.'),
+            accountNumber: z.string().min(1).max(30).optional(),
+            makeDefault: z.boolean().optional().describe('Make this the channel STK pushes use by default.'),
+        },
+        annotations: { title: 'Add a payment channel', ...WRITE },
+    }, guarded(ctx, 'palpluss_create_payment_channel', async ({ name, type, shortcode, accountNumber, makeDefault }) => {
+        if (type === 'PAYBILL' && !accountNumber)
+            throw new ToolRefusal('A PAYBILL channel needs an accountNumber.', 'ACCOUNT_NUMBER_REQUIRED');
+        if (type !== 'PAYBILL' && accountNumber)
+            throw new ToolRefusal(`A ${type} channel must not have an accountNumber.`, 'ACCOUNT_NUMBER_NOT_ALLOWED');
+        const approval = await requireApproval(ctx, {
+            action: 'channel_create',
+            title: `Add payment channel "${name}"`,
+            details: {
+                Channel: describe({ name, type, shortcode, accountNumber }),
+                'Make default': makeDefault ? 'Yes — new STK payments will go here' : 'No',
+            },
+            consequence: makeDefault
+                ? `Customer payments will start going to ${type} ${shortcode}${accountNumber ? ` (account ${accountNumber})` : ''}. Check the numbers carefully.`
+                : `The channel is added but not used by default.`,
+        }, 'channel');
+        const res = await client.createChannel({ name, type, shortcode, ...(accountNumber ? { accountNumber } : {}), isDefault: !!makeDefault });
+        return okOrPending(res, { note: `Cleared (${approval}). Channel added.` });
+    }));
+    server.registerTool('palpluss_update_payment_channel', {
+        title: 'Edit a payment channel',
+        description: 'Rename a channel or change its number or account number. Needs the person\'s approval.',
+        inputSchema: {
+            channelId: z.string().uuid(),
+            name: z.string().min(1).max(80).optional(),
+            type: z.enum(CHANNEL_TYPES).optional(),
+            shortcode: z.string().regex(/^\d{4,10}$/).optional(),
+            accountNumber: z.string().min(1).max(30).nullable().optional(),
+        },
+        annotations: { title: 'Edit a payment channel', ...WRITE, idempotentHint: true },
+    }, guarded(ctx, 'palpluss_update_payment_channel', async ({ channelId, ...changes }) => {
+        const patch = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined));
+        if (!Object.keys(patch).length)
+            throw new ToolRefusal('Nothing to change — pass at least one field.', 'NO_CHANGES');
+        const current = (await client.getChannel(channelId));
+        const next = { ...current, ...patch };
+        const approval = await requireApproval(ctx, {
+            action: 'channel_update',
+            title: `Change payment channel "${String(current.name ?? channelId)}"`,
+            details: { Now: describe(current), 'After the change': describe(next), Default: current.isDefault ? 'Yes' : 'No' },
+            consequence: current.isDefault
+                ? 'This is your default channel: new customer payments will go to the changed number.'
+                : 'Payments that use this channel will go to the changed number.',
+        }, 'channel');
+        const res = await client.updateChannel(channelId, patch);
+        return okOrPending(res, { note: `Cleared (${approval}). Channel updated.` });
+    }));
+    server.registerTool('palpluss_set_default_payment_channel', {
+        title: 'Set the default payment channel',
+        description: 'Make a channel the default — STK pushes without a channelId collect into it. Needs the person\'s approval.',
+        inputSchema: { channelId: z.string().uuid() },
+        annotations: { title: 'Set the default payment channel', ...WRITE, idempotentHint: true },
+    }, guarded(ctx, 'palpluss_set_default_payment_channel', async ({ channelId }) => {
+        const target = (await client.getChannel(channelId));
+        if (target.isDefault)
+            return ok(target, { note: 'Already the default channel. Nothing changed.' });
+        const list = (await client.listChannels());
+        const currentDefault = list.items?.find((c) => c.isDefault);
+        const approval = await requireApproval(ctx, {
+            action: 'channel_set_default',
+            title: `Make "${String(target.name ?? channelId)}" the default channel`,
+            details: {
+                'New default': describe(target),
+                'Current default': currentDefault ? describe(currentDefault) : 'None',
+            },
+            consequence: 'All new STK payments without a specific channel will go to the new default.',
+        }, 'channel');
+        const res = await client.updateChannel(channelId, { isDefault: true });
+        return okOrPending(res, { note: `Cleared (${approval}). Default channel changed.` });
+    }));
+    server.registerTool('palpluss_delete_payment_channel', {
+        title: 'Remove a payment channel',
+        description: 'Remove a payment channel. Past transactions keep their record; if it was the default, another channel becomes the default. Needs the person\'s approval.',
+        inputSchema: { channelId: z.string().uuid() },
+        annotations: { title: 'Remove a payment channel', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, guarded(ctx, 'palpluss_delete_payment_channel', async ({ channelId }) => {
+        const current = (await client.getChannel(channelId));
+        const approval = await requireApproval(ctx, {
+            action: 'channel_delete',
+            title: `Remove payment channel "${String(current.name ?? channelId)}"`,
+            details: { Channel: describe(current), Default: current.isDefault ? 'Yes — another channel will become the default' : 'No' },
+            consequence: 'The channel can no longer be used for payments.',
+        }, 'channel');
+        const res = await client.deleteChannel(channelId);
+        return okOrPending(res ?? { deleted: true, channelId }, { note: `Cleared (${approval}). Channel removed.` });
+    }));
+}
+/** Payment links: hosted pages where a customer enters their number and pays. Live keys only. */
+export function registerPaymentLinkTools(ctx) {
+    const { server, client } = ctx;
+    server.registerTool('palpluss_create_payment_link', {
+        title: 'Create a payment link',
+        description: 'Create a PalPluss payment link — a page the customer opens to pay by M-Pesa. Fix the amount or let the customer type it; optionally pre-fill their phone. Nothing is charged until a customer pays. Returns the link URL to share. Needs a live key.',
+        inputSchema: {
+            amount: amountSchema.optional().describe('Fixed amount in whole shillings. Omit to let the customer enter it.'),
+            phone: phoneSchema.optional().describe('Pre-fill the customer\'s phone (optional).'),
+            customerName: z.string().max(120).optional(),
+            reference: z.string().max(120).optional().describe('Your order/invoice reference.'),
+            channelId: z.string().uuid().optional().describe('Payment channel to collect into (default channel if omitted).'),
+            expiry: z.enum(['1h', '6h', '24h', '72h', '168h', '720h', 'never']).optional().describe('How long the link works (default: never expires).'),
+            callbackUrl: callbackSchema,
+        },
+        annotations: { title: 'Create a payment link', ...WRITE },
+    }, guarded(ctx, 'palpluss_create_payment_link', async ({ amount, phone, customerName, reference, channelId, expiry, callbackUrl }) => {
+        const msisdn = phone ? requirePhone(phone) : undefined;
+        const res = await client.createPaymentLink({
+            ...(amount !== undefined ? { amount } : {}),
+            ...(msisdn ? { phone_number: msisdn } : {}),
+            ...(customerName ? { customer_name: customerName } : {}),
+            ...(reference ? { external_reference: reference } : {}),
+            ...(channelId ? { channel_id: channelId } : {}),
+            ...(expiry ? { expiry } : {}),
+            ...(callbackUrl ? { callbackUrl } : {}),
+        });
+        return ok(res, { note: 'Link created. Share the url with the customer; payments show up in palpluss_list_transactions.' });
+    }));
+    server.registerTool('palpluss_disable_payment_link', {
+        title: 'Disable a payment link',
+        description: 'Stop a payment link from accepting payments. Past payments are kept. Needs the person\'s approval.',
+        inputSchema: { paymentLinkId: z.string().uuid() },
+        annotations: { title: 'Disable a payment link', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, guarded(ctx, 'palpluss_disable_payment_link', async ({ paymentLinkId }) => {
+        const link = (await client.getPaymentLink(paymentLinkId));
+        if (link.status === 'DISABLED')
+            return ok(link, { note: 'Already disabled. Nothing changed.' });
+        const approval = await requireApproval(ctx, {
+            action: 'paylink_disable',
+            title: 'Disable a payment link',
+            details: { Link: String(link.url ?? paymentLinkId), Amount: link.amount ? kes(link.amount) : 'Customer enters it' },
+            consequence: 'Customers who open this link will no longer be able to pay through it.',
+        }, 'paylink');
+        await client.disablePaymentLink(paymentLinkId);
+        return ok({ paymentLinkId, status: 'DISABLED' }, { note: `Cleared (${approval}). The link no longer accepts payments.` });
+    }));
+}
+/** Follow a request PalPluss is holding for the merchant's approval. */
+export function registerApprovalTools(ctx) {
+    const { server, client } = ctx;
+    const DONE = new Set(['EXECUTED', 'FAILED', 'REJECTED', 'EXPIRED']);
+    server.registerTool('palpluss_wait_for_approval', {
+        title: 'Wait for the merchant\'s approval',
+        description: 'Wait (up to 120 seconds) while the merchant approves or rejects a held payout or channel change in the PalPluss console, then return the outcome: EXECUTED (with the result), REJECTED, EXPIRED or FAILED. Returns PENDING_APPROVAL if they haven\'t decided yet — call it again later rather than retrying the original request.',
+        inputSchema: {
+            approvalId: z.string().uuid(),
+            timeoutSeconds: z.number().int().min(5).max(120).optional().describe('How long to wait (default 60).'),
+        },
+        annotations: { title: 'Wait for approval', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, guarded(ctx, 'palpluss_wait_for_approval', async ({ approvalId, timeoutSeconds }) => {
+        const deadline = Date.now() + (timeoutSeconds ?? 60) * 1000;
+        let req = (await client.getApproval(approvalId));
+        while (!DONE.has(String(req.status)) && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 3000));
+            req = (await client.getApproval(approvalId));
+        }
+        const notes = {
+            EXECUTED: 'Approved and done. See result.',
+            FAILED: 'Approved, but PalPluss could not complete it. See error.',
+            REJECTED: 'The merchant declined. Nothing was done.',
+            EXPIRED: 'Nobody approved it in time. Nothing was done.',
+        };
+        return ok(req, { note: notes[String(req.status)] ?? 'Still waiting for the merchant to decide in the console.' });
+    }));
+}

package/dist/tools/read.d.ts

@@ -0,0 +1,2 @@
+import { type ToolContext } from './common.js';
+export declare function registerReadTools(ctx: ToolContext): void;