shabaaspay-mcp-server 1.0.1 → 1.0.3

package/LICENSE

@@ -1,21 +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.
+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

@@ -1,29 +1,26 @@
 import { Config } from '../config/index.js';
 import { ApiResponse } from '../types/index.js';
+/** Options for API calls that need backend auth; requestApiKey comes from the request (no .env). */
+export type RequestAuthOptions = {
+    requestUuid?: string;
+};
 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.
+     * Returns a bearer token for backend API calls. Use the API key from the request (Authorization header).
+     * No .env or global API key; requestUuid must be provided by the caller (value is the API key from the authenticated request).
+     * The backend accepts API key only.
      */
-    authorize(): Promise<{
-        token: string;
-        raw: any;
-    }>;
-    private tokenLooksFresh;
-    ensureAuthenticated(): Promise<void>;
+    getTokenForRequest(requestUuid?: string): Promise<string>;
     private withAuthRetry;
-    getAuthToken(): Promise<{
+    getAuthToken(options?: RequestAuthOptions): Promise<{
         token: string;
         fetchedAt: string;
     }>;
-    getPaymentAgreement(id: string): Promise<ApiResponse>;
+    getPaymentAgreement(id: string, options?: RequestAuthOptions): Promise<ApiResponse>;
     createPaymentAgreement(data: {
         name: string;
         type: string;
@@ -31,30 +28,33 @@ export declare class ShabaasApiClient {
         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>;
+        phone_number?: string;
+        bsb?: number;
+        account_number?: number;
+        agreement_type?: string;
+        start_date?: string;
+        end_date?: string;
+    }, options?: RequestAuthOptions): Promise<ApiResponse>;
+    cancelPaymentAgreement(id: string, options?: RequestAuthOptions): Promise<ApiResponse>;
+    resendPaymentAgreement(id: string, options?: RequestAuthOptions): Promise<ApiResponse>;
     initiatePayment(data: {
         payment_agreement_id: string;
         amount: string | number;
         description?: string;
-        idempotency_key: string;
-    }): Promise<ApiResponse>;
-    getPaymentInitiation(id: string): Promise<ApiResponse>;
+    }, options?: RequestAuthOptions): Promise<ApiResponse>;
+    getPaymentInitiation(id: string, options?: RequestAuthOptions): Promise<ApiResponse>;
     initiateDirectDebit(data: {
         payment_agreement_id: string;
         amount: string | number;
         description?: string;
-        idempotency_key: string;
-    }): Promise<ApiResponse>;
+    }, options?: RequestAuthOptions): Promise<ApiResponse>;
     getPaymentLink(data: {
         amount: string;
         reference?: string;
-    }): Promise<ApiResponse>;
+    }, options?: RequestAuthOptions): Promise<ApiResponse>;
     registerWebhook(data: {
         url: string;
         events: string[];
-    }): Promise<ApiResponse>;
-    listWebhooks(): Promise<ApiResponse>;
+    }, options?: RequestAuthOptions): Promise<ApiResponse>;
+    listWebhooks(options?: RequestAuthOptions): Promise<ApiResponse>;
 }

package/dist/api/client.js

@@ -6,11 +6,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ShabaasApiClient = void 0;
 const axios_1 = __importDefault(require("axios"));
 const index_js_1 = require("../config/index.js");
