@naturalpay/sdk 0.0.3 → 0.0.5

package/dist/mcp/cli.cjs

@@ -213,6 +213,22 @@ function logToolCall(logger4, toolName, options) {
     logger4.info(`Tool call: ${toolName}`, extra);
   }
 }
+var toolCallStorage = new async_hooks.AsyncLocalStorage();
+function getToolCallHeader() {
+  const data = toolCallStorage.getStore();
+  if (!data) return void 0;
+  return btoa(JSON.stringify(data));
+}
+function runWithToolCall(name, args, fn) {
+  return toolCallStorage.run(
+    {
+      tool: name,
+      arguments: args,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    fn
+  );
+}
 
 // src/http.ts
 var logger = getLogger("http");
@@ -446,9 +462,15 @@ var HTTPClient = class {
       const headers = {
         Authorization: `Bearer ${jwt}`,
         "Content-Type": "application/json",
-        "User-Agent": `naturalpay-ts/${SDK_VERSION2}`,
-        ...options?.headers
+        "User-Agent": `naturalpay-ts/${SDK_VERSION2}`
       };
+      const toolCallHeader = getToolCallHeader();
+      if (toolCallHeader) {
+        headers["X-Tool-Call"] = toolCallHeader;
+      }
+      if (options?.headers) {
+        Object.assign(headers, options.headers);
+      }
       const response = await fetch(url, {
         method,
         headers,
@@ -564,9 +586,16 @@ var PaymentsResource = class extends BaseResource {
     };
     if (params.memo) attributes["description"] = params.memo;
     const body = { data: { attributes } };
+    const headers = { "Idempotency-Key": idempotencyKey };
+    if (params.agentId) {
+      headers["X-Agent-ID"] = params.agentId;
+    }
+    if (params.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
     const response = await this.http.post("/payments", {
       body,
-      headers: { "Idempotency-Key": idempotencyKey }
+      headers
     });
     return unwrapPayment(response);
   }
@@ -576,8 +605,14 @@ var PaymentsResource = class extends BaseResource {
    * @param transferId - The transfer ID to look up
    * @returns Payment object with current status
    */
-  async retrieve(transferId) {
-    const response = await this.http.get(`/payments/${transferId}`);
+  async retrieve(transferId, options) {
+    const headers = {};
+    if (options?.instanceId) {
+      headers["X-Instance-ID"] = options.instanceId;
+    }
+    const response = await this.http.get(`/payments/${transferId}`, {
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
     return unwrapPayment(response);
   }
 };
@@ -603,14 +638,71 @@ function unwrapBalance(response) {
     pendingClaimCount: attributes.pendingClaimCount != null ? Number(attributes.pendingClaimCount) : void 0
   };
 }
+function unwrapDeposit(response) {
+  if (!response?.data) {
+    throw new NaturalError('Unexpected response format: missing "data" field in deposit response');
+  }
+  const { data } = response;
+  if (data.type !== "deposit" || !data.attributes) {
+    throw new NaturalError(
+      `Unexpected resource format: expected type "deposit", got "${data.type}"`
+    );
+  }
+  const { id, attributes } = data;
+  return {
+    transferId: id ?? void 0,
+    status: String(attributes.status),
+    amount: attributes.amount != null ? String(attributes.amount) : "",
+    currency: String(attributes.currency),
+    estimatedSettlement: attributes.estimatedSettlement != null ? String(attributes.estimatedSettlement) : void 0,
+    error: attributes.error != null ? String(attributes.error) : void 0,
+    errorDetails: attributes.errorDetails != null ? String(attributes.errorDetails) : void 0
+  };
+}
+function unwrapWithdrawal(response) {
+  if (!response?.data) {
+    throw new NaturalError(
+      'Unexpected response format: missing "data" field in withdrawal response'
+    );
+  }
+  const { data } = response;
+  if (data.type !== "withdrawal" || !data.attributes) {
+    throw new NaturalError(
+      `Unexpected resource format: expected type "withdrawal", got "${data.type}"`
+    );
+  }
+  const { id, attributes } = data;
+  return {
+    transferId: id ?? void 0,
+    instructionId: attributes.instructionId != null ? String(attributes.instructionId) : void 0,
+    status: String(attributes.status),
+    amount: attributes.amount != null ? String(attributes.amount) : "",
+    currency: String(attributes.currency),
+    estimatedSettlement: attributes.estimatedSettlement != null ? String(attributes.estimatedSettlement) : void 0,
+    kycRequired: Boolean(attributes.kycRequired),
+    kycStatus: attributes.kycStatus != null ? String(attributes.kycStatus) : void 0,
+    kycSessionUrl: attributes.kycSessionUrl != null ? String(attributes.kycSessionUrl) : void 0,
+    mfaRequired: Boolean(attributes.mfaRequired),
+    mfaChallengeId: attributes.mfaChallengeId != null ? String(attributes.mfaChallengeId) : void 0,
+    mfaExpiresAt: attributes.mfaExpiresAt != null ? String(attributes.mfaExpiresAt) : void 0,
+    error: attributes.error != null ? String(attributes.error) : void 0,
+    errorDetails: attributes.errorDetails != null ? String(attributes.errorDetails) : void 0
+  };
+}
 var WalletResource = class extends BaseResource {
   /**
    * Get current wallet balance.
    *
    * @returns AccountBalance with available, current, pending amounts
    */
-  async balance() {
-    const response = await this.http.get("/wallet/balance");
+  async balance(options) {
+    const headers = {};
+    if (options?.instanceId) {
+      headers["X-Instance-ID"] = options.instanceId;
+    }
+    const response = await this.http.get("/wallet/balance", {
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
     return unwrapBalance(response);
   }
   /**
@@ -620,18 +712,20 @@ var WalletResource = class extends BaseResource {
    * @returns DepositResponse with transfer status
    */
   async deposit(params) {
-    const body = {
+    const attributes = {
       amount: params.amount,
       currency: params.currency ?? "USD",
       paymentInstrumentId: params.paymentInstrumentId
     };
     if (params.description) {
-      body["description"] = params.description;
+      attributes["description"] = params.description;
     }
-    return this.http.post("/wallet/deposit", {
+    const body = { data: { attributes } };
+    const response = await this.http.post("/wallet/deposit", {
       body,
       headers: { "Idempotency-Key": params.idempotencyKey }
     });
+    return unwrapDeposit(response);
   }
   /**
    * Initiate a withdrawal to a linked bank account.
@@ -640,21 +734,19 @@ var WalletResource = class extends BaseResource {
    * @returns WithdrawResponse with transfer status (may require KYC/MFA)
    */
   async withdraw(params) {
-    const body = {
+    const attributes = {
       amount: params.amount,
       currency: params.currency ?? "USD",
       paymentInstrumentId: params.paymentInstrumentId
     };
-    if (params.description) {
-      body["description"] = params.description;
-    }
-    if (params.walletId) {
-      body["walletId"] = params.walletId;
-    }
-    return this.http.post("/wallet/withdraw", {
+    if (params.description) attributes["description"] = params.description;
+    if (params.walletId) attributes["walletId"] = params.walletId;
+    const body = { data: { attributes } };
+    const response = await this.http.post("/wallet/withdraw", {
       body,
       headers: { "Idempotency-Key": params.idempotencyKey }
     });
+    return unwrapWithdrawal(response);
   }
 };
 
@@ -704,6 +796,9 @@ var TransactionsResource = class extends BaseResource {
     if (params?.customerPartyId) {
       headers["X-On-Behalf-Of"] = params.customerPartyId;
     }
+    if (params?.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
     const response = await this.http.get("/transactions", {
       params: {
         limit: params?.limit ?? 50,
@@ -775,13 +870,18 @@ var AgentsResource = class extends BaseResource {
    * @returns AgentListResponse with list of agents
    */
   async list(params) {
+    const headers = {};
+    if (params?.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
     const response = await this.http.get("/agents", {
       params: {
         status: params?.status,
         partyId: params?.partyId,
         limit: params?.limit ?? 50,
         cursor: params?.cursor
-      }
+      },
+      headers: Object.keys(headers).length > 0 ? headers : void 0
     });
     return unwrapAgentList(response);
   }
@@ -856,6 +956,52 @@ var AgentsResource = class extends BaseResource {
 };
 
 // src/resources/delegations.ts
+function unwrapDelegationResource(resource) {
+  if (resource.type !== "delegation" || !resource.attributes) {
+    throw new NaturalError(
+      `Unexpected resource format: expected type "delegation", got "${resource.type}"`
+    );
+  }
+  const { id, attributes, relationships } = resource;
+  return {
+    id,
+    delegatingPartyId: relationships?.delegatingParty?.data?.id ?? "",
+    delegatedPartyId: relationships?.delegatedParty?.data?.id ?? "",
+    delegatingPartyName: attributes.delegatingPartyName != null ? String(attributes.delegatingPartyName) : void 0,
+    delegatedPartyName: attributes.delegatedPartyName != null ? String(attributes.delegatedPartyName) : void 0,
+    delegatingPartyEmail: attributes.delegatingPartyEmail != null ? String(attributes.delegatingPartyEmail) : void 0,
+    delegatedPartyEmail: attributes.delegatedPartyEmail != null ? String(attributes.delegatedPartyEmail) : void 0,
+    permissions: Array.isArray(attributes.permissions) ? attributes.permissions : [],
+    sourceType: attributes.sourceType != null ? String(attributes.sourceType) : void 0,
+    sourceId: attributes.sourceId != null ? String(attributes.sourceId) : void 0,
+    expiresAt: attributes.expiresAt != null ? String(attributes.expiresAt) : void 0,
+    status: String(attributes.status),
+    createdAt: String(attributes.createdAt),
+    createdBy: attributes.createdBy != null ? String(attributes.createdBy) : void 0
+  };
+}
+function unwrapDelegation(response) {
+  if (!response?.data) {
+    throw new NaturalError(
+      'Unexpected response format: missing "data" field in delegation response'
+    );
+  }
+  return unwrapDelegationResource(response.data);
+}
+function unwrapDelegationList(response) {
+  if (!response?.data || !Array.isArray(response.data)) {
+    throw new NaturalError(
+      'Unexpected response format: missing "data" array in delegation list response'
+    );
+  }
+  const delegations = response.data.map(unwrapDelegationResource);
+  const pagination = response.meta?.pagination ?? {};
+  return {
+    delegations,
+    hasMore: pagination.hasMore ?? false,
+    nextCursor: pagination.nextCursor ?? null
+  };
+}
 var DelegationsResource = class extends BaseResource {
   /**
    * List delegations with optional filters.
@@ -864,7 +1010,7 @@ var DelegationsResource = class extends BaseResource {
    * @returns DelegationListResponse with list of delegations
    */
   async list(params) {
-    return this.http.get("/delegations", {
+    const response = await this.http.get("/delegations", {
       params: {
         status: params?.status,
         delegatingPartyId: params?.delegatingPartyId,
@@ -873,6 +1019,7 @@ var DelegationsResource = class extends BaseResource {
         cursor: params?.cursor
       }
     });
+    return unwrapDelegationList(response);
   }
   /**
    * Get delegation by ID.
@@ -881,7 +1028,8 @@ var DelegationsResource = class extends BaseResource {
    * @returns Delegation details
    */
   async get(delegationId) {
-    return this.http.get(`/delegations/${delegationId}`);
+    const response = await this.http.get(`/delegations/${delegationId}`);
+    return unwrapDelegation(response);
   }
   /**
    * Update an existing delegation.
@@ -891,11 +1039,15 @@ var DelegationsResource = class extends BaseResource {
    * @returns Updated Delegation
    */
   async update(delegationId, params) {
-    const body = {};
-    if (params.status !== void 0) body["status"] = params.status;
-    if (params.permissions !== void 0) body["permissions"] = params.permissions;
-    if (params.expiresAt !== void 0) body["expiresAt"] = params.expiresAt;
-    return this.http.put(`/delegations/${delegationId}`, { body });
+    const attributes = {};
+    if (params.status !== void 0) attributes["status"] = params.status;
+    if (params.permissions !== void 0) attributes["permissions"] = params.permissions;
+    if (params.expiresAt !== void 0) attributes["expiresAt"] = params.expiresAt;
+    const body = { data: { attributes } };
+    const response = await this.http.put(`/delegations/${delegationId}`, {
+      body
+    });
+    return unwrapDelegation(response);
   }
   /**
    * Revoke a delegation (soft delete by setting status to REVOKED).
@@ -909,6 +1061,41 @@ var DelegationsResource = class extends BaseResource {
 };
 
 // src/resources/customers.ts
+function unwrapCustomerResource(resource) {
+  if (resource.type !== "customer" || !resource.attributes) {
+    throw new NaturalError(
+      `Unexpected resource format: expected type "customer", got "${resource.type}"`
+    );
+  }
+  const { id, attributes, relationships } = resource;
+  return {
+    party: {
+      id,
+      type: String(attributes.partyType),
+      legalName: attributes.legalName != null ? String(attributes.legalName) : void 0,
+      displayName: attributes.displayName != null ? String(attributes.displayName) : void 0,
+      status: attributes.partyStatus != null ? String(attributes.partyStatus) : void 0
+    },
+    delegationId: relationships?.delegation?.data?.id ?? "",
+    permissions: Array.isArray(attributes.permissions) ? attributes.permissions : [],
+    delegationStatus: String(attributes.delegationStatus),
+    createdAt: String(attributes.createdAt)
+  };
+}
+function unwrapCustomerList(response) {
+  if (!response?.data || !Array.isArray(response.data)) {
+    throw new NaturalError(
+      'Unexpected response format: missing "data" array in customer list response'
+    );
+  }
+  const items = response.data.map(unwrapCustomerResource);
+  const pagination = response.meta?.pagination ?? {};
+  return {
+    items,
+    hasMore: pagination.hasMore ?? false,
+    nextCursor: pagination.nextCursor ?? null
+  };
+}
 var CustomersResource = class extends BaseResource {
   /**
    * List customers onboarded by the partner via delegation.
@@ -917,12 +1104,13 @@ var CustomersResource = class extends BaseResource {
    * @returns CustomerListResponse with items, hasMore, nextCursor
    */
   async list(params) {
-    return this.http.get("/customers", {
+    const response = await this.http.get("/customers", {
       params: {
         limit: params?.limit,
         cursor: params?.cursor
       }
     });
+    return unwrapCustomerList(response);
   }
 };
 
@@ -962,7 +1150,8 @@ var NaturalClient = class {
 
 // src/mcp/server.ts
 var logger2 = getLogger("mcp.server");
-function createServer(apiKey) {
+function createServer(apiKeyOrOptions) {
+  const options = typeof apiKeyOrOptions === "string" ? { apiKey: apiKeyOrOptions } : apiKeyOrOptions ?? {};
   logger2.info("Creating Natural Payments MCP server");
   const server = new fastmcp.FastMCP({
     name: "Natural Payments",
@@ -971,7 +1160,7 @@ function createServer(apiKey) {
   let client = null;
   const getClient = () => {
     if (!client) {
-      client = new NaturalClient({ apiKey });
+      client = new NaturalClient({ apiKey: options.apiKey });
     }
     return client;
   };
@@ -982,11 +1171,13 @@ function createServer(apiKey) {
       amount: zod.z.number().positive().describe("Payment amount"),
       memo: zod.z.string().describe("Payment memo (required)"),
       customerPartyId: zod.z.string().describe("Customer party ID on whose behalf (pty_xxx)"),
+      agentId: zod.z.string().optional().describe("Agent ID (agt_xxx) for agent-initiated payments"),
       recipientEmail: zod.z.string().email().optional().describe("Recipient email address"),
       recipientPhone: zod.z.string().optional().describe("Recipient phone number"),
-      recipientPartyId: zod.z.string().optional().describe("Recipient party ID (pty_xxx)")
+      recipientPartyId: zod.z.string().optional().describe("Recipient party ID (pty_xxx)"),
+      instanceId: zod.z.string().optional().describe("Developer's session/conversation ID for observability grouping")
     }),
-    execute: async (args) => {
+    execute: async (args) => runWithToolCall("create_payment", args, async () => {
       const startTime = Date.now();
       try {
         const result = await getClient().payments.create({
@@ -995,7 +1186,9 @@ function createServer(apiKey) {
           recipientPartyId: args.recipientPartyId,
           amount: args.amount,
           memo: args.memo,
-          customerPartyId: args.customerPartyId
+          customerPartyId: args.customerPartyId,
+          agentId: args.agentId,
+          instanceId: args.instanceId
         });
         const durationMs = Date.now() - startTime;
         logToolCall(logger2, "create_payment", { success: true, durationMs });
@@ -1009,18 +1202,21 @@ function createServer(apiKey) {
         });
         throw error;
       }
-    }
+    })
   });
   server.addTool({
     name: "get_payment_status",
     description: "Check the status of a payment by transfer ID",
     parameters: zod.z.object({
-      transferId: zod.z.string().describe("The transfer ID returned from create_payment")
+      transferId: zod.z.string().describe("The transfer ID returned from create_payment"),
+      instanceId: zod.z.string().optional().describe("Developer's session/conversation ID for observability grouping")
     }),
-    execute: async (args) => {
+    execute: async (args) => runWithToolCall("get_payment_status", args, async () => {
       const startTime = Date.now();
       try {
-        const result = await getClient().payments.retrieve(args.transferId);
+        const result = await getClient().payments.retrieve(args.transferId, {
+          instanceId: args.instanceId
+        });
         const durationMs = Date.now() - startTime;
         logToolCall(logger2, "get_payment_status", { success: true, durationMs });
         return JSON.stringify(result, null, 2);
@@ -1033,16 +1229,18 @@ function createServer(apiKey) {
         });
         throw error;
       }
-    }
+    })
   });
   server.addTool({
     name: "get_account_balance",
     description: "Get the current wallet balance",
-    parameters: zod.z.object({}),
-    execute: async () => {
+    parameters: zod.z.object({
+      instanceId: zod.z.string().optional().describe("Developer's session/conversation ID for observability grouping")
+    }),
+    execute: async (args) => runWithToolCall("get_account_balance", args, async () => {
       const startTime = Date.now();
       try {
-        const result = await getClient().wallet.balance();
+        const result = await getClient().wallet.balance({ instanceId: args.instanceId });
         const balances = result.balances.map((bal) => ({
           assetCode: bal.assetCode,
           available: bal.available.amountDollars,
@@ -1073,7 +1271,7 @@ function createServer(apiKey) {
         });
         throw error;
       }
-    }
+    })
   });
   server.addTool({
     name: "list_transactions",
@@ -1082,16 +1280,18 @@ function createServer(apiKey) {
       limit: zod.z.number().min(1).max(100).default(50).describe("Maximum number of transactions"),
       cursor: zod.z.string().optional().describe("Pagination cursor from previous response"),
       agentId: zod.z.string().optional().describe("Agent ID for agent-context authentication"),
-      customerPartyId: zod.z.string().optional().describe("Customer party ID when acting on behalf of customer")
+      customerPartyId: zod.z.string().optional().describe("Customer party ID when acting on behalf of customer"),
+      instanceId: zod.z.string().optional().describe("Developer's session/conversation ID for observability grouping")
     }),
-    execute: async (args) => {
+    execute: async (args) => runWithToolCall("list_transactions", args, async () => {
       const startTime = Date.now();
       try {
         const result = await getClient().transactions.list({
           limit: args.limit,
           cursor: args.cursor,
           agentId: args.agentId,
-          customerPartyId: args.customerPartyId
+          customerPartyId: args.customerPartyId,
+          instanceId: args.instanceId
         });
         const durationMs = Date.now() - startTime;
         logToolCall(logger2, "list_transactions", { success: true, durationMs });
@@ -1105,21 +1305,23 @@ function createServer(apiKey) {
         });
         throw error;
       }
-    }
+    })
   });
   server.addTool({
     name: "list_agents",
     description: "List agents for the partner",
     parameters: zod.z.object({
       status: zod.z.enum(["ACTIVE", "REVOKED"]).optional().describe("Filter by status"),
-      limit: zod.z.number().min(1).max(100).default(50).describe("Maximum number of agents")
+      limit: zod.z.number().min(1).max(100).default(50).describe("Maximum number of agents"),
+      instanceId: zod.z.string().optional().describe("Developer's session/conversation ID for observability grouping")
     }),
-    execute: async (args) => {
+    execute: async (args) => runWithToolCall("list_agents", args, async () => {
       const startTime = Date.now();
       try {
         const result = await getClient().agents.list({
           status: args.status,
-          limit: args.limit
+          limit: args.limit,
+          instanceId: args.instanceId
         });
         const durationMs = Date.now() - startTime;
         logToolCall(logger2, "list_agents", { success: true, durationMs });
@@ -1133,7 +1335,7 @@ function createServer(apiKey) {
         });
         throw error;
       }
-    }
+    })
   });
   return server;
 }
@@ -1158,7 +1360,7 @@ mcpCommand.command("serve").description("Start the MCP server").option("-t, --tr
   if (options.serverUrl) {
     process.env["NATURAL_SERVER_URL"] = options.serverUrl;
   }
-  const server = createServer(options.apiKey);
+  const server = createServer({ apiKey: options.apiKey });
   if (options.transport === "stdio") {
     logger3.info("Running with stdio transport");
     server.start({ transportType: "stdio" });