@secondlayer/sdk 6.41.0 → 6.43.0

package/dist/streams/rows.d.ts

@@ -0,0 +1,356 @@
+import { StreamsEventType } from "@secondlayer/shared";
+/** 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
+};
+type StreamsEventBase = {
+	/**
+	* Globally unique, monotonic position of this event (`<block>:<index>`). Use
+	* it as the primary key of your projection rows — replaying a batch then
+	* upserts cleanly. Don't synthesize your own id from `tx_id`/`event_index`.
+	*/
+	cursor: string
+	block_height: number
+	block_hash: string
+	burn_block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	contract_id: string | null
+	ts: string
+	/**
+	* True when this event's block is past the finality boundary (immutable).
+	* Optional for back-compat; the API always sets it on Streams responses.
+	*/
+	finalized?: boolean
+	/**
+	* Labels whose filter group this event satisfied, present only when the
+	* request used a labelled `filters` map. The SDK dispatches on it for you
+	* (`on.<label>`), so handlers rarely read it directly.
+	*/
+	matched?: string[]
+};
+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 FtTransferEvent = Extract<StreamsEvent, {
+	event_type: "ft_transfer"
+}>;
+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 NftTransferEvent = Extract<StreamsEvent, {
+	event_type: "nft_transfer"
+}>;
+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 DecodedStxTransferPayload = {
+	sender: string
+	recipient: string
+	amount: string
+	memo: string | null
+};
+type DecodedStxTransfer = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "stx_transfer"
+	decoded_payload: DecodedStxTransferPayload
+	source_cursor: string
+};
+type DecodedStxMintPayload = {
+	recipient: string
+	amount: string
+};
+type DecodedStxMint = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "stx_mint"
+	decoded_payload: DecodedStxMintPayload
+	source_cursor: string
+};
+type DecodedStxBurnPayload = {
+	sender: string
+	amount: string
+};
+type DecodedStxBurn = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "stx_burn"
+	decoded_payload: DecodedStxBurnPayload
+	source_cursor: string
+};
+declare function isStxTransfer(event: StreamsEvent): event is StreamsEvent & {
+	event_type: "stx_transfer"
+};
+declare function decodeStxTransfer(event: StreamsEvent): DecodedStxTransfer;
+declare function isStxMint(event: StreamsEvent): event is StreamsEvent & {
+	event_type: "stx_mint"
+};
+declare function decodeStxMint(event: StreamsEvent): DecodedStxMint;
+declare function isStxBurn(event: StreamsEvent): event is StreamsEvent & {
+	event_type: "stx_burn"
+};
+declare function decodeStxBurn(event: StreamsEvent): DecodedStxBurn;
+type DecodedStxLockPayload = {
+	sender: string
+	amount: string
+	payload: {
+		unlock_height: string | null
+	}
+};
+type DecodedStxLock = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "stx_lock"
+	decoded_payload: DecodedStxLockPayload
+	source_cursor: string
+};
+declare function isStxLock(event: StreamsEvent): event is StreamsEvent & {
+	event_type: "stx_lock"
+};
+declare function decodeStxLock(event: StreamsEvent): DecodedStxLock;
+type DecodedFtMintPayload = {
+	asset_identifier: string
+	contract_id: string
+	token_name: string | null
+	recipient: string
+	amount: string
+};
+type DecodedFtMint = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "ft_mint"
+	decoded_payload: DecodedFtMintPayload
+	source_cursor: string
+};
+type DecodedFtBurnPayload = {
+	asset_identifier: string
+	contract_id: string
+	token_name: string | null
+	sender: string
+	amount: string
+};
+type DecodedFtBurn = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "ft_burn"
+	decoded_payload: DecodedFtBurnPayload
+	source_cursor: string
+};
+type DecodedNftMintPayload = {
+	asset_identifier: string
+	contract_id: string
+	token_name: string | null
+	recipient: string
+	value: string
+};
+type DecodedNftMint = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "nft_mint"
+	decoded_payload: DecodedNftMintPayload
+	source_cursor: string
+};
+type DecodedNftBurnPayload = {
+	asset_identifier: string
+	contract_id: string
+	token_name: string | null
+	sender: string
+	value: string
+};
+type DecodedNftBurn = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "nft_burn"
+	decoded_payload: DecodedNftBurnPayload
+	source_cursor: string
+};
+declare function isFtMint(event: StreamsEvent): event is StreamsEvent & {
+	event_type: "ft_mint"
+};
+declare function decodeFtMint(event: StreamsEvent): DecodedFtMint;
+declare function isFtBurn(event: StreamsEvent): event is StreamsEvent & {
+	event_type: "ft_burn"
+};
+declare function decodeFtBurn(event: StreamsEvent): DecodedFtBurn;
+declare function isNftMint(event: StreamsEvent): event is StreamsEvent & {
+	event_type: "nft_mint"
+};
+declare function decodeNftMint(event: StreamsEvent): DecodedNftMint;
+declare function isNftBurn(event: StreamsEvent): event is StreamsEvent & {
+	event_type: "nft_burn"
+};
+declare function decodeNftBurn(event: StreamsEvent): DecodedNftBurn;
+/** Decoded form of a Clarity `print` event:
+*  - `topic`: the print topic, when the contract emits a `{ topic, ... }` tuple
+*  - `value`: the Clarity value decoded to JSON (uints as strings, buffers as
+*    `0x…` hex, tuples as objects)
+*  - `raw_value`: the canonical serialized hex, for byte-exact consumers */
+type DecodedPrintValue = {
+	topic: string | null
+	value: unknown
+	raw_value: string | null
+};
+type DecodedPrintPayload = {
+	contract_id: string | null
+	payload: DecodedPrintValue
+};
+type DecodedPrint = {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: "print"
+	decoded_payload: DecodedPrintPayload
+	source_cursor: string
+};
+declare function isPrint(event: StreamsEvent): event is StreamsEvent & {
+	event_type: "print"
+};
+declare function decodePrint(event: StreamsEvent): DecodedPrint;
+/** Superset of the columns the decoded_events table holds. Every decoded
+*  event's `decoded_payload` is assignable to this, so the indexer's writer
+*  can map columns generically instead of per-event-type. */
+type DecodedEventColumns = {
+	contract_id?: string | null
+	asset_identifier?: string | null
+	sender?: string | null
+	recipient?: string | null
+	amount?: string | null
+	value?: string | null
+	memo?: string | null
+	/** JSONB overflow for non-flat types (e.g. print's decoded value). */
+	payload?: unknown
+};
+type DecodedEventRow = DecodedFtTransfer | DecodedNftTransfer | DecodedStxTransfer | DecodedStxMint | DecodedStxBurn | DecodedStxLock | DecodedFtMint | DecodedFtBurn | DecodedNftMint | DecodedNftBurn | DecodedPrint;
+export { isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, DecodedStxTransfer, DecodedStxMint, DecodedStxLock, DecodedStxBurn, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMint, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMint, DecodedFtBurn, DecodedEventRow, DecodedEventColumns };

