@secondlayer/sdk 10.1.1 → 10.3.0

package/dist/index.js

@@ -110,6 +110,39 @@ class ValidationError extends ApiError {
     this.name = "ValidationError";
   }
 }
+
+class ArchiveSignatureError extends SecondLayerError {
+  constructor(message = "Archive manifest signature is missing or invalid.") {
+    super(message, { code: "ARCHIVE_SIGNATURE", retryable: false });
+    this.name = "ArchiveSignatureError";
+  }
+}
+
+class ArchiveAuthError extends SecondLayerError {
+  constructor(message = "Archive ops request was not authenticated.") {
+    super(message, { code: "ARCHIVE_AUTH", retryable: false });
+    this.name = "ArchiveAuthError";
+  }
+}
+
+class InsufficientArchiveCreditsError extends SecondLayerError {
+  shortfallUsdMicros;
+  constructor(message = "Insufficient archive credits.", shortfallUsdMicros) {
+    super(message, {
+      code: "INSUFFICIENT_ARCHIVE_CREDITS",
+      retryable: false
+    });
+    this.name = "InsufficientArchiveCreditsError";
+    this.shortfallUsdMicros = shortfallUsdMicros;
+  }
+}
+
+class ArchiveGateNotConfiguredError extends SecondLayerError {
+  constructor(message = "The archive gate is not configured on the server.") {
+    super(message, { code: "ARCHIVE_GATE_NOT_CONFIGURED", retryable: false });
+    this.name = "ArchiveGateNotConfiguredError";
+  }
+}
 function parseRetryAfter(value) {
   if (!value)
     return;
@@ -139,33 +172,55 @@ function raceAbort(promise, signal) {
   });
 }
 var LOCAL_API_URL = "http://127.0.0.1:3800";
+var INSTANCE_TOKEN_ENV = "INSTANCE_TOKEN";
+var ACCOUNT_KEY_ENV = "SECONDLAYER_API_KEY";
+var warnedUrlAlias = false;
 function resolveBaseUrl(explicit) {
   if (explicit && explicit.length > 0)
     return explicit.replace(/\/+$/, "");
   if (typeof process !== "undefined") {
-    const fromEnv = process.env?.SL_API_URL || process.env?.SECONDLAYER_API_URL;
-    if (fromEnv)
-      return fromEnv.replace(/\/+$/, "");
+    const primary = process.env?.SECONDLAYER_API_URL || undefined;
+    if (primary)
+      return primary.replace(/\/+$/, "");
+    const legacy = process.env?.SL_API_URL || undefined;
+    if (legacy) {
+      if (!warnedUrlAlias) {
+        warnedUrlAlias = true;
+        console.warn("[secondlayer] SL_API_URL is a legacy alias of SECONDLAYER_API_URL; using the alias this once.");
+      }
+      return legacy.replace(/\/+$/, "");
+    }
   }
   return LOCAL_API_URL;
 }
