Build desktop apps for Odoo.
In an afternoon.

Start here

What is a .vapp?

One zip file. One window. The full Vizum desktop experience for free.

How it works

Why a vapp instead of a native Odoo module?

A native module is the right tool when you need to change Odoo's own core behaviour. For everything else — a department tool, a customer-facing mini-app, a dashboard, an integration — a vapp gets you there in an afternoon, with none of the server risk.

Start here

Quickstart — a TypeScript vApp with sdk-next SDK-next

Scaffold, build and pack a TypeScript vApp with sdk-next, the Vizum developer kit. It contains the typed SDK (@vizum/vapp-types), the UI tokens, charts, forms, the vzm CLI and the templates, as one pnpm workspace. You need Node 22.13+ and pnpm.

1. Scaffold from a template

From the root of the kit (sdk-next/):

node packages/vapp-cli/bin/vzm.mjs new vanilla-ts examples/my-app

A template's manifest.json already declares "min_platform": "5.67", the highest. Lower it only to install on an older platform, and only if your app uses nothing above that version: vzm check names the version each native declaration needs (see Platform capabilities).

2. Build and pack

pnpm install --filter ./examples/my-app...
cd examples/my-app
pnpm run build
pnpm run pack

pnpm run pack runs vzm pack dist and writes <id>.vapp: a zip of your built files plus the manifest.

3. Install

On the desktop, open the dock's apps menu, choose + Install .vapp, pick the file, then Open. An app that asks only for its own private data installs for any user. Anything more (Odoo records, server-side code, routes) needs an administrator's approval.

What the template does

import { connect, model, applyTheme, V } from "@vizum/vapp-types";

interface IResPartner { id: number; name?: string; email?: string }
const ResPartner = model<IResPartner>("res.partner");

await connect();     // the handshake, before any other SDK call
applyTheme();        // follow the desktop's accent and dark mode
const rows = await ResPartner.searchRead([["is_company", "=", true]], ["name", "email"], { limit: 8 });
V.ui.notify(`Loaded ${rows.length} partners`, "success");

Next:

• The toolchain: the vzm CLI, generating typed models from Odoo, and the packages.
• Server-side code: hooks, triggers and guards.
• Quickstart without a build step: three hand-written files.

Start here

The toolchain — vzm, TypeScript, Vite and the packages

Build vApps as visual and maintainable as a modern SaaS app — TypeScript, a typed ORM, a UI kit, charts, forms and maps — without changing how a vApp installs or runs. A compiled vApp is still the same .vapp the platform serves to the sandboxed iframe.

Two ways to build — same installable .vapp

"Compiled" only affects the developer's machine (a Vite build step). The output is the same zip of static files — installed by the store / api_install exactly as before. Hand-written and AI-generated single/multi-file vApps need no build.

TypeScript & a typed ORM

The SDK ships TypeScript types for every namespace, plus a generator that turns live Odoo metadata into typed models — autocomplete, compile-time safety, and far more reliable AI codegen.

// 1. generate typed interfaces from real Odoo fields
$ vzm introspect --from fields.json --out src/models.ts

// 2. use them — searchRead is typed; create() returns a SCALAR id (no number[] footgun)
import { SaleOrder } from "./models";
const rows = await SaleOrder.searchRead(
  [["state", "=", "sale"]], ["name", "amount_total"], { limit: 10 });
const id = await SaleOrder.create({ name: "From my vApp" });  // number, not number[]

The vzm CLI

Multi-file — no single huge app.js, no build

A .vapp can hold as many files/folders as you like. The platform serves every file with Access-Control-Allow-Origin: *, so ES-module imports across files (incl. subfolders) work in the sandboxed iframe with no build step — keep big apps tidy either way.

my-app/
  index.html          <!-- <script type="module" src="js/main.js"> -->
  js/main.js          // import { renderHome } from "./views/home.js"
  js/sdk.js           // local model()/connect() — no npm
  js/views/home.js
  css/style.css

The SDK-next packages — the full kit

Nine tree-shaken packages under the @vizum/vapp-* scope. Import only what you use; every one bundles its assets and fetches nothing at runtime (a hard requirement inside the opaque-origin vApp iframe), and every one reads the host --vzm-* design tokens so it follows light/dark mode automatically.

Maps & external data

A vApp iframe can load CORS-enabled external resources directly — verified with MapLibre styles + OpenStreetMap tiles + Nominatim geocoding, no platform change. For APIs that don't send CORS headers, use the server-proxied Vizum.net.fetch.

Offline, PWA & native mobile

A vApp iframe runs on an opaque origin, so localStorage/IndexedDB are blocked inside it — a vApp can't keep its own offline queue. That's exactly why the host (the desktop page, with normal storage) owns the outbox behind Vizum.offline:

// only APPROVED manifest actions can be queued — never arbitrary writes:
//   "actions": [{ "name": "ticket.ack", "model": "helpdesk.ticket", "method": "action_acknowledge" }]
await Vizum.offline.status();                 // { online: boolean }
Vizum.offline.on((s) => render(s.online));    // live connectivity flips
const r = await Vizum.offline.run("ticket.ack", { ids: [42] });
//   online  → runs live now, returns { ok, result }
//   offline → the HOST queues it, returns { id, queued: true }
await Vizum.offline.pending();                // what's waiting in the host outbox
await Vizum.offline.flush();                  // replay on reconnect (also automatic)
Vizum.offline.onFlushed((r) => toast(`synced ${r.sent}`));

Since 5.80 the host also keeps the datasets your manifest declares on the device and queues Vizum.offline.create / write: read, write, and resolve conflicts with no coverage (Offline data; the offline-field-app template). Vizum Solo opens with no network after one online visit, and the Android app sends queued actions, creates and changes with the app closed (sdk-next/docs/offline-pwa-mobile.md). A service worker and install prompt for the desktop are not built; a vApp iframe can't register one.

Example gallery

15 example apps ship with the toolchain — every one verified running in the desktop.

Start here

Quickstart without a build step

Three files, one zip, one click to install.

{
  "schema": 1,
  "id": "com.acme.hello",
  "name": "Hello Vizum",
  "version": "1.0.0",
  "entry": "index.html",
  "icon": "icon.png",
  "window": { "w": 360, "h": 300 },
  "permissions": { "data": "user" }
}

<!DOCTYPE html>
<html><head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="/vizum_apps_platform/static/sdk/vizum-glass.css">
</head>
<body style="padding:16px">
  <div class="vz-card">
    <h2>Hello!</h2>
    <p>Opened <b id="n">…</b> times by you.</p>
    <button id="reset" class="vz-btn">Reset</button>
  </div>
  <script src="/vizum_apps_platform/static/sdk/vizum-sdk.js"></script>
  <script src="app.js"></script>
</body></html>

(async function () {
    await Vizum.connect();                          // handshake with the desktop
    const n = ((await Vizum.data.get("opens")) || 0) + 1;
    await Vizum.data.set("opens", n);               // persisted per user, in Odoo
    document.getElementById("n").textContent = n;
    document.getElementById("reset").onclick = async () => {
        await Vizum.data.set("opens", 0);
        Vizum.ui.notify("Counter reset", "success");
        Vizum.window.close();
    };
})();

Zip it (plus any 256×256 icon.png) and install:

cd hello-vizum/
zip -r ../com.acme.hello.vapp . -x '.*'

On the desktop: dock 🧩 → “+ Install .vapp” → pick the file → Open. Because this manifest only asks for private data, any user can install it instantly — no admin needed.

Start here

Package anatomy

A .vapp is a renamed zip with one required contract: the manifest.

my-app.vapp
├── manifest.json          // REQUIRED — identity + permissions
├── index.html             // REQUIRED — your entry point
├── app.js                 // your code, any structure you like
├── style.css  assets/…    // css, images, fonts — vendor everything
└── icon.png               // REQUIRED — square PNG, 256×256

Concepts

The manifest, field by field

Your app's identity, window preferences and — most importantly — its permission contract.

{
  "schema": 1,
  "id": "com.yourcompany.appname",
  "name": "App Name",
  "version": "1.0.0",
  "min_platform": "5.49",
  "entry": "index.html",
  "icon": "icon.png",
  "window": { "w": 420, "h": 560, "singleton": true },
  "permissions": {
    "data": "user",
    "orm": [
      { "model": "sale.order",
        "ops": ["search", "read"],
        "fields": ["name", "amount_total", "state"],
        "domain": [["user_id", "=", "uid"]] }
    ],
    "ui": ["notify", "openRecord"],
    "events": { "emit": ["myapp.ping"], "listen": ["otherapp.pong"] }
  }
}

Concepts

Permissions & install tiers

Declare exactly what you need. Admins approve exactly what you declared. The server enforces it on every call.

The two install tiers

Write actions ask the user

Every mutating ORM call (create, write, unlink, call: methods) pops a host-rendered confirmation the sandboxed app cannot fake or skip: “AppName wants to create 1 account.move record — Allow / Deny”. Creates, updates and method calls ask once per app + operation + model and are then remembered; deletions ask every time. Users reset an app's remembered grants from Vizum Apps (↺ on the card). Denied calls reject with Error("UserDenied") — handle it gracefully.

Concepts

Version compatibility — write once, run on every Odoo

A .vapp keeps working when the customer upgrades Odoo (17 → 18 → 19 → 20 → …). You don't repackage it. Here's why, and the handful of rules that keep it true.

Why your app survives upgrades

• The SDK is shared, never bundled. Your package does not contain a copy of vizum-sdk.js — it loads the platform's single shared copy. Upgrading the platform upgrades the SDK for every installed app at once; there are no stale copies.
• The window.Vizum contract is version-stable. The transport (postMessage) and every namespace below are the same across Odoo versions. The platform absorbs the Odoo internals.
• Renamed core fields are translated for you. Odoo occasionally renames a field (e.g. res.users.groups_id became group_ids in 19, and 20 keeps it). The orm proxy transparently maps the known renames in both directions, so an app written against either name keeps reading/writing/searching it on any version — the result comes back under the name you asked for.

Three rules to stay future-proof

1. Never read group fields off res.users directly. Use Vizum.user / Vizum.roles (below) — they speak stable group XMLIDs, which never change between versions.
2. Stick to standard fields. id, name, login, lang, tz, company_id, currency_id, create_date, write_date, display_name are stable everywhere.
3. Branch on the version only if you truly must — Vizum.session.odoo_version gives the running major (17/18/19/20).

Vizum.user — version-safe identity & groups

