@diousk/pi-usage-fast 0.1.0

package/src/providers/xai.ts

@@ -0,0 +1,179 @@
+import { sanitizeDisplayText } from "../core.js";
+import type { UsageBucket, UsageMetric, UsageReport, XaiBillingPayload } from "../types.js";
+
+const MAX_SAFE_CENTS = Number.MAX_SAFE_INTEGER;
+
+export function normalizeXaiBillingPayload(
+  payload: XaiBillingPayload,
+  subscriptionTier: unknown,
+  capturedAt: number,
+): UsageReport {
+  const configValue = payload.config;
+  if (configValue !== null && configValue !== undefined && !isRecord(configValue)) {
+    throw new Error("xAI billing response config was not an object or null.");
+  }
+  const config = isRecord(configValue) ? configValue : undefined;
+  const buckets: UsageBucket[] = [];
+  const metrics: UsageMetric[] = [];
+  const notes: string[] = [];
+
+  if (config) {
+    const period = normalizePeriod(config.currentPeriod, config.billingPeriodStart, config.billingPeriodEnd);
+    const preferredPercent = optionalPercent(config.creditUsagePercent, "creditUsagePercent");
+    if (preferredPercent !== undefined) {
+      buckets.push({
+        id: "included-allowance",
+        label: "Included allowance",
+        used: preferredPercent,
+        remaining: 100 - preferredPercent,
+        unit: "percent",
+        ...period,
+      });
+    } else {
+      const limit = optionalUsd(config.monthlyLimit, "monthlyLimit");
+      const used = optionalUsd(config.used, "used");
+      if (limit !== undefined || used !== undefined) {
+        buckets.push({
+          id: "included-allowance",
+          label: "Included allowance",
+          ...(limit !== undefined ? { limit } : {}),
+          ...(used !== undefined ? { used } : {}),
+          ...(limit !== undefined && used !== undefined ? { remaining: limit - used } : {}),
+          unit: "usd",
+          ...period,
+        });
+      } else if (period.period || period.resetsAt !== undefined) {
+        buckets.push({
+          id: "included-allowance",
+          label: "Included allowance",
+          unit: "percent",
+          ...period,
+        });
+      }
+    }
+
+    const onDemandCap = optionalUsd(config.onDemandCap, "onDemandCap");
+    const onDemandUsed = optionalUsd(config.onDemandUsed, "onDemandUsed");
+    if (onDemandCap !== undefined || onDemandUsed !== undefined) {
+      buckets.push({
+        id: "on-demand",
+        label: "On-demand usage",
+        ...(onDemandCap !== undefined ? { limit: onDemandCap } : {}),
+        ...(onDemandUsed !== undefined ? { used: onDemandUsed } : {}),
+        ...(onDemandCap !== undefined && onDemandUsed !== undefined ? { remaining: onDemandCap - onDemandUsed } : {}),
+        unit: "usd",
+      });
+    }
+
+    const prepaidBalance = optionalUsd(config.prepaidBalance, "prepaidBalance");
+    if (prepaidBalance !== undefined) {
+      metrics.push({
+        id: "prepaid-balance",
+        label: "Prepaid balance",
+        value: prepaidBalance,
+        unit: "usd",
+      });
+    }
+  }
+
+  const tier = optionalTier(subscriptionTier);
+  if (tier) metrics.push({ id: "subscription-tier", label: "Plan tier", value: tier });
+  if (!config) notes.push("No xAI consumer billing configuration is available for this account.");
+  else if (buckets.length === 0 && metrics.length === 0) {
+    notes.push("The xAI consumer billing response contained no displayable usage fields.");
+  }
+
+  return {
+    providerId: "xai",
+    providerName: "xAI",
+    capturedAt,
+    source: "cli-chat-proxy.grok.com consumer billing",
+    semantics: {
+      kind: "consumer-subscription",
+      label: "xAI consumer subscription usage",
+    },
+    buckets,
+    metrics,
+    ...(notes.length > 0 ? { notes } : {}),
+  };
+}
+
+function normalizePeriod(
+  currentPeriod: unknown,
+  legacyStart: unknown,
+  legacyEnd: unknown,
+): Pick<UsageBucket, "period" | "resetsAt"> {
+  if (currentPeriod !== undefined && currentPeriod !== null && !isRecord(currentPeriod)) {
+    throw new Error("xAI billing currentPeriod was not an object or null.");
+  }
+  if (isRecord(currentPeriod)) {
+    const type = optionalString(currentPeriod.type, "currentPeriod.type");
+    const start = optionalTimestamp(currentPeriod.start, "currentPeriod.start");
+    const end = optionalTimestamp(currentPeriod.end, "currentPeriod.end");
+    return {
+      ...(periodLabel(type, start) ? { period: periodLabel(type, start) } : {}),
+      ...(end !== undefined ? { resetsAt: end } : {}),
+    };
+  }
+  const start = optionalTimestamp(legacyStart, "billingPeriodStart");
+  const end = optionalTimestamp(legacyEnd, "billingPeriodEnd");
+  return {
+    ...(start !== undefined ? { period: "Monthly" } : {}),
+    ...(end !== undefined ? { resetsAt: end } : {}),
+  };
+}
+
+function periodLabel(type: string | undefined, start: number | undefined): string | undefined {
+  if (type === "USAGE_PERIOD_TYPE_WEEKLY") return "Weekly";
+  if (type === "USAGE_PERIOD_TYPE_MONTHLY") return "Monthly";
+  if (type) return sanitizeDisplayText(type.replace(/^USAGE_PERIOD_TYPE_/u, "").replaceAll("_", " "), 40);
+  return start === undefined ? undefined : "Current period";
+}
+
+function optionalUsd(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) throw new Error(`xAI billing ${field} was not a cent wrapper.`);
+  const cents = value.val === undefined ? 0 : value.val;
+  if (!Number.isSafeInteger(cents) || Math.abs(cents as number) > MAX_SAFE_CENTS) {
+    throw new Error(`xAI billing ${field}.val was not a safe signed integer.`);
+  }
+  return (cents as number) / 100;
+}
+
+function optionalPercent(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 100) {
+    throw new Error(`xAI billing ${field} was outside 0–100.`);
+  }
+  return value;
+}
+
+function optionalTimestamp(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || value.length > 80) {
+    throw new Error(`xAI billing ${field} was not a bounded timestamp.`);
+  }
+  const milliseconds = Date.parse(value);
+  if (!Number.isFinite(milliseconds)) throw new Error(`xAI billing ${field} was invalid.`);
+  return Math.floor(milliseconds / 1000);
+}
+
+function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || value.length > 80) {
+    throw new Error(`xAI billing ${field} was not a bounded string.`);
+  }
+  return value;
+}
+
+function optionalTier(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string" || value.length > 160) {
+    throw new Error("xAI subscription tier was not a bounded string or null.");
+  }
+  return sanitizeDisplayText(value, 80) || undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/providers/zai-errors.ts

