@cxxi-lab/hubbyware-sdk 3.5.0 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/frame/index.ts CHANGED
@@ -3,6 +3,6 @@
3
3
  // the base stylesheet, extracted into runtime.css at build (the frame page links it)
4
4
  import './runtime.css'
5
5
 
6
- export { call, collection, nav, notifications, oauth, settings, useInit, usePath, type Doc, type OAuthConnection } from './sdk'
6
+ export { call, collection, nav, notifications, oauth, settings, tasks, useInit, usePath, type Doc, type OAuthConnection, type Task, type TaskState } from './sdk'
7
7
  export { defineHubby, start, type HubbyDefinition, type HubbyPageDefinition } from './hubby'
8
8
  export { useBackHandler, useMediaQuery } from '@cxxi-lab/hubbyware-ui'
package/frame/sdk.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { useEffect, useState } from 'react'
2
2
  import { onBackDepth, handleBack } from '@cxxi-lab/hubbyware-ui'
3
- import { PROTOCOL, type Envelope, type GuestMessage, type HostMessage, type HubbyPage } from '../protocol'
3
+ import { PROTOCOL, type Envelope, type GuestMessage, type HostMessage, type HubbyPage, type TaskState } from '../protocol'
4
4
 
5
5
  /**
6
6
  * The hubby SDK inside its frame (prototype): every call goes to the host by message and comes
@@ -11,6 +11,7 @@ let nextId = 1
11
11
  const pending = new Map<number, { resolve: (v: unknown) => void, reject: (e: Error) => void }>()
12
12
  const initListeners = new Set<(init: Extract<HostMessage, { type: 'init' }>) => void>()
13
13
  const pathListeners = new Set<(path: string) => void>()
14
+ const taskListeners = new Map<string, Set<(state: TaskState) => void>>()
14
15
  let init: Extract<HostMessage, { type: 'init' }> | null = null
15
16
 
16
17
  function post(message: GuestMessage) {
@@ -49,6 +50,7 @@ window.addEventListener('message', event => {
49
50
  else if (m.type === 'back') handleBack()
50
51
  else if (m.type === 'path') pathListeners.forEach(l => l(m.path))
51
52
  else if (m.type === 'theme') applyTheme(m.theme, m.accent)
53
+ else if (m.type === 'task') taskListeners.get(m.task.id)?.forEach(l => l(m.task))
52
54
  })
53
55
 
54
56
  /** A call to the host (the platform API, through it). */
@@ -124,6 +126,83 @@ export const oauth = {
124
126
  accessToken: (connection: string) => call<{ accessToken: string, expiresAt: number }>('oauth.accessToken', connection),
125
127
  }
126
128
 
