@bardioc/app-sdk 1.0.0 → 1.0.2

package/README.md

@@ -113,7 +113,7 @@ response body as `details`.
 ```ts
 import { installDevHost, isDevStandalone } from '@bardioc/app-sdk/dev';
 
-if (isDevStandalone()) installDevHost({ appId: 'my-app' });
+if (isDevStandalone()) installDevHost();
 ```
 
 The dev host answers the same contract as the Bardioc host: BFF calls go through the dev-auth

package/dist/client.d.ts

@@ -96,6 +96,10 @@ declare function open(port: MessagePort, initial: Context): {
         launch: (id: string) => Promise<{
             windowId: string | null;
         }>;
+        /** The caller's settings of the developer application `id`, as the host holds them. */
+        getConfig: (id: string) => Promise<import("./contract.js").DevAppConfig>;
+        /** Replaces them with the edited document; the host applies the answer at once. */
+        saveConfig: (id: string, data: Record<string, unknown>) => Promise<import("./contract.js").DevAppConfig>;
     };
 };
 export type Bardioc = ReturnType<typeof open>;

package/dist/client.js

@@ -92,6 +92,10 @@ function open(port, initial) {
             /** The file contents are transferred to the host and unusable here afterwards. */
             upload: (upload) => call('apps.upload', upload, { transfer: upload.files.map(file => file.content) }),
             launch: (id) => call('apps.launch', { id }),
+            /** The caller's settings of the developer application `id`, as the host holds them. */
+            getConfig: (id) => call('apps.getConfig', { id }),
+            /** Replaces them with the edited document; the host applies the answer at once. */
+            saveConfig: (id, data) => call('apps.saveConfig', { id, data }),
         },
     };
 }

package/dist/contract.d.ts

@@ -122,11 +122,43 @@ export interface OsConfig {
     windowId: string;
     instanceId: string | null;
 }
