@palpluss/mcp 0.0.0-stage → 0.2.0

package/dist/config.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Groups of tools. `read` is always on; the rest are switched on explicitly.
+ * Payouts and channel changes are off unless you name them.
+ */
+export declare const TOOLSETS: readonly ["read", "wallets", "collect", "channels", "payouts"];
+export type Toolset = (typeof TOOLSETS)[number];
+export declare const DEFAULT_TOOLSETS: Toolset[];
+/**
+ * How money-moving and channel-changing tools get a human's yes:
+ * - `elicit` (default): the MCP client shows the person an approval prompt;
+ *   the AI never sees or answers it. Clients without that support are refused.
+ * - `backend`: rely on PalPluss itself. Only works with MCP keys: PalPluss
+ *   enforces the key's permissions and limits and holds payouts and channel
+ *   changes until the merchant approves them in the console. Anything else is
+ *   refused. Used by PalPluss' hosted server and by apps that embed this one.
+ * - `none`: no prompt. Only for automated tests against a fake or local API, never a live key.
+ */
+export type ApprovalMode = 'elicit' | 'backend' | 'none';
+export interface Limits {
+    /** Largest single B2C payout, KES. */
+    maxPayout: number;
+    /** Total B2C payouts per Nairobi calendar day, KES. */
+    dailyPayoutTotal: number;
+    /** Number of B2C payouts per Nairobi calendar day. */
+    dailyPayoutCount: number;
+    /** Largest wallet top-up, KES. */
+    maxTopup: number;
+    /** Largest STK push request, KES. */
+    maxStk: number;
+    /** If non-empty, payouts may only go to these numbers (254XXXXXXXXX). */
+    payoutAllowlist: string[];
+}
+export interface PalplussMcpConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs: number;
+    toolsets: Toolset[];
+    /** Kill switch: when true, every tool that changes anything is refused. */
+    readOnly: boolean;
+    approval: ApprovalMode;
+    limits: Limits;
+    /** Where to keep the daily payout tally between restarts (stdio installs). */
+    stateFile?: string;
+    /** Append-only JSON-lines audit log of every tool call. */
+    auditFile?: string;
+}
+export declare const DEFAULT_BASE_URL = "https://api.palpluss.com";
+export declare const DEFAULT_LIMITS: Limits;
+export declare class ConfigError extends Error {
+}
+export declare function parseToolsets(raw: string | undefined): Toolset[];
+export declare function parseAllowlist(raw: string | undefined): string[];
+/** Build the configuration from environment variables (the CLI path). */
+export declare function loadConfigFromEnv(env?: NodeJS.ProcessEnv): PalplussMcpConfig;
+/** Fill in defaults for programmatic use (embedding in another app). */
+export declare function resolveConfig(input: Partial<PalplussMcpConfig> & {
+    apiKey: string;
+}): PalplussMcpConfig;

package/dist/config.js

