@bardioc/app-sdk 0.4.8 → 0.4.10

package/README.md

@@ -105,7 +105,7 @@ export default defineConfig({
 });
 ```
 
-Handles dev base path, port config, host session proxy routes, optional Cloudflare tunnel, platform fonts, and manifest validation on build.
+Handles dev base path, port config, host session proxy routes, platform fonts, and manifest validation on build.
 
 ### Platform fonts
 
@@ -118,7 +118,7 @@ The Bardioc platform guarantees a stable font endpoint wherever an app runs —
 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.
+- **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.
 
@@ -131,7 +131,16 @@ Standalone local development is host-backed only.
 
 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.
 
-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.
+Dev servers that cannot host the Vite plugin (angular, nextjs) run the same proxy as a standalone server:
+
+```javascript
+import { startDevAuthProxy } from '@bardioc/app-sdk/dev-proxy';
+
+// Reads DEV_SECRET / API_BASE_URL from the project's .env files; resolves to null when unset.
+await startDevAuthProxy({ projectDir: process.cwd(), port: 3105 });
+```
+
+Point the app at it with `installDevBridge({ apiBaseUrl: 'http://127.0.0.1:3105/rest' })`.
 
 ## React hooks
 
@@ -199,14 +208,34 @@ 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',
+});
 ```
 
-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`.
+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.
 

package/dist/dev-auth-env.d.ts

@@ -0,0 +1,15 @@
+export interface DevAuthEnv {
+    devSecret?: string;
+    apiBaseUrl?: string;
+}
+export interface ResolveDevAuthEnvOptions {
+    /** Directory holding the `.env` files (Vite's `envDir`, or the app root). */
+    envDir: string;
+    /** Vite mode, when the mode-specific files should be read too. */
+    mode?: string;
+}
+/**
+ * Resolves the standalone dev-auth contract (`DEV_SECRET` + `API_BASE_URL`) the same way
+ * Vite loads env: dotenv files first, `process.env` last so a shell value always wins.
+ */
+export declare function resolveDevAuthEnv(options: ResolveDevAuthEnvOptions): DevAuthEnv;

package/dist/dev-auth-env.js

@@ -0,0 +1,33 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { readDotEnvFile } from './dot-env.js';
+/**
+ * Resolves the standalone dev-auth contract (`DEV_SECRET` + `API_BASE_URL`) the same way
+ * Vite loads env: dotenv files first, `process.env` last so a shell value always wins.
+ */
+export function resolveDevAuthEnv(options) {
+    const mode = options.mode?.trim();
+    const env = {};
+    for (const fileName of [
+        '.env',
+        '.env.local',
+        mode ? `.env.${mode}` : null,
+        mode ? `.env.${mode}.local` : null,
+    ]) {
+        if (!fileName)
+            continue;
+        const filePath = resolve(options.envDir, fileName);
+        if (existsSync(filePath)) {
+            Object.assign(env, readDotEnvFile(filePath));
+        }
+    }
+    for (const [key, value] of Object.entries(process.env)) {
+        if (typeof value === 'string') {
+            env[key] = value;
+        }
+    }
+    return {
+        devSecret: env.DEV_SECRET?.trim(),
+        apiBaseUrl: env.API_BASE_URL?.trim().replace(/\/$/, ''),
+    };
+}

package/dist/dev-proxy.d.ts

@@ -1,4 +1,4 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 export interface DevAuthProxyOptions {
     /** Upstream BFF base URL (e.g. `https://your-bff-host`). */
     apiBaseUrl: string;
@@ -9,9 +9,30 @@ export interface DevAuthProxyOptions {
 }
 interface SendJsonOptions {
     allowOrigin?: string;
+    requestOrigin?: string;
 }
 export declare function readRequestBody(req: IncomingMessage): Promise<Buffer>;
