@cardinal4/opencode-tavily-quota 1.0.1 → 1.1.0

package/README.md

@@ -5,6 +5,7 @@ session sidebar.
 
 ```
 Tavily
+resets in 6d 12h
 █████████████████████████   84% left
 ```
 
@@ -20,19 +21,25 @@ 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
 
 - OpenCode 2 (`opencode --version` reports `2.x`).
-- A Tavily API key, supplied one of two ways:
-  - `TAVILY_API_KEY` in the environment OpenCode is started from, or
-  - the `apiKey` plugin option configured on this plugin in `cli.json`.
-
-`TAVILY_API_KEY` takes precedence when both are set. The key is read in the CLI
-process and sent only to `api.tavily.com` as a `Bearer` token. It is never
-displayed.
+- A Tavily API key, supplied by:
+  - `TAVILY_API_KEY` in the CLI environment,
+  - the `apiKey` plugin option configured in `cli.json`, or
+  - OpenCode's active Tavily connection (use `opencode auth login tavily` or
+    `/connect` to connect Tavily).
+
+The CLI environment takes precedence over `apiKey`; OpenCode's active
+connection is used when neither supplies a key. The server resolves its saved
+credential and fetches `/usage` itself. Only quota data returns to the TUI;
+the saved key is never sent over plugin RPC or displayed. With a remote server,
+install this plugin there too to use its active connection.
 
 The `apiKey` option also accepts `{file:...}` and `{env:...}` references, which
 the plugin expands itself because `cli.json` does not (unlike `opencode.jsonc`).
@@ -40,12 +47,13 @@ the plugin expands itself because `cli.json` does not (unlike `opencode.jsonc`).
 ## Layout
 
 ```
-index.ts         # server entrypoint (no-op; required for discovery)
+index.ts         # server entrypoint: integration credential + quota RPC
+rpc.ts           # shared RPC definition
 tui.tsx          # TUI entrypoint: sidebar slot + command
 usage.ts         # key resolution, /usage fetch, formatting
 usage.test.ts    # unit tests for usage.ts
 scripts/build.mjs
-dist/            # built entrypoints shipped to npm (dist/index.js, dist/tui.js)
+dist/            # built entrypoints shipped to npm
 ```
 
 `npm run build` compiles the TypeScript/JSX sources into `dist/`, which is what
@@ -55,12 +63,13 @@ Solid JSX runtime (`@opentui/solid`) is only provided at runtime, not from the
 installed plugin.
 
 OpenCode installs package plugins under `~/.cache/opencode/npm/`. The server
-entrypoint (`dist/index.js`) satisfies discovery; the `tui` entrypoint
-(`dist/tui.js`) is loaded by the CLI to render the sidebar.
+entrypoint (`dist/index.js`) registers the quota RPC; the `tui` entrypoint
+(`dist/tui.js`) renders the sidebar in the CLI.
 
 ## Configuration
 
-Register the plugin in `cli.json` to pass the API key as a plugin option:
+If you already connected Tavily in OpenCode, no key option is needed. To pass
+the API key as a plugin option instead, register the plugin in `cli.json`:
 
 ```json title="cli.json"
 {
@@ -108,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
@@ -119,22 +128,26 @@ 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
-tested anywhere. `usage.test.ts` covers the pure quota math (`deriveSnapshot`,
-`formatPercent`, `formatRemaining`), key resolution, and every `fetchQuota`
-error branch using an injected `fetch`.
+tested anywhere. The tests cover quota math, local-key precedence and fallback,
+the connected-key RPC, and HTTP error handling using a mock `fetch`.
 
 Run the tests and type check from the repository root:
 
 ```sh
 npm install
