@jeffreycao/copilot-api 1.9.3 → 1.9.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@jeffreycao/copilot-api",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "description": "Turn GitHub Copilot into OpenAI/Anthropic API compatible server. Usable with Claude Code Or Codex Or Opencode!",
   "keywords": [
     "proxy",

package/pages/index.html

@@ -92,6 +92,12 @@
         border-color: var(--color-blue);
       }
 
+      button:disabled,
+      select:disabled {
+        cursor: not-allowed;
+        opacity: 0.55;
+      }
+
 
     </style>
   </head>
@@ -140,29 +146,73 @@
         >
           <form
             id="endpoint-form"
-            class="flex flex-col sm:flex-row items-center gap-3"
+            class="grid grid-cols-1 xl:grid-cols-[minmax(0,2fr)_minmax(0,1fr)_180px_auto] gap-3 items-end"
           >
-            <label
-              for="endpoint-url"
-              class="font-semibold whitespace-nowrap text-sm"
-              style="color: var(--color-fg-lightest)"
-              >API Endpoint URL</label
-            >
-            <input
-              type="text"
-              id="endpoint-url"
-              class="w-full px-3 py-1.5 border focus:ring-1 transition input-focus text-sm"
-              style="
-                background-color: var(--color-bg-darkest);
-                border-color: var(--color-bg-light-3);
-                color: var(--color-fg-medium);
-              "
-              placeholder="http://localhost:4141/usage"
-            />
+            <div class="w-full">
+              <label
+                for="endpoint-url"
+                class="mb-1 block font-semibold whitespace-nowrap text-sm"
+                style="color: var(--color-fg-lightest)"
+                >Usage Endpoint URL</label
+              >
+              <input
+                type="text"
+                id="endpoint-url"
+                class="w-full px-3 py-2 border focus:ring-1 transition input-focus text-sm"
+                style="
+                  background-color: var(--color-bg-darkest);
+                  border-color: var(--color-bg-light-3);
+                  color: var(--color-fg-medium);
+                "
+                placeholder="http://localhost:4141/usage"
+              />
+            </div>
+            <div class="w-full">
+              <label
+                for="x-api-key"
+                class="mb-1 block font-semibold whitespace-nowrap text-sm"
+                style="color: var(--color-fg-lightest)"
+                >x-api-key</label
+              >
+              <input
+                type="password"
+                id="x-api-key"
+                class="w-full px-3 py-2 border focus:ring-1 transition input-focus text-sm"
+                style="
+                  background-color: var(--color-bg-darkest);
+                  border-color: var(--color-bg-light-3);
+                  color: var(--color-fg-medium);
+                "
+                placeholder="Optional when auth is enabled"
+                autocomplete="off"
+                spellcheck="false"
+              />
+            </div>
+            <div class="w-full">
+              <label
+                for="token-usage-period"
+                class="mb-1 block font-semibold whitespace-nowrap text-sm"
+                style="color: var(--color-fg-lightest)"
+                >Token Usage Period</label
+              >
+              <select
+                id="token-usage-period"
+                class="w-full px-3 py-2 border focus:ring-1 transition input-focus text-sm"
+                style="
+                  background-color: var(--color-bg-darkest);
+                  border-color: var(--color-bg-light-3);
+                  color: var(--color-fg-medium);
+                "
+              >
+                <option value="day">Day</option>
+                <option value="week">Week</option>
+                <option value="month">Month</option>
+              </select>
+            </div>
             <button
               id="fetch-button"
               type="submit"
-              class="w-full sm:w-auto font-bold py-1.5 px-5 transition-colors flex items-center justify-center gap-2 text-sm"
+              class="w-full xl:w-auto font-bold py-2 px-5 transition-colors flex items-center justify-center gap-2 text-sm"
               style="
                 background-color: var(--color-blue);
                 color: var(--color-bg-darkest);
@@ -188,6 +238,11 @@
               <span>Fetch</span>
             </button>
           </form>
+          <p class="mt-3 text-xs" style="color: var(--color-gray-accent)">
+            The page derives <code>/token-usage</code> and
+            <code>/token-usage/events</code> from the usage endpoint and sends
+            <code>x-api-key</code> to all requests when provided.
+          </p>
         </div>
 
         <!-- Content Area for dynamic data -->
@@ -199,8 +254,13 @@
       document.addEventListener("DOMContentLoaded", () => {
         const endpointForm = document.getElementById("endpoint-form");
         const endpointUrlInput = document.getElementById("endpoint-url");
+        const apiKeyInput = document.getElementById("x-api-key");
+        const tokenUsagePeriodSelect = document.getElementById(
+          "token-usage-period"
+        );
         const contentArea = document.getElementById("content-area");
         const fetchButton = document.getElementById("fetch-button");
+        const fetchButtonLabel = fetchButton.querySelector("span");
 
         // Apply hover effect for fetch button via JS
         fetchButton.addEventListener("mouseenter", () => {
@@ -211,12 +271,31 @@
         });
 
         const DEFAULT_ENDPOINT = "http://localhost:4141/usage";
+        const DEFAULT_TOKEN_USAGE_PERIOD = "day";
+        const DEFAULT_TOKEN_USAGE_EVENTS_PAGE_SIZE = 20;
+        const API_KEY_STORAGE_KEY = "copilot-api.usage-viewer.x-api-key";
+        const VALID_PERIODS = new Set(["day", "week", "month"]);
+        const EMPTY_TOKEN_USAGE_TOTALS = {
+          cache_creation_input_tokens: 0,
+          cache_read_input_tokens: 0,
+          input_tokens: 0,
+          output_tokens: 0,
+          request_count: 0,
+          total_tokens: 0,
+        };
 
         // --- State Management ---
         const state = {
           isLoading: false,
+          isTokenUsageLoading: false,
+          isEventsLoading: false,
           error: null,
           data: null,
+          tokenUsageSummary: null,
+          tokenUsageEventsPage: null,
+          tokenUsageSummaryError: null,
+          tokenUsageEventsError: null,
+          tokenUsagePeriod: DEFAULT_TOKEN_USAGE_PERIOD,
         };
 
         // --- Rendering Logic ---
@@ -230,24 +309,253 @@
           }
         }
 
