@naturalpay/sdk 0.1.1

package/dist/index.js

@@ -0,0 +1,1208 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+// 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";
+  }
+};
+
+// src/version.ts
+var VERSION = "0.1.1";
+
+// src/logging.ts
+var LOG_LEVEL_VALUES = {
+  debug: 10,
+  info: 20,
+  warning: 30,
+  error: 40
+};
+var asyncContext = new 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: 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"] = 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);
+  }
+}
+var toolCallStorage = new AsyncLocalStorage();
+function getToolCallHeader() {
+  const data = toolCallStorage.getStore();
+  if (!data) return void 0;
+  return btoa(JSON.stringify(data));
+}
+
+// src/http.ts
+var logger = getLogger("http");
+var DEFAULT_BASE_URL = "https://api.natural.co";
+var DEFAULT_TIMEOUT = 3e4;
+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);
+}
+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("sk_ntl_")) {
+      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/api/token" });
+    try {
+      const response = await fetch(`${this.baseUrl}/auth/api/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/api/token"
+        });
+        throw authError;
+      }
+      const data = await response.json();
+      const expiresIn = data.expiresIn ?? 900;
+      const expiresAt = Date.now() + (expiresIn - 30) * 1e3;
+      this.jwtCache.set(cacheKey, { token: data.accessToken, expiresAt });
+      return data.accessToken;
+    } 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/api/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/api/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) {
+          url.searchParams.set(key, 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 errBody = data;
+      const errors = Array.isArray(errBody.errors) ? errBody.errors : [];
+      const firstError = errors[0] ?? {};
+      const errorMessage = firstError.detail ?? errBody.detail ?? errBody.message ?? errBody.error ?? "Request failed";
+      const errorCode = firstError.code ?? errBody.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 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/${VERSION}`
+      };
+      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,
+        body: options?.body ? JSON.stringify(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, options) {
+    return this.request("DELETE", path, options);
+  }
+};
+
+// src/resources/base.ts
+var BaseResource = class {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+};
+
+// src/resources/transactions.ts
+function unwrapTransactionResource(resource) {
+  if (resource.type !== "transaction" || !resource.attributes) {
+    throw new NaturalError(
+      `Unexpected resource format: expected type "transaction", got "${resource.type}"`
+    );
+  }
+  const { id, attributes, relationships } = resource;
+  return {
+    transactionId: id,
+    amount: Number(attributes.amount),
+    currency: String(attributes.currency),
+    status: String(attributes.status),
+    description: attributes.description != null ? String(attributes.description) : void 0,
+    memo: attributes.memo != null ? String(attributes.memo) : void 0,
+    createdAt: String(attributes.createdAt),
+    updatedAt: attributes.updatedAt != null ? String(attributes.updatedAt) : void 0,
+    isDelegated: Boolean(attributes.isDelegated),
+    customerName: attributes.customerName != null ? String(attributes.customerName) : void 0,
+    customerAgentId: attributes.customerAgentId != null ? String(attributes.customerAgentId) : void 0,
+    senderName: attributes.senderName != null ? String(attributes.senderName) : void 0,
+    recipientName: attributes.recipientName != null ? String(attributes.recipientName) : void 0,
+    transactionType: String(attributes.transactionType),
+    category: String(attributes.category),
+    direction: String(attributes.direction),
+    sourcePartyId: relationships?.sourceParty?.data?.id,
+    destinationPartyId: relationships?.destinationParty?.data?.id,
+    sourceWalletId: relationships?.sourceWallet?.data?.id,
+    destinationWalletId: relationships?.destinationWallet?.data?.id,
+    instanceId: attributes.instanceId != null ? String(attributes.instanceId) : void 0,
+    claimLink: attributes.claimLink != null ? String(attributes.claimLink) : void 0
+  };
+}
+var TransactionsResource = class extends BaseResource {
+  /**
+   * Get a transaction by ID.
+   *
+   * @param transactionId - Transaction ID (txn_xxx)
+   * @param params - Optional parameters for observability
+   * @returns Transaction details
+   */
+  async get(transactionId, params) {
+    const headers = {};
+    if (params?.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
+    const queryParams = {};
+    if (params?.customerPartyId) {
+      queryParams["partyId"] = params.customerPartyId;
+    }
+    const response = await this.http.get(`/transactions/${transactionId}`, {
+      params: Object.keys(queryParams).length > 0 ? queryParams : void 0,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    if (!response?.data) {
+      throw new NaturalError('Unexpected response format: missing "data" in transaction response');
+    }
+    return unwrapTransactionResource(response.data);
+  }
+  /**
+   * List recent transactions.
+   *
+   * @param params - List parameters including agent context
+   * @returns TransactionListResponse with transactions and pagination info
+   */
+  async list(params) {
+    const headers = {};
+    if (params?.agentId) {
+      if (!params?.instanceId) {
+        throw new InvalidRequestError("instanceId is required when agentId is provided");
+      }
+      headers["X-Agent-ID"] = params.agentId;
+    }
+    if (params?.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
+    const queryParams = {
+      limit: params?.limit ?? 50,
+      cursor: params?.cursor,
+      type: params?.type
+    };
+    const response = await this.http.get("/transactions", {
+      params: queryParams,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    if (!response?.data || !Array.isArray(response.data)) {
+      throw new NaturalError(
+        'Unexpected response format: missing "data" array in transaction list response'
+      );
+    }
+    const transactions = response.data.map(unwrapTransactionResource);
+    const pagination = response.meta?.pagination ?? {};
+    return {
+      transactions,
+      hasMore: pagination.hasMore ?? false,
+      nextCursor: pagination.nextCursor ?? null
+    };
+  }
+};
+
+// src/resources/payments.ts
+var PHONE_DIGITS_RE = /^\d{10,}$/;
+var PHONE_PLUS_RE = /^\+\d{7,}$/;
+function validateRecipient(recipient) {
+  if (!recipient) {
+    throw new InvalidRequestError("recipient cannot be empty");
+  }
+  if (recipient.startsWith("pty_")) return;
+  if (recipient.includes("@")) return;
+  if (PHONE_PLUS_RE.test(recipient)) return;
+  if (PHONE_DIGITS_RE.test(recipient)) return;
+  throw new InvalidRequestError(
+    "Invalid recipient format. Expected: party ID (pty_*), email (contains @), or phone (+ prefix or 10+ digits)"
+  );
+}
+function unwrapPaymentResponse(response) {
+  if (!response?.data) {
+    throw new NaturalError('Unexpected response format: missing "data" field in payment response');
+  }
+  const base = unwrapTransactionResource(response.data);
+  const { relationships, attributes } = response.data;
+  return {
+    ...base,
+    // Payment responses may omit these fields; provide sensible defaults.
+    transactionType: String(attributes.transactionType ?? "payment"),
+    category: String(attributes.category ?? "sent"),
+    direction: String(attributes.direction ?? "OUTBOUND"),
+    // Mirror description into memo for payment convenience.
+    memo: base.description,
+    // Payments use customerParty/counterparty relationship keys,
+    // falling back to the generic sourceParty/destinationParty.
+    sourcePartyId: relationships?.customerParty?.data?.id ?? base.sourcePartyId,
+    destinationPartyId: relationships?.counterparty?.data?.id ?? base.destinationPartyId
+  };
+}
+var PaymentsResource = class extends BaseResource {
+  /**
+   * Create a payment.
+   *
+   * @param params - Payment creation parameters
+   * @returns Transaction object with transaction_id (txn_*), status, etc.
+   */
+  async create(params) {
+    const recipient = params.recipient.trim();
+    validateRecipient(recipient);
+    if (!Number.isInteger(params.amount) || params.amount <= 0) {
+      throw new InvalidRequestError("amount must be a positive integer (minor units in cents)");
+    }
+    const attributes = {
+      amount: params.amount,
+      currency: params.currency ?? "USD",
+      counterparty: recipient,
+      customerPartyId: params.customerPartyId
+    };
+    attributes["description"] = params.memo;
+    const body = { data: { attributes } };
+    const headers = {
+      "Idempotency-Key": params.idempotencyKey
+    };
+    if (params.agentId) {
+      if (!params.instanceId) {
+        throw new InvalidRequestError("instanceId is required when agentId is provided");
+      }
+      headers["X-Agent-ID"] = params.agentId;
+    }
+    if (params.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
+    const response = await this.http.post("/payments", {
+      body,
+      headers
+    });
+    return unwrapPaymentResponse(response);
+  }
+};
+
+// src/resources/wallet.ts
+function toAmountInfo(raw) {
+  const obj = raw;
+  return {
+    amountMinor: Number(obj?.amountMinor ?? 0)
+  };
+}
+function unwrapBalance(response) {
+  if (!response?.data) {
+    throw new NaturalError(
+      'Unexpected response format: missing "data" field in wallet balance response'
+    );
+  }
+  const { data } = response;
+  if (data.type !== "walletBalance" || !data.attributes) {
+    throw new NaturalError(
+      `Unexpected resource format: expected type "walletBalance", got "${data.type}"`
+    );
+  }
+  const { id, attributes } = data;
+  const rawBreakdown = attributes.breakdown;
+  const breakdown = {
+    operatingFunded: toAmountInfo(rawBreakdown?.operatingFunded),
+    operatingAdvanced: toAmountInfo(rawBreakdown?.operatingAdvanced),
+    escrowFundedSettled: toAmountInfo(rawBreakdown?.escrowFundedSettled),
+    escrowAdvanced: toAmountInfo(rawBreakdown?.escrowAdvanced),
+    holdsOutbound: toAmountInfo(rawBreakdown?.holdsOutbound)
+  };
+  return {
+    walletId: id,
+    breakdown,
+    available: toAmountInfo(attributes.available),
+    pendingClaimAmountMinor: attributes.pendingClaimAmountMinor != null ? Number(attributes.pendingClaimAmountMinor) : void 0,
+    pendingClaimCount: attributes.pendingClaimCount != null ? Number(attributes.pendingClaimCount) : 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 ? Number(attributes.amount) : 0,
+    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(options) {
+    const headers = {};
+    if (options?.instanceId) {
+      headers["X-Instance-ID"] = options.instanceId;
+    }
+    const params = {};
+    if (options?.customerPartyId) {
+      params["partyId"] = options.customerPartyId;
+    }
+    const response = await this.http.get("/wallet/balance", {
+      params: Object.keys(params).length > 0 ? params : void 0,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    return unwrapBalance(response);
+  }
+  /**
+   * Initiate a withdrawal to a linked bank account.
+   *
+   * @param params - Withdrawal parameters
+   * @returns WithdrawResponse with transfer status (may require KYC/MFA)
+   */
+  async withdraw(params) {
+    if (!Number.isInteger(params.amount) || params.amount <= 0) {
+      throw new InvalidRequestError("amount must be a positive integer (minor units in cents)");
+    }
+    const attributes = {
+      amount: params.amount,
+      currency: params.currency ?? "USD",
+      externalFundingSourceId: params.externalFundingSourceId
+    };
+    if (params.description) attributes["description"] = params.description;
+    const body = { data: { attributes } };
+    const response = await this.http.post("/wallet/withdraw", {
+      body,
+      headers: { "Idempotency-Key": params.idempotencyKey }
+    });
+    return unwrapWithdrawal(response);
+  }
+};
+
+// src/resources/agents.ts
+function unwrapAgentResource(resource) {
+  if (resource.type !== "agent" || !resource.attributes) {
+    throw new NaturalError(
+      `Unexpected resource format: expected type "agent", got "${resource.type}"`
+    );
+  }
+  const { id, attributes, relationships } = resource;
+  return {
+    id,
+    name: String(attributes.name),
+    description: attributes.description != null ? String(attributes.description) : void 0,
+    status: String(attributes.status),
+    partyId: relationships?.party?.data?.id ?? "",
+    createdAt: attributes.createdAt != null ? String(attributes.createdAt) : void 0,
+    createdBy: attributes.createdBy != null ? String(attributes.createdBy) : void 0,
+    updatedAt: attributes.updatedAt != null ? String(attributes.updatedAt) : void 0,
+    updatedBy: attributes.updatedBy != null ? String(attributes.updatedBy) : void 0
+  };
+}
+function unwrapAgent(response) {
+  if (!response?.data) {
+    throw new NaturalError('Unexpected response format: missing "data" field in agent response');
+  }
+  return unwrapAgentResource(response.data);
+}
+function unwrapAgentList(response) {
+  if (!response?.data || !Array.isArray(response.data)) {
+    throw new NaturalError(
+      'Unexpected response format: missing "data" array in agent list response'
+    );
+  }
+  const agents = response.data.map(unwrapAgentResource);
+  const pagination = response.meta?.pagination ?? {};
+  return {
+    agents,
+    hasMore: pagination.hasMore ?? false,
+    nextCursor: pagination.nextCursor ?? null
+  };
+}
+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) {
+    const headers = {};
+    if (params?.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
+    const queryParams = {
+      status: params?.status,
+      limit: params?.limit ?? 50,
+      cursor: params?.cursor
+    };
+    const response = await this.http.get("/agents", {
+      params: queryParams,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    return unwrapAgentList(response);
+  }
+  /**
+   * Get agent by ID.
+   *
+   * @param agentId - The agent ID to retrieve (agt_xxx)
+   * @returns Agent details
+   */
+  async get(agentId, options) {
+    const headers = {};
+    if (options?.instanceId) {
+      headers["X-Instance-ID"] = options.instanceId;
+    }
+    const response = await this.http.get(`/agents/${agentId}`, {
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    return unwrapAgent(response);
+  }
+  /**
+   * Create a new agent.
+   *
+   * @param params - Agent creation parameters
+   * @returns AgentCreateResponse with created agent details
+   */
+  async create(params) {
+    const attributes = {
+      name: params.name
+    };
+    if (params.description) {
+      attributes["description"] = params.description;
+    }
+    if (params.limits) {
+      attributes["limits"] = params.limits;
+    }
+    const body = { data: { attributes } };
+    const headers = {};
+    if (params.idempotencyKey) {
+      headers["Idempotency-Key"] = params.idempotencyKey;
+    }
+    if (params.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
+    const response = await this.http.post("/agents", {
+      body,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    return unwrapAgent(response);
+  }
+  /**
+   * 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 attributes = {};
+    if (params.name !== void 0) attributes["name"] = params.name;
+    if (params.description !== void 0) attributes["description"] = params.description;
+    if (params.status !== void 0) attributes["status"] = params.status;
+    const body = { data: { attributes } };
+    const headers = {};
+    if (params.idempotencyKey) {
+      headers["Idempotency-Key"] = params.idempotencyKey;
+    }
+    if (params.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
+    const response = await this.http.put(`/agents/${agentId}`, {
+      body,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    return unwrapAgent(response);
+  }
+  /**
+   * Delete an agent.
+   *
+   * @param agentId - The agent ID to delete (agt_xxx)
+   * @param options - Optional observability parameters
+   */
+  async delete(agentId, options) {
+    const headers = {};
+    if (options?.instanceId) {
+      headers["X-Instance-ID"] = options.instanceId;
+    }
+    await this.http.delete(`/agents/${agentId}`, {
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+  }
+};
+
+// src/resources/delegations.ts
+function unwrapAgentDelegationResource(resource) {
+  if (resource.type !== "agentDelegation" || !resource.attributes) {
+    throw new NaturalError(
+      `Unexpected resource format: expected type "agentDelegation", got "${resource.type}"`
+    );
+  }
+  const { id, attributes, relationships } = resource;
+  return {
+    id,
+    agentName: attributes.agentName != null ? String(attributes.agentName) : void 0,
+    agentId: relationships?.agent?.data?.id ?? "",
+    delegationId: relationships?.delegation?.data?.id ?? "",
+    delegatorPartyId: relationships?.delegatorParty?.data?.id,
+    delegateePartyId: relationships?.delegateeParty?.data?.id,
+    delegatorPartyName: attributes.delegatorPartyName != null ? String(attributes.delegatorPartyName) : void 0,
+    delegateePartyName: attributes.delegateePartyName != null ? String(attributes.delegateePartyName) : void 0,
+    permissions: Array.isArray(attributes.permissions) ? attributes.permissions : [],
+    limits: attributes.limits != null ? attributes.limits : void 0,
+    expiresAt: attributes.expiresAt != null ? String(attributes.expiresAt) : void 0,
+    createdAt: String(attributes.createdAt),
+    createdBy: attributes.createdBy != null ? String(attributes.createdBy) : void 0,
+    updatedAt: String(attributes.updatedAt)
+  };
+}
+function unwrapAgentDelegation(response) {
+  if (!response?.data) {
+    throw new NaturalError(
+      'Unexpected response format: missing "data" field in agent delegation response'
+    );
+  }
+  return unwrapAgentDelegationResource(response.data);
+}
+function unwrapAgentDelegationList(response) {
+  if (!response?.data || !Array.isArray(response.data)) {
+    throw new NaturalError(
+      'Unexpected response format: missing "data" array in agent delegation list response'
+    );
+  }
+  const agentDelegations = response.data.map(unwrapAgentDelegationResource);
+  const pagination = response.meta?.pagination ?? {};
+  return {
+    agentDelegations,
+    hasMore: pagination.hasMore ?? false,
+    nextCursor: pagination.nextCursor ?? null
+  };
+}
+var DelegationsResource = class extends BaseResource {
+  /**
+   * List agent delegations with optional filters.
+   *
+   * @param params - Filter parameters
+   * @returns AgentDelegationListResponse with list of agent delegations
+   */
+  async list(params) {
+    const headers = {};
+    if (params?.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
+    const queryParams = {
+      delegationId: params?.delegationId,
+      agentId: params?.agentId,
+      delegatorPartyId: params?.delegatorPartyId,
+      delegateePartyId: params?.delegateePartyId,
+      includeRevoked: params?.includeRevoked,
+      limit: params?.limit ?? 50,
+      cursor: params?.cursor
+    };
+    const response = await this.http.get("/agent-delegations", {
+      params: queryParams,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    return unwrapAgentDelegationList(response);
+  }
+  /**
+   * Get agent delegation by ID.
+   *
+   * @param agentDelegationId - The agent delegation handle (adl_xxx)
+   * @returns AgentDelegation details
+   */
+  async get(agentDelegationId) {
+    const response = await this.http.get(
+      `/agent-delegations/${agentDelegationId}`
+    );
+    return unwrapAgentDelegation(response);
+  }
+};
+
+// src/resources/customers.ts
+var VALID_CUSTOMER_TYPES = /* @__PURE__ */ new Set(["party", "delegationInvitation"]);
+var VALID_WALLET_ACCESS = /* @__PURE__ */ new Set(["granted", "denied", "noWallet"]);
+function isCustomerType(value) {
+  return VALID_CUSTOMER_TYPES.has(value);
+}
+function isWalletAccess(value) {
+  return typeof value === "string" && VALID_WALLET_ACCESS.has(value);
+}
+function unwrapCustomerResource(resource) {
+  if (!isCustomerType(resource.type) || !resource.attributes) {
+    throw new NaturalError(
+      `Unexpected resource format: expected type "party" or "delegationInvitation", got "${resource.type}"`
+    );
+  }
+  const { id, attributes } = resource;
+  const party = typeof attributes.party === "object" && attributes.party != null ? {
+    id: String(attributes.party.id),
+    name: String(attributes.party.name),
+    email: typeof attributes.party.email === "string" ? String(attributes.party.email) : void 0
+  } : void 0;
+  return {
+    id,
+    type: resource.type,
+    party,
+    email: typeof attributes.email === "string" ? attributes.email : void 0,
+    status: typeof attributes.status === "string" ? attributes.status : "",
+    permissions: Array.isArray(attributes.permissions) ? attributes.permissions : [],
+    createdAt: typeof attributes.createdAt === "string" ? attributes.createdAt : "",
+    walletAvailableMinor: typeof attributes.walletAvailableMinor === "number" ? attributes.walletAvailableMinor : void 0,
+    walletAvailableDollars: typeof attributes.walletAvailableDollars === "string" ? attributes.walletAvailableDollars : void 0,
+    walletAccess: isWalletAccess(attributes.walletAccess) ? attributes.walletAccess : "denied"
+  };
+}
+function unwrapCustomerList(response) {
+  if (!response?.data || !Array.isArray(response.data)) {
+    throw new NaturalError(
+      'Unexpected response format: missing "data" array in customer list response'
+    );
+  }
+  const pagination = response.meta?.pagination ?? {};
+  return {
+    items: response.data.map(unwrapCustomerResource),
+    hasMore: pagination.hasMore ?? false,
+    nextCursor: pagination.nextCursor ?? null
+  };
+}
+var CustomersResource = class extends BaseResource {
+  /**
+   * List customers who have delegated access to the partner.
+   *
+   * @param params - Pagination parameters
+   * @returns CustomerListResponse with items, hasMore, nextCursor
+   */
+  async list(params) {
+    const headers = {};
+    if (params?.instanceId) {
+      headers["X-Instance-ID"] = params.instanceId;
+    }
+    const queryParams = {
+      limit: params?.limit,
+      cursor: params?.cursor
+    };
+    const response = await this.http.get("/customers", {
+      params: queryParams,
+      headers: Object.keys(headers).length > 0 ? headers : void 0
+    });
+    return unwrapCustomerList(response);
+  }
+};
+
+// src/client.ts
+var NaturalClient = class {
+  http;
+  /** Payments API resource. */
+  payments;
+  /** Wallet API resource for balance and withdrawals. */
+  wallet;
+  /** Transactions API resource. */
+  transactions;
+  /** Agents API resource for managing agents. */
+  agents;
+  /** Agent delegations API resource. */
+  delegations;
+  /** Customers API resource for listing parties who delegated access. */
+  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 || {});
+
+export { AuthenticationError, InsufficientFundsError, InvalidRequestError, NaturalClient, NaturalError, PaymentError, RateLimitError, RecipientNotFoundError, ServerError, TransactionTypeFilter, VERSION, bindContext, clearContext, configureLogging, getContext, getLogger, logApiCall, logError, logToolCall, runWithContext };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map