@dolphy-app/extension-sdk 0.4.0 → 0.6.0

package/docs/recipe-event-storage.md

@@ -20,49 +20,31 @@ File `extension.json` (events):
   "name": "Day streak",
   "description": "Counts the days in a row with a closed attempt and shows the streak.",
   "author": "your-github-login",
-  "permissions": ["learning.events"],
-  "tags": ["learning"],
-  "contributes": {
-    "events": [{ "event": "attempt.closed" }],
-    "commands": [
-      { "id": "acme.hello.show", "title": "Show the streak", "category": "Streak" },
-      { "id": "acme.hello.data", "title": "Streak data", "palette": false }
-    ],
-    "panels": [{ "id": "acme.hello.view", "title": "Streak" }]
-  }
+  "tags": ["learning"]
 }
 ```
 
-- `permissions: ["learning.events"]` and `contributes.events` are both required
-  to receive an event. The events are `session.started`, `session.finished` and
-  `attempt.closed`. The payloads carry ids, the grade, the outcome and the time,
-  never the learner's answer or the exercise text.
-- Mention the permission in your `README.md` and say what it is for: the catalog
-  review asks.
-- Storage and settings need no permission.
+Nothing about events is in the manifest: `server.on` is the subscription.
 
-## The code
+## The server part
 
 File `src/index.ts` (events):
 
 ```ts
-import {
-  defineExtension,
-  defineExtensionPanel,
-  inActivate,
-  notify,
-  openPanel,
-} from '@dolphy-app/extension-sdk';
-import type { ExtensionPanels } from '@dolphy-app/extension-sdk';
+export { client } from './client.ts';
+export { server } from './server.ts';
+```
 
+File `src/streak.ts` (events):
+
+```ts
 // a `type`, not an `interface`: an interface has no index signature and is
-// not JSON for `ctx.storage`
+// not JSON for `server.storage`
 export type Streak = {
   days: number;
   last: string;
 };
 
-const KEY = 'streak';
 const DAY_MS = 86_400_000;
 
 const dayOf = (at: number): string => new Date(at).toISOString().slice(0, 10);
@@ -76,69 +58,111 @@ export const advance = (streak: Streak | undefined, at: number): Streak => {
     streak !== undefined && dayOf(Date.parse(streak.last) + DAY_MS) === day;
   return { days: continues ? streak.days + 1 : 1, last: day };
 };
+```
 
-// every event and command declared in extension.json is listed here;
-// `inActivate` means "registered in `activate`": the handlers need `ctx`
-export const host = defineExtension({
-  events: { 'attempt.closed': inActivate },
-  commands: { 'acme.hello.show': inActivate, 'acme.hello.data': inActivate },
-  activate(ctx) {
-    // delivered asynchronously, once per recorded attempt
-    ctx.events.on('attempt.closed', async ({ at, outcome }) => {
-      if (outcome === 'gave-up') return;
-      const streak = await ctx.storage.get<Streak>(KEY);
-      await ctx.storage.set(KEY, advance(streak, at));
-    });
+File `src/server.ts` (events):
 
-    // data for the panel: hidden from the palette, the panel calls it
-    ctx.commands.register(
-      'acme.hello.data',
-      async () => (await ctx.storage.get<Streak>(KEY)) ?? { days: 0, last: '' },
-    );
+```ts
+import { defineServer, notify, openPanel } from '@dolphy-app/extension-sdk';
+import { advance } from './streak.ts';
+import type { Streak } from './streak.ts';
+
+const KEY = 'streak';
 
