@secondlayer/shared 7.11.2 → 9.0.0

package/dist/src/streams-rows/index.d.ts

@@ -0,0 +1,399 @@
+/** Make a cvToValue result JSON-serializable: Clarity (u)ints decode to bigint,
+*  which JSON.stringify can't handle — convert recursively to strings. */
+declare function toJsonSafe(value: unknown): unknown;
+/** Decode a hex-encoded Clarity value to JSON-safe JS (uints as strings,
+*  buffers as `0x…` hex, tuples as objects). Returns the input hex on failure. */
+declare function decodeClarityValue(hex: string): unknown;
+import { DECODED_EVENT_TYPES } from "@secondlayer/stacks/filters";
+import { DecodedEventType } from "@secondlayer/stacks/filters";
+/** Alias kept for the Streams surface (identical to {@link DECODED_EVENT_TYPES}).
+*  Explicit type annotation required — isolatedDeclarations emits `unknown` for
+*  a bare const-to-const alias. */
+declare const STREAMS_EVENT_TYPES: typeof DECODED_EVENT_TYPES;
+type StreamsEventType = DecodedEventType;
+/** 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 = {
+	/**
+	* 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>;
+/** 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
+};
+declare function requireString(payload: Record<string, unknown>, field: string, eventType: string): string;
+declare function optionalString(value: unknown): string | null;
+declare function requireAmountField(payload: Record<string, unknown>, field: string, eventType: string): string;
+declare function requireAmount(payload: Record<string, unknown>, eventType: string): string;
+declare function parseAssetIdentifier(assetIdentifier: string, eventType: string): {
+	contract_id: string
+	token_name: string | null
+};
+/** NFT token id: live streams emits a typed Clarity value at `value` and the
+*  canonical hex at `raw_value`; prefer raw_value when present. */
+declare function requireHexValue(payload: Record<string, unknown>, eventType: string): string;
+/** Common envelope fields shared by every decoded event, lifted off the
+*  source StreamsEvent. The decoder supplies event_type + decoded_payload. */
+declare function decodedRow<
+	T extends string,
+	P
+>(event: StreamsEvent, eventType: T, decoded_payload: P): {
+	cursor: string
+	block_height: number
+	tx_id: string
+	tx_index: number
+	event_index: number
+	event_type: T
+	decoded_payload: P
+	source_cursor: string
+};
+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;
+/** 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;
+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;
+/** Union of every decoded DB-row shape the guard+decode pairs produce —
+*  exactly what the `decoded_events` table stores. */
+type DecodedEventRow = DecodedFtTransfer | DecodedNftTransfer | DecodedStxTransfer | DecodedStxMint | DecodedStxBurn | DecodedStxLock | DecodedFtMint | DecodedFtBurn | DecodedNftMint | DecodedNftBurn | DecodedPrint;
+export { toJsonSafe, requireString, requireHexValue, requireAmountField, requireAmount, parseAssetIdentifier, optionalString, isStxTransfer, isStxMint, isStxLock, isStxBurn, isPrint, isNftTransfer, isNftMint, isNftBurn, isFtTransfer, isFtMint, isFtBurn, decodedRow, decodeStxTransfer, decodeStxMint, decodeStxLock, decodeStxBurn, decodePrint, decodeNftTransfer, decodeNftMint, decodeNftBurn, decodeFtTransfer, decodeFtMint, decodeFtBurn, decodeClarityValue, StxTransferPayload, StxMintPayload, StxLockPayload, StxBurnPayload, StreamsEventType, StreamsEventPayload, StreamsEventBase, StreamsEvent, StreamsClarityValue, STREAMS_EVENT_TYPES, PrintPayload, NftTransferPayload, NftTransferEvent, NftMintPayload, NftBurnPayload, FtTransferPayload, FtTransferEvent, FtMintPayload, FtBurnPayload, DecodedStxTransferPayload, DecodedStxTransfer, DecodedStxMintPayload, DecodedStxMint, DecodedStxLockPayload, DecodedStxLock, DecodedStxBurnPayload, DecodedStxBurn, DecodedPrintValue, DecodedPrintPayload, DecodedPrint, DecodedNftTransferPayload, DecodedNftTransfer, DecodedNftMintPayload, DecodedNftMint, DecodedNftBurnPayload, DecodedNftBurn, DecodedFtTransferPayload, DecodedFtTransfer, DecodedFtMintPayload, DecodedFtMint, DecodedFtBurnPayload, DecodedFtBurn, DecodedEventRow, DecodedEventColumns };