@naturalpay/sdk 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,24 +1,102 @@
+/**
+ * Agent config and model usage for LLM observability.
+ *
+ * Tracks static agent configuration (system prompt, tools) and per-request
+ * model usage so the observability service can attribute API calls to
+ * specific LLM sessions.
+ */
+/**
+ * Static agent configuration — set once per client, sent to observability.
+ *
+ * Describes the agent's identity (system prompt and available tools).
+ * Model/provider are per-request and belong in ModelUsage.
+ */
+interface AgentConfig {
+    systemPrompt: string;
+    toolsAvailable: string[];
+}
+interface ModelUsage {
+    model?: string;
+    provider?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    toolsCalled?: string[];
+}
+interface AgentConfigDict {
+    system_prompt: string;
+    tools_available: string[];
+}
+interface ModelUsageDict {
+    model?: string;
+    provider?: string;
+    input_tokens?: number;
+    output_tokens?: number;
+    tools_called?: string[];
+}
+/**
+ * SHA-256 hash for change detection.
+ *
+ * Covers only {system_prompt, tools_available} — model/provider
+ * are dynamic per-request and excluded from the config hash.
+ */
+declare function configHash(cfg: AgentConfig): string;
+declare function agentConfigToDict(cfg: AgentConfig): AgentConfigDict;
+declare function modelUsageToDict(usage: ModelUsage): ModelUsageDict;
+
 /**
  * HTTP client for Natural Server API with JWT caching.
  */
+
+/**
+ * Parse an API key and return its environment label.
+ *
+ * Accepts keys matching `sk_ntl_(dev|sandbox|prod)_*`. Throws
+ * `InvalidRequestError` for anything else. The return type is a narrowed
+ * literal union so callers can discriminate on the env without a second
+ * parse.
+ */
+declare function parseApiKeyEnv(key: string): 'dev' | 'sandbox' | 'prod';
+/**
+ * Validate that a base URL uses HTTPS, with a localhost auto-allow and an
+ * `NATURAL_ALLOW_HTTP=1` escape hatch for non-localhost plaintext hosts.
+ *
+ * Throws `InvalidRequestError` if the URL is not HTTPS and neither escape
+ * hatch applies. Runs at client construction, not per-request.
+ */
+declare function validateBaseUrl(baseUrl: string): void;
 interface HTTPClientOptions {
     apiKey?: string;
     baseUrl?: string;
     timeout?: number;
+    agentConfig?: AgentConfig;
+    /** Default model/provider sent with every request as X-Model-Usage. */
+    defaultModelUsage?: Pick<ModelUsage, 'model' | 'provider'>;
+    maxRetries?: number;
 }
 interface RequestOptions {
     body?: Record<string, unknown>;
     params?: Record<string, unknown>;
     headers?: Record<string, string>;
+    modelUsage?: ModelUsage;
 }
 declare class HTTPClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly maxRetries;
     private readonly jwtCache;
