mindoodb-app-sdk 0.0.4

package/dist/types-BGdIfp-D.d.ts

@@ -0,0 +1,372 @@
+import { MindooDBAppBooleanExpression, MindooDBAppExpression, MindooDBAppViewSortDirection, MindooDBAppViewTotalMode, MindooDBAppViewDefinition, MindooDBAppViewPageRequest, MindooDBAppViewPageResult, MindooDBAppViewExpansionState, MindooDBAppViewRow, MindooDBAppViewLookupByPath, MindooDBAppViewCategoryChildrenPageRequest } from 'mindoodb-view-language';
+
+/** Launch target used by the Administrator when opening an app. */
+type MindooDBAppRuntime = "iframe" | "window";
+/** Theme mode currently active in the Administrator host UI. */
+type MindooDBAppThemeMode = "light" | "dark";
+/** Host theme snapshot exposed to running apps. */
+interface MindooDBAppHostTheme {
+    mode: MindooDBAppThemeMode;
+    preset: string;
+}
+/** Iframe viewport dimensions reported by the Haven host. */
+interface MindooDBAppViewport {
+    width: number;
+    height: number;
+}
+/** Saved categorization mode for Haven-managed view mappings delivered at launch time. */
+type MindooDBAppConfiguredViewCategorizationStyle = "document_then_category" | "category_then_document";
+/** Preferred preview layout for a Haven-managed view mapping. */
+type MindooDBAppConfiguredViewPreviewMode = "tree" | "table";
+/** Column role used by Haven-managed view mappings. */
+type MindooDBAppConfiguredViewColumnRole = "category" | "sort" | "display" | "total";
+/** Filter authoring mode used by Haven-managed view mappings. */
+type MindooDBAppConfiguredViewFilterMode = "rules" | "formula";
+/** Rule match mode used by visual-rule filters. */
+type MindooDBAppConfiguredViewRuleMatchMode = "all" | "any";
+/** Visual-rule operator supported by Haven-managed view mappings. */
+type MindooDBAppConfiguredViewRuleOperator = "eq" | "neq" | "contains" | "notContains" | "gt" | "gte" | "lt" | "lte" | "exists" | "notExists";
+/** Field/formula authoring modes for Haven-managed view columns. */
+type MindooDBAppConfiguredViewExpressionMode = "field" | "formula";
+/** One visual filter rule inside a Haven-managed view mapping. */
+interface MindooDBAppConfiguredViewFilterRule {
+    id: string;
+    field: string;
+    operator: MindooDBAppConfiguredViewRuleOperator;
+    value?: string;
+}
+/** Field-based value expression used by Haven-managed view mappings. */
+interface MindooDBAppConfiguredViewFieldExpression {
+    mode: "field";
+    field: string;
+}
+/** Formula-based value expression used by Haven-managed view mappings. */
+interface MindooDBAppConfiguredViewFormulaExpression {
+    mode: "formula";
+    expression: MindooDBAppExpression;
+}
+/** Column expression authoring shape used by Haven-managed view mappings. */
+type MindooDBAppConfiguredViewValueExpression = MindooDBAppConfiguredViewFieldExpression | MindooDBAppConfiguredViewFormulaExpression;
+/** Rule-based filter stored by Haven for app-owned view mappings. */
+interface MindooDBAppConfiguredViewRuleFilterDefinition {
+    mode: "rules";
+    match: MindooDBAppConfiguredViewRuleMatchMode;
+    rules: MindooDBAppConfiguredViewFilterRule[];
+}
+/** Formula-based filter stored by Haven for app-owned view mappings. */
+interface MindooDBAppConfiguredViewFormulaFilterDefinition {
+    mode: "formula";
+    expression: MindooDBAppBooleanExpression;
+}
+/** Full filter authoring shape stored for Haven-managed app view mappings. */
+type MindooDBAppConfiguredViewFilterDefinition = MindooDBAppConfiguredViewRuleFilterDefinition | MindooDBAppConfiguredViewFormulaFilterDefinition;
+/** Column definition stored for a Haven-managed app view mapping. */
+interface MindooDBAppConfiguredViewColumn {
+    id: string;
+    title: string;
+    name: string;
+    role: MindooDBAppConfiguredViewColumnRole;
+    expression: MindooDBAppConfiguredViewValueExpression;
+    sorting: MindooDBAppViewSortDirection;
+    totalMode: MindooDBAppViewTotalMode;
+    hidden: boolean;
+}
+/** One resolved source binding for an app-owned Haven view mapping. */
+interface MindooDBAppResolvedViewSource {
+    origin: string;
+    databaseId: string;
+    title: string;
+    targetMode: "local" | "server";
+    connectionId?: string;
+    tenantId: string;
+    databaseName: string;
+}
+/** Full Haven-managed view mapping delivered to the running application at launch time. */
+interface MindooDBAppResolvedViewDefinition {
+    id: string;
+    description?: string;
+    categorizationStyle: MindooDBAppConfiguredViewCategorizationStyle;
+    previewMode: MindooDBAppConfiguredViewPreviewMode;
+    sources: MindooDBAppResolvedViewSource[];
+    filter: MindooDBAppConfiguredViewFilterDefinition;
+    columns: MindooDBAppConfiguredViewColumn[];
+}
+/** Permission/capability flags exposed for a database binding inside the app session. */
+type MindooDBAppCapability = "read" | "create" | "update" | "delete" | "history" | "attachments" | "views";
+/** Metadata about the current app launch supplied by the Administrator host. */
+interface MindooDBAppLaunchContext {
+    appId: string;
+    appInstanceId: string;
+    appVersion?: string;
+    launchId: string;
+    runtime: MindooDBAppRuntime;
+    theme: MindooDBAppHostTheme;
+    viewport: MindooDBAppViewport | null;
+    tenantId?: string;
+    preferredDatabaseId?: string;
+    user: {
+        id: string;
+        username: string;
+    };
+    launchParameters: Record<string, string>;
+    views: MindooDBAppResolvedViewDefinition[];
+}
+/** Attachment metadata returned by the attachment APIs. */
+interface MindooDBAppAttachmentInfo {
+    attachmentId: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+}
+/** Database entry visible to the app during launch and database listing. */
+interface MindooDBAppDatabaseInfo {
+    id: string;
+    title: string;
+    role?: string;
+    capabilities: MindooDBAppCapability[];
+}
+/** Lightweight document row returned by list operations. */
+interface MindooDBAppDocumentSummary {
+    id: string;
+    data?: Record<string, unknown>;
+    attachmentCount?: number;
+    updatedAt?: string;
+}
+/** Fully loaded document returned by `get()`, `create()`, or `update()`. */
+interface MindooDBAppDocument {
+    id: string;
+    data: Record<string, unknown>;
+    attachments?: MindooDBAppAttachmentInfo[];
+    updatedAt?: string;
+}
+/** One entry in the document history timeline. */
+interface MindooDBAppDocumentHistoryEntry {
+    timestamp: number;
+    publicKey: string;
+    publicKeyFingerprint?: string;
+    identityLabel?: string;
+    isDeleted: boolean;
+    isCurrent: boolean;
+    summary?: string;
+}
+/** Historical snapshot returned for a document at a specific timestamp. */
+interface MindooDBAppHistoricalDocument {
+    id: string;
+    timestamp: number;
+    state: "missing" | "deleted" | "exists";
+    data: Record<string, unknown> | null;
+}
+/** Query options for paging through documents in a database. */
+interface MindooDBAppDocumentListQuery {
+    limit?: number;
+    cursor?: string | null;
+    fields?: string[];
+    filter?: Record<string, unknown>;
+}
+/** Paged result returned by `documents.list()`. */
+interface MindooDBAppDocumentListResult {
+    items: MindooDBAppDocumentSummary[];
+    nextCursor: string | null;
+}
+/** Payload used when creating a new document. */
+interface MindooDBAppCreateDocumentInput {
+    data: Record<string, unknown>;
+    /** Optional named document key. Defaults to `"default"` when omitted. */
+    decryptionKeyId?: string;
+}
+/** Patch payload used when updating an existing document. */
+interface MindooDBAppUpdateDocumentInput {
+    data: Record<string, unknown>;
+}
+/** Query used for history lookups at a specific timestamp. */
+interface MindooDBAppHistoryQuery {
+    timestamp: number;
+}
+/** Optional parameters for establishing the app bridge connection. */
+interface MindooDBAppBridgeConnectOptions {
+    launchId?: string;
+    targetOrigin?: string;
+    connectTimeoutMs?: number;
+}
+/** Initial postMessage handshake sent from the app to the Administrator. */
+interface MindooDBAppBridgeConnectMessage {
+    protocol: "mindoodb-app-bridge";
+    type: "mindoodb-app:connect";
+    launchId: string;
+}
+/** Handshake acknowledgement returned by the Administrator host. */
+interface MindooDBAppBridgeConnectedMessage {
+    protocol: "mindoodb-app-bridge";
+    type: "mindoodb-app:connected";
+}
+/** Structured error payload transported over bridge RPC or stream messages. */
+interface MindooDBAppBridgeErrorPayload {
+    code: string;
+    message: string;
+}
+/** Request envelope used by the port-based RPC transport. */
+interface MindooDBAppBridgeRpcRequest<TParams = unknown> {
+    protocol: "mindoodb-app-bridge";
+    kind: "request";
+    id: string;
+    method: string;
+    params: TParams;
+}
+/** Successful RPC response envelope. */
+interface MindooDBAppBridgeRpcSuccess<TResult = unknown> {
+    protocol: "mindoodb-app-bridge";
+    kind: "success";
+    id: string;
+    result: TResult;
+}
+/** Failed RPC response envelope. */
+interface MindooDBAppBridgeRpcError {
+    protocol: "mindoodb-app-bridge";
+    kind: "error";
+    id: string;
+    error: MindooDBAppBridgeErrorPayload;
+}
+/** Union of all RPC-level bridge messages. */
+type MindooDBAppBridgeRpcMessage = MindooDBAppBridgeRpcRequest | MindooDBAppBridgeRpcSuccess | MindooDBAppBridgeRpcError;
+/** Result returned when the host opens a streamed attachment channel. */
+interface MindooDBAppBridgeStreamOpenResult {
+    streamId: string;
+}
+/** Request asking the host for the next chunk on a read stream. */
+interface MindooDBAppBridgeStreamReadRequest {
+    protocol: "mindoodb-app-bridge";
+    kind: "stream-read";
+    streamId: string;
+}
+/** Request sending one chunk over a write stream. */
+interface MindooDBAppBridgeStreamWriteRequest {
+    protocol: "mindoodb-app-bridge";
+    kind: "stream-write";
+    streamId: string;
+    chunk: ArrayBuffer;
+}
+/** Request closing a stream gracefully. */
+interface MindooDBAppBridgeStreamCloseRequest {
+    protocol: "mindoodb-app-bridge";
+    kind: "stream-close";
+    streamId: string;
+}
+/** Request aborting a stream due to cancellation or failure. */
+interface MindooDBAppBridgeStreamAbortRequest {
+    protocol: "mindoodb-app-bridge";
+    kind: "stream-abort";
+    streamId: string;
+}
+/** Streamed attachment payload delivered over the message port. */
+interface MindooDBAppAttachmentChunk {
+    protocol: "mindoodb-app-bridge";
+    kind: "stream-chunk";
+    streamId: string;
+    chunk?: ArrayBuffer;
+    done: boolean;
+}
+/** Host acknowledgement for a write/close/abort stream request. */
+interface MindooDBAppBridgeStreamAck {
+    protocol: "mindoodb-app-bridge";
+    kind: "stream-ack";
+    streamId: string;
+}
+/** Stream-level error message. */
+interface MindooDBAppBridgeStreamError {
+    protocol: "mindoodb-app-bridge";
+    kind: "stream-error";
+    streamId: string;
+    error: MindooDBAppBridgeErrorPayload;
+}
+/** Union of all non-RPC stream transport messages. */
+type MindooDBAppBridgeStreamMessage = MindooDBAppBridgeStreamReadRequest | MindooDBAppBridgeStreamWriteRequest | MindooDBAppBridgeStreamCloseRequest | MindooDBAppBridgeStreamAbortRequest | MindooDBAppAttachmentChunk | MindooDBAppBridgeStreamAck | MindooDBAppBridgeStreamError;
+/** Host-pushed event emitted when the Administrator theme changes. */
+interface MindooDBAppBridgeThemeChangedMessage {
+    protocol: "mindoodb-app-bridge";
+    kind: "theme-changed";
+    theme: MindooDBAppHostTheme;
+}
+/** Host-pushed event emitted when the Haven iframe viewport changes. */
+interface MindooDBAppBridgeViewportChangedMessage {
+    protocol: "mindoodb-app-bridge";
+    kind: "viewport-changed";
+    viewport: MindooDBAppViewport;
+}
+/** Any message that can travel across the dedicated bridge MessagePort. */
+type MindooDBAppBridgePortMessage = MindooDBAppBridgeRpcMessage | MindooDBAppBridgeStreamMessage | MindooDBAppBridgeThemeChangedMessage | MindooDBAppBridgeViewportChangedMessage;
+/** Pull-based read stream for document attachments. */
+interface MindooDBAppReadableAttachmentStream {
+    read(): Promise<Uint8Array | null>;
+    close(): Promise<void>;
+}
+/** Push-based write stream for document attachments. */
+interface MindooDBAppWritableAttachmentStream {
+    write(chunk: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+    abort(): Promise<void>;
+}
+/** Document operations exposed by an opened database handle. */
+interface MindooDBAppDocumentApi {
+    list(query?: MindooDBAppDocumentListQuery): Promise<MindooDBAppDocumentListResult>;
+    get(docId: string): Promise<MindooDBAppDocument | null>;
+    create(input: MindooDBAppCreateDocumentInput): Promise<MindooDBAppDocument>;
+    update(docId: string, patch: MindooDBAppUpdateDocumentInput): Promise<MindooDBAppDocument>;
+    delete(docId: string): Promise<{
+        ok: true;
+    }>;
+    listHistory(docId: string): Promise<MindooDBAppDocumentHistoryEntry[]>;
+    getAtTimestamp(docId: string, timestamp: number): Promise<MindooDBAppHistoricalDocument>;
+}
+/** Handle for one created or opened virtual view. */
+interface MindooDBAppViewHandle {
+    getDefinition(): Promise<MindooDBAppViewDefinition>;
+    refresh(): Promise<void>;
+    page(input?: MindooDBAppViewPageRequest): Promise<MindooDBAppViewPageResult>;
+    getExpansionState(): Promise<MindooDBAppViewExpansionState>;
+    setExpansionState(state: MindooDBAppViewExpansionState): Promise<MindooDBAppViewExpansionState>;
+    expand(rowKey: string): Promise<MindooDBAppViewExpansionState>;
+    collapse(rowKey: string): Promise<MindooDBAppViewExpansionState>;
+    expandAll(): Promise<MindooDBAppViewExpansionState>;
+    collapseAll(): Promise<MindooDBAppViewExpansionState>;
+    getRow(rowKey: string): Promise<MindooDBAppViewRow | null>;
+    getCategory(input: MindooDBAppViewLookupByPath): Promise<MindooDBAppViewRow | null>;
+    pageCategory(categoryKey: string, input?: MindooDBAppViewCategoryChildrenPageRequest): Promise<MindooDBAppViewPageResult>;
+    listCategoryDocumentIds(categoryKey: string): Promise<string[]>;
+    dispose(): Promise<void>;
+}
+/** Entry point for creating or opening views in a database. */
+interface MindooDBAppViewApi {
+    create(definition: MindooDBAppViewDefinition): Promise<MindooDBAppViewHandle>;
+    open(viewId: string): Promise<MindooDBAppViewHandle>;
+}
+/** Attachment operations exposed by an opened database handle. */
+interface MindooDBAppAttachmentApi {
+    list(docId: string): Promise<MindooDBAppAttachmentInfo[]>;
+    remove(docId: string, attachmentName: string): Promise<{
+        ok: true;
+    }>;
+    openReadStream(docId: string, attachmentName: string): Promise<MindooDBAppReadableAttachmentStream>;
+    openWriteStream(docId: string, attachmentName: string, contentType?: string): Promise<MindooDBAppWritableAttachmentStream>;
+}
+/** Database handle returned from `session.openDatabase()`. */
+interface MindooDBAppDatabase {
+    info(): Promise<MindooDBAppDatabaseInfo>;
+    documents: MindooDBAppDocumentApi;
+    views: MindooDBAppViewApi;
+    attachments: MindooDBAppAttachmentApi;
+}
+/** Connected session between the running app and the Administrator host. */
+interface MindooDBAppSession {
+    getLaunchContext(): Promise<MindooDBAppLaunchContext>;
+    listDatabases(): Promise<MindooDBAppDatabaseInfo[]>;
+    openDatabase(databaseId: string): Promise<MindooDBAppDatabase>;
+    onThemeChange(listener: (theme: MindooDBAppHostTheme) => void): () => void;
+    onViewportChange(listener: (viewport: MindooDBAppViewport) => void): () => void;
+    disconnect(): Promise<void>;
+}
+/** Root SDK bridge object used to establish a session. */
+interface MindooDBAppBridge {
+    connect(options?: MindooDBAppBridgeConnectOptions): Promise<MindooDBAppSession>;
+}
+
+export type { MindooDBAppResolvedViewDefinition as $, MindooDBAppConfiguredViewExpressionMode as A, MindooDBAppConfiguredViewFieldExpression as B, MindooDBAppConfiguredViewFilterDefinition as C, MindooDBAppConfiguredViewFilterMode as D, MindooDBAppConfiguredViewFilterRule as E, MindooDBAppConfiguredViewFormulaExpression as F, MindooDBAppConfiguredViewFormulaFilterDefinition as G, MindooDBAppConfiguredViewPreviewMode as H, MindooDBAppConfiguredViewRuleFilterDefinition as I, MindooDBAppConfiguredViewRuleMatchMode as J, MindooDBAppConfiguredViewRuleOperator as K, MindooDBAppConfiguredViewValueExpression as L, MindooDBAppBridge as M, MindooDBAppCreateDocumentInput as N, MindooDBAppDatabase as O, MindooDBAppDatabaseInfo as P, MindooDBAppDocument as Q, MindooDBAppDocumentApi as R, MindooDBAppDocumentHistoryEntry as S, MindooDBAppDocumentListQuery as T, MindooDBAppDocumentListResult as U, MindooDBAppDocumentSummary as V, MindooDBAppHistoricalDocument as W, MindooDBAppHistoryQuery as X, MindooDBAppHostTheme as Y, MindooDBAppLaunchContext as Z, MindooDBAppReadableAttachmentStream as _, MindooDBAppAttachmentApi as a, MindooDBAppResolvedViewSource as a0, MindooDBAppRuntime as a1, MindooDBAppSession as a2, MindooDBAppThemeMode as a3, MindooDBAppUpdateDocumentInput as a4, MindooDBAppViewApi as a5, MindooDBAppViewHandle as a6, MindooDBAppViewport as a7, MindooDBAppWritableAttachmentStream as a8, MindooDBAppAttachmentChunk as b, MindooDBAppAttachmentInfo as c, MindooDBAppBridgeConnectMessage as d, MindooDBAppBridgeConnectOptions as e, MindooDBAppBridgeConnectedMessage as f, MindooDBAppBridgeErrorPayload as g, MindooDBAppBridgePortMessage as h, MindooDBAppBridgeRpcError as i, MindooDBAppBridgeRpcMessage as j, MindooDBAppBridgeRpcRequest as k, MindooDBAppBridgeRpcSuccess as l, MindooDBAppBridgeStreamAbortRequest as m, MindooDBAppBridgeStreamAck as n, MindooDBAppBridgeStreamCloseRequest as o, MindooDBAppBridgeStreamError as p, MindooDBAppBridgeStreamMessage as q, MindooDBAppBridgeStreamOpenResult as r, MindooDBAppBridgeStreamReadRequest as s, MindooDBAppBridgeStreamWriteRequest as t, MindooDBAppBridgeThemeChangedMessage as u, MindooDBAppBridgeViewportChangedMessage as v, MindooDBAppCapability as w, MindooDBAppConfiguredViewCategorizationStyle as x, MindooDBAppConfiguredViewColumn as y, MindooDBAppConfiguredViewColumnRole as z };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "mindoodb-app-sdk",
+  "version": "0.0.4",
+  "description": "MindooDB app SDK for building apps that connect to the Haven host bridge",
+  "license": "ISC",
+  "author": "Mindoo GmbH",
+  "keywords": [
+    "mindoodb",
+    "haven",
+    "sdk",
+    "iframe",
+    "bridge"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "TESTING.md"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/testing/index.ts --format esm --dts --clean --tsconfig tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "dependencies": {
+    "mindoodb-view-language": "^0.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}