-export declare function applyCors(res: ServerResponse, allowOrigin?: string): void;
+export declare function applyCors(res: ServerResponse, allowOrigin?: string, requestOrigin?: string): void;
 export declare function sendJson(res: ServerResponse, status: number, body: unknown, options?: SendJsonOptions): void;
 export declare function createDevAuthProxyHandler(options: DevAuthProxyOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface StartDevAuthProxyOptions {
+    /** Port the proxy listens on. Templates use the app port + 100. */
+    port: number;
+    /** Directory the `.env` files are read from. Defaults to `process.cwd()`. */
+    projectDir?: string;
+    /** Interface to bind. Defaults to `127.0.0.1`. */
+    host?: string;
+    /** CORS origin for the app dev server. Defaults to `*` (echoed back per request). */
+    allowOrigin?: string;
+    /** Explicit upstream, skips env resolution when both this and `devSecret` are given. */
+    apiBaseUrl?: string;
+    devSecret?: string;
+    /** Mode-specific `.env.<mode>` files to include. */
+    mode?: string;
+}
+/**
+ * Starts a standalone dev-auth proxy for dev servers that cannot use the Vite plugin
+ * (angular, nextjs). Resolves to `null` when `DEV_SECRET` / `API_BASE_URL` are missing.
+ */
+export declare function startDevAuthProxy(options: StartDevAuthProxyOptions): Promise<Server | null>;
 export {};

package/dist/dev-proxy.js

@@ -1,3 +1,5 @@
+import { createServer } from 'node:http';
+import { resolveDevAuthEnv } from './dev-auth-env.js';
 export async function readRequestBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -6,16 +8,23 @@ export async function readRequestBody(req) {
         req.on('error', reject);
     });
 }
