@bardioc/app-sdk 0.4.11 → 1.0.0

package/README.md

@@ -1,25 +1,17 @@
 # @bardioc/app-sdk
 
-SDK and Vite integration for building apps for the Bardioc OS.
+SDK for building apps that run inside Bardioc as isolated iframes.
 
-This package focuses on the runtime SDK and Vite plugin only:
-
-1. Bridge communication between an app and the OS, IndexedDB, and host APIs.
-2. Validate app manifests and wire Vite apps for iframe-based development.
+An app talks to its host only through a typed contract over a `MessagePort`: it calls host
+methods (`ui.*`, `bff.request`, `idb.*`, `apps.*`), receives host calls (`ui.command`) and
+events (`context.changed`), and reads streams (`events.graph`). Every failure is a
+`BardiocError` with a `code`.
 
 ## Requirements
 
 - Node.js `>=20.19.0`
 - TypeScript `>=6.0.0`
-- For React apps, install `react` and `react-dom` in the consuming project
-
-## Install into an existing project
-
-```bash
-pnpm add @bardioc/app-sdk
-```
-
-Apps can be developed independently outside the Bardioc OS and then tested through a live AppStore development session. That keeps the local development loop fast while still exercising the real host communication path.
+- For React apps, `react` and `react-dom` in the consuming project
 
 ## Quick start
 
@@ -29,284 +21,135 @@ import { createRoot } from 'react-dom/client';
 
 function App() {
   const notify = useNotify();
-
-  function sayHello() {
-    notify('Hello from my app', 'success');
-  }
-
-  return <button onClick={sayHello}>Say hello</button>;
+  return <button onClick={() => notify('Hello.', 'success')}>Say hello</button>;
 }
 
-const isInsideIframe = globalThis.window.parent !== globalThis.window;
-
 createRoot(document.getElementById('root')!).render(
-  isInsideIframe ? (
-    <AppSdkProvider appId="my-app">
-      <App />
-    </AppSdkProvider>
-  ) : (
-    <div>Open this app from the Bardioc OS dock to use SDK features.</div>
-  )
+  <AppSdkProvider>
+    <App />
+  </AppSdkProvider>
 );
 ```
 
-## Exports
-
-| Path                        | Contents                                    |
-| --------------------------- | ------------------------------------------- |
-| `@bardioc/app-sdk`          | `createHostBridge`, errors, types, manifest |
-| `@bardioc/app-sdk/react`    | `AppSdkProvider`, hooks (`useSdk`, etc.)    |
-| `@bardioc/app-sdk/dev`      | standalone dev bridge helpers               |
-| `@bardioc/app-sdk/types`    | Type-only TypeScript exports                |
-| `@bardioc/app-sdk/protocol` | `SDK_MSG` constants, wire format types      |
-| `@bardioc/app-sdk/vite`     | `bardiocApp()` Vite plugin                  |
-
-### Key exports
-
-```ts
-// Bridge and types
-import {
-  createHostBridge,
-  type HostBridge,
-  type HostBridgeConfig,
-  type GraphNodeRaw,
-  type GraphEdgeRaw,
-  type UserProfile,
-  type OrgStructure,
-} from '@bardioc/app-sdk';
-
-// Errors
-import {
-  EntityNotFoundError,
-  ValidationError,
-  PermissionError,
-  TimeoutError,
-  NetworkError,
-  SdkError,
-} from '@bardioc/app-sdk';
-
-// React hooks
-import { AppSdkProvider, useSdk, useNotify, useSendToKernel } from '@bardioc/app-sdk/react';
-
-// Standalone dev helpers
-import { installDevBridge, isDevStandalone, isInsideIframe } from '@bardioc/app-sdk/dev';
-```
-
-## Vite plugin
+Without React:
 
 ```ts
-// vite.config.ts
-import { bardiocApp } from '@bardioc/app-sdk/vite';
-import react from '@vitejs/plugin-react';
-import { defineConfig } from 'vite';
+import { connect } from '@bardioc/app-sdk';
 
