opencode-glm-quota 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,240 @@
+# opencode-glm-quota
+
+[![npm version](https://badge.fury.io/js/opencode-glm-quota.svg)](https://www.npmjs.com/package/opencode-glm-quota)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://github.com/guyinwonder168/opencode-glm-quota/workflows/Build%20&%20Test/badge.svg)](https://github.com/guyinwonder168/opencode-glm-quota/actions)
+
+OpenCode plugin to query Z.ai GLM Coding Plan usage statistics with real-time quota monitoring, model usage tracking, and MCP tool usage.
+
+## Features
+
+- 📊 Query current quota limits (5-hour token cycle, monthly MCP usage)
+- 🤖 View model usage statistics (24-hour rolling window)
+- 🔧 View MCP tool usage (web_search, web_reader, etc.)
+- 🌍 Supports both Global (api.z.ai) and CN (open.bigmodel.cn) platforms
+- 🔐 Automatic credential discovery from OpenCode auth.json
+- 📈 Visual progress bars for quota percentages
+- ⚡ Fail-fast error handling (no retry logic - user controls when to retry)
+
+## Installation
+
+### Option 1: npm (Recommended)
+
+```bash
+npm install opencode-glm-quota
+```
+
+Then add to your OpenCode config (`~/.config/opencode/config.json`):
+
+```json
+{
+  "plugins": ["opencode-glm-quota"]
+}
+```
+
+### Option 2: From GitHub
+
+```bash
+npm install github:guyinwonder168/opencode-glm-quota
+```
+
+### Option 3: Manual Installation
+
+1. Download the latest release from GitHub
+2. Copy `dist/index.js` to `~/.config/opencode/plugin/glm-quota.js`
+
+## Quick Start
+
+Once installed, simply run the plugin command in OpenCode:
+
+```bash
+/glm_quota
+```
+
+The plugin will automatically detect your credentials (from OpenCode authentication) and display your usage statistics.
+
+## Usage
+
+### Authentication Setup
+
+This plugin uses OpenCode's built-in authentication system. No manual configuration required.
+
+**Primary Method (Recommended):**
+
+```bash
+# In OpenCode TUI
+/connect
+# Select: Z.AI Coding Plan or Z.AI
+# Enter your API key
+```
+
+**Fallback (Development/Testing Only):**
+
+```bash
+# For Global platform (api.z.ai)
+export ZAI_API_KEY="your-api-key"
+
+# For CN platform (open.bigmodel.cn)
+export ZHIPU_API_KEY="your-api-key"
+```
+
+### Running the Plugin
+
+After authentication, simply run:
+
+```bash
+/glm_quota
+```
+
+### Output Example
+
+```
+╔════════════════════════════════════════════════════════════╗
+║           Z.ai GLM Coding Plan Usage Statistics            ║
+╠════════════════════════════════════════════════════════════╣
+║  Platform: ZAI                                             ║
+║  Period: 2026-01-12 14:00:00 → 2026-01-13 14:59:59         ║
+╠════════════════════════════════════════════════════════════╣
+║  📊 QUOTA LIMITS                                           ║
+╟────────────────────────────────────────────────────────────╢
+║  Token usage(5 Hour)   [████████████░░░░░░░░░░░░░░░░░░]  40.5% ║
+║  MCP usage(1 Month)    [████░░░░░░░░░░░░░░░░░░░░░░░░░░]  12.3% ║
+║       Used: 123/1000                                       ║
+╠════════════════════════════════════════════════════════════╣
+║  🤖 MODEL USAGE (24h)                                      ║
+╟────────────────────────────────────────────────────────────╢
+║  {                                                         ║
+║    "requests": 45,                                         ║
+║    "tokens": 125000                                        ║
+║  }                                                         ║
+╠════════════════════════════════════════════════════════════╣
+║  🔧 TOOL/MCP USAGE (24h)                                   ║
+╟────────────────────────────────────────────────────────────╢
+║  {                                                         ║
+║    "web_search": 15,                                       ║
+║    "web_reader": 8                                         ║
+║  }                                                         ║
+╚════════════════════════════════════════════════════════════╝
+```
+
+### Error Handling
+
+The plugin uses fail-fast error handling. If any API request fails, it will display the error and stop (no automatic retries). This gives you full control over when to retry.
+
+**Example Error Output:**
+
+```
+╔════════════════════════════════════════════════════════════╗
+║  ❌ Authentication Error                                    ║
+╠════════════════════════════════════════════════════════════╣
+║  Not authenticated with Z.AI. Please run `/connect`       ║
+║  command in OpenCode TUI and select "Z.AI Coding Plan".    ║
+╚════════════════════════════════════════════════════════════╝
+```
+
+## API Reference
+
+This plugin queries three Z.ai monitoring endpoints:
+
+| Endpoint | Purpose | Query Params |
+|----------|---------|--------------|
+| `/api/monitor/usage/quota/limit` | Current quota percentages | None |
+| `/api/monitor/usage/model-usage` | Model usage (24h window) | `startTime`, `endTime` |
+| `/api/monitor/usage/tool-usage` | MCP tool usage (24h window) | `startTime`, `endTime` |
+
+### Platform Detection
+
+The plugin automatically detects the platform based on the provider ID used during authentication:
+
+| Provider ID | Platform | API Base URL |
+|-------------|----------|---------------|
+| `zai-coding-plan` | ZAI | `https://api.z.ai` |
+| `zai` | ZAI | `https://api.z.ai` |
+| `zhipu` | ZHIPU | `https://open.bigmodel.cn` |
+
+### Credential Priority
+
+The plugin discovers credentials in this order:
+
+1. **OpenCode auth.json** (`~/.local/share/opencode/auth.json`) - PRIMARY
+2. **Environment variable** `ZAI_API_KEY` (Global) or `ZHIPU_API_KEY` (CN) - FALLBACK (dev/testing only)
+
+### Time Window
+
+Usage statistics are queried for a 24-hour rolling window:
+- **Start**: Yesterday at current hour (e.g., 14:00:00)
+- **End**: Today at current hour end (e.g., 14:59:59)
+
+### Authentication
+
+**Critical**: The plugin does NOT use "Bearer" prefix in the Authorization header. The token is passed directly:
+
+```http
+Authorization: {token}
+Accept-Language: en-US,en
+Content-Type: application/json
+```
+
+## Development
+
+### Build Commands
+
+```bash
+# Build TypeScript to JavaScript
+npm run build
+
+# Clean build artifacts
+npm run clean
+
+# Run all tests
+npm run test
+
+# Run specific test file
+npm run test -- path/to/test.test.ts
+
+# Watch mode during development
+npm run test -- --watch
+
+# Lint source code
+npm run lint
+
+# Prepare for npm publish
+npm run prepublishOnly
+```
+
+### Project Structure
+
+```
+src/
+  index.ts           # Main plugin entry point
+dist/               # Compiled JavaScript (generated)
+package.json         # Dependencies and scripts
+tsconfig.json        # TypeScript configuration
+```
+
+### Code Style Guidelines
+
+- Target: ES2022
+- Module: NodeNext
+- Strict mode enabled
+- Always use type annotations for function returns
+- Use `as const` for immutable constants
+
+For detailed coding conventions, see [AGENTS.md](AGENTS.md).
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT © 2026
+
+## Acknowledgments
+
+- API specification verified from [zai-org/zai-coding-plugins](https://github.com/zai-org/zai-coding-plugins)
+- Built for [OpenCode](https://opencode.ai)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and detailed changes.

package/dist/index.js

@@ -0,0 +1,95 @@
+/**
+ * OpenCode GLM Quota Plugin
+ *
+ * Query Z.ai GLM Coding Plan usage statistics including quota limits,
+ * model usage, and MCP tool usage.
+ */
+import { tool } from "@opencode-ai/plugin/tool";
+/**
+ * Provider ID to platform mapping
+ */
+const PLATFORM_MAP = {
+    'zai-coding-plan': 'ZAI',
+    'zai': 'ZAI',
+    'zhipu': 'ZHIPU',
+    'zhipuai': 'ZHIPU'
+};
+/**
+ * Get provider platform from provider ID
+ * @param providerId - The provider ID from OpenCode authentication
+ * @returns Platform type or null if unknown
+ */
+export function getProviderPlatform(providerId) {
+    return PLATFORM_MAP[providerId] || null;
+}
+/**
+ * Create error message for missing credentials
+ * @returns Error message with setup instructions
+ */
+export function createCredentialError() {
+    return `No credentials found. Please authenticate by running /connect command in OpenCode.
+
+Supported providers:
+- Z.AI Coding Plan (recommended)
+- Z.AI
+- Zhipu
+
+For development/testing, you can also set environment variables for appropriate platform.`;
+}
+/**
+ * Get credentials from OpenCode auth context or environment variables
+ * @param authContext - Optional auth context from OpenCode plugin system
+ * @returns Credentials object or null if no credentials found
+ */
+export async function getCredentials(authContext) {
+    // Priority 1: OpenCode auth context
+    if (authContext && authContext.providerId && authContext.token) {
+        const platform = getProviderPlatform(authContext.providerId);
+        if (platform) {
+            return {
+                token: authContext.token,
+                platform
+            };
+        }
+    }
+    // Priority 2: Environment variables (fallback for development/testing)
+    if (process.env.ZAI_API_KEY) {
+        return {
+            token: process.env.ZAI_API_KEY,
+            platform: 'ZAI'
+        };
+    }
+    if (process.env.ZHIPU_API_KEY || process.env.ZHIPUAI_API_KEY) {
+        return {
+            token: (process.env.ZHIPU_API_KEY || process.env.ZHIPUAI_API_KEY),
+            platform: 'ZHIPU'
+        };
+    }
+    // No credentials found
+    return null;
+}
+/**
+ * Main GLM Quota Plugin
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export const GlmQuotaPlugin = async (_ctx) => {
+    return {
+        tool: {
+            glm_quota: tool({
+                description: 'Query Z.ai GLM Coding Plan usage statistics including quota limits, model usage, and MCP tool usage',
+                args: {},
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                async execute(_args, _context) {
+                    // TODO: Implement full feature in subsequent slices
+                    // For now, verify credential discovery works
+                    const credentials = await getCredentials();
+                    if (!credentials) {
+                        return createCredentialError();
+                    }
+                    return `✅ Credentials found for ${credentials.platform} platform\n\nFeature coming soon: quota limits, model usage, and MCP tool usage statistics.`;
+                }
+            })
+        }
+    };
+};
+export default GlmQuotaPlugin;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "opencode-glm-quota",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "OpenCode plugin to query Z.ai GLM Coding Plan usage statistics including quota limits, model usage, and MCP tool usage",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "node --test",
+    "lint": "eslint src/"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "zai",
+    "z.ai",
+    "zhipu",
+    "glm",
+    "quota",
+    "usage",
+    "coding-plan",
+    "ai",
+    "llm"
+  ],
+  "author": "guyinwonder168 <guyinwonder168@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guyinwonder168/opencode-glm-quota.git"
+  },
+  "bugs": {
+    "url": "https://github.com/guyinwonder168/opencode-glm-quota/issues"
+  },
+  "homepage": "https://github.com/guyinwonder168/opencode-glm-quota#readme",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "eslint": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0"
+  }
+}