@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 CHANGED
@@ -1,3 +1,71 @@
1
- # Temporary Holding Version
1
+ # NEXT Surfaces SDK
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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`.
@@ -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
+ };
@@ -0,0 +1,3 @@
1
+ export declare const SURFACE_PROTOCOL_VERSION = 1;
2
+ export declare const SURFACE_CONNECT = "next.surface.connect";
3
+ export declare const GET_MEMORY = "memories.get";
@@ -0,0 +1,3 @@
1
+ export const SURFACE_PROTOCOL_VERSION = 1;
2
+ export const SURFACE_CONNECT = 'next.surface.connect';
3
+ export const GET_MEMORY = 'memories.get';
package/package.json CHANGED
@@ -1,6 +1,27 @@
1
1
  {
2
- "name": "@collaborne/surfaces-sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ }