@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 +1 -1
- package/frame/sdk.ts +80 -1
- package/package.json +1 -1
- package/protocol.ts +15 -0
- package/types/index.d.ts +85 -2
- package/version.json +1 -1
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.
|
|
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.
|
|
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