+/** Cache bearer token per API key so we don't refetch every request. */
+const tokenCache = new Map();
+const CACHE_TTL_MS = 50 * 60 * 1000; // 50 min
 class ShabaasApiClient {
     client;
     config;
-    bearerToken = null;
-    bearerTokenFetchedAtMs = null;
     constructor(config) {
         this.config = config;
         const baseURL = (0, index_js_1.getApiUrl)(config);
@@ -18,12 +19,17 @@ class ShabaasApiClient {
             baseURL,
             headers: {
                 'Content-Type': 'application/json',
+                // Identify requests as coming from the MCP server so the backend
+                'X-Shabaas-Client': 'mcp',
             },
             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}`);
+            if (process.env.MCP_DEBUG === '1' || process.env.SHABAAS_DEBUG_HEADERS === '1') {
+                console.error(`[API Request] X-Shabaas-Client: ${cfg.headers['X-Shabaas-Client'] ?? '(not set)'}`);
+            }
             return cfg;
         }, (error) => {
             console.error('[API Request Error]', error);
@@ -49,14 +55,24 @@ class ShabaasApiClient {
             : `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.
+     * Returns a bearer token for backend API calls. Use the API key from the request (Authorization header).
+     * No .env or global API key; requestUuid must be provided by the caller (value is the API key from the authenticated request).
+     * The backend accepts API key only.
      */
-    async authorize() {
+    async getTokenForRequest(requestUuid) {
+        const apiKey = (requestUuid ?? this.config.shabaasAuthUuid ?? '').trim();
+        if (!apiKey) {
+            throw new Error('Backend API auth requires the API key. Send it in the Authorization header (Bearer <your_api_key>) when calling the MCP server.');
+        }
+        const cacheKey = apiKey;
+        const cached = tokenCache.get(cacheKey);
+        if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+            return cached.token;
+        }
+        const authHeader = apiKey.toLowerCase().startsWith('bearer ') ? apiKey : `Bearer ${apiKey}`;
         const response = await this.client.post('/api/public/authorization', null, {
             headers: {
-                Authorization: this.config.shabaasAuthUuid,
+                Authorization: authHeader,
                 accept: 'application/json',
             },
         });
@@ -71,81 +87,81 @@ class ShabaasApiClient {
             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) {
+        tokenCache.set(cacheKey, { token, fetchedAt: Date.now() });
+        return token;
+    }
+    async withAuthRetry(fn, requestUuid) {
         try {
-            await this.ensureAuthenticated();
-            return await fn();
+            const token = await this.getTokenForRequest(requestUuid);
+            return await fn(token);
         }
         catch (err) {
             const status = err?.response?.status;
-            if (status === 401 || status === 403) {
-                await this.authorize();
-                return await fn();
+            if ((status === 401 || status === 403) && requestUuid) {
+                tokenCache.delete((requestUuid ?? '').trim());
+                const token = await this.getTokenForRequest(requestUuid);
+                return await fn(token);
             }
             throw err;
         }
     }
-    async getAuthToken() {
-        const { token } = await this.authorize();
+    async getAuthToken(options) {
+        const token = await this.getTokenForRequest(options?.requestUuid);
         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)}`);
+    async getPaymentAgreement(id, options) {
+        return await this.withAuthRetry(async (token) => {
+            const response = await this.client.get(`/api/public/payment_agreement?id=${encodeURIComponent(id)}`, { headers: { Authorization: token } });
             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,
-                },
+        }, options?.requestUuid);
+    }
+    async createPaymentAgreement(data, options) {
+        return await this.withAuthRetry(async (token) => {
+            const pa = {
+                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,
             };
+            if (data.phone_number != null)
+                pa.phone_number = data.phone_number;
+            if (data.bsb != null)
+                pa.bsb = data.bsb;
+            if (data.account_number != null)
+                pa.account_number = data.account_number;
+            if (data.agreement_type != null)
+                pa.agreement_type = data.agreement_type;
+            if (data.start_date != null)
+                pa.start_date = data.start_date;
+            if (data.end_date != null)
+                pa.end_date = data.end_date;
+            const body = { payment_agreement: pa };
             const response = await this.client.post('/api/public/payment_agreement', body, {
                 headers: {
-                    'Idempotency-Key': data.idempotency_key,
+                    Authorization: token,
                 },
             });
             return response.data;
-        });
+        }, options?.requestUuid);
     }
-    async cancelPaymentAgreement(id) {
-        return await this.withAuthRetry(async () => {
-            const response = await this.client.delete(`/api/public/payment_agreement/cancel?id=${encodeURIComponent(id)}`);
+    async cancelPaymentAgreement(id, options) {
+        return await this.withAuthRetry(async (token) => {
+            const response = await this.client.delete(`/api/public/payment_agreement/cancel?id=${encodeURIComponent(id)}`, { headers: { Authorization: token } });
             return response.data;
-        });
+        }, options?.requestUuid);
     }
-    async resendPaymentAgreement(id) {
-        return await this.withAuthRetry(async () => {
-            const response = await this.client.patch('/api/public/payment_agreement/resend', { id });
+    async resendPaymentAgreement(id, options) {
+        return await this.withAuthRetry(async (token) => {
+            const response = await this.client.patch('/api/public/payment_agreement/resend', { id }, {
+                headers: { Authorization: token },
+            });
             return response.data;
-        });
+        }, options?.requestUuid);
     }
-    async initiatePayment(data) {
-        return await this.withAuthRetry(async () => {
+    async initiatePayment(data, options) {
+        return await this.withAuthRetry(async (token) => {
             const amount = normalizeAmount(data.amount);
             const response = await this.client.post('/api/public/payment_initiation', {
                 payment_initiation: {
@@ -155,20 +171,22 @@ class ShabaasApiClient {
                 },
             }, {
                 headers: {
-                    'Idempotency-Key': data.idempotency_key,
+                    Authorization: token,
                 },
+                // Backend may call Monoova and can take up to Rack timeout (60s); use 65s so we get Rails response
+                timeout: 65000,
             });
             return response.data;
-        });
+        }, options?.requestUuid);
     }
-    async getPaymentInitiation(id) {
-        return await this.withAuthRetry(async () => {
-            const response = await this.client.get(`/api/public/payment_initiation?id=${encodeURIComponent(id)}`);
+    async getPaymentInitiation(id, options) {
+        return await this.withAuthRetry(async (token) => {
+            const response = await this.client.get(`/api/public/payment_initiation?id=${encodeURIComponent(id)}`, { headers: { Authorization: token } });
             return response.data;
-        });
+        }, options?.requestUuid);
     }
-    async initiateDirectDebit(data) {
-        return await this.withAuthRetry(async () => {
+    async initiateDirectDebit(data, options) {
+        return await this.withAuthRetry(async (token) => {
             const amount = normalizeAmount(data.amount);
             const response = await this.client.post('/api/public/payment_initiation/direct_debit', {
                 payment_initiation: {
@@ -178,29 +196,35 @@ class ShabaasApiClient {
                 },
             }, {
                 headers: {
-                    'Idempotency-Key': data.idempotency_key,
+                    Authorization: token,
                 },
             });
             return response.data;
-        });
+        }, options?.requestUuid);
     }
-    async getPaymentLink(data) {
-        return await this.withAuthRetry(async () => {
-            const response = await this.client.post('/api/get_url', data);
+    async getPaymentLink(data, options) {
+        return await this.withAuthRetry(async (token) => {
+            const response = await this.client.post('/api/get_url', data, {
+                headers: { Authorization: token },
+            });
             return response.data;
-        });
+        }, options?.requestUuid);
     }
-    async registerWebhook(data) {
-        return await this.withAuthRetry(async () => {
-            const response = await this.client.post('/api/public/webhooks', data);
+    async registerWebhook(data, options) {
+        return await this.withAuthRetry(async (token) => {
+            const response = await this.client.post('/api/public/webhooks', data, {
+                headers: { Authorization: token },
+            });
             return response.data;
-        });
+        }, options?.requestUuid);
     }
-    async listWebhooks() {
-        return await this.withAuthRetry(async () => {
-            const response = await this.client.get('/api/public/webhooks');
+    async listWebhooks(options) {
+        return await this.withAuthRetry(async (token) => {
+            const response = await this.client.get('/api/public/webhooks', {
+                headers: { Authorization: token },
+            });
             return response.data;
-        });
+        }, options?.requestUuid);
     }
 }
 exports.ShabaasApiClient = ShabaasApiClient;

package/dist/api/mcp-auth.d.ts

@@ -0,0 +1,18 @@
+import type { ClientPolicy } from '../security/policy.js';
+export type FetchPolicyResult = {
+    policy: ClientPolicy;
+    rejection?: undefined;
+} | {
+    policy?: undefined;
+    rejection: string;
+};
+/**
+ * Returns policy for the given token, using in-memory cache when ttlMs > 0.
+ * On cache miss or when ttlMs <= 0, calls the backend. Only successful results are cached.
+ */
+export declare function getPolicyWithCache(token: string, baseUrl: string, environment: 'sandbox' | 'production', ttlMs: number): Promise<FetchPolicyResult>;
+/**
+ * Calls backend GET /api/mcp/auth with Bearer token (API key); returns policy or rejection.
+ * The backend looks up the user by API key only.
+ */
+export declare function fetchPolicyFromBackend(token: string, baseUrl: string, environment: 'sandbox' | 'production'): Promise<FetchPolicyResult>;

package/dist/api/mcp-auth.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPolicyWithCache = getPolicyWithCache;
+exports.fetchPolicyFromBackend = fetchPolicyFromBackend;
+const policyCache = new Map();
+function policyCacheKey(token, baseUrl, environment) {
+    return `${token.trim()}\u0000${baseUrl}\u0000${environment}`;
+}
+/**
+ * Returns policy for the given token, using in-memory cache when ttlMs > 0.
+ * On cache miss or when ttlMs <= 0, calls the backend. Only successful results are cached.
+ */
+async function getPolicyWithCache(token, baseUrl, environment, ttlMs) {
+    if (ttlMs <= 0) {
+        return fetchPolicyFromBackend(token, baseUrl, environment);
+    }
+    const key = policyCacheKey(token, baseUrl, environment);
+    const cached = policyCache.get(key);
+    if (cached) {
+        if (cached.expiresAt > Date.now()) {
+            return { policy: cached.policy };
+        }
+        policyCache.delete(key);
+    }
+    const result = await fetchPolicyFromBackend(token, baseUrl, environment);
+    if (result.policy) {
+        policyCache.set(key, {
+            policy: result.policy,
+            expiresAt: Date.now() + ttlMs,
+        });
+    }
+    return result;
+}
+/**
+ * Calls backend GET /api/mcp/auth with Bearer token (API key); returns policy or rejection.
+ * The backend looks up the user by API key only.
+ */
+async function fetchPolicyFromBackend(token, baseUrl, environment) {
+    const url = `${baseUrl.replace(/\/$/, '')}/api/mcp/auth`;
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok) {
+            return { rejection: response.status === 401 ? 'unknown_client' : 'policy_load_failed' };
+        }
+        const data = (await response.json());
+        if (!data || !Array.isArray(data.allowed_tools)) {
+            return { rejection: 'invalid_response' };
+        }
+        const policy = {
+            client_id: token,
+            status: 'active',
+            allowed_tools: data.allowed_tools,
+            environment,
+            admin: false,
+        };
+        return { policy };
+    }
+    catch {
+        return { rejection: 'policy_load_failed' };
+    }
+}

package/dist/config/index.d.ts

@@ -1,16 +1,13 @@
 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
+ * - Backend URLs are derived from environment in code (canonical URLs); no need to set in env/config.
+ * - Override only when needed (e.g. local dev: SHABAAS_SANDBOX_URL=http://localhost:3000).
+ * - Auth uses the API key from each request (Authorization header).
  */
 declare const ConfigSchema: z.ZodObject<{
     environment: z.ZodDefault<z.ZodEnum<["sandbox", "production"]>>;
-    shabaasAuthUuid: z.ZodString;
+    shabaasAuthUuid: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     sandboxUrl: z.ZodDefault<z.ZodString>;
     productionUrl: z.ZodDefault<z.ZodString>;
     httpPort: z.ZodDefault<z.ZodNumber>;
@@ -21,6 +18,7 @@ declare const ConfigSchema: z.ZodObject<{
     rateLimitPerMinute: z.ZodDefault<z.ZodNumber>;
     rateLimitPerHour: z.ZodDefault<z.ZodNumber>;
     authTokenMaxAgeMinutes: z.ZodDefault<z.ZodNumber>;
+    policyCacheTtlMs: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     environment: "sandbox" | "production";
     shabaasAuthUuid: string;
@@ -34,9 +32,10 @@ declare const ConfigSchema: z.ZodObject<{
     rateLimitPerMinute: number;
     rateLimitPerHour: number;
     authTokenMaxAgeMinutes: number;
+    policyCacheTtlMs: number;
 }, {
-    shabaasAuthUuid: string;
     environment?: "sandbox" | "production" | undefined;
+    shabaasAuthUuid?: string | undefined;
     sandboxUrl?: string | undefined;
     productionUrl?: string | undefined;
     httpPort?: number | undefined;
@@ -47,6 +46,7 @@ declare const ConfigSchema: z.ZodObject<{
     rateLimitPerMinute?: number | undefined;
     rateLimitPerHour?: number | undefined;
     authTokenMaxAgeMinutes?: number | undefined;
+    policyCacheTtlMs?: number | undefined;
 }>;
 export type Config = z.infer<typeof ConfigSchema>;
 export declare function loadConfig(): Config;

package/dist/config/index.js

@@ -1,31 +1,25 @@
 "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();
+const backend_urls_js_1 = require("../constants/backend-urls.js");
+// No .env file is loaded; use process.env (e.g. from mcp.json or shell) or defaults.
 /**
  * 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
+ * - Backend URLs are derived from environment in code (canonical URLs); no need to set in env/config.
+ * - Override only when needed (e.g. local dev: SHABAAS_SANDBOX_URL=http://localhost:3000).
+ * - Auth uses the API key from each request (Authorization header).
  */
 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),
+    // Optional fallback when request does not provide API key (e.g. legacy); normally leave empty. Value is treated as API key.
+    shabaasAuthUuid: zod_1.z.string().optional().default(''),
+    // Backend API base URLs: default to canonical URLs from code; override via env only for local/dev
+    sandboxUrl: zod_1.z.string().url().default(backend_urls_js_1.CANONICAL_SANDBOX_BASE_URL),
+    productionUrl: zod_1.z.string().url().default(backend_urls_js_1.CANONICAL_PRODUCTION_BASE_URL),
+    // HTTP mode: MCP server port (default 3001 so it does not conflict with backend on 3000)
+    httpPort: zod_1.z.coerce.number().default(3001),
     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(''),
@@ -38,6 +32,8 @@ const ConfigSchema = zod_1.z.object({
     // 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),
+    // Policy cache: TTL in ms for in-memory MCP policy cache. If 0, policy is not cached and backend is called every time.
+    policyCacheTtlMs: zod_1.z.coerce.number().default(300_000),
 });
 function loadConfig() {
     try {
@@ -57,6 +53,7 @@ function loadConfig() {
             rateLimitPerMinute: process.env.API_RATE_LIMIT_PER_MINUTE,
             rateLimitPerHour: process.env.API_RATE_LIMIT_PER_HOUR,
             authTokenMaxAgeMinutes: process.env.AUTH_TOKEN_MAX_AGE_MINUTES,
+            policyCacheTtlMs: process.env.MCP_POLICY_CACHE_TTL_MS || process.env.POLICY_CACHE_TTL_MS,
         });
     }
     catch (error) {

package/dist/constants/backend-urls.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Canonical backend base URLs by environment (code-only; single source of truth).
+ * Used when SHABAAS_SANDBOX_URL / SHABAAS_PRODUCTION_URL are not set in env,
+ * so the backend URL does not need to be exposed in config or Cloudflare vars.
+ * Override via env only when needed (e.g. local dev: SHABAAS_SANDBOX_URL=http://localhost:3000).
+ */
+export declare const CANONICAL_SANDBOX_BASE_URL = "https://dev-api.shabaas.com";
+export declare const CANONICAL_PRODUCTION_BASE_URL = "https://api.shabaas.com";

package/dist/constants/backend-urls.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANONICAL_PRODUCTION_BASE_URL = exports.CANONICAL_SANDBOX_BASE_URL = void 0;
+/**
+ * Canonical backend base URLs by environment (code-only; single source of truth).
+ * Used when SHABAAS_SANDBOX_URL / SHABAAS_PRODUCTION_URL are not set in env,
+ * so the backend URL does not need to be exposed in config or Cloudflare vars.
+ * Override via env only when needed (e.g. local dev: SHABAAS_SANDBOX_URL=http://localhost:3000).
+ */
+exports.CANONICAL_SANDBOX_BASE_URL = 'https://dev-api.shabaas.com';
+exports.CANONICAL_PRODUCTION_BASE_URL = 'https://api.shabaas.com';

package/dist/enricher/index.d.ts

@@ -1,2 +1,4 @@
 import { PaymentAgreement, StandardResponse } from "../types/index.js";
 export declare function enrichPaymentAgreement(data: PaymentAgreement, includeRaw: boolean, rawResponse: any, environment: "sandbox" | "production"): StandardResponse<PaymentAgreement>;
+/** Shared enricher for payment initiation (get_payment_initiation and initiate_payment). */
+export declare function enrichPaymentInitiation(data: any, raw: any, processingTime: number, environment: "sandbox" | "production", mode: "initiate" | "retrieve"): StandardResponse<any>;