@candledottv/agent-sdk 0.6.9 → 0.6.11

package/dist/index.js

@@ -4389,6 +4389,201 @@ async function readPerpsHistoryPage(req) {
   return kind === "fills" ? { ...envelope, fills: page } : { ...envelope, funding: page };
 }
 
+// src/token-clusters.ts
+var CLUSTER_REASONS = [
+  "disabled",
+  "invalid_config",
+  "unsupported_chain",
+  "invalid_mint",
+  "key_missing",
+  "gate_uncalibrated",
+  "market_data_missing",
+  "market_data_stale",
+  "token_too_new",
+  "gate_not_met",
+  "not_indexed",
+  "empty_analysis",
+  "invalid_response",
+  "timeout",
+  "upstream_unavailable",
+  "upstream_4xx",
+  "upstream_5xx",
+  "rate_limited",
+  "quota_exhausted",
+  "budget_exhausted",
+  "budget_unavailable",
+  "request_in_progress",
+  "transport_error",
+  "internal_unavailable"
+];
+var CLUSTER_MESSAGE = "Cluster analysis not available for this token";
+var CLUSTER_LABEL = "Third-party cluster analysis";
+var CLUSTER_CAVEAT = "Third-party estimates of linked wallets. Exchange, pool and service wallets may be grouped together. These figures do not establish common ownership, insider conduct or wrongdoing.";
+function clusterUnavailable(mint, reason, retryAt) {
+  return {
+    status: "unavailable",
+    mint,
+    reason,
+    message: CLUSTER_MESSAGE,
+    ...retryAt !== undefined && Number.isFinite(retryAt) ? { retryAt: new Date(retryAt).toISOString() } : {}
+  };
+}
+function readClusterResult(value, mint) {
+  if (!value || typeof value !== "object")
+    return null;
+  const v = value;
+  if (v.mint !== mint)
+    return null;
+  if (v.status === "unavailable" && CLUSTER_REASONS.includes(v.reason)) {
+    const retry = v.retryAt === undefined ? undefined : typeof v.retryAt === "string" ? Date.parse(v.retryAt) : NaN;
+    if (retry !== undefined && !Number.isFinite(retry))
+      return null;
+    return clusterUnavailable(mint, v.reason, retry);
+  }
+  if (v.status !== "available" || v.chain !== "solana" || v.source !== "third_party" || !["hit", "miss"].includes(v.cache) || typeof v.fetchedAt !== "string" || typeof v.expiresAt !== "string" || !Number.isFinite(Date.parse(v.fetchedAt)) || !(Date.parse(v.expiresAt) > Date.parse(v.fetchedAt)))
+    return null;
+  const a = v.analysis;
+  const percent = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 && n <= 100;
+  if (!a || !percent(a.clusterSupplyPct) || !Array.isArray(a.clusters) || !a.clusters.length || a.clusters.length > 100)
+    return null;
+  let addresses = 0;
+  for (const c of a.clusters) {
+    if (!c || !percent(c.supplyPct) || c.supplyPct > a.clusterSupplyPct + 0.01 || !Array.isArray(c.addresses) || !Array.isArray(c.tags) || c.tags.length > 32 || c.tags.some((t) => typeof t !== "string" || t.length > 100) || c.addresses.some((x) => typeof x !== "string" || !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(x)))
+      return null;
+    addresses += c.addresses.length;
+  }
+  if (addresses > 1000 || a.clusterSupplyPct === 0 && a.clusters.every((c) => c.supplyPct === 0))
+    return null;
+  return {
+    status: "available",
+    chain: "solana",
+    mint,
+    source: "third_party",
+    label: CLUSTER_LABEL,
+    caveat: CLUSTER_CAVEAT,
+    fetchedAt: v.fetchedAt,
+    expiresAt: v.expiresAt,
+    cache: v.cache,
+    analysis: {
+      clusterSupplyPct: a.clusterSupplyPct,
+      clusters: a.clusters.map((c) => ({ supplyPct: c.supplyPct, addresses: [...c.addresses], tags: [...c.tags] }))
+    }
+  };
+}
+
+// src/token-pages.ts
+class TokenPageError extends CandleApiError {
+  idempotencyKey;
+  latest;
+  retryAfterHeader;
+  constructor(error, options = {}) {
+    super(error);
+    this.name = "TokenPageError";
+    this.idempotencyKey = options.idempotencyKey;
+    this.latest = options.latest;
+    this.retryAfterHeader = options.retryAfterHeader ?? null;
+  }
+}
+function createTokenPagesClient(io) {
+  function path(token, suffix = "") {
+    return `/api/v1/token-pages/${encodeURIComponent(token.chain)}/${encodeURIComponent(token.address)}${suffix}`;
+  }
+  function query(options = {}) {
+    const params = new URLSearchParams;
+    if (options.limit !== undefined)
+      params.set("limit", String(options.limit));
+    if (options.cursor !== undefined)
+      params.set("cursor", options.cursor);
+    return params.size ? `?${params}` : "";
+  }
+  async function request(method, url, authenticated, body, idempotencyKey) {
+    const headers = io.headers(authenticated);
+    if (body !== undefined)
+      headers["content-type"] = "application/json";
+    if (idempotencyKey !== undefined)
+      headers["Idempotency-Key"] = idempotencyKey;
+    const init = {
+      method,
+      headers,
+      redirect: "error",
+      cache: "no-store",
+      ...body !== undefined ? { body: JSON.stringify(body) } : {}
+    };
+    const attempts = idempotencyKey === undefined ? 1 : 2;
+    for (let attempt = 0;attempt < attempts; attempt++) {
+      let response;
+      let text;
+      try {
+        response = await io.fetch(`${io.apiUrl()}${url}`, init);
+        text = await response.text();
+      } catch {
+        if (attempt + 1 < attempts)
+          continue;
+        throw new TokenPageError(new CandleApiError({
+          code: idempotencyKey ? "OUTCOME_UNKNOWN" : "NETWORK_ERROR",
+          status: 0,
+          message: idempotencyKey ? "No complete answer; replay the same body with this idempotency key." : "No complete answer from Candle.",
+          retryable: true
+        }), { idempotencyKey });
+      }
+      if (!response.ok) {
+        let refusal = {};
+        try {
+          refusal = JSON.parse(text);
+        } catch {}
+        const error = refusal?.success === false && typeof refusal.error === "string" ? new CandleApiError({
+          code: refusal.error,
+          message: `Token page request refused (${refusal.error}).`,
+          status: response.status,
+          retryable: false
+        }) : candleApiErrorFromResponse(response.status, text);
+        throw new TokenPageError(error, {
+          idempotencyKey,
+          latest: refusal?.latest,
+          retryAfterHeader: response.headers.get("retry-after")
+        });
+      }
+      try {
+        const envelope = JSON.parse(text);
+        if (envelope?.success !== true || !("data" in envelope))
+          throw new Error;
+        return envelope.data;
+      } catch {
+        throw new TokenPageError(new CandleApiError({
+          code: idempotencyKey ? "OUTCOME_UNKNOWN" : "BAD_RESPONSE",
+          message: "Candle returned an invalid response.",
+          status: response.status,
+          retryable: false
+        }), { idempotencyKey });
+      }
+    }
+    throw new Error("Unreachable");
+  }
+  async function write(method, url, body, options = {}) {
+    const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+    if (!idempotencyKey.length || idempotencyKey.length > 128)
+      throw new Error("idempotencyKey must be 1 to 128 characters");
+    return { data: await request(method, url, true, body, idempotencyKey), idempotencyKey };
+  }
+  const sectionPath = (section) => `/sections/${encodeURIComponent(section)}`;
+  return {
+    updates: (token, options) => request("GET", path(token, `/updates${query(options)}`), false),
+    postUpdate: (token, body, options) => write("POST", path(token, "/updates"), body, options),
+    deletePost: (token, id, options) => write("DELETE", path(token, `/posts/${encodeURIComponent(id)}`), {}, options),
+    seen: (token) => request("GET", path(token, "/seen"), true),
+    markSeen: (token, visibleUpdateSequence, options) => write("POST", path(token, "/seen"), { visibleUpdateSequence }, options),
+    about: (token) => request("GET", path(token), false),
+    capabilities: (token) => request("GET", path(token, "/capabilities"), true),
+    burns: (token, options) => request("GET", path(token, `/burns${query(options)}`), false),
+    history: (token, section, options) => request("GET", path(token, `${sectionPath(section)}/history${query(options)}`), false),
+    creatorChallenge: (token) => request("POST", path(token, "/creator-challenges"), true, {}),
+    claim: (token, body, options) => write("POST", path(token, "/claims"), body, options),
+    setSection: (token, section, body, options) => write("PUT", path(token, sectionPath(section)), body, options),
+    restoreSection: (token, section, body, options) => write("POST", path(token, `${sectionPath(section)}/restore`), body, options),
+    flag: (token, body, options) => write("POST", path(token, "/flags"), body, options)
+  };
+}
+
 // src/wallet-import.ts
 import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
 import { CipherSuite, DhkemP256HkdfSha256, HkdfSha256 } from "@hpke/core";
