@dolphy-app/extension-sdk 0.3.0 → 0.5.0

package/dist/testing.d.ts

@@ -1,5 +1,7 @@
-import { t as AnswerView } from "./answer-view-D6wnyThb.js";
-import { AnswerChangeDetail, AnswerElementProps, CommandOutcome, ExtensionCommands, ExtensionEvents, ExtensionLogger, ExtensionModule, ExtensionSettings, ExtensionStorage, GradePolicyInput, GradeResult, GradeValue, JsonSchema, JsonValue, LearningEventName, LearningEventPayloads, LibraryReader, PanelModule, SettingContribution, SettingValue } from "@dolphy-app/extension-api";
+import { t as ExtensionEngine } from "./index-I_CXC6Lj.js";
+import { a as MountContext$1, i as InjectionRegistration$1, l as ServerEntry$1, o as Mountable, r as ClientEntry, s as PanelRegistration$1, t as AppApi$1 } from "./define-entry-lsuxzKdD.js";
+import { AnswerViewProps, AppLocale, AppTheme, ClientCommandRegistration, CommandOutcome, Disposable, ExportInput, ExportResult, ExtensionHookName, ExtensionLogger, ExtensionNotification, ExtensionNotifications, ExtensionSecrets, ExtensionSettings, ExtensionStats, ExtensionStorage, GradePolicyInput, GradeResult, GradeValue, HookRequest, HookResponse, ImportInput, ImportResult, JsonSchema, JsonValue, LearningEventName, LearningEventPayloads, LibraryReader, MarkdownBlockProps, RpcContract, ServerRegistration, SettingDefinition, SettingValue, ThemeRegistration } from "@dolphy-app/extension-api";
+import { Component } from "vue";
 //#region packages/extension-sdk/src/testing.d.ts
 export declare const createMemoryLibrary: (files: Readonly<Record<string, string>>) => LibraryReader;
 /**
@@ -8,6 +10,22 @@ export declare const createMemoryLibrary: (files: Readonly<Record<string, string
  * JSON text and returned as copies; on rejection nothing changes.
  */
 export declare const createMemoryStorage: () => ExtensionStorage;
+/** In-memory secrets for tests: `ExtensionSecrets` plus a switch that imitates a missing system key store. */
+export interface MemorySecrets extends ExtensionSecrets {
+  /** Imitates the system key store becoming (un)available; stored values are kept. */
+  setAvailable(available: boolean): void;
+}
+export interface MemorySecretsOptions {
+  /** Default `true`; `false` imitates Linux `basic_text`, no key store, or an app that is not ready. */
+  available?: boolean;
+}
+/**
+ * In-memory secrets with the engine's limits and errors
+ * (`EXTENSION_SECRET_LIMITS`, `StorageQuotaError`, `SecretsUnavailableError`):
+ * without a key store `set` and `get` of an existing key throw, `get` of a
+ * missing key gives `undefined` and `delete` works.
+ */
+export declare const createMemorySecrets: (options?: MemorySecretsOptions) => MemorySecrets;
 export interface MemorySettings extends ExtensionSettings {
   /**
    * Changes the value as the user does in the dialog: the value is validated
@@ -15,54 +33,82 @@ export interface MemorySettings extends ExtensionSettings {
    * Unlike the host, a handler failure is not swallowed but rejects the promise.
    */
   set(id: string, value: SettingValue): Promise<void>;
+  /** Adds definitions, as `server.registerSettings` does; an id registered twice throws. The returned `Disposable` removes them. */
+  register(definitions: readonly SettingDefinition[]): Disposable;
 }
