@tokenomist-ai/tokenomist-cli 0.1.2 → 0.2.0

package/dist/index.js

@@ -1,16 +1,21 @@
 #!/usr/bin/env node
+import {
+  package_default
+} from "./chunk-DCGA3ANT.js";
 
 // src/index.ts
-import { Command as Command11 } from "commander";
+import { Command as Command12 } from "commander";
 
 // src/commands/token.ts
 import { Command } from "commander";
 
 // src/api/errors.ts
 function classifyStatus(status) {
+  if (status === 400) return "BAD_REQUEST" /* BAD_REQUEST */;
   if (status === 401) return "UNAUTHORIZED" /* UNAUTHORIZED */;
   if (status === 403) return "FORBIDDEN" /* FORBIDDEN */;
   if (status === 404) return "NOT_FOUND" /* NOT_FOUND */;
+  if (status === 422) return "VALIDATION_ERROR" /* VALIDATION_ERROR */;
   if (status === 429) return "RATE_LIMITED" /* RATE_LIMITED */;
   if (status >= 500 && status < 600) return "SERVER_ERROR" /* SERVER_ERROR */;
   return "UNKNOWN" /* UNKNOWN */;
@@ -30,6 +35,14 @@ var ApiError = class _ApiError extends Error {
     this.name = "ApiError";
   }
   retriesExhausted = false;
+  /** How many attempts were made before giving up (set with retriesExhausted). */
+  attempts;
+  /** Point-in-time routes: machine-readable cause, e.g. NO_VERSION_AT_AS_OF. */
+  errorCode;
+  /** Point-in-time routes: the next/first `asOf` that has a version (on NO_VERSION_AT_AS_OF, or inside the plan's range on PLAN_NOT_ELIGIBLE). */
+  earliestValidDate;
+  /** 422 validation errors: one entry per failing field. */
+  fieldErrors;
   get retryable() {
     return this.code === "RATE_LIMITED" /* RATE_LIMITED */ || this.code === "SERVER_ERROR" /* SERVER_ERROR */ || this.code === "NETWORK_ERROR" /* NETWORK_ERROR */;
   }
@@ -37,30 +50,56 @@ var ApiError = class _ApiError extends Error {
     const b = body && typeof body === "object" ? body : {};
     const errorMessage = typeof b.errorMessage === "string" ? b.errorMessage : void 0;
     const errorDetail = typeof b.errorDetail === "string" ? b.errorDetail : void 0;
+    let err;
     if (status === 200 && b.status === false) {
       const bodyStatus = typeof b.statusCode === "number" ? b.statusCode : 0;
-      const code2 = bodyStatus > 0 ? classifyStatus(bodyStatus) : "UNKNOWN" /* UNKNOWN */;
-      return new _ApiError(
+      const code = bodyStatus > 0 ? classifyStatus(bodyStatus) : "UNKNOWN" /* UNKNOWN */;
+      err = new _ApiError(
         errorMessage || "API request failed",
-        code2,
+        code,
         errorDetail,
         bodyStatus || void 0
       );
+    } else {
+      err = new _ApiError(
+        errorMessage || `HTTP ${status}`,
+        classifyStatus(status),
+        errorDetail,
+        status,
+        parseRetryAfter(retryAfterHeader)
+      );
     }
-    const code = classifyStatus(status);
-    return new _ApiError(
-      errorMessage || `HTTP ${status}`,
-      code,
-      errorDetail,
-      status,
-      parseRetryAfter(retryAfterHeader)
-    );
+    if (typeof b.errorCode === "string" && b.errorCode) err.errorCode = b.errorCode;
+    if (typeof b.earliestValidDate === "string" && b.earliestValidDate) {
+      err.earliestValidDate = b.earliestValidDate;
+    }
+    if (Array.isArray(b.data)) {
+      const fields = b.data.filter(
+        (f) => !!f && typeof f === "object" && typeof f.message === "string"
+      );
+      if (fields.length > 0) err.fieldErrors = fields;
+    }
+    return err;
   }
   static fromNetworkError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return new _ApiError(message, "NETWORK_ERROR" /* NETWORK_ERROR */);
   }
 };
