openvibers/openvibe.sdk Commits

Add AI credentials SDK client (#143)

OP OpenVibers committed 5 days ago · 3edb310bdf · 19 files, +157 −32

* Add AI credentials SDK client

* Regenerate SDK browser bundle for credentials

* Declare browser credentials namespace

* 0.103.0: openvibe-sdk/credentials (a person's AI keys and session cookies, metadata only); merge main (trust)

Changes

ddiff --git a/CHANGELOG.md b/CHANGELOG.md
iindex 2cde3c5..b72fec6 100644
---- a/CHANGELOG.md
++++ b/CHANGELOG.md
@@@ -1,5 +1,12 @@
  # Changelog
  
++## 0.103.0 (2026-11-08)
++
++- Add `openvibe-sdk/credentials`: `createCredentialsClient` for a person's own provider credentials on OpenVibe.AI:
++  `list()` (metadata only: kind, provider, label, created, last used, expired), `add()` for an API key or a browser
++  session cookie, `remove()`, and `balance()` (that credential's fixed read-only balance readers: Anthropic Console
++  prepaid credits and current spend, OpenAI credit grants). A secret never comes back from any call.
++
  ## 0.102.0 (2026-11-08)
  
  - Add `openvibe-sdk/trust`: `createTrustClient({ networkUrl, getToken })` with `.me()` (the caller's own signals, a
ddiff --git a/README.md b/README.md
iindex 96234a3..ebf8aa8 100644
---- a/README.md
++++ b/README.md
@@@ -2,7 +2,7 @@
  
  > Supported browser and server clients for the OpenVibe platform.
  
--**Status:** alpha, v0.102.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.103.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.
  
@@@ -11,7 +11,7 @@
  After v0.97.1 is tagged:
  
  ```bash
--npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.102.0
++npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.103.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 6956089..8b538f7 100644
---- a/STATUS.json
++++ b/STATUS.json
@@@ -3,7 +3,7 @@
    "stage": "alpha",
    "code": true,
    "wave": "W2",
--  "version": "0.102.0",
++  "version": "0.103.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.js b/browser.js
iindex 50ba74a..eea053d 100644
---- a/browser.js
++++ b/browser.js
@@@ -24,6 +24,7 @@ module.exports = {
      redact: require('./src/redact'),
      chat: require('./src/chat'),
      ai: require('./src/ai'),
++    credentials: require('./src/credentials'),
      jobs: require('./src/jobs'),
      tools: require('./src/tools'),
      projects: require('./src/projects'),
ddiff --git a/browser/openvibe-sdk.mjs b/browser/openvibe-sdk.mjs
iindex 6815f56..c4f9202 100644
---- a/browser/openvibe-sdk.mjs
++++ b/browser/openvibe-sdk.mjs
@@@ -1,6 +1,6 @@
--// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.102.0, MIT). Do not edit.
++// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.103.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, community, bot, search, bench, meme, vision, themes, redact, chat, ai, jobs, tools, projects, geo). No server-only code: no service tokens, JWT verification, events, identity.
++// (auth, locker, registry, trust, modules, realtime, media, community, bot, search, bench, meme, vision, themes, redact, chat, ai, credentials, jobs, tools, projects, geo). No server-only code: no service tokens, JWT verification, events, identity.
  /* eslint-disable */
  const __defs = [
  // ── 0: browser.js ──────────────────────────────────────────────────
@@@ -31,10 +31,11 @@ module.exports = {
      redact: __load(33),
      chat: __load(34),
      ai: __load(35),
--    jobs: __load(36),
--    tools: __load(38),
--    projects: __load(39),
--    geo: __load(40),
++    credentials: __load(36),
++    jobs: __load(37),
++    tools: __load(39),
++    projects: __load(40),
++    geo: __load(41),
  };
  },
  // ── 1: src/core/index.js ───────────────────────────────────────────
@@@ -49,7 +50,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.102.0';
++const SDK_VERSION = '0.103.0';
  
  module.exports = {
      createClient,
@@@ -4773,7 +4774,25 @@ function createAiClient(client, defaults = {}) {
  
  module.exports = { createAiClient, TERMINAL, OPS, CLASSES };
  },
--// ── 36: src/jobs.js ─────────────────────────────────────────────────
++// ── 36: src/credentials.js ──────────────────────────────────────────
++function (module, exports) {
++'use strict';
++
++/** The current person's AI credentials and provider balance readers (metadata only on list). */
++function createCredentialsClient(client, defaults = {}) {
++    const { baseUrl } = defaults;
++    const call = (opts, o = {}) => client.json({ service: 'ai', baseUrl, audience: 'openvibe.ai', ...opts, signal: o.signal });
++    return {
++        list: (o = {}) => call({ method: 'GET', path: '/api/v1/me/credentials' }, o),
++        add: (credential, o = {}) => call({ method: 'POST', path: '/api/v1/me/credentials', body: credential }, o),
++        remove: (id, o = {}) => call({ method: 'DELETE', path: `/api/v1/me/credentials/${encodeURIComponent(id)}` }, o),
++        balance: (id, o = {}) => call({ method: 'GET', path: `/api/v1/me/credentials/${encodeURIComponent(id)}/balance` }, o),
++    };
++}
++
++module.exports = { createCredentialsClient };
++},
++// ── 37: src/jobs.js ─────────────────────────────────────────────────
  function (module, exports) {
  'use strict';
  /**
@@@ -4811,7 +4830,7 @@ function (module, exports) {
   */
  const { OpenVibeError, isOpenVibeError } = __load(3);
  const { newIdempotencyKey } = __load(5);
--const { appendFiles } = __load(37);
++const { appendFiles } = __load(38);
  const { parseSSE } = __load(23);
  
  const TERMINAL = new Set(['succeeded', 'failed', 'cancelled']);
@@@ -4975,7 +4994,7 @@ function createJobsClient(client, { baseUrl, service = 'tools', audience = 'open
  
  module.exports = { createJobsClient, isTerminal, TERMINAL_STATES: [...TERMINAL] };
  },
--// ── 37: src/core/form.js ────────────────────────────────────────────
++// ── 38: src/core/form.js ────────────────────────────────────────────
  function (module, exports) {
  'use strict';
  /**
@@@ -5009,7 +5028,7 @@ function appendFiles(form, list, where) {
  
  module.exports = { isBlob, isUpload, appendFiles };
  },
--// ── 38: src/tools.js ────────────────────────────────────────────────
++// ── 39: src/tools.js ────────────────────────────────────────────────
  function (module, exports) {
  'use strict';
  /**
@@@ -5043,8 +5062,8 @@ function (module, exports) {
   */
  const { OpenVibeError, isOpenVibeError } = __load(3);
  const { newIdempotencyKey } = __load(5);
--const { isUpload, appendFiles } = __load(37);
--const { createJobsClient } = __load(36);
++const { isUpload, appendFiles } = __load(38);
++const { createJobsClient } = __load(37);
  
  const enc = encodeURIComponent;
  const ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
@@@ -5294,7 +5313,7 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope
  
  module.exports = { createToolsClient, ToolRunError, isToolRunError };
  },
--// ── 39: src/projects.js ─────────────────────────────────────────────
++// ── 40: src/projects.js ─────────────────────────────────────────────
  function (module, exports) {
  'use strict';
  /**
@@@ -5410,7 +5429,7 @@ function createProjectsClient(client, { baseUrl } = {}) {
  
  module.exports = { createProjectsClient };
  },
--// ── 40: src/geo.js ──────────────────────────────────────────────────
++// ── 41: src/geo.js ──────────────────────────────────────────────────
  function (module, exports) {
  'use strict';
  /**
@@@ -5491,7 +5510,7 @@ export const {
      satisfiesRange, compareVersions, CONTRACTS_RANGE, DEFAULT_NETWORK, SDK_VERSION, auth,
      locker, registry, trust, modules, realtime, media,
      community, bot, search, bench, meme, vision,
--    themes, redact, chat, ai, jobs, tools,
--    projects, geo,
++    themes, redact, chat, ai, credentials, jobs,
++    tools, projects, geo,
  } = sdk;
  export default sdk;
ddiff --git a/docs/api-surface.json b/docs/api-surface.json
iindex 9c1ee32..6a277bd 100644
---- a/docs/api-surface.json
++++ b/docs/api-surface.json
@@@ -110,6 +110,11 @@
        ]
      },
      "createClient": "function",
++    "credentials": {
++      "object": [
++        "createCredentialsClient"
++      ]
++    },
      "deals": {
        "object": [
          "createDealsClient"
@@@ -599,6 +604,9 @@
    "openvibe-sdk/coupons": {
      "createCouponsClient": "function"
    },
++  "openvibe-sdk/credentials": {
++    "createCredentialsClient": "function"
++  },
    "openvibe-sdk/db": {
      "DbError": "class",
      "ISOLATION": {
ddiff --git a/docs/credentials.md b/docs/credentials.md
nnew file mode 100644
iindex 0000000..5ec975a
---- /dev/null
++++ b/docs/credentials.md
@@@ -0,0 +1,17 @@
++# AI credentials
++
++Use `createCredentialsClient` from `openvibe-sdk/credentials` with a person-authenticated core client to list metadata, add or remove a credential, and run its balance readers. `list()` never returns secret values.
++
++```js
++const credentials = createCredentialsClient(client, { baseUrl: 'https://ai.openvibe.network' });
++const { credentials: stored } = await credentials.list();
++const { credential } = await credentials.add({
++  kind: 'session_cookie', provider: 'openai', cookie: process.env.OPENAI_SESSION,
++  label: 'OpenAI browser session',
++});
++const result = await credentials.balance(credential.id);
++```
++
++Session cookies are encrypted at rest. They can perform actions available to the signed-in browser account while valid. OpenVibe uses them only for fixed, read-only provider readers: Anthropic Console prepaid credits and current spend at `console.anthropic.com`, and OpenAI credit grants at `api.openai.com/dashboard/billing/credit_grants`. Redirects are refused. Signing out of the provider ends the session. Anthropic credentials require the organization ID as `org_id`.
++
++The API is `GET`, `POST`, and `DELETE /api/v1/me/credentials`, plus `GET /api/v1/me/credentials/:id/balance`.
ddiff --git a/esm/credentials.mjs b/esm/credentials.mjs
nnew file mode 100644
iindex 0000000..8d01bc5
---- /dev/null
++++ b/esm/credentials.mjs
@@@ -0,0 +1,5 @@
++// Generated by scripts/esm.js from src/credentials.js. Do not edit.
++import cjs from '../src/credentials.js';
++
++export const { createCredentialsClient } = cjs;
++export default cjs;
ddiff --git a/esm/index.mjs b/esm/index.mjs
iindex c45cbb5..ac606a4 100644
---- a/esm/index.mjs
++++ b/esm/index.mjs
@@@ -8,11 +8,11 @@ export const {
      locker, auth, registry, identity, trust, modules,
      events, realtime, media, community, bot, search,
      bench, meme, vision, themes, redact, chat,
--    chatApps, ai, jobs, tools, projects, resources,
--    vip, quest, live, inventory, tips, blog,
--    reviews, wiki, coupons, deals, trade, space,
--    host, news, food, actor, run, video,
--    work, zone, play, download, openre, geo,
--    usage, commerce, telemetry,
++    chatApps, ai, credentials, jobs, tools, projects,
++    resources, vip, quest, live, inventory, tips,
++    blog, reviews, wiki, coupons, deals, trade,
++    space, host, news, food, actor, run,
++    video, work, zone, play, download, openre,
++    geo, usage, commerce, telemetry,
  } = cjs;
  export default cjs;
ddiff --git a/index.js b/index.js
iindex aa23ab2..61bdef5 100644
---- a/index.js
++++ b/index.js
@@@ -29,6 +29,7 @@ module.exports = {
      chat: require('./src/chat'),
      chatApps: require('./src/chat-apps'),
      ai: require('./src/ai'),
++    credentials: require('./src/credentials'),
      jobs: require('./src/jobs'),
      tools: require('./src/tools'),
      projects: require('./src/projects'),
ddiff --git a/package-lock.json b/package-lock.json
iindex ef5d089..e0a2537 100644
---- a/package-lock.json
++++ b/package-lock.json
@@@ -1,12 +1,12 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.102.0",
++  "version": "0.103.0",
    "lockfileVersion": 3,
    "requires": true,
    "packages": {
      "": {
        "name": "openvibe-sdk",
--      "version": "0.102.0",
++      "version": "0.103.0",
        "license": "MIT",
        "bin": {
          "openvibe-download": "bin/openvibe-download.js"
ddiff --git a/package.json b/package.json
iindex 07eb9bc..9916e6f 100644
---- a/package.json
++++ b/package.json
@@@ -1,6 +1,6 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.102.0",
++  "version": "0.103.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",
@@@ -256,6 +256,12 @@
        "import": "./esm/ai.mjs",
        "default": "./src/ai.js"
      },
++    "./credentials": {
++      "types": "./types/credentials.d.ts",
++      "browser": "./src/credentials.js",
++      "import": "./esm/credentials.mjs",
++      "default": "./src/credentials.js"
++    },
      "./jobs": {
        "types": "./types/jobs.d.ts",
        "import": "./esm/jobs.mjs",
ddiff --git a/src/core/index.js b/src/core/index.js
iindex 9b4f75e..29c6ed2 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.102.0';
++const SDK_VERSION = '0.103.0';
  
  module.exports = {
      createClient,
ddiff --git a/src/credentials.js b/src/credentials.js
nnew file mode 100644
iindex 0000000..5b18475
---- /dev/null
++++ b/src/credentials.js
@@@ -0,0 +1,15 @@
++'use strict';
++
++/** The current person's AI credentials and provider balance readers (metadata only on list). */
++function createCredentialsClient(client, defaults = {}) {
++    const { baseUrl } = defaults;
++    const call = (opts, o = {}) => client.json({ service: 'ai', baseUrl, audience: 'openvibe.ai', ...opts, signal: o.signal });
++    return {
++        list: (o = {}) => call({ method: 'GET', path: '/api/v1/me/credentials' }, o),
++        add: (credential, o = {}) => call({ method: 'POST', path: '/api/v1/me/credentials', body: credential }, o),
++        remove: (id, o = {}) => call({ method: 'DELETE', path: `/api/v1/me/credentials/${encodeURIComponent(id)}` }, o),
++        balance: (id, o = {}) => call({ method: 'GET', path: `/api/v1/me/credentials/${encodeURIComponent(id)}/balance` }, o),
++    };
++}
++
++module.exports = { createCredentialsClient };
ddiff --git a/test/credentials.test.js b/test/credentials.test.js
nnew file mode 100644
iindex 0000000..1f42225
---- /dev/null
++++ b/test/credentials.test.js
@@@ -0,0 +1,16 @@
++'use strict';
++const t = require('node:test');
++const assert = require('node:assert/strict');
++const { createCredentialsClient } = require('../src/credentials');
++
++t.test('credentials client uses person-scoped metadata and balance endpoints', async () => {
++    const calls = [];
++    const client = { json: async (request) => { calls.push(request); return { credentials: [] }; } };
++    const api = createCredentialsClient(client, { baseUrl: 'https://ai.example' });
++    await api.list(); await api.add({ provider: 'openai', cookie: 'private' }); await api.balance('id/one'); await api.remove('id/one');
++    assert.deepEqual(calls.map((x) => [x.method, x.path]), [
++        ['GET', '/api/v1/me/credentials'], ['POST', '/api/v1/me/credentials'],
++        ['GET', '/api/v1/me/credentials/id%2Fone/balance'], ['DELETE', '/api/v1/me/credentials/id%2Fone'],
++    ]);
++    assert.ok(calls.every((x) => x.audience === 'openvibe.ai' && x.baseUrl === 'https://ai.example'));
++});
ddiff --git a/test/pack.test.js b/test/pack.test.js
iindex c15aa37..156b8d5 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, 90);   // Adds the browser-safe trust client.
++            assert.equal(subpaths.length, 91);   // Adds the browser-safe trust client (0.102.0) and the AI credentials client.
              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/bundle.d.ts b/types/bundle.d.ts
iindex 251388b..502e3dc 100644
---- a/types/bundle.d.ts
++++ b/types/bundle.d.ts
@@@ -14,6 +14,7 @@ import * as themes from './themes';
  import * as redact from './redact';
  import * as chat from './chat';
  import * as ai from './ai';
++import * as credentials from './credentials';
  import * as jobs from './jobs';
  import * as tools from './tools';
  import * as projects from './projects';
@@@ -38,6 +39,7 @@ export * as themes from './themes';
  export * as redact from './redact';
  export * as chat from './chat';
  export * as ai from './ai';
++export * as credentials from './credentials';
  export * as jobs from './jobs';
  export * as tools from './tools';
  export * as projects from './projects';
@@@ -47,6 +49,6 @@ export * as trust from './trust';
  
  declare const sdk: typeof core & {
      auth: typeof auth; registry: typeof registry; modules: typeof modules; realtime: typeof realtime;
--    media: typeof media; community: typeof community; bot: typeof bot; search: typeof search; bench: typeof bench; meme: typeof meme; vision: typeof vision; themes: typeof themes; redact: typeof redact; chat: typeof chat; ai: typeof ai; jobs: typeof jobs; tools: typeof tools; projects: typeof projects; geo: typeof geo; locker: typeof locker; trust: typeof trust;
++    media: typeof media; community: typeof community; bot: typeof bot; search: typeof search; bench: typeof bench; meme: typeof meme; vision: typeof vision; themes: typeof themes; redact: typeof redact; chat: typeof chat; ai: typeof ai; credentials: typeof credentials; jobs: typeof jobs; tools: typeof tools; projects: typeof projects; geo: typeof geo; locker: typeof locker; trust: typeof trust;
  };
  export default sdk;
ddiff --git a/types/credentials.d.ts b/types/credentials.d.ts
nnew file mode 100644
iindex 0000000..7a98351
---- /dev/null
++++ b/types/credentials.d.ts
@@@ -0,0 +1,27 @@
++export interface CredentialMetadata {
++    id: string;
++    kind: 'api_key' | 'admin_key' | 'session_cookie';
++    provider: string;
++    label?: string;
++    created?: string;
++    last_used?: string | null;
++    expires?: string | null;
++    expired?: boolean;
++}
++export interface SessionCookieInput {
++    kind?: 'session_cookie';
++    provider: 'anthropic' | 'openai';
++    cookie: string;
++    label?: string;
++    expires_at?: string;
++    /** Anthropic organization identifier; not a secret. */
++    org_id?: string;
++}
++export interface ApiKeyInput { kind?: 'api_key'; provider: string; key: string; label?: string; base_url?: string; }
++export interface CredentialsClient {
++    list(options?: { signal?: AbortSignal }): Promise<{ credentials: CredentialMetadata[] }>;
++    add(credential: SessionCookieInput | ApiKeyInput, options?: { signal?: AbortSignal }): Promise<{ credential: CredentialMetadata }>;
++    remove(id: string, options?: { signal?: AbortSignal }): Promise<void>;
++    balance(id: string, options?: { signal?: AbortSignal }): Promise<{ balance: { credential: CredentialMetadata; source: string; at: string; values: Record<string, unknown> } }>;
++}
++export function createCredentialsClient(client: unknown, defaults?: { baseUrl?: string }): CredentialsClient;
ddiff --git a/types/index.d.ts b/types/index.d.ts
iindex fd5004a..9b7fc17 100644
---- a/types/index.d.ts
++++ b/types/index.d.ts
@@@ -17,6 +17,7 @@ export * as redact from './redact';
  export * as chat from './chat';
  export * as chatApps from './chat-apps';
  export * as ai from './ai';
++export * as credentials from './credentials';
  export * as jobs from './jobs';
  export * as tools from './tools';
  export * as projects from './projects';