mindoodb-app-sdk 0.0.54 → 0.0.55

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { ay as MindooDBAppCreateViewNavigatorInput, cC as MindooDBAppViewNavigator, $ as MindooDBAppBridgeRpcRequest, b7 as MindooDBAppHostTheme, ag as MindooDBAppCapability, i as MindooDBAppDefinition, e as MindooDBAppBridge, cc as MindooDBAppSession, bE as MindooDBAppProposeAppInput, cK as MindooDBAppViewport, cw as MindooDBAppUiPreferences, bK as MindooDBAppQueryResult, cJ as MindooDBAppViewUpdateStats, X as MindooDBAppBridgePortMessage, bl as MindooDBAppLaunchContext, az as MindooDBAppDatabaseInfo, aI as MindooDBAppDocumentApi, cE as MindooDBAppViewNavigatorOpenOptions, A as MindooDBAppAttachmentApi, b8 as MindooDBAppIdentityApi, cs as MindooDBAppTimestampApi, aG as MindooDBAppDirectoryApi, k as MindooDBAppDocument, b4 as MindooDBAppFulltextSetup, b3 as MindooDBAppExtractionSetup, ck as MindooDBAppSummarySetup, bF as MindooDBAppProposeAppResult, c as MindooDBAppDragStartResult, aZ as MindooDBAppDragProfile } from '../types-CX-o1Xyq.js';
+import { aG as MindooDBAppCreateViewNavigatorInput, cM as MindooDBAppViewNavigator, a7 as MindooDBAppBridgeRpcRequest, bf as MindooDBAppHostTheme, ao as MindooDBAppCapability, j as MindooDBAppDefinition, G as MindooDBAppAttachmentApi, e as MindooDBAppBridge, cm as MindooDBAppSession, bO as MindooDBAppProposeAppInput, cU as MindooDBAppViewport, cG as MindooDBAppUiPreferences, bU as MindooDBAppQueryResult, cT as MindooDBAppViewUpdateStats, a3 as MindooDBAppBridgePortMessage, aH as MindooDBAppDatabaseInfo, $ as MindooDBAppBridgeErrorPayload, bt as MindooDBAppLaunchContext, aQ as MindooDBAppDocumentApi, cO as MindooDBAppViewNavigatorOpenOptions, bg as MindooDBAppIdentityApi, cC as MindooDBAppTimestampApi, aO as MindooDBAppDirectoryApi, l as MindooDBAppDocument, bc as MindooDBAppFulltextSetup, bb as MindooDBAppExtractionSetup, cu as MindooDBAppSummarySetup, bP as MindooDBAppProposeAppResult, c as MindooDBAppDragStartResult, b5 as MindooDBAppDragProfile } from '../types-Dl70Tlfj.js';
 import * as mindoodb from 'mindoodb';
 import 'mindoodb-view-language';
 
