openvibers/openvibe.sdk AGENTS.md
AGENTS.md
| 1 | # AGENTS.md — OpenVibe.SDK |
| 2 | |
| 3 | ## Project overview |
| 4 | |
| 5 | The one supported way for any app — first-party service or an outside developer — to call the |
| 6 | OpenVibe network. This repository is the npm package `openvibe-sdk` (MIT), a dependency-free |
| 7 | JavaScript/TypeScript client library, not a service: it owns no database, no port and no deploy. |
| 8 | |
| 9 | - **Entry points:** `index.js` (Node, CommonJS), `browser.js` (browser-safe), `esm/*.mjs` (generated |
| 10 | ESM shims for every subpath), `types/*.d.ts`, and `browser/openvibe-sdk.mjs` (one self-contained |
| 11 | browser bundle, checked in). |
| 12 | - **Source:** one module or directory per capability under `src/` (`src/core/`, `src/auth/`, |
| 13 | `src/db/`, `src/service/`, `src/events.js`, `src/valkey.js`, `src/media.js`, `src/community.js`, |
| 14 | `src/chat.js`, `src/ai.js`, `src/tools.js`, …), each exposing a `create*Client` factory. |
| 15 | - **Contract types:** `openvibe-contracts` is a dev dependency used by the tests; at runtime the SDK |
| 16 | copies the types and shapes it needs, so consumers install the SDK alone. |
| 17 | - **Docs:** `README.md` is the API reference, `docs/` holds capability guides |
| 18 | (`docs/service.md`, `docs/consent.md`, `docs/tools-routing.md`, `docs/identity-emails.md`, …), |
| 19 | `docs/api-surface.json` is the generated export inventory and `docs/one-point-oh.*` the 1.0 |
| 20 | freeze plan. |
| 21 | - **CLI:** `bin/openvibe-download.js` installs as the `openvibe-download` command. |
| 22 | |
| 23 | ## Who calls it, what it calls |
| 24 | |
| 25 | Every OpenVibe service pins a released SDK tag |
| 26 | (`"openvibe-sdk": "https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/vX.Y.Z"`) |
| 27 | and calls services only through it. The rule in `README.md` is binding: **if a capability is not in |
| 28 | the SDK, it is not public** — a route with no SDK wrapper is internal and may change without notice. |
| 29 | To make something public, define it in OpenVibe.Contracts first, then wrap it here. |
| 30 | |
| 31 | The SDK never talks to a database or to another SDK module directly; each client takes a |
| 32 | `createClient()` and calls one service's documented HTTP API: Network (auth, identity, registry, |
| 33 | projects, user cards), Events, Media, Community, Chat, AI, Tools, Search, Bench, Vision, Live, |
| 34 | OpenRestream, Inventory, Tips, Blog, Reviews, Wiki, Coupons, Deals, Trade, Space, Host, Run, Video, |
| 35 | Work, Zone and VIP. `src/testing` provides `createMockPlatform()` so an app can test without the |
| 36 | network. |
| 37 | |
| 38 | ## Commands |
| 39 | |
| 40 | ```bash |
| 41 | npm ci # install (Node >= 20) |
| 42 | npm test # every test/*.test.js, one process each, no network |
| 43 | npm test -- core pack # only files whose name contains a word |
| 44 | npm test -- --strict # a skipped test fails the run |
| 45 | node scripts/esm.js # regenerate esm/*.mjs from the CommonJS sources |
| 46 | node scripts/browser-bundle.js # regenerate browser/openvibe-sdk.mjs (checked in; a stale bundle fails test/bundle.test.js) |
| 47 | node scripts/surface.js --check # compare exports with docs/api-surface.json; exits non-zero on a 1.0-core break |
| 48 | node scripts/surface.js # rewrite docs/api-surface.json after an intentional export change |
| 49 | node --check <file.js> # syntax check; there is no linter |
| 50 | ``` |
| 51 | |
| 52 | There is no build step for consumers and no runtime dependency: the package is plain CommonJS with |
| 53 | checked-in ESM and browser bundles. `npm test` uses local stub servers and `createMockPlatform()`; |
| 54 | it never touches the live platform. |
| 55 | |
| 56 | ## Conventions |
| 57 | |
| 58 | - **CommonJS** (`require` / `module.exports`) in `src/`; ESM files under `esm/` are generated, never |
| 59 | edited by hand. |
| 60 | - **4-space indent, single quotes, semicolons.** No linter or formatter is configured. |
| 61 | - **`create<Thing>Client` factories** take a `createClient()` (or explicit `{baseUrl, tokenClient}`) |
| 62 | and return a plain object of methods. Errors are `OpenVibeError`/`ToolRunError` with a problem |
| 63 | code, not bare `Error`. |
| 64 | - **Every subpath is an entry in `package.json` `exports`** with `types`, `import` and `default` |
| 65 | (and `browser` when browser-safe). Add a capability to `index.js`, `browser.js` (if safe), |
| 66 | `types/`, `esm/`, and `docs/api-surface.json`. |
| 67 | - **Writes are retried only when idempotent.** Either the service honours `Idempotency-Key` or the |
| 68 | client does not retry (chat, live, streams and other writes are documented as never retried). |
| 69 | - **Deadlines, trace propagation and safe retries** live in `src/core`; use them instead of |
| 70 | `fetch` + `setTimeout` by hand. |
| 71 | - **No secrets in code or tests.** Tokens are injected; `src/redact` is the shared scrubber. |
| 72 | |
| 73 | ## Key pitfalls |
| 74 | |
| 75 | - **The 1.0 core surface is frozen:** `core`, `auth`, `events`, `db` and `media` cannot lose or |
| 76 | rename an export without a major release. `test/surface.test.js` pins the exact lists and |
| 77 | `docs/one-point-oh.json` gives each name a tier. |
| 78 | - **Generated files are checked in:** `esm/`, `browser/openvibe-sdk.mjs`, `types/` and |
| 79 | `docs/api-surface.json` must be regenerated and committed with a source change; the tests fail on |
| 80 | a stale bundle or surface. Never edit `node_modules`. |
| 81 | - **Browser safety:** only browser-safe modules may be added to `browser.js` or the bundle — no |
| 82 | `fs`, `crypto` server APIs, `pg` or Valkey. A Node-only capability gets an `exports` entry with |
| 83 | `"browser": null` (see `./app-signin`). |
| 84 | - **Versioning:** every release is a tag and services pin it; the changelog is `CHANGELOG.md`. |
| 85 | Breaking a frozen core export, changing a problem code or a retry rule is a major-version change. |
| 86 | - **Consumers copy nothing:** `openvibe-sdk/no-looks` is deprecated (AI text may describe people); |
| 87 | `src/explicit` is the rule for sexual content, `src/front-page` for what may lead a front page. |
| 88 | - **Do not add a runtime dependency.** The package is deliberately dependency-free and needs only |
| 89 | Node >= 20 or a browser with `fetch`, Web Crypto and `TextDecoder`. |
| 90 | |
| 91 | ## Testing |
| 92 | |
| 93 | `test/run.js` runs every `test/*.test.js` in its own process (240 s timeout), honours |
| 94 | `npm test -- <filter>`, and treats a skipped file as not passed; `--strict` makes any skip fail the |
| 95 | run. Files under `test/` use `assert` and local stub servers, never the live platform; `testdata/` |
| 96 | holds fixtures. `test/browser-entries.test.js` and `test/bundle.test.js` guard the browser surface; |
| 97 | `test/surface.test.js` guards the public API inventory. Run `node scripts/surface.js --check` before |
| 98 | committing a client change. |
| 99 |