package/dist/streams/rows.js

@@ -0,0 +1,306 @@
+// src/streams/_payload.ts
+function requireString(payload, field, eventType) {
+  const value = payload[field];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${eventType} payload missing ${field}`);
+  }
+  return value;
+}
+function optionalString(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function requireAmountField(payload, field, eventType) {
+  const amount = requireString(payload, field, eventType);
+  if (!/^(0|[1-9]\d*)$/.test(amount)) {
+    throw new Error(`${eventType} payload has malformed ${field}`);
+  }
+  return amount;
+}
+function requireAmount(payload, eventType) {
+  return requireAmountField(payload, "amount", eventType);
+}
+function parseAssetIdentifier(assetIdentifier, eventType) {
+  const [contractId, tokenName] = assetIdentifier.split("::");
+  if (!contractId) {
+    throw new Error(`${eventType} payload has malformed asset_identifier`);
+  }
+  return {
+    contract_id: contractId,
+    token_name: tokenName && tokenName.length > 0 ? tokenName : null
+  };
+}
+function requireHexValue(payload, eventType) {
+  const rawValue = payload.raw_value;
+  if (typeof rawValue === "string") {
+    if (!/^0x[0-9a-fA-F]*$/.test(rawValue)) {
+      throw new Error(`${eventType} payload has malformed value`);
+    }
+    return rawValue;
+  }
+  const value = payload.value;
+  const hex = typeof value === "string" ? value : value && typeof value === "object" && typeof value.hex === "string" ? value.hex : null;
+  if (!hex) {
+    throw new Error(`${eventType} payload missing value`);
+  }
+  if (!/^0x[0-9a-fA-F]*$/.test(hex)) {
+    throw new Error(`${eventType} payload has malformed value`);
+  }
+  return hex;
+}
+function decodedRow(event, eventType, decoded_payload) {
+  return {
+    cursor: event.cursor,
+    block_height: event.block_height,
+    tx_id: event.tx_id,
+    tx_index: event.tx_index,
+    event_index: event.event_index,
+    event_type: eventType,
+    decoded_payload,
+    source_cursor: event.cursor
+  };
+}
+
+// src/streams/ft-transfer.ts
+function isFtTransfer(event) {
+  return event.event_type === "ft_transfer";
+}
+function decodeFtTransfer(event) {
+  if (!isFtTransfer(event)) {
+    throw new Error(`Expected ft_transfer event, got ${event.event_type}`);
+  }
+  const payload = event.payload;
+  const assetIdentifier = requireString(payload, "asset_identifier", "ft_transfer");
+  const sender = requireString(payload, "sender", "ft_transfer");
+  const recipient = requireString(payload, "recipient", "ft_transfer");
+  const amount = requireAmount(payload, "ft_transfer");
+  const { contract_id, token_name } = parseAssetIdentifier(assetIdentifier, "ft_transfer");
+  return decodedRow(event, "ft_transfer", {
+    asset_identifier: assetIdentifier,
+    contract_id: event.contract_id ?? contract_id,
+    token_name,
+    sender,
+    recipient,
+    amount
+  });
+}
+// src/streams/nft-transfer.ts
+function isNftTransfer(event) {
+  return event.event_type === "nft_transfer";
+}
+function decodeNftTransfer(event) {
+  if (!isNftTransfer(event)) {
+    throw new Error(`Expected nft_transfer event, got ${event.event_type}`);
+  }
+  const payload = event.payload;
+  const assetIdentifier = requireString(payload, "asset_identifier", "nft_transfer");
+  const sender = requireString(payload, "sender", "nft_transfer");
+  const recipient = requireString(payload, "recipient", "nft_transfer");
+  const value = requireHexValue(payload, "nft_transfer");
+  const { contract_id, token_name } = parseAssetIdentifier(assetIdentifier, "nft_transfer");
+  return decodedRow(event, "nft_transfer", {
+    asset_identifier: assetIdentifier,
+    contract_id: event.contract_id ?? contract_id,
+    token_name,
+    sender,
+    recipient,
+    value
+  });
+}
+// src/clarity.ts
+import { cvToValue, deserializeCV } from "@secondlayer/stacks/clarity";
+function toJsonSafe(value) {
+  if (typeof value === "bigint")
+    return value.toString();
+  if (Array.isArray(value))
+    return value.map(toJsonSafe);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+      out[key] = toJsonSafe(val);
+    }
+    return out;
+  }
+  return value;
+}
+function decodeClarityValue(hex) {
+  try {
+    const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+    return toJsonSafe(cvToValue(deserializeCV(clean)));
+  } catch {
+    return hex;
+  }
+}
+
+// src/streams/print.ts
+function printValueHex(payload) {
+  if (typeof payload.raw_value === "string")
+    return payload.raw_value;
+  const value = payload.value;
+  if (typeof value === "string" && value.startsWith("0x"))
+    return value;
+  if (value && typeof value === "object" && typeof value.hex === "string") {
+    return value.hex;
+  }
+  return null;
+}
+function isPrint(event) {
+  return event.event_type === "print";
+}
+function decodePrint(event) {
+  if (!isPrint(event)) {
+    throw new Error(`Expected print event, got ${event.event_type}`);
+  }
+  const payload = event.payload;
+  const topic = optionalString(payload.topic);
+  const rawValue = printValueHex(payload);
+  const value = rawValue ? decodeClarityValue(rawValue) : toJsonSafe(payload.value ?? null);
+  return decodedRow(event, "print", {
+    contract_id: event.contract_id ?? optionalString(payload.contract_id),
+    payload: { topic, value, raw_value: rawValue }
+  });
+}
+// src/streams/stx-events.ts
+function isStxTransfer(event) {
+  return event.event_type === "stx_transfer";
+}
+function decodeStxTransfer(event) {
+  if (!isStxTransfer(event)) {
+    throw new Error(`Expected stx_transfer event, got ${event.event_type}`);
+  }
+  const payload = event.payload;
+  return decodedRow(event, "stx_transfer", {
+    sender: requireString(payload, "sender", "stx_transfer"),
+    recipient: requireString(payload, "recipient", "stx_transfer"),
+    amount: requireAmount(payload, "stx_transfer"),
+    memo: optionalString(payload.memo)
+  });
+}
+function isStxMint(event) {
+  return event.event_type === "stx_mint";
+}
+function decodeStxMint(event) {
+  if (!isStxMint(event)) {
+    throw new Error(`Expected stx_mint event, got ${event.event_type}`);
+  }
+  const payload = event.payload;
+  return decodedRow(event, "stx_mint", {
+    recipient: requireString(payload, "recipient", "stx_mint"),
+    amount: requireAmount(payload, "stx_mint")
+  });
+}
+function isStxBurn(event) {
+  return event.event_type === "stx_burn";
+}
+function decodeStxBurn(event) {
+  if (!isStxBurn(event)) {
+    throw new Error(`Expected stx_burn event, got ${event.event_type}`);
+  }
+  const payload = event.payload;
+  return decodedRow(event, "stx_burn", {
+    sender: requireString(payload, "sender", "stx_burn"),
+    amount: requireAmount(payload, "stx_burn")
+  });
+}
+function isStxLock(event) {
+  return event.event_type === "stx_lock";
+}
+function decodeStxLock(event) {
+  if (!isStxLock(event)) {
+    throw new Error(`Expected stx_lock event, got ${event.event_type}`);
+  }
+  const payload = event.payload;
+  return decodedRow(event, "stx_lock", {
+    sender: requireString(payload, "locked_address", "stx_lock"),
+    amount: requireAmountField(payload, "locked_amount", "stx_lock"),
+    payload: { unlock_height: optionalString(payload.unlock_height) }
+  });
+}
+// src/streams/token-mint-burn.ts
+function assetFields(event, eventType) {
+  const assetIdentifier = requireString(event.payload, "asset_identifier", eventType);
+  const { contract_id, token_name } = parseAssetIdentifier(assetIdentifier, eventType);
+  return {
+    asset_identifier: assetIdentifier,
+    contract_id: event.contract_id ?? contract_id,
+    token_name
+  };
+}
+function isFtMint(event) {
+  return event.event_type === "ft_mint";
+}
+function decodeFtMint(event) {
+  if (!isFtMint(event)) {
+    throw new Error(`Expected ft_mint event, got ${event.event_type}`);
+  }
+  return decodedRow(event, "ft_mint", {
+    ...assetFields(event, "ft_mint"),
+    recipient: requireString(event.payload, "recipient", "ft_mint"),
+    amount: requireAmount(event.payload, "ft_mint")
+  });
+}
+function isFtBurn(event) {
+  return event.event_type === "ft_burn";
+}
+function decodeFtBurn(event) {
+  if (!isFtBurn(event)) {
+    throw new Error(`Expected ft_burn event, got ${event.event_type}`);
+  }
+  return decodedRow(event, "ft_burn", {
+    ...assetFields(event, "ft_burn"),
+    sender: requireString(event.payload, "sender", "ft_burn"),
+    amount: requireAmount(event.payload, "ft_burn")
+  });
+}
+function isNftMint(event) {
+  return event.event_type === "nft_mint";
+}
+function decodeNftMint(event) {
+  if (!isNftMint(event)) {
+    throw new Error(`Expected nft_mint event, got ${event.event_type}`);
+  }
+  return decodedRow(event, "nft_mint", {
+    ...assetFields(event, "nft_mint"),
+    recipient: requireString(event.payload, "recipient", "nft_mint"),
+    value: requireHexValue(event.payload, "nft_mint")
+  });
+}
+function isNftBurn(event) {
+  return event.event_type === "nft_burn";
+}
+function decodeNftBurn(event) {
+  if (!isNftBurn(event)) {
+    throw new Error(`Expected nft_burn event, got ${event.event_type}`);
+  }
+  return decodedRow(event, "nft_burn", {
+    ...assetFields(event, "nft_burn"),
+    sender: requireString(event.payload, "sender", "nft_burn"),
+    value: requireHexValue(event.payload, "nft_burn")
+  });
+}
+export {
+  isStxTransfer,
+  isStxMint,
+  isStxLock,
+  isStxBurn,
+  isPrint,
+  isNftTransfer,
+  isNftMint,
+  isNftBurn,
+  isFtTransfer,
+  isFtMint,
+  isFtBurn,
+  decodeStxTransfer,
+  decodeStxMint,
+  decodeStxLock,
+  decodeStxBurn,
+  decodePrint,
+  decodeNftTransfer,
+  decodeNftMint,
+  decodeNftBurn,
+  decodeFtTransfer,
+  decodeFtMint,
+  decodeFtBurn
+};
+
+//# debugId=1AF7A1B9E39F783164756E2164756E21
+//# sourceMappingURL=rows.js.map