-export default defineConfig({
-  plugins: [react(), bardiocApp({ appName: 'my-app', port: 3005 })],
-});
+const bardioc = await connect();
+const profile = await bardioc.os.profile.get();
 ```
 
-Handles dev base path, port config, host session proxy routes, platform fonts, and manifest validation on build.
-
-### Platform fonts
-
-The Bardioc platform guarantees a stable font endpoint wherever an app runs — like `/api/transport`, it is a public contract that will never be renamed or removed. Load it with one line in `index.html` and do **not** bundle font packages into your app:
+## Exports
 
-```html
-<link rel="stylesheet" href="/fonts/bardioc-fonts.css" />
-```
+| Path                         | Contents                                                      |
+| ---------------------------- | ------------------------------------------------------------- |
+| `@bardioc/app-sdk`           | `connect`, `Bardioc`, `BardiocError`, manifest, domain types  |
+| `@bardioc/app-sdk/react`     | `AppSdkProvider` and hooks                                    |
+| `@bardioc/app-sdk/protocol`  | the contract: `APP_METHODS`, `serve`, `acceptApp` — for hosts |
+| `@bardioc/app-sdk/dev`       | `installDevHost`, `isDevStandalone`, `isInsideIframe`         |
+| `@bardioc/app-sdk/dev-proxy` | `startDevAuthProxy` for dev servers without the Vite plugin   |
+| `@bardioc/app-sdk/vite`      | `bardiocApp()`, `bardiocDevAuth()`                            |
+| `@bardioc/app-sdk/testing`   | `hostConformance`: the behaviour every host must share        |
 
-It provides `Nunito Sans Variable` (normal + italic) and `Geist Mono Variable` as variable fonts (latin subset), matching the `--font-nunito-sans` / `--font-geist-mono` theme variables that `@bardioc/ui` resolves by default.
+## API
 
-- **Embedded in the OS** the URL resolves same-origin against the host, which serves it with immutable caching — one download shared by the host and every app.
-- **Standalone dev** the `bardiocApp()` plugin serves the same files from assets shipped inside this package (dev server only — they are never added to your bundle). This applies to Vite-based apps; the angular and nextjs templates run their own dev servers, where the link is a harmless 404 standalone and resolves normally embedded in the OS.
-
-New apps scaffolded with `create-bardioc-app` include the `<link>` already.
-
-## Standalone Dev Session
+```ts
+const bardioc = await connect();
 
-Standalone local development is host-backed only.
+bardioc.context; // { appId, host: 'os' | 'dev', osConfig }
+bardioc.onContextChange(context => {});
 
-1. Set `DEV_SECRET` and `API_BASE_URL` in your local `.env`.
-2. Run `pnpm dev`.
+await bardioc.ui.notify('Saved.', 'success');
+await bardioc.ui.setCommands([{ id: 'save', title: 'Save' }]);
+await bardioc.ui.setMenu([{ label: 'File', items: [{ type: 'command', commandId: 'save' }] }]);
+const off = bardioc.ui.onCommand('save', () => save());
 
-The Vite plugin proxies `/rest/*` requests to `API_BASE_URL` with the `X-Dev-Secret` header, and `installDevBridge()` handles SDK messages when running in standalone dev.
+await bardioc.bff.request({ path: '/os/me/profile' }); // any BFF path outside /auth
+await bardioc.graph.query('ogit/_type:ogit/Note', { limit: 10 });
+await bardioc.os.organization.getStructure();
+await bardioc.relay('notes').request({ path: '/items' });
 
-Dev servers that cannot host the Vite plugin (angular, nextjs) run the same proxy as a standalone server:
+const notes = bardioc.idb('notes');
+await notes.put('n1', { title: 'Hi' });
+await notes.get('n1'); // { key, value, updatedAt } | null
 
-```javascript
-import { startDevAuthProxy } from '@bardioc/app-sdk/dev-proxy';
+const end = await bardioc.events.graph({ types: ['ogit/Note'] }, event => {});
+end();
 
-// Reads DEV_SECRET / API_BASE_URL from the project's .env files; resolves to null when unset.
-await startDevAuthProxy({ projectDir: process.cwd(), port: 3105 });
+await bardioc.apps.list();
 ```
 
