@bardioc/app-sdk 0.4.0

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 ALMATO AG. All rights reserved.
+
+This is an internal library for ALMATO AG.

package/README.md

@@ -0,0 +1,368 @@
+# @bardioc/app-sdk
+
+SDK and Vite integration for building apps for the Bardioc OS.
+
+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.
+
+## 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.
+
+## Quick start
+
+```tsx
+import { AppSdkProvider, useNotify } from '@bardioc/app-sdk/react';
+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>;
+}
+
+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>
+  )
+);
+```
+
+## Exports
+
+| Path                        | Contents                                    |
+| --------------------------- | ------------------------------------------- |
+| `@bardioc/app-sdk`          | `createHostBridge`, errors, types, manifest |
+| `@bardioc/app-sdk/react`    | `AppSdkProvider`, hooks (`useSdk`, etc.)    |
+| `@bardioc/app-sdk/dev`      | host-backed standalone dev-session 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,
+  useStandaloneDevLogout,
+} from '@bardioc/app-sdk/react';
+
+// Standalone dev helpers
+import {
+  ensureDevAuthSession,
+  installDevBridge,
+  isDevStandalone,
+  isInsideIframe,
+} from '@bardioc/app-sdk/dev';
+```
+
+## Vite plugin
+
+```ts
+// vite.config.ts
+import { bardiocApp } from '@bardioc/app-sdk/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [react(), bardiocApp({ appName: 'my-app', port: 3005 })],
+});
+```
+
+Handles dev base path, port config, host session proxy routes, optional Cloudflare tunnel, 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:
+
+```html
+<link rel="stylesheet" href="/fonts/bardioc-fonts.css" />
+```
+
+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.
+
+- **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 / tunnel mode** 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
+
+Standalone local development is host-backed only.
+
+1. Create or open the app in the host App Store so you have its `VITE_APP_ID`.
+2. In the host App Store, open the app details and use `Copy Dev Session`.
+3. Paste the snippet into your local `.env`.
+4. Set `VITE_ENABLE_DEV_AUTH=true` and run `pnpm dev`.
+
+That flow stores a host-issued dev session locally and routes transport calls through the host `/api/transport` endpoint. There is no separate local token exchange mode anymore.
+
+For public testing against a live URL, run `pnpm dev:live` and use the emitted tunnel URL as the app's live URL in the host App Store configuration.
+
+## React hooks
+
+- `useSdk()` — raw bridge instance
+- `useNotify()` — fire-and-forget toast
+- `useSendToKernel()` — proxy a whitelisted message to the OS service worker
+- `useStandaloneDevLogout()` — clear standalone dev auth state and reload the page
+
+### IndexedDB persistence
+
+`useSdk()` exposes `bridge.idb(storeName)` for app-scoped persistence:
+
+```ts
+const drafts = bridge.idb('drafts');
+
+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');
+```
+
+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.
+
+**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.
+
+#### Graph API
+
+Access the graph database via `bridge.transport.graph.*`:
+
+```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',
+});
+
+// Create edge
+await sdk.transport.graph.connect(fromId, toId, 'ogit/relates');
+
+// Delete node
+await sdk.transport.graph.delete('node-id');
+
+// Time series
+const values = await sdk.transport.graph.timeseries.get('ts-id', {
+  from: '2026-01-01',
+  to: '2026-01-31',
+});
+```
+
+Available methods: `get`, `getMany`, `getByXid`, `query`, `gremlin`, `combined`, `create`, `update`, `delete`, `connect`, `history`, `batch.delete`, `timeseries.get`, `timeseries.add`, `timeseries.query`, `content.set`, `content.get`.
+
+All graph request option types accept optional `scopeId` when a request must target a specific scope.
+
+#### OS API
+
+Access OS features via `bridge.transport.os.*`:
+
+```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',
+});
+
+// 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',
+});
+```
+
+Available namespaces:
+
+- `os.profile.*` — `get`, `getAvatar`, `setAvatar`, `getInstances`
+- `os.organization.*` — `getStructure`, `createUnit`, `updateUnit`, `createMember`, `updateMember`, `deleteMember`, `inviteMember`
+- `os.applications.*` — `list`, `get`, `upload`, `download`, `getFiles`, `getFile`, `getConfigurations`
+
+### Error handling
+
+All transport methods throw structured errors:
+
+```ts
+import {
+  EntityNotFoundError,
+  ValidationError,
+  PermissionError,
+  TimeoutError,
+  NetworkError,
+  SdkError,
+} from '@bardioc/app-sdk';
+
+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);
+  }
+}
+```
+
+All errors extend `SdkError` with properties: `code`, `statusCode`, `context`, `message`.
+
+## App manifest
+
+Every app must include `public/app-manifest.json`:
+
+```json
+{
+  "manifestVersion": 2,
+  "id": "my-app",
+  "name": "My App",
+  "version": "1.0.0",
+  "permissions": ["notify", "transport"]
+}
+```
+
+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
+
+Optionally control how the OS frames the app via a `window` block:
+
+```json
+{
+  "manifestVersion": 2,
+  "id": "my-app",
+  "name": "My App",
+  "version": "1.0.0",
+  "permissions": ["notify"],
+  "window": {
+    "size": "md",
+    "resizable": true
+  }
+}
+```
+
+`size` picks a tier (default `md`):
+
+| Tier | Size (w × h) | Min (w × h) |
+| ---- | ------------ | ----------- |
+| `xs` | 480 × 320    | 360 × 280   |
+| `sm` | 640 × 480    | 480 × 320   |
+| `md` | 800 × 600    | 480 × 320   |
+| `lg` | 1024 × 800   | 640 × 480   |
+| `xl` | 1280 × 800   | 800 × 600   |
+
+Instead of a tier, `size` may be a custom dimensions object — `{ width, height }` (px), with optional `minWidth`/`minHeight` (each defaults to a floor when omitted). Custom dimensions are literal, so `orientation` does not swap them:
+
+```json
+{
+  "window": { "size": { "width": 720, "height": 540, "minWidth": 400, "minHeight": 300 } }
+}
+```
+
+Other flags (all optional booleans): `canHaveMultipleWindows`, `isInstanceAware`, `resizable`, `maximizable`, `minimizable`, `customScroll`, `centered`, `isHeaderless`.
+
+## Support
+
+For support, contact yevhenii.atlanov@almato.com.
+
+## License
+
+MIT.
+
+Copyright (c) 2026 ALMATO AG. All rights reserved.
+
+This is an internal library for ALMATO AG.

package/assets/fonts/README.md

@@ -0,0 +1,11 @@
+# Platform font contract assets (dev server only)
+
+Byte-identical copies of the canonical files served by webos-host at `/fonts/*`
+(source of truth: `bardioc-desktop-frontend/apps/webos-host/public/fonts/`).
+
+The `bardiocApp()` Vite plugin serves these at `/fonts/*` in standalone dev mode so
+the same `<link rel="stylesheet" href="/fonts/bardioc-fonts.css" />` works embedded
+in the OS and standalone. They are dev-server assets only — never bundled into apps.
+
+When webos-host's fonts change, re-copy the files verbatim. Files under `v1/` are
+immutable: never overwrite a published binary, mirror new version directories instead.

package/assets/fonts/bardioc-fonts.css

@@ -0,0 +1,55 @@
+/*
+ * Bardioc platform font contract — stable entry point.
+ *
+ * Hosted apps load this file with a single static line in index.html:
+ *   <link rel="stylesheet" href="/fonts/bardioc-fonts.css" />
+ * It resolves same-origin both embedded in the OS shell (served by webos-host)
+ * and in standalone dev mode (served by the @bardioc/app-sdk Vite plugin).
+ *
+ * This URL is a public platform API: it must never be renamed or removed,
+ * because installed 3rd-party app zips reference it and cannot be rebuilt.
+ * The binaries below are versioned (./v1/) so the contents of this file can
+ * evolve without breaking already-installed apps.
+ *
+ * Variable fonts, latin subset only — matching the OS shell (layout.tsx loads
+ * subsets: ['latin']). Each file covers the full weight axis; the
+ * unicode-range gates keep the door open to add more script subsets
+ * additively later. Sources are verbatim from @fontsource-variable packages
+ * (see README.md), with URLs rewritten to the local ./v1/ copies.
+ */
+
+/* nunito-sans-latin-wght-normal — @fontsource-variable/nunito-sans 5.2.7 */
+@font-face {
+    font-family: 'Nunito Sans Variable';
+    font-style: normal;
+    font-display: swap;
+    font-weight: 200 1000;
+    src: url(./v1/nunito-sans-latin-wght-normal.woff2) format('woff2-variations');
+    unicode-range:
+        U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308,
+        U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+/* nunito-sans-latin-wght-italic — @fontsource-variable/nunito-sans 5.2.7 */
+@font-face {
+    font-family: 'Nunito Sans Variable';
+    font-style: italic;
+    font-display: swap;
+    font-weight: 200 1000;
+    src: url(./v1/nunito-sans-latin-wght-italic.woff2) format('woff2-variations');
+    unicode-range:
+        U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308,
+        U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+/* geist-mono-latin-wght-normal — @fontsource-variable/geist-mono 5.2.8 */
+@font-face {
+    font-family: 'Geist Mono Variable';
+    font-style: normal;
+    font-display: swap;
+    font-weight: 100 900;
+    src: url(./v1/geist-mono-latin-wght-normal.woff2) format('woff2-variations');
+    unicode-range:
+        U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308,
+        U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}

package/dist/contract-matrix.d.ts

@@ -0,0 +1,130 @@
+import type { AppManifestPermission } from './manifest.js';
+export declare const SDK_CONTRACT_MATRIX: {
+    readonly SDK_INIT: {
+        readonly requestPayload: "{ appId?: string }";
+        readonly responsePayload: "SdkInitResponse";
+        readonly permission: null;
+        readonly expectedHostBehavior: "Handshake the iframe app and return SDK-owned host context.";
+    };
+    readonly SDK_NOTIFY: {
+        readonly requestPayload: "SdkNotifyPayload";
+        readonly responsePayload: "{ ok: true }";
+        readonly permission: "notify";
+        readonly expectedHostBehavior: "Surface a host-level notification and acknowledge delivery.";
+    };
+    readonly SDK_KERNEL_PROXY: {
+        readonly requestPayload: "SdkKernelProxyPayload";
+        readonly responsePayload: "KernelProtocol response";
+        readonly permission: "kernel-proxy";
+        readonly expectedHostBehavior: "Forward only allow-listed kernel messages through the host.";
+    };
+    readonly SDK_TRANSPORT: {
+        readonly requestPayload: "SdkTransportPayload";
+        readonly responsePayload: "Upstream transport response payload";
+        readonly permission: "transport";
+        readonly expectedHostBehavior: "Relay app-scoped transport requests with scope-aware host mediation.";
+    };
+    readonly SDK_SET_COMMANDS: {
+        readonly requestPayload: "SdkSetCommandsPayload";
+        readonly responsePayload: "{ ok: true }";
+        readonly permission: null;
+        readonly expectedHostBehavior: "Store the app command registry for host command invocation.";
+    };
+    readonly SDK_SET_MENU: {
+        readonly requestPayload: "SdkSetMenuPayload";
+        readonly responsePayload: "{ ok: true }";
+        readonly permission: null;
+        readonly expectedHostBehavior: "Store the app menu tree without degrading supported SDK menu kinds.";
+    };
+    readonly SDK_SET_ACTIVE_TAB: {
+        readonly requestPayload: "SdkSetActiveTabPayload";
+        readonly responsePayload: "{ ok: true }";
+        readonly permission: null;
+        readonly expectedHostBehavior: "Persist the app-reported active tab label in host window state.";
+    };
+    readonly SDK_SHORTCUT_EVENT: {
+        readonly requestPayload: "SdkShortcutEventPayload";
+        readonly responsePayload: null;
+        readonly permission: null;
+        readonly expectedHostBehavior: "Route a focused iframe shortcut event through host shortcut handling.";
+    };
+    readonly SDK_STORAGE_GET: {
+        readonly requestPayload: "SdkStorageGetPayload";
+        readonly responsePayload: "unknown";
+        readonly permission: "storage";
+        readonly expectedHostBehavior: "Host-owned storage bridge; currently deferred in bdf.";
+    };
+    readonly SDK_STORAGE_SET: {
+        readonly requestPayload: "SdkStorageSetPayload";
+        readonly responsePayload: "void";
+        readonly permission: "storage";
+        readonly expectedHostBehavior: "Host-owned storage bridge; currently deferred in bdf.";
+    };
+    readonly SDK_STORAGE_DELETE: {
+        readonly requestPayload: "SdkStorageDeletePayload";
+        readonly responsePayload: "void";
+        readonly permission: "storage";
+        readonly expectedHostBehavior: "Host-owned storage bridge; currently deferred in bdf.";
+    };
+    readonly SDK_STORAGE_KEYS: {
+        readonly requestPayload: "{}";
+        readonly responsePayload: "string[]";
+        readonly permission: "storage";
+        readonly expectedHostBehavior: "Host-owned storage bridge; currently deferred in bdf.";
+    };
+    readonly SDK_IDB_GET: {
+        readonly requestPayload: "SdkIdbGetPayload";
+        readonly responsePayload: "SdkIdbEntry | null";
+        readonly permission: "indexdb";
+        readonly expectedHostBehavior: "Perform app-scoped IndexedDB reads in host-owned storage.";
+    };
+    readonly SDK_IDB_PUT: {
+        readonly requestPayload: "SdkIdbPutPayload";
+        readonly responsePayload: "void";
+        readonly permission: "indexdb";
+        readonly expectedHostBehavior: "Perform app-scoped IndexedDB writes in host-owned storage.";
+    };
+    readonly SDK_IDB_DELETE: {
+        readonly requestPayload: "SdkIdbDeletePayload";
+        readonly responsePayload: "void";
+        readonly permission: "indexdb";
+        readonly expectedHostBehavior: "Perform app-scoped IndexedDB deletes in host-owned storage.";
+    };
+    readonly SDK_IDB_QUERY: {
+        readonly requestPayload: "SdkIdbQueryPayload";
+        readonly responsePayload: "SdkIdbEntry[]";
+        readonly permission: "indexdb";
+        readonly expectedHostBehavior: "Perform app-scoped IndexedDB queries in host-owned storage.";
+    };
+    readonly SDK_LAUNCH_APP: {
+        readonly requestPayload: "{ appId: string }";
+        readonly responsePayload: "{ windowId: string | null }";
+        readonly permission: null;
+        readonly expectedHostBehavior: "Launch another registered app through the host shell.";
+    };
+    readonly SDK_COMMAND_INVOKE: {
+        readonly requestPayload: "SdkCommandInvokePayload";
+        readonly responsePayload: "{ ok: true }";
+        readonly permission: null;
+        readonly expectedHostBehavior: "Host-to-app command callback delivery.";
+    };
+    readonly SDK_OS_CONFIG_UPDATE: {
+        readonly requestPayload: "OsConfig";
+        readonly responsePayload: null;
+        readonly permission: null;
+        readonly expectedHostBehavior: "Host-to-app runtime OS configuration update delivery.";
+    };
+    readonly SDK_RESPONSE: {
+        readonly requestPayload: "SdkResponse";
+        readonly responsePayload: null;
+        readonly permission: null;
+        readonly expectedHostBehavior: "Request/response envelope used by the bridge runtime.";
+    };
+    readonly SDK_INIT_ACK: {
+        readonly requestPayload: "SdkInitResponse";
+        readonly responsePayload: null;
+        readonly permission: null;
+        readonly expectedHostBehavior: "Handshake acknowledgement used by the bridge runtime.";
+    };
+};
+export declare function getRequiredPermissionForSdkMessage(messageType: string): AppManifestPermission | null;