-    ctx.commands.register('acme.hello.show', async () => {
-      const streak = await ctx.storage.get<Streak>(KEY);
+// runs in the extension host: every call registers a contribution
+export const server = defineServer((s) => {
+  // delivered asynchronously, once per recorded attempt
+  s.on('attempt.closed', async ({ at, outcome }) => {
+    if (outcome === 'gave-up') return;
+    const streak = await s.storage.get<Streak>(KEY);
+    await s.storage.set(KEY, advance(streak, at));
+  });
+
+  // data for the panel: hidden from the palette, the panel calls it
+  s.registerCommand({
+    id: 'acme.hello.data',
+    title: 'Streak data',
+    palette: false,
+    run: async () =>
+      (await s.storage.get<Streak>(KEY)) ?? { days: 0, last: '' },
+  });
+
+  s.registerCommand({
+    id: 'acme.hello.show',
+    title: { en: 'Show the streak', ru: 'Показать серию' },
+    category: 'Streak',
+    run: async () => {
+      const streak = await s.storage.get<Streak>(KEY);
       if (streak === undefined) {
         return notify('No streak yet: finish your first exercise.');
       }
       return openPanel('acme.hello.view', { days: streak.days });
-    });
-  },
-});
-
-// the panel runs in an isolated frame: no network, the only way out is `ctx.call`
-export const panels = {
-  'acme.hello.view': defineExtensionPanel({
-    async mount(container, ctx) {
-      const line = container.ownerDocument.createElement('p');
-      container.append(line);
-      const render = async () => {
-        const streak = (await ctx.call('acme.hello.data')) as Streak;
-        line.textContent =
-          streak.days === 0
-            ? 'No streak yet.'
-            : `Streak: ${streak.days} days, last day ${streak.last}`;
-      };
-      // the command opens the panel again with new properties: redraw
-      ctx.signal.addEventListener(
-        'abort',
-        ctx.onProps(() => void render()),
-      );
-      await render();
     },
-  }),
-} satisfies ExtensionPanels;
+  });
+});
 ```
 
-- `ctx.events.on(name, handler)`: one handler per event. Delivery is
-  asynchronous, in order and at most once; a handler gets 2 seconds, the queue
-  holds 100 events per extension, and a failing handler only reaches the log.
-- `ctx.storage` is JSON under string keys, private to the extension, kept across
-  restarts and updates. The value must be JSON: that is why `Streak` is a
+- `server.on(name, handler)` subscribes to a learning event: `session.started`,
+  `session.finished` or `attempt.closed`. The payloads carry ids, the grade, the
+  outcome and the time, never the learner's answer or the exercise text. One
+  handler per event. Delivery is asynchronous, in order and at most once; a
+  handler gets 2 seconds, the queue holds 100 events per extension, and a
+  failing handler only reaches the log.
+- `server.storage` is JSON under string keys, private to the extension, kept
+  across restarts and updates. The value must be JSON: that is why `Streak` is a
   `type`, not an `interface`. Ceilings: key 128 characters, value 64 KiB, 256
   keys, 1 MiB in total; exceeding one throws `StorageQuotaError`.
-- `advance` is a pure function exported for the test. The hidden command
-  `acme.hello.data` is how the panel reads the stored value.
+- `advance` is a pure function in its own file, so the test can import it. The
+  hidden command `acme.hello.data` is how the panel reads the stored value.
+
+## The client part
+
+File `src/client.ts` (events):
+
+```ts
+import { defineClient } from '@dolphy-app/extension-sdk';
+import { StreakPanel } from './streak-panel.ts';
+
+// runs in the app window: the panel is a Vue component the app draws
+export const client = defineClient((c) => {
+  c.addPanel({
+    id: 'acme.hello.view',
+    title: { en: 'Streak', ru: 'Серия' },
+    component: StreakPanel,
+  });
+});
+```
+
+File `src/streak-panel.ts` (events):
+
+```ts
+import { usePanel } from '@dolphy-app/extension-sdk/client';
+import { defineComponent, h, ref, watchEffect } from 'vue';
+import type { Streak } from './streak.ts';
+
+// the only way to the data is `panel.call` to the commands of the server
+export const StreakPanel = defineComponent({
+  setup() {
+    const panel = usePanel();
+    const text = ref('');
+    // the command opens the panel again with new properties: ask again
+    watchEffect(async () => {
+      void panel.props;
+      const streak = (await panel.call('acme.hello.data')) as Streak;
+      text.value =
+        streak.days === 0
+          ? 'No streak yet.'
+          : `Streak: ${streak.days} days, last day ${streak.last}`;
+    });
+    return () => h('p', text.value);
+  },
+});
+```
+
+- The panel is a Vue component registered with `client.addPanel`: `usePanel()`
+  gives it `call` for the commands of the server part and the reactive `props`.
+  Reading `panel.props` inside `watchEffect` makes the panel ask again when the
+  `show` command opens it with new properties.
 
 ## The tests
 
@@ -146,15 +170,20 @@ File `test/index.test.ts` (events):
 
 ```ts
 // @vitest-environment happy-dom
