@cardinal4/opencode-tavily-quota 1.0.2 → 1.1.0

package/README.md

@@ -5,6 +5,7 @@ session sidebar.
 
 ```
 Tavily
+resets in 6d 12h
 █████████████████████████   84% left
 ```
 
@@ -20,8 +21,10 @@ Or declare it in `cli.json` to pass the API key option (see
 the package so the plugin is not loaded twice.
 
 The sidebar follows the built-in quota styling — the heading uses the default
-text color and the body (bar included) uses the muted/subdued text color. It
-polls every 10 minutes and can be refreshed on demand with the command below.
+text color and the body (bar included) uses the muted/subdued text color. A
+countdown between the heading and the bar shows how long until the monthly
+credits reset. It polls every 10 minutes and can be refreshed on demand with the
+command below.
 
 ## Requirements
 
@@ -114,7 +117,7 @@ reported in the sidebar instead of being used as the key.
 ## Commands
 
 - `/tavily-quota` — slash command that re-fetches and reports the current quota
-  in a toast.
+  and reset countdown in a toast.
 - "Refresh Tavily quota" — the same action from the command palette (`Ctrl+P`).
 
 ## Data source
@@ -125,6 +128,11 @@ e.g. `Researcher` with 1000 monthly credits) and falls back to the per-key limit
 when the plan limit is absent. A `null` per-key limit (unlimited key) is
 therefore handled.
 
+The response has no reset timestamp, so the sidebar countdown is derived from
+the calendar: Tavily resets credits on the first day of each month (not the
+billing date), and the plugin assumes `00:00 UTC` for that reset. If Tavily
+later exposes an explicit reset time, prefer it over this derivation.
+
 ## Development
 
 `usage.ts` is deliberately free of OpenCode and OpenTUI imports so it can be

package/dist/tui.js

@@ -25,7 +25,7 @@ import { createElement as _$createElement } from "@opentui/solid";
 
 import { Plugin } from "@opencode/plugin/tui";
 import { createSignal } from "solid-js";
-import { fetchQuotaWithFallback, formatPercent, formatQuotaLine, formatRemaining } from "./usage.js";
+import { fetchQuotaWithFallback, formatPercent, formatQuotaLine, formatRemaining, formatResetLine } from "./usage.js";
 import { TavilyQuotaRpc } from "./rpc.js";
 export const PLUGIN_ID = "opencode-tavily-quota";
 // Tavily's `/usage` endpoint allows at most 10 requests per 10 minutes, so poll
@@ -43,7 +43,7 @@ function readThemeColors(context) {
     textMuted: text.subdued ?? text.muted
   };
 }
-export function buildLines(state) {
+export function buildLines(state, now = Date.now()) {
   if (state.status === "loading") {
     return ["loading…"];
   }
@@ -51,7 +51,9 @@ export function buildLines(state) {
     return [`⚠ ${state.message}`];
   }
   const snapshot = state.snapshot;
-  return [formatQuotaLine(snapshot)];
+  // Reset countdown sits between the heading and the bar, matching the sidebar
+  // order used by the built-in quota section.
+  return [formatResetLine(now), formatQuotaLine(snapshot)];
 }
 function TavilyQuotaSidebar(props) {
   const colors = () => readThemeColors(props.context);
@@ -100,7 +102,7 @@ function TavilyQuotaCommands(props) {
       },
       run: async () => {
         const next = await props.refresh();
-        const message = next.status === "ready" ? `${formatRemaining(next.snapshot)} · ${formatPercent(next.snapshot.percentRemaining)}` : next.status === "error" ? next.message : "still loading…";
+        const message = next.status === "ready" ? `${formatRemaining(next.snapshot)} · ${formatPercent(next.snapshot.percentRemaining)} · ${formatResetLine()}` : next.status === "error" ? next.message : "still loading…";
         props.context.ui.toast.show({
           title: "Tavily quota",
           message,

package/dist/usage.js

@@ -185,6 +185,44 @@ export function formatQuotaLine(snapshot, width = DEFAULT_BAR_WIDTH) {
 export function formatRemaining(snapshot) {
   return `${snapshot.remaining} credits left`;
 }
+const MS_PER_MINUTE = 60_000;
+const MS_PER_HOUR = 3_600_000;
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * When the credit quota next resets, as epoch milliseconds.
+ *
+ * Tavily resets credits on the first day of each month (calendar-based, not the
+ * billing date) and `/usage` does not report when. Derive it as `00:00 UTC` on
+ * the 1st of the following month. Tavily does not document a reset timezone;
+ * UTC is assumed (see the README).
+ */
+export function nextMonthlyResetAt(now = Date.now()) {
+  const date = new Date(now);
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 1, 0, 0, 0, 0);
+}
+
+/**
+ * Countdown to `resetAt`, e.g. `12d 4h`, `5h 12m`, or `45m`.
+ *
+ * Days and hours are floored so the value never overstates the time left; a
+ * sub-minute remainder rounds up to `1m`, and a past reset reads `0m`.
+ */
+export function formatResetCountdown(resetAt, now = Date.now()) {
+  const diff = resetAt - now;
+  if (!Number.isFinite(diff) || diff <= 0) return "0m";
+  const days = Math.floor(diff / MS_PER_DAY);
+  const hours = Math.floor(diff % MS_PER_DAY / MS_PER_HOUR);
+  const minutes = Math.floor(diff % MS_PER_HOUR / MS_PER_MINUTE);
+  if (days > 0) return `${days}d ${hours}h`;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  return `${Math.max(1, minutes)}m`;
+}
+
+/** Sidebar line for the next reset, e.g. `resets in 12d 4h`. */
+export function formatResetLine(now = Date.now()) {
+  return `resets in ${formatResetCountdown(nextMonthlyResetAt(now), now)}`;
+}
 
 /**
  * Fetch and derive the current Tavily quota.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@cardinal4/opencode-tavily-quota",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "OpenCode 2 TUI plugin that shows remaining Tavily API credits in the sidebar.",
   "type": "module",
   "license": "MIT",