@collaborne/surfaces-sdk 0.0.0-stage → 0.1.15
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/README.md +70 -2
- package/dist/index.d.ts +36 -0
- package/dist/index.js +76 -0
- package/dist/protocol.d.ts +3 -0
- package/dist/protocol.js +3 -0
- package/package.json +26 -5
package/README.md
CHANGED
|
@@ -1,3 +1,71 @@
|
|
|
1
|
-
#
|
|
1
|
+
# NEXT Surfaces SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Use this browser SDK to access NEXT data and launch parameters from a Surface.
|
|
4
|
+
The SDK connects to the sandbox host, which authenticates and authorizes
|
|
5
|
+
requests. Your Surface does not need an API token.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install @collaborne/surfaces-sdk
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Read a memory
|
|
14
|
+
|
|
15
|
+
Load this code from your Surface's browser entry point so the SDK can
|
|
16
|
+
receive the host's connection message when the iframe loads.
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { next } from '@collaborne/surfaces-sdk';
|
|
20
|
+
|
|
21
|
+
async function render() {
|
|
22
|
+
await next.ready();
|
|
23
|
+
const memoryId = next.context.m;
|
|
24
|
+
if (!memoryId) {
|
|
25
|
+
document.body.textContent = 'Missing memory ID.';
|
|
26
|
+
return;
|
|
27
|
+
}
|
|
28
|
+
const memory = await next.memories.get(memoryId);
|
|
29
|
+
document.body.textContent = memory.title ?? memory.id;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
void render().catch(error => {
|
|
33
|
+
document.body.textContent = String(error);
|
|
34
|
+
});
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
To try it locally, start your app's dev server and run the NEXT sandbox with
|
|
38
|
+
a project-scoped API token in `NEXT_API_TOKEN`.
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
npx @collaborne/surfaces-dev \
|
|
42
|
+
--surface-url 'http://127.0.0.1:5173/' \
|
|
43
|
+
--api-token "$NEXT_API_TOKEN"
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Open `http://127.0.0.1:4174/?m=MEMORY_ID` with a memory ID from that project.
|
|
47
|
+
The sandbox forwards launch parameters as context. This example uses `m`
|
|
48
|
+
as its memory ID parameter.
|
|
49
|
+
|
|
50
|
+
## Public API
|
|
51
|
+
|
|
52
|
+
- `next.ready()` resolves when the host connects. Load the SDK in a Surface
|
|
53
|
+
iframe with a compatible host.
|
|
54
|
+
- `next.context` contains the host's launch parameters as string values.
|
|
55
|
+
Read it after `next.ready()` resolves.
|
|
56
|
+
- `next.memories.get(id)` returns a `SurfaceMemory`.
|
|
57
|
+
- `next.memories.query({ focusQuery }, offset)` returns `items` and optional
|
|
58
|
+
`pagination.total`. Pass a NEXT Focus query and a zero-based result offset.
|
|
59
|
+
- `next.memories.create({ title, description, source, tagId? })` returns the
|
|
60
|
+
created memory. `tagId` is optional.
|
|
61
|
+
- `next.memories.update({ id, title, description })` updates a memory.
|
|
62
|
+
- `next.memories.delete(id)` deletes a memory.
|
|
63
|
+
|
|
64
|
+
The local sandbox supports all five memory operations. The NEXT share host
|
|
65
|
+
supports `get` and can enable `query` for a Surface. Write operations require
|
|
66
|
+
a host that implements them. Memory requests reject with an error if the host
|
|
67
|
+
rejects them or fails to respond within 15 seconds after connection.
|
|
68
|
+
|
|
69
|
+
TypeScript users can import `SurfaceMemory`, `QueryMemoriesFilter`,
|
|
70
|
+
`QueryMemoriesResult`, `CreateMemoryParams`, and `UpdateMemoryParams` from
|
|
71
|
+
`@collaborne/surfaces-sdk`.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
export interface SurfaceMemory {
|
|
2
|
+
id: string;
|
|
3
|
+
title?: string;
|
|
4
|
+
description?: string;
|
|
5
|
+
source?: string;
|
|
6
|
+
tag_ids?: string[];
|
|
7
|
+
evidence_text?: string;
|
|
8
|
+
contributor_name?: string | null;
|
|
9
|
+
recordedAt?: string;
|
|
10
|
+
}
|
|
11
|
+
export type CreateMemoryParams = Required<Pick<SurfaceMemory, 'title' | 'description' | 'source'>> & {
|
|
12
|
+
tagId?: string;
|
|
13
|
+
};
|
|
14
|
+
export type UpdateMemoryParams = Required<Pick<SurfaceMemory, 'id' | 'title' | 'description'>>;
|
|
15
|
+
export interface QueryMemoriesFilter {
|
|
16
|
+
focusQuery: string;
|
|
17
|
+
}
|
|
18
|
+
export interface QueryMemoriesResult {
|
|
19
|
+
items: SurfaceMemory[];
|
|
20
|
+
pagination?: {
|
|
21
|
+
total?: number;
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
declare function connect(): Promise<MessagePort>;
|
|
25
|
+
export declare const next: {
|
|
26
|
+
readonly context: Record<string, string | undefined>;
|
|
27
|
+
ready: typeof connect;
|
|
28
|
+
memories: {
|
|
29
|
+
get: (id: string) => Promise<SurfaceMemory>;
|
|
30
|
+
query: (filter: QueryMemoriesFilter, offset: number) => Promise<QueryMemoriesResult>;
|
|
31
|
+
create: (params: CreateMemoryParams) => Promise<SurfaceMemory>;
|
|
32
|
+
update: (params: UpdateMemoryParams) => Promise<void>;
|
|
33
|
+
delete: (id: string) => Promise<void>;
|
|
34
|
+
};
|
|
35
|
+
};
|
|
36
|
+
export {};
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
import { GET_MEMORY, SURFACE_CONNECT, SURFACE_PROTOCOL_VERSION, } from './protocol.js';
|
|
2
|
+
const REQUEST_TIMEOUT_MS = 15_000;
|
|
3
|
+
let context = {};
|
|
4
|
+
let portPromise;
|
|
5
|
+
function connect() {
|
|
6
|
+
if (portPromise) {
|
|
7
|
+
return portPromise;
|
|
8
|
+
}
|
|
9
|
+
portPromise = new Promise(resolve => {
|
|
10
|
+
function onConnect(event) {
|
|
11
|
+
if (event.source !== window.parent ||
|
|
12
|
+
event.data?.type !== SURFACE_CONNECT ||
|
|
13
|
+
event.data?.version !== SURFACE_PROTOCOL_VERSION ||
|
|
14
|
+
!event.ports[0]) {
|
|
15
|
+
return;
|
|
16
|
+
}
|
|
17
|
+
context = event.data.context ?? {};
|
|
18
|
+
const port = event.ports[0];
|
|
19
|
+
port.start();
|
|
20
|
+
window.removeEventListener('message', onConnect);
|
|
21
|
+
resolve(port);
|
|
22
|
+
}
|
|
23
|
+
window.addEventListener('message', onConnect);
|
|
24
|
+
});
|
|
25
|
+
return portPromise;
|
|
26
|
+
}
|
|
27
|
+
// The parent transfers the port on iframe load, which can precede a React effect.
|
|
28
|
+
if (typeof window !== 'undefined' && window.parent !== window) {
|
|
29
|
+
void connect();
|
|
30
|
+
}
|
|
31
|
+
async function request(input) {
|
|
32
|
+
const port = await connect();
|
|
33
|
+
const id = crypto.randomUUID();
|
|
34
|
+
return new Promise((resolve, reject) => {
|
|
35
|
+
const requestState = { timeout: 0 };
|
|
36
|
+
const onMessage = (event) => {
|
|
37
|
+
if (event.data?.version !== SURFACE_PROTOCOL_VERSION ||
|
|
38
|
+
event.data.id !== id) {
|
|
39
|
+
return;
|
|
40
|
+
}
|
|
41
|
+
window.clearTimeout(requestState.timeout);
|
|
42
|
+
port.removeEventListener('message', onMessage);
|
|
43
|
+
if (event.data.error) {
|
|
44
|
+
reject(new Error(event.data.error.message));
|
|
45
|
+
return;
|
|
46
|
+
}
|
|
47
|
+
resolve(event.data.result);
|
|
48
|
+
};
|
|
49
|
+
requestState.timeout = window.setTimeout(() => {
|
|
50
|
+
port.removeEventListener('message', onMessage);
|
|
51
|
+
reject(new Error(`NEXT request timed out (${input.operation})`));
|
|
52
|
+
}, REQUEST_TIMEOUT_MS);
|
|
53
|
+
port.addEventListener('message', onMessage);
|
|
54
|
+
port.postMessage({
|
|
55
|
+
version: SURFACE_PROTOCOL_VERSION,
|
|
56
|
+
id,
|
|
57
|
+
...input,
|
|
58
|
+
});
|
|
59
|
+
});
|
|
60
|
+
}
|
|
61
|
+
export const next = {
|
|
62
|
+
get context() {
|
|
63
|
+
return context;
|
|
64
|
+
},
|
|
65
|
+
ready: connect,
|
|
66
|
+
memories: {
|
|
67
|
+
get: (id) => request({ operation: GET_MEMORY, params: { id } }),
|
|
68
|
+
query: (filter, offset) => request({
|
|
69
|
+
operation: 'memories.query',
|
|
70
|
+
params: { ...filter, offset },
|
|
71
|
+
}),
|
|
72
|
+
create: (params) => request({ operation: 'memories.create', params }),
|
|
73
|
+
update: (params) => request({ operation: 'memories.update', params }),
|
|
74
|
+
delete: (id) => request({ operation: 'memories.delete', params: { id } }),
|
|
75
|
+
},
|
|
76
|
+
};
|
package/dist/protocol.js
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,27 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@collaborne/surfaces-sdk",
|
|
3
|
+
"version": "0.1.15",
|
|
4
|
+
"description": "Browser SDK for applications running in the NEXT Surface sandbox",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git+https://github.com/Collaborne/carrot-surfaces.git",
|
|
8
|
+
"directory": "packages/surfaces-sdk"
|
|
9
|
+
},
|
|
10
|
+
"type": "module",
|
|
11
|
+
"exports": {
|
|
12
|
+
".": {
|
|
13
|
+
"types": "./dist/index.d.ts",
|
|
14
|
+
"default": "./dist/index.js"
|
|
15
|
+
}
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"dist"
|
|
19
|
+
],
|
|
20
|
+
"publishConfig": {
|
|
21
|
+
"access": "public"
|
|
22
|
+
},
|
|
23
|
+
"scripts": {
|
|
24
|
+
"build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json",
|
|
25
|
+
"prepack": "npm run build"
|
|
26
|
+
}
|
|
27
|
+
}
|