-import type { LearningEventPayloads } from '@dolphy-app/extension-api';
+import { PANEL_HANDLE_KEY } from '@dolphy-app/extension-sdk';
+import type {
+  JsonValue,
+  LearningEventPayloads,
+  PanelHandle,
+} from '@dolphy-app/extension-sdk';
 import {
-  createMemoryStorage,
-  loadCommands,
-  loadEvents,
-  loadPanel,
+  createTestClient,
+  createTestServer,
 } from '@dolphy-app/extension-sdk/testing';
 import { afterEach, describe, expect, it } from 'vitest';
-import { host, panels } from '../src/index.ts';
+import { createApp, h, nextTick, shallowReactive } from 'vue';
+import { client, server } from '../src/index.ts';
+import { StreakPanel } from '../src/streak-panel.ts';
 
 const disposables: { dispose(): unknown }[] = [];
 afterEach(async () => {
@@ -173,44 +202,65 @@ const attempt = (day: string, outcome: Attempt['outcome'] = 'passed'): Attempt =
   at: Date.parse(`${day}T12:00:00Z`),
 });
 
-const load = async () => {
-  const storage = createMemoryStorage();
-  const events = await loadEvents(host, {
-    storage,
-    declared: ['attempt.closed'],
+const start = async () => {
+  const running = await createTestServer(server, { extensionId: 'acme.hello' });
+  disposables.push(running);
+  return running;
+};
+
+// draws the panel the way the app does: the handle is provided to the component
+const mountPanel = async (call: PanelHandle['call']) => {
+  const handle = shallowReactive({
+    panelId: 'acme.hello.view',
+    props: undefined as JsonValue | undefined,
+    context: { courseId: null },
+    call,
   });
-  const commands = await loadCommands(host, {
-    storage,
-    declaredCommands: ['acme.hello.show', 'acme.hello.data'],
-    declaredPanels: ['acme.hello.view'],
+  const host = document.createElement('div');
+  document.body.append(host);
+  const app = createApp({ render: () => h(StreakPanel) });
+  app.provide(PANEL_HANDLE_KEY, handle);
+  app.mount(host);
+  disposables.push({
+    dispose: () => {
+      app.unmount();
+      host.remove();
+    },
   });
-  disposables.push(events, commands);
-  return { storage, events, commands };
+  // the panel asks a command: wait for the reply, then for the redraw
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await nextTick();
+  return host;
 };
 
 describe('acme.hello: events and storage', () => {
+  it('subscribes to attempt.closed', async () => {
+    const running = await start();
+    expect(running.registration.events).toEqual(['attempt.closed']);
+  });
+
   it('counts consecutive days, ignores a repeat on the same day', async () => {
-    const { storage, events } = await load();
-    await events.emit('attempt.closed', attempt('2026-10-01'));
-    await events.emit('attempt.closed', attempt('2026-10-01'));
-    await events.emit('attempt.closed', attempt('2026-10-02'));
-    expect(await storage.get('streak')).toEqual({
+    const running = await start();
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    await running.events.emit('attempt.closed', attempt('2026-10-02'));
+    expect(await running.storage.get('streak')).toEqual({
       days: 2,
       last: '2026-10-02',
     });
   });
 
   it('a skipped day starts over; giving up leaves the streak alone', async () => {
-    const { storage, events } = await load();
-    await events.emit('attempt.closed', attempt('2026-10-01'));
-    await events.emit('attempt.closed', attempt('2026-10-02'));
-    await events.emit('attempt.closed', attempt('2026-10-03', 'gave-up'));
-    expect(await storage.get('streak')).toEqual({
+    const running = await start();
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    await running.events.emit('attempt.closed', attempt('2026-10-02'));
+    await running.events.emit('attempt.closed', attempt('2026-10-03', 'gave-up'));
+    expect(await running.storage.get('streak')).toEqual({
       days: 2,
       last: '2026-10-02',
     });
-    await events.emit('attempt.closed', attempt('2026-10-05'));
-    expect(await storage.get('streak')).toEqual({
+    await running.events.emit('attempt.closed', attempt('2026-10-05'));
+    expect(await running.storage.get('streak')).toEqual({
       days: 1,
       last: '2026-10-05',
     });
@@ -219,46 +269,56 @@ describe('acme.hello: events and storage', () => {
 
 describe('acme.hello: commands and panel', () => {
   it('without a streak the show command notifies, the data command returns zeros', async () => {
-    const { commands } = await load();
-    expect(await commands.run('acme.hello.show')).toMatchObject({ kind: 'notify' });
-    expect(await commands.run('acme.hello.data')).toEqual({
+    const running = await start();
+    expect(await running.commands.run('acme.hello.show')).toMatchObject({
+      kind: 'notify',
+    });
+    expect(await running.commands.run('acme.hello.data')).toEqual({
       kind: 'data',
       value: { days: 0, last: '' },
     });
   });
 
   it('with a streak the show command opens the panel with the days', async () => {
-    const { events, commands } = await load();
-    await events.emit('attempt.closed', attempt('2026-10-01'));
-    expect(await commands.run('acme.hello.show')).toEqual({
+    const running = await start();
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    expect(await running.commands.run('acme.hello.show')).toEqual({
       kind: 'openPanel',
       panelId: 'acme.hello.view',
       props: { days: 1 },
     });
   });
 
+  it('the client adds the panel the show command opens', async () => {
+    const running = await createTestClient(client, { extensionId: 'acme.hello' });
+    disposables.push(running);
+    expect(running.panels.map((panel) => panel.id)).toEqual(['acme.hello.view']);
+  });
+
   it('the panel shows what the data command returns', async () => {
-    const { events, commands } = await load();
-    await events.emit('attempt.closed', attempt('2026-10-01'));
-    const panel = await loadPanel(panels, 'acme.hello.view', {
-      call: async (commandId) => {
-        const result = await commands.run(commandId);
-        return result.kind === 'data' ? result.value : undefined;
-      },
+    const running = await start();
+    await running.events.emit('attempt.closed', attempt('2026-10-01'));
+    const panel = await mountPanel(async (commandId) => {
+      const result = await running.commands.run(commandId);
+      return result.kind === 'data' ? (result.value as JsonValue) : undefined;
     });
-    disposables.push(panel);
-    expect(panel.container.querySelector('p')?.textContent).toBe(
+    expect(panel.querySelector('p')?.textContent).toBe(
       'Streak: 1 days, last day 2026-10-01',
     );
   });
 });
 ```
 
-`loadEvents` activates the extension and gives `emit(name, payload)`, so the test
-sends events the way the host delivers them. `createMemoryStorage` has the same
-ceilings as the app. Pass the same `storage` to `loadEvents` and `loadCommands`
-and both see one state. Unlike the host, the helpers do not swallow a handler's
-failure and do not count the 2 seconds.
+`createTestServer(server, { extensionId })` starts `server`, and
+`running.events.emit(name, payload)` delivers an event the way the host does and
+awaits the handler; `running.registration.events` lists the subscriptions.
+`running.storage` is in memory with the same ceilings as the app, and the test
+reads what the handler wrote. Unlike the host, the harness does not swallow a
+handler's failure and does not count the 2 seconds.
+
+The panel is mounted with `createApp` in `happy-dom`;
+`app.provide(PANEL_HANDLE_KEY, handle)` gives it a handle whose `call` runs the
+real command handlers of the running server.
 
 ## Try and ship