@@ -0,0 +1,94 @@
+// Fixed messages from https://docs.z.ai/api-reference/api-code. Never interpolate provider text:
+// error messages and their template parameters can contain credentials or terminal controls.
+const ERROR_MESSAGES: Readonly<Record<string, string>> = {
+  "1000": "Authentication failed. Check your API key.",
+  "1001": "Authentication header missing. Check your API key.",
+  "1003": "Authentication token expired. Obtain a new token.",
+  "1005": "Two-factor authentication required.",
+  "1113": "Insufficient balance or no resource package. Recharge your account.",
+  "1200": "API call error. Try again later.",
+  "1210": "Invalid API parameter. Check the API documentation.",
+  "1211": "Unknown model. Check the model ID.",
+  "1212": "This model does not support the requested method.",
+  "1213": "A required parameter is missing.",
+  "1214": "Invalid parameter. Check the API documentation.",
+  "1215": "Conflicting parameters. Check the API documentation.",
+  "1220": "Access denied. Check your permissions.",
+  "1221": "This API has been taken offline.",
+  "1222": "This API does not exist.",
+  "1230": "API processing error. Try again later.",
+  "1234": "Network error. Try again later.",
+  "1261": "Prompt too long. Reduce the input length.",
+  "1301": "Content rejected by the safety policy.",
+  "1302": "Request rate limit reached. Try again later.",
+  "1305": "Service overloaded. Try again later.",
+  "1308": "Usage limit reached. Wait for the quota reset.",
+  "1309": "GLM Coding Plan expired. Renew your subscription.",
+  "1310": "Weekly or monthly limit exhausted. Wait for the quota reset.",
+  "1311": "Your subscription does not include this model.",
+  "1313": "Request frequency restricted by the Fair Usage Policy. Contact support.",
+  "1314": "Enterprise package expired. Contact your administrator.",
+  "1315": "This API key requires an enterprise coding package scenario. Replace the key.",
+  "1316": "5-hour limit reached; insufficient balance for extra usage. Wait for reset.",
+  "1317": "7-day limit reached; insufficient balance for extra usage. Wait for reset.",
+  "1318": "5-hour limit reached; extra usage blocked by monthly spend limit.",
+  "1319": "7-day limit reached; extra usage blocked by monthly spend limit.",
+  "1320": "5-hour limit reached; extra usage blocked by monthly spend limit.",
+  "1321": "7-day limit reached; extra usage blocked by monthly spend limit.",
+};
+
+const HTTP_MESSAGES: Readonly<Record<number, string>> = {
+  400: "Invalid request. Check the API documentation.",
+  401: "Authentication failed. Check your API key.",
+  403: "Access denied. Check your permissions.",
+  429: "Request or usage limit reached. Try again later.",
+  500: "Internal error. Try again later.",
+};
+
+export function zaiPayloadError(payload: unknown): string | undefined {
+  const object = asObject(payload);
+  if (!object) return undefined;
+  const nested = asObject(object.error);
+  // Missing nested metadata must not hide a top-level code; explicit nested values retain priority.
+  const rawCode = nested?.code === undefined ? object.code : nested.code;
+  const code = errorCode(rawCode);
+  if (
+    object.error === undefined &&
+    object.success !== false &&
+    (rawCode === undefined || code === "0" || code === "200")
+  ) {
+    return undefined;
+  }
+  return code && code !== "0" && code !== "200"
+    ? `Z.AI ${code}: ${ERROR_MESSAGES[code] ?? "API request failed."}`
+    : "Z.AI: API request failed.";
+}
+
+export function zaiResponseError(status: number, text: string): string | undefined {
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text) as unknown;
+  } catch {
+    // Do not expose JSON parser excerpts, response bodies, or statusText.
+    if (status >= 200 && status < 300) return "Z.AI: Invalid JSON response.";
+  }
+  const error = zaiPayloadError(payload);
+  if (error) return error;
+  if (status < 200 || status >= 300) {
+    return `Z.AI HTTP ${status}: ${HTTP_MESSAGES[status] ?? "API request failed."}`;
+  }
+  return undefined;
+}
+
+function errorCode(value: unknown): string | undefined {
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 9999) {
+    return String(value);
+  }
+  return typeof value === "string" && /^(?:0|[1-9]\d{0,3})$/u.test(value) ? value : undefined;
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}

