@secondlayer/sdk 5.9.0 → 6.0.0

package/README.md

@@ -19,9 +19,12 @@ const sl = new SecondLayer({
 });
 ```
 
-Reads are public during open beta — no key needed. Writes require an `sk-sl_`
-API key, created in the platform console at
-https://secondlayer.tools/platform/api-keys.
+`sl.index` and `sl.subgraphs` reads are anonymous — no key needed. **`sl.streams`
+reads require a bearer token** (`apiKey`) and resolve a per-tier tenant; a
+publicly-known free-tier token exists but a bearer is always required. Writes
+require an `sk-sl_` API key, created in the platform console at
+https://secondlayer.tools/platform/api-keys. (Public Streams bulk dumps —
+`client.dumps`, `events.replay` — need no key.)
 
 ## Mental model
 
@@ -31,16 +34,20 @@ https://secondlayer.tools/platform/api-keys.
 
 ## Stacks Streams
 
-Typed L1 HTTP client. Reads are public — no key needed.
+Typed L1 HTTP client. Reads require a bearer token (`apiKey`).
 
 ```typescript
 const tip = await sl.streams.tip();
+// tip.finalized_height — highest immutable (past Bitcoin-anchored finality) block
 const page = await sl.streams.events.list({
   types: ["ft_transfer"],
   contractId: "SP...sbtc-token",
+  sender: "SP...",       // exact payload sender (events that have one)
+  recipient: "SP...",    // exact payload recipient
+  assetIdentifier: "SP...token::asset", // exact FT/NFT asset id
   limit: 10,
 });
-
+// each event carries `finalized: boolean`
 console.log({ tip, firstCursor: page.events[0]?.cursor });
 ```
 
@@ -50,10 +57,19 @@ console.log({ tip, firstCursor: page.events[0]?.cursor });
 import { createStreamsClient } from "@secondlayer/sdk";
 
 const streams = createStreamsClient({
-  apiKey: process.env.SL_API_KEY!, // sk-sl_...
+  apiKey: process.env.SL_API_KEY!, // sk-sl_... — required for reads
+  // verify: true,                 // verify ed25519 X-Signature on every read
+  //                               // (auto-fetches the public key; { publicKey } pins a PEM)
+  // dumpsBaseUrl: process.env.SL_STREAMS_DUMPS_URL, // required to use client.dumps
 });
 ```
 
+Verified responses: every Streams read is signed (ed25519 `X-Signature` +
+`X-Signature-KeyId`). Pass `verify: true` to check it on every read (or
+`{ publicKey }` to pin a PEM); a missing/bad signature throws
+`StreamsSignatureError`. The public key is at
+`GET /public/streams/signing-key`.
+
 Convenience reads:
 
 ```typescript
@@ -102,6 +118,46 @@ for await (const event of streams.events.stream({
 }
 ```
 