@@ -0,0 +1,119 @@
+import { normalizePhone } from './safety/redact.js';
+/**
+ * Groups of tools. `read` is always on; the rest are switched on explicitly.
+ * Payouts and channel changes are off unless you name them.
+ */
+export const TOOLSETS = ['read', 'wallets', 'collect', 'channels', 'payouts'];
+export const DEFAULT_TOOLSETS = ['read', 'wallets', 'collect'];
+export const DEFAULT_BASE_URL = 'https://api.palpluss.com';
+export const DEFAULT_LIMITS = {
+    maxPayout: 5_000,
+    dailyPayoutTotal: 20_000,
+    dailyPayoutCount: 20,
+    maxTopup: 50_000,
+    maxStk: 150_000,
+    payoutAllowlist: [],
+};
+export class ConfigError extends Error {
+}
+function num(env, key, fallback) {
+    const raw = env[key];
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 0) {
+        throw new ConfigError(`${key} must be a non-negative number (got "${raw}").`);
+    }
+    return n;
+}
+function bool(env, key, fallback) {
+    const raw = env[key]?.trim().toLowerCase();
+    if (!raw)
+        return fallback;
+    if (['1', 'true', 'yes', 'on'].includes(raw))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(raw))
+        return false;
+    throw new ConfigError(`${key} must be true or false (got "${env[key]}").`);
+}
+export function parseToolsets(raw) {
+    if (!raw || !raw.trim())
+        return [...DEFAULT_TOOLSETS];
+    const wanted = raw
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    if (wanted.includes('all'))
+        return [...TOOLSETS];
+    const unknown = wanted.filter((t) => !TOOLSETS.includes(t));
+    if (unknown.length) {
+        throw new ConfigError(`Unknown toolset(s): ${unknown.join(', ')}. Use any of: ${TOOLSETS.join(', ')} (or "all").`);
+    }
+    return [...new Set(['read', ...wanted])];
+}
+export function parseAllowlist(raw) {
+    if (!raw || !raw.trim())
+        return [];
+    const out = [];
+    for (const part of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
+        const phone = normalizePhone(part);
+        if (!phone)
+            throw new ConfigError(`PALPLUSS_MCP_PAYOUT_ALLOWLIST has an invalid phone number: "${part}".`);
+        out.push(phone);
+    }
+    return [...new Set(out)];
+}
+/** Build the configuration from environment variables (the CLI path). */
+export function loadConfigFromEnv(env = process.env) {
+    const apiKey = env.PALPLUSS_API_KEY?.trim();
+    if (!apiKey) {
+        throw new ConfigError('PALPLUSS_API_KEY is not set. Create a key at console.palpluss.com → API Keys and pass it as an environment variable.');
+    }
+    const approval = (env.PALPLUSS_MCP_APPROVAL?.trim().toLowerCase() || 'elicit');
+    if (approval !== 'elicit' && approval !== 'backend' && approval !== 'none') {
+        throw new ConfigError('PALPLUSS_MCP_APPROVAL must be "elicit", "backend" or "none".');
+    }
+    return {
+        apiKey,
+        baseUrl: (env.PALPLUSS_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, ''),
+        timeoutMs: num(env, 'PALPLUSS_MCP_TIMEOUT_MS', 30_000),
+        toolsets: parseToolsets(env.PALPLUSS_MCP_TOOLSETS),
+        readOnly: bool(env, 'PALPLUSS_MCP_READ_ONLY', false),
+        approval,
+        limits: {
+            maxPayout: num(env, 'PALPLUSS_MCP_MAX_PAYOUT', DEFAULT_LIMITS.maxPayout),
+            dailyPayoutTotal: num(env, 'PALPLUSS_MCP_DAILY_PAYOUT_TOTAL', DEFAULT_LIMITS.dailyPayoutTotal),
+            dailyPayoutCount: num(env, 'PALPLUSS_MCP_DAILY_PAYOUT_COUNT', DEFAULT_LIMITS.dailyPayoutCount),
+            maxTopup: num(env, 'PALPLUSS_MCP_MAX_TOPUP', DEFAULT_LIMITS.maxTopup),
+            maxStk: num(env, 'PALPLUSS_MCP_MAX_STK', DEFAULT_LIMITS.maxStk),
+            payoutAllowlist: parseAllowlist(env.PALPLUSS_MCP_PAYOUT_ALLOWLIST),
+        },
+        stateFile: env.PALPLUSS_MCP_STATE_FILE?.trim() || undefined,
+        auditFile: env.PALPLUSS_MCP_AUDIT_FILE?.trim() || undefined,
+    };
+}
+/** Fill in defaults for programmatic use (embedding in another app). */
+export function resolveConfig(input) {
+    if (!input.apiKey?.trim())
+        throw new ConfigError('apiKey is required.');
+    return {
+        apiKey: input.apiKey.trim(),
+        baseUrl: (input.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ''),
+        timeoutMs: input.timeoutMs ?? 30_000,
+        toolsets: input.toolsets ? [...new Set(['read', ...input.toolsets])] : [...DEFAULT_TOOLSETS],
+        readOnly: input.readOnly ?? false,
+        approval: input.approval ?? 'elicit',
+        limits: {
+            ...DEFAULT_LIMITS,
+            ...input.limits,
+            payoutAllowlist: (input.limits?.payoutAllowlist ?? []).map((p) => {
+                const n = normalizePhone(p);
+                if (!n)
+                    throw new ConfigError(`Invalid allowlist phone number: "${p}".`);
+                return n;
+            }),
+        },
+        stateFile: input.stateFile,
+        auditFile: input.auditFile,
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,42 @@
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { PalplussMcpConfig } from './config.js';
+import { type CreateServerOptions } from './server.js';
+export interface HttpServerOptions {
+    /** Base configuration (from env). Its apiKey is used unless per-request keys are allowed. */
+    config: PalplussMcpConfig;
+    host?: string;
+    port?: number;
+    /**
+     * Required bearer token for every request (PALPLUSS_MCP_HTTP_TOKEN). Protects
+     * the endpoint so only the app you run it for can call it.
+     */
+    token: string;
+    /**
+     * Accept the merchant's PalPluss key in `X-PalPluss-Api-Key` when a session
+     * starts (one endpoint serving many merchants). Off by default.
+     */
+    allowKeyHeader?: boolean;
+    /** Close sessions idle longer than this (default 30 minutes). */
+    sessionIdleMs?: number;
+    extra?: Omit<CreateServerOptions, keyof PalplussMcpConfig>;
+}
+/**
+ * Streamable HTTP endpoint at /mcp with sessions. Each session is one MCP
+ * client connection with its own server, bound to the PalPluss key it started
+ * with, so approval prompts (elicitation) and the client's capabilities carry
+ * across requests. Requires a bearer token on every request.
+ */
+export declare function startHttpServer(opts: HttpServerOptions): Promise<Server>;
+/**
+ * Handle one MCP request without sessions: a fresh server and transport per
+ * request, closed when the response ends. For hosts that run several
+ * instances behind a load balancer (no shared session state).
+ *
+ * Elicitation needs a session, so approval prompts are not available here:
+ * use `approval: 'backend'` with an MCP key (PalPluss holds payouts and
+ * channel changes for console approval), or pass your own `approver`.
+ *
+ * `body` is the already-parsed JSON body (frameworks like Express or NestJS
+ * parse it before your handler runs).
+ */
+export declare function handleStatelessMcpRequest(req: IncomingMessage, res: ServerResponse, body: unknown, options: CreateServerOptions): Promise<void>;

package/dist/http.js

@@ -0,0 +1,141 @@
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { createPalplussMcpServer } from './server.js';
+const hash = (s) => createHash('sha256').update(s).digest();
+function sameSecret(a, b) {
+    return timingSafeEqual(hash(a), hash(b));
+}
+function send(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json' }).end(JSON.stringify(body));
+}
+const rpcError = (code, message) => ({ jsonrpc: '2.0', error: { code, message }, id: null });
+async function readJson(req, limit = 1_000_000) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > limit)
+            throw new Error('Request body too large');
+        chunks.push(chunk);
+    }
+    const text = Buffer.concat(chunks).toString('utf8');
+    return text ? JSON.parse(text) : undefined;
+}
+/**
+ * Streamable HTTP endpoint at /mcp with sessions. Each session is one MCP
+ * client connection with its own server, bound to the PalPluss key it started
+ * with, so approval prompts (elicitation) and the client's capabilities carry
+ * across requests. Requires a bearer token on every request.
+ */
+export function startHttpServer(opts) {
+    const host = opts.host ?? '127.0.0.1';
+    const port = opts.port ?? 3333;
+    const idleMs = opts.sessionIdleMs ?? 30 * 60_000;
+    if (!opts.token || opts.token.length < 24) {
+        throw new Error('PALPLUSS_MCP_HTTP_TOKEN must be set to a random secret of at least 24 characters.');
+    }
+    const sessions = new Map();
+    const closeSession = (id) => {
+        const s = sessions.get(id);
+        if (!s)
+            return;
+        sessions.delete(id);
+        void s.transport.close();
+        void s.server.close();
+    };
+    const sweeper = setInterval(() => {
+        const cutoff = Date.now() - idleMs;
+        for (const [id, s] of sessions)
+            if (s.lastSeen < cutoff)
+                closeSession(id);
+    }, 60_000);
+    sweeper.unref();
+    const keyFor = (req) => {
+        const headerKey = req.headers['x-palpluss-api-key'];
+        return opts.allowKeyHeader && typeof headerKey === 'string' && headerKey.trim() ? headerKey.trim() : opts.config.apiKey;
+    };
+    const httpServer = createServer(async (req, res) => {
+        try {
+            const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+            if (url.pathname === '/health')
+                return send(res, 200, { ok: true, sessions: sessions.size });
+            if (url.pathname !== '/mcp')
+                return send(res, 404, { error: 'Not found' });
+            const auth = req.headers.authorization ?? '';
+            const presented = auth.startsWith('Bearer ') ? auth.slice(7).trim() : '';
+            if (!presented || !sameSecret(presented, opts.token))
+                return send(res, 401, rpcError(-32001, 'Unauthorized'));
+            const apiKey = keyFor(req);
+            if (!apiKey)
+                return send(res, 400, rpcError(-32602, 'No PalPluss API key: set PALPLUSS_API_KEY or send X-PalPluss-Api-Key.'));
+            const keyHash = hash(apiKey).toString('hex');
+            const sessionId = req.headers['mcp-session-id'];
+            const body = req.method === 'POST' ? await readJson(req) : undefined;
+            if (typeof sessionId === 'string' && sessionId) {
+                const s = sessions.get(sessionId);
+                if (!s)
+                    return send(res, 404, rpcError(-32001, 'Session not found or expired. Reconnect.'));
+                // A session belongs to the key that opened it.
+                if (s.keyHash !== keyHash)
+                    return send(res, 403, rpcError(-32001, 'This session belongs to a different PalPluss key.'));
+                s.lastSeen = Date.now();
+                if (req.method === 'DELETE') {
+                    await s.transport.handleRequest(req, res, body);
+                    closeSession(sessionId);
+                    return;
+                }
+                return s.transport.handleRequest(req, res, body);
+            }
+            if (req.method !== 'POST' || !isInitializeRequest(body)) {
+                return send(res, 400, rpcError(-32000, 'Start a session with an initialize request first.'));
+            }
+            const { server } = createPalplussMcpServer({ ...opts.config, ...opts.extra, apiKey });
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (id) => {
+                    sessions.set(id, { server, transport, keyHash, lastSeen: Date.now() });
+                },
+            });
+            transport.onclose = () => {
+                if (transport.sessionId)
+                    sessions.delete(transport.sessionId);
+            };
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (err) {
+            if (!res.headersSent)
+                send(res, 400, rpcError(-32700, err.message || 'Bad request'));
+        }
+    });
+    httpServer.on('close', () => {
+        clearInterval(sweeper);
+        for (const id of [...sessions.keys()])
+            closeSession(id);
+    });
+    return new Promise((resolve) => httpServer.listen(port, host, () => resolve(httpServer)));
+}
+/**
+ * Handle one MCP request without sessions: a fresh server and transport per
+ * request, closed when the response ends. For hosts that run several
+ * instances behind a load balancer (no shared session state).
+ *
+ * Elicitation needs a session, so approval prompts are not available here:
+ * use `approval: 'backend'` with an MCP key (PalPluss holds payouts and
+ * channel changes for console approval), or pass your own `approver`.
+ *
+ * `body` is the already-parsed JSON body (frameworks like Express or NestJS
+ * parse it before your handler runs).
+ */
+export async function handleStatelessMcpRequest(req, res, body, options) {
+    const { server } = createPalplussMcpServer(options);
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+    res.on('close', () => {
+        void transport.close();
+        void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, body);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createPalplussMcpServer, SERVER_NAME, SERVER_VERSION, type CreateServerOptions } from './server.js';
+export { loadConfigFromEnv, resolveConfig, parseToolsets, ConfigError, TOOLSETS, DEFAULT_TOOLSETS, DEFAULT_LIMITS, DEFAULT_BASE_URL, type PalplussMcpConfig, type Toolset, type Limits, type ApprovalMode, } from './config.js';
+export type { Approver, ApprovalRequest, ApprovalOutcome } from './safety/approval.js';
+export type { AuditEvent, AuditSink } from './safety/audit.js';
+export { PalplussApiError, isPendingApproval, type KeyInfo, type PendingApproval } from './api/client.js';
+export { startHttpServer, handleStatelessMcpRequest, type HttpServerOptions } from './http.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createPalplussMcpServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+export { loadConfigFromEnv, resolveConfig, parseToolsets, ConfigError, TOOLSETS, DEFAULT_TOOLSETS, DEFAULT_LIMITS, DEFAULT_BASE_URL, } from './config.js';
+export { PalplussApiError, isPendingApproval } from './api/client.js';
+export { startHttpServer, handleStatelessMcpRequest } from './http.js';

package/dist/safety/approval.d.ts

@@ -0,0 +1,34 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApprovalMode } from '../config.js';
+/** One action waiting for a human's yes. */
+export interface ApprovalRequest {
+    /** Stable action name, e.g. "b2c_payout". */
+    action: string;
+    /** One line a person can read at a glance. */
+    title: string;
+    /** Label → value pairs shown to the person (already masked where needed). */
+    details: Record<string, string>;
+    /** What happens if they approve, in plain words. */
+    consequence: string;
+}
+export type ApprovalOutcome = {
+    approved: true;
+    via: 'elicitation' | 'host' | 'disabled';
+} | {
+    approved: false;
+    reason: 'declined' | 'cancelled' | 'unavailable';
+    message: string;
+};
+/**
+ * Decides whether an action may go ahead. An embedding app
+ * can pass its own — for example one that opens its confirm dialog.
+ */
+export type Approver = (request: ApprovalRequest) => Promise<ApprovalOutcome>;
+/**
+ * Ask the person directly through the MCP client (elicitation). The request
+ * goes from this server to the person's app and back — the AI model never
+ * sees or answers it, so it cannot approve its own actions.
+ */
+export declare function createElicitationApprover(server: McpServer): Approver;
+/** Pick the approver for a server: the embedder's, the client prompt, or none. */
+export declare function resolveApprover(mode: ApprovalMode, server: McpServer, custom?: Approver): Approver;

