codex-usage-analyzer 0.1.0 → 0.2.0

package/docs/account-usage.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Codex Account Usage Contract",
+  "description": "Identity-free account usage output produced by codex-usage-analyzer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "capturedAt",
+    "summary",
+    "dailyUsageBuckets"
+  ],
+  "properties": {
+    "contractVersion": {
+      "const": 1
+    },
+    "capturedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "summary": {
+      "$ref": "#/definitions/summary"
+    },
+    "dailyUsageBuckets": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/dailyUsageBucket"
+          }
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "nullableNonNegativeInteger": {
+      "oneOf": [
+        {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "lifetimeTokens",
+        "peakDailyTokens",
+        "longestRunningTurnSec",
+        "currentStreakDays",
+        "longestStreakDays"
+      ],
+      "properties": {
+        "lifetimeTokens": {
+          "$ref": "#/definitions/nullableNonNegativeInteger"
+        },
+        "peakDailyTokens": {
+          "$ref": "#/definitions/nullableNonNegativeInteger"
+        },
+        "longestRunningTurnSec": {
+          "$ref": "#/definitions/nullableNonNegativeInteger"
+        },
+        "currentStreakDays": {
+          "$ref": "#/definitions/nullableNonNegativeInteger"
+        },
+        "longestStreakDays": {
+          "$ref": "#/definitions/nullableNonNegativeInteger"
+        }
+      }
+    },
+    "dailyUsageBucket": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "startDate",
+        "tokens"
+      ],
+      "properties": {
+        "startDate": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+        },
+        "tokens": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      }
+    }
+  }
+}

package/docs/downstream-integration.md

