@chainlink/ccip-sdk 1.1.1 → 1.2.0

package/dist/api/index.d.ts

@@ -1,13 +1,13 @@
 import type { SetRequired } from 'type-fest';
 import { type CCIPRequest, type ExecutionInput, type Lane, type Logger, type WithLogger } from '../types.ts';
-import type { LaneLatencyResponse } from './types.ts';
-export type { APICCIPRequestMetadata, APIErrorResponse, LaneLatencyResponse } from './types.ts';
+import type { LaneLatencyResponse, MessageSearchFilters, MessageSearchPage, MessageSearchResult } from './types.ts';
+export type { APICCIPRequestMetadata, APIErrorResponse, LaneLatencyResponse, MessageSearchFilters, MessageSearchPage, MessageSearchResult, } from './types.ts';
 /** Default CCIP API base URL */
 export declare const DEFAULT_API_BASE_URL = "https://api.ccip.chain.link";
 /** Default timeout for API requests in milliseconds */
 export declare const DEFAULT_TIMEOUT_MS = 30000;
 /** SDK version string for telemetry header */
-export declare const SDK_VERSION = "1.1.1-593a607";
+export declare const SDK_VERSION = "1.2.0-7dcdd16";
 /** SDK telemetry header name */
 export declare const SDK_VERSION_HEADER = "X-SDK-Version";
 /**
@@ -91,10 +91,15 @@ export declare class CCIPAPIClient {
      *
      * @param sourceChainSelector - Source chain selector (bigint)
      * @param destChainSelector - Destination chain selector (bigint)
+     * @param numberOfBlocks - Optional number of block confirmations for latency calculation.
+     *   When omitted or 0, uses the lane's default finality. When provided as a positive
+     *   integer, the API returns latency for that custom finality value (sent as `numOfBlocks`
+     *   query parameter).
      * @returns Promise resolving to {@link LaneLatencyResponse} with totalMs
      *
      * @throws {@link CCIPLaneNotFoundError} when lane not found (404)
      * @throws {@link CCIPTimeoutError} if request times out
+     * @throws {@link CCIPAbortError} if request is aborted via signal
      * @throws {@link CCIPHttpError} on other HTTP errors with context:
      *   - `status` - HTTP status code (e.g., 500)
      *   - `statusText` - HTTP status message
@@ -110,6 +115,15 @@ export declare class CCIPAPIClient {
      * console.log(`Estimated delivery: ${Math.round(latency.totalMs / 60000)} minutes`)
      * ```
      *
+     * @example Custom block confirmations
+     * ```typescript
+     * const latency = await api.getLaneLatency(
+     *   5009297550715157269n,  // Ethereum mainnet
+     *   4949039107694359620n,  // Arbitrum mainnet
+     *   10,                    // 10 block confirmations
+     * )
+     * ```
+     *
      * @example Handling specific API errors
      * ```typescript
      * try {
@@ -121,7 +135,9 @@ export declare class CCIPAPIClient {
      * }
      * ```
      */
