@secondlayer/sdk 3.3.2 → 3.5.0

package/dist/subgraphs/index.d.ts

@@ -2,11 +2,14 @@ import { ReindexResponse, SubgraphDetail, SubgraphGapsResponse, SubgraphQueryPar
 import { DeploySubgraphRequest, DeploySubgraphResponse } from "@secondlayer/shared/schemas/subgraphs";
 import { SubgraphAgentSchema, SubgraphSpecOptions } from "@secondlayer/shared/subgraphs/spec";
 import { InferSubgraphClient } from "@secondlayer/subgraphs";
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface SecondLayerOptions {
 	/** Base URL of the Secondlayer API (trailing slashes are stripped). */
 	baseUrl: string;
 	/** Bearer token for authenticated requests. */
 	apiKey?: string;
+	/** Fetch implementation. Tests and edge runtimes can provide their own. */
+	fetchImpl?: FetchLike;
 	/** Deploy origin label sent as `x-sl-origin` (telemetry). Defaults to `cli`. */
 	origin?: "cli" | "mcp" | "session";
 }
@@ -102,6 +105,210 @@ declare class Subgraphs extends BaseClient {
 	private createTableClient;
 }
 import { InferSubgraphClient as InferSubgraphClient2 } from "@secondlayer/subgraphs";
+type IndexTip = {
+	block_height: number
+	lag_seconds: number
+};
+type FtTransfer = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "ft_transfer"
+	contract_id: string
+	asset_identifier: string
+	sender: string
+	recipient: string
+	amount: string
+};
+type FtTransfersEnvelope = {
+	events: FtTransfer[]
+	next_cursor: string | null
+	tip: IndexTip
+	reorgs: never[]
+};
+type FtTransfersListParams = {
+	cursor?: string | null
+	fromCursor?: string | null
+	limit?: number
+	contractId?: string
+	sender?: string
+	recipient?: string
+	fromHeight?: number
+	toHeight?: number
+};
+type FtTransfersWalkParams = Omit<FtTransfersListParams, "limit"> & {
+	batchSize?: number
+	signal?: AbortSignal
+};
+type NftTransfer = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "nft_transfer"
+	contract_id: string
+	asset_identifier: string
+	sender: string
+	recipient: string
+	value: string
+};
+type NftTransfersEnvelope = {
+	events: NftTransfer[]
+	next_cursor: string | null
+	tip: IndexTip
+	reorgs: never[]
+};
+type NftTransfersListParams = {
+	cursor?: string | null
+	fromCursor?: string | null
+	limit?: number
+	contractId?: string
+	assetIdentifier?: string
+	sender?: string
+	recipient?: string
+	fromHeight?: number
+	toHeight?: number
+};
+type NftTransfersWalkParams = Omit<NftTransfersListParams, "limit"> & {
+	batchSize?: number
+	signal?: AbortSignal
+};
+declare class Index extends BaseClient {
+	constructor(options?: Partial<SecondLayerOptions>);
+	readonly ftTransfers: {
+		list: (params?: FtTransfersListParams) => Promise<FtTransfersEnvelope>
+		walk: (params?: FtTransfersWalkParams) => AsyncIterable<FtTransfer>
+	};
+	readonly nftTransfers: {
+		list: (params?: NftTransfersListParams) => Promise<NftTransfersEnvelope>
+		walk: (params?: NftTransfersWalkParams) => AsyncIterable<NftTransfer>
+	};
+	private listFtTransfers;
+	private listNftTransfers;
+	private walkFtTransfers;
+	private walkNftTransfers;
+}
+declare const STREAMS_EVENT_TYPES: readonly ["stx_transfer", "stx_mint", "stx_burn", "stx_lock", "ft_transfer", "ft_mint", "ft_burn", "nft_transfer", "nft_mint", "nft_burn", "print"];
+type StreamsEventType = (typeof STREAMS_EVENT_TYPES)[number];
+type StreamsEventPayload = Record<string, unknown>;
+type StreamsEvent = {
+	cursor: string
+	block_height: number
+	index_block_hash: string
+	burn_block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: StreamsEventType
+	contract_id: string | null
+	payload: StreamsEventPayload
+	ts: string
+};
+type StreamsTip = {
+	block_height: number
+	index_block_hash: string
+	burn_block_height: number
+	lag_seconds: number
+};
+type StreamsCanonicalBlock = {
+	block_height: number
+	index_block_hash: string
+	burn_block_height: number
+	burn_block_hash: string | null
+	is_canonical: true
+};
+type StreamsReorg = {
+	detected_at: string
+	fork_point_height: number
+	orphaned_range: {
+		from: string
+		to: string
+	}
+	new_canonical_tip: string
+};
+type StreamsEventsEnvelope = {
+	events: StreamsEvent[]
+	next_cursor: string | null
+	tip: StreamsTip
+	reorgs: StreamsReorg[]
+};
+type StreamsEventsListEnvelope = Omit<StreamsEventsEnvelope, "next_cursor">;
+type StreamsReorgsListParams = {
+	since: string
+	limit?: number
+};
+type StreamsReorgsListEnvelope = {
+	reorgs: StreamsReorg[]
+	next_since: string | null
+};
+type StreamsEventsListParams = {
+	cursor?: string | null
+	fromHeight?: number
+	toHeight?: number
+	types?: readonly StreamsEventType[]
+	contractId?: string
+	limit?: number
+};
+type StreamsEventsStreamParams = {
+	fromCursor?: string | null
+	types?: readonly StreamsEventType[]
+	batchSize?: number
+	emptyBackoffMs?: number
+	maxPages?: number
+	maxEmptyPolls?: number
+	signal?: AbortSignal
+};
+type StreamsEventsConsumeParams = {
+	fromCursor?: string | null
+	mode?: "tail" | "bounded"
+	types?: readonly StreamsEventType[]
+	batchSize?: number
+	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined
+	emptyBackoffMs?: number
+	maxPages?: number
+	maxEmptyPolls?: number
+	signal?: AbortSignal
+};
+type StreamsEventsConsumeResult = {
+	cursor: string | null
+	pages: number
+	emptyPolls: number
+};
+type StreamsClient = {
+	events: {
+		list(params?: StreamsEventsListParams): Promise<StreamsEventsEnvelope>
+		byTxId(txId: string): Promise<StreamsEventsListEnvelope>
+		/**
+		* Pull pages from Streams and call `onBatch` after each page.
+		*
+		* Use `consume` for indexers and ETL jobs that own checkpointing. Return
+		* the checkpoint cursor from `onBatch`. Default `mode: "tail"` keeps
+		* polling when caught up; `mode: "bounded"` exits on the first empty page.
+		* The consumer also exits when `maxPages`, `maxEmptyPolls`, or `signal`
+		* stops it.
+		*/
+		consume(params: StreamsEventsConsumeParams): Promise<StreamsEventsConsumeResult>
+		/**
+		* Follow Streams as an async iterator.
+		*
+		* Use `stream` for live processors and watch-style apps. It tails
+		* indefinitely by default and stops when its `AbortSignal`, `maxPages`, or
+		* `maxEmptyPolls` stops it.
+		*/
+		stream(params?: StreamsEventsStreamParams): AsyncIterable<StreamsEvent>
+	}
+	blocks: {
+		events(heightOrHash: number | string): Promise<StreamsEventsListEnvelope>
+	}
+	reorgs: {
+		list(params: StreamsReorgsListParams): Promise<StreamsReorgsListEnvelope>
+	}
+	canonical(height: number): Promise<StreamsCanonicalBlock>
+	tip(): Promise<StreamsTip>
+};
 import { CreateSubscriptionRequest, CreateSubscriptionResponse, DeadRow, DeliveryRow, ReplayResult, RotateSecretResponse, SubscriptionDetail, SubscriptionSummary, UpdateSubscriptionRequest } from "@secondlayer/shared/schemas/subscriptions";
 declare class Subscriptions extends BaseClient {
 	list(): Promise<{
@@ -131,6 +338,8 @@ declare class Subscriptions extends BaseClient {
 	}>;
 }
 declare class SecondLayer extends BaseClient {
+	readonly streams: StreamsClient;
+	readonly index: Index;
 	readonly subgraphs: Subgraphs;
 	readonly subscriptions: Subscriptions;
 	constructor(options?: Partial<SecondLayerOptions>);

package/dist/subgraphs/index.js

@@ -276,6 +276,370 @@ class Subgraphs extends BaseClient {
     };
   }
 }