@@ -0,0 +1,195 @@
+# Downstream Integration Guide
+
+This guide defines the boundary between `codex-usage-analyzer` and a service that stores account usage or renders a profile card.
+
+The CLI owns one artifact: the identity-free [Account Usage Contract](account-usage-contract.md). A downstream service owns identity, authorization, submission, persistence, rendering, cache behavior, privacy controls, and deletion.
+
+## Recommended architecture
+
+```text
+Codex app-server
+      |
+      v
+codex-usage-analyzer --json
+      |
+      | identity-free usage document
+      v
+downstream submit API ---- GitHub account binding
+      |
+      +---- validated usage storage
+      +---- sanitized identity projection
+      +---- stable card/image endpoint
+```
+
+Do not extend the CLI document with downstream fields. Keep the usage contract reusable and combine identity only after the downstream has authenticated the submitter.
+
+## Responsibility boundary
+
+| Concern | CLI | Downstream |
+|---|---|---|
+| Read account usage | Call the official app-server method | Never request Codex credentials |
+| Normalize usage | Emit contract-versioned allowlisted fields | Validate the complete contract before accepting it |
+| GitHub identity | None | Authenticate and bind a stable GitHub user id |
+| submit token | None | Issue, hash, rotate, revoke, and rate-limit its own token |
+| Storage | None | Store only the minimum usage and identity projection needed |
+| Card rendering | None | Format values, localize labels, and render the image |
+| HTTP cache | None | Define freshness, validators, and revision behavior |
+| Privacy and delete controls | None | Explain visibility and retention; provide revoke and delete paths |
+
+## GitHub identity
+
+Use the downstream's GitHub OAuth or GitHub App session as the account ownership proof. Bind records to GitHub's stable numeric user id, not to a mutable login or display name.
+
+Recommended normalized fields inside the downstream only:
+
+```json
+{
+  "provider": "github",
+  "providerUserId": "12345678",
+  "username": "octocat",
+  "displayName": "The Octocat",
+  "avatarUrl": "https://avatars.githubusercontent.com/u/12345678?v=4"
+}
+```
+
+The values are illustrative. Map GitHub `login` to `username`, use `name` for `displayName` when present, and fall back to `login` when it is absent. Map `avatar_url` to `avatarUrl` only after validating the response from GitHub.
+
+Never trust identity fields supplied beside a CLI upload. A user who can submit usage must not be able to overwrite another account's name, username, avatar, ownership id, or public URL.
+
+## Submit authentication
+
+Issue a narrow downstream submit token after GitHub account binding. The token should authorize only usage updates for one bound downstream account.
+
+- Do not accept an OpenAI, Codex, GitHub, npm, or operating-system credential as a submit token.
+- Show the token only at creation, store only a slow or cryptographic hash as appropriate, and support rotation and immediate revocation.
+- Keep the token out of command arguments, URLs, image URLs, logs, analytics, and error bodies.
+- Prefer stdin, an environment variable, or an operating-system secret store in the downstream client.
+- Apply per-account and per-token rate limits and record security events without recording payload values.
+
+The base CLI does not define a submit command or token field. A downstream-specific wrapper should own that interface.
+
+## Suggested submit API
+
+The following protocol is non-normative. It illustrates a boundary that does not mix identity with usage.
+
+```http
+POST /v1/account-usage
+Authorization: Bearer <downstream-issued-submit-token>
+Content-Type: application/json
+```
+
+The request body is exactly one Account Usage Contract document:
+
+```json
+{
+  "contractVersion": 1,
+  "capturedAt": "2026-07-11T00:00:00.000Z",
+  "summary": {
+    "lifetimeTokens": 1234567890,
+    "peakDailyTokens": 45600000,
+    "longestRunningTurnSec": 754,
+    "currentStreakDays": 3,
+    "longestStreakDays": 21
+  },
+  "dailyUsageBuckets": []
+}
+```
+
+All values are synthetic. A successful response can return opaque downstream metadata:
+
+```json
+{
+  "status": "accepted",
+  "revision": "opaque-revision",
+  "imageUrl": "https://example.invalid/u/octocat/codex-usage.png"
+}
+```
+
+Do not copy `revision` or `imageUrl` into the account usage document.
+
+## Validation and storage
+
+Before storing a submission:
+
+1. Authenticate and rate-limit the downstream submit token.
+2. Enforce request content type and a conservative body-size limit.
+3. Validate the JSON Schema and reject unknown `contractVersion` values.
+4. Reject extra fields, unsafe integers, invalid dates, and future `capturedAt` values beyond a small clock-skew allowance.
+5. Reject stale or replayed updates according to an explicit policy.
+6. Bind the write to the token's account, never to a body-supplied username.
+
+Store only fields needed to render the product. Separate usage data from credential records, encrypt sensitive stores at rest, limit operator access, and define a retention period. Logs should contain request ids, result codes, timings, contract version, and coarse byte counts, not account usage values or identity payloads.
+
+Preserve null semantics:
+
+- `null` means unavailable and must not be displayed as zero.
+- `[]` means daily data was available but contained no rows.
+- Daily `startDate` values are source dates and must not be timezone-rebucketed.
+
+## Rendering and cache behavior
+
+The downstream owns all presentation decisions, including number formatting, localization, missing-value labels, heatmap color thresholds, and avatar treatment.
+
+For a README image endpoint:
+
+- Keep one stable HTTPS image URL per public profile.
+- Return an actual image content type and deterministic bytes for a stored revision.
+- Send `ETag` and `Last-Modified` validators and a deliberate `Cache-Control` policy that permits revalidation.
+- Update the validator when a new submission changes rendered content.
+- Keep immutable, revision-addressed assets internally so rendering can be retried and rolled back.
+- Expect GitHub's image proxy to introduce cache delay; do not promise immediate refresh after submit.
+- Do not include submit tokens, account ids, private revisions, or sensitive query parameters in the public image URL.
+
+Fetch remote avatars server-side only with strict HTTPS host policy, redirect limits, response-size limits, image decoding, and content-type verification. Re-encode to a safe image format before storage or rendering. This prevents browser tracking and reduces server-side request forgery and image parser risk.
+
+## Privacy, revocation, and deletion
+
+Before a profile becomes public, explain exactly which identity and usage fields will be visible. Default new profiles to private unless the product intentionally and clearly asks for public visibility.
+
+Provide controls to:
+
+- revoke every submit token
+- disable the public card without deleting the account
+- delete stored usage, rendered assets, and the downstream identity binding
+- export or inspect the stored fields when required by the product's policy
+
+Deletion should invalidate caches where possible and make the stable image URL return a non-sensitive tombstone or `404`. Document backup-retention limits and avoid retaining deleted data indefinitely.
+
+## Experimental profile identity
+
+A future adapter for private or undocumented profile endpoints such as `/wham/profiles/me` must remain separate from the default CLI and its contract. It is not implemented by `codex-usage-analyzer`.
+
+If a downstream chooses to experiment with such an adapter:
+
+- require explicit opt-in for every invocation
+- label the source unstable and unsupported
+- never silently fall back to it
+- never use its identity as authentication, authorization, or account ownership proof
+- allowlist only cosmetic fields and discard usage metrics from that response
+- never persist or log raw responses, credentials, account identifiers, or private URLs
+- sanitize and re-host an avatar instead of exposing a raw remote URL to viewers
+- make failure non-fatal to the official account usage path
+
+A separate downstream-owned envelope may use these field names:
+
+```json
+{
+  "experimentalProfile": {
+    "source": "codex-private-profile",
+    "displayName": "Example Name",
+    "username": "example",
+    "avatarUrl": "https://example.invalid/avatar-source",
+    "observedAt": "2026-07-11T00:00:00.000Z"
+  }
+}
+```
+
+This envelope is not part of the Account Usage Contract. GitHub identity should remain the default display source and the only account binding unless a later, separately reviewed design establishes another verifiable identity source.
+
+Keep the experimental envelope authenticated and non-public. Treat `avatarUrl` as untrusted adapter input and replace it with a sanitized downstream asset before rendering or storage.
+
+## Versioning
+
+Accept only contract versions the downstream explicitly supports. A new root field, changed field meaning, changed nullability, or changed date semantics requires a new contract version and coordinated rollout.
+
+Deploy downstream read support before emitting a new version. Keep old readers and stored records isolated by `contractVersion`, and do not reinterpret old data under new semantics.

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "codex-usage-analyzer",
-  "version": "0.1.0",
-  "description": "Analyze local Codex usage and emit UsageSnapshot v2 JSON.",
+  "version": "0.2.0",
+  "description": "Read Codex account usage through the official app-server protocol.",
+  "keywords": [
+    "codex",
+    "openai",
+    "usage",
+    "cli",
+    "app-server"
+  ],
+  "license": "MIT",
   "type": "module",
   "homepage": "https://github.com/postmelee/codex-usage-analyzer#readme",
   "repository": {
@@ -23,17 +31,21 @@
   },
   "files": [
     "bin",
-    "src/analyze.js",
+    "docs",
+    "src/account-usage.js",
+    "src/app-server-client.js",
     "src/cli.js",
-    "src/fixtures/sample-v2-snapshot.js",
+    "src/errors.js",
+    "src/format-account-usage.js",
     "src/index.d.ts",
     "src/index.js",
-    "src/parser",
-    "src/snapshot",
-    "README.md"
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "release:preflight": "node scripts/release-preflight.js"
   },
   "engines": {
     "node": ">=20"

package/src/account-usage.js

@@ -0,0 +1,115 @@
+import { requestAccountUsageFromAppServer } from "./app-server-client.js";
+import { CODEX_USAGE_ERROR_CODES, CodexUsageError } from "./errors.js";
+
+export const ACCOUNT_USAGE_CONTRACT_VERSION = 1;
+
+export const ACCOUNT_USAGE_SUMMARY_FIELDS = Object.freeze([
+  "lifetimeTokens",
+  "peakDailyTokens",
+  "longestRunningTurnSec",
+  "currentStreakDays",
+  "longestStreakDays"
+]);
+
+export async function readAccountUsage(options = {}) {
+  const result = await requestAccountUsageFromAppServer({
+    timeoutMs: options.timeoutMs,
+    spawnProcess: options.spawnProcess
+  });
+
+  return normalizeAccountUsageResult(result);
+}
+
+export function normalizeAccountUsageResult(result, options = {}) {
+  if (!isRecord(result) || !isRecord(result.summary)) {
+    throw invalidResponse();
+  }
+
+  const summary = {};
+  for (const field of ACCOUNT_USAGE_SUMMARY_FIELDS) {
+    summary[field] = normalizeNullableInteger(result.summary[field]);
+  }
+
+  return {
+    contractVersion: ACCOUNT_USAGE_CONTRACT_VERSION,
+    capturedAt: normalizeCapturedAt(options.capturedAt),
+    summary,
+    dailyUsageBuckets: normalizeDailyUsageBuckets(result.dailyUsageBuckets)
+  };
+}
+
+function normalizeDailyUsageBuckets(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+
+  if (!Array.isArray(value)) {
+    throw invalidResponse();
+  }
+
+  return value.map((bucket) => {
+    if (!isRecord(bucket) || !isDateOnly(bucket.startDate)) {
+      throw invalidResponse();
+    }
+
+    return {
+      startDate: bucket.startDate,
+      tokens: normalizeRequiredInteger(bucket.tokens)
+    };
+  });
+}
+
+function normalizeNullableInteger(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+
+  return normalizeRequiredInteger(value);
+}
+
+function normalizeRequiredInteger(value) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw invalidResponse();
+  }
+
+  return value;
+}
+
+function normalizeCapturedAt(value) {
+  if (value === undefined) {
+    return new Date().toISOString();
+  }
+
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw invalidResponse();
+  }
+
+  return date.toISOString();
+}
+
+function isDateOnly(value) {
+  if (typeof value !== "string") return false;
+
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/u.exec(value);
+  if (match === null) return false;
+
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const date = new Date(Date.UTC(year, month - 1, day));
+
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day;
+}
+
+function invalidResponse() {
+  return new CodexUsageError(
+    CODEX_USAGE_ERROR_CODES.INVALID_ACCOUNT_USAGE_RESPONSE
+  );
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/app-server-client.js

@@ -0,0 +1,229 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+import { CODEX_USAGE_ERROR_CODES, CodexUsageError } from "./errors.js";
+
+export const DEFAULT_APP_SERVER_TIMEOUT_MS = 15_000;
+export const MAX_APP_SERVER_TIMEOUT_MS = 120_000;
+
+const INITIALIZE_REQUEST_ID = 0;
+const ACCOUNT_USAGE_REQUEST_ID = 1;
+
+export async function requestAccountUsageFromAppServer(options = {}) {
+  const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
+  const spawnProcess = options.spawnProcess ?? spawn;
+  let child;
+
+  try {
+    child = spawnProcess("codex", ["app-server"], {
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true
+    });
+  } catch (error) {
+    return Promise.reject(createSpawnError(error));
+  }
+
+  if (!child?.stdin || !child?.stdout || !child?.stderr) {
+    stopChild(child);
+    return Promise.reject(new CodexUsageError(
+      CODEX_USAGE_ERROR_CODES.APP_SERVER_START_FAILED
+    ));
+  }
+
+  child.stderr.resume();
+
+  return new Promise((resolve, reject) => {
+    const lines = createInterface({
+      input: child.stdout,
+      crlfDelay: Infinity
+    });
+    let phase = "initializing";
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      fail(new CodexUsageError(CODEX_USAGE_ERROR_CODES.APP_SERVER_TIMEOUT));
+    }, timeoutMs);
+
+    function cleanup() {
+      clearTimeout(timer);
+      lines.removeAllListeners();
+      lines.close();
+
+      if (!child.stdin.destroyed) {
+        child.stdin.end();
+      }
+
+      stopChild(child);
+    }
+
+    function succeed(result) {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    }
+
+    function fail(error) {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    }
+
+    function send(message) {
+      if (settled) return;
+
+      try {
+        child.stdin.write(`${JSON.stringify(message)}\n`, (error) => {
+          if (error) {
+            fail(new CodexUsageError(
+              CODEX_USAGE_ERROR_CODES.APP_SERVER_PROTOCOL_ERROR
+            ));
+          }
+        });
+      } catch {
+        fail(new CodexUsageError(
+          CODEX_USAGE_ERROR_CODES.APP_SERVER_PROTOCOL_ERROR
+        ));
+      }
+    }
+
+    function onError(error) {
+      fail(createSpawnError(error));
+    }
+
+    function onExit() {
+      fail(new CodexUsageError(CODEX_USAGE_ERROR_CODES.APP_SERVER_EXITED));
+    }
+
+    function onLine(line) {
+      let message;
+
+      try {
+        message = JSON.parse(line);
+      } catch {
+        fail(new CodexUsageError(
+          CODEX_USAGE_ERROR_CODES.APP_SERVER_PROTOCOL_ERROR
+        ));
+        return;
+      }
+
+      if (!isRecord(message)) {
+        fail(new CodexUsageError(
+          CODEX_USAGE_ERROR_CODES.APP_SERVER_PROTOCOL_ERROR
+        ));
+        return;
+      }
+
+      if (message.id === INITIALIZE_REQUEST_ID) {
+        if (phase !== "initializing") {
+          fail(new CodexUsageError(
+            CODEX_USAGE_ERROR_CODES.APP_SERVER_PROTOCOL_ERROR
+          ));
+          return;
+        }
+
+        if (hasRpcError(message)) {
+          fail(createRpcError(message.error));
+          return;
+        }
+
+        if (!Object.hasOwn(message, "result")) {
+          fail(new CodexUsageError(
+            CODEX_USAGE_ERROR_CODES.APP_SERVER_PROTOCOL_ERROR
+          ));
+          return;
+        }
+
+        phase = "reading_usage";
+        send({ method: "initialized", params: {} });
+        send({ method: "account/usage/read", id: ACCOUNT_USAGE_REQUEST_ID });
+        return;
+      }
+
+      if (message.id === ACCOUNT_USAGE_REQUEST_ID) {
+        if (phase !== "reading_usage") {
+          fail(new CodexUsageError(
+            CODEX_USAGE_ERROR_CODES.APP_SERVER_PROTOCOL_ERROR
+          ));
+          return;
+        }
+
+        if (hasRpcError(message)) {
+          fail(createRpcError(message.error));
+          return;
+        }
+
+        if (!Object.hasOwn(message, "result")) {
+          fail(new CodexUsageError(
+            CODEX_USAGE_ERROR_CODES.APP_SERVER_PROTOCOL_ERROR
+          ));
+          return;
+        }
+
+        succeed(message.result);
+      }
+    }
+
+    child.once("error", onError);
+    child.once("exit", onExit);
+    lines.on("line", onLine);
+
+    send({
+      method: "initialize",
+      id: INITIALIZE_REQUEST_ID,
+      params: {
+        clientInfo: {
+          name: "codex_usage_analyzer",
+          title: "Codex Usage Analyzer",
+          version: "0.2.0"
+        }
+      }
+    });
+  });
+}
+
+function normalizeTimeoutMs(value) {
+  if (value === undefined) {
+    return DEFAULT_APP_SERVER_TIMEOUT_MS;
+  }
+
+  if (!Number.isInteger(value) || value < 1 || value > MAX_APP_SERVER_TIMEOUT_MS) {
+    throw new CodexUsageError(CODEX_USAGE_ERROR_CODES.INVALID_TIMEOUT);
+  }
+
+  return value;
+}
+
+function createSpawnError(error) {
+  const code = error && typeof error === "object" ? error.code : undefined;
+  return new CodexUsageError(
+    code === "ENOENT"
+      ? CODEX_USAGE_ERROR_CODES.CODEX_NOT_FOUND
+      : CODEX_USAGE_ERROR_CODES.APP_SERVER_START_FAILED
+  );
+}
+
+function createRpcError(error) {
+  return new CodexUsageError(CODEX_USAGE_ERROR_CODES.APP_SERVER_RPC_ERROR, {
+    rpcCode: Number.isInteger(error?.code) ? error.code : undefined
+  });
+}
+
+function hasRpcError(message) {
+  return Object.hasOwn(message, "error");
+}
+
+function stopChild(child) {
+  if (!child || child.exitCode !== null || child.killed) return;
+
+  try {
+    child.kill();
+  } catch {
+    // Cleanup failure does not replace the safe protocol result.
+  }
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}