shabaaspay-mcp-server 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShaBaas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/api/client.d.ts

@@ -0,0 +1,60 @@
+import { Config } from '../config/index.js';
+import { ApiResponse } from '../types/index.js';
+export declare class ShabaasApiClient {
+    private client;
+    private config;
+    private bearerToken;
+    private bearerTokenFetchedAtMs;
+    constructor(config: Config);
+    private normalizeBearer;
+    /**
+     * Exchanges the configured UUID for a Bearer token.
+     * UUID must be sent only to /api/public/authorization in the Authorization header.
+     * The returned token is used for all subsequent API calls.
+     */
+    authorize(): Promise<{
+        token: string;
+        raw: any;
+    }>;
+    private tokenLooksFresh;
+    ensureAuthenticated(): Promise<void>;
+    private withAuthRetry;
+    getAuthToken(): Promise<{
+        token: string;
+        fetchedAt: string;
+    }>;
+    getPaymentAgreement(id: string): Promise<ApiResponse>;
+    createPaymentAgreement(data: {
+        name: string;
+        type: string;
+        maximum_amount: string;
+        frequency: string;
+        number_of_transactions_permitted: number;
+        pay_id: string;
+        idempotency_key: string;
+    }): Promise<ApiResponse>;
+    cancelPaymentAgreement(id: string): Promise<ApiResponse>;
+    resendPaymentAgreement(id: string): Promise<ApiResponse>;
+    initiatePayment(data: {
+        payment_agreement_id: string;
+        amount: string | number;
+        description?: string;
+        idempotency_key: string;
+    }): Promise<ApiResponse>;
+    getPaymentInitiation(id: string): Promise<ApiResponse>;
+    initiateDirectDebit(data: {
+        payment_agreement_id: string;
+        amount: string | number;
+        description?: string;
+        idempotency_key: string;
+    }): Promise<ApiResponse>;
+    getPaymentLink(data: {
+        amount: string;
+        reference?: string;
+    }): Promise<ApiResponse>;
+    registerWebhook(data: {
+        url: string;
+        events: string[];
+    }): Promise<ApiResponse>;
+    listWebhooks(): Promise<ApiResponse>;
+}

package/dist/api/client.js