package/src/providers/zai.ts

@@ -0,0 +1,239 @@
+import { sanitizeDisplayText } from "../core.js";
+import type {
+  UsageBucket,
+  UsageMetric,
+  UsageReport,
+  ZaiPlanInfo,
+  ZaiQuotaPayload,
+  ZaiSubscriptionPayload,
+} from "../types.js";
+
+import { zaiPayloadError } from "./zai-errors.js";
+
+const FIVE_HOUR_WINDOW_MINUTES = 300;
+const WEEKLY_WINDOW_MINUTES = 10_080;
+
+export function normalizeZaiQuotaPayload(
+  providerId: string,
+  providerName: string,
+  payload: ZaiQuotaPayload,
+  capturedAt: number,
+  plan?: ZaiPlanInfo,
+): UsageReport {
+  const error = zaiPayloadError(payload);
+  if (error) throw new Error(error);
+  const data = asObject(payload.data);
+  if (!data) throw new Error("Z.AI quota response data was not an object.");
+  const limits = Array.isArray(data.limits) ? (data.limits as unknown[]) : [];
+
+  const buckets: UsageBucket[] = [];
+  const metrics: UsageMetric[] = [];
+  for (const raw of limits) {
+    const limit = asObject(raw);
+    if (!limit) continue;
+    const type = asString(limit.type);
+    const unit = asNonnegativeNumber(limit.unit);
+    const isPlanUsage = type === "TOKENS_LIMIT" || type === "CREDIT_LIMIT";
+    if (type === "TIME_LIMIT") {
+      addCountBucket(buckets, limit, "mcp-monthly", "MCP monthly allowance");
+      addUsageDetailMetrics(metrics, limit.usageDetails);
+    } else if (isPlanUsage && unit === 3) {
+      addPercentBucket(buckets, limit, "five-hour", sessionWindowLabel(limit), sessionWindowMinutes(limit));
+    } else if (isPlanUsage && unit === 6) {
+      const used = asNonnegativeNumber(limit.currentValue);
+      const quota = asNonnegativeNumber(limit.usage);
+      if (used !== undefined && quota !== undefined) {
+        addCountBucket(buckets, limit, "weekly", "Weekly window", weeklyWindowMinutes(limit));
+      } else {
+        addPercentBucket(buckets, limit, "weekly", "Weekly window", weeklyWindowMinutes(limit));
+      }
+    }
+  }
+  if (buckets.length === 0) {
+    throw new Error("Z.AI quota endpoint returned no displayable usage data.");
+  }
+
+  const notes: string[] = [];
+  const level = asString(data.level);
+  const planLabel = plan?.name ?? level;
+  if (planLabel) {
+    notes.push(plan?.renewsAt ? `Plan: ${planLabel} · renews ${plan.renewsAt}` : `Plan: ${planLabel}`);
+  }
+
+  return {
+    providerId,
+    providerName,
+    capturedAt,
+    source: "zai-quota",
+    semantics: { kind: "consumer-subscription", label: "GLM Coding Plan usage" },
+    buckets,
+    metrics,
+    ...(notes.length > 0 ? { notes } : {}),
+  };
+}
+
+// The undocumented subscription endpoint can include historical products. Prefer the current,
+// valid product and fail closed to the quota plan level when only explicitly inactive products exist.
+export function normalizeZaiSubscriptionPayload(payload: ZaiSubscriptionPayload): ZaiPlanInfo | undefined {
+  if (zaiPayloadError(payload)) return undefined;
+  if (!Array.isArray(payload.data)) return undefined;
+
+  const candidates: Array<{
+    plan: ZaiPlanInfo;
+    status?: string;
+    inCurrentPeriod?: boolean;
+  }> = [];
+  for (const raw of payload.data) {
+    const entry = asObject(raw);
+    if (!entry) continue;
+    const name = asString(entry.productName);
+    if (!name) continue;
+    const renewsAt = planRenewalDate(entry.nextRenewTime);
+    const status = asString(entry.status)?.toUpperCase();
+    const inCurrentPeriod = asBoolean(entry.inCurrentPeriod);
+    candidates.push({
+      plan: { name, ...(renewsAt !== undefined ? { renewsAt } : {}) },
+      ...(status !== undefined ? { status } : {}),
+      ...(inCurrentPeriod !== undefined ? { inCurrentPeriod } : {}),
+    });
+  }
+
+  const hasStateMetadata = candidates.some(
+    (candidate) => candidate.status !== undefined || candidate.inCurrentPeriod !== undefined,
+  );
+  if (!hasStateMetadata) return candidates[0]?.plan;
+  return (
+    candidates.find((candidate) => candidate.inCurrentPeriod === true && candidate.status === "VALID")?.plan ??
+    candidates.find((candidate) => candidate.inCurrentPeriod === true && candidate.status === undefined)?.plan ??
+    candidates.find((candidate) => candidate.status === "VALID" && candidate.inCurrentPeriod === undefined)?.plan
+  );
+}
+
+function planRenewalDate(value: unknown): string | undefined {
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}/u.test(value)) return value.slice(0, 10);
+  const millis = asNonnegativeNumber(value);
+  if (millis === undefined || millis === 0) return undefined;
+  return new Date(millis).toISOString().slice(0, 10);
+}
+
+// Z.AI encodes each window as a (unit, number) pair — unit 3 counts hours and unit 6 counts
+// weeks — so the payload's number drives the window length and session label; the established
+// 5-hour and weekly constants remain the fallback when the payload omits it.
+function sessionWindowMinutes(limit: Record<string, unknown>): number {
+  const hours = asPositiveNumber(limit.number);
+  return hours === undefined ? FIVE_HOUR_WINDOW_MINUTES : Math.round(hours * 60);
+}
+
+function sessionWindowLabel(limit: Record<string, unknown>): string {
+  const minutes = sessionWindowMinutes(limit);
+  return minutes === FIVE_HOUR_WINDOW_MINUTES ? "5h window" : `${Math.round(minutes / 60)}h window`;
+}
+
+function weeklyWindowMinutes(limit: Record<string, unknown>): number {
+  const weeks = asPositiveNumber(limit.number);
+  return weeks === undefined ? WEEKLY_WINDOW_MINUTES : Math.round(weeks * WEEKLY_WINDOW_MINUTES);
+}
+
+function addPercentBucket(
+  buckets: UsageBucket[],
+  limit: Record<string, unknown>,
+  id: string,
+  label: string,
+  windowMinutes: number,
+): void {
+  const used = asNonnegativeNumber(limit.percentage);
+  if (used === undefined) return;
+  const percent = clampPercent(used);
+  const resetsAt = asEpochSeconds(limit.nextResetTime);
+  buckets.push({
+    id,
+    label,
+    used: percent,
+    remaining: 100 - percent,
+    limit: 100,
+    unit: "percent",
+    windowMinutes,
+    ...(resetsAt !== undefined ? { resetsAt } : {}),
+  });
+}
+
+function addCountBucket(
+  buckets: UsageBucket[],
+  limit: Record<string, unknown>,
+  id: string,
+  label: string,
+  windowMinutes?: number,
+): void {
+  const used = asNonnegativeNumber(limit.currentValue);
+  const quota = asNonnegativeNumber(limit.usage);
+  if (used === undefined || quota === undefined) return;
+  const resetsAt = asEpochSeconds(limit.nextResetTime);
+  buckets.push({
+    id,
+    label,
+    used,
+    remaining: Math.max(0, quota - used),
+    limit: quota,
+    unit: "count",
+    ...(windowMinutes !== undefined ? { windowMinutes } : {}),
+    ...(resetsAt !== undefined ? { resetsAt } : {}),
+  });
+}
+
+function addUsageDetailMetrics(metrics: UsageMetric[], value: unknown): void {
+  if (!Array.isArray(value)) return;
+  for (const raw of value) {
+    const detail = asObject(raw);
+    if (!detail) continue;
+    const label = asString(detail.modelCode);
+    const usage = asNonnegativeNumber(detail.usage);
+    if (!label || usage === undefined) continue;
+    metrics.push({ id: `mcp-${kebabCase(label)}`, label, value: usage, unit: "count" });
+  }
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  return sanitizeDisplayText(value, 80) || undefined;
+}
+
+function asNonnegativeNumber(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
+  return value;
+}
+
+function asPositiveNumber(value: unknown): number | undefined {
+  const number = asNonnegativeNumber(value);
+  return number !== undefined && number > 0 ? number : undefined;
+}
+
+function asBoolean(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (value === 1) return true;
+  if (value === 0) return false;
+  return undefined;
+}
+
+function asEpochSeconds(value: unknown): number | undefined {
+  const millis = asNonnegativeNumber(value);
+  if (millis === undefined) return undefined;
+  return Math.floor(millis / 1000);
+}
+
+function kebabCase(label: string): string {
+  return (
+    label
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/gu, "-")
+      .replace(/^-+|-+$/gu, "") || "tool"
+  );
+}
+
+function clampPercent(value: number): number {
+  return Math.min(100, Math.max(0, value));
+}