package/dist/safety/approval.js

@@ -0,0 +1,61 @@
+function renderMessage(req) {
+    const lines = Object.entries(req.details).map(([k, v]) => `• ${k}: ${v}`);
+    return [`PalPluss — ${req.title}`, '', ...lines, '', req.consequence, '', 'Approve only if you asked for this.'].join('\n');
+}
+/**
+ * Ask the person directly through the MCP client (elicitation). The request
+ * goes from this server to the person's app and back — the AI model never
+ * sees or answers it, so it cannot approve its own actions.
+ */
+export function createElicitationApprover(server) {
+    return async (req) => {
+        const caps = server.server.getClientCapabilities();
+        if (!caps?.elicitation) {
+            return {
+                approved: false,
+                reason: 'unavailable',
+                message: 'This action needs your approval, but this app cannot show approval prompts (MCP elicitation). Use a client that supports them, or do it in the PalPluss console.',
+            };
+        }
+        try {
+            const result = await server.server.elicitInput({
+                mode: 'form',
+                message: renderMessage(req),
+                requestedSchema: {
+                    type: 'object',
+                    properties: {
+                        approve: {
+                            type: 'boolean',
+                            title: 'Approve this action',
+                            description: req.title,
+                            default: false,
+                        },
+                    },
+                    required: ['approve'],
+                },
+            });
+            if (result.action === 'accept' && result.content?.approve === true) {
+                return { approved: true, via: 'elicitation' };
+            }
+            if (result.action === 'cancel') {
+                return { approved: false, reason: 'cancelled', message: 'The approval prompt was dismissed. Nothing was done.' };
+            }
+            return { approved: false, reason: 'declined', message: 'You declined. Nothing was done.' };
+        }
+        catch (err) {
+            return {
+                approved: false,
+                reason: 'unavailable',
+                message: `Could not show the approval prompt (${err?.message ?? 'unknown error'}). Nothing was done.`,
+            };
+        }
+    };
+}
+/** Pick the approver for a server: the embedder's, the client prompt, or none. */
+export function resolveApprover(mode, server, custom) {
+    if (custom)
+        return custom;
+    if (mode === 'none')
+        return async () => ({ approved: true, via: 'disabled' });
+    return createElicitationApprover(server);
+}

