@secondlayer/sdk 3.3.2 → 3.4.0

package/README.md

@@ -19,6 +19,107 @@ const sl = new SecondLayer({
 });
 ```
 
+## Stacks Streams
+
+Typed HTTP client.
+
+`sk-sl_streams_status_public` is a public, non-secret Free-tier key used by the
+Second Layer status page. Production apps should use their own Streams API key.
+
+```typescript
+import { createStreamsClient } from "@secondlayer/sdk";
+
+const client = createStreamsClient({
+  apiKey: process.env.SECONDLAYER_API_KEY!,
+  baseUrl: process.env.SECONDLAYER_API_URL,
+});
+
+const tip = await client.tip();
+const page = await client.events.list({
+  types: ["ft_transfer"],
+  limit: 10,
+});
+
+console.log({ tip, firstCursor: page.events[0]?.cursor });
+```
+
+Checkpointed consumer.
+
+Use `client.events.consume` for indexers and ETL jobs. Write your database rows
+inside `onBatch`, then return the cursor you committed. It exits when
+`maxPages`, `maxEmptyPolls`, or `signal` stops it.
+
+```typescript
+import { createStreamsClient } from "@secondlayer/sdk";
+
+const client = createStreamsClient({
+  apiKey: process.env.SECONDLAYER_API_KEY!,
+});
+
+await client.events.consume({
+  types: ["ft_transfer"],
+  batchSize: 100,
+  maxPages: 1,
+  onBatch: async (events, envelope) => {
+    for (const event of events) {
+      console.log(event.cursor, event.tx_id);
+    }
+    return envelope.next_cursor;
+  },
+});
+```
+
+Live stream.
+
+Use `client.events.stream` for live processors and watch-style apps. It follows
+the tip indefinitely. Stop it with an `AbortSignal`.
+
+```typescript
+import { createStreamsClient } from "@secondlayer/sdk";
+
+const client = createStreamsClient({
+  apiKey: process.env.SECONDLAYER_API_KEY!,
+});
+
+const abort = new AbortController();
+process.once("SIGINT", () => abort.abort());
+
+for await (const event of client.events.stream({
+  types: ["ft_transfer"],
+  batchSize: 100,
+  signal: abort.signal,
+})) {
+  console.log(event.cursor, event.tx_id);
+}
+```
+
+Decoder helper.
+
+```typescript
+import {
+  createStreamsClient,
+  decodeFtTransfer,
+  isFtTransfer,
+} from "@secondlayer/sdk";
+
+const client = createStreamsClient({
+  apiKey: process.env.SECONDLAYER_API_KEY!,
+});
+
+for await (const event of client.events.stream({ types: ["ft_transfer"] })) {
+  if (!isFtTransfer(event)) continue;
+  const transfer = decodeFtTransfer(event);
+  console.log(transfer.decoded_payload);
+  break;
+}
+```
+
+Helper convention: each event helper is a pure function with no shared state.
+Use `is<EventName>(event)` as the type guard and `decode<EventName>(event)` as
+the decoder. Decoders throw when the event type or payload is malformed. Add new
+helpers beside `src/streams/ft-transfer.ts` and export them through
+`src/streams/index.ts`.
+
 ## Subgraphs
 
 Deploy and query subgraphs (custom indexers).

package/dist/index.d.ts

@@ -102,6 +102,92 @@ 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;
+}
 import { CreateSubscriptionRequest, CreateSubscriptionResponse, DeadRow, DeliveryRow, ReplayResult, RotateSecretResponse, SubscriptionDetail, SubscriptionSummary, UpdateSubscriptionRequest } from "@secondlayer/shared/schemas/subscriptions";
 import { CreateSubscriptionRequest as CreateSubscriptionRequest2, CreateSubscriptionResponse as CreateSubscriptionResponse2, DeadRow as DeadRow2, DeliveryRow as DeliveryRow2, ReplayResult as ReplayResult2, RotateSecretResponse as RotateSecretResponse2, SubscriptionDetail as SubscriptionDetail2, SubscriptionFormat, SubscriptionRuntime, SubscriptionStatus, SubscriptionSummary as SubscriptionSummary2, UpdateSubscriptionRequest as UpdateSubscriptionRequest2 } from "@secondlayer/shared/schemas/subscriptions";
 declare class Subscriptions extends BaseClient {
@@ -132,6 +218,7 @@ declare class Subscriptions extends BaseClient {
 	}>;
 }
 declare class SecondLayer extends BaseClient {
+	readonly index: Index;
 	readonly subgraphs: Subgraphs;
 	readonly subscriptions: Subscriptions;
 	constructor(options?: Partial<SecondLayerOptions>);
@@ -154,6 +241,188 @@ declare function getSubgraph<T extends {
 	name: string
 	schema: Record<string, unknown>
 }>(def: T, options?: Partial<SecondLayerOptions> | SecondLayer | Subgraphs): InferSubgraphClient2<T>;
+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 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 StreamsEventsListParams = {
+	cursor?: string | null
+	fromHeight?: number
+	toHeight?: number
+	types?: readonly StreamsEventType[]
+	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 FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+type StreamsClient = {
+	events: {
+		list(params?: StreamsEventsListParams): Promise<StreamsEventsEnvelope>
+		/**
+		* 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>
+	}
+	tip(): Promise<StreamsTip>
+};
+type CreateStreamsClientOptions = {
+	apiKey: string
+	baseUrl?: string
+	fetchImpl?: FetchLike
+};
+declare function createStreamsClient(options: CreateStreamsClientOptions): StreamsClient;
+declare class AuthError extends Error {
+	readonly status = 401;
+	constructor(message?: string);
+}
+declare class RateLimitError extends Error {
+	readonly retryAfter?: string;
+	readonly status = 429;
+	constructor(message?: string, retryAfter?: string);
+}
+declare class ValidationError extends Error {
+	readonly status: number;
+	readonly body?: unknown;
+	constructor(message: string, status: number, body?: unknown);
+}
+declare class StreamsServerError extends Error {
+	readonly status: number;
+	readonly body?: unknown;
+	constructor(message: string, status: number, body?: unknown);
+}
+type FtTransferPayload = {
+	asset_identifier: string
+	sender: string
+	recipient: string
+	amount: string
+};
+type FtTransferEvent = StreamsEvent & {
+	event_type: "ft_transfer"
+	payload: FtTransferPayload
+};
+type DecodedFtTransferPayload = {
+	asset_identifier: string
+	contract_id: string
+	token_name: string | null
+	sender: string
+	recipient: string
+	amount: string
+};
+type DecodedFtTransfer = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "ft_transfer"
+	decoded_payload: DecodedFtTransferPayload
+	source_cursor: string
+};
+declare function isFtTransfer(event: StreamsEvent): event is FtTransferEvent;
+declare function decodeFtTransfer(event: StreamsEvent): DecodedFtTransfer;
+type NftTransferPayload = {
+	asset_identifier: string
+	sender: string
+	recipient: string
+	value: string | {
+		hex: string
+	}
+};
+type NftTransferEvent = StreamsEvent & {
+	event_type: "nft_transfer"
+	payload: NftTransferPayload
+};
+type DecodedNftTransferPayload = {
+	asset_identifier: string
+	contract_id: string
+	token_name: string | null
+	sender: string
+	recipient: string
+	value: string
+};
+type DecodedNftTransfer = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "nft_transfer"
+	decoded_payload: DecodedNftTransferPayload
+	source_cursor: string
+};
+declare function isNftTransfer(event: StreamsEvent): event is NftTransferEvent;
+declare function decodeNftTransfer(event: StreamsEvent): DecodedNftTransfer;
+type DecodedEventRow = DecodedFtTransfer | DecodedNftTransfer;
 import { SubgraphAgentSchema as SubgraphAgentSchema3, SubgraphSpecFormat as SubgraphSpecFormat2, SubgraphSpecOptions as SubgraphSpecOptions3 } from "@secondlayer/shared/subgraphs/spec";
 /**
 * Error thrown by {@link SecondLayer} when an API request fails.
@@ -214,4 +483,4 @@ declare class VersionConflictError extends ApiError {
 * ```
 */
 declare function verifyWebhookSignature(rawBody: string, signatureHeader: string, secret: string, toleranceSeconds?: number): boolean;