@@ -0,0 +1,214 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShabaasApiClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+const index_js_1 = require("../config/index.js");
+class ShabaasApiClient {
+    client;
+    config;
+    bearerToken = null;
+    bearerTokenFetchedAtMs = null;
+    constructor(config) {
+        this.config = config;
+        const baseURL = (0, index_js_1.getApiUrl)(config);
+        this.client = axios_1.default.create({
+            baseURL,
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            timeout: 30000,
+        });
+        this.client.interceptors.request.use((cfg) => {
+            // Log to stderr to keep STDIO transport stdout clean for MCP JSON
+            console.error(`[API Request] ${cfg.method?.toUpperCase()} ${cfg.url}`);
+            return cfg;
+        }, (error) => {
+            console.error('[API Request Error]', error);
+            return Promise.reject(error);
+        });
+        this.client.interceptors.response.use((response) => response, (error) => {
+            if (error.response) {
+                console.error('[API Response Error]', JSON.stringify({
+                    status: error.response.status,
+                    data: error.response.data,
+                }, null, 2));
+            }
+            else {
+                console.error('[API Network Error]', error.message);
+            }
+            return Promise.reject(error);
+        });
+    }
+    normalizeBearer(token) {
+        const trimmed = token.trim();
+        return trimmed.toLowerCase().startsWith('bearer ')
+            ? trimmed
+            : `Bearer ${trimmed}`;
+    }
+    /**
+     * Exchanges the configured UUID for a Bearer token.
+     * UUID must be sent only to /api/public/authorization in the Authorization header.
+     * The returned token is used for all subsequent API calls.
+     */
+    async authorize() {
+        const response = await this.client.post('/api/public/authorization', null, {
+            headers: {
+                Authorization: this.config.shabaasAuthUuid,
+                accept: 'application/json',
+            },
+        });
+        const payload = response.data;
+        const rawToken = payload?.data?.token ||
+            payload?.data?.access_token ||
+            payload?.token ||
+            payload?.access_token ||
+            payload?.token ||
+            payload?.access_token;
+        if (!rawToken || typeof rawToken !== 'string') {
+            throw new Error('Authorization succeeded but no token was returned. Expected token in response at data.token.');
+        }
+        const token = this.normalizeBearer(rawToken);
+        this.bearerToken = token;
+        this.bearerTokenFetchedAtMs = Date.now();
+        this.client.defaults.headers.common['Authorization'] = token;
+        return { token, raw: payload };
+    }
+    tokenLooksFresh() {
+        if (!this.bearerToken || !this.bearerTokenFetchedAtMs)
+            return false;
+        const ageMs = Date.now() - this.bearerTokenFetchedAtMs;
+        const maxAgeMs = this.config.authTokenMaxAgeMinutes * 60 * 1000;
+        return ageMs < maxAgeMs;
+    }
+    async ensureAuthenticated() {
+        if (this.tokenLooksFresh())
+            return;
+        await this.authorize();
+    }
+    async withAuthRetry(fn) {
+        try {
+            await this.ensureAuthenticated();
+            return await fn();
+        }
+        catch (err) {
+            const status = err?.response?.status;
+            if (status === 401 || status === 403) {
+                await this.authorize();
+                return await fn();
+            }
+            throw err;
+        }
+    }
+    async getAuthToken() {
+        const { token } = await this.authorize();
+        return { token, fetchedAt: new Date().toISOString() };
+    }
+    async getPaymentAgreement(id) {
+        return await this.withAuthRetry(async () => {
+            const response = await this.client.get(`/api/public/payment_agreement?id=${encodeURIComponent(id)}`);
+            return response.data;
+        });
+    }
+    async createPaymentAgreement(data) {
+        return await this.withAuthRetry(async () => {
+            const body = {
+                payment_agreement: {
+                    name: data.name,
+                    type: data.type,
+                    maximum_amount: data.maximum_amount,
+                    frequency: data.frequency,
+                    number_of_transactions_permitted: data.number_of_transactions_permitted,
+                    pay_id: data.pay_id,
+                },
+            };
+            const response = await this.client.post('/api/public/payment_agreement', body, {
+                headers: {
+                    'Idempotency-Key': data.idempotency_key,
+                },
+            });
+            return response.data;
+        });
+    }
+    async cancelPaymentAgreement(id) {
+        return await this.withAuthRetry(async () => {
+            const response = await this.client.delete(`/api/public/payment_agreement/cancel?id=${encodeURIComponent(id)}`);
+            return response.data;
+        });
+    }
+    async resendPaymentAgreement(id) {
+        return await this.withAuthRetry(async () => {
+            const response = await this.client.patch('/api/public/payment_agreement/resend', { id });
+            return response.data;
+        });
+    }
+    async initiatePayment(data) {
+        return await this.withAuthRetry(async () => {
+            const amount = normalizeAmount(data.amount);
+            const response = await this.client.post('/api/public/payment_initiation', {
+                payment_initiation: {
+                    payment_agreement_id: data.payment_agreement_id,
+                    amount,
+                    description: data.description,
+                },
+            }, {
+                headers: {
+                    'Idempotency-Key': data.idempotency_key,
+                },
+            });
+            return response.data;
+        });
+    }
+    async getPaymentInitiation(id) {
+        return await this.withAuthRetry(async () => {
+            const response = await this.client.get(`/api/public/payment_initiation?id=${encodeURIComponent(id)}`);
+            return response.data;
+        });
+    }
+    async initiateDirectDebit(data) {
+        return await this.withAuthRetry(async () => {
+            const amount = normalizeAmount(data.amount);
+            const response = await this.client.post('/api/public/payment_initiation/direct_debit', {
+                payment_initiation: {
+                    payment_agreement_id: data.payment_agreement_id,
+                    amount,
+                    description: data.description,
+                },
+            }, {
+                headers: {
+                    'Idempotency-Key': data.idempotency_key,
+                },
+            });
+            return response.data;
+        });
+    }
+    async getPaymentLink(data) {
+        return await this.withAuthRetry(async () => {
+            const response = await this.client.post('/api/get_url', data);
+            return response.data;
+        });
+    }
+    async registerWebhook(data) {
+        return await this.withAuthRetry(async () => {
+            const response = await this.client.post('/api/public/webhooks', data);
+            return response.data;
+        });
+    }
+    async listWebhooks() {
+        return await this.withAuthRetry(async () => {
+            const response = await this.client.get('/api/public/webhooks');
+            return response.data;
+        });
+    }
+}
+exports.ShabaasApiClient = ShabaasApiClient;
+function normalizeAmount(amount) {
+    const numeric = typeof amount === 'string' ? Number(amount) : amount;
+    if (Number.isNaN(numeric)) {
+        throw new Error('Amount must be a number');
+    }
+    const rounded = Math.round(numeric * 100) / 100;
+    return rounded.toString();
+}

