@tabs-and-spaces/sdk 0.3.0 → 0.5.0

package/dist/client.d.ts

@@ -38,6 +38,11 @@ export interface Connection {
     readonly context: PageContext;
     /** The workspace's theme now. */
     readonly theme: Theme;
+    /**
+     * The workspace is read-only now (its bill is unpaid): your data can be read,
+     * not changed. Kept in step with `context.workspace.readOnly`.
+     */
+    readonly readOnly: boolean;
     /**
      * 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).
@@ -77,6 +82,11 @@ export interface Connection {
     }): Promise<void>;
     /** Called when the reader switches between light and dark. Returns an unsubscribe. */
     onTheme(listener: (theme: Theme) => void): () => void;
+    /**
+     * Called when the workspace becomes read-only, or writable again (its bill
+     * paid), while your page is open. Returns an unsubscribe.
+     */
+    onReadOnly(listener: (readOnly: boolean) => void): () => void;
     /** Stops listening. */
     close(): void;
 }

package/dist/client.js

@@ -34,6 +34,7 @@ export function connect({ timeoutMs = 10_000, window: win = window } = {}) {
         let theme = "light";
         let counter = 0;
         const themeListeners = new Set();
+        const readOnlyListeners = new Set();
         const waiting = new Map();
         let pending = null;
         const send = (message) => parent.postMessage(message, hostOrigin ?? "*");
@@ -85,6 +86,13 @@ export function connect({ timeoutMs = 10_000, window: win = window } = {}) {
                     waiter.reject(new WorkspaceError(message.message, message.code ?? null));
                     return;
                 }
+                case "readOnly":
+                    if (!context || context.workspace.readOnly === message.readOnly)
+                        return;
+                    context = { ...context, workspace: { ...context.workspace, readOnly: message.readOnly } };
+                    for (const listener of readOnlyListeners)
+                        listener(message.readOnly);
+                    return;
                 case "theme":
                     theme = message.theme;
                     for (const listener of themeListeners)
@@ -105,6 +113,9 @@ export function connect({ timeoutMs = 10_000, window: win = window } = {}) {
             get context() {
                 return context;
             },
+            get readOnly() {
+                return context.workspace.readOnly;
+            },
             get theme() {
                 return theme;
             },
@@ -164,6 +175,10 @@ export function connect({ timeoutMs = 10_000, window: win = window } = {}) {
                     },
                 };
             },
+            onReadOnly(listener) {
+                readOnlyListeners.add(listener);
+                return () => readOnlyListeners.delete(listener);
+            },
             onTheme(listener) {
                 themeListeners.add(listener);
                 return () => themeListeners.delete(listener);

package/dist/index.d.ts

@@ -3,4 +3,4 @@
  * 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 HomeContext, type HostMessage, isHome, type PageContext, type TabContext, type Theme, } from "./protocol.js";
+export { PROTOCOL_VERSION, readAppMessage, readHostMessage, type AppMessage, type DataRecord, type DataRequest, type DataScope, type EventKey, type HomeContext, type HostMessage, isHome, type PageContext, type TabContext, type Theme, type WorkspaceInfo, } from "./protocol.js";

package/dist/protocol.d.ts

@@ -5,17 +5,24 @@
  * tokens and theme changes. Every message carries `tands: 1`.
  */
 export declare const PROTOCOL_VERSION = 1;
+/**
+ * The workspace around your page. `readOnly`: it's read-only until its bill is
+ * paid, so your app's data can be read but not changed (writes are refused
+ * with `WORKSPACE_READ_ONLY`); say so, and offer nothing that writes.
+ */
+export interface WorkspaceInfo {
+    id: string;
+    slug: string;
+    name: string;
+    readOnly: boolean;
+}
 /** Who's looking, and where, in a Custom tab (also inside the token, signed). */
 export interface TabContext {
     user: {
         id: string;
         name: string;
     };
-    workspace: {
-        id: string;
-        slug: string;
-        name: string;
-    };
+    workspace: WorkspaceInfo;
     /**
      * `name` is the one the reader sees: General and My Space in their language,
      * a DM by its other people.
@@ -47,11 +54,7 @@ export interface HomeContext {
         name: string;
         guest: boolean;
     };
-    workspace: {
-        id: string;
-        slug: string;
-        name: string;
-    };
+    workspace: WorkspaceInfo;
     space: null;
     tab: null;
     /** Which of your manifest's `home` pages this is. */
@@ -213,8 +216,16 @@ export type HostMessage = {
     tands: 1;
     type: "theme";
     theme: Theme;
+}
+/** The workspace became read-only, or writable again, while your page is open. */
+ | {
+    tands: 1;
+    type: "readOnly";
+    readOnly: boolean;
 };
 /** A message from an app's page, or null. */
 export declare function readAppMessage(data: unknown): AppMessage | null;
+/** A context from a workspace that doesn't say `readOnly` (older ones): writable. */
+export declare function withReadOnly<T extends PageContext>(context: T): T;
 /** A message from the workspace, or null. */
 export declare function readHostMessage(data: unknown): HostMessage | null;

package/dist/protocol.js

@@ -70,6 +70,13 @@ export function readAppMessage(data) {
     }
     return null;
 }