-npm test        # tsx --test usage.test.ts
+npm test
 npm run typecheck
 ```
 
 ## Notes
 
-- The plugin is a no-op on the server. All work happens in the CLI runtime,
-  which is where TUI slots live.
+- The server handles OpenCode-connected credentials and their quota requests;
+  the CLI handles local keys and renders TUI slots.

package/dist/index.js

@@ -1,21 +1,31 @@
 /**
- * Server entrypoint for the Tavily quota sidebar plugin.
- *
- * OpenCode discovers a local plugin directory by its `index` (server) entry and
- * loads the `tui` entry beside it for the terminal UI. All rendering happens in
- * the CLI runtime (`tui.tsx`); this file only exists so the directory is a
- * complete plugin and shows up by id instead of as an anonymous entry.
- *
- * It deliberately imports nothing beyond `@opencode/plugin` so the background
- * service can load it in any runtime.
+ * Server entrypoint. Resolve the active Tavily integration credential and
+ * fetch quota here; only the quota result crosses the RPC boundary to the TUI.
  */
 
 import { Plugin } from "@opencode/plugin";
+import { TavilyQuotaRpc } from "./rpc.js";
+import { fetchQuota } from "./usage.js";
 export const PLUGIN_ID = "opencode-tavily-quota";
 export default Plugin.define({
   id: PLUGIN_ID,
-  setup() {
-    // Intentional no-op: the sidebar and command are registered by the TUI
-    // entrypoint (tui.tsx), which runs in the CLI process.
+  async setup(ctx) {
+    await ctx.rpc.register(TavilyQuotaRpc, {
+      usage: async () => {
+        const connection = await ctx.integration.connection.active("tavily");
+        const credential = connection && (await ctx.integration.connection.resolve(connection));
+        const key = credential?.type === "key" ? credential.key : connection?.type === "env" ? process.env[connection.name] : undefined;
+        if (!key) {
+          return {
+            ok: false,
+            message: "no active Tavily connection (run opencode auth login tavily)"
+          };
+        }
+        return fetchQuota({
+          apiKey: key,
+          env: {}
+        });
+      }
+    });
   }
 });

package/dist/rpc.js

@@ -0,0 +1,54 @@
+import { Rpc } from "@opencode/plugin/rpc";
+
+/** The server fetches quota so the saved OpenCode credential never enters the TUI. */
+export const TavilyQuotaRpc = Rpc.define({
+  id: "opencode-tavily-quota",
+  methods: {
+    usage: {
+      input: {
+        type: "object",
+        properties: {},
+        additionalProperties: false
+      },
+      output: {
+        type: "object",
+        properties: {
+          ok: {
+            type: "boolean"
+          },
+          message: {
+            type: "string"
+          },
+          snapshot: {
+            type: "object",
+            properties: {
+              planName: {
+                type: "string"
+              },
+              used: {
+                type: "number"
+              },
+              limit: {
+                type: "number"
+              },
+              remaining: {
+                type: "number"
+              },
+              percentRemaining: {
+                type: "number"
+              },
+              updatedAt: {
+                type: "number"
+              }
+            },
+            required: ["planName", "used", "limit", "remaining", "percentRemaining", "updatedAt"],
+            additionalProperties: false
+          }
+        },
+        required: ["ok"],
+        additionalProperties: false
+      }
+    }
+  },
+  events: {}
+});

package/dist/tui.js

@@ -19,14 +19,14 @@ import { createElement as _$createElement } from "@opentui/solid";
  * Colors follow the built-in quota sections: the heading uses the default text
  * color and the body (bar included) uses the muted/subdued text color.
  *
- * Authenticate with `TAVILY_API_KEY`, or with the `apiKey` plugin option
- * configured on this plugin in `cli.json`. Resolution and the network call
- * live in `./usage.ts`.
+ * Authenticate with `TAVILY_API_KEY`, the `apiKey` plugin option in `cli.json`,
+ * or OpenCode's active Tavily integration. A saved key is used server-side.
  */
 
 import { Plugin } from "@opencode/plugin/tui";
 import { createSignal } from "solid-js";
-import { fetchQuota, 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
 // once per window and rely on the `/tavily-quota` command for on-demand reads.
@@ -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,
@@ -118,6 +120,7 @@ export const TavilyQuotaTuiPlugin = Plugin.define({
       status: "loading"
     });
     const apiKey = typeof context.options.apiKey === "string" ? context.options.apiKey : undefined;
+    const remote = context.client.rpc(TavilyQuotaRpc);
     const refreshMs = typeof context.options.refreshMs === "number" && context.options.refreshMs > 0 ? context.options.refreshMs : REFRESH_INTERVAL_MS;
     let disposed = false;
     let inFlight = false;
@@ -125,8 +128,11 @@ export const TavilyQuotaTuiPlugin = Plugin.define({
       if (inFlight) return state();
       inFlight = true;
       try {
-        const result = await fetchQuota({
-          apiKey
+        const result = await fetchQuotaWithFallback({
+          apiKey,
+          remote: () => remote.usage({}, {
+            location: context.location ?? context.data.location.default()
+          })
         });
         if (!disposed) {
           setState(result.ok ? {

package/dist/usage.js

@@ -36,6 +36,29 @@ export const DEFAULT_BAR_WIDTH = SIDEBAR_WIDTH - BAR_SEPARATOR.length - PERCENT_
 
 /** Shape of `GET https://api.tavily.com/usage` (all fields optional). */
 
+/** Prefer CLI credentials; ask the server only when the CLI has no key. */
+export async function fetchQuotaWithFallback(options) {
+  try {
+    const key = resolveApiKey(options.env, options.apiKey, options);
+    if (key) return fetchQuota({
+      ...options,
+      apiKey: key,
+      env: {}
+    });
+  } catch {
+    // Preserve the existing inline error for an unreadable {file:...} option.
+    return fetchQuota(options);
+  }
+  try {
+    return await options.remote();
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      message: `OpenCode Tavily credential unavailable: ${reason}`
+    };
+  }
+}
 function finite(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
@@ -162,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.1",
+  "version": "1.1.0",
   "description": "OpenCode 2 TUI plugin that shows remaining Tavily API credits in the sidebar.",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,7 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "prepublishOnly": "npm run build",
-    "test": "tsx --test usage.test.ts",
+    "test": "tsx --test usage.test.ts index.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "keywords": [