package/dist/config/index.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+/**
+ * Configuration notes
+ * - ShaBaas API auth uses a UUID that must ONLY be sent to /api/public/authorization to obtain a Bearer token.
+ * - The Bearer token returned by that endpoint is used for all subsequent ShaBaas API calls.
+ *
+ * Env var compatibility:
+ * - Prefer SHABAAS_AUTH_UUID
+ * - SHABAAS_API_KEY is accepted as a backwards compatible alias for SHABAAS_AUTH_UUID
+ */
+declare const ConfigSchema: z.ZodObject<{
+    environment: z.ZodDefault<z.ZodEnum<["sandbox", "production"]>>;
+    shabaasAuthUuid: z.ZodString;
+    sandboxUrl: z.ZodDefault<z.ZodString>;
+    productionUrl: z.ZodDefault<z.ZodString>;
+    httpPort: z.ZodDefault<z.ZodNumber>;
+    httpHost: z.ZodDefault<z.ZodString>;
+    mcpHttpApiKey: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    mcpStdioApiKey: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    allowedOrigins: z.ZodDefault<z.ZodEffects<z.ZodString, string[], string>>;
+    rateLimitPerMinute: z.ZodDefault<z.ZodNumber>;
+    rateLimitPerHour: z.ZodDefault<z.ZodNumber>;
+    authTokenMaxAgeMinutes: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    environment: "sandbox" | "production";
+    shabaasAuthUuid: string;
+    sandboxUrl: string;
+    productionUrl: string;
+    httpPort: number;
+    httpHost: string;
+    mcpHttpApiKey: string;
+    mcpStdioApiKey: string;
+    allowedOrigins: string[];
+    rateLimitPerMinute: number;
+    rateLimitPerHour: number;
+    authTokenMaxAgeMinutes: number;
+}, {
+    shabaasAuthUuid: string;
+    environment?: "sandbox" | "production" | undefined;
+    sandboxUrl?: string | undefined;
+    productionUrl?: string | undefined;
+    httpPort?: number | undefined;
+    httpHost?: string | undefined;
+    mcpHttpApiKey?: string | undefined;
+    mcpStdioApiKey?: string | undefined;
+    allowedOrigins?: string | undefined;
+    rateLimitPerMinute?: number | undefined;
+    rateLimitPerHour?: number | undefined;
+    authTokenMaxAgeMinutes?: number | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(): Config;
+export declare function getApiUrl(config: Config): string;
+export {};

package/dist/config/index.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.getApiUrl = getApiUrl;
+const dotenv_1 = __importDefault(require("dotenv"));
+const zod_1 = require("zod");
+dotenv_1.default.config();
+/**
+ * Configuration notes
+ * - ShaBaas API auth uses a UUID that must ONLY be sent to /api/public/authorization to obtain a Bearer token.
+ * - The Bearer token returned by that endpoint is used for all subsequent ShaBaas API calls.
+ *
+ * Env var compatibility:
+ * - Prefer SHABAAS_AUTH_UUID
+ * - SHABAAS_API_KEY is accepted as a backwards compatible alias for SHABAAS_AUTH_UUID
+ */
+const ConfigSchema = zod_1.z.object({
+    environment: zod_1.z.enum(['sandbox', 'production']).default('sandbox'),
+    // ShaBaas API authentication
+    shabaasAuthUuid: zod_1.z.string().min(1, 'ShaBaas auth UUID is required'),
+    // Base URLs (override via env; defaults are placeholders only)
+    sandboxUrl: zod_1.z.string().url().default('https://sandbox.example.com'),
+    productionUrl: zod_1.z.string().url().default('https://api.example.com'),
+    // HTTP mode configuration (optional)
+    httpPort: zod_1.z.coerce.number().default(3000),
+    httpHost: zod_1.z.string().default('0.0.0.0'),
+    // If set, HTTP mode requires: Authorization: Bearer <mcpHttpApiKey>
+    mcpHttpApiKey: zod_1.z.string().optional().default(''),
+    // STDIO mode optional guard: include authorization field in tool arguments
+    mcpStdioApiKey: zod_1.z.string().optional().default(''),
+    // Security
+    allowedOrigins: zod_1.z.string().transform(str => str.split(',')).default('*'),
+    rateLimitPerMinute: zod_1.z.coerce.number().default(60),
+    rateLimitPerHour: zod_1.z.coerce.number().default(1000),
+    // Token cache settings
+    // Used only as a heuristic if the auth response does not include expiry metadata
+    authTokenMaxAgeMinutes: zod_1.z.coerce.number().default(50),
+});
+function loadConfig() {
+    try {
+        const shabaasAuthUuid = process.env.SHABAAS_AUTH_UUID ||
+            process.env.SHABAAS_API_KEY || // backwards compatible alias
+            '';
+        return ConfigSchema.parse({
+            environment: process.env.SHABAAS_ENVIRONMENT,
+            shabaasAuthUuid,
+            sandboxUrl: process.env.SHABAAS_SANDBOX_URL,
+            productionUrl: process.env.SHABAAS_PRODUCTION_URL,
+            httpPort: process.env.HTTP_PORT,
+            httpHost: process.env.HTTP_HOST,
+            mcpHttpApiKey: process.env.MCP_HTTP_API_KEY || process.env.HTTP_API_KEY || '',
+            mcpStdioApiKey: process.env.MCP_STDIO_API_KEY || process.env.STDIO_API_KEY || '',
+            allowedOrigins: process.env.ALLOWED_ORIGINS,
+            rateLimitPerMinute: process.env.API_RATE_LIMIT_PER_MINUTE,
+            rateLimitPerHour: process.env.API_RATE_LIMIT_PER_HOUR,
+            authTokenMaxAgeMinutes: process.env.AUTH_TOKEN_MAX_AGE_MINUTES,
+        });
+    }
+    catch (error) {
+        if (error instanceof zod_1.z.ZodError) {
+            console.error('Configuration error:');
+            error.errors.forEach(err => {
+                console.error(`  - ${err.path.join('.')}: ${err.message}`);
+            });
+        }
+        else {
+            console.error('Failed to load configuration:', error);
+        }
+        process.exit(1);
+    }
+}
+function getApiUrl(config) {
+    return config.environment === 'production'
+        ? config.productionUrl
+        : config.sandboxUrl;
+}

package/dist/enricher/action-suggester.d.ts

@@ -0,0 +1,2 @@
+import { PaymentAgreement } from "../types/index.js";
+export declare function suggestActions(agreement: PaymentAgreement): string[];

package/dist/enricher/action-suggester.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggestActions = suggestActions;
+function suggestActions(agreement) {
+    const actions = [];
+    const status = (agreement.status || "").toLowerCase().trim();
+    actions.push("get_payment_agreement");
+    if (status === "active") {
+        actions.push("initiate_payment");
+        actions.push("initiate_direct_debit");
+        actions.push("cancel_payment_agreement");
+        return actions;
+    }
+    if (status === "created" || status === "pending") {
+        actions.push("resend_payment_agreement");
+        actions.push("cancel_payment_agreement");
+        actions.push("request_payer_authorisation");
+        return actions;
+    }
+    if (status === "cancelled" || status === "canceled" || status === "expired") {
+        actions.push("create_payment_agreement");
+        return actions;
+    }
+    actions.push("manual_review_required");
+    return actions;
+}

package/dist/enricher/index.d.ts

@@ -0,0 +1,2 @@
+import { PaymentAgreement, StandardResponse } from "../types/index.js";
+export declare function enrichPaymentAgreement(data: PaymentAgreement, includeRaw: boolean, rawResponse: any, environment: "sandbox" | "production"): StandardResponse<PaymentAgreement>;

package/dist/enricher/index.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichPaymentAgreement = enrichPaymentAgreement;
+const status_analyzer_js_1 = require("./status-analyzer.js");
+const action_suggester_js_1 = require("./action-suggester.js");
+const summary_generator_js_1 = require("./summary-generator.js");
+function enrichPaymentAgreement(data, includeRaw, rawResponse, environment) {
+    const startTime = Date.now();
+    const statusAnalysis = (0, status_analyzer_js_1.analyzeStatus)(data.status, data.extented_status);
+    const nextActions = (0, action_suggester_js_1.suggestActions)(data);
+    const business = buildBusinessInsights(data, statusAnalysis);
+    const summary = (0, summary_generator_js_1.generateSummary)(data, statusAnalysis, business);
+    return {
+        success: true,
+        timestamp: new Date().toISOString(),
+        data,
+        metadata: {
+            requestId: generateRequestId(),
+            processingTime: Date.now() - startTime,
+            environment,
+        },
+        insights: {
+            status: statusAnalysis.displayStatus,
+            canProceed: statusAnalysis.canInitiatePayment,
+            nextActions,
+            warnings: statusAnalysis.warnings,
+            business,
+        },
+        summary,
+        ...(includeRaw ? { raw: rawResponse } : {}),
+    };
+}
+function generateRequestId() {
+    return `req_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function parseExtendedStatus(ext) {
+    if (!ext)
+        return {};
+    const parts = ext
+        .split("-")
+        .map((p) => p.trim())
+        .filter(Boolean);
+    if (parts.length === 0)
+        return {};
+    const maximumAmount = parts[0] && !Number.isNaN(Number(parts[0])) ? Number(parts[0]) : undefined;
+    const frequency = parts.length > 1 ? parts[1] : undefined;
+    const numberOfTransactionsPermitted = parts.length > 2 && !Number.isNaN(Number(parts[2])) ? Number(parts[2]) : undefined;
+    const status = parts.length > 3 ? parts[3] : undefined;
+    return { maximumAmount, frequency, numberOfTransactionsPermitted, status };
+}
+function safeDate(value) {
+    if (!value)
+        return undefined;
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime()))
+        return undefined;
+    return d;
+}
+function daysDiff(from, to) {
+    return Math.floor((to.getTime() - from.getTime()) / 86400000);
+}
+function buildBusinessInsights(agreement, statusAnalysis) {
+    const ext = parseExtendedStatus(agreement.extented_status);
+    const status = (agreement.status || "").toLowerCase();
+    const canInitiate = !!statusAnalysis.canInitiatePayment;
+    const createdAt = safeDate(agreement.created_at);
+    const endAt = safeDate(agreement.end_date);
+    const now = new Date();
+    const createdDaysAgo = createdAt ? Math.abs(daysDiff(createdAt, now)) : undefined;
+    const expiresInDays = endAt ? Math.max(0, Math.ceil((endAt.getTime() - now.getTime()) / 86400000)) : undefined;
+    const isExpiringSoon = typeof expiresInDays === "number" ? expiresInDays <= 30 : undefined;
+    const maximumAmountFromField = agreement.maximum_amount && !Number.isNaN(Number(agreement.maximum_amount))
+        ? Number(agreement.maximum_amount)
+        : undefined;
+    const maximumAmount = maximumAmountFromField ?? ext.maximumAmount;
+    const meaning = canInitiate
+        ? "Agreement is active and ready for real time payment initiation"
+        : status === "created" || status === "pending"
+            ? "Agreement is created but not yet authorised by the payer"
+            : status === "suspended"
+                ? "Agreement is suspended and payments should not be initiated"
+                : status === "cancelled" || status === "canceled"
+                    ? "Agreement is cancelled and cannot be used for further payments"
+                    : status === "expired"
+                        ? "Agreement is expired and cannot be used for further payments"
+                        : "Agreement status requires manual review before proceeding";
+    const readinessReason = canInitiate
+        ? "Agreement is active so payment initiation can proceed within the agreed limit"
+        : status === "created" || status === "pending"
+            ? "Agreement exists but payer must authorise it in their banking app before any debit can occur"
+            : status === "suspended"
+                ? "Agreement is suspended so payment initiation should not proceed"
+                : status === "cancelled" || status === "canceled"
+                    ? "Agreement is cancelled so a new agreement is required"
+                    : status === "expired"
+                        ? "Agreement is expired so a new agreement is required"
+                        : "Agreement is not in a state that supports payment initiation";
+    const payerControls = [
+        "Payer authorises PayTo agreements in online banking before a business can take a payment",
+        "Payer can view agreements and pause, resume or cancel them in online banking",
+    ];
+    const reconciliationNotes = [
+        "PayTo agreements carry richer agreement data which can support reconciliation and reduce manual matching",
+    ];
+    const operationalChecks = [];
+    if (canInitiate) {
+        operationalChecks.push("Initiate the payment then verify payment initiation status");
+        operationalChecks.push("If a payer reports an unexpected debit remind them they can review agreement details in their banking app");
+    }
+    else {
+        operationalChecks.push("Ask the payer to authorise the agreement in their banking app then re check agreement status");
+        operationalChecks.push("If the payer cannot locate the agreement ask them to check PayTo agreements in their banking app");
+    }
+    if (isExpiringSoon) {
+        operationalChecks.push("Agreement is expiring soon. Consider issuing a new agreement to avoid collection disruption");
+    }
+    const riskFlags = [];
+    if (typeof maximumAmount === "number" && maximumAmount <= 0) {
+        riskFlags.push("Maximum amount is zero or negative");
+    }
+    if (typeof maximumAmount === "number" && maximumAmount < 2) {
+        riskFlags.push("Very low maximum amount. Confirm commercial intent");
+    }
+    if (isExpiringSoon) {
+        riskFlags.push("Agreement expiring soon");
+    }
+    const frequencyLabel = ext.frequency ? ext.frequency.toLowerCase() : undefined;
+    const recommendedCustomerCopy = canInitiate
+        ? `Your PayTo agreement is active. We will only debit up to AUD ${typeof maximumAmount === "number" ? maximumAmount.toFixed(2) : ""}${frequencyLabel ? " " + frequencyLabel : ""}. You can manage or cancel the agreement in your banking app.`
+        : "Please authorise this PayTo agreement in your banking app so we can initiate payments within the agreed limit.";
+    const references = [
+        { title: "PayTo overview", url: "https://www.auspayplus.com.au/solutions/payto" },
+        { title: "PayTo FAQs", url: "https://www.auspayplus.com.au/solutions/payto-faqs" },
+        { title: "PayTo for consumers", url: "https://www.auspayplus.com.au/solutions/payto-for-consumers" },
+        { title: "PayTo business use cases", url: "https://www.auspayplus.com.au/solutions/payto-for-businesses-use-cases" },
+    ];
+    return {
+        product: "PayTo",
+        meaning,
+        readiness: {
+            canInitiatePayment: canInitiate,
+            reason: readinessReason,
+        },
+        limits: {
+            maximumAmount,
+            currency: "AUD",
+        },
+        cadence: {
+            frequency: ext.frequency,
+            numberOfTransactionsPermitted: ext.numberOfTransactionsPermitted,
+        },
+        timing: {
+            createdAt: agreement.created_at,
+            endDate: agreement.end_date,
+            createdDaysAgo,
+            expiresInDays,
+            isExpiringSoon,
+        },
+        payerControls,
+        reconciliationNotes,
+        operationalChecks,
+        recommendedCustomerCopy,
+        riskFlags,
+        references,
+    };
+}

package/dist/enricher/status-analyzer.d.ts

@@ -0,0 +1,6 @@
+export interface StatusAnalysis {
+    displayStatus: string;
+    canInitiatePayment: boolean;
+    warnings?: string[];
+}
+export declare function analyzeStatus(status: string, extendedStatus?: string): StatusAnalysis;