sidekick-shared 0.24.2 → 0.24.4

package/dist/pricingCatalog.d.ts

@@ -18,8 +18,12 @@
  */
 import { type ModelPricing } from './modelInfo';
 export interface HydrateOptions {
-    /** Directory for the on-disk cache (e.g. ~/.config/sidekick). */
-    cacheDir: string;
+    /**
+     * Directory for the on-disk cache. Defaults to the Sidekick config dir,
+     * which honors `SIDEKICK_CONFIG_DIR` and `setConfigDir()` — pass this only
+     * to place the cache somewhere outside the config root.
+     */
+    cacheDir?: string;
     /** Inject a fetch implementation (tests, custom agents). Defaults to `globalThis.fetch`. */
     fetchImpl?: typeof fetch;
     /** Cache TTL in ms. Default 24h. */
@@ -52,7 +56,7 @@ export declare const LITELLM_CATALOG_URL = "https://raw.githubusercontent.com/Be
  *
  * Always resolves — never throws. Offline-safe.
  */
-export declare function hydratePricingCatalog(options: HydrateOptions): Promise<HydrateResult>;
+export declare function hydratePricingCatalog(options?: HydrateOptions): Promise<HydrateResult>;
 /**
  * Convert a LiteLLM catalog payload to our `ModelPricing` override map.
  * Exported for tests; rarely called directly.

package/dist/pricingCatalog.js

@@ -59,6 +59,7 @@ const node_fs_1 = require("node:fs");
 const path = __importStar(require("node:path"));
 const modelContext_1 = require("./modelContext");
 const modelInfo_1 = require("./modelInfo");
+const paths_1 = require("./paths");
 // ── Constants ──
 exports.LITELLM_CATALOG_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
 const CACHE_FILE_NAME = 'pricing-catalog.json';
@@ -75,8 +76,8 @@ const DEFAULT_TIMEOUT_MS = 3_000;
  *
  * Always resolves — never throws. Offline-safe.
  */
-async function hydratePricingCatalog(options) {
-    const { cacheDir, fetchImpl = globalThis.fetch, ttlMs = DEFAULT_TTL_MS, timeoutMs = DEFAULT_TIMEOUT_MS, url = exports.LITELLM_CATALOG_URL, logger, } = options;
+async function hydratePricingCatalog(options = {}) {
+    const { cacheDir = (0, paths_1.getConfigDir)(), fetchImpl = globalThis.fetch, ttlMs = DEFAULT_TTL_MS, timeoutMs = DEFAULT_TIMEOUT_MS, url = exports.LITELLM_CATALOG_URL, logger, } = options;
     const cachePath = path.join(cacheDir, CACHE_FILE_NAME);
     const now = Date.now();
     // 1. Fresh cache?

package/dist/zaiQuota.d.ts

@@ -27,6 +27,10 @@ import type { QuotaState } from './quota';
  * "One prompt ≈ one query; each prompt is estimated to invoke the model
  * 15–20 times." We use the midpoint (17.5) when converting observed
  * assistant turns into prompt equivalents.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare const ZAI_TIER_BUDGETS: {
     readonly lite: {
@@ -42,20 +46,43 @@ export declare const ZAI_TIER_BUDGETS: {
         readonly weekly: 8000;
     };
 };
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export type ZaiTier = 'lite' | 'pro' | 'max';
 /**
  * Midpoint of z.ai's documented "15–20 model invocations per prompt" range.
  * Used to convert accumulated assistant turns into prompt equivalents.
  * Calibration note: this constant may need per-tier adjustment after
  * real-world validation against the z.ai web UI.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare const ZAI_PROMPT_INVOCATIONS = 17.5;
 /**
  * Provider IDs that OpenCode tags on z.ai-routed messages.
  * `zai-coding-plan` is the Coding Plan key; `zai` is the bare API key.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare const ZAI_PROVIDER_IDS: readonly ["zai", "zai-coding-plan"];
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export type ZaiProviderId = (typeof ZAI_PROVIDER_IDS)[number];
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export declare function isZaiProviderId(value: unknown): value is ZaiProviderId;
 /**
  * Minimal description of a z.ai-routed assistant turn needed to accumulate
@@ -64,6 +91,10 @@ export declare function isZaiProviderId(value: unknown): value is ZaiProviderId;
  * provider comparability; cost is omitted (always 0 for z.ai).
  *
  * `timestampMs` is when the assistant turn completed (epoch milliseconds).
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export interface ZaiAssistantTurn {
     timestampMs: number;
@@ -74,6 +105,11 @@ export interface ZaiAssistantTurn {
     cacheWriteTokens: number;
     reasoningTokens: number;
 }
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export interface ZaiAccumulatedUsage {
     /** Number of z.ai assistant turns inside the 5-hour window. */
     fiveHourTurns: number;
@@ -96,6 +132,10 @@ export interface ZaiAccumulatedUsage {
  * Sums the token fields of a single turn into a scalar.
  * Cache reads are weighted at 0.1× (Anthropic convention) to avoid
  * over-counting repeated context. Output and reasoning tokens are weighted 1×.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function turnTokenWeight(turn: Pick<ZaiAssistantTurn, 'inputTokens' | 'outputTokens' | 'cacheReadTokens' | 'cacheWriteTokens' | 'reasoningTokens'>): number;
 /**
@@ -104,6 +144,10 @@ export declare function turnTokenWeight(turn: Pick<ZaiAssistantTurn, 'inputToken
  * Pure & stateless: the caller is responsible for passing the relevant turns.
  * Turns outside the 7-day window are ignored; turns inside the 7-day window
  * but outside the 5-hour window still count toward weekly usage.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function accumulateZaiUsage(turns: readonly ZaiAssistantTurn[], nowMs?: number): ZaiAccumulatedUsage;
 /**
@@ -113,8 +157,17 @@ export declare function accumulateZaiUsage(turns: readonly ZaiAssistantTurn[], n
  * the user must be on a higher tier. This under-detects at the start of a
  * weekly cycle (a Max user looks identical to a Lite user until they cross
  * 400 prompts/week), so callers should still expose an explicit override.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function resolveZaiTier(configured: ZaiTier | 'auto', accumulated: ZaiAccumulatedUsage): ZaiTier;
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export interface InferZaiQuotaStateOptions {
     /** ISO timestamp to stamp on the sample. Default: now. */
     capturedAt?: string;
@@ -138,9 +191,23 @@ export interface InferZaiQuotaStateOptions {
  *   - `sevenDay.resetsAt` ← first turn in window + 7d (documented as
  *     "7 days from order time" — order time is unknown, so this is a
  *     lower bound at best).
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function inferZaiQuotaState(accumulated: ZaiAccumulatedUsage, tier: ZaiTier, options?: InferZaiQuotaStateOptions): QuotaState;
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export type ZaiQuotaErrorKind = 'exhausted' | 'fup' | 'expired' | 'invalid';
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 export interface ZaiQuotaError {
     kind: ZaiQuotaErrorKind;
     /** ISO timestamp parsed from `${next_flush_time}` in the error message, if present. */
@@ -159,6 +226,10 @@ export interface ZaiQuotaError {
  * `YYYY-MM-DD HH:mm:ss` form defensively.
  *
  * Returns `null` when the code is not a quota-related business error.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function parseZaiQuotaError(error: {
     code?: string | number;
@@ -171,17 +242,29 @@ export declare function parseZaiQuotaError(error: {
  * Handles ISO 8601 (`2025-01-31T14:00:00Z`), space-separated
  * (`2025-01-31 14:00:00`), and epoch-seconds (1234567890) forms.
  * Returns undefined when no parseable timestamp is found.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function extractNextFlushTime(message: string): string | undefined;
 /**
  * Builds an unavailable z.ai `QuotaState` for the cold-start case where
  * no z.ai traffic has been observed yet.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function makeUnavailableZaiQuotaState(error?: string, tier?: ZaiTier, capturedAt?: string): QuotaState;
 /**
  * Shape of a row returned by `OpenCodeDatabase.getAssistantMessagesByProviderId`.
  * Defined here to keep the sidekick-shared helper self-contained without
  * leaking the OpenCode db module into the public quota surface.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export interface ZaiOpenCodeRow {
     timeCreated: number;
@@ -202,6 +285,10 @@ export interface ZaiOpenCodeRow {
  *
  * Returns `{ turns, errors }` so callers can replay them through
  * `ZaiQuotaWatcher.ingestAssistantTurns` and `ingestError`.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 export declare function rowsToZaiTurnsAndErrors(rows: readonly ZaiOpenCodeRow[]): {
     turns: ZaiAssistantTurn[];

package/dist/zaiQuota.js

@@ -18,6 +18,10 @@ exports.rowsToZaiTurnsAndErrors = rowsToZaiTurnsAndErrors;
  * "One prompt ≈ one query; each prompt is estimated to invoke the model
  * 15–20 times." We use the midpoint (17.5) when converting observed
  * assistant turns into prompt equivalents.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 exports.ZAI_TIER_BUDGETS = {
     lite: { fiveHour: 80, weekly: 400 },
@@ -29,6 +33,10 @@ exports.ZAI_TIER_BUDGETS = {
  * Used to convert accumulated assistant turns into prompt equivalents.
  * Calibration note: this constant may need per-tier adjustment after
  * real-world validation against the z.ai web UI.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 exports.ZAI_PROMPT_INVOCATIONS = 17.5;
 const FIVE_HOUR_MS = 5 * 3_600_000;
@@ -36,8 +44,17 @@ const SEVEN_DAY_MS = 7 * 86_400_000;
 /**
  * Provider IDs that OpenCode tags on z.ai-routed messages.
  * `zai-coding-plan` is the Coding Plan key; `zai` is the bare API key.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 exports.ZAI_PROVIDER_IDS = ['zai', 'zai-coding-plan'];
+/**
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
+ */
 function isZaiProviderId(value) {
     return value === 'zai' || value === 'zai-coding-plan';
 }
@@ -45,6 +62,10 @@ function isZaiProviderId(value) {
  * Sums the token fields of a single turn into a scalar.
  * Cache reads are weighted at 0.1× (Anthropic convention) to avoid
  * over-counting repeated context. Output and reasoning tokens are weighted 1×.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function turnTokenWeight(turn) {
     return (turn.inputTokens +
@@ -59,6 +80,10 @@ function turnTokenWeight(turn) {
  * Pure & stateless: the caller is responsible for passing the relevant turns.
  * Turns outside the 7-day window are ignored; turns inside the 7-day window
  * but outside the 5-hour window still count toward weekly usage.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function accumulateZaiUsage(turns, nowMs = Date.now()) {
     const fiveHourCutoff = nowMs - FIVE_HOUR_MS;
@@ -104,6 +129,10 @@ function accumulateZaiUsage(turns, nowMs = Date.now()) {
  * the user must be on a higher tier. This under-detects at the start of a
  * weekly cycle (a Max user looks identical to a Lite user until they cross
  * 400 prompts/week), so callers should still expose an explicit override.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function resolveZaiTier(configured, accumulated) {
     if (configured !== 'auto')
@@ -128,6 +157,10 @@ function resolveZaiTier(configured, accumulated) {
  *   - `sevenDay.resetsAt` ← first turn in window + 7d (documented as
  *     "7 days from order time" — order time is unknown, so this is a
  *     lower bound at best).
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function inferZaiQuotaState(accumulated, tier, options = {}) {
     const budget = exports.ZAI_TIER_BUDGETS[tier];
@@ -185,6 +218,10 @@ const ZAI_ERROR_CODES = {
  * `YYYY-MM-DD HH:mm:ss` form defensively.
  *
  * Returns `null` when the code is not a quota-related business error.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function parseZaiQuotaError(error) {
     if (!error)
@@ -203,6 +240,10 @@ function parseZaiQuotaError(error) {
  * Handles ISO 8601 (`2025-01-31T14:00:00Z`), space-separated
  * (`2025-01-31 14:00:00`), and epoch-seconds (1234567890) forms.
  * Returns undefined when no parseable timestamp is found.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function extractNextFlushTime(message) {
     if (!message)
@@ -236,6 +277,10 @@ function extractNextFlushTime(message) {
 /**
  * Builds an unavailable z.ai `QuotaState` for the cold-start case where
  * no z.ai traffic has been observed yet.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function makeUnavailableZaiQuotaState(error = 'No z.ai usage observed yet', tier = 'lite', capturedAt = new Date().toISOString()) {
     return {
@@ -259,6 +304,10 @@ function makeUnavailableZaiQuotaState(error = 'No z.ai usage observed yet', tier
  *
  * Returns `{ turns, errors }` so callers can replay them through
  * `ZaiQuotaWatcher.ingestAssistantTurns` and `ingestError`.
+ *
+ * @deprecated Use `resolveZaiQuota()` from `zaiQuotaApi`, which reads z.ai's
+ * authoritative quota endpoint. This observed-traffic estimator is retained
+ * for backward compatibility only and drifts from actual billing.
  */
 function rowsToZaiTurnsAndErrors(rows) {
     const turns = [];

package/dist/zaiQuotaWatcher.d.ts

@@ -10,6 +10,10 @@ type TierResolver = (configured: ZaiTier | 'auto', accumulated: ZaiAccumulatedUs
 type SnapshotReader = (providerId: ZaiSnapshotProvider, accountId: string) => QuotaState | null;
 type SnapshotWriter = (providerId: ZaiSnapshotProvider, accountId: string, quota: QuotaState) => void;
 type HistoryAppender = (sample: QuotaHistorySample) => void | Promise<void>;
+/**
+ * @deprecated Unreachable from every package entrypoint and no longer used by
+ * product code. Use `resolveZaiQuota()` from `zaiQuotaApi` instead.
+ */
 export interface ZaiQuotaWatcherOptions {
     /** Configured tier. Default: `'auto'` (heuristic from observed usage). */
     tier?: ZaiTier | 'auto';
@@ -39,6 +43,9 @@ export interface ZaiQuotaWatcherOptions {
  * for every observed z.ai assistant turn, and `ingestError` whenever a
  * z.ai business error is observed. The watcher debounces recompute and
  * emits via `onUpdate` / `onQuotaUpdate`.
+ *
+ * @deprecated Unreachable from every package entrypoint and no longer used by
+ * product code. Use `resolveZaiQuota()` from `zaiQuotaApi` instead.
  */
 export declare class ZaiQuotaWatcher implements Disposable {
     private readonly tier;

package/dist/zaiQuotaWatcher.js

@@ -37,6 +37,9 @@ function enrichZaiState(state) {
  * for every observed z.ai assistant turn, and `ingestError` whenever a
  * z.ai business error is observed. The watcher debounces recompute and
  * emits via `onUpdate` / `onQuotaUpdate`.
+ *
+ * @deprecated Unreachable from every package entrypoint and no longer used by
+ * product code. Use `resolveZaiQuota()` from `zaiQuotaApi` instead.
  */
 class ZaiQuotaWatcher {
     tier;

package/package.json

@@ -1,7 +1,35 @@
 {
   "name": "sidekick-shared",
-  "version": "0.24.2",
+  "version": "0.24.4",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
+  "keywords": [
+    "claude-code",
+    "codex-cli",
+    "opencode",
+    "session-monitor",
+    "token-usage",
+    "quota",
+    "jsonl",
+    "ai-coding-assistant",
+    "agent-hub",
+    "zod-schemas"
+  ],
+  "homepage": "https://cesarandreslopez.github.io/sidekick-agent-hub/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cesarandreslopez/sidekick-agent-hub",
+    "directory": "sidekick-shared"
+  },
+  "bugs": {
+    "url": "https://github.com/cesarandreslopez/sidekick-agent-hub/issues"
+  },
+  "author": {
+    "name": "Cesar Andres Lopez",
+    "email": "cesarandreslopez@gmail.com"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -47,8 +75,38 @@
     },
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "browser": [
+        "dist/browser.d.ts"
+      ],
+      "node": [
+        "dist/node.d.ts"
+      ],
+      "schemas": [
+        "dist/schemas/index.d.ts"
+      ],
+      "phrases": [
+        "dist/phrases.d.ts"
+      ],
+      "modelContext": [
+        "dist/modelContext.d.ts"
+      ],
+      "modelInfo": [
+        "dist/modelInfo.d.ts"
+      ],
+      "formatting": [
+        "dist/formatting.d.ts"
+      ],
+      "statusline": [
+        "dist/statusline/index.d.ts"
+      ]
+    }
+  },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "sideEffects": false,
   "publishConfig": {