-Point the app at it with `installDevBridge({ apiBaseUrl: 'http://127.0.0.1:3105/rest' })`.
-
-## React hooks
+Scope: a call without `scopeId` uses the window's instance; `scopeId` makes the scope required;
+`scopePolicy: 'none'` sends none.
 
-- `useSdk()` — raw bridge instance
-- `useNotify()` — fire-and-forget toast
-- `useSendToKernel()` — proxy a whitelisted message to the OS service worker
+### React hooks
 
-### IndexedDB persistence
+`useSdk()`, `useNotify()`, `useCommandMenu(commands, menu)`, `useActiveTab(tab)`,
+`useOsConfig()`, `useGraphEvents({ types }, handler)`.
 
-`useSdk()` exposes `bridge.idb(storeName)` for app-scoped persistence:
+### Errors
 
 ```ts
-const drafts = bridge.idb('drafts');
+import { BardiocError } from '@bardioc/app-sdk';
 
-await drafts.put('welcome', {
-  title: 'Q2 rollout',
-  summary: 'Publish SDK changes before updating the host workspace.',
-});
-const draft = await drafts.get<{ title: string; summary: string }>('welcome');
-const items = await drafts.query({ prefix: 'wel', limit: 20 });
-await drafts.delete('welcome');
+try {
+  await bardioc.graph.get(id);
+} catch (error) {
+  if (error instanceof BardiocError && error.code === 'not_found') return null;
+  throw error;
+}
 ```
 
-Each handle is scoped by the host to the app's manifest `id`, so two apps can use the same `storeName` without colliding.
-
-### Transport API
-
-The bridge provides namespaced transport APIs for graph database and OS operations.
+Codes: `invalid`, `unauthenticated`, `forbidden`, `not_found`, `conflict`, `rate_limited`,
+`unavailable`, `timeout`, `cancelled`, `protocol`, `internal`. HTTP failures carry `status` and the
+response body as `details`.
 
-**Note:** For multiple graph/OS instances or contexts, the Host OS is responsible for routing requests. The SDK proxies all transport requests to the host via postMessage - one bridge = one iframe = one host connection.
+## Standalone development
 
-#### Graph API
-
-Access the graph database via `bridge.transport.graph.*`:
+1. Set `DEV_SECRET` and `API_BASE_URL` in `.env`.
+2. Install the dev host before rendering, then run `pnpm dev`:
 
 ```ts
-const sdk = useSdk();
-
-// Get single node
-const node = await sdk.transport.graph.get<GraphNodeRaw>('node-id');
-
-// Query with Lucene
-const people = await sdk.transport.graph.query<GraphNodeRaw>(
-  'ogit/_type:ogit/Person AND ogit/name:John*',
-  { limit: 50, offset: 0, scopeId: 'instance-scope-id' }
-);
-
-// Gremlin traversal
-const edges = await sdk.transport.graph.gremlin(rootId, "outE('ogit/relates')");
-
-// Create node
-const newNode = await sdk.transport.graph.create('ogit/Person', {
-  'ogit/name': 'Jane Doe',
-  'ogit/email': 'jane@example.com',
-});
-
-// Update node
-await sdk.transport.graph.update('node-id', {
-  'ogit/name': 'Updated Name',
-});
+import { installDevHost, isDevStandalone } from '@bardioc/app-sdk/dev';
 
-// Create edge
-await sdk.transport.graph.connect(fromId, toId, 'ogit/relates');
-
-// Delete node
-await sdk.transport.graph.delete('node-id');
-
-// Combined query: Elasticsearch picks the start vertices, Gremlin traverses from them
-const speeches = await sdk.transport.graph.combined(
-  '+(ogit\\/_type: "ogit/Politics/AgendaItem")',
-  "inE().outV().has('ogit/_type', 'ogit/Politics/Discussion')",
-  { limit: 1000 }
-);
-
-// Time series
-const values = await sdk.transport.graph.timeseries.get('ts-id', {
-  from: '2026-01-01',
-  to: '2026-01-31',
-});
-
-// Several series in one request, averaged per timestamp
-const merged = await sdk.transport.graph.timeseries.get('ts-id', {
-  from: '2026-01-01',
-  to: '2026-01-31',
-  withIds: ['ts-id-2', 'ts-id-3'],
-  aggregate: 'avg',
-});
+if (isDevStandalone()) installDevHost({ appId: 'my-app' });
 ```
 