129
+ export type { TaskState }
130
+
131
+ const finished = (state: TaskState) => state.status === 'succeeded' || state.status === 'failed' || state.status === 'cancelled'
132
+
133
+ /** A task of the hubby, through its host: followed by a hook or a stream, then its result. */
134
+ export interface Task {
135
+ readonly id: string
136
+ readonly state: TaskState
137
+ on(listener: (state: TaskState) => void): () => void
138
+ events(signal?: AbortSignal): AsyncIterableIterator<TaskState>
139
+ result<T>(): Promise<T>
140
+ cancel(): Promise<TaskState>
141
+ }
142
+
143
+ function frameTask(initial: TaskState): Task {
144
+ let state = initial
145
+ const on = (listener: (state: TaskState) => void) => {
146
+ listener(state)
147
+ if (finished(state)) return () => {}
148
+ let set = taskListeners.get(state.id)
149
+ if (!set) {
150
+ taskListeners.set(state.id, set = new Set())
151
+ void call('tasks.follow', state.id)
152
+ }
153
+ const wrapped = (next: TaskState) => { state = next; listener(next) }
154
+ set.add(wrapped)
155
+ return () => {
156
+ set.delete(wrapped)
157
+ if (set.size === 0) {
158
+ taskListeners.delete(state.id)
159
+ void call('tasks.unfollow', state.id)
160
+ }
161
+ }
162
+ }
163
+ return {
164
+ id: state.id,
165
+ get state() { return state },
166
+ on,
167
+ async *events(signal?: AbortSignal) {
168
+ const queue: TaskState[] = []
169
+ let wake: (() => void) | null = null
170
+ const stop = on(s => { queue.push(s); wake?.() })
171
+ const abort = () => wake?.()
172
+ signal?.addEventListener('abort', abort)
173
+ try {
174
+ while (!signal?.aborted) {
175
+ if (queue.length === 0) await new Promise<void>(resolve => { wake = resolve })
176
+ wake = null
177
+ while (queue.length > 0) {
178
+ const s = queue.shift()!
179
+ yield s
180
+ if (finished(s)) return
181
+ }
182
+ }
183
+ }
184
+ finally {
185
+ stop()
186
+ signal?.removeEventListener('abort', abort)
187
+ }
188
+ },
189
+ result: <T>() => call<T>('tasks.result', state.id),
190
+ cancel: async () => (state = await call<TaskState>('tasks.cancel', state.id))
191
+ }
192
+ }
193
+
194
+ /**
195
+ * The hubby's tasks (server docs/plan-tasks.md): a capability's call (/api/cap/…) run in the
196
+ * background by the host, as the hubby; followed live, its result read once finished.
197
+ */
198
+ export const tasks = {
199
+ /** `options`: the call's method, JSON body (a string) and headers */
200
+ start: async (path: string, options: { method?: string, body?: string, headers?: Record<string, string> } = {}) =>
201
+ frameTask(await call<TaskState>('tasks.start', path, options)),
202
+ get: async (id: string) => frameTask(await call<TaskState>('tasks.get', id)),
203
+ list: (status?: TaskState['status']) => call<TaskState[]>('tasks.list', status)
204
+ }
205
+
127
206
  export function register(pages: HubbyPage[], sections: Record<string, unknown>) {
128
207
  post({ type: 'register', pages, sections })
129
208
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cxxi-lab/hubbyware-sdk",
3
- "version": "3.5.0",
3
+ "version": "3.6.0",
4
4
  "description": "The contract of Hubbyware's hubbies: the SDK a hubby builds on (provided by the host app at run time), and the SDK of the hubbies running isolated in their frame. Formerly @cxxi-lab/hub-sdk.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/protocol.ts CHANGED
@@ -15,6 +15,19 @@ export interface HubbyPage {
15
15
  section?: string
16
16
  }
17
17
 
18
+ /** A task of the hubby (server docs/plan-tasks.md), as its frame hears it. */
19
+ export interface TaskState {
20
+ id: string
21
+ operation: string
22
+ status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled'
23
+ progress: { done: number, total: number | null, message: string | null } | null
24
+ httpStatus: number | null
25
+ error: string | null
26
+ createdAt: string
27
+ startedAt: string | null
28
+ finishedAt: string | null
29
+ }
30
+
18
31
  /** Guest → host. */
19
32
  export type GuestMessage =
20
33
  | { type: 'ready', at: number }
@@ -34,6 +47,8 @@ export type HostMessage =
34
47
  | { type: 'path', path: string }
35
48
  /** the app's theme or accent changed */
36
49
  | { type: 'theme', theme: 'light' | 'dark', accent?: string }
50
+ /** a task the frame follows changed (`tasks.follow`): its state */
51
+ | { type: 'task', task: TaskState }
37
52
 
38
53
  export const PROTOCOL = 'hubby/1'
39
54
 
package/types/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- // @cxxi-lab/hubbyware-sdk 3.5.0: generated by app/scripts/emit-sdk-types.mjs from app/src/sdk — do not edit.
1
+ // @cxxi-lab/hubbyware-sdk 3.6.0: generated by app/scripts/emit-sdk-types.mjs from app/src/sdk — do not edit.
2
2
  import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
3
3
  import { ComponentType, HTMLInputTypeAttribute, MouseEventHandler, ReactNode, TdHTMLAttributes, ThHTMLAttributes } from 'react';
4
4
 
@@ -13,6 +13,67 @@ export declare class ApiError extends Error {
13
13
  }
14
14
  /** Best human-readable message for a caught error: server detail first. */
15
15
  export declare function errorMessage(err: unknown, fallback?: string): string;
16
+ /**
17
+ * A hubby's tasks (server docs/plan-tasks.md): a capability's call it runs in the background, and
18
+ * follows by a hook (`task.on`) or a stream (`for await … of task.events()`), then reads its
19
+ * result (`task.result()`: the response the call got, as the call itself would have given it).
20
+ * The calls are the hubby's (its token): it sees its own tasks only.
21
+ *
22
+ * Live: the server publishes each change on the hubby's topic (Mercure, /api/cap/tasks/live), one
23
+ * stream per hubby for all its tasks, open while some task is followed; without a hub, or while
24
+ * it is cut, the followed tasks are polled.
25
+ */
26
+ export type TaskStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
27
+ export interface TaskProgress {
28
+ done: number;
29
+ total: number | null;
30
+ message: string | null;
31
+ }
32
+ /** A task, as its hubby sees it. */
33
+ export interface TaskState {
34
+ id: string;
35
+ /** the call: `POST /api/cap/…` */
36
+ operation: string;
37
+ status: TaskStatus;
38
+ progress: TaskProgress | null;
39
+ /** finished: the status of the response its call got */
40
+ httpStatus: number | null;
41
+ error: string | null;
42
+ createdAt: string;
43
+ startedAt: string | null;
44
+ finishedAt: string | null;
45
+ }
46
+ export interface Task {
47
+ readonly id: string;
48
+ /** its state as last heard */
49
+ readonly state: TaskState;
50
+ /** Calls `listener` at each change (the current state first); gives back how to stop. */
51
+ on(listener: (state: TaskState) => void): () => void;
52
+ /** Its changes, the current state first, until it is finished (or `signal` aborts). */
53
+ events(signal?: AbortSignal): AsyncIterableIterator<TaskState>;
54
+ /**
55
+ * Once finished, what its call would have given: its JSON (an ApiError for a failed call, the
56
+ * operation's own error), a TaskCancelledError when cancelled.
57
+ */
58
+ result<T>(): Promise<T>;
59
+ /** Cancels it: queued, at once; running, at the operation's next report. */
60
+ cancel(): Promise<TaskState>;
61
+ }
62
+ export interface TasksApi {
63
+ /**
64
+ * Runs a capability's call as a task (`Prefer: respond-async`). An operation that can't run as
65
+ * one runs at once: the task given back is already finished, its result the call's.
66
+ */
67
+ start(path: string, options?: RequestInit): Promise<Task>;
68
+ /** One of the hubby's tasks, by its id. */
69
+ get(id: string): Promise<Task>;
70
+ /** The hubby's tasks, newest first (finished ones are kept 24 h). */
71
+ list(status?: TaskStatus): Promise<TaskState[]>;
72
+ }
73
+ export declare class TaskCancelledError extends Error {
74
+ readonly task: string;
75
+ constructor(task: string);
76
+ }
16
77
  export type StreamEventHandler = (event: string, data: unknown) => void;
17
78
  /**
18
79
  * Parses a text/event-stream body, calling onEvent with each event name and its
@@ -678,6 +739,13 @@ export interface HubbyInfo {
678
739
  requiresCapabilities?: string[];
679
740
  /** shared features (HubbySupport) */
680
741
  supports?: string[];
742
+ /**
743
+ * its way out (server docs/plan-reseau-vpn.md): `{"egress": "vpn"}`, its webviews and players
744
+ * through the user's VPN (the platform's 'vpn' support then; formerly `supports: ['vpn']`)
745
+ */
746
+ network?: {
747
+ egress?: string;
748
+ } | string;
681
749
  }