+/** A setting's value as the configuration service holds it. */
+export type SettingValue = string | number | boolean | null;
 /** What the host tells an app when it connects, and again whenever it changes. */
 export interface Context {
     appId: string;
     host: 'os' | 'dev';
     osConfig: OsConfig;
+    /** The app's own settings, keyed `<group>.<field>` as its manifest declares them. */
+    settings?: Record<string, SettingValue>;
+}
+/** One setting as the configuration service renders it: value, flags and declared metadata. */
+export interface Setting {
+    value: SettingValue;
+    type: string;
+    editable: boolean;
+    hidden: boolean;
+    immutable: boolean;
+    declared: boolean;
+    origin: string;
+    section: string;
+    label?: string;
+    description?: string;
+    unit?: string;
+    enum?: SettingValue[];
+    min?: number;
+    max?: number;
+    step?: number;
+    order?: number;
+    appId?: string;
+}
+/**
+ * A developer's own settings of a developer application: `data` is the document they edit
+ * (keys `apps.<id>.<group>.<field>`, group flags under `<group>.__flags`), `settings` its view.
+ */
+export interface DevAppConfig {
+    data: Record<string, unknown>;
+    settings: Record<string, Setting>;
 }
 export interface IdbEntry<T = unknown> {
     key: string;
@@ -274,6 +306,13 @@ export declare const APP_METHODS: {
     }, z.core.$strict>, {
         windowId: string | null;
     }>;
+    readonly 'apps.getConfig': CallMethod<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+    }, z.core.$strict>, DevAppConfig>;
+    readonly 'apps.saveConfig': CallMethod<z.ZodMiniObject<{
+        id: z.ZodMiniString<string>;
+        data: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>;
+    }, z.core.$strict>, DevAppConfig>;
 };
 /** Methods a host calls on its app. */
 export declare const HOST_METHODS: {

package/dist/contract.js

@@ -103,6 +103,10 @@ const AppRecord = z.strictObject({
     bundleSize: z.optional(count),
     fileCount: z.optional(count),
 });
+const AppConfigSave = z.strictObject({
+    id: text,
+    data: z.record(z.string(), z.unknown()),
+});
 const AppUpload = z.strictObject({
     alias: text,
     name: text,
@@ -138,6 +142,8 @@ export const APP_METHODS = {
     'apps.delete': call(AppId).returns(),
     'apps.upload': call(AppUpload).returns(120_000),
     'apps.launch': call(AppId).returns(),
+    'apps.getConfig': call(AppId).returns(),
+    'apps.saveConfig': call(AppConfigSave).returns(),
 };
 /** Methods a host calls on its app. */
 export const HOST_METHODS = {

package/dist/dev-idb.d.ts

@@ -1,7 +1,7 @@
 import type { AppMethods, IdbEntry, Params } from './contract.js';
 type In<K extends keyof AppMethods> = Params<AppMethods[K]>;
 /** The host's app storage, kept in this browser's IndexedDB while running standalone. */
-export declare function devIdb(appId: string): {
+export declare function devIdb(): {
     get: ({ store, key }: In<"idb.get">) => Promise<IdbEntry<unknown> | null>;
     put: ({ store, key, value }: In<"idb.put">) => Promise<void>;
     delete: ({ store, key }: In<"idb.delete">) => Promise<void>;

package/dist/dev-idb.js

@@ -12,11 +12,11 @@ function open(name) {
 }
 const toEntry = ({ key, value, updatedAt }) => ({ key, value, updatedAt });
 /** The host's app storage, kept in this browser's IndexedDB while running standalone. */
-export function devIdb(appId) {
+export function devIdb() {
     // Opened on first use: most apps never touch their store.
     let db;
     const entries = async (mode) => {
-        db ??= open(`bardioc-dev:${appId}`);
+        db ??= open('bardioc-dev');
         return (await db).transaction(ENTRIES, mode).objectStore(ENTRIES);
     };
     return {

package/dist/dev.d.ts

@@ -2,17 +2,13 @@ import { type HostHandlers } from './serve.js';
 export declare function isInsideIframe(): boolean;
 export declare function isDevStandalone(): boolean;
 export interface DevHostOptions {
-    /** The app's manifest id, handed to the app as `context.appId`. */
-    appId: string;
-    /** The app's ogit/Auth/Application id, sent as `X-App-ID` on scoped calls; defaults to `appId`. */
-    clientId?: string;
     /** Where the dev-auth proxy answers `/rest`. Default: `/rest` on this origin. */
     apiBaseUrl?: string;
 }
 /** The dev host's answers to every app method. */
-export declare function devHandlers({ appId, clientId, apiBaseUrl, }: DevHostOptions): HostHandlers;
+export declare function devHandlers({ apiBaseUrl }?: DevHostOptions): HostHandlers;
 /**
  * Stands in for the host while the app runs standalone in development: `connect()` reaches it
  * the way it reaches the host, and BFF calls go through the dev-auth proxy.
  */
-export declare function installDevHost(options: DevHostOptions): () => void;
+export declare function installDevHost(options?: DevHostOptions): () => void;

package/dist/dev.js

@@ -23,8 +23,8 @@ const unavailable = () => {
     throw new BardiocError('unavailable', 'Installed apps live in the Bardioc host');
 };
 /** The dev host's answers to every app method. */
-export function devHandlers({ appId, clientId = appId, apiBaseUrl = '/rest', }) {
-    const idb = devIdb(appId);
+export function devHandlers({ apiBaseUrl = '/rest' } = {}) {
+    const idb = devIdb();
     const request = async ({ path, method = 'GET', body, contentType, scopeId, scopePolicy }, signal) => {
         if (scopePolicy === 'required' && !scopeId) {
             throw new BardiocError('invalid', 'scopeId is required: a dev session has no instance');
@@ -32,10 +32,9 @@ export function devHandlers({ appId, clientId = appId, apiBaseUrl = '/rest', })
         const headers = new Headers({ 'X-Requested-With': 'XMLHttpRequest' });
         if (contentType && body !== undefined)
             headers.set('Content-Type', contentType);
-        if (scopeId) {
+        // No X-App-ID: a dev app claims no app token and runs on the user's own.
+        if (scopeId)
             headers.set('X-Scope-ID', scopeId);
-            headers.set('X-App-ID', clientId);
-        }
         const encoded = contentType === 'application/json' ? JSON.stringify(body) : body;
         const response = await fetch(`${apiBaseUrl}${path}`, {
             method,
@@ -58,6 +57,16 @@ export function devHandlers({ appId, clientId = appId, apiBaseUrl = '/rest', })
         }
         return () => source.close();
     };
+    // The BFF's own answer, so a standalone app tries the settings the host would hold.
+    const devConfig = async (id, signal, data) => {
+        const layer = (await request({
+            path: `/os/dev/config/apps/${encodeURIComponent(id)}`,
+            method: data ? 'PUT' : 'GET',
+            body: data ? { layer: 'dev', data } : undefined,
+            contentType: data ? 'application/json' : undefined,
+        }, signal));
+        return { data: layer.data ?? {}, settings: layer.settings ?? {} };
+    };
     return {
         'ui.notify': () => undefined,
         'ui.setCommands': () => undefined,
@@ -76,6 +85,8 @@ export function devHandlers({ appId, clientId = appId, apiBaseUrl = '/rest', })
         'apps.delete': unavailable,
         'apps.upload': unavailable,
         'apps.launch': unavailable,
+        'apps.getConfig': ({ id }, signal) => devConfig(id, signal),
+        'apps.saveConfig': ({ id, data }, signal) => devConfig(id, signal, data),
     };
 }
 const DARK = '(prefers-color-scheme: dark)';
@@ -90,9 +101,9 @@ const osConfig = () => ({
  * Stands in for the host while the app runs standalone in development: `connect()` reaches it
  * the way it reaches the host, and BFF calls go through the dev-auth proxy.
  */
-export function installDevHost(options) {
+export function installDevHost(options = {}) {
     const handlers = devHandlers(options);
-    const context = () => ({ appId: options.appId, host: 'dev', osConfig: osConfig() });
+    const context = () => ({ appId: 'dev', host: 'dev', osConfig: osConfig() });
     let connection;
     const stopAccepting = acceptApp({
         source: () => window,

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { connect } from './client.js';
 export type { Bardioc } from './client.js';
 export { BardiocError } from './errors.js';
 export type { ErrorCode } from './errors.js';
-export type { AppRecord, AppUpload, BffRequest, Command, Context, GraphEvent, IdbEntry, InstalledApp, MenuItem, MenuRoot, NotifyLevel, OsConfig, Shortcut, UploadResult, } from './contract.js';
+export type { AppRecord, AppUpload, BffRequest, Command, Context, DevAppConfig, GraphEvent, IdbEntry, InstalledApp, MenuItem, MenuRoot, NotifyLevel, OsConfig, Setting, SettingValue, Shortcut, UploadResult, } from './contract.js';
 export { DEFAULT_WINDOW_SIZE, MANIFEST_FILENAME, WINDOW_SIZES, validateManifest, } from './manifest.js';
 export type { AppManifest, AppManifestRole, AppManifestRules, AppManifestWindowConfig, CustomWindowSize, WindowSizePreset, } from './manifest.js';
 export type { Application, BatchResult, CombinedQueryOptions, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphNodeRaw, GremlinOptions, HistoryEntry, HistoryOptions, InstanceList, MutationOptions, OrgMember, OrgStructure, OrgUnit, QueryOptions, TimeseriesAggregate, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';

package/dist/protocol.d.ts

@@ -1,5 +1,5 @@
 export { APP_METHODS, GRAPH_EVENT_TYPES, HOST_METHODS, PROTOCOL_VERSION, graphEventFilter, } from './contract.js';
-export type { AppMethods, AppRecord, AppUpload, BffRequest, CallMethod, Command, Context, GraphEvent, HostEvents, HostMethods, IdbEntry, InstalledApp, MenuItem, MenuRoot, Method, NotifyLevel, OsConfig, Params, Result, Shortcut, StreamMethod, UploadResult, } from './contract.js';
+export type { AppMethods, AppRecord, AppUpload, BffRequest, CallMethod, Command, Context, DevAppConfig, GraphEvent, HostEvents, HostMethods, IdbEntry, InstalledApp, MenuItem, MenuRoot, Method, NotifyLevel, OsConfig, Params, Result, Setting, SettingValue, Shortcut, StreamMethod, UploadResult, } from './contract.js';
 export { BardiocError } from './errors.js';
 export type { ErrorCode, WireError } from './errors.js';
 export { acceptApp, serve } from './serve.js';

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import { type DependencyList, type ReactNode } from 'react';
 import { type Bardioc } from './client.js';
-import type { Command, GraphEvent, MenuRoot, NotifyLevel, OsConfig } from './contract.js';
+import type { Command, GraphEvent, MenuRoot, NotifyLevel, OsConfig, SettingValue } from './contract.js';
 export interface AppSdkProviderProps {
     children: ReactNode;
     /** Apply theme, language and size to this document. Default: `true`. */
@@ -21,6 +21,8 @@ export declare function useCommandMenu(commands: AppCommand[], menu: MenuRoot[]
 export declare function useActiveTab(activeTab: string | null): void;
 /** The host's current theme, language and size. */
 export declare function useOsConfig(): OsConfig;
+/** The app's own settings, keyed `<group>.<field>`; follows every change the host pushes. */
+export declare function useSettings(): Record<string, SettingValue>;
 /** Streams graph events of `types` while mounted; `handler` may change without resubscribing. */
 export declare function useGraphEvents({ types }: {
     types: string[];

package/dist/react.js

@@ -102,6 +102,17 @@ export function useOsConfig() {
     }, [bardioc]);
     return osConfig;
 }
+/** The app's own settings, keyed `<group>.<field>`; follows every change the host pushes. */
+export function useSettings() {
+    const bardioc = useSdk();
+    const [settings, setSettings] = useState(bardioc.context.settings ?? NO_SETTINGS);
+    useEffect(() => {
+        setSettings(bardioc.context.settings ?? NO_SETTINGS);
+        return bardioc.onContextChange(context => setSettings(context.settings ?? NO_SETTINGS));
+    }, [bardioc]);
+    return settings;
+}
+const NO_SETTINGS = {};
 /** Streams graph events of `types` while mounted; `handler` may change without resubscribing. */
 export function useGraphEvents({ types }, handler, deps = []) {
     const { events } = useSdk();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bardioc/app-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "SDK for building apps for Bardioc",
   "license": "MIT",
   "private": false,