@bardioc/app-sdk 0.4.0

package/dist/types.d.ts

@@ -0,0 +1,343 @@
+/** Wire-level envelope sent from iframe → host. */
+export interface SdkMessage<T extends string = string, P = unknown> {
+    type: T;
+    id: string;
+    payload: P;
+}
+/** Wire-level envelope sent from host → iframe as a response. */
+export interface SdkResponse<P = unknown> {
+    type: string;
+    id: string;
+    payload: P;
+    error?: string;
+}
+/** OS configuration provided to apps. */
+export interface OsConfig {
+    theme: string;
+    language: string;
+    tabId: string;
+    windowId: string;
+    instanceId: string | null;
+    systemSize?: string;
+}
+/** Context returned by the host after a successful handshake. */
+export interface SdkInitResponse {
+    appId: string;
+    instanceId: string | null;
+    osConfig?: OsConfig;
+}
+export type SdkCommandHandler = () => void | Promise<void>;
+export interface SdkCommandDefinition {
+    id: string;
+    title?: string;
+    disabled?: boolean;
+    checked?: boolean;
+}
+export interface SdkMenuCommandItem {
+    type: 'command';
+    commandId: string;
+    label?: string;
+    leftIcon?: string;
+    separatorAbove?: boolean;
+    shortcut?: string;
+    variant?: 'default' | 'destructive';
+}
+export interface SdkMenuSubmenuItem {
+    type: 'submenu';
+    label: string;
+    leftIcon?: string;
+    separatorAbove?: boolean;
+    items: SdkMenuItem[];
+    contentWidth?: string;
+}
+export type SdkMenuItem = SdkMenuCommandItem | SdkMenuSubmenuItem;
+export type SdkMenuRootKind = 'app' | 'menu';
+export interface SdkMenuRoot {
+    label: string;
+    kind?: SdkMenuRootKind;
+    leftIcon?: string;
+    items: SdkMenuItem[];
+    contentWidth?: string;
+}
+export interface SdkSetCommandsPayload {
+    commands: SdkCommandDefinition[];
+}
+export interface SdkSetMenuPayload {
+    menu: SdkMenuRoot[] | null;
+}
+export interface SdkSetActiveTabPayload {
+    activeTab: string | null;
+}
+export interface SdkCommandInvokePayload {
+    commandId: string;
+}
+export interface SdkShortcutEventPayload {
+    /**
+     * Physical-key identifier (`KeyboardEvent.code`), e.g. `"KeyS"`, `"Digit1"`,
+     * `"Comma"`. Layout- and modifier-independent. Hosts that match shortcuts
+     * by physical key (recommended for cross-platform / cross-layout
+     * correctness, especially macOS Option combinations) use this field.
+     */
+    code: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+    shiftKey: boolean;
+}
+export type NotifyLevel = 'success' | 'error' | 'info' | 'warning';
+export interface SdkNotifyPayload {
+    message: string;
+    level: NotifyLevel;
+}
+export interface SdkStorageGetPayload {
+    key: string;
+}
+export interface SdkStorageSetPayload {
+    key: string;
+    value: unknown;
+}
+export interface SdkStorageDeletePayload {
+    key: string;
+}
+export interface SdkKernelProxyPayload {
+    kernelType: string;
+    kernelPayload?: unknown;
+}
+export interface SdkTransportPayload {
+    path: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    contentType?: string;
+    scopeId?: string;
+    scopePolicy?: 'none' | 'optional' | 'required';
+}
+export interface TransportScopeOptions {
+    scopeId?: string;
+}
+export interface SdkIdbGetPayload {
+    storeName: string;
+    key: string;
+}
+export interface SdkIdbPutPayload {
+    storeName: string;
+    key: string;
+    value: unknown;
+}
+export interface SdkIdbDeletePayload {
+    storeName: string;
+    key: string;
+}
+export interface SdkIdbQueryPayload {
+    storeName: string;
+    prefix?: string;
+    limit?: number;
+}
+/** Configuration passed to {@link createHostBridge}. */
+export interface HostBridgeConfig {
+    appId?: string;
+    /** Override the host origin for `postMessage`. Inferred from `document.referrer` by default. */
+    targetOrigin?: string;
+    /** Handshake timeout in ms. Default: `5000`. */
+    connectTimeout?: number;
+    /** Enable verbose `[app-sdk]` console output. Default: `false`. */
+    debug?: boolean;
+}
+/** Key-value storage sandboxed to this app by the host. */
+export interface SdkStorage {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+}
+export interface SdkIdbEntry<T = unknown> {
+    key: string;
+    value: T;
+    updatedAt: number;
+}
+export interface SdkIdbStore {
+    get<T = unknown>(key: string): Promise<T | null>;
+    put(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    query<T = unknown>(options?: {
+        prefix?: string;
+        limit?: number;
+    }): Promise<SdkIdbEntry<T>[]>;
+}
+export interface SdkTransport {
+    graph: GraphTransport;
+    os: OsTransport;
+}
+/** Graph node in raw backend format (ogit/* fields) */
+export interface GraphNodeRaw {
+    'ogit/_id': string;
+    'ogit/_type': string;
+    [key: string]: unknown;
+}
+/** Graph edge in raw backend format */
+export interface GraphEdgeRaw {
+    'ogit/_id': string;
+    'ogit/_type': string;
+    'ogit/_in-id': string;
+    'ogit/_out-id': string;
+    [key: string]: unknown;
+}
+export interface GetNodeOptions extends TransportScopeOptions {
+    fields?: string;
+    includeDeleted?: boolean;
+    listMeta?: boolean;
+    vid?: number;
+}
+export interface QueryOptions extends TransportScopeOptions {
+    limit?: number;
+    offset?: number;
+    fields?: string;
+    includeDeleted?: boolean;
+    listMeta?: boolean;
+    order?: string;
+}
+export interface GremlinOptions extends TransportScopeOptions {
+    fields?: string;
+    includeDeleted?: boolean;
+    listMeta?: boolean;
+}
+export interface MutationOptions extends TransportScopeOptions {
+    fullResponse?: boolean;
+    listMeta?: boolean;
+}
+export interface DeleteOptions extends TransportScopeOptions {
+    hard?: boolean;
+}
+export interface HistoryOptions extends TransportScopeOptions {
+    from?: number | string;
+    to?: number | string;
+    limit?: number;
+    offset?: number;
+    includeDeleted?: boolean;
+}
+export interface HistoryEntry {
+    version: number;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+export interface TimeseriesValue {
+    timestamp: number;
+    value: unknown;
+}
+export interface TimeseriesOptions extends TransportScopeOptions {
+    from?: number | string;
+    to?: number | string;
+    limit?: number;
+    order?: 'asc' | 'desc';
+}
+export interface TimeseriesQueryOptions extends TimeseriesOptions {
+    ids?: string[];
+    aggregate?: string;
+}
+export interface BatchResult {
+    succeeded: string[];
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+}
+export interface UserProfile {
+    id: string;
+    email: string;
+    name?: string;
+    [key: string]: unknown;
+}
+export interface OrgUnit {
+    id: string;
+    name: string;
+    parentId?: string;
+    [key: string]: unknown;
+}
+export interface OrgMember {
+    id: string;
+    mailAddress: string;
+    firstName?: string;
+    lastName?: string;
+    [key: string]: unknown;
+}
+export interface OrgStructure {
+    units: OrgUnit[];
+    members: OrgMember[];
+}
+export interface Application {
+    id: string;
+    name: string;
+    version?: string;
+    [key: string]: unknown;
+}
+export interface Configuration {
+    key: string;
+    value: unknown;
+}
+export interface FileEntry {
+    path: string;
+    size: number;
+    mimeType?: string;
+}
+export interface InstanceList {
+    instances: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export interface CreateUnitInput {
+    name: string;
+    parentId?: string;
+    [key: string]: unknown;
+}
+export interface UpdateUnitInput {
+    name?: string;
+    parentId?: string;
+    [key: string]: unknown;
+}
+export interface CreateMemberInput {
+    mailAddress: string;
+    firstName?: string;
+    lastName?: string;
+    [key: string]: unknown;
+}
+export interface UpdateMemberInput {
+    mailAddress?: string;
+    firstName?: string;
+    lastName?: string;
+    [key: string]: unknown;
+}
+export interface OsRequestOptions extends TransportScopeOptions {
+    path: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    contentType?: string;
+    scopePolicy?: 'none' | 'optional' | 'required';
+}
+/** Live connection between an iframe app and its host OS. */
+export interface HostBridge {
+    /** Perform the SDK handshake. Resolves with host context. Cached after first call. */
+    connect(): Promise<SdkInitResponse>;
+    /** Tear down the bridge and reject all pending requests. */
+    destroy(): void;
+    readonly connected: boolean;
+    readonly context: SdkInitResponse | null;
+    notify(message: string, level?: NotifyLevel): void;
+    storage: SdkStorage;
+    idb(storeName: string): SdkIdbStore;
+    transport: SdkTransport;
+    setCommands(commands: SdkCommandDefinition[]): Promise<void>;
+    setMenu(menu: SdkMenuRoot[] | null): Promise<void>;
+    setActiveTab(activeTab: string | null): Promise<void>;
+    sendShortcutEvent(payload: SdkShortcutEventPayload): void;
+    registerCommandHandlers(handlers: Record<string, SdkCommandHandler>): () => void;
+    onOsConfigUpdate(callback: (config: OsConfig) => void): () => void;
+    /** Forward a whitelisted message to the OS service worker. */
+    sendToKernel<R = unknown>(kernelType: string, kernelPayload?: unknown): Promise<R>;
+    /** Launch an app by ID in the OS. Returns the window ID if successful. */
+    launchApp(appId: string): Promise<{
+        windowId: string | null;
+    }>;
+}
+/** Forward declarations for transport classes */
+export type GraphTransport = import('./transports/graph-transport.js').GraphTransport;
+export type OsTransport = import('./transports/os-transport.js').OsTransport;

package/dist/vite.d.ts

@@ -0,0 +1,9 @@
+/** Vite plugin for Bardioc iframe apps. Usage: `bardiocApp({ appName, port })` */
+export { bardiocDevAuth, type BardiocDevAuthOptions } from './dev-auth-vite.js';
+export interface BardiocAppOptions {
+    appName?: string;
+    port: number;
+    previewPort?: number;
+}
+/** Returns an array of Vite plugins for a Bardioc iframe app. */
+export declare function bardiocApp(opts: BardiocAppOptions): any[];

package/dist/vite.js

@@ -0,0 +1,262 @@
+/** Vite plugin for Bardioc iframe apps. Usage: `bardiocApp({ appName, port })` */
+import { execSync, spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readDotEnvValue } from './dot-env.js';
+import { MANIFEST_FILENAME, validateManifest } from './manifest.js';
+export { bardiocDevAuth } from './dev-auth-vite.js';
+function hasCommand(cmd) {
+    try {
+        execSync(`which ${cmd}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function startTunnel(port) {
+    return new Promise((resolve, reject) => {
+        if (!hasCommand('cloudflared')) {
+            reject(new Error('cloudflared is not installed.\n' +
+                '  macOS:   brew install cloudflared\n' +
+                '  Linux:   apt install cloudflared\n' +
+                '  Other:   https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/'));
+            return;
+        }
+        const proc = spawn('cloudflared', ['tunnel', '--url', `http://localhost:${port}`], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let found = false;
+        const timeout = setTimeout(() => {
+            if (!found) {
+                proc.kill();
+                reject(new Error('Tunnel timed out waiting for URL'));
+            }
+        }, 30_000);
+        function onData(data) {
+            const text = data.toString();
+            const match = text.match(/(https:\/\/[a-z0-9-]+\.trycloudflare\.com)/);
+            if (match?.[1] && !found) {
+                found = true;
+                clearTimeout(timeout);
+                resolve({ url: match[1], process: proc });
+            }
+        }
+        proc.stdout?.on('data', onData);
+        proc.stderr?.on('data', onData);
+        proc.on('close', code => {
+            if (!found) {
+                clearTimeout(timeout);
+                reject(new Error(`cloudflared exited with code ${code} before providing a URL`));
+            }
+        });
+    });
+}
+function devProxy(opts) {
+    const { port } = opts;
+    const wantTunnel = !!process.env.BARDIOC_TUNNEL;
+    let tunnelProcess = null;
+    let tunnelHost = null;
+    let tunnelReady = null;
+    return {
+        name: 'bardioc-dev-proxy',
+        apply: 'serve',
+        configureServer(server) {
+            if (wantTunnel) {
+                tunnelReady = (async () => {
+                    try {
+                        const manifestPath = resolve(process.cwd(), 'public', MANIFEST_FILENAME);
+                        let manifestId = opts.appName;
+                        if (existsSync(manifestPath)) {
+                            try {
+                                const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+                                manifestId = manifest.id || manifestId;
+                            }
+                            catch {
+                                // ignore
+                            }
+                        }
+                        console.log(`[bardioc] Starting tunnel for "${manifestId}" on port ${port}...`);
+                        const tunnel = await startTunnel(port);
+                        tunnelProcess = tunnel.process;
+                        tunnelHost = new URL(tunnel.url).host;
+                        console.log(`[bardioc] Tunnel ready: ${tunnel.url}`);
+                    }
+                    catch (err) {
+                        console.error(`[bardioc] Tunnel failed: ${err.message}`);
+                        process.exit(1);
+                    }
+                })();
+            }
+            server.httpServer?.on('listening', async () => {
+                const manifestPath = resolve(process.cwd(), 'public', MANIFEST_FILENAME);
+                const envPath = resolve(process.cwd(), '.env');
+                const envAppId = existsSync(envPath) ? readDotEnvValue(envPath, 'VITE_APP_ID') : null;
+                if (!existsSync(manifestPath)) {
+                    console.warn(`[bardioc] public/${MANIFEST_FILENAME} not found`);
+                    return;
+                }
+                let manifest;
+                try {
+                    manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+                }
+                catch (err) {
+                    console.error(`[bardioc] Failed to read manifest: ${err}`);
+                    return;
+                }
+                const manifestId = opts.appName || manifest.id;
+                if (wantTunnel) {
+                    await tunnelReady;
+                    if (!tunnelHost) {
+                        console.error(`[bardioc] Tunnel was requested but failed to start`);
+                        process.exit(1);
+                    }
+                    console.log(`[bardioc] Use this live URL in the host App Store app configuration:`);
+                    console.log(`[bardioc]   App Name: ${manifestId}`);
+                    console.log(`[bardioc]   App ID: ${envAppId || '<from .env VITE_APP_ID>'}`);
+                    console.log(`[bardioc]   Live URL: https://${tunnelHost}`);
+                }
+                else {
+                    console.log(`[bardioc] Dev server ready: http://localhost:${port}`);
+                    console.log(`[bardioc] For standalone host-backed auth, open this app in the host App Store and use "Copy Dev Session".`);
+                    console.log(`[bardioc]   App Name: ${manifestId}`);
+                    console.log(`[bardioc]   App ID: ${envAppId || '<from .env VITE_APP_ID>'}`);
+                    console.log(`[bardioc]   URL: http://localhost:${port}`);
+                }
+            });
+            server.httpServer?.on('close', () => {
+                tunnelProcess?.kill();
+            });
+        },
+    };
+}
+const FONTS_URL_PREFIX = '/fonts/';
+const FONT_CONTENT_TYPES = {
+    css: 'text/css; charset=utf-8',
+    woff2: 'font/woff2',
+};
+/**
+ * Serves the platform font contract (`/fonts/bardioc-fonts.css` + `/fonts/v1/*`)
+ * from assets shipped inside the SDK package, so the same absolute URL apps use
+ * embedded in the OS also resolves in standalone dev mode (and tunnel mode —
+ * the tunnel terminates at this server). Dev-server only; the assets are never
+ * bundled into apps.
+ *
+ * Vite's dev HTML transform rewrites the root-absolute contract <link> to a
+ * base-prefixed URL (/_apps/<id>/fonts/...), so like the dev-auth middleware
+ * this strips the configured base before matching. The reserved /fonts/ path
+ * intentionally shadows an app's own public/fonts/ in dev.
+ */
+function fontsMiddleware() {
+    // import.meta.url must not be inlined into new URL(): Vite statically rewrites
+    // the `new URL('...', import.meta.url)` pattern (asset URL detection), which
+    // breaks the path under vite-based tooling such as vitest.
+    const moduleUrl = import.meta.url;
+    const fontsDir = fileURLToPath(new URL('../assets/fonts/', moduleUrl));
+    return {
+        name: 'bardioc-fonts',
+        apply: 'serve',
+        configureServer(server) {
+            const basePath = server.config.base.endsWith('/')
+                ? server.config.base.slice(0, -1)
+                : server.config.base;
+            server.middlewares.use((req, res, next) => {
+                const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+                const routePath = pathname.startsWith(basePath)
+                    ? pathname.slice(basePath.length) || '/'
+                    : pathname;
+                const isReadMethod = req.method === 'GET' || req.method === 'HEAD';
+                if (!routePath.startsWith(FONTS_URL_PREFIX) || !isReadMethod) {
+                    next();
+                    return;
+                }
+                const contentType = FONT_CONTENT_TYPES[routePath.split('.').pop() ?? ''];
+                const filePath = resolve(fontsDir, routePath.slice(FONTS_URL_PREFIX.length));
+                // Traversal guard: only files inside the packaged fonts directory.
+                if (!contentType || !filePath.startsWith(fontsDir.replace(/[/\\]$/, '') + sep)) {
+                    next();
+                    return;
+                }
+                if (!existsSync(filePath)) {
+                    res.statusCode = 404;
+                    res.end('Not found');
+                    return;
+                }
+                res.setHeader('Content-Type', contentType);
+                // Mirror the host's semantics: versioned binaries are immutable, the
+                // entry stylesheet must always be revalidated so edits show up in dev.
+                res.setHeader('Cache-Control', routePath.startsWith(`${FONTS_URL_PREFIX}v1/`)
+                    ? 'public, max-age=31536000, immutable'
+                    : 'no-cache');
+                res.end(req.method === 'HEAD' ? undefined : readFileSync(filePath));
+            });
+        },
+    };
+}
+function manifestCheck() {
+    return {
+        name: 'bardioc-manifest-check',
+        apply: 'build',
+        enforce: 'post',
+        closeBundle() {
+            const manifestPath = resolve(process.cwd(), 'public', MANIFEST_FILENAME);
+            if (!existsSync(manifestPath)) {
+                throw new Error(`[bardioc] public/${MANIFEST_FILENAME} not found`);
+            }
+            try {
+                const raw = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+                const { valid, errors } = validateManifest(raw);
+                if (!valid) {
+                    throw new Error(`[bardioc] Manifest validation errors:\n${errors.map(error => `  - ${error}`).join('\n')}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.startsWith('[bardioc]')) {
+                    throw error;
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`[bardioc] Could not parse ${MANIFEST_FILENAME}: ${message}`);
+            }
+        },
+    };
+}
+/** Returns an array of Vite plugins for a Bardioc iframe app. */
+export function bardiocApp(opts) {
+    const { port, previewPort } = opts;
+    // Read manifest to get app ID
+    const manifestPath = resolve(process.cwd(), 'public', MANIFEST_FILENAME);
+    let manifestId = opts.appName;
+    if (existsSync(manifestPath)) {
+        try {
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            manifestId = manifest.id || manifestId;
+        }
+        catch (err) {
+            console.warn(`[bardioc] Could not read manifest, using appName from options`);
+        }
+    }
+    if (!manifestId) {
+        throw new Error('[bardioc] No appName found in options or manifest. Please provide appName or create public/app-manifest.json');
+    }
+    const baseConfig = {
+        name: 'bardioc-base-config',
+        config(_config, env) {
+            const isDev = env.command === 'serve';
+            return {
+                base: isDev ? `/_apps/${manifestId}/` : './',
+                server: {
+                    port,
+                    allowedHosts: true,
+                },
+                preview: {
+                    port: previewPort ?? port + 1000,
+                },
+                build: {
+                    outDir: 'dist',
+                },
+            };
+        },
+    };
+    return [baseConfig, devProxy(opts), fontsMiddleware(), manifestCheck()];
+}