opencode-firmware-quota 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# opencode-firmware-quota
+
+OpenCode plugin for monitoring your [Firmware](https://firmware.ai) API quota usage.
+
+## Features
+
+- **`firmware_quota` tool** - AI can check your quota on demand
+- **`/usage` command** - Quick quota check via slash command
+- **Auto-show on session start** - See your quota when starting a new session
+- **Low quota warnings** - Get notified when usage exceeds 75% or 90%
+
+## Installation
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-firmware-quota"]
+}
+```
+
+## Prerequisites
+
+Connect your Firmware account using the `/connect` command in OpenCode:
+
+```
+/connect
+```
+
+Search for **Firmware** and enter your API key from [app.firmware.ai](https://app.firmware.ai).
+
+## Usage
+
+### Slash Command
+
+```
+/usage
+```
+
+Shows a toast notification with your current quota usage.
+
+### AI Tool
+
+Ask the AI to check your quota:
+
+```
+Check my Firmware quota
+```
+
+### Automatic Notifications
+
+- **Session start**: Quota is displayed when you start a new session
+- **Low quota (75%+)**: Warning notification shown
+- **Critical quota (90%+)**: Error notification shown
+
+## Configuration
+
+The plugin reads your Firmware API key from:
+
+1. `FIRMWARE_API_KEY` environment variable (if set)
+2. OpenCode auth storage (`~/.local/share/opencode/auth.json`)
+
+No additional configuration is required if you've connected Firmware via `/connect`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * OpenCode plugin for Firmware API quota monitoring
+ *
+ * Features:
+ * - firmware_quota tool: Check quota on demand
+ * - /usage command: Quick quota check via slash command
+ * - Auto-show quota on session start
+ * - Low quota warnings when usage exceeds thresholds
+ */
+export declare const FirmwareQuotaPlugin: Plugin;
+export default FirmwareQuotaPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAkGjD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAsHjC,CAAA;AAGD,eAAe,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,196 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+// Configuration
+const LOW_QUOTA_THRESHOLD = 75; // Show warning at 75%
+const CRITICAL_QUOTA_THRESHOLD = 90; // Show critical warning at 90%
+/**
+ * Get the Firmware API key from environment or OpenCode auth storage
+ */
+function getFirmwareApiKey() {
+    // Try environment variable first
+    if (process.env.FIRMWARE_API_KEY) {
+        return process.env.FIRMWARE_API_KEY;
+    }
+    // Fall back to OpenCode auth storage
+    const authPath = join(homedir(), ".local", "share", "opencode", "auth.json");
+    try {
+        const auth = JSON.parse(readFileSync(authPath, "utf-8"));
+        if (auth.firmware?.key) {
+            return auth.firmware.key;
+        }
+    }
+    catch {
+        // File doesn't exist or is invalid
+    }
+    return null;
+}
+/**
+ * Fetch quota information from Firmware API
+ */
+async function fetchQuota(apiKey) {
+    const response = await fetch("https://app.firmware.ai/api/v1/quota", {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!response.ok) {
+        throw new Error(`API returned ${response.status}`);
+    }
+    return response.json();
+}
+/**
+ * Parse quota response into usable info
+ */
+function parseQuotaInfo(data) {
+    const usedPercent = Math.round(data.used * 100);
+    let resetTime = null;
+    if (data.reset) {
+        const resetDate = new Date(data.reset);
+        resetTime = resetDate.toLocaleTimeString([], {
+            hour: "2-digit",
+            minute: "2-digit",
+            timeZoneName: "short",
+        });
+    }
+    return {
+        usedPercent,
+        resetTime,
+        isLow: usedPercent >= LOW_QUOTA_THRESHOLD,
+        isCritical: usedPercent >= CRITICAL_QUOTA_THRESHOLD,
+    };
+}
+/**
+ * Format quota info as a display message
+ */
+function formatQuotaMessage(info) {
+    const resetPart = info.resetTime ? `Resets at ${info.resetTime}` : "No active window";
+    if (info.isCritical) {
+        return `Firmware: ${info.usedPercent}% used (CRITICAL) | ${resetPart}`;
+    }
+    else if (info.isLow) {
+        return `Firmware: ${info.usedPercent}% used (LOW) | ${resetPart}`;
+    }
+    return `Firmware: ${info.usedPercent}% used | ${resetPart}`;
+}
+/**
+ * OpenCode plugin for Firmware API quota monitoring
+ *
+ * Features:
+ * - firmware_quota tool: Check quota on demand
+ * - /usage command: Quick quota check via slash command
+ * - Auto-show quota on session start
+ * - Low quota warnings when usage exceeds thresholds
+ */
+export const FirmwareQuotaPlugin = async ({ client }) => {
+    /**
+     * Core function to check and display quota
+     */
+    async function checkQuota(options = {}) {
+        const { showToast = true, silent = false } = options;
+        const apiKey = getFirmwareApiKey();
+        if (!apiKey) {
+            const errorMsg = "Firmware API key not found. Run /connect and add your Firmware credentials.";
+            if (showToast && !silent) {
+                await client.tui.showToast({
+                    body: { message: "Firmware not connected. Run /connect", variant: "error" },
+                });
+            }
+            return `Error: ${errorMsg}`;
+        }
+        try {
+            const data = await fetchQuota(apiKey);
+            const info = parseQuotaInfo(data);
+            const message = formatQuotaMessage(info);
+            if (showToast) {
+                const variant = info.isCritical ? "error" : info.isLow ? "warning" : "info";
+                await client.tui.showToast({
+                    body: { message, variant },
+                });
+            }
+            return message;
+        }
+        catch (err) {
+            const error = err;
+            const errorMsg = `Quota fetch failed: ${error.message}`;
+            if (showToast && !silent) {
+                await client.tui.showToast({
+                    body: { message: errorMsg, variant: "error" },
+                });
+            }
+            return `Error: ${errorMsg}`;
+        }
+    }
+    /**
+     * Check if Firmware is connected (has API key)
+     */
+    function isFirmwareConnected() {
+        return getFirmwareApiKey() !== null;
+    }
+    return {
+        // Tool: firmware_quota - Check quota on demand via AI tool call
+        tool: {
+            firmware_quota: {
+                description: "Check your Firmware API quota usage",
+                args: {},
+                async execute() {
+                    return checkQuota();
+                },
+            },
+        },
+        // Command: /usage - Quick quota check via slash command
+        command: {
+            usage: {
+                description: "Check your Firmware API quota usage",
+                async execute() {
+                    await checkQuota();
+                },
+            },
+        },
+        // Event handlers
+        event: async ({ event }) => {
+            // Auto-show quota on session start (only if Firmware is connected)
+            if (event.type === "session.created") {
+                if (isFirmwareConnected()) {
+                    // Small delay to let the UI settle
+                    setTimeout(async () => {
+                        await checkQuota({ showToast: true });
+                    }, 500);
+                }
+            }
+            // Low quota warning when session becomes idle (after AI response)
+            // This is a good time to check quota without being too intrusive
+            if (event.type === "session.idle") {
+                if (isFirmwareConnected()) {
+                    try {
+                        const apiKey = getFirmwareApiKey();
+                        if (apiKey) {
+                            const data = await fetchQuota(apiKey);
+                            const info = parseQuotaInfo(data);
+                            // Only show warning if quota is low/critical
+                            if (info.isCritical) {
+                                await client.tui.showToast({
+                                    body: {
+                                        message: `Warning: Firmware quota at ${info.usedPercent}%!`,
+                                        variant: "error",
+                                    },
+                                });
+                            }
+                            else if (info.isLow) {
+                                await client.tui.showToast({
+                                    body: {
+                                        message: `Notice: Firmware quota at ${info.usedPercent}%`,
+                                        variant: "warning",
+                                    },
+                                });
+                            }
+                        }
+                    }
+                    catch {
+                        // Silently ignore errors during background checks
+                    }
+                }
+            }
+        },
+    };
+};
+// Default export for convenience
+export default FirmwareQuotaPlugin;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "opencode-firmware-quota",
+  "version": "1.0.0",
+  "description": "OpenCode plugin for Firmware API quota monitoring - check usage, get warnings, and track your Firmware API consumption",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "firmware",
+    "firmware-ai",
+    "llm",
+    "quota",
+    "usage"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-username/opencode-firmware-quota"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.0.0",
+    "@types/node": "^25.0.10",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.0.0"
+  }
+}