@cardinal4/opencode-tavily-quota 1.0.1 → 1.0.2

package/README.md

@@ -26,13 +26,17 @@ 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 +44,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 +60,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"
 {
@@ -122,19 +128,18 @@ therefore handled.
 ## 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 } 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.
@@ -118,6 +118,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 +126,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;
 }

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.0.2",
   "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": [