openvibers/openvibe.sdk Commits

Add Exchange keys, private usage, deployments and search SDK (#152)

OP OpenVibers committed 4 days ago · b89add66ea · 12 files, +81 −15

* Add Exchange key management, deployment and search clients

* Merge main

* 0.123.0

Changes

ddiff --git a/CHANGELOG.md b/CHANGELOG.md
iindex 2409ae5..b793766 100644
---- a/CHANGELOG.md
++++ b/CHANGELOG.md
@@@ -1,5 +1,9 @@
  # Changelog
  
++## 0.123.0 (2026-11-09)
++
++- ov.exchange: keys (list, create, revoke), private usage, deployments, and web, image and icon search with fetch (the Exchange API platform)
++
  ## 0.122.0 (2026-11-09)
  
  - dms.viewPreference() and setViewPreference(): a conversation's saved view, bubbles or room
ddiff --git a/README.md b/README.md
iindex beb3854..a0bd441 100644
---- a/README.md
++++ b/README.md
@@@ -10,7 +10,7 @@ npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags
  
  > Supported browser and server clients for the OpenVibe platform.
  
--**Status:** alpha, v0.122.0 (the five 1.0 core entries — `core`, `auth`, `events`, `db` and `media` — are frozen: their exported names change only with a major release; roadmap Wave 2; developer apps from Wave 20; Media objects v2 from Wave 4; the Tools platform API; Search, Chat, AI, Vision and consent clients; sign-in with recovery and a client health check). Every release is tagged (see [CHANGELOG.md](CHANGELOG.md)). Tested against local stub servers and the built-in mock platform only, never against the live platform. Services pin release tags; each repository's `STATUS.json` names the one it uses.
++**Status:** alpha, v0.123.0 (the five 1.0 core entries — `core`, `auth`, `events`, `db` and `media` — are frozen: their exported names change only with a major release; roadmap Wave 2; developer apps from Wave 20; Media objects v2 from Wave 4; the Tools platform API; Search, Chat, AI, Vision and consent clients; sign-in with recovery and a client health check). Every release is tagged (see [CHANGELOG.md](CHANGELOG.md)). Tested against local stub servers and the built-in mock platform only, never against the live platform. Services pin release tags; each repository's `STATUS.json` names the one it uses.
  **Plan:** OpenVibe End-to-End Realignment & Implementation Plan, revision 3 (20 Sep 2026), §3.2; roadmap §30.  
  **License:** MIT ([LICENSE](LICENSE)). This package is a library that apps outside the network embed, so it uses MIT. The OpenVibe services themselves stay AGPL-3.0.
  
@@@ -19,7 +19,7 @@ npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags
  After v0.97.1 is tagged:
  
  ```bash
--npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.122.0
++npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.123.0
  ```
  
  It has no runtime dependencies. It needs Node ≥ 20, or any browser with `fetch`, Web Crypto and `TextDecoder`. There is no build step. The package is CommonJS with ESM entry points (`import` works). Each subpath has its own `.d.ts`. For a page with no bundler, `browser/openvibe-sdk.mjs` is one self-contained ES module of the browser-safe subpaths (see [Browser without a bundler](#browser-without-a-bundler)). It does not depend on `openvibe-contracts` at runtime: it copies the contract types it uses (from the temporary Contracts sharing branch, a devDependency the tests check them against).
ddiff --git a/STATUS.json b/STATUS.json
iindex cc85165..3e24aad 100644
---- a/STATUS.json
++++ b/STATUS.json
@@@ -3,7 +3,7 @@
    "stage": "alpha",
    "code": true,
    "wave": "W2",
--  "version": "0.122.0",
++  "version": "0.123.0",
    "plan": "OpenVibe End-to-End Realignment & Implementation Plan, revision 3 (20 Sep 2026), §3.2; roadmap §30",
    "deployed": false,
    "deployment": "none: a package released as git tags; services and apps pin a tag",
ddiff --git a/browser/openvibe-sdk.mjs b/browser/openvibe-sdk.mjs
iindex 5f93b75..306dc25 100644
---- a/browser/openvibe-sdk.mjs
++++ b/browser/openvibe-sdk.mjs
@@@ -1,4 +1,4 @@
--// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.122.0, MIT). Do not edit.
++// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.123.0, MIT). Do not edit.
  // One self-contained ES module: core at the top level plus the browser-safe subpaths as namespaces
  // (auth, locker, registry, trust, modules, realtime, media, cam, mediaUpload, ui, community, homeFeed, bot, search, bench, meme, vision, themes, design, redact, chat, ai, credentials, jobs, tools, projects, geo). No server-only code: no service tokens, JWT verification, events, identity.
  /* eslint-disable */
@@@ -56,7 +56,7 @@ const { paginate, offsetPager } = __load(7);
  const semver = __load(6);
  
  /** The package version (test/version.test.js keeps it equal to package.json). */
--const SDK_VERSION = '0.122.0';
++const SDK_VERSION = '0.123.0';
  
  module.exports = {
      createClient,
ddiff --git a/docs/exchange.md b/docs/exchange.md
iindex 53b7b66..4fc799d 100644
---- a/docs/exchange.md
++++ b/docs/exchange.md
@@@ -175,3 +175,25 @@ createExchangeClient({
      agent,
  })
  ```
++
++### Keys, search and deployments
++
++```js
++const ov = { exchange: createExchangeClient({ developerKey: process.env.OPENVIBE_TOKEN }) };
++// Manage keys using your Network user token, not an Exchange inference key.
++const { key, secret } = await ov.exchange.keys.create({
++  name: 'My app', monthly_cap_usd: 10, allowed_models: ['deepseek/deepseek-chat'],
++}); // Save secret now: lists never return it.
++await ov.exchange.keyUsage(); // private usage by key, model and UTC day
++await ov.exchange.keys.revoke(key.id);
++await ov.exchange.deployments.list();
++await ov.exchange.search('open models', { engine: 'openvibe' });
++await ov.exchange.images('mountains', { engine: 'openverse', license: 'cc0' });
++await ov.exchange.search.icons('home');
++await ov.exchange.fetch('https://example.org');
++```
++
++Search responses carry the selected engine, USD cost and elapsed milliseconds. Image results retain
++licence, author, original source page and attribution; keep that attribution when using an image.
++`usage()` and `keyUsage()` read the signed-in dashboard. Passing `days` or `scope: "public"` selects the public aggregate.
++SearXNG requires an operator-configured instance. Paid engines are not enabled by this release.
ddiff --git a/package-lock.json b/package-lock.json
iindex fe75146..fa2a9e1 100644
---- a/package-lock.json
++++ b/package-lock.json
@@@ -1,12 +1,12 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.122.0",
++  "version": "0.123.0",
    "lockfileVersion": 3,
    "requires": true,
    "packages": {
      "": {
        "name": "openvibe-sdk",
--      "version": "0.122.0",
++      "version": "0.123.0",
        "license": "MIT",
        "bin": {
          "openvibe-download": "bin/openvibe-download.js"
ddiff --git a/package.json b/package.json
iindex f2636a6..9d472cb 100644
---- a/package.json
++++ b/package.json
@@@ -1,6 +1,6 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.122.0",
++  "version": "0.123.0",
    "description": "Supported browser and server clients for the OpenVibe platform: auth (incl. developer apps), registry discovery, identity, user modules, events, realtime, media, community, Bot robots, search, chat, AI runs, Tools (registry, run API and jobs), VIP memberships and developer projects, the async PostgreSQL data layer (db) and the Valkey cache, limits store, queue and pub/sub, with deadlines, safe retries, problem errors and trace propagation.",
    "main": "index.js",
    "types": "types/index.d.ts",
ddiff --git a/src/core/index.js b/src/core/index.js
iindex d9f07c4..78ac8a2 100644
---- a/src/core/index.js
++++ b/src/core/index.js
@@@ -8,7 +8,7 @@ const { paginate, offsetPager } = require('./paginate');
  const semver = require('./semver');
  
  /** The package version (test/version.test.js keeps it equal to package.json). */
--const SDK_VERSION = '0.122.0';
++const SDK_VERSION = '0.123.0';
  
  module.exports = {
      createClient,
ddiff --git a/src/exchange.js b/src/exchange.js
iindex 9159572..5f8d133 100644
---- a/src/exchange.js
++++ b/src/exchange.js
@@@ -540,7 +540,23 @@ function createExchangeClient({
          },
      };
  
++    const search = (q, opts = {}) => { const { signal, ...query } = opts; return jsonCall('POST', '/v1/search', { json: { ...query, q }, signal }); };
++    search.icons = (q, opts = {}) => { const { signal, ...query } = opts; return jsonCall('POST', '/v1/search/icons', { json: { ...query, q }, signal }); };
      return {
++        keys: {
++            list: ({ signal } = {}) => jsonCall('GET', '/api/v1/exchange/keys', { signal }),
++            create: (input, { signal } = {}) => jsonCall('POST', '/api/v1/exchange/keys', { json: input, signal }),
++            revoke: (id, { signal } = {}) => { if (!id) throw new TypeError('keys.revoke: id is required'); return jsonCall('DELETE', '/api/v1/exchange/keys/' + encodeURIComponent(id), { signal }); },
++        },
++        keyUsage: ({ signal } = {}) => jsonCall('GET', '/api/v1/exchange/key-usage', { signal }),
++        deployments: {
++            list: ({ signal } = {}) => jsonCall('GET', '/api/v1/exchange/deployments', { signal }),
++            create: (input, { signal } = {}) => jsonCall('POST', '/api/v1/exchange/deployments', { json: input, signal }),
++            stop: (id, { signal } = {}) => { if (!id) throw new TypeError('deployments.stop: id is required'); return jsonCall('POST', '/api/v1/exchange/deployments/' + encodeURIComponent(id) + '/stop', { signal }); },
++        },
++        search,
++        images: (q, opts = {}) => { const { signal, ...query } = opts; return jsonCall('POST', '/v1/search/images', { json: { ...query, q }, signal }); },
++        fetch: (url, { signal } = {}) => jsonCall('POST', '/v1/fetch', { json: { url }, signal }),
          arena: {
              /** Start a blind comparison round using the caller's prompt and pair. */
              async start({ prompt, category = 'chat', entries } = {}, { signal } = {}) {
@@@ -619,11 +635,12 @@ function createExchangeClient({
          },
  
          /**
--         * The usage of the Exchange: by default the public aggregate (requests, tokens and spend by day, by
--         * model and by product); with from, to or requester, the platform's own usage for that requester,
++         * The caller's key usage by default. With days or scope public, the public aggregate;
++         * with from, to or requester, the platform's own usage for that requester,
           * which needs the capability ai.usage.read.
           */
--        async usage({ days = 30, from = null, to = null, requester = null } = {}, { signal } = {}) {
++        async usage({ days = null, from = null, to = null, requester = null, scope = 'mine' } = {}, { signal } = {}) {
++            if (days == null && !from && !to && !requester && scope === 'mine') return await jsonCall('GET', '/api/v1/exchange/key-usage', { signal });
              if (from || to || requester) {
                  return await jsonCall('GET', paths.platformUsage, { query: { from, to, requester }, signal });
              }
ddiff --git a/test/exchange-platform.test.js b/test/exchange-platform.test.js
nnew file mode 100644
iindex 0000000..0b68fbd
---- /dev/null
++++ b/test/exchange-platform.test.js
@@@ -0,0 +1,5 @@
++'use strict';
++const assert=require('node:assert/strict');const {createExchangeClient}=require('../src/exchange');
++(async()=>{const calls=[];const c=createExchangeClient({developerKey:'test',maxRetries:0,fetchImpl:async(url,options)=>{calls.push({url,...options});return new Response('{}',{status:200});}});
++await c.keys.list();await c.keys.create({name:'demo',monthly_cap_usd:5,allowed_models:[]});await c.keys.revoke('a/b');await c.keyUsage();await c.deployments.list();await c.search('hello',{engine:'openvibe'});await c.images('cat',{license:'cc0'});await c.search.icons('home');await c.fetch('https://example.org');
++assert.ok(calls[2].url.endsWith('/keys/a%2Fb'));assert.equal(calls[2].method,'DELETE');assert.equal(JSON.parse(calls[5].body).q,'hello');assert.ok(calls[6].url.endsWith('/v1/search/images'));assert.ok(calls[7].url.endsWith('/v1/search/icons'));console.log('Exchange platform SDK wire shapes passed');})().catch(e=>{console.error(e);process.exitCode=1;});
ddiff --git a/test/pack.test.js b/test/pack.test.js
iindex 437b66e..89c57ab 100644
---- a/test/pack.test.js
++++ b/test/pack.test.js
@@@ -72,7 +72,7 @@ run([
                  })().catch((err) => { console.error(err); process.exit(1); });`;
              const res = execFileSync(process.execPath, ['-e', script], { cwd: app, encoding: 'utf8' });
              assert.match(res, new RegExp(`consumer ok: ${subpaths.length} subpaths \\+ the browser bundle`));
--            assert.equal(subpaths.length, 98);   // Adds the upload client and the UI entry (0.122.0); the wallet came in 0.119.0.
++            assert.equal(subpaths.length, 98);   // Adds the upload client and the UI entry (0.123.0); the wallet came in 0.119.0.
              assert.ok(!fs.existsSync(path.join(app, 'node_modules/openvibe-contracts')), 'the optional peer is not installed');
          } finally {
              fs.rmSync(tmp, { recursive: true, force: true });
ddiff --git a/types/exchange.d.ts b/types/exchange.d.ts
iindex 2d1de03..3bd7310 100644
---- a/types/exchange.d.ts
++++ b/types/exchange.d.ts
@@@ -332,7 +332,25 @@ export type ExchangeEarnings = {
      [field: string]: unknown;
  };
  
++export type ExchangeKey = { id: string; name: string; prefix: string; monthly_cap_usd: number; allowed_models: string[]; created_at: string; revoked_at: string | null };
++export type ExchangeSearchOptions = { engine?: string; limit?: number; license?: string; commercial?: boolean; format?: string; orientation?: string; size?: string; style?: 'line' | 'solid' | 'any'; set?: string; signal?: AbortSignal };
++export type ExchangeSearchResult = { results: Array<{ title: string; url: string; snippet: string; engine: string; published: string | null; thumbnail?: string | null; license?: string | null; author?: string | null; source_page?: string | null; attribution?: string | null }>; receipt: { engine: string; cost_usd: number; time_ms: number } };
  export type ExchangeClient = {
++    keys: {
++        list(opts?: { signal?: AbortSignal }): Promise<{ keys: ExchangeKey[] }>;
++        create(input: { name: string; monthly_cap_usd: number; allowed_models: string[] }, opts?: { signal?: AbortSignal }): Promise<{ key: ExchangeKey; secret: string }>;
++        revoke(id: string, opts?: { signal?: AbortSignal }): Promise<{ id: string; revoked: boolean }>;
++    };
++    keyUsage(opts?: { signal?: AbortSignal }): Promise<{ rows: Array<{ day: string; key_id: string; model: string; requests: number; tokens_in: number; tokens_out: number; cost_usd: number; status: string }> }>;
++    deployments: {
++        list(opts?: { signal?: AbortSignal }): Promise<{ endpoints: unknown[]; status: unknown }>;
++        create(input: { model: string; idle_minutes?: number }, opts?: { signal?: AbortSignal }): Promise<unknown>;
++        stop(id: string, opts?: { signal?: AbortSignal }): Promise<unknown>;
++    };
++    search: ((q: string, opts?: ExchangeSearchOptions) => Promise<ExchangeSearchResult>) & { icons(q: string, opts?: ExchangeSearchOptions): Promise<ExchangeSearchResult> };
++    images(q: string, opts?: ExchangeSearchOptions): Promise<ExchangeSearchResult>;
++    fetch(url: string, opts?: { signal?: AbortSignal }): Promise<{ url: string; text: string; receipt: ExchangeSearchResult['receipt'] }>;
++
      arena: {
          start(input: { prompt: string; category?: string; entries: unknown[] }, options?: { signal?: AbortSignal }): Promise<unknown>;
          vote(roundId: string, choice: 'left' | 'right' | 'tie' | 'both_bad', options?: { signal?: AbortSignal }): Promise<unknown>;
@@@ -352,8 +370,8 @@ export type ExchangeClient = {
          update(name: string, input: { policy: ExchangePresetPolicy }, opts?: { signal?: AbortSignal }): Promise<ExchangePreset>;
          remove(name: string, opts?: { signal?: AbortSignal }): Promise<unknown>;
      };
--    /** The public aggregate, or the platform's own usage for a requester. */
--    usage(query?: { days?: number; from?: string; to?: string; requester?: string }, opts?: { signal?: AbortSignal }): Promise<ExchangeUsageAggregate | { usage: unknown }>;
++    /** Private key usage by default; days or scope public requests aggregates. */
++    usage(query?: { scope?: 'mine' | 'public'; days?: number; from?: string; to?: string; requester?: string }, opts?: { signal?: AbortSignal }): Promise<ExchangeUsageAggregate | { usage: unknown } | { rows: unknown[] }>;
      /** The receipt of one answered request. */
      receipt(id: string, opts?: { signal?: AbortSignal }): Promise<ExchangeReceipt>;
      seller: {