@tabs-and-spaces/sdk 0.2.0 → 0.3.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type DataRecord, type DataRequest, type DataScope, type EventKey, 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;
     /**
@@ -67,6 +67,14 @@ export interface Connection {
      * 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

@@ -125,6 +125,15 @@ export function connect({ timeoutMs = 10_000, window: win = window } = {}) {
                 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 }));
             },

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 EventKey, 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";
@@ -139,6 +170,14 @@ export type AppMessage = {
     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 {
@@ -149,7 +188,7 @@ export interface EventKey {
 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) {
@@ -39,6 +41,19 @@ export function readAppMessage(data) {
             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, EventKey, 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;

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). */

package/package.json

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