+Bulk parquet dumps.
+
+Finalized history is published as public parquet files. Set `dumpsBaseUrl`
+(or `SL_STREAMS_DUMPS_URL`) — no API key needed for dumps. The SDK does **not**
+decode parquet; `download` hands you sha256-verified bytes to process with your
+own tooling.
+
+```typescript
+const streams = createStreamsClient({
+  apiKey: process.env.SL_API_KEY!,
+  dumpsBaseUrl: process.env.SL_STREAMS_DUMPS_URL!,
+});
+
+const manifest = await streams.dumps.list();       // parse the manifest
+for (const file of manifest.files) {
+  const bytes = await streams.dumps.download(file); // fetch + verify sha256
+  await myParquetReader(bytes);
+}
+```
+
+Backfill then tail (`events.replay`).
+
+Backfills from bulk dumps, then tails live from the manifest's
+`latest_finalized_cursor` — no gap or dupe at the seam. `onDumpFile` hands you
+each finalized file; `onBatch` receives live events after the seam.
+
+```typescript
+await streams.events.replay({
+  from: lastCheckpoint,
+  async onDumpFile(file) {
+    const bytes = await streams.dumps.download(file);
+    await ingestParquet(bytes); // your tooling
+  },
+  async onBatch(events, envelope) {
+    for (const event of events) await handle(event);
+    return envelope.next_cursor;
+  },
+});
+```
+
 Decoder helper.
 
 ```typescript

package/dist/index.d.ts

@@ -346,8 +346,77 @@ declare class Index extends BaseClient {
 }
 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 = {
+/** A Clarity value as Streams serves it: the canonical hex string, a typed
+*  object carrying that hex (`{ hex }`), or a decoded Clarity-JSON object.
+*  Decode helpers (`decodeNftTransfer`, etc.) resolve it to a concrete value. */
+type StreamsClarityValue = string | {
+	hex: string
+} | Record<string, unknown>;
+type StxTransferPayload = {
+	sender: string
+	recipient: string
+	amount: string
+	memo?: string
+};
+type StxMintPayload = {
+	recipient: string
+	amount: string
+};
+type StxBurnPayload = {
+	sender: string
+	amount: string
+};
+type StxLockPayload = {
+	locked_address: string
+	locked_amount: string
+	unlock_height: string
+};
+type FtTransferPayload = {
+	asset_identifier: string
+	sender: string
+	recipient: string
+	amount: string
+};
+type FtMintPayload = {
+	asset_identifier: string
+	recipient: string
+	amount: string
+};
+type FtBurnPayload = {
+	asset_identifier: string
+	sender: string
+	amount: string
+};
+type NftTransferPayload = {
+	asset_identifier: string
+	sender: string
+	recipient: string
+	value: StreamsClarityValue
+	/** Canonical serialized hex of `value`, when the stream carries it. */
+	raw_value?: string
+};
+type NftMintPayload = {
+	asset_identifier: string
+	recipient: string
+	value: StreamsClarityValue
+	raw_value?: string
+};
+type NftBurnPayload = {
+	asset_identifier: string
+	sender: string
+	value: StreamsClarityValue
+	raw_value?: string
+};
+type PrintPayload = {
+	contract_id?: string | null
+	topic?: string
+	value?: unknown
+	raw_value?: string
+};
+/** Union of every Streams payload shape, discriminated by `event_type` on the
+*  parent `StreamsEvent`. */
+type StreamsEventPayload = StxTransferPayload | StxMintPayload | StxBurnPayload | StxLockPayload | FtTransferPayload | FtMintPayload | FtBurnPayload | NftTransferPayload | NftMintPayload | NftBurnPayload | PrintPayload;
+type StreamsEventBase = {
 	cursor: string
 	block_height: number
 	block_hash: string
@@ -355,9 +424,7 @@ type StreamsEvent = {
 	tx_id: string
 	tx_index: number
 	event_index: number
-	event_type: StreamsEventType
 	contract_id: string | null
-	payload: StreamsEventPayload
 	ts: string
 	/**
 	* True when this event's block is past the finality boundary (immutable).
@@ -365,6 +432,16 @@ type StreamsEvent = {
 	*/
 	finalized?: boolean
 };
+type StreamsEventOf<
+	T extends StreamsEventType,
+	P
+> = StreamsEventBase & {
+	event_type: T
+	payload: P
+};
+/** A raw Streams event. Discriminated on `event_type`, so `event.payload`
+*  narrows to the matching payload shape once the type is checked. */
+type StreamsEvent = StreamsEventOf<"stx_transfer", StxTransferPayload> | StreamsEventOf<"stx_mint", StxMintPayload> | StreamsEventOf<"stx_burn", StxBurnPayload> | StreamsEventOf<"stx_lock", StxLockPayload> | StreamsEventOf<"ft_transfer", FtTransferPayload> | StreamsEventOf<"ft_mint", FtMintPayload> | StreamsEventOf<"ft_burn", FtBurnPayload> | StreamsEventOf<"nft_transfer", NftTransferPayload> | StreamsEventOf<"nft_mint", NftMintPayload> | StreamsEventOf<"nft_burn", NftBurnPayload> | StreamsEventOf<"print", PrintPayload>;
 type StreamsTip = {
 	block_height: number
 	block_hash: string
@@ -407,23 +484,28 @@ type StreamsReorgsListEnvelope = {
 	reorgs: StreamsReorg[]
 	next_since: string | null
 };
+/** A filter that matches a single value or any value in a list. */
+type StreamsFilterValue = string | readonly string[];
 type StreamsEventsListParams = {
 	cursor?: string | null
 	fromHeight?: number
 	toHeight?: number
 	types?: readonly StreamsEventType[]
-	contractId?: string
-	sender?: string
-	recipient?: string
+	/** Event types to exclude (applied after `types`). */
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
 	assetIdentifier?: string
 	limit?: number
 };
 type StreamsEventsStreamParams = {
 	fromCursor?: string | null
 	types?: readonly StreamsEventType[]
-	contractId?: string
-	sender?: string
-	recipient?: string
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
 	assetIdentifier?: string
 	batchSize?: number
 	emptyBackoffMs?: number
@@ -435,9 +517,10 @@ type StreamsEventsConsumeParams = {
 	fromCursor?: string | null
 	mode?: "tail" | "bounded"
 	types?: readonly StreamsEventType[]
-	contractId?: string
-	sender?: string
-	recipient?: string
+	notTypes?: readonly StreamsEventType[]
+	contractId?: StreamsFilterValue
+	sender?: StreamsFilterValue
+	recipient?: StreamsFilterValue
 	assetIdentifier?: string
 	batchSize?: number
 	onBatch: (events: StreamsEvent[], envelope: StreamsEventsEnvelope) => Promise<string | null | undefined> | string | null | undefined
@@ -647,16 +730,9 @@ declare class StreamsServerError extends Error {
 declare class StreamsSignatureError extends Error {
 	constructor(message?: string);
 }
-type FtTransferPayload = {
-	asset_identifier: string
-	sender: string
-	recipient: string
-	amount: string
-};
-type FtTransferEvent = StreamsEvent & {
+type FtTransferEvent = Extract<StreamsEvent, {
 	event_type: "ft_transfer"
-	payload: FtTransferPayload
-};
+}>;
 type DecodedFtTransferPayload = {
 	asset_identifier: string
 	contract_id: string
@@ -677,18 +753,9 @@ type DecodedFtTransfer = {
 };
 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 & {
+type NftTransferEvent = Extract<StreamsEvent, {
 	event_type: "nft_transfer"
-	payload: NftTransferPayload
-};
+}>;
 type DecodedNftTransferPayload = {
 	asset_identifier: string
 	contract_id: string

package/dist/index.js

@@ -532,6 +532,7 @@ async function consumeStreamsEvents(opts) {
       cursor,
       limit: opts.batchSize,
       types: opts.types,
+      notTypes: opts.notTypes,
       contractId: opts.contractId,
       sender: opts.sender,
       recipient: opts.recipient,
@@ -570,6 +571,7 @@ async function* streamStreamsEvents(opts) {
       cursor,
       limit: opts.batchSize,
       types: opts.types,
+      notTypes: opts.notTypes,
       contractId: opts.contractId,
       sender: opts.sender,
       recipient: opts.recipient,
@@ -705,6 +707,13 @@ function appendSearchParam2(params, name, value) {
     return;
   params.set(name, String(value));
 }
+function appendListParam(params, name, value) {
+  if (value === undefined || value === null)
+    return;
+  const joined = Array.isArray(value) ? value.join(",") : value;
+  if (joined.length > 0)
+    params.set(name, joined);
+}
 async function responseBody(response) {
   const text = await response.text();
   if (text.length === 0)
@@ -748,13 +757,16 @@ function createStreamsClient(options) {
     baseUrl: options.dumpsBaseUrl,
     fetchImpl
   });
-  let publicKeyPromise = null;
-  function getPublicKey() {
-    if (publicKeyPromise)
-      return publicKeyPromise;
-    publicKeyPromise = (async () => {
+  let keyPromise = null;
+  function loadKey() {
+    if (keyPromise)
+      return keyPromise;
+    keyPromise = (async () => {
       if (typeof verify === "object") {
-        return ed25519.loadEd25519PublicKey(verify.publicKey);
+        return {
+          keyId: ed25519.ed25519KeyId(verify.publicKey),
+          publicKey: ed25519.loadEd25519PublicKey(verify.publicKey)
+        };
       }
       const res = await fetchImpl(`${baseUrl}/public/streams/signing-key`);
       if (!res.ok) {
@@ -764,9 +776,12 @@ function createStreamsClient(options) {
       if (!body.public_key_pem) {
         throw new StreamsSignatureError("Signing key response missing key.");
       }
-      return ed25519.loadEd25519PublicKey(body.public_key_pem);
+      return {
+        keyId: body.key_id ?? ed25519.ed25519KeyId(body.public_key_pem),
+        publicKey: ed25519.loadEd25519PublicKey(body.public_key_pem)
+      };
     })();
-    return publicKeyPromise;
+    return keyPromise;
   }
   async function request(path) {
     const response = await fetchImpl(`${baseUrl}${path}`, {
@@ -780,8 +795,19 @@ function createStreamsClient(options) {
       if (!signature) {
         throw new StreamsSignatureError("Response is missing X-Signature.");
       }
-      const publicKey = await getPublicKey();
-      if (!ed25519.verifyEd25519(text, signature, publicKey)) {
+      const responseKeyId = response.headers.get("X-Signature-KeyId");
+      let key = await loadKey();
+      if (responseKeyId && responseKeyId !== key.keyId) {
+        if (typeof verify === "object") {
+          throw new StreamsSignatureError(`Response signed with key '${responseKeyId}', expected pinned key '${key.keyId}'.`);
+        }
+        keyPromise = null;
+        key = await loadKey();
+        if (responseKeyId !== key.keyId) {
+          throw new StreamsSignatureError(`Response signed with key '${responseKeyId}' not served by the signing-key endpoint.`);
+        }
+      }
+      if (!ed25519.verifyEd25519(text, signature, key.publicKey)) {
         throw new StreamsSignatureError;
       }
     }
@@ -791,6 +817,7 @@ function createStreamsClient(options) {
     cursor,
     limit,
     types,
+    notTypes,
     contractId,
     sender,
     recipient,
@@ -800,6 +827,7 @@ function createStreamsClient(options) {
       cursor,
       limit,
       types,
+      notTypes,
       contractId,
       sender,
       recipient,
@@ -812,13 +840,16 @@ function createStreamsClient(options) {
     appendSearchParam2(searchParams, "from_height", params.fromHeight);
     appendSearchParam2(searchParams, "to_height", params.toHeight);
     appendSearchParam2(searchParams, "limit", params.limit);
-    appendSearchParam2(searchParams, "contract_id", params.contractId);
-    appendSearchParam2(searchParams, "sender", params.sender);
-    appendSearchParam2(searchParams, "recipient", params.recipient);
+    appendListParam(searchParams, "contract_id", params.contractId);
+    appendListParam(searchParams, "sender", params.sender);
+    appendListParam(searchParams, "recipient", params.recipient);
     appendSearchParam2(searchParams, "asset_identifier", params.assetIdentifier);
     if (params.types?.length) {
       searchParams.set("types", params.types.join(","));
     }
+    if (params.notTypes?.length) {
+      searchParams.set("not_types", params.notTypes.join(","));
+    }
     const query = searchParams.toString();
     return request(`/v1/streams/events${query ? `?${query}` : ""}`);
   }
@@ -833,6 +864,7 @@ function createStreamsClient(options) {
           fromCursor: params.fromCursor,
           mode: params.mode,
           types: params.types,
+          notTypes: params.notTypes,
           contractId: params.contractId,
           sender: params.sender,
           recipient: params.recipient,
@@ -850,6 +882,7 @@ function createStreamsClient(options) {
         return streamStreamsEvents({
           fromCursor: params.fromCursor,
           types: params.types,
+          notTypes: params.notTypes,
           contractId: params.contractId,
           sender: params.sender,
           recipient: params.recipient,
@@ -1558,5 +1591,5 @@ export {
   ApiError
 };
 
-//# debugId=54289A1292072EB864756E2164756E21
+//# debugId=4712778CA4B6FFB664756E2164756E21
 //# sourceMappingURL=index.js.map