+        function escapeHtml(value) {
+          return String(value)
+            .replaceAll("&", "&amp;")
+            .replaceAll("<", "&lt;")
+            .replaceAll(">", "&gt;")
+            .replaceAll('"', "&quot;")
+            .replaceAll("'", "&#39;");
+        }
+
+        function getErrorMessage(error) {
+          if (error instanceof Error) {
+            return error.message;
+          }
+          return typeof error === "string" ? error : "Unknown error.";
+        }
+
+        function isMissingTokenUsageEndpointError(error) {
+          return Boolean(
+            error
+              && typeof error === "object"
+              && "status" in error
+              && error.status === 404
+          );
+        }
+
+        function normalizePeriod(value) {
+          return VALID_PERIODS.has(value)
+            ? value
+            : DEFAULT_TOKEN_USAGE_PERIOD;
+        }
+
+        function getSelectedPeriod() {
+          const normalized = normalizePeriod(tokenUsagePeriodSelect.value);
+          tokenUsagePeriodSelect.value = normalized;
+          state.tokenUsagePeriod = normalized;
+          return normalized;
+        }
+
+        function loadStoredApiKey() {
+          try {
+            return localStorage.getItem(API_KEY_STORAGE_KEY) || "";
+          } catch (error) {
+            console.warn("Could not read stored API key:", getErrorMessage(error));
+            return "";
+          }
+        }
+
+        function storeApiKey(value) {
+          try {
+            const trimmed = value.trim();
+            if (trimmed) {
+              localStorage.setItem(API_KEY_STORAGE_KEY, trimmed);
+            } else {
+              localStorage.removeItem(API_KEY_STORAGE_KEY);
+            }
+          } catch (error) {
+            console.warn("Could not store API key:", getErrorMessage(error));
+          }
+        }
+
+        function buildRequestHeaders() {
+          const headers = {};
+          const apiKey = apiKeyInput.value.trim();
+          if (apiKey) {
+            headers["x-api-key"] = apiKey;
+          }
+          return headers;
+        }
+
+        function resolveUsageUrl(endpoint) {
+          return new URL(endpoint, window.location.href).toString();
+        }
+
+        function deriveEndpointUrl(usageEndpoint, targetPath) {
+          const url = new URL(usageEndpoint, window.location.href);
+          const normalizedTargetPath = targetPath.replace(/^\/+/, "");
+          const normalizedPath = url.pathname.replace(/\/+$/, "");
+          const nextPath = normalizedPath.endsWith("/usage")
+            ? normalizedPath.replace(/\/usage$/, `/${normalizedTargetPath}`)
+            : `${normalizedPath || ""}/${normalizedTargetPath}`;
+
+          url.pathname = nextPath.startsWith("/") ? nextPath : `/${nextPath}`;
+          url.search = "";
+          url.hash = "";
+          return url.toString();
+        }
+
+        function buildTokenUsageSummaryUrl(usageEndpoint, period) {
+          const url = new URL(deriveEndpointUrl(usageEndpoint, "token-usage"));
+          url.searchParams.set("period", period);
+          return url.toString();
+        }
+
+        function buildTokenUsageEventsUrl(usageEndpoint, period, page) {
+          const url = new URL(
+            deriveEndpointUrl(usageEndpoint, "token-usage/events")
+          );
+          url.searchParams.set("period", period);
+          url.searchParams.set("page", String(page));
+          url.searchParams.set(
+            "page_size",
+            String(DEFAULT_TOKEN_USAGE_EVENTS_PAGE_SIZE)
+          );
+          return url.toString();
+        }
+
+        async function fetchJson(url) {
+          const response = await fetch(url, {
+            headers: buildRequestHeaders(),
+          });
+
+          if (!response.ok) {
+            let message = response.statusText || "Request failed";
+
+            try {
+              const contentType = response.headers.get("content-type") || "";
+              if (contentType.includes("application/json")) {
+                const payload = await response.json();
+                const apiMessage = payload?.error?.message || payload?.message;
+                if (typeof apiMessage === "string" && apiMessage.trim()) {
+                  message = apiMessage.trim();
+                }
+              } else {
+                const text = await response.text();
+                if (text.trim()) {
+                  message = text.trim();
+                }
+              }
+            } catch (error) {
+              console.warn(
+                "Could not parse error response:",
+                getErrorMessage(error)
+              );
+            }
+
+            const error = new Error(
+              `Request failed with status ${response.status}: ${message}`
+            );
+            error.status = response.status;
+            throw error;
+          }
+
+          return response.json();
+        }
+
+        function syncUrlState() {
+          try {
+            const currentUrl = new URL(window.location.href);
+            const endpoint = endpointUrlInput.value.trim();
+            const period = getSelectedPeriod();
+
+            if (endpoint) {
+              currentUrl.searchParams.set("endpoint", endpoint);
+            } else {
+              currentUrl.searchParams.delete("endpoint");
+            }
+
+            currentUrl.searchParams.set("period", period);
+            window.history.pushState({}, "", currentUrl);
+          } catch (error) {
+            console.warn("Could not update URL:", getErrorMessage(error));
+          }
+        }
+
+        function updateControls() {
+          fetchButton.disabled = state.isLoading;
+          fetchButtonLabel.textContent = state.isLoading ? "Fetching..." : "Fetch";
+          tokenUsagePeriodSelect.disabled =
+            state.isLoading || state.isTokenUsageLoading;
+        }
+
+        function formatNumber(value) {
+          return Number.isFinite(value) ? Number(value).toLocaleString() : "0";
+        }
+
+        function formatDateTime(value) {
+          if (!Number.isFinite(value)) {
+            return "N/A";
+          }
+          return new Date(value).toLocaleString();
+        }
+
+        function formatCellText(value) {
+          if (typeof value !== "string") {
+            return "—";
+          }
+
+          const trimmed = value.trim();
+          return trimmed || "—";
+        }
+
+        function renderTokenUsageRangeText(period, range) {
+          const labels = {
+            day: "Day window",
+            week: "Week window",
+            month: "Month window",
+          };
+
+          if (!range) {
+            return labels[period] || labels.day;
+          }
+
+          return `${labels[period] || labels.day}: ${formatDateTime(
+            range.start_ms
+          )} - ${formatDateTime(range.end_ms)}`;
+        }
+
         /**
          * Renders the entire UI based on the current state.
          */
         function render() {
+          updateControls();
+
           if (state.isLoading) {
             contentArea.innerHTML = renderSpinner();
+            createIcons();
             return;
           }
-          if (state.error) {
-            contentArea.innerHTML = renderError(state.error);
+
+          const hasContent = Boolean(
+            state.error
+              || state.data
+              || state.isTokenUsageLoading
+              || state.isEventsLoading
+              || state.tokenUsageSummary
+              || state.tokenUsageEventsPage
+              || state.tokenUsageSummaryError
+              || state.tokenUsageEventsError
+          );
+
+          if (!hasContent) {
+            contentArea.innerHTML = renderWelcomeMessage();
+          } else if (state.error && !state.data) {
+            contentArea.innerHTML = `
+              ${renderError(state.error, "Usage request failed")}
+              ${renderTokenUsageSection()}
+            `;
           } else if (state.data) {
             contentArea.innerHTML = `
-                        ${renderUsageQuotas(state.data.quota_snapshots)}
-                        ${renderDetailedData(state.data)}
-                    `;
+              ${renderUsageQuotas(state.data.quota_snapshots)}
+              ${renderTokenUsageSection()}
+              ${renderDetailedData(state.data)}
+            `;
           } else {
-            contentArea.innerHTML = renderWelcomeMessage();
+            contentArea.innerHTML = renderTokenUsageSection();
           }
+
           // Replace placeholder icons with actual Lucide icons
           createIcons();
         }
@@ -301,7 +609,7 @@
           return `
                     <div class="p-4 border" style="background-color: var(--color-bg); border-color: var(--color-bg-light-2);">
                         <div class="flex justify-between items-center mb-2">
-                            <h3 class="text-md font-semibold capitalize" style="color: var(--color-fg-lightest);">${title.replace(/_/g, " ")}</h3>
+                            <h3 class="text-md font-semibold capitalize" style="color: var(--color-fg-lightest);">${escapeHtml(title.replace(/_/g, " "))}</h3>
                             ${
                               unlimited
                                 ? `<span class="px-2 py-0.5 text-xs font-medium" style="color: var(--color-blue-accent); background-color: var(--color-bg-light-1);">Unlimited</span>`
@@ -328,14 +636,14 @@
          */
         function formatObject(obj) {
           if (obj === null || typeof obj !== "object") {
-            return `<span style="color: var(--color-green-accent);">${JSON.stringify(obj)}</span>`;
+            return `<span style="color: var(--color-green-accent);">${escapeHtml(JSON.stringify(obj))}</span>`;
           }
 
           return (
             '<div class="pl-4">' +
             Object.entries(obj)
               .map(([key, value]) => {
-                const formattedKey = key.replace(/_/g, " ");
+                const formattedKey = escapeHtml(key.replace(/_/g, " "));
                 let displayValue;
 
                 if (Array.isArray(value)) {
@@ -346,9 +654,9 @@
                 } else if (typeof value === "object" && value !== null) {
                   displayValue = formatObject(value);
                 } else if (typeof value === "boolean") {
-                  displayValue = `<span class="font-semibold" style="color: ${value ? "var(--color-green-accent)" : "var(--color-red-accent)"}">${value}</span>`;
+                  displayValue = `<span class="font-semibold" style="color: ${value ? "var(--color-green-accent)" : "var(--color-red-accent)"}">${escapeHtml(String(value))}</span>`;
                 } else {
-                  displayValue = `<span style="color: var(--color-blue-accent);">${JSON.stringify(value)}</span>`;
+                  displayValue = `<span style="color: var(--color-blue-accent);">${escapeHtml(JSON.stringify(value))}</span>`;
                 }
 
                 return `<div class="mt-1">
@@ -371,15 +679,329 @@
           return `
                     <section id="detailed-data">
                         <h2 class="text-xl font-bold mb-3 flex items-center gap-2" style="color: var(--color-fg-lightest);">
-                           <i data-lucide="file-text"></i> Detailed Information
+                           <i data-lucide="file-text"></i> Usage API Response
                         </h2>
-                        <div class="border p-4 relative font-mono text-xs" style="background-color: var(--color-bg-darkest); border-color: var(--color-bg-light-2);">
+                        <div class="border p-4 relative font-mono text-xs code-block overflow-auto" style="background-color: var(--color-bg-darkest); border-color: var(--color-bg-light-2);">
                             ${formattedDetails}
                         </div>
                     </section>
                 `;
         }
 
+        function renderTokenUsageSection() {
+          const hasTokenUsageContent = Boolean(
+            state.isTokenUsageLoading
+              || state.isEventsLoading
+              || state.tokenUsageSummary
+              || state.tokenUsageEventsPage
+              || state.tokenUsageSummaryError
+              || state.tokenUsageEventsError
+          );
+
+          if (!hasTokenUsageContent) {
+            return "";
+          }
+
+          const summary = state.tokenUsageSummary;
+          const eventsPage = state.tokenUsageEventsPage;
+          const totals = summary?.totals || EMPTY_TOKEN_USAGE_TOTALS;
+          const activeRange = summary?.range || eventsPage?.range || null;
+          const totalPages = eventsPage ? Math.max(eventsPage.total_pages, 1) : 1;
+          const eventsMeta = eventsPage
+            ? `Page ${eventsPage.page} / ${totalPages} · ${formatNumber(
+                eventsPage.total
+              )} events`
+            : "No detail page loaded yet.";
+
+          return `
+            <section id="token-usage" class="mb-6">
+              <div class="mb-3 flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+                <div>
+                  <h2 class="text-xl font-bold flex items-center gap-2" style="color: var(--color-fg-lightest);">
+                    <i data-lucide="database"></i> Token Usage
+                  </h2>
+                  <p class="mt-1 text-xs" style="color: var(--color-gray);">${escapeHtml(
+                    renderTokenUsageRangeText(state.tokenUsagePeriod, activeRange)
+                  )}</p>
+                </div>
+                <div class="flex flex-wrap items-center gap-2 text-xs" style="color: var(--color-gray-accent);">
+                  ${
+                    state.isTokenUsageLoading
+                      ? "<span>Refreshing summary...</span>"
+                      : ""
+                  }
+                  ${
+                    state.isEventsLoading
+                      ? "<span>Refreshing details...</span>"
+                      : ""
+                  }
+                </div>
+              </div>
+
+              ${
+                state.tokenUsageSummaryError
+                  ? renderError(
+                      state.tokenUsageSummaryError,
+                      "Token usage summary failed"
+                    )
+                  : ""
+              }
+
+              <div class="grid grid-cols-2 lg:grid-cols-3 xl:grid-cols-6 gap-3 ${
+                state.isTokenUsageLoading ? "opacity-60" : ""
+              }">
+                ${renderTokenUsageMetric(
+                  "Total",
+                  totals.total_tokens,
+                  "var(--color-fg-lightest)"
+                )}
+                ${renderTokenUsageMetric(
+                  "Input",
+                  totals.input_tokens,
+                  "var(--color-blue-accent)"
+                )}
+                ${renderTokenUsageMetric(
+                  "Output",
+                  totals.output_tokens,
+                  "var(--color-green-accent)"
+                )}
+                ${renderTokenUsageMetric(
+                  "Cache Read",
+                  totals.cache_read_input_tokens,
+                  "var(--color-aqua-accent)"
+                )}
+                ${renderTokenUsageMetric(
+                  "Cache Write",
+                  totals.cache_creation_input_tokens,
+                  "var(--color-yellow-accent)"
+                )}
+                ${renderTokenUsageMetric(
+                  "Requests",
+                  totals.request_count,
+                  "var(--color-purple-accent)"
+                )}
+              </div>
+
+              <div class="mt-4 border" style="background-color: var(--color-bg); border-color: var(--color-bg-light-2);">
+                <div class="px-4 py-3 border-b flex items-center justify-between gap-3" style="background-color: var(--color-bg-soft); border-color: var(--color-bg-light-2);">
+                  <div>
+                    <p class="text-sm font-semibold" style="color: var(--color-fg-lightest);">By Model</p>
+                    <p class="mt-1 text-xs" style="color: var(--color-gray-accent);">${summary ? `${formatNumber(summary.byModel.length)} models` : "No summary rows loaded."}</p>
+                  </div>
+                </div>
+                ${renderTokenUsageModelBreakdown(summary)}
+              </div>
+
+              <div class="mt-4 border" style="background-color: var(--color-bg); border-color: var(--color-bg-light-2);">
+                <div class="px-4 py-3 border-b flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between" style="background-color: var(--color-bg-soft); border-color: var(--color-bg-light-2);">
+                  <div>
+                    <p class="text-sm font-semibold" style="color: var(--color-fg-lightest);">Event Details</p>
+                    <p class="mt-1 text-xs" style="color: var(--color-gray-accent);">${escapeHtml(
+                      eventsMeta
+                    )}</p>
+                  </div>
+                  <div class="flex items-center gap-2">
+                    ${renderPaginationButton(
+                      "previous",
+                      "Previous",
+                      !eventsPage || state.isEventsLoading || eventsPage.page <= 1
+                    )}
+                    ${renderPaginationButton(
+                      "next",
+                      "Next",
+                      !eventsPage
+                        || state.isEventsLoading
+                        || eventsPage.page >= totalPages
+                    )}
+                  </div>
+                </div>
+                ${
+                  state.tokenUsageEventsError
+                    ? `<div class="p-4">${renderError(
+                        state.tokenUsageEventsError,
+                        "Token usage details failed"
+                      )}</div>`
+                    : ""
+                }
+                ${renderTokenUsageEventsTable(eventsPage)}
+              </div>
+            </section>
+          `;
+        }
+
+        function renderTokenUsageMetric(label, value, accentColor) {
+          return `
+            <div class="p-4 border" style="background-color: var(--color-bg); border-color: var(--color-bg-light-2);">
+              <div class="text-lg font-bold" style="color: ${accentColor};">${formatNumber(
+                value
+              )}</div>
+              <div class="mt-1 text-xs uppercase tracking-wide" style="color: var(--color-gray-accent);">${escapeHtml(
+                label
+              )}</div>
+            </div>
+          `;
+        }
+
+        function renderTokenUsageModelBreakdown(summary) {
+          if (!summary || summary.byModel.length === 0) {
+            return renderEmptyState(
+              "No token usage recorded for the selected period."
+            );
+          }
+
+          const rows = summary.byModel
+            .map((model) => {
+              return `
+                <tr class="border-b last:border-b-0" style="border-color: var(--color-bg-light-1);">
+                  <td class="px-4 py-2 max-w-[280px] truncate" style="color: var(--color-fg-lightest);" title="${escapeHtml(
+                    model.model
+                  )}">${escapeHtml(model.model)}</td>
+                  <td class="px-4 py-2 text-right" style="color: var(--color-fg-dark);">${formatNumber(
+                    model.request_count
+                  )}</td>
+                  <td class="px-4 py-2 text-right" style="color: var(--color-fg-dark);">${formatNumber(
+                    model.input_tokens
+                  )}</td>
+                  <td class="px-4 py-2 text-right" style="color: var(--color-fg-dark);">${formatNumber(
+                    model.output_tokens
+                  )}</td>
+                  <td class="px-4 py-2 text-right" style="color: var(--color-fg-dark);">${formatNumber(
+                    model.cache_read_input_tokens
+                  )}</td>
+                  <td class="px-4 py-2 text-right" style="color: var(--color-fg-dark);">${formatNumber(
+                    model.cache_creation_input_tokens
+                  )}</td>
+                  <td class="px-4 py-2 text-right font-semibold" style="color: var(--color-yellow-accent);">${formatNumber(
+                    model.total_tokens
+                  )}</td>
+                </tr>
+              `;
+            })
+            .join("");
+
+          return `
+            <div class="overflow-auto ${state.isTokenUsageLoading ? "opacity-60" : ""}">
+              <table class="w-full min-w-[760px] text-left text-xs sm:text-sm">
+                <thead style="background-color: var(--color-bg-light-1); color: var(--color-fg-medium);">
+                  <tr>
+                    <th class="px-4 py-2 font-semibold">Model</th>
+                    <th class="px-4 py-2 text-right font-semibold">Requests</th>
+                    <th class="px-4 py-2 text-right font-semibold">Input</th>
+                    <th class="px-4 py-2 text-right font-semibold">Output</th>
+                    <th class="px-4 py-2 text-right font-semibold">Cache Read</th>
+                    <th class="px-4 py-2 text-right font-semibold">Cache Write</th>
+                    <th class="px-4 py-2 text-right font-semibold">Total</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  ${rows}
+                </tbody>
+              </table>
+            </div>
+          `;
+        }
+
+        function renderTokenUsageEventsTable(eventsPage) {
+          if (!eventsPage || eventsPage.items.length === 0) {
+            return renderEmptyState(
+              "No token usage detail rows for the selected period."
+            );
+          }
+
+          const rows = eventsPage.items
+            .map((event) => {
+              const userId = formatCellText(event.user_id);
+              const sessionId = formatCellText(event.session_id);
+              const traceId = formatCellText(event.trace_id);
+
+              return `
+                <tr class="border-b last:border-b-0" style="border-color: var(--color-bg-light-1);">
+                  <td class="px-4 py-2 whitespace-nowrap" style="color: var(--color-fg-dark);" title="${escapeHtml(
+                    event.created_at_utc
+                  )}">${escapeHtml(formatDateTime(event.created_at_ms))}</td>
+                  <td class="px-4 py-2 max-w-[160px] truncate" style="color: var(--color-fg-lightest);" title="${escapeHtml(
+                    userId
+                  )}">${escapeHtml(userId)}</td>
+                  <td class="px-4 py-2 whitespace-nowrap" style="color: var(--color-fg-dark);">${escapeHtml(
+                    event.endpoint.replace(/_/g, " ")
+                  )}</td>
+                  <td class="px-4 py-2 max-w-[220px] truncate" style="color: var(--color-fg-lightest);" title="${escapeHtml(
+                    event.model
+                  )}">${escapeHtml(event.model)}</td>
+                  <td class="px-4 py-2 max-w-[180px] truncate font-mono" style="color: var(--color-fg-dark);" title="${escapeHtml(
+                    sessionId
+                  )}">${escapeHtml(sessionId)}</td>
+                  <td class="px-4 py-2 max-w-[200px] truncate font-mono" style="color: var(--color-fg-dark);" title="${escapeHtml(
+                    traceId
+                  )}">${escapeHtml(traceId)}</td>
+                  <td class="px-4 py-2 text-right" style="color: var(--color-fg-dark);">${formatNumber(
+                    event.input_tokens
+                  )}</td>
+                  <td class="px-4 py-2 text-right" style="color: var(--color-fg-dark);">${formatNumber(
+                    event.output_tokens
+                  )}</td>
+                  <td class="px-4 py-2 text-right" style="color: var(--color-fg-dark);">${formatNumber(
+                    event.cache_read_input_tokens
+                  )}</td>
+                  <td class="px-4 py-2 text-right" style="color: var(--color-fg-dark);">${formatNumber(
+                    event.cache_creation_input_tokens
+                  )}</td>
+                  <td class="px-4 py-2 text-right font-semibold" style="color: var(--color-yellow-accent);">${formatNumber(
+                    event.total_tokens
+                  )}</td>
+                </tr>
+              `;
+            })
+            .join("");
+
+          return `
+            <div class="overflow-auto ${state.isEventsLoading ? "opacity-60" : ""}">
+              <table class="w-full min-w-[1180px] text-left text-xs sm:text-sm">
+                <thead style="background-color: var(--color-bg-light-1); color: var(--color-fg-medium);">
+                  <tr>
+                    <th class="px-4 py-2 font-semibold">Time</th>
+                    <th class="px-4 py-2 font-semibold">User</th>
+                    <th class="px-4 py-2 font-semibold">Endpoint</th>
+                    <th class="px-4 py-2 font-semibold">Model</th>
+                    <th class="px-4 py-2 font-semibold">Session</th>
+                    <th class="px-4 py-2 font-semibold">Trace</th>
+                    <th class="px-4 py-2 text-right font-semibold">Input</th>
+                    <th class="px-4 py-2 text-right font-semibold">Output</th>
+                    <th class="px-4 py-2 text-right font-semibold">Cache Read</th>
+                    <th class="px-4 py-2 text-right font-semibold">Cache Write</th>
+                    <th class="px-4 py-2 text-right font-semibold">Total</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  ${rows}
+                </tbody>
+              </table>
+            </div>
+          `;
+        }
+
+        function renderPaginationButton(action, label, disabled) {
+          return `
+            <button
+              type="button"
+              data-page-action="${action}"
+              class="px-3 py-1.5 border text-xs font-medium"
+              style="background-color: var(--color-bg-darkest); border-color: var(--color-bg-light-2); color: var(--color-fg-light);"
+              ${disabled ? "disabled" : ""}
+            >
+              ${label}
+            </button>
+          `;
+        }
+
+        function renderEmptyState(message) {
+          return `
+            <div class="px-4 py-6 text-sm" style="color: var(--color-gray);">
+              ${escapeHtml(message)}
+            </div>
+          `;
+        }
+
         /**
          * Renders a loading spinner.
          * @returns {string} HTML string for the spinner.
@@ -396,32 +1018,22 @@
          * @param {string} message - The error message to display.
          * @returns {string} HTML string for the error message.
          */
-        function renderError(message) {
-          const container = document.createElement("div");
-          container.className = "p-3 border";
-          container.style.backgroundColor = "rgba(204, 36, 29, 0.2)";
-          container.style.borderColor = "var(--color-red)";
-          container.style.color = "var(--color-red-accent)";
-          container.setAttribute("role", "alert");
-
-          container.innerHTML = `
-                <div class="flex items-center">
-                    <i data-lucide="alert-triangle" class="h-5 w-5 mr-3"></i>
-                    <div>
-                        <p class="font-bold text-sm">An Error Occurred</p>
-                        <p class="text-xs">${message}</p>
-                    </div>
+        function renderError(message, title = "An Error Occurred") {
+          return `
+            <div
+              class="p-3 border"
+              style="background-color: rgba(204, 36, 29, 0.2); border-color: var(--color-red); color: var(--color-red-accent);"
+              role="alert"
+            >
+              <div class="flex items-start">
+                <i data-lucide="alert-triangle" class="h-5 w-5 mr-3 mt-0.5"></i>
+                <div>
+                  <p class="font-bold text-sm">${escapeHtml(title)}</p>
+                  <p class="text-xs">${escapeHtml(message)}</p>
                 </div>
-            `;
-          // Must create icons *after* innerHTML is set
-          setTimeout(
-            () =>
-              lucide.createIcons({
-                nodes: [container.querySelector("[data-lucide]")],
-              }),
-            0
-          );
-          return container.outerHTML;
+              </div>
+            </div>
+          `;
         }
 
         /**
@@ -433,7 +1045,7 @@
             <div class="text-center py-16 px-4 border" style="background-color: var(--color-bg-soft); border-color: var(--color-bg-light-2);">
                 <i data-lucide="info" class="mx-auto h-10 w-10" style="color: var(--color-gray-accent);"></i>
                 <h3 class="mt-2 text-lg font-semibold" style="color: var(--color-fg-lightest);">Welcome!</h3>
-                <p class="mt-1 text-sm" style="color: var(--color-gray);">Enter an API endpoint URL and click "Fetch" to see usage data.</p>
+                <p class="mt-1 text-sm" style="color: var(--color-gray);">Enter a usage endpoint, optionally provide an x-api-key, and click "Fetch" to load usage and token usage data.</p>
             </div>
           `;
         }
