@secondlayer/sdk 15.0.1 → 15.0.2

package/dist/streams/index.d.ts

@@ -147,6 +147,7 @@ type IndexEventBase = {
 	tx_contract_id?: string | null;
 	tx_function_name?: string | null;
 };
+/** A fungible-token transfer event. */
 type IndexFtTransfer = IndexEventBase & {
 	event_type: "ft_transfer";
 	asset_identifier: string;
@@ -154,6 +155,7 @@ type IndexFtTransfer = IndexEventBase & {
 	recipient: string;
 	amount: string;
 };
+/** A non-fungible-token transfer event. */
 type IndexNftTransfer = IndexEventBase & {
 	event_type: "nft_transfer";
 	asset_identifier: string;
@@ -161,6 +163,7 @@ type IndexNftTransfer = IndexEventBase & {
 	recipient: string;
 	value: string;
 };
+/** An STX transfer event. */
 type IndexStxTransfer = IndexEventBase & {
 	event_type: "stx_transfer";
 	sender: string;
@@ -168,16 +171,19 @@ type IndexStxTransfer = IndexEventBase & {
 	amount: string;
 	memo: string | null;
 };
+/** An STX mint event. */
 type IndexStxMint = IndexEventBase & {
 	event_type: "stx_mint";
 	recipient: string;
 	amount: string;
 };
+/** An STX burn event. */
 type IndexStxBurn = IndexEventBase & {
 	event_type: "stx_burn";
 	sender: string;
 	amount: string;
 };
+/** An STX lock event with its unlock height. */
 type IndexStxLock = IndexEventBase & {
 	event_type: "stx_lock";
 	sender: string;
@@ -186,30 +192,35 @@ type IndexStxLock = IndexEventBase & {
 		unlock_height: string | null;
 	};
 };
+/** A fungible-token mint event. */
 type IndexFtMint = IndexEventBase & {
 	event_type: "ft_mint";
 	asset_identifier: string;
 	recipient: string;
 	amount: string;
 };
+/** A fungible-token burn event. */
 type IndexFtBurn = IndexEventBase & {
 	event_type: "ft_burn";
 	asset_identifier: string;
 	sender: string;
 	amount: string;
 };
+/** A non-fungible-token mint event. */
 type IndexNftMint = IndexEventBase & {
 	event_type: "nft_mint";
 	asset_identifier: string;
 	recipient: string;
 	value: string;
 };
+/** A non-fungible-token burn event. */
 type IndexNftBurn = IndexEventBase & {
 	event_type: "nft_burn";
 	asset_identifier: string;
 	sender: string;
 	value: string;
 };
+/** A contract `print` event with its topic and value. */
 type IndexPrint = IndexEventBase & {
 	event_type: "print";
 	payload: {
@@ -218,6 +229,7 @@ type IndexPrint = IndexEventBase & {
 		raw_value: string | null;
 	};
 };
+/** A contract call made from inside another contract call. */
 type IndexNestedContractCall = IndexEventBase & {
 	event_type: "nested_contract_call";
 	sender: string | null;
@@ -226,23 +238,27 @@ type IndexNestedContractCall = IndexEventBase & {
 	function_args: unknown;
 	raw_result: string | null;
 };
+/** A contract data variable write. */
 type IndexVarSet = IndexEventBase & {
 	event_type: "var_set";
 	var_name: string;
 	raw_value: string;
 };
+/** A contract map entry overwrite. */
 type IndexMapSet = IndexEventBase & {
 	event_type: "map_set";
 	map: string;
 	raw_key: string;
 	raw_value: string;
 };
+/** A new contract map entry. */
 type IndexMapInsert = IndexEventBase & {
 	event_type: "map_insert";
 	map: string;
 	raw_key: string;
 	raw_value: string;
 };
+/** A contract map entry deletion. */
 type IndexMapDelete = IndexEventBase & {
 	event_type: "map_delete";
 	map: string;
@@ -251,6 +267,7 @@ type IndexMapDelete = IndexEventBase & {
 /** Decoded chain event, discriminated by `event_type`. */
 type IndexEvent = IndexFtTransfer | IndexNftTransfer | IndexStxTransfer | IndexStxMint | IndexStxBurn | IndexStxLock | IndexFtMint | IndexFtBurn | IndexNftMint | IndexNftBurn | IndexPrint | IndexNestedContractCall | IndexVarSet | IndexMapSet | IndexMapInsert | IndexMapDelete;
 import { StreamsWireEvent as StreamsWireEvent2, RuneEtchEntry, RuneEventPayload, StreamsEventPayload } from "@secondlayer/shared/streams-rows";
+/** The chain tip: latest block, Bitcoin anchor, and finality boundary. */
 type StreamsTip = {
 	block_height: number;
 	block_hash: string;
@@ -270,15 +287,19 @@ type StreamsTip = {
 	/** Oldest seekable cursor (`<oldest_seekable_height>:0`); `null` = unlimited. */
 	oldest_cursor?: string | null;
 };
-/** `chain=bitcoin` tip — no `burn_block_height`/retention fields,
-*  since Bitcoin has no burn chain of its own and Runes reads have no
-*  retention ladder. Returned by `tip({ chain: "bitcoin" })`. */
+/**
+* The Bitcoin tip, without burn-chain or retention fields.
+*
+* Bitcoin has no burn chain of its own, and Runes reads have no retention
+* ladder. Returned by `tip({ chain: "bitcoin" })`.
+*/
 type StreamsBitcoinTip = {
 	block_height: number;
 	block_hash: string;
 	finalized_height: number;
 	lag_seconds: number;
 };
+/** A canonical Stacks block with its Bitcoin anchor. */
 type StreamsCanonicalBlock = {
 	block_height: number;
 	block_hash: string;
@@ -286,7 +307,7 @@ type StreamsCanonicalBlock = {
 	burn_block_hash: string | null;
 	is_canonical: true;
 };
-/** `chain=bitcoin` canonical block — no burn-chain fields. */
+/** A Bitcoin canonical block, without burn-chain fields. */
 type StreamsBitcoinCanonicalBlock = {
 	block_height: number;
 	block_hash: string;
@@ -307,6 +328,7 @@ type StreamsReorg = {
 	*/
 	new_canonical_tip: string;
 };
+/** One page of events with the next cursor, tip, and reorgs. */
 type StreamsEventsEnvelope<
 	TEvent = StreamsEvent,
 	TTip = StreamsTip
@@ -316,24 +338,30 @@ type StreamsEventsEnvelope<
 	tip: TTip;
 	reorgs: StreamsReorg[];
 };
+/** One page of events with the tip and reorgs, no cursor. */
 type StreamsEventsListEnvelope<
 	TEvent = StreamsEvent,
 	TTip = StreamsTip
 > = Omit<StreamsEventsEnvelope<TEvent, TTip>, "next_cursor">;
-/** The StreamsEvent union narrowed to a `types` selection — what a
-*  const-generic `types: ["ft_transfer"]` buys at the type level. */
+/**
+* The event union narrowed to a `types` selection.
+*
+* A const-generic `types: ["ft_transfer"]` narrows the event type.
+*/
 type StreamsEventOfTypes<T extends readonly StreamsEventType[]> = Extract<StreamsEvent, {
 	event_type: T[number];
 }>;
+/** A starting point and limit for listing reorgs. */
 type StreamsReorgsListParams = {
 	since: string;
 	limit?: number;
 };
+/** A list of reorgs and the cursor to resume from. */
 type StreamsReorgsListEnvelope = {
 	reorgs: StreamsReorg[];
 	next_since: string | null;
 };
-/** A filter that matches a single value or any value in a list. */
+/** A single value or a list of values to match. */
 type StreamsFilterValue = string | readonly string[];
 /**
 * One labelled filter group. Fields inside a group AND together; groups in a
@@ -363,6 +391,7 @@ type StreamsEventForFilter<
 }> : Extract<StreamsEvent, {
 	event_type: T;
 }> : D extends true ? IndexEvent : StreamsEvent;
+/** Cursor, height range, and limit shared by every list call. */
 type StreamsEventsListParamsCommon = {
 	cursor?: string | null;
 	fromHeight?: number;
@@ -390,12 +419,13 @@ type StreamsEventsStacksListParams = StreamsEventsListParamsCommon & {
 	filters?: StreamsFilterMap;
 };
 /**
-* `chain: "bitcoin"` — Runes events, own cursor space. `types` is
-* restricted to {@link RuneEventType} at the type level, so e.g.
-* `{ chain: "bitcoin", types: ["ft_transfer"] }` is a compile error rather
-* than a silent 400 at request time. `contractId`/`sender`/`recipient`/
-* `assetIdentifier`/`filters`/`clock` don't exist on this branch — they're
-* Stacks-only (the server 400s on them too).
+* List options for Runes events, with their own cursor space.
+*
+* `types` is restricted to `RuneEventType` at the type level, so e.g. `{ chain:
+* "bitcoin", types: ["ft_transfer"] }` is a compile error rather than a silent
+* 400 at request time. `contractId`, `sender`, `recipient`, `assetIdentifier`,
+* `filters`, and `clock` don't exist on this branch; they're Stacks-only (the
+* server 400s on them too).
 */
 type StreamsEventsBitcoinListParams = StreamsEventsListParamsCommon & {
 	chain: "bitcoin";
@@ -406,7 +436,9 @@ type StreamsEventsBitcoinListParams = StreamsEventsListParamsCommon & {
 	/** A mainnet address. */
 	address?: string;
 };
+/** Chain, cursor, height range, and filters for listing Streams events. */
 type StreamsEventsListParams = StreamsEventsStacksListParams | StreamsEventsBitcoinListParams;
+/** Cursor, batching, and stop options shared by every event stream. */
 type StreamsEventsStreamCommon = {
 	fromCursor?: string | null;
 	batchSize?: number;
@@ -415,8 +447,12 @@ type StreamsEventsStreamCommon = {
 	maxEmptyPolls?: number;
 	signal?: AbortSignal;
 };
-/** `chain: "stacks"` (default, omit `chain` entirely) — matches
-*  {@link StreamsEventsStacksListParams}. */
+/**
+* Stream options for Stacks events, the default chain.
+*
+* `chain: "stacks"` is the default, so omit `chain` entirely. Matches
+* `StreamsEventsStacksListParams`.
+*/
 type StreamsEventsStreamStacksParams = StreamsEventsStreamCommon & {
 	chain?: "stacks";
 	types?: readonly StreamsEventType[];
@@ -428,11 +464,14 @@ type StreamsEventsStreamStacksParams = StreamsEventsStreamCommon & {
 	/** Labelled filter groups; see {@link StreamsEventsListParams.filters}. */
 	filters?: StreamsFilterMap;
 };
-/** `chain: "bitcoin"` — Runes events, tailed the same way as
-*  the Stacks default. `types` is restricted to {@link RuneEventType} at the
-*  type level, matching {@link StreamsEventsBitcoinListParams}.
-*  `contractId`/`sender`/`recipient`/`assetIdentifier`/`filters` don't exist
-*  on this branch — they're Stacks-only. */
+/**
+* Stream options for Runes events, tailed like the Stacks default.
+*
+* `types` is restricted to `RuneEventType` at the type level, matching
+* `StreamsEventsBitcoinListParams`. `contractId`, `sender`, `recipient`,
+* `assetIdentifier`, and `filters` don't exist on this branch; they're
+* Stacks-only.
+*/
 type StreamsEventsStreamBitcoinParams = StreamsEventsStreamCommon & {
 	chain: "bitcoin";
 	types?: readonly RuneEventType[];
@@ -486,9 +525,12 @@ type StreamsEventsSubscribeStacksParams = StreamsEventsSubscribeCommon & {
 	*/
 	onEvent: (event: StreamsEvent) => void | Promise<void>;
 };
-/** `chain: "bitcoin"` — Runes events pushed live, on their own
-*  cursor space. `contractId`/`sender`/`recipient`/`assetIdentifier`/`filters`
-*  don't exist on this branch — they're Stacks-only. */
+/**
+* Options for pushing Runes events live, on their own cursor space.
+*
+* `contractId`, `sender`, `recipient`, `assetIdentifier`, and `filters` don't
+* exist on this branch; they're Stacks-only.
+*/
 type StreamsEventsSubscribeBitcoinParams = StreamsEventsSubscribeCommon & {
 	chain: "bitcoin";
 	types?: readonly RuneEventType[];
@@ -579,6 +621,7 @@ type StreamsBatchContext = ConsumerBatchContext;
 type StreamsReorgContext = {
 	cursor: string | null;
 };
+/** Options for consuming Streams events: cursor, batching, filters, handler. */
 type StreamsEventsConsumeParams<
 	TTx = never,
 	D extends boolean = false,
@@ -696,13 +739,14 @@ type StreamsEventsConsumeParams<
 	wake?: () => Promise<void>;
 };
 /**
-* `chain: "bitcoin"` — the checkpointed sweep over Runes
-* events. A separate, simpler type from {@link StreamsEventsConsumeParams}
-* rather than a widened union member: `filters`/`on`/`decoded` are Stacks-only
-* concepts (labelled OR-groups and Index-shaped projection have no Runes
-* equivalent yet), so `onBatch` is the only way in and is required. Reorg
-* rewind still works the same way (bitcoin reorgs carry the same
-* `fork_point_height` + `new_canonical_tip` shape as Stacks ones).
+* Options for the checkpointed sweep over Runes events.
+*
+* A separate, simpler type from `StreamsEventsConsumeParams` rather than a
+* widened union member: `filters`, `on`, and `decoded` are Stacks-only concepts
+* (labelled OR-groups and Index-shaped projection have no Runes equivalent
+* yet), so `onBatch` is the only way in and is required. Reorg rewind still
+* works the same way (bitcoin reorgs carry the same `fork_point_height` and
+* `new_canonical_tip` shape as Stacks ones).
 */
 type StreamsEventsConsumeBitcoinParams<TTx = never> = {
 	chain: "bitcoin";
@@ -735,9 +779,10 @@ type StreamsEventsConsumeBitcoinParams<TTx = never> = {
 	wake?: () => Promise<void>;
 };
 /**
-* One yielded page from {@link StreamsClient.consume} — the
-* `GET /v1/streams/events` envelope verbatim, with `next_cursor` renamed to
-* `cursor` (the checkpoint to persist and resume from).
+* One page yielded by `consume`, with `cursor` to persist and resume.
+*
+* It is the `GET /v1/streams/events` envelope verbatim, with `next_cursor`
+* renamed to `cursor`.
 */
 type StreamsBatch<
 	TEvent = StreamsEvent,
@@ -751,6 +796,7 @@ type StreamsBatch<
 	/** Chain reorgs reported alongside this page; empty when none. */
 	reorgs: StreamsReorg[];
 };
+/** Cursor, batch size, and polling options shared by every consume loop. */
 type StreamsConsumeCommon = {
 	/** Resume strictly after this cursor; omit to start from the oldest seekable page. */
 	cursor?: string | null;
@@ -774,9 +820,12 @@ type StreamsConsumeStacksParams = StreamsConsumeCommon & {
 	*  event echoes the labels it matched. */
 	filters?: StreamsFilterMap;
 };
-/** `chain: "bitcoin"` — Runes batches, own cursor space.
-*  `contractId`/`sender`/`recipient`/`assetIdentifier`/`filters` don't exist
-*  on this branch — they're Stacks-only. */
+/**
+* Consume options for Runes batches, with their own cursor space.
+*
+* `contractId`, `sender`, `recipient`, `assetIdentifier`, and `filters` don't
+* exist on this branch; they're Stacks-only.
+*/
 type StreamsConsumeBitcoinParams = StreamsConsumeCommon & {
 	chain: "bitcoin";
 	types?: readonly RuneEventType[];
@@ -787,11 +836,13 @@ type StreamsConsumeBitcoinParams = StreamsConsumeCommon & {
 	address?: string;
 };
 type StreamsConsumeParams = StreamsConsumeStacksParams | StreamsConsumeBitcoinParams;
+/** Where a consume loop stopped: cursor, pages read, empty polls. */
 type StreamsEventsConsumeResult = {
 	cursor: string | null;
 	pages: number;
 	emptyPolls: number;
 };
+/** Options for replaying history from dump files, then tailing live. */
 type StreamsEventsReplayParams = {
 	/** Start point: `"genesis"` (default) or a `<block>:<index>` cursor. */
 	from?: "genesis" | string;
@@ -847,6 +898,7 @@ type StreamsDumpFile = {
 	schema_version: number;
 	created_at: string;
 };
+/** The index of finalized Parquet dump files for one dataset. */
 type StreamsDumpsManifest = {
 	dataset: string;
 	network: string;