+// src/index-api/client.ts
+function appendSearchParam(params, name, value) {
+  if (value === undefined || value === null)
+    return;
+  params.set(name, String(value));
+}
+function firstWalkFromHeight(params) {
+  if (params.fromHeight !== undefined)
+    return params.fromHeight;
+  if (params.cursor || params.fromCursor)
+    return;
+  return 0;
+}
+
+class Index extends BaseClient {
+  constructor(options = {}) {
+    super(options);
+  }
+  ftTransfers = {
+    list: (params = {}) => this.listFtTransfers(params),
+    walk: (params = {}) => this.walkFtTransfers(params)
+  };
+  nftTransfers = {
+    list: (params = {}) => this.listNftTransfers(params),
+    walk: (params = {}) => this.walkNftTransfers(params)
+  };
+  async listFtTransfers(params = {}) {
+    const searchParams = new URLSearchParams;
+    appendSearchParam(searchParams, "cursor", params.cursor);
+    appendSearchParam(searchParams, "from_cursor", params.fromCursor);
+    appendSearchParam(searchParams, "limit", params.limit);
+    appendSearchParam(searchParams, "contract_id", params.contractId);
+    appendSearchParam(searchParams, "sender", params.sender);
+    appendSearchParam(searchParams, "recipient", params.recipient);
+    appendSearchParam(searchParams, "from_height", params.fromHeight);
+    appendSearchParam(searchParams, "to_height", params.toHeight);
+    const query = searchParams.toString();
+    return this.request("GET", `/v1/index/ft-transfers${query ? `?${query}` : ""}`);
+  }
+  async listNftTransfers(params = {}) {
+    const searchParams = new URLSearchParams;
+    appendSearchParam(searchParams, "cursor", params.cursor);
+    appendSearchParam(searchParams, "from_cursor", params.fromCursor);
+    appendSearchParam(searchParams, "limit", params.limit);
+    appendSearchParam(searchParams, "contract_id", params.contractId);
+    appendSearchParam(searchParams, "asset_identifier", params.assetIdentifier);
+    appendSearchParam(searchParams, "sender", params.sender);
+    appendSearchParam(searchParams, "recipient", params.recipient);
+    appendSearchParam(searchParams, "from_height", params.fromHeight);
+    appendSearchParam(searchParams, "to_height", params.toHeight);
+    const query = searchParams.toString();
+    return this.request("GET", `/v1/index/nft-transfers${query ? `?${query}` : ""}`);
+  }
+  async* walkFtTransfers(params = {}) {
+    const batchSize = params.batchSize ?? 200;
+    let cursor = params.cursor ?? params.fromCursor ?? null;
+    let firstPage = true;
+    while (!params.signal?.aborted) {
+      const envelope = await this.listFtTransfers({
+        ...params,
+        limit: batchSize,
+        cursor: firstPage ? params.cursor : cursor,
+        fromCursor: firstPage ? params.fromCursor : undefined,
+        fromHeight: firstPage ? firstWalkFromHeight(params) : undefined
+      });
+      for (const event of envelope.events) {
+        if (params.signal?.aborted)
+          return;
+        yield event;
+      }
+      const nextCursor = envelope.next_cursor;
+      if (!nextCursor || nextCursor === cursor || envelope.events.length < batchSize) {
+        return;
+      }
+      cursor = nextCursor;
+      firstPage = false;
+    }
+  }
+  async* walkNftTransfers(params = {}) {
+    const batchSize = params.batchSize ?? 200;
+    let cursor = params.cursor ?? params.fromCursor ?? null;
+    let firstPage = true;
+    while (!params.signal?.aborted) {
+      const envelope = await this.listNftTransfers({
+        ...params,
+        limit: batchSize,
+        cursor: firstPage ? params.cursor : cursor,
+        fromCursor: firstPage ? params.fromCursor : undefined,
+        fromHeight: firstPage ? firstWalkFromHeight(params) : undefined
+      });
+      for (const event of envelope.events) {
+        if (params.signal?.aborted)
+          return;
+        yield event;
+      }
+      const nextCursor = envelope.next_cursor;
+      if (!nextCursor || nextCursor === cursor || envelope.events.length < batchSize) {
+        return;
+      }
+      cursor = nextCursor;
+      firstPage = false;
+    }
+  }
+}
+
+// src/streams/consumer.ts
+async function defaultSleep(ms, signal) {
+  if (signal?.aborted)
+    return;
+  await new Promise((resolve) => {
+    const timeout = setTimeout(resolve, ms);
+    if (!signal)
+      return;
+    signal.addEventListener("abort", () => {
+      clearTimeout(timeout);
+      resolve();
+    }, { once: true });
+  });
+}
+async function consumeStreamsEvents(opts) {
+  const sleep = opts.sleep ?? defaultSleep;
+  const mode = opts.mode ?? "tail";
+  const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
+  const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
+  const maxEmptyPolls = opts.maxEmptyPolls ?? Number.POSITIVE_INFINITY;
+  let cursor = opts.fromCursor ?? null;
+  let pages = 0;
+  let emptyPolls = 0;
+  while (pages < maxPages && emptyPolls < maxEmptyPolls && !opts.signal?.aborted) {
+    const envelope = await opts.fetchEvents({
+      cursor,
+      limit: opts.batchSize,
+      types: opts.types
+    });
+    pages++;
+    const returnedCursor = await opts.onBatch(envelope.events, envelope);
+    const nextCursor = returnedCursor ?? envelope.next_cursor;
+    if (nextCursor && nextCursor !== cursor) {
+      cursor = nextCursor;
+      emptyPolls = 0;
+      continue;
+    }
+    if (envelope.events.length === 0) {
+      emptyPolls++;
+      if (mode === "bounded") {
+        return { cursor, pages, emptyPolls };
+      }
+      await sleep(emptyBackoffMs, opts.signal);
+      continue;
+    }
+    return { cursor, pages, emptyPolls };
+  }
+  return { cursor, pages, emptyPolls };
+}
+async function* streamStreamsEvents(opts) {
+  const sleep = opts.sleep ?? defaultSleep;
+  const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
+  const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
+  const maxEmptyPolls = opts.maxEmptyPolls ?? Number.POSITIVE_INFINITY;
+  let cursor = opts.fromCursor ?? null;
+  let pages = 0;
+  let emptyPolls = 0;
+  while (pages < maxPages && emptyPolls < maxEmptyPolls && !opts.signal?.aborted) {
+    const envelope = await opts.fetchEvents({
+      cursor,
+      limit: opts.batchSize,
+      types: opts.types
+    });
+    pages++;
+    for (const event of envelope.events) {
+      if (opts.signal?.aborted)
+        return;
+      yield event;
+    }
+    const nextCursor = envelope.next_cursor;
+    if (nextCursor && nextCursor !== cursor) {
+      cursor = nextCursor;
+      emptyPolls = 0;
+      continue;
+    }
+    if (envelope.events.length === 0) {
+      emptyPolls++;
+      if (emptyPolls >= maxEmptyPolls || pages >= maxPages)
+        return;
+      await sleep(emptyBackoffMs, opts.signal);
+      continue;
+    }
+    return;
+  }
+}
+
+// src/streams/errors.ts
+class AuthError extends Error {
+  status = 401;
+  constructor(message = "API key invalid or expired.") {
+    super(message);
+    this.name = "AuthError";
+  }
+}
+
+class RateLimitError extends Error {
+  retryAfter;
+  status = 429;
+  constructor(message = "Rate limited. Try again later.", retryAfter) {
+    super(message);
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+}
+
+class ValidationError extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "ValidationError";
+  }
+}
+
+class StreamsServerError extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "StreamsServerError";
+  }
+}
+
+// src/streams/client.ts
+var DEFAULT_STREAMS_BASE_URL = "https://api.secondlayer.tools";
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/+$/, "");
+}
+function appendSearchParam2(params, name, value) {
+  if (value === undefined || value === null)
+    return;
+  params.set(name, String(value));
+}
+async function responseBody(response) {
+  const text = await response.text();
+  if (text.length === 0)
+    return;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function errorMessage(body, fallback) {
+  if (body && typeof body === "object") {
+    const record = body;
+    const message = record.error ?? record.message;
+    if (typeof message === "string" && message.length > 0)
+      return message;
+  }
+  if (typeof body === "string" && body.length > 0)
+    return body;
+  return fallback;
+}
+async function mapStreamsError(response) {
+  const body = await responseBody(response);
+  if (response.status === 401) {
+    throw new AuthError(errorMessage(body, "API key invalid or expired."));
+  }
+  if (response.status === 429) {
+    const retryAfter = response.headers.get("Retry-After") ?? undefined;
+    throw new RateLimitError(errorMessage(body, "Rate limited. Try again later."), retryAfter);
+  }
+  if (response.status >= 500) {
+    throw new StreamsServerError(errorMessage(body, `Streams server returned ${response.status}.`), response.status, body);
+  }
+  throw new ValidationError(errorMessage(body, `Streams request returned ${response.status}.`), response.status, body);
+}
+function createStreamsClient(options) {
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_STREAMS_BASE_URL);
+  const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+  async function request(path) {
+    const response = await fetchImpl(`${baseUrl}${path}`, {
+      headers: { Authorization: `Bearer ${options.apiKey}` }
+    });
+    if (!response.ok)
+      await mapStreamsError(response);
+    return await response.json();
+  }
+  const fetchEvents = async ({
+    cursor,
+    limit,
+    types
+  }) => {
+    return listEvents({ cursor, limit, types });
+  };
+  async function listEvents(params = {}) {
+    const searchParams = new URLSearchParams;
+    appendSearchParam2(searchParams, "cursor", params.cursor);
+    appendSearchParam2(searchParams, "from_height", params.fromHeight);
+    appendSearchParam2(searchParams, "to_height", params.toHeight);
+    appendSearchParam2(searchParams, "limit", params.limit);
+    appendSearchParam2(searchParams, "contract_id", params.contractId);
+    if (params.types?.length) {
+      searchParams.set("types", params.types.join(","));
+    }
+    const query = searchParams.toString();
+    return request(`/v1/streams/events${query ? `?${query}` : ""}`);
+  }
+  return {
+    events: {
+      list: listEvents,
+      byTxId(txId) {
+        return request(`/v1/streams/events/${encodeURIComponent(txId)}`);
+      },
+      consume(params) {
+        return consumeStreamsEvents({
+          fromCursor: params.fromCursor,
+          mode: params.mode,
+          types: params.types,
+          batchSize: params.batchSize ?? 100,
+          fetchEvents,
+          onBatch: params.onBatch,
+          emptyBackoffMs: params.emptyBackoffMs,
+          maxPages: params.maxPages,
+          maxEmptyPolls: params.maxEmptyPolls,
+          signal: params.signal
+        });
+      },
+      stream(params = {}) {
+        return streamStreamsEvents({
+          fromCursor: params.fromCursor,
+          types: params.types,
+          batchSize: params.batchSize ?? 100,
+          emptyBackoffMs: params.emptyBackoffMs,
+          maxPages: params.maxPages,
+          maxEmptyPolls: params.maxEmptyPolls,
+          signal: params.signal,
+          fetchEvents
+        });
+      }
+    },
+    blocks: {
+      events(heightOrHash) {
+        return request(`/v1/streams/blocks/${encodeURIComponent(String(heightOrHash))}/events`);
+      }
+    },
+    reorgs: {
+      list(params) {
+        const searchParams = new URLSearchParams;
+        appendSearchParam2(searchParams, "since", params.since);
+        appendSearchParam2(searchParams, "limit", params.limit);
+        const query = searchParams.toString();
+        return request(`/v1/streams/reorgs${query ? `?${query}` : ""}`);
+      }
+    },
+    canonical(height) {
+      return request(`/v1/streams/canonical/${height}`);
+    },
+    tip() {
+      return request("/v1/streams/tip");
+    }
+  };
+}
+
 // src/subscriptions/client.ts
 class Subscriptions extends BaseClient {
   async list() {
@@ -318,10 +682,18 @@ class Subscriptions extends BaseClient {
 
 // src/client.ts
 class SecondLayer extends BaseClient {
+  streams;
+  index;
   subgraphs;
   subscriptions;
   constructor(options = {}) {
     super(options);
+    this.streams = createStreamsClient({
+      apiKey: options.apiKey ?? "",
+      baseUrl: options.baseUrl,
+      fetchImpl: options.fetchImpl
+    });
+    this.index = new Index(options);
     this.subgraphs = new Subgraphs(options);
     this.subscriptions = new Subscriptions(options);
   }
@@ -342,5 +714,5 @@ export {
   Subgraphs
 };
 
-//# debugId=ADD697A31D92DD7264756E2164756E21
+//# debugId=E734D986870AD6AC64756E2164756E21
 //# sourceMappingURL=index.js.map