sidekick-shared 0.13.6 → 0.13.8

package/README.md

@@ -77,10 +77,22 @@ import { fetchQuota, readClaudeMaxCredentials } from 'sidekick-shared';
 const creds = readClaudeMaxCredentials();
 if (creds) {
   const quota = await fetchQuota(creds.accessToken);
-  console.log(`5-hour utilization: ${quota.fiveHour.percentUsed}%`);
+  if (quota.available) {
+    console.log(`5-hour utilization: ${quota.fiveHour.utilization}%`);
+  } else {
+    console.log(quota.failureKind, quota.httpStatus, quota.retryAfterMs);
+  }
 }
 ```
 
+Unavailable quota responses remain non-throwing and may include:
+
+- `failureKind`: `auth | network | rate_limit | server | unknown`
+- `httpStatus`: HTTP response status when available
+- `retryAfterMs`: retry delay in milliseconds for `429` responses when the API provides `Retry-After`
+
+For first-party style messaging, `describeQuotaFailure()` maps unavailable quota states to stable alert keys plus display-ready severity/title/message/detail fields for CLI and VS Code consumers.
+
 ## Building
 
 ```bash

package/dist/index.d.ts

@@ -83,5 +83,7 @@ export { readClaudeMaxCredentials, readClaudeMaxAccessTokenSync } from './creden
 export type { ClaudeMaxCredentials } from './credentials';
 export { fetchQuota } from './quota';
 export type { QuotaWindow, QuotaState } from './quota';
+export { describeQuotaFailure } from './quotaPresentation';
+export type { QuotaFailureDescriptor } from './quotaPresentation';
 export { fetchProviderStatus } from './providerStatus';
 export type { ProviderStatusState } from './providerStatus';

package/dist/index.js

@@ -5,7 +5,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findActiveClaudeSession = exports.discoverSessionDirectory = exports.getClaudeSessionDirectory = exports.encodeClaudeWorkspacePath = exports.detectSessionActivity = exports.extractTaskInfo = exports.scanSubagentDir = exports.normalizeCodexToolInput = exports.normalizeCodexToolName = exports.extractPatchFilePaths = exports.CodexRolloutParser = exports.parseDbPartData = exports.parseDbMessageData = exports.convertOpenCodeMessage = exports.detectPlanModeFromText = exports.normalizeToolInput = exports.normalizeToolName = exports.TRUNCATION_PATTERNS = exports.JsonlParser = exports.CodexProvider = exports.OpenCodeProvider = exports.ClaudeCodeProvider = exports.getAllDetectedProviders = exports.detectProvider = exports.readClaudeCodePlanFiles = exports.getPlanAnalytics = exports.writePlans = exports.getLatestPlan = exports.readPlans = exports.readLatestHandoff = exports.readHistory = exports.readNotes = exports.readDecisions = exports.readTasks = exports.getProjectSlugRaw = exports.getProjectSlug = exports.encodeWorkspacePath = exports.getGlobalDataPath = exports.getProjectDataPath = exports.getConfigDir = exports.MAX_PLANS_PER_PROJECT = exports.PLAN_SCHEMA_VERSION = exports.createEmptyTokenTotals = exports.HISTORICAL_DATA_SCHEMA_VERSION = exports.STALENESS_THRESHOLDS = exports.IMPORTANCE_DECAY_FACTORS = exports.KNOWLEDGE_NOTE_SCHEMA_VERSION = exports.DECISION_LOG_SCHEMA_VERSION = exports.normalizeTaskStatus = exports.TASK_PERSISTENCE_SCHEMA_VERSION = void 0;
 exports.HeatmapTracker = exports.FrequencyTracker = exports.getSnapshotPath = exports.isSnapshotValid = exports.deleteSnapshot = exports.loadSnapshot = exports.saveSnapshot = exports.parseTodoDependencies = exports.EventAggregator = exports.getRandomPhrase = exports.ALL_PHRASES = exports.HIGHLIGHT_CSS = exports.clearHighlightCache = exports.highlightEvent = exports.formatSessionJson = exports.formatSessionMarkdown = exports.formatSessionText = exports.classifyNoise = exports.shouldMergeWithPrevious = exports.classifyFollowEvent = exports.classifyMessage = exports.getSoftNoiseReason = exports.isHardNoiseFollowEvent = exports.isHardNoise = exports.formatToolSummary = exports.toFollowEvents = exports.createWatcher = exports.parseChangelog = exports.extractProposedPlanShared = exports.parsePlanMarkdownShared = exports.PlanExtractor = exports.composeContext = exports.FilterEngine = exports.searchSessions = exports.CodexDatabase = exports.OpenCodeDatabase = exports.discoverDebugLogs = exports.collapseDuplicates = exports.filterByLevel = exports.parseDebugLog = exports.scanSubagentTraces = exports.findAllSessionsWithWorktrees = exports.discoverWorktreeSiblings = exports.resolveWorktreeMainRepo = exports.getAllClaudeProjectFolders = exports.decodeEncodedPath = exports.getMostRecentlyActiveSessionDir = exports.findSubdirectorySessionDirs = exports.findSessionsInDirectory = exports.findAllClaudeSessions = void 0;