682
750
  export type Described = Pick<HubbyManifest, "label" | "description" | "local" | "requires" | "requiresCapabilities" | "supports">;
683
751
  /** The manifest's descriptive part, from its hubby.json (one source for both). */
@@ -1042,6 +1110,20 @@ export declare function formatDuration(seconds: number | null): string;
1042
1110
  export declare function formatDate(iso: string | null): string;
1043
1111
  /** A call to the server's API, as the hubby: its JSON (nothing on a 204), an ApiError otherwise. */
1044
1112
  export declare function api<T>(path: string, options?: RequestInit, retry?: boolean): Promise<T>;
1113
+ /**
1114
+ * The hubby's tasks (server docs/plan-tasks.md): a capability's call run in the background, the
1115
+ * hubby choosing at each call. In sync, `await api(path, options)`: a promise of the result (an
1116
+ * operation always run as a task is awaited the same, unseen). As a task:
1117
+ *
1118
+ * const task = await tasks.start('/api/cap/scrape/video', { method: 'POST', body })
1119
+ * task.on(state => …) // a hook: queued, running (progress), finished
1120
+ * for await (const state of task.events()) … // or a stream, until it is finished
1121
+ * const video = await task.result() // what the call would have given
1122
+ * await task.cancel()
1123
+ *
1124
+ * `tasks.list()`: its tasks, running and recent (24 h); `tasks.get(id)`: one again (after a reload).
1125
+ */
1126
+ export declare const tasks: TasksApi;
1045
1127
  /**
1046
1128
  * Opens an authenticated server-sent event stream, as the hubby — over fetch, so it can POST a
1047
1129
  * body and carry the token — and resolves once the server closes it.
@@ -1055,7 +1137,8 @@ export declare function getApiBaseUrl(_path?: string): string;
1055
1137
  /**
1056
1138
  * The partition of the hubby's <webview>s (desktop): its own session, its sites' cookies and storage
1057
1139
  * apart from the other hubbies', going out through the VPN when it declares so (server
1058
- * docs/plan-reseau-vpn.md). `<webview partition={webviewPartition} …>`.
1140
+ * docs/plan-reseau-vpn.md). `<webview partition={webviewPartition} …>`. A webview outside its
1141
+ * hubby's partition is refused (an SDK imported without a hubby: none).
1059
1142
  */
1060
1143
  export declare const webviewPartition: string;
1061
1144
  /**
package/version.json CHANGED
@@ -1,4 +1,4 @@
1
1
  {
2
- "version": "3.5.0",
2
+ "version": "3.6.0",
3
3
  "compatible": []
4
4
  }