package/dist/safety/audit.d.ts

@@ -0,0 +1,26 @@
+export interface AuditEvent {
+    at: string;
+    tool: string;
+    outcome: 'ok' | 'error' | 'refused' | 'declined';
+    /** Tool arguments with phone numbers masked. */
+    args?: unknown;
+    /** PalPluss transaction or channel id involved, if any. */
+    ref?: string;
+    code?: string;
+    message?: string;
+    approval?: string;
+    requestId?: string;
+}
+export type AuditSink = (event: AuditEvent) => void;
+/**
+ * Records every tool call: to a JSON-lines file (PALPLUSS_MCP_AUDIT_FILE)
+ * and/or to a sink an embedding app provides. Never logs the API key.
+ */
+export declare class AuditLog {
+    private readonly file?;
+    private readonly sink?;
+    constructor(file?: string | undefined, sink?: AuditSink | undefined);
+    record(event: Omit<AuditEvent, 'at' | 'args'> & {
+        args?: unknown;
+    }): void;
+}

package/dist/safety/audit.js

@@ -0,0 +1,40 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { maskArgs } from './redact.js';
+/**
+ * Records every tool call: to a JSON-lines file (PALPLUSS_MCP_AUDIT_FILE)
+ * and/or to a sink an embedding app provides. Never logs the API key.
+ */
+export class AuditLog {
+    file;
+    sink;
+    constructor(file, sink) {
+        this.file = file;
+        this.sink = sink;
+        if (file) {
+            try {
+                mkdirSync(dirname(file), { recursive: true });
+            }
+            catch {
+                /* reported on first write */
+            }
+        }
+    }
+    record(event) {
+        const full = { ...event, at: new Date().toISOString(), args: maskArgs(event.args) };
+        if (this.file) {
+            try {
+                appendFileSync(this.file, `${JSON.stringify(full)}\n`, { mode: 0o600 });
+            }
+            catch (err) {
+                process.stderr.write(`[palpluss-mcp] could not write audit log: ${err.message}\n`);
+            }
+        }
+        try {
+            this.sink?.(full);
+        }
+        catch {
+            /* an embedder's sink must never break a tool call */
+        }
+    }
+}