-exports.fetchProviderStatus = exports.fetchQuota = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.openInBrowser = exports.parseTranscript = exports.generateHtmlReport = exports.PatternExtractor = void 0;
+exports.fetchProviderStatus = exports.describeQuotaFailure = exports.fetchQuota = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.openInBrowser = exports.parseTranscript = exports.generateHtmlReport = exports.PatternExtractor = void 0;
 var taskPersistence_1 = require("./types/taskPersistence");
 Object.defineProperty(exports, "TASK_PERSISTENCE_SCHEMA_VERSION", { enumerable: true, get: function () { return taskPersistence_1.TASK_PERSISTENCE_SCHEMA_VERSION; } });
 Object.defineProperty(exports, "normalizeTaskStatus", { enumerable: true, get: function () { return taskPersistence_1.normalizeTaskStatus; } });
@@ -181,6 +181,8 @@ Object.defineProperty(exports, "readClaudeMaxAccessTokenSync", { enumerable: tru
 // Quota
 var quota_1 = require("./quota");
 Object.defineProperty(exports, "fetchQuota", { enumerable: true, get: function () { return quota_1.fetchQuota; } });
+var quotaPresentation_1 = require("./quotaPresentation");
+Object.defineProperty(exports, "describeQuotaFailure", { enumerable: true, get: function () { return quotaPresentation_1.describeQuotaFailure; } });
 // Provider Status
 var providerStatus_1 = require("./providerStatus");
 Object.defineProperty(exports, "fetchProviderStatus", { enumerable: true, get: function () { return providerStatus_1.fetchProviderStatus; } });

package/dist/quota.d.ts

@@ -17,6 +17,12 @@ export interface QuotaState {
     available: boolean;
     /** Human-readable error if not available */
     error?: string;
+    /** Machine-readable failure classification for unavailable states */
+    failureKind?: 'auth' | 'network' | 'rate_limit' | 'server' | 'unknown';
+    /** HTTP status code for unavailable API responses */
+    httpStatus?: number;
+    /** Retry delay in milliseconds when rate-limited */
+    retryAfterMs?: number;
     /** Projected 5-hour utilization at reset (percentage, capped at 200) */
     projectedFiveHour?: number;
     /** Projected 7-day utilization at reset (percentage, capped at 200) */

package/dist/quota.js

@@ -29,14 +29,27 @@ function projectFromElapsed(utilization, resetsAt, windowMs) {
 /**
  * Helper to build an unavailable QuotaState.
  */
-function unavailableState(error) {
+function unavailableState(error, meta = {}) {
     return {
         fiveHour: { utilization: 0, resetsAt: '' },
         sevenDay: { utilization: 0, resetsAt: '' },
         available: false,
         error,
+        ...meta,
     };
 }
+function parseRetryAfterMs(retryAfter) {
+    if (!retryAfter)
+        return undefined;
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.round(seconds * 1000);
+    }
+    const retryAt = Date.parse(retryAfter);
+    if (Number.isNaN(retryAt))
+        return undefined;
+    return Math.max(retryAt - Date.now(), 0);
+}
 /**
  * Fetch current quota utilization from the Anthropic OAuth usage API.
  *
@@ -57,9 +70,29 @@ async function fetchQuota(accessToken) {
             },
         });
         if (!res.ok) {
-            if (res.status === 401)
-                return unavailableState('Sign in to Claude Code to view quota');
-            return unavailableState(`API error: ${res.status}`);
+            if (res.status === 401) {
+                return unavailableState('Sign in to Claude Code to view quota', {
+                    failureKind: 'auth',
+                    httpStatus: res.status,
+                });
+            }
+            if (res.status === 429) {
+                return unavailableState(`API error: ${res.status}`, {
+                    failureKind: 'rate_limit',
+                    httpStatus: res.status,
+                    retryAfterMs: parseRetryAfterMs(res.headers.get('retry-after')),
+                });
+            }
+            if (res.status >= 500 && res.status <= 599) {
+                return unavailableState(`API error: ${res.status}`, {
+                    failureKind: 'server',
+                    httpStatus: res.status,
+                });
+            }
+            return unavailableState(`API error: ${res.status}`, {
+                failureKind: 'unknown',
+                httpStatus: res.status,
+            });
         }
         const data = await res.json();
         const fiveUtil = data.five_hour?.utilization ?? 0;
@@ -75,6 +108,6 @@ async function fetchQuota(accessToken) {
         };
     }
     catch {
-        return unavailableState('Network error');
+        return unavailableState('Network error', { failureKind: 'network' });
     }
 }

package/dist/quotaPresentation.d.ts

@@ -0,0 +1,10 @@
+import type { QuotaState } from './quota';
+export interface QuotaFailureDescriptor {
+    severity: 'info' | 'warning' | 'error';
+    title: string;
+    message: string;
+    detail?: string;
+    alertKey: string;
+    isRetryable: boolean;
+}
+export declare function describeQuotaFailure(quota: QuotaState | null | undefined): QuotaFailureDescriptor | null;

package/dist/quotaPresentation.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeQuotaFailure = describeQuotaFailure;
+function formatRetryAfter(ms) {
+    if (ms <= 0)
+        return 'now';
+    const totalSeconds = Math.ceil(ms / 1000);
+    const days = Math.floor(totalSeconds / 86_400);
+    const hours = Math.floor((totalSeconds % 86_400) / 3_600);
+    const minutes = Math.floor((totalSeconds % 3_600) / 60);
+    const seconds = totalSeconds % 60;
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0 && days === 0)
+        parts.push(`${minutes}m`);
+    if (parts.length === 0)
+        parts.push(`${seconds}s`);
+    return parts.join(' ');
+}
+function describeQuotaFailure(quota) {
+    if (!quota || quota.available || !quota.failureKind)
+        return null;
+    switch (quota.failureKind) {
+        case 'auth':
+            if (quota.error === 'No OAuth token available') {
+                return {
+                    severity: 'error',
+                    title: 'Sign in required',
+                    message: 'No Claude Code credentials are available in this environment.',
+                    detail: 'Run `claude` to sign in, then retry quota refresh.',
+                    alertKey: 'auth:no-credentials',
+                    isRetryable: false,
+                };
+            }
+            return {
+                severity: 'error',
+                title: 'Claude Code sign-in expired',
+                message: 'The current Claude Code OAuth session was rejected.',
+                detail: 'Sign in again to refresh subscription quota.',
+                alertKey: `auth:${quota.httpStatus ?? 'unknown'}`,
+                isRetryable: false,
+            };
+        case 'network':
+            return {
+                severity: 'warning',
+                title: 'Quota API unreachable',
+                message: 'Could not reach Anthropic from the current environment.',
+                detail: 'Check connectivity, proxy, or firewall settings, then retry.',
+                alertKey: 'network',
+                isRetryable: true,
+            };
+        case 'rate_limit':
+            return {
+                severity: 'warning',
+                title: 'Quota API rate limited',
+                message: quota.retryAfterMs != null
+                    ? `Retry in ${formatRetryAfter(quota.retryAfterMs)}.`
+                    : 'Retry shortly.',
+                detail: quota.httpStatus != null ? `Anthropic returned HTTP ${quota.httpStatus}.` : undefined,
+                alertKey: `rate_limit:${quota.httpStatus ?? 429}`,
+                isRetryable: true,
+            };
+        case 'server':
+            return {
+                severity: 'warning',
+                title: 'Quota API unavailable',
+                message: quota.httpStatus != null
+                    ? `Anthropic returned HTTP ${quota.httpStatus}. Try again shortly.`
+                    : 'Anthropic quota data is temporarily unavailable.',
+                alertKey: `server:${quota.httpStatus ?? 'unknown'}`,
+                isRetryable: true,
+            };
+        case 'unknown':
+            return {
+                severity: 'error',
+                title: 'Unexpected quota response',
+                message: quota.httpStatus != null
+                    ? `Anthropic returned HTTP ${quota.httpStatus}.`
+                    : (quota.error ?? 'Quota data could not be retrieved.'),
+                detail: 'This failure is not classified as retryable.',
+                alertKey: `unknown:${quota.httpStatus ?? 'none'}`,
+                isRetryable: false,
+            };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.13.6",
+  "version": "0.13.8",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",