+/** A context from a workspace that doesn't say `readOnly` (older ones): writable. */
+export function withReadOnly(context) {
+    const workspace = context.workspace;
+    if (!workspace || typeof workspace.readOnly === "boolean")
+        return context;
+    return { ...context, workspace: { ...workspace, readOnly: false } };
+}
 /** A message from the workspace, or null. */
 export function readHostMessage(data) {
     if (!isRecord(data) || data.tands !== PROTOCOL_VERSION)
@@ -83,7 +90,7 @@ export function readHostMessage(data) {
                 ? {
                     tands: 1,
                     type: "context",
-                    context: data.context,
+                    context: withReadOnly(data.context),
                     token: data.token,
                     expiresAt: data.expiresAt,
                     theme,
@@ -111,6 +118,10 @@ export function readHostMessage(data) {
                 : null;
         case "theme":
             return { tands: 1, type: "theme", theme };
+        case "readOnly":
+            return typeof data.readOnly === "boolean"
+                ? { tands: 1, type: "readOnly", readOnly: data.readOnly }
+                : null;
         default:
             return null;
     }

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import type { DataRecord, DataRequest, DataScope, EventKey, PageContext, TabContext } from "./protocol.js";
-export { isHome, type HomeContext, type PageContext, type TabContext } from "./protocol.js";
+export { isHome, type HomeContext, type PageContext, type TabContext, type WorkspaceInfo, } 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
@@ -54,6 +54,105 @@ export interface ActionRequest<Input = Record<string, unknown>> {
     dataKey: string;
     dataUrl: string;
 }
+type Tone = "good" | "warning" | "bad" | "neutral";
+/** A day (`2030-01-08`, all day) or an ISO time; without an offset, the asker's. */
+type When = string;
+/**
+ * A card showing what an action found, drawn under the agent's answer (the
+ * agent then doesn't retype it). Links are http(s) only. At most 8 per answer.
+ */
+export type ActionCard = {
+    type: "emails";
+    title?: string;
+    items: {
+        from: string;
+        subject: string;
+        snippet?: string;
+        at?: When;
+        url?: string;
+        unread?: boolean;
+        important?: boolean;
+        note?: string;
+    }[];
+} | {
+    type: "events";
+    title?: string;
+    items: {
+        title: string;
+        start: When;
+        end?: When;
+        where?: string;
+        people?: string[];
+        url?: string;
+        /** A video call's link. */
+        join?: string;
+        status?: "accepted" | "tentative" | "declined" | "needs_answer";
+        note?: string;
+    }[];
+} | {
+    type: "metrics";
+    title?: string;
+    items: {
+        label: string;
+        value: string;
+        detail?: string;
+        tone?: Tone;
+    }[];
+} | {
+    type: "table";
+    title?: string;
+    columns: string[];
+    rows: (string | number | null)[][];
+} | {
+    type: "list";
+    title?: string;
+    items: {
+        title: string;
+        detail?: string;
+        meta?: string;
+        url?: string;
+        tone?: Tone;
+    }[];
+} | {
+    type: "links";
+    title?: string;
+    items: {
+        label: string;
+        url: string;
+        detail?: string;
+    }[];
+} | {
+    type: "note";
+    tone?: "info" | "success" | "warning" | "danger";
+    title?: string;
+    text: string;
+} | {
+    type: "bars";
+    title?: string;
+    unit?: string;
+    items: {
+        label: string;
+        value: number;
+    }[];
+} | {
+    type: "actions";
+    items: {
+        label: string;
+        prompt: string;
+    }[];
+};
+/** What an action's endpoint answers, with 200. */
+export interface ActionAnswer {
+    /** For the agent to read: a sentence, or any JSON. */
+    result: unknown;
+    /** What it found, shown as cards under the agent's answer (actions that change nothing). */
+    cards?: ActionCard[];
+    /**
+     * For your action's view (its manifest's `view`), not the agent: what the
+     * page is told besides `result`, as MCP Apps' `structuredContent`.
+     */
+    data?: Record<string, unknown>;
+}
 /**
  * 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,

package/dist/server.js

@@ -1,4 +1,5 @@
-export { isHome } from "./protocol.js";
+import { withReadOnly } from "./protocol.js";
+export { isHome, } from "./protocol.js";
 export class TokenError extends Error {
 }
 /** The deployment's public keys (cache them; they change only if its secret does). */
@@ -51,7 +52,7 @@ export async function verifyToken(token, { keys, audience, issuer, now = Date.no
         throw new TokenError("It has expired.");
     }
     return {
-        context: payload.ctx,
+        context: withReadOnly(payload.ctx),
         issuer: String(payload.iss),
         expiresAt: new Date(payload.exp * 1000),
         action: typeof payload.act === "string" ? payload.act : null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabs-and-spaces/sdk",
-  "version": "0.3.0",
+  "version": "0.5.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",