-Available methods: `get`, `getMany`, `getByXid`, `query`, `gremlin`, `combined`, `create`, `update`, `delete`, `connect`, `history`, `batch.delete`, `timeseries.get`, `timeseries.add`, `timeseries.query`, `timeseries.history`, `content.set`, `content.get`.
-
-`combined` and multi-ID time series reads both return one flat result set: a combined query carries
-no marker for which start vertex a row came from (label and `select()` in the traversal when you need
-it), and time series entries carry only `timestamp` and `value` (read one ID per request when values
-must stay attributable).
-
-All graph request option types accept optional `scopeId` when a request must target a specific scope.
+The dev host answers the same contract as the Bardioc host: BFF calls go through the dev-auth
+proxy (the `bardiocDevAuth` Vite plugin, or `startDevAuthProxy` beside angular and nextjs dev
+servers — pass its origin as `apiBaseUrl`), `idb` lives in this browser's IndexedDB, `ui` calls
+are acknowledged, and `apps` answer `unavailable`.
 
-#### OS API
-
-Access OS features via `bridge.transport.os.*`:
+## Vite plugin
 
 ```ts
-const sdk = useSdk();
-
-// User profile
-const profile = await sdk.transport.os.profile.get();
-const avatar = await sdk.transport.os.profile.getAvatar();
-await sdk.transport.os.profile.setAvatar(imageBlob);
-
-// Organization
-const org = await sdk.transport.os.organization.getStructure();
-const unit = await sdk.transport.os.organization.createUnit({
-  name: 'Engineering',
-  parentId: 'parent-unit-id',
-});
+// vite.config.ts
+import { bardiocApp } from '@bardioc/app-sdk/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
 
-// Applications
-const apps = await sdk.transport.os.applications.list();
-const app = await sdk.transport.os.applications.get('app-id');
-await sdk.transport.os.applications.upload('app-id', zipBlob);
-await sdk.transport.os.request({
-  path: '/custom/endpoint',
-  method: 'GET',
-  scopeId: 'instance-scope-id',
+export default defineConfig({
+  plugins: [react(), bardiocApp({ appName: 'my-app', port: 3005 })],
 });
 ```
 
-Available namespaces:
+Handles dev base path, port config, host session proxy routes, platform fonts, and manifest validation on build.
 
-- `os.profile.*` — `get`, `getAvatar`, `setAvatar`, `getInstances`
-- `os.organization.*` — `getStructure`, `createUnit`, `updateUnit`, `createMember`, `updateMember`, `deleteMember`, `inviteMember`
-- `os.applications.*` — `list`, `get`, `upload`, `download`, `getFiles`, `getFile`, `getConfigurations`
+### Platform fonts
 
-### Error handling
+The Bardioc platform guarantees a stable font endpoint wherever an app runs — like `/api/transport`, it is a public contract that will never be renamed or removed. Load it with one line in `index.html` and do **not** bundle font packages into your app:
 
-All transport methods throw structured errors:
+```html
+<link rel="stylesheet" href="/fonts/bardioc-fonts.css" />
+```
 
