@secondlayer/sdk 5.9.0 → 6.0.0

package/dist/streams/index.d.ts

@@ -1,7 +1,76 @@
 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
@@ -9,9 +78,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).
@@ -19,6 +86,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
@@ -61,23 +138,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
@@ -89,9 +171,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
@@ -247,16 +330,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
@@ -277,18 +353,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/streams/index.js

@@ -29,6 +29,7 @@ async function consumeStreamsEvents(opts) {
       cursor,
       limit: opts.batchSize,
       types: opts.types,
+      notTypes: opts.notTypes,
       contractId: opts.contractId,
       sender: opts.sender,
       recipient: opts.recipient,
@@ -67,6 +68,7 @@ async function* streamStreamsEvents(opts) {
       cursor,
       limit: opts.batchSize,
       types: opts.types,
+      notTypes: opts.notTypes,
       contractId: opts.contractId,
       sender: opts.sender,
       recipient: opts.recipient,
@@ -202,6 +204,13 @@ function appendSearchParam(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)
@@ -245,13 +254,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) {
@@ -261,9 +273,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}`, {
@@ -277,8 +292,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;
       }
     }
@@ -288,6 +314,7 @@ function createStreamsClient(options) {
     cursor,
     limit,
     types,
+    notTypes,
     contractId,
     sender,
     recipient,
@@ -297,6 +324,7 @@ function createStreamsClient(options) {
       cursor,
       limit,
       types,
+      notTypes,
       contractId,
       sender,
       recipient,
@@ -309,13 +337,16 @@ function createStreamsClient(options) {
     appendSearchParam(searchParams, "from_height", params.fromHeight);
     appendSearchParam(searchParams, "to_height", params.toHeight);
     appendSearchParam(searchParams, "limit", params.limit);
-    appendSearchParam(searchParams, "contract_id", params.contractId);
-    appendSearchParam(searchParams, "sender", params.sender);
-    appendSearchParam(searchParams, "recipient", params.recipient);
+    appendListParam(searchParams, "contract_id", params.contractId);
+    appendListParam(searchParams, "sender", params.sender);
+    appendListParam(searchParams, "recipient", params.recipient);
     appendSearchParam(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}` : ""}`);
   }
@@ -330,6 +361,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,
@@ -347,6 +379,7 @@ function createStreamsClient(options) {
         return streamStreamsEvents({
           fromCursor: params.fromCursor,
           types: params.types,
+          notTypes: params.notTypes,
           contractId: params.contractId,
           sender: params.sender,
           recipient: params.recipient,
@@ -804,5 +837,5 @@ export {
   AuthError
 };
 
-//# debugId=AC24B4EAD103932F64756E2164756E21
+//# debugId=E556011474C772DE64756E2164756E21
 //# sourceMappingURL=index.js.map