@tabs-and-spaces/sdk 0.1.0 → 0.3.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type DataRecord, type DataRequest, type DataScope, type TabContext, type Theme } from "./protocol.js";
+import { type DataRecord, type DataRequest, type DataScope, type EventKey, type PageContext, 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;
@@ -35,7 +35,7 @@ export interface Collection<T extends Record<string, unknown> = Record<string, u
 }
 export interface Connection {
     /** Who's looking, and where. */
-    readonly context: TabContext;
+    readonly context: PageContext;
     /** The workspace's theme now. */
     readonly theme: Theme;
     /**
@@ -54,6 +54,27 @@ export interface Connection {
      * (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>;
+    /**
+     * Takes the person to a space, or one of its tabs (decision 177): a home page's
+     * links into the workspace. The workspace goes there; your page is left.
+     */
+    open(target: {
+        space: string;
+        tab?: string;
+    }): Promise<void>;
     /** Called when the reader switches between light and dark. Returns an unsubscribe. */
     onTheme(listener: (theme: Theme) => void): () => void;
     /** Stops listening. */

package/dist/client.js

@@ -124,6 +124,19 @@ export function connect({ timeoutMs = 10_000, window: win = window } = {}) {
             async emit(name, fields = {}) {
                 await ask((id) => ({ tands: 1, type: "event", id, name, data: fields }));
             },
+            requestEventKey: () => ask((id) => ({ tands: 1, type: "eventKey", id })),
+            async open(target) {
+                await ask((id) => ({
+                    tands: 1,
+                    type: "open",
+                    id,
+                    space: target.space,
+                    tab: target.tab ?? null,
+                }));
+            },
+            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,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
- * Tabs & Spaces apps (M9). In a Custom tab's page: `connect()`. On your
+ * Tabs & Spaces apps (M9). In a Custom tab's or home page'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 HostMessage, 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, } from "./protocol.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 /**
- * Tabs & Spaces apps (M9). In a Custom tab's page: `connect()`. On your
+ * Tabs & Spaces apps (M9). In a Custom tab's or home page'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";
+export { PROTOCOL_VERSION, readAppMessage, readHostMessage, isHome, } from "./protocol.js";

package/dist/protocol.d.ts

@@ -5,7 +5,7 @@
  * 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). */
+/** Who's looking, and where, in a Custom tab (also inside the token, signed). */
 export interface TabContext {
     user: {
         id: string;
@@ -35,7 +35,38 @@ export interface TabContext {
     };
     /** The reader's language, like "en" or "fr". */
     locale: string;
+    home?: undefined;
 }
+/**
+ * Who's looking at one of your home pages (decision 177): the workspace's Home,
+ * so no space or tab around it. Guests see it too: `user.guest` says so.
+ */
+export interface HomeContext {
+    user: {
+        id: string;
+        name: string;
+        guest: boolean;
+    };
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    space: null;
+    tab: null;
+    /** Which of your manifest's `home` pages this is. */
+    home: {
+        id: string;
+    };
+    app: {
+        id: string;
+    };
+    locale: string;
+}
+/** Where your page is: a Custom tab in a space, or the workspace's Home. */
+export type PageContext = TabContext | HomeContext;
+/** Whether your page is the workspace's Home (no space or tab around it). */
+export declare const isHome: (context: PageContext) => context is HomeContext;
 export type Theme = "light" | "dark";
 /** Where app data lives, and so who sees it. */
 export type DataScope = "workspace" | "space" | "tab" | "user";
@@ -120,12 +151,44 @@ export type AppMessage = {
     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;
+}
+/** Takes the person to a space, or one of its tabs (decision 177). Answered like data. */
+ | {
+    tands: 1;
+    type: "open";
+    id: string;
+    space: string;
+    tab: 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;
+    context: PageContext;
     token: string;
     expiresAt: string;
     theme: Theme;

package/dist/protocol.js

@@ -5,6 +5,8 @@
  * tokens and theme changes. Every message carries `tands: 1`.
  */
 export const PROTOCOL_VERSION = 1;
+/** Whether your page is the workspace's Home (no space or tab around it). */
+export const isHome = (context) => Boolean(context.home);
 const isRecord = (value) => typeof value === "object" && value !== null;
 /** A message from an app's page, or null. */
 export function readAppMessage(data) {
@@ -23,6 +25,35 @@ export function readAppMessage(data) {
         // 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,
+        };
+    }
+    const id = (value) => typeof value === "string" && value.length > 0 && value.length <= 64;
+    if (data.type === "open" &&
+        id(data.id) &&
+        id(data.space) &&
+        (data.tab === undefined || data.tab === null || id(data.tab))) {
+        return {
+            tands: 1,
+            type: "open",
+            id: data.id,
+            space: data.space,
+            tab: typeof data.tab === "string" ? data.tab : null,
+        };
+    }
     if (data.type === "event" &&
         typeof data.id === "string" &&
         data.id.length <= 64 &&

package/dist/server.d.ts

@@ -1,4 +1,5 @@
-import type { DataRecord, DataRequest, DataScope, TabContext } from "./protocol.js";
+import type { DataRecord, DataRequest, DataScope, EventKey, PageContext, TabContext } from "./protocol.js";
+export { isHome, type HomeContext, type PageContext, type 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
@@ -17,7 +18,8 @@ export interface PublicKey {
     alg?: string;
 }
 export interface VerifiedToken {
-    context: TabContext;
+    /** A Custom tab's, or a home page's (`isHome()`); an action's is always a tab's. */
+    context: PageContext;
     /** The deployment that signed it (its public address). */
     issuer: string;
     expiresAt: Date;
@@ -89,8 +91,19 @@ export declare function dataClient({ dataKey, dataUrl }: Pick<ActionRequest, "da
         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

@@ -1,3 +1,4 @@
+export { isHome } from "./protocol.js";
 export class TokenError extends Error {
 }
 /** The deployment's public keys (cache them; they change only if its secret does). */
@@ -122,6 +123,26 @@ export function dataClient({ dataKey, dataUrl }, fetcher = fetch) {
         },
     };
 }
+/**
+ * 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;

package/package.json

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