openvibers/openvibe.sdk Commits

0.127.0: openvibe-sdk/git, the OpenVibe.Git client (#166)

OP OpenVibers committed 4 days ago · d878d4f753 · 18 files, +288 −13

openvibe-sdk/git (ov.git) on today's main, rebuilt from #166 with the service's current git.repo.read and git.repo.write token scopes. Version 0.127.0; ESM, browser bundle, API surface and the 100-subpath pack test regenerated.

Changes

ddiff --git a/CHANGELOG.md b/CHANGELOG.md
iindex 444baa1..5d0a8f2 100644
---- a/CHANGELOG.md
++++ b/CHANGELOG.md
@@@ -1,5 +1,11 @@
  # Changelog
  
++## 0.127.0 — 2026-11-09
++
++- `openvibe-sdk/git` (`ov.git`): repositories, trees, blobs, commits, branches, tags, releases, contributors,
++  insights and stars; `commits.create()` writes a branch and files without a clone; `tokens.create()` makes a
++  short-lived clone token; `clone(repo, { to: 'link' })` hands a clone to Link.
++
  ## 0.126.0 (2026-11-09)
  
  - Add `openvibe-sdk/pics`: the public gallery and picture reads, private uploads with resumable chunks, publication, likes and albums on OpenVibe.Pics.
ddiff --git a/README.md b/README.md
iindex 9251f80..8b99374 100644
---- a/README.md
++++ b/README.md
@@@ -10,7 +10,7 @@ npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags
  
  > Supported browser and server clients for the OpenVibe platform.
  
--**Status:** alpha, v0.126.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.127.0 (the five 1.0 core entries — `core`, `auth`, `events`, `db` and `media` — are frozen: their exported names change only with a major release; roadmap Wave 2; developer apps from Wave 20; Media objects v2 from Wave 4; the Tools platform API; Search, Chat, AI, Vision and consent clients; sign-in with recovery and a client health check). Every release is tagged (see [CHANGELOG.md](CHANGELOG.md)). Tested against local stub servers and the built-in mock platform only, never against the live platform. Services pin release tags; each repository's `STATUS.json` names the one it uses.
  **Plan:** OpenVibe End-to-End Realignment & Implementation Plan, revision 3 (20 Sep 2026), §3.2; roadmap §30.  
  **License:** MIT ([LICENSE](LICENSE)). This package is a library that apps outside the network embed, so it uses MIT. The OpenVibe services themselves stay AGPL-3.0.
  
@@@ -19,7 +19,7 @@ npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags
  After v0.97.1 is tagged:
  
  ```bash
--npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.126.0
++npm install https://codeload.github.com/OpenVibers/OpenVibe.SDK/tar.gz/refs/tags/v0.127.0
  ```
  
  It has no runtime dependencies. It needs Node ≥ 20, or any browser with `fetch`, Web Crypto and `TextDecoder`. There is no build step. The package is CommonJS with ESM entry points (`import` works). Each subpath has its own `.d.ts`. For a page with no bundler, `browser/openvibe-sdk.mjs` is one self-contained ES module of the browser-safe subpaths (see [Browser without a bundler](#browser-without-a-bundler)). It does not depend on `openvibe-contracts` at runtime: it copies the contract types it uses (from the temporary Contracts sharing branch, a devDependency the tests check them against).
ddiff --git a/STATUS.json b/STATUS.json
iindex 8cea3e0..3de9020 100644
---- a/STATUS.json
++++ b/STATUS.json
@@@ -3,7 +3,7 @@
    "stage": "alpha",
    "code": true,
    "wave": "W2",
--  "version": "0.126.0",
++  "version": "0.127.0",
    "plan": "OpenVibe End-to-End Realignment & Implementation Plan, revision 3 (20 Sep 2026), \u00a73.2; roadmap \u00a730",
    "deployed": false,
    "deployment": "none: a package released as git tags; services and apps pin a tag",
ddiff --git a/browser/openvibe-sdk.mjs b/browser/openvibe-sdk.mjs
iindex 58ab6b0..3313dd6 100644
---- a/browser/openvibe-sdk.mjs
++++ b/browser/openvibe-sdk.mjs
@@@ -1,4 +1,4 @@
--// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.126.0, MIT). Do not edit.
++// Generated by scripts/browser-bundle.js from browser.js (openvibe-sdk 0.127.0, MIT). Do not edit.
  // One self-contained ES module: core at the top level plus the browser-safe subpaths as namespaces
  // (auth, locker, registry, trust, modules, realtime, media, cam, mediaUpload, ui, community, homeFeed, bot, search, bench, meme, vision, themes, design, redact, chat, ai, credentials, jobs, tools, projects, geo). No server-only code: no service tokens, JWT verification, events, identity.
  /* eslint-disable */
@@@ -56,7 +56,7 @@ const { paginate, offsetPager } = __load(7);
  const semver = __load(6);
  
  /** The package version (test/version.test.js keeps it equal to package.json). */
--const SDK_VERSION = '0.126.0';
++const SDK_VERSION = '0.127.0';
  
  module.exports = {
      createClient,
ddiff --git a/docs/api-surface.json b/docs/api-surface.json
iindex 346c575..7c60017 100644
---- a/docs/api-surface.json
++++ b/docs/api-surface.json
@@@ -173,6 +173,14 @@
          "createGeoClient"
        ]
      },
++    "git": {
++      "object": [
++        "SCOPES",
++        "SORTS",
++        "STARTERS",
++        "createGitClient"
++      ]
++    },
      "homeFeed": {
        "object": [
          "createHomeFeedClient"
@@@ -770,6 +778,12 @@
    "openvibe-sdk/geo": {
      "createGeoClient": "function"
    },
++  "openvibe-sdk/git": {
++    "SCOPES": "array",
++    "SORTS": "array",
++    "STARTERS": "array",
++    "createGitClient": "function"
++  },
    "openvibe-sdk/govern": {
      "UNITS": "array",
      "WINDOWS": {
ddiff --git a/esm/git.mjs b/esm/git.mjs
nnew file mode 100644
iindex 0000000..c4adfcf
---- /dev/null
++++ b/esm/git.mjs
@@@ -0,0 +1,7 @@
++// Generated by scripts/esm.js from src/git.js. Do not edit.
++import cjs from '../src/git.js';
++
++export const {
++    createGitClient, SCOPES, SORTS, STARTERS,
++} = cjs;
++export default cjs;
ddiff --git a/esm/index.mjs b/esm/index.mjs
iindex a61bdf5..2bcf21a 100644
---- a/esm/index.mjs
++++ b/esm/index.mjs
@@@ -14,7 +14,7 @@ export const {
      tips, blog, reviews, wiki, coupons, deals,
      shoes, trade, space, host, news, food,
      actor, run, video, pics, work, zone,
--    play, download, openre, geo, usage, commerce,
--    telemetry,
++    git, play, download, openre, geo, usage,
++    commerce, telemetry,
  } = cjs;
  export default cjs;
ddiff --git a/index.js b/index.js
iindex b22ae0a..000f2be 100644
---- a/index.js
++++ b/index.js
@@@ -63,6 +63,7 @@ module.exports = {
      pics: require('./src/pics'),
      work: require('./src/work'),
      zone: require('./src/zone'),
++    git: require('./src/git'),
      play: require('./src/play'),
      download: require('./src/download'),
      openre: require('./src/openre'),
ddiff --git a/package-lock.json b/package-lock.json
iindex a28cb42..623ebaf 100644
---- a/package-lock.json
++++ b/package-lock.json
@@@ -1,12 +1,12 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.126.0",
++  "version": "0.127.0",
    "lockfileVersion": 3,
    "requires": true,
    "packages": {
      "": {
        "name": "openvibe-sdk",
--      "version": "0.126.0",
++      "version": "0.127.0",
        "license": "MIT",
        "bin": {
          "openvibe-download": "bin/openvibe-download.js"
ddiff --git a/package.json b/package.json
iindex f2bcf4b..2c61af0 100644
---- a/package.json
++++ b/package.json
@@@ -1,6 +1,6 @@
  {
    "name": "openvibe-sdk",
--  "version": "0.126.0",
++  "version": "0.127.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",
@@@ -427,6 +427,12 @@
        "import": "./esm/zone.mjs",
        "default": "./src/zone.js"
      },
++    "./git": {
++      "types": "./types/git.d.ts",
++      "browser": null,
++      "import": "./esm/git.mjs",
++      "default": "./src/git.js"
++    },
      "./reviews": {
        "types": "./types/reviews.d.ts",
        "browser": null,
ddiff --git a/scripts/esm.js b/scripts/esm.js
iindex 9ab3043..6675d84 100644
---- a/scripts/esm.js
++++ b/scripts/esm.js
@@@ -103,6 +103,7 @@ const ENTRIES = {
      'pics.mjs': '../src/pics.js',
      'work.mjs': '../src/work.js',
      'zone.mjs': '../src/zone.js',
++    'git.mjs': '../src/git.js',
      'vip.mjs': '../src/vip.js',
      'frame.mjs': '../src/frame.js',
      'menu.mjs': '../src/menu/index.js',
ddiff --git a/src/core/index.js b/src/core/index.js
iindex 509e46c..f88cf67 100644
---- a/src/core/index.js
++++ b/src/core/index.js
@@@ -8,7 +8,7 @@ const { paginate, offsetPager } = require('./paginate');
  const semver = require('./semver');
  
  /** The package version (test/version.test.js keeps it equal to package.json). */
--const SDK_VERSION = '0.126.0';
++const SDK_VERSION = '0.127.0';
  
  module.exports = {
      createClient,
ddiff --git a/src/git.js b/src/git.js
nnew file mode 100644
iindex 0000000..250b333
---- /dev/null
++++ b/src/git.js
@@@ -0,0 +1,114 @@
++'use strict';
++/**
++ * openvibe-sdk/git — OpenVibe.Git (git.openvibe.codes): repositories, trees, blobs, commits, branches, tags,
++ * releases, contributors, insights and stars, the contents write that makes a commit without a clone, clone
++ * tokens, and the three ways to get a repository onto a computer.
++ *
++ *   const git = createGitClient(createClient({ tokenProvider }));
++ *   const { repositories } = await git.repos.list({ sort: 'trending', language: 'JavaScript' });
++ *   const repo = await git.repos.get('openvibers/openvibe.codes');
++ *   const tree = await git.repos.tree(repo.full_name, { ref: 'main', path: 'server' });
++ *   const file = await git.repos.blob(repo.full_name, { ref: 'main', path: 'README.md' });   // { text, … }
++ *   await git.commits.create(repo.full_name, { branch: 'agent/run-1', message: 'Fix the title', files: [{ path: 'README.md', content: '…' }] });
++ *   const { token, command } = await git.tokens.create({ scopes: ['git.repo.write'] });
++ *   git.clone(repo.full_name, { to: 'link' });        // Link opens and asks the person to approve the clone
++ *
++ * A public repository is readable without a token. A contents write, a star and a clone token need a signed-in
++ * person's client; a service acts with its own Network token (audience openvibe.git, capability git.repo.write).
++ */
++const enc = encodeURIComponent;
++const FULL_RE = /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\/[a-z0-9][a-z0-9._-]{0,99}$/;
++const SCOPES = ['git.repo.read', 'git.repo.write'];
++const SORTS = ['trending', 'pushed', 'stars', 'new'];
++const STARTERS = ['empty', 'app', 'static'];
++
++function fullName(full, where) {
++    const s = String(full || '').toLowerCase();
++    if (!FULL_RE.test(s)) throw new TypeError(`${where}: a repository is owner/name (lower-case)`);
++    return s;
++}
++
++function createGitClient(client, { baseUrl } = {}) {
++    if (!client || typeof client.json !== 'function' || typeof client.request !== 'function') {
++        throw new TypeError('createGitClient: pass an openvibe-sdk/core client');
++    }
++    const at = { service: 'git', baseUrl, audience: 'openvibe.git' };
++    const call = (opts) => client.json({ ...at, ...opts });
++    const repo = (full, where) => `/api/v1/repos/${fullName(full, where).split('/').map(enc).join('/')}`;
++    const repoAt = (full, tail, where) => `${repo(full, where)}/${tail}`;
++
++    return {
++        repos: {
++            /** Search and filter: q, language, official, mirror, mine, starred; sort trending|pushed|stars|new. */
++            list: ({ q, language, official, mirror, mine, starred, sort, limit, cursor, signal } = {}) => {
++                if (sort != null && !SORTS.includes(sort)) throw new TypeError(`git.repos.list: sort is one of ${SORTS.join(', ')}`);
++                return call({ path: '/api/v1/repos', query: { q, language, official, mirror, mine, starred, sort, limit, cursor }, signal });
++            },
++            get: (full, { signal } = {}) => call({ path: repo(full, 'git.repos.get'), signal }),
++            /** name, description, visibility, topics, starter (empty|app|static) or mirror_url (a public GitHub URL). */
++            create: (fields = {}, { signal } = {}) => {
++                if (!fields.name) throw new TypeError('git.repos.create: a name');
++                if (fields.starter != null && !STARTERS.includes(fields.starter)) throw new TypeError(`git.repos.create: starter is one of ${STARTERS.join(', ')}`);
++                return call({ method: 'POST', path: '/api/v1/repos', json: fields, signal });
++            },
++            tree: (full, { ref = 'main', path = '', signal } = {}) => call({ path: repoAt(full, 'tree', 'git.repos.tree'), query: { ref, path }, signal }),
++            blob: (full, { ref = 'main', path, signal } = {}) => {
++                if (!path) throw new TypeError('git.repos.blob: a path');
++                return call({ path: repoAt(full, 'blob', 'git.repos.blob'), query: { ref, path }, signal });
++            },
++            /** The file's bytes as text (a binary file answers with its type and no text). */
++            raw: async (full, { ref = 'main', path, signal } = {}) => {
++                if (!path) throw new TypeError('git.repos.raw: a path');
++                const { data } = await client.request({ ...at, path: repoAt(full, 'raw', 'git.repos.raw'), query: { ref, path }, responseType: 'text', signal });
++                return data;
++            },
++            commits: (full, { ref = 'main', path, limit, cursor, signal } = {}) => call({ path: repoAt(full, 'commits', 'git.repos.commits'), query: { ref, path, limit, cursor }, signal }),
++            commit: (full, sha, { diff = false, signal } = {}) => call({ path: repoAt(full, `commit/${enc(String(sha))}`, 'git.repos.commit'), query: { diff }, signal }),
++            branches: (full, { signal } = {}) => call({ path: repoAt(full, 'branches', 'git.repos.branches'), signal }),
++            tags: (full, { signal } = {}) => call({ path: repoAt(full, 'tags', 'git.repos.tags'), signal }),
++            releases: (full, { signal } = {}) => call({ path: repoAt(full, 'releases', 'git.repos.releases'), signal }),
++            contributors: (full, { signal } = {}) => call({ path: repoAt(full, 'contributors', 'git.repos.contributors'), signal }),
++            insights: (full, { days = 30, signal } = {}) => call({ path: repoAt(full, 'insights', 'git.repos.insights'), query: { days }, signal }),
++            /** Star or unstar; true stars, false unstars. */
++            star: (full, on = true, { signal } = {}) => call({ method: on ? 'PUT' : 'DELETE', path: repoAt(full, 'star', 'git.repos.star'), idempotent: true, signal }),
++            /** Mirror settings: { push_url, push_token } to push every push back to GitHub, or {} to stop. */
++            mirror: (full, fields = {}, { signal } = {}) => call({ method: 'POST', path: repoAt(full, 'mirror', 'git.repos.mirror'), json: fields, signal }),
++        },
++
++        commits: {
++            /**
++             * A branch and files in one request, no clone: files [{ path, content, encoding?: 'utf8'|'base64' }].
++             * `base` (a branch or sha) makes a new branch from it; without it the branch is the default branch.
++             */
++            create: (full, { branch, message, files, base, author, signal } = {}) => {
++                if (!branch) throw new TypeError('git.commits.create: a branch');
++                if (!message) throw new TypeError('git.commits.create: a message');
++                if (!Array.isArray(files) || !files.length) throw new TypeError('git.commits.create: at least one file');
++                for (const f of files) if (!f || !f.path || f.content == null) throw new TypeError('git.commits.create: every file has a path and content');
++                return call({ method: 'POST', path: repoAt(full, 'commits', 'git.commits.create'), json: { branch, message, files, base, author }, signal });
++            },
++        },
++
++        tokens: {
++            /** A clone token for the person (or the service): scopes git.repo.read and/or git.repo.write, hours (default 1). */
++            create: ({ scopes = ['git.repo.read'], hours = 1, label, signal } = {}) => {
++                const list = Array.isArray(scopes) ? scopes : [scopes];
++                if (!list.length || list.some((s) => !SCOPES.includes(s))) throw new TypeError(`git.tokens.create: scopes are ${SCOPES.join(' and ')}`);
++                return call({ method: 'POST', path: '/api/v1/tokens', json: { scopes: list, hours, label }, signal });
++            },
++        },
++
++        /** The three ways onto a computer: https (a clone URL), link (the Link app approves it) or codes. */
++        clone: (full, { to = 'https', directory, token } = {}) => {
++            const name = fullName(full, 'git.clone');
++            const url = `https://git.openvibe.codes/${name}.git`;
++            const target = directory ? ` ${directory}` : '';
++            if (to === 'https') return { repo: name, url, command: `git clone ${token ? url.replace('https://', `https://x-access-token:${token}@`) : url}${target}` };
++            if (to === 'link') return { repo: name, url, command: `git clone ${url}${target}`, href: `openvibe-link://clone?repo=${enc(name)}${directory ? `&directory=${enc(directory)}` : ''}` };
++            if (to === 'codes') return { repo: name, url, href: `https://openvibe.codes/new?repo=${enc(name)}` };
++            throw new TypeError("git.clone: to is 'https', 'link' or 'codes'");
++        },
++    };
++}
++
++module.exports = { createGitClient, SCOPES, SORTS, STARTERS };
ddiff --git a/test/browser-entries.test.js b/test/browser-entries.test.js
iindex fa8875b..1bb133a 100644
---- a/test/browser-entries.test.js
++++ b/test/browser-entries.test.js
@@@ -76,7 +76,7 @@ run([
              for (const [re, why] of FORBIDDEN) if (re.test(src)) problems.push(`${path.relative(ROOT, file)}: ${why}`);
          }
          assert.deepEqual(problems, []);
--        assert.deepEqual(blocked.sort(), ['./account-data', './actor', './app-signin', './assertions', './blog', './cache', './chat-apps', './commerce', './compute', './consent', './cost', './coupons', './db', './deals', './delivery', './design', './download', './events', './exchange', './food', './govern', './host', './identity', './inventory', './limits', './link', './live', './menu', './news', './notifications', './openre', './placement', './play', './pubsub', './quest', './queue', './reports', './resources', './reviews', './run', './runtime', './service', './share', './shoes', './space', './sso', './storage', './streams', './telemetry', './testing', './tips', './trade', './usage', './valkey', './vibes', './video', './vip', './wiki', './work', './zone']);
++        assert.deepEqual(blocked.sort(), ['./account-data', './actor', './app-signin', './assertions', './blog', './cache', './chat-apps', './commerce', './compute', './consent', './cost', './coupons', './db', './deals', './delivery', './design', './download', './events', './exchange', './food', './git', './govern', './host', './identity', './inventory', './limits', './link', './live', './menu', './news', './notifications', './openre', './placement', './play', './pubsub', './quest', './queue', './reports', './resources', './reviews', './run', './runtime', './service', './share', './shoes', './space', './sso', './storage', './streams', './telemetry', './testing', './tips', './trade', './usage', './valkey', './vibes', './video', './vip', './wiki', './work', './zone']);
          const rel = [...scanned].map((f) => path.relative(ROOT, f).split(path.sep).join('/'));   // the same names on Windows
          for (const must of ['browser.js', 'src/core/client.js', 'src/auth/browser.js', 'src/cam/index.js', 'src/realtime.js', 'src/media.js', 'src/community.js', 'src/bot.js', 'src/modules.js', 'src/registry.js', 'src/jobs.js', 'src/tools.js', 'src/core/form.js', 'src/projects.js', 'browser/openvibe-sdk.mjs']) {
              assert.ok(rel.includes(must), `${must} is scanned`);
ddiff --git a/test/git.test.js b/test/git.test.js
nnew file mode 100644
iindex 0000000..d05d7fe
---- /dev/null
++++ b/test/git.test.js
@@@ -0,0 +1,62 @@
++'use strict';
++/** openvibe-sdk/git: the client's paths, validation and the three ways to a computer. */
++const assert = require('node:assert/strict');
++const { createGitClient } = require('../src/git');
++
++function fake() {
++    const calls = [];
++    return {
++        calls,
++        json: async (opts) => { calls.push(opts); return { ok: true, ...opts }; },
++        request: async (opts) => { calls.push(opts); return { data: 'raw text' }; },
++    };
++}
++
++(async () => {
++    let n = 0;
++    const ok = (cond, msg) => { assert.ok(cond, msg); n += 1; };
++
++    const client = fake();
++    const git = createGitClient(client, { baseUrl: 'https://git.openvibe.codes' });
++
++    await git.repos.get('openvibers/openvibe.sdk');
++    ok(client.calls.at(-1).path === '/api/v1/repos/openvibers/openvibe.sdk', 'get path');
++    ok(client.calls.at(-1).service === 'git' && client.calls.at(-1).audience === 'openvibe.git', 'service and audience');
++
++    await git.repos.tree('OpenVibers/OpenVibe.SDK', { ref: 'main', path: 'server/git' });
++    ok(client.calls.at(-1).query.ref === 'main' && client.calls.at(-1).query.path === 'server/git', 'tree query');
++
++    await git.repos.commits('openvibers/openvibe.sdk', { path: 'README.md', limit: 10 });
++    ok(client.calls.at(-1).path.endsWith('/commits'), 'commits path');
++
++    await git.repos.star('openvibers/openvibe.sdk', true);
++    ok(client.calls.at(-1).method === 'PUT', 'star is PUT');
++    await git.repos.star('openvibers/openvibe.sdk', false);
++    ok(client.calls.at(-1).method === 'DELETE', 'unstar is DELETE');
++
++    await git.commits.create('openvibers/openvibe.sdk', {
++        branch: 'agent/run-1', message: 'Fix it', files: [{ path: 'README.md', content: 'hello' }],
++    });
++    ok(client.calls.at(-1).method === 'POST' && client.calls.at(-1).path.endsWith('/commits'), 'contents write');
++    assert.throws(() => git.commits.create('openvibers/openvibe.sdk', { branch: 'x', message: 'y', files: [] }), /file/); n += 1;
++
++    await git.tokens.create({ scopes: ['git.repo.write'], hours: 2 });
++    ok(JSON.stringify(client.calls.at(-1).json) === JSON.stringify({ scopes: ['git.repo.write'], hours: 2, label: undefined }), 'token scopes');
++    assert.throws(() => git.tokens.create({ scopes: ['nope'] }), /scopes/); n += 1;
++
++    const https = git.clone('openvibers/openvibe.sdk', { to: 'https' });
++    ok(https.command === 'git clone https://git.openvibe.codes/openvibers/openvibe.sdk.git', 'https clone command');
++    const withToken = git.clone('openvibers/openvibe.sdk', { to: 'https', token: 'git_abc', directory: 'sdk' });
++    ok(withToken.command.includes('x-access-token:git_abc@') && withToken.command.endsWith(' sdk'), 'token clone and folder');
++    const link = git.clone('openvibers/openvibe.sdk', { to: 'link', directory: 'code/sdk' });
++    ok(link.href.startsWith('openvibe-link://clone?repo=openvibers%2Fopenvibe.sdk') && link.href.includes('directory=code%2Fsdk'), 'Link deep link');
++    const codes = git.clone('openvibers/openvibe.sdk', { to: 'codes' });
++    ok(codes.href === 'https://openvibe.codes/new?repo=openvibers%2Fopenvibe.sdk', 'Codes link');
++    assert.throws(() => git.clone('../etc/passwd'), /owner\/name/); n += 1;
++
++    const raw = await git.repos.raw('openvibers/openvibe.sdk', { path: 'README.md' });
++    ok(raw === 'raw text' && client.calls.at(-1).responseType === 'text', 'raw text');
++    assert.throws(() => git.repos.get('Not A Repo'), /owner\/name/); n += 1;
++
++    console.log(`git: ${n} checks passed`);
++})().catch((err) => { console.error(err); process.exit(1); });
ddiff --git a/test/pack.test.js b/test/pack.test.js
iindex 215e48b..f5d3d9c 100644
---- a/test/pack.test.js
++++ b/test/pack.test.js
@@@ -72,7 +72,7 @@ run([
                  })().catch((err) => { console.error(err); process.exit(1); });`;
              const res = execFileSync(process.execPath, ['-e', script], { cwd: app, encoding: 'utf8' });
              assert.match(res, new RegExp(`consumer ok: ${subpaths.length} subpaths \\+ the browser bundle`));
--            assert.equal(subpaths.length, 99);   // Pics adds one subpath (0.125.0); the upload client and UI entry came in 0.123.0.
++            assert.equal(subpaths.length, 100);   // openvibe-sdk/git adds the 100th subpath (0.127.0).
              assert.ok(!fs.existsSync(path.join(app, 'node_modules/openvibe-contracts')), 'the optional peer is not installed');
          } finally {
              fs.rmSync(tmp, { recursive: true, force: true });
ddiff --git a/types/git.d.ts b/types/git.d.ts
nnew file mode 100644
iindex 0000000..8439bfd
---- /dev/null
++++ b/types/git.d.ts
@@@ -0,0 +1,63 @@
++/** openvibe-sdk/git: OpenVibe.Git — repositories, browsing, contents writes, clone tokens and the three ways to a computer. */
++type Opts = { signal?: AbortSignal };
++type GitJson = Record<string, any>;
++export type GitScope = 'git.repo.read' | 'git.repo.write';
++export type GitSort = 'trending' | 'pushed' | 'stars' | 'new';
++export type GitStarter = 'empty' | 'app' | 'static';
++
++export interface GitRepo {
++    id: string;
++    owner: { username: string; subject?: string | null; display_name?: string | null; avatar_url?: string | null };
++    name: string;
++    full_name: string;
++    description: string;
++    visibility: 'public' | 'private';
++    default_branch: string;
++    topics: string[];
++    stars: number;
++    watchers: number;
++    forks: number;
++    language: string | null;
++    languages: Record<string, number>;
++    html_url: string;
++    clone_url: string;
++    mirror: { url: string; state: 'ready' | 'syncing' | 'error'; last_synced_at: string | null; error: string | null } | null;
++    github: { full_name: string; html_url: string; stars: number; open_issues: number; open_pull_requests: number; ci_state: 'success' | 'failure' | 'pending' | 'unknown'; fetched_at: string } | null;
++    created_at: string;
++    updated_at: string;
++    pushed_at?: string | null;
++}
++
++export interface GitRepos {
++    list(params?: { q?: string; language?: string; official?: boolean; mirror?: boolean; mine?: boolean; starred?: boolean; sort?: GitSort; limit?: number; cursor?: string } & Opts): Promise<{ repositories: GitRepo[]; next_cursor: string | null }>;
++    get(full: string, opts?: Opts): Promise<GitRepo>;
++    create(fields: { name: string; description?: string; visibility?: 'public' | 'private'; topics?: string[]; starter?: GitStarter; mirror_url?: string }, opts?: Opts): Promise<GitRepo>;
++    tree(full: string, opts?: { ref?: string; path?: string } & Opts): Promise<GitJson>;
++    blob(full: string, opts: { ref?: string; path: string } & Opts): Promise<GitJson>;
++    raw(full: string, opts: { ref?: string; path: string } & Opts): Promise<string>;
++    commits(full: string, opts?: { ref?: string; path?: string; limit?: number; cursor?: string } & Opts): Promise<{ commits: GitJson[]; next_cursor: string | null }>;
++    commit(full: string, sha: string, opts?: { diff?: boolean } & Opts): Promise<GitJson>;
++    branches(full: string, opts?: Opts): Promise<GitJson>;
++    tags(full: string, opts?: Opts): Promise<GitJson>;
++    releases(full: string, opts?: Opts): Promise<GitJson>;
++    contributors(full: string, opts?: Opts): Promise<GitJson>;
++    insights(full: string, opts?: { days?: number } & Opts): Promise<GitJson>;
++    star(full: string, on?: boolean, opts?: Opts): Promise<GitJson>;
++    mirror(full: string, fields?: { push_url?: string | null; push_token?: string | null }, opts?: Opts): Promise<GitJson>;
++}
++
++export interface GitClient {
++    repos: GitRepos;
++    commits: {
++        create(full: string, fields: { branch: string; message: string; files: { path: string; content: string; encoding?: 'utf8' | 'base64' }[]; base?: string; author?: { name: string; email: string } }, opts?: Opts): Promise<GitJson>;
++    };
++    tokens: {
++        create(fields?: { scopes?: GitScope[]; hours?: number; label?: string }, opts?: Opts): Promise<{ token: string; token_type: string; expires_at: string; scopes: GitScope[]; clone_url: string; command: string }>;
++    };
++    clone(full: string, opts?: { to?: 'https' | 'link' | 'codes'; directory?: string; token?: string }): { repo: string; url: string; command?: string; href?: string };
++}
++
++export function createGitClient(client: { json(opts: Record<string, unknown>): Promise<any>; request(opts: Record<string, unknown>): Promise<{ data: any }> }, options?: { baseUrl?: string }): GitClient;
++export const SCOPES: readonly GitScope[];
++export const SORTS: readonly GitSort[];
++export const STARTERS: readonly GitStarter[];
ddiff --git a/types/index.d.ts b/types/index.d.ts
iindex 0263fa6..e9bb6fa 100644
---- a/types/index.d.ts
++++ b/types/index.d.ts
@@@ -53,6 +53,7 @@ export * as video from './video';
  export * as pics from './pics';
  export * as work from './work';
  export * as zone from './zone';
++export * as git from './git';
  export * as play from './play';
  export * as download from './download';
  export * as openre from './openre';