openvibers/openvibe.sdk Commits
SDK 0.147.0: consolidate six feature releases (#206)
Changes
@@@ -1,5 +1,14 @@# Changelog++## 0.147.0 — 2026-11-10++++- #181: add `chat.activity` (the person's feed: mentions, replies, reactions, server invites, accepted friend requests and roles), `rooms.react()` and `reply_to_id` on room and DM sends.++- #182: add the `system` and `can_run` machine metadata to the machine reader type.++- #201: add `quest.cardData({ token, timeZone })` for the shared quest card: today's quest, the public catalog kept ten minutes and the person's badges and quest log.++- #202: add `chat.embeds(message)` and `readEmbeds()` for the typed `chat.embed@1` address previews on a chat message.++- #204: add `tools.run(tool, input, { prefer })` for worker placement (`auto`, `home`, `host`) over JSON and multipart requests, with execution receipt types and `tools.jobs.get(id)` examples.++- #205: add the browser-safe, typed `userCard.createUserCardClient(core).get(username)` public Network aggregate; hidden or unavailable fields stay optional and the read sends no credentials.++## 0.146.0 — 2026-11-10- #183: add the private history reader for cursor reads, search, summaries, agent recent reads, settings and owner-scoped deletes.@@@ -8,12 +8,12 @@**Install and test:** `npm ci && npm test` (Node 20 or newer)```bash--npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.146.0++npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.147.0```> Supported browser and server clients for the OpenVibe platform.--**Status:** alpha, v0.146.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.147.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.@@@ -22,7 +22,7 @@ npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tagsAfter v0.97.1 is tagged:```bash--npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.146.0++npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.147.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).@@@ -196,6 +196,7 @@ Until OpenVibe.Tools serves the gateway facade (Tools S6), point the jobs client| `openvibe-sdk/registry` | both | `createRegistryClient(client)`: `services({status})`, `service(id)`, `capabilities({owner})`, `capability(id)`, `namespaces()`, `contracts()`, `topics()`, `domain(host)`, `descriptor()` || `openvibe-sdk/identity` | server | `createIdentityClient(client)`: `resolve({subjectId} \| {system,type,id})`, `resolveBatch({subjectIds} \| {system,type,ids})`; `createAccountEmailsClient({getToken})` manages the signed-in person's verified addresses ([guide](docs/identity-emails.md)) || `openvibe-sdk/trust` | both | `createTrustClient({networkUrl, getToken})`: `me()` reads the caller's own account or guest signals; `of(subject)` reads an account or guest with `identity.trust.read`; `isNew(signals, {hours})`, `atLeast(signals, band)`, `AGE_BANDS` |++| `openvibe-sdk/user-card` | both | `createUserCardClient(client)`: `get(username)` reads the public Network aggregate (display name, avatar, level, streak, badges, followers, active sites). No credentials; hidden or unavailable fields stay absent ([guide](docs/user-card.md)) || `openvibe-sdk/notifications` | server | `createNotificationsClient(client)`: `push({subjectId \| userId, type, title, message, url, category, priority, …})` through Network (`network.notifications.push`); `{ sent, skipped }` or `{ sent: false, reason: 'unknown_subject' }`; attempted once, the caller retries || `openvibe-sdk/modules` | both | `createModulesClient(client)`: `get`, `put(ns, data, {revision})`, `delete`, `list`, `update(ns, fn)`, `publicGet`; `forSubject.get/put/update` for services || `openvibe-sdk/events` | server | `createEventsClient(client, {source})`: `publish`, `prepare`, `pull`, `iterate`, `get`, `get/setCheckpoint`, `subscriptions.create/list/get/disable/enable` (`subscribe`), `deliveries`, `replay`; `parseDelivery` (v1 and v2, `requireV2`), `verifyDeliveryV2`, `signDeliveryV2`, `signDeliveryHeaders`, `verifyDelivery`, `signDelivery`; developer apps: `createAppEvents(client, {projectId, appId, onBehalfOf?})` (same calls, scoped to `app.<project_key>.*`), `projectKey`, `appSource`; `createOutbox`, `createInbox`, `createPgOutbox`, `createPgInbox`; `createServiceOutbox({db, source, eventsUrl, clientId, clientSecret, eventTypes?, validate?})` (a service's outbox in one call: `emit`/`emitIn` inside the change's transaction, `moderationAction`, `start`/`stop`/`kick`/`status`) |@@@ -213,10 +214,10 @@ Until OpenVibe.Tools serves the gateway facade (Tools S6), point the jobs client| `openvibe-sdk/search` | both | `createSearchClient(client, {actingSubject?})`: `query(text, {owner, type, lang, filter, facets, limit, cursor})`, `iterate(text, {…, max})`, `suggest(text, {owner, type, limit})`, `document(owner, type, id)` (null when missing or not visible), `code(text, opts)` for merged code results or `{deep: true}` for a cited answer, `codeIterate(text, opts)` || `openvibe-sdk/limits` | node | `createActorLimiter({limits: {minute, hour, day}, actor?, maxActors?, onLimited?})` → `limits(name, {minute?, hour?, day?})` Express middleware: per-actor fixed windows at a capability boundary (service principal, else the signed-in person, else `ip:`), 429 problem+json `rate_limited` with Retry-After before the handler; `defaultActor(req)`, `.stats()` || `openvibe-sdk/account-data` | node | `createAccountData({db, service, tables: [{table, subject, value?, file?, columns?, erase?}], extraExport?, extraErase?})` → `.apply(event, {send})`, `.consumer({secrets, send, onEvent?})` (a POST /internal/events handler), `.exportPart(subject)`, `.erase(subjects)`, `.ensureSchema()`; `createNetworkSender({networkInternalUrl, clientId, clientSecret})`; `startSubscriptions({eventsUrl, endpoint, secret, networkInternalUrl, clientId, clientSecret})` (the two Events subscriptions, created at boot when missing): a service's share of account export and deletion (ADR-033), idempotent per export/deletion id; telemetry is covered once here (the person's `telemetry_samples` exported as `telemetry.json`, its `subject` set to NULL and the sample kept) unless the table is listed; `uncovered(db, {tables, taskKeyed?, exempt?})` lists the tables with a person column (`subject`, `owner`, `created_by`, `user_id`, `person`) that nothing covers, for a service test to assert is empty |--| `openvibe-sdk/chat` | both | `createChatClient(client)`: `global.send/history/search`, `rooms.*` (list, create, get, update, messages, send, deleteMessage, join, leave, read, members, setMember), `dms.*` (list, create, get, messages, send, deleteMessage, read, unread, blocks, block, unblock), `exportMine()`, `vibe.*` (list, start, rename, remove: chats with Vibe), `inboxes.*` (list, create, get, update, remove, addMember, removeMember, conversations, messages, reply, setStatus, read, identity, replies, saveReply, deleteReply, webhooks, addWebhook, testWebhook, removeWebhook: a support inbox's team), `support.*` (list, messages, send: their own conversations with sites' chats), `feeds.*` (mine, create, update, rotateKey, remove, view, onLive). With no account: `createInboxVisitor(client, { inbox, token, user, account })` (visit, send, messages, handoff, rate: your own panel for an inbox, from any site) and `createFeedPublisher(client, { feed, key })` (hello, publish, claudeCode: vibe coding events with the feed's key) |++| `openvibe-sdk/chat` | both | `createChatClient(client)`: `global.send/history/search`, `rooms.*` (list, create, get, update, messages, send, deleteMessage, join, leave, read, members, setMember, react), `dms.*` (list, create, get, messages, send, deleteMessage, read, unread, blocks, block, unblock), `activity.*` (list, unread, readOne, read: what happened to the person in Chat), `embeds(message)` (the typed `chat.embed@1` address previews on a message), `exportMine()`, `vibe.*` (list, start, rename, remove: chats with Vibe), `inboxes.*` (list, create, get, update, remove, addMember, removeMember, conversations, messages, reply, setStatus, read, identity, replies, saveReply, deleteReply, webhooks, addWebhook, testWebhook, removeWebhook: a support inbox's team), `support.*` (list, messages, send: their own conversations with sites' chats), `feeds.*` (mine, create, update, rotateKey, remove, view, onLive). With no account: `createInboxVisitor(client, { inbox, token, user, account })` (visit, send, messages, handoff, rate: your own panel for an inbox, from any site) and `createFeedPublisher(client, { feed, key })` (hello, publish, claudeCode: vibe coding events with the feed's key) || `openvibe-sdk/ai` | both | `createAiClient(client)`: `runs.create(workflow, input, {wait, idempotencyKey, latency, deadlineHours, …})`, `runs.get/list/cancel/retry/citations/addCitations/waitFor`, `batches.create/get/list/cancel`, `creations()` (the public catalogue of what AI can make, no token sent), `chat/generate/summarize/classify/extract/enrich/embed`. A run may ask for the class it may wait in (`latency`: `interactive`, `background`, `batch`; `deadlineHours`: 1–72 for a batch run); `waitFor` gives a batch run back pending rather than throwing when the wait is over — the answer comes with the run's completion event or webhook. || `openvibe-sdk/jobs` | both | `createJobsClient(client, {baseUrl?})`: `submit` (Idempotency-Key), `get`, `cancel`, `retry`, `reference`, `unreference`, `events` (SSE, reattaches), `wait`, `file` (raw Response); `isTerminal()`. Default origin: the Tools gateway's jobs facade |--| `openvibe-sdk/tools` | both | `createToolsClient(client, {baseUrl?, anonymousReads?})`: `list({family, q, execution, api, status})`, `get(id)`, `schema(id)`, `run(id, input, {files, waitMs, idempotencyKey, signal, timeoutMs})` (+ `.wait()`), `jobs`; `ToolRunError`, `isToolRunError()` |++| `openvibe-sdk/tools` | both | `createToolsClient(client, {baseUrl?, anonymousReads?})`: `list({family, q, execution, api, status})`, `get(id)`, `schema(id)`, `run(id, input, {files, waitMs, idempotencyKey, signal, timeoutMs, prefer})` (+ `.wait()`), `jobs`; `ToolRunError`, `isToolRunError()`; `prefer` picks the worker placement (`auto`, `home`, `host`) ([details](docs/tools-routing.md)) || `openvibe-sdk/projects` | both (user token) | `createProjectsClient(client)`: `catalog`, `list`, `create`, `get`, `update`, `archive`, `setAllowance`, `setEnvironmentPolicy`, `members.*`, `apps.*`, `credentials.list/rotate/revoke`, `grants.list/request/approve/deny/revoke`, `quotas.*`, `audit`, `iterateAudit` || `openvibe-sdk/resources` | server | `parseResourceName`/`resourceName`/`resourceNameOf` (OVRN, via the pinned `contracts.resources`) and `RESOURCE_KINDS` (only the chosen `med`/`wch` prefixes); `createResourceIndex({authorities, token, fetch, pageLimit, concurrency, timeoutMs, maxPages, maxMs})`: `list({project, kind, owner, limit})` -> `{resources, stale}` (`owner`: a subject id, each authority answering only what it owns), fanning out over the authorities' `GET /api/v1/resources`, following each opaque `next_cursor` and merging `common.resource-list-result@1` pages (an authority that fails — or whose cursor chain repeats, outruns `maxPages`, or outruns `maxMs` — is reported in `stale`, never fatal), and `iterate`; `createResourceClient({origin, token})`: `control(request)` POSTs a `common.resource-control-request@1` to `/api/v1/resources/control` — idempotency-keyed, transient failures retried with the same key and body, a thrown error carrying that `idempotencyKey` — and returns the `common.resource-control-result@1` (`done`/`pending`/`refused`/`failed`, a refused/failed one returned even with a non-retryable non-2xx) || `openvibe-sdk/geo` | both | `createGeoClient(client, {samples?, timeoutMs?})`: `nodes({role, region})` from Network's public node registry, `measure(nodes)` (beacon round trips, fastest first), `nearest({role, region, preferRegion})` → `{node, rtt_ms, measured}` (up/degraded nodes only; falls back to preferRegion when nothing can be measured) |@@@ -224,7 +225,7 @@ Until OpenVibe.Tools serves the gateway facade (Tools S6), point the jobs client| `openvibe-sdk/placement` | server | `plan(requirements, offers, {rateCards, states, now, current, minGain, weights, success})` → `platform.placement-result@1`; `place(requirements, offers, {…plan, person, step, floor, priors, outcomes, rules, names})` → `{result, line, ranked, rejected, fallback}`: the person's rules and ownership, the quality bar, cost per success and one sentence saying why; `optionKey`, `learn`, `successOf`, `escalate`, `lineFor`; `TRUST_CLASSES`, `TRUST_ORDER`, `DEFAULT_TRUST`; `planAi(requirements, deployments, {enabled, usage, evidence, rates, current})` → `{chosen, rejected, objective, estimate, explain}`: the AI Exchange face of the same planner (hard gates, the cost per success in nano-USD, sparse evidence marked), off by default ([details](docs/placement.md)) || `openvibe-sdk/play` | server | `createPlayClient(client)`: OpenVibe.Play's achievements and leaderboards for any game — `titles.define(title, {name, url?, summary?, achievements, boards})`, `scores.post(title, {board, ref, entries})`, `achievements.unlock(title, {player, achievements})`, `players.adopt(title, guest, person)`, `players.achievements(title, player)`; public `titles.list/get` and `boards.get(title, board, {period, page})` need no token || `openvibe-sdk/download` | server | `createDownloadClient({ key })`: OpenVibe.Download, a person's drive — `files.list/all/get/remove`, `folders.list/create/ensurePath(path)`, `upload({ path \| data, name, folderId })` in parts, `usage()`, and `sync(dir, { to, delete, dryRun, exclude })` backups. The `openvibe-download` command: `sync <folder> --to <drive/path>`, `ls`, `usage` (`OPENVIBE_DOWNLOAD_KEY`, a sync key from openvibe.download/sync) |--| `openvibe-sdk/quest` | server | `createQuestClient(client)`: `daily()`, `myDaily()`, `today()` (authenticated current-day response), `stepTypes()`, `contributeStepType(step)` for the shared daily quest and reviewable event-backed steps (`quest.steps.contribute`); `appQuests.define/list/retire` for an app's own badge quests (`quest.app_quest.manage`); `eventType(projectId, name)` builds an app event topic. App quests pay badges only; production events count |++| `openvibe-sdk/quest` | server | `createQuestClient(client)`: `daily()`, `myDaily()`, `today()` (authenticated current-day response), `stepTypes()`, `contributeStepType(step)` for the shared daily quest and reviewable event-backed steps (`quest.steps.contribute`); `cardData({ token, timeZone })` for the shared quest card (today's quest, the catalog kept ten minutes, and the person's badges/quests), with the person's Network token; `appQuests.define/list/retire` for an app's own badge quests (`quest.app_quest.manage`); `eventType(projectId, name)` builds an app event topic. App quests pay badges only; production events count || `openvibe-sdk/live` | server | `createLiveClient(client)`: OpenVibe.Live's documented routes. `streams.list/get/recentlyOnline/mine/update/end/heartbeat/endpoint`, `slots.list/create/update/remove/regenerateKey` (a slot is a saved setup with its own stream key), `goLive(slotId, {title, category, tags})` → `{ stream, endpoint }`, `channels.get/mine/update/toggleFollow/url`, `content.feed/moments({type, sort, window, cursor, limit})`; WHIP: `whip.url(streamKey)`, `whip.publish(url, offerSdp, {key?})` → `{ answer, location }` (the client's own token never goes to `/whip`), `whip.end(location)`. Writes are never retried || `openvibe-sdk/streams` | server | `createStreamsClient(client, {baseUrl?})`: an agent's own stream on OpenVibe.Live (the Agent Streams plan, S1; `live.agent-stream@1`, an `ags_…` id with no stream key and no slot). `startAgentStream({title, task, visibility, allowSites})` → `{stream, publish}` (the WHIP url and the one-time `wpt_…` ticket with its expiry), `renewTicket(id)` and `revokeTicket(id)` (the kill switch: Live ends the WHIP session at once), `state(id, {ticket})` (what the desk polls: viewers, `encode`, the curtain, `ends_at`), `postFrame(id, bytes, {ticket, contentType})` (the last frame while Live wants no video, JPEG or WebP at most 200 KB), `setCurtain(id, up, reason)`, `setVisibility(id, v)`, `end(id)` and `viewTicket(id)`. The publish ticket is a bearer of its own on the desk routes; a bad id, visibility, curtain reason or an oversized frame is refused before anything leaves. [Docs](docs/streams.md) || `openvibe-sdk/inventory` | server | `createInventoryClient(client)`: OpenVibe.Inventory, the network-wide inventory (ADR-054). Public reads: `kinds.list/get`, `definitions.list({kind, issuer})/get`, `people.items(subject)`, `people.holdings(subject, opts)`, `people.holdingsCount(subject, opts)`, `people.holdingPages(subject, opts)`, `people.equipped(subject)`, `equipped([subjects])` (≤ 100, for chat renders). The person's own: `me.items()`, `me.equip({kind, slot, instance_id | null})`. An issuer's: `definitions.create/update`, `grants.create({definition_id, subject, idempotency_key})` → `{ instance, created }` (retry-safe on the key), `instances.consume/revoke`. `forPerson(usr_…)` sends `X-OV-Subject` for a service acting for a person. Audience `openvibe.inventory` |@@@ -402,6 +403,8 @@ try {}```++[Worker placement and execution receipts](docs/tools-routing.md): `tools.run(tool, input, { prefer })` and `tools.jobs.get(id)`.++- **What `run()` resolves to.** An inline tool, or a job that finished within `waitMs`, gives `{ state: 'succeeded', tool, result, took_ms, job?, location? }`. `result` carries `data` (output kind json), `text` (kind text) or `files` (kind file or files: the job's result files). A job still queued or running gives `{ state: 'queued' | 'running', tool, job, location }`. Both have `idempotencyKey`, `replayed` and a non-enumerable `wait(opts)`. On a finished run `wait()` resolves to the run itself, so `await (await tools.run(…)).wait()` works for every tool. On a job, `wait()` takes `jobs.wait`'s options (`signal`, `onEvent`, `lastEventId`), and `tools.jobs.wait(job.id)` gives the raw job.- **Failures.** A run that finished `failed` or `cancelled` throws `ToolRunError`. It is an `OpenVibeError` with the tool's problem+json mapped: `code`, `status` (the problem's, e.g. 422 or 504, not the HTTP 200), `detail` and `errors`. It also carries `state`, `tool`, `job` and `run`. When `err.retryable`, `tools.jobs.retry(err.job.id)` runs the failed job again. A refusal before the tool ran is a plain `OpenVibeError`: 404 `tools.tool.not_found` or `tools.tool.not_runnable` (`api: false`: the YouTube downloader is page-only and never in the SDK), 422 `tools.input.invalid` (with `errors[]` pointers), 401 `token.*`, 403 `capability.denied`, 413/415 for files, 429 `quota.exceeded` or `tools.job.too_many_active`, 503 `tools.tool.unavailable`.- **Idempotency and retries.** Every run carries an `Idempotency-Key`, generated when you pass none and returned as `idempotencyKey`. The same key and request give the same job (`replayed: true`); a different request under that key is 409 `tools.job.idempotency_conflict`. Inline tools ignore the key. Because of the key, the client retries a 429 after its `Retry-After` (capped by `maxRetryDelayMs`) and retries 5xx and timeouts without creating a second job. To survive a crash between the run and saving the job id, derive the key from the request and run again with it.@@@ -3,7 +3,7 @@"stage": "alpha","code": true,"wave": "W2",-- "version": "0.146.0",++ "version": "0.147.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",@@@ -37,4 +37,5 @@ module.exports = {projects: require('./src/projects'),geo: require('./src/geo'),history: require('./src/history'),++ userCard: require('./src/user-card'),};@@@ -1,6 +1,6 @@--// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.146.0, MIT). Do not edit.++// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.147.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, levels, modules, realtime, media, cam, mediaUpload, ui, community, homeFeed, bot, search, bench, meme, vision, themes, design, redact, chat, ai, credentials, jobs, tools, projects, geo, history). No server-only code: no service tokens, JWT verification, events, identity.++// (auth, locker, registry, trust, levels, modules, realtime, media, cam, mediaUpload, ui, community, homeFeed, bot, search, bench, meme, vision, themes, design, redact, chat, ai, credentials, jobs, tools, projects, geo, history, userCard). No server-only code: no service tokens, JWT verification, events, identity./* eslint-disable */const __defs = [// ── 0: browser.js ──────────────────────────────────────────────────@@@ -44,6 +44,7 @@ module.exports = {projects: __load(49),geo: __load(50),history: __load(51),++ userCard: __load(52),};},// ── 1: src/core/index.js ───────────────────────────────────────────@@@ -58,7 +59,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.146.0';++const SDK_VERSION = '0.147.0';module.exports = {createClient,@@@ -4871,6 +4872,32 @@ const { isOpenVibeError } = __load(3);const enc = encodeURIComponent;const history = __load(42);++/** The kinds chat.embed@1 names; anything else is not a preview this SDK returns. */++const EMBED_KINDS = new Set(['link', 'video', 'image', 'live', 'picture', 'design', 'post', 'profile', 'game']);++++/** One chat.embed@1 object as the typed shape, or null when it is not one. Data only: never markup. */++function embedOf(value) {++ if (!value || typeof value !== 'object' || Array.isArray(value)) return null;++ if (!EMBED_KINDS.has(value.kind)) return null;++ if (typeof value.url !== 'string' || !value.url) return null;++ if (typeof value.site_name !== 'string' || typeof value.title !== 'string' || !value.title || typeof value.description !== 'string') return null;++ if (!(value.image === null || typeof value.image === 'string')) return null;++ if (!Number.isInteger(value.width) || !Number.isInteger(value.height) || value.width < 0 || value.height < 0) return null;++ const embed = {++ kind: value.kind, url: value.url, site_name: value.site_name, title: value.title,++ description: value.description, image: value.image, width: value.width, height: value.height,++ };++ if (typeof value.by === 'string' && value.by) embed.by = value.by;++ if (typeof value.live === 'boolean') embed.live = value.live;++ return embed;++}++++/** The address previews a message carries (chat.embed@1), typed: [] when there are none. */++function readEmbeds(message) {++ if (!message || !Array.isArray(message.embeds)) return [];++ return message.embeds.map(embedOf).filter(Boolean);++}++function createChatClient(client, defaults = {}) {const { baseUrl } = defaults;const call = (opts, o = {}) => client.json({ service: 'chat', baseUrl, audience: 'openvibe.chat', ...opts, signal: o.signal });@@@ -4884,6 +4911,8 @@ function createChatClient(client, defaults = {}) {return {/** Shared async page iterator and scroll-preserving DOM history controller. */history,++ /** The typed address previews on a message (chat.embed@1): [] when it has none. */++ embeds: (message) => readEmbeds(message),/** Vibe's model comparison API, authenticated as the person. */ask: (input, o = {}) => call({ method: 'POST', path: '/api/vibe/ask', json: input, ...once }, o),pick: (messageId, model, o = {}) => call({ method: 'POST', path: '/api/vibe/pick', json: { message_id: messageId, model }, ...once }, o),@@@ -4916,7 +4945,10 @@ function createChatClient(client, defaults = {}) {update: (slug, patch, o = {}) => call({ method: 'PATCH', path: room(slug), json: patch, ...once }, o),/** query: before | after (message id), limit */messages: (slug, query = {}, o = {}) => call({ path: `${room(slug)}/messages`, query }, o),-- send: (slug, message, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages`, json: { message }, ...once }, o),++ /** extra: { reply_to_id } answers one of the room's messages. */++ send: (slug, message, extra = {}, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages`, json: { message, ...extra }, ...once }, o),++ /** reaction: thumbsup | thumbsdown | heart | laugh | surprised | sad. The same one again takes it back. */++ react: (slug, messageId, reaction, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages/${enc(messageId)}/react`, json: { reaction }, ...once }, o),deleteMessage: (slug, id, o = {}) => call({ method: 'DELETE', path: `${room(slug)}/messages/${enc(id)}`, ...once }, o),join: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/join`, ...once }, o),leave: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/leave`, ...once }, o),@@@ -4932,7 +4964,8 @@ function createChatClient(client, defaults = {}) {get: (id, o = {}) => orNull(call({ path: conv(id) }, o)),/** query: limit, before */messages: (id, query = {}, o = {}) => call({ path: `${conv(id)}/messages`, query }, o),-- send: (id, message, o = {}) => call({ method: 'POST', path: `${conv(id)}/messages`, json: { message }, ...once }, o),++ /** extra: { reply_to_id } answers one of the conversation's messages. */++ send: (id, message, extra = {}, o = {}) => call({ method: 'POST', path: `${conv(id)}/messages`, json: { message, ...extra }, ...once }, o),deleteMessage: (id, msgId, o = {}) => call({ method: 'DELETE', path: `${conv(id)}/messages/${enc(msgId)}`, ...once }, o),read: (id, o = {}) => call({ method: 'POST', path: `${conv(id)}/read`, ...once }, o),unread: (o = {}) => call({ path: '/api/dm/unread' }, o),@@@ -4943,6 +4976,21 @@ function createChatClient(client, defaults = {}) {viewPreference: (id, o = {}) => call({ path: `${conv(id)}/view` }, o),setViewPreference: (id, view, o = {}) => call({ method: 'PUT', path: `${conv(id)}/view`, json: { view }, ...once }, o),},++ /**++ * What happened to you in Chat, newest first (server/chat/activity.js in OpenVibe.Chat): mentions, replies to++ * your messages, reactions to them, server invites, accepted friend requests and roles given to you.++ * query: { limit, before (the last row's id), kind: 'mention' | … | 'mention,reply' }++ */++ activity: {++ /** → { items, next_before, unread } */++ list: (query = {}, o = {}) => call({ path: '/api/v1/activity', query }, o),++ /** → { unread } */++ unread: (o = {}) => call({ path: '/api/v1/activity/unread' }, o),++ /** One row: POST /api/v1/activity/:id/read → { ok, read, unread } */++ readOne: (id, o = {}) => call({ method: 'POST', path: `/api/v1/activity/${enc(id)}/read`, ...once }, o),++ /** No ids: all of it. → { ok, read, unread } */++ read: (ids = null, o = {}) => call({ method: 'POST', path: '/api/v1/activity/read', json: ids == null ? { all: true } : { ids: [].concat(ids) }, ...once }, o),++ },/** Every message you sent that is still visible: { username, total, truncated, messages } (JSON). */exportMine: (o = {}) => call({ path: '/api/chat/me/export' }, o),/** Vibe, OpenVibe's assistant: the person's chats with it (people only; an API token gets 403). */@@@ -5101,7 +5149,7 @@ function createFeedPublisher(client, { feed, key, baseUrl } = {}) {};}--module.exports = { createChatClient, createInboxVisitor, createFeedPublisher, history };++module.exports = { createChatClient, createInboxVisitor, createFeedPublisher, history, readEmbeds };},// ── 42: src/chat-history.js ─────────────────────────────────────────function (module, exports) {@@@ -5872,8 +5920,9 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope* A request refused before the tool ran (404 tools.tool.not_found | not_runnable, 422* tools.input.invalid, 403 capability.denied, 503 tools.tool.unavailable…) throws OpenVibeError.*/-- async function run(id, input = {}, { files, waitMs, idempotencyKey, signal, timeoutMs } = {}) {++ async function run(id, input = {}, { files, waitMs, idempotencyKey, signal, timeoutMs, prefer } = {}) {checkId(id, 'tools.run');++ if (prefer != null && !['auto', 'home', 'host'].includes(prefer)) throw new TypeError('tools.run: prefer must be auto, home or host');if (input == null) input = {};if (typeof input !== 'object' || Array.isArray(input)) throw new TypeError('tools.run: input must be an object');if (waitMs != null && (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > MAX_WAIT_MS)) throw new TypeError(`tools.run: waitMs is an integer, 0..${MAX_WAIT_MS}`);@@@ -5892,6 +5941,7 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'opeconst key = idempotencyKey || newIdempotencyKey();const opts = { method: 'POST', path: `/api/v1/tools/${enc(id)}/run`, idempotencyKey: key, signal };++ if (prefer != null) opts.headers = { 'X-Tools-Prefer': prefer };if (uploads.length) {const form = new FormData();form.append('input', JSON.stringify(input));@@@ -6159,6 +6209,22 @@ function createHistoryClient(client, { baseUrl } = {}) {module.exports = { createHistoryClient };},++// ── 52: src/user-card.js ────────────────────────────────────────────++function (module, exports) {++'use strict';++/** One public Network aggregate. Hidden/unavailable fields stay absent; no credentials are needed. */++function createUserCardClient(client, { baseUrl } = {}) {++ if (!client || typeof client.json !== 'function') throw new TypeError('createUserCardClient: pass an SDK core client');++ return {++ get(username, { signal } = {}) {++ if (typeof username !== 'string' || !/^[A-Za-z0-9_]{3,24}$/.test(username)) throw new TypeError('invalid username');++ return client.json({ service: 'network', audience: 'openvibe.network', baseUrl,++ path: `/api/v1/people/${encodeURIComponent(username)}/card`, signal, auth: false, credentials: 'omit' });++ },++ };++}++module.exports = { createUserCardClient };++},];const __cache = new Array(__defs.length);function __load(i) {@@@ -6178,6 +6244,6 @@ export const {realtime, media, cam, mediaUpload, ui, community,homeFeed, bot, search, bench, meme, vision,themes, design, redact, chat, ai, credentials,-- jobs, tools, projects, geo, history,++ jobs, tools, projects, geo, history, userCard,} = sdk;export default sdk;@@@ -74,7 +74,8 @@"createChatClient","createFeedPublisher","createInboxVisitor",-- "history"++ "history",++ "readEmbeds"]},"chatApps": {@@@ -465,6 +466,11 @@"validateUsageSample"]},++ "userCard": {++ "object": [++ "createUserCardClient"++ ]++ },"video": {"object": ["createVideoClient"@@@ -600,7 +606,8 @@"attach","pages"]-- }++ },++ "readEmbeds": "function"},"openvibe-sdk/chat-apps": {"APP_LIMITS": {@@@ -1255,6 +1262,9 @@"usageSample": "function","validateUsageSample": "function"},++ "openvibe-sdk/user-card": {++ "createUserCardClient": "function"++ },"openvibe-sdk/valkey": {"createValkey": "function"},nnew file mode 100644@@@ -0,0 +1,12 @@++# Tools worker placement++++```js++const run = await tools.run('png', {}, { files: [fileBlob], prefer: 'host' });++const done = await run.wait();++const job = await tools.jobs.get(done.job.id);++console.log(job.result.data.execution);++```++++`prefer` is `auto` (default), `home`, or `host`, sent as `X-Tools-Prefer` for JSON and multipart requests. `host` keeps the job on the host. `home` is advisory: the owner's routing order still applies. Fetch-based jobs always stay on the host, and the owner must enable worker routing.++++Durable job results carry `result.data.execution`: the final worker id, location, total execution milliseconds and each attempt's location, time and outcome. Failed or cancelled jobs carry the receipt at `error.execution`. `ToolsExecutionReceipt` describes the shape. Receipts survive `tools.jobs.get(id)` and the usual run/wait helpers.nnew file mode 100644@@@ -0,0 +1,17 @@++# Public user card++++```js++import { createClient, userCard } from 'openvibe-sdk';++const cards = userCard.createUserCardClient(createClient());++const controller = new AbortController();++const person = await cards.get('Example', { signal: controller.signal });++// Or: import { createUserCardClient } from 'openvibe-sdk/user-card';++```++++The browser bundle exports the same `userCard` namespace. `get()` makes one public `GET /api/v1/people/:username/card` on Network; it sends neither Bearer credentials nor cookies, even when the core client has them configured. Usernames are 3–24 letters, digits or underscores. Standard SDK deadlines, cancellation and errors apply; the owner switch being off returns HTTP 503 `user_card.disabled`.++++`UserCard` always has `username` and `profile_url`. The optional fields are `display_name`, `avatar_url`, `channel_url`, `level`, `streak`, `badges_count`, `followers`, `active_sites: {id,name,url}[]`, and `live: {now:false} | {now:true,site:'live',url}`. Network owns the global level; Quest supplies daily streak and badge count. A field omitted for privacy or an unavailable source remains absent. Never turn an absent count into zero or absent live state into offline.++++Network caches the aggregate for 30 seconds, coalesces concurrent misses and rechecks privacy/account eligibility before cache use. HTTP responses use `no-store`; this SDK adds no cache. Weekly sites need the person's opt-in and expose site names only from the last seven days of Network history.++++Next for the design (For Fable): Shared's `OVUser.card` consumes this shape; visual presentation and the visibility controls are a separate task.@@@ -2,6 +2,6 @@import cjs from '../src/chat.js';export const {-- createChatClient, createInboxVisitor, createFeedPublisher, history,++ createChatClient, createInboxVisitor, createFeedPublisher, history, readEmbeds,} = cjs;export default cjs;@@@ -15,6 +15,6 @@ export const {deals, shoes, trade, space, host, news,food, actor, run, video, pics, work,zone, git, play, download, openre, geo,-- history, usage, commerce, moneyReasons, telemetry,++ history, usage, commerce, moneyReasons, telemetry, userCard,} = cjs;export default cjs;nnew file mode 100644@@@ -0,0 +1,7 @@++// Generated by scripts/esm.js from src/user-card.js. Do not edit.++import cjs from '../src/user-card.js';++++export const {++ createUserCardClient,++} = cjs;++export default cjs;@@@ -74,4 +74,5 @@ module.exports = {commerce: require('./src/commerce'),moneyReasons: require('./src/money-reasons'),telemetry: require('./src/telemetry'),++ userCard: require('./src/user-card'),};@@@ -1,12 +1,12 @@{"name": "openvibe-sdk",-- "version": "0.146.0",++ "version": "0.147.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "openvibe-sdk",-- "version": "0.146.0",++ "version": "0.147.0","license": "MIT","bin": {"openvibe-download": "bin/openvibe-download.js"@@@ -1,6 +1,6 @@{"name": "openvibe-sdk",-- "version": "0.146.0",++ "version": "0.147.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",@@@ -589,6 +589,11 @@"types": "./types/levels.d.ts","import": "./esm/levels.mjs","default": "./src/levels.js"++ },++ "./user-card": {++ "types": "./types/user-card.d.ts",++ "import": "./esm/user-card.mjs",++ "default": "./src/user-card.js"}},"bin": {@@@ -12,6 +12,7 @@ const path = require('path');const ROOT = path.join(__dirname, '..');const ENTRIES = {++ 'user-card.mjs': '../src/user-card.js','wallet.mjs': '../src/wallet.js','compute.mjs': '../src/compute/index.js','share.mjs': '../src/share.js',@@@ -31,6 +31,32 @@ const { isOpenVibeError } = require('./core/errors');const enc = encodeURIComponent;const history = require('./chat-history');++/** The kinds chat.embed@1 names; anything else is not a preview this SDK returns. */++const EMBED_KINDS = new Set(['link', 'video', 'image', 'live', 'picture', 'design', 'post', 'profile', 'game']);++++/** One chat.embed@1 object as the typed shape, or null when it is not one. Data only: never markup. */++function embedOf(value) {++ if (!value || typeof value !== 'object' || Array.isArray(value)) return null;++ if (!EMBED_KINDS.has(value.kind)) return null;++ if (typeof value.url !== 'string' || !value.url) return null;++ if (typeof value.site_name !== 'string' || typeof value.title !== 'string' || !value.title || typeof value.description !== 'string') return null;++ if (!(value.image === null || typeof value.image === 'string')) return null;++ if (!Number.isInteger(value.width) || !Number.isInteger(value.height) || value.width < 0 || value.height < 0) return null;++ const embed = {++ kind: value.kind, url: value.url, site_name: value.site_name, title: value.title,++ description: value.description, image: value.image, width: value.width, height: value.height,++ };++ if (typeof value.by === 'string' && value.by) embed.by = value.by;++ if (typeof value.live === 'boolean') embed.live = value.live;++ return embed;++}++++/** The address previews a message carries (chat.embed@1), typed: [] when there are none. */++function readEmbeds(message) {++ if (!message || !Array.isArray(message.embeds)) return [];++ return message.embeds.map(embedOf).filter(Boolean);++}++function createChatClient(client, defaults = {}) {const { baseUrl } = defaults;const call = (opts, o = {}) => client.json({ service: 'chat', baseUrl, audience: 'openvibe.chat', ...opts, signal: o.signal });@@@ -44,6 +70,8 @@ function createChatClient(client, defaults = {}) {return {/** Shared async page iterator and scroll-preserving DOM history controller. */history,++ /** The typed address previews on a message (chat.embed@1): [] when it has none. */++ embeds: (message) => readEmbeds(message),/** Vibe's model comparison API, authenticated as the person. */ask: (input, o = {}) => call({ method: 'POST', path: '/api/vibe/ask', json: input, ...once }, o),pick: (messageId, model, o = {}) => call({ method: 'POST', path: '/api/vibe/pick', json: { message_id: messageId, model }, ...once }, o),@@@ -76,7 +104,10 @@ function createChatClient(client, defaults = {}) {update: (slug, patch, o = {}) => call({ method: 'PATCH', path: room(slug), json: patch, ...once }, o),/** query: before | after (message id), limit */messages: (slug, query = {}, o = {}) => call({ path: `${room(slug)}/messages`, query }, o),-- send: (slug, message, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages`, json: { message }, ...once }, o),++ /** extra: { reply_to_id } answers one of the room's messages. */++ send: (slug, message, extra = {}, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages`, json: { message, ...extra }, ...once }, o),++ /** reaction: thumbsup | thumbsdown | heart | laugh | surprised | sad. The same one again takes it back. */++ react: (slug, messageId, reaction, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages/${enc(messageId)}/react`, json: { reaction }, ...once }, o),deleteMessage: (slug, id, o = {}) => call({ method: 'DELETE', path: `${room(slug)}/messages/${enc(id)}`, ...once }, o),join: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/join`, ...once }, o),leave: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/leave`, ...once }, o),@@@ -92,7 +123,8 @@ function createChatClient(client, defaults = {}) {get: (id, o = {}) => orNull(call({ path: conv(id) }, o)),/** query: limit, before */messages: (id, query = {}, o = {}) => call({ path: `${conv(id)}/messages`, query }, o),-- send: (id, message, o = {}) => call({ method: 'POST', path: `${conv(id)}/messages`, json: { message }, ...once }, o),++ /** extra: { reply_to_id } answers one of the conversation's messages. */++ send: (id, message, extra = {}, o = {}) => call({ method: 'POST', path: `${conv(id)}/messages`, json: { message, ...extra }, ...once }, o),deleteMessage: (id, msgId, o = {}) => call({ method: 'DELETE', path: `${conv(id)}/messages/${enc(msgId)}`, ...once }, o),read: (id, o = {}) => call({ method: 'POST', path: `${conv(id)}/read`, ...once }, o),unread: (o = {}) => call({ path: '/api/dm/unread' }, o),@@@ -103,6 +135,21 @@ function createChatClient(client, defaults = {}) {viewPreference: (id, o = {}) => call({ path: `${conv(id)}/view` }, o),setViewPreference: (id, view, o = {}) => call({ method: 'PUT', path: `${conv(id)}/view`, json: { view }, ...once }, o),},++ /**++ * What happened to you in Chat, newest first (server/chat/activity.js in OpenVibe.Chat): mentions, replies to++ * your messages, reactions to them, server invites, accepted friend requests and roles given to you.++ * query: { limit, before (the last row's id), kind: 'mention' | … | 'mention,reply' }++ */++ activity: {++ /** → { items, next_before, unread } */++ list: (query = {}, o = {}) => call({ path: '/api/v1/activity', query }, o),++ /** → { unread } */++ unread: (o = {}) => call({ path: '/api/v1/activity/unread' }, o),++ /** One row: POST /api/v1/activity/:id/read → { ok, read, unread } */++ readOne: (id, o = {}) => call({ method: 'POST', path: `/api/v1/activity/${enc(id)}/read`, ...once }, o),++ /** No ids: all of it. → { ok, read, unread } */++ read: (ids = null, o = {}) => call({ method: 'POST', path: '/api/v1/activity/read', json: ids == null ? { all: true } : { ids: [].concat(ids) }, ...once }, o),++ },/** Every message you sent that is still visible: { username, total, truncated, messages } (JSON). */exportMine: (o = {}) => call({ path: '/api/chat/me/export' }, o),/** Vibe, OpenVibe's assistant: the person's chats with it (people only; an API token gets 403). */@@@ -261,4 +308,4 @@ function createFeedPublisher(client, { feed, key, baseUrl } = {}) {};}--module.exports = { createChatClient, createInboxVisitor, createFeedPublisher, history };++module.exports = { createChatClient, createInboxVisitor, createFeedPublisher, history, readEmbeds };@@@ -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.146.0';++const SDK_VERSION = '0.147.0';module.exports = {createClient,@@@ -15,6 +15,11 @@* await quest.appQuests.list(); // { project_id, max, quests }* await quest.appQuests.retire('collector'); // completions and badges stay*++ * The card any site can show reads today's quest and what waits on Quest, with a person's Network token:++ * await quest.cardData({ token, timeZone }); // { signed_in, quest, more: { quests, sites, mine } }++ * It makes the same three reads OpenVibe.Live's server makes (/daily or /me/daily, /quests and /me/quests), keeps the++ * catalog ten minutes, and never sends a browser cookie: the site fetches it server-side and passes the token.++ ** Errors are OpenVibeError (status, code): quest.app_only (not an app token with a project), quest.foreign_event (a* step names another project's events), quest.invalid, quest.limit, capability.denied.*/@@@ -38,6 +43,33 @@ function eventType(projectId, name) {function createQuestClient(client, { baseUrl } = {}) {if (!client || typeof client.json !== 'function') throw new TypeError('createQuestClient: pass an openvibe-sdk/core client');const call = (opts) => client.json({ service: 'quest', baseUrl, audience: 'openvibe.quest', ...opts });++ const CATALOG_TTL_MS = 10 * 60 * 1000;++ let catalog = null; // { at, value: { quests, sites } }, the public catalog++ const soft = (p) => p.catch(() => null); // a door figure never costs the card itself++ const get = (path, token, opts = {}) => call({ path, token, timeoutMs: 4500, ...opts });++ /** How many quests and sites the public catalog has; one read per ten minutes. */++ const counts = async (token) => {++ if (catalog && Date.now() - catalog.at < CATALOG_TTL_MS) return catalog.value;++ const all = await soft(get('/api/v1/quests', token));++ if (!all || !Array.isArray(all.quests)) return null;++ const value = { quests: all.quests.length, sites: Array.isArray(all.sites) ? all.sites.length : 0 };++ catalog = { at: Date.now(), value };++ return value;++ };++ /** A person's badges and quest states, as counts. */++ const mine = async (token) => {++ const me = token ? await soft(get('/api/v1/me/quests', token)) : null;++ if (!me || !Array.isArray(me.quests)) return null;++ return {++ badges: Array.isArray(me.badges) ? me.badges.length : 0,++ in_progress: me.quests.filter((q) => q && q.state === 'in_progress').length,++ completed: me.quests.filter((q) => q && q.state === 'completed').length,++ };++ };++ const withMore = async (result, token) => {++ const [cat, own] = await Promise.all([counts(token), mine(token)]);++ return { ...result, more: { ...(cat || {}), ...(own ? { mine: own } : {}) } };++ };const appQuests = {/** Create or replace one of your app's quests (quest.app-quest-request@1) → quest.app-quest@1. */define: (slug, quest, { signal } = {}) => call({ method: 'PUT', path: `/api/v1/app-quests/${enc(slug)}`, json: quest, signal, idempotencyKey: false }),@@@ -46,8 +78,29 @@ function createQuestClient(client, { baseUrl } = {}) {/** Retire one: no longer counted or listed; its completions and badges stay. → quest.app-quest@1 */retire: (slug, { signal } = {}) => call({ method: 'DELETE', path: `/api/v1/app-quests/${enc(slug)}`, signal }),};++ /**++ * The daily quest card's data, with the same three Quest reads Live makes. Signed out reads the public today++ * question; a token reads the person's own checklist and can send `timeZone` for their local day. Returns null++ * when the quest itself cannot be read; the catalog and the person's log are best-effort.++ */++ const cardData = async ({ token = null, timeZone = 'UTC' } = {}) => {++ try {++ if (!token) {++ const [quest, extra] = await Promise.all([get('/api/v1/daily', null), withMore({}, null)]);++ return quest && { signed_in: false, quest, ...extra };++ }++ if (timeZone && /^[A-Za-z0-9_+\/-]{1,64}$/.test(timeZone)) {++ await soft(get('/api/v1/me/daily/time-zone', token, {++ method: 'PUT', json: { time_zone: timeZone }, idempotencyKey: false,++ }));++ }++ const [quest, extra] = await Promise.all([get('/api/v1/me/daily', token), withMore({}, token)]);++ if (!quest) return null;++ return { signed_in: true, quest, ...extra };++ } catch { return null; }++ };return {-- appQuests, eventType, projectKey,++ appQuests, eventType, projectKey, cardData,/** The network-wide quest for today, or a past YYYY-MM-DD date (quest.daily@1). */daily: ({ date, signal } = {}) => call({ path: date ? `/api/v1/daily/${enc(date)}` : '/api/v1/daily', signal }),/** This signed-in person's guided quest for today (requires a person token). */@@@ -212,8 +212,9 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope* A request refused before the tool ran (404 tools.tool.not_found | not_runnable, 422* tools.input.invalid, 403 capability.denied, 503 tools.tool.unavailable…) throws OpenVibeError.*/-- async function run(id, input = {}, { files, waitMs, idempotencyKey, signal, timeoutMs } = {}) {++ async function run(id, input = {}, { files, waitMs, idempotencyKey, signal, timeoutMs, prefer } = {}) {checkId(id, 'tools.run');++ if (prefer != null && !['auto', 'home', 'host'].includes(prefer)) throw new TypeError('tools.run: prefer must be auto, home or host');if (input == null) input = {};if (typeof input !== 'object' || Array.isArray(input)) throw new TypeError('tools.run: input must be an object');if (waitMs != null && (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > MAX_WAIT_MS)) throw new TypeError(`tools.run: waitMs is an integer, 0..${MAX_WAIT_MS}`);@@@ -232,6 +233,7 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'opeconst key = idempotencyKey || newIdempotencyKey();const opts = { method: 'POST', path: `/api/v1/tools/${enc(id)}/run`, idempotencyKey: key, signal };++ if (prefer != null) opts.headers = { 'X-Tools-Prefer': prefer };if (uploads.length) {const form = new FormData();form.append('input', JSON.stringify(input));nnew file mode 100644@@@ -0,0 +1,13 @@++'use strict';++/** One public Network aggregate. Hidden/unavailable fields stay absent; no credentials are needed. */++function createUserCardClient(client, { baseUrl } = {}) {++ if (!client || typeof client.json !== 'function') throw new TypeError('createUserCardClient: pass an SDK core client');++ return {++ get(username, { signal } = {}) {++ if (typeof username !== 'string' || !/^[A-Za-z0-9_]{3,24}$/.test(username)) throw new TypeError('invalid username');++ return client.json({ service: 'network', audience: 'openvibe.network', baseUrl,++ path: `/api/v1/people/${encodeURIComponent(username)}/card`, signal, auth: false, credentials: 'omit' });++ },++ };++}++module.exports = { createUserCardClient };@@@ -7,7 +7,7 @@const assert = require('node:assert/strict');const { stubServer, send, run } = require('./helpers');const { createClient } = require('../src/core');--const { createChatClient, createInboxVisitor, createFeedPublisher, history } = require('../src/chat');++const { createChatClient, createInboxVisitor, createFeedPublisher, history, readEmbeds } = require('../src/chat');async function chatStub() {let busy = 0;@@@ -20,6 +20,17 @@ async function chatStub() {}run([++ ['embeds reads chat.embed@1 and returns the typed shape, dropping what is not one', async () => {++ const chat = createChatClient(createClient({ baseUrls: { chat: 'http://127.0.0.1:9' }, token: 'person-token' }));++ const link = { kind: 'link', url: 'https://example.com/a', site_name: 'Example', title: 'A story', description: 'What happened', image: null, width: 640, height: 360 };++ const live = { kind: 'live', url: 'https://openvibe.live/@streamer', site_name: 'OpenVibe.Live', title: 'The Streamer', description: '', image: 'https://openvibe.media/avatars/s.jpg', width: 0, height: 0, by: 'streamer', live: true };++ assert.deepEqual(chat.embeds({ embeds: [link, live] }), [link, live]);++ assert.deepEqual(chat.embeds({ embeds: [link, { ...link, kind: 'article' }, { ...link, title: '' }, null, 'x'] }), [link], 'only real embeds come back');++ assert.deepEqual(Object.keys(chat.embeds({ embeds: [{ ...link, extra: 'dropped' }] })[0]).sort(), Object.keys(link).sort());++ assert.deepEqual(chat.embeds({}), []);++ assert.deepEqual(chat.embeds(null), []);++ assert.deepEqual(readEmbeds({ embeds: [live] }), [live], 'the reader is exported too');++ }],['the ESM chat entry exports the shared history helper', async () => {const esm = await import('../esm/chat.mjs');assert.equal(typeof esm.history.pages, 'function');@@@ -152,6 +163,30 @@ run([assert.equal(srv.requests[6].headers.authorization, undefined, 'a feed is read without the person\'s token');await srv.close();}],++ ['activity: the person\'s feed, its unread count and marking read; replies and reactions', async () => {++ const srv = await chatStub();++ const chat = createChatClient(createClient({ baseUrls: { chat: srv.url }, token: 'person-token' }));++ await chat.activity.list({ limit: 2, before: 9, kind: 'mention' });++ await chat.activity.unread();++ await chat.activity.readOne(7);++ await chat.activity.read([1, 2]);++ await chat.activity.read();++ await chat.rooms.send('builders', 'first!', { reply_to_id: 5 });++ await chat.rooms.react('builders', 9, 'heart');++ await chat.dms.send(7, 'hi', { reply_to_id: 3 });++ const got = srv.requests.map((r) => [r.method, r.url, r.body && String(r.body).length ? JSON.parse(String(r.body)) : null]);++ assert.deepEqual(got, [++ ['GET', '/api/v1/activity?limit=2&before=9&kind=mention', null],++ ['GET', '/api/v1/activity/unread', null],++ ['POST', '/api/v1/activity/7/read', null],++ ['POST', '/api/v1/activity/read', { ids: [1, 2] }],++ ['POST', '/api/v1/activity/read', { all: true }],++ ['POST', '/api/chat/rooms/builders/messages', { message: 'first!', reply_to_id: 5 }],++ ['POST', '/api/chat/rooms/builders/messages/9/react', { reaction: 'heart' }],++ ['POST', '/api/dm/conversations/7/messages', { message: 'hi', reply_to_id: 3 }],++ ]);++ await srv.close();++ }],['an inbox visitor needs no account and keeps its token; a feed publisher sends the key', async () => {const INBOX = `inb_${'A'.repeat(26)}`; const FEED = `fed_${'B'.repeat(26)}`; const KEY = `ovf_${'k'.repeat(32)}`;let fails = 1;@@@ -10,7 +10,7 @@ const assert = require('node:assert/strict');const { stubServer, send, run, sleep } = require('./helpers');const { createMachines, DEFAULT_TIMEOUT_MS } = require('../src/machines');--const MACHINE = { id: 'dev_01ARZ3NDEKTSV4RRFFQ69G5FAV', kind: 'server', online: true, roles: ['codes.worker'], running: [] };++const MACHINE = { id: 'dev_01ARZ3NDEKTSV4RRFFQ69G5FAV', kind: 'server', online: true, roles: ['codes.worker'], running: [], system: 'Linux', can_run: ['worker'] };async function hub(answer) {const state = { requests: [], token: 'person-token' };@@@ -58,6 +58,8 @@ run([const list = await machines.list();assert.equal(list.machines.length, 1);assert.equal(list.machines[0].id, MACHINE.id);++ assert.equal(list.machines[0].system, 'Linux');++ assert.deepEqual(list.machines[0].can_run, ['worker']);assert.equal((await machines.get(MACHINE.id)).machine.kind, 'server');assert.equal((await machines.catalogue()).roles[0].id, 'codes.worker');assert.equal((await machines.pair()).pairing.code, 'ABCD-EFGH');@@@ -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, 102); // history adds the 102nd subpath after levels.++ assert.equal(subpaths.length, 103); // user-card adds the 103rd subpath after history.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 });nnew file mode 100644@@@ -0,0 +1,116 @@++'use strict';++// openvibe-sdk/quest cardData: the same three Quest reads Live's server makes — today's quest (/daily or /me/daily),++// the public catalog (/quests) and the person's log (/me/quests) — with the catalog kept ten minutes, best-effort++// door figures, and null when the quest itself cannot be read.++const assert = require('node:assert/strict');++const { createQuestClient } = require('../src/quest');++++const steps = [++ { id: 'pics', event_type: 'mediahub.picture.uploaded', site: 'openvibe.pics', sentence: 'Upload a picture', href: 'https://openvibe.pics/', count: 1, progress: 1, done: true },++ { id: 'chat', event_type: 'chat.room.message.created', site: 'openvibe.chat', sentence: 'Send a public chat message', href: 'https://openvibe.chat/', count: 1, progress: 0, done: false },++];++const publicQuest = { date: '2026-11-10', title: 'Make something today', story: 'Three small things, across the network.', steps, finished_today: 12 };++const myQuest = { ...publicQuest, steps, progress: 1, streak: 5, completed: false, time_zone: 'Europe/London' };++const catalog = { quests: Array.from({ length: 12 }, (_, i) => ({ id: `q${i}` })), sites: Array.from({ length: 6 }, (_, i) => ({ site: `s${i}` })) };++++function fake(overrides = {}) {++ const calls = [];++ const client = {++ json: async (opts) => {++ calls.push(opts);++ const answer = Object.prototype.hasOwnProperty.call(overrides, opts.path) ? overrides[opts.path] : {++ '/api/v1/daily': publicQuest,++ '/api/v1/me/daily': myQuest,++ '/api/v1/quests': catalog,++ '/api/v1/me/quests': {++ quests: [{ state: 'completed' }, { state: 'completed' }, { state: 'in_progress' }, { state: 'not_started' }],++ badges: [{ id: 'b1' }, { id: 'b2' }, { id: 'b3' }],++ },++ '/api/v1/me/daily/time-zone': { ok: true },++ }[opts.path];++ if (answer instanceof Error) throw answer;++ return answer;++ },++ };++ return { quest: createQuestClient(client, { baseUrl: 'http://quest.test' }), calls };++}++++(async () => {++ // Signed out: the public quest and the catalog. No person's log and no time-zone write.++ {++ const { quest, calls } = fake();++ const data = await quest.cardData({ timeZone: 'Europe/London' });++ assert.equal(data.signed_in, false);++ assert.equal(data.quest.title, 'Make something today');++ assert.deepEqual(data.more, { quests: 12, sites: 6 });++ assert.deepEqual(calls.map((c) => c.path).sort(), ['/api/v1/daily', '/api/v1/quests']);++ assert.equal(calls.find((c) => c.path === '/api/v1/daily').token, null);++ assert.equal(calls.find((c) => c.path === '/api/v1/quests').token, null);++ assert.equal(calls.find((c) => c.path === '/api/v1/daily').audience, 'openvibe.quest');++ assert.equal(calls.find((c) => c.path === '/api/v1/daily').service, 'quest');++ assert.equal(calls.find((c) => c.path === '/api/v1/daily').baseUrl, 'http://quest.test');++ assert.equal(calls.find((c) => c.path === '/api/v1/daily').timeoutMs, 4500);++ }++++ // Signed in: time zone first, then the person's quest and log; the catalog was read once and is reused.++ {++ const { quest, calls } = fake();++ const data = await quest.cardData({ token: 'tok_123', timeZone: 'Europe/London' });++ assert.equal(data.signed_in, true);++ assert.equal(data.quest.streak, 5);++ assert.deepEqual(data.more, { quests: 12, sites: 6, mine: { badges: 3, in_progress: 1, completed: 2 } });++ assert.equal(calls[0].path, '/api/v1/me/daily/time-zone');++ assert.equal(calls[0].method, 'PUT');++ assert.deepEqual(calls[0].json, { time_zone: 'Europe/London' });++ assert.equal(calls[0].idempotencyKey, false);++ assert.ok(calls.every((c) => c.token === 'tok_123'), 'the person token is on every read');++ assert.deepEqual(calls.slice(1).map((c) => c.path).sort(), ['/api/v1/me/daily', '/api/v1/me/quests', '/api/v1/quests']);++++ // A second card read reuses the catalog; an invalid time zone is not sent.++ const before = calls.filter((c) => c.path === '/api/v1/quests').length;++ await quest.cardData({ token: 'tok_123', timeZone: 'not a zone' });++ assert.equal(calls.filter((c) => c.path === '/api/v1/quests').length, before, 'catalog cached');++ assert.equal(calls.filter((c) => c.path === '/api/v1/me/daily/time-zone').length, 1, 'invalid zone skipped');++ }++++ // The catalog is kept ten minutes, then read again.++ {++ const { quest, calls } = fake();++ const realNow = Date.now;++ let clock = 1_000_000;++ Date.now = () => clock;++ try {++ await quest.cardData();++ assert.equal(calls.filter((c) => c.path === '/api/v1/quests').length, 1);++ clock += 10 * 60 * 1000 - 1;++ await quest.cardData();++ assert.equal(calls.filter((c) => c.path === '/api/v1/quests').length, 1, 'still inside ten minutes');++ clock += 2;++ await quest.cardData();++ assert.equal(calls.filter((c) => c.path === '/api/v1/quests').length, 2, 'one second after ten minutes');++ } finally { Date.now = realNow; }++ }++++ // A door figure that fails never costs the card; a failed quest does.++ {++ const catalogDown = fake({ '/api/v1/quests': new Error('down') });++ const data = await catalogDown.quest.cardData({ token: 'tok_123' });++ assert.equal(data.signed_in, true);++ assert.deepEqual(data.more, { mine: { badges: 3, in_progress: 1, completed: 2 } });++++ const logDown = fake({ '/api/v1/me/quests': new Error('down') });++ const other = await logDown.quest.cardData({ token: 'tok_123' });++ assert.deepEqual(other.more, { quests: 12, sites: 6 });++++ const everythingDown = fake({ '/api/v1/quests': new Error('down'), '/api/v1/me/quests': new Error('down') });++ const bare = await everythingDown.quest.cardData({ token: 'tok_123' });++ assert.deepEqual(bare.more, {});++++ const questDown = fake({ '/api/v1/daily': new Error('down') });++ assert.equal(await questDown.quest.cardData(), null);++ const myQuestDown = fake({ '/api/v1/me/daily': new Error('down') });++ assert.equal(await myQuestDown.quest.cardData({ token: 'tok_123' }), null);++ }++++ process.stdout.write('quest cardData passed\n');++})().catch((err) => { process.stderr.write(String(err.stack || err) + '\n'); process.exit(1); });nnew file mode 100644@@@ -0,0 +1,25 @@++'use strict';++const assert = require('node:assert/strict');++const { createToolsClient } = require('../src/tools');++(async () => {++ const requests = [];++ const execution = { worker: 'host', location: 'host', took_ms: 12, attempts: [{ worker: 'host', location: 'host', took_ms: 12, state: 'succeeded' }] };++ const id = 'job_01K5WZX7S7Q4D2B8N3M6V1C9TR';++ const tools = createToolsClient({ options: {}, async request(opts) {++ requests.push(opts);++ const body = opts.path.startsWith('/api/v1/jobs/') ? { id, state: 'succeeded', result: { data: { execution } } } : { state: 'succeeded', tool: 'png', took_ms: 12, result: { data: { execution } } };++ return { data: body, status: 200, headers: new Headers({ 'content-type': 'application/json' }) };++ } });++ const first = await tools.run('png', {}, { prefer: 'host' });++ assert.equal(requests[0].headers['X-Tools-Prefer'], 'host');++ assert.deepEqual(requests[0].json, { input: {} }, 'preference is a header, preserving the request contract');++ assert.deepEqual(first.result.data.execution, execution);++ await tools.run('png', {}, { prefer: 'home', files: [{ name: 'a.png', data: new Uint8Array([1, 2]), type: 'image/png' }] });++ assert.equal(requests[1].headers['X-Tools-Prefer'], 'home'); assert(requests[1].form instanceof FormData);++ await tools.run('png', {}); assert.equal(requests[2].headers, undefined);++ await assert.rejects(tools.run('png', {}, { prefer: 'somewhere' }), TypeError);++ const job = await tools.jobs.get(id);++ assert.equal(requests.at(-1).path, `/api/v1/jobs/${id}`);++ assert.deepEqual(job.result.data.execution, execution);++ console.log('tools routing: JSON/multipart preferences, validation, default and jobs.get receipts passed');++})().catch(e => { console.error(e); process.exitCode = 1; });nnew file mode 100644@@@ -0,0 +1,30 @@++'use strict';++const assert = require('node:assert/strict');++const { createClient } = require('../src/core');++const { createUserCardClient } = require('../src/user-card');++(async () => {++ const calls = [];++ const hidden = { username: 'Example', profile_url: 'https://openvibe.network/@Example' };++ const signal = new AbortController().signal;++ const reader = createUserCardClient({ json: async options => { calls.push(options); return hidden; } }, { baseUrl: 'https://network.example' });++ assert.deepEqual(await reader.get('Example', { signal }), hidden);++ assert.deepEqual(calls[0], { service: 'network', audience: 'openvibe.network', baseUrl: 'https://network.example', path: '/api/v1/people/Example/card', signal, auth: false, credentials: 'omit' });++ for (const bad of ['../admin', '', 'ab', '@Example', 'x'.repeat(25), null, ['Example']]) assert.throws(() => reader.get(bad), TypeError);++ assert.throws(() => createUserCardClient({}), TypeError);++ let sent, count = 0;++ const core = createClient({ network: 'https://network.example', token: 'test-only', credentials: 'include', retries: 0, autoDiscover: false,++ fetch: async (url, options) => { sent = { url, options }; count++; return new Response(JSON.stringify(hidden), { headers: { 'Content-Type': 'application/json' } }); } });++ assert.deepEqual(await createUserCardClient(core).get('Example'), hidden);++ assert.equal(count, 1, 'one HTTP aggregate read');++ assert.equal(sent.url, 'https://network.example/api/v1/people/Example/card');++ assert.equal(new Headers(sent.options.headers).get('authorization'), null);++ assert.equal(sent.options.credentials, 'omit');++ const disabled = createUserCardClient({ json: async () => { throw Object.assign(new Error('user_card.disabled'), { status: 503 }); } });++ await assert.rejects(disabled.get('Example'), { status: 503 });++ const esm = await import('../esm/user-card.mjs');++ const browser = await import('../browser/openvibe-sdk.mjs');++ assert.equal(esm.createUserCardClient, createUserCardClient);++ assert.equal(typeof browser.userCard.createUserCardClient, 'function');++ assert.equal(require('../index').userCard.createUserCardClient, createUserCardClient);++ console.log('user-card: one public read, omitted fields preserved, credentials omitted, validation, errors and browser/ESM exports passed');++})().catch(e => { console.error(e); process.exitCode = 1; });@@@ -1,3 +1,4 @@++import * as userCard from './user-card';/** browser/openvibe-sdk.mjs: one self-contained ES module with the browser-safe subpaths (same shape as the package's browser entry). */import * as auth from './auth-browser';import * as registry from './registry';@@@ -62,8 +63,11 @@ export * as locker from './locker';export * as trust from './trust';export * as levels from './levels';++export * as userCard from './user-card';++declare const sdk: typeof core & {createWalletClient: typeof createWalletClient;++ userCard: typeof userCard;auth: typeof auth; registry: typeof registry; modules: typeof modules; realtime: typeof realtime;media: typeof media; cam: typeof cam; mediaUpload: typeof mediaUpload; ui: typeof ui; community: typeof community; homeFeed: typeof homeFeed; bot: typeof bot; search: typeof search; bench: typeof bench; meme: typeof meme; vision: typeof vision; themes: typeof themes; design: typeof design; redact: typeof redact; chat: typeof chat; ai: typeof ai; credentials: typeof credentials; jobs: typeof jobs; tools: typeof tools; projects: typeof projects; geo: typeof geo; history: typeof history; locker: typeof locker; trust: typeof trust; levels: typeof levels;};@@@ -2,6 +2,24 @@ import type { OpenVibeClient } from './core';type Opts = { signal?: AbortSignal };type Json = Record<string, unknown>;++/** The kinds chat.embed@1 names. */++export type ChatEmbedKind = 'link' | 'video' | 'image' | 'live' | 'picture' | 'design' | 'post' | 'profile' | 'game';++/** chat.embed@1: one address preview under a chat message, the shape every client draws. Plain data; escape it. */++export interface ChatEmbed {++ kind: ChatEmbedKind;++ url: string;++ site_name: string;++ title: string;++ description: string;++ /** An OpenVibe.Media address, or null (another site's picture is never hot-linked). */++ image: string | null;++ width: number;++ height: number;++ /** On OpenVibe's own kinds, the person or channel the thing belongs to. */++ by?: string;++ /** On a Live channel, whether it is broadcasting now. */++ live?: boolean;++}/** chat.room-insight-result@1: a room's public AI insight (see the contract in openvibe-contracts). */export interface RoomInsight {overview: {@@@ -16,7 +34,19 @@ export interface RoomInsight {timeline: { at: string; kind: string; title: string; text: string; message_id: number | null }[];state: 'ready' | 'quiet' | 'off';}++/** The typed address previews a message carries (chat.embed@1): [] when it has none. */++export function readEmbeds(message?: { embeds?: unknown } | null): ChatEmbed[];export type ChatMessageView = 'bubbles' | 'room';++export type ActivityKind = 'mention' | 'reply' | 'reaction' | 'server_invite' | 'friend_accept' | 'role';++export interface ActivityItem {++ id: number;++ kind: ActivityKind;++ actor: { id: number | null; username: string | null; display_name: string | null; avatar_url: string | null };++ where: { kind: 'room' | 'dm' | 'global' | 'server' | 'friends'; label: string; href: string; room?: string | null; server?: string | null; conversation?: number };++ what: { excerpt: string | null; reaction: string | null; role: string | null };++ at: string;++ read: boolean;++}export interface ChatHistoryPage<T extends { id: number | string } = { id: number | string; [field: string]: unknown }> { messages: T[]; more: boolean; [field: string]: unknown; }export interface ChatHistoryOptions { limit?: number; before?: number | string | null; signal?: AbortSignal; }export interface ChatHistoryHelper {@@@ -65,6 +95,8 @@ export interface RoomMemory {}export interface ChatClient {++ /** The typed address previews a message carries (chat.embed@1): [] when it has none. */++ embeds(message?: { embeds?: unknown } | null): ChatEmbed[];history: ChatHistoryHelper;/** Ask Vibe using Auto, one catalogue model, or two to three models side by side. */ask(input: { message: string; models?: string[]; slug?: string; fresh?: boolean; system_prompt?: string; temperature?: number }, opts?: Opts): Promise<{ chat: Json; message: Json }>;@@@ -87,7 +119,8 @@ export interface ChatClient {forgetMyMemory(id: string, opts?: Opts): Promise<{ removed: number }>;update(slug: string, patch: { name?: string; topic?: string; visibility?: 'public' | 'private'; slow_seconds?: number }, opts?: Opts): Promise<Json>;messages(slug: string, query?: { before?: number; after?: number; limit?: number }, opts?: Opts): Promise<Json>;-- send(slug: string, message: string, opts?: Opts): Promise<Json>;++ send(slug: string, message: string, extra?: { reply_to_id?: number }, opts?: Opts): Promise<Json>;++ react(slug: string, messageId: number | string, reaction: 'thumbsup' | 'thumbsdown' | 'heart' | 'laugh' | 'surprised' | 'sad', opts?: Opts): Promise<{ ok: boolean; reaction: string | null }>;deleteMessage(slug: string, id: number | string, opts?: Opts): Promise<Json>;join(slug: string, opts?: Opts): Promise<Json>;leave(slug: string, opts?: Opts): Promise<Json>;@@@ -100,7 +133,7 @@ export interface ChatClient {create(userIds: number[], extra?: { name?: string }, opts?: Opts): Promise<Json>;get(id: number | string, opts?: Opts): Promise<Json | null>;messages(id: number | string, query?: { limit?: number; before?: number }, opts?: Opts): Promise<Json>;-- send(id: number | string, message: string, opts?: Opts): Promise<Json>;++ send(id: number | string, message: string, extra?: { reply_to_id?: number }, opts?: Opts): Promise<Json>;deleteMessage(id: number | string, msgId: number | string, opts?: Opts): Promise<Json>;read(id: number | string, opts?: Opts): Promise<Json>;unread(opts?: Opts): Promise<{ unread: number }>;@@@ -111,6 +144,12 @@ export interface ChatClient {setViewPreference(id: number | string, view: ChatMessageView, opts?: Opts): Promise<{ view: ChatMessageView; conversation_id: number }>;};exportMine(opts?: Opts): Promise<{ username: string; exported_at: string; total: number; truncated: boolean; messages: Json[] }>;++ activity: {++ list(query?: { limit?: number; before?: number; kind?: string }, opts?: Opts): Promise<{ items: ActivityItem[]; next_before: number | null; unread: number }>;++ unread(opts?: Opts): Promise<{ unread: number }>;++ readOne(id: number | string, opts?: Opts): Promise<{ ok: boolean; read: number; unread: number }>;++ read(ids?: number[] | null, opts?: Opts): Promise<{ ok: boolean; read: number; unread: number }>;++ };vibe: {list(opts?: Opts): Promise<{ chats: Json[]; allowance?: Json }>;conversations(opts?: Opts): Promise<{ conversations: Array<{ slug: string; name: string; last_message_at: string; created_at: string; last_line: string | null; last_answer_at: string | null; site: string | null }>; count: number }>;@@@ -69,3 +69,5 @@ export * as locker from './locker';export const createWalletClient: typeof import('./wallet').createWalletClient;export * as levels from './levels';++++export * as userCard from './user-card';@@@ -18,6 +18,10 @@ export interface Machine {name?: string;/** The operating system the machine reports. */os?: string;++ /** Safe display label for the operating system or machine kind. */++ system?: string;++ /** Human-readable work classes the Link machine can run (worker, browser, models, robot). */++ can_run?: string[];/** When the machine was last seen. */last_seen_at?: string;/** The OpenVibe Link version the machine reports. */@@@ -14,6 +14,19 @@ export interface AppQuest {title: string; why: string | null; steps: AppQuestStep[]; badge: { id: string; name: string }; url: string | null;status: 'active' | 'retired'; created_at: string; updated_at: string; completions: number;}++export interface QuestCardData {++ signed_in: boolean;++ quest: QuestDaily;++ more: {++ quests?: number;++ sites?: number;++ mine?: { badges: number; in_progress: number; completed: number };++ };++}++export interface QuestCardOptions {++ token?: string | null;++ timeZone?: string;++}export interface QuestClient {daily(opts?: { date?: string; signal?: AbortSignal }): Promise<DailyQuest>;today(opts?: { signal?: AbortSignal }): Promise<DailyProgress>;@@@ -25,6 +38,7 @@ export interface QuestClient {list(opts?: { signal?: AbortSignal }): Promise<{ project_id: string; max: number; quests: AppQuest[] }>;retire(slug: string, opts?: { signal?: AbortSignal }): Promise<AppQuest>;};++ cardData(opts?: QuestCardOptions): Promise<QuestCardData | null>;eventType(projectId: string, name: string): string;projectKey(projectId: string): string;}@@@ -31,7 +31,17 @@ export interface ToolListQuery {signal?: AbortSignal;}++/** Durable job execution receipt at result.data.execution, or error.execution on failure/cancellation. */++export interface ToolsExecutionReceipt {++ worker: string;++ location: 'home' | 'host';++ took_ms: number;++ attempts: Array<{ worker: string; location: 'home' | 'host'; took_ms: number; state: 'succeeded' | 'failed' | 'cancelled' | 'disconnected' }>;++}++export interface ToolRunOptions {++ /** host keeps work on the host; home is advisory and respects owner order. Default auto. */++ prefer?: 'auto' | 'home' | 'host';/** Uploads first, then references, in order; the count must fit the descriptor's files.min..max. */files?: ToolRunFile | ToolRunFile[];/** Job tools: wait up to this long (0..60000 ms) before answering; 200 finished, else 202. */nnew file mode 100644@@@ -0,0 +1,23 @@++import type { OpenVibeClient } from './core';++/** An omitted field is hidden or unavailable, never an implied zero/offline state. */++export interface UserCard {++ username: string;++ profile_url: string;++ display_name?: string;++ avatar_url?: string;++ channel_url?: string;++ live?: { now: false } | { now: true; site: 'live'; url: string };++ /** Network's global level (the level shown by Quest). */++ level?: number;++ /** Consecutive completed daily quests, using the person's chosen time zone. */++ streak?: number;++ badges_count?: number;++ followers?: number;++ /** Explicit opt-in; site names only, from the last seven days of Network history. */++ active_sites?: Array<{ id: string; name: string; url: string }>;++}++export interface UserCardClient {++ get(username: string, options?: { signal?: AbortSignal }): Promise<UserCard>;++}++/** Public read, without Bearer credentials or cookies. Disabled owner switch returns HTTP 503. */++export function createUserCardClient(client: OpenVibeClient, options?: { baseUrl?: string }): UserCardClient;
@@ -1,5 +1,14 @@
@@ -1,5 +1,14 @@
# Changelog
# Changelog
+## 0.147.0 — 2026-11-10
+
+- #181: add `chat.activity` (the person's feed: mentions, replies, reactions, server invites, accepted friend requests and roles), `rooms.react()` and `reply_to_id` on room and DM sends.
+- #182: add the `system` and `can_run` machine metadata to the machine reader type.
+- #201: add `quest.cardData({ token, timeZone })` for the shared quest card: today's quest, the public catalog kept ten minutes and the person's badges and quest log.
+- #202: add `chat.embeds(message)` and `readEmbeds()` for the typed `chat.embed@1` address previews on a chat message.
+- #204: add `tools.run(tool, input, { prefer })` for worker placement (`auto`, `home`, `host`) over JSON and multipart requests, with execution receipt types and `tools.jobs.get(id)` examples.
+- #205: add the browser-safe, typed `userCard.createUserCardClient(core).get(username)` public Network aggregate; hidden or unavailable fields stay optional and the read sends no credentials.
+
## 0.146.0 — 2026-11-10
## 0.146.0 — 2026-11-10
- #183: add the private history reader for cursor reads, search, summaries, agent recent reads, settings and owner-scoped deletes.
- #183: add the private history reader for cursor reads, search, summaries, agent recent reads, settings and owner-scoped deletes.
@@ -8,12 +8,12 @@
@@ -8,12 +8,12 @@
**Install and test:** `npm ci && npm test` (Node 20 or newer)
**Install and test:** `npm ci && npm test` (Node 20 or newer)
```bash
```bash
-npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.146.0
+npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.147.0
```
```
> Supported browser and server clients for the OpenVibe platform.
> Supported browser and server clients for the OpenVibe platform.
-**Status:** alpha, v0.146.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.147.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.
**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.
**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.
@@ -22,7 +22,7 @@ npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags
@@ -22,7 +22,7 @@ npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags
After v0.97.1 is tagged:
After v0.97.1 is tagged:
```bash
```bash
-npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.146.0
+npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.147.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).
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).
@@ -196,6 +196,7 @@ Until OpenVibe.Tools serves the gateway facade (Tools S6), point the jobs client
@@ -196,6 +196,7 @@ Until OpenVibe.Tools serves the gateway facade (Tools S6), point the jobs client
| `openvibe-sdk/registry` | both | `createRegistryClient(client)`: `services({status})`, `service(id)`, `capabilities({owner})`, `capability(id)`, `namespaces()`, `contracts()`, `topics()`, `domain(host)`, `descriptor()` |
| `openvibe-sdk/registry` | both | `createRegistryClient(client)`: `services({status})`, `service(id)`, `capabilities({owner})`, `capability(id)`, `namespaces()`, `contracts()`, `topics()`, `domain(host)`, `descriptor()` |
| `openvibe-sdk/identity` | server | `createIdentityClient(client)`: `resolve({subjectId} \| {system,type,id})`, `resolveBatch({subjectIds} \| {system,type,ids})`; `createAccountEmailsClient({getToken})` manages the signed-in person's verified addresses ([guide](docs/identity-emails.md)) |
| `openvibe-sdk/identity` | server | `createIdentityClient(client)`: `resolve({subjectId} \| {system,type,id})`, `resolveBatch({subjectIds} \| {system,type,ids})`; `createAccountEmailsClient({getToken})` manages the signed-in person's verified addresses ([guide](docs/identity-emails.md)) |
| `openvibe-sdk/trust` | both | `createTrustClient({networkUrl, getToken})`: `me()` reads the caller's own account or guest signals; `of(subject)` reads an account or guest with `identity.trust.read`; `isNew(signals, {hours})`, `atLeast(signals, band)`, `AGE_BANDS` |
| `openvibe-sdk/trust` | both | `createTrustClient({networkUrl, getToken})`: `me()` reads the caller's own account or guest signals; `of(subject)` reads an account or guest with `identity.trust.read`; `isNew(signals, {hours})`, `atLeast(signals, band)`, `AGE_BANDS` |
+| `openvibe-sdk/user-card` | both | `createUserCardClient(client)`: `get(username)` reads the public Network aggregate (display name, avatar, level, streak, badges, followers, active sites). No credentials; hidden or unavailable fields stay absent ([guide](docs/user-card.md)) |
| `openvibe-sdk/notifications` | server | `createNotificationsClient(client)`: `push({subjectId \| userId, type, title, message, url, category, priority, …})` through Network (`network.notifications.push`); `{ sent, skipped }` or `{ sent: false, reason: 'unknown_subject' }`; attempted once, the caller retries |
| `openvibe-sdk/notifications` | server | `createNotificationsClient(client)`: `push({subjectId \| userId, type, title, message, url, category, priority, …})` through Network (`network.notifications.push`); `{ sent, skipped }` or `{ sent: false, reason: 'unknown_subject' }`; attempted once, the caller retries |
| `openvibe-sdk/modules` | both | `createModulesClient(client)`: `get`, `put(ns, data, {revision})`, `delete`, `list`, `update(ns, fn)`, `publicGet`; `forSubject.get/put/update` for services |
| `openvibe-sdk/modules` | both | `createModulesClient(client)`: `get`, `put(ns, data, {revision})`, `delete`, `list`, `update(ns, fn)`, `publicGet`; `forSubject.get/put/update` for services |
| `openvibe-sdk/events` | server | `createEventsClient(client, {source})`: `publish`, `prepare`, `pull`, `iterate`, `get`, `get/setCheckpoint`, `subscriptions.create/list/get/disable/enable` (`subscribe`), `deliveries`, `replay`; `parseDelivery` (v1 and v2, `requireV2`), `verifyDeliveryV2`, `signDeliveryV2`, `signDeliveryHeaders`, `verifyDelivery`, `signDelivery`; developer apps: `createAppEvents(client, {projectId, appId, onBehalfOf?})` (same calls, scoped to `app.<project_key>.*`), `projectKey`, `appSource`; `createOutbox`, `createInbox`, `createPgOutbox`, `createPgInbox`; `createServiceOutbox({db, source, eventsUrl, clientId, clientSecret, eventTypes?, validate?})` (a service's outbox in one call: `emit`/`emitIn` inside the change's transaction, `moderationAction`, `start`/`stop`/`kick`/`status`) |
| `openvibe-sdk/events` | server | `createEventsClient(client, {source})`: `publish`, `prepare`, `pull`, `iterate`, `get`, `get/setCheckpoint`, `subscriptions.create/list/get/disable/enable` (`subscribe`), `deliveries`, `replay`; `parseDelivery` (v1 and v2, `requireV2`), `verifyDeliveryV2`, `signDeliveryV2`, `signDeliveryHeaders`, `verifyDelivery`, `signDelivery`; developer apps: `createAppEvents(client, {projectId, appId, onBehalfOf?})` (same calls, scoped to `app.<project_key>.*`), `projectKey`, `appSource`; `createOutbox`, `createInbox`, `createPgOutbox`, `createPgInbox`; `createServiceOutbox({db, source, eventsUrl, clientId, clientSecret, eventTypes?, validate?})` (a service's outbox in one call: `emit`/`emitIn` inside the change's transaction, `moderationAction`, `start`/`stop`/`kick`/`status`) |
@@ -213,10 +214,10 @@ Until OpenVibe.Tools serves the gateway facade (Tools S6), point the jobs client
@@ -213,10 +214,10 @@ Until OpenVibe.Tools serves the gateway facade (Tools S6), point the jobs client
| `openvibe-sdk/search` | both | `createSearchClient(client, {actingSubject?})`: `query(text, {owner, type, lang, filter, facets, limit, cursor})`, `iterate(text, {…, max})`, `suggest(text, {owner, type, limit})`, `document(owner, type, id)` (null when missing or not visible), `code(text, opts)` for merged code results or `{deep: true}` for a cited answer, `codeIterate(text, opts)` |
| `openvibe-sdk/search` | both | `createSearchClient(client, {actingSubject?})`: `query(text, {owner, type, lang, filter, facets, limit, cursor})`, `iterate(text, {…, max})`, `suggest(text, {owner, type, limit})`, `document(owner, type, id)` (null when missing or not visible), `code(text, opts)` for merged code results or `{deep: true}` for a cited answer, `codeIterate(text, opts)` |
| `openvibe-sdk/limits` | node | `createActorLimiter({limits: {minute, hour, day}, actor?, maxActors?, onLimited?})` → `limits(name, {minute?, hour?, day?})` Express middleware: per-actor fixed windows at a capability boundary (service principal, else the signed-in person, else `ip:`), 429 problem+json `rate_limited` with Retry-After before the handler; `defaultActor(req)`, `.stats()` |
| `openvibe-sdk/limits` | node | `createActorLimiter({limits: {minute, hour, day}, actor?, maxActors?, onLimited?})` → `limits(name, {minute?, hour?, day?})` Express middleware: per-actor fixed windows at a capability boundary (service principal, else the signed-in person, else `ip:`), 429 problem+json `rate_limited` with Retry-After before the handler; `defaultActor(req)`, `.stats()` |
| `openvibe-sdk/account-data` | node | `createAccountData({db, service, tables: [{table, subject, value?, file?, columns?, erase?}], extraExport?, extraErase?})` → `.apply(event, {send})`, `.consumer({secrets, send, onEvent?})` (a POST /internal/events handler), `.exportPart(subject)`, `.erase(subjects)`, `.ensureSchema()`; `createNetworkSender({networkInternalUrl, clientId, clientSecret})`; `startSubscriptions({eventsUrl, endpoint, secret, networkInternalUrl, clientId, clientSecret})` (the two Events subscriptions, created at boot when missing): a service's share of account export and deletion (ADR-033), idempotent per export/deletion id; telemetry is covered once here (the person's `telemetry_samples` exported as `telemetry.json`, its `subject` set to NULL and the sample kept) unless the table is listed; `uncovered(db, {tables, taskKeyed?, exempt?})` lists the tables with a person column (`subject`, `owner`, `created_by`, `user_id`, `person`) that nothing covers, for a service test to assert is empty |
| `openvibe-sdk/account-data` | node | `createAccountData({db, service, tables: [{table, subject, value?, file?, columns?, erase?}], extraExport?, extraErase?})` → `.apply(event, {send})`, `.consumer({secrets, send, onEvent?})` (a POST /internal/events handler), `.exportPart(subject)`, `.erase(subjects)`, `.ensureSchema()`; `createNetworkSender({networkInternalUrl, clientId, clientSecret})`; `startSubscriptions({eventsUrl, endpoint, secret, networkInternalUrl, clientId, clientSecret})` (the two Events subscriptions, created at boot when missing): a service's share of account export and deletion (ADR-033), idempotent per export/deletion id; telemetry is covered once here (the person's `telemetry_samples` exported as `telemetry.json`, its `subject` set to NULL and the sample kept) unless the table is listed; `uncovered(db, {tables, taskKeyed?, exempt?})` lists the tables with a person column (`subject`, `owner`, `created_by`, `user_id`, `person`) that nothing covers, for a service test to assert is empty |
-| `openvibe-sdk/chat` | both | `createChatClient(client)`: `global.send/history/search`, `rooms.*` (list, create, get, update, messages, send, deleteMessage, join, leave, read, members, setMember), `dms.*` (list, create, get, messages, send, deleteMessage, read, unread, blocks, block, unblock), `exportMine()`, `vibe.*` (list, start, rename, remove: chats with Vibe), `inboxes.*` (list, create, get, update, remove, addMember, removeMember, conversations, messages, reply, setStatus, read, identity, replies, saveReply, deleteReply, webhooks, addWebhook, testWebhook, removeWebhook: a support inbox's team), `support.*` (list, messages, send: their own conversations with sites' chats), `feeds.*` (mine, create, update, rotateKey, remove, view, onLive). With no account: `createInboxVisitor(client, { inbox, token, user, account })` (visit, send, messages, handoff, rate: your own panel for an inbox, from any site) and `createFeedPublisher(client, { feed, key })` (hello, publish, claudeCode: vibe coding events with the feed's key) |
+| `openvibe-sdk/chat` | both | `createChatClient(client)`: `global.send/history/search`, `rooms.*` (list, create, get, update, messages, send, deleteMessage, join, leave, read, members, setMember, react), `dms.*` (list, create, get, messages, send, deleteMessage, read, unread, blocks, block, unblock), `activity.*` (list, unread, readOne, read: what happened to the person in Chat), `embeds(message)` (the typed `chat.embed@1` address previews on a message), `exportMine()`, `vibe.*` (list, start, rename, remove: chats with Vibe), `inboxes.*` (list, create, get, update, remove, addMember, removeMember, conversations, messages, reply, setStatus, read, identity, replies, saveReply, deleteReply, webhooks, addWebhook, testWebhook, removeWebhook: a support inbox's team), `support.*` (list, messages, send: their own conversations with sites' chats), `feeds.*` (mine, create, update, rotateKey, remove, view, onLive). With no account: `createInboxVisitor(client, { inbox, token, user, account })` (visit, send, messages, handoff, rate: your own panel for an inbox, from any site) and `createFeedPublisher(client, { feed, key })` (hello, publish, claudeCode: vibe coding events with the feed's key) |
| `openvibe-sdk/ai` | both | `createAiClient(client)`: `runs.create(workflow, input, {wait, idempotencyKey, latency, deadlineHours, …})`, `runs.get/list/cancel/retry/citations/addCitations/waitFor`, `batches.create/get/list/cancel`, `creations()` (the public catalogue of what AI can make, no token sent), `chat/generate/summarize/classify/extract/enrich/embed`. A run may ask for the class it may wait in (`latency`: `interactive`, `background`, `batch`; `deadlineHours`: 1–72 for a batch run); `waitFor` gives a batch run back pending rather than throwing when the wait is over — the answer comes with the run's completion event or webhook. |
| `openvibe-sdk/ai` | both | `createAiClient(client)`: `runs.create(workflow, input, {wait, idempotencyKey, latency, deadlineHours, …})`, `runs.get/list/cancel/retry/citations/addCitations/waitFor`, `batches.create/get/list/cancel`, `creations()` (the public catalogue of what AI can make, no token sent), `chat/generate/summarize/classify/extract/enrich/embed`. A run may ask for the class it may wait in (`latency`: `interactive`, `background`, `batch`; `deadlineHours`: 1–72 for a batch run); `waitFor` gives a batch run back pending rather than throwing when the wait is over — the answer comes with the run's completion event or webhook. |
| `openvibe-sdk/jobs` | both | `createJobsClient(client, {baseUrl?})`: `submit` (Idempotency-Key), `get`, `cancel`, `retry`, `reference`, `unreference`, `events` (SSE, reattaches), `wait`, `file` (raw Response); `isTerminal()`. Default origin: the Tools gateway's jobs facade |
| `openvibe-sdk/jobs` | both | `createJobsClient(client, {baseUrl?})`: `submit` (Idempotency-Key), `get`, `cancel`, `retry`, `reference`, `unreference`, `events` (SSE, reattaches), `wait`, `file` (raw Response); `isTerminal()`. Default origin: the Tools gateway's jobs facade |
-| `openvibe-sdk/tools` | both | `createToolsClient(client, {baseUrl?, anonymousReads?})`: `list({family, q, execution, api, status})`, `get(id)`, `schema(id)`, `run(id, input, {files, waitMs, idempotencyKey, signal, timeoutMs})` (+ `.wait()`), `jobs`; `ToolRunError`, `isToolRunError()` |
+| `openvibe-sdk/tools` | both | `createToolsClient(client, {baseUrl?, anonymousReads?})`: `list({family, q, execution, api, status})`, `get(id)`, `schema(id)`, `run(id, input, {files, waitMs, idempotencyKey, signal, timeoutMs, prefer})` (+ `.wait()`), `jobs`; `ToolRunError`, `isToolRunError()`; `prefer` picks the worker placement (`auto`, `home`, `host`) ([details](docs/tools-routing.md)) |
| `openvibe-sdk/projects` | both (user token) | `createProjectsClient(client)`: `catalog`, `list`, `create`, `get`, `update`, `archive`, `setAllowance`, `setEnvironmentPolicy`, `members.*`, `apps.*`, `credentials.list/rotate/revoke`, `grants.list/request/approve/deny/revoke`, `quotas.*`, `audit`, `iterateAudit` |
| `openvibe-sdk/projects` | both (user token) | `createProjectsClient(client)`: `catalog`, `list`, `create`, `get`, `update`, `archive`, `setAllowance`, `setEnvironmentPolicy`, `members.*`, `apps.*`, `credentials.list/rotate/revoke`, `grants.list/request/approve/deny/revoke`, `quotas.*`, `audit`, `iterateAudit` |
| `openvibe-sdk/resources` | server | `parseResourceName`/`resourceName`/`resourceNameOf` (OVRN, via the pinned `contracts.resources`) and `RESOURCE_KINDS` (only the chosen `med`/`wch` prefixes); `createResourceIndex({authorities, token, fetch, pageLimit, concurrency, timeoutMs, maxPages, maxMs})`: `list({project, kind, owner, limit})` -> `{resources, stale}` (`owner`: a subject id, each authority answering only what it owns), fanning out over the authorities' `GET /api/v1/resources`, following each opaque `next_cursor` and merging `common.resource-list-result@1` pages (an authority that fails — or whose cursor chain repeats, outruns `maxPages`, or outruns `maxMs` — is reported in `stale`, never fatal), and `iterate`; `createResourceClient({origin, token})`: `control(request)` POSTs a `common.resource-control-request@1` to `/api/v1/resources/control` — idempotency-keyed, transient failures retried with the same key and body, a thrown error carrying that `idempotencyKey` — and returns the `common.resource-control-result@1` (`done`/`pending`/`refused`/`failed`, a refused/failed one returned even with a non-retryable non-2xx) |
| `openvibe-sdk/resources` | server | `parseResourceName`/`resourceName`/`resourceNameOf` (OVRN, via the pinned `contracts.resources`) and `RESOURCE_KINDS` (only the chosen `med`/`wch` prefixes); `createResourceIndex({authorities, token, fetch, pageLimit, concurrency, timeoutMs, maxPages, maxMs})`: `list({project, kind, owner, limit})` -> `{resources, stale}` (`owner`: a subject id, each authority answering only what it owns), fanning out over the authorities' `GET /api/v1/resources`, following each opaque `next_cursor` and merging `common.resource-list-result@1` pages (an authority that fails — or whose cursor chain repeats, outruns `maxPages`, or outruns `maxMs` — is reported in `stale`, never fatal), and `iterate`; `createResourceClient({origin, token})`: `control(request)` POSTs a `common.resource-control-request@1` to `/api/v1/resources/control` — idempotency-keyed, transient failures retried with the same key and body, a thrown error carrying that `idempotencyKey` — and returns the `common.resource-control-result@1` (`done`/`pending`/`refused`/`failed`, a refused/failed one returned even with a non-retryable non-2xx) |
| `openvibe-sdk/geo` | both | `createGeoClient(client, {samples?, timeoutMs?})`: `nodes({role, region})` from Network's public node registry, `measure(nodes)` (beacon round trips, fastest first), `nearest({role, region, preferRegion})` → `{node, rtt_ms, measured}` (up/degraded nodes only; falls back to preferRegion when nothing can be measured) |
| `openvibe-sdk/geo` | both | `createGeoClient(client, {samples?, timeoutMs?})`: `nodes({role, region})` from Network's public node registry, `measure(nodes)` (beacon round trips, fastest first), `nearest({role, region, preferRegion})` → `{node, rtt_ms, measured}` (up/degraded nodes only; falls back to preferRegion when nothing can be measured) |
@@ -224,7 +225,7 @@ Until OpenVibe.Tools serves the gateway facade (Tools S6), point the jobs client
@@ -224,7 +225,7 @@ Until OpenVibe.Tools serves the gateway facade (Tools S6), point the jobs client
| `openvibe-sdk/placement` | server | `plan(requirements, offers, {rateCards, states, now, current, minGain, weights, success})` → `platform.placement-result@1`; `place(requirements, offers, {…plan, person, step, floor, priors, outcomes, rules, names})` → `{result, line, ranked, rejected, fallback}`: the person's rules and ownership, the quality bar, cost per success and one sentence saying why; `optionKey`, `learn`, `successOf`, `escalate`, `lineFor`; `TRUST_CLASSES`, `TRUST_ORDER`, `DEFAULT_TRUST`; `planAi(requirements, deployments, {enabled, usage, evidence, rates, current})` → `{chosen, rejected, objective, estimate, explain}`: the AI Exchange face of the same planner (hard gates, the cost per success in nano-USD, sparse evidence marked), off by default ([details](docs/placement.md)) |
| `openvibe-sdk/placement` | server | `plan(requirements, offers, {rateCards, states, now, current, minGain, weights, success})` → `platform.placement-result@1`; `place(requirements, offers, {…plan, person, step, floor, priors, outcomes, rules, names})` → `{result, line, ranked, rejected, fallback}`: the person's rules and ownership, the quality bar, cost per success and one sentence saying why; `optionKey`, `learn`, `successOf`, `escalate`, `lineFor`; `TRUST_CLASSES`, `TRUST_ORDER`, `DEFAULT_TRUST`; `planAi(requirements, deployments, {enabled, usage, evidence, rates, current})` → `{chosen, rejected, objective, estimate, explain}`: the AI Exchange face of the same planner (hard gates, the cost per success in nano-USD, sparse evidence marked), off by default ([details](docs/placement.md)) |
| `openvibe-sdk/play` | server | `createPlayClient(client)`: OpenVibe.Play's achievements and leaderboards for any game — `titles.define(title, {name, url?, summary?, achievements, boards})`, `scores.post(title, {board, ref, entries})`, `achievements.unlock(title, {player, achievements})`, `players.adopt(title, guest, person)`, `players.achievements(title, player)`; public `titles.list/get` and `boards.get(title, board, {period, page})` need no token |
| `openvibe-sdk/play` | server | `createPlayClient(client)`: OpenVibe.Play's achievements and leaderboards for any game — `titles.define(title, {name, url?, summary?, achievements, boards})`, `scores.post(title, {board, ref, entries})`, `achievements.unlock(title, {player, achievements})`, `players.adopt(title, guest, person)`, `players.achievements(title, player)`; public `titles.list/get` and `boards.get(title, board, {period, page})` need no token |
| `openvibe-sdk/download` | server | `createDownloadClient({ key })`: OpenVibe.Download, a person's drive — `files.list/all/get/remove`, `folders.list/create/ensurePath(path)`, `upload({ path \| data, name, folderId })` in parts, `usage()`, and `sync(dir, { to, delete, dryRun, exclude })` backups. The `openvibe-download` command: `sync <folder> --to <drive/path>`, `ls`, `usage` (`OPENVIBE_DOWNLOAD_KEY`, a sync key from openvibe.download/sync) |
| `openvibe-sdk/download` | server | `createDownloadClient({ key })`: OpenVibe.Download, a person's drive — `files.list/all/get/remove`, `folders.list/create/ensurePath(path)`, `upload({ path \| data, name, folderId })` in parts, `usage()`, and `sync(dir, { to, delete, dryRun, exclude })` backups. The `openvibe-download` command: `sync <folder> --to <drive/path>`, `ls`, `usage` (`OPENVIBE_DOWNLOAD_KEY`, a sync key from openvibe.download/sync) |
-| `openvibe-sdk/quest` | server | `createQuestClient(client)`: `daily()`, `myDaily()`, `today()` (authenticated current-day response), `stepTypes()`, `contributeStepType(step)` for the shared daily quest and reviewable event-backed steps (`quest.steps.contribute`); `appQuests.define/list/retire` for an app's own badge quests (`quest.app_quest.manage`); `eventType(projectId, name)` builds an app event topic. App quests pay badges only; production events count |
+| `openvibe-sdk/quest` | server | `createQuestClient(client)`: `daily()`, `myDaily()`, `today()` (authenticated current-day response), `stepTypes()`, `contributeStepType(step)` for the shared daily quest and reviewable event-backed steps (`quest.steps.contribute`); `cardData({ token, timeZone })` for the shared quest card (today's quest, the catalog kept ten minutes, and the person's badges/quests), with the person's Network token; `appQuests.define/list/retire` for an app's own badge quests (`quest.app_quest.manage`); `eventType(projectId, name)` builds an app event topic. App quests pay badges only; production events count |
| `openvibe-sdk/live` | server | `createLiveClient(client)`: OpenVibe.Live's documented routes. `streams.list/get/recentlyOnline/mine/update/end/heartbeat/endpoint`, `slots.list/create/update/remove/regenerateKey` (a slot is a saved setup with its own stream key), `goLive(slotId, {title, category, tags})` → `{ stream, endpoint }`, `channels.get/mine/update/toggleFollow/url`, `content.feed/moments({type, sort, window, cursor, limit})`; WHIP: `whip.url(streamKey)`, `whip.publish(url, offerSdp, {key?})` → `{ answer, location }` (the client's own token never goes to `/whip`), `whip.end(location)`. Writes are never retried |
| `openvibe-sdk/live` | server | `createLiveClient(client)`: OpenVibe.Live's documented routes. `streams.list/get/recentlyOnline/mine/update/end/heartbeat/endpoint`, `slots.list/create/update/remove/regenerateKey` (a slot is a saved setup with its own stream key), `goLive(slotId, {title, category, tags})` → `{ stream, endpoint }`, `channels.get/mine/update/toggleFollow/url`, `content.feed/moments({type, sort, window, cursor, limit})`; WHIP: `whip.url(streamKey)`, `whip.publish(url, offerSdp, {key?})` → `{ answer, location }` (the client's own token never goes to `/whip`), `whip.end(location)`. Writes are never retried |
| `openvibe-sdk/streams` | server | `createStreamsClient(client, {baseUrl?})`: an agent's own stream on OpenVibe.Live (the Agent Streams plan, S1; `live.agent-stream@1`, an `ags_…` id with no stream key and no slot). `startAgentStream({title, task, visibility, allowSites})` → `{stream, publish}` (the WHIP url and the one-time `wpt_…` ticket with its expiry), `renewTicket(id)` and `revokeTicket(id)` (the kill switch: Live ends the WHIP session at once), `state(id, {ticket})` (what the desk polls: viewers, `encode`, the curtain, `ends_at`), `postFrame(id, bytes, {ticket, contentType})` (the last frame while Live wants no video, JPEG or WebP at most 200 KB), `setCurtain(id, up, reason)`, `setVisibility(id, v)`, `end(id)` and `viewTicket(id)`. The publish ticket is a bearer of its own on the desk routes; a bad id, visibility, curtain reason or an oversized frame is refused before anything leaves. [Docs](docs/streams.md) |
| `openvibe-sdk/streams` | server | `createStreamsClient(client, {baseUrl?})`: an agent's own stream on OpenVibe.Live (the Agent Streams plan, S1; `live.agent-stream@1`, an `ags_…` id with no stream key and no slot). `startAgentStream({title, task, visibility, allowSites})` → `{stream, publish}` (the WHIP url and the one-time `wpt_…` ticket with its expiry), `renewTicket(id)` and `revokeTicket(id)` (the kill switch: Live ends the WHIP session at once), `state(id, {ticket})` (what the desk polls: viewers, `encode`, the curtain, `ends_at`), `postFrame(id, bytes, {ticket, contentType})` (the last frame while Live wants no video, JPEG or WebP at most 200 KB), `setCurtain(id, up, reason)`, `setVisibility(id, v)`, `end(id)` and `viewTicket(id)`. The publish ticket is a bearer of its own on the desk routes; a bad id, visibility, curtain reason or an oversized frame is refused before anything leaves. [Docs](docs/streams.md) |
| `openvibe-sdk/inventory` | server | `createInventoryClient(client)`: OpenVibe.Inventory, the network-wide inventory (ADR-054). Public reads: `kinds.list/get`, `definitions.list({kind, issuer})/get`, `people.items(subject)`, `people.holdings(subject, opts)`, `people.holdingsCount(subject, opts)`, `people.holdingPages(subject, opts)`, `people.equipped(subject)`, `equipped([subjects])` (≤ 100, for chat renders). The person's own: `me.items()`, `me.equip({kind, slot, instance_id | null})`. An issuer's: `definitions.create/update`, `grants.create({definition_id, subject, idempotency_key})` → `{ instance, created }` (retry-safe on the key), `instances.consume/revoke`. `forPerson(usr_…)` sends `X-OV-Subject` for a service acting for a person. Audience `openvibe.inventory` |
| `openvibe-sdk/inventory` | server | `createInventoryClient(client)`: OpenVibe.Inventory, the network-wide inventory (ADR-054). Public reads: `kinds.list/get`, `definitions.list({kind, issuer})/get`, `people.items(subject)`, `people.holdings(subject, opts)`, `people.holdingsCount(subject, opts)`, `people.holdingPages(subject, opts)`, `people.equipped(subject)`, `equipped([subjects])` (≤ 100, for chat renders). The person's own: `me.items()`, `me.equip({kind, slot, instance_id | null})`. An issuer's: `definitions.create/update`, `grants.create({definition_id, subject, idempotency_key})` → `{ instance, created }` (retry-safe on the key), `instances.consume/revoke`. `forPerson(usr_…)` sends `X-OV-Subject` for a service acting for a person. Audience `openvibe.inventory` |
@@ -402,6 +403,8 @@ try {
@@ -402,6 +403,8 @@ try {
}
}
```
```
+[Worker placement and execution receipts](docs/tools-routing.md): `tools.run(tool, input, { prefer })` and `tools.jobs.get(id)`.
+
- **What `run()` resolves to.** An inline tool, or a job that finished within `waitMs`, gives `{ state: 'succeeded', tool, result, took_ms, job?, location? }`. `result` carries `data` (output kind json), `text` (kind text) or `files` (kind file or files: the job's result files). A job still queued or running gives `{ state: 'queued' | 'running', tool, job, location }`. Both have `idempotencyKey`, `replayed` and a non-enumerable `wait(opts)`. On a finished run `wait()` resolves to the run itself, so `await (await tools.run(…)).wait()` works for every tool. On a job, `wait()` takes `jobs.wait`'s options (`signal`, `onEvent`, `lastEventId`), and `tools.jobs.wait(job.id)` gives the raw job.
- **What `run()` resolves to.** An inline tool, or a job that finished within `waitMs`, gives `{ state: 'succeeded', tool, result, took_ms, job?, location? }`. `result` carries `data` (output kind json), `text` (kind text) or `files` (kind file or files: the job's result files). A job still queued or running gives `{ state: 'queued' | 'running', tool, job, location }`. Both have `idempotencyKey`, `replayed` and a non-enumerable `wait(opts)`. On a finished run `wait()` resolves to the run itself, so `await (await tools.run(…)).wait()` works for every tool. On a job, `wait()` takes `jobs.wait`'s options (`signal`, `onEvent`, `lastEventId`), and `tools.jobs.wait(job.id)` gives the raw job.
- **Failures.** A run that finished `failed` or `cancelled` throws `ToolRunError`. It is an `OpenVibeError` with the tool's problem+json mapped: `code`, `status` (the problem's, e.g. 422 or 504, not the HTTP 200), `detail` and `errors`. It also carries `state`, `tool`, `job` and `run`. When `err.retryable`, `tools.jobs.retry(err.job.id)` runs the failed job again. A refusal before the tool ran is a plain `OpenVibeError`: 404 `tools.tool.not_found` or `tools.tool.not_runnable` (`api: false`: the YouTube downloader is page-only and never in the SDK), 422 `tools.input.invalid` (with `errors[]` pointers), 401 `token.*`, 403 `capability.denied`, 413/415 for files, 429 `quota.exceeded` or `tools.job.too_many_active`, 503 `tools.tool.unavailable`.
- **Failures.** A run that finished `failed` or `cancelled` throws `ToolRunError`. It is an `OpenVibeError` with the tool's problem+json mapped: `code`, `status` (the problem's, e.g. 422 or 504, not the HTTP 200), `detail` and `errors`. It also carries `state`, `tool`, `job` and `run`. When `err.retryable`, `tools.jobs.retry(err.job.id)` runs the failed job again. A refusal before the tool ran is a plain `OpenVibeError`: 404 `tools.tool.not_found` or `tools.tool.not_runnable` (`api: false`: the YouTube downloader is page-only and never in the SDK), 422 `tools.input.invalid` (with `errors[]` pointers), 401 `token.*`, 403 `capability.denied`, 413/415 for files, 429 `quota.exceeded` or `tools.job.too_many_active`, 503 `tools.tool.unavailable`.
- **Idempotency and retries.** Every run carries an `Idempotency-Key`, generated when you pass none and returned as `idempotencyKey`. The same key and request give the same job (`replayed: true`); a different request under that key is 409 `tools.job.idempotency_conflict`. Inline tools ignore the key. Because of the key, the client retries a 429 after its `Retry-After` (capped by `maxRetryDelayMs`) and retries 5xx and timeouts without creating a second job. To survive a crash between the run and saving the job id, derive the key from the request and run again with it.
- **Idempotency and retries.** Every run carries an `Idempotency-Key`, generated when you pass none and returned as `idempotencyKey`. The same key and request give the same job (`replayed: true`); a different request under that key is 409 `tools.job.idempotency_conflict`. Inline tools ignore the key. Because of the key, the client retries a 429 after its `Retry-After` (capped by `maxRetryDelayMs`) and retries 5xx and timeouts without creating a second job. To survive a crash between the run and saving the job id, derive the key from the request and run again with it.
@@ -3,7 +3,7 @@
@@ -3,7 +3,7 @@
"stage": "alpha",
"stage": "alpha",
"code": true,
"code": true,
"wave": "W2",
"wave": "W2",
- "version": "0.146.0",
+ "version": "0.147.0",
"plan": "OpenVibe End-to-End Realignment & Implementation Plan, revision 3 (20 Sep 2026), §3.2; roadmap §30",
"plan": "OpenVibe End-to-End Realignment & Implementation Plan, revision 3 (20 Sep 2026), §3.2; roadmap §30",
"deployed": false,
"deployed": false,
"deployment": "none: a package released as git tags; services and apps pin a tag",
"deployment": "none: a package released as git tags; services and apps pin a tag",
@@ -37,4 +37,5 @@ module.exports = {
@@ -37,4 +37,5 @@ module.exports = {
projects: require('./src/projects'),
projects: require('./src/projects'),
geo: require('./src/geo'),
geo: require('./src/geo'),
history: require('./src/history'),
history: require('./src/history'),
+ userCard: require('./src/user-card'),
};
};
@@ -1,6 +1,6 @@
@@ -1,6 +1,6 @@
-// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.146.0, MIT). Do not edit.
+// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.147.0, MIT). Do not edit.
// One self-contained ES module: core at the top level plus the browser-safe subpaths as namespaces
// One self-contained ES module: core at the top level plus the browser-safe subpaths as namespaces
-// (auth, locker, registry, trust, levels, modules, realtime, media, cam, mediaUpload, ui, community, homeFeed, bot, search, bench, meme, vision, themes, design, redact, chat, ai, credentials, jobs, tools, projects, geo, history). No server-only code: no service tokens, JWT verification, events, identity.
+// (auth, locker, registry, trust, levels, modules, realtime, media, cam, mediaUpload, ui, community, homeFeed, bot, search, bench, meme, vision, themes, design, redact, chat, ai, credentials, jobs, tools, projects, geo, history, userCard). No server-only code: no service tokens, JWT verification, events, identity.
/* eslint-disable */
/* eslint-disable */
const __defs = [
const __defs = [
// ── 0: browser.js ──────────────────────────────────────────────────
// ── 0: browser.js ──────────────────────────────────────────────────
@@ -44,6 +44,7 @@ module.exports = {
@@ -44,6 +44,7 @@ module.exports = {
projects: __load(49),
projects: __load(49),
geo: __load(50),
geo: __load(50),
history: __load(51),
history: __load(51),
+ userCard: __load(52),
};
};
},
},
// ── 1: src/core/index.js ───────────────────────────────────────────
// ── 1: src/core/index.js ───────────────────────────────────────────
@@ -58,7 +59,7 @@ const { paginate, offsetPager } = __load(7);
@@ -58,7 +59,7 @@ const { paginate, offsetPager } = __load(7);
const semver = __load(6);
const semver = __load(6);
/** The package version (test/version.test.js keeps it equal to package.json). */
/** The package version (test/version.test.js keeps it equal to package.json). */
-const SDK_VERSION = '0.146.0';
+const SDK_VERSION = '0.147.0';
module.exports = {
module.exports = {
createClient,
createClient,
@@ -4871,6 +4872,32 @@ const { isOpenVibeError } = __load(3);
@@ -4871,6 +4872,32 @@ const { isOpenVibeError } = __load(3);
const enc = encodeURIComponent;
const enc = encodeURIComponent;
const history = __load(42);
const history = __load(42);
+/** The kinds chat.embed@1 names; anything else is not a preview this SDK returns. */
+const EMBED_KINDS = new Set(['link', 'video', 'image', 'live', 'picture', 'design', 'post', 'profile', 'game']);
+
+/** One chat.embed@1 object as the typed shape, or null when it is not one. Data only: never markup. */
+function embedOf(value) {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+ if (!EMBED_KINDS.has(value.kind)) return null;
+ if (typeof value.url !== 'string' || !value.url) return null;
+ if (typeof value.site_name !== 'string' || typeof value.title !== 'string' || !value.title || typeof value.description !== 'string') return null;
+ if (!(value.image === null || typeof value.image === 'string')) return null;
+ if (!Number.isInteger(value.width) || !Number.isInteger(value.height) || value.width < 0 || value.height < 0) return null;
+ const embed = {
+ kind: value.kind, url: value.url, site_name: value.site_name, title: value.title,
+ description: value.description, image: value.image, width: value.width, height: value.height,
+ };
+ if (typeof value.by === 'string' && value.by) embed.by = value.by;
+ if (typeof value.live === 'boolean') embed.live = value.live;
+ return embed;
+}
+
+/** The address previews a message carries (chat.embed@1), typed: [] when there are none. */
+function readEmbeds(message) {
+ if (!message || !Array.isArray(message.embeds)) return [];
+ return message.embeds.map(embedOf).filter(Boolean);
+}
+
function createChatClient(client, defaults = {}) {
function createChatClient(client, defaults = {}) {
const { baseUrl } = defaults;
const { baseUrl } = defaults;
const call = (opts, o = {}) => client.json({ service: 'chat', baseUrl, audience: 'openvibe.chat', ...opts, signal: o.signal });
const call = (opts, o = {}) => client.json({ service: 'chat', baseUrl, audience: 'openvibe.chat', ...opts, signal: o.signal });
@@ -4884,6 +4911,8 @@ function createChatClient(client, defaults = {}) {
@@ -4884,6 +4911,8 @@ function createChatClient(client, defaults = {}) {
return {
return {
/** Shared async page iterator and scroll-preserving DOM history controller. */
/** Shared async page iterator and scroll-preserving DOM history controller. */
history,
history,
+ /** The typed address previews on a message (chat.embed@1): [] when it has none. */
+ embeds: (message) => readEmbeds(message),
/** Vibe's model comparison API, authenticated as the person. */
/** Vibe's model comparison API, authenticated as the person. */
ask: (input, o = {}) => call({ method: 'POST', path: '/api/vibe/ask', json: input, ...once }, o),
ask: (input, o = {}) => call({ method: 'POST', path: '/api/vibe/ask', json: input, ...once }, o),
pick: (messageId, model, o = {}) => call({ method: 'POST', path: '/api/vibe/pick', json: { message_id: messageId, model }, ...once }, o),
pick: (messageId, model, o = {}) => call({ method: 'POST', path: '/api/vibe/pick', json: { message_id: messageId, model }, ...once }, o),
@@ -4916,7 +4945,10 @@ function createChatClient(client, defaults = {}) {
@@ -4916,7 +4945,10 @@ function createChatClient(client, defaults = {}) {
update: (slug, patch, o = {}) => call({ method: 'PATCH', path: room(slug), json: patch, ...once }, o),
update: (slug, patch, o = {}) => call({ method: 'PATCH', path: room(slug), json: patch, ...once }, o),
/** query: before | after (message id), limit */
/** query: before | after (message id), limit */
messages: (slug, query = {}, o = {}) => call({ path: `${room(slug)}/messages`, query }, o),
messages: (slug, query = {}, o = {}) => call({ path: `${room(slug)}/messages`, query }, o),
- send: (slug, message, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages`, json: { message }, ...once }, o),
+ /** extra: { reply_to_id } answers one of the room's messages. */
+ send: (slug, message, extra = {}, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages`, json: { message, ...extra }, ...once }, o),
+ /** reaction: thumbsup | thumbsdown | heart | laugh | surprised | sad. The same one again takes it back. */
+ react: (slug, messageId, reaction, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages/${enc(messageId)}/react`, json: { reaction }, ...once }, o),
deleteMessage: (slug, id, o = {}) => call({ method: 'DELETE', path: `${room(slug)}/messages/${enc(id)}`, ...once }, o),
deleteMessage: (slug, id, o = {}) => call({ method: 'DELETE', path: `${room(slug)}/messages/${enc(id)}`, ...once }, o),
join: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/join`, ...once }, o),
join: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/join`, ...once }, o),
leave: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/leave`, ...once }, o),
leave: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/leave`, ...once }, o),
@@ -4932,7 +4964,8 @@ function createChatClient(client, defaults = {}) {
@@ -4932,7 +4964,8 @@ function createChatClient(client, defaults = {}) {
get: (id, o = {}) => orNull(call({ path: conv(id) }, o)),
get: (id, o = {}) => orNull(call({ path: conv(id) }, o)),
/** query: limit, before */
/** query: limit, before */
messages: (id, query = {}, o = {}) => call({ path: `${conv(id)}/messages`, query }, o),
messages: (id, query = {}, o = {}) => call({ path: `${conv(id)}/messages`, query }, o),
- send: (id, message, o = {}) => call({ method: 'POST', path: `${conv(id)}/messages`, json: { message }, ...once }, o),
+ /** extra: { reply_to_id } answers one of the conversation's messages. */
+ send: (id, message, extra = {}, o = {}) => call({ method: 'POST', path: `${conv(id)}/messages`, json: { message, ...extra }, ...once }, o),
deleteMessage: (id, msgId, o = {}) => call({ method: 'DELETE', path: `${conv(id)}/messages/${enc(msgId)}`, ...once }, o),
deleteMessage: (id, msgId, o = {}) => call({ method: 'DELETE', path: `${conv(id)}/messages/${enc(msgId)}`, ...once }, o),
read: (id, o = {}) => call({ method: 'POST', path: `${conv(id)}/read`, ...once }, o),
read: (id, o = {}) => call({ method: 'POST', path: `${conv(id)}/read`, ...once }, o),
unread: (o = {}) => call({ path: '/api/dm/unread' }, o),
unread: (o = {}) => call({ path: '/api/dm/unread' }, o),
@@ -4943,6 +4976,21 @@ function createChatClient(client, defaults = {}) {
@@ -4943,6 +4976,21 @@ function createChatClient(client, defaults = {}) {
viewPreference: (id, o = {}) => call({ path: `${conv(id)}/view` }, o),
viewPreference: (id, o = {}) => call({ path: `${conv(id)}/view` }, o),
setViewPreference: (id, view, o = {}) => call({ method: 'PUT', path: `${conv(id)}/view`, json: { view }, ...once }, o),
setViewPreference: (id, view, o = {}) => call({ method: 'PUT', path: `${conv(id)}/view`, json: { view }, ...once }, o),
},
},
+ /**
+ * What happened to you in Chat, newest first (server/chat/activity.js in OpenVibe.Chat): mentions, replies to
+ * your messages, reactions to them, server invites, accepted friend requests and roles given to you.
+ * query: { limit, before (the last row's id), kind: 'mention' | … | 'mention,reply' }
+ */
+ activity: {
+ /** → { items, next_before, unread } */
+ list: (query = {}, o = {}) => call({ path: '/api/v1/activity', query }, o),
+ /** → { unread } */
+ unread: (o = {}) => call({ path: '/api/v1/activity/unread' }, o),
+ /** One row: POST /api/v1/activity/:id/read → { ok, read, unread } */
+ readOne: (id, o = {}) => call({ method: 'POST', path: `/api/v1/activity/${enc(id)}/read`, ...once }, o),
+ /** No ids: all of it. → { ok, read, unread } */
+ read: (ids = null, o = {}) => call({ method: 'POST', path: '/api/v1/activity/read', json: ids == null ? { all: true } : { ids: [].concat(ids) }, ...once }, o),
+ },
/** Every message you sent that is still visible: { username, total, truncated, messages } (JSON). */
/** Every message you sent that is still visible: { username, total, truncated, messages } (JSON). */
exportMine: (o = {}) => call({ path: '/api/chat/me/export' }, o),
exportMine: (o = {}) => call({ path: '/api/chat/me/export' }, o),
/** Vibe, OpenVibe's assistant: the person's chats with it (people only; an API token gets 403). */
/** Vibe, OpenVibe's assistant: the person's chats with it (people only; an API token gets 403). */
@@ -5101,7 +5149,7 @@ function createFeedPublisher(client, { feed, key, baseUrl } = {}) {
@@ -5101,7 +5149,7 @@ function createFeedPublisher(client, { feed, key, baseUrl } = {}) {
};
};
}
}
-module.exports = { createChatClient, createInboxVisitor, createFeedPublisher, history };
+module.exports = { createChatClient, createInboxVisitor, createFeedPublisher, history, readEmbeds };
},
},
// ── 42: src/chat-history.js ─────────────────────────────────────────
// ── 42: src/chat-history.js ─────────────────────────────────────────
function (module, exports) {
function (module, exports) {
@@ -5872,8 +5920,9 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope
@@ -5872,8 +5920,9 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope
* A request refused before the tool ran (404 tools.tool.not_found | not_runnable, 422
* A request refused before the tool ran (404 tools.tool.not_found | not_runnable, 422
* tools.input.invalid, 403 capability.denied, 503 tools.tool.unavailable…) throws OpenVibeError.
* tools.input.invalid, 403 capability.denied, 503 tools.tool.unavailable…) throws OpenVibeError.
*/
*/
- async function run(id, input = {}, { files, waitMs, idempotencyKey, signal, timeoutMs } = {}) {
+ async function run(id, input = {}, { files, waitMs, idempotencyKey, signal, timeoutMs, prefer } = {}) {
checkId(id, 'tools.run');
checkId(id, 'tools.run');
+ if (prefer != null && !['auto', 'home', 'host'].includes(prefer)) throw new TypeError('tools.run: prefer must be auto, home or host');
if (input == null) input = {};
if (input == null) input = {};
if (typeof input !== 'object' || Array.isArray(input)) throw new TypeError('tools.run: input must be an object');
if (typeof input !== 'object' || Array.isArray(input)) throw new TypeError('tools.run: input must be an object');
if (waitMs != null && (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > MAX_WAIT_MS)) throw new TypeError(`tools.run: waitMs is an integer, 0..${MAX_WAIT_MS}`);
if (waitMs != null && (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > MAX_WAIT_MS)) throw new TypeError(`tools.run: waitMs is an integer, 0..${MAX_WAIT_MS}`);
@@ -5892,6 +5941,7 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope
@@ -5892,6 +5941,7 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope
const key = idempotencyKey || newIdempotencyKey();
const key = idempotencyKey || newIdempotencyKey();
const opts = { method: 'POST', path: `/api/v1/tools/${enc(id)}/run`, idempotencyKey: key, signal };
const opts = { method: 'POST', path: `/api/v1/tools/${enc(id)}/run`, idempotencyKey: key, signal };
+ if (prefer != null) opts.headers = { 'X-Tools-Prefer': prefer };
if (uploads.length) {
if (uploads.length) {
const form = new FormData();
const form = new FormData();
form.append('input', JSON.stringify(input));
form.append('input', JSON.stringify(input));
@@ -6159,6 +6209,22 @@ function createHistoryClient(client, { baseUrl } = {}) {
@@ -6159,6 +6209,22 @@ function createHistoryClient(client, { baseUrl } = {}) {
module.exports = { createHistoryClient };
module.exports = { createHistoryClient };
},
},
+// ── 52: src/user-card.js ────────────────────────────────────────────
+function (module, exports) {
+'use strict';
+/** One public Network aggregate. Hidden/unavailable fields stay absent; no credentials are needed. */
+function createUserCardClient(client, { baseUrl } = {}) {
+ if (!client || typeof client.json !== 'function') throw new TypeError('createUserCardClient: pass an SDK core client');
+ return {
+ get(username, { signal } = {}) {
+ if (typeof username !== 'string' || !/^[A-Za-z0-9_]{3,24}$/.test(username)) throw new TypeError('invalid username');
+ return client.json({ service: 'network', audience: 'openvibe.network', baseUrl,
+ path: `/api/v1/people/${encodeURIComponent(username)}/card`, signal, auth: false, credentials: 'omit' });
+ },
+ };
+}
+module.exports = { createUserCardClient };
+},
];
];
const __cache = new Array(__defs.length);
const __cache = new Array(__defs.length);
function __load(i) {
function __load(i) {
@@ -6178,6 +6244,6 @@ export const {
@@ -6178,6 +6244,6 @@ export const {
realtime, media, cam, mediaUpload, ui, community,
realtime, media, cam, mediaUpload, ui, community,
homeFeed, bot, search, bench, meme, vision,
homeFeed, bot, search, bench, meme, vision,
themes, design, redact, chat, ai, credentials,
themes, design, redact, chat, ai, credentials,
- jobs, tools, projects, geo, history,
+ jobs, tools, projects, geo, history, userCard,
} = sdk;
} = sdk;
export default sdk;
export default sdk;
@@ -74,7 +74,8 @@
@@ -74,7 +74,8 @@
"createChatClient",
"createChatClient",
"createFeedPublisher",
"createFeedPublisher",
"createInboxVisitor",
"createInboxVisitor",
- "history"
+ "history",
+ "readEmbeds"
]
]
},
},
"chatApps": {
"chatApps": {
@@ -465,6 +466,11 @@
@@ -465,6 +466,11 @@
"validateUsageSample"
"validateUsageSample"
]
]
},
},
+ "userCard": {
+ "object": [
+ "createUserCardClient"
+ ]
+ },
"video": {
"video": {
"object": [
"object": [
"createVideoClient"
"createVideoClient"
@@ -600,7 +606,8 @@
@@ -600,7 +606,8 @@
"attach",
"attach",
"pages"
"pages"
]
]
- }
+ },
+ "readEmbeds": "function"
},
},
"openvibe-sdk/chat-apps": {
"openvibe-sdk/chat-apps": {
"APP_LIMITS": {
"APP_LIMITS": {
@@ -1255,6 +1262,9 @@
@@ -1255,6 +1262,9 @@
"usageSample": "function",
"usageSample": "function",
"validateUsageSample": "function"
"validateUsageSample": "function"
},
},
+ "openvibe-sdk/user-card": {
+ "createUserCardClient": "function"
+ },
"openvibe-sdk/valkey": {
"openvibe-sdk/valkey": {
"createValkey": "function"
"createValkey": "function"
},
},
new file mode 100644
new file mode 100644
@@ -0,0 +1,12 @@
@@ -0,0 +1,12 @@
+# Tools worker placement
+
+```js
+const run = await tools.run('png', {}, { files: [fileBlob], prefer: 'host' });
+const done = await run.wait();
+const job = await tools.jobs.get(done.job.id);
+console.log(job.result.data.execution);
+```
+
+`prefer` is `auto` (default), `home`, or `host`, sent as `X-Tools-Prefer` for JSON and multipart requests. `host` keeps the job on the host. `home` is advisory: the owner's routing order still applies. Fetch-based jobs always stay on the host, and the owner must enable worker routing.
+
+Durable job results carry `result.data.execution`: the final worker id, location, total execution milliseconds and each attempt's location, time and outcome. Failed or cancelled jobs carry the receipt at `error.execution`. `ToolsExecutionReceipt` describes the shape. Receipts survive `tools.jobs.get(id)` and the usual run/wait helpers.
new file mode 100644
new file mode 100644
@@ -0,0 +1,17 @@
@@ -0,0 +1,17 @@
+# Public user card
+
+```js
+import { createClient, userCard } from 'openvibe-sdk';
+const cards = userCard.createUserCardClient(createClient());
+const controller = new AbortController();
+const person = await cards.get('Example', { signal: controller.signal });
+// Or: import { createUserCardClient } from 'openvibe-sdk/user-card';
+```
+
+The browser bundle exports the same `userCard` namespace. `get()` makes one public `GET /api/v1/people/:username/card` on Network; it sends neither Bearer credentials nor cookies, even when the core client has them configured. Usernames are 3–24 letters, digits or underscores. Standard SDK deadlines, cancellation and errors apply; the owner switch being off returns HTTP 503 `user_card.disabled`.
+
+`UserCard` always has `username` and `profile_url`. The optional fields are `display_name`, `avatar_url`, `channel_url`, `level`, `streak`, `badges_count`, `followers`, `active_sites: {id,name,url}[]`, and `live: {now:false} | {now:true,site:'live',url}`. Network owns the global level; Quest supplies daily streak and badge count. A field omitted for privacy or an unavailable source remains absent. Never turn an absent count into zero or absent live state into offline.
+
+Network caches the aggregate for 30 seconds, coalesces concurrent misses and rechecks privacy/account eligibility before cache use. HTTP responses use `no-store`; this SDK adds no cache. Weekly sites need the person's opt-in and expose site names only from the last seven days of Network history.
+
+Next for the design (For Fable): Shared's `OVUser.card` consumes this shape; visual presentation and the visibility controls are a separate task.
@@ -2,6 +2,6 @@
@@ -2,6 +2,6 @@
import cjs from '../src/chat.js';
import cjs from '../src/chat.js';
export const {
export const {
- createChatClient, createInboxVisitor, createFeedPublisher, history,
+ createChatClient, createInboxVisitor, createFeedPublisher, history, readEmbeds,
} = cjs;
} = cjs;
export default cjs;
export default cjs;
@@ -15,6 +15,6 @@ export const {
@@ -15,6 +15,6 @@ export const {
deals, shoes, trade, space, host, news,
deals, shoes, trade, space, host, news,
food, actor, run, video, pics, work,
food, actor, run, video, pics, work,
zone, git, play, download, openre, geo,
zone, git, play, download, openre, geo,
- history, usage, commerce, moneyReasons, telemetry,
+ history, usage, commerce, moneyReasons, telemetry, userCard,
} = cjs;
} = cjs;
export default cjs;
export default cjs;
new file mode 100644
new file mode 100644
@@ -0,0 +1,7 @@
@@ -0,0 +1,7 @@
+// Generated by scripts/esm.js from src/user-card.js. Do not edit.
+import cjs from '../src/user-card.js';
+
+export const {
+ createUserCardClient,
+} = cjs;
+export default cjs;
@@ -74,4 +74,5 @@ module.exports = {
@@ -74,4 +74,5 @@ module.exports = {
commerce: require('./src/commerce'),
commerce: require('./src/commerce'),
moneyReasons: require('./src/money-reasons'),
moneyReasons: require('./src/money-reasons'),
telemetry: require('./src/telemetry'),
telemetry: require('./src/telemetry'),
+ userCard: require('./src/user-card'),
};
};
@@ -1,12 +1,12 @@
@@ -1,12 +1,12 @@
{
{
"name": "openvibe-sdk",
"name": "openvibe-sdk",
- "version": "0.146.0",
+ "version": "0.147.0",
"lockfileVersion": 3,
"lockfileVersion": 3,
"requires": true,
"requires": true,
"packages": {
"packages": {
"": {
"": {
"name": "openvibe-sdk",
"name": "openvibe-sdk",
- "version": "0.146.0",
+ "version": "0.147.0",
"license": "MIT",
"license": "MIT",
"bin": {
"bin": {
"openvibe-download": "bin/openvibe-download.js"
"openvibe-download": "bin/openvibe-download.js"
@@ -1,6 +1,6 @@
@@ -1,6 +1,6 @@
{
{
"name": "openvibe-sdk",
"name": "openvibe-sdk",
- "version": "0.146.0",
+ "version": "0.147.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.",
"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",
"main": "index.js",
"types": "types/index.d.ts",
"types": "types/index.d.ts",
@@ -589,6 +589,11 @@
@@ -589,6 +589,11 @@
"types": "./types/levels.d.ts",
"types": "./types/levels.d.ts",
"import": "./esm/levels.mjs",
"import": "./esm/levels.mjs",
"default": "./src/levels.js"
"default": "./src/levels.js"
+ },
+ "./user-card": {
+ "types": "./types/user-card.d.ts",
+ "import": "./esm/user-card.mjs",
+ "default": "./src/user-card.js"
}
}
},
},
"bin": {
"bin": {
@@ -12,6 +12,7 @@ const path = require('path');
@@ -12,6 +12,7 @@ const path = require('path');
const ROOT = path.join(__dirname, '..');
const ROOT = path.join(__dirname, '..');
const ENTRIES = {
const ENTRIES = {
+ 'user-card.mjs': '../src/user-card.js',
'wallet.mjs': '../src/wallet.js',
'wallet.mjs': '../src/wallet.js',
'compute.mjs': '../src/compute/index.js',
'compute.mjs': '../src/compute/index.js',
'share.mjs': '../src/share.js',
'share.mjs': '../src/share.js',
@@ -31,6 +31,32 @@ const { isOpenVibeError } = require('./core/errors');
@@ -31,6 +31,32 @@ const { isOpenVibeError } = require('./core/errors');
const enc = encodeURIComponent;
const enc = encodeURIComponent;
const history = require('./chat-history');
const history = require('./chat-history');
+/** The kinds chat.embed@1 names; anything else is not a preview this SDK returns. */
+const EMBED_KINDS = new Set(['link', 'video', 'image', 'live', 'picture', 'design', 'post', 'profile', 'game']);
+
+/** One chat.embed@1 object as the typed shape, or null when it is not one. Data only: never markup. */
+function embedOf(value) {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+ if (!EMBED_KINDS.has(value.kind)) return null;
+ if (typeof value.url !== 'string' || !value.url) return null;
+ if (typeof value.site_name !== 'string' || typeof value.title !== 'string' || !value.title || typeof value.description !== 'string') return null;
+ if (!(value.image === null || typeof value.image === 'string')) return null;
+ if (!Number.isInteger(value.width) || !Number.isInteger(value.height) || value.width < 0 || value.height < 0) return null;
+ const embed = {
+ kind: value.kind, url: value.url, site_name: value.site_name, title: value.title,
+ description: value.description, image: value.image, width: value.width, height: value.height,
+ };
+ if (typeof value.by === 'string' && value.by) embed.by = value.by;
+ if (typeof value.live === 'boolean') embed.live = value.live;
+ return embed;
+}
+
+/** The address previews a message carries (chat.embed@1), typed: [] when there are none. */
+function readEmbeds(message) {
+ if (!message || !Array.isArray(message.embeds)) return [];
+ return message.embeds.map(embedOf).filter(Boolean);
+}
+
function createChatClient(client, defaults = {}) {
function createChatClient(client, defaults = {}) {
const { baseUrl } = defaults;
const { baseUrl } = defaults;
const call = (opts, o = {}) => client.json({ service: 'chat', baseUrl, audience: 'openvibe.chat', ...opts, signal: o.signal });
const call = (opts, o = {}) => client.json({ service: 'chat', baseUrl, audience: 'openvibe.chat', ...opts, signal: o.signal });
@@ -44,6 +70,8 @@ function createChatClient(client, defaults = {}) {
@@ -44,6 +70,8 @@ function createChatClient(client, defaults = {}) {
return {
return {
/** Shared async page iterator and scroll-preserving DOM history controller. */
/** Shared async page iterator and scroll-preserving DOM history controller. */
history,
history,
+ /** The typed address previews on a message (chat.embed@1): [] when it has none. */
+ embeds: (message) => readEmbeds(message),
/** Vibe's model comparison API, authenticated as the person. */
/** Vibe's model comparison API, authenticated as the person. */
ask: (input, o = {}) => call({ method: 'POST', path: '/api/vibe/ask', json: input, ...once }, o),
ask: (input, o = {}) => call({ method: 'POST', path: '/api/vibe/ask', json: input, ...once }, o),
pick: (messageId, model, o = {}) => call({ method: 'POST', path: '/api/vibe/pick', json: { message_id: messageId, model }, ...once }, o),
pick: (messageId, model, o = {}) => call({ method: 'POST', path: '/api/vibe/pick', json: { message_id: messageId, model }, ...once }, o),
@@ -76,7 +104,10 @@ function createChatClient(client, defaults = {}) {
@@ -76,7 +104,10 @@ function createChatClient(client, defaults = {}) {
update: (slug, patch, o = {}) => call({ method: 'PATCH', path: room(slug), json: patch, ...once }, o),
update: (slug, patch, o = {}) => call({ method: 'PATCH', path: room(slug), json: patch, ...once }, o),
/** query: before | after (message id), limit */
/** query: before | after (message id), limit */
messages: (slug, query = {}, o = {}) => call({ path: `${room(slug)}/messages`, query }, o),
messages: (slug, query = {}, o = {}) => call({ path: `${room(slug)}/messages`, query }, o),
- send: (slug, message, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages`, json: { message }, ...once }, o),
+ /** extra: { reply_to_id } answers one of the room's messages. */
+ send: (slug, message, extra = {}, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages`, json: { message, ...extra }, ...once }, o),
+ /** reaction: thumbsup | thumbsdown | heart | laugh | surprised | sad. The same one again takes it back. */
+ react: (slug, messageId, reaction, o = {}) => call({ method: 'POST', path: `${room(slug)}/messages/${enc(messageId)}/react`, json: { reaction }, ...once }, o),
deleteMessage: (slug, id, o = {}) => call({ method: 'DELETE', path: `${room(slug)}/messages/${enc(id)}`, ...once }, o),
deleteMessage: (slug, id, o = {}) => call({ method: 'DELETE', path: `${room(slug)}/messages/${enc(id)}`, ...once }, o),
join: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/join`, ...once }, o),
join: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/join`, ...once }, o),
leave: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/leave`, ...once }, o),
leave: (slug, o = {}) => call({ method: 'POST', path: `${room(slug)}/leave`, ...once }, o),
@@ -92,7 +123,8 @@ function createChatClient(client, defaults = {}) {
@@ -92,7 +123,8 @@ function createChatClient(client, defaults = {}) {
get: (id, o = {}) => orNull(call({ path: conv(id) }, o)),
get: (id, o = {}) => orNull(call({ path: conv(id) }, o)),
/** query: limit, before */
/** query: limit, before */
messages: (id, query = {}, o = {}) => call({ path: `${conv(id)}/messages`, query }, o),
messages: (id, query = {}, o = {}) => call({ path: `${conv(id)}/messages`, query }, o),
- send: (id, message, o = {}) => call({ method: 'POST', path: `${conv(id)}/messages`, json: { message }, ...once }, o),
+ /** extra: { reply_to_id } answers one of the conversation's messages. */
+ send: (id, message, extra = {}, o = {}) => call({ method: 'POST', path: `${conv(id)}/messages`, json: { message, ...extra }, ...once }, o),
deleteMessage: (id, msgId, o = {}) => call({ method: 'DELETE', path: `${conv(id)}/messages/${enc(msgId)}`, ...once }, o),
deleteMessage: (id, msgId, o = {}) => call({ method: 'DELETE', path: `${conv(id)}/messages/${enc(msgId)}`, ...once }, o),
read: (id, o = {}) => call({ method: 'POST', path: `${conv(id)}/read`, ...once }, o),
read: (id, o = {}) => call({ method: 'POST', path: `${conv(id)}/read`, ...once }, o),
unread: (o = {}) => call({ path: '/api/dm/unread' }, o),
unread: (o = {}) => call({ path: '/api/dm/unread' }, o),
@@ -103,6 +135,21 @@ function createChatClient(client, defaults = {}) {
@@ -103,6 +135,21 @@ function createChatClient(client, defaults = {}) {
viewPreference: (id, o = {}) => call({ path: `${conv(id)}/view` }, o),
viewPreference: (id, o = {}) => call({ path: `${conv(id)}/view` }, o),
setViewPreference: (id, view, o = {}) => call({ method: 'PUT', path: `${conv(id)}/view`, json: { view }, ...once }, o),
setViewPreference: (id, view, o = {}) => call({ method: 'PUT', path: `${conv(id)}/view`, json: { view }, ...once }, o),
},
},
+ /**
+ * What happened to you in Chat, newest first (server/chat/activity.js in OpenVibe.Chat): mentions, replies to
+ * your messages, reactions to them, server invites, accepted friend requests and roles given to you.
+ * query: { limit, before (the last row's id), kind: 'mention' | … | 'mention,reply' }
+ */
+ activity: {
+ /** → { items, next_before, unread } */
+ list: (query = {}, o = {}) => call({ path: '/api/v1/activity', query }, o),
+ /** → { unread } */
+ unread: (o = {}) => call({ path: '/api/v1/activity/unread' }, o),
+ /** One row: POST /api/v1/activity/:id/read → { ok, read, unread } */
+ readOne: (id, o = {}) => call({ method: 'POST', path: `/api/v1/activity/${enc(id)}/read`, ...once }, o),
+ /** No ids: all of it. → { ok, read, unread } */
+ read: (ids = null, o = {}) => call({ method: 'POST', path: '/api/v1/activity/read', json: ids == null ? { all: true } : { ids: [].concat(ids) }, ...once }, o),
+ },
/** Every message you sent that is still visible: { username, total, truncated, messages } (JSON). */
/** Every message you sent that is still visible: { username, total, truncated, messages } (JSON). */
exportMine: (o = {}) => call({ path: '/api/chat/me/export' }, o),
exportMine: (o = {}) => call({ path: '/api/chat/me/export' }, o),
/** Vibe, OpenVibe's assistant: the person's chats with it (people only; an API token gets 403). */
/** Vibe, OpenVibe's assistant: the person's chats with it (people only; an API token gets 403). */
@@ -261,4 +308,4 @@ function createFeedPublisher(client, { feed, key, baseUrl } = {}) {
@@ -261,4 +308,4 @@ function createFeedPublisher(client, { feed, key, baseUrl } = {}) {
};
};
}
}
-module.exports = { createChatClient, createInboxVisitor, createFeedPublisher, history };
+module.exports = { createChatClient, createInboxVisitor, createFeedPublisher, history, readEmbeds };
@@ -8,7 +8,7 @@ const { paginate, offsetPager } = require('./paginate');
@@ -8,7 +8,7 @@ const { paginate, offsetPager } = require('./paginate');
const semver = require('./semver');
const semver = require('./semver');
/** The package version (test/version.test.js keeps it equal to package.json). */
/** The package version (test/version.test.js keeps it equal to package.json). */
-const SDK_VERSION = '0.146.0';
+const SDK_VERSION = '0.147.0';
module.exports = {
module.exports = {
createClient,
createClient,
@@ -15,6 +15,11 @@
@@ -15,6 +15,11 @@
* await quest.appQuests.list(); // { project_id, max, quests }
* await quest.appQuests.list(); // { project_id, max, quests }
* await quest.appQuests.retire('collector'); // completions and badges stay
* await quest.appQuests.retire('collector'); // completions and badges stay
*
*
+ * The card any site can show reads today's quest and what waits on Quest, with a person's Network token:
+ * await quest.cardData({ token, timeZone }); // { signed_in, quest, more: { quests, sites, mine } }
+ * It makes the same three reads OpenVibe.Live's server makes (/daily or /me/daily, /quests and /me/quests), keeps the
+ * catalog ten minutes, and never sends a browser cookie: the site fetches it server-side and passes the token.
+ *
* Errors are OpenVibeError (status, code): quest.app_only (not an app token with a project), quest.foreign_event (a
* Errors are OpenVibeError (status, code): quest.app_only (not an app token with a project), quest.foreign_event (a
* step names another project's events), quest.invalid, quest.limit, capability.denied.
* step names another project's events), quest.invalid, quest.limit, capability.denied.
*/
*/
@@ -38,6 +43,33 @@ function eventType(projectId, name) {
@@ -38,6 +43,33 @@ function eventType(projectId, name) {
function createQuestClient(client, { baseUrl } = {}) {
function createQuestClient(client, { baseUrl } = {}) {
if (!client || typeof client.json !== 'function') throw new TypeError('createQuestClient: pass an openvibe-sdk/core client');
if (!client || typeof client.json !== 'function') throw new TypeError('createQuestClient: pass an openvibe-sdk/core client');
const call = (opts) => client.json({ service: 'quest', baseUrl, audience: 'openvibe.quest', ...opts });
const call = (opts) => client.json({ service: 'quest', baseUrl, audience: 'openvibe.quest', ...opts });
+ const CATALOG_TTL_MS = 10 * 60 * 1000;
+ let catalog = null; // { at, value: { quests, sites } }, the public catalog
+ const soft = (p) => p.catch(() => null); // a door figure never costs the card itself
+ const get = (path, token, opts = {}) => call({ path, token, timeoutMs: 4500, ...opts });
+ /** How many quests and sites the public catalog has; one read per ten minutes. */
+ const counts = async (token) => {
+ if (catalog && Date.now() - catalog.at < CATALOG_TTL_MS) return catalog.value;
+ const all = await soft(get('/api/v1/quests', token));
+ if (!all || !Array.isArray(all.quests)) return null;
+ const value = { quests: all.quests.length, sites: Array.isArray(all.sites) ? all.sites.length : 0 };
+ catalog = { at: Date.now(), value };
+ return value;
+ };
+ /** A person's badges and quest states, as counts. */
+ const mine = async (token) => {
+ const me = token ? await soft(get('/api/v1/me/quests', token)) : null;
+ if (!me || !Array.isArray(me.quests)) return null;
+ return {
+ badges: Array.isArray(me.badges) ? me.badges.length : 0,
+ in_progress: me.quests.filter((q) => q && q.state === 'in_progress').length,
+ completed: me.quests.filter((q) => q && q.state === 'completed').length,
+ };
+ };
+ const withMore = async (result, token) => {
+ const [cat, own] = await Promise.all([counts(token), mine(token)]);
+ return { ...result, more: { ...(cat || {}), ...(own ? { mine: own } : {}) } };
+ };
const appQuests = {
const appQuests = {
/** Create or replace one of your app's quests (quest.app-quest-request@1) → quest.app-quest@1. */
/** Create or replace one of your app's quests (quest.app-quest-request@1) → quest.app-quest@1. */
define: (slug, quest, { signal } = {}) => call({ method: 'PUT', path: `/api/v1/app-quests/${enc(slug)}`, json: quest, signal, idempotencyKey: false }),
define: (slug, quest, { signal } = {}) => call({ method: 'PUT', path: `/api/v1/app-quests/${enc(slug)}`, json: quest, signal, idempotencyKey: false }),
@@ -46,8 +78,29 @@ function createQuestClient(client, { baseUrl } = {}) {
@@ -46,8 +78,29 @@ function createQuestClient(client, { baseUrl } = {}) {
/** Retire one: no longer counted or listed; its completions and badges stay. → quest.app-quest@1 */
/** Retire one: no longer counted or listed; its completions and badges stay. → quest.app-quest@1 */
retire: (slug, { signal } = {}) => call({ method: 'DELETE', path: `/api/v1/app-quests/${enc(slug)}`, signal }),
retire: (slug, { signal } = {}) => call({ method: 'DELETE', path: `/api/v1/app-quests/${enc(slug)}`, signal }),
};
};
+ /**
+ * The daily quest card's data, with the same three Quest reads Live makes. Signed out reads the public today
+ * question; a token reads the person's own checklist and can send `timeZone` for their local day. Returns null
+ * when the quest itself cannot be read; the catalog and the person's log are best-effort.
+ */
+ const cardData = async ({ token = null, timeZone = 'UTC' } = {}) => {
+ try {
+ if (!token) {
+ const [quest, extra] = await Promise.all([get('/api/v1/daily', null), withMore({}, null)]);
+ return quest && { signed_in: false, quest, ...extra };
+ }
+ if (timeZone && /^[A-Za-z0-9_+\/-]{1,64}$/.test(timeZone)) {
+ await soft(get('/api/v1/me/daily/time-zone', token, {
+ method: 'PUT', json: { time_zone: timeZone }, idempotencyKey: false,
+ }));
+ }
+ const [quest, extra] = await Promise.all([get('/api/v1/me/daily', token), withMore({}, token)]);
+ if (!quest) return null;
+ return { signed_in: true, quest, ...extra };
+ } catch { return null; }
+ };
return {
return {
- appQuests, eventType, projectKey,
+ appQuests, eventType, projectKey, cardData,
/** The network-wide quest for today, or a past YYYY-MM-DD date (quest.daily@1). */
/** The network-wide quest for today, or a past YYYY-MM-DD date (quest.daily@1). */
daily: ({ date, signal } = {}) => call({ path: date ? `/api/v1/daily/${enc(date)}` : '/api/v1/daily', signal }),
daily: ({ date, signal } = {}) => call({ path: date ? `/api/v1/daily/${enc(date)}` : '/api/v1/daily', signal }),
/** This signed-in person's guided quest for today (requires a person token). */
/** This signed-in person's guided quest for today (requires a person token). */
@@ -212,8 +212,9 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope
@@ -212,8 +212,9 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope
* A request refused before the tool ran (404 tools.tool.not_found | not_runnable, 422
* A request refused before the tool ran (404 tools.tool.not_found | not_runnable, 422
* tools.input.invalid, 403 capability.denied, 503 tools.tool.unavailable…) throws OpenVibeError.
* tools.input.invalid, 403 capability.denied, 503 tools.tool.unavailable…) throws OpenVibeError.
*/
*/
- async function run(id, input = {}, { files, waitMs, idempotencyKey, signal, timeoutMs } = {}) {
+ async function run(id, input = {}, { files, waitMs, idempotencyKey, signal, timeoutMs, prefer } = {}) {
checkId(id, 'tools.run');
checkId(id, 'tools.run');
+ if (prefer != null && !['auto', 'home', 'host'].includes(prefer)) throw new TypeError('tools.run: prefer must be auto, home or host');
if (input == null) input = {};
if (input == null) input = {};
if (typeof input !== 'object' || Array.isArray(input)) throw new TypeError('tools.run: input must be an object');
if (typeof input !== 'object' || Array.isArray(input)) throw new TypeError('tools.run: input must be an object');
if (waitMs != null && (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > MAX_WAIT_MS)) throw new TypeError(`tools.run: waitMs is an integer, 0..${MAX_WAIT_MS}`);
if (waitMs != null && (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > MAX_WAIT_MS)) throw new TypeError(`tools.run: waitMs is an integer, 0..${MAX_WAIT_MS}`);
@@ -232,6 +233,7 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope
@@ -232,6 +233,7 @@ function createToolsClient(client, { baseUrl, service = 'tools', audience = 'ope
const key = idempotencyKey || newIdempotencyKey();
const key = idempotencyKey || newIdempotencyKey();
const opts = { method: 'POST', path: `/api/v1/tools/${enc(id)}/run`, idempotencyKey: key, signal };
const opts = { method: 'POST', path: `/api/v1/tools/${enc(id)}/run`, idempotencyKey: key, signal };
+ if (prefer != null) opts.headers = { 'X-Tools-Prefer': prefer };
if (uploads.length) {
if (uploads.length) {
const form = new FormData();
const form = new FormData();
form.append('input', JSON.stringify(input));
form.append('input', JSON.stringify(input));
new file mode 100644
new file mode 100644
@@ -0,0 +1,13 @@
@@ -0,0 +1,13 @@
+'use strict';
+/** One public Network aggregate. Hidden/unavailable fields stay absent; no credentials are needed. */
+function createUserCardClient(client, { baseUrl } = {}) {
+ if (!client || typeof client.json !== 'function') throw new TypeError('createUserCardClient: pass an SDK core client');
+ return {
+ get(username, { signal } = {}) {
+ if (typeof username !== 'string' || !/^[A-Za-z0-9_]{3,24}$/.test(username)) throw new TypeError('invalid username');
+ return client.json({ service: 'network', audience: 'openvibe.network', baseUrl,
+ path: `/api/v1/people/${encodeURIComponent(username)}/card`, signal, auth: false, credentials: 'omit' });
+ },
+ };
+}
+module.exports = { createUserCardClient };
@@ -7,7 +7,7 @@
@@ -7,7 +7,7 @@
const assert = require('node:assert/strict');
const assert = require('node:assert/strict');
const { stubServer, send, run } = require('./helpers');
const { stubServer, send, run } = require('./helpers');
const { createClient } = require('../src/core');
const { createClient } = require('../src/core');
-const { createChatClient, createInboxVisitor, createFeedPublisher, history } = require('../src/chat');
+const { createChatClient, createInboxVisitor, createFeedPublisher, history, readEmbeds } = require('../src/chat');
async function chatStub() {
async function chatStub() {
let busy = 0;
let busy = 0;
@@ -20,6 +20,17 @@ async function chatStub() {
@@ -20,6 +20,17 @@ async function chatStub() {
}
}
run([
run([
+ ['embeds reads chat.embed@1 and returns the typed shape, dropping what is not one', async () => {
+ const chat = createChatClient(createClient({ baseUrls: { chat: 'http://127.0.0.1:9' }, token: 'person-token' }));
+ const link = { kind: 'link', url: 'https://example.com/a', site_name: 'Example', title: 'A story', description: 'What happened', image: null, width: 640, height: 360 };
+ const live = { kind: 'live', url: 'https://openvibe.live/@streamer', site_name: 'OpenVibe.Live', title: 'The Streamer', description: '', image: 'https://openvibe.media/avatars/s.jpg', width: 0, height: 0, by: 'streamer', live: true };
+ assert.deepEqual(chat.embeds({ embeds: [link, live] }), [link, live]);
+ assert.deepEqual(chat.embeds({ embeds: [link, { ...link, kind: 'article' }, { ...link, title: '' }, null, 'x'] }), [link], 'only real embeds come back');
+ assert.deepEqual(Object.keys(chat.embeds({ embeds: [{ ...link, extra: 'dropped' }] })[0]).sort(), Object.keys(link).sort());
+ assert.deepEqual(chat.embeds({}), []);
+ assert.deepEqual(chat.embeds(null), []);
+ assert.deepEqual(readEmbeds({ embeds: [live] }), [live], 'the reader is exported too');
+ }],
['the ESM chat entry exports the shared history helper', async () => {
['the ESM chat entry exports the shared history helper', async () => {
const esm = await import('../esm/chat.mjs');
const esm = await import('../esm/chat.mjs');
assert.equal(typeof esm.history.pages, 'function');
assert.equal(typeof esm.history.pages, 'function');
@@ -152,6 +163,30 @@ run([
@@ -152,6 +163,30 @@ run([
assert.equal(srv.requests[6].headers.authorization, undefined, 'a feed is read without the person\'s token');
assert.equal(srv.requests[6].headers.authorization, undefined, 'a feed is read without the person\'s token');
await srv.close();
await srv.close();
}],
}],
+ ['activity: the person\'s feed, its unread count and marking read; replies and reactions', async () => {
+ const srv = await chatStub();
+ const chat = createChatClient(createClient({ baseUrls: { chat: srv.url }, token: 'person-token' }));
+ await chat.activity.list({ limit: 2, before: 9, kind: 'mention' });
+ await chat.activity.unread();
+ await chat.activity.readOne(7);
+ await chat.activity.read([1, 2]);
+ await chat.activity.read();
+ await chat.rooms.send('builders', 'first!', { reply_to_id: 5 });
+ await chat.rooms.react('builders', 9, 'heart');
+ await chat.dms.send(7, 'hi', { reply_to_id: 3 });
+ const got = srv.requests.map((r) => [r.method, r.url, r.body && String(r.body).length ? JSON.parse(String(r.body)) : null]);
+ assert.deepEqual(got, [
+ ['GET', '/api/v1/activity?limit=2&before=9&kind=mention', null],
+ ['GET', '/api/v1/activity/unread', null],
+ ['POST', '/api/v1/activity/7/read', null],
+ ['POST', '/api/v1/activity/read', { ids: [1, 2] }],
+ ['POST', '/api/v1/activity/read', { all: true }],
+ ['POST', '/api/chat/rooms/builders/messages', { message: 'first!', reply_to_id: 5 }],
+ ['POST', '/api/chat/rooms/builders/messages/9/react', { reaction: 'heart' }],
+ ['POST', '/api/dm/conversations/7/messages', { message: 'hi', reply_to_id: 3 }],
+ ]);
+ await srv.close();
+ }],
['an inbox visitor needs no account and keeps its token; a feed publisher sends the key', async () => {
['an inbox visitor needs no account and keeps its token; a feed publisher sends the key', async () => {
const INBOX = `inb_${'A'.repeat(26)}`; const FEED = `fed_${'B'.repeat(26)}`; const KEY = `ovf_${'k'.repeat(32)}`;
const INBOX = `inb_${'A'.repeat(26)}`; const FEED = `fed_${'B'.repeat(26)}`; const KEY = `ovf_${'k'.repeat(32)}`;
let fails = 1;
let fails = 1;
@@ -10,7 +10,7 @@ const assert = require('node:assert/strict');
@@ -10,7 +10,7 @@ const assert = require('node:assert/strict');
const { stubServer, send, run, sleep } = require('./helpers');
const { stubServer, send, run, sleep } = require('./helpers');
const { createMachines, DEFAULT_TIMEOUT_MS } = require('../src/machines');
const { createMachines, DEFAULT_TIMEOUT_MS } = require('../src/machines');
-const MACHINE = { id: 'dev_01ARZ3NDEKTSV4RRFFQ69G5FAV', kind: 'server', online: true, roles: ['codes.worker'], running: [] };
+const MACHINE = { id: 'dev_01ARZ3NDEKTSV4RRFFQ69G5FAV', kind: 'server', online: true, roles: ['codes.worker'], running: [], system: 'Linux', can_run: ['worker'] };
async function hub(answer) {
async function hub(answer) {
const state = { requests: [], token: 'person-token' };
const state = { requests: [], token: 'person-token' };
@@ -58,6 +58,8 @@ run([
@@ -58,6 +58,8 @@ run([
const list = await machines.list();
const list = await machines.list();
assert.equal(list.machines.length, 1);
assert.equal(list.machines.length, 1);
assert.equal(list.machines[0].id, MACHINE.id);
assert.equal(list.machines[0].id, MACHINE.id);
+ assert.equal(list.machines[0].system, 'Linux');
+ assert.deepEqual(list.machines[0].can_run, ['worker']);
assert.equal((await machines.get(MACHINE.id)).machine.kind, 'server');
assert.equal((await machines.get(MACHINE.id)).machine.kind, 'server');
assert.equal((await machines.catalogue()).roles[0].id, 'codes.worker');
assert.equal((await machines.catalogue()).roles[0].id, 'codes.worker');
assert.equal((await machines.pair()).pairing.code, 'ABCD-EFGH');
assert.equal((await machines.pair()).pairing.code, 'ABCD-EFGH');
@@ -72,7 +72,7 @@ run([
@@ -72,7 +72,7 @@ run([
})().catch((err) => { console.error(err); process.exit(1); });`;
})().catch((err) => { console.error(err); process.exit(1); });`;
const res = execFileSync(process.execPath, ['-e', script], { cwd: app, encoding: 'utf8' });
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.match(res, new RegExp(`consumer ok: ${subpaths.length} subpaths \\+ the browser bundle`));
- assert.equal(subpaths.length, 102); // history adds the 102nd subpath after levels.
+ assert.equal(subpaths.length, 103); // user-card adds the 103rd subpath after history.
assert.ok(!fs.existsSync(path.join(app, 'node_modules/openvibe-contracts')), 'the optional peer is not installed');
assert.ok(!fs.existsSync(path.join(app, 'node_modules/openvibe-contracts')), 'the optional peer is not installed');
} finally {
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
fs.rmSync(tmp, { recursive: true, force: true });
new file mode 100644
new file mode 100644
@@ -0,0 +1,116 @@
@@ -0,0 +1,116 @@
+'use strict';
+// openvibe-sdk/quest cardData: the same three Quest reads Live's server makes — today's quest (/daily or /me/daily),
+// the public catalog (/quests) and the person's log (/me/quests) — with the catalog kept ten minutes, best-effort
+// door figures, and null when the quest itself cannot be read.
+const assert = require('node:assert/strict');
+const { createQuestClient } = require('../src/quest');
+
+const steps = [
+ { id: 'pics', event_type: 'mediahub.picture.uploaded', site: 'openvibe.pics', sentence: 'Upload a picture', href: 'https://openvibe.pics/', count: 1, progress: 1, done: true },
+ { id: 'chat', event_type: 'chat.room.message.created', site: 'openvibe.chat', sentence: 'Send a public chat message', href: 'https://openvibe.chat/', count: 1, progress: 0, done: false },
+];
+const publicQuest = { date: '2026-11-10', title: 'Make something today', story: 'Three small things, across the network.', steps, finished_today: 12 };
+const myQuest = { ...publicQuest, steps, progress: 1, streak: 5, completed: false, time_zone: 'Europe/London' };
+const catalog = { quests: Array.from({ length: 12 }, (_, i) => ({ id: `q${i}` })), sites: Array.from({ length: 6 }, (_, i) => ({ site: `s${i}` })) };
+
+function fake(overrides = {}) {
+ const calls = [];
+ const client = {
+ json: async (opts) => {
+ calls.push(opts);
+ const answer = Object.prototype.hasOwnProperty.call(overrides, opts.path) ? overrides[opts.path] : {
+ '/api/v1/daily': publicQuest,
+ '/api/v1/me/daily': myQuest,
+ '/api/v1/quests': catalog,
+ '/api/v1/me/quests': {
+ quests: [{ state: 'completed' }, { state: 'completed' }, { state: 'in_progress' }, { state: 'not_started' }],
+ badges: [{ id: 'b1' }, { id: 'b2' }, { id: 'b3' }],
+ },
+ '/api/v1/me/daily/time-zone': { ok: true },
+ }[opts.path];
+ if (answer instanceof Error) throw answer;
+ return answer;
+ },
+ };
+ return { quest: createQuestClient(client, { baseUrl: 'http://quest.test' }), calls };
+}
+
+(async () => {
+ // Signed out: the public quest and the catalog. No person's log and no time-zone write.
+ {
+ const { quest, calls } = fake();
+ const data = await quest.cardData({ timeZone: 'Europe/London' });
+ assert.equal(data.signed_in, false);
+ assert.equal(data.quest.title, 'Make something today');
+ assert.deepEqual(data.more, { quests: 12, sites: 6 });
+ assert.deepEqual(calls.map((c) => c.path).sort(), ['/api/v1/daily', '/api/v1/quests']);
+ assert.equal(calls.find((c) => c.path === '/api/v1/daily').token, null);
+ assert.equal(calls.find((c) => c.path === '/api/v1/quests').token, null);
+ assert.equal(calls.find((c) => c.path === '/api/v1/daily').audience, 'openvibe.quest');
+ assert.equal(calls.find((c) => c.path === '/api/v1/daily').service, 'quest');
+ assert.equal(calls.find((c) => c.path === '/api/v1/daily').baseUrl, 'http://quest.test');
+ assert.equal(calls.find((c) => c.path === '/api/v1/daily').timeoutMs, 4500);
+ }
+
+ // Signed in: time zone first, then the person's quest and log; the catalog was read once and is reused.
+ {
+ const { quest, calls } = fake();
+ const data = await quest.cardData({ token: 'tok_123', timeZone: 'Europe/London' });
+ assert.equal(data.signed_in, true);
+ assert.equal(data.quest.streak, 5);
+ assert.deepEqual(data.more, { quests: 12, sites: 6, mine: { badges: 3, in_progress: 1, completed: 2 } });
+ assert.equal(calls[0].path, '/api/v1/me/daily/time-zone');
+ assert.equal(calls[0].method, 'PUT');
+ assert.deepEqual(calls[0].json, { time_zone: 'Europe/London' });
+ assert.equal(calls[0].idempotencyKey, false);
+ assert.ok(calls.every((c) => c.token === 'tok_123'), 'the person token is on every read');
+ assert.deepEqual(calls.slice(1).map((c) => c.path).sort(), ['/api/v1/me/daily', '/api/v1/me/quests', '/api/v1/quests']);
+
+ // A second card read reuses the catalog; an invalid time zone is not sent.
+ const before = calls.filter((c) => c.path === '/api/v1/quests').length;
+ await quest.cardData({ token: 'tok_123', timeZone: 'not a zone' });
+ assert.equal(calls.filter((c) => c.path === '/api/v1/quests').length, before, 'catalog cached');
+ assert.equal(calls.filter((c) => c.path === '/api/v1/me/daily/time-zone').length, 1, 'invalid zone skipped');
+ }
+
+ // The catalog is kept ten minutes, then read again.
+ {
+ const { quest, calls } = fake();
+ const realNow = Date.now;
+ let clock = 1_000_000;
+ Date.now = () => clock;
+ try {
+ await quest.cardData();
+ assert.equal(calls.filter((c) => c.path === '/api/v1/quests').length, 1);
+ clock += 10 * 60 * 1000 - 1;
+ await quest.cardData();
+ assert.equal(calls.filter((c) => c.path === '/api/v1/quests').length, 1, 'still inside ten minutes');
+ clock += 2;
+ await quest.cardData();
+ assert.equal(calls.filter((c) => c.path === '/api/v1/quests').length, 2, 'one second after ten minutes');
+ } finally { Date.now = realNow; }
+ }
+
+ // A door figure that fails never costs the card; a failed quest does.
+ {
+ const catalogDown = fake({ '/api/v1/quests': new Error('down') });
+ const data = await catalogDown.quest.cardData({ token: 'tok_123' });
+ assert.equal(data.signed_in, true);
+ assert.deepEqual(data.more, { mine: { badges: 3, in_progress: 1, completed: 2 } });
+
+ const logDown = fake({ '/api/v1/me/quests': new Error('down') });
+ const other = await logDown.quest.cardData({ token: 'tok_123' });
+ assert.deepEqual(other.more, { quests: 12, sites: 6 });
+
+ const everythingDown = fake({ '/api/v1/quests': new Error('down'), '/api/v1/me/quests': new Error('down') });
+ const bare = await everythingDown.quest.cardData({ token: 'tok_123' });
+ assert.deepEqual(bare.more, {});
+
+ const questDown = fake({ '/api/v1/daily': new Error('down') });
+ assert.equal(await questDown.quest.cardData(), null);
+ const myQuestDown = fake({ '/api/v1/me/daily': new Error('down') });
+ assert.equal(await myQuestDown.quest.cardData({ token: 'tok_123' }), null);
+ }
+
+ process.stdout.write('quest cardData passed\n');
+})().catch((err) => { process.stderr.write(String(err.stack || err) + '\n'); process.exit(1); });
new file mode 100644
new file mode 100644
@@ -0,0 +1,25 @@
@@ -0,0 +1,25 @@
+'use strict';
+const assert = require('node:assert/strict');
+const { createToolsClient } = require('../src/tools');
+(async () => {
+ const requests = [];
+ const execution = { worker: 'host', location: 'host', took_ms: 12, attempts: [{ worker: 'host', location: 'host', took_ms: 12, state: 'succeeded' }] };
+ const id = 'job_01K5WZX7S7Q4D2B8N3M6V1C9TR';
+ const tools = createToolsClient({ options: {}, async request(opts) {
+ requests.push(opts);
+ const body = opts.path.startsWith('/api/v1/jobs/') ? { id, state: 'succeeded', result: { data: { execution } } } : { state: 'succeeded', tool: 'png', took_ms: 12, result: { data: { execution } } };
+ return { data: body, status: 200, headers: new Headers({ 'content-type': 'application/json' }) };
+ } });
+ const first = await tools.run('png', {}, { prefer: 'host' });
+ assert.equal(requests[0].headers['X-Tools-Prefer'], 'host');
+ assert.deepEqual(requests[0].json, { input: {} }, 'preference is a header, preserving the request contract');
+ assert.deepEqual(first.result.data.execution, execution);
+ await tools.run('png', {}, { prefer: 'home', files: [{ name: 'a.png', data: new Uint8Array([1, 2]), type: 'image/png' }] });
+ assert.equal(requests[1].headers['X-Tools-Prefer'], 'home'); assert(requests[1].form instanceof FormData);
+ await tools.run('png', {}); assert.equal(requests[2].headers, undefined);
+ await assert.rejects(tools.run('png', {}, { prefer: 'somewhere' }), TypeError);
+ const job = await tools.jobs.get(id);
+ assert.equal(requests.at(-1).path, `/api/v1/jobs/${id}`);
+ assert.deepEqual(job.result.data.execution, execution);
+ console.log('tools routing: JSON/multipart preferences, validation, default and jobs.get receipts passed');
+})().catch(e => { console.error(e); process.exitCode = 1; });
new file mode 100644
new file mode 100644
@@ -0,0 +1,30 @@
@@ -0,0 +1,30 @@
+'use strict';
+const assert = require('node:assert/strict');
+const { createClient } = require('../src/core');
+const { createUserCardClient } = require('../src/user-card');
+(async () => {
+ const calls = [];
+ const hidden = { username: 'Example', profile_url: 'https://openvibe.network/@Example' };
+ const signal = new AbortController().signal;
+ const reader = createUserCardClient({ json: async options => { calls.push(options); return hidden; } }, { baseUrl: 'https://network.example' });
+ assert.deepEqual(await reader.get('Example', { signal }), hidden);
+ assert.deepEqual(calls[0], { service: 'network', audience: 'openvibe.network', baseUrl: 'https://network.example', path: '/api/v1/people/Example/card', signal, auth: false, credentials: 'omit' });
+ for (const bad of ['../admin', '', 'ab', '@Example', 'x'.repeat(25), null, ['Example']]) assert.throws(() => reader.get(bad), TypeError);
+ assert.throws(() => createUserCardClient({}), TypeError);
+ let sent, count = 0;
+ const core = createClient({ network: 'https://network.example', token: 'test-only', credentials: 'include', retries: 0, autoDiscover: false,
+ fetch: async (url, options) => { sent = { url, options }; count++; return new Response(JSON.stringify(hidden), { headers: { 'Content-Type': 'application/json' } }); } });
+ assert.deepEqual(await createUserCardClient(core).get('Example'), hidden);
+ assert.equal(count, 1, 'one HTTP aggregate read');
+ assert.equal(sent.url, 'https://network.example/api/v1/people/Example/card');
+ assert.equal(new Headers(sent.options.headers).get('authorization'), null);
+ assert.equal(sent.options.credentials, 'omit');
+ const disabled = createUserCardClient({ json: async () => { throw Object.assign(new Error('user_card.disabled'), { status: 503 }); } });
+ await assert.rejects(disabled.get('Example'), { status: 503 });
+ const esm = await import('../esm/user-card.mjs');
+ const browser = await import('../browser/openvibe-sdk.mjs');
+ assert.equal(esm.createUserCardClient, createUserCardClient);
+ assert.equal(typeof browser.userCard.createUserCardClient, 'function');
+ assert.equal(require('../index').userCard.createUserCardClient, createUserCardClient);
+ console.log('user-card: one public read, omitted fields preserved, credentials omitted, validation, errors and browser/ESM exports passed');
+})().catch(e => { console.error(e); process.exitCode = 1; });
@@ -1,3 +1,4 @@
@@ -1,3 +1,4 @@
+import * as userCard from './user-card';
/** browser/openvibe-sdk.mjs: one self-contained ES module with the browser-safe subpaths (same shape as the package's browser entry). */
/** browser/openvibe-sdk.mjs: one self-contained ES module with the browser-safe subpaths (same shape as the package's browser entry). */
import * as auth from './auth-browser';
import * as auth from './auth-browser';
import * as registry from './registry';
import * as registry from './registry';
@@ -62,8 +63,11 @@ export * as locker from './locker';
@@ -62,8 +63,11 @@ export * as locker from './locker';
export * as trust from './trust';
export * as trust from './trust';
export * as levels from './levels';
export * as levels from './levels';
+export * as userCard from './user-card';
+
declare const sdk: typeof core & {
declare const sdk: typeof core & {
createWalletClient: typeof createWalletClient;
createWalletClient: typeof createWalletClient;
+ userCard: typeof userCard;
auth: typeof auth; registry: typeof registry; modules: typeof modules; realtime: typeof realtime;
auth: typeof auth; registry: typeof registry; modules: typeof modules; realtime: typeof realtime;
media: typeof media; cam: typeof cam; mediaUpload: typeof mediaUpload; ui: typeof ui; community: typeof community; homeFeed: typeof homeFeed; bot: typeof bot; search: typeof search; bench: typeof bench; meme: typeof meme; vision: typeof vision; themes: typeof themes; design: typeof design; redact: typeof redact; chat: typeof chat; ai: typeof ai; credentials: typeof credentials; jobs: typeof jobs; tools: typeof tools; projects: typeof projects; geo: typeof geo; history: typeof history; locker: typeof locker; trust: typeof trust; levels: typeof levels;
media: typeof media; cam: typeof cam; mediaUpload: typeof mediaUpload; ui: typeof ui; community: typeof community; homeFeed: typeof homeFeed; bot: typeof bot; search: typeof search; bench: typeof bench; meme: typeof meme; vision: typeof vision; themes: typeof themes; design: typeof design; redact: typeof redact; chat: typeof chat; ai: typeof ai; credentials: typeof credentials; jobs: typeof jobs; tools: typeof tools; projects: typeof projects; geo: typeof geo; history: typeof history; locker: typeof locker; trust: typeof trust; levels: typeof levels;
};
};
@@ -2,6 +2,24 @@ import type { OpenVibeClient } from './core';
@@ -2,6 +2,24 @@ import type { OpenVibeClient } from './core';
type Opts = { signal?: AbortSignal };
type Opts = { signal?: AbortSignal };
type Json = Record<string, unknown>;
type Json = Record<string, unknown>;
+/** The kinds chat.embed@1 names. */
+export type ChatEmbedKind = 'link' | 'video' | 'image' | 'live' | 'picture' | 'design' | 'post' | 'profile' | 'game';
+/** chat.embed@1: one address preview under a chat message, the shape every client draws. Plain data; escape it. */
+export interface ChatEmbed {
+ kind: ChatEmbedKind;
+ url: string;
+ site_name: string;
+ title: string;
+ description: string;
+ /** An OpenVibe.Media address, or null (another site's picture is never hot-linked). */
+ image: string | null;
+ width: number;
+ height: number;
+ /** On OpenVibe's own kinds, the person or channel the thing belongs to. */
+ by?: string;
+ /** On a Live channel, whether it is broadcasting now. */
+ live?: boolean;
+}
/** chat.room-insight-result@1: a room's public AI insight (see the contract in openvibe-contracts). */
/** chat.room-insight-result@1: a room's public AI insight (see the contract in openvibe-contracts). */
export interface RoomInsight {
export interface RoomInsight {
overview: {
overview: {
@@ -16,7 +34,19 @@ export interface RoomInsight {
@@ -16,7 +34,19 @@ export interface RoomInsight {
timeline: { at: string; kind: string; title: string; text: string; message_id: number | null }[];
timeline: { at: string; kind: string; title: string; text: string; message_id: number | null }[];
state: 'ready' | 'quiet' | 'off';
state: 'ready' | 'quiet' | 'off';
}
}
+/** The typed address previews a message carries (chat.embed@1): [] when it has none. */
+export function readEmbeds(message?: { embeds?: unknown } | null): ChatEmbed[];
export type ChatMessageView = 'bubbles' | 'room';
export type ChatMessageView = 'bubbles' | 'room';
+export type ActivityKind = 'mention' | 'reply' | 'reaction' | 'server_invite' | 'friend_accept' | 'role';
+export interface ActivityItem {
+ id: number;
+ kind: ActivityKind;
+ actor: { id: number | null; username: string | null; display_name: string | null; avatar_url: string | null };
+ where: { kind: 'room' | 'dm' | 'global' | 'server' | 'friends'; label: string; href: string; room?: string | null; server?: string | null; conversation?: number };
+ what: { excerpt: string | null; reaction: string | null; role: string | null };
+ at: string;
+ read: boolean;
+}
export interface ChatHistoryPage<T extends { id: number | string } = { id: number | string; [field: string]: unknown }> { messages: T[]; more: boolean; [field: string]: unknown; }
export interface ChatHistoryPage<T extends { id: number | string } = { id: number | string; [field: string]: unknown }> { messages: T[]; more: boolean; [field: string]: unknown; }
export interface ChatHistoryOptions { limit?: number; before?: number | string | null; signal?: AbortSignal; }
export interface ChatHistoryOptions { limit?: number; before?: number | string | null; signal?: AbortSignal; }
export interface ChatHistoryHelper {
export interface ChatHistoryHelper {
@@ -65,6 +95,8 @@ export interface RoomMemory {
@@ -65,6 +95,8 @@ export interface RoomMemory {
}
}
export interface ChatClient {
export interface ChatClient {
+ /** The typed address previews a message carries (chat.embed@1): [] when it has none. */
+ embeds(message?: { embeds?: unknown } | null): ChatEmbed[];
history: ChatHistoryHelper;
history: ChatHistoryHelper;
/** Ask Vibe using Auto, one catalogue model, or two to three models side by side. */
/** Ask Vibe using Auto, one catalogue model, or two to three models side by side. */
ask(input: { message: string; models?: string[]; slug?: string; fresh?: boolean; system_prompt?: string; temperature?: number }, opts?: Opts): Promise<{ chat: Json; message: Json }>;
ask(input: { message: string; models?: string[]; slug?: string; fresh?: boolean; system_prompt?: string; temperature?: number }, opts?: Opts): Promise<{ chat: Json; message: Json }>;
@@ -87,7 +119,8 @@ export interface ChatClient {
@@ -87,7 +119,8 @@ export interface ChatClient {
forgetMyMemory(id: string, opts?: Opts): Promise<{ removed: number }>;
forgetMyMemory(id: string, opts?: Opts): Promise<{ removed: number }>;
update(slug: string, patch: { name?: string; topic?: string; visibility?: 'public' | 'private'; slow_seconds?: number }, opts?: Opts): Promise<Json>;
update(slug: string, patch: { name?: string; topic?: string; visibility?: 'public' | 'private'; slow_seconds?: number }, opts?: Opts): Promise<Json>;
messages(slug: string, query?: { before?: number; after?: number; limit?: number }, opts?: Opts): Promise<Json>;
messages(slug: string, query?: { before?: number; after?: number; limit?: number }, opts?: Opts): Promise<Json>;
- send(slug: string, message: string, opts?: Opts): Promise<Json>;
+ send(slug: string, message: string, extra?: { reply_to_id?: number }, opts?: Opts): Promise<Json>;
+ react(slug: string, messageId: number | string, reaction: 'thumbsup' | 'thumbsdown' | 'heart' | 'laugh' | 'surprised' | 'sad', opts?: Opts): Promise<{ ok: boolean; reaction: string | null }>;
deleteMessage(slug: string, id: number | string, opts?: Opts): Promise<Json>;
deleteMessage(slug: string, id: number | string, opts?: Opts): Promise<Json>;
join(slug: string, opts?: Opts): Promise<Json>;
join(slug: string, opts?: Opts): Promise<Json>;
leave(slug: string, opts?: Opts): Promise<Json>;
leave(slug: string, opts?: Opts): Promise<Json>;
@@ -100,7 +133,7 @@ export interface ChatClient {
@@ -100,7 +133,7 @@ export interface ChatClient {
create(userIds: number[], extra?: { name?: string }, opts?: Opts): Promise<Json>;
create(userIds: number[], extra?: { name?: string }, opts?: Opts): Promise<Json>;
get(id: number | string, opts?: Opts): Promise<Json | null>;
get(id: number | string, opts?: Opts): Promise<Json | null>;
messages(id: number | string, query?: { limit?: number; before?: number }, opts?: Opts): Promise<Json>;
messages(id: number | string, query?: { limit?: number; before?: number }, opts?: Opts): Promise<Json>;
- send(id: number | string, message: string, opts?: Opts): Promise<Json>;
+ send(id: number | string, message: string, extra?: { reply_to_id?: number }, opts?: Opts): Promise<Json>;
deleteMessage(id: number | string, msgId: number | string, opts?: Opts): Promise<Json>;
deleteMessage(id: number | string, msgId: number | string, opts?: Opts): Promise<Json>;
read(id: number | string, opts?: Opts): Promise<Json>;
read(id: number | string, opts?: Opts): Promise<Json>;
unread(opts?: Opts): Promise<{ unread: number }>;
unread(opts?: Opts): Promise<{ unread: number }>;
@@ -111,6 +144,12 @@ export interface ChatClient {
@@ -111,6 +144,12 @@ export interface ChatClient {
setViewPreference(id: number | string, view: ChatMessageView, opts?: Opts): Promise<{ view: ChatMessageView; conversation_id: number }>;
setViewPreference(id: number | string, view: ChatMessageView, opts?: Opts): Promise<{ view: ChatMessageView; conversation_id: number }>;
};
};
exportMine(opts?: Opts): Promise<{ username: string; exported_at: string; total: number; truncated: boolean; messages: Json[] }>;
exportMine(opts?: Opts): Promise<{ username: string; exported_at: string; total: number; truncated: boolean; messages: Json[] }>;
+ activity: {
+ list(query?: { limit?: number; before?: number; kind?: string }, opts?: Opts): Promise<{ items: ActivityItem[]; next_before: number | null; unread: number }>;
+ unread(opts?: Opts): Promise<{ unread: number }>;
+ readOne(id: number | string, opts?: Opts): Promise<{ ok: boolean; read: number; unread: number }>;
+ read(ids?: number[] | null, opts?: Opts): Promise<{ ok: boolean; read: number; unread: number }>;
+ };
vibe: {
vibe: {
list(opts?: Opts): Promise<{ chats: Json[]; allowance?: Json }>;
list(opts?: Opts): Promise<{ chats: Json[]; allowance?: Json }>;
conversations(opts?: Opts): Promise<{ conversations: Array<{ slug: string; name: string; last_message_at: string; created_at: string; last_line: string | null; last_answer_at: string | null; site: string | null }>; count: number }>;
conversations(opts?: Opts): Promise<{ conversations: Array<{ slug: string; name: string; last_message_at: string; created_at: string; last_line: string | null; last_answer_at: string | null; site: string | null }>; count: number }>;
@@ -69,3 +69,5 @@ export * as locker from './locker';
@@ -69,3 +69,5 @@ export * as locker from './locker';
export const createWalletClient: typeof import('./wallet').createWalletClient;
export const createWalletClient: typeof import('./wallet').createWalletClient;
export * as levels from './levels';
export * as levels from './levels';
+
+export * as userCard from './user-card';
@@ -18,6 +18,10 @@ export interface Machine {
@@ -18,6 +18,10 @@ export interface Machine {
name?: string;
name?: string;
/** The operating system the machine reports. */
/** The operating system the machine reports. */
os?: string;
os?: string;
+ /** Safe display label for the operating system or machine kind. */
+ system?: string;
+ /** Human-readable work classes the Link machine can run (worker, browser, models, robot). */
+ can_run?: string[];
/** When the machine was last seen. */
/** When the machine was last seen. */
last_seen_at?: string;
last_seen_at?: string;
/** The OpenVibe Link version the machine reports. */
/** The OpenVibe Link version the machine reports. */
@@ -14,6 +14,19 @@ export interface AppQuest {
@@ -14,6 +14,19 @@ export interface AppQuest {
title: string; why: string | null; steps: AppQuestStep[]; badge: { id: string; name: string }; url: string | null;
title: string; why: string | null; steps: AppQuestStep[]; badge: { id: string; name: string }; url: string | null;
status: 'active' | 'retired'; created_at: string; updated_at: string; completions: number;
status: 'active' | 'retired'; created_at: string; updated_at: string; completions: number;
}
}
+export interface QuestCardData {
+ signed_in: boolean;
+ quest: QuestDaily;
+ more: {
+ quests?: number;
+ sites?: number;
+ mine?: { badges: number; in_progress: number; completed: number };
+ };
+}
+export interface QuestCardOptions {
+ token?: string | null;
+ timeZone?: string;
+}
export interface QuestClient {
export interface QuestClient {
daily(opts?: { date?: string; signal?: AbortSignal }): Promise<DailyQuest>;
daily(opts?: { date?: string; signal?: AbortSignal }): Promise<DailyQuest>;
today(opts?: { signal?: AbortSignal }): Promise<DailyProgress>;
today(opts?: { signal?: AbortSignal }): Promise<DailyProgress>;
@@ -25,6 +38,7 @@ export interface QuestClient {
@@ -25,6 +38,7 @@ export interface QuestClient {
list(opts?: { signal?: AbortSignal }): Promise<{ project_id: string; max: number; quests: AppQuest[] }>;
list(opts?: { signal?: AbortSignal }): Promise<{ project_id: string; max: number; quests: AppQuest[] }>;
retire(slug: string, opts?: { signal?: AbortSignal }): Promise<AppQuest>;
retire(slug: string, opts?: { signal?: AbortSignal }): Promise<AppQuest>;
};
};
+ cardData(opts?: QuestCardOptions): Promise<QuestCardData | null>;
eventType(projectId: string, name: string): string;
eventType(projectId: string, name: string): string;
projectKey(projectId: string): string;
projectKey(projectId: string): string;
}
}
@@ -31,7 +31,17 @@ export interface ToolListQuery {
@@ -31,7 +31,17 @@ export interface ToolListQuery {
signal?: AbortSignal;
signal?: AbortSignal;
}
}
+/** Durable job execution receipt at result.data.execution, or error.execution on failure/cancellation. */
+export interface ToolsExecutionReceipt {
+ worker: string;
+ location: 'home' | 'host';
+ took_ms: number;
+ attempts: Array<{ worker: string; location: 'home' | 'host'; took_ms: number; state: 'succeeded' | 'failed' | 'cancelled' | 'disconnected' }>;
+}
+
export interface ToolRunOptions {
export interface ToolRunOptions {
+ /** host keeps work on the host; home is advisory and respects owner order. Default auto. */
+ prefer?: 'auto' | 'home' | 'host';
/** Uploads first, then references, in order; the count must fit the descriptor's files.min..max. */
/** Uploads first, then references, in order; the count must fit the descriptor's files.min..max. */
files?: ToolRunFile | ToolRunFile[];
files?: ToolRunFile | ToolRunFile[];
/** Job tools: wait up to this long (0..60000 ms) before answering; 200 finished, else 202. */
/** Job tools: wait up to this long (0..60000 ms) before answering; 200 finished, else 202. */
new file mode 100644
new file mode 100644
@@ -0,0 +1,23 @@
@@ -0,0 +1,23 @@
+import type { OpenVibeClient } from './core';
+/** An omitted field is hidden or unavailable, never an implied zero/offline state. */
+export interface UserCard {
+ username: string;
+ profile_url: string;
+ display_name?: string;
+ avatar_url?: string;
+ channel_url?: string;
+ live?: { now: false } | { now: true; site: 'live'; url: string };
+ /** Network's global level (the level shown by Quest). */
+ level?: number;
+ /** Consecutive completed daily quests, using the person's chosen time zone. */
+ streak?: number;
+ badges_count?: number;
+ followers?: number;
+ /** Explicit opt-in; site names only, from the last seven days of Network history. */
+ active_sites?: Array<{ id: string; name: string; url: string }>;
+}
+export interface UserCardClient {
+ get(username: string, options?: { signal?: AbortSignal }): Promise<UserCard>;
+}
+/** Public read, without Bearer credentials or cookies. Disabled owner switch returns HTTP 503. */
+export function createUserCardClient(client: OpenVibeClient, options?: { baseUrl?: string }): UserCardClient;