@@ -31,12 +31,22 @@ declare function createEvaluatingViewNavigator(input: MindooDBAppCreateViewNavig
  * tenant and an install in a real Haven. It is never meant to be deployed where end
  * users can reach it.
  */
-/** A scan the test host hands out on the app's next `attachments.scan()` call. */
+/**
+ * A scan the test host hands out on the app's `attachments.scan()` call. With `bytes`
+ * the file is written to the document's attachments, as Haven's scanner does; without,
+ * only the attachment info is returned.
+ */
 interface BrowserTestHostScan {
     fileName: string;
     mimeType: "image/jpeg" | "image/png" | "application/pdf";
-    size: number;
+    size?: number;
+    bytes?: Uint8Array;
 }
+/**
+ * What a scan returns when no {@link BrowserTestHost.setNextScan} is pending: cancel,
+ * a generated sample page, or a fixed file.
+ */
+type BrowserTestHostScanMode = "cancel" | "sample" | BrowserTestHostScan;
 /** What the test host recorded, in the order the app asked. */
 interface BrowserTestHostLog {
     notifications: Array<{
@@ -54,15 +64,22 @@ interface BrowserTestHostLog {
         databaseId: string;
         docId: string;
         result: "scanned" | "cancelled";
+        fileName?: string;
+        mimeType?: string;
+        size?: number;
     }>;
     focusRequests: number;
     requests: MindooDBAppBridgeRpcRequest[];
+    /** The answer to each request, by request id (result or error, duration). */
+    responses: Record<string, FakeBridgeRpcResponse>;
 }
 interface CreateBrowserTestHostOptions extends CreateFakeBridgeHostOptions {
     /** The iframe the app runs in. Its `src` is set by the host. */
     frame: HTMLIFrameElement;
     /** URL of the app page, relative to the test page or absolute. */
     appUrl: string;
+    /** What scans return while no `setNextScan()` is pending. Default `"cancel"`. */
+    scanMode?: BrowserTestHostScanMode;
     /** Called after every request, e.g. to re-render a control panel. */
     onChange?: () => void;
 }
@@ -70,30 +87,98 @@ interface BrowserTestHost {
     host: FakeBridgeHostController;
     log: BrowserTestHostLog;
     /**
-     * Decides the outcome of the app's next `attachments.scan()`: a file description to
-     * "scan", or `null` to act as if the user cancelled. Without a call, scans cancel.
+     * Decides the outcome of the app's next `attachments.scan()`: a file to "scan", or
+     * `null` to act as if the user cancelled. Later scans follow {@link setScanMode}.
      */
     setNextScan(scan: BrowserTestHostScan | null): void;
+    /** What scans return while no `setNextScan()` is pending. */
+    setScanMode(mode: BrowserTestHostScanMode): void;
+    getScanMode(): BrowserTestHostScanMode;
     setTheme(theme: MindooDBAppHostTheme): void;
     setHostFocus(focused: boolean): void;
+    /** Haven's language changed: the app gets `onLocaleChange`, no reload. */
+    setLocale(locale: string): void;
+    /**
+     * Grants a mapped database these capabilities and reloads the app, like Haven
+     * relaunching it after a permission change.
+     */
+    setCapabilities(databaseId: string, capabilities: MindooDBAppCapability[]): void;
+    /** Turns the capability checks on or off (`enforceCapabilities`). */
+    setEnforceCapabilities(enforce: boolean): void;
+    /** Replaces the usernames of the tenant directory (`directory.listUsers()`). */
+    setDirectoryUsers(users: readonly string[]): void;
     /** Reloads the app frame. The mock data survives; the app's in-memory state does not. */
     reloadApp(): void;
     dispose(): void;
 }
+/** Every capability Haven can grant, in the order the panel lists them. */
+declare const ALL_CAPABILITIES: readonly MindooDBAppCapability[];
 /**
  * The capabilities Haven grants for the permissions a definition requests. `read` is
  * implied by the mapping, `write` is create plus update.
  */
 declare function capabilitiesForDefinitionPermissions(permissions: readonly string[] | undefined): MindooDBAppCapability[];
-/** Mock databases for every database a `haven-app.json` declares, granted as requested. */
-declare function mockDatabasesFromDefinition(definition: Pick<MindooDBAppDefinition, "databases">, seed?: Record<string, MockMindooDBAppDatabaseDefinition["documents"]>): MockMindooDBAppDatabaseDefinition[];
+/** Changes to one database of a definition, for testing other mappings than requested. */
+interface MockDatabaseOverride {
+    title?: string;
+    /** Grant exactly these instead of what the definition requests. */
+    capabilities?: MindooDBAppCapability[];
+    /** `false`: the user did not map this database to the app. */
+    mapped?: boolean;
+}
+interface MockDatabasesFromDefinitionOptions {
+    /** By logical database id. */
+    overrides?: Record<string, MockDatabaseOverride>;
+    /**
+     * `"memory"` (default): attachments the app writes can be listed and read back.
+     * `"none"`: the mock's stateless default.
+     */
+    attachments?: "memory" | "none";
+}
+/**
+ * Mock databases for every database a `haven-app.json` declares, granted as requested
+ * unless `options.overrides` says otherwise.
+ */
+declare function mockDatabasesFromDefinition(definition: Pick<MindooDBAppDefinition, "databases">, seed?: Record<string, MockMindooDBAppDatabaseDefinition["documents"]>, options?: MockDatabasesFromDefinitionOptions): MockMindooDBAppDatabaseDefinition[];
+/**
+ * Test-host settings from the page URL, so a scenario can be linked or scripted:
+ *
+ * - `db=<id>:<capability>,<capability>` grants exactly these; `db=<id>:none` unmaps it
+ * - `enforce=1` turns the capability checks on
+ * - `users=<count>` fills the directory with generated users
+ * - `locale=<tag>`, `theme=dark|light`
+ */
+interface TestHostUrlSettings {
+    overrides: Record<string, MockDatabaseOverride>;
+    enforceCapabilities?: boolean;
+    directoryUserCount?: number;
+    locale?: string;
+    theme?: "dark" | "light";
+}
+declare function readTestHostUrlSettings(search: string): TestHostUrlSettings;
 declare function createBrowserTestHost(options: CreateBrowserTestHostOptions): BrowserTestHost;
 interface MountHavenTestHostOptions extends Omit<CreateBrowserTestHostOptions, "frame" | "onChange"> {
     /** Element to render into. Defaults to `document.body`, which is cleared. */
     container?: HTMLElement;
     /** Heading of the control panel, e.g. the app label. */
     title?: string;
+    /** Locales offered in the panel's language switcher. */
+    locales?: ReadonlyArray<{
+        tag: string;
+        label: string;
+    }>;
+    /**
+     * Read `db=`, `enforce=`, `users=`, `locale=` and `theme=` from the page URL (see
+     * {@link readTestHostUrlSettings}) and keep the URL in sync with the panel. Default
+     * true. URL settings win over the options passed here.
+     */
+    urlSettings?: boolean;
 }
+/** The locales Haven's UI offers; the default of the panel's language switcher. */
+declare const TEST_HOST_LOCALES: ReadonlyArray<{
+    tag: string;
+    label: string;
+}>;
 declare global {
     interface Window {
         /** Set by {@link mountHavenTestHost} so Playwright can script the host. */
@@ -101,12 +186,36 @@ declare global {
     }
 }
 /**
- * Renders the full test page: the app frame plus a control panel for theme, host focus
- * and the next scan, and a live log of notifications, previews, scans and requests.
+ * JSON for the request log: binary as size plus a hex preview, long strings and arrays
+ * cut, deep objects summarized.
+ */
+declare function previewJson(value: unknown, maxString?: number, maxItems?: number, maxDepth?: number): string;
+/**
+ * Renders the full test page: the app frame plus a control panel — theme, host focus,
+ * language, capabilities per database, directory users, the scanner — and a live log
+ * of notifications, previews, scans and requests (click an entry for details).
  * The returned host is also available as `window.__havenTestHost`.
  */
 declare function mountHavenTestHost(options: MountHavenTestHostOptions): BrowserTestHost;
 
+/**
+ * In-memory attachments for mock databases: what an app writes can be listed and read
+ * back, like in Haven. The default mock attachment API stores nothing; the browser test
+ * host (`mockDatabasesFromDefinition`) uses this store instead.
+ */
+
+declare function createMemoryAttachments(): Partial<MindooDBAppAttachmentApi>;
+
+/**
+ * Capability checks for the mock databases, the way Haven enforces them: a call the
+ * database was not granted is rejected with a `forbidden` error. Opt in with
+ * `enforceCapabilities: true`; without it the mock only lists the capabilities.
+ */
+
+declare class MockForbiddenError extends Error {
+    name: string;
+}
+
 type MaybePromise<T> = T | Promise<T>;
 type MockViewApi = {
     create(input: MindooDBAppCreateViewNavigatorInput): MaybePromise<MindooDBAppViewNavigator>;
@@ -198,7 +307,27 @@ interface CreateMockMindooDBAppSessionOptions {
     proposeApp?: (input: MindooDBAppProposeAppInput) => MindooDBAppProposeAppResult;
     /** Initial contents of `session.storage`. */
     storage?: Record<string, string>;
+    /**
+     * Reject calls a database was not granted, like Haven does (a `forbidden` error;
+     * `documents.canCreate()` and friends answer `allowed: false`). Off by default so
+     * existing tests keep passing; turn it on to test how an app handles missing rights.
+     */
+    enforceCapabilities?: boolean;
+    /**
+     * Usernames `directory.listUsers()` returns on every database (Haven's directory is
+     * tenant-wide), e.g. `generateDirectoryUsers(120)`. A database's own
+     * `methods.directory` still wins.
+     */
+    directoryUsers?: readonly string[];
 }
+/**
+ * Test usernames in Haven's canonical form: `CN=Test User 001/O=Test`, …
+ * Enough of them (e.g. 120) exercise the paging of `directory.listUsers({ … })`.
+ */
+declare function generateDirectoryUsers(count: number, options?: {
+    prefix?: string;
+    organization?: string;
+}): string[];
 interface MockMindooDBAppSessionController {
     bridge: MindooDBAppBridge;
     session: MindooDBAppSession;
@@ -209,6 +338,16 @@ interface MockMindooDBAppSessionController {
     proposedApps: MindooDBAppProposeAppInput[];
     listDatabases(): MindooDBAppDatabaseInfo[];
     setDatabases(definitions: MockMindooDBAppDatabaseDefinition[]): void;
+    /**
+     * Replaces the capabilities of one mapped database. Takes effect on the next call
+     * (with `enforceCapabilities`) and in the launch context; apps that read the
+     * capabilities once at start see the change after a reload.
+     */
+    setCapabilities(databaseId: string, capabilities: MindooDBAppCapability[]): void;
+    /** Turns the capability checks on or off (see `enforceCapabilities`). */
+    setEnforceCapabilities(enforce: boolean): void;
+    /** Replaces the directory's usernames (see `directoryUsers`). */
+    setDirectoryUsers(users: readonly string[]): void;
     emitThemeChange(theme: MindooDBAppHostTheme): void;
     emitViewportChange(viewport: MindooDBAppViewport): void;
     emitUiPreferencesChange(uiPreferences: MindooDBAppUiPreferences): void;
@@ -232,11 +371,23 @@ type FakeBridgePortMessageHandler = (message: Exclude<MindooDBAppBridgePortMessa
     host: FakeBridgeHostController;
     port: MessagePort;
 }) => MaybePromise<boolean | void>;
+/** How the fake host answered one RPC request (see `onResponse`). */
+type FakeBridgeRpcResponse = {
+    ok: true;
+    result: unknown;
+    durationMs: number;
+} | {
+    ok: false;
+    error: MindooDBAppBridgeErrorPayload;
+    durationMs: number;
+};
 interface CreateFakeBridgeHostOptions extends CreateMockMindooDBAppSessionOptions {
     windowMode?: "parent" | "opener";
     requestHandlers?: Record<string, FakeBridgeRequestHandler>;
     /** Called for every RPC request the app sends, before it is answered. */
     onRequest?: (request: MindooDBAppBridgeRpcRequest) => void;
+    /** Called with the answer to every RPC request, right after it was sent. */
+    onResponse?: (request: MindooDBAppBridgeRpcRequest, response: FakeBridgeRpcResponse) => void;
     onPortMessage?: FakeBridgePortMessageHandler;
 }
 interface FakeBridgeHostController {
@@ -272,7 +423,16 @@ interface FakeBridgeHostController {
     postPortMessage(message: MindooDBAppBridgePortMessage, transfer?: Transferable[]): void;
     setRequestHandler(method: string, handler: FakeBridgeRequestHandler): void;
     clearRequestHandler(method: string): void;
+    listDatabases(): MindooDBAppDatabaseInfo[];
+    /** See {@link MockMindooDBAppSessionController.setCapabilities}. */
+    setCapabilities(databaseId: string, capabilities: MindooDBAppCapability[]): void;
+    /** See {@link CreateMockMindooDBAppSessionOptions.enforceCapabilities}. */
+    setEnforceCapabilities(enforce: boolean): void;
+    getEnforceCapabilities(): boolean;
+    /** See {@link CreateMockMindooDBAppSessionOptions.directoryUsers}. */
+    setDirectoryUsers(users: readonly string[]): void;
+    getDirectoryUsers(): string[];
 }
 declare function createFakeBridgeHost(options?: CreateFakeBridgeHostOptions): FakeBridgeHostController;
 
-export { type BrowserTestHost, type BrowserTestHostLog, type BrowserTestHostScan, type CreateBrowserTestHostOptions, type CreateFakeBridgeHostOptions, type CreateMockMindooDBAppSessionOptions, type EvaluatingViewDocument, type FakeBridgeHostController, type FakeBridgePortMessageHandler, type FakeBridgeRequestHandler, type MockMindooDBAppDatabaseDefinition, type MockMindooDBAppSessionController, type MockSealedChannelOptions, type MockSeedDocument, type MountHavenTestHostOptions, capabilitiesForDefinitionPermissions, createBrowserTestHost, createEvaluatingViewNavigator, createFakeBridgeHost, createMockMindooDBAppBridge, createMockMindooDBAppSession, loadMindoodbForTesting, mockDatabasesFromDefinition, mountHavenTestHost };
+export { ALL_CAPABILITIES, type BrowserTestHost, type BrowserTestHostLog, type BrowserTestHostScan, type BrowserTestHostScanMode, type CreateBrowserTestHostOptions, type CreateFakeBridgeHostOptions, type CreateMockMindooDBAppSessionOptions, type EvaluatingViewDocument, type FakeBridgeHostController, type FakeBridgePortMessageHandler, type FakeBridgeRequestHandler, type FakeBridgeRpcResponse, type MockDatabaseOverride, type MockDatabasesFromDefinitionOptions, MockForbiddenError, type MockMindooDBAppDatabaseDefinition, type MockMindooDBAppSessionController, type MockSealedChannelOptions, type MockSeedDocument, type MountHavenTestHostOptions, TEST_HOST_LOCALES, type TestHostUrlSettings, capabilitiesForDefinitionPermissions, createBrowserTestHost, createEvaluatingViewNavigator, createFakeBridgeHost, createMemoryAttachments, createMockMindooDBAppBridge, createMockMindooDBAppSession, generateDirectoryUsers, loadMindoodbForTesting, mockDatabasesFromDefinition, mountHavenTestHost, previewJson, readTestHostUrlSettings };