-```ts
-import {
-  EntityNotFoundError,
-  ValidationError,
-  PermissionError,
-  TimeoutError,
-  NetworkError,
-  SdkError,
-} from '@bardioc/app-sdk';
+It provides `Nunito Sans Variable` (normal + italic) and `Geist Mono Variable` as variable fonts (latin subset), matching the `--font-nunito-sans` / `--font-geist-mono` theme variables that `@bardioc/ui` resolves by default.
 
-try {
-  const node = await sdk.transport.graph.get('node-id');
-} catch (error) {
-  if (error instanceof EntityNotFoundError) {
-    console.log('Node not found:', error.context.id);
-  } else if (error instanceof ValidationError) {
-    console.log('Invalid data:', error.context?.field);
-  } else if (error instanceof PermissionError) {
-    console.log('Missing permission:', error.context.permission);
-  } else if (error instanceof TimeoutError) {
-    console.log('Request timed out:', error.context.operation);
-  } else if (error instanceof NetworkError) {
-    console.log('Network error:', error.statusCode, error.message);
-  }
-}
-```
+- **Embedded in the OS** the URL resolves same-origin against the host, which serves it with immutable caching — one download shared by the host and every app.
+- **Standalone dev** the `bardiocApp()` plugin serves the same files from assets shipped inside this package (dev server only — they are never added to your bundle). This applies to Vite-based apps; the angular and nextjs templates run their own dev servers, where the link is a harmless 404 standalone and resolves normally embedded in the OS.
 
-All errors extend `SdkError` with properties: `code`, `statusCode`, `context`, `message`.
+New apps scaffolded with `create-bardioc-app` include the `<link>` already.
 
 ## App manifest
 
@@ -317,19 +160,10 @@ Every app must include `public/app-manifest.json`:
   "manifestVersion": 2,
   "id": "my-app",
   "name": "My App",