package/dist/safety/limits.d.ts

@@ -0,0 +1,42 @@
+import type { Limits } from '../config.js';
+/** Today's date in Nairobi, YYYY-MM-DD. */
+export declare function nairobiDay(now?: Date): string;
+export declare class LimitError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Per-key payout limits enforced by this MCP server: per payout, per day
+ * (total and count) and an optional recipient allowlist.
+ *
+ * A payout reserves its amount before the API call and releases it if the
+ * call fails, so two payouts approved at the same moment can't both slip
+ * under the daily limit.
+ *
+ * These are a guardrail in front of the API, not a replacement for limits the
+ * backend enforces; they reset if the state file is removed.
+ */
+export declare class PayoutLimiter {
+    private readonly limits;
+    private readonly stateFile?;
+    private readonly now;
+    private static readonly shared;
+    private readonly key;
+    constructor(limits: Limits, apiKey: string, stateFile?: string | undefined, now?: () => Date);
+    private load;
+    private persist;
+    /** What's left today, for display. */
+    remaining(): {
+        day: string;
+        usedTotal: number;
+        usedCount: number;
+        remainingTotal: number;
+        remainingCount: number;
+    };
+    /** Throws LimitError if this payout isn't allowed. Does not reserve. */
+    check(amount: number, phone: string): void;
+    /** Check and reserve atomically (single-threaded JS). Returns a release fn. */
+    reserve(amount: number, phone: string): () => void;
+    /** Test helper. */
+    static resetAll(): void;
+}