@@ -4607,6 +4802,7 @@ function isAtomicSubmitOutcome(value) {
   return false;
 }
 var DEFAULT_MAX_RETRIES = 3;
+var CLUSTER_READ_TIMEOUT_MS = 12000;
 var DEFAULT_POLL_MS = 2000;
 var DEFAULT_WAIT_TIMEOUT_MS = 180000;
 function isLoopbackHost(hostname) {
@@ -4696,6 +4892,18 @@ function keyedRedirectGuard(doFetch) {
 }
 
 class CandleClient {
+  tokenPages = createTokenPagesClient({
+    fetch: (input, init) => this.fetchImpl(input, init),
+    apiUrl: () => this.apiUrl,
+    headers: (authenticated) => {
+      if (authenticated)
+        this.requireKey("tokenPages");
+      const headers = this.headers();
+      if (!authenticated)
+        delete headers["x-api-key"];
+      return headers;
+    }
+  });
   apiUrl;
   apiKey;
   fetchImpl;
@@ -4861,9 +5069,48 @@ class CandleClient {
       nextCursor: body.nextCursor
     };
   }
+  async getTokenCard(chain, mint, opts = {}) {
+    const query = opts.tag !== undefined ? `?${new URLSearchParams({ cst: opts.tag }).toString()}` : "";
+    const body = await this.requestJson("GET", `/api/v1/tokens/${chain}/${encodeURIComponent(mint)}/card${query}`);
+    return body.card;
+  }
+  async editTokenMetadata(request, opts = {}) {
+    this.requireKey("editTokenMetadata()");
+    const body = {
+      ...request.description !== undefined ? { description: request.description } : {},
+      ...request.socials !== undefined ? { socials: request.socials } : {}
+    };
+    const res = await this.fetchImpl(`${this.apiUrl}/api/v1/tokens/${request.chain}/${encodeURIComponent(request.mint)}/metadata`, {
+      method: "PATCH",
+      headers: { ...this.headers({ json: true }), "Idempotency-Key": opts.idempotencyKey ?? crypto.randomUUID() },
+      body: JSON.stringify(body)
+    });
+    return (await this.parseResponse(res)).payload;
+  }
+  async tokenMetadataHistory(params) {
+    const query = new URLSearchParams({
+      ...params.limit !== undefined ? { limit: String(params.limit) } : {},
+      ...params.cursor !== undefined ? { cursor: params.cursor } : {}
+    }).toString();
+    const body = await this.requestJson("GET", `/api/v1/tokens/${params.chain}/${encodeURIComponent(params.mint)}/metadata/history${query ? `?${query}` : ""}`);
+    return body.payload;
+  }
   async verify(chain, mint) {
     return this.requestJson("GET", `/api/v1/verify/${chain}/${encodeURIComponent(mint)}`);
   }
+  async getTokenClusters(mint, opts = {}) {
+    const chain = opts.chain ?? "solana";
+    try {
+      const res = await this.fetchImpl(`${this.apiUrl}/api/v1/tokens/${encodeURIComponent(mint)}/clusters?chain=${encodeURIComponent(chain)}`, { method: "GET", cache: "no-store", signal: AbortSignal.timeout(CLUSTER_READ_TIMEOUT_MS) });
+      noteLatestSdkVersion(res.headers?.get?.("x-candle-sdk-latest") ?? null);
+      if (res.ok) {
+        const body = JSON.parse(await res.text());
+        if (body?.success === true)
+          return readClusterResult(body.data, mint) ?? clusterUnavailable(mint, "transport_error");
+      }
+    } catch {}
+    return clusterUnavailable(mint, "transport_error");
+  }
   async getOwnProfile() {
     this.requireKey("getOwnProfile()");
     return this.requestJson("GET", "/api/v1/agent/keys/self/public-profile");
@@ -6504,7 +6751,7 @@ function generateClientLaunchId() {
 function generateClientTradeId() {
   return generateSdkId();
 }
-var SDK_VERSION = "0.6.9";
+var SDK_VERSION = "0.6.11";
 var sdkUpdateWarned = false;
 function noteLatestSdkVersion(value) {
   if (sdkUpdateWarned || !value || !/^\d+\.\d+\.\d+$/.test(value))
@@ -6629,6 +6876,107 @@ class KeychainSecretStore {
     await this.exec("secret-tool", ["clear", "service", SERVICE, "account", ref]);
   }
 }
+// src/lab.ts
+var LAB_DEFAULT_URL = "https://api.hacc.fun";
+var LAB_PATH = "/v1/strategy-lab";
+var LAB_CALL_TIMEOUT_MS = 1e4;
+var LAB_REPLAY_INTERVAL_MS = 5000;
+var LAB_REPLAY_TIMEOUT_MS = 660000;
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function transportRefusal(code, message) {
+  return { ok: false, refusal: { status: 0, code, message } };
+}
+function query(values) {
+  const search = new URLSearchParams;
+  for (const [key, value] of Object.entries(values))
+    if (value !== undefined)
+      search.set(key, String(value));
+  return search.size ? `?${search}` : "";
+}
+function createLabClient(options) {
+  const base = new URL(options.apiUrl ?? LAB_DEFAULT_URL);
+  if (base.protocol !== "https:" || base.username || base.password || base.search || base.hash) {
+    throw new Error("The lab needs an HTTPS CANDLE_HACC_URL without credentials, query or fragment.");
+  }
+  const root = base.toString().replace(/\/+$/, "");
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const callMs = options.callTimeoutMs ?? LAB_CALL_TIMEOUT_MS;
+  const now = options.now ?? Date.now;
+  const sleep3 = options.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+  async function call(method, path, valid = () => true, body, timeoutMs = callMs) {
+    const controller = new AbortController;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    try {
+      const response = await doFetch(`${root}${LAB_PATH}${path}`, {
+        method,
+        redirect: "error",
+        signal: controller.signal,
+        headers: {
+          authorization: `Bearer ${options.apiKey}`,
+          accept: "application/json",
+          ...body !== undefined ? { "content-type": "application/json" } : {}
+        },
+        ...body !== undefined ? { body: JSON.stringify(body) } : {}
+      });
+      const received = await response.json().catch(() => {
+        return;
+      });
+      if (timedOut)
+        return transportRefusal("TIMEOUT", "The lab request timed out.");
+      if (!response.ok) {
+        return {
+          ok: false,
+          refusal: {
+            status: response.status,
+            code: record(received) && typeof received.code === "string" ? received.code : `HTTP_${response.status}`,
+            message: record(received) && typeof received.error === "string" ? received.error : `Lab request failed (${response.status}).`,
+            body: received
+          }
+        };
+      }
+      if (!record(received) || !valid(received)) {
+        return transportRefusal("BAD_RESPONSE", "The lab returned an unreadable response.");
+      }
+      return { ok: true, status: response.status, body: received };
+    } catch {
+      return transportRefusal(timedOut ? "TIMEOUT" : "NETWORK_ERROR", timedOut ? "The lab request timed out." : "Could not reach the lab.");
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  const jobPath = (id) => `/replay/${encodeURIComponent(String(id))}`;
+  const validId = (id) => typeof id === "string" && id.length > 0 || typeof id === "number" && Number.isSafeInteger(id) && id > 0;
+  const validJob = (body) => validId(body.job_id) && typeof body.status === "string";
+  return {
+    status: () => call("GET", "/status", (b) => typeof b.plan === "string" && typeof b.allowed === "boolean" && record(b.replays)),
+    replay: (body) => call("POST", "/replay", (b) => validId(b.job_id), body),
+    replayGet: (id) => call("GET", jobPath(id), validJob),
+    replayCancel: (id) => call("POST", `${jobPath(id)}/cancel`),
+    runners: (q = {}) => call("GET", `/runners${query(q)}`),
+    edges: (q = {}) => call("GET", `/edges${query(q)}`),
+    async waitForReplay(id, wait = {}) {
+      const intervalMs = wait.intervalMs ?? LAB_REPLAY_INTERVAL_MS;
+      const timeoutMs = wait.timeoutMs ?? LAB_REPLAY_TIMEOUT_MS;
+      if (!Number.isFinite(intervalMs) || intervalMs <= 0 || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("Replay polling interval and timeout must be positive finite numbers.");
+      }
+      const deadline = now() + timeoutMs;
+      while (now() < deadline) {
+        const answer = await call("GET", jobPath(id), validJob, undefined, Math.min(callMs, deadline - now()));
+        if (!answer.ok || !["pending", "running"].includes(answer.body.status))
+          return answer;
+        await sleep3(Math.min(intervalMs, Math.max(0, deadline - now())));
+      }
+      return transportRefusal("REPLAY_TIMEOUT", `Replay ${id} is still pending or running. Read it with candle lab replay get ${id}.`);
+    }
+  };
+}
 // src/plans.ts
 var PLAN_CAPABILITY_NOTE = "A capability marked yes is what the plan allows. It is subject to the deployment's own switches (perps and own-wallet bridges each have one) and to the wallet, scopes and setup the feature needs. Every plan can launch a token from its embedded wallet, with an optional dev buy (same transaction on Solana; best-effort follow-up on Hood), through the headless launch; the two launch rows are additional routes, not the only ones.";
 var PLAN_CAPABILITY_LABELS = {
@@ -6717,28 +7065,28 @@ function newClientTurnId() {
   return crypto.randomUUID();
 }
 function quantRefusalCode(body) {
-  const record = asRecord(body);
-  if (typeof record?.code === "string")
-    return record.code;
-  const inner = asRecord(record?.error);
+  const record2 = asRecord(body);
+  if (typeof record2?.code === "string")
+    return record2.code;
+  const inner = asRecord(record2?.error);
   return typeof inner?.code === "string" ? inner.code : undefined;
 }
 function asRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
 }
 function refusalOf(status, body) {
-  const record = asRecord(body) ?? {};
-  const relayCode = typeof record.code === "string" ? record.code : undefined;
+  const record2 = asRecord(body) ?? {};
+  const relayCode = typeof record2.code === "string" ? record2.code : undefined;
   const code = quantRefusalCode(body) ?? `HTTP_${status}`;
   const refusal = { code, status, shape: relayCode !== undefined ? "relay" : "envelope" };
-  if (typeof record.retryable === "boolean")
-    refusal.retryable = record.retryable;
-  if (typeof record.resetsAt === "string" || typeof record.resetsAt === "number")
-    refusal.resetsAt = record.resetsAt;
-  if (typeof record.turnId === "string")
-    refusal.turnId = record.turnId;
-  if (typeof record.limit === "number")
-    refusal.limit = record.limit;
+  if (typeof record2.retryable === "boolean")
+    refusal.retryable = record2.retryable;
+  if (typeof record2.resetsAt === "string" || typeof record2.resetsAt === "number")
+    refusal.resetsAt = record2.resetsAt;
+  if (typeof record2.turnId === "string")
+    refusal.turnId = record2.turnId;
+  if (typeof record2.limit === "number")
+    refusal.limit = record2.limit;
   return refusal;
 }
 function parseStatus(body) {
@@ -6873,12 +7221,12 @@ function createQuantKeyClient(options) {
     }),
     cancel: (turnId) => call("POST", `${turnPath(turnId)}/cancel`, (body) => asRecord(body) ?? {}, { timeoutMs: callMs }),
     history: (input = {}) => {
-      const query = new URLSearchParams;
+      const query2 = new URLSearchParams;
       if (input.before !== undefined)
-        query.set("before", input.before);
+        query2.set("before", input.before);
       if (input.limit !== undefined)
-        query.set("limit", String(input.limit));
-      const encoded = query.toString();
+        query2.set("limit", String(input.limit));
+      const encoded = query2.toString();
       const suffix = encoded ? `?${encoded}` : "";
       return call("GET", `/history${suffix}`, parseHistory, { timeoutMs: callMs });
     }
@@ -7083,9 +7431,11 @@ export {
   encryptWalletKeyForImport,
   effectivePerpsRisk,
   createQuantKeyClient,
+  createLabClient,
   TradeLegOutcomeError,
   TradeLandedUnconfirmedError,
   TradeLandedFeeLegError,
+  TokenPageError,
   SelfLaunchOutcomeError,
   QUANT_POLL_TIMEOUT_MS,
   QUANT_DEFAULT_MAX_TEXT_CHARS,
@@ -7103,6 +7453,11 @@ export {
   PERPS_FUNDING_HISTORY_MAX_MS,
   PERPS_FLATTEN_MAX_STEPS,
   PERPS_CANDLE_INTERVALS,
+  LAB_REPLAY_TIMEOUT_MS,
+  LAB_REPLAY_INTERVAL_MS,
+  LAB_PATH,
+  LAB_DEFAULT_URL,
+  LAB_CALL_TIMEOUT_MS,
   KeychainSecretStore,
   JsonRpcError,
   InMemorySecretStore,
@@ -7116,6 +7471,10 @@ export {
   CandleOperationError,
   CandleClient,
   CandleApiError,
+  CLUSTER_REASONS,
+  CLUSTER_MESSAGE,
+  CLUSTER_LABEL,
+  CLUSTER_CAVEAT,
   CANDLE_PERPS_WITHDRAW_PINS,
   CANDLE_HYPERLIQUID_BUILDER_ADDRESS,
   BRIDGE_ERROR_CODES

package/dist/lab.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Dependency-free hacc strategy lab client (BE-2038, strategy lab spec R18).
+ * The CLI carries a byte-identical copy. Copy changes verbatim:
+ * `cp packages/sdk/src/lab.ts packages/cli/src/lab.ts`.
+ * Bodies, including refusals and older results without a lead card, are kept unchanged.
+ */
+export declare const LAB_DEFAULT_URL = "https://api.hacc.fun";
+export declare const LAB_PATH = "/v1/strategy-lab";
+export declare const LAB_CALL_TIMEOUT_MS = 10000;
+export declare const LAB_REPLAY_INTERVAL_MS = 5000;
+export declare const LAB_REPLAY_TIMEOUT_MS = 660000;
+export type LabRecord = Record<string, unknown>;
+export type LabJobId = string | number;
+export interface LabStatus extends LabRecord {
+    plan: string;
+    allowed: boolean;
+    replays: {
+        cap: number | null;
+        used: number | null;
+        resets_at: string;
+    };
+    active_job_id: LabJobId | null;
+}
+export interface LabReplayInput {
+    definition: LabRecord;
+    from: string;
+    to: string;
+    asset_ids?: number[];
+    cost?: {
+        fee_bps_per_side?: number;
+        slippage_bps_per_side?: number;
+    };
+}
+export interface LabReplayStarted extends LabRecord {
+    job_id: LabJobId;
+}
+export interface LabReplayJob extends LabReplayStarted {
+    status: string;
+    error?: string | null;
+    result?: LabRecord | null;
+}
+export interface LabRefusal {
+    status: number;
+    code: string;
+    message: string;
+    /** The server's complete body, retained for machine output and future additive fields. */
+    body?: unknown;
+}
+export type LabAnswer<T> = {
+    ok: true;
+    status: number;
+    body: T;
+} | {
+    ok: false;
+    refusal: LabRefusal;
+};
+export interface LabClientOptions {
+    apiKey: string;
+    /** Pass CANDLE_HACC_URL here; it must be HTTPS, including for local servers. */
+    apiUrl?: string;
+    fetch?: typeof fetch;
+    callTimeoutMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface LabClient {
+    status(): Promise<LabAnswer<LabStatus>>;
+    replay(body: LabReplayInput): Promise<LabAnswer<LabReplayStarted>>;
+    replayGet(id: LabJobId): Promise<LabAnswer<LabReplayJob>>;
+    replayCancel(id: LabJobId): Promise<LabAnswer<LabRecord>>;
+    runners(q?: {
+        hours?: number;
+        min_wallets?: number;
+    }): Promise<LabAnswer<LabRecord>>;
+    edges(q?: {
+        days?: number;
+        min_n?: number;
+    }): Promise<LabAnswer<LabRecord>>;
+    waitForReplay(id: LabJobId, options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<LabAnswer<LabReplayJob>>;
+}
+export declare function createLabClient(options: LabClientOptions): LabClient;
+//# sourceMappingURL=lab.d.ts.map

package/dist/lab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lab.d.ts","sourceRoot":"","sources":["../src/lab.ts"],"names":[],"mappings":"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"}

package/dist/token-clusters.d.ts

@@ -0,0 +1,36 @@
+/** Public protocol for the optional cluster read. Unavailable never contains numeric analysis. */
+export declare const CLUSTER_REASONS: readonly ["disabled", "invalid_config", "unsupported_chain", "invalid_mint", "key_missing", "gate_uncalibrated", "market_data_missing", "market_data_stale", "token_too_new", "gate_not_met", "not_indexed", "empty_analysis", "invalid_response", "timeout", "upstream_unavailable", "upstream_4xx", "upstream_5xx", "rate_limited", "quota_exhausted", "budget_exhausted", "budget_unavailable", "request_in_progress", "transport_error", "internal_unavailable"];
+export type ClusterReason = (typeof CLUSTER_REASONS)[number];
+export declare const CLUSTER_MESSAGE = "Cluster analysis not available for this token";
+export declare const CLUSTER_LABEL = "Third-party cluster analysis";
+export declare const CLUSTER_CAVEAT = "Third-party estimates of linked wallets. Exchange, pool and service wallets may be grouped together. These figures do not establish common ownership, insider conduct or wrongdoing.";
+export interface ClusterAnalysis {
+    clusterSupplyPct: number;
+    clusters: {
+        supplyPct: number;
+        addresses: string[];
+        tags: string[];
+    }[];
+}
+export type ClusterResult = {
+    status: "available";
+    chain: "solana";
+    mint: string;
+    source: "third_party";
+    label: typeof CLUSTER_LABEL;
+    caveat: string;
+    fetchedAt: string;
+    expiresAt: string;
+    cache: "hit" | "miss";
+    analysis: ClusterAnalysis;
+} | {
+    status: "unavailable";
+    mint: string;
+    reason: ClusterReason;
+    message: typeof CLUSTER_MESSAGE;
+    retryAt?: string;
+};
+export declare function clusterUnavailable(mint: string, reason: ClusterReason, retryAt?: number): ClusterResult;
+/** Construct only protocol fields; malformed/unknown server output is a client availability failure. */
+export declare function readClusterResult(value: unknown, mint: string): ClusterResult | null;
+//# sourceMappingURL=token-clusters.d.ts.map

package/dist/token-clusters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-clusters.d.ts","sourceRoot":"","sources":["../src/token-clusters.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,eAAO,MAAM,eAAe,scAyBlB,CAAA;AACV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAC5D,eAAO,MAAM,eAAe,kDAAkD,CAAA;AAC9E,eAAO,MAAM,aAAa,iCAAiC,CAAA;AAC3D,eAAO,MAAM,cAAc,yLAC6J,CAAA;AACxL,MAAM,WAAW,eAAe;IAC9B,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAA;CACvE;AACD,MAAM,MAAM,aAAa,GACrB;IACE,MAAM,EAAE,WAAW,CAAA;IACnB,KAAK,EAAE,QAAQ,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,aAAa,CAAA;IACrB,KAAK,EAAE,OAAO,aAAa,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,KAAK,GAAG,MAAM,CAAA;IACrB,QAAQ,EAAE,eAAe,CAAA;CAC1B,GACD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,OAAO,eAAe,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AACrH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,CAQvG;AAED,wGAAwG;AACxG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAuDpF"}