@secondlayer/sdk 6.0.0 → 6.2.0

package/dist/subgraphs/index.js

@@ -25,6 +25,19 @@ class VersionConflictError extends ApiError {
 
 // src/base.ts
 var DEFAULT_BASE_URL = "https://api.secondlayer.tools";
+function buildQuery(params) {
+  const search = new URLSearchParams;
+  for (const [name, value] of Object.entries(params)) {
+    if (value === undefined || value === null)
+      continue;
+    const serialized = Array.isArray(value) ? value.join(",") : String(value);
+    if (serialized.length === 0)
+      continue;
+    search.set(name, serialized);
+  }
+  const query = search.toString();
+  return query ? `?${query}` : "";
+}
 
 class BaseClient {
   baseUrl;
@@ -311,12 +324,143 @@ class Subgraphs extends BaseClient {
     };
   }
 }
-// src/index-api/client.ts
-function appendSearchParam(params, name, value) {
-  if (value === undefined || value === null)
-    return;
-  params.set(name, String(value));
+// src/contracts/client.ts
+class Contracts extends BaseClient {
+  constructor(options = {}) {
+    super(options);
+  }
+  list(params) {
+    return this.request("GET", `/v1/contracts${buildQuery({
+      trait: params.trait,
+      conformance: params.conformance,
+      include: params.include,
+      limit: params.limit,
+      cursor: params.cursor
+    })}`);
+  }
+}
+
+// src/datasets/client.ts
+var PARAM_KEYS = {
+  fromBlock: "from_block",
+  toBlock: "to_block",
+  functionName: "function_name",
+  delegateTo: "delegate_to",
+  signerKey: "signer_key",
+  rewardCycle: "reward_cycle",
+  eventType: "event_type",
+  bnsId: "bns_id"
+};
+var CURSOR_SLUGS = {
+  "stx-transfers": { path: "stx-transfers", rowKey: "events" },
+  "sbtc-events": { path: "sbtc/events", rowKey: "events" },
+  "sbtc-token-events": { path: "sbtc/token-events", rowKey: "events" },
+  "pox-4-calls": { path: "pox-4/calls", rowKey: "calls" },
+  "burnchain-rewards": { path: "burnchain/rewards", rowKey: "rewards" },
+  "burnchain-reward-slots": {
+    path: "burnchain/reward-slots",
+    rowKey: "slots"
+  },
+  "bns-events": { path: "bns/events", rowKey: "events" },
+  "bns-namespace-events": { path: "bns/namespace-events", rowKey: "events" },
+  "bns-marketplace-events": {
+    path: "bns/marketplace-events",
+    rowKey: "events"
+  }
+};
+
+class Datasets extends BaseClient {
+  constructor(options = {}) {
+    super(options);
+  }
+  listDatasets() {
+    return this.request("GET", "/v1/datasets");
+  }
+  async query(slug, params = {}) {
+    const d = CURSOR_SLUGS[slug];
+    if (!d) {
+      throw new Error(`unknown cursor dataset "${slug}" (use one of: ${Object.keys(CURSOR_SLUGS).join(", ")})`);
+    }
+    const env = await this.get(d.path, this.paramsToQuery(params));
+    return {
+      rows: env[d.rowKey] ?? [],
+      next_cursor: env.next_cursor ?? null,
+      tip: env.tip
+    };
+  }
+  stxTransfers = this.cursorDataset("stx-transfers", "events");
+  sbtcEvents = this.cursorDataset("sbtc/events", "events");
+  sbtcTokenEvents = this.cursorDataset("sbtc/token-events", "events");
+  pox4Calls = this.cursorDataset("pox-4/calls", "calls");
+  burnchainRewards = this.cursorDataset("burnchain/rewards", "rewards");
+  burnchainRewardSlots = this.cursorDataset("burnchain/reward-slots", "slots");
+  bnsEvents = this.cursorDataset("bns/events", "events");
+  bnsNamespaceEvents = this.cursorDataset("bns/namespace-events", "events");
+  bnsMarketplaceEvents = this.cursorDataset("bns/marketplace-events", "events");
+  bnsNames(params = {}) {
+    return this.get("bns/names", buildQuery({
+      namespace: params.namespace,
+      owner: params.owner,
+      limit: params.limit,
+      offset: params.offset
+    }));
+  }
+  bnsNamespaces() {
+    return this.get("bns/namespaces", "");
+  }
+  bnsResolve(fqn) {
+    return this.get("bns/resolve", buildQuery({ fqn }));
+  }
+  networkHealth() {
+    return this.get("network-health/summary", "");
+  }
+  get(path, query) {
+    return this.request("GET", `/v1/datasets/${path}${query}`);
+  }
+  paramsToQuery(params) {
+    const mapped = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (v === undefined || v === null || k === "batchSize" || k === "signal")
+        continue;
+      mapped[PARAM_KEYS[k] ?? k] = v;
+    }
+    return buildQuery(mapped);
+  }
+  cursorDataset(path, rowKey) {
+    const list = async (params = {}) => {
+      const envelope = await this.get(path, this.paramsToQuery(params));
+      return {
+        rows: envelope[rowKey] ?? [],
+        next_cursor: envelope.next_cursor ?? null,
+        tip: envelope.tip
+      };
+    };
+    const walk = async function* (params = {}) {
+      const batchSize = params.batchSize ?? 200;
+      let cursor = params.cursor ?? null;
+      let first = true;
+      while (!params.signal?.aborted) {
+        const env = await list({
+          ...params,
+          limit: batchSize,
+          cursor: first ? params.cursor : cursor ?? undefined
+        });
+        for (const row of env.rows) {
+          if (params.signal?.aborted)
+            return;
+          yield row;
+        }
+        if (!env.next_cursor || env.next_cursor === cursor || env.rows.length < batchSize)
+          return;
+        cursor = env.next_cursor;
+        first = false;
+      }
+    }.bind(this);
+    return { list, walk };
+  }
 }
