@naturalpay/sdk 0.0.2

package/dist/index.cjs

@@ -0,0 +1,968 @@
+'use strict';
+
+var async_hooks = require('async_hooks');
+var crypto = require('crypto');
+
+// src/errors.ts
+var NaturalError = class extends Error {
+  statusCode;
+  code;
+  constructor(message, options) {
+    super(message);
+    this.name = "NaturalError";
+    this.statusCode = options?.statusCode;
+    this.code = options?.code;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var AuthenticationError = class extends NaturalError {
+  constructor(message = "Invalid or missing API key") {
+    super(message, { statusCode: 401, code: "authentication_error" });
+    this.name = "AuthenticationError";
+  }
+};
+var InvalidRequestError = class extends NaturalError {
+  constructor(message, code = "invalid_request") {
+    super(message, { statusCode: 400, code });
+    this.name = "InvalidRequestError";
+  }
+};
+var PaymentError = class extends NaturalError {
+  constructor(message, code = "payment_error") {
+    super(message, { statusCode: 400, code });
+    this.name = "PaymentError";
+  }
+};
+var InsufficientFundsError = class extends PaymentError {
+  constructor(message = "Insufficient funds") {
+    super(message, "insufficient_funds");
+    this.name = "InsufficientFundsError";
+  }
+};
+var RecipientNotFoundError = class extends PaymentError {
+  constructor(message = "Recipient not found") {
+    super(message, "recipient_not_found");
+    this.name = "RecipientNotFoundError";
+  }
+};
+var RateLimitError = class extends NaturalError {
+  retryAfter;
+  constructor(message = "Rate limit exceeded", retryAfter) {
+    super(message, { statusCode: 429, code: "rate_limit_exceeded" });
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ServerError = class extends NaturalError {
+  constructor(message = "Internal server error") {
+    super(message, { statusCode: 500, code: "server_error" });
+    this.name = "ServerError";
+  }
+};
+var SDK_VERSION = "0.0.1";
+var LOG_LEVEL_VALUES = {
+  debug: 10,
+  info: 20,
+  warning: 30,
+  error: 40
+};
+var asyncContext = new async_hooks.AsyncLocalStorage();
+var globalContext = {};
+function getContext() {
+  const asyncStore = asyncContext.getStore();
+  if (asyncStore) {
+    return { ...asyncStore };
+  }
+  return { ...globalContext };
+}
+function sanitizeString(value) {
+  let sanitized = "";
+  for (const char of value) {
+    if (char === "\r" || char === "\n") {
+      sanitized += "\\n";
+    } else if (char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127) {
+      sanitized += `\\x${char.charCodeAt(0).toString(16).padStart(2, "0")}`;
+    } else {
+      sanitized += char;
+    }
+  }
+  const maxLength = 1e3;
+  if (sanitized.length > maxLength) {
+    sanitized = sanitized.slice(0, maxLength) + "...[truncated]";
+  }
+  return sanitized;
+}
+function sanitizeLogValue(value, depth = 0) {
+  const maxDepth = 10;
+  if (depth > maxDepth) {
+    return "[max depth exceeded]";
+  }
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "string") {
+    return sanitizeString(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeLogValue(item, depth + 1));
+  }
+  if (typeof value === "object") {
+    const sanitized = {};
+    for (const [key, val] of Object.entries(value)) {
+      const sanitizedKey = sanitizeString(key);
+      sanitized[sanitizedKey] = sanitizeLogValue(val, depth + 1);
+    }
+    return sanitized;
+  }
+  return `[${typeof value}]`;
+}
+function bindContext(context) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(context)) {
+    sanitized[key] = sanitizeLogValue(value);
+  }
+  const asyncStore = asyncContext.getStore();
+  if (asyncStore) {
+    Object.assign(asyncStore, sanitized);
+  }
+  globalContext = { ...globalContext, ...sanitized };
+}
+function clearContext() {
+  const asyncStore = asyncContext.getStore();
+  if (asyncStore) {
+    for (const key of Object.keys(asyncStore)) {
+      delete asyncStore[key];
+    }
+  }
+  globalContext = {};
+}
+function runWithContext(context, fn) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(context)) {
+    sanitized[key] = sanitizeLogValue(value);
+  }
+  return asyncContext.run(sanitized, fn);
+}
+var loggingConfig = {
+  level: process.env["NATURAL_LOG_LEVEL"]?.toLowerCase() || "info",
+  jsonFormat: process.env["NATURAL_LOG_FORMAT"]?.toLowerCase() === "json",
+  serviceName: "naturalpay-sdk",
+  environment: process.env["NATURAL_ENV"] || process.env["DD_ENV"] || "development"
+};
+function configureLogging(options) {
+  if (options?.level) {
+    loggingConfig.level = options.level;
+  }
+  if (options?.jsonFormat !== void 0) {
+    loggingConfig.jsonFormat = options.jsonFormat;
+  }
+  if (options?.serviceName) {
+    loggingConfig.serviceName = options.serviceName;
+  }
+}
+function getSourceInfo() {
+  const stack = new Error().stack;
+  if (!stack) {
+    return { file: "unknown", line: 0, function: "unknown" };
+  }
+  const lines = stack.split("\n");
+  const callerLine = lines[4] || lines[3] || "";
+  const match = callerLine.match(/at\s+(?:(.+?)\s+\()?(.*?):(\d+):\d+\)?/);
+  if (match) {
+    return {
+      function: match[1] || "anonymous",
+      file: match[2] || "unknown",
+      line: parseInt(match[3] || "0", 10)
+    };
+  }
+  return { file: "unknown", line: 0, function: "unknown" };
+}
+function formatJsonLog(level, loggerName, message, extra) {
+  const record = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    level: level.toUpperCase(),
+    logger: loggerName,
+    message,
+    source: getSourceInfo(),
+    service: loggingConfig.serviceName,
+    environment: loggingConfig.environment,
+    version: SDK_VERSION,
+    ...getContext(),
+    ...extra
+  };
+  const ddTraceId = process.env["DD_TRACE_ID"];
+  const ddSpanId = process.env["DD_SPAN_ID"];
+  if (ddTraceId) {
+    record["dd.trace_id"] = ddTraceId;
+    record["dd.span_id"] = ddSpanId;
+    record["dd.service"] = loggingConfig.serviceName;
+    record["dd.version"] = SDK_VERSION;
+    record["dd.env"] = loggingConfig.environment;
+  }
+  return JSON.stringify(record);
+}
+function formatTextLog(level, loggerName, message, extra) {
+  const contextEntries = Object.entries({ ...getContext(), ...extra });
+  const contextStr = contextEntries.length > 0 ? ` [${contextEntries.map(([k, v]) => `${k}=${v}`).join(", ")}]` : "";
+  return `${level.toUpperCase().padEnd(8)} ${loggerName}: ${message}${contextStr}`;
+}
+var Logger = class {
+  constructor(name) {
+    this.name = name;
+  }
+  log(level, message, extra) {
+    if (LOG_LEVEL_VALUES[level] < LOG_LEVEL_VALUES[loggingConfig.level]) {
+      return;
+    }
+    const formatted = loggingConfig.jsonFormat ? formatJsonLog(level, this.name, message, extra) : formatTextLog(level, this.name, message, extra);
+    if (level === "error") {
+      console.error(formatted);
+    } else if (level === "warning") {
+      console.warn(formatted);
+    } else {
+      console.error(formatted);
+    }
+  }
+  debug(message, extra) {
+    this.log("debug", message, extra);
+  }
+  info(message, extra) {
+    this.log("info", message, extra);
+  }
+  warning(message, extra) {
+    this.log("warning", message, extra);
+  }
+  warn(message, extra) {
+    this.warning(message, extra);
+  }
+  error(message, extra) {
+    this.log("error", message, extra);
+  }
+};
+function getLogger(name) {
+  if (!name.startsWith("naturalpay")) {
+    name = `naturalpay.${name}`;
+  }
+  return new Logger(name);
+}
+function logError(logger2, message, options) {
+  const extra = { ...options };
+  if (options?.error) {
+    extra["errorType"] = options.error.name;
+    extra["errorMessage"] = options.error.message;
+    if (options.error.stack) {
+      extra["errorStack"] = options.error.stack.split("\n").slice(0, 5).join("\n");
+    }
+    delete extra["error"];
+  }
+  logger2.error(message, extra);
+}
+function logApiCall(logger2, method, path, options) {
+  const extra = {
+    method,
+    path,
+    ...options
+  };
+  if (options?.statusCode) {
+    extra["statusCode"] = options.statusCode;
+  }
+  if (options?.durationMs !== void 0) {
+    extra["durationMs"] = Math.round(options.durationMs * 100) / 100;
+  }
+  if (options?.error) {
+    logError(logger2, `API call failed: ${method} ${path}`, extra);
+  } else if (options?.statusCode && options.statusCode >= 400) {
+    logger2.warning(`API call error: ${method} ${path} -> ${options.statusCode}`, extra);
+  } else {
+    logger2.info(`API call: ${method} ${path} -> ${options?.statusCode}`, extra);
+  }
+}
+function logToolCall(logger2, toolName, options) {
+  const extra = {
+    toolName,
+    ...options
+  };
+  if (options?.durationMs !== void 0) {
+    extra["durationMs"] = Math.round(options.durationMs * 100) / 100;
+  }
+  if (options?.error) {
+    logError(logger2, `Tool call failed: ${toolName}`, extra);
+  } else if (options?.success === false) {
+    logger2.warning(`Tool call returned error: ${toolName}`, extra);
+  } else {
+    logger2.info(`Tool call: ${toolName}`, extra);
+  }
+}
+
+// src/http.ts
+var logger = getLogger("http");
+var DEFAULT_BASE_URL = "https://api.natural.co";
+var DEFAULT_TIMEOUT = 3e4;
+var SDK_VERSION2 = "0.0.1";
+function hashString(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(16).slice(0, 16);
+}
+function snakeToCamel(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(snakeToCamel);
+  }
+  if (typeof obj === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      const camelKey = key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+      result[camelKey] = snakeToCamel(value);
+    }
+    return result;
+  }
+  return obj;
+}
+function camelToSnake(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(camelToSnake);
+  }
+  if (typeof obj === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      const snakeKey = key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+      result[snakeKey] = camelToSnake(value);
+    }
+    return result;
+  }
+  return obj;
+}
+var HTTPClient = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  jwtCache = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    this.apiKey = options.apiKey ?? process.env["NATURAL_API_KEY"] ?? "";
+    this.baseUrl = (options.baseUrl ?? process.env["NATURAL_SERVER_URL"] ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  }
+  /**
+   * Get a cached JWT or exchange API key for a new one.
+   */
+  async getJwt() {
+    if (!this.apiKey) {
+      throw new AuthenticationError();
+    }
+    if (!this.apiKey.startsWith("pk_")) {
+      return this.apiKey;
+    }
+    const cacheKey = hashString(this.apiKey);
+    const cached = this.jwtCache.get(cacheKey);
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.token;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    logger.debug("Exchanging API key for JWT", { path: "/auth/partner/token" });
+    try {
+      const response = await fetch(`${this.baseUrl}/auth/partner/token`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const authError = new AuthenticationError(
+          `Authentication failed (status=${response.status})`
+        );
+        logError(logger, "JWT exchange failed", {
+          error: authError,
+          statusCode: response.status,
+          path: "/auth/partner/token"
+        });
+        throw authError;
+      }
+      const data = await response.json();
+      const expiresIn = data.expires_in ?? 900;
+      const expiresAt = Date.now() + (expiresIn - 30) * 1e3;
+      this.jwtCache.set(cacheKey, { token: data.access_token, expiresAt });
+      return data.access_token;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof AuthenticationError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        const networkError2 = new NaturalError("Request timed out during authentication");
+        logError(logger, "JWT exchange network error", {
+          error: networkError2,
+          path: "/auth/partner/token"
+        });
+        throw networkError2;
+      }
+      const networkError = new NaturalError(
+        `Network error during authentication: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+      logError(logger, "JWT exchange network error", {
+        error: networkError,
+        path: "/auth/partner/token"
+      });
+      throw networkError;
+    }
+  }
+  /**
+   * Build URL with query parameters.
+   */
+  buildUrl(path, params) {
+    const url = new URL(path, this.baseUrl);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0 && value !== null) {
+          const snakeKey = key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+          url.searchParams.set(snakeKey, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  /**
+   * Handle API response and throw appropriate errors.
+   */
+  async handleResponse(response, method, path, durationMs) {
+    if (response.status === 401) {
+      const authError = new AuthenticationError();
+      logApiCall(logger, method, path, {
+        statusCode: response.status,
+        durationMs,
+        error: authError
+      });
+      throw authError;
+    }
+    if (response.status === 429) {
+      const retryAfter = response.headers.get("Retry-After");
+      const rateError = new RateLimitError(
+        "Rate limit exceeded",
+        retryAfter ? parseInt(retryAfter, 10) : void 0
+      );
+      logger.warning(`Rate limited: ${method} ${path}`, {
+        method,
+        path,
+        statusCode: response.status,
+        retryAfter,
+        durationMs: Math.round(durationMs * 100) / 100
+      });
+      throw rateError;
+    }
+    if (response.status >= 500) {
+      const serverError = new ServerError(`Server error: ${response.status}`);
+      logApiCall(logger, method, path, {
+        statusCode: response.status,
+        durationMs,
+        error: serverError
+      });
+      throw serverError;
+    }
+    let data;
+    try {
+      const text = await response.text();
+      data = text ? JSON.parse(text) : {};
+    } catch {
+      if (response.status >= 400) {
+        const parseError = new NaturalError(`Request failed: ${response.status}`, {
+          statusCode: response.status
+        });
+        logApiCall(logger, method, path, {
+          statusCode: response.status,
+          durationMs,
+          error: parseError
+        });
+        throw parseError;
+      }
+      logApiCall(logger, method, path, { statusCode: response.status, durationMs });
+      return {};
+    }
+    if (response.status >= 400) {
+      const errorData = data;
+      const errorMessage = errorData.detail ?? errorData.message ?? errorData.error ?? "Request failed";
+      const errorCode = errorData.code ?? "unknown_error";
+      const requestError = new InvalidRequestError(
+        `${errorMessage} (status=${response.status})`,
+        errorCode
+      );
+      logApiCall(logger, method, path, {
+        statusCode: response.status,
+        durationMs,
+        error: requestError
+      });
+      throw requestError;
+    }
+    logApiCall(logger, method, path, { statusCode: response.status, durationMs });
+    return snakeToCamel(data);
+  }
+  /**
+   * Make an authenticated request.
+   */
+  async request(method, path, options) {
+    const jwt = await this.getJwt();
+    const url = this.buildUrl(path, options?.params);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    logger.debug(`API request: ${method} ${path}`, {
+      method,
+      path,
+      hasBody: !!options?.body
+    });
+    const startTime = Date.now();
+    try {
+      const headers = {
+        Authorization: `Bearer ${jwt}`,
+        "Content-Type": "application/json",
+        "User-Agent": `naturalpay-ts/${SDK_VERSION2}`,
+        ...options?.headers
+      };
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: options?.body ? JSON.stringify(camelToSnake(options.body)) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const durationMs = Date.now() - startTime;
+      return this.handleResponse(response, method, path, durationMs);
+    } catch (error) {
+      clearTimeout(timeoutId);
+      const durationMs = Date.now() - startTime;
+      if (error instanceof NaturalError || error instanceof AuthenticationError || error instanceof InvalidRequestError || error instanceof RateLimitError || error instanceof ServerError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        const networkError2 = new NaturalError("Request timed out");
+        logApiCall(logger, method, path, { durationMs, error: networkError2 });
+        throw networkError2;
+      }
+      const networkError = new NaturalError(
+        `Network error: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+      logApiCall(logger, method, path, { durationMs, error: networkError });
+      throw networkError;
+    }
+  }
+  async get(path, options) {
+    return this.request("GET", path, options);
+  }
+  async post(path, options) {
+    return this.request("POST", path, options);
+  }
+  async put(path, options) {
+    return this.request("PUT", path, options);
+  }
+  async delete(path) {
+    return this.request("DELETE", path);
+  }
+};
+
+// src/resources/base.ts
+var BaseResource = class {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+};
+
+// src/resources/payments.ts
+var IDEMPOTENCY_WINDOW_SECONDS = 300;
+var PaymentsResource = class extends BaseResource {
+  /**
+   * Generate idempotency key based on payment details + time window.
+   */
+  generateIdempotencyKey(recipient, amount, memo) {
+    const timeWindow = Math.floor(Date.now() / 1e3 / IDEMPOTENCY_WINDOW_SECONDS);
+    const data = [recipient, String(amount), memo ?? "", String(timeWindow)].join(":");
+    return crypto.createHash("sha256").update(data).digest("hex").slice(0, 32);
+  }
+  /**
+   * Create a payment.
+   *
+   * Must provide exactly one of: recipientEmail, recipientPhone, or recipientPartyId.
+   *
+   * @param params - Payment creation parameters
+   * @returns Payment object with transfer_id, status, etc.
+   */
+  async create(params) {
+    const recipientCount = [
+      params.recipientEmail,
+      params.recipientPhone,
+      params.recipientPartyId
+    ].filter((r) => r !== void 0).length;
+    if (recipientCount !== 1) {
+      throw new Error(
+        "Must provide exactly one of: recipientEmail, recipientPhone, or recipientPartyId"
+      );
+    }
+    const recipient = params.recipientEmail ?? params.recipientPhone ?? params.recipientPartyId;
+    const idempotencyKey = params.idempotencyKey ?? this.generateIdempotencyKey(recipient, params.amount, params.memo);
+    const body = {
+      amount: params.amount
+    };
+    if (params.recipientEmail) body["recipientEmail"] = params.recipientEmail;
+    if (params.recipientPhone) body["recipientPhone"] = params.recipientPhone;
+    if (params.recipientPartyId) body["recipientPartyId"] = params.recipientPartyId;
+    if (params.memo) body["memo"] = params.memo;
+    if (params.agentId) body["agentId"] = params.agentId;
+    if (params.customerPartyId) body["customerPartyId"] = params.customerPartyId;
+    if (params.instanceId) body["instanceId"] = params.instanceId;
+    return this.http.post("/payments/initiate", {
+      body,
+      headers: { "Idempotency-Key": idempotencyKey }
+    });
+  }
+  /**
+   * Get payment status by transfer ID.
+   *
+   * @param transferId - The transfer ID to look up
+   * @returns Payment object with current status
+   */
+  async retrieve(transferId) {
+    return this.http.get(`/payments/${transferId}`);
+  }
+  /**
+   * Cancel a pending payment.
+   *
+   * @param transferId - The transfer ID to cancel
+   * @returns Cancellation result with status and message
+   */
+  async cancel(transferId) {
+    return this.http.post(`/payments/${transferId}/cancel`);
+  }
+};
+
+// src/resources/wallet.ts
+var WalletResource = class extends BaseResource {
+  /**
+   * Get current wallet balance.
+   *
+   * @returns AccountBalance with available, current, pending amounts
+   */
+  async balance() {
+    return this.http.get("/wallet/balance");
+  }
+  /**
+   * Initiate a deposit from a linked bank account.
+   *
+   * @param params - Deposit parameters
+   * @returns DepositResponse with transfer status
+   */
+  async deposit(params) {
+    const body = {
+      amount: params.amount,
+      currency: params.currency ?? "USD",
+      paymentInstrumentId: params.paymentInstrumentId
+    };
+    if (params.description) {
+      body["description"] = params.description;
+    }
+    return this.http.post("/wallet/deposit", {
+      body,
+      headers: { "Idempotency-Key": params.idempotencyKey }
+    });
+  }
+  /**
+   * Initiate a withdrawal to a linked bank account.
+   *
+   * @param params - Withdrawal parameters
+   * @returns WithdrawResponse with transfer status (may require KYC/MFA)
+   */
+  async withdraw(params) {
+    const body = {
+      amount: params.amount,
+      currency: params.currency ?? "USD",
+      paymentInstrumentId: params.paymentInstrumentId
+    };
+    if (params.description) {
+      body["description"] = params.description;
+    }
+    return this.http.post("/wallet/withdraw", {
+      body,
+      headers: { "Idempotency-Key": params.idempotencyKey }
+    });
+  }
+};
+
+// src/resources/transactions.ts
+var TransactionsResource = class extends BaseResource {
+  /**
+   * List recent transactions.
+   *
+   * @param params - List parameters including agent context
+   * @returns List of Transaction objects
+   */
+  async list(params) {
+    const headers = {};
+    if (params?.agentId) {
+      headers["X-Agent-ID"] = params.agentId;
+    }
+    if (params?.customerPartyId) {
+      headers["X-On-Behalf-Of"] = params.customerPartyId;
+    }
+    const data = await this.http.get("/transactions", {
+      params: {
+        limit: params?.limit ?? 10,
+        offset: params?.offset ?? 0,
+        customerFilter: params?.customerFilter,
+        type: params?.type
+      },
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    return data.transfers ?? data.transactions ?? [];
+  }
+};
+
+// src/resources/agents.ts
+var AgentsResource = class extends BaseResource {
+  /**
+   * List agents for the partner.
+   *
+   * @param params - Filter and pagination parameters
+   * @returns AgentListResponse with list of agents
+   */
+  async list(params) {
+    return this.http.get("/agents", {
+      params: {
+        status: params?.status,
+        partyId: params?.partyId,
+        limit: params?.limit ?? 50,
+        offset: params?.offset ?? 0
+      }
+    });
+  }
+  /**
+   * Get agent by ID.
+   *
+   * @param agentId - The agent ID to retrieve (agt_xxx)
+   * @returns Agent details
+   */
+  async get(agentId) {
+    return this.http.get(`/agents/${agentId}`);
+  }
+  /**
+   * Create a new agent.
+   *
+   * @param params - Agent creation parameters
+   * @returns AgentCreateResponse with created agent details
+   */
+  async create(params) {
+    const body = {
+      name: params.name,
+      partyId: params.partyId
+    };
+    if (params.description) {
+      body["description"] = params.description;
+    }
+    const headers = {};
+    if (params.idempotencyKey) {
+      headers["Idempotency-Key"] = params.idempotencyKey;
+    }
+    return this.http.post("/agents", {
+      body,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+  }
+  /**
+   * Update an existing agent.
+   *
+   * @param agentId - The agent ID to update (agt_xxx)
+   * @param params - Update parameters
+   * @returns AgentUpdateResponse with updated agent details
+   */
+  async update(agentId, params) {
+    const body = {};
+    if (params.name !== void 0) body["name"] = params.name;
+    if (params.description !== void 0) body["description"] = params.description;
+    if (params.status !== void 0) body["status"] = params.status;
+    const headers = {};
+    if (params.idempotencyKey) {
+      headers["Idempotency-Key"] = params.idempotencyKey;
+    }
+    return this.http.put(`/agents/${agentId}`, {
+      body,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+  }
+  /**
+   * Delete an agent.
+   *
+   * @param agentId - The agent ID to delete (agt_xxx)
+   */
+  async delete(agentId) {
+    await this.http.delete(`/agents/${agentId}`);
+  }
+};
+
+// src/resources/delegations.ts
+var DelegationsResource = class extends BaseResource {
+  /**
+   * List delegations with optional filters.
+   *
+   * @param params - Filter parameters
+   * @returns DelegationListResponse with list of delegations
+   */
+  async list(params) {
+    return this.http.get("/delegations", {
+      params: {
+        status: params?.status,
+        delegatingPartyId: params?.delegatingPartyId,
+        delegatedPartyId: params?.delegatedPartyId
+      }
+    });
+  }
+  /**
+   * Get delegation by ID.
+   *
+   * @param delegationId - The delegation handle (dlg_xxx)
+   * @returns Delegation details
+   */
+  async get(delegationId) {
+    return this.http.get(`/delegations/${delegationId}`);
+  }
+  /**
+   * Create a new delegation (party-to-party trust relationship).
+   *
+   * @param params - Delegation creation parameters
+   * @returns Created Delegation
+   */
+  async create(params) {
+    const body = {
+      delegatingPartyId: params.delegatingPartyId,
+      delegatedPartyId: params.delegatedPartyId,
+      permissions: params.permissions
+    };
+    if (params.expiresAt) {
+      body["expiresAt"] = params.expiresAt;
+    }
+    const headers = {};
+    if (params.idempotencyKey) {
+      headers["Idempotency-Key"] = params.idempotencyKey;
+    }
+    return this.http.post("/delegations", {
+      body,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+  }
+  /**
+   * Update an existing delegation.
+   *
+   * @param delegationId - Delegation handle (dlg_xxx)
+   * @param params - Update parameters
+   * @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 });
+  }
+  /**
+   * Revoke a delegation (soft delete by setting status to REVOKED).
+   *
+   * @param delegationId - Delegation handle (dlg_xxx)
+   * @returns Revoked Delegation
+   */
+  async revoke(delegationId) {
+    return this.http.put(`/delegations/${delegationId}/revoke`);
+  }
+};
+
+// src/resources/customers.ts
+var CustomersResource = class extends BaseResource {
+  /**
+   * List customers onboarded by the partner via delegation.
+   *
+   * @returns List of Customer objects with party info and delegation details
+   */
+  async list() {
+    return this.http.get("/customers");
+  }
+};
+
+// src/client.ts
+var NaturalClient = class {
+  http;
+  /** Payments API resource. */
+  payments;
+  /** Wallet API resource for balance, transfers, deposits, and withdrawals. */
+  wallet;
+  /** Transactions API resource. */
+  transactions;
+  /** Agents API resource for managing agents. */
+  agents;
+  /** Delegations API resource for managing party-to-party delegations. */
+  delegations;
+  /** Customers API resource for listing customers onboarded via delegation. */
+  customers;
+  /**
+   * Initialize the Natural client.
+   *
+   * @param options - Client configuration options
+   * @param options.apiKey - API key (defaults to NATURAL_API_KEY env var)
+   * @param options.baseUrl - API base URL (defaults to https://api.natural.co)
+   * @param options.timeout - Request timeout in milliseconds (default: 30000)
+   */
+  constructor(options = {}) {
+    this.http = new HTTPClient(options);
+    this.payments = new PaymentsResource(this.http);
+    this.wallet = new WalletResource(this.http);
+    this.transactions = new TransactionsResource(this.http);
+    this.agents = new AgentsResource(this.http);
+    this.delegations = new DelegationsResource(this.http);
+    this.customers = new CustomersResource(this.http);
+  }
+};
+
+// src/types/transactions.ts
+var TransactionTypeFilter = /* @__PURE__ */ ((TransactionTypeFilter2) => {
+  TransactionTypeFilter2["PAYMENT"] = "payment";
+  TransactionTypeFilter2["TRANSFER"] = "transfer";
+  TransactionTypeFilter2["ALL"] = "all";
+  return TransactionTypeFilter2;
+})(TransactionTypeFilter || {});
+
+// src/index.ts
+var VERSION = "0.0.1";
+
+exports.AuthenticationError = AuthenticationError;
+exports.InsufficientFundsError = InsufficientFundsError;
+exports.InvalidRequestError = InvalidRequestError;
+exports.NaturalClient = NaturalClient;
+exports.NaturalError = NaturalError;
+exports.PaymentError = PaymentError;
+exports.RateLimitError = RateLimitError;
+exports.RecipientNotFoundError = RecipientNotFoundError;
+exports.ServerError = ServerError;
+exports.TransactionTypeFilter = TransactionTypeFilter;
+exports.VERSION = VERSION;
+exports.bindContext = bindContext;
+exports.clearContext = clearContext;
+exports.configureLogging = configureLogging;
+exports.getContext = getContext;
+exports.getLogger = getLogger;
+exports.logApiCall = logApiCall;
+exports.logError = logError;
+exports.logToolCall = logToolCall;
+exports.runWithContext = runWithContext;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map