-export { verifyWebhookSignature, getSubgraph, VersionConflictError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphAgentSchema3 as SubgraphAgentSchema, SecondLayerOptions, SecondLayer, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, DeliveryRow2 as DeliveryRow, DeadRow2 as DeadRow, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, ApiError };
+export { verifyWebhookSignature, isNftTransfer, isFtTransfer, getSubgraph, decodeNftTransfer, decodeFtTransfer, createStreamsClient, VersionConflictError, ValidationError, UpdateSubscriptionRequest2 as UpdateSubscriptionRequest, Subscriptions, SubscriptionSummary2 as SubscriptionSummary, SubscriptionStatus, SubscriptionRuntime, SubscriptionFormat, SubscriptionDetail2 as SubscriptionDetail, Subgraphs, SubgraphSpecOptions3 as SubgraphSpecOptions, SubgraphSpecFormat2 as SubgraphSpecFormat, SubgraphAgentSchema3 as SubgraphAgentSchema, StreamsTip, StreamsServerError, StreamsReorg, StreamsEventsStreamParams, StreamsEventsListParams, StreamsEventsEnvelope, StreamsEventsConsumeResult, StreamsEventsConsumeParams, StreamsEventType, StreamsEventPayload, StreamsEvent, StreamsClient, SecondLayerOptions, SecondLayer, RotateSecretResponse2 as RotateSecretResponse, ReplayResult2 as ReplayResult, RateLimitError, NftTransfersWalkParams, NftTransfersListParams, NftTransfersEnvelope, NftTransferPayload, NftTransferEvent, NftTransfer, IndexTip, Index, FtTransfersWalkParams, FtTransfersListParams, FtTransfersEnvelope, FtTransferPayload, FtTransferEvent, FtTransfer, FetchLike, DeliveryRow2 as DeliveryRow, DecodedNftTransferPayload, DecodedNftTransfer, DecodedFtTransferPayload, DecodedFtTransfer, DecodedEventRow, DeadRow2 as DeadRow, CreateSubscriptionResponse2 as CreateSubscriptionResponse, CreateSubscriptionRequest2 as CreateSubscriptionRequest, AuthError, ApiError };