@tabs-and-spaces/sdk 0.1.0 → 0.2.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 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;
@@ -54,6 +54,19 @@ 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>;
     /** 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,10 @@ 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 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

@@ -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 HostMessage, type TabContext, type Theme, } from "./protocol.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/protocol.d.ts

@@ -120,7 +120,31 @@ 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;
 };
+/** 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;

package/dist/protocol.js

@@ -23,6 +23,22 @@ 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,
+        };
+    }
     if (data.type === "event" &&
         typeof data.id === "string" &&
         data.id.length <= 64 &&

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import type { DataRecord, DataRequest, DataScope, TabContext } from "./protocol.js";
+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
@@ -89,8 +89,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

@@ -122,6 +122,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.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",