+
+// src/index-api/client.ts
 function firstWalkFromHeight(params) {
   if (params.fromHeight !== undefined)
     return params.fromHeight;
@@ -346,31 +490,29 @@ class Index extends BaseClient {
     walk: (params = {}) => this.walkContractCalls(params)
   };
   async listFtTransfers(params = {}) {
-    const searchParams = new URLSearchParams;
-    appendSearchParam(searchParams, "cursor", params.cursor);
-    appendSearchParam(searchParams, "from_cursor", params.fromCursor);
-    appendSearchParam(searchParams, "limit", params.limit);
-    appendSearchParam(searchParams, "contract_id", params.contractId);
-    appendSearchParam(searchParams, "sender", params.sender);
-    appendSearchParam(searchParams, "recipient", params.recipient);
-    appendSearchParam(searchParams, "from_height", params.fromHeight);
-    appendSearchParam(searchParams, "to_height", params.toHeight);
-    const query = searchParams.toString();
-    return this.request("GET", `/v1/index/ft-transfers${query ? `?${query}` : ""}`);
+    return this.request("GET", `/v1/index/ft-transfers${buildQuery({
+      cursor: params.cursor,
+      from_cursor: params.fromCursor,
+      limit: params.limit,
+      contract_id: params.contractId,
+      sender: params.sender,
+      recipient: params.recipient,
+      from_height: params.fromHeight,
+      to_height: params.toHeight
+    })}`);
   }
   async listNftTransfers(params = {}) {
-    const searchParams = new URLSearchParams;
-    appendSearchParam(searchParams, "cursor", params.cursor);
-    appendSearchParam(searchParams, "from_cursor", params.fromCursor);
-    appendSearchParam(searchParams, "limit", params.limit);
-    appendSearchParam(searchParams, "contract_id", params.contractId);
-    appendSearchParam(searchParams, "asset_identifier", params.assetIdentifier);
-    appendSearchParam(searchParams, "sender", params.sender);
-    appendSearchParam(searchParams, "recipient", params.recipient);
-    appendSearchParam(searchParams, "from_height", params.fromHeight);
-    appendSearchParam(searchParams, "to_height", params.toHeight);
-    const query = searchParams.toString();
-    return this.request("GET", `/v1/index/nft-transfers${query ? `?${query}` : ""}`);
+    return this.request("GET", `/v1/index/nft-transfers${buildQuery({
+      cursor: params.cursor,
+      from_cursor: params.fromCursor,
+      limit: params.limit,
+      contract_id: params.contractId,
+      asset_identifier: params.assetIdentifier,
+      sender: params.sender,
+      recipient: params.recipient,
+      from_height: params.fromHeight,
+      to_height: params.toHeight
+    })}`);
   }
   async* walkFtTransfers(params = {}) {
     const batchSize = params.batchSize ?? 200;
@@ -423,18 +565,18 @@ class Index extends BaseClient {
     }
   }
   async listEvents(params) {
-    const searchParams = new URLSearchParams;
-    appendSearchParam(searchParams, "event_type", params.eventType);
-    appendSearchParam(searchParams, "cursor", params.cursor);
-    appendSearchParam(searchParams, "from_cursor", params.fromCursor);
-    appendSearchParam(searchParams, "limit", params.limit);
-    appendSearchParam(searchParams, "contract_id", params.contractId);
-    appendSearchParam(searchParams, "asset_identifier", params.assetIdentifier);
-    appendSearchParam(searchParams, "sender", params.sender);
-    appendSearchParam(searchParams, "recipient", params.recipient);
-    appendSearchParam(searchParams, "from_height", params.fromHeight);
-    appendSearchParam(searchParams, "to_height", params.toHeight);
-    return this.request("GET", `/v1/index/events?${searchParams.toString()}`);
+    return this.request("GET", `/v1/index/events${buildQuery({
+      event_type: params.eventType,
+      cursor: params.cursor,
+      from_cursor: params.fromCursor,
+      limit: params.limit,
+      contract_id: params.contractId,
+      asset_identifier: params.assetIdentifier,
+      sender: params.sender,
+      recipient: params.recipient,
+      from_height: params.fromHeight,
+      to_height: params.toHeight
+    })}`);
   }
   async* walkEvents(params) {
     const batchSize = params.batchSize ?? 200;
@@ -462,17 +604,16 @@ class Index extends BaseClient {
     }
   }
   async listContractCalls(params = {}) {
-    const searchParams = new URLSearchParams;
-    appendSearchParam(searchParams, "cursor", params.cursor);
-    appendSearchParam(searchParams, "from_cursor", params.fromCursor);
-    appendSearchParam(searchParams, "limit", params.limit);
-    appendSearchParam(searchParams, "contract_id", params.contractId);
-    appendSearchParam(searchParams, "function_name", params.functionName);
-    appendSearchParam(searchParams, "sender", params.sender);
-    appendSearchParam(searchParams, "from_height", params.fromHeight);
-    appendSearchParam(searchParams, "to_height", params.toHeight);
-    const query = searchParams.toString();
-    return this.request("GET", `/v1/index/contract-calls${query ? `?${query}` : ""}`);
+    return this.request("GET", `/v1/index/contract-calls${buildQuery({
+      cursor: params.cursor,
+      from_cursor: params.fromCursor,
+      limit: params.limit,
+      contract_id: params.contractId,
+      function_name: params.functionName,
+      sender: params.sender,
+      from_height: params.fromHeight,
+      to_height: params.toHeight
+    })}`);
   }
   async* walkContractCalls(params = {}) {
     const batchSize = params.batchSize ?? 200;
@@ -504,7 +645,74 @@ class Index extends BaseClient {
 // src/streams/client.ts
 import { ed25519 } from "@secondlayer/shared";
 
+// src/streams/errors.ts
+class AuthError extends Error {
+  status = 401;
+  constructor(message = "API key invalid or expired.") {
+    super(message);
+    this.name = "AuthError";
+  }
+}
+
+class RateLimitError extends Error {
+  retryAfter;
+  status = 429;
+  constructor(message = "Rate limited. Try again later.", retryAfter) {
+    super(message);
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+}
+
+class ValidationError extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "ValidationError";
+  }
+}
+
+class StreamsServerError extends Error {
+  status;
+  body;
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "StreamsServerError";
+  }
+}
+
+class StreamsSignatureError extends Error {
+  constructor(message = "Streams response signature verification failed.") {
+    super(message);
+    this.name = "StreamsSignatureError";
+  }
+}
+
+// src/streams/cursor.ts
+var Cursor = {
+  atHeight(height) {
+    return `${height}:0`;
+  },
+  parse(cursor) {
+    const parts = cursor.split(":");
+    const blockHeight = Number(parts[0]);
+    const eventIndex = Number(parts[1]);
+    if (parts.length !== 2 || !Number.isInteger(blockHeight) || !Number.isInteger(eventIndex)) {
+      throw new ValidationError(`Invalid stream cursor "${cursor}"; expected "<block>:<index>" (e.g. "951475:3").`, 400);
+    }
+    return { blockHeight, eventIndex };
+  }
+};
+
 // src/streams/consumer.ts
+function reorgKey(reorg) {
+  return `${reorg.detected_at}|${reorg.fork_point_height}|${reorg.new_canonical_tip}`;
+}
 async function defaultSleep(ms, signal) {
   if (signal?.aborted)
     return;
@@ -521,10 +729,12 @@ async function defaultSleep(ms, signal) {
 async function consumeStreamsEvents(opts) {
   const sleep = opts.sleep ?? defaultSleep;
   const mode = opts.mode ?? "tail";
+  const finalizedOnly = opts.finalizedOnly ?? false;
   const emptyBackoffMs = opts.emptyBackoffMs ?? 500;
   const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;
   const maxEmptyPolls = opts.maxEmptyPolls ?? Number.POSITIVE_INFINITY;
   let cursor = opts.fromCursor ?? null;
+  const handledReorgs = new Set;
   let pages = 0;
   let emptyPolls = 0;
   while (pages < maxPages && emptyPolls < maxEmptyPolls && !opts.signal?.aborted) {
@@ -539,14 +749,32 @@ async function consumeStreamsEvents(opts) {
       assetIdentifier: opts.assetIdentifier
     });
     pages++;
-    const returnedCursor = await opts.onBatch(envelope.events, envelope);
-    const nextCursor = returnedCursor ?? envelope.next_cursor;
+    if (!finalizedOnly && opts.onReorg) {
+      const fresh = envelope.reorgs.filter((reorg) => !handledReorgs.has(reorgKey(reorg))).sort((a, b) => a.fork_point_height - b.fork_point_height);
+      if (fresh.length > 0) {
+        const forkPoint = Math.min(...fresh.map((reorg) => reorg.fork_point_height));
+        const rewind = Cursor.atHeight(forkPoint);
+        for (const reorg of fresh) {
+          await opts.onReorg(reorg, { cursor: rewind });
+          handledReorgs.add(reorgKey(reorg));
+        }
+        cursor = rewind;
+        emptyPolls = 0;
+        continue;
+      }
+    }
+    const emitted = finalizedOnly ? envelope.events.filter((event) => event.finalized) : envelope.events;
+    const checkpoint = finalizedOnly ? emitted.at(-1)?.cursor ?? cursor : envelope.next_cursor;
+    const returnedCursor = await opts.onBatch(emitted, envelope, {
+      cursor: checkpoint
+    });
+    const nextCursor = returnedCursor ?? checkpoint;
     if (nextCursor && nextCursor !== cursor) {
       cursor = nextCursor;
       emptyPolls = 0;
       continue;
     }
-    if (envelope.events.length === 0) {
+    if (emitted.length === 0) {
       emptyPolls++;
       if (mode === "bounded") {
         return { cursor, pages, emptyPolls };
@@ -602,56 +830,6 @@ async function* streamStreamsEvents(opts) {
 
 // src/streams/dumps.ts
 import { createHash } from "node:crypto";
-
-// src/streams/errors.ts
-class AuthError extends Error {
-  status = 401;
-  constructor(message = "API key invalid or expired.") {
-    super(message);
-    this.name = "AuthError";
-  }
-}
-
-class RateLimitError extends Error {
-  retryAfter;
-  status = 429;
-  constructor(message = "Rate limited. Try again later.", retryAfter) {
-    super(message);
-    this.retryAfter = retryAfter;
-    this.name = "RateLimitError";
-  }
-}
-
-class ValidationError extends Error {
-  status;
-  body;
-  constructor(message, status, body) {
-    super(message);
-    this.status = status;
-    this.body = body;
-    this.name = "ValidationError";
-  }
-}
-
-class StreamsServerError extends Error {
-  status;
-  body;
-  constructor(message, status, body) {
-    super(message);
-    this.status = status;
-    this.body = body;
-    this.name = "StreamsServerError";
-  }
-}
-
-class StreamsSignatureError extends Error {
-  constructor(message = "Streams response signature verification failed.") {
-    super(message);
-    this.name = "StreamsSignatureError";
-  }
-}
-
-// src/streams/dumps.ts
 function createStreamsDumps(opts) {
   const baseUrl = opts.baseUrl?.replace(/\/+$/, "");
   function requireBaseUrl() {
@@ -690,8 +868,12 @@ function createStreamsDumps(opts) {
 function cursorTuple(cursor) {
   if (!cursor)
     return [-1, -1];
-  const [block, index] = cursor.split(":");
-  return [Number(block), Number(index)];
+  const parts = cursor.split(":");
+  const [block, index] = parts.map(Number);
+  if (parts.length !== 2 || !Number.isInteger(block) || !Number.isInteger(index)) {
+    throw new ValidationError(`Invalid stream cursor "${cursor}"; expected "<block>:<index>" (e.g. "951475:3").`, 400);
+  }
+  return [block, index];
 }
 function maxCursor(a, b) {
   const [ah, ai] = cursorTuple(a);
@@ -702,18 +884,6 @@ var DEFAULT_STREAMS_BASE_URL = "https://api.secondlayer.tools";
 function normalizeBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
-function appendSearchParam2(params, name, value) {
-  if (value === undefined || value === null)
-    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)
@@ -835,23 +1005,18 @@ function createStreamsClient(options) {
     });
   };
   async function listEvents(params = {}) {
-    const searchParams = new URLSearchParams;
-    appendSearchParam2(searchParams, "cursor", params.cursor);
-    appendSearchParam2(searchParams, "from_height", params.fromHeight);
-    appendSearchParam2(searchParams, "to_height", params.toHeight);
-    appendSearchParam2(searchParams, "limit", params.limit);
-    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}` : ""}`);
+    return request(`/v1/streams/events${buildQuery({
+      cursor: params.cursor,
+      from_height: params.fromHeight,
+      to_height: params.toHeight,
+      limit: params.limit,
+      contract_id: params.contractId,
+      sender: params.sender,
+      recipient: params.recipient,
+      asset_identifier: params.assetIdentifier,
+      types: params.types,
+      not_types: params.notTypes
+    })}`);
   }
   return {
     events: {
@@ -863,6 +1028,7 @@ function createStreamsClient(options) {
         return consumeStreamsEvents({
           fromCursor: params.fromCursor,
           mode: params.mode,
+          finalizedOnly: params.finalizedOnly,
           types: params.types,
           notTypes: params.notTypes,
           contractId: params.contractId,
@@ -872,6 +1038,7 @@ function createStreamsClient(options) {
           batchSize: params.batchSize ?? 100,
           fetchEvents,
           onBatch: params.onBatch,
+          onReorg: params.onReorg,
           emptyBackoffMs: params.emptyBackoffMs,
           maxPages: params.maxPages,
           maxEmptyPolls: params.maxEmptyPolls,
@@ -926,11 +1093,10 @@ function createStreamsClient(options) {
     },
     reorgs: {
       list(params) {
-        const searchParams = new URLSearchParams;
-        appendSearchParam2(searchParams, "since", params.since);
-        appendSearchParam2(searchParams, "limit", params.limit);
-        const query = searchParams.toString();
-        return request(`/v1/streams/reorgs${query ? `?${query}` : ""}`);
+        return request(`/v1/streams/reorgs${buildQuery({
+          since: params.since,
+          limit: params.limit
+        })}`);
       }
     },
     dumps,
@@ -987,6 +1153,8 @@ class Subscriptions extends BaseClient {
 class SecondLayer extends BaseClient {
   streams;
   index;
+  datasets;
+  contracts;
   subgraphs;
   subscriptions;
   constructor(options = {}) {
@@ -997,6 +1165,8 @@ class SecondLayer extends BaseClient {
       fetchImpl: options.fetchImpl
     });
     this.index = new Index(options);
+    this.datasets = new Datasets(options);
+    this.contracts = new Contracts(options);
     this.subgraphs = new Subgraphs(options);
     this.subscriptions = new Subscriptions(options);
   }
@@ -1017,5 +1187,5 @@ export {
   Subgraphs
 };
 
-//# debugId=9589AE42EB31EABA64756E2164756E21
+//# debugId=9C60733D992A531964756E2164756E21
 //# sourceMappingURL=index.js.map