No permission required (it only ever reveals the current user's own info).

await Vizum.connect();
Vizum.user.id;        // 12        (sync, from the handshake)
Vizum.user.name;      // "Jane Doe"
Vizum.user.isAdmin;   // true if ERP-manager/admin
Vizum.user.isSystem;  // true if in base.group_system

// is the user in an Odoo group? (stable XMLID — works on every version)
if (await Vizum.user.inGroup("sales_team.group_sale_manager")) showApproveButton();

const xmlids = await Vizum.user.groups();  // the user's OWN group XMLIDs
const full   = await Vizum.user.info();    // {id,name,login,isAdmin,isSystem,company,lang,tz}

Vizum.scope — am I per-user or global?

Tells your app which storage scope it runs in, so you can label the UI honestly (“shared with everyone” vs “your data”). Derived from your approved manifest.

const s = await Vizum.scope();
// { data: "user" | "global",        // your Vizum.data / key-value scope
//   tables: { notes: {shared: true} }, // per Vizum.db table
//   install_scope: "user" | "admin",
//   default_access: "all" | "restricted" }
if (s.data === "global") banner("Notes are shared with your whole company.");

Declaring scope is done in the manifest, not at runtime: permissions.data: "global" makes the KV store company-wide (privileged); a tables[].shared: true table gives each row an owner + per-row sharing (Vizum.db.share()), versus the default per-user isolation. See Permissions & tiers and The manifest.

Vizum.roles — declarative app roles

Map your own role names to Odoo groups in the manifest; the platform evaluates them as the real user (stable has_group(xmlid)) so the answer is trustworthy.

"roles": [{"name": "manager", "label": "Approver",
           "groups": ["sales_team.group_sale_manager", "base.group_system"]}]

if (await Vizum.roles.has("manager")) enableApprovals();
await Vizum.roles.mine();   // ["manager", ...] the roles the user has

Concepts

Platform capabilities and min_platform GENERATED

Current platform capability: 5.86.

A vApp declares the capability it needs in its manifest, "min_platform": "x.y". The installer refuses the app on an older platform instead of installing it and letting the feature fail at runtime (often silently: an ignored key, a missing V.* name, a guard that never runs). Set it to the highest row whose feature your app uses; a higher value only locks out instances for nothing.

Versions compare numerically per part: 5.9 < 5.10 < 5.54.

Summary

Details

5.86

OFFLINE: A RECORD DELETED ON THE SERVER IS ITS OWN KIND OF ISSUE. A queued write (or action) on a record that no longer exists answers CONFLICT with details.deleted; the device lists it as reason: "deleted" (with canRecreate) instead of a generic rejection, removes the local row (no ghost), and the user either discards the change or recreates the record (keep_mine: ONE create from what they saw, offered when the app may create the model offline). Vizum.supports("offline-deleted"). Also hardened in the same release, no contract change: a replay runs in the company it was queued under (a company the user lost is a clear refusal), an app waiting for approval holds the queue instead of rejecting it, a write naming a field that left the model is refused before anything is written, relation commands compare against the base correctly, and every replay outcome leaves a platform audit row. An app that handles reason: "deleted" sets min_platform 5.86. sdk-next/docs/offline-data.md.

5.85

A vApp CAN TAKE ITS WINDOW FULL SCREEN. Vizum.ui.fullscreen() / exitFullscreen() (grant "fullscreen" in permissions.ui; exitFullscreen is always allowed) on the desktop and the native Odoo host: the window is painted over the viewport with the dock, the Odoo navbar and the titlebar hidden (a render mode: the window's saved geometry is never touched), and the browser is asked for real fullscreen too, best effort - the click happened inside the sandboxed iframe and only some browsers hand that activation to the host document, so the kiosk layer never needs a gesture. A host Exit button, Escape and the browser's own exit end it (Vizum.ui.onFullscreenChange). Vizum.supports("ui-fullscreen"); Solo and device pages answer {active:false, supported:false} (device pages keep Vizum.device.fullscreen). An app that calls it sets min_platform 5.85 (vzm check). sdk-next/docs/ui-fullscreen.md.

5.84

NATIVE STRINGS FROM THE CATALOGUE. The i18n/<lang>.json an app already ships (5.73, 5.77) now also translates what the app puts in Odoo's own backend: field labels and help, selection options, model labels, groups, menus, window/server actions, view and report arch terms, the translatable values of native.records, a binding's label and a public page's website-menu entry. A key is the plain English text (an existing catalogue works at once) or an optional context key "@native:<ref>" (model, model.field, model.field#help, model.field=value, @group, <record id>.<field>, app, route:<name>; models/vapp_native_i18n.py). The strings are written at install, update, approval and language install/reactivation (and by vizum.app.action_native_i18n_reload) into the jsonb columns Odoo reads, computed from the stored en_US every time; en_US is never written and a missing string stays English. An administrator's own translation of one of these strings is kept (a hash of what the platform last wrote lives on native_i18n_state). The schema compiler now compares and writes the source columns in en_US, so a Spanish installer no longer rewrites them. Not a permission change: a translations-only update still asks for no approval and is audited (i18n:update, i18n:native). Keys do nothing on an older platform, so no min_platform is required. vzm check warns about untranslated native strings and dangling @native: keys (--strict-i18n makes them errors). sdk-next/docs/server-side.md.

5.83

the shared vector scope of a user-scoped app. Vizum.vector.sharedNamespaces() lists the namespaces (name, count, model, dim) the app owns in the SHARED (global) scope, and Vizum.vector.moveScope(ns, {from, to, user_id?, doc_id?, batch?}) moves a namespace's rows between the shared scope and a user's scope WITHOUT re-embedding: the owner of the existing rows changes, so embedding, text, metadata and chunk order are the stored bytes, nothing is embedded and nothing is metered. Administrator or the app's service user only (the store does not record who wrote a shared row, so a plain user cannot be given "the shared rows that are theirs"); user to global is administrator only; batched, re-runnable, never overwrites a row the destination already holds. V.vector.shared_namespaces() (server code) reads the list. An app that calls V.vector.shared_namespaces sets min_platform 5.83. Managed RAG storage lists but cannot move.

5.82

two asks of a paired-device page. (1) Player control: the app cannot reach the YouTube / Vimeo player the PAGE framed for it, so it names the handle embed() returned and the page posts the player's own postMessage command (setVolume 0-100, mute, unmute, play, pause) to that iframe, targetOrigin the provider's exact origin (never "*"), only for players this page created. No new host, no CSP change. Vizum.device.embed(...) handles gain setVolume/mute/unmute/play/pause; feature device-embed-control. (2) Per-device storage, Vizum.device.store get/set/delete/all: a frame with an opaque origin has no localStorage, so a screen's settings (volume) live server side in vizum.app.device.kv, keyed by the paired device (so by app + device), reached only with that device's own token through POST /vizum/device/<slug>/_store: at most 64 keys of at most 4 KB of JSON each (256 KB a device), dropped when the device is revoked. Feature device-store. Device pages only.

5.81

two server-computed facts a guard could not learn, and two limits lifted. (1) The trigger payload carries su: True when the write that fired the trigger ran in a superuser environment (env.su: a vApp method's sudo(), platform-internal code, uid 1), False for the user's own write. sudo() keeps the uid, so uid alone could not tell them apart; it is read from the write's records in base.automation._process, never from the app, and cannot be forged. (2) V.is_service_user(): True when the code runs as the app's own service user (the passwordless job user that jobs, triggers and device routes run as), False for any human. A vApp that reads rec["su"] or names V.is_service_user sets min_platform 5.81 (the install gate refuses it below). (3) A unique of a company_scoped model may list x_company_id, the synthesized company column (a prefix unique per company, one settings row per company); nulls_not_distinct works with it as for any column. A unique that names it sets min_platform 5.81. (4) A job may run with permissions.data "user": the platform writes no shared tick for it, and the job's own V.data is the scope of the user it runs as (the app's service user), never another user's private data; before 5.81 jobs required "global". An app with jobs and data "user" sets min_platform 5.81.

5.80

the offline data layer. A manifest may declare offline {datasets, writes, fallback, max_mb}: named, approved slices of the user's own Odoo data (model, fields, domain with {uid}/{company_ids}/{today±N}, order, limit) that the HOST keeps on the device, and the writes (create / write, with the fields each may touch) that may be queued with no network. The device sends a dataset NAME; the server (api_offline: datasets, config, sync) reads model, fields and domain from the approved snapshot and runs the read as the user, so grants, field ceilings and record rules apply as to a live call. A queued write carries the values the user saw (base) and a queued create or action the computed fields the user saw (expect); a difference answers CONFLICT, and a replay for another user answers OFFLINE_USER_MISMATCH and is kept. The host owns the outbox in IndexedDB (per database and user), applies a queued change to the local copy at once (rollback when the server refuses it), swaps a temporary id (vzm-tmp:...) for the real one when its create replays, syncs on start, on reconnect, on app open and every 15 minutes, hides a copy older than 7 days, and removes the rows (never the queue) on logout or a change of user. Vizum.offline gains datasets, sync, query, readGroup, create, write, conflicts, resolve. A vApp that declares offline sets min_platform 5.80; every actions[].model must be granted or owned. sdk-next/docs/offline-data.md.

5.79

Vizum.identity.confirm: step-up authentication. A vApp asks the HOST to re-confirm the user; the host shows its own dialog (dimming the whole desktop), the user types the account password there and it goes over a dedicated route to the closed model vizum.app.stepup, never through the bridge or to the iframe. The app gets a single-use token (120 s, bound to the user, app, action and session) and spends it in server code with V.identity.consume(token, action), which returns a receipt (id, user, action, meaning, reason, confirmed_at). Not on Solo (UNSUPPORTED_CALL); a device page gets PERMISSION_DENIED. A vApp that names V.identity sets min_platform 5.79 (the install gate refuses it below). sdk-next/docs/identity-step-up.md.

5.78

group_ops. An orm grant may carry group_ops: [{groups, ops}], extra ops (create, write, unlink, call:<method>) for the CALLING user who is in at least one of the groups: "@name" (the app's own native.groups), "<app-key>/@name" (an app in requires) or a real xmlid, never an administrative group. They are computed in _orm_rule, so api_orm, call:, actions and read_group all honour them, and Solo's access group is minted from ops only: a UI app can keep ops read-only for every Solo user and give the owner app's administrators the writes. An op is in ops or in group_ops, not both; moving an op from ops into group_ops narrows (no re-approval), adding one widens. A vApp that uses it sets min_platform 5.78 (the validator and vzm check refuse it below).

5.77

V.tr. The script-hook (trigger guards included), job and native-method sandboxes get V.tr(source, *args, lang=None, **kwargs): the method-side tr() on the app's own i18n catalogue (5.73), interpolated after the lookup, never raising for a missing or malformed translation. Language: lang= when installed, else the call's (a hook: the user whose write fired it), else the language of the user the code runs as; a job runs in its job user's language. A vApp that names V.tr sets min_platform 5.77 (the install gate refuses it below).

5.76

Vizum.app.key. The host already sent the app's key in vizum:ready (app) and the SDK dropped it, so vApps parsed it out of the run URL, which on a multi-database host reads "@<db>" (/vizum/apps/run/@<db>/<key>/...). The SDK now exposes it; vzm check and the store gate warn on code that parses the key from the URL. No server behaviour changes.

5.75

V.sha256. The script-hook, job and native-method sandboxes get V.sha256(data, encoding=None): the SHA-256 hex of a str (UTF-8), bytes or base64 str, at most 32 MiB a call and 256 MiB / 2000 calls a run, charged before the input is decoded. It is an integrity digest, not a signature (package signing is the authenticity check). hashlib stays in the method sandbox for now. A vApp that names V.sha256 sets min_platform 5.75 (the install gate refuses it below).

5.74

NETWORK REACH AND IMAGE FETCH. permissions.net may hold "*": any PUBLIC website (never a private, loopback, link-local, metadata or tunnel address; every hop of a redirect is checked again, the connection is pinned to the address that was verified, and only a short header allowlist is sent), download-only; V.net.fetch_image / Vizum.net.fetchImage fetch ONE image server-side, with a size cap and a deadline for the whole fetch. A host the manifest NAMES reaches ports 80 and 443 only unless the entry says host:port (an app below min_platform 5.74 keeps the old behaviour and is warned). A vApp that uses any of it sets min_platform 5.74.

5.73

SERVER-SIDE TRANSLATIONS. The i18n/<lang>.json files the browser SDK reads also answer tr() in the app's model methods: the install stores them on vizum.app.i18n_catalog (models/vapp_i18n.py), tr() reads the language of the call (context.lang through the bridge, an installed language is just lang; one the instance lacks is kept as vizum_req_lang next to the lang the ORM kept, so the ORM keeps working and a nested with_context(lang=X) still wins), tries es_419 -> es -> msgid and keeps the % formatting. The instance, the Store upload and vzm check refuse a catalogue whose placeholders differ from the msgid's, with markup, or over 512 KB (2 MB together); an update that changes only translations asks no approval and is audited (i18n:update). A vApp that uses it sets min_platform 5.73.

5.72

RESUMABLE CHUNKED UPLOADS. A dropped connection no longer restarts a big Vizum.files.putBlob from zero: POST /vizum/apps/files/<key>/upload/status?token answers {received, next_part, size, sha256, expires_at} behind the same user / app / expiry gate as the other upload routes; the host keeps the token on a network error, sends the same part again with backoff, asks status and goes on from next_part, and when it gives up it aborts explicitly (an abort that cannot reach the server is retried when the network returns) so the quota reservation and the upload slot are freed. Nothing changes for an app: the same Vizum.files.putBlob call. A vApp that wants the guarantee sets min_platform 5.72.

5.71

LARGE APP FILES. Vizum.files.putBlob above 32 MB uploads in parts (begin / part / commit / abort: models/vizum_app_upload.py, the platform reserves the declared size against every quota and verifies size + sha256 before the file reaches the filestore); Vizum.files.getBlob and getRange stream a file out with Range support. permissions.file_limits.max_mb may go up to 512 MB, but a file above 200 MB needs its own administrator approval (permissions.large_files, synthesized) and an app storage cap; the single-request routes (Vizum.files.put, putBlob up to 32 MB, orm.writeBlob) stay at 200 MB. Duplicate app files that an old race left behind are renamed (never deleted) by a one-time migration. A vApp that uses any of it sets min_platform 5.71.

5.70

PAIRED DEVICES AND LARGE FILES. A route may be auth: "device": a screen, kiosk or time clock with no Odoo login pairs with an 8-digit PIN the platform shows and an administrator claims on the desktop; it then holds a hashed, revocable token and reaches only the app's device pages, json and file routes (controllers/device.py, device-routes.md); a device page plays YouTube / Vimeo over the app (Vizum.device.embed, framed by the page, only the providers of device.embeds) and keeps an offline cache (device_sw.js, device_host.js); Vizum.pairedDevices manages the devices from the desktop. permissions.file_limits raises Vizum.files per app (up to 200 MB a file) with a streamed upload — Vizum.files.putBlob, Vizum.orm.writeBlob. A vApp that uses any of it sets min_platform 5.70.

5.69

UPDATES THAT RE-ASK, VERSIONED CONTRACTS, VERIFIED CALLERS, INSTANCE TELEMETRY. An update that changes server code (script hooks and library, model methods, routes, jobs, webhooks, fields with server logic, constraints, automations, native migrations, the evaluated parts of native.ui and manifest actions) sends the app back to needs_approval like a wider grant, and api_update_preflight names each permission and code change (lifecycle.md); Vizum.backend task rows carry status — retrying, expired, dead_letter (reliability.md); provides may name a contract version (name@x.y.z) and requires a contract in a version range (composition.md); a method another app calls through its call: grant reads that app's key with caller_app(), verified by the platform (server-side.md); the instance reports a daily technical profile (edition, active-user band, installed vApps) from 2026-11-04 per Terms 15.4 v1.2, and an administrator can switch the upload off. A vApp that uses versioned contracts, caller_app() or task status sets min_platform 5.69.

5.68

A MODULE THE SIZE OF ELEV8DM AS A vAPP (its 1766 tests run on the vApp; plan 2026-10-02-plataforma-5.68-elev8dm). In the sandbox: the module's own classes as objects (new_class: public attributes, the program's own methods, a closed list of dunders), its pure modules as the app's library (up to 1 MB / 32 parts with methods; a program of 3 MB / 300k nodes), fields_of(model), with savepoint(): (the only with), base_url(), sign / consteq / verify_legacy (the module's signed links, only for an app that replaces it), format_text, a governed PIL (Image, ImageOps), hashlib, uuid, binascii, pg_errors, clock (time/monotonic), lock_read / fetched_row, with_user / with_env, and fields_get / check_access / has_access on the app's own models; self.env.cr / execute / registry / pool stay unreachable (refused at upload by the platform and the store). An app's methods share one program per process, as a module does. Models: unique entries {fields, nulls_not_distinct, name} (empty values collide; the index named <table>_<name>, as Odoo names the module's constraint), check entries {name, field, op, value} (a PostgreSQL CHECK <table>_<name>), a many2many pair (one relation from two own models), default_get and invalidation by an alias name, order, readonly on any field; native.replaces_min_version (adopt only from a module at its last migration); native.routes kind "file" (a binary behind a link the platform signs: route_file_url / route_file_token / route_file_verify); native.records match (a seeded row whose xmlid is gone is anchored again by its unique fields); the app's groups under a privilege/category named after it; native.adopt on real data: the rows are copied as data, not as events (the app's create/write overrides stay out, its constraints run once over the adopted rows), attachment binaries are shared by reference (no byte read), refs ({id_field, model_field | model_by}) and links to ir.model / ir.model.fields follow the adopted rows; an UPDATE whose requires names an app that is missing or out of range is refused, the installed version stays. A vApp that uses any of it sets min_platform 5.68.

5.67

THE PLATFORM CONTRACT AND SDK RELIABILITY (SDK plan P0–P4). The platform contract reaches apps (Vizum.platform, Vizum.sdk, Vizum.features(), Vizum.supports()); every failed call rejects with a VizumError {code, category, retryable, correlationId}, and Vizum.errors.is / normalize / catalog read them; every call carries a request id; orm.create, actions.run, backend.enqueue and offline.run take an idempotency key, so a retry or an offline replay runs once; the vApp bus no longer fans out across users and apps; packages can be signed (vzm keygen / pack --sign, package-signing.md) and every install verifies them, refusing a modified package; the store can revoke a version and every instance disables it; requires takes version ranges and contracts, Vizum.apps.status() reports them and a required app is not uninstalled by accident (composition.md); an app declares event_contracts and the desktop refuses an emit that breaks them, and Vizum.events.catalog() lists them (events.md); Vizum.apps.health() and api_update_preflight say how an app runs and what an update would change before it is installed (lifecycle.md); the CLI gains a platform emulator (vzm test, vzm dev), vzm diff and agent-ready scaffolds (emulator.md, cli.md); inbound webhooks get a delivery ledger with replay protection, ack/fail (from the browser or a job: V.webhooks) and a dead letter, the bridge a per-app rate limit and metrics, and Vizum.errors.retry (reliability.md); an AI tool declares its risk and side effects, and every host confirms an update or destructive one with the user before the app is reached (ai-tools.md); files carry a sha256, put refuses damaged or disguised bytes and public links expire (files.md); an administrator can give each app an AI-token, network and storage budget (QUOTA_EXCEEDED, reliability.md); a manifest action declares retry and timeout_minutes for its backend tasks (reliability.md). See platform-contract.md. A vApp that uses any of it sets min_platform 5.67.

5.66

A WHOLE ODOO MODULE AS A vAPP (psi_dsd → PSI DSD Core, its 818 tests green on the vApp). native.methods: Python model methods run in the sandbox and installed as real methods of the Odoo class — self/env[...] are governed recordsets (the app's orm grants, ACLs and rules; sudo() lifts ACLs, never the grants), overrides of Odoo methods call super_() (privileged permissions.methods), private helpers are p_x, another app calls them through its own call: grant; computes, defaults, constraints and jobs by method; permissions.private_calls / params / peer_data. native.aliases: the module's field names are real (related) fields of the ORM. native.records / rules / ui (views, actions, menus, reports, the vzm_geo_map widget) / groups.implies. native.replaces: while the named module is installed the app waits (no alias, override, constraint, backend or job on Odoo's models) and adopts — its rows, its columns on Odoo's models, its groups' members (groups[].adopt), and the chatter of each adopted row when the module is uninstalled; then the app goes live by itself. A vApp that uses any of it sets min_platform 5.66.

5.65

Vizum.team COVERS WHAT A USER-PROVISIONING MODULE DID (united_insurance_team). team.whoami() -> {uid, manager, role}; member rows carry phone, last_login, self, role_label and admin (an administrative account holding a role is listed, still untouchable); save takes a phone, reactivates a member the app manages and refuses to change the caller's own role. A role may let its own groups into other apps of the same vendor (role apps: [{key, solo?}], each listed in the privileged permissions.team_apps; restricted desktop access and, with solo, the phone launcher; never removed). native.team.adopt_existing "dedicated" (privileged permissions.team_adopt) takes over, on install/update, the accounts that already play the app's roles and hold nothing else, so its managers can reset their password; an account with any other group keeps only "give or take the role". A vApp that uses any of it sets min_platform 5.65.

5.64

A vAPP CAN TAKE OVER THE DATA OF THE MODULE IT REPLACES. native.adopt: [{model, from, fields: {own field: module field}}] copies every row of an installed module's model into one of the app's own models, once (vizum.app.adopt.map), on each install/update while that model exists: rows first, then the links between adopted models translated through the map (links to shared models keep their ids). Each from must be listed in the privileged grant permissions.adopt (a new one widens); platform, identity and security models and secret fields are refused. The customer uninstalls the module afterwards. A vApp that adopts sets min_platform 5.64.

5.63

THE LAST FIELD SHAPES A MODULE USES. translate: true on a char/text/html field (one value per language, as translate=True in a module); type "json" (fields.Json); a one2many from an own model to a SHARED model whose inverse is a many2one column the app adds to that model in native.fields (created after it, in _apply_shared_one2many); up to 80 own models per app (was 50). Also fixed: an app that added to res.partner a many2one pointing at its own model could not be uninstalled (Odoo reflects the column on res.users as a 'base' field, and dropping the model refused it): such a column is now dropped before the model. A vApp that uses translate, json, a one2many to a shared model or more than 50 models sets min_platform 5.63.

5.62

A SANDBOX FOR REAL LOGIC, WITH A CLOCK. Script hooks may define top-level functions (def, no decorators, no nesting — so no closures) and use while; the app may share code between its hooks in native.script.lib ({name: code}, vetted the same way, run before each hook). In exchange every run has a TIME BUDGET — 30 s, 120 s for a scheduled job — enforced by a check the platform injects into every loop and function body (no signals or threads); a run that exhausts it stops with a clear error. On a 5.61 build a def or a while is refused at install, so a vApp that uses them (or lib) sets min_platform 5.62.

5.61

NATIVE DATA ACROSS VERSIONS. native.migrations: [{to, ops}] run by reconcile on the update that crosses to (vizum.app.native_schema_version remembers the version last reconciled; a first install migrates nothing): rename_field (the column and its data keep living under the new name; the app's views are dropped first and rebuilt), copy (old column into an empty new one, both existing), hook (a script hook of the app, run as its job user with installing=True). Order: renames, new schema, data ops, then the stale columns go. native.seed: [{model, key, rows | file (a .json in the bundle), update?}] upserted by the natural key on every install/update, references {"$ref": "<model>:<key>"} to rows seeded earlier. Uninstall deletes the data, as a native module's uninstall does. A vApp that declares either sets min_platform 5.61.

5.60

Vizum.team: A MANAGER OF THE APP CREATES AND EDITS THE USERS WHO PLAY ITS ROLES. The manifest declares native.team {managers: [group refs], roles: [{name, label, help, groups}]} under the privileged grant permissions.team; api_team (vizum_app_team.py) offers roles / members / save / set_active / remove / set_password / invite. Only a manager (or a settings admin) calls it; a role gives exactly its approved groups and never one that is or implies an administrative group (checked on the implied closure at run time); administrative accounts are never touched; a user the app's team did not create (vizum.app.team.member) can only gain or lose the app's roles. It replaces the per-customer Odoo module apps needed for this (united_insurance_team, psi_dsd's manager_provision_user). A vApp that calls Vizum.team sets min_platform 5.60.

5.59

A vAPP CAN DEFEND A FIELD OF ITS OWN MODELS (closes the 2026-09-01 field-ceiling concern). An own-model field may declare writers (["@server", "@<declared group>", "<group xmlid>"]), server_only: true (= ["@server"]) or computed_by: "<hook>" (a trigger hook of the app on that model computes it; = ["@server"]). The ORM refuses a create/write that sets it unless the caller is a writer — one gate for the iframe, the invoked hooks, the backend and RPC (vizum.app.native.runtime on base). "@server" is the app's SERVICE USER — an internal user with no password, created when the app declares a server writer (or native.service_user), member of base.group_user and of the groups its models grant, made its job user (triggers and jobs run as it), archived at uninstall — or Python running as the superuser/sudo, as for a native module's field only its code writes. Administrators are writers only when listed. Apps that declare none of this keep their job user unchanged. min_platform 5.59.

5.58

WHAT A MODULE'S PYTHON GIVES ITS MODELS, DECLARED. On the app's own models: default (a literal of the field's type, or {"dynamic": today|now|user|company}) and sequence ({prefix, padding}: numbered on create from the app's own ir.sequence), both applied by the platform runtime (vizum.app.native.runtime extends default_get and create on base, acting only on a READY app's x_vzm_ models, from a cached map of the manifests); unique (real PostgreSQL unique indexes, vizum.app.native.unique, refused at install when rows collide); chatter (mail thread + activities, only ever turned on) with tracking on fields. Computed fields on own models: formula (manifest names, dependencies derived), related (from one of the model's many2one) and aggregate ({of: <one2many>, op: sum|count|min|max|avg, field}) — the totals of a document — compiled into platform-owned compute bodies, created in dependency order (Odoo checks a compute's path against the registry at create time). They hold for the vApp, the backend and RPC. A 5.57 build refuses or ignores every one of these keys, so a vApp that uses any of them sets min_platform 5.58.

5.57

A vAPP CAN MODEL A DOCUMENT WITH LINES. On the app's own native models: a one2many names its inverse (a many2one declared on another of the app's own models, pointing back) and compiles to Odoo's relation_field — before, the validator accepted a one2many the compiler could not install. A many2one takes ondelete ("set null", the default; "cascade"; "restrict"), enforced by PostgreSQL's foreign key, and any field but an x2many or a boolean takes required (a required many2one cannot "set null"). A one2many may also sit on a SHARED model to list the app's rows (res.partner -> its orders); there required and cascade are refused — they would act on records other modules own. A version may add, change or drop them: the compiler drops a one2many before its inverse (Odoo refuses the reverse outside a module uninstall), a dropped ondelete returns the field to "set null", and a one2many is never archived (it has no column). The bridge's relational guard already governs the nested commands. On a 5.56 build a one2many dies at install on Odoo's own error and ondelete/required are silently ignored — so a vApp that uses any of them sets min_platform 5.57.

5.56

A HOOK CAN GUARD A DELETION. native.script.hooks[].trigger.on accepts "unlink" (with enforce): a base.automation on_unlink whose action calls the same dispatcher, run BEFORE the deletion — a hook that raises (V.fail) aborts it, for every ORM unlink: the backend, sudo, crons, the app's own Vizum.orm.unlink. Payload: event "unlink", changed [], old = every stored content field as the row is before the deletion (same ceilings), new {}. Every trigger payload gains installing (true while the app's own install/update runs its migrations; the guard still runs and decides). Uninstall is unaffected: the automation is torn down before the model, whose table is dropped, not unlinked. NOT seen by any trigger: deletions PostgreSQL performs itself — a set-null or cascade many2one (every vApp many2one is set null), many2many link rows — so guard the record actually deleted. A vApp that declares on: "unlink" sets min_platform 5.56.

5.55

PUBLIC ROUTE PAGES. A route may declare auth: "public" — a PAGE only (a public json route does not exist), with no groups — at /app/<slug>/<route>, open to anyone, signed in or not, of the company it is served in (the website's company when website is installed, else the public user's; an app of another company answers the identical 404). The page carries the bundle credential and nothing else: NO caps and NO route run-token, so the bridge refuses every call from its iframe; an anonymous visitor's page is Cache-Control: public, max-age=300. Public page names surface as permissions.public_routes, a separate privileged grant (widening → needs_approval) shown on its own approval card with each full URL. Optional website_menu ({text <= 40, sequence}) becomes a website.menu entry per website of the app's company (all websites without one), a recorded website_menu artifact removed when the app leaves ready, drops the route, or is uninstalled; skipped without website. Optional sitemap: true lists the page in the website sitemap (part of the approved descriptor). A vApp that declares a public route sets min_platform 5.55.

5.54

A TRIGGER KNOWS WHO WROTE, WHO OWNS, AND WHAT THE WRITE LEFT. The hook payload gains uid (env.uid of the write — 1 when server code writes as the superuser), owner (the row's create_uid) and new (post-image of the written fields; every stored content field on a create), read with the platform's rights like old and under old's ceilings: the app's read grant, never a field the app hides from the hook identity (VZ-SEC-23), binaries as their size, text over TRIGGER_TEXT_CAP as its length (also in old now). A guard runs as the job user, whose record rules may hide the row it guards; before 5.54 "only the owner may share this" could not be enforced server-side (Vizum Sheets). A hook that reads uid/owner/new sets min_platform 5.54.

5.53

ROUTES A vAPP DECLARES (native.routes), portal and internal only. The platform serves GET /app/<slug>/<route>[/<sub>] (a platform page embedding the app's sandboxed iframe, with the route as its intent — Vizum.route) and POST /app/<slug>/<route> (a json route: CSRF, body <= 64 KB, rate-limited per user/app/route, audited, the declared hook run AS THE VISITOR), plus the GET alias /my/<slug>/… for a portal page and an optional card on the portal home. A route is served only while its exact descriptor is in the approved snapshot (permissions.routes; declaring or editing one needs approval, and the app needs install_scope admin). A portal (share) user reaches the bridge ONLY through the route run-token the dispatcher mints for that app, route and user — and only api_session (minimal) / api_orm / api_run_hook (the route's json hooks, with that route's rate limit, size cap and audit) / api_watch_hash / api_eval_domain / api_route_token_refresh, within the app's grant bounded by the visitor's own rules. auth: public and website_menu are refused by the validator. A vApp that declares routes sets min_platform 5.53.

5.52

Vizum.assistant.kbSearch(query, {catalogs, topK}): passages from the Knowledge (RAG) catalogs for a vApp holding permissions.assistant — the Assistant's own retrieval (hybrid, rerank, CRAG), run as the CALLING user (their scope and per-reader record filter, never the job user), catalogs the user cannot read refused by name, bounded (query 2000 chars, 20 catalogs, top-k 8, 1500 chars per passage) and traced in Knowledge → Trazas as vapp:<key>. A vApp that reads Knowledge this way (Vapp Creator) sets min_platform 5.52.

5.51

AN EXPLICIT COMPANY ON A company_scoped NATIVE MODEL IS HONOURED, AND VETTED ON WRITE. A create used to replace an explicit x_company_id with env.company, and a write was not checked at all (Odoo re-checks record rules after a create, only before a write), so an app could move a row into a company its user is not in, or make it global. Now an explicit x_company_id — on create, write, a nested line update or a copy default — must be one of env.companies (the browser's active companies; the job user's own companies for a hook), else ValidationError; False on a write is refused; a create naming none is still stamped. A vApp that files rows under another of its user's companies without re-writing x_company_id after the create sets min_platform 5.51.

5.50

MENUS HIDDEN PER USER OR PER GROUP. vizum.menu.hide (menu, users, groups, hidden until, why, app_key) is subtracted from ir.ui.menu._visible_menu_ids — the result Odoo's menu service, the command palette and the Vizum desktop all read — with its submenus. Not an ir.rule: Odoo caches visible menus by GROUP SET, so a per-user rule leaks one user's hiding to everyone with the same groups. Administrators are never subject to it, Settings and Apps cannot be hidden, an empty table costs no query, and uninstalling the vApp that created rows (app_key) deletes them. Admin-only ACL. A vApp that manages hidden menus (Hide Menu) sets min_platform 5.50.

5.49

AN APP'S OWN NATIVE MODELS NEED NO ORM GRANT IN THE BROWSER EITHER. The server (_orm_rule) always granted an app its own native models, and the native fields it added to shared models, without permissions.orm; the browser gate of orm/mail/activity/meta still demanded a non-empty permissions.orm, so a vApp whose only data was its own model got PermissionDenied. The host caps now carry a server-computed orm_native (_client_caps). A vApp that calls its own models without declaring an orm grant sets min_platform 5.49.

5.48

MAP TILES THROUGH THE PLATFORM. OpenStreetMap answers a tile request with no Referer with its "Access blocked" PNG, and a vApp iframe (opaque origin) never sends one. The platform now serves /vizum/tiles/<key>/<token>/<exp>/<z>/<x>/<y>.png (the iframe's run capability is the credential — never an open proxy) and /vizum/tiles/<z>/<x>/<y>.png for a signed-in user: it fetches from OSM identified as the tile usage policy asks, caches on disk for at least 7 days, never caches a refusal, and serves with CORS. The SDK exposes Vizum.map.tileUrl(). A vApp that uses it sets min_platform 5.48.

5.47

WORKFLOW CONTEXT KEYS. api_orm (and V.orm in hooks) accepts, besides lang, the two context keys Odoo's web client itself sends to finish a PARTIAL transfer: skip_backorder and picking_ids_not_to_backorder on stock.picking.button_validate — typed, ids restricted to the call's own (ORM_WORKFLOW_CONTEXT). A 5.46 build refuses them, so a vApp that validates partial transfers in-app (with or without a backorder) gates on 5.47 or hands the transfer to the Odoo form.

5.46

RETIRING A COMPUTED FIELD FREEZES IT INSTEAD OF BREAKING RECOMPUTES. A vApp version that stops declaring a formula field used to archive it by rename (<name>__archived_<id>) with its compute still writing the old name: every recompute of its dependencies raised KeyError(<old name>) — on res.partner no contact could be renamed and no user created (measured on dev with CRM Booster 2.1.0). From 5.46 the archive clears compute/depends first and keeps the stored data, and the 5.46 upgrade repairs fields archived before it. A vApp whose new version retires a computed field sets min_platform 5.46, so the installer refuses the update on an instance without the fix.

5.45

THE PGVECTOR GUIDE CAN FINISH THE JOB. Before it, nothing a vApp could call set the RAG storage mode to pgvector: the "RAG pgvector Setup" guide sent the admin to Managed AI, and Managed AI answered "enable it from the guide". vector.pgvActivate({active, force?}) (admin) switches Mode 3 on — refusing when the infrastructure is missing, when stored vectors are not yet in pgvector (they would drop out of search), or out of managed storage — and back to Local. vector.pgvIndex(opts) exposes the existing per-dimension hnsw op, and pgvStatus adds per-dimension counts and the table size for administrators.

5.44

RAG THAT OBEYS ODOO, AND A DOCUMENT REPLACED IN ONE PIECE. (1) vector.search / dump / indexed_docs and rag.list_chunks withhold every passage derived from an Odoo record the CALLER cannot read under record rules, or whose id now names another record (measured: a global sale.order job served order text to a user with no sales access). (2) vector.delete takes {doc_id, keep_gen} (commit a rewrite: retire every chunk of the doc not of that meta.gen) and {doc_id, gen} (roll a failed rewrite back) — a 5.43 build ignores both keys and deletes the WHOLE document, so a vApp that writes generations gates on 5.44. Also: rag jobs prune records deleted at the source, rag.update changes only the keys it is sent (and keeps the owner), and Ollama chat sends num_ctx + think:false.

5.43

COMPARE-AND-SET ON A NATIVE MODEL: orm.write(model, ids, vals, {expect}) in the JS SDK and V.orm.write(model, ids, vals, expect=…) in the script runtime. The rows are locked (SELECT … FOR UPDATE), re-read, and written only if every expected field still holds its value; the call then resolves to {updated, current} instead of Odoo's bare True. Vizum.db has had this since 5.39 — but ONLY for an app's own tables (api_update), so a native Odoo model had nothing and the only way to CLAIM a record was read-then-write. Two clients that read the same value both wrote it: two approvers of one Agent Center proposal both read pending, both wrote executing, both executed. The same shape reaches money — two registers claiming one IoT print job, two terminals redeeming one gift card. A 5.42 build refuses expect as an unsupported keyword (_orm_bind_args fails closed), so a vApp that relies on it gates on 5.43 rather than silently losing the guarantee.

5.42

vizum.migration.run.action_discover(): the migration plan and the source→target field map are built SERVER-SIDE from both live schemas (models/migration_engine/plan.py), and the run exposes discovery_json / include_master / include_vapps / extra_models. Until 5.42 the plan could only be built by the Migration Assistant's own browser code, from the destination's schema alone — a 5.41 build has no action_discover and the call raises, so a vApp that plans this way gates on 5.42.

5.41

db.share(table, id, {users: ["job_user", …]}): the literal "job_user" resolves server-side to the identity the app's jobs/hooks run as (job_user_id, default installer; never superuser/archived/portal). Lets a row reach the app's automations without being public (Agent Center memory, audit P4). A 5.40 build does int("job_user") and raises, so a vApp that shares this way gates on 5.41.

5.40

V.vector.search(namespace, query, opts) / V.vector.namespaces() in server scripts (hooks and jobs): READ-ONLY, through the same api_vector the iframe uses, gated by permissions.vector, metered on its own per-run budget (20). Lets a scheduled agent consult the knowledge base (Agent Center audit P2). A 5.39 script has no V.vector and fails with AttributeError, so a vApp whose hook uses it gates on 5.40.

5.39

Vizum.db compare-and-set: db.update(table, id, values, {expect: {field: value}}) writes ONLY if the row still holds every expected value, under a row lock, and the result says _updated: true|false. It is what lets two approvers race for the same proposal and have exactly one win (Agent Center audit P1, docs/audits/2026-09-25-agentcenter-rule-reach.md). A 5.38 build drops the fourth argument and writes unconditionally, so a vApp that relies on it gates on 5.39.

5.38

Vizum Instances pass: Vizum.instances.pass() -> {token, expiresAt} behind the new boolean grant permissions.instances_api (privileged; gaining it widens). The server asks the Vizum Store (/store/api/v1/instance/assertion) with this database's instance token — which never reaches the iframe — for a 5-minute pass signed with the Store's Ed25519 key: database, Vizum account, acting user by Odoo email. The Vizum Instances API verifies it with the Store's public key, so no key is pasted by hand into each Odoo (decision 2026-09-24). A 5.37 build has no instances namespace: the call is refused, so the vApp gates on 5.38.

5.37

Report Builder 1.0 (native visual editing of Odoo reports, §3.3 of its spec): four small platform changes, all four lines. reports.html(name, ids) -> {html} — the host fetches /report/html/... and inlines same-origin CSS, because the app iframe is an opaque origin that cannot fetch either itself. permissions.reports accepts "<prefix>.*" and "*" (Report Builder's templates are dynamic: vzm_reportbuilder.template_<id>; an exact-name-only allowlist would force re-approving the manifest per saved template) — "*" is privileged. api_orm kwargs.context now accepts ONLY {"lang": "xx"} (reading an arch without translating it); any other key is refused. _apply_bindings skips (log, don't fail) a binding whose model this base does not have installed, and reconcile() retries it on the next version change.

5.36

native.bindings: a manifest may bind the app to the Action menu of a NATIVE model (native.bindings, one entry per {name, model, label, groups}, gated by the native_bindings grant). The platform compiles one ir.actions.server per binding whose only code calls the trusted dispatcher vizum.app._open_binding, which opens the app with the selected records as Vizum.intent {binding, model, ids}. min_platform 5.36: an older build has no whitelist under native, so bindings is silently ignored — the app installs and the Action-menu entry never appears, which is the silent no-op that makes it a capability. 2026-09-12, still 5.36: a binding may add target: "window" | "modal" (modal = ActionDialog over the record). NOT a bump on purpose: _valid_native_bindings ignores unknown keys, so a 5.36 build installs a manifest that declares target and opens it in a window — a graceful degradation the author can see, not a silent no-op.

5.35

assistant.send accepts the CALLING APP's model / reasoning effort / knowledge base ({model, effort, namespace}). vizum.assistant.pref is per-USER, so before this a vertical vapp's administrator could not fix the AI behaviour for their crew: two technicians in the same app got different models. All three are REQUESTS — the server still caps effort at the user's vizum.ai.policy ceiling and filters the model through it, so an app can never exceed the policy. The forced namespace IS a hard filter over what the model asks for. min_platform 5.35: on an older build the three fields are silently dropped and the app's setting reaches nobody — a silent no-op, which is why it is a capability and not a soft add.

5.34

an AI call may carry ref, an opaque attribution tag naming which of the app's OWN internal consumers spent the tokens (Agent Center names the agent). The host pops it before the provider ever sees it and records it on the same audit row as the charge, so Managed AI can break an app's spend down one level with nothing to reconcile. An app that sends ref MUST declare min_platform 5.34: on an older build the field is not recognised as the host's and is forwarded into the provider request, which rejects the unknown field — so the app installs happily and every AI call fails.

5.33

V.db — the app's own Vizum.db TABLES reached from a server-side script. The store was browser-only: V wired orm/net/oauth/files/ai/data/json, so a SCHEDULED job could not read the very tables its app's UI writes. An app whose cron acts on app-owned state (an automation registry, a retry queue, a schedule) therefore had to mirror that state into a V.data collection and hand-sync two stores for one fact. V.db routes to api_db, the same permission-gated dispatcher the iframe uses, so the manifest schema, the declared rules and indexes, the admin-authored write gate and the acting-user row scoping all still apply. An app whose job reads its own tables MUST declare min_platform 5.33 — on an older build V.db is simply absent and the hook dies with a NameError on its first tick, having installed happily.

5.32

enforcing, delta-aware script triggers. A trigger hook may declare trigger.enforce, which makes the platform REFUSE the triggering write when the hook cannot run instead of proceeding unguarded; and every trigger hook's rec now carries the write's own change set (event, changed, old). Both are load-bearing for a guard: without enforce an archived job user silently disarms it, and without changed it can only assert properties of the post-image, every one of which the caller can satisfy by writing more fields in the same call. An app that relies on either MUST declare min_platform 5.32 — on an older build enforce is ignored and changed is absent, so the guard would install and then quietly not guard.

5.29

native.groups: the schema compiler creates real res.groups for a manifest's declared roles (stable xmlid), so access/rules can reference "@name" instead of every vApp with roles needing a hand-written Odoo addon just to get a group to bind to.

5.28

V.commit() in the JOB runtime + one savepoint/commit PER APP in the job cron. A job POSTs to Instagram (irreversible) and then writes remote_id (undoable). They used to share ONE transaction spanning every job of every app, so any later failure rolled the bookkeeping back while the post stayed published — and the next tick posted it AGAIN.

5.27

Vizum.files.publicUrl — an unguessable but PUBLIC https link to one of the app's own files (permissions.files_public). Instagram has NO byte upload: you hand Meta a URL and Meta downloads it. Without this a social vApp can generate an image and then has no way to put it on the post. revokePublic kills the link once the network has taken it.

5.26

the SOCIAL OAuth rail: shared (brand) connections usable by every user AND by the unattended jobs (permissions.oauth_shared + V.oauth in the script runtime), many accounts per provider (account_ref), PKCE + provider client-auth styles (X, TikTok), Meta's long-lived page-token dance, and a refresh cron so a token cannot lapse overnight and kill the 09:00 post.

5.25

Vizum.ai.image — image GENERATION for vapps (managed mode only). Metered PER IMAGE, not per token, so it needs its own permissions.ai_image on top of permissions.ai.

5.24

Vizum.devices.location — HOST-mediated one-shot GPS fix (devices:["location"]). navigator.geolocation is auto-denied inside the opaque-origin iframe (same reason the mic is host-mediated), so the host asks on its real origin and only {lat,lng,accuracy,ts} crosses.

5.21

Vizum.ui.openUrl — the host opens an external http(s) URL in a new tab. A sandboxed, opaque-origin iframe CANNOT window.open (it returns null and nothing happens), so any vapp that sends the user to Stripe, an OAuth consent screen or a doc link needs this. All shipped.

5.20

server-side vApp code: a manifest jobs[].script runs a native.script.hooks entry as job_user_id, with V.net / V.ai / V.data / V.json (and, from 5.33, V.db) and the time helpers (V.now_odoo, V.add_minutes, V.minutes_between, V.clock). An app that must answer a webhook with nobody's browser open declares min_platform 5.20 — on an older platform its job would install happily and then silently never run.

5.5

Vizum.audio (transcription — local Whisper default / managed metered-per-minute gateway).

5.4

Vizum.ocr (OCR — local Tesseract default / managed metered-per-page gateway)

5.3

AI tools — manifest ai_tools + Vizum.ai.tools.handle (client-handled) + Vizum.ui.openApp(key, payload)

5.2

Vizum.docs (raw-document store for RAG re-indexing) + Vizum.vector.pgv* (Mode-3 local-pgvector setup)

5.1

Vizum.domain (Visual Domain Builder)

5.0

Vizum.vector / Vizum.embed / Vizum.sessions

Concepts

The platform contract — versions, feature detection, stability and errors GENERATED

Everything a vApp can rely on — which API exists, what it needs, since which capability, how stable it is and how it fails — comes from ONE machine-readable file, vizum-platform-contract.json (served at /vizum_apps_platform/static/sdk/vizum-platform-contract.json and shipped inside @vizum/vapp-cli), which the platform, the SDK, the vzm CLI and this page are all built from. A coding agent should read that file (or run vzm context) rather than this page.

Contract 1 · capability 5.86 · SDK 5.86.0 · api version 1 · manifest schema 1.

Using it

await Vizum.connect();

// Which platform, which host — informational; never branch on `build`.
console.log(Vizum.platform.capability, Vizum.platform.host, Vizum.sdk.version);

// Feature-detect before using something newer than your min_platform, or that only
// some hosts serve. On a platform older than 5.67 supports() itself is absent.
const can = (n) => typeof Vizum.supports === "function" && Vizum.supports(n);
if (can("realtime")) { Vizum.realtime.channel("board").on("changed", reload); }
else { Vizum.refresh.on(reload); }                 // Solo has no realtime receive

// Branch on the error's code or category, never on its text.
try {
    await Vizum.orm.write("x_vzm_board", [id], vals, { expect: { x_rev: rev } });
} catch (e) {
    if (Vizum.errors.is(e, "CONFLICT")) { await reloadAndMerge(); }
    else if (e.retryable) { scheduleRetry(); }       // network, timeout, rate limit
    else { Vizum.ui.notify(e.message, "danger"); Vizum.errors.capture(e); }
}

Six versions, six meanings

Gate an app on capability (min_platform) or on a feature (Vizum.supports(...)), never on the platform build or the Odoo version.

Stability policy

Error catalogue

Every failed call rejects with an Error carrying code, category, retryable, correlationId and details (see Vizum.errors). message keeps the text it always had, so code that reads e.message keeps working; new code should test e.code.

Request ids, retries and idempotency

Every call carries a request id (the SDK mints it). It reaches the server, which records it on the audit rows the call produces, and it comes back on a failure as VizumError.correlationId — one id names the call from the iframe to the server's trail (Vizum.audit.search({request_id})). An AI call stores it on its charge too (vizum.ai.usage.request_id, 5.69): a billed charge names the call that caused it. It stays on the instance — it is not sent to the Store with the charge.

Whether a call may be repeated depends on what it does. The rule is explicit per operation:

A key is 8-128 characters of A-Z a-z 0-9 _ . : - (crypto.randomUUID() works), scoped to the app and the user, and lives 8 days (the whole offline window). Only a success is remembered: a call that failed did not happen, and a retry with the same key runs it. A key reused for different arguments rejects with IDEMPOTENCY_MISMATCH instead of returning another operation's result. VizumError.retryable says when repeating the same call can help (lost connection, timeout, rate limit); repeat a write that is not idempotent only with its key.

const key = crypto.randomUUID();                 // one key per business operation
async function save() {
    try { return await Vizum.orm.create("x_vzm_order", vals, { idempotencyKey: key }); }
    catch (e) { if (e.retryable) { return save(); } throw e; }   // safe: same key
}

Permissions

Every grant a manifest can hold, from the same registry the installer's risk tier is checked against (tools/store_risk_tier_matches_contract_test.py). Privileged grants make the app wait for an administrator at install, and the store for a human reviewer; an update that ADDS one is re-approved. *Derived* grants are not written by the author: the validator builds them from another manifest section.

Host features

Vizum.capabilities().features lists what the host the app runs in serves. Detect a feature before relying on it; not every host serves every feature.

API reference

since is set where a capability introduced the member; a member without one predates the capability notes and is available on every supported platform. Permission is what the host gate and the server enforce for the bridge namespace behind the member.

Top level

Vizum._t, Vizum.app (since 5.76), Vizum.capabilities, Vizum.connect, Vizum.env, Vizum.features (since 5.67), Vizum.intent, Vizum.isMobile, Vizum.model, Vizum.onClose (since 5.7), Vizum.onPause (since 5.7), Vizum.onResume (since 5.7), Vizum.onVisibility (since 5.7), Vizum.platform (since 5.67), Vizum.query, Vizum.route, Vizum.scope, Vizum.sdk (since 5.67), Vizum.session, Vizum.supports (since 5.67), Vizum.theme

Signatures (from vizum-sdk.d.ts):

• _t(key: string, ...params: any[]): string — i18n/<lang>.json lookup in the iframe, %s filled in order.
• readonly app: { readonly key: string | null } — SDK 5.76 — this app's own key, sent by the host in the handshake: key is set once connect() resolves (null before, and on a host older than 5.76).
• capabilities(): Vizum.Capabilities
• connect(): Promise<{ caps: Vizum.Caps; theme: any; session: Vizum.Session | null; intent: any; mobile: boolean }>
• env: { mobile: boolean } — SDK v3 runtime environment.
• features(): string[] — SDK 5.67 — the feature ids this host serves (a copy of capabilities().features).
• readonly intent: any
• readonly isMobile: boolean — True on a phone-sized desktop (mirrors env.mobile).
• model<T = Record<string, any>>(name: string): { readonly name: string; search(domain?: Vizum.Domain, opts?: object): Promise<number[]>; searchRead(domain?: Vizum.Domain, fields?: (keyof T & string)[], opts?: object): Promise<Array<Partial<T> & { id: number }>… — A per-model accessor — the no-build equivalent of @vizum/vapp-types' model<T>().
• onClose(cb: (event: Vizum.CloseEvent) => void): Vizum.Subscription — One-shot dispose signal posted just before teardown.
• onPause(cb: (event: Vizum.VisibilityEvent) => void): Vizum.Subscription — Sugar over onVisibility, fired only on the hidden edge (visible === false).
• onResume(cb: (event: Vizum.VisibilityEvent) => void): Vizum.Subscription — Sugar over onVisibility, fired only on the visible edge (visible === true).
• onVisibility(cb: (event: Vizum.VisibilityEvent) => void): Vizum.Subscription — SDK v5.7 lifecycle events (opt-in, advisory; no manifest grant).
• readonly platform: Vizum.PlatformInfo — SDK 5.67 — the platform, its versions and its host (sdk-next/docs/platform-contract.md).
• query(model: string): Vizum.Query — SDK v4 fluent query builder (also Vizum.orm.query).
• readonly route: Vizum.Route | null — SDK 5.53 — the declared route (native.routes) this app was opened on, from a route page (/app/<slug>/<route>[/<sub>] or its /my/<slug>/… alias); null anywhere else.
• scope(): Promise<Vizum.Scope> — SDK 4.1 — what storage scope this app runs in.
• readonly sdk: Vizum.SdkInfo — SDK 5.67 — the runtime SDK's own version and api version.
• readonly session: Vizum.Session | null
• supports(name: string): boolean — SDK 5.67 — true when this platform AND this host serve name: a feature id ("realtime") or an SDK member ("files.publicUrl", "phone").
• readonly theme: { accent: string; dark: boolean }

actions

stability stable · permission: permissions.actions (non-empty)

Members: Vizum.actions.list, Vizum.actions.run

Bridge ops: list, run

• list(): Promise<Array<{ name: string; label: string; model: string; groups: string[] }>>
• run(name: string, params: { ids: number[]; [k: string]: any }, opts?: Vizum.Idempotent): Promise<{ ok: boolean; result: any }> — SDK 5.67 idempotencyKey: a retried run never runs the action twice.

activity

stability stable · permission: permissions.orm (or own native models)

Members: Vizum.activity.done, Vizum.activity.list, Vizum.activity.schedule

Bridge ops: done, list, schedule

• done(model: string, id: number, activityId: number, feedback?: string): Promise<boolean>
• list(model: string, id: number): Promise<Array<{ id: number; summary: string; note: string; date_deadline: string | null; user: [number, string]; type: string; overdue: boolean }>>
• schedule(model: string, id: number, opts: { summary?: string; note?: string; date_deadline?: string; user_id?: number; type?: string }): Promise<{ id: number }>

ai

stability stable · permission: permissions.ai; storeAccount also store_account; billing/byok/instance settings also ai_admin; image also ai_image

Members: Vizum.ai.account, Vizum.ai.appPermissions, Vizum.ai.billing, Vizum.ai.byokFallback, Vizum.ai.byokSet, Vizum.ai.byokStatus, Vizum.ai.chat, Vizum.ai.complete, Vizum.ai.embed, Vizum.ai.getInstanceSettings, Vizum.ai.image (since 5.25), Vizum.ai.managedModels, Vizum.ai.models, Vizum.ai.ragMigrate, Vizum.ai.rerank, Vizum.ai.setAllowedModels, Vizum.ai.setDefaultModel, Vizum.ai.setInstanceSettings, Vizum.ai.storeAccount, Vizum.ai.tools, Vizum.ai.usageByApp, Vizum.ai.usageByUser, Vizum.ai.usageHasRefs

Bridge ops: account, appPermissions, billing, byokFallback, byokSet, byokStatus, chat, complete, embed, getInstanceSettings, image, managedModels, models, ragMigrate, rerank, setAllowedModels, setDefaultModel, setInstanceSettings, storeAccount, usageByApp, usageByUser, usageHasRefs

• account(): Promise<{ mode: string; account_type: string; balance: number; currency: string; trial: { active: boolean; remaining: number; expiry: string | null }; subscription_state: string; subscription_cancel_at?: string | null; data_purge_at?: string | null… — SDK v5.8 admin surface — base.group_system only; others get AccessError.
• appPermissions(payload: { keys: string[] }): Promise<{ rows: Array<{ key: string; name: string; data: string; logic: string | null; ai: boolean; ai_image: boolean; vector: string | null; orm: Array<{ model: string; ops: string[]; write_fields: string[] | null… — Admin only.
• billing(payload: { op: "topup" | "subscribe" | "portal" | "plans"; amount?: number; plan_id?: number }): Promise<{ url?: string; id?: string; plans?: any[] }> — SDK v5.8 admin surface — create or fetch a Stripe Checkout / portal / plans session.
• byokFallback(payload: { value: boolean }): Promise<{ ok: boolean }>
• byokSet(payload: { provider: string; key: string }): Promise<{ ok: boolean }>
• byokStatus(): Promise<{ providers: Array<{ provider: string; has_key: boolean }>; ai_byok_fallback: boolean }> — SDK v5.15 admin — read whether this instance BYOKs (bring your own key) to the Vizum store, per provider (booleans only — the key is never returned).
• chat(payload: { messages?: AiMessage[]; prompt?: string; system?: string; model?: string; max_tokens?: number; temperature?: number; tools?: any[]; /** Extended reasoning budget. Today only the anthropic branch * ('_apply_effort') applies it: raises 'max_toke…
• complete(prompt: string, opts?: { model?: string; system?: string; max_tokens?: number; temperature?: number }): Promise<string>
• embed(input: string | string[], opts?: { model?: string }): Promise<{ vectors: number[][]; model: string }>
• getInstanceSettings(): Promise<VizumAiInstanceSettings> — SDK v5.14 admin surface — instance-wide AI parameters.
• image(payload: { prompt: string; n?: number; size?: string } ): Promise<{ images: string[]; model: string | null; mime: string }> — SDK 5.25 — image GENERATION.
• managedModels(): Promise<{ models: Array<{ id: string; provider: string; model: string; label: string; enabled: boolean }>; all_enabled: boolean; default_model_id: string | null; mode: string; editable: boolean }> — SDK v5.9 admin surface — managed-MODEL selection: the models the owner offers this instance + which are enabled.
• models(): Promise<Array<{ id: string; label: string; provider: string }>>
• ragMigrate(opts?: { dryRun?: boolean }): Promise<{ migrated: number; skipped: Record<string, number>; namespaces: string[] }> — SDK v5.15 admin — local → managed RAG migration.
• rerank(query: string, documents: string[], opts?: { topN?: number; model?: string } ): Promise<{ results: Array<{ index: number; score: number }>; model: string | null }> — SDK v5 listwise reranker (provider-agnostic — runs on the chat model, no Cohere/Jina key).
• setAllowedModels(payload: { model_ids: string[] }): Promise<{ models: Array<{ id: string; provider: string; model: string; label: string; enabled: boolean }>; all_enabled: boolean; default_model_id: string | null; mode: string; editable: boolean }> — Admin: enable a subset of the owner's offered models (clamped to the owner ceiling).
• setDefaultModel(payload: { model_id: string | number }): Promise<{ models: Array<{ id: string; provider: string; model: string; label: string; enabled: boolean }>; all_enabled: boolean; default_model_id: string | null; mode: string; editable: boolean }> — SDK v5.13 admin — the default CHAT model for no-model managed calls (e.g.
• setInstanceSettings(payload: Partial<Pick<VizumAiInstanceSettings, "assistantMaxTokens" | "assistantTimeBudget" | "generalMaxTokens">>): Promise<VizumAiInstanceSettings> — SDK v5.14 — persist any subset of the instance AI parameters (clamped server-side) and return the fresh snapshot.
• storeAccount(payload: { op: "status" } | { op: "logout" } | { op: "login"; email: string; password: string } | { op: "signup"; name: string; email: string; password: string } ): Promise<{ linked: boolean; email?: string; name?: string; can_buy?: boolean; offl… — SDK v5.22 — link / unlink / inspect the Vizum store account from inside the app.
• tools: { handle(name: string, handler: (values: Record<string, any>) => any): void; } — SDK v5.3 — AI TOOLS: let the AI Assistant DRIVE your app.
• usageByApp(payload?: { days?: number }): Promise<{ rows: Array<{ app_id: number | null; key: string | null; name: string; calls: number; tokens_in: number; tokens_out: number; charge: number; /** Per-consumer model usage, judged against the users who ran that… — refs is the app's own Vizum.ai.chat({..., ref}) breakdown — empty when the app never tags a call.
• usageByUser(): Promise<{ rows: Array<{ user_id: number | null; name: string; login: string | null; spend: number; calls: number; tool_calls: number; by_kind: Array<{ kind: string; charge: number; calls: number }> }> }> — SDK v5.8 admin surface — per-user spend + call rollup.
• usageHasRefs(payload?: { days?: number }): Promise<{ available: boolean }> — Admin: cheap yes/no — does any app tag its spend with ref (no 90-day fold)?

apps

stability stable · permission: none (open targets checked against permissions.apps)

Members: Vizum.apps.find, Vizum.apps.health (since 5.67), Vizum.apps.installed, Vizum.apps.open, Vizum.apps.provides, Vizum.apps.requires, Vizum.apps.status (since 5.67)

Bridge ops: find, health, installed, open, provides, requires, status

• find(contract: string): Promise<Array<{ key: string; name: string; version: string; ready: boolean; provides: string[] }>>
• health(): Promise<{ status: "healthy" | "degraded" | "failing"; lifecycle: "running" | "blocked" | "pending_approval" | "disabled" | "withdrawn"; checks: Array<{ name: "state" | "dependencies" | "runtime_errors" | "background_tasks"; status: "healthy" | "degr… — 5.67 — how this app is doing: approval state, dependencies, its own runtime errors and failed background tasks over the last 24 h.
• installed(): Promise<Array<{ key: string; name: string; version: string; ready: boolean; provides: string[] }>>
• open(key: string, payload?: any): Promise<boolean>
• provides(): Promise<string[]>
• requires(): Promise<Array<Vizum.DependencyRow & { key: string; installed: boolean; ready: boolean }>>
• status(): Promise<{ state: "ok" | "degraded" | "blocked"; dependencies: Vizum.DependencyRow[] }> — 5.67 — whether everything this app requires is ready.

assistant

stability stable · permission: permissions.assistant

Members: Vizum.assistant.cancel, Vizum.assistant.confirm, Vizum.assistant.contexts, Vizum.assistant.delete, Vizum.assistant.deleteProject, Vizum.assistant.history, Vizum.assistant.kbInfo, Vizum.assistant.kbSearch (since 5.52), Vizum.assistant.models, Vizum.assistant.newSession, Vizum.assistant.projects, Vizum.assistant.rate, Vizum.assistant.reject, Vizum.assistant.rename, Vizum.assistant.saveProject, Vizum.assistant.send, Vizum.assistant.sessions, Vizum.assistant.setContext, Vizum.assistant.setEffort, Vizum.assistant.setModel, Vizum.assistant.setSessionProject, Vizum.assistant.sourceDoc, Vizum.assistant.thumb, Vizum.assistant.upload

Bridge ops: cancel, confirm, contexts, delete, deleteProject, history, kbInfo, kbSearch, models, newSession, projects, rate, reject, rename, saveProject, send, sessions, setContext, setEffort, setModel, setSessionProject, sourceDoc, thumb, upload

• cancel(sessionId: number): Promise<{ ok: boolean }> — Ask the in-flight turn on this session to abort at its next step.
• confirm(sessionId: number, actionId: number): Promise<Record<string, any>>
• contexts(): Promise<{ available: Array<{ id: number; name: string; industry?: string; section?: string; summary?: string }>; current: number; current_name?: string; locals: Array<{ name: string }> }> — The user's available pre-contextualizations (personas) + their current pick + the applicable LOCAL contexts.
• delete(sessionId: number): Promise<{ ok: boolean }>
• deleteProject(id: number): Promise<{ ok: boolean }>
• history(sessionId: number): Promise<Array<Record<string, any>>>
• kbInfo(): Promise<{ docs: number; namespaces: string[]; names: string[]; tags: string[]; categories: string[] }> — SDK 5.19 — a CHEAP snapshot of the user's Knowledge Base (no LLM): how many documents are actually indexed, the namespaces, and the tag/category vocab.
• kbSearch(query: string, opts?: { catalogs?: string[]; topK?: number }): Promise<{ ok: boolean; catalogs?: string[]; note?: string; error?: { code: string; message?: string }; passages?: Array<{ source: string; text: string; score: number; kind?: string; categ… — SDK 5.52 — passages from the Knowledge (RAG) catalogs THIS user can read, with their sources: the Assistant's own retrieval (hybrid search, rerank), run as the calling user.
• models(): Promise<{ configured: boolean; models: Array<{ id: string; provider: string; model: string; label: string; vision: boolean }>; chosen: string | false }>
• newSession(title?: string, projectId?: number): Promise<{ id: number }>
• projects(): Promise<Array<{ id: number; name: string; persona_id: number; persona_name: string; instructions: string; session_count: number }>> — Per-user chat folders, each with an attached persona.
• rate(sessionId: number, messageId: number | string, rating: "up" | "down"): Promise<{ ok: boolean; message_id?: number; rating?: "up" | "down" }> — SDK 5.19 (active learning, still evolving) — thumbs up/down on ONE assistant message (its id comes from history()/send()'s message_id — a numeric Odoo id, a numeric string also works, the server coerces with int()).
• reject(sessionId: number, actionId: number): Promise<Record<string, any>>
• rename(sessionId: number, title: string): Promise<{ ok: boolean }>
• saveProject(vals: { id?: number; name: string; persona_id?: number; instructions?: string; sequence?: number; active?: boolean }): Promise<Record<string, any>> — Create/update a project.
• send(sessionId: number, text: string, opts?: { /** Multimodal input (SDK v5.11) — attachments from upload(). */ attachments?: Array<{ id: string; route?: string }>; /** SDK v5.19 — the editor document the user is viewing (live-edit awareness). */ active_doc?:…
• sessions(): Promise<Array<Record<string, any>>>
• setContext(id?: number): Promise<{ ok: boolean; context_id: number }> — Pick one of YOUR allowed global contexts (or 0/null to clear).
• setEffort(effort?: "auto" | AiEffort): Promise<{ ok: boolean; effort: string }> — Pick your reasoning EFFORT (extended thinking for Claude & thinking-capable models).
• setModel(model?: string): Promise<{ ok: boolean; model: string }> — Pick the model for YOUR chats (one of your allowed models; ""/null = automatic).
• setSessionProject(sessionId: number, projectId?: number): Promise<{ ok: boolean; project_id: number | false }> — Move a chat into a project (0/null = out of any project).
• sourceDoc(namespace: string, docId: string): Promise<{ ok: boolean; doc?: { doc_id: string; name: string; content_type: string; size: number; data: string } }> — SDK v5.2 — fetch a cited Knowledge SOURCE document for in-chat preview.
• thumb(attachmentId: string): Promise<{ ok: boolean; mime?: string; name?: string; data?: string | null }> — A small image preview for an uploaded attachment (history re-render).
• upload(sessionId: number, data: string, name?: string, mime?: string): Promise<{ attachment_id: string; mime: string; name: string; size: number; session_id: number }> — SDK v5.11 — store an uploaded file (base64) as a session-scoped attachment; keeps bytes OUT of the chat text.

audio

stability stable · since 5.5 · permission: recordClip/recordStop/micLevel: permissions.media ['microphone']; transcribe/status: permissions.audio

Members: Vizum.audio.micLevel, Vizum.audio.recordClip (since 5.10), Vizum.audio.recordStop, Vizum.audio.status, Vizum.audio.transcribe, Vizum.audio.transcribeBatch

Bridge ops: micLevel, recordClip, recordStop, status, transcribe

• micLevel(): Promise<{ level: number; ready: boolean }> — Instantaneous RMS mic level (0..~1) — for a live meter / dead-mic detection.
• recordClip(ms: number | { ms?: number }): Promise<{ b64: string; mime: string; size: number }> — Record ~ms of audio from the mic in-browser -> a clip.
• recordStop(): Promise<{ ok: boolean }> — Release the microphone acquired by recordClip().
• status(): Promise<{ mode: "local" | "managed"; provider: string; available: boolean; credits_per_min?: number | null }> — Which engine is live + a cost hint.
• transcribe(input: File | Blob | string | { data: string; content_type?: string } | { namespace: string; doc_id: string }, opts?: { mode?: "local" | "managed"; language?: string; translate?: boolean; model?: string; onProgress?: (p: { stage?: string; duration?… — input: a File | Blob | base64 string | {data,content_type} | {namespace,doc_id}.
• transcribeBatch(inputs: Array<File | Blob | string>, opts?: { mode?: "local" | "managed"; language?: string; translate?: boolean; model?: string; onProgress?: (p: { item: number; total: number }) => void } ): Promise<{ results: Array<Vizum.AudioResult | { err… — Batch transcribe; per-item progress via opts.onProgress.

audit

stability stable · permission: none (app-scoped); activity: permissions.audit server-side

Members: Vizum.audit.activity, Vizum.audit.log, Vizum.audit.search

Bridge ops: activity, log, search

• activity(query?: { model?: string; res_id?: number; action?: "create" | "write" | "unlink"; user_id?: number; source?: "vapp" | "native"; date_from?: string; date_to?: string; limit?: number; offset?: number }): Promise<Array<{ id: number; ts: string; user: [… — SDK v5: the old->new CHANGE trail the platform captures for the app's declared native.audit models.
• log(action: string, payload?: Record<string, any>): Promise<{ id: number; ts: string }>
• search(query?: { action?: string; user_id?: number; ok?: boolean; date_from?: string; date_to?: string; limit?: number; offset?: number }): Promise<Array<{ id: number; ts: string; user: [number, string]; action: string; payload: Record<string, any>; ok: boole…

backend

stability stable · permission: permissions.actions (non-empty)

Members: Vizum.backend.approve, Vizum.backend.cancel, Vizum.backend.enqueue, Vizum.backend.list, Vizum.backend.progress, Vizum.backend.status

Bridge ops: approve, cancel, enqueue, get, list, progress

• approve(id: number | string): Promise<any>
• cancel(id: number | string): Promise<any>
• enqueue(action: string, params?: Record<string, any>, opts?: Vizum.Idempotent): Promise<{ id: number | string; [k: string]: any }> — SDK 5.67 idempotencyKey: one task per key, however often it is retried.
• list(q?: Record<string, any>): Promise<Vizum.BackendTask[]>
• progress(id: number | string, vals?: { done?: number; total?: number; cursor?: any; /** Report a percentage directly when 'total' isn't known/tracked this call — * used ONLY when 'total' is absent; 'done'/'total' take priority when both are * given. */ progre… — A RUNNING action reports {done,total,cursor?} between batches for a live progress bar + resumable cursor, and gets back {cancel_requested} so it can stop cleanly on a cooperative cancel().
• status(id: number | string): Promise<Vizum.BackendTask>

cutover

stability stable · permission: permissions.cutover (+ administrator)

Members: Vizum.cutover.adopt, Vizum.cutover.release

Bridge ops: adopt, release

• adopt(p?: { app_key?: string; source_db?: string; version?: string; [k: string]: any }): Promise<any>
• release(p?: { app_key?: string; source_db?: string; version?: string; [k: string]: any }): Promise<any>

data

stability stable · permission: none (scope from permissions.data)

Members: Vizum.data.collection, Vizum.data.del, Vizum.data.get, Vizum.data.list, Vizum.data.set, Vizum.data.subscribe

Bridge ops: collection, del, get, list, set, subscribe

• collection<T = any>(name: string): Vizum.Collection<T>
• del(k: string): Promise<boolean>
• get(k: string): Promise<any>
• list(): Promise<string[]>
• set(k: string, v: any): Promise<boolean>
• subscribe(k: string, cb: () => void): Promise<boolean>

db

stability stable · permission: permissions.tables; meta_tables/meta_fields/query_app: permissions.db_cross_read; owner_query: row ACL

Members: Vizum.db.count, Vizum.db.delete, Vizum.db.get, Vizum.db.insert, Vizum.db.insertMany, Vizum.db.insert_many, Vizum.db.meta, Vizum.db.ownerQuery, Vizum.db.queryApp, Vizum.db.search, Vizum.db.share, Vizum.db.update

Bridge ops: count, delete, get, insert, insert_many, meta_fields, meta_tables, owner_query, query_app, search, share, update

• count(table: string, domain?: any[][]): Promise<number>
• delete(table: string, id: string): Promise<boolean>
• get(table: string, id: string): Promise<Record<string, any> | null>
• insert(table: string, values: Record<string, any>): Promise<Record<string, any>>
• insertMany(table: string, rows: Array<Record<string, any>>): Promise<Array<Record<string, any>>> — Bulk insert in one round-trip; returns the created rows (with ids).
• insert_many(table: string, rows: Array<Record<string, any>>): Promise<Array<Record<string, any>>>
• meta: { tables(): Promise<Array<Record<string, any>>>; fields(appKey: string, table: string): Promise<Array<Record<string, any>>>; } — Cross-app Vizum.db read (Phase 4) — PRIVILEGED, READ-ONLY, ACL-bounded.
• ownerQuery(table: string, rowId: string, widgetId: string): Promise<any[]> — Run-as-owner render of a SHARED row's owner-persisted widget query.
• queryApp(appKey: string, table: string, spec?: Record<string, any>): Promise<any>
• search(table: string, domain?: any[][], opts?: { order?: string; limit?: number; offset?: number; scope?: "mine" | "shared" }): Promise<Array<Record<string, any>>>
• share(table: string, id: string, opts: { users?: Array<number | "job_user">; visibility?: "private" | "shared" | "public" }): Promise<any> — 5.41: users may include "job_user" — the identity this app's jobs run as, resolved server-side (never the superuser, an archived or a portal user).
• update(table: string, id: string, values: Record<string, any>, opts?: { expect?: Record<string, any> }): Promise<Record<string, any> & { _updated?: boolean }> — 5.39: opts.expect = compare-and-set — written only if the row still holds those values (row lock); the result then carries _updated: true | false.

dev

stability stable · client-side only (no bridge op)

Members: Vizum.dev.logs

• logs(q?: Record<string, any>): Promise<any[]>

device

stability stable · hosts: device · permission: an auth "device" page (native.routes)

Members: Vizum.device.blobUrl (since 5.70), Vizum.device.cache (since 5.70), Vizum.device.call (since 5.70), Vizum.device.embed (since 5.70), Vizum.device.embeds (since 5.70), Vizum.device.fileUrls (since 5.70), Vizum.device.fullscreen (since 5.70), Vizum.device.info (since 5.70), Vizum.device.onReload (since 5.70), Vizum.device.store (since 5.82)

Bridge ops: blobUrl, cache, call, embed, embedMute, embedPause, embedPlay, embedRemove, embedSetVolume, embedUnmute, embedUpdate, embeds, fileUrls, fullscreen, info, onReload, storeAll, storeDelete, storeGet, storeSet

• blobUrl(url: string): Promise<string | null> — An object URL for url, served from the offline cache when the network is gone.
• cache(urls: string[]): Promise<{ cached: number; bytes: number }> — Pre-fetch URLs into the offline cache (LRU, the page's device.cache_mb).
• call(route: string, payload?: Record<string, any>): Promise<any> — Run the app's device json route route (its hook sees V.device).
• embed(opts: Vizum.DeviceEmbedOptions): Promise<Vizum.DeviceEmbedHandle> — A YouTube / Vimeo player laid over this app by the platform page (a player nested in the sandboxed app frame does not play).
• embeds(): Promise<number> — Remove every player this app opened; resolves with how many.
• fileUrls(route: string, ids: number[]): Promise<Record<string, string>> — Signed URLs (24 h) for records of the device file route route, keyed by id.
• fullscreen(): Promise<boolean> — Ask the platform page to go fullscreen.
• info(): Promise<Vizum.DeviceInfo> — This device: id, name, the record it is linked to, the page it was paired on.
• onReload(cb: () => void): () => void — The administrator pressed "Reload screen".
• store: Vizum.DeviceStore — SDK 5.82 — per-device key/value storage (the app frame has no localStorage).

devices

stability stable · permission: permissions.devices: print | scan | location

Members: Vizum.devices.location (since 5.24), Vizum.devices.onScan, Vizum.devices.print, Vizum.devices.printReceipt, Vizum.devices.readTag, Vizum.devices.scan, Vizum.devices.serialSupported

Bridge ops: location, onScan, print, printReceipt, readTag, scan

• location(opts?: { timeout?: number; maximumAge?: number; highAccuracy?: boolean }): Promise<{ lat: number; lng: number; accuracy: number; ts: number }> — SDK 5.24 (grant devices:["location"]) — one-shot GPS fix, HOST-mediated (geolocation is auto-denied in the opaque-origin iframe).
• onScan(cb: (scan: { type: "nfc" | "rfid"; value: string }) => void): Promise<boolean> — NFC taps + RFID/barcode reader scans captured by the desktop (grant devices:["scan"]).
• print(title: string, lines: string[]): Promise<boolean> — Host-rendered text printing (scriptless).
• printReceipt(lines: Array<string | { text: string; align?: "left" | "center" | "right"; bold?: boolean; size?: "normal" | "double"; underline?: boolean }>, opts?: { cut?: boolean; [k: string]: any }): Promise<boolean> — Send an ESC/POS receipt to the user's default paired printer (grant devices:["print"]).
• readTag(opts?: { timeout?: number }): Promise<{ ok: boolean; type?: "nfc" | "rfid"; value?: string; cancelled?: boolean; degraded?: boolean }> — One-shot ACTIVE NFC/RFID read — "read a tag now", the active twin of onScan (grant devices:["scan"], no new token).
• scan(opts?: Record<string, any>): Promise<{ ok: boolean; text?: string; format?: string; cancelled?: boolean }> — One-shot barcode/QR scan on the native host — the phone camera, or the hardware laser on a rugged PDA (grant devices:["scan"], same grant as onScan/readTag).
• serialSupported(): boolean — Whether navigator.serial is available (declare permissions.devices ["serial"]).

docs

stability stable · client-side only (no bridge op)

Members: Vizum.docs.del, Vizum.docs.get, Vizum.docs.list, Vizum.docs.put

• del(namespace: string, sel: { doc_id?: string } | { all: true }): Promise<{ deleted: number }> — Delete by id or all in the namespace.
• get(namespace: string, docId: string): Promise<{ doc_id: string; name: string; content_type: string; size: number; data: string } | null> — Fetch one document (with its base64 data), or null.
• list(namespace?: string): Promise<Array<{ doc_id: string; name: string; namespace: string; content_type: string; size: number; at: string }>> — List stored documents (metadata only — no bytes).
• put(namespace: string, doc: { doc_id: string; name?: string; content_type?: string; data: string }): Promise<{ doc_id: string; size: number }> — Store/replace a source document.

domain

stability stable · client-side only (no bridge op)

Members: Vizum.domain.compile, Vizum.domain.mount, Vizum.domain.open, Vizum.domain.parse, Vizum.domain.summarize

• compile(ast: any): Promise<Vizum.Domain> — Pure helper: AST -> Odoo domain array.
• mount(elOrId: HTMLElement | string, opts: DomainBuilderOpts): Promise<DomainController> — Mount an inline builder into a container (element or element id).
• open(opts: DomainBuilderOpts): Promise<Vizum.Domain | null> — Open a modal builder; resolves to a domain array, or null if cancelled.
• parse(domain: Vizum.Domain | string): Promise<any> — Pure helper: Odoo domain (array or string) -> editable AST.
• summarize(domain: Vizum.Domain | string, opts?: { model?: string; fields?: DomainField[] }): Promise<string> — Human-readable one-liner for a domain (filter chips / previews).

editable

stability stable · since 5.19 · permission: permissions.editable

Members: Vizum.editable.active, Vizum.editable.apply, Vizum.editable.clear, Vizum.editable.onApply, Vizum.editable.publish

Bridge ops: active, apply, clear, publish

• active(): Promise<{ app_key: string; doc_id: string; title?: string; snapshot: string; tools: Array<{ op: string; args?: any; desc?: string }> } | null>
• apply(appKey: string, docId: string, ops: any[]): Promise<{ ok: boolean }>
• clear(): Promise<{ ok: boolean }>
• onApply(cb: (ops: any[], docId: string) => void): () => void
• publish(reg: { doc_id: string; title?: string; snapshot: string; tools?: Array<{ op: string; args?: any; desc?: string }> }): Promise<{ ok: boolean }>

errors

stability stable · client-side only (no bridge op)

Members: Vizum.errors.capture, Vizum.errors.catalog (since 5.67), Vizum.errors.is (since 5.67), Vizum.errors.normalize (since 5.67), Vizum.errors.retry (since 5.67)

• readonly _count: number — Internal rate-limit counter (capped at 20 per session) — read-only, not something a vApp should set.
• capture(err: any, ctx?: Record<string, any>): Promise<boolean>
• catalog(): Record<Vizum.ErrorCode, { category: Vizum.ErrorCategory; retryable: boolean; legacy: string[]; server: string[] }> — SDK 5.67 — the error catalogue this SDK was built with.
• is(err: unknown, codeOrCategory: Vizum.ErrorCode | Vizum.ErrorCategory): boolean — SDK 5.67 — is(err, "CONFLICT") or is(err, "network"): a code or a category.
• normalize(err: unknown): Vizum.VizumError — SDK 5.67 — any failure (a rejected call, an Error, a string, a resolved {ok: false, error} value) as a VizumError.
• retry<T>(fn: (attempt: number) => Promise<T>, opts?: { retries?: number; baseMs?: number; maxMs?: number }): Promise<T> — SDK 5.67 — retry fn while it fails with a retryable error, with exponential backoff (defaults: retries 3, baseMs 250, maxMs 4000); any other error rejects at once.

events

stability stable · permission: permissions.events.emit / .listen (built-in host events need none)

Members: Vizum.events.catalog (since 5.67), Vizum.events.emit, Vizum.events.on

Bridge ops: catalog, emit:<name>, listen:<name>

• catalog(): Promise<Array<{ name: string; version: number; description: string; schema: Record<string, unknown>; producer: string }>> — 5.67 — the event contracts installed apps declare.
• emit(name: string, payload?: any): Promise<boolean> — Rejects with VALIDATION_FAILED (5.67) when the payload does not match the event's contract in this app's manifest event_contracts.
• on(name: string, cb: (payload: any, meta: Vizum.EventMeta | null) => void): Promise<boolean> — meta (5.67): who emitted the event and the contract version it follows; null for host events and events without a contract's producer.

files

stability stable · permission: none (app-scoped); publicUrl/revokePublic: permissions.files_public

Members: Vizum.files.del, Vizum.files.download, Vizum.files.get, Vizum.files.getBlob (since 5.71), Vizum.files.getRange (since 5.71), Vizum.files.list, Vizum.files.publicUrl (since 5.27), Vizum.files.put, Vizum.files.putBlob (since 5.70), Vizum.files.revokePublic (since 5.27)

Bridge ops: del, download, get, getBlob, getRange, list, publicUrl, put, putBlob, revokePublic

• del(name: string): Promise<boolean>
• download(filename: string, data: Blob | ArrayBuffer | Uint8Array | string, contentType?: string): Promise<boolean> — Save a file to the user's disk.
• get(name: string): Promise<{ name: string; b64: string; mimetype: string; size: number; sha256?: string }>
• getBlob(name: string): Promise<Blob> — SDK 5.71 — the stored file as a Blob, streamed (no base64).
• getRange(name: string, offset: number, length: number): Promise<Uint8Array> — SDK 5.71 — length bytes (at most 32 MB) from offset.
• list(): Promise<Array<{ name: string; size: number; mimetype: string; sha256?: string | null }>> — sha256 is null for a file stored before 5.67 until it is next read.
• publicUrl(name: string, opts?: { expires_in?: number }): Promise<{ name: string; url: string; size: number; mimetype: string; expires_at?: string }> — 5.67: the link expires — opts.expires_in seconds, 60 ..
• put(name: string, b64: string, opts?: { sha256?: string }): Promise<{ name: string; size: number; mimetype?: string; sha256?: string }> — 5.67: the bytes must be what the name says (a .png that is not an image is refused, VALIDATION_FAILED); opts.sha256 — the checksum the app computed — refuses a file damaged on the way.
• putBlob(name: string, blob: Blob, opts?: { sha256?: string; onProgress?: (p: { phase: "hash" | "upload"; sent: number; total: number }) => void }): Promise<{ name: string; size: number; mimetype: string; sha256: string }> — SDK 5.70 — a Blob or File streamed by the host (no base64): past 16 MB, up to permissions.file_limits.max_mb (ceiling 200).
• revokePublic(name: string): Promise<boolean> — Invalidate every public link previously minted for this file.

format

stability stable · client-side only (no bridge op)

Members: Vizum.format.date, Vizum.format.datetime, Vizum.format.money, Vizum.format.number

• date(d: Date | string): string
• datetime(d: Date | string): string
• money(n: number | string): string
• number(n: number | string, decimals?: number): string

help

stability stable · client-side only (no bridge op)

Members: Vizum.help.button, Vizum.help.show

• button(title: string, sections: Array<{ h?: string; p?: string; rows?: [string, string][] }>): HTMLButtonElement
• show(title: string, sections: Array<{ h?: string; p?: string; rows?: [string, string][] }>): void

identity

stability stable · since 5.79 · hosts: desktop, native · permission: none (like ui.confirm): the host asks the user for the account password in its own dialog; the password never reaches the app. A vApp that names Vizum.identity sets min_platform 5.79

Members: Vizum.identity.confirm (since 5.79)

Bridge ops: confirm

• confirm(opts: Vizum.ConfirmRequest): Promise<Vizum.ConfirmResult> — Ask the HOST to re-confirm the user.

import

stability stable · client-side only (no bridge op)

Members: Vizum.import.csv, Vizum.import.open, Vizum.import.pick, Vizum.import.xlsx

• csv(text: string): { columns: string[]; rows: Array<Record<string, any>> } — Parse CSV text (auto-detects , ; tab; full quote handling).
• open(opts?: { accept?: string; requiredColumns?: string[] }): Promise<{ columns: string[]; rows: Array<Record<string, any>>; filename: string }> — Picker + parse in one call; validates opts.requiredColumns.
• pick(accept?: string): Promise<File> — Native file picker; resolves with the chosen File (rejects Error("UserDenied")/Error("NoFile")).
• xlsx(arrayBuffer: ArrayBuffer): Promise<{ columns: string[]; rows: Array<Record<string, any>> }> — Parse an .xlsx ArrayBuffer (native ZIP + inflate + sharedStrings reader).

instances

stability stable · since 5.38 · permission: permissions.instances_api

Members: Vizum.instances.pass (since 5.38)

Bridge ops: pass

• pass(): Promise<{ token: string; expiresAt: number }>

jobs

stability stable · permission: none (the app's own manifest jobs)

Members: Vizum.jobs.list, Vizum.jobs.logs, Vizum.jobs.runNow, Vizum.jobs.status

Bridge ops: list, logs, run_now, status

• list(): Promise<any[]>
• logs(name: string): Promise<any[]>
• runNow(name: string): Promise<any>
• status(name: string): Promise<any>

license

stability stable · permission: none

Members: Vizum.license.current, Vizum.license.openUpgrade, Vizum.license.require

Bridge ops: current, openUpgrade

• current(): Promise<{ licensed: boolean; [k: string]: any }>
• openUpgrade(): Promise<boolean>
• require(): Promise<{ licensed: boolean; [k: string]: any }> — Throws Error("LicenseRequired") AND opens the store when unlicensed.

mail

stability stable · permission: permissions.orm (or own native models)

Members: Vizum.mail.log, Vizum.mail.post

Bridge ops: log, post

• log(model: string, id: number, body: string): Promise<{ id: number }>
• post(model: string, id: number, body: string, opts?: { subject?: string }): Promise<{ id: number }>

map

stability stable · client-side only (no bridge op)

Members: Vizum.map.tileUrl (since 5.48)

• tileUrl(): string

media

stability stable · permission: permissions.rag or permissions.audio

Members: Vizum.media.cancel, Vizum.media.ingest, Vizum.media.jobs, Vizum.media.result, Vizum.media.runNow, Vizum.media.status, Vizum.media.upload

Bridge ops: cancel, ingest, list, result, run_now, status, upload_chunk, upload_finish, upload_init

• cancel(id: number): Promise<{ ok: boolean }>
• ingest(cfg: { source_type: string; source_ref: string; web_url?: string; name?: string; namespace: string; language?: string; max_minutes?: number; scope_kind?: "user" | "group" | "global"; [k: string]: any }): Promise<{ id: number; state: string }>
• jobs(): Promise<Array<Record<string, any>>>
• result(id: number): Promise<{ transcript?: { text: string; segments: any[] }; [k: string]: any }> — -> the transcript once state === 'done'.
• runNow(id: number): Promise<Record<string, any>>
• status(id: number): Promise<{ state: string; progress?: number; duration_s?: number; chunks_indexed?: number; [k: string]: any }>
• upload(file: File | Blob, cfg?: { name?: string; language?: string; translate?: boolean; max_minutes?: number; doc_id?: string; index_rag?: boolean; namespace?: string; scope_kind?: "user" | "group" | "global"; window_seconds?: number; onProgress?: (p: { phas… — SDK v5.21 — chunked upload of a LOCAL GB file → async server transcription.

meta

stability stable · permission: permissions.orm (or own native models)

Members: Vizum.meta.fields, Vizum.meta.models, Vizum.meta.selection

Bridge ops: fields, models, selection

• fields(model: string): Promise<Array<{ name: string; label: string; type: string; required: boolean; readonly: boolean; selection: Array<[string, string]> | null; relation: string | null }>>
• models(): Promise<Array<{ model: string; label: string; ops: string[]; fields: string[] | null }>>
• selection(modelDotField: string): Promise<Array<[string, string]>>

net

stability stable · permission: permissions.net (host allowlist)

Members: Vizum.net.fetch, Vizum.net.fetchImage (since 5.74)

Bridge ops: fetch, fetchImage

• fetch(url: string, opts?: { method?: string; headers?: Record<string, string>; body?: any; timeout?: number }): Promise<{ status: number; ok: boolean; headers: Record<string, string>; binary: boolean; body: string; json?: any }> — Headers / URL / string bodies may carry $secret:name placeholders — substituted server-side, the value never reaches the browser.
• fetchImage(url: string, opts?: { max_bytes?: number; timeout?: number }): Promise<{ content_type: "image/png" | "image/jpeg" | "image/gif" | "image/webp"; size: number; sha256: string; base64: string }> — SDK 5.74 — download ONE image server-side.

notifications

stability stable · permission: none (app + user scoped)

Members: Vizum.notifications.clear, Vizum.notifications.count, Vizum.notifications.create, Vizum.notifications.list, Vizum.notifications.markRead

Bridge ops: clear, count, create, list, mark_read

• clear(): Promise<boolean>
• count(unread?: boolean): Promise<number>
• create(n: { title: string; body?: string; priority?: "low" | "normal" | "high"; user_id?: number; action?: Record<string, any> }): Promise<AppNotification>
• list(query?: { unread?: boolean; limit?: number; offset?: number }): Promise<AppNotification[]>
• markRead(ids: number[], value?: boolean): Promise<boolean>

oauth

stability stable · permission: permissions.oauth

Members: Vizum.oauth.accounts, Vizum.oauth.configure, Vizum.oauth.configured, Vizum.oauth.connect, Vizum.oauth.connected, Vizum.oauth.disconnect, Vizum.oauth.fetch, Vizum.oauth.status

Bridge ops: configure, connect, disconnect, fetch, status

• accounts(provider: string): Promise<Array<{ account_ref: string; name: string; shared: boolean; expired: boolean }>> — SDK 5.26 — the accounts of one provider (see status().accounts).
• configure(provider: string, conf: { client_id: string; client_secret: string; scopes: string; auth_url?: string; token_url?: string; api_base?: string; }): Promise<{ ok: boolean; configured: boolean }> — Admin-only: store the provider's client_id/secret/scopes in the DB registry.
• configured(provider: string): Promise<boolean> — True once an admin has configured the provider's client_id/secret/scopes.
• connect(provider: string, opts?: { shared?: boolean } ): Promise<{ provider: string; connected: boolean }> — Host-opened consent popup; resolves when the provider round-trip lands.
• connected(provider: string): Promise<boolean>
• disconnect(provider: string, account?: string | null): Promise<boolean> — account = "" for the caller's own connection, or a page/business id.
• fetch(provider: string, path: string, opts?: { method?: string; headers?: Record<string, string>; body?: any }): Promise<{ status: number; ok: boolean; headers: Record<string, string>; binary: boolean; body: string; json?: any }> — Proxied call to the provider's api_base with the user's token injected.
• status(): Promise<Array<{ provider: string; configured: boolean; connected: boolean; /** SDK 5.26 — the accounts this caller can act as. A brand with five Facebook * pages is FIVE entries, not one boolean. 'expired' = the token lapsed and * cannot be refreshe…

ocr

stability stable · since 5.4 · permission: permissions.ocr

Members: Vizum.ocr.recognize, Vizum.ocr.recognizeBatch, Vizum.ocr.scan, Vizum.ocr.status

Bridge ops: recognize, status

• recognize(input: File | Blob | string | { data: string; content_type?: string } | { namespace: string; doc_id: string }, opts?: { want?: "text" | "blocks" | "tables"; languages?: string[]; mode?: "local" | "managed"; pages?: string; dpi?: number; preprocess?:… — input: a File | Blob | base64 string | {data,content_type} | {namespace,doc_id}.
• recognizeBatch(inputs: Array<File | Blob | string>, opts?: { want?: "text" | "blocks" | "tables"; languages?: string[]; onProgress?: (p: { item: number; total: number }) => void } ): Promise<{ results: Array<Vizum.OcrResult | { error: string }>; pages_total: … — Batch recognise; per-item progress via opts.onProgress.
• scan(opts?: { want?: "text" | "blocks" | "tables"; languages?: string[]; camera?: boolean; mode?: "local" | "managed"; pages?: string; dpi?: number; preprocess?: boolean; model?: string; onProgress?: (p: { page: number; total: number }) => void } ): Promise<V… — Quick capture UI (file, or the device camera with camera: true) → an OcrResult, or null if cancelled.
• status(): Promise<{ mode: "local" | "managed"; provider: string; languages?: string[]; available: boolean; credits_per_page?: number | null }> — Which engine is live + a cost hint.

offline

stability stable · permission: status/pending: none; run/flush: permissions.actions; datasets/sync/query/readGroup/conflicts/resolve: permissions.offline.datasets; create/write: permissions.offline.writes (5.80)

Members: Vizum.offline.conflicts (since 5.80), Vizum.offline.create (since 5.80), Vizum.offline.datasets (since 5.80), Vizum.offline.flush, Vizum.offline.on, Vizum.offline.onConflict (since 5.80), Vizum.offline.onFlushed, Vizum.offline.onSync (since 5.80), Vizum.offline.pending, Vizum.offline.query (since 5.80), Vizum.offline.readGroup (since 5.80), Vizum.offline.resolve (since 5.80), Vizum.offline.run, Vizum.offline.status, Vizum.offline.sync (since 5.80), Vizum.offline.write (since 5.80)

Bridge ops: conflicts, create, datasets, flush, pending, query, readGroup, resolve, run, status, sync, write

• conflicts(): Promise<Vizum.OfflineConflict[]> — SDK 5.80 — the changes the server refused as a conflict and that wait for a decision.
• create(model: string, vals: Record<string, any>, opts?: Vizum.Idempotent & { expect?: Record<string, any> }): Promise<{ id: string; queued: true; opId: string }> — SDK 5.80 — queue a create (a model in offline.writes with op create).
• datasets(): Promise<Vizum.OfflineDataset[]> — SDK 5.80 — the datasets the manifest's offline.datasets declares, with what the device holds of each.
• flush(): Promise<{ sent: number; failed: Array<{ id: string; error: string }>; remaining: number }>
• on(cb: (s: { online: boolean }) => void): void
• onConflict(cb: (c: Vizum.OfflineConflict) => void): { stop(): void } — SDK 5.80 — a queued change came back as a conflict.
• onFlushed(cb: (r: { sent: number; remaining: number }) => void): void
• onSync(cb: (r: Vizum.OfflineSyncResult) => void): { stop(): void } — SDK 5.80 — a dataset finished syncing.
• pending(): Promise<Array<{ id: string; action: string; params: object; ts: number }>>
• query(name: string, opts?: Vizum.OfflineQuery): Promise<Vizum.OfflineQueryResult> — SDK 5.80 — read a dataset from the device: domain (= != < <= > >= in not in like ilike =like =ilike, & | !), order, limit, offset, fields.
• readGroup(name: string, opts: Vizum.OfflineReadGroup): Promise<Array<Record<string, any>>> — SDK 5.80 — a read_group over a dataset, on the device: one or two groupby fields (date fields with :day|week|month|quarter|year), aggregates field:count|sum|avg|min|max.
• resolve(id: number, choice: "keep_mine" | "keep_server" | "discard"): Promise<{ resolved: boolean; choice: string }> — SDK 5.80 — settle one: keep_mine sends it again over the server's values, keep_server drops it and shows the server's values, discard drops it.
• run(action: string, params?: { ids?: number[]; [k: string]: any }, opts?: Vizum.Idempotent): Promise<{ ok: boolean; result: any } | { id: string; queued: true }>
• status(): Promise<{ online: boolean }>
• sync(name?: string): Promise<{ datasets: Vizum.OfflineSyncResult[] }> — SDK 5.80 — bring one dataset (or all) up to date now.
• write(model: string, ids: Array<number | string>, vals: Record<string, any>, opts?: Vizum.Idempotent): Promise<{ queued: true; opId: string; opIds: string[] }> — SDK 5.80 — queue a write (a model in offline.writes with op write).

orm

stability stable · permission: permissions.orm (or own native models); per-model ops, fields, domain

Members: Vizum.orm.call, Vizum.orm.callOn, Vizum.orm.create, Vizum.orm.live, Vizum.orm.query, Vizum.orm.read, Vizum.orm.readGroup, Vizum.orm.search, Vizum.orm.searchCount, Vizum.orm.searchRead, Vizum.orm.unlink, Vizum.orm.watch, Vizum.orm.write, Vizum.orm.writeBlob (since 5.70)

• call(model: string, method: string, args?: any[], opts?: { context?: Vizum.OrmContext }): Promise<any> — opts.context: see {@link Vizum.OrmContext}.
• callOn(model: string, ids: number[], method: string, args?: any[], opts?: { context?: Vizum.OrmContext }): Promise<any> — opts.context: see {@link Vizum.OrmContext}.
• create(model: string, vals: object, opts?: { context?: Vizum.OrmContext } & Vizum.Idempotent): Promise<number[]> — SDK 5.67 idempotencyKey: a retry with the same key never creates a second record.
• live(renderFn: () => any, opts?: { interval?: number; debounce?: number; models?: string[] }): { refresh(): void; stop(): void } — SDK v5.4 — LIVE DATA the easy way.
• query(model: string): Vizum.Query
• read(model: string, ids: number[], fields?: string[]): Promise<any[]>
• readGroup(model: string, domain: Vizum.Domain, groupby: string[], aggregates: string[], opts?: { limit?: number; offset?: number; order?: string }): Promise<any[]>
• search(model: string, domain?: Vizum.Domain, opts?: object): Promise<number[]>
• searchCount(model: string, domain?: Vizum.Domain): Promise<number>
• searchRead(model: string, domain?: Vizum.Domain, fields?: string[], opts?: object): Promise<any[]>
• unlink(model: string, ids: number[]): Promise<boolean>
• watch(model: string, domain: Vizum.Domain, cb: (h: { count: number; max_write: string | null }) => void, opts?: { interval?: number }): Vizum.Watcher
• write(model: string, ids: number | number[], vals: object, opts?: { expect?: Record<string, unknown>, context?: Vizum.OrmContext }): Promise<boolean | { updated: boolean; current: Record<string, unknown> }> — With opts.expect ({field: value}, SDK 5.43) this is a COMPARE-AND-SET on a NATIVE model: the rows are locked, re-read, and written only if every expected field still holds its value — and it resolves to `{updated, cur…
• writeBlob(model: string, id: number, field: string, blob: Blob): Promise<{ id: number; field: string; size: number; sha256: string }> — SDK 5.70 — stream a file into a binary field of one record (what a device file route plays); checked like write(model, [id], {[field]: base64}).

pairedDevices

stability stable · hosts: desktop, native, solo · permission: native.routes with auth "device" (permissions.device_routes); changes need base.group_system

Members: Vizum.pairedDevices.claim (since 5.70), Vizum.pairedDevices.link (since 5.70), Vizum.pairedDevices.list (since 5.70), Vizum.pairedDevices.reload (since 5.70), Vizum.pairedDevices.rename (since 5.70), Vizum.pairedDevices.revoke (since 5.70)

Bridge ops: claim, link, list, reload, rename, revoke

• claim(pin: string, opts: { name: string; link?: number | null }): Promise<Vizum.PairedDevice> — Claim the PIN a device page shows; the device receives its token on its next poll.
• link(id: number, link: number | null): Promise<Vizum.PairedDevice>
• list(): Promise<Vizum.PairedDevice[]>
• reload(id: number): Promise<Vizum.PairedDevice> — The screen reloads on its next heartbeat.
• rename(id: number, name: string): Promise<Vizum.PairedDevice>
• revoke(id: number): Promise<{ ok: true }> — Unpair: the device's token dies now and the page returns to the PIN screen.

perf

stability stable · permission: none (sessions: administrator)

Members: Vizum.perf.desktop, Vizum.perf.ping, Vizum.perf.sessions

Bridge ops: desktop, ping, sessions

• desktop(): Promise<{ windows: { total: number; open: number; minimized: number; vapps: number; actions: number; byKind: Record<string, number>; activeId: number | null }; memory: { heapMB: number; totalMB: number; limitMB: number; pct: number } | null; fps: n… — This browser tab's live runtime: windows open, JS heap, sampled FPS, desktop state.
• ping(): Promise<{ latencyMs: number; server: { ts: string; uid: number } }> — Round-trip latency (ms) of a cheap server call — a proxy for how busy the Odoo server is (server CPU/RAM are not exposed to apps).
• sessions(): Promise<{ supported: boolean; online_users: number | null; online_mine: number; sessions_total: number | null; sessions_mine: number | null; sessions_note?: string }> — ADMIN only: active-session counts across the instance.

permissions

stability stable · permission: none

Members: Vizum.permissions.explain, Vizum.permissions.raw

Bridge ops: explain, raw

• explain(): Promise<Array<{ capability: string; detail: string; risk: "low" | "medium" | "high" }>>
• raw(): Promise<Record<string, any>>

phone

stability stable · since 5.31 · hosts: desktop · permission: permissions.media ['microphone']

Members: Vizum.phone.answer, Vizum.phone.dial, Vizum.phone.dtmf, Vizum.phone.hangup, Vizum.phone.mute, Vizum.phone.onState, Vizum.phone.register, Vizum.phone.state, Vizum.phone.unregister

Bridge ops: answer, dial, dtmf, hangup, mute, register, state, unregister

• answer(): Promise<any> — Answer what is ringing.
• dial(opts?: Record<string, any>): Promise<any>
• dtmf(digits: string): Promise<any>
• hangup(): Promise<any> — Ends a live call, and REJECTS one that never got answered — a BYE on an unestablished session is ignored and the caller keeps ringing.
• mute(on?: boolean): Promise<any>
• onState(cb: (state: string) => void): () => void — "registered" | "registration" | "ringing" | "dialing" | "answered" | "ended" | "mute" | "audio_blocked" | "transport_down"
• register(ticket?: Record<string, any>): Promise<any>
• state(): Promise<any>
• unregister(): Promise<any>

rag

stability stable · permission: permissions.rag

Members: Vizum.rag.create, Vizum.rag.estimate, Vizum.rag.feedback, Vizum.rag.fields, Vizum.rag.groups, Vizum.rag.indexDoc, Vizum.rag.jobs, Vizum.rag.listChunks, Vizum.rag.models, Vizum.rag.remove, Vizum.rag.runNow, Vizum.rag.update

Bridge ops: create, delete, estimate, feedback, fields, groups, index_doc, list, list_chunks, models, run_now, update

• create(cfg: { name: string; model_name: string; domain?: Vizum.Domain; namespace: string; field_names: string[]; scope_kind?: "user" | "group" | "global"; interval_number?: number; interval_type?: "minutes" | "hours" | "days"; max_per_run?: number; [k: string…
• estimate(cfgOrId: number | Record<string, any>): Promise<{ ok: boolean; pending: number; this_run: number; est_chunks: number; per_record: number; note?: string }> — Estimate a SAVED job (pass its id) or an ad-hoc config object.
• feedback(cfg: { ns?: string; namespace?: string; docIds?: string | string[]; doc_ids?: string | string[]; rating: "good" | "ok" | "bad"; q?: string; question?: string; a?: string; answer?: string }): Promise<{ ok: boolean }> — SDK 5.19 (active learning, still evolving) — rate an answer/its sources good | ok | bad, tagged with the doc_id(s) it was grounded in.
• fields(model: string): Promise<Array<Record<string, any>>> — A model's text+binary fields.
• groups(): Promise<Array<Record<string, any>>> — Admin — groups eligible for shared-scope jobs.
• indexDoc(cfg: { namespace: string; doc_id: string; name?: string; content_type?: string; scope?: string }): Promise<{ ok: boolean; doc_id: string; chunks: number; kinds: { text: number; table: number; image: number } }> — SDK v5.19 — MULTIMODAL index of an already-uploaded document (its bytes stored via Vizum.docs).
• jobs(): Promise<Array<Record<string, any>>>
• listChunks(cfg: Record<string, any>): Promise<Array<Record<string, any>>>
• models(): Promise<Array<Record<string, any>>> — Indexable models.
• remove(id: number): Promise<{ deleted: boolean }>
• runNow(id: number): Promise<Record<string, any>>
• update(cfg: { id: number; [k: string]: any }): Promise<Record<string, any>>

realtime

stability stable · permission: none (app-scoped)

Members: Vizum.realtime.channel

Bridge ops: publish, subscribe, unsubscribe

• channel(name: string): RealtimeChannel

refresh

stability stable · client-side only (no bridge op)

Members: Vizum.refresh.on

• on(cb: () => void, opts?: { interval?: number; debounce?: number; models?: string[] }): { refresh(): void; stop(): void }

reports

stability stable · permission: permissions.reports (per report name)

Members: Vizum.reports.data, Vizum.reports.download, Vizum.reports.html

Bridge ops: data, download, html

• data(reportName: string, ids: number[]): Promise<{ b64: string; size: number }> — SDK v3: the PDF as bytes for re-upload (e.g.
• download(reportName: string, ids: number[], filename?: string): Promise<boolean>
• html(reportName: string, ids: number[]): Promise<{ html: string }> — Report Builder 1.0: a self-contained HTML string (same-origin CSS already inlined, <script> stripped) — for a live preview inside the app; the app iframe cannot fetch /report/html/...

roles

stability stable · permission: none

Members: Vizum.roles.has, Vizum.roles.list, Vizum.roles.mine

Bridge ops: has, list, mine

• has(name: string): Promise<boolean>
• list(): Promise<Array<{ name: string; label: string; active: boolean }>>
• mine(): Promise<string[]>

scope

stability stable · permission: none

Bridge ops: get

script

stability stable · permission: permissions.logic = 'script'

Members: Vizum.script.run

Bridge ops: run

• run(name: string, payload?: Record<string, any>): Promise<any>

secrets

stability stable · permission: permissions.secrets

Members: Vizum.secrets.configure, Vizum.secrets.exists, Vizum.secrets.names

Bridge ops: configure, names

• configure(name: string): Promise<{ name: string; configured: boolean }> — Host-rendered dialog where an ADMIN types the value (rejects Error("UserDenied") on cancel).
• exists(name: string): Promise<boolean>
• names(): Promise<Array<{ name: string; configured: boolean }>> — Every manifest-declared secret + whether an admin configured it.

sessions

stability stable · permission: permissions.sessions (+ administrator)

Members: Vizum.sessions.getPolicy, Vizum.sessions.revoke, Vizum.sessions.revokeUser, Vizum.sessions.setActivityAudit, Vizum.sessions.setActivityAuditGlobal, Vizum.sessions.setLoginAlerts, Vizum.sessions.setSessionTimeout

Bridge ops: getPolicy, revoke, revokeUser, setActivityAudit, setActivityAuditGlobal, setLoginAlerts, setSessionTimeout

• getPolicy(): Promise<{ login_alerts: boolean; session_timeout: { enabled: boolean; hours: number; min_hours: number }; activity_audit: { enabled: boolean; global: boolean }; supported: boolean }> — Read the session security policy.
• revoke(deviceId: number): Promise<{ revoked: number[] }> — Revoke one session by its res.device id (signs that session out).
• revokeUser(userId: number): Promise<{ revoked: number[] }> — Revoke ALL of a user's other sessions by res.users id.
• setActivityAudit(on: boolean): Promise<{ login_alerts: boolean; session_timeout: { enabled: boolean; hours: number; min_hours: number }; activity_audit: { enabled: boolean; global: boolean }; supported: boolean }> — Master switch for the activity audit (admin).
• setActivityAuditGlobal(on: boolean): Promise<{ login_alerts: boolean; session_timeout: { enabled: boolean; hours: number; min_hours: number }; activity_audit: { enabled: boolean; global: boolean }; supported: boolean }> — ADVANCED master switch: also audit native-UI / RPC writes (a global per-write hook on the whole DB).
• setLoginAlerts(on: boolean): Promise<{ login_alerts: boolean; session_timeout: { enabled: boolean; hours: number; min_hours: number }; activity_audit: { enabled: boolean; global: boolean }; supported: boolean }> — Enable/disable in-app "new sign-in" alerts (admin; needs Odoo 18+).
• setSessionTimeout(on: boolean, hours?: number): Promise<{ login_alerts: boolean; session_timeout: { enabled: boolean; hours: number; min_hours: number }; activity_audit: { enabled: boolean; global: boolean }; supported: boolean }> — Enable/disable idle-session auto-revoke after hours (admin; needs Odoo 18+).

settings

stability stable · permission: none (set: administrator)

Members: Vizum.settings.get, Vizum.settings.open, Vizum.settings.set (since 5.35)

Bridge ops: get, open, set

• get(): Promise<Record<string, any>> — Stored values with manifest defaults merged in.
• open(): Promise<Record<string, any>> — Opens the host settings dialog (admin saves; rejects Error("UserDenied") on cancel).
• set(values: Record<string, any>): Promise<Record<string, any>> — SDK 5.35 — write the app's own settings from the app's own form, for choices whose options only exist at runtime (models this gateway offers, knowledge bases that exist).

team

stability stable · since 5.60 · permission: permissions.team

Members: Vizum.team.invite, Vizum.team.members, Vizum.team.remove, Vizum.team.roles, Vizum.team.save, Vizum.team.setActive, Vizum.team.setPassword, Vizum.team.whoami (since 5.65)

Bridge ops: invite, members, remove, roles, save, set_active, set_password, whoami

• invite(id: number): Promise<boolean> — Send the sign-up / reset-password email (needs auth_signup).
• members(): Promise<Vizum.TeamMember[]>
• remove(id: number): Promise<boolean> — Take away every role of this app (the user's other groups stay).
• roles(): Promise<Array<{ name: string; label: string; help: string }>>
• save(member: { id?: number; name?: string; login?: string; email?: string; phone?: string; role: string; password?: string }): Promise<Vizum.TeamMember> — Create (no id) or update a member; role is a role name from the manifest.
• setActive(id: number, active: boolean): Promise<Vizum.TeamMember>
• setPassword(id: number, password: string): Promise<boolean>
• whoami(): Promise<{ uid: number; manager: boolean; role: string | false }> — SDK 5.65 — the caller: is a manager of the team, and the role they play.

telemetry

stability stable · permission: none

Members: Vizum.telemetry.summary, Vizum.telemetry.track

Bridge ops: summary, track

• summary(query?: { event?: string; date_from?: string; date_to?: string }): Promise<{ totals: Record<string, number>; total: number }>
• track(event: string, n?: number): Promise<boolean>

ui

stability stable · permission: permissions.ui lists the op (confirm/openHtml/openDocument/exitFullscreen always allowed)

Members: Vizum.ui.addPaletteCommand, Vizum.ui.confirm, Vizum.ui.editDomain, Vizum.ui.evalDomain, Vizum.ui.exitFullscreen (since 5.85), Vizum.ui.fullscreen (since 5.85), Vizum.ui.notify, Vizum.ui.onFullscreenChange (since 5.85), Vizum.ui.openApp, Vizum.ui.openDocument, Vizum.ui.openHtml, Vizum.ui.openList, Vizum.ui.openRecord, Vizum.ui.openUrl (since 5.21), Vizum.ui.pinWidget, Vizum.ui.setBadge, Vizum.ui.sound

Bridge ops: addPaletteCommand, confirm, editDomain, evalDomain, exitFullscreen, fullscreen, notify, openApp, openDocument, openHtml, openList, openRecord, openUrl, pinWidget, setBadge, sound

• addPaletteCommand(label: string): Promise<boolean>
• confirm(message: string, title?: string): Promise<boolean> — The host's own confirmation dialog (Odoo's, never window.confirm): true on Confirm, false on Cancel, Escape or close.
• editDomain(model: string, domain?: string, title?: string): Promise<string | null> — Host-rendered REAL Odoo domain builder (DomainSelectorDialog).
• evalDomain(domainStr: string): Promise<Vizum.Domain> — Evaluate an Odoo domain STRING into a concrete domain ARRAY in the host (py.js), resolving relative-date virtual operators.
• exitFullscreen(): Promise<{ active: boolean; browser: boolean; supported?: false }> — SDK 5.85: hand the screen back.
• fullscreen(on?: boolean): Promise<{ active: boolean; browser: boolean; supported?: false }> — SDK 5.85 (grant "fullscreen"): take the whole screen for this app.
• notify(msg: string, type?: "info" | "success" | "warning" | "danger"): Promise<boolean>
• onFullscreenChange(cb: (e: { active: boolean }) => void): () => void — SDK 5.85: cb({ active: false }) when the full screen ends for a reason the app did not ask for (the host's Exit button, Escape, the browser leaving fullscreen).
• openApp(key: string, payload?: any): Promise<boolean> — Open another INSTALLED vapp by key (grant "openApp").
• openDocument(doc: { data: string; contentType: string; name?: string }): Promise<{ opened: boolean; mode: "view" | "download"; popupBlocked?: boolean }> — Open the app's OWN stored document (a KB source PDF, an image, a text file).
• openHtml(html: string, title?: string): Promise<boolean> — Open a self-contained HTML document (e.g.
• openList(model: string, domain?: Vizum.Domain, label?: string): Promise<boolean>
• openRecord(model: string, id: number, label?: string): Promise<boolean>
• openUrl(url: string): Promise<boolean> — Open an EXTERNAL http(s) URL in a new tab.
• pinWidget(spec: { label: string; model: string; measure?: string; domain?: Vizum.Domain; format?: string; icon?: string; [k: string]: any }): Promise<boolean> — SDK 4.1 (grant "pinWidget"): pin a LIVE KPI to the desktop.
• setBadge(n: number | string): Promise<boolean>
• sound(name?: "message" | "notification" | "share" | "snap" | "trash" | "error"): Promise<boolean> — SDK 5.30 — a short synthesized chime for an event the user should HEAR (an arriving chat message above all).

user

stability stable · permission: none

Members: Vizum.user.groups, Vizum.user.id, Vizum.user.inGroup, Vizum.user.info, Vizum.user.isAdmin, Vizum.user.isSystem, Vizum.user.login, Vizum.user.name

Bridge ops: groups, in_group, info

• groups(): Promise<string[]>
• id: number
• inGroup(xmlid: string): Promise<boolean>
• info(): Promise<{ id: number; name: string; login: string; isAdmin: boolean; isSystem: boolean; lang: string; tz: string; company: { id: number; name: string } }>
• isAdmin: boolean
• isSystem: boolean
• login: string
• name: string

vector

stability stable · permission: permissions.vector

Members: Vizum.vector.del, Vizum.vector.dump, Vizum.vector.getDocAccess, Vizum.vector.global, Vizum.vector.graph, Vizum.vector.graphClear, Vizum.vector.graphDocs, Vizum.vector.graphRecompute, Vizum.vector.indexedDocs, Vizum.vector.moveScope (since 5.83), Vizum.vector.namespaces, Vizum.vector.pgvActivate, Vizum.vector.pgvBackfill, Vizum.vector.pgvIndex, Vizum.vector.pgvProvision, Vizum.vector.pgvStatus, Vizum.vector.principals, Vizum.vector.search, Vizum.vector.setDocAccess, Vizum.vector.sharedNamespaces (since 5.83), Vizum.vector.stats, Vizum.vector.tags, Vizum.vector.unpack, Vizum.vector.upsert

Bridge ops: delete, docdelete, docget, doclist, docput, dump, get_doc_access, global, graph, graph_clear, graph_docs, graph_recompute, indexed_docs, move_scope, namespaces, pgvactivate, pgvbackfill, pgvindex, pgvprovision, pgvstatus, principals, search, set_doc_access, shared_namespaces, stats, tags, upsert

• del(namespace: string, sel: { id?: number | number[] } | { doc_id?: string | string[] } | { doc_id: string | string[]; gen: string | number } | { doc_id: string | string[]; keep_gen: string | number } | { all: true }): Promise<{ deleted: number }> — {doc_id, keep_gen} (platform 5.44) retires every chunk of the doc whose meta.gen is not keep_gen (commit a rewrite); {doc_id, gen} retires only that generation (roll a failed rewrite back).
• dump(namespace: string, opts?: { offset?: number; limit?: number }): Promise<{ namespace: string; dim: number; model: string | null; total: number; offset: number; limit: number; items: Array<{ id: number; doc_id: string; seq: number; text: string; meta: Reco… — Small-corpus offline fallback (packed base64 float32; refused above a few thousand vectors).
• getDocAccess(namespace: string, docId: string): Promise<{ is_public: boolean; users: Array<{ id: number; name: string }>; groups: Array<{ id: number; name: string }>; can_manage: boolean }> — Per-document ACCESS grants (users / groups / public=internal).
• global(namespace: string, query: string, opts?: Record<string, any>): Promise<Array<{ cid: string; title: string; summary: string; size: number; rank: number; member_names: string[] }>> — GraphRAG G2 global/map-reduce — the community summaries most relevant to query (broad/thematic "what are the main themes" questions).
• graph(namespace: string): Promise<{ entities: Array<{ name: string; type: string; rank: number; mentions: number; community: number }>; edges: Array<{ src: string; dst: string; relation: string; weight: number }> }> — GraphRAG G1 — the knowledge graph for a namespace: entities (with PageRank rank + community) + relation edges (scoped like the chunks).
• graphClear(namespace: string): Promise<{ ok: boolean; cleared: number }> — WIPE the namespace's knowledge graph for the caller's writable scope(s) so it can be rebuilt clean.
• graphDocs(namespace: string): Promise<{ doc_ids: string[]; counts: Record<string, number> }> — Which documents in a namespace are IN the knowledge graph (the per-doc "in the graph" indicator's authoritative data source) + how many entities mention each.
• graphRecompute(namespace: string): Promise<{ communities: number; summarized: number; entities_described: number; entities: number; edges: number } | { busy: true }> — GraphRAG on-demand recompute: rebuild the namespace's graph NOW (PageRank + community detection/summaries + entity descriptions) for the CALLER's writable scope, so a "Temas" panel fills right after ingest instead of wa…
• indexedDocs(namespace: string): Promise<{ doc_ids: string[]; counts: Record<string, number>; degraded?: boolean; degraded_reason?: string }> — Which documents are ACTUALLY indexed on the server for namespace, in the caller's readable scope (global ∪ own ∪ my-groups + per-doc grants), with per-doc chunk counts — server truth for a Library, not a local registr…
• moveScope(namespace: string, opts: { from: "global" | "user"; to: "user" | "global"; user_id?: number; doc_id?: string | string[]; batch?: number }): Promise<{ moved: number; remaining: number; conflicts: number; done: boolean; from: string; to: string; user_… — SDK 5.83 — move one namespace's rows between the shared scope and a user's scope WITHOUT re-embedding: the owner of the stored rows changes (embedding, text, metadata and chunk order stay as stored; nothing is embedded …
• namespaces(): Promise<Array<{ name: string; count: number; model: string | null; dim: number }>>
• pgvActivate(opts: { active: boolean; force?: boolean }): Promise<{ available: boolean; installed: boolean; column_ready: boolean; active: boolean; mode: string; pending_backfill: number; error?: string; [k: string]: unknown }> — Switch RAG storage to Mode 3 or back to Local (admin, platform 5.45).
• pgvBackfill(): Promise<{ backfilled: number; skipped?: number; remaining: number; error?: string }> — Migrate existing base64 vectors into pgvector (admin, batched).
• pgvIndex(opts?: { blocking?: boolean }): Promise<{ extversion: string | null; dims: number[]; present: number[]; built: number[]; invalid: number[]; unindexable?: number[]; max_ann_dim?: number; sql: string[]; blocking: boolean; error?: string; failed?: { dim… — Per-dimension hnsw index state (admin, platform 5.45).
• pgvProvision(): Promise<{ available: boolean; installed: boolean; column_ready: boolean; active: boolean; mode: string; pending_backfill: number }> — Install the pgvector extension + column in this database (admin).
• pgvStatus(): Promise<{ available: boolean; installed: boolean; column_ready: boolean; active: boolean; mode: string; pending_backfill: number }> — Mode-3 (local pgvector) setup, for the "RAG pgvector Setup" guide.
• principals(query: string): Promise<{ users: Array<{ id: number; name: string }>; groups: Array<{ id: number; name: string }> }> — For the share picker — people/groups matching query.
• search(namespace: string, query: string | number[], opts?: { topK?: number; minScore?: number; mode?: "vector" | "keyword" | "hybrid"; filter?: { doc_id?: string | string[] } } ): Promise<{ matches: Array<{ id: number; score: number; text: string; doc_id: str… — Top-k retrieval.
• setDocAccess(namespace: string, docId: string, cfg: { is_public?: boolean; user_ids?: number[]; group_ids?: number[] } ): Promise<{ ok: boolean }>
• sharedNamespaces(): Promise<Array<{ name: string; count: number; model: string | null; dim: number }>> — SDK 5.83 (Vizum.supports("vector-scope")) — the namespaces this user-scoped app owns in the SHARED (global) scope, with row counts: what an app that narrowed from vector "global" to "user" must migrate.
• stats(namespace: string): Promise<{ namespace: string; count: number; dim: number; model: string | null; bytes: number; doc_count: number }>
• tags(namespace: string): Promise<{ tags: string[]; categories: string[] }> — The distinct tag vocabulary + auto-classified categories in a namespace.
• unpack(b64: string): Float32Array — Decode one packed base64 float32 blob to a Float32Array (offline path).
• upsert(namespace: string, items: Array<{ id?: number; text?: string; embedding?: number[]; doc_id?: string; seq?: number; meta?: Record<string, any> }>, opts?: { embed_model?: string }): Promise<{ upserted: number; dim: number; model: string }> — Upsert chunks.

vision

stability stable · since 5.11 · permission: permissions.media ['camera']

Members: Vizum.vision.onResults, Vizum.vision.start, Vizum.vision.stop

Bridge ops: start, stop

• onResults(cb: (r: { hands: Array<{ landmarks: Array<{ x: number; y: number; z?: number }>; handedness: any }>; preview?: string; }) => void): Vizum.Subscription
• start(opts?: { numHands?: number; preview?: boolean }): Promise<{ ok: boolean; already?: boolean }>
• stop(): Promise<{ ok: boolean }>

webhooks

stability stable · permission: permissions.webhooks

Members: Vizum.webhooks.ack (since 5.67), Vizum.webhooks.deliveries (since 5.67), Vizum.webhooks.fail (since 5.67), Vizum.webhooks.list, Vizum.webhooks.retry (since 5.67), Vizum.webhooks.url

Bridge ops: ack, deliveries, fail, list, retry, url

• ack(deliveryId: number): Promise<Vizum.WebhookDelivery> — 5.67 — mark a queued delivery (its row's v.delivery) processed.
• deliveries(hook?: string | null, opts?: { status?: Vizum.WebhookDeliveryStatus; limit?: number }): Promise<Vizum.WebhookDelivery[]> — 5.67 — the delivery ledger (metadata only, newest first, at most 200).
• fail(deliveryId: number, error?: string): Promise<Vizum.WebhookDelivery> — 5.67 — could not process it: re-queued, or dead-lettered at the hook's max_attempts.
• list(): Promise<Array<{ name: string; url: string; signed: boolean }>>
• retry(deliveryId: number): Promise<Vizum.WebhookDelivery> — 5.67 — installer or administrator: send a failed / dead-lettered delivery back.
• url(name: string): Promise<{ url: string }>

window

stability stable · permission: none

Members: Vizum.window.close, Vizum.window.openPanel, Vizum.window.resize, Vizum.window.setTitle

Bridge ops: close, openPanel, resize, setTitle

• close(): Promise<boolean>
• openPanel(path: string, opts?: { title?: string; w?: number; h?: number; payload?: any }): Promise<boolean>
• resize(w: number, h: number): Promise<boolean>
• setTitle(t: string): Promise<boolean>

workflow

stability stable · permission: permissions.workflows

Members: Vizum.workflow.approve, Vizum.workflow.cancel, Vizum.workflow.get, Vizum.workflow.list, Vizum.workflow.reject, Vizum.workflow.start

Bridge ops: approve, cancel, get, list, reject, start

• approve(id: number, opts?: { note?: string }): Promise<WorkflowInstance>
• cancel(id: number): Promise<WorkflowInstance>
• get(id: number): Promise<WorkflowInstance>
• list(query?: { workflow?: string; state?: string; mine?: boolean; limit?: number }): Promise<WorkflowInstance[]>
• reject(id: number, opts?: { note?: string }): Promise<WorkflowInstance>
• start(name: string, payload?: Record<string, any>): Promise<WorkflowInstance>

Compatibility matrix

Generated from the since values above: the oldest capability that serves each member introduced by a capability note. Members without a since are served everywhere.

Concepts

Composition — apps that need other apps

*Since capability 5.67* (the plain app-id form below works since SDK v4).

An app declares what it needs in requires and what it offers in provides. The platform resolves every dependency against what this database has installed, reports it to the app and to administrators, and stops an administrator from removing an app other apps cannot run without — by accident.

{
  "min_platform": "5.67",
  "provides": ["crm:leads:v1"],
  "requires": [
    "com.acme.contacts",
    { "app": "com.acme.inventory", "version": "^1.4" },
    { "app": "com.acme.labels", "version": ">=2.1.0 <3.0.0", "optional": true },
    { "contract": "payments:v1", "optional": true }
  ]
}

The object forms need min_platform 5.67: an older platform refuses the manifest at install, and vzm check says so.

Versioned contracts (5.69)

Before 5.69 a contract carried its version in its name (payments:v1, payments:v2), so a provider could only say "I am v1". Since 5.69 a provides entry may name the version of the contract the app implements, and a requirement may take a range:

{
  "min_platform": "5.69",
  "provides": ["payments@1.3.0"],
  "requires": [{ "contract": "ledger", "version": "^2.1" }]
}

• A versioned requirement is met only by a provider that names a version inside the range; a provider in another version reports the dependency incompatible (the row's provided_versions says which version each provider names). A provider that names no version cannot meet a range.
• An unversioned requirement ({ "contract": "payments" }) accepts a provider in any version.
• The 5.67 names keep their meaning: payments:v1 is a name, matched exactly, by every platform.
• Vizum.apps.find(name) takes the contract name (payments, or payments:v1).
• Removal protection counts only providers in the dependent's range: uninstalling the last provider of ^1.2 is refused even while another app provides payments@3.0.0.
• vzm diff reads a provider's minor bump (@1.3.0 → @1.4.0) as compatible, and a new major, or a provider that stops naming its version (@1.3.0 → no version), as breaking. A dependent that pins an exact version (1.3.0) instead of a range opts out of minor bumps: semver ranges (^1.3) are what a provider's compatible release promises.

Both forms need min_platform 5.69: an older platform refuses them at install (its provides grammar has no @, and a contract requirement there takes no version), and both the install gate and vzm check (MIN_PLATFORM_TOO_LOW) refuse a manifest that uses them with a lower min_platform. A versioned contract may appear once in provides.

Version ranges

Space-separated comparators that must all hold:

Status

Each dependency is ready (installed, approved, in range), missing, disabled (installed but waiting for approval or disabled) or incompatible (installed, outside the range). The app as a whole is ok (every required dependency ready), degraded (an optional one is not) or blocked (a required one is not).

const { state, dependencies } = await Vizum.apps.status();
if (state === "blocked") {
  const what = dependencies.filter((d) => !d.optional && d.status !== "ready");
  showSetupScreen(what);          // tell the user what to install or update
}

Installing and updating

A first install never fails for an unmet requirement: the order apps arrive in is not the installer's to choose, so the app installs and reports blocked until what it needs arrives.

Approving a first install whose non-optional requirement is missing or out of range does not make it ready: the app stays in needs_approval with the reason waiting for <app> <range> (Apps Manager health, api_installed_detail().waiting_for). Approving several apps at once still approves the others. This holds for a zero-risk first install too (nothing to approve, a plain Install click): it does not land ready and wait to be refused at open, it waits in needs_approval with the same reason. Once the required app is installed, a normal approval puts it in ready. An app that is already ready while a non-optional requirement is missing (installed before this rule) is refused when opened: "<App> needs <X>, which is not installed". Optional requirements and installed-but-disabled dependencies never hold an app back.

The name of a requirement is not shown to people who cannot open the app. When an app is restricted (Specific people) and a user outside the list opens it, the platform checks the access first and answers the ordinary access error; the "needs X, which is not installed" message, which names the app's requirement, is only for users who may open the app (administrators included).

An update never replaces a working app with a version that cannot run. When the new version requires an app (or contract) that is missing or incompatible, the install is refused with an error naming it, before anything is written: the installed version stays as it was and keeps working. The same refusal covers the store's automatic update, which keeps the app on its current version. An app that is installed and in range but disabled (or waiting for approval) does not refuse the update — an administrator brings it back and nothing is lost — and an optional requirement never does. The store's automatic update waits (no failed attempt counted, the version is not blacklisted) and installs once the dependency arrives. Restoring the rollback snapshot of a failing update is not stopped by this gate. A required app that is ready but still waiting for the Odoo module it replaces counts as ready, so its dependents can be installed in the middle of a module-to-vApp cutover. Approving an update installed before this gate also refuses a missing requirement.

Vizum.apps.requires() returns the same rows with the SDK v4 fields (key, installed, ready) still on them.

A first install never fails because a dependency is missing — apps arrive in whatever order they arrive (an update does, see above). api_install returns the report (dependencies) for a first install or a version change (re-installing the same version answers only {id, key, state}), and the installed-app detail shows it next to required_by.

Removal protection

Uninstalling an app that another ready installed app requires (not optionally) — by id, or as the last ready provider of a contract it requires — is refused, naming the apps that need it. A disabled or unapproved dependent does not hold it in place. An administrator can force it: the desktop's uninstall dialog names the apps that depend on it, and confirming there forces the uninstall (api_uninstall(key, force=true) over RPC); the dependents then report blocked instead of failing without a word. Whether you may uninstall is checked first, so a user who may not learns nothing about the dependents.

Checked before you ship

vzm check reports INVALID_REQUIRES for a range that does not parse, an app requiring itself or a contract it provides (in any version), a duplicate entry or a versioned contract provided twice, and MIN_PLATFORM_TOO_LOW for the object form below 5.67 and for versioned contracts below 5.69.

Group-scoped ops on the models of an app you require (5.78)

A UI app that sits on an owner app (an Engine) often needs the owner's administrators to write where its technicians only read. An orm grant says so with group_ops:

{"model": "x_vzm_elev8dm_brand",
 "ops": ["search", "read"],
 "group_ops": [{"groups": ["com.elev8.elev8dm/@admin"],
                "ops": ["create", "write", "unlink", "call:rebuild_index"]}]}

• ops is what everyone who runs the app gets. Each group_ops entry adds its ops only for the calling user (never the installer) who is in at least one of its groups. fields, write_fields, domain and chatter_only stay the grant's own and bound both lists.
• A group is "@name" (one of this app's native.groups), "<app-key>/@name" (a group of an app in requires, resolved the way that app's own rules resolve it) or a real xmlid such as sales_team.group_sale_manager. base.group_system, base.group_erp_manager and any group that implies them are refused. A group that does not exist on the instance grants nothing.
• The platform computes it in one place, so Vizum.orm, call:, actions and read_group all honour it. In Solo mode the access group every Solo user holds is minted from ops only, never from group_ops: a technician who is not in the owner's admin group keeps the owner's own read-only ACL. The group named in group_ops has to carry the Odoo ACL for the model itself (the owner's native.models[].access, or a module).
• An op is in ops or in group_ops, not both. For the approval: moving an op from ops into group_ops narrows the grant (the update applies with no new approval and replaces the approved snapshot); adding a group_ops op nobody had, or naming one more group for it, widens it. Vizum.app.info-style introspection (api_meta models) lists the ops the current user holds.
• min_platform 5.78 or later. An older platform ignores the key, so the app would lose the group's ops silently; the validator, the Store gate and vzm check (MIN_PLATFORM_TOO_LOW) refuse the manifest below it. Vizum.supports("orm-group-ops") tells a screen whether the host serves it.

Concepts

Events — between open apps, with a contract

Vizum.events lets the apps open on a desktop talk to each other: one emits, the others listen. Both sides need the grant (permissions.events.emit / .listen). Events are browser-local and immediate — nothing is stored or delivered to someone who is not looking. For data other users or a later session must see, use Vizum.realtime (server fan-out to the users of an app), Vizum.db or webhooks.

await Vizum.events.emit("order.created", { id: 42, total: 99.5 });
Vizum.events.on("order.created", (payload, meta) => {
  // meta (5.67): { producer: "com.acme.orders", version: 2 }
});

Event contracts (capability 5.67)

The app that emits an event can declare its shape, once, in its manifest:

{
  "min_platform": "5.67",
  "permissions": { "events": { "emit": ["order.created"] } },
  "event_contracts": {
    "order.created": {
      "version": 2,
      "description": "A sales order was confirmed",
      "schema": {
        "type": "object",
        "required": ["id", "total"],
        "additionalProperties": false,
        "properties": {
          "id": { "type": "integer", "minimum": 1 },
          "total": { "type": "number", "minimum": 0 },
          "status": { "enum": ["draft", "confirmed"] }
        }
      }
    }
  }
}

What the platform does with it:

• At install it checks the contract: only events the app may emit, an integer version 1–999, and a schema written with the supported keywords only — type, enum, const, properties, required, additionalProperties, items, minItems, maxItems, minLength, maxLength, pattern, minimum, maximum, description. Any other keyword is refused instead of being silently ignored. A pattern that repeats a group made only of repeated parts — (a+)+, (\w+\s?)+ — is refused too: it can take exponential time on the desktop of whoever emits.
• A contract reserves the event's name. Once a ready app declares a contract for an event, no other app may emit it: the desktop rejects the emit with VALIDATION_FAILED naming the producer. Adding an event to permissions.events.emit in an update is a permission widening, like adding one to listen — an administrator approves it.
• On every emit the desktop host checks the payload against the contract. A payload that does not match is not delivered to anyone, and emit rejects with a VizumError VALIDATION_FAILED naming each problem (payload.total must be >= 0).
• Every listener receives meta = { producer, version } as the second argument — the app that emitted it and the contract version, so a listener can handle two versions while the producer migrates. version is null when the producer declares no contract for that event; meta is null for the host's own events.
• Vizum.events.catalog() lists every contract the ready (approved, enabled) installed apps you can see declare: [{ name, version, description, schema, producer }] — what you can listen for, and in which shape.

Versioning. Raise version whenever a listener could break: a removed or renamed field, a changed type, a new required field. Adding an optional field to an open object is not a new version.

vzm check reports INVALID_EVENT_CONTRACT (an event the app does not emit, an unsupported keyword), MIN_PLATFORM_TOO_LOW below 5.67, and EVENT_UNDOCUMENTED (info) for each event the app emits without a contract.

Events run on the desktop. In Odoo's own menus and in Vizum Solo an app is alone in its page, so emit, on and catalog degrade there (Vizum.supports("event-contracts") is false).

Concepts

Lifecycle, health and update preflight

*Since capability 5.67.*

Where an app is

Which companies see it

An app installed from a zip (a developer install) is available to the company the installer was working in. Another company's user who tries to install the same key gets "already installed for the company X ...". A Settings administrator changes that in Apps Manager ("Available to": all companies, or one of the administrator's own companies); the call is vizum.app.api_set_app_company(key, company_id) (false = every company) and each change is audited as platform:company_scope. Apps from the Vizum Store and the first-party defaults stay available to every company: their licence belongs to the whole database, so restricting one is refused and a Store update clears the restriction. This is visibility only; the rows of a company_scoped model stay isolated by company either way. No SDK call and no capability.

How it is doing — Vizum.apps.health()

const h = await Vizum.apps.health();
// { status: "healthy" | "degraded" | "failing", lifecycle: "running", since: "…",
//   checks: [{ name: "runtime_errors", status: "degraded", detail: "1 error(s) …" }, …] }

Five checks, from facts the platform already records — nothing to configure:

A sixth check appears only when it has something to say: jobs_time_limit (degraded) names each job whose last run in the window went past the platform's 300 second limit for method jobs (see reliability); a healthy app reports nothing.

Errors and tasks count over the last 24 hours. A runtime error counts only when the app's own code threw it, and not a benign notice — the same evidence the automatic update uses to roll a bad release back. The app's status is its worst check.

The schema check names each drifted field — job.hours: database char, manifest datetime — left by an update that changed a field's type before the platform refused it (see below). It never blocks an update; the cure is a migration in the app.

The desktop's Apps Manager shows this instead of the bare state: one call, api_apps_status(), when it opens, gives every visible app its lifecycle, whether a pending_approval is an *update* waiting (not a first install), the missing apps of a blocked one and — for the installer or an administrator — its health and the checks that are not healthy. The card reads *Ready*, *Needs attention*, *Broken*, *Needs approval*, *Update awaits approval*, *Missing dependency*, *Disabled* or *Withdrawn*, with the reason in its tooltip, and the filter chips count those same words.

An app reads only its own health. An administrator or the app's installer reads any app's with api_health(key), and the installed-app detail includes it.

What an update will do — api_update_preflight

In the Store window, the Update button shows this report before it installs anything. It opens a review sheet that downloads the new version, runs the preflight (nothing is installed or written) and lists data loss, irreversible changes, server code, permissions and migrations. A version with data loss or an irreversible change needs the administrator to tick a box; a version with a blocking finding cannot be confirmed; if the preflight itself fails the sheet blocks and offers *Retry*. The preview download is not counted as a download of the app in the store's statistics.

Before installing a package over an installed version, ask what it would change. Nothing is installed or written.

env["vizum.app"].api_update_preflight(vapp_base64)

{
  "ok": true, "blocking": [],
  "version": {"from": "1.4.2", "to": "2.0.0", "change": "major"},
  "trust": {"state": "store_verified", "publisher": "acme", "publisher_key": "ed25519:…"},
  "permissions": {"added": ["ai"], "removed": [], "changed": ["net", "orm"], "tier": "privileged",
                  "needs_approval": true,
                  "detail": {"ai": {"from": null, "to": true},
                             "net": {"added": ["api.stripe.com"]},
                             "orm": {"widened": [{"model": "res.partner", "ops": ["write"],
                                                  "fields": ["email"]}]}}},
  "code": {"hooks": {"changed": ["sync_orders"], "added": ["refund"]},
           "routes": {"changed": ["portal_status"]}},
  "schema": {"create": 3, "remove": ["model:x_vzm_acme_old"],
             "data_loss": ["model:x_vzm_acme_old"], "refused": []},
  "migrations": {"db": [{"version": "2.0.0", "table": "orders"}], "native": []},
  "dependencies": {"state": "ok", "dependencies": []},
  "reversible": {"reversible": false, "why": ["removes native schema that can hold data"]},
  "approval": {"needed": true, "reasons": ["server code changed", "permissions widened"]}
}

• blocking — every install gate that would refuse the package: min_platform, Odoo version and modules, routes, games, licence binding, a revoked version, a signature that does not hold, this instance's package_trust policy, an admin-only install, and a field whose type or comodel changes (schema.refused, below).
• permissions.needs_approval — the update widens what the app may do, so the app goes back to pending_approval until an administrator approves it.
• permissions.detail — the change, item by item, against what this database APPROVED: hosts, secrets, devices and every other list grant as added / removed; scalars as from / to; nested grants (OAuth providers and scopes) one level down; orm per model — new models, and for existing ones the operations, fields and write_fields gained (dropping a field list reads as fields: ["*"], every readable field) and a changed domain.
• code — server code and entry points that change: script hooks (code or trigger), the script library, model methods, routes, jobs, webhooks, fields with server behaviour (compute, default, formula, aggregate, related, depends), constraints, automations, native migrations, manifest actions, and what the server evaluates in native.ui — view expressions (QWeb t-*, domain, context, attrs/invisible/readonly/required, groups, decoration-*), action domains and context, server-action code, report expressions — as added / changed / removed. Layout is not code: reordering, relabelling or a plain menu does not count. They run with the grants the app already holds, so since SDK 5.69 a change here sends the app back to pending_approval like a wider grant (below).
• approval — whether installing the package leaves the app waiting for an administrator, and why: first install, server code changed, permissions widened. A zero-tier app (no privileged permission) never waits.
• schema.data_loss — native schema the new version stops declaring that can hold data — every app-owned model and every stored field, whether or not it has rows today (an app-owned model is dropped; a field on a shared model is archived, not dropped).
• reversible — whether the update can be undone. The automatic pre-update snapshot restores the app's data (KV and collections, Vizum.db rows, its files) — not its code; the previous code comes back by reinstalling the earlier package (automatic for an auto-update, which keeps it). Neither brings back native-model data an update drops or a native migration rewrites, and a downgrade may not read newer data.

A server-code change is approved like a wider grant (SDK 5.69)

An update — a new version, the automatic update, or a same-version repackage — whose code is not empty puts the app in pending_approval. Until an administrator approves it, none of its server code runs: hooks, methods, routes, webhooks and jobs run only for an approved app. An app an administrator disabled stays disabled.

• The reference is the installed manifest, compared item by item (the full SHA-256 of each hook's code and trigger, each library part and method, each route, job and webhook, each field's server behaviour, each constraint, automation and migration step). A migration that newly runs an approved hook, or a compute that wires an approved method to a new field, counts as a change: the code that runs changed even though no body did. No fingerprint is stored, so the first update after an instance moves to 5.69 re-asks only if the code really changed.
• An update with the same code (new UI, new assets, a new name) and an app with no server code keep their state. An asset-only refresh of the same version changes nothing.
• The installed-app detail carries code_change — the names that changed since the last approval, never the code — and a second update while the app waits adds to that list instead of replacing it. Approving clears it.

In the desktop, the detail of an app whose update waits for approval starts with a card This update asks for — every line of the permission cards the new version produces that the approved one did not, in the same words — and, when its code changed, a card Server code changed: "Script hooks changed: sync_orders", "Routes added: portal_status"…

Only the app's installer or an administrator can plan an update of an installed app; any internal user can plan a first install.

What an update may not change — a field's type or comodel

An update that changes the type of a field that already exists, or the comodel of a relational one, is refused on every instance before anything is written, with the list of fields; api_update_preflight reports it in blocking and schema.refused; the Store refuses to publish it; vzm diff and vzm schema diff exit with SCHEMA_CHANGE_REFUSED. This holds on the app's own models and on the columns it adds to shared ones, whatever the version number.

Why: the platform reconciles the schema by adding and removing fields, never by changing one in place. Measured on Odoo 19 before the refusal existed — a changed type was not applied (the column kept the old type, silently, and the app read and wrote the wrong one), and a changed comodel was rewritten under the stored ids, which then pointed at another model's records.

The way to do it, in one update:

1. declare a new field with the new type or comodel;
2. fill it from the old one — {"op": "copy", "model": "job", "from": "hours", "to": "duration"} in this version's native.migrations (a plain column copy), or a migration hook for a conversion a copy cannot do (a char to a datetime, a partner id to a user id);
3. stop declaring the old field. It is dropped (or archived, on a shared model) in the same update, after the copy has run.

A rename_field keeps the field's type and comodel, so a rename alone passes; a rename that also changes the type is refused like any other type change. A one2many may change its comodel (it stores no ids; the platform re-points it), never its type. A verified rollback — the automatic one, reinstalling a snapshot whose bytes still match the digest recorded when it was taken — is exempt: it returns the app to a manifest it already ran. The Store compares an upload with every lower version still installable (passed or pending, not revoked), because an instance may jump to it from any of them.

Concepts

Where your data lives — JSON vs native Odoo tables

Vizum gives you three places to keep data, from a zero-ceremony JSON key–value bag up to real Odoo tables that the rest of Odoo — reports, pivots, other modules, Studio — can see. Choose by one question: does anything outside your app need to read this?

The three storage tiers

Declaring fields on an existing model

Add columns to a shared Odoo model — e.g. surface an app-owned attribute on res.partner. The platform creates a real manual field named x_vzm_<app>_<name> and archives it (never drops it) on uninstall, so data survives.

"permissions": {
  "schema": { "models": ["res.partner"], "create_models": false }
},
"native": {
  "fields": [
    { "model": "res.partner", "name": "health", "type": "integer", "label": "Health Score" },
    { "model": "res.partner", "name": "tier", "type": "selection", "label": "Tier",
      "selection": [["bronze","Bronze"], ["silver","Silver"], ["gold","Gold"]] }
  ]
}

Declaring a brand-new model

Own a whole table. The platform creates a real model x_vzm_<app>_<model> with x_-prefixed columns. Owned models are hard-dropped on uninstall (their rows go with them), so use them for app-owned data, not shared business records.

"permissions": {
  "schema": { "models": [], "create_models": true }
},
"native": {
  "models": [
    { "name": "vehicle", "label": "Vehicle",
      "access": [{ "group": "base.group_user", "ops": ["read","write","create","unlink"] }],
      "fields": [
        { "name": "make",   "type": "char",      "label": "Make" },
        { "name": "year",   "type": "integer",   "label": "Year" },
        { "name": "owner",  "type": "many2one",  "relation": "res.partner", "label": "Owner" },
        { "name": "status", "type": "selection", "label": "Status",
          "selection": [["active","Active"], ["sold","Sold"]] }
      ]
    }
  ]
}

Field types: char, text, integer, float, monetary, boolean, date, datetime, selection, many2one/many2many/one2many (with relation; a one2many also names its inverse, from SDK 5.57). From 5.57 a many2one takes ondelete (set null, cascade, restrict) and a field takes required — a document and its lines. From 5.58 your own models also take default, sequence, unique, chatter/tracking and computed fields (formula, related, aggregate) — see the server-side guide.

Reading & writing native data from app.js

await Vizum.connect();
const MODEL = "x_vzm_vehicles_vehicle";   // x_vzm_<app>_<model>; fields are x_-prefixed

const rows = await Vizum.orm.searchRead(MODEL, [["x_status","=","active"]],
  ["x_make","x_year","x_owner"], { order: "id desc", limit: 50 });

const id = await Vizum.orm.create(MODEL,
  { x_make: "Ford", x_year: 2024, x_owner: partnerId });   // bare int id for a many2one

await Vizum.orm.write(MODEL, [id], { x_status: "sold" });

const byYear = await Vizum.orm.readGroup(MODEL, [], ["__count"], ["x_year"]);   // real SQL aggregation

Already using a companion addon?

If your app calls Vizum.orm against models defined by a packaged Odoo addon you ship alongside (the way the PSI field-service apps use dsd.*), you are already fully native — those are real tables the rest of Odoo sees, no native.* needed. The manifest native.* mechanism is the alternative for apps that want to declare their schema without shipping a separate module. Don't re-declare an addon's models as native.models — that creates empty parallel tables and orphans the real data.

Concepts

Theming — look native for free

The host pushes the desktop theme into your app, live. The SDK keeps two things in sync:

With vizum-glass.css you also get --vz-bg · --vz-ink · --vz-card · --vz-muted · --vz-border plus ready-made .vz-card · .vz-btn · .vz-input classes:

.my-panel { background: var(--vz-card); color: var(--vz-ink); }
.my-cta   { background: var(--vizum-accent); }
/* nothing else to do — light/dark/accent switches reach you instantly */

SDK & server

The browser SDK — window.Vizum

Load two files, call connect(), and everything below is yours (within your approved permissions).

<link rel="stylesheet" href="/vizum_apps_platform/static/sdk/vizum-glass.css">
<script src="/vizum_apps_platform/static/sdk/vizum-sdk.js"></script>

Vizum.connect()

const { caps, theme } = await Vizum.connect();
// caps  = the permissions the admin actually approved
// theme = { accent: "#6c5bd8", dark: false } — kept live afterwards

Vizum.data — persistence

await Vizum.data.set("settings", { sound: true, limit: 20 });  // any JSON
const s    = await Vizum.data.get("settings");                 // null if absent
const keys = await Vizum.data.list();
await Vizum.data.del("settings");

// global-scope apps can react to writes made by OTHER users:
Vizum.data.subscribe("counter", () => refresh());

Vizum.orm — Odoo data

const rows = await Vizum.orm.searchRead(
    "sale.order", [["state", "=", "sale"]],
    ["name", "amount_total"], { limit: 10, order: "amount_total desc" });

const ids   = await Vizum.orm.search("sale.order", [["state", "=", "sale"]]);
const recs  = await Vizum.orm.read("sale.order", ids, ["name", "state"]);
const count = await Vizum.orm.searchCount("sale.order", []);
const created = await Vizum.orm.create("crm.lead", { name: "From my vapp" });
const newId = created[0];   // ⚠ create returns number[] (an array of ids) — take [0] for a single record
await Vizum.orm.write("crm.lead", newId, { priority: "2" });  // passing the array as the id raises "unhashable type: list"
await Vizum.orm.call("res.currency", "name_search", ["USD"]); // needs "call:name_search"

// server-side aggregation (needs the "read_group" op) — dashboards should
// NEVER pull thousands of rows to add them up in JS:
const byMonth = await Vizum.orm.readGroup(
    "sale.order", [["state", "=", "sale"]],
    ["date_order:month"],                  // groupby (granularity optional)
    ["amount_total:sum", "__count"],       // aggregates
    { limit: 12, order: "date_order:month" });
// → [{ "date_order:month": "2026-05-01", "amount_total:sum": 80214.5, "__count": 31 }, …]
// many2one groupby values arrive as [id, display_name]

Denied calls reject with Error("PermissionDenied") — catch them and degrade gracefully.

Vizum.query — fluent queries (SDK v4)

const hot = await Vizum.query("crm.lead")
    .where("stage_id.name", "=", "Proposition")
    .where("expected_revenue", ">", 10000)
    .orWhere("priority", "=", "3")           // (revenue>10k OR priority=3)
    .order("expected_revenue desc")
    .fields("name", "expected_revenue", "partner_id")
    .limit(20)
    .all();

const total  = await Vizum.query("sale.order").where("state", "=", "sale").count();
const lead   = await Vizum.query("crm.lead").where("id", "=", id).first();   // row | null
const pageOf = await Vizum.query("account.move")
    .whereIn("move_type", ["out_invoice", "out_refund"])
    .group([["state", "=", "posted"], ["state", "=", "draft"]])   // (posted OR draft)
    .order("invoice_date desc")
    .page(0, 25);                            // {rows, total, page, pages}

A chainable builder that compiles to a real Odoo domain (inspect it with .toDomain()) and runs through the same orm proxy — so the manifest allowlist, your declared fields and the user's ACLs apply exactly as with searchRead. where chains with AND; orWhere ORs with the previous term; group([...]) adds a parenthesised OR-block. Terminals: all · first · count · ids · page · groupBy. Reads only — use Vizum.orm.create/write to change data. Available as Vizum.query() or Vizum.orm.query().

Vizum.net — external APIs (allowlisted)

// manifest: "permissions": { "net": ["api.frankfurter.app"] }
const res = await Vizum.net.fetch("https://api.frankfurter.app/latest?to=EUR");
if (res.ok) {
    console.log(res.json.rates.EUR);   // .json is pre-parsed for JSON responses
}
// POST with headers — Cookie/Host are stripped, your API keys pass through:
await Vizum.net.fetch("https://api.example.com/items", {
    method: "POST",
    headers: { "X-Api-Key": "…" },
    body: { name: "from my vapp" },    // objects are sent as JSON
});

The request happens on the Odoo server, never in the browser: no CORS, no leaked session. Hosts outside permissions.net reject with PermissionDenied; binary bodies arrive base64-encoded with binary: true.

Reach and images (5.74). A host you name is reachable on ports 80 and 443; for another port write "host:port". "net": ["*"] is any public website (download-only, never a private or metadata address, privileged, needs min_platform 5.74). Vizum.net.fetchImage(url, {max_bytes}) downloads one image (PNG, JPEG, GIF or WEBP, checked by its bytes) and re-checks every redirect. Details: Network & images.

Vizum.ui — talk to the desktop

Vizum.ui.notify("Saved!", "success");            // info | success | warning | danger
Vizum.ui.openRecord("res.partner", 42, "ACME");  // opens a REAL Odoo form window

// open a real Odoo LIST window, filtered (grant: "openList"):
Vizum.ui.openList("sale.order", [["partner_id", "=", 42]], "ACME's orders");

// host-rendered confirmation dialog (always available) -> boolean:
const yes = await Vizum.ui.confirm("Post 3 invoices now?", "Approval Center");
if (!yes) { return; }

confirm is Odoo's own dialog on the desktop and in native windows, never the browser's window.confirm (which a sandboxed frame cannot show). It resolves true on Confirm and false on Cancel, Escape or close.

Vizum.window — your own window

Vizum.window.setTitle("Pomodoro — 12:25 left");
Vizum.window.resize(480, 600);
Vizum.window.close();

Full screen — Vizum.ui.fullscreen (SDK 5.85)

A kiosk, a signage console or a counter screen wants every pixel. Declare "ui": ["fullscreen"] and call it from your own button:

if (Vizum.supports("ui-fullscreen")) {
  const r = await Vizum.ui.fullscreen();      // -> { active: true, browser: true | false }
  Vizum.ui.onFullscreenChange((e) => { if (!e.active) showEnterButton(); });
}
await Vizum.ui.exitFullscreen();              // always allowed, ends only YOUR full screen

Two layers, because of the gesture. The click happens inside your sandboxed iframe, and the browser's Fullscreen API asks for a fresh user gesture in the page that calls it — the host. Chrome and Firefox pass the activation up to the host for a few seconds; Safari does not. So the host always paints your window over the whole viewport with the dock, the Odoo navbar and the titlebar hidden (a kiosk: no gesture needed, and the window's saved size and position are never touched), and also asks the browser for real fullscreen. browser tells you which one you got; a refusal is normal, not an error, and the kiosk still stands.

Leaving. The host always shows a small Exit full screen button, and Escape (or the browser's own exit) gives the screen back, because a sandboxed app cannot be trusted to. You hear it in onFullscreenChange({active:false}). Closing, minimising or focusing another window ends it too. A step-up confirmation (identity.confirm) always leaves full screen first and refuses it while its dialog is open. Desktop and Odoo-menu hosts only; Solo and paired-device pages answer {active:false, supported:false} (a device page already has Vizum.device.fullscreen). Set min_platform 5.85; vzm check flags a missing "fullscreen" entry in permissions.ui.

Vizum.help — ship documentation with your app

// One call gives you a floating ? button + a styled help overlay. Free.
Vizum.help.button("My App — guide", [
    { h: "Getting started", p: "One-paragraph overview of what the app does." },
    { h: "Shortcuts", rows: [["Ctrl+B", "bold"], ["⟳", "refresh the data"]] },
]);
// or open it yourself from any button:
Vizum.help.show("My App — guide", sections);

Every serious app ships in-app help — the Vapp Creator template already includes a wired-up Vizum.help.button() for you to edit.

Vizum.session & Vizum.format — who is using you (SDK v2)

const { session } = await Vizum.connect();
// { uid, name, login, lang, tz, company: {id, name},
//   currency: { name, symbol, position, decimal_places } }

Vizum.format.money(1234.5);     // "$ 1,234.50" — REAL Odoo currency & position
Vizum.format.number(0.1234, 2); // locale-aware
Vizum.format.date("2026-06-11");
Vizum.format.datetime("2026-06-11 14:00:00"); // Odoo naive-UTC → user tz

A safe subset only: no tokens, no groups. Stop hardcoding "$" — every serious app formats through Vizum.format.

Vizum.app.key — your own key (SDK 5.76)

await Vizum.connect();
const key = Vizum.app.key;   // "com.acme.crm"

The host sends the key in the connect handshake on every host (desktop, native, Solo, device). Never parse it out of the URL: on a multi-database host the run path is /vizum/apps/run/@<db>/<key>/… and a regex over it reads @<db> as your key. vzm check and the Store upload gate warn on code that does. Choosing a shell before the first paint? Await Vizum.connect() first; the key is there when it resolves.

Collections — multi-user data done right (SDK v2)

const tasks = Vizum.data.collection("tasks");
const { id, rev } = await tasks.insert({ title: "Ship v2", done: false });
await tasks.update(id, rev, { title: "Ship v2", done: true });  // rev 1 → 2
// stale writes REJECT instead of clobbering a teammate:
try { await tasks.update(id, 1, { done: false }); }
catch (e) { /* e.message === "rev_conflict" → reload the item */ }

const rows = await tasks.list();        // [{id, rev, value}, …] (≤500)
await tasks.remove(id);
tasks.subscribe(() => refresh());       // live, when data:"global"

Each item is its own record with an optimistic revision — the cure for the classic “two users editing one big KV document” clobber. Scope follows permissions.data (user/global) exactly like the KV.

Vizum.files — binary storage (SDK v2)

await Vizum.files.put("export.png", base64Png);   // small files; 64 MB/file by default
const f = await Vizum.files.get("export.png");    // {b64, mimetype, size}
const all = await Vizum.files.list();             // 50 files, 128 MB by default
await Vizum.files.del("export.png");

// Big files (5.70+): streamed, no base64 in the browser
await Vizum.files.putBlob("tour.mp4", file, { onProgress: p => bar(p.sent / p.total) });
const part = await Vizum.files.getRange("tour.mp4", 0, 1_000_000);   // Range read

Backed by real attachments, scoped like your KV, never reachable through the public run URL. Stop smuggling base64 blobs through data.set. Raise the limits with permissions.file_limits (up to 200 MB a file since 5.70, 512 MB since 5.71, the part above 200 MB behind its own administrator approval). Above 32 MB the host uploads in parts, re-checks the quota at commit, and since 5.72 resumes after a dropped connection: it asks the server which part is next, sends only what is missing and, if it gives up, aborts so nothing stays reserved (nothing changes in your code; Vizum.supports("upload-resume") tells you the host does it). Details: Files.

Vizum.apps — intents (SDK v2)

// manifest: "permissions": { "apps": ["com.vizumapps.kds"] }
await Vizum.apps.open("com.vizumapps.kds", { table: "T5" });

// the TARGET app receives the payload:
const { intent } = await Vizum.connect();        // when opened by an intent
Vizum.events.on("intent", (p) => { … });         // when already running

Declared targets only, and only if the user has the target installed — Error("AppNotInstalled") otherwise.

Dock badge & command palette (SDK v2)

Vizum.ui.setBadge(7);                       // red counter on your dock tile
Vizum.ui.setBadge("");                      // clear it
Vizum.ui.addPaletteCommand("POS: new sale"); // shows in the desktop palette
Vizum.events.on("palette", (label) => { … }); // fired when the user runs it

Pin a live KPI to the desktop (SDK 4.1)

Pin any aggregate as a desktop widget that re-queries Odoo on its own timer — it keeps updating even after your app is closed. Declare "ui": ["pinWidget"]; the model must be one your app is granted to read, and the widget runs as the user.

await Vizum.ui.pinWidget({
    label:   "Open deals",
    model:   "crm.lead",
    measure: "expected_revenue:sum",   // "field:sum|avg|min|max"; omit ⇒ record count
    domain:  [["probability", "<", 100]],
    format:  "cur",                    // "cur" | "int" | "dec" | "pct" | null
    icon:    "🎯",
});

Clicking the widget opens the matching Odoo list. Sheets Lite ships this: select a =ODOO(…) cell and hit 📌 Pin KPI.

Vizum UI Kit — components for free (SDK v2)

<script src="/vizum_apps_platform/static/sdk/vizum-ui.js"></script>

document.body.appendChild(VUI.table({
    columns: [
        { key: "name", label: "Product" },
        { key: "price", label: "Price", align: "right", format: (v) => VUI.money(v) },
    ],
    rows: products,
    onRow: (r) => Vizum.ui.openRecord("product.template", r.id, r.name),
}));
document.body.appendChild(VUI.chart.bar(series));     // series = [{label, value}]

// SDK v4.20 — the full chart family, one call each:
VUI.chart.line(series);  VUI.chart.area(series);          // trend, filled trend
VUI.chart.donut(series); VUI.chart.pie(series);           // share-of-total + legend
VUI.chart.hbar(series);                                   // horizontal ranking
VUI.chart.multibar(groups, seriesList, { mode: "stacked" });   // or "grouped"
VUI.chart.multiline(groups, seriesList);                  // several trends, one plot
// multi-series shape: groups = [{label}], seriesList = [{name, values: [...]}]
const ok = await VUI.confirm("Delete this board?");
VUI.searchPicker({ model: "res.partner", fields: ["name", "email"],
                   onPick: (r) => setCustomer(r) });

Zero dependencies, XSS-safe by construction (everything renders through textContent), themed by the same tokens as vizum-glass.css. Components: el · dialog · confirm · prompt · table · chart.bar/line/area/donut/pie/hbar/multibar/multiline · searchPicker · tabs · empty · form · wizard · pipeline · signature · pdf · dataGrid · xlsx.

VUI.dataGrid — the enterprise grid (SDK v3)

const grid = VUI.dataGrid({
    model: "account.move",
    columns: [
        { field: "name", label: "Number" },
        { field: "partner_id", label: "Customer" },                  // many2one renders its name
        { field: "invoice_date", label: "Date", type: "date" },
        { field: "amount_total", label: "Total", type: "money", total: true, editable: true },
    ],
    domain: [["move_type", "=", "out_invoice"]],
    search: ["name", "partner_id"],          // top search box
    groupBy: "partner_id",                   // grouped headers w/ counts + Σ, click to drill in
    orderBy: "invoice_date desc", pageSize: 25, id: "invoices",
    actions: [{ label: "✓ Post", onClick: (ids) => postAll(ids) }],
    onOpen: (r) => Vizum.ui.openRecord("account.move", r.id, r.name),
});
container.appendChild(grid);
grid.reload();                               // call after external changes

Server-side everything: paging (searchRead + searchCount), column sort, per-column filters and grouping (readGroup) all build real Odoo domains — so the manifest allowlist, your declared fields and the user's ACLs apply to every byte. Inline editing (double-click) goes through orm.write and therefore through the host's confirmation gate. Bulk actions receive the selected ids. The ⚙ menu hides columns per user (persisted). ⤓ XLSX exports every row matching the current filters (up to 10k) as a real .xlsx built in-browser with zero dependencies — also available standalone as VUI.xlsx("file.xlsx", [{name, rows}]) for any tabular data (strings, numbers, full unicode).

VUI.wizard — multi-step flows (SDK v4)

const wiz = VUI.wizard({
    steps: [
        { title: "Customer", fields: [                // a step is a VUI.form spec…
            { name: "name", label: "Company", required: true, width: "full" },
            { name: "email", label: "Email", type: "email" } ] },
        { title: "Items", render: (box, ctx) => {     // …or draw anything
            box.appendChild(buildLineEditor(ctx.values)); } },
        { title: "Confirm", render: (box, ctx) => {
            box.appendChild(VUI.el("p", { text: "Create order for " + ctx.values.name + "?" })); } },
    ],
    onCancel: () => win.close(),
    onFinish: async (v) => { await Vizum.orm.create("sale.order", toOrder(v)); },
});
container.appendChild(wiz.el);

A guided multi-step flow with a numbered step rail (done / current / pending), Back / Next / Finish, and accumulated state. A step with fields builds a VUI.form and won't advance until it validates; a step with render(box, ctx) draws anything and reads prior answers from ctx.values. An optional validate(values) per step returns an error string to block. onFinish(allValues) runs busy-stated; completed steps are clickable to go back. Returns {el, values(), goTo, next, back}.

VUI.signature + VUI.pdf — capture & document (SDK v4)

const sig = VUI.signature({ width: 420, height: 170, label: "Customer signature" });
container.appendChild(sig.el);
// later — build a proof-of-delivery PDF and stash it on the record:
if (!sig.isEmpty()) {
    const doc = VUI.pdf({ size: "A4", margin: 50 });
    doc.text("Proof of Delivery", { size: 20, bold: true });
    doc.text("Order " + order.name, { y: 120, size: 12, color: [0.3, 0.3, 0.3] });
    doc.line(50, 140, 545, 140, { width: 0.8 });
    doc.text("Received by:", { y: 160 });
    doc.image(sig.toDataURL("image/jpeg"), { x: 50, y: 180, w: 240 });   // JPEG only
    doc.save("delivery_" + order.name + ".pdf");                          // or doc.toBase64()
    await Vizum.files.put("pod_" + order.id + ".pdf", doc.toBase64());    // keep it
}

VUI.signature is a HiDPI-correct canvas pad with smooth strokes, a placeholder hint and a clear button; isEmpty(), clear() and toDataURL()/toBlob() (JPEG-on-white by default). VUI.pdf is a zero-dependency PDF builder — text (Helvetica / Helvetica-Bold, color, left/center/right), line, rect, multi-page (addPage) and JPEG images (DCTDecode), with top-left point coordinates. Output as save(filename) · toBase64() · toBlob() · dataUrl() — hand the base64 to Vizum.files.put or a net upload. Images are JPEG-only so embedding stays robust (no PNG predictors) — and signature.toDataURL() already returns JPEG, so the two compose directly. For pixel-perfect branded documents use server-side Vizum.reports (QWeb); reach for VUI.pdf when an app needs to generate one on the spot with no template.

VUI.pipeline — a drag-and-drop kanban board (SDK v4)

const board = VUI.pipeline({
    model: "crm.lead",
    stageField: "stage_id",
    stageModel: "crm.stage",                 // shows empty stages too (else derived from data)
    domain: [["type", "=", "opportunity"]],
    fields: ["name", "expected_revenue", "partner_id"],
    sumField: "expected_revenue",            // per-column Σ in the header
    search: ["name", "partner_id"],
    onOpen: (r) => Vizum.ui.openRecord("crm.lead", r.id, r.name),
    // onMove defaults to orm.write({stage_id: newStage}); override for side-effects
});
container.appendChild(board);
board.reload();

One column per stage, cards drag between them, and the move persists through orm.write — so the manifest allowlist, the host confirmation gate and the user's ACLs apply to every stage change. Stages come from stageModel (so empty columns still render), from an explicit stages list, or are derived from the data with read_group. Each column shows a live count and an optional sumField total; supply a card(rec) renderer for a custom card or let the kit draw name + amount. Override onMove(id, stageId, rec) to run a real Odoo method (e.g. callOn to mark won) instead of a plain write.

A call: result is plain JSON data: dates and datetimes as ISO strings in UTC ("2026-10-03", "2026-10-03 12:30:05"), decimals as numbers, UTF-8 bytes as text, sets and tuples as arrays, a top-level recordset as its ids. The whole result comes back as true (and the platform logs a warning) when it holds a recordset nested in a dict or list, bytes that are not UTF-8, NaN or Infinity, any other object, more than 32 levels, 10 000 entries or 4 MiB.

VUI.form — declarative forms with validation (SDK v4)

const f = VUI.form({
    columns: 2,
    fields: [
        { name: "name",      label: "Name", required: true, width: "full" },
        { name: "email",     label: "Email", type: "email" },
        { name: "amount",    label: "Budget", type: "money", min: 0 },
        { name: "stage",     label: "Stage", type: "select",
          options: [["new", "New"], ["won", "Won"], ["lost", "Lost"]] },
        { name: "partner_id", label: "Customer", type: "many2one",
          model: "res.partner", fields: ["name", "email"] },
        { name: "due",       label: "Due", type: "date" },
        { name: "vip",       label: "VIP account", type: "checkbox" },
    ],
    values: { stage: "new" },
    onSubmit: async (v) => {                 // busy spinner until it resolves
        await Vizum.orm.create("crm.lead", v);
        Vizum.ui.notify("Saved", "success");
    },
});
container.appendChild(f.el);
// programmatic: f.values(), f.setValues({…}), f.validate(), f.reset()

One object describes the whole form; the kit renders inputs, labels, help text and inline validation, and wires a busy-stated submit button. Field type: text · textarea · number · integer · money · email · tel · url · password · select · checkbox · date · datetime · many2one. many2one fields open a searchPicker over your granted model. required · min · max and a custom validate(value, all) run before onSubmit; throw {field, message} from onSubmit to flag a server-side error on a specific field. Same theme tokens, same XSS-safe rendering as the rest of the kit.

Vizum.orm.watch — live data without hammering (SDK v2.1)

const watcher = Vizum.orm.watch("pos.order",
    [["state", "in", ["draft", "paid"]]],
    (h) => refresh(),          // called ONLY when something changed
    { interval: 6 });           // seconds (4–60, default 8)
watcher.stop();

The desktop polls a cheap server fingerprint (record count + max write_date, one aggregated query) and wakes your app only on a change. Needs the search grant on the model; your manifest domain is injected as always. (The poll pauses while the tab is hidden.)

Vizum.orm.live / Vizum.refresh — auto live data (SDK v5.4)

Don't list the models by hand. Vizum.orm.live(render) runs your render, notes every model it reads, watches them, and re-runs it whenever any change — created/updated/deleted by you OR another user — plus when the tab regains focus. One line replaces a reload timer.

// vanilla: a single idempotent render (clear-then-build) stays live by itself
const live = Vizum.orm.live(async () => {
    const rows = await Vizum.orm.searchRead("sale.order", dom, fields);
    render(rows);               // auto re-runs on any sale.order change / tab focus
});
// live.refresh()  → force a re-run now;   live.stop()  → tear down

// no single render fn (load-once, or a React store)? point refresh at your reload:
Vizum.refresh.on(() => reload());   // fires on any model you've READ changing + on focus

Both build on watch (same cheap fingerprint, same search grant) — no extra permission. opts: { interval?:4–60s, debounce?:ms, models?:[…] }.

Vizum.window.openPanel — multi-window apps (SDK v2.1)

// a SECOND window of your app, showing another file of your package:
Vizum.window.openPanel("inspector.html", { title: "Inspector", w: 380, h: 520,
                                           payload: { recordId: 42 } });
// inspector.html reads the payload via Vizum.intent and talks to the main
// window with Vizum.events (same app = same event bus)

Panels close automatically with their parent window.

Vizum.reports — real QWeb PDFs (SDK v2.1)

// manifest: "permissions": { "reports": ["account.report_invoice"] }
await Vizum.reports.download("account.report_invoice", [invoiceId], "invoice.pdf");

Rendered by Odoo's own report engine as the user — record rules apply. Per-report allowlist in the manifest.

i18n — ship translations in the package (SDK v2.1)

// package:  i18n/es.json → {"New order": "Nueva orden", "Hello %s": "Hola %s"}
Vizum._t("New order");          // "Nueva orden" when session.lang = es_*
Vizum._t("Hello %s", name);

The SDK loads i18n/<lang>.json (then the short code) at connect; missing keys fall back to the key itself.

The same files translate the server (5.73). The package's i18n/<lang>.json also answers tr() in your model methods: tr("%s items", n) reads the call's context.lang, tries es_419 then es, then your source text. Use Odoo's language codes for the files and the manifest's i18n list (es_419, not es-419); each translation keeps the placeholders of its source text; a translations-only update needs no new approval. The Desktop, native-window and Solo hosts all send the user's language (Vizum.supports("server-i18n")). A language the instance has not installed no longer breaks the call. Set min_platform 5.73. See Server-side code.

Native strings from the same files (SDK 5.84)

The package's i18n/<lang>.json also translates what your app puts in Odoo's backend: field labels and help, selection options, model labels, groups, menus, actions and view terms. Nothing to declare and no min_platform: a key is the English text of the manifest ("Customer": "Cliente") or, to remove an ambiguity, "@native:audit.state=done": "Hecho" (@native:<model>, .<field>, #help, =<value>, @native:@<group>, @native:<record id>.<field>, @native:app). The strings are written at install, update, approval and whenever a language is installed; the English source is never touched, a missing string stays in English and a translation an administrator typed by hand is kept. vzm check warns about untranslated native strings (--strict-i18n makes it an error). See Server-side code.

Translated messages in hooks and jobs (SDK 5.77)

Trigger hooks (guards included), jobs and methods have V.tr(source, *args, lang=None, **kwargs), the same lookup as tr() on your i18n/<lang>.json files. A guard's V.fail(V.tr("Phone cannot change")) reaches the user in the language of the write that fired it; a job speaks its job user's language, and lang=partner.lang translates one mail per recipient (an unknown code is ignored). The text is looked up first and interpolated after; a missing or malformed translation gives your source text and never raises. Set min_platform 5.77; the install gate and vzm check refuse V.tr below it. See Server-side code.

Who wrote, and who is running — rec["su"] and V.is_service_user() (SDK 5.81)

A trigger hook's payload has rec["su"]: True when the write that fired it ran in a superuser environment (a method of your app that wrote with sudo(), platform code, the superuser), False when it was the user's own write. sudo() keeps the user's id, so rec["uid"] alone cannot tell the two apart; with su a guard can say "a ticket is created only through wl_issue". The platform sets it from the write itself, and your app cannot. V.is_service_user(), in methods, hooks and jobs, is True when the code runs as your app's own service user (what its jobs, triggers and device routes run as) and False for any person, an administrator included: a method can tell that your paired screen, not a person at the counter, called it. Set min_platform 5.81; the install gate and vzm check refuse both below it. See Server-side code.

Signing an action — Vizum.identity.confirm (SDK 5.79)

For an approval, a release or a period close, ask the host to re-confirm the user: const {token} = await Vizum.identity.confirm({action: "qms.doc:42:approve", meaning: "approval", reason: "Approve SOP-017"}). The host draws its own dialog over a backdrop that dims the whole desktop and the user types the account password there; your app never sees it. Spend the single-use token (120 seconds, bound to the user, your app, that exact action and the session) in server code with V.identity.consume(token, action): it returns a receipt (id, name, login, meaning, reason, time) to store on your signature record, or raises one fixed error for every failure. Put the record in action. Rejects USER_CANCELLED, RATE_LIMITED (details.retryAfter) or PERMISSION_DENIED; Vizum Solo answers UNSUPPORTED_CALL (check Vizum.supports("step-up")). Every attempt is a row in a ledger only the platform writes. Never draw a password box in your own window: vzm check and the Store warn (PASSWORD_INPUT_IN_BUNDLE). Set min_platform 5.79; the install gate refuses V.identity below it. See Server-side code.

Paired screens — kiosks, signage, time clocks (SDK 5.70)

A route with auth: "device" serves a page to a screen that has no Odoo login. The screen shows an 8-digit PIN, an administrator claims it on the desktop, and it then holds a revocable token. The device's code runs only as the app's own service user (native.service_user: true), the page can embed YouTube or Vimeo and keeps an offline cache, and a screen that has not reached the server for 7 days must be paired again. Vizum.pairedDevices lists, claims (by PIN), renames, links, reloads and revokes them from the desktop. Everything, with the limits: Device routes.

Screen volume and settings — player control and Vizum.device.store (SDK 5.82)

The handle Vizum.device.embed returns can now steer its player: setVolume(0–100), mute(), unmute(), play() and pause(). The page sends the player's own command to the player it created, addressed to its exact origin, never a wildcard; a handle the page did not issue is NOT_FOUND. The app frame has no localStorage, so Vizum.device.store (get, set, delete, all) keeps a screen's own settings on the platform: JSON values of at most 4096 bytes, at most 64 keys per paired device, readable only by that device of that app, dropped when it is revoked. Set min_platform 5.82; vzm check refuses Vizum.device.store below it. See Device routes.

Hashing on the server (SDK 5.75)

Hooks, jobs and native methods have V.sha256(data), a metered SHA-256 hex digest (a string, bytes or base64). It is a fingerprint, for detecting change or deduplicating — a hash is not a signature; it never proves who made the data. Set min_platform 5.75. See Server-side code.

Background jobs (SDK v2.1)

// manifest (requires data:"global"; max 5 jobs):
"jobs": [{ "name": "daily_digest", "every_hours": 24,
           "webhook": "https://api.example.com/hook" }]   // host must be in net

// in the app — react live or on next open:
Vizum.data.subscribe("job:daily_digest", () => buildDigest());
const last = await Vizum.data.get("job:daily_digest");    // {ts, job}

The platform cron writes a tick into your global store on schedule (and optionally POSTs your webhook). Your JS never runs server-side — the tick is the contract.

Camera & microphone (SDK v2.2)

// manifest: "permissions": { "media": ["camera"] }   // or "microphone"
// then use the STANDARD web APIs — no Vizum wrapper needed:
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const codes  = await new BarcodeDetector().detect(videoEl);  // barcode scanning

Without the manifest entry the sandboxed iframe gets no device access at all (Permissions-Policy). With it, the host delegates the capability — and the browser still shows its own camera/mic prompt to the user on first use, so access is always double-gated. Feature-detect with Vizum.capabilities().features.includes("media"). Adding media in an update re-triggers approval (permission widening). See Vizum Barcode for a worked camera scanner.

Vizum.audit — a business diary you can show an auditor (SDK v3)

await Vizum.audit.log("approved_purchase", { purchase_id: 55, amount: 1200000 });
const logs = await Vizum.audit.search({ action: "approved_purchase",
                                        date_from: "2026-06-01" });
// → [{ts, user: [id, name], action, payload, ok, duration_ms, app_version}]

App-scoped: every user of the app reads its trail (an approver wants to see everyone's approvals), never another app's. Payloads cap at 4 KB, entries prune after 180 days, and action runs land here automatically — including failures, written in an isolated transaction so a rollback can't erase the evidence.

Vizum.actions — auditable business operations (SDK v3)

// manifest — the admin approves a CATALOGUE, not loose method calls:
"actions": [
  { "name": "invoice.post", "model": "account.move", "method": "action_post",
    "label": "Post invoices", "groups": ["account.group_account_invoice"] }
]

// in the app:
await Vizum.actions.run("invoice.post", { ids: [12, 13, 14] });

Each run: host confirmation dialog → required Odoo groups checked on top of normal ACLs → record-bound method executes as the user → automatic audit entry with who/ids/params/result/duration. Declaring actions makes the app privileged-tier, and adding one in an update requires re-approval. This is what turns “the app calls action_post” into “finance approved posting invoices from this app, and every run is on file”.

Vizum.webhooks — receive events, stop polling (SDK v3)

// manifest (requires data:"global"):
"webhooks": [{ "name": "whatsapp_inbound", "secret_name": "wa_app_secret" }]

// in the app — give the URL to the provider, react live:
const { url } = await Vizum.webhooks.url("whatsapp_inbound");
Vizum.data.subscribe("c:hook_whatsapp_inbound", refreshChat);
const deliveries = await Vizum.data.collection("hook_whatsapp_inbound").list();

The URL is a capability (an HMAC token bound to app+hook — unguessable, no session needed). Hooks with a secret_name also verify Meta-style X-Hub-Signature-256 against the vaulted secret. GET handles the Meta/WhatsApp subscribe handshake (use the URL's last segment as the verify token). Deliveries are 64 KB max, kept FIFO 500 per hook in the app's global collection, with a bus ping so open desktops update instantly. Shopify orders, Stripe payments, WhatsApp messages — no polling.

Heads-up — public URL. The webhook URL is built from your Odoo's web.base.url. If that is an internal address (a LAN IP like https://192.168.x.x:8090, localhost, a docker host), external providers like Meta/WhatsApp, Shopify or Stripe can't reach it. Set the system parameter vizum_apps_platform.public_base_url (Settings ▸ Technical ▸ System Parameters) to your public HTTPS origin and the webhook URL uses that instead — without moving web.base.url, which also drives email/report links. The server must still be reachable from the internet (reverse proxy / tunnel) with a valid TLS certificate.

Vizum.import + VUI.importMapper — Excel in, Odoo records out (SDK v3)

// one call: file picker -> parse -> map columns -> batch create
const res = await VUI.importMapper({ model: "res.partner" });
// res = {created: [ids…], errors: [{row, error}], total}

// or the pieces, when you want your own flow:
const { columns, rows } = await Vizum.import.open({ requiredColumns: ["name"] });
const fields = await Vizum.meta.fields("res.partner");   // labels, types, required…

CSV parsing auto-detects , ; tab and handles quoted delimiters/newlines; .xlsx is read natively (ZIP central directory + DecompressionStream + sharedStrings — zero libraries). The mapper auto-suggests by column/label similarity, casts types, imports in chunks of 50 and falls back to row-by-row on a failed chunk so one bad line never sinks fifty good ones — every failure reported with its row number. Vizum.meta.fields() returns metadata only, and only for models the manifest already grants.

Vizum.jobs — a scheduler you can operate (SDK v3)

// manifest — cron expressions and retries (or keep every_hours):
"jobs": [{ "name": "sync_orders", "cron": "*/15 * * * *",
           "webhook": "https://api.acme.com/hook",
           "retry": { "count": 3, "backoff": "exponential" } }]

// in the app:
await Vizum.jobs.runNow("sync_orders");          // manual trigger
const st = await Vizum.jobs.status("sync_orders"); // {last_run, fails, retry_at…}
const history = await Vizum.jobs.logs("sync_orders"); // audit-backed run log

Full 5-field cron (*/n, ranges, lists, dow 0-7) at 10-minute platform resolution. Failed webhook deliveries retry with exponential or linear backoff up to count times — state is visible in status(), and every run (scheduled, manual or retry) lands in the audit trail with its outcome.

A job that calls a native method has a 300 s limit. A method cannot be interrupted from outside, so an overrun is measured, not cut off: it is recorded on the job, in the audit trail and in the app's health as jobs_time_limit. Keep a batch under the limit. (A script job has its own 120 s budget, which does stop it.)

Vizum.sessions — see & revoke who is logged in (SDK 5)

// manifest: "permissions": { "sessions": ["revoke", "revokeUser"] }  — admin-gated.
// Read the device list through Vizum.orm on res.device (Odoo 18+):
const devices = await Vizum.orm.searchRead("res.device", [],
  ["user_id", "browser", "platform", "ip_address", "last_activity", "is_current"]);

await Vizum.sessions.revoke(deviceId);     // kill ONE session (a res.device id)
await Vizum.sessions.revokeUser(userId);   // kill ALL of a user's OTHER sessions

A sandboxed app cannot end an Odoo session itself — the real kill (res.device._revoke()) is private and identity-checked. The platform performs it under a base.group_system gate plus a host confirmation, so you can build a "my devices" panel, an IT force-logout, or a kill-switch for a lost laptop without shipping a native module. Needs Odoo 18+ for res.device.

Session security policy — alerts, idle timeout, audit (SDK 5)

// manifest: "permissions": { "sessions": ["getPolicy", "setLoginAlerts",
//   "setSessionTimeout", "setActivityAudit", "setActivityAuditGlobal"] }
const p = await Vizum.sessions.getPolicy();
// → { login_alerts, session_timeout:{enabled, hours, min_hours},
//     activity_audit:{enabled, global}, supported }

await Vizum.sessions.setLoginAlerts(true);          // in-app notify on every NEW sign-in
await Vizum.sessions.setSessionTimeout(true, 24);   // auto-revoke sessions idle > 24h (min 2h)
await Vizum.sessions.setActivityAudit(true);        // turn ON the change-log (see Vizum.audit.activity)
await Vizum.sessions.setActivityAuditGlobal(true);  // ADVANCED: also log native-UI / RPC writes

One platform capability replaces a whole "advanced session management" add-on — no native install. getPolicy() reads on every Odoo version; the setters are admin-only. Login alerts poll new res.device sign-ins on a 2-minute cron and notify the user in-app. Session timeout auto-revokes idle sessions on a cron — with a 2-hour floor that protects active users, because Odoo only refreshes last_activity about once an hour. Both degrade gracefully where res.device is absent (Odoo 17); supported in the policy tells you which side you are on.

Vizum.audit.activity — old→new field history (SDK 5)

// manifest — declare WHICH models/fields to change-log, and opt in:
"permissions": { "audit": true },
"native": { "audit": { "models": [
  { "name": "res.users",            "fields": ["login", "active", "name"] },
  { "name": "x_vzm_myapp_contract", "fields": ["x_state", "x_amount"] }
] } }

// in the app — read the trail (needs the admin's master switch ON):
const rows = await Vizum.audit.activity({ model: "res.users", limit: 50 });
// → [{ ts, user:[id,name], model, res_id, record_name, action, source,
//      fields_changed:["login"], changes:{ login:{old, new} }, summary }]

A field-level "who changed what, from what, to what" diary. Where Vizum.audit logs business operations you record explicitly, this captures real old→new diffs on the models you declare in native.audit. Two layers: writes through your app are captured at the ORM choke point; flip setActivityAuditGlobal(true) and a global base write/create/unlink hook also captures native-UI and external-RPC writes to the same models. Off by default, entries prune after 180 days, and the query filters by model, res_id, user_id, action, source, date_from, date_to, limit.

Vizum.db — internal relational tables (SDK v4)

// manifest — typed tables with indexes, internal m2o and Odoo refs:
"tables": {
  "commission_run":  { "fields": { "period": "string", "state": "selection",
                                    "total": "float" }, "indexes": ["period"] },
  "commission_line": { "fields": { "run_id": "many2one:commission_run",
                                   "invoice_id": "odoo:account.move",
                                   "amount": "float" } }
}

// in the app — no 500-row cap, domain search, typed coercion:
const run = await Vizum.db.insert("commission_run", { period: "2026-06", total: 18.5e6 });
const lines = await Vizum.db.search("commission_line",
    [["run_id", "=", run.id], ["amount", ">", 0]], { order: "amount desc", limit: 100 });
await Vizum.db.update("commission_run", run.id, { state: "posted" });

A lightweight relational store per app for the data Collections can't hold well: commission engines, bank reconcilers, import staging, approval boards. Field types: string · text · integer · float · monetary · boolean · date · datetime · selection · many2one:<table> · odoo:<model>. Searches take a domain (= != < <= > >= in like ilike) applied server-side; values are type-coerced and odoo: references are existence-checked with the user's ACLs. Rows are scoped user/global like the KV store. Declaring tables makes the app privileged-tier; adding a table in an update re-triggers approval.

// manifest "migrations" — applied to stored rows when the version climbs:
"version": "1.2.0",
"migrations": [
  { "version": "1.1.0", "table": "commission_line", "ops": [
      { "rename": ["amt", "amount"] },           // amt → amount on every row
      { "default": ["approved", false] } ] },    // fill missing field
  { "version": "1.2.0", "table": "commission_line", "ops": [
      { "drop": "legacy_note" } ] }
]

Because rows are schema-less JSON, adding a field needs no migration — new rows carry it, old rows read the default. For renames, drops, copies and back-fills, declare a migrations entry per version: when an updated package installs, the platform runs every migration whose version falls in (installed, new], in order, transforming the app's existing rows. Ops: {rename:[a,b]} · {drop:f} · {default:[f,v]} · {copy:[a,b]}. They run server-side at install time — there is no runtime API and nothing for the app to call.

// a table can declare validation rules — enforced on every insert/update:
"commission_line": {
  "fields": { "email": "string", "amount": "float", "status": "string", "period": "string" },
  "rules": [
    { "field": "amount", "required": true, "min": 0 },
    { "field": "email", "format": "email" },
    { "field": "status", "choices": ["draft", "posted"] },
    { "unique": ["period"] }
  ]
}

Beyond field types, a table's rules are enforced by the server on every Vizum.db.insert/update — required, numeric min/max, format (email / url), choices (an allowed set) and composite unique (no two of the app's rows share that field combination). A violation rejects the write with a clear error, so the invariant holds no matter which client wrote it — the same guarantee an Odoo model constraint gives, declared in the manifest.

Vizum.workflow — a process engine (SDK v4)

// manifest — ordered steps, group assignees, per-step SLA:
"workflows": [{
  "name": "purchase_approval",
  "steps": [
    { "name": "manager_review", "assignee": "group:purchase.group_purchase_manager", "sla_hours": 24 },
    { "name": "finance_review",  "assignee": "group:account.group_account_manager" }
  ]
}]

// in the app — start, then assignees approve/reject down the chain:
const wf = await Vizum.workflow.start("purchase_approval", { purchase_id: 55 });
// running | approved | rejected | cancelled — wf.step is the live stage
await Vizum.workflow.approve(wf.id, { note: "ok by manager" });
const mine = await Vizum.workflow.list({ state: "running" });

Where Vizum.actions run one approved operation, a workflow manages a whole process: ordered steps, each with a group (group:<xmlid>) or the starter (user:starter) as assignee, optional SLA deadlines, and approve/reject with notes. Only an assignee of the current step can act; advancing notifies the next step's assignees via Vizum.notifications, and a breached SLA escalates automatically (a 15-minute cron). Every transition lands in the instance history and the audit trail. Declaring workflows makes the app privileged-tier.

Vizum.notifications — a persistent per-user inbox (SDK v4)

await Vizum.notifications.create({
  user_id: 12, title: "PO00045 pending", body: "Needs your approval",
  priority: "high", action: { payload: { purchase_id: 45 } } });

const unread = await Vizum.notifications.count();          // badge it
const rows = await Vizum.notifications.list({ unread: true });
await Vizum.notifications.markRead(rows.map((r) => r.id));

An inbox owned by your app and scoped per user on the server — it survives reloads, carries read/unread state, a low·normal·high priority and a click action, and pings the bus so open desktops update live. No permission needed: the server scopes every row by app + user. The inbox is FIFO-bounded and auto-pruned after 90 days. This is the channel workflows, jobs and webhooks use to reach a human.

Vizum.realtime — ephemeral multi-user pub/sub (SDK v4)

// every open copy of THIS app shares a named room — nothing is stored:
const ch = Vizum.realtime.channel("kds");
ch.on("ticket", (t, { from }) => renderTicket(t));
ch.on("bump",   (id) => removeTicket(id));

// publishing reaches every other screen instantly (via the Odoo bus):
await ch.publish("ticket", { id: 7, table: 12, items: [...] });
// later: ch.close();

A live room for screens that must agree right now: kitchen displays, picking stations, live approval queues, presence cursors. A channel is just a name every open copy of the same app shares; publish fans a small JSON event (≤16 KB) out over the Odoo bus to every other instance, stamped with the sender's user id. Nothing is persisted — when a screen reloads it has no history, so pair realtime with Vizum.db or Collections for the durable copy. Channels are app-scoped by construction (the host only forwards your own app's messages) and need no permission.

Vizum.offline — act now, sync later (SDK v4)

// run an approved action — or queue it if there's no connection:
const r = await Vizum.offline.run("delivery.confirm", { ids: [orderId] });
if (r.queued) { VUI.toast && VUI.toast("Saved — will sync when back online"); }

Vizum.offline.on((s) => { offlineBanner.hidden = s.online; });   // connectivity flip
Vizum.offline.onFlushed((f) => refresh());                       // outbox drained
const queued = await Vizum.offline.pending();                    // [{id, action, params, ts}]
const { online } = await Vizum.offline.status();

A vapp runs in an opaque-origin iframe and cannot persist anything locally — so the host (a normal origin) owns the outbox. While the browser is offline, offline.run(action, params) queues the intent in localStorage and returns {queued: true}; the moment connectivity returns the host replays each queued action through the same api_action path, so it is re-validated server-side (allowlist, groups, ACLs, audit) exactly as if run live. A permanent rejection (bad action / no access) is dropped and reported in flush()'s failed list; a transport error keeps the item queued. The unit of deferral is an approved action, never arbitrary code — so offline never weakens the security model. Confirmation is asked once, when the user acts; the automatic replay does not re-prompt. Needs permissions.actions.

Offline data — read and write with no coverage (SDK 5.80)

// manifest: "offline": {datasets: [...], writes: [...]}, "min_platform": "5.80"
await Vizum.offline.sync();                                          // bring the device copy up to date
const { records, as_of } = await Vizum.offline.query("stops", { domain: [["x_state", "=", "todo"]], order: "x_seq" });
const made = await Vizum.offline.create("sale.order", { partner_id: 7 }, { expect: { amount_total: 120 } });
await Vizum.offline.write("x_vzm_dsd_visit", [4, made.id], { x_note: "gate code" });   // made.id is a temp id
const issues = await Vizum.offline.conflicts();                       // what the server refused
await Vizum.offline.resolve(issues[0].id, "keep_mine");               // or "keep_server", "discard"

The host keeps the datasets your manifest declares on the device and answers query and readGroup from them with no network. create and write are queued, applied to the local rows at once and replayed in order, exactly once, as the user, when the network is back; a queued write carries the values the device saw and the server answers CONFLICT if someone changed them. A refused change is listed for the user to keep, replace or discard. The rows are removed on logout; the queue stays, and signing out with changes or sync issues still pending warns first and never discards them. Everything is in Offline data; vzm new offline-field-app scaffolds a working app with tests.

App composition — requires & provides (SDK v4)

// manifest — declare what you need and what you offer:
"requires": ["com.acme.crm_core"],
"provides": ["contract:invoice_printer", "contract:lead_scorer"]

// at runtime — check your deps, discover peers, route to a contract:
const deps = await Vizum.apps.requires();      // [{key, installed, ready}]
if (deps.some((d) => !d.ready)) { showSetupBanner(deps); }

const printers = await Vizum.apps.find("contract:invoice_printer");
if (printers[0]?.ready) { await Vizum.apps.open(printers[0].key, { invoice_id: id }); }
const all = await Vizum.apps.installed();       // [{key, name, version, ready, provides}]

Apps stop being islands. requires names peer vapps this one needs — Vizum.apps.requires() reports whether each is installed and ready so you can prompt the user to add a missing one (advisory, not a hard install block, since apps can arrive in any order). provides publishes capability contracts (free-form strings) that any app can discover with Vizum.apps.find(contract) and then reach through the existing intent (Vizum.apps.open, gated by permissions.apps). The catalogue read (installed()) is low-risk — the user already sees every app in the launcher — so discovery needs no permission; only opening a peer does.

Vizum.telemetry — product analytics, privately (SDK v4)

Vizum.telemetry.track("export_clicked");
Vizum.telemetry.track("rows_imported", batch.length);
const s = await Vizum.telemetry.summary({ date_from: "2026-06-01" });
// { totals: { export_clicked: 42, rows_imported: 1880 }, total: 1922 }

Where Vizum.audit records business operations (who posted which invoice), Vizum.telemetry is the other axis — product analytics: which features get used, how often. To stay bounded and privacy-safe it stores only daily aggregated counters per (app, event, day) — never per-user rows, never free-form payloads. track(event, n?) bumps today's counter; summary({event?, date_from?, date_to?}) returns the app's own roll-up. Admins see it under Vizum Apps Admin → Telemetry. App-scoped and zero-risk.

Vizum.permissions + Vizum.meta — self-aware apps (SDK v4)

// show the user exactly what this app can do (risk-tagged):
const caps = await Vizum.permissions.explain();
// [{capability: "Read & change Contacts", detail: "ops: read, write", risk: "high"}, …]

// build dynamic UIs from the granted models' metadata:
const models = await Vizum.meta.models();              // [{model, label, ops, fields}]
const cols   = await Vizum.meta.fields("crm.lead");    // [{name, label, type, …}]
const stages = await Vizum.meta.selection("crm.lead.priority");  // [["0","Low"], …]

Vizum.permissions.explain() turns the app's approved grants into a human-readable, risk-tagged list — drop it into a "what can this app do?" panel so users (and you) can audit a vapp from the inside; raw() returns the snapshot itself. Vizum.meta exposes metadata for the models the manifest grants — fields(model), models() (every granted model + label + ops) and selection("model.field") — so generic tools (import mappers, report builders, dynamic forms) can adapt to the schema. Metadata only: reading actual data still goes through the orm proxy with every gate intact. Both are read-only and zero-risk.

Vizum.mail + Vizum.activity — live in Odoo (SDK v4)

// post to the record's chatter (the model needs a "write" orm grant):
await Vizum.mail.post("crm.lead", id, "Called the customer — very interested");
await Vizum.mail.log("crm.lead", id, "Internal note: budget confirmed");

// schedule / list / complete real Odoo activities on the record:
await Vizum.activity.schedule("crm.lead", id,
    { summary: "Send proposal", date_deadline: "2026-06-20" });
const todos = await Vizum.activity.list("crm.lead", id);   // [{id, summary, overdue, …}]
await Vizum.activity.done("crm.lead", id, todos[0].id, "Sent");

The point of a Vizum app is to live inside Odoo, not beside it. Vizum.mail posts to a record's chatter (message_post) — a real message or an internal note; Vizum.activity schedules, lists and completes the same activities the rest of Odoo shows in the systray and on the form. Both ride the model's existing orm grant — a mutation needs the write op, listing needs read — and run as the user, so Odoo's ACLs and record rules decide. No new permission: if your app can already write the record, it can talk about it.

Vizum.roles — declarative app roles (SDK v4)

// manifest — name your roles and map each to Odoo groups:
"roles": [
  { "name": "manager", "label": "Approver", "groups": ["base.group_system"] },
  { "name": "agent",   "groups": ["base.group_user"] }
]

// in the app — gate your OWN UI (real authority stays in Odoo ACLs):
if (await Vizum.roles.has("manager")) { showApproveButton(); }
const mine = await Vizum.roles.mine();          // ["agent", …]
const all  = await Vizum.roles.list();          // [{name, label, active}]

A clean way to express "who can do what" inside your app without scattering group xmlids through the UI. Each role maps to one or more Odoo groups; has()/mine() are evaluated server-side as the real user (has_group), so the answer can't be spoofed from the iframe — but it's for presentation: the server still enforces real ACLs on every orm/action call. A role with no groups matches everyone. Read-only and zero-risk, so declaring roles never changes the install tier.

Vizum.ai — a managed LLM gateway (SDK v4)

// manifest — declare access (true = any gateway model, or an allowlist):
"permissions": { "ai": true }

// in the app — the platform admin owns the provider key:
const out = await Vizum.ai.chat({
    system: "You are a terse sales assistant.",
    messages: [{ role: "user", content: "Summarise lead #" + id + ": " + notes }],
    max_tokens: 400,
});
console.log(out.content, out.usage);       // {input, output} tokens

const text = await Vizum.ai.complete("Write a follow-up email subject line.");
const models = await Vizum.ai.models();    // [{id, label, provider}]
const { vectors } = await Vizum.ai.embed(["alpha", "beta"]);   // OpenAI gateway

A platform-managed bridge to an LLM: the administrator configures one gateway once (provider + key + the models to expose, under Vizum Apps Admin → AI), and any app that declares permissions.ai can call it. The provider key is encrypted at rest and never crosses the iframe boundary — exactly like Vizum.secrets, but owned by the platform. Five providers ship — anthropic · openai · gemini · ollama (Cloud) · grok — all normalised to one shape — {content, tool_calls, usage, model, finish_reason} — so swapping providers doesn't touch app code. Every call is metered (token usage per app/user) and written to the audit trail, the output-token ceiling and an optional monthly budget are enforced server-side, and permissions.ai can pin the app to a specific model allowlist. Declaring it makes the app privileged-tier (it can incur provider cost).

Vizum.assistant — an AI bridge to Odoo & your apps (SDK 5)

// manifest: "permissions": { "assistant": true }  — admin-approved, high-risk.
// A server-side agent runs a tool-loop as the REAL user (no sudo): it reads any
// model the user can read and PROPOSES writes you confirm. Per-user history.
const turn = await Vizum.assistant.send(0, "how many open opportunities do I have?");
// → { session_id, text, tool_steps:[…], pending_actions:[…] }

// the model proposed a write? it never auto-runs — confirm (or reject) it:
const t2 = await Vizum.assistant.send(turn.session_id, "create a lead 'Acme' for partner 14");
if (t2.pending_actions.length)
    await Vizum.assistant.confirm(t2.session_id, t2.pending_actions[0].id);

// per-user chat history (each user sees ONLY their own):
const chats = await Vizum.assistant.sessions();
const msgs  = await Vizum.assistant.history(chats[0].id);
await Vizum.assistant.newSession("Q3 review");
await Vizum.assistant.rename(id, "Renamed");  await Vizum.assistant["delete"](id);

The agent runs server-side as the logged-in user, so Odoo's ACLs and record rules are the real limit — it only sees and changes what that user can. Reads execute immediately; create/update PROPOSE a pending action the user must confirm() (a hallucination can't silently write). Model tiers: technical/infra models (ir.*, res.users, mail.mail, payment internals) are blocked; accounting/stock (account.move, stock.*) are read-only; everything else is read + confirm-write. The admin configures the provider once (Anthropic / OpenAI / Gemini / Ollama Cloud / Grok) — keys never leave the server. Ships as the AI Assistant app (chat UI + an "Ask AI" desktop entry).

Vizum.perf — desktop health metrics (SDK 5)

// this browser tab's live runtime — windows, JS heap, sampled FPS, desktop state
const d = await Vizum.perf.desktop();
// d.windows {total, open, minimized, vapps, actions, byKind, activeId}
// d.memory {heapMB, totalMB, limitMB, pct} | null   d.fps   d.desktop {active, mobile, effects, space…}

// server responsiveness — round-trip latency of a cheap call (server CPU/RAM aren't exposed)
const { latencyMs } = await Vizum.perf.ping();

// ADMIN only — active-session counts across the instance (sessions_* need Odoo 18+; null on 17)
const s = await Vizum.perf.sessions(); // {supported, online_users, online_mine, sessions_total, sessions_mine}

Read-only health metrics for monitoring the Vizum desktop's impact on speed, memory and the server. The sandboxed iframe can't read the parent tab's performance APIs, so desktop() is computed by the host. Ships as the admin-only Vizum Monitor app. Degrades gracefully on Odoo 17 (no res.device session counts).

Vizum.vector & Vizum.docs — Knowledge / RAG (SDK 5–5.2)

// manifest: "permissions": { "vector": "user", "ai": true }
// Vizum.vector is the durable, server-side embedding store (an opaque-origin vapp
// iframe cannot persist anything). Rows are scoped user/global like Vizum.db; embedding
// rides permissions.ai so the provider key never reaches the iframe.
await Vizum.vector.upsert("kb", [
    { text: "chunk one", doc_id: "f1", seq: 0, meta: { src: "policy.pdf" } },
    { text: "chunk two", doc_id: "f1", seq: 1 }]);          // host embeds the text
const { matches } = await Vizum.vector.search("kb", "how do I request leave?",
    { topK: 5, mode: "hybrid" });   // vector | keyword | hybrid (RRF) → [{id,score,text,doc_id,seq,meta}]

// Vizum.docs — keep the ORIGINAL document bytes so the index can be RE-BUILT later
// (new embedding model, a storage-mode switch, recovering lost vectors). Stored in the
// FILESTORE (disk), never DB rows, so the database never bloats. Rides permissions.vector.
await Vizum.docs.put("kb", { doc_id: "f1", name: "policy.pdf",
    content_type: "application/pdf", data: base64Bytes });
const doc = await Vizum.docs.get("kb", "f1");              // {…, data: base64} → re-chunk & re-embed

Three storage modes, chosen by the instance admin (Vizum Apps Admin → AI → Managed Mode → RAG vector storage) — your code is identical in all three; only where the vectors live changes:

// Mode-3 (local pgvector) setup — what the "RAG pgvector Setup" app automates.
// pgvStatus is read-only; pgvProvision / pgvBackfill require an admin user.
const s = await Vizum.vector.pgvStatus();   // {available, installed, column_ready, active, mode, pending_backfill}
if (s.available && !s.column_ready) await Vizum.vector.pgvProvision();   // CREATE EXTENSION + column
if (s.pending_backfill) await Vizum.vector.pgvBackfill();                // migrate existing vectors (no re-embed)

Vector residency is the client's choice because a knowledge base can be sensitive. stats().backend reports where a namespace currently lives (local / pgvector / managed). Switching mode does not migrate existing vectors — re-index from Vizum.docs, or use Backfill for the local→pgvector move. This powers the Knowledge (RAG) flagship app.

The shared vector scope — sharedNamespaces and moveScope (SDK 5.83)

An app whose approved vector grant is "user" reads and writes its own rows. An app that narrowed from "global" to "user" (an update that asks the administrator again) leaves its old rows in the shared scope, where namespaces() does not list them. Two calls let the administrator, or the app's own service user in a migration job, find them and move them without paying for the embeddings again:

// -> [{ name, count, model, dim }]: the namespaces THIS app owns in the shared scope
const shared = await Vizum.vector.sharedNamespaces();
for (const ns of shared) {
  let r;
  do {   // each call moves one batch of whole documents; loop until done
    r = await Vizum.vector.moveScope(ns.name, { from: "global", to: "user", batch: 2000 });
  } while (!r.done);       // r = { moved, remaining, conflicts, done, from, to, user_id }
}

What a move does. The owner of the stored rows changes; the embedding, text, metadata, chunk order and doc_id stay exactly as stored, no embedding is computed and nothing is metered. A call is one transaction, bounded by batch (default 2000, at most 10000; whole documents move together), and re-running it after done moves nothing. A row whose (doc_id, chunk_seq) the destination already holds is never overwritten or duplicated: it stays in the source and is counted in conflicts. A document that has fully left the shared scope loses its knowledge graph there and its per-document access grants, so nothing public keeps naming it; the graph of the destination is rebuilt by re-indexing or graphRecompute().

Who may call. An administrator, or the app's service user (V.is_service_user()); never a plain user. The store does not record who wrote a shared row, so "the shared rows that belong to this user" cannot be told; the caller names the target (user_id; an administrator may omit it for their own scope, the service user must name it). { from: "user", to: "global" } publishes private knowledge to every user of the app and is administrator-only. A "global" app has no user scope to move into and is refused; managed RAG storage lists but cannot move. Server code reads the list with V.vector.shared_namespaces(). Set min_platform 5.83 (the install gate refuses V.vector.shared_namespaces below it, and vzm check the browser members); Vizum.supports("vector-scope") tells a screen whether the host serves it.

AI tools — let the Assistant use your app (SDK 5.3)

// manifest.json — tools the AI Assistant can DISCOVER + invoke. With a `model` the
// Assistant CREATEs a record (confirmed); WITHOUT a model your app builds the content.
"ai_tools": [
  { "name": "create_document",
    "description": "Build a document. title + content_md (markdown).",
    "input": ["title", "content_md"] }
]

// CLIENT-HANDLED — the Assistant opens your app with the request; you build it:
Vizum.ai.tools.handle("create_document", async ({ title, content_md }) => {
    const id = await Vizum.orm.create(MODEL, { x_name: title, x_data: mdToHtml(content_md) });
    Vizum.ui.notify("Created by AI", "success");
});

The Assistant calls use_vapp_tool(app_key, tool, values) — so a user can say "draft a 5-slide deck about Q3" and the right app builds it. Vizum Doc, Vizum Point, Sheets Lite, Dashboard Builder and Report Builder ship example tools.

Vizum.backend — async business operations (SDK v3)

// the unit of execution is an APPROVED manifest action — never code:
"actions": [{ "name": "invoice.post", "model": "account.move",
              "method": "action_post", "approval": true }]

const t = await Vizum.backend.enqueue("invoice.post", { ids: bigList });
// queued | waiting_approval | running | done | failed | cancelled
const st = await Vizum.backend.status(t.id);   // + per-task log lines
await Vizum.backend.approve(t.id);             // admins release gated tasks

Tasks run on the server (2-minute queue tick) as the user who enqueued them — their ACLs and record rules decide, and a failed action rolls back its own writes only (savepoint) while the task records the failure honestly. Actions with "approval": true wait for an administrator. The window stays free; runs land in the audit trail like any action. The app states an intent — the bridge validates — the queue executes: the same contract heavier external workers will honour.

The queue is bounded: at most 500 pending (waiting_approval + queued) tasks per app and 100 per user, and enqueue() beyond that rejects with QUOTA_EXCEEDED. A task nobody approves within 7 days is cancelled (last_error: "approval expired"), never deleted.

Vizum.license + Vizum.errors + Vizum.devices (SDK v3)

// licensing-aware features (paid store apps):
const lic = await Vizum.license.current();   // {pricing, licensed, status, expires}
await Vizum.license.require();               // throws + opens the store when unlicensed

// observability — uncaught errors are captured automatically into the audit
// trail (rate-limited); add your own context:
Vizum.errors.capture(err, { screen: "approval_board" });
const errors = await Vizum.dev.logs();

// devices — manifest: "permissions": { "devices": ["print", "serial"] }
await Vizum.devices.print("Picking 00042", ["PICK 00042", "2 x Desk", "1 x Lamp"]);
const port = await navigator.serial.requestPort();  // scales, scanners, printers

print renders your text into a scriptless host-side frame and opens the system print dialog — labels and tickets without a single privileged byte. serial delegates the standard Web Serial API to your sandboxed iframe (Chromium; the browser shows its own port chooser). Both are manifest grants and count as permission widening on update.

Receipt printing & scan capture (SDK 4.1)

// ESC/POS receipt to the user's default paired printer (USB / Bluetooth-BLE /
// Serial — paired once in Settings → Devices). grant: "devices": ["print"]
await Vizum.devices.printReceipt([
    { text: "ACME Foods",   align: "center", bold: true, size: "double" },
    { text: "Order S00042", align: "center" },
    "--------------------------------",
    "2 x Desk          $ 90.00",
    { text: "TOTAL  $120.00", bold: true },
], { cut: true });        // each line = a string OR {text, align, bold, size, underline}

// NFC taps + RFID/barcode reader scans the desktop captures. grant: "devices": ["scan"]
Vizum.devices.onScan(({ type, value }) => {   // type: "nfc" | "rfid"
    lookupByCode(value);
});

printReceipt sends a real ESC/POS byte stream to the printer the user paired in Settings → Devices — no port chooser per print. onScan surfaces hardware the desktop owns (an NFC reader via Web NFC, or a keyboard-wedge RFID/barcode scanner), so several apps can share one device. Both live under the "devices" grant and count as permission widening on update.

Vizum.settings — admin-ready configuration for free (SDK v3)

// manifest — a typed schema, no UI code needed:
"settings": [
  { "key": "default_journal_id", "type": "many2one", "model": "account.journal",
    "label": "Journal" },
  { "key": "alert_days", "type": "integer", "default": 7, "label": "Alert after (days)" },
  { "key": "mode", "type": "selection", "options": ["fast", "thorough"], "default": "fast" },
  { "key": "notify_managers", "type": "boolean", "default": true }
]

// in the app:
const cfg = await Vizum.settings.get();        // {alert_days: 7, …} with defaults merged
await Vizum.settings.open();                   // HOST renders the whole form
Vizum.events… // the "settings" event fires with the new values after save

Types: string, integer, float, boolean, selection and many2one (type-ahead picker that searches as the admin — Odoo ACLs apply). Values are stored per database, validated/coerced server-side, only administrators can save, and clearing a field falls back to the declared default. This is what makes apps installable by non-technical admins.

Network host settings. A setting that permissions.net names with $setting:<key> is a network host the app may call and send $secret: credentials to, so it is the administrator's decision, never the app's. Only the host dialog (Vizum.settings.open()) can write it, and only what the administrator typed: the manifest default of such a key shows as a placeholder and is not stored until the admin enters it, and the dialog adds a fixed warning beside the field. Vizum.settings.set refuses the key with an AccessError. When an update newly names a setting as a network host, the value stored under that key before is cleared on approval: the administrator enters it in the dialog.

Vizum.secrets — keys that never live in your zip (SDK v3)

// manifest: "permissions": { "secrets": ["openai_api_key"], "net": ["api.openai.com"] }
if (!await Vizum.secrets.exists("openai_api_key")) {
    await Vizum.secrets.configure("openai_api_key");  // HOST dialog — admin types it
}
// use it WITHOUT ever seeing it: the server substitutes $secret:… after
// the allowlist checks, so the value never reaches the browser at all:
const r = await Vizum.net.fetch("https://api.openai.com/v1/chat/completions", {
    method: "POST",
    headers: { Authorization: "Bearer $secret:openai_api_key" },
    body: { model: "gpt-4o-mini", messages: [...] },
});

The vault is write-only from the app's side: names() /exists() only reveal what is configured, and configure() opens a host-rendered password input the iframe can neither draw nor read (cancelling rejects with Error("UserDenied")). Values are encrypted at rest (Fernet keyed off database.secret) and adding a secret in an update is permission widening — re-approval required. This is what makes serious integrations shippable: HubSpot sync, WhatsApp connectors, AI assistants — with zero tokens inside the .vapp package.

Vizum.oauth — Google/HubSpot/anything OAuth2, per user (SDK v3)

// manifest: "permissions": { "oauth": ["google"] }
// 1) once per database, an admin registers the provider (System Parameters →
//    vizum_apps_platform.oauth_providers): auth_url, token_url, api_base,
//    client_id, client_secret, scopes.
if (!await Vizum.oauth.connected("google")) {
    await Vizum.oauth.connect("google");   // host popup → provider consent → done
}
const r = await Vizum.oauth.fetch("google", "/calendar/v3/users/me/calendarList");
console.log(r.json.items);

Connections are per user (your calendar, not your colleague's) and the whole token lifecycle lives server-side: the code exchange uses the client secret inside Odoo, tokens are stored encrypted, refreshed automatically a minute before expiry, and fetch() joins your path to the provider's registered api_base — there is no way to point it anywhere else. The callback round-trip is HMAC-signed and expires in 10 minutes. Combined with Vizum.secrets this unlocks real connectors: Google Calendar ↔ Odoo scheduler, HubSpot sync, WhatsApp dashboards — with zero credentials in the package.

Tooling — typings, mock, schema (SDK v2.1)

Vizum.events — app ↔ app

// manifest: "events": { "emit": ["pomodoro.done"], "listen": ["pomodoro.done"] }
Vizum.events.emit("pomodoro.done", { task: "Write docs" });
Vizum.events.on("pomodoro.done", (p) => Vizum.ui.notify("Done: " + p.task));

SDK & server

Server-side code — hooks, triggers, guards and the platform's contracts PRIVILEGED

A vApp runs in a sandboxed iframe, and anything enforced only there can be bypassed by opening the same record in Odoo's own form. A rule that must hold, such as "only the owner may share this" or "an approved request cannot change", has to live on the server. This page covers the server side of a vApp: where its code runs, as whom, what it receives, and the platform contracts it can rely on.

For the capability each feature needs, see Platform capabilities (generated from the platform's own notes). The TypeScript side is in @vizum/vapp-types (vizum.d.ts).

1. Where server code lives

Server code is Python, declared in the manifest under native.script.hooks:

"permissions": { "logic": "script" },
"native": {
  "script": {
    "hooks": [
      { "name": "approve", "code": "..." },
      { "name": "guard_share", "code": "...",
        "trigger": { "model": "x_vzm_sheets_doc", "on": "write", "enforce": true } }
    ]
  }
}

• permissions.logic: "script" is privileged: an administrator approves it at install time, and the code is AST-vetted at install and again on every run. The code is statements and, from 5.62, top-level functions (see "Functions, a shared library, and the time budget"). There are no imports, lambda, class, with or match, and no underscore attributes (V._env is unreachable). Loops are allowed, which is why every run has a call budget and, from 5.62, a time budget.
• The only rich global is V: V.orm, V.db (5.33), V.data, V.files (5.27), V.net, V.oauth (5.26), V.ai, V.vector (5.40, read-only; 5.83: shared_namespaces()), V.webhooks (5.67: ack, fail, deliveries — settle what a job drained from its hook_* queue, reliability.md), V.json, V.sha256 (5.75), V.tr (5.77), V.identity (5.79: consume(token, action) spends a step-up confirmation, identity-step-up.md), V.log, V.fail, V.uid(), V.is_service_user() (5.81), the time helpers (V.now_odoo, V.add_minutes, V.minutes_between, V.clock), and V.commit() in jobs only (5.28). Each run has a call budget: 50 net, 10 ai and 20 vector calls. Since 5.67 a script's V.net and V.files.put also count against the per-app budgets an administrator sets (QUOTA_EXCEEDED, reliability.md), and a script's V.files cannot pass sha256 or expires_in: its public links get the one-day default (files.md). Since 5.74 V.net.fetch_image(url, {max_bytes}) downloads one image (redirects re-checked, byte cap, PNG/JPEG/GIF/WEBP only; net.md) and counts as one net call.
• V.orm.read and V.orm.search_read return a binary or image field (image_1920, datas) as a base64 str, or False when it is empty, on every Odoo line — the same value Vizum.orm.read gives the iframe. Odoo itself reads it as bytes on 17/18/19 and as {content, size} on 20; the platform normalises it, so a script never branches on the line. A bin_size read keeps Odoo's size label. Every value is loaded in full, so a script that only needs to know whether a file exists, or how big it is, reads with context={"bin_size": True} instead of pulling the bytes.
• A hook ends by setting result, which is what Vizum.script.run resolves to.

A hook runs in one of three ways:

The job user is job_user_id, or the installer by default. The platform refuses to run a trigger or a job as the superuser, an archived user or a portal user. It logs the refusal and records it in the app's own audit trail. A job is not an ir.cron of its own: one platform cron dispatches every app's jobs, so finding no cron named after your app is expected.

Jobs and permissions.data (5.81)

Before 5.81 a job required permissions.data: "global", because each tick the platform wrote (job:<name>) lives in the app's shared store. Since 5.81 an app with jobs may declare "data": "user". The platform then writes no tick and sends no ping for its jobs (the schedule, Vizum.jobs and the audit trail do not need one), and the job's own V.data is the private scope of the user the job runs as, the app's service user. A job cannot read a human user's private keys; the keys it writes are its own, and no user reads them back through Vizum.data (they are the service user's, not theirs). To hand data to people a job must write it to a model or to a global store. A job of an app without a service user runs as the installer, and its V.data is then that installer's scope. An app that declares jobs with data: "user" must declare min_platform 5.81; the install gate and vzm check enforce it (an older platform refuses the combination), and Vizum.supports("jobs-user-data") tells a screen whether the host serves it.

2. Triggers: the payload

A trigger hook receives rec once per written (or, with on: "unlink", deleted) record. The TypeScript mirror is Vizum.TriggerRec.

The platform reads old and new with its own rights and applies the same ceilings to both:

• Only fields the app's read grant on that model covers are included.
• Fields the app hides from the hook identity (VZ-SEC-23, see §4) are never included.
• A relational value is ids: an id (or False) for many2one, a list for x2many.
• A date or datetime is an ISO string.
• A binary is {"__binary__": size}.
• Text over 64 KB is {"__text__": length}.

Decide from the payload, do not re-read the row. The hook runs as the job user, whose record rules may hide the very row it guards (a private document is visible only to its owner). This is why 5.54 added uid, owner and new. A hook that reads them sets min_platform: "5.54".

# guard_share — only the owner may change who a document is shared with
if "x_shared_with" in rec["changed"] and rec["uid"] not in (rec["owner"], 1):
    V.fail("Only the owner can change who this document is shared with.")

Who wrote: uid and su (5.81)

sudo() keeps the caller's uid, so rec["uid"] is the same for a person's own write and for a write that one of your methods made with sudo() on that person's behalf. rec["su"] tells them apart:

Exactly: su is env.su of the records that were written, read by the platform when the write fires the trigger. It is not "the user is an administrator" and not "the app's service user wrote it" (use V.is_service_user() for who the *code* runs as; the service user's own write has su False unless it also called sudo()). The app cannot set it: the platform assigns it on every trigger run, after any context the caller built.

# guard_issue — a ticket is created only by wl_issue, which writes with sudo()
if rec["event"] == "create" and not rec["su"]:
    V.fail(V.tr("Tickets are issued from the counter or a screen."))

A hook that reads rec["su"] must declare min_platform 5.81 (the install gate and vzm check refuse it below: on an older platform the key is missing and the guard raises KeyError). Vizum.supports("trigger-su") tells a screen whether the host serves it.

3. A trigger hook that raises aborts the write

A trigger runs inside the transaction of the write that fired it. Any exception it raises, including V.fail(msg), propagates out of Odoo's automation and rolls the triggering write back. The user sees msg as the error. This makes a trigger a guard, and it has three consequences:

• Nothing the hook writes on the failing path survives. An audit row, a counter or a notification written before V.fail is rolled back with the write. To record a refusal, do it from somewhere that does not fail, such as the iframe after it catches the error, or a job.
• An ordinary hook that crashes also blocks the write. A KeyError in a numbering hook stops every save of that model. Write non-guard hooks defensively.
• enforce: true makes the guard fail closed. Without it, a hook that *cannot run* (the app is not ready, or its job user is missing, archived, portal or the superuser) is skipped, and the write proceeds unguarded. With it, the write is refused instead. Declare it on every hook that exists to refuse writes, and never on one that grants, indexes or numbers. enforce needs 5.32.

Guarding a deletion (5.56)

on: "unlink" runs the hook before the record is deleted, for every ORM deletion: the Odoo backend (an administrator included), sudo(), crons, odoo shell, and the app's own Vizum.orm.unlink. A hook that raises aborts the deletion, and enforce: true fails closed exactly as for a write. One hook has one event, so a model guarded on write and on delete declares two hooks.

{ "name": "pay_group_delete_guard", "code": "…",
  "trigger": { "model": "x_vzm_contador365_pay_group", "on": "unlink", "enforce": true } }

# pay_group_delete_guard — a group with members is not deleted
if V.orm.search_count("x_vzm_contador365_employee_link", [["x_pay_group", "=", rec["id"]]]):
    V.fail("Move this group's employees to another group first.")

What a delete guard never sees. Deletions that PostgreSQL performs itself do not go through the ORM, so no trigger runs for them:

• the link of a many2one whose target is deleted. Every vApp many2one is set null at the database, so the field is simply cleared;
• rows removed by an Odoo ondelete="cascade" field;
• the link rows of a many2many.

Guard the record that is actually deleted (the parent) and decide there from what still refers to it. A guard on the child does not run when the parent goes.

Uninstalling the app is never blocked by its own guard. The platform removes the app's automations before its models, and a model's table is dropped, not unlinked row by row.

A vApp that declares on: "unlink" sets min_platform: "5.56"; an older platform refuses the manifest at install.

4. Security contracts the platform enforces

These rules hold whatever the vApp does, so do not build around them.

• Portal users have no bridge (VZ-SEC-21). A portal (share) session cannot call the vApp bridge: no orm, data, db, run_hook or install. The single exception is a declared route (5.53, below). A route page receives a run-token minted for that app, route and user, and reaches only a minimal session, orm within the app's grant (bounded by the visitor's own record rules), the route's own json hooks (with its rate limit, size cap and audit), watch hashes, domain evaluation and token refresh.
• Hidden fields stay hidden along every path (VZ-SEC-23). A field the manifest hides with groups (on a native.models[].fields[] entry) is protected only by the bridge, because Odoo does not apply groups to a manual x_ field. The bridge resolves every hop of a dotted path (x_rel.x_secret) in domains, order, fields, groupby, aggregates, any / not any sub-domains and watch hashes, and refuses the first hidden field on any model along the path. Do not expect a dotted path to reach a field the direct name cannot.
• x_company_id is the platform's (5.51). On a company_scoped native model the platform synthesizes x_company_id; never declare a company_id.
  • A create that names none is stamped with the user's current company.
  • An explicit value on create, write, a nested line update or a copy default must be one of the user's active companies (for a hook, the job user's companies). Anything else raises a ValidationError.
  • Writing False (making the row global) is refused.
  • Before 5.51 an explicit company on create was replaced silently, and a write was not checked at all.
• An app's own models need no orm grant (5.49). The server always granted an app its own native models, and the fields it added to shared models, with no permissions.orm. From 5.49 the browser agrees: connect() returns caps.orm_native: true. The platform computes it; declaring it in the manifest does nothing.

5. Naming: what your fields are called in Odoo

The x_<name> rule for your own model's fields is the one people get wrong. A domain, a fields list or a V.orm call that uses x_vzm_<app>_status on your own model finds nothing. The platform also mirrors your model's rec_name into x_name.

A document with lines (5.57)

From 5.57 your own models can hold a document and its lines the way an Odoo module does:

"models": [
  { "name": "order", "fields": [
      { "name": "name", "type": "char", "required": true },
      { "name": "line_ids", "type": "one2many", "relation": "x_vzm_<app>_line", "inverse": "order" } ] },
  { "name": "line", "fields": [
      { "name": "order", "type": "many2one", "relation": "x_vzm_<app>_order",
        "required": true, "ondelete": "cascade" },
      { "name": "qty", "type": "float" } ] }
]

• one2many needs inverse: the manifest name (no x_) of a many2one declared on the model in relation, which must be one of your own models, pointing back at this one.
• ondelete on a many2one: set null (the default, as before 5.57), cascade (the line goes with its order) or restrict (a master still referenced cannot be deleted). PostgreSQL enforces it, so it holds for the backend, sudo and crons too. A cascade is one of the deletions no trigger sees (§3): guard the order, not its lines.
• required: the column is NOT NULL. Not for an x2many or a boolean. A required many2one needs cascade or restrict.
• On a shared model a one2many may list your rows ({"model": "res.partner", "name": "orders", "type": "one2many", "relation": "x_vzm_<app>_order", "inverse": "partner"}), but required and cascade are refused there: they would act on records other modules own.
• Write lines through the document with Odoo's commands — [0, 0, {…}] creates, [1, id, {…}] updates, [2, id, 0] deletes — from Vizum.orm or V.orm. A version may add, change or drop any of this; dropping ondelete returns the field to set null.
• A vApp that uses inverse, ondelete or required sets min_platform: "5.57".

Defaults, numbering, unique keys, chatter and computed fields (5.58)

What a module writes in Python, your own models declare. The platform applies it in the ORM, so it holds for your vApp, the Odoo backend and RPC alike:

{ "name": "order", "chatter": true, "unique": [["code"]], "fields": [
    { "name": "number", "type": "char", "sequence": { "prefix": "OT-", "padding": 5 } },
    { "name": "code", "type": "char" },
    { "name": "state", "type": "selection", "default": "draft", "tracking": true,
      "selection": [["draft", "Draft"], ["done", "Done"]] },
    { "name": "date", "type": "date", "default": { "dynamic": "today" } },
    { "name": "owner", "type": "many2one", "relation": "res.users", "default": { "dynamic": "user" } },
    { "name": "partner", "type": "many2one", "relation": "res.partner" },
    { "name": "partner_email", "type": "char", "related": "partner.email" },
    { "name": "line_ids", "type": "one2many", "relation": "x_vzm_<app>_line", "inverse": "order" },
    { "name": "subtotal", "type": "float", "aggregate": { "of": "line_ids", "op": "sum", "field": "amount" } },
    { "name": "discount", "type": "float" },
    { "name": "total", "type": "float", "formula": "round(subtotal * (1 - discount / 100), 2)" } ] }

• default: a literal of the field's type, or {"dynamic": "today" | "now" | "user" | "company"}. An explicit value always wins.
• sequence: the field is numbered on create when it is left empty, from an ir.sequence the app owns.
• unique: real PostgreSQL unique indexes. An install or update refuses while existing rows already collide, and names the value. Empty values never collide. Since 5.68 an entry can also be an object: {"fields": [...], "nulls_not_distinct": true} makes empty values collide too (PostgreSQL 15+), and "name": "code_uniq" names the index <table>_code_uniq, as Odoo names a module's constraint — code that recognises its own duplicate by exc.diag.constraint_name finds it. Since 5.81 a unique of a company_scoped model may list x_company_id, the synthesized company column, beside declared fields: {"company_scoped": true, "unique": [["x_company_id", "prefix"]]} is a prefix unique per company (two companies reuse one, one company cannot), and [["x_company_id"]] is one settings row per company. It is the real column, so nulls_not_distinct works as for any other. A unique that names it on a model that is not company_scoped is refused (there is no such column), and so is a declared field called x_company_id named in the same list (it would be ambiguous). An app that uses it must declare min_platform 5.81; the install gate and vzm check enforce it, and Vizum.supports("company-unique") tells a screen whether the host serves it.
• check (5.68, on a model): real PostgreSQL CHECK constraints, each {"name": "quantity_positive", "field": "quantity", "op": ">=", "value": 1} — a declared integer, float or monetary field compared (>, >=, <, <=, !=) with a number. The constraint is <table>_<name>, as Odoo names a module's CHECK (quantity >= 1), and a write that breaks it fails in the database (an IntegrityError), whoever writes. An empty value passes, as in SQL. An install or update refuses while rows already break it, and says how many; removing the entry or uninstalling drops the constraint. A condition over two fields stays a constraints method.
• order (5.68, on a model): its default order, as a module's _order — "order": "code_id, sequence, id", in your field names, each optionally asc/desc and nulls first/nulls last; besides your declared fields it may name id, create_date, write_date, create_uid and write_uid.
• pair (5.68, many2many between two of your own models): "pair": "manual.model_ids" on model.manual_ids, and "pair": "model.manual_ids" back on manual.model_ids, make the two fields ONE relation seen from each side — linking a manual on the model shows the model on the manual, as two module fields sharing one relation table. Each must name the other and point at the other's model. It is set when the fields are created; an update cannot pair two existing fields (their rows live in different tables).
• chatter gives the model messages, followers and activities. tracking posts a field's changes there.
• formula reads the record's own fields by their manifest names; its dependencies are worked out for you. related reads through one of the model's many2one, and can go on from there: order.customer.email on a line. Steps through your own models use their manifest names; from the first Odoo model on (res.partner, …) use Odoo's names. A related field may itself read through another related field. Add "store": true to store it. aggregate totals a one2many (sum, count, min, max, avg). All three compile into compute code the platform writes; your manifest supplies names and operators only.
• A vApp that uses any of these keys sets min_platform: "5.58".