@vymalo/opencode-models-info 0.1.0 → 0.4.0

package/README.md

@@ -24,30 +24,32 @@ Add it to your `opencode.json` plugin list:
 
 ## Usage
 
-For every provider you want enriched, add `options.meta.modelsInfoUrl`:
+`meta.modelsInfoUrl` is **the HTTP(S) endpoint that returns the metadata JSON** — an absolute URL or a path resolved against `options.baseURL`. Point it at your own provider's metadata endpoint:
 
 ```json
 {
   "plugin": ["@vymalo/opencode-models-info"],
   "provider": {
-    "my-gateway": {
+    "my-provider": {
       "npm": "@ai-sdk/openai-compatible",
       "options": {
-        "baseURL": "https://gateway.example.com/v1",
+        "baseURL": "https://api.example.com/v1",
         "meta": {
-          "modelsInfoUrl": "models/info",
+          "modelsInfoUrl": "https://api.example.com/v1/models",
           "modelsInfoTtlSeconds": 86400,
           "modelsInfoTimeoutMs": 5000
         }
       },
-      "models": {
-        "gpt-x-large": {}
-      }
+      "models": { "my-model-large": {} }
     }
   }
 }
 ```
 
+An absolute URL is clearest. A relative path is also accepted — it resolves against `baseURL` (e.g. `"models"` → `https://api.example.com/v1/models`); see [URL resolution](#url-resolution).
+
+> **What shape must that endpoint return?** The JSON described in [Expected response shape](#expected-response-shape-openrouter) below — commonly called the **OpenRouter shape** because OpenRouter's `/models` endpoint returns it, but the plugin has no dependency on OpenRouter and never contacts it. The compatibility bar is low: a **bare top-level array** (no `data` wrapper) is accepted, and the mapping is **partial**, so your endpoint only needs to emit the fields you want enriched (e.g. just `id` + `context_length` + `pricing`). **But note:** a vanilla OpenAI-compatible `/v1/models` returns only `id` / `object` / `owned_by` — *none* of the fields this plugin maps — so pointing `modelsInfoUrl` there fetches successfully and enriches nothing. The endpoint has to actually carry the richer data.
+
 That's it. After OpenCode starts:
 
 1. The hook picks up every provider with a `meta.modelsInfoUrl`.
@@ -87,6 +89,32 @@ The plugin sends the union of `options.headers` and `meta.modelsInfoHeaders` (me
 
 If you need a different token for the metadata endpoint than for inference (e.g. a service-account bearer), set it explicitly under `meta.modelsInfoHeaders.Authorization` — it'll override whatever the provider has set.
 
+#### Example: with `@vymalo/opencode-oauth2`
+
+List the oauth2 plugin **first** so its `config` hook runs before this one — that's what puts the bearer on `options.headers` in time for the metadata fetch:
+
+```jsonc
+{
+  "plugin": ["@vymalo/opencode-oauth2", "@vymalo/opencode-models-info"],
+  "provider": {
+    "my-provider": {
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "baseURL": "https://api.example.com/v1",
+        "oauth2": {
+          "issuer": "https://auth.example.com",
+          "clientId": "opencode-client",
+          "scopes": ["openid", "profile", "offline_access"]
+        },
+        "meta": { "modelsInfoUrl": "https://api.example.com/v1/models" }
+      }
+    }
+  }
+}
+```
+
+oauth2 authenticates the provider and discovers its models; this plugin then fetches `modelsInfoUrl` using the token oauth2 stamped onto the provider headers, and enriches those discovered models. No `models` block and no `Authorization` header to manage — both are handled for you.
+
 ### Expected response shape (OpenRouter)
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vymalo/opencode-models-info",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "OpenCode plugin that enriches model entries with full metadata (context length, pricing, modalities, capability flags) fetched from a provider-supplied OpenRouter-shaped endpoint.",
   "license": "MIT",
   "author": "vymalo contributors",