+    private readonly agentConfig?;
+    private readonly _defaultModelUsage?;
+    private _configResolved;
+    private _configAttempted;
+    private _registerConfigPromise;
+    private _nextRetryAt;
+    private _retryBackoffMs;
+    private static readonly MAX_RETRY_BACKOFF_MS;
     constructor(options?: HTTPClientOptions);
     /**
      * Get a cached JWT or exchange API key for a new one.
+     * Retries on transient failures (5xx, network) but not on 401.
      */
     private getJwt;
     /**
@@ -30,7 +108,18 @@ declare class HTTPClient {
      */
     private handleResponse;
     /**
-     * Make an authenticated request.
+     * Register agent config with the observability service.
+     *
+     * Called lazily before the first request. Errors are caught and logged,
+     * never thrown.
+     */
+    private registerConfig;
+    /**
+     * Add agent config hash and model usage headers if configured.
+     */
+    private injectModelContextHeaders;
+    /**
+     * Make an authenticated request with automatic retries.
      */
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: Omit<RequestOptions, 'body'>): Promise<T>;
@@ -66,6 +155,8 @@ interface PaymentCreateParams {
     idempotencyKey: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 
 /**
@@ -108,8 +199,12 @@ interface Transaction {
 interface TransactionGetParams {
     /** Customer party ID (pty_xxx) for delegated transaction lookup. */
     customerPartyId?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface TransactionListParams {
     limit?: number;
@@ -119,6 +214,8 @@ interface TransactionListParams {
     type?: TransactionTypeFilter;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface TransactionListResponse {
     transactions: Transaction[];
@@ -163,8 +260,12 @@ interface AccountBalance {
 interface BalanceOptions {
     /** Customer party ID (pty_xxx) when acting on behalf of customer. */
     customerPartyId?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface WithdrawParams {
     /** Withdrawal amount in minor units (cents). 5000 = $50.00. */
@@ -174,6 +275,12 @@ interface WithdrawParams {
     currency?: string;
     description?: string;
     idempotencyKey: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
+    /** Developer's session/conversation ID for observability grouping. */
+    instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface WithdrawResponse {
     transferId?: string;
@@ -257,8 +364,12 @@ interface AgentCreateParams {
     description?: string;
     limits?: TransactionLimits;
     idempotencyKey?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 /** @deprecated Use Agent instead — server returns full resource for all operations. */
 type AgentCreateResponse = Agent;
@@ -267,8 +378,12 @@ interface AgentUpdateParams {
     description?: string;
     status?: AgentStatus;
     idempotencyKey?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 /** @deprecated Use Agent instead — server returns full resource for all operations. */
 type AgentUpdateResponse = Agent;
@@ -276,16 +391,28 @@ interface AgentListParams {
     status?: AgentStatus;
     limit?: number;
     cursor?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface AgentGetOptions {
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface AgentDeleteOptions {
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface AgentListResponse {
     agents: Agent[];
@@ -365,6 +492,8 @@ interface AgentDelegationListParams {
     cursor?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface AgentDelegationListResponse {
     agentDelegations: AgentDelegation[];
@@ -416,8 +545,12 @@ interface Customer {
 interface CustomerListParams {
     limit?: number;
     cursor?: string;
+    /** Agent ID (agt_xxx) for observability attribution. */
+    agentId?: string;
     /** Developer's session/conversation ID for observability grouping. */
     instanceId?: string;
+    /** Trace ID for distributed tracing correlation. */
+    traceId?: string;
 }
 interface CustomerListResponse {
     items: Customer[];
@@ -450,9 +583,9 @@ interface NaturalClientOptions extends HTTPClientOptions {
  *
  * @example
  * ```typescript
- * import { NaturalClient } from 'naturalpay';
+ * import { NaturalClient } from '@naturalpay/sdk';
  *
- * const client = new NaturalClient({ apiKey: 'sk_ntl_sandbox_xxx' });
+ * const client = new NaturalClient({ apiKey: process.env['NATURAL_API_KEY'] });
  *
  * // Create a payment
  * const payment = await client.payments.create({
@@ -493,6 +626,48 @@ declare class NaturalClient {
     constructor(options?: NaturalClientOptions);
 }
 
+/** Branded string types for observability IDs */
+type InstanceId = string & {
+    readonly __brand: 'InstanceId';
+};
+type TraceId = string & {
+    readonly __brand: 'TraceId';
+};
+type ToolCallId = string & {
+    readonly __brand: 'ToolCallId';
+};
+
+/**
+ * Tool call context for MCP server -> HTTP layer communication.
+ *
+ * The MCP server sets tool call data (id + name + arguments) before invoking
+ * SDK methods. The HTTP layer reads it and sends the X-Tool-Call header to the
+ * BFF for audit/observability. Direct SDK users never interact with this module.
+ */
+
+/**
+ * Generate a unique tool call ID with the `tc_` prefix.
+ */
+declare function generateToolCallId(): ToolCallId;
+/**
+ * Get the base64-encoded X-Tool-Call header value, or undefined if not in
+ * a tool call context.
+ *
+ * If the full header (with arguments) exceeds 16 KB, the arguments are
+ * omitted and a warning is logged.
+ */
+declare function getToolCallHeader(): string | undefined;
+/**
+ * Run a function within a tool call context. The HTTP layer will automatically
+ * pick up the tool call data and send it as the X-Tool-Call header.
+ *
+ * @param toolCallId - Unique ID for this invocation (tc_<uuid>).
+ * @param name       - Tool name (e.g. "create_payment").
+ * @param args       - Raw tool arguments.
+ * @param fn         - The function to execute within the context.
+ */
+declare function runWithToolCall<T>(toolCallId: ToolCallId, name: string, args: Record<string, unknown>, fn: () => T): T;
+
 /**
  * Structured logging for Natural Payments SDK.
  *
@@ -667,10 +842,38 @@ declare class RateLimitError extends NaturalError {
 declare class ServerError extends NaturalError {
     constructor(message?: string);
 }
+/**
+ * Webhook signature verification failed.
+ */
+declare class WebhookVerificationError extends NaturalError {
+    constructor(message: string);
+}
+
+/**
+ * Webhook signature verification using Standard Webhooks HMAC-SHA256.
+ */
+interface VerifyWebhookOptions {
+    toleranceInSeconds?: number;
+}
+/**
+ * Verify a webhook signature using Standard Webhooks HMAC-SHA256.
+ *
+ * The body must be the raw request body — not a parsed and re-serialized
+ * JSON object, as whitespace or key ordering differences would produce a
+ * different signature.
+ *
+ * @param body - Raw request body (string, Buffer, or Uint8Array)
+ * @param headers - Request headers containing webhook-id, webhook-timestamp, webhook-signature
+ * @param secret - Signing secret (with or without whsec_ prefix)
+ * @param options - Optional configuration (toleranceInSeconds)
+ * @returns Parsed JSON payload
+ * @throws WebhookVerificationError on any verification failure
+ */
+declare function verifyWebhookSignature(body: string | Buffer | Uint8Array, headers: Record<string, string> | Headers, secret: string, options?: VerifyWebhookOptions): unknown;
 
 /**
  * Single source of truth for the SDK version string.
  */
-declare const VERSION = "0.1.1";
+declare const VERSION = "0.1.4";
 
-export { type AccountBalance, type Agent, type AgentCreateParams, type AgentCreateResponse, type AgentDelegation, type AgentDelegationListParams, type AgentDelegationListResponse, type AgentDeleteOptions, type AgentGetOptions, type AgentListParams, type AgentListResponse, type AgentStatus, type AgentUpdateParams, type AgentUpdateResponse, type AmountInfo, AuthenticationError, type BalanceBreakdown, type Customer, type CustomerListParams, type CustomerListResponse, type CustomerPartyInfo, InsufficientFundsError, InvalidRequestError, type LogLevel, Logger, NaturalClient, type NaturalClientOptions, NaturalError, type PaymentCreateParams, PaymentError, RateLimitError, RecipientNotFoundError, ServerError, type Transaction, type TransactionGetParams, type TransactionListParams, type TransactionListResponse, TransactionTypeFilter, VERSION, type WithdrawParams, type WithdrawResponse, bindContext, clearContext, configureLogging, getContext, getLogger, logApiCall, logError, logToolCall, runWithContext };
+export { type AccountBalance, type Agent, type AgentConfig, type AgentConfigDict, type AgentCreateParams, type AgentCreateResponse, type AgentDelegation, type AgentDelegationListParams, type AgentDelegationListResponse, type AgentDeleteOptions, type AgentGetOptions, type AgentListParams, type AgentListResponse, type AgentStatus, type AgentUpdateParams, type AgentUpdateResponse, type AmountInfo, AuthenticationError, type BalanceBreakdown, type Customer, type CustomerListParams, type CustomerListResponse, type CustomerPartyInfo, type InstanceId, InsufficientFundsError, InvalidRequestError, type LogLevel, Logger, type ModelUsage, type ModelUsageDict, NaturalClient, type NaturalClientOptions, NaturalError, type PaymentCreateParams, PaymentError, RateLimitError, RecipientNotFoundError, ServerError, type ToolCallId, type TraceId, type Transaction, type TransactionGetParams, type TransactionListParams, type TransactionListResponse, TransactionTypeFilter, VERSION, type VerifyWebhookOptions, WebhookVerificationError, type WithdrawParams, type WithdrawResponse, agentConfigToDict, bindContext, clearContext, configHash, configureLogging, generateToolCallId, getContext, getLogger, getToolCallHeader, logApiCall, logError, logToolCall, modelUsageToDict, parseApiKeyEnv, runWithContext, runWithToolCall, validateBaseUrl, verifyWebhookSignature };