-  "version": "1.0.0",
-  "permissions": ["notify", "transport"]
+  "version": "1.0.0"
 }
 ```
 
-Available permissions:
-
-- `notify` — Show toast notifications via `bridge.notify()`
-- `storage` — Key-value storage via `bridge.storage.*`
-- `indexdb` — App-scoped IndexedDB via `bridge.idb()`
-- `kernel-proxy` — Message the OS service worker via `bridge.sendToKernel()`
-- `transport` — Access graph and OS APIs via `bridge.transport.*`
-
 The Vite plugin validates this automatically and fails the build when the manifest is missing or invalid.
 
 ### Window
@@ -342,7 +176,6 @@ Optionally control how the OS frames the app via a `window` block:
   "id": "my-app",
   "name": "My App",
   "version": "1.0.0",
-  "permissions": ["notify"],
   "window": {
     "size": "md",
     "resizable": true

package/dist/api/graph.d.ts

@@ -0,0 +1,30 @@
+import type { BatchResult, CombinedQueryOptions, DeleteOptions, GetNodeOptions, GraphEdgeRaw, GraphNodeRaw, GremlinOptions, HistoryEntry, HistoryOptions, MutationOptions, QueryOptions, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions } from '../types.js';
+import { type BffRequester } from './request.js';
+/** The Bardioc graph API, called through the host. */
+export declare function graphApi(request: BffRequester): {
+    get: <T = GraphNodeRaw>(id: string, options?: GetNodeOptions) => Promise<T>;
+    getMany: <T = GraphNodeRaw>(ids: string[], options?: GetNodeOptions) => Promise<(T | undefined)[]>;
+    getByXid: <T = GraphNodeRaw>(xid: string, options?: GetNodeOptions) => Promise<T>;
+    query: <T = GraphNodeRaw>(lucene: string, options?: QueryOptions) => Promise<T[]>;
+    gremlin: <T = unknown>(rootId: string, query: string, options?: GremlinOptions) => Promise<T[]>;
+    combined: <T = unknown>(elasticsearchQuery: string, gremlinQuery: string, options?: CombinedQueryOptions) => Promise<T[]>;
+    create: <T = GraphNodeRaw>(type: string, data: Record<string, unknown>, options?: MutationOptions) => Promise<T>;
+    update: <T = GraphNodeRaw>(id: string, data: Record<string, unknown>, options?: MutationOptions) => Promise<T>;
+    delete: (id: string, options?: DeleteOptions) => Promise<void>;
+    connect: <T = GraphEdgeRaw>(from: string, to: string, type: string, options?: MutationOptions) => Promise<T>;
+    history: (id: string, options?: HistoryOptions) => Promise<HistoryEntry[]>;
+    batch: {
+        delete: (ids: string[], options?: DeleteOptions) => Promise<BatchResult>;
+    };
+    timeseries: {
+        get: (id: string, options?: TimeseriesOptions) => Promise<TimeseriesValue[]>;
+        add: (id: string, values: TimeseriesValue[], options?: TransportScopeOptions) => Promise<void>;
+        query: (options: TimeseriesQueryOptions) => Promise<TimeseriesValue[]>;
+        history: (id: string, timestamp: number, options?: TimeseriesHistoryOptions) => Promise<TimeseriesHistory>;
+    };
+    content: {
+        set: (id: string, data: Blob, contentType: string, options?: TransportScopeOptions) => Promise<string>;
+        get: (id: string, contentId: string, options?: TransportScopeOptions) => Promise<Blob>;
+    };
+};
+export type GraphApi = ReturnType<typeof graphApi>;

package/dist/api/graph.js

@@ -0,0 +1,139 @@
+import { json, scoped, withQuery } from './request.js';
+const GRAPH = '/bardioc/api/graph/7.4';
+const node = (id, suffix = '') => `${GRAPH}/${encodeURIComponent(id)}${suffix}`;
+const readFields = ({ fields, includeDeleted, listMeta }) => ({
+    fields,
+    includeDeleted,
+    listMeta,
+});
+const mutationQuery = ({ fullResponse, listMeta }) => ({ fullResponse, listMeta });
+/** The Bardioc graph API, called through the host. */
+export function graphApi(request) {
+    const get = (id, options = {}) => request({
+        path: withQuery(node(id), { ...readFields(options), vid: options.vid }),
+        ...scoped(options),
+    });
+    const remove = (id, options = {}) => request({
+        path: withQuery(node(id), { hard: options.hard }),
+        method: 'DELETE',
+        ...scoped(options),
+    });
+    return {
+        get,
+        getMany: (ids, options = {}) => request({
+            path: withQuery(`${GRAPH}/query/ids`, { query: ids.join(','), ...readFields(options) }),
+            ...scoped(options),
+        }),
+        getByXid: (xid, options = {}) => request({
+            path: withQuery(`${GRAPH}/xid/${encodeURIComponent(xid)}`, readFields(options)),
+            ...scoped(options),
+        }),
+        query: (lucene, options = {}) => request({
+            path: withQuery(`${GRAPH}/query/vertices`, {
+                query: lucene,
+                limit: options.limit,
+                offset: options.offset,
+                order: options.order,
+                ...readFields(options),
+            }),
+            ...scoped(options),
+        }),
+        gremlin: (rootId, query, options = {}) => request({
+            path: `${GRAPH}/query/gremlin`,
+            ...json({ root: rootId, query, ...readFields(options) }),
+            ...scoped(options),
+        }),
+        combined: (elasticsearchQuery, gremlinQuery, options = {}) => request({
+            path: `${GRAPH}/query/combined`,
+            ...json({
+                elasticsearch_query: elasticsearchQuery,
+                gremlin_query: gremlinQuery,
+                limit: options.limit,
+            }),
+            ...scoped(options),
+        }),
+        create: (type, data, options = {}) => request({
+            path: withQuery(`${GRAPH}/new/${encodeURIComponent(type)}`, mutationQuery(options)),
+            ...json(data),
+            ...scoped(options),
+        }),
+        update: (id, data, options = {}) => request({
+            path: withQuery(node(id), mutationQuery(options)),
+            ...json(data),
+            ...scoped(options),
+        }),
+        delete: remove,
+        connect: (from, to, type, options = {}) => request({
+            path: withQuery(`${GRAPH}/connect`, mutationQuery(options)),
+            ...json({ fromId: from, toId: to, edgeType: type }),
+            ...scoped(options),
+        }),
+        history: (id, options = {}) => request({
+            path: withQuery(node(id, '/history'), {
+                from: options.from,
+                to: options.to,
+                limit: options.limit,
+                offset: options.offset,
+                includeDeleted: options.includeDeleted,
+            }),
+            ...scoped(options),
+        }),
+        batch: {
+            delete: async (ids, options = {}) => {
+                const results = await Promise.allSettled(ids.map(id => remove(id, options)));
+                const result = { succeeded: [], failed: [] };
+                results.forEach((outcome, index) => {
+                    const id = ids[index];
+                    if (outcome.status === 'fulfilled')
+                        result.succeeded.push(id);
+                    else
+                        result.failed.push({ id, error: String(outcome.reason?.message ?? outcome.reason) });
+                });
+                return result;
+            },
+        },
+        timeseries: {
+            get: (id, options = {}) => request({
+                path: withQuery(node(id, '/values'), {
+                    from: options.from,
+                    to: options.to,
+                    limit: options.limit,
+                    order: options.order,
+                    with: options.withIds?.join(','),
+                    aggregate: options.aggregate,
+                    includeDeleted: options.includeDeleted,
+                }),
+                ...scoped(options),
+            }),
+            add: (id, values, options = {}) => request({ path: node(id, '/values'), ...json({ values }), ...scoped(options) }),
+            query: (options) => request({
+                path: withQuery(`${GRAPH}/query/values`, {
+                    ids: options.ids?.join(','),
+                    from: options.from,
+                    to: options.to,
+                    limit: options.limit,
+                    order: options.order,
+                    aggregate: options.aggregate,
+                }),
+                ...scoped(options),
+            }),
+            history: (id, timestamp, options = {}) => request({
+                path: withQuery(node(id, '/values/history'), {
+                    timestamp,
+                    includeDeleted: options.includeDeleted,
+                }),
+                ...scoped(options),
+            }),
+        },
+        content: {
+            set: async (id, data, contentType, options = {}) => (await request({
+                path: node(id, '/content'),
+                method: 'POST',
+                body: data,
+                contentType,
+                ...scoped(options),
+            })).contentId,
+            get: (id, contentId, options = {}) => request({ path: withQuery(node(id, '/content'), { contentId }), ...scoped(options) }),
+        },
+    };
+}

package/dist/api/os.d.ts

@@ -0,0 +1,30 @@
+import type { Application, Configuration, CreateMemberInput, CreateUnitInput, FileEntry, InstanceList, OrgMember, OrgStructure, OrgUnit, UpdateMemberInput, UpdateUnitInput, UserProfile } from '../types.js';
+import { type BffRequester } from './request.js';
+/** The Bardioc OS API, called through the host. */
+export declare function osApi(request: BffRequester): {
+    profile: {
+        get: () => Promise<UserProfile>;
+        getAvatar: () => Promise<Blob>;
+        setAvatar: (image: Blob) => Promise<void>;
+        getInstances: () => Promise<InstanceList>;
+    };
+    organization: {
+        getStructure: () => Promise<OrgStructure>;
+        createUnit: (data: CreateUnitInput) => Promise<OrgUnit>;
+        updateUnit: (id: string, data: UpdateUnitInput) => Promise<OrgUnit>;
+        createMember: (data: CreateMemberInput) => Promise<OrgMember>;
+        updateMember: (id: string, data: UpdateMemberInput) => Promise<OrgMember>;
+        deleteMember: (id: string) => Promise<void>;
+        inviteMember: (id: string) => Promise<void>;
+    };
+    applications: {
+        list: () => Promise<Application[]>;
+        get: (id: string) => Promise<Application>;
+        upload: (id: string, zip: Blob) => Promise<void>;
+        download: (id: string) => Promise<Blob>;
+        getFiles: (id: string) => Promise<FileEntry[]>;
+        getFile: (id: string, path: string) => Promise<string>;
+        getConfigurations: (id: string) => Promise<Configuration[]>;
+    };
+};
+export type OsApi = ReturnType<typeof osApi>;