-    getLaneLatency(sourceChainSelector: bigint, destChainSelector: bigint): Promise<LaneLatencyResponse>;
+    getLaneLatency(sourceChainSelector: bigint, destChainSelector: bigint, numberOfBlocks?: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<LaneLatencyResponse>;
     /**
      * Fetches a CCIP message by its unique message ID.
      *
@@ -130,6 +146,7 @@ export declare class CCIPAPIClient {
      *
      * @throws {@link CCIPMessageIdNotFoundError} when message not found (404)
      * @throws {@link CCIPTimeoutError} if request times out
+     * @throws {@link CCIPAbortError} if request is aborted via signal
      * @throws {@link CCIPHttpError} on HTTP errors with context:
      *   - `status` - HTTP status code
      *   - `statusText` - HTTP status message
@@ -156,17 +173,119 @@ export declare class CCIPAPIClient {
      * }
      * ```
      */
-    getMessageById(messageId: string): Promise<SetRequired<CCIPRequest, 'metadata'>>;
+    getMessageById(messageId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<SetRequired<CCIPRequest, 'metadata'>>;
+    /**
+     * Searches CCIP messages using filters with cursor-based pagination.
+     *
+     * @param filters - Optional search filters. Ignored when `options.cursor` is provided
+     *   (the cursor already encodes the original filters).
+     * @param options - Optional pagination options: `limit` (max results per page) and
+     *   `cursor` (opaque token from a previous {@link MessageSearchPage} for the next page).
+     * @returns Promise resolving to a {@link MessageSearchPage} with results and pagination info.
+     *
+     * @remarks
+     * A 404 response is treated as "no results found" and returns an empty page,
+     * unlike {@link CCIPAPIClient.getMessageById} which throws on 404.
+     * When paginating with a cursor, the `filters` parameter is ignored because
+     * the cursor encodes the original filters.
+     *
+     * @throws {@link CCIPTimeoutError} if request times out.
+     * @throws {@link CCIPAbortError} if request is aborted via signal.
+     * @throws {@link CCIPHttpError} on HTTP errors (4xx/5xx, except 404 which returns empty).
+     *
+     * @see {@link MessageSearchFilters} — available filter fields
+     * @see {@link MessageSearchPage} — return type with pagination
+     * @see {@link CCIPAPIClient.searchAllMessages} — async generator that handles pagination automatically
+     * @see {@link CCIPAPIClient.getMessageById} — fetch full message details for a search result
+     * @see {@link CCIPAPIClient.getMessageIdsInTx} — convenience wrapper using `sourceTransactionHash`
+     *
+     * @example Search by sender
+     * ```typescript
+     * const page = await api.searchMessages({
+     *   sender: '0x9d087fC03ae39b088326b67fA3C788236645b717',
+     * })
+     * for (const msg of page.data) {
+     *   console.log(`${msg.messageId}: ${msg.status}`)
+     * }
+     * ```
+     *
+     * @example Paginate through all results
+     * ```typescript
+     * let page = await api.searchMessages({ sender: '0x...' }, { limit: 10 })
+     * const all = [...page.data]
+     * while (page.hasNextPage) {
+     *   page = await api.searchMessages(undefined, { cursor: page.cursor! })
+     *   all.push(...page.data)
+     * }
+     * ```
+     *
+     * @example Filter by lane and sender
+     * ```typescript
+     * const page = await api.searchMessages({
+     *   sender: '0x9d087fC03ae39b088326b67fA3C788236645b717',
+     *   sourceChainSelector: 16015286601757825753n,
+     *   destChainSelector: 14767482510784806043n,
+     * })
+     * ```
+     */
+    searchMessages(filters?: MessageSearchFilters, options?: {
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<MessageSearchPage>;
+    /**
+     * Async generator that streams all messages matching the given filters,
+     * handling cursor-based pagination automatically.
+     *
+     * @param filters - Optional search filters (same as {@link CCIPAPIClient.searchMessages}).
+     * @param options - Optional `limit` controlling the per-page fetch size (number of
+     *   results fetched per API call). The total number of results is controlled by the
+     *   consumer — break out of the loop to stop early.
+     * @returns AsyncGenerator yielding {@link MessageSearchResult} one at a time, across all pages.
+     *
+     * @throws {@link CCIPTimeoutError} if a page request times out.
+     * @throws {@link CCIPAbortError} if a page request is aborted via signal.
+     * @throws {@link CCIPHttpError} on HTTP errors (4xx/5xx, except 404 which yields nothing).
+     *
+     * @see {@link CCIPAPIClient.searchMessages} — for page-level control and explicit cursor handling
+     * @see {@link CCIPAPIClient.getMessageById} — fetch full message details for a search result
+     *
+     * @example Iterate all messages for a sender
+     * ```typescript
+     * for await (const msg of api.searchAllMessages({ sender: '0x...' })) {
+     *   console.log(`${msg.messageId}: ${msg.status}`)
+     * }
+     * ```
+     *
+     * @example Stop after collecting 5 results
+     * ```typescript
+     * const results: MessageSearchResult[] = []
+     * for await (const msg of api.searchAllMessages({ sender: '0x...' })) {
+     *   results.push(msg)
+     *   if (results.length >= 5) break
+     * }
+     * ```
+     */
+    searchAllMessages(filters?: MessageSearchFilters, options?: {
+        limit?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<MessageSearchResult>;
     /**
      * Fetches message IDs from a source transaction hash.
      *
-     * @param txHash - Source transaction hash (EVM hex or Solana Base58)
-     * @returns Promise resolving to array of message IDs
+     * @remarks
+     * Uses {@link CCIPAPIClient.searchMessages} internally with `sourceTransactionHash` filter and `limit: 100`.
      *
-     * @throws {@link CCIPMessageNotFoundInTxError} when no messages found (404 or empty)
-     * @throws {@link CCIPUnexpectedPaginationError} when hasNextPage is true
-     * @throws {@link CCIPTimeoutError} if request times out
-     * @throws {@link CCIPHttpError} on HTTP errors
+     * @param txHash - Source transaction hash.
+     * @returns Promise resolving to array of message IDs.
+     *
+     * @throws {@link CCIPMessageNotFoundInTxError} when no messages found (404 or empty).
+     * @throws {@link CCIPUnexpectedPaginationError} when hasNextPage is true.
+     * @throws {@link CCIPTimeoutError} if request times out.
+     * @throws {@link CCIPAbortError} if request is aborted via signal.
+     * @throws {@link CCIPHttpError} on HTTP errors.
      *
      * @example Basic usage
      * ```typescript
@@ -175,14 +294,45 @@ export declare class CCIPAPIClient {
      * )
      * console.log(`Found ${messageIds.length} messages`)
      * ```
+     *
+     * @example Fetch full details for each message
+     * ```typescript
+     * const api = CCIPAPIClient.fromUrl()
+     * const messageIds = await api.getMessageIdsInTx(txHash)
+     * for (const id of messageIds) {
+     *   const request = await api.getMessageById(id)
+     *   console.log(`${id}: ${request.metadata.status}`)
+     * }
+     * ```
      */
-    getMessageIdsInTx(txHash: string): Promise<string[]>;
+    getMessageIdsInTx(txHash: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<string[]>;
     /**
      * Fetches the execution input for a given message by id.
-     * @param messageId - The ID of the message to fetch the execution input for.
-     * @returns Either `{ encodedMessage, verifications }` or `{ message, offchainTokenData, ...proof }`, offRamp and lane
+     * For v2.0 messages, returns `{ encodedMessage, verifications }`.
+     * For pre-v2 messages, returns `{ message, offchainTokenData, proofs, ... }` with merkle proof.
+     *
+     * @param messageId - The CCIP message ID (32-byte hex string)
+     * @returns Execution input with offRamp address and lane info
+     *
+     * @throws {@link CCIPMessageIdNotFoundError} when message not found (404)
+     * @throws {@link CCIPTimeoutError} if request times out
+     * @throws {@link CCIPAbortError} if request is aborted via signal
+     * @throws {@link CCIPHttpError} on other HTTP errors
+     *
+     * @example
+     * ```typescript
+     * const api = CCIPAPIClient.fromUrl()
+     * const execInput = await api.getExecutionInput('0x1234...')
+     * // Use with dest.execute():
+     * const { offRamp, ...input } = execInput
+     * await dest.execute({ offRamp, input, wallet })
+     * ```
      */
-    getExecutionInput(messageId: string): Promise<ExecutionInput & Lane & {
+    getExecutionInput(messageId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ExecutionInput & Lane & {
         offRamp: string;
     }>;
     /**

package/dist/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAc5C,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,MAAM,EAGX,KAAK,UAAU,EAKhB,MAAM,aAAa,CAAA;AAEpB,OAAO,KAAK,EAEV,mBAAmB,EAMpB,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAE/F,gCAAgC;AAChC,eAAO,MAAM,oBAAoB,gCAAgC,CAAA;AAEjE,uDAAuD;AACvD,eAAO,MAAM,kBAAkB,QAAQ,CAAA;AAEvC,8CAA8C;AAG9C,eAAO,MAAM,WAAW,kBAAkB,CAAA;AAG1C,gCAAgC;AAChC,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AAEjD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,aAAa;IACxB,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IASrC;;;;OAIG;gBACS,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,oBAAoB;IAuBxD;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,oBAAoB,GAAG,aAAa;IAI3E;;;;;;;OAOG;YACW,iBAAiB;IAsB/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,cAAc,CAClB,mBAAmB,EAAE,MAAM,EAC3B,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,mBAAmB,CAAC;IAiD/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IA4CtF;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA0D1D;;;;OAIG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAuGhG;;;;OAIG;IACH,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,WAAW,EAAE,UAAU,CAAC;CAkF9E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"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"}