-/** In-memory settings from manifest definitions; `initial` provides user values in place of `default`. */
-export declare const createMemorySettings: (definitions: readonly SettingContribution[], initial?: Readonly<Record<string, SettingValue>>) => MemorySettings;
-export interface MemoryEvents extends ExtensionEvents {
-  /**
-   * Sends the event to the subscribed handler and awaits it. With no subscription,
-   * the event is skipped, as in the host. Unlike the host, a handler failure
-   * is not swallowed but rejects the promise, and the 2 s handler timeout is not applied.
-   */
-  emit<N extends LearningEventName>(name: N, payload: LearningEventPayloads[N]): Promise<void>;
+/**
+ * In-memory settings. `definitions` are registered at once, more come through
+ * `register`; `initial` provides user values in place of `default`, applied
+ * when the setting with that id is registered.
+ */
+export declare const createMemorySettings: (definitions?: readonly SettingDefinition[], initial?: Readonly<Record<string, SettingValue>>) => MemorySettings;
+export interface MemoryStatsAttempt {
+  /** When the attempt happened: epoch milliseconds, a `Date`, or an ISO-8601 string. */
+  at: number | Date | string;
+  /** Grade 1-5; 3 and higher counts as correct, as in the app. */
+  grade: number;
+  /** Course of the attempt, for the `courseId` filter. Without it the attempt belongs to no course. */
+  courseId?: string;
 }
-export interface MemoryEventsOptions {
-  /** Events from `contributes.events`: subscribing to another throws, as in the host. Unset — any are allowed. */
-  declared?: readonly LearningEventName[];
-  /** false — subscribing throws `PermissionError`, as for an extension without `learning.events`. Defaults to true. */
-  permitted?: boolean;
+export interface MemoryStatsOptions {
+  /** Attempts the statistics start with; more arrive through `record`. */
+  attempts?: readonly MemoryStatsAttempt[];
+  /** IANA time zone whose local days are counted. Defaults to the time zone of this process. */
+  timeZone?: string;
+  /** The current time, for the `current` streak. Defaults to `Date.now`. */
+  now?: () => number;
 }
-/** In-memory learning event subscriptions: one handler per event, as in the host. */
-export declare const createMemoryEvents: (options?: MemoryEventsOptions) => MemoryEvents;
-export interface MemoryCommands extends ExtensionCommands {
-  /**
-   * Runs a registered command the way the host does: the same
-   * argument and result bounds, the same result normalization. An unregistered
-   * command and an invalid result reject the promise. The 10 s handler timeout is not applied.
-   */
-  run(id: string, args?: JsonValue): Promise<CommandOutcome>;
-  /** Registered commands in registration order. */
-  ids(): string[];
-}
-export interface MemoryCommandsOptions {
-  /** Commands from `contributes.commands`: registering another throws, as in the host. Unset — any are allowed. */
-  declaredCommands?: readonly string[];
-  /** Panels from `contributes.panels`: `openPanel` on another is invalid, as in the host. Unset — any. */
-  declaredPanels?: readonly string[];
-}
-/** In-memory commands: the same registration rules and result parsing as the host. */
-export declare const createMemoryCommands: (options?: MemoryCommandsOptions) => MemoryCommands;
-/** What a test replaces in the extension context; by default everything is in memory and silent. */
-export interface LoadOptions {
+export interface MemoryStats extends ExtensionStats {
+  /** Adds an attempt to the history. */
+  record(attempt: MemoryStatsAttempt): void;
+}
+/**
+ * In-memory statistics with the semantics of the app: local days in a time zone,
+ * correct at grade 3 or higher, `current` streak not broken while today has no
+ * attempts yet, one `daily` entry per date (at most `EXTENSION_STATS_LIMITS.dailyDays`).
+ */
+export declare const createMemoryStats: (options?: MemoryStatsOptions) => MemoryStats;
+export interface MemoryNotificationsOptions {
+  /** false — the operating system does not support notifications: `show` resolves `false`. Defaults to true. */
+  supported?: boolean;
+  /** false — the user switched notifications off for the extension: `show` resolves `false`. Defaults to true. */
+  enabled?: boolean;
+  /** The current time for the rate windows. Defaults to `Date.now`. */
+  now?: () => number;
+}
+export interface MemoryNotifications extends ExtensionNotifications {
+  /** Notifications handed to the (imitated) operating system, oldest first, as the app shows them: sanitized text. */
+  readonly shown: readonly ExtensionNotification[];
+  /** The user's switch "Notifications" of the extension. */
+  setEnabled(enabled: boolean): void;
+  /** Whether the imitated operating system supports notifications. */
+  setSupported(supported: boolean): void;
+}
+/**
+ * In-memory notifications with the engine's rules: the text is sanitized and
+ * limited, `perMinute`/`perHour` windows throw `NotificationRateLimitError`,
+ * a switched-off extension or an unsupporting system resolves `false` (and
+ * does not use the rate limit). `shown` is the log the app's fake notifier
+ * would keep.
+ */
+export declare const createMemoryNotifications: (options?: MemoryNotificationsOptions) => MemoryNotifications;
+export declare const createSchemaValidator: (schema: JsonSchema) => (value: unknown) => string[];
+/** What a test replaces in the context of the server part; by default everything is in memory and silent. */
+export interface TestServerOptions {
+  /** Default `test`. When set, every registered id must be equal to it or start with `<extensionId>.`, as the host checks. */
+  extensionId?: string;
   library?: LibraryReader;
   logger?: ExtensionLogger;
   storage?: ExtensionStorage;
-  settings?: ExtensionSettings;
-  events?: ExtensionEvents;
-  commands?: ExtensionCommands;
+  secrets?: MemorySecrets;
+  stats?: MemoryStats;
+  notifications?: MemoryNotifications;
+  /** User values of settings in place of `default`, by setting id; every id must be registered by the entry. */
+  settingValues?: Readonly<Record<string, SettingValue>>;
+  /** The engine `ctx.engine` gives to the entry; by default every use of it throws, as the test server has no engine. */
+  engine?: ExtensionEngine;
 }
-export declare const createSchemaValidator: (schema: JsonSchema) => (value: unknown) => string[];
-export interface LoadedExerciseType {
+export interface TestExerciseType {
   project(spec: unknown, options?: {
     exerciseId?: string;
   }): Promise<unknown>;
@@ -81,95 +127,176 @@ export interface LoadedExerciseType {
   } | {
     found: false;
   }>;
-  /** Deactivates the extension module. */
-  dispose(): Promise<void>;
 }
-export declare const loadExerciseType: (module: ExtensionModule, type: string, options?: LoadOptions) => Promise<LoadedExerciseType>;
-export interface LoadedGradePolicy {
+export interface TestGradePolicy {
   evaluate(input: GradePolicyInput): Promise<GradeValue | null>;
-  /** Deactivates the extension module. */
+}
+export interface TestImporter {
+  /**
+   * Runs the importer the way the host does: the input must have the form the
+   * importer declares and at most `EXTENSION_TRANSFER_LIMITS.inputBytes`; the
+   * result goes through `normalizeImportResult`. An invalid result rejects the
+   * promise. The handler timeout is not applied.
+   */
+  run(input: ImportInput): Promise<ImportResult>;
+}
+export interface TestExporter {
+  /**
+   * Runs the exporter the way the host does: the input must match the
+   * exporter's `scope` and a course snapshot is at most
+   * `EXTENSION_TRANSFER_LIMITS.totalBytes`; the result goes through
+   * `normalizeExportResult`. An invalid result rejects the promise. The handler
+   * timeout is not applied.
+   */
+  run(input: ExportInput): Promise<ExportResult>;
+}
+/** The server part of an extension, started on in-memory fakes. */
+export interface TestServer {
+  readonly extensionId: string;
+  /** What the entry registered, as the host's registrar hands it to the engine (checked for types and unique ids only: the host checks the rest). */
+  readonly registration: ServerRegistration;
+  readonly library: LibraryReader;
+  readonly storage: ExtensionStorage;
+  readonly secrets: MemorySecrets;
+  readonly settings: MemorySettings;
+  readonly stats: MemoryStats;
+  readonly notifications: MemoryNotifications;
+  /** The engine of the context: `options.engine`. */
+  readonly engine: ExtensionEngine;
+  readonly commands: {
+    /**
+     * Runs a registered command the way the host does: the same argument and
+     * result bounds, the same result normalization. An unregistered command
+     * and an invalid result reject the promise. The handler timeout is not applied.
+     */
+    run(id: string, args?: JsonValue): Promise<CommandOutcome>;
+  };
+  readonly events: {
+    /**
+     * Sends the event to the subscribed handler and awaits it. With no
+     * subscription the event is skipped, as in the host. Unlike the host, a
+     * handler failure is not swallowed but rejects the promise, and the
+     * handler timeout is not applied.
+     */
+    emit<N extends LearningEventName>(name: N, payload: LearningEventPayloads[N]): Promise<void>;
+  };
+  /**
+   * Calls the handler registered with `server.before` the way the host does:
+   * the request must pass `EXTENSION_HOOKS[name].request` and the response
+   * `EXTENSION_HOOKS[name].response`. An unregistered hook, a schema
+   * violation and an error of the handler reject the promise. The handler
+   * timeout is not applied, and no other extension's handlers run.
+   */
+  hook<N extends ExtensionHookName>(name: N, request: HookRequest<N>): Promise<HookResponse<N>>;
+  readonly schedule: {
+    /**
+     * Fires a registered schedule the way the host does and awaits the
+     * handler: resolves `true` once the handler returned, `false` while the
+     * handler of the previous firing is still running. An unregistered
+     * schedule rejects the promise. Unlike the host, a handler failure is not
+     * swallowed but rejects the promise.
+     */
+    fire(id: string): Promise<boolean>;
+  };
+  exerciseType(id: string): TestExerciseType;
+  gradePolicy(id: string): TestGradePolicy;
+  importer(id: string): TestImporter;
+  exporter(id: string): TestExporter;
+  /**
+   * Calls the handler registered with `server.handle` under `contract.name`
+   * the way the host does: the input must serialize to at most
+   * `EXTENSION_RPC_LIMITS.inputChars` characters and pass the input schema
+   * the handler registered; the result must pass the output schema. An
+   * unregistered contract, a schema violation and an error of the handler
+   * reject the promise. The handler timeout is not applied.
+   */
+  rpc<Input, Output>(contract: RpcContract<Input, Output>, input: Input): Promise<Output>;
+  /** Runs the cleanup the entry returned and removes the registrations. */
   dispose(): Promise<void>;
 }
-export declare const loadGradePolicy: (module: ExtensionModule, id: string, options?: LoadOptions) => Promise<LoadedGradePolicy>;
-export interface LoadedEvents {
-  /** Events are delivered as in the host: to the subscribed handler, one at a time. See `MemoryEvents.emit`. */
-  emit: MemoryEvents['emit'];
-  storage: ExtensionStorage;
-  settings: MemorySettings;
-  /** Deactivates the extension module. */
+/**
+ * Starts `entry` (the `server` export of an extension) with in-memory
+ * storage, secrets, settings, statistics, notifications and library, and
+ * returns a harness to call what it registered. Registration is all or
+ * nothing, as in the host: when `entry` throws, so does `createTestServer`.
+ */
+export declare const createTestServer: (entry: ServerEntry$1, options?: TestServerOptions) => Promise<TestServer>;
+/** An answer view as registered: a Vue component or a `Mountable`. */
+export type AnswerViewComponent = Component | Mountable<AnswerViewProps>;
+/** A markdown renderer as registered: a Vue component or a `Mountable`. */
+export type MarkdownRendererComponent = Component | Mountable<MarkdownBlockProps>;
+/** The client part of an extension, started on a recording context. */
+export interface TestClient {
+  readonly extensionId: string;
+  readonly panels: readonly PanelRegistration$1[];
+  /** Injections as registered, with `position` defaulted to `append`. */
+  readonly injections: readonly Required<InjectionRegistration$1>[];
+  /** Answer views by exercise type id, as registered (a Vue component or a `Mountable`). */
+  readonly answerViews: ReadonlyMap<string, AnswerViewComponent>;
+  /** Markdown renderers by block language, as registered (a Vue component or a `Mountable`). */
+  readonly markdownRenderers: ReadonlyMap<string, MarkdownRendererComponent>;
+  readonly themes: readonly ThemeRegistration[];
+  readonly commands: readonly ClientCommandRegistration[];
+  /** Runs the cleanup the entry returned and removes the registrations. */
   dispose(): Promise<void>;
 }
-export interface LoadEventsOptions extends Omit<LoadOptions, 'storage' | 'settings' | 'events'>, MemoryEventsOptions {
-  storage?: ExtensionStorage;
-  /** Definitions from the manifest's `contributes.settings`; values are read and changed through `settings`. */
-  settings?: readonly SettingContribution[];
-  /** User values in place of `default`. */
-  settingValues?: Readonly<Record<string, SettingValue>>;
+export interface TestClientOptions {
+  /** Default `test`. When set, every registered id must be equal to it or start with `<extensionId>.`, as the window checks. */
+  extensionId?: string;
+  /** The window API `client.app` gives to the entry; by default every use of it throws, as the test client has no window. */
+  app?: AppApi$1;
+  /** The engine `client.engine` gives to the entry; by default every use of it throws. */
+  engine?: ExtensionEngine;
 }
 /**
- * Activates the module with in-memory storage, settings, and events, and lets the test
- * send events and change settings.
+ * Starts `entry` (the `client` export of an extension) on a context that
+ * records what it adds, so a test can mount the components and read the
+ * themes and commands. An id added twice and an injection with a bad target
+ * or position fail like in the window.
  */
-export declare const loadEvents: (module: ExtensionModule, options?: LoadEventsOptions) => Promise<LoadedEvents>;
-export interface LoadedCommands {
-  run: MemoryCommands['run'];
-  ids: MemoryCommands['ids'];
-  /** Deactivates the extension module. */
-  dispose(): Promise<void>;
+export declare const createTestClient: (entry: ClientEntry, options?: TestClientOptions) => Promise<TestClient>;
+/** What `mountForTest` gives `ctx`; everything is optional except `props`. */
+export interface MountForTestOptions<Props, Handle = undefined> {
+  /** The first `ctx.props`. */
+  props: Props;
+  /** The element to draw into; by default a new `<div>` of the global `document`. Required without a DOM. */
+  el?: HTMLElement;
+  /** `ctx.handle`: a panel or injection handle; `undefined` by default. */
+  handle?: Handle;
+  /** `ctx.app`; by default every use of it throws, as the test has no window. */
+  app?: AppApi$1;
+  /** `ctx.engine`, the engine of `ctx.callRpc`; by default every use of it throws. */
+  engine?: ExtensionEngine;
+  /** Default `{ id: 'light', dark: false }`. */
+  theme?: AppTheme;
+  /** Default `en`. */
+  locale?: AppLocale;
+  /** Default `test`. */
+  extensionId?: string;
 }
-export interface LoadCommandsOptions extends Omit<LoadOptions, 'commands'>, MemoryCommandsOptions {}
-/** Activates the module with in-memory commands and lets the test invoke them like the host. */
-export declare const loadCommands: (module: ExtensionModule, options?: LoadCommandsOptions) => Promise<LoadedCommands>;
-export interface LoadViewOptions extends Partial<AnswerElementProps> {
-  /** `aria-label` of the host element, as the app sets it. */
-  label?: string;
-  /** Where to mount; defaults to a new `div` in `document.body`. */
-  container?: HTMLElement;
-}
-export interface LoadedView {
-  /** The kind's custom element, as the app creates it. */
-  readonly element: HTMLElement;
-  /** The element's shadow root: the view renders its UI here. */
-  readonly root: ShadowRoot;
-  /** `dolphy-answer-change` events in order. */
-  readonly changes: readonly AnswerChangeDetail[];
-  /** How many times the view asked to submit the answer (`dolphy-answer-submit`). */
-  readonly submissions: number;
-  /** Sets element properties and waits for the view to apply the update. */
-  update(props: Partial<AnswerElementProps>): Promise<void>;
-  query<E extends Element = Element>(selector: string): E | null;
-  queryAll<E extends Element = Element>(selector: string): E[];
-  /** Removes the element from the document; the view receives `destroy()`. */
-  dispose(): void;
+/** A `Mountable` mounted by `mountForTest`. */
+export interface MountedForTest<Props, Handle = undefined> {
+  readonly el: HTMLElement;
+  /** The context the `Mountable` got. */
+  readonly ctx: MountContext$1<Props, Handle>;
+  /** Replaces `ctx.props` and calls the `onProps` listeners. */
+  setProps(next: Props): void;
+  /** Replaces `ctx.theme` and calls the `onTheme` listeners. */
+  setTheme(next: AppTheme): void;
+  /** Replaces `ctx.locale` and calls the `onLocale` listeners. */
+  setLocale(next: AppLocale): void;
+  /** Every `ctx.emit` call, in order: `[event, payload]`. */
+  readonly emitted: readonly (readonly [string, unknown])[];
+  /** Every `ctx.reportError` call, in order. */
+  readonly errors: readonly unknown[];
+  /** Aborts `ctx.signal` and runs the cleanup `mount` returned, once. */
+  unmount(): Promise<void>;
 }
 /**
- * Mounts a view from `views[id]` in the test DOM environment with the same element
- * the app creates (test tags are issued; the manifest `element` is not needed).
+ * Mounts a `Mountable` into an element on a recording context, so a test can
+ * change the props, the theme and the language, read what the component
+ * emitted and reported, and unmount it. Rejects with what `mount` throws. Needs
+ * a DOM (`document`) or `options.el`.
  */
-export declare const loadView: (views: Readonly<Record<string, AnswerView>>, id: string, options?: LoadViewOptions) => Promise<LoadedView>;
-export interface LoadPanelOptions {
-  /** Properties the panel was opened with (`openPanel(id, props)`). */
-  props?: JsonValue;
-  /** Reply to `ctx.call`; by default the call is rejected. */
-  call?: (commandId: string, args: JsonValue | undefined) => JsonValue | undefined | Promise<JsonValue | undefined>;
-  /** Where to mount; defaults to a new `div` in `document.body`. */
-  container?: HTMLElement;
-}
-export interface LoadedPanel {
-  /** Container the panel received in `mount`. */
-  readonly container: HTMLElement;
-  /** `ctx.call` invocations in order. */
-  readonly calls: readonly {
-    commandId: string;
-    args: JsonValue | undefined;
-  }[];
-  /** Whether `ctx.signal` was aborted (after `dispose()`). */
-  readonly aborted: boolean;
-  /** Sends new properties to the panel (`ctx.onProps`). */
-  setProps(props: JsonValue | undefined): void;
-  /** Closes the frame: aborts `ctx.signal` and removes the container. */
-  dispose(): void;
-}
-/** Mounts a panel from `panels[id]` in the test DOM environment with the same context the frame provides. */
-export declare const loadPanel: (panels: Readonly<Record<string, PanelModule<HTMLElement>>>, id: string, options?: LoadPanelOptions) => Promise<LoadedPanel>;
+export declare const mountForTest: <Props, Handle = undefined>(mountable: Mountable<Props, Handle>, options: MountForTestOptions<Props, Handle>) => Promise<MountedForTest<Props, Handle>>;
 //#endregion