@@ -441,40 +1053,184 @@
         // --- Data Fetching ---
 
         /**
-         * Fetches data from the specified API endpoint.
+         * Fetches usage data and token usage data from the specified API endpoint.
          */
-        async function fetchData() {
-          const url = endpointUrlInput.value.trim();
-          if (!url) {
+        async function fetchData(page = 1) {
+          const endpoint = endpointUrlInput.value.trim();
+          if (!endpoint) {
+            state.data = null;
+            state.tokenUsageSummary = null;
+            state.tokenUsageEventsPage = null;
             state.error = "Endpoint URL cannot be empty.";
-            state.isLoading = false;
+            state.tokenUsageSummaryError =
+              "Token usage requires a valid endpoint URL.";
+            state.tokenUsageEventsError = null;
             render();
             return;
           }
 
+          const period = getSelectedPeriod();
           state.isLoading = true;
           state.error = null;
+          state.tokenUsageSummaryError = null;
+          state.tokenUsageEventsError = null;
           render();
 
           try {
-            const response = await fetch(url);
-            if (!response.ok) {
-              throw new Error(
-                `Request failed with status ${response.status}: ${response.statusText}`
+            const usageUrl = resolveUsageUrl(endpoint);
+            const [usageResult, summaryResult, eventsResult] =
+              await Promise.allSettled([
+                fetchJson(usageUrl),
+                fetchJson(buildTokenUsageSummaryUrl(usageUrl, period)),
+                fetchJson(buildTokenUsageEventsUrl(usageUrl, period, page)),
+              ]);
+
+            if (usageResult.status === "fulfilled") {
+              state.data = usageResult.value;
+            } else {
+              state.data = null;
+              state.error = getErrorMessage(usageResult.reason);
+            }
+
+            if (summaryResult.status === "fulfilled") {
+              state.tokenUsageSummary = summaryResult.value;
+            } else if (
+              isMissingTokenUsageEndpointError(summaryResult.reason)
+            ) {
+              state.tokenUsageSummary = null;
+              state.tokenUsageSummaryError = null;
+            } else {
+              state.tokenUsageSummary = null;
+              state.tokenUsageSummaryError = getErrorMessage(
+                summaryResult.reason
+              );
+            }
+
+            if (eventsResult.status === "fulfilled") {
+              state.tokenUsageEventsPage = eventsResult.value;
+            } else if (
+              isMissingTokenUsageEndpointError(eventsResult.reason)
+            ) {
+              state.tokenUsageEventsPage = null;
+              state.tokenUsageEventsError = null;
+            } else {
+              state.tokenUsageEventsPage = null;
+              state.tokenUsageEventsError = getErrorMessage(
+                eventsResult.reason
               );
             }
-            const jsonData = await response.json();
-            state.data = jsonData;
           } catch (error) {
             console.error("Fetch error:", error);
             state.data = null;
-            state.error = error.message;
+            state.tokenUsageSummary = null;
+            state.tokenUsageEventsPage = null;
+            state.error = getErrorMessage(error);
+            state.tokenUsageSummaryError = getErrorMessage(error);
+            state.tokenUsageEventsError = getErrorMessage(error);
           } finally {
             state.isLoading = false;
             render();
           }
         }
 
+        async function fetchTokenUsageSummaryAndEvents(page = 1) {
+          const endpoint = endpointUrlInput.value.trim();
+          if (!endpoint) {
+            state.tokenUsageSummary = null;
+            state.tokenUsageEventsPage = null;
+            state.tokenUsageSummaryError =
+              "Token usage requires a valid endpoint URL.";
+            state.tokenUsageEventsError = null;
+            render();
+            return;
+          }
+
+          const period = getSelectedPeriod();
+          state.isTokenUsageLoading = true;
+          state.tokenUsageSummary = null;
+          state.tokenUsageEventsPage = null;
+          state.tokenUsageSummaryError = null;
+          state.tokenUsageEventsError = null;
+          render();
+
+          try {
+            const usageUrl = resolveUsageUrl(endpoint);
+            const [summaryResult, eventsResult] = await Promise.allSettled([
+              fetchJson(buildTokenUsageSummaryUrl(usageUrl, period)),
+              fetchJson(buildTokenUsageEventsUrl(usageUrl, period, page)),
+            ]);
+
+            if (summaryResult.status === "fulfilled") {
+              state.tokenUsageSummary = summaryResult.value;
+            } else if (
+              isMissingTokenUsageEndpointError(summaryResult.reason)
+            ) {
+              state.tokenUsageSummary = null;
+              state.tokenUsageSummaryError = null;
+            } else {
+              state.tokenUsageSummary = null;
+              state.tokenUsageSummaryError = getErrorMessage(
+                summaryResult.reason
+              );
+            }
+
+            if (eventsResult.status === "fulfilled") {
+              state.tokenUsageEventsPage = eventsResult.value;
+            } else if (
+              isMissingTokenUsageEndpointError(eventsResult.reason)
+            ) {
+              state.tokenUsageEventsPage = null;
+              state.tokenUsageEventsError = null;
+            } else {
+              state.tokenUsageEventsPage = null;
+              state.tokenUsageEventsError = getErrorMessage(
+                eventsResult.reason
+              );
+            }
+          } catch (error) {
+            console.error("Token usage fetch error:", error);
+            state.tokenUsageSummary = null;
+            state.tokenUsageEventsPage = null;
+            state.tokenUsageSummaryError = getErrorMessage(error);
+            state.tokenUsageEventsError = getErrorMessage(error);
+          } finally {
+            state.isTokenUsageLoading = false;
+            render();
+          }
+        }
+
+        async function fetchTokenUsageEventsPage(page) {
+          const endpoint = endpointUrlInput.value.trim();
+          if (!endpoint) {
+            state.tokenUsageEventsError =
+              "Token usage requires a valid endpoint URL.";
+            render();
+            return;
+          }
+
+          state.isEventsLoading = true;
+          state.tokenUsageEventsError = null;
+          render();
+
+          try {
+            const usageUrl = resolveUsageUrl(endpoint);
+            state.tokenUsageEventsPage = await fetchJson(
+              buildTokenUsageEventsUrl(usageUrl, getSelectedPeriod(), page)
+            );
+          } catch (error) {
+            if (isMissingTokenUsageEndpointError(error)) {
+              state.tokenUsageEventsPage = null;
+              state.tokenUsageEventsError = null;
+            } else {
+              console.error("Token usage events fetch error:", error);
+              state.tokenUsageEventsError = getErrorMessage(error);
+            }
+          } finally {
+            state.isEventsLoading = false;
+            render();
+          }
+        }
+
         // --- Event Handlers & Initialization ---
 
         /**
@@ -483,18 +1239,41 @@
          */
         function handleFormSubmit(event) {
           event.preventDefault();
-          const url = endpointUrlInput.value.trim();
+          storeApiKey(apiKeyInput.value);
+          syncUrlState();
+          void fetchData();
+        }
 
-          // Update URL query parameter, catching potential security errors in sandboxed environments
-          try {
-            const currentUrl = new URL(window.location);
-            currentUrl.searchParams.set("endpoint", url);
-            window.history.pushState({}, "", currentUrl);
-          } catch (e) {
-            console.warn("Could not update URL: ", e.message);
+        function handlePeriodChange() {
+          syncUrlState();
+          void fetchTokenUsageSummaryAndEvents(1);
+        }
+
+        function handleContentAreaClick(event) {
+          if (!(event.target instanceof Element)) {
+            return;
+          }
+
+          const actionButton = event.target.closest("[data-page-action]");
+          if (!actionButton || !state.tokenUsageEventsPage || state.isEventsLoading) {
+            return;
           }
 
-          fetchData();
+          const action = actionButton.getAttribute("data-page-action");
+          if (
+            action === "previous"
+            && state.tokenUsageEventsPage.page > 1
+          ) {
+            void fetchTokenUsageEventsPage(state.tokenUsageEventsPage.page - 1);
+          }
+
+          if (
+            action === "next"
+            && state.tokenUsageEventsPage.page
+              < state.tokenUsageEventsPage.total_pages
+          ) {
+            void fetchTokenUsageEventsPage(state.tokenUsageEventsPage.page + 1);
+          }
         }
 
         /**
@@ -502,17 +1281,27 @@
          */
         function init() {
           endpointForm.addEventListener("submit", handleFormSubmit);
+          tokenUsagePeriodSelect.addEventListener("change", handlePeriodChange);
+          apiKeyInput.addEventListener("input", () => {
+            storeApiKey(apiKeyInput.value);
+          });
+          contentArea.addEventListener("click", handleContentAreaClick);
+
+          apiKeyInput.value = loadStoredApiKey();
 
-          // Get endpoint from URL param on load
           const urlParams = new URLSearchParams(window.location.search);
+          const periodFromUrl = normalizePeriod(urlParams.get("period"));
           const endpointFromUrl = urlParams.get("endpoint");
 
+          state.tokenUsagePeriod = periodFromUrl;
+          tokenUsagePeriodSelect.value = periodFromUrl;
+
           if (endpointFromUrl) {
             endpointUrlInput.value = endpointFromUrl;
-            fetchData();
+            void fetchData();
           } else {
             endpointUrlInput.value = DEFAULT_ENDPOINT;
-            render(); // Render initial welcome message
+            render();
           }
         }