-export function applyCors(res, allowOrigin) {
+export function applyCors(res, allowOrigin, requestOrigin) {
     if (!allowOrigin) {
         return;
     }
-    res.setHeader('Access-Control-Allow-Origin', allowOrigin);
+    // The dev bridge fetches with `credentials: 'include'`, which a browser refuses to pair
+    // with a wildcard origin — echo the caller's origin instead and allow credentials.
+    const credentialed = allowOrigin === '*' && !!requestOrigin;
+    res.setHeader('Access-Control-Allow-Origin', credentialed ? requestOrigin : allowOrigin);
+    if (credentialed) {
+        res.setHeader('Access-Control-Allow-Credentials', 'true');
+        res.setHeader('Vary', 'Origin');
+    }
     res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Scope-ID, X-Requested-With');
 }
 export function sendJson(res, status, body, options = {}) {
-    applyCors(res, options.allowOrigin);
+    applyCors(res, options.allowOrigin, options.requestOrigin);
     res.statusCode = status;
     res.setHeader('Content-Type', 'application/json');
     res.setHeader('Cache-Control', 'no-store');
@@ -46,14 +55,15 @@ export function createDevAuthProxyHandler(options) {
     const { devSecret, allowOrigin } = options;
     return async (req, res) => {
         const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        const requestOrigin = typeof req.headers.origin === 'string' ? req.headers.origin : undefined;
         if (req.method === 'OPTIONS') {
-            applyCors(res, allowOrigin);
+            applyCors(res, allowOrigin, requestOrigin);
             res.statusCode = 204;
             res.end();
             return;
         }
         if (!url.pathname.startsWith('/rest/')) {
-            sendJson(res, 404, { error: 'not_found' }, { allowOrigin });
+            sendJson(res, 404, { error: 'not_found' }, { allowOrigin, requestOrigin });
             return;
         }
         const upstreamPath = url.pathname.slice('/rest'.length) + url.search;
@@ -95,7 +105,7 @@ export function createDevAuthProxyHandler(options) {
             body = await readRequestBody(req);
         }
         catch {
-            sendJson(res, 400, { error: 'invalid_body' }, { allowOrigin });
+            sendJson(res, 400, { error: 'invalid_body' }, { allowOrigin, requestOrigin });
             return;
         }
         try {
@@ -105,7 +115,7 @@ export function createDevAuthProxyHandler(options) {
                 body: body.length > 0 ? new Uint8Array(body) : undefined,
                 cache: 'no-store',
             });
-            applyCors(res, allowOrigin);
+            applyCors(res, allowOrigin, requestOrigin);
             res.statusCode = upstreamRes.status;
             res.setHeader('Cache-Control', 'no-store');
             const upstreamContentType = upstreamRes.headers.get('content-type');
@@ -116,7 +126,45 @@ export function createDevAuthProxyHandler(options) {
             res.end(responseBody);
         }
         catch {
-            sendJson(res, 502, { error: 'upstream_unavailable' }, { allowOrigin });
+            sendJson(res, 502, { error: 'upstream_unavailable' }, { allowOrigin, requestOrigin });
         }
     };
 }
+/**
+ * Starts a standalone dev-auth proxy for dev servers that cannot use the Vite plugin
+ * (angular, nextjs). Resolves to `null` when `DEV_SECRET` / `API_BASE_URL` are missing.
+ */
+export async function startDevAuthProxy(options) {
+    const { port, host = '127.0.0.1', allowOrigin = '*' } = options;
+    const env = options.apiBaseUrl && options.devSecret
+        ? { apiBaseUrl: options.apiBaseUrl, devSecret: options.devSecret }
+        : resolveDevAuthEnv({ envDir: options.projectDir ?? process.cwd(), mode: options.mode });
+    if (!env.apiBaseUrl || !env.devSecret) {
+        process.stderr.write('[bardioc-dev-auth] DEV_SECRET and API_BASE_URL are required for dev auth — proxy disabled\n');
+        return null;
+    }
+    const handler = createDevAuthProxyHandler({
+        apiBaseUrl: env.apiBaseUrl,
+        devSecret: env.devSecret,
+        allowOrigin,
+    });
+    const server = createServer((req, res) => {
+        void handler(req, res);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const boundPort = typeof address === 'object' && address ? address.port : port;
+    process.stdout.write(`[bardioc-dev-auth] proxying /rest/* → ${env.apiBaseUrl} on http://${host}:${boundPort}/rest\n`);
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.once(signal, () => {
+            server.close(() => process.exit(0));
+        });
+    }
+    return server;
+}

package/dist/index.d.ts

@@ -1,9 +1,8 @@
 export { createHostBridge } from './host-bridge.js';
 export { DEFAULT_WINDOW_SIZE, MANIFEST_FILENAME, WINDOW_SIZES, validateManifest, } from './manifest.js';
 export type { AppManifest, AppManifestPermission, AppManifestWindowConfig, CustomWindowSize, WindowSizePreset, } from './manifest.js';
-export { useGraphEvents, useOsConfig } from './react.js';
 export { SDK_CONTRACT_MATRIX, getRequiredPermissionForSdkMessage } from './contract-matrix.js';
 export { ALLOWED_KERNEL_MESSAGES, SDK_MSG } from './protocol.js';
 export type { SdkMessageType } from './protocol.js';
 export { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from './errors.js';
-export type { Application, BatchResult, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, EventSubscribeRequest, EventSubscribeResponse, EventUnsubscribeRequest, EventsApi, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphEvent, GraphEventPushPayload, GraphEventType, GraphNodeRaw, GraphTransport, GremlinOptions, HistoryEntry, HistoryOptions, HostBridge, HostBridgeConfig, InstanceList, MutationOptions, NotifyLevel, OrgMember, OrgStructure, OrgUnit, OsConfig, OsRequestOptions, OsTransport, QueryOptions, SdkCommandDefinition, SdkCommandHandler, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbEntry, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkIdbStore, SdkInitResponse, SdkKernelProxyPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorage, SdkStorageDeletePayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransport, SdkTransportPayload, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';
+export type { Application, BatchResult, CombinedQueryOptions, Configuration, CreateMemberInput, CreateUnitInput, DeleteOptions, EventSubscribeRequest, EventSubscribeResponse, EventUnsubscribeRequest, EventsApi, FileEntry, GetNodeOptions, GraphEdgeRaw, GraphEvent, GraphEventPushPayload, GraphEventType, GraphNodeRaw, GraphTransport, GremlinOptions, HistoryEntry, HistoryOptions, HostBridge, HostBridgeConfig, InstanceList, MutationOptions, NotifyLevel, OrgMember, OrgStructure, OrgUnit, OsConfig, OsRequestOptions, OsTransport, QueryOptions, SdkCommandDefinition, SdkCommandHandler, SdkCommandInvokePayload, SdkIdbDeletePayload, SdkIdbEntry, SdkIdbGetPayload, SdkIdbPutPayload, SdkIdbQueryPayload, SdkIdbStore, SdkInitResponse, SdkKernelProxyPayload, SdkMenuItem, SdkMenuRoot, SdkMessage, SdkNotifyPayload, SdkResponse, SdkSetActiveTabPayload, SdkSetCommandsPayload, SdkSetMenuPayload, SdkShortcutEventPayload, SdkStorage, SdkStorageDeletePayload, SdkStorageGetPayload, SdkStorageSetPayload, SdkTransport, SdkTransportPayload, TimeseriesAggregate, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions, UpdateMemberInput, UpdateUnitInput, UserProfile, } from './types.js';

package/dist/index.js

@@ -1,6 +1,5 @@
 export { createHostBridge } from './host-bridge.js';
 export { DEFAULT_WINDOW_SIZE, MANIFEST_FILENAME, WINDOW_SIZES, validateManifest, } from './manifest.js';
-export { useGraphEvents, useOsConfig } from './react.js';
 export { SDK_CONTRACT_MATRIX, getRequiredPermissionForSdkMessage } from './contract-matrix.js';
 export { ALLOWED_KERNEL_MESSAGES, SDK_MSG } from './protocol.js';
 export { EntityNotFoundError, NetworkError, PermissionError, SdkError, TimeoutError, ValidationError, } from './errors.js';

package/dist/transports/graph-transport.d.ts

@@ -1,4 +1,4 @@
-import type { BatchResult, DeleteOptions, GetNodeOptions, GraphEdgeRaw, GraphNodeRaw, GremlinOptions, HistoryEntry, HistoryOptions, MutationOptions, QueryOptions, SdkTransportPayload, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions } from '../types.js';
+import type { BatchResult, CombinedQueryOptions, DeleteOptions, GetNodeOptions, GraphEdgeRaw, GraphNodeRaw, GremlinOptions, HistoryEntry, HistoryOptions, MutationOptions, QueryOptions, SdkTransportPayload, TimeseriesHistory, TimeseriesHistoryOptions, TimeseriesOptions, TimeseriesQueryOptions, TimeseriesValue, TransportScopeOptions } from '../types.js';
 /** Graph transport class providing graph database operations */
 export declare class GraphTransport {
     private _request;
@@ -64,20 +64,24 @@ export declare class GraphTransport {
      */
     gremlin<T = unknown>(rootId: string, query: string, options?: GremlinOptions): Promise<T[]>;
     /**
-     * Execute combined query (Lucene + Gremlin in single call)
-     * Returns raw results (structure varies by query)
+     * Execute combined query: Elasticsearch selects the start vertices, the Gremlin traversal
+     * runs from their IDs. Returns raw results (structure varies by the traversal).
+     *
+     * The result is one flat set for all start vertices — it carries no marker for which start
+     * vertex a row came from. Label and select in the traversal when attribution is needed.
      *
      * @example
-     * const results = await graph.combined(
-     *   'ogit/_type:ogit/Person AND name:Test',
-     *   { limit: 50 }
+     * const speeches = await graph.combined(
+     *   '+(ogit\\/_type: "ogit/Politics/AgendaItem")',
+     *   "inE().outV().has('ogit/_type', 'ogit/Politics/Discussion')",
+     *   { limit: 1000 }
      * );
      *
-     * @throws {ValidationError} if query syntax is invalid
+     * @throws {ValidationError} if either query is invalid
      * @throws {NetworkError} on HTTP errors
      * @throws {TimeoutError} on request timeout
      */
-    combined<T = unknown>(query: string, options?: QueryOptions): Promise<T[]>;
+    combined<T = unknown>(elasticsearchQuery: string, gremlinQuery: string, options?: CombinedQueryOptions): Promise<T[]>;
     /**
      * Create new graph node
      *
@@ -165,7 +169,11 @@ export declare class GraphTransport {
      */
     timeseries: {
         /**
-         * Get time series values
+         * Get time series values.
+         *
+         * `withIds` pulls further time series into the same request and `aggregate` combines the
+         * values sharing a timestamp. Entries carry only timestamp and value, so a multi-ID request
+         * yields one merged series — read a single ID per request when values must stay attributable.
          *
          * @throws {EntityNotFoundError} if time series doesn't exist
          * @throws {NetworkError} on HTTP errors
@@ -189,6 +197,15 @@ export declare class GraphTransport {
          * @throws {TimeoutError} on request timeout
          */
         query: (options: TimeseriesQueryOptions) => Promise<TimeseriesValue[]>;
+        /**
+         * Get every value ever written for one timestamp of a time series.
+         * Keyed by timestamp, so a single-timestamp request returns a single-entry map.
+         *
+         * @throws {EntityNotFoundError} if time series doesn't exist
+         * @throws {NetworkError} on HTTP errors
+         * @throws {TimeoutError} on request timeout
+         */
+        history: (id: string, timestamp: number, options?: TimeseriesHistoryOptions) => Promise<TimeseriesHistory>;
     };
     /**
      * Content/blob operations

package/dist/transports/graph-transport.js

@@ -232,38 +232,40 @@ export class GraphTransport {
         }
     }
     /**
-     * Execute combined query (Lucene + Gremlin in single call)
-     * Returns raw results (structure varies by query)
+     * Execute combined query: Elasticsearch selects the start vertices, the Gremlin traversal
+     * runs from their IDs. Returns raw results (structure varies by the traversal).
+     *
+     * The result is one flat set for all start vertices — it carries no marker for which start
+     * vertex a row came from. Label and select in the traversal when attribution is needed.
      *
      * @example
-     * const results = await graph.combined(
-     *   'ogit/_type:ogit/Person AND name:Test',
-     *   { limit: 50 }
+     * const speeches = await graph.combined(
+     *   '+(ogit\\/_type: "ogit/Politics/AgendaItem")',
+     *   "inE().outV().has('ogit/_type', 'ogit/Politics/Discussion')",
+     *   { limit: 1000 }
      * );
      *
-     * @throws {ValidationError} if query syntax is invalid
+     * @throws {ValidationError} if either query is invalid
      * @throws {NetworkError} on HTTP errors
      * @throws {TimeoutError} on request timeout
      */
-    async combined(query, options) {
+    async combined(elasticsearchQuery, gremlinQuery, options) {
         try {
-            const qs = buildQueryString({
-                query,
-                limit: options?.limit,
-                offset: options?.offset,
-                fields: options?.fields,
-                includeDeleted: options?.includeDeleted,
-                listMeta: options?.listMeta,
-                order: options?.order,
-            });
-            this.log('combined', { path: `${GRAPH_BASE}/query/combined${qs}`, query });
+            const path = `${GRAPH_BASE}/query/combined`;
+            this.log('combined', { path, elasticsearchQuery, gremlinQuery, limit: options?.limit });
             return await this._request(this.withScope({
-                path: `${GRAPH_BASE}/query/combined${qs}`,
-                method: 'GET',
+                path,
+                method: 'POST',
+                body: {
+                    elasticsearch_query: elasticsearchQuery,
+                    gremlin_query: gremlinQuery,
+                    ...(options?.limit === undefined ? {} : { limit: options.limit }),
+                },
+                contentType: 'application/json',
             }, options));
         }
         catch (error) {
-            throw parseError(error, 'graph.combined', { query, ...options });
+            throw parseError(error, 'graph.combined', { elasticsearchQuery, gremlinQuery, ...options });
         }
     }
     /**
@@ -450,7 +452,11 @@ export class GraphTransport {
      */
     timeseries = {
         /**
-         * Get time series values
+         * Get time series values.
+         *
+         * `withIds` pulls further time series into the same request and `aggregate` combines the
+         * values sharing a timestamp. Entries carry only timestamp and value, so a multi-ID request
+         * yields one merged series — read a single ID per request when values must stay attributable.
          *
          * @throws {EntityNotFoundError} if time series doesn't exist
          * @throws {NetworkError} on HTTP errors
@@ -463,6 +469,9 @@ export class GraphTransport {
                     to: options?.to,
                     limit: options?.limit,
                     order: options?.order,
+                    with: options?.withIds?.join(','),
+                    aggregate: options?.aggregate,
+                    includeDeleted: options?.includeDeleted,
                 });
                 return await this._request(this.withScope({
                     path: `${GRAPH_BASE}/${encodeURIComponent(id)}/values${qs}`,
@@ -520,6 +529,29 @@ export class GraphTransport {
                 throw parseError(error, 'graph.timeseries.query', { ...options });
             }
         },
+        /**
+         * Get every value ever written for one timestamp of a time series.
+         * Keyed by timestamp, so a single-timestamp request returns a single-entry map.
+         *
+         * @throws {EntityNotFoundError} if time series doesn't exist
+         * @throws {NetworkError} on HTTP errors
+         * @throws {TimeoutError} on request timeout
+         */
+        history: async (id, timestamp, options) => {
+            try {
+                const qs = buildQueryString({
+                    timestamp,
+                    includeDeleted: options?.includeDeleted,
+                });
+                return await this._request(this.withScope({
+                    path: `${GRAPH_BASE}/${encodeURIComponent(id)}/values/history${qs}`,
+                    method: 'GET',
+                }, options));
+            }
+            catch (error) {
+                throw parseError(error, 'graph.timeseries.history', { id, timestamp, ...options });
+            }
+        },
     };
     /**
      * Content/blob operations

package/dist/types.d.ts

@@ -231,6 +231,10 @@ export interface QueryOptions extends TransportScopeOptions {
     listMeta?: boolean;
     order?: string;
 }
+export interface CombinedQueryOptions extends TransportScopeOptions {
+    /** Cap on the vertices the Elasticsearch stage feeds into the traversal. */
+    limit?: number;
+}
 export interface GremlinOptions extends TransportScopeOptions {
     fields?: string;
     includeDeleted?: boolean;
@@ -259,16 +263,26 @@ export interface TimeseriesValue {
     timestamp: number;
     value: unknown;
 }
+export type TimeseriesAggregate = 'avg' | 'min' | 'max' | 'sum' | 'none';
 export interface TimeseriesOptions extends TransportScopeOptions {
     from?: number | string;
     to?: number | string;
     limit?: number;
     order?: 'asc' | 'desc';
+    /** Further time series merged into the same request (sent as `with`). */
+    withIds?: string[];
+    /** How values sharing a timestamp are combined across the requested series. */
+    aggregate?: TimeseriesAggregate;
+    includeDeleted?: boolean;
 }
 export interface TimeseriesQueryOptions extends TimeseriesOptions {
     ids?: string[];
-    aggregate?: string;
 }
+export interface TimeseriesHistoryOptions extends TransportScopeOptions {
+    includeDeleted?: boolean;
+}
+/** Values ever written for a timestamp, keyed by that timestamp in ms. */
+export type TimeseriesHistory = Record<string, unknown>;
 export interface BatchResult {
     succeeded: string[];
     failed: Array<{

package/dist/vite.js

@@ -1,95 +1,17 @@
 /** 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 { resolveDevAuthEnv } from './dev-auth-env.js';
 import { createDevAuthProxyHandler } from './dev-proxy.js';
-import { readDotEnvFile } from './dot-env.js';
 import { MANIFEST_FILENAME, validateManifest } from './manifest.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 () => {
+            server.httpServer?.on('listening', () => {
                 const manifestPath = resolve(process.cwd(), 'public', MANIFEST_FILENAME);
                 if (!existsSync(manifestPath)) {
                     console.warn(`[bardioc] public/${MANIFEST_FILENAME} not found`);
@@ -103,26 +25,10 @@ function devProxy(opts) {
                     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]   Live URL: https://${tunnelHost}`);
-                }
-                else {
-                    console.log(`[bardioc] Dev server ready: http://localhost:${port}`);
-                    console.log(`[bardioc] For standalone dev auth, set DEV_SECRET and API_BASE_URL in .env.`);
-                    console.log(`[bardioc]   App Name: ${manifestId}`);
-                    console.log(`[bardioc]   URL: http://localhost:${port}`);
-                }
-            });
-            server.httpServer?.on('close', () => {
-                tunnelProcess?.kill();
+                console.log(`[bardioc] Dev server ready: http://localhost:${port}`);
+                console.log(`[bardioc] For standalone dev auth, set DEV_SECRET and API_BASE_URL in .env.`);
+                console.log(`[bardioc]   App Name: ${opts.appName || manifest.id}`);
+                console.log(`[bardioc]   URL: http://localhost:${port}`);
             });
         },
     };
@@ -217,33 +123,6 @@ function manifestCheck() {
         },
     };
 }
-function readRuntimeEnv(server) {
-    const envDir = server.config.envDir ?? server.config.root;
-    const mode = server.config.mode?.trim();
-    const env = {};
-    for (const fileName of [
-        '.env',
-        '.env.local',
-        mode ? `.env.${mode}` : null,
-        mode ? `.env.${mode}.local` : null,
-    ]) {
-        if (!fileName)
-            continue;
-        const filePath = resolve(envDir, fileName);
-        if (existsSync(filePath)) {
-            Object.assign(env, readDotEnvFile(filePath));
-        }
-    }
-    for (const [key, value] of Object.entries(process.env)) {
-        if (typeof value === 'string') {
-            env[key] = value;
-        }
-    }
-    return {
-        DEV_SECRET: env.DEV_SECRET?.trim(),
-        API_BASE_URL: env.API_BASE_URL?.trim().replace(/\/$/, ''),
-    };
-}
 export function bardiocDevAuth(options) {
     let proxyOptions = options.proxy ?? null;
     return {
@@ -252,14 +131,17 @@ export function bardiocDevAuth(options) {
         enforce: 'pre',
         configureServer(server) {
             if (!proxyOptions) {
-                const env = readRuntimeEnv(server);
-                if (!env.DEV_SECRET || !env.API_BASE_URL) {
+                const env = resolveDevAuthEnv({
+                    envDir: server.config.envDir ?? server.config.root,
+                    mode: server.config.mode,
+                });
+                if (!env.devSecret || !env.apiBaseUrl) {
                     server.config.logger.warn(`[bardioc-dev-auth] DEV_SECRET and API_BASE_URL are required for dev auth — disabled for appName="${options.appName}".`);
                     return;
                 }
                 proxyOptions = {
-                    apiBaseUrl: env.API_BASE_URL,
-                    devSecret: env.DEV_SECRET,
+                    apiBaseUrl: env.apiBaseUrl,
+                    devSecret: env.devSecret,
                 };
             }
             const handler = createDevAuthProxyHandler(proxyOptions);

package/package.json

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