@tabs-and-spaces/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tabs & Spaces
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @tabs-and-spaces/sdk
 
-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.
+Build apps for [Tabs & Spaces](https://tabsandspaces.dev): a Custom tab's page talks to the
+workspace showing it, and your server checks who's asking. No dependencies.
+
+```sh
+npm install @tabs-and-spaces/sdk
+```
+
+**In your Custom tab's page:**
+
+```ts
+import { connect } from "@tabs-and-spaces/sdk";
+
+const tands = await connect();
+document.querySelector("h1")!.textContent = `Hello, ${tands.context.user.name}`;
+
+// Data your manifest declares, kept by the workspace.
+await tands.collection("notes").create({ text: "Ship it" });
+```
+
+**On your server** (Node 22+, Deno, Bun, Cloudflare Workers):
+
+```ts
+import { fetchKeys, verifyToken } from "@tabs-and-spaces/sdk/server";
+
+const WORKSPACE = "https://chat.acme.com"; // the deployment you serve
+const keys = await fetchKeys(WORKSPACE); // cache these
+
+const { context } = await verifyToken(token, {
+  keys,
+  audience: "https://notes.example.com", // your app's origin
+  issuer: WORKSPACE,
+});
+```
+
+Start an app in a minute: `npx tands new my-app` ([tands](https://www.npmjs.com/package/tands)).
+
+Docs: **https://developer.tabsandspaces.dev/sdk/**
+
+MIT licensed.

package/dist/client.d.ts

@@ -0,0 +1,92 @@
+import { type DataRecord, type DataRequest, type DataScope, type EventKey, type TabContext, type Theme } from "./protocol.js";
+/** A refusal from the workspace, with its reason's code (like `INVALID` or `FORBIDDEN`). */
+export declare class WorkspaceError extends Error {
+    readonly code: string | null;
+    constructor(message: string, code: string | null);
+}
+/** Free-form values in one scope: settings, state, anything up to 16 KB each. */
+export interface Values {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    list(): Promise<Record<string, unknown>>;
+}
+/** Records in one of the collections your manifest declares. */
+export interface Collection<T extends Record<string, unknown> = Record<string, unknown>> {
+    list(options?: {
+        where?: Partial<Record<keyof T & string, string | number | boolean | null>>;
+        orderBy?: {
+            field: (keyof T & string) | "createdAt" | "updatedAt";
+            direction?: "asc" | "desc";
+        };
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        records: DataRecord<T>[];
+        cursor: string | null;
+    }>;
+    get(id: string): Promise<DataRecord<T>>;
+    create(data: T): Promise<DataRecord<T>>;
+    /** The fields that change; `null` clears one that isn't required. */
+    update(id: string, data: Partial<{
+        [K in keyof T]: T[K] | null;
+    }>): Promise<DataRecord<T>>;
+    delete(id: string): Promise<void>;
+}
+export interface Connection {
+    /** Who's looking, and where. */
+    readonly context: TabContext;
+    /** The workspace's theme now. */
+    readonly theme: Theme;
+    /**
+     * A token for your server: who's looking, signed by the workspace. Fresh
+     * (a new one is fetched when this one has less than a minute left).
+     */
+    token(): Promise<string>;
+    /** Free-form values: the workspace's, this space's, this tab's, or the reader's own. */
+    values(scope: DataScope): Values;
+    /** Records in a collection your manifest declares (its scope is the manifest's). */
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): Collection<T>;
+    /** Any data request, as sent (what `values()` and `collection()` use). */
+    data(request: DataRequest): Promise<unknown>;
+    /**
+     * Reports something that happened, as your manifest's `events` declare it
+     * (triggers in this space may start a task). Resolves once it's taken.
+     */
+    emit(name: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Asks for a key your server can report events with, in this tab, whenever they
+     * happen (a webhook from another service, say). The person sees what's asked and
+     * allows it (only those who manage the space's tabs can); a new key replaces this
+     * tab's last one. Fails with `DECLINED` if they don't, `FORBIDDEN` if they can't.
+     */
+    requestEventKey(): Promise<EventKey>;
+    /**
+     * Opens a new trigger in this space, starting on one of your manifest's events in this
+     * tab (or the first, without `event`): the person sets the task and saves it. Fails
+     * with `NO_TASKS_TAB` when the space has no Tasks tab to keep triggers in.
+     */
+    openTrigger(event?: string): Promise<void>;
+    /** Called when the reader switches between light and dark. Returns an unsubscribe. */
+    onTheme(listener: (theme: Theme) => void): () => void;
+    /** Stops listening. */
+    close(): void;
+}
+export interface ConnectOptions {
+    /** Give up after this long without the workspace answering (default 10 s). */
+    timeoutMs?: number;
+    /** For tests: the window the page runs in. */
+    window?: Window;
+}
+/**
+ * Connects a Custom tab's page to the workspace showing it. Resolves with who's
+ * looking; rejects when the page isn't in a workspace (opened on its own) or it
+ * doesn't answer in time.
+ *
+ * ```ts
+ * const tands = await connect();
+ * greet(tands.context.user.name);
+ * await fetch("/api/contacts", { headers: { authorization: `Bearer ${await tands.token()}` } });
+ * ```
+ */
+export declare function connect({ timeoutMs, window: win }?: ConnectOptions): Promise<Connection>;

package/dist/client.js

@@ -0,0 +1,172 @@
+import { readHostMessage, } from "./protocol.js";
+/** A refusal from the workspace, with its reason's code (like `INVALID` or `FORBIDDEN`). */
+export class WorkspaceError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Less than this left on a token: get another. */
+const REFRESH_MS = 60_000;
+/**
+ * Connects a Custom tab's page to the workspace showing it. Resolves with who's
+ * looking; rejects when the page isn't in a workspace (opened on its own) or it
+ * doesn't answer in time.
+ *
+ * ```ts
+ * const tands = await connect();
+ * greet(tands.context.user.name);
+ * await fetch("/api/contacts", { headers: { authorization: `Bearer ${await tands.token()}` } });
+ * ```
+ */
+export function connect({ timeoutMs = 10_000, window: win = window } = {}) {
+    return new Promise((resolve, reject) => {
+        const parent = win.parent;
+        if (!parent || parent === win) {
+            reject(new Error("This page isn't open in a Tabs & Spaces workspace."));
+            return;
+        }
+        // Learned from the first answer: later messages go there, and only theirs count.
+        let hostOrigin = null;
+        let context = null;
+        let current = { token: "", expiresAt: 0 };
+        let theme = "light";
+        let counter = 0;
+        const themeListeners = new Set();
+        const waiting = new Map();
+        let pending = null;
+        const send = (message) => parent.postMessage(message, hostOrigin ?? "*");
+        const timer = setTimeout(() => {
+            win.removeEventListener("message", listen);
+            reject(new Error("The workspace didn't answer."));
+        }, timeoutMs);
+        function listen(event) {
+            if (event.source !== parent)
+                return;
+            if (hostOrigin && event.origin !== hostOrigin)
+                return;
+            const message = readHostMessage(event.data);
+            if (!message)
+                return;
+            switch (message.type) {
+                case "context":
+                    if (context)
+                        return;
+                    hostOrigin = event.origin;
+                    context = message.context;
+                    theme = message.theme;
+                    current = { token: message.token, expiresAt: Date.parse(message.expiresAt) };
+                    clearTimeout(timer);
+                    resolve(connection);
+                    return;
+                case "token": {
+                    const waiter = waiting.get(message.id);
+                    if (!waiter)
+                        return;
+                    waiting.delete(message.id);
+                    current = { token: message.token, expiresAt: Date.parse(message.expiresAt) };
+                    waiter.resolve(message.token);
+                    return;
+                }
+                case "data": {
+                    const waiter = waiting.get(message.id);
+                    if (!waiter)
+                        return;
+                    waiting.delete(message.id);
+                    waiter.resolve(message.result);
+                    return;
+                }
+                case "error": {
+                    const waiter = message.id ? waiting.get(message.id) : undefined;
+                    if (!waiter || !message.id)
+                        return;
+                    waiting.delete(message.id);
+                    waiter.reject(new WorkspaceError(message.message, message.code ?? null));
+                    return;
+                }
+                case "theme":
+                    theme = message.theme;
+                    for (const listener of themeListeners)
+                        listener(theme);
+                    return;
+            }
+        }
+        /** Sends a request; its answer (or refusal) settles it. */
+        function ask(message) {
+            return new Promise((ok, fail) => {
+                const id = `r${++counter}`;
+                waiting.set(id, { resolve: ok, reject: fail });
+                send(message(id));
+            });
+        }
+        const data = (request) => ask((id) => ({ tands: 1, type: "data", id, request }));
+        const connection = {
+            get context() {
+                return context;
+            },
+            get theme() {
+                return theme;
+            },
+            token() {
+                if (current.expiresAt - Date.now() > REFRESH_MS)
+                    return Promise.resolve(current.token);
+                pending ??= new Promise((ok, fail) => {
+                    const id = `t${++counter}`;
+                    waiting.set(id, { resolve: ok, reject: fail });
+                    send({ tands: 1, type: "token", id });
+                }).finally(() => {
+                    pending = null;
+                });
+                return pending;
+            },
+            data,
+            async emit(name, fields = {}) {
+                await ask((id) => ({ tands: 1, type: "event", id, name, data: fields }));
+            },
+            requestEventKey: () => ask((id) => ({ tands: 1, type: "eventKey", id })),
+            async openTrigger(event) {
+                await ask((id) => ({ tands: 1, type: "openTrigger", id, event: event ?? null }));
+            },
+            values(scope) {
+                return {
+                    get: async (key) => (await data({ op: "values.get", scope, key })).value,
+                    set: async (key, value) => {
+                        await data({ op: "values.set", scope, key, value });
+                    },
+                    delete: async (key) => (await data({ op: "values.delete", scope, key })).deleted,
+                    list: async () => (await data({ op: "values.list", scope }))
+                        .values,
+                };
+            },
+            collection(name) {
+                return {
+                    list: async (options = {}) => (await data({
+                        op: "records.list",
+                        collection: name,
+                        ...options,
+                    })),
+                    get: async (id) => (await data({ op: "records.get", collection: name, id })).record,
+                    create: async (fields) => (await data({ op: "records.create", collection: name, data: fields })).record,
+                    update: async (id, fields) => (await data({ op: "records.update", collection: name, id, data: fields }))
+                        .record,
+                    delete: async (id) => {
+                        await data({ op: "records.delete", collection: name, id });
+                    },
+                };
+            },
+            onTheme(listener) {
+                themeListeners.add(listener);
+                return () => themeListeners.delete(listener);
+            },
+            close() {
+                win.removeEventListener("message", listen);
+                for (const waiter of waiting.values())
+                    waiter.reject(new Error("Closed."));
+                waiting.clear();
+            },
+        };
+        win.addEventListener("message", listen);
+        send({ tands: 1, type: "hello" });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tabs & Spaces apps (M9). In a Custom tab's page: `connect()`. On your
+ * server: `verifyToken()` from "@tabs-and-spaces/sdk/server".
+ */
+export { connect, WorkspaceError, type Collection, type Connection, type ConnectOptions, type Values, } from "./client.js";
+export { PROTOCOL_VERSION, readAppMessage, readHostMessage, type AppMessage, type DataRecord, type DataRequest, type DataScope, type EventKey, type HostMessage, type TabContext, type Theme, } from "./protocol.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * Tabs & Spaces apps (M9). In a Custom tab's page: `connect()`. On your
+ * server: `verifyToken()` from "@tabs-and-spaces/sdk/server".
+ */
+export { connect, WorkspaceError, } from "./client.js";
+export { PROTOCOL_VERSION, readAppMessage, readHostMessage, } from "./protocol.js";

package/dist/protocol.d.ts

@@ -0,0 +1,181 @@
+/**
+ * How a Custom tab's page and the workspace around it talk (version 1), with
+ * `postMessage`. The page says hello to its parent; the workspace answers with
+ * who's looking and a token, sent to the app's origin only, and later with new
+ * tokens and theme changes. Every message carries `tands: 1`.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/** Who's looking, and where (also inside the token, signed). */
+export interface TabContext {
+    user: {
+        id: string;
+        name: string;
+    };
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    /**
+     * `name` is the one the reader sees: General and My Space in their language,
+     * a DM by its other people.
+     */
+    space: {
+        id: string;
+        kind: "general" | "personal" | "normal" | "dm";
+        name: string;
+    };
+    /** `appTabId`: which of the app's tabs this is. */
+    tab: {
+        id: string;
+        appTabId: string;
+    };
+    app: {
+        id: string;
+    };
+    /** The reader's language, like "en" or "fr". */
+    locale: string;
+}
+export type Theme = "light" | "dark";
+/** Where app data lives, and so who sees it. */
+export type DataScope = "workspace" | "space" | "tab" | "user";
+/** A request for the app's data (the workspace adds where, and who's asking). */
+export type DataRequest = {
+    op: "values.get";
+    scope: DataScope;
+    key: string;
+} | {
+    op: "values.set";
+    scope: DataScope;
+    key: string;
+    value: unknown;
+} | {
+    op: "values.delete";
+    scope: DataScope;
+    key: string;
+} | {
+    op: "values.list";
+    scope: DataScope;
+} | {
+    op: "records.list";
+    collection: string;
+    where?: Record<string, string | number | boolean | null>;
+    orderBy?: {
+        field: string;
+        direction?: "asc" | "desc";
+    };
+    limit?: number;
+    cursor?: string;
+} | {
+    op: "records.get";
+    collection: string;
+    id: string;
+} | {
+    op: "records.create";
+    collection: string;
+    data: Record<string, unknown>;
+} | {
+    op: "records.update";
+    collection: string;
+    id: string;
+    data: Record<string, unknown>;
+} | {
+    op: "records.delete";
+    collection: string;
+    id: string;
+};
+/** A record, as the workspace returns it. */
+export interface DataRecord<T = Record<string, unknown>> {
+    id: string;
+    data: T;
+    createdBy: {
+        userId: string;
+        name: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+/** From the page to the workspace. */
+export type AppMessage = {
+    tands: 1;
+    type: "hello";
+}
+/** A new token, before the current one expires (`id` matches the answer). */
+ | {
+    tands: 1;
+    type: "token";
+    id: string;
+}
+/** The app's data (`id` matches the answer). */
+ | {
+    tands: 1;
+    type: "data";
+    id: string;
+    request: DataRequest;
+}
+/** Something that happened, as the manifest's `events` declare it (answered like data). */
+ | {
+    tands: 1;
+    type: "event";
+    id: string;
+    name: string;
+    data: Record<string, unknown>;
+}
+/**
+ * A key for the app's server to report events in this tab on its own (answered like
+ * data, with an `EventKey`), once the person allows it.
+ */
+ | {
+    tands: 1;
+    type: "eventKey";
+    id: string;
+}
+/**
+ * Opens a new trigger in this space, starting on one of the app's events in this tab
+ * (decision 174). Answered like data once it's open.
+ */
+ | {
+    tands: 1;
+    type: "openTrigger";
+    id: string;
+    event: string | null;
+};
+/** What the app's server reports events with, at `eventsUrl` (decision 170). */
+export interface EventKey {
+    key: string;
+    eventsUrl: string;
+}
+/** From the workspace to the page. */
+export type HostMessage = {
+    tands: 1;
+    type: "context";
+    context: TabContext;
+    token: string;
+    expiresAt: string;
+    theme: Theme;
+} | {
+    tands: 1;
+    type: "token";
+    id: string;
+    token: string;
+    expiresAt: string;
+} | {
+    tands: 1;
+    type: "data";
+    id: string;
+    result: unknown;
+} | {
+    tands: 1;
+    type: "error";
+    id?: string;
+    message: string;
+    code?: string;
+} | {
+    tands: 1;
+    type: "theme";
+    theme: Theme;
+};
+/** A message from an app's page, or null. */
+export declare function readAppMessage(data: unknown): AppMessage | null;
+/** A message from the workspace, or null. */
+export declare function readHostMessage(data: unknown): HostMessage | null;

package/dist/protocol.js

@@ -0,0 +1,102 @@
+/**
+ * How a Custom tab's page and the workspace around it talk (version 1), with
+ * `postMessage`. The page says hello to its parent; the workspace answers with
+ * who's looking and a token, sent to the app's origin only, and later with new
+ * tokens and theme changes. Every message carries `tands: 1`.
+ */
+export const PROTOCOL_VERSION = 1;
+const isRecord = (value) => typeof value === "object" && value !== null;
+/** A message from an app's page, or null. */
+export function readAppMessage(data) {
+    if (!isRecord(data) || data.tands !== PROTOCOL_VERSION)
+        return null;
+    if (data.type === "hello")
+        return { tands: 1, type: "hello" };
+    if (data.type === "token" && typeof data.id === "string" && data.id.length <= 64) {
+        return { tands: 1, type: "token", id: data.id };
+    }
+    if (data.type === "data" &&
+        typeof data.id === "string" &&
+        data.id.length <= 64 &&
+        isRecord(data.request) &&
+        typeof data.request.op === "string") {
+        // Checked in full by the workspace's server.
+        return { tands: 1, type: "data", id: data.id, request: data.request };
+    }
+    if (data.type === "eventKey" && typeof data.id === "string" && data.id.length <= 64) {
+        return { tands: 1, type: "eventKey", id: data.id };
+    }
+    if (data.type === "openTrigger" &&
+        typeof data.id === "string" &&
+        data.id.length <= 64 &&
+        (data.event === undefined ||
+            data.event === null ||
+            (typeof data.event === "string" && data.event.length <= 40))) {
+        return {
+            tands: 1,
+            type: "openTrigger",
+            id: data.id,
+            event: typeof data.event === "string" ? data.event : null,
+        };
+    }
+    if (data.type === "event" &&
+        typeof data.id === "string" &&
+        data.id.length <= 64 &&
+        typeof data.name === "string" &&
+        data.name.length <= 40 &&
+        (data.data === undefined || isRecord(data.data))) {
+        return {
+            tands: 1,
+            type: "event",
+            id: data.id,
+            name: data.name,
+            data: data.data ?? {},
+        };
+    }
+    return null;
+}
+/** A message from the workspace, or null. */
+export function readHostMessage(data) {
+    if (!isRecord(data) || data.tands !== PROTOCOL_VERSION)
+        return null;
+    const theme = data.theme === "dark" ? "dark" : "light";
+    switch (data.type) {
+        case "context":
+            return isRecord(data.context) &&
+                typeof data.token === "string" &&
+                typeof data.expiresAt === "string"
+                ? {
+                    tands: 1,
+                    type: "context",
+                    context: data.context,
+                    token: data.token,
+                    expiresAt: data.expiresAt,
+                    theme,
+                }
+                : null;
+        case "token":
+            return typeof data.id === "string" &&
+                typeof data.token === "string" &&
+                typeof data.expiresAt === "string"
+                ? { tands: 1, type: "token", id: data.id, token: data.token, expiresAt: data.expiresAt }
+                : null;
+        case "data":
+            return typeof data.id === "string"
+                ? { tands: 1, type: "data", id: data.id, result: data.result }
+                : null;
+        case "error":
+            return typeof data.message === "string"
+                ? {
+                    tands: 1,
+                    type: "error",
+                    message: data.message,
+                    ...(typeof data.id === "string" ? { id: data.id } : {}),
+                    ...(typeof data.code === "string" ? { code: data.code } : {}),
+                }
+                : null;
+        case "theme":
+            return { tands: 1, type: "theme", theme };
+        default:
+            return null;
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,107 @@
+import type { DataRecord, DataRequest, DataScope, EventKey, TabContext } from "./protocol.js";
+/**
+ * Checking a Custom tab's token on your server (Node 22+, Deno, Bun, Workers:
+ * anywhere with Web Crypto's Ed25519). The workspace signs it (EdDSA); its
+ * public keys are at `<workspace address>/api/apps/keys`.
+ *
+ * ```ts
+ * const keys = await fetchKeys("https://chat.acme.com");
+ * const { context } = await verifyToken(token, { keys, audience: "https://crm.example.com" });
+ * ```
+ */
+export interface PublicKey {
+    kty: string;
+    crv: string;
+    x: string;
+    kid: string;
+    alg?: string;
+}
+export interface VerifiedToken {
+    context: TabContext;
+    /** The deployment that signed it (its public address). */
+    issuer: string;
+    expiresAt: Date;
+    /** An action's token (sent to your action's endpoint): which action. */
+    action: string | null;
+}
+export declare class TokenError extends Error {
+}
+/** The deployment's public keys (cache them; they change only if its secret does). */
+export declare function fetchKeys(deploymentUrl: string, fetcher?: typeof fetch): Promise<PublicKey[]>;
+/**
+ * Checks a token: signed by one of `keys`, meant for `audience` (your app's
+ * origin), not expired, and (optionally) from `issuer`. Returns who's looking.
+ */
+export declare function verifyToken(token: string, { keys, audience, issuer, now, }: {
+    keys: PublicKey[];
+    audience: string;
+    issuer?: string;
+    now?: number;
+}): Promise<VerifiedToken>;
+/** What an action's endpoint is sent, as JSON (verify its bearer token first). */
+export interface ActionRequest<Input = Record<string, unknown>> {
+    action: string;
+    input: Input;
+    context: TabContext;
+    /** The agent asking, for the person in `context` (null: they asked themselves). */
+    agent: {
+        id: string;
+        name: string;
+    } | null;
+    /** A short-lived key to your app's data for this request; see `dataClient()`. */
+    dataKey: string;
+    dataUrl: string;
+}
+/**
+ * Your app's data in the workspace, from your server, with the data key an
+ * action was given: the same place (its space, tab and person) as the action,
+ * for the next few minutes.
+ *
+ * ```ts
+ * const data = dataClient(request);
+ * await data.collection("guestbook").create({ message: request.input.message });
+ * ```
+ */
+export declare function dataClient({ dataKey, dataUrl }: Pick<ActionRequest, "dataKey" | "dataUrl">, fetcher?: typeof fetch): {
+    data: (request: DataRequest) => Promise<unknown>;
+    /**
+     * Reports something that happened in your app (M9 slice 5), as your
+     * manifest's `events` declare it, for the person and place of the action.
+     * One from an agent's action starts no trigger (no loops).
+     */
+    emit(name: string, fields?: Record<string, unknown>): Promise<void>;
+    values(scope: DataScope): {
+        get: <T = unknown>(key: string) => Promise<T | null>;
+        set: (key: string, value: unknown) => Promise<void>;
+        delete: (key: string) => Promise<boolean>;
+        list: () => Promise<Record<string, unknown>>;
+    };
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): {
+        list: (options?: Omit<Extract<DataRequest, {
+            op: "records.list";
+        }>, "op" | "collection">) => Promise<{
+            records: DataRecord<T>[];
+            cursor: string | null;
+        }>;
+        get: (id: string) => Promise<DataRecord<T>>;
+        create: (fields: T) => Promise<DataRecord<T>>;
+        update: (id: string, fields: Partial<{ [K in keyof T]: T[K] | null; }>) => Promise<DataRecord<T>>;
+        delete: (id: string) => Promise<void>;
+    };
+};
+/**
+ * Reports an event from your server at any time (decision 170), with the event key
+ * your tab got from `requestEventKey()`: in that tab's space, for the person who
+ * allowed it. Keep the key secret, like a password.
+ *
+ * ```ts
+ * await reportEvent(stored, "pull_request_opened", { title: "Fix login", number: 42 });
+ * ```
+ */
+export declare function reportEvent({ key, eventsUrl }: EventKey, name: string, fields?: Record<string, unknown>, fetcher?: typeof fetch): Promise<void>;
+/** A refusal from the workspace's data endpoint, with its code. */
+export declare class DataError extends Error {
+    readonly code: string | null;
+    constructor(message: string, code: string | null);
+}
+export type { EventKey } from "./protocol.js";

package/dist/server.js

@@ -0,0 +1,152 @@
+export class TokenError extends Error {
+}
+/** The deployment's public keys (cache them; they change only if its secret does). */
+export async function fetchKeys(deploymentUrl, fetcher = fetch) {
+    const response = await fetcher(new URL("/api/apps/keys", deploymentUrl));
+    if (!response.ok)
+        throw new TokenError(`Couldn't fetch the keys (${response.status}).`);
+    const body = (await response.json());
+    return body.keys ?? [];
+}
+const decode = (part) => {
+    const base64 = part.replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(base64 + "=".repeat((4 - (base64.length % 4)) % 4));
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+};
+const json = (part) => {
+    try {
+        return JSON.parse(new TextDecoder().decode(decode(part)));
+    }
+    catch {
+        throw new TokenError("That isn't a token.");
+    }
+};
+/**
+ * Checks a token: signed by one of `keys`, meant for `audience` (your app's
+ * origin), not expired, and (optionally) from `issuer`. Returns who's looking.
+ */
+export async function verifyToken(token, { keys, audience, issuer, now = Date.now(), }) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw new TokenError("That isn't a token.");
+    const [headerPart, payloadPart, signaturePart] = parts;
+    const header = json(headerPart);
+    if (header.alg !== "EdDSA")
+        throw new TokenError("Unexpected signing algorithm.");
+    const jwk = keys.find((key) => key.kid === header.kid && key.crv === "Ed25519");
+    if (!jwk)
+        throw new TokenError("Signed with a key we don't know.");
+    const key = await crypto.subtle.importKey("jwk", { kty: jwk.kty, crv: jwk.crv, x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+    const valid = await crypto.subtle.verify({ name: "Ed25519" }, key, decode(signaturePart), new TextEncoder().encode(`${headerPart}.${payloadPart}`));
+    if (!valid)
+        throw new TokenError("The signature doesn't match.");
+    const payload = json(payloadPart);
+    if (payload.aud !== audience)
+        throw new TokenError("It's meant for another app.");
+    if (issuer !== undefined && payload.iss !== issuer) {
+        throw new TokenError("It's from another deployment.");
+    }
+    if (typeof payload.exp !== "number" || payload.exp * 1000 <= now) {
+        throw new TokenError("It has expired.");
+    }
+    return {
+        context: payload.ctx,
+        issuer: String(payload.iss),
+        expiresAt: new Date(payload.exp * 1000),
+        action: typeof payload.act === "string" ? payload.act : null,
+    };
+}
+/**
+ * Your app's data in the workspace, from your server, with the data key an
+ * action was given: the same place (its space, tab and person) as the action,
+ * for the next few minutes.
+ *
+ * ```ts
+ * const data = dataClient(request);
+ * await data.collection("guestbook").create({ message: request.input.message });
+ * ```
+ */
+export function dataClient({ dataKey, dataUrl }, fetcher = fetch) {
+    async function data(request) {
+        const response = await fetcher(dataUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${dataKey}` },
+            body: JSON.stringify(request),
+        });
+        const body = (await response.json().catch(() => null));
+        if (!response.ok) {
+            throw new DataError(body?.error?.message ?? `It answered ${response.status}.`, body?.error?.code ?? null);
+        }
+        return body?.result;
+    }
+    return {
+        data,
+        /**
+         * Reports something that happened in your app (M9 slice 5), as your
+         * manifest's `events` declare it, for the person and place of the action.
+         * One from an agent's action starts no trigger (no loops).
+         */
+        async emit(name, fields = {}) {
+            const response = await fetcher(dataUrl.replace(/\/data$/, "/events"), {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${dataKey}` },
+                body: JSON.stringify({ name, data: fields }),
+            });
+            if (!response.ok) {
+                const body = (await response.json().catch(() => null));
+                throw new DataError(body?.error?.message ?? `It answered ${response.status}.`, body?.error?.code ?? null);
+            }
+        },
+        values(scope) {
+            return {
+                get: async (key) => (await data({ op: "values.get", scope, key })).value,
+                set: async (key, value) => {
+                    await data({ op: "values.set", scope, key, value });
+                },
+                delete: async (key) => (await data({ op: "values.delete", scope, key })).deleted,
+                list: async () => (await data({ op: "values.list", scope }))
+                    .values,
+            };
+        },
+        collection(name) {
+            return {
+                list: async (options = {}) => (await data({ op: "records.list", collection: name, ...options })),
+                get: async (id) => (await data({ op: "records.get", collection: name, id })).record,
+                create: async (fields) => (await data({ op: "records.create", collection: name, data: fields })).record,
+                update: async (id, fields) => (await data({ op: "records.update", collection: name, id, data: fields }))
+                    .record,
+                delete: async (id) => {
+                    await data({ op: "records.delete", collection: name, id });
+                },
+            };
+        },
+    };
+}
+/**
+ * Reports an event from your server at any time (decision 170), with the event key
+ * your tab got from `requestEventKey()`: in that tab's space, for the person who
+ * allowed it. Keep the key secret, like a password.
+ *
+ * ```ts
+ * await reportEvent(stored, "pull_request_opened", { title: "Fix login", number: 42 });
+ * ```
+ */
+export async function reportEvent({ key, eventsUrl }, name, fields = {}, fetcher = fetch) {
+    const response = await fetcher(eventsUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${key}` },
+        body: JSON.stringify({ name, data: fields }),
+    });
+    if (!response.ok) {
+        const body = (await response.json().catch(() => null));
+        throw new DataError(body?.error?.message ?? `It answered ${response.status}.`, body?.error?.code ?? null);
+    }
+}
+/** A refusal from the workspace's data endpoint, with its code. */
+export class DataError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@tabs-and-spaces/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Building apps for Tabs & Spaces: a Custom tab's page talks to the workspace, its server checks who's looking. No dependencies.",
+  "license": "MIT",
+  "author": "Tabs & Spaces",
+  "homepage": "https://developer.tabsandspaces.dev/sdk/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proteusai/workspace.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "tabs-and-spaces",
+    "sdk",
+    "apps",
+    "custom-tabs"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./server": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      }
+    },
+    "types": "./dist/index.d.ts"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "5.0.2",
+    "eslint": "^10.11.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.1",
+    "vitest": "5.0.2"
+  },
+  "types": "./dist/index.d.ts"
 }