+function errorHeadline(err) {
+  const code = err.errorCode ? `${err.code} (${err.errorCode})` : err.code;
+  return `${code}: ${err.message}`;
+}
+function formatApiError(err) {
+  const gaveUp = err.retriesExhausted ? ` (gave up after ${err.attempts ?? "repeated"} attempts)` : "";
+  const lines = [`${errorHeadline(err)}${gaveUp}`];
+  if (err.detail && err.detail !== err.message) lines.push(`Detail: ${err.detail}`);
+  for (const f of err.fieldErrors ?? []) {
+    lines.push(`  - ${f.key}: ${f.message}`);
+  }
+  if (err.earliestValidDate) lines.push(`Earliest valid date: ${err.earliestValidDate}`);
+  return lines;
+}
 
 // src/api/retry.ts
 var DEFAULTS = {
@@ -91,13 +130,14 @@ async function withRetry(fn, options) {
       const calculated = baseDelay * Math.pow(2, attempt - 1) + jitter;
       const delay = err.retryAfter ? Math.min(err.retryAfter * 1e3, maxDelay) : Math.min(calculated, maxDelay);
       process.stderr.write(
-        `${err.code}: ${err.message}. Retrying in ${Math.round(delay / 1e3)}s... (attempt ${attempt + 1}/${maxAttempts})
+        `${errorHeadline(err)}. Retrying in ${Math.round(delay / 1e3)}s... (attempt ${attempt + 1}/${maxAttempts})
 `
       );
       await sleep(delay);
     }
   }
   lastError.retriesExhausted = true;
+  lastError.attempts = maxAttempts;
   throw lastError;
 }
 
@@ -207,20 +247,25 @@ var TokenomistClient = class {
     this.cache = new ResponseCache();
   }
   cache;
+  /** GET a V5 route and return its `data` only. */
   async get(path, params) {
+    return (await this.getWithMeta(path, params)).data;
+  }
+  /** GET a V5 route and return `data` together with the envelope's `metadata`. */
+  async getWithMeta(path, params) {
     const url = this.buildUrl(path, params);
     const urlStr = url.toString();
     const cacheKey = this.cache.buildKey(urlStr, this.apiKey);
     const useCache = this.options?.noCache !== true;
     if (useCache) {
       const cached = this.cache.get(cacheKey);
-      if (cached) return cached;
+      if (cached && typeof cached === "object" && "metadata" in cached) return cached;
     }
-    const data = await withRetry(() => this.fetchFromApi(url));
+    const result = await withRetry(() => this.fetchFromApi(url));
     if (useCache) {
-      this.cache.set(cacheKey, urlStr, data);
+      this.cache.set(cacheKey, urlStr, result);
     }
-    return data;
+    return result;
   }
   buildUrl(path, params) {
     const url = new URL(path, this.baseUrl);
@@ -231,6 +276,7 @@ var TokenomistClient = class {
         }
       }
     }
+    url.searchParams.set("showError", "true");
     return url;
   }
   async fetchFromApi(url) {
@@ -258,7 +304,9 @@ var TokenomistClient = class {
     if (!body.status) {
       throw ApiError.fromResponse(200, body);
     }
-    return body.data;
+    const metadata = body.metadata ?? {};
+    const data = body.data ?? (metadata.page !== void 0 ? [] : null);
+    return { data, metadata };
   }
 };
 
@@ -430,21 +478,61 @@ import { Command as Command2 } from "commander";
 
 // src/api/unlock.ts
 async function listUnlockEvents(client, params) {
-  return client.get("/v5/unlock/events/list", params);
+  return client.getWithMeta(
+    "/v5/unlock/events/list",
+    params
+  );
 }
 async function listUpcomingUnlockEvents(client, params) {
-  return client.get(
+  return client.getWithMeta(
     "/v5/unlock/events/upcoming",
     params
   );
 }
 async function getUnlockEvents(client, tokenId, params) {
-  return client.get(
+  return client.getWithMeta(
     `/v5/unlock/events/${encodeURIComponent(tokenId)}`,
     params
   );
 }
 
+// src/output/pagination.ts
+function paginationOf(metadata) {
+  if (metadata.page === void 0 || metadata.totalPages === void 0) return void 0;
+  return {
+    page: metadata.page,
+    totalPages: metadata.totalPages,
+    pageSize: metadata.pageSize ?? 0,
+    // Upstream omits `total` when it is 0.
+    total: metadata.total ?? 0
+  };
+}
+function formatPaginationHint(p) {
+  const parts = [`Page ${p.page}/${p.totalPages}`, `${p.total.toLocaleString()} total`];
+  if (p.page < p.totalPages) {
+    parts.push(`next: --page ${p.page + 1} (or raise --page-size)`);
+  }
+  return parts.join(" \xB7 ");
+}
+function printPaginationHint(metadata, stream = process.stderr) {
+  const p = paginationOf(metadata);
+  if (!p) return;
+  stream.write(`${formatPaginationHint(p)}
+`);
+}
+
+// src/commands/validate.ts
+function validateDateRange(start, end, names = ["--start", "--end"]) {
+  if (start && end && start > end) {
+    throw new Error(`${names[0]} ${start} is after ${names[1]} ${end}`);
+  }
+}
+function validateVersionSelector(asOf, versionId) {
+  if (asOf && versionId) {
+    throw new Error("Use either --as-of or --version-id, not both");
+  }
+}
+
 // src/commands/unlock.ts
 var listColumns = [
   { key: "tokenName", header: "Token" },
@@ -491,7 +579,11 @@ addListFilterOptions(
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
-  const data = await listUnlockEvents(client, {
+  validateDateRange(opts.minUnlockDate, opts.maxUnlockDate, [
+    "--min-unlock-date",
+    "--max-unlock-date"
+  ]);
+  const { data, metadata } = await listUnlockEvents(client, {
     minMarketCap: opts.minMarketCap,
     minReleasedPercentage: opts.minReleasedPercentage,
     minUnlockDate: opts.minUnlockDate,
@@ -507,6 +599,7 @@ addListFilterOptions(
     eventCount: d.events.length
   }));
   output(rows, listColumns, globalOpts.output || "table");
+  printPaginationHint(metadata);
 });
 addUpcomingFilterOptions(
   unlockCommand.command("upcoming").description("List next upcoming unlock event per token")
@@ -516,7 +609,8 @@ addUpcomingFilterOptions(
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
-  const data = await listUpcomingUnlockEvents(client, {
+  validateDateRange(opts.start, opts.end);
+  const { data, metadata } = await listUpcomingUnlockEvents(client, {
     start: opts.start,
     end: opts.end,
     standardAllocation: opts.standardAllocation,
@@ -538,6 +632,7 @@ addUpcomingFilterOptions(
     upcomingColumns,
     globalOpts.output || "table"
   );
+  printPaginationHint(metadata);
 });
 addPaginationOptions(
   unlockCommand.command("events <tokenId>").description("Get unlock events for a specific token").option("--start <date>", "Start date (YYYY-MM-DD)").option("--end <date>", "End date (YYYY-MM-DD)").option("--standard-allocation <names>", "Filter by allocation (comma-separated)")
@@ -547,7 +642,8 @@ addPaginationOptions(
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
-  const data = await getUnlockEvents(client, tokenId, {
+  validateDateRange(opts.start, opts.end);
+  const { data, metadata } = await getUnlockEvents(client, tokenId, {
     start: opts.start,
     end: opts.end,
     standardAllocation: opts.standardAllocation,
@@ -561,6 +657,7 @@ addPaginationOptions(
     valueToMarketCap: d.cliffUnlocks.valueToMarketCap
   }));
   output(rows, eventsColumns, globalOpts.output || "table");
+  printPaginationHint(metadata);
 });
 
 // src/commands/investor.ts
@@ -568,7 +665,7 @@ import { Command as Command3 } from "commander";
 
 // src/api/investor.ts
 async function listInvestors(client, params) {
-  return client.get(
+  return client.getWithMeta(
     "/v5/fundraising/investors/list",
     params
   );
@@ -605,7 +702,11 @@ investorCommand.command("list").description("List all investors with their fundi
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
-  const data = await listInvestors(client, {
+  validateDateRange(opts.startLatestFundingDate, opts.endLatestFundingDate, [
+    "--start-latest-funding-date",
+    "--end-latest-funding-date"
+  ]);
+  const { data, metadata } = await listInvestors(client, {
     startLatestFundingDate: opts.startLatestFundingDate,
     endLatestFundingDate: opts.endLatestFundingDate,
     page: opts.page,
@@ -613,9 +714,11 @@ investorCommand.command("list").description("List all investors with their fundi
   });
   const rows = data.map((d) => ({
     ...d,
-    roundCount: d.fundingRounds?.length || 0
+    // The list omits fundingRounds in production; null renders as "—", not a misleading 0.
+    roundCount: d.fundingRounds ? d.fundingRounds.length : null
   }));
   output(rows, listColumns2, globalOpts.output || "table");
+  printPaginationHint(metadata);
 });
 investorCommand.command("detail <investorId>").description("Get investor detail with funding rounds").option("--is-lead-investor", "Filter by lead investor status").option("--funding-date-min <date>", "Min funding date (YYYY-MM-DD)").option("--funding-date-max <date>", "Max funding date (YYYY-MM-DD)").option("--raised-amount-min <value>", "Min raised amount").option("--raised-amount-max <value>", "Max raised amount").action(async (investorId, opts, cmd) => {
   const globalOpts = cmd.optsWithGlobals();
@@ -695,13 +798,15 @@ import { Command as Command5 } from "commander";
 
 // src/api/burn.ts
 async function listBurns(client, params) {
-  return client.get("/v5/burn/list", params);
+  return client.getWithMeta("/v5/burn/list", { ...params });
 }
 async function getBurnDetail(client, tokenId, params) {
-  return client.get(
+  const data = await client.get(
     `/v5/burn/${encodeURIComponent(tokenId)}`,
     params
   );
+  if (!data.burns?.length && data.totalBurnValue == null) data.totalBurnValue = 0;
+  return data;
 }
 
 // src/commands/burn.ts
@@ -709,13 +814,17 @@ var listColumns3 = [
   { key: "tokenId", header: "ID" },
   { key: "tokenName", header: "Name" },
   { key: "tokenSymbol", header: "Symbol" },
-  { key: "totalBurnAmount", header: "Total Burned", align: "right" }
+  { key: "totalBurnAmount", header: "Total Burned", align: "right" },
+  { key: "totalBurnValue", header: "Total Value (USD)", align: "right" }
 ];
 var detailColumns2 = [
   { key: "burnEventLabel", header: "Label" },
   { key: "burnType", header: "Type" },
   { key: "burnDate", header: "Date" },
-  { key: "amount", header: "Amount", align: "right" }
+  { key: "amount", header: "Amount", align: "right" },
+  // Added in 0.2.0 — appended so 0.1.x CSV columns keep their positions.
+  { key: "pricePerToken", header: "Price", align: "right" },
+  { key: "value", header: "Value (USD)", align: "right" }
 ];
 var burnCommand = new Command5("burn").description("Token burn commands");
 burnCommand.command("list").description("List all tokens with burn events").option("--token-id <ids>", "Filter by token IDs (comma-separated)").option("--page <number>", "Page number").option("--page-size <number>", "Items per page").action(async (opts, cmd) => {
@@ -724,12 +833,13 @@ burnCommand.command("list").description("List all tokens with burn events").opti
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
-  const data = await listBurns(client, {
+  const { data, metadata } = await listBurns(client, {
     tokenId: opts.tokenId,
     page: opts.page,
     pageSize: opts.pageSize
   });
   output(data, listColumns3, globalOpts.output || "table");
+  printPaginationHint(metadata);
 });
 burnCommand.command("detail <tokenId>").description("Get burn events for a specific token").option("--start <date>", "Start date (YYYY-MM-DD)").option("--end <date>", "End date (YYYY-MM-DD)").action(async (tokenId, opts, cmd) => {
   const globalOpts = cmd.optsWithGlobals();
@@ -737,6 +847,7 @@ burnCommand.command("detail <tokenId>").description("Get burn events for a speci
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
+  validateDateRange(opts.start, opts.end);
   const data = await getBurnDetail(client, tokenId, {
     start: opts.start,
     end: opts.end
@@ -747,6 +858,9 @@ burnCommand.command("detail <tokenId>").description("Get burn events for a speci
   } else {
     console.log(`Token: ${data.tokenName} (${data.tokenSymbol})`);
     console.log(`Total Burned: ${data.totalBurnAmount.toLocaleString()}`);
+    if (outputMode === "table") {
+      console.log(`Total Value (USD): ${data.totalBurnValue?.toLocaleString() ?? "\u2014"}`);
+    }
     console.log();
     output(data.burns, detailColumns2, outputMode);
   }
@@ -757,13 +871,15 @@ import { Command as Command6 } from "commander";
 
 // src/api/buyback.ts
 async function listBuybacks(client, params) {
-  return client.get("/v5/buyback/list", params);
+  return client.getWithMeta("/v5/buyback/list", { ...params });
 }
 async function getBuybackDetail(client, tokenId, params) {
-  return client.get(
+  const data = await client.get(
     `/v5/buyback/${encodeURIComponent(tokenId)}`,
     params
   );
+  if (!data.buybacks?.length && data.totalBuybackValue == null) data.totalBuybackValue = 0;
+  return data;
 }
 
 // src/commands/buyback.ts
@@ -771,7 +887,8 @@ var listColumns4 = [
   { key: "tokenId", header: "ID" },
   { key: "tokenName", header: "Name" },
   { key: "tokenSymbol", header: "Symbol" },
-  { key: "totalBuybackAmount", header: "Total Buyback", align: "right" }
+  { key: "totalBuybackAmount", header: "Total Buyback", align: "right" },
+  { key: "totalBuybackValue", header: "Total Value (USD)", align: "right" }
 ];
 var detailColumns3 = [
   { key: "buybackEventLabel", header: "Label" },
@@ -780,7 +897,9 @@ var detailColumns3 = [
   { key: "tokenAmount", header: "Amount", align: "right" },
   { key: "value", header: "Value", align: "right" },
   { key: "spentAmount", header: "Spent", align: "right" },
-  { key: "spentUnit", header: "Unit" }
+  { key: "spentUnit", header: "Unit" },
+  // Added in 0.2.0 — appended so 0.1.x CSV columns keep their positions.
+  { key: "pricePerToken", header: "Price", align: "right" }
 ];
 var buybackCommand = new Command6("buyback").description("Token buyback commands");
 buybackCommand.command("list").description("List all tokens with buyback events").option("--token-id <ids>", "Filter by token IDs (comma-separated)").option("--page <number>", "Page number").option("--page-size <number>", "Items per page").action(async (opts, cmd) => {
@@ -789,12 +908,13 @@ buybackCommand.command("list").description("List all tokens with buyback events"
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
-  const data = await listBuybacks(client, {
+  const { data, metadata } = await listBuybacks(client, {
     tokenId: opts.tokenId,
     page: opts.page,
     pageSize: opts.pageSize
   });
   output(data, listColumns4, globalOpts.output || "table");
+  printPaginationHint(metadata);
 });
 buybackCommand.command("detail <tokenId>").description("Get buyback events for a specific token").option("--start <date>", "Start date (YYYY-MM-DD)").option("--end <date>", "End date (YYYY-MM-DD)").action(async (tokenId, opts, cmd) => {
   const globalOpts = cmd.optsWithGlobals();
@@ -802,6 +922,7 @@ buybackCommand.command("detail <tokenId>").description("Get buyback events for a
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
+  validateDateRange(opts.start, opts.end);
   const data = await getBuybackDetail(client, tokenId, {
     start: opts.start,
     end: opts.end
@@ -812,6 +933,9 @@ buybackCommand.command("detail <tokenId>").description("Get buyback events for a
   } else {
     console.log(`Token: ${data.tokenName} (${data.tokenSymbol})`);
     console.log(`Total Buyback: ${data.totalBuybackAmount.toLocaleString()}`);
+    if (outputMode === "table") {
+      console.log(`Total Value (USD): ${data.totalBuybackValue?.toLocaleString() ?? "\u2014"}`);
+    }
     console.log();
     output(data.buybacks, detailColumns3, outputMode);
   }
@@ -822,13 +946,13 @@ import { Command as Command7 } from "commander";
 
 // src/api/emission.ts
 async function getDailyEmission(client, tokenId, params) {
-  return client.get(
+  return client.getWithMeta(
     `/v5/daily-emission/${encodeURIComponent(tokenId)}`,
     params
   );
 }
 async function getWeeklyEmission(client, tokenId, params) {
-  return client.get(
+  return client.getWithMeta(
     `/v5/emission/${encodeURIComponent(tokenId)}`,
     params
   );
@@ -852,7 +976,8 @@ emissionCommand.command("daily <tokenId>").description("Get daily emission break
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
-  const data = await getDailyEmission(client, tokenId, {
+  validateDateRange(opts.start, opts.end);
+  const { data, metadata } = await getDailyEmission(client, tokenId, {
     start: opts.start,
     end: opts.end,
     standardAllocation: opts.standardAllocation,
@@ -860,6 +985,7 @@ emissionCommand.command("daily <tokenId>").description("Get daily emission break
     pageSize: opts.pageSize
   });
   output(data, columns3, globalOpts.output || "table");
+  printPaginationHint(metadata);
 });
 emissionCommand.command("weekly <tokenId>").description("Get weekly emission breakdown for a token").option("--start <date>", "Start date (YYYY-MM-DD)").option("--end <date>", "End date (YYYY-MM-DD)").option("--standard-allocation <names>", "Filter by allocation (comma-separated)").option("--page <number>", "Page number").option("--page-size <number>", "Items per page").action(async (tokenId, opts, cmd) => {
   const globalOpts = cmd.optsWithGlobals();
@@ -867,7 +993,8 @@ emissionCommand.command("weekly <tokenId>").description("Get weekly emission bre
   const client = new TokenomistClient(config.apiKey, config.baseUrl, {
     noCache: config.noCache
   });
-  const data = await getWeeklyEmission(client, tokenId, {
+  validateDateRange(opts.start, opts.end);
+  const { data, metadata } = await getWeeklyEmission(client, tokenId, {
     start: opts.start,
     end: opts.end,
     standardAllocation: opts.standardAllocation,
@@ -875,6 +1002,7 @@ emissionCommand.command("weekly <tokenId>").description("Get weekly emission bre
     pageSize: opts.pageSize
   });
   output(data, columns3, globalOpts.output || "table");
+  printPaginationHint(metadata);
 });
 
 // src/commands/allocation.ts
@@ -982,8 +1110,12 @@ import { Command as Command10 } from "commander";
 // src/schema.json
 var schema_default = {
   name: "tok",
-  version: "0.1.0",
+  version: "0.2.0",
   description: "CLI tool for the Tokenomist API",
+  notes: {
+    pagination: "Paginated commands (unlock list/upcoming/events, emission daily/weekly, investor list, burn list, buyback list, pit versions/daily-emission/unlock-events) return one page (default 20 rows). The page position is printed to stderr as 'Page <page>/<totalPages> \xB7 <total> total'; stdout stays the data only. A page past the last returns the last page again. pit commands with --output json include it as a 'pagination' object.",
+    pointInTime: "pit commands answer from one tokenomics version: --as-of <instant> (YYYY-MM-DD or RFC 3339) or --version-id <id> from 'pit versions', never both; neither means the current version. Their --output json is {asOf, version, data, pagination?}; pit versions returns {data, pagination}. They need a plan with point-in-time access (API, ELITE or TEAM); others get FORBIDDEN (PLAN_NOT_ELIGIBLE or Forbidden)."
+  },
   globalOptions: {
     "api-key": { flags: "-k, --api-key <key>", description: "API key (overrides env/config)" },
     output: { flags: "-o, --output <format>", description: "Output format: table, json, csv", default: "table" },
@@ -1143,6 +1275,54 @@ var schema_default = {
       arguments: { tokenId: { required: true, description: "Token ID" } },
       example: "tok allocation detail solana --output json"
     },
+    "pit versions <tokenId>": {
+      description: "List a token's tokenomics versions on its project timeline (point-in-time)",
+      arguments: { tokenId: { required: true, description: "Token ID (e.g. arbitrum)" } },
+      options: {
+        start: { flags: "--start <date>", description: "Keep versions valid from this day (YYYY-MM-DD)" },
+        end: { flags: "--end <date>", description: "Keep versions valid from up to this day (YYYY-MM-DD)" },
+        page: { flags: "--page <number>", description: "Page number" },
+        "page-size": { flags: "--page-size <number>", description: "Items per page" }
+      },
+      example: "tok pit versions arbitrum --output json"
+    },
+    "pit allocation <tokenId>": {
+      description: "Get a token's allocations as published at a version (point-in-time, no USD fields)",
+      arguments: { tokenId: { required: true, description: "Token ID" } },
+      options: {
+        "as-of": { flags: "--as-of <instant>", description: "Answer as known at this instant (YYYY-MM-DD or RFC 3339)" },
+        "version-id": { flags: "--version-id <id>", description: "Answer from this version (from pit versions)" }
+      },
+      example: "tok pit allocation arbitrum --as-of 2024-01-01 --output json"
+    },
+    "pit daily-emission <tokenId>": {
+      description: "Get a token's daily emission (cliff + linear) as published at a version (point-in-time, no USD fields)",
+      arguments: { tokenId: { required: true, description: "Token ID" } },
+      options: {
+        "as-of": { flags: "--as-of <instant>", description: "Answer as known at this instant (YYYY-MM-DD or RFC 3339)" },
+        "version-id": { flags: "--version-id <id>", description: "Answer from this version (from pit versions)" },
+        start: { flags: "--start <date>", description: "Start date (YYYY-MM-DD)" },
+        end: { flags: "--end <date>", description: "End date (YYYY-MM-DD)" },
+        "standard-allocation": { flags: "--standard-allocation <names>", description: "Filter by allocation (comma-separated: community, founderTeam, privateInvestors, publicInvestors, others, reserve)" },
+        page: { flags: "--page <number>", description: "Page number" },
+        "page-size": { flags: "--page-size <number>", description: "Items per page" }
+      },
+      example: "tok pit daily-emission arbitrum --as-of 2024-01-01 --start 2024-03-01 --end 2024-03-31"
+    },
+    "pit unlock-events <tokenId>": {
+      description: "Get a token's cliff unlock events as published at a version (point-in-time, no USD fields)",
+      arguments: { tokenId: { required: true, description: "Token ID" } },
+      options: {
+        "as-of": { flags: "--as-of <instant>", description: "Answer as known at this instant (YYYY-MM-DD or RFC 3339)" },
+        "version-id": { flags: "--version-id <id>", description: "Answer from this version (from pit versions)" },
+        start: { flags: "--start <date>", description: "Start date (YYYY-MM-DD)" },
+        end: { flags: "--end <date>", description: "End date (YYYY-MM-DD)" },
+        "standard-allocation": { flags: "--standard-allocation <names>", description: "Filter by allocation (comma-separated: community, founderTeam, privateInvestors, publicInvestors, others, reserve)" },
+        page: { flags: "--page <number>", description: "Page number" },
+        "page-size": { flags: "--page-size <number>", description: "Items per page" }
+      },
+      example: "tok pit unlock-events arbitrum --version-id arbitrum-p-6502a0ab2e1d22b626158232 --output json"
+    },
     "auth login": {
       description: "Store API key",
       options: {
@@ -1174,6 +1354,211 @@ var schemaCommand = new Command10("schema").description("Print full command sche
   console.log(JSON.stringify(schema_default, null, indent));
 });
 
+// src/commands/pit.ts
+import { Command as Command11 } from "commander";
+
+// src/api/point-in-time.ts
+var BASE = "/v5/point-in-time";
+async function getTokenVersions(client, tokenId, params) {
+  return client.getWithMeta(
+    `${BASE}/token-versions/${encodeURIComponent(tokenId)}`,
+    { ...params }
+  );
+}
+async function getPointInTimeAllocation(client, tokenId, params) {
+  return client.getWithMeta(
+    `${BASE}/allocations/${encodeURIComponent(tokenId)}`,
+    { ...params }
+  );
+}
+async function getPointInTimeDailyEmission(client, tokenId, params) {
+  return client.getWithMeta(
+    `${BASE}/daily-emission/${encodeURIComponent(tokenId)}`,
+    { ...params }
+  );
+}
+async function getPointInTimeUnlockEvents(client, tokenId, params) {
+  return client.getWithMeta(
+    `${BASE}/unlock/events/${encodeURIComponent(tokenId)}`,
+    { ...params }
+  );
+}
+
+// src/commands/pit.ts
+var versionColumns = [
+  { key: "historyOrder", header: "#", align: "right" },
+  { key: "id", header: "Version ID" },
+  { key: "status", header: "Status" },
+  { key: "validFrom", header: "Valid From" },
+  { key: "validUntil", header: "Valid Until" },
+  { key: "changeCategory", header: "Change" },
+  { key: "changeTitle", header: "Title" }
+];
+var allocationColumns = [
+  { key: "allocationName", header: "Allocation" },
+  { key: "allocationType", header: "Type" },
+  { key: "standardAllocationName", header: "Std. Allocation" },
+  { key: "allocationAmount", header: "Amount", align: "right" },
+  { key: "allocationUnlockedAmount", header: "Unlocked", align: "right" },
+  { key: "allocationLockedAmount", header: "Locked", align: "right" },
+  { key: "trackedAllocationPercentage", header: "Tracked %", align: "right" }
+];
+var emissionColumns = [
+  { key: "startDate", header: "Start" },
+  { key: "endDate", header: "End" },
+  { key: "tokenSymbol", header: "Symbol" },
+  { key: "unlockAmount", header: "Unlock Amt", align: "right" },
+  { key: "totalCumulativeUnlockedAmount", header: "Cumulative", align: "right" },
+  { key: "committedClaimAmount", header: "Committed Claim", align: "right" }
+];
+var unlockColumns = [
+  { key: "unlockDate", header: "Date" },
+  { key: "tokenSymbol", header: "Symbol" },
+  { key: "cliffAmount", header: "Cliff Amount", align: "right" },
+  { key: "allocationNames", header: "Allocations" }
+];
+var STANDARD_ALLOCATION_HELP = "Filter by allocation (comma-separated: community, founderTeam, privateInvestors, publicInvestors, others, reserve)";
+function addSelectorOptions(cmd) {
+  return cmd.option(
+    "--as-of <instant>",
+    "Answer as known at this instant (YYYY-MM-DD or RFC 3339, e.g. 2024-07-01T12:00:00Z)"
+  ).option("--version-id <id>", "Answer from this version (from `tok pit versions`)");
+}
+function addSeriesOptions(cmd) {
+  return addSelectorOptions(cmd).option("--start <date>", "Start date (YYYY-MM-DD)").option("--end <date>", "End date (YYYY-MM-DD)").option("--standard-allocation <names>", STANDARD_ALLOCATION_HELP).option("--page <number>", "Page number").option("--page-size <number>", "Items per page");
+}
+function clientFor(cmd) {
+  const globalOpts = cmd.optsWithGlobals();
+  const config = resolveConfig(globalOpts);
+  const client = new TokenomistClient(config.apiKey, config.baseUrl, {
+    noCache: config.noCache
+  });
+  return { client, mode: globalOpts.output || "table" };
+}
+function printJson(result) {
+  const { metadata, data } = result;
+  const pagination = paginationOf(metadata);
+  const out = {};
+  if (metadata.asOf !== void 0) out.asOf = metadata.asOf;
+  if (metadata.version !== void 0) out.version = metadata.version;
+  out.data = data;
+  if (pagination) out.pagination = pagination;
+  console.log(JSON.stringify(out, null, 2));
+}
+function printVersionContext(result, mode) {
+  const { asOf, version } = result.metadata;
+  if (asOf === void 0 && version === void 0) return;
+  const lines = [];
+  if (asOf) lines.push(`As of: ${asOf}`);
+  if (version) {
+    const id = typeof version.id === "string" ? version.id : "\u2014";
+    const status = typeof version.status === "string" ? ` (${version.status})` : "";
+    lines.push(`Version: ${id}${status}`);
+  }
+  writeContext(lines, mode);
+}
+function writeContext(lines, mode) {
+  if (lines.length === 0) return;
+  const text = lines.join("\n") + "\n";
+  if (mode === "csv") process.stderr.write(text);
+  else process.stdout.write(text + "\n");
+}
+var pitCommand = new Command11("pit").alias("point-in-time").description(
+  "Point-in-time history: a token's data as published at a past version (no USD fields)"
+);
+pitCommand.command("versions <tokenId>").description("List a token's tokenomics versions (project timeline)").option("--start <date>", "Keep versions valid from this day (YYYY-MM-DD)").option("--end <date>", "Keep versions valid from up to this day (YYYY-MM-DD)").option("--page <number>", "Page number").option("--page-size <number>", "Items per page").action(async (tokenId, opts, cmd) => {
+  validateDateRange(opts.start, opts.end);
+  const { client, mode } = clientFor(cmd);
+  const result = await getTokenVersions(client, tokenId, {
+    start: opts.start,
+    end: opts.end,
+    page: opts.page,
+    pageSize: opts.pageSize
+  });
+  if (mode === "json") return printJson(result);
+  const rows = result.data.map((v) => ({
+    ...v,
+    changeCategory: v.change?.category,
+    changeTitle: v.change?.title
+  }));
+  output(rows, versionColumns, mode);
+  printPaginationHint(result.metadata);
+});
+addSelectorOptions(
+  pitCommand.command("allocation <tokenId>").description("Get a token's allocations as published at a version")
+).action(async (tokenId, opts, cmd) => {
+  validateVersionSelector(opts.asOf, opts.versionId);
+  const { client, mode } = clientFor(cmd);
+  const result = await getPointInTimeAllocation(client, tokenId, {
+    asOf: opts.asOf,
+    versionId: opts.versionId
+  });
+  if (mode === "json") return printJson(result);
+  const d = result.data;
+  printVersionContext(result, mode);
+  writeContext(
+    [
+      `Token: ${d.name} (${d.symbol})`,
+      `Max Supply: ${d.maxSupply?.toLocaleString() ?? "\u2014"}`,
+      `Total Unlocked: ${d.totalUnlockedAmount.toLocaleString()}`,
+      `Total Locked: ${d.totalLockedAmount.toLocaleString()}`,
+      `Total TBD Locked: ${d.totalTBDLockedAmount.toLocaleString()}`,
+      `Total Untracked: ${d.totalUntrackedAmount.toLocaleString()}`
+    ],
+    mode
+  );
+  output(d.allocations, allocationColumns, mode);
+});
+addSeriesOptions(
+  pitCommand.command("daily-emission <tokenId>").description("Get a token's daily emission (cliff + linear) as published at a version")
+).action(async (tokenId, opts, cmd) => {
+  validateVersionSelector(opts.asOf, opts.versionId);
+  validateDateRange(opts.start, opts.end);
+  const { client, mode } = clientFor(cmd);
+  const result = await getPointInTimeDailyEmission(client, tokenId, {
+    asOf: opts.asOf,
+    versionId: opts.versionId,
+    start: opts.start,
+    end: opts.end,
+    standardAllocation: opts.standardAllocation,
+    page: opts.page,
+    pageSize: opts.pageSize
+  });
+  if (mode === "json") return printJson(result);
+  printVersionContext(result, mode);
+  const rows = result.data.map((d) => ({
+    ...d,
+    committedClaimAmount: d.committedClaim?.amount ?? null
+  }));
+  output(rows, emissionColumns, mode);
+  printPaginationHint(result.metadata);
+});
+addSeriesOptions(
+  pitCommand.command("unlock-events <tokenId>").description("Get a token's cliff unlock events as published at a version")
+).action(async (tokenId, opts, cmd) => {
+  validateVersionSelector(opts.asOf, opts.versionId);
+  validateDateRange(opts.start, opts.end);
+  const { client, mode } = clientFor(cmd);
+  const result = await getPointInTimeUnlockEvents(client, tokenId, {
+    asOf: opts.asOf,
+    versionId: opts.versionId,
+    start: opts.start,
+    end: opts.end,
+    standardAllocation: opts.standardAllocation,
+    page: opts.page,
+    pageSize: opts.pageSize
+  });
+  if (mode === "json") return printJson(result);
+  printVersionContext(result, mode);
+  const rows = result.data.map((e) => ({
+    ...e,
+    cliffAmount: e.cliffUnlocks.cliffAmount,
+    allocationNames: e.cliffUnlocks.allocationBreakdown.map((a) => a.allocationName)
+  }));
+  output(rows, unlockColumns, mode);
+  printPaginationHint(result.metadata);
+});
+
 // src/banner.ts
 var BANNER_COLOR_OPEN = "\x1B[38;2;197;16;82m";
 var COLOR_RESET = "\x1B[0m";
@@ -1226,6 +1611,26 @@ function printWelcome(stream) {
 `);
 }
 
+// src/update-notice.ts
+function isNewerVersion(latest, current) {
+  const parse = (v) => v.replace(/^v/, "").split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const a = parse(latest);
+  const b = parse(current);
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+  }
+  return false;
+}
+function updateNotice(cache, running, now, maxAgeMs) {
+  if (typeof cache.latest !== "string" || typeof cache.checkedAt !== "number") return null;
+  if (now - cache.checkedAt >= maxAgeMs) return null;
+  if (!isNewerVersion(cache.latest, running)) return null;
+  return `
+Update available: ${running} \u2192 ${cache.latest}  (npm i -g @tokenomist-ai/tokenomist-cli)
+
+`;
+}
+
 // src/index.ts
 import { spawn } from "child_process";
 import { readFileSync as readFileSync3 } from "fs";
@@ -1237,15 +1642,8 @@ function showUpdateNotification() {
   if (process.env.NO_UPDATE_NOTIFIER === "1" || process.env.CI === "1") return;
   try {
     const raw = readFileSync3(join3(homedir3(), ".tokenomist", "update-check.json"), "utf-8");
-    const data = JSON.parse(raw);
-    if (data.latest !== data.current && Date.now() - data.checkedAt < ONE_DAY) {
-      process.stderr.write(
-        `
-Update available: ${data.current} \u2192 ${data.latest}  (npm i -g @tokenomist-ai/tokenomist-cli)
-
-`
-      );
-    }
+    const notice = updateNotice(JSON.parse(raw), package_default.version, Date.now(), ONE_DAY);
+    if (notice) process.stderr.write(notice);
   } catch {
   }
 }
@@ -1265,10 +1663,10 @@ function spawnUpdateCheck() {
   } catch {
   }
 }
-var program = new Command11();
+var program = new Command12();
 program.name("tok").description(
-  "CLI tool for the Tokenomist API \u2014 query token unlocks, emissions, fundraising, burns, and buybacks"
-).version("0.1.0").option("-k, --api-key <key>", "API key (overrides env/config)").option("-o, --output <format>", "Output format: table, json, csv", "table").option("--base-url <url>", "API base URL").option("--no-cache", "Bypass response cache");
+  "CLI tool for the Tokenomist API \u2014 query token unlocks, emissions, fundraising, burns, buybacks, and point-in-time history"
+).version(package_default.version).option("-k, --api-key <key>", "API key (overrides env/config)").option("-o, --output <format>", "Output format: table, json, csv", "table").option("--base-url <url>", "API base URL").option("--no-cache", "Bypass response cache");
 program.addCommand(tokenCommand);
 program.addCommand(unlockCommand);
 program.addCommand(investorCommand);
@@ -1277,6 +1675,7 @@ program.addCommand(burnCommand);
 program.addCommand(buybackCommand);
 program.addCommand(emissionCommand);
 program.addCommand(allocationCommand);
+program.addCommand(pitCommand);
 program.addCommand(authCommand);
 program.addCommand(schemaCommand);
 if (showWelcomeBanner()) {
@@ -1288,12 +1687,7 @@ program.parseAsync(process.argv).then(() => {
   spawnUpdateCheck();
 }).catch((err) => {
   if (err instanceof ApiError) {
-    if (err.retriesExhausted) {
-      if (err.detail) console.error(`Detail: ${err.detail}`);
-    } else {
-      console.error(`${err.code}: ${err.message}`);
-      if (err.detail) console.error(`Detail: ${err.detail}`);
-    }
+    for (const line of formatApiError(err)) console.error(line);
   } else {
     console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
   }