-var CREDENTIAL_ENV_VARS = ["INSTANCE_TOKEN", "SL_API_KEY"];
-var warnedConflicts = new Set;
 function resolveApiKey(apiKey) {
   if (apiKey !== undefined)
     return apiKey;
   if (typeof process === "undefined")
     return;
-  const instanceToken = process.env?.INSTANCE_TOKEN || undefined;
-  const legacyKey = process.env?.SL_API_KEY || undefined;
-  if (instanceToken && legacyKey && instanceToken !== legacyKey) {
-    const pair = `${instanceToken}\x00${legacyKey}`;
-    if (!warnedConflicts.has(pair)) {
-      warnedConflicts.add(pair);
-      console.warn("[secondlayer] INSTANCE_TOKEN and SL_API_KEY are set to different values — using INSTANCE_TOKEN (SL_API_KEY is a legacy alias for it).");
+  const token = process.env?.INSTANCE_TOKEN || undefined;
+  return token;
+}
+var warnedArchiveAlias = false;
+function resolveAccountKey(accountKey) {
+  if (accountKey !== undefined)
+    return accountKey;
+  if (typeof process === "undefined")
+    return;
+  const primary = process.env?.SECONDLAYER_API_KEY || undefined;
+  const slAlias = process.env?.SL_API_KEY || undefined;
+  const archiveAlias = process.env?.SL_ARCHIVE_API_KEY || undefined;
+  if (primary)
+    return primary;
+  const legacy = slAlias ?? archiveAlias;
+  if (legacy) {
+    if (!warnedArchiveAlias) {
+      warnedArchiveAlias = true;
+      console.warn("[secondlayer] SL_API_KEY / SL_ARCHIVE_API_KEY are legacy aliases of SECONDLAYER_API_KEY; using the alias this once.");
     }
+    return legacy;
   }
-  return instanceToken ?? legacyKey;
+  return;
 }
 function seg(value) {
   return encodeURIComponent(String(value));
@@ -814,6 +869,244 @@ class Subgraphs extends BaseClient {
     };
   }
 }
+// src/archive/client.ts
+import { createHash } from "node:crypto";
+import {
+  checkSignature,
+  loadReference
+} from "@secondlayer/shared/archive/reference";
+var OFFICIAL_ARCHIVE_HOST = "archive.secondlayer.tools";
+var DEFAULT_ARCHIVE_BASE_URL = "https://archive.secondlayer.tools";
+var DEFAULT_ARCHIVE_OPS_URL = "https://api.secondlayer.tools";
+var MAX_FETCH_BATCH = 64;
+var ARCHIVE_CREDENTIAL_RE = /^s[ks]-sl_/;
+function quoteFromBody(body) {
+  return {
+    partitions: body.partitions,
+    bundles: body.bundles,
+    usdMicros: body.usd_micros,
+    usd: body.usd,
+    freeAllowanceAppliedMicros: body.free_allowance_applied_micros,
+    allowanceRemainingBundles: body.allowance_remaining_bundles,
+    balanceUsdMicros: body.balance_usd_micros,
+    sufficient: body.sufficient
+  };
+}
+function stripSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function createArchiveClient(options = {}) {
+  const accountKey = resolveAccountKey(options.accountKey ?? options.apiKey);
+  const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+  const archiveBaseUrl = stripSlash(options.archiveBaseUrl ?? DEFAULT_ARCHIVE_BASE_URL);
+  const archiveOpsUrl = stripSlash(options.archiveOpsUrl ?? DEFAULT_ARCHIVE_OPS_URL);
+  const verifyManifest = options.verifyManifest ?? true;
+  const pinnedPem = options.publicKeyPem;
+  let keyPromise = null;
+  async function fetchSigningKey() {
+    if (pinnedPem)
+      return pinnedPem;
+    if (keyPromise)
+      return keyPromise;
+    const pending = (async () => {
+      const res = await fetchImpl(`${archiveOpsUrl}/public/streams/signing-key`);
+      if (!res.ok) {
+        throw new ArchiveSignatureError(`Could not fetch archive signing key (${res.status}).`);
+      }
+      const body = await res.json();
+      if (typeof body.public_key_pem !== "string") {
+        throw new ArchiveSignatureError("Signing key response missing key.");
+      }
+      return body.public_key_pem;
+    })();
+    keyPromise = pending;
+    pending.catch(() => {
+      if (keyPromise === pending)
+        keyPromise = null;
+    });
+    return pending;
+  }
+  async function throwOpsError(response) {
+    const envelope = parseErrorEnvelope(await response.text());
+    if (response.status === 401) {
+      throw new ArchiveAuthError(envelope.message ?? "Archive ops request was not authenticated.");
+    }
+    if (response.status === 402) {
+      const raw = envelope.body && typeof envelope.body === "object" && "shortfall_usd_micros" in envelope.body ? Number(envelope.body.shortfall_usd_micros) : undefined;
+      throw new InsufficientArchiveCreditsError(envelope.message ?? "Insufficient archive credits.", Number.isFinite(raw) ? raw : undefined);
+    }
+    if (response.status === 503) {
+      throw new ArchiveGateNotConfiguredError(envelope.message ?? "The archive gate is not configured on the server.");
+    }
+    throw new ApiError(response.status, envelope.message ?? `Archive ops returned ${response.status}.`, envelope.body, envelope.code);
+  }
+  async function opsRequest(method, path, body, authed = true) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (authed && accountKey) {
+      if (!ARCHIVE_CREDENTIAL_RE.test(accountKey)) {
+        throw new ArchiveAuthError("archive ops need SECONDLAYER_API_KEY (sk-sl_*), not INSTANCE_TOKEN");
+      }
+      headers.Authorization = `Bearer ${accountKey}`;
+    }
+    const response = await fetchImpl(`${archiveOpsUrl}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined
+    });
+    if (!response.ok)
+      await throwOpsError(response);
+    return await response.json();
+  }
+  async function load(against, opts = {}) {
+    if (!/^https?:\/\//i.test(against)) {
+      throw new ValidationError("archive.load() accepts only http(s) URLs; local paths stay on the CLI.", 400);
+    }
+    const insecure = opts.insecure === true;
+    const publicKeyPem = pinnedPem ?? (verifyManifest && !insecure ? await fetchSigningKey() : undefined);
+    const ref = await loadReference(against, {
+      publicKeyPem,
+      fetchImpl
+    });
+    const signature = checkSignature(ref.manifest, publicKeyPem, insecure);
+    if (verifyManifest && !insecure && !signature.verified) {
+      throw new ArchiveSignatureError(signature.reason ?? "Archive manifest signature is missing or invalid.");
+    }
+    return { ...ref, signature };
+  }
+  async function latest(against, opts = {}) {
+    return load(against ?? `${archiveBaseUrl}/latest.json`, opts);
+  }
+  async function status() {
+    const response = await fetchImpl(`${archiveBaseUrl}/status.json`);
+    if (!response.ok) {
+      throw new ApiError(response.status, `Could not fetch archive status (${response.status}).`);
+    }
+    return response.json();
+  }
+  function partitions(ref, filter) {
+    let list = ref.manifest.partitions ?? [];
+    if (!filter)
+      return list;
+    if (filter.dataset) {
+      list = list.filter((p) => p.dataset === filter.dataset);
+    }
+    const fromBlock = filter.fromBlock;
+    if (fromBlock !== undefined) {
+      list = list.filter((p) => p.to_block >= fromBlock);
+    }
+    const toBlock = filter.toBlock;
+    if (toBlock !== undefined) {
+      list = list.filter((p) => p.from_block <= toBlock);
+    }
+    return list;
+  }
+  async function quote(input) {
+    const body = await opsRequest("POST", "/api/archive/quote", { paths: input.paths, flow: input.flow });
+    return quoteFromBody(body);
+  }
+  async function fetchPartitions(input) {
+    const urls = [];
+    let chargedTotalUsdMicros = 0;
+    let balanceAfterUsdMicros = 0;
+    for (let i = 0;i < input.paths.length; i += MAX_FETCH_BATCH) {
+      const chunk = input.paths.slice(i, i + MAX_FETCH_BATCH);
+      const body = await opsRequest("POST", "/api/archive/fetch", { paths: chunk, flow: input.flow });
+      for (const item of body.urls) {
+        urls.push({
+          path: item.path,
+          url: item.url,
+          expiresAt: item.expires_at,
+          chargedUsdMicros: item.charged_usd_micros
+        });
+      }
+      chargedTotalUsdMicros += body.charged_total_usd_micros;
+      balanceAfterUsdMicros = body.balance_after_usd_micros;
+    }
+    return { urls, chargedTotalUsdMicros, balanceAfterUsdMicros };
+  }
+  async function download(partition, opts) {
+    let url = opts?.url;
+    if (!url) {
+      let official = false;
+      try {
+        official = new URL(archiveBaseUrl).hostname === OFFICIAL_ARCHIVE_HOST;
+      } catch {
+        official = false;
+      }
+      if (official) {
+        throw new ValidationError("Official archive host requires a presigned URL from archive.fetch() before download.", 400);
+      }
+      url = `${archiveBaseUrl}/${partition.path.replace(/^\/+/, "")}`;
+    }
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+      throw new ApiError(response.status, `Could not download ${partition.path} (${response.status}).`);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== partition.sha256) {
+      throw new ArchiveSignatureError(`${partition.path} sha256 mismatch (expected ${partition.sha256}, got ${digest}).`);
+    }
+    return bytes;
+  }
+  return {
+    latest,
+    load,
+    status,
+    partitions,
+    quote,
+    fetch: fetchPartitions,
+    download,
+    credits: {
+      async balance() {
+        const body = await opsRequest("GET", "/api/billing/status");
+        return {
+          creditsUsdMicros: body.creditsUsdMicros,
+          refill: body.refill
+        };
+      },
+      async checkout(input) {
+        const body = await opsRequest("POST", "/api/public/credits/checkout", { email: input.email, amount: input.pack }, false);
+        return { url: body.url };
+      },
+      async refill(input) {
+        const payload = "off" in input && input.off ? { belowUsd: null } : {
+          belowUsd: input.belowUsd,
+          packUsd: input.packUsd
+        };
+        const body = await opsRequest("POST", "/api/billing/refill", payload);
+        return { belowUsd: body.belowUsd, packUsd: body.packUsd };
+      }
+    }
+  };
+}
+
+// src/archive/instance.ts
+import {
+  diagnoseInstanceStatus
+} from "@secondlayer/shared/archive/instance-diagnosis";
+function createArchiveVerify(request) {
+  return (input) => request("POST", "/v1/archive/verify", {
+    against: input.against,
+    target: input.target ?? "raw",
+    from_block: input.fromBlock,
+    to_block: input.toBlock,
+    insecure: input.insecure,
+    public_key_pem: input.publicKeyPem
+  });
+}
+function createInstanceClient(request) {
+  async function status() {
+    return request("GET", "/public/status");
+  }
+  async function diagnose() {
+    return diagnoseInstanceStatus(await status());
+  }
+  return { status, diagnose };
+}
+
 // src/contracts/client.ts
 class Contracts extends BaseClient {
   constructor(options = {}) {
@@ -1786,7 +2079,7 @@ function decode(event) {
 }
 
 // src/streams/dumps.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import { verifyStreamsBulkManifestSignature } from "@secondlayer/shared/streams-bulk-manifest";
 function createStreamsDumps(opts) {
   const baseUrl = opts.baseUrl?.replace(/\/+$/, "");
@@ -1838,7 +2131,7 @@ function createStreamsDumps(opts) {
     if (!res.body) {
       throw new StreamsServerError(`Dump ${file.path} response has no body.`, 0);
     }
-    const hash = createHash("sha256");
+    const hash = createHash2("sha256");
     const chunks = [];
     let total = 0;
     const reader = res.body.getReader();
@@ -2232,6 +2525,8 @@ class SecondLayer extends BaseClient {
   contracts;
   subgraphs;
   subscriptions;
+  archive;
+  instance;
   constructor(options = {}) {
     super(options);
     this.streams = createStreamsClient({
@@ -2247,17 +2542,36 @@ class SecondLayer extends BaseClient {
     this.contracts = new Contracts(options);
     this.subgraphs = new Subgraphs(options);
     this.subscriptions = new Subscriptions(options);
+    const request = (method, path, body) => this.request(method, path, body);
+    this.archive = {
+      ...createArchiveClient({
+        accountKey: options.accountKey,
+        fetchImpl: options.fetchImpl,
+        archiveBaseUrl: options.archiveBaseUrl,
+        archiveOpsUrl: options.archiveOpsUrl
+      }),
+      verify: createArchiveVerify(request)
+    };
+    this.instance = createInstanceClient(request);
   }
   async batch(requests) {
     return this.request("POST", "/v1/batch", { requests });
   }
   async context() {
-    const [account, streamsTip, indexEnv, subgraphsRes, subscriptionsRes] = await Promise.all([
+    const [
+      account,
+      streamsTip,
+      indexEnv,
+      subgraphsRes,
+      subscriptionsRes,
+      instance
+    ] = await Promise.all([
       contextField(this.request("GET", "/api/accounts/me")),
       contextField(this.streams.tip()),
       contextField(this.index.canonical.list({ limit: 1 })),
       contextField(this.subgraphs.list()),
-      contextField(this.subscriptions.list())
+      contextField(this.subscriptions.list()),
+      contextField(this.instance.diagnose())
     ]);
     const subgraphs = {
       value: subgraphsRes.value?.data ?? null,
@@ -2309,7 +2623,8 @@ class SecondLayer extends BaseClient {
       },
       subgraphs,
       subscriptions,
-      activeOperations
+      activeOperations,
+      instance
     };
   }
 }
@@ -2562,6 +2877,7 @@ export {
   shutdownSignal,
   resolveBaseUrl,
   resolveApiKey,
+  resolveAccountKey,
   parseRetryAfter,
   isStxTransfer,
   isStxMint,
@@ -2591,6 +2907,7 @@ export {
   decodeChainWebhook,
   decode,
   createStreamsClient,
+  createArchiveClient,
   contextField,
   consumerHealth,
   consumeIndexFeed,
@@ -2603,15 +2920,20 @@ export {
   SecondLayer,
   RateLimitError,
   LOCAL_API_URL,
+  InsufficientArchiveCreditsError,
   Index,
+  INSTANCE_TOKEN_ENV,
   INDEX_MAX_PAGE_SIZE,
   DEFAULT_REQUEST_TIMEOUT_MS,
   Cursor,
   Contracts,
-  CREDENTIAL_ENV_VARS,
   AuthError,
-  ApiError
+  ArchiveSignatureError,
+  ArchiveGateNotConfiguredError,
+  ArchiveAuthError,
+  ApiError,
+  ACCOUNT_KEY_ENV
 };
 
-//# debugId=CDF488058C75012864756E2164756E21
+//# debugId=4C4D7DCC9A7B5FE064756E2164756E21
 //# sourceMappingURL=index.js.map