esoul-sdk 0.4.0 → 0.7.0

package/dist/manifest.js

@@ -35,6 +35,126 @@ export const PluginConnectionSchema = z
     .strict()
     .refine((c) => c.kind !== "oauth2" ||
     (!!c.authorizeUrl && !!c.tokenUrl && !!c.clientIdEnv), { message: "oauth2 connections require authorizeUrl + tokenUrl + clientIdEnv" });
+/**
+ * WHO MAY REACH A SURFACE — the access level of one op, route or kickable task.
+ *
+ * Every entry point of an app has always been owner-or-editor-only, which is
+ * the right default and the wrong ONLY option: an app with customers needs a
+ * catalogue anyone may read and an order anyone signed in may place.
+ *
+ *   write  (default) — people who may edit the workspace. Today's behaviour.
+ *   read            — anyone who may see it, including a read-only member.
+ *   public          — anyone on the app's public share link, signed in or not.
+ *
+ * `requires: "account"` adds "…but they must be signed in", answered with
+ * `login-required` (and a way back) rather than a flat refusal, so the app can
+ * render a sign-in wall instead of an error.
+ *
+ * NOTHING opens by default. A level is opt-in per NAME, and the install card
+ * lists every public door before the owner presses Install.
+ */
+export const PLUGIN_ACCESS_LEVELS = ["write", "read", "public"];
+export const PluginSurfaceEntrySchema = z
+    .object({
+    access: z.enum(PLUGIN_ACCESS_LEVELS).optional().default("write"),
+    requires: z.literal("account").optional(),
+})
+    .strict();
+/**
+ * A surface list is EITHER the plain array of names it has always been (every
+ * entry `write`), OR a map of name → access. The two forms exist so no shipped
+ * manifest has to change; the map is what an app with customers writes, and it
+ * keeps a name and its access in ONE place — a separate access block would be a
+ * second list to forget to update, and the failure mode of forgetting would be
+ * a surface quietly staying shut.
+ */
+const surfaceList = (nameRe) => z
+    .union([
+    z.array(z.string().regex(nameRe)),
+    z.record(z.string().regex(nameRe), PluginSurfaceEntrySchema),
+])
+    .optional()
+    .default([]);
+/** Normalised view of any surface list: every declared name, in order. */
+export function surfaceNames(list) {
+    if (Array.isArray(list))
+        return list.map(String);
+    if (list && typeof list === "object")
+        return Object.keys(list);
+    return [];
+}
+/** The access a surface declares. Absent, unknown or array-form → `write`. */
+export function surfaceAccess(list, name) {
+    if (list && !Array.isArray(list) && typeof list === "object") {
+        const e = list[name];
+        if (e)
+            return { level: e.access ?? "write", requiresAccount: e.requires === "account" };
+    }
+    return { level: "write", requiresAccount: false };
+}
+/** Every name in this list that is reachable without a workspace session. */
+export function publicSurfaceNames(list) {
+    return surfaceNames(list).filter((n) => surfaceAccess(list, n).level === "public");
+}
+/**
+ * WHAT THE APP CALLS ITS PEOPLE.
+ *
+ * The platform knows owner / member / visitor / anonymous. A shop thinks in
+ * customer / staff / owner. An app declares its own words and how the
+ * platform's kinds map onto them, and the owner can override the word for one
+ * person and one app in the sharing settings — the `appRoles` column that has
+ * carried a "Phase 5+" comment since it was added, and that nothing has ever
+ * written.
+ *
+ * `describe` is not decoration: it is what the role picker shows the owner when
+ * they are deciding what to give somebody.
+ */
+export const PluginRolesSchema = z
+    .object({
+    vocabulary: z.array(z.string().regex(/^[a-z][a-z0-9_-]*$/)).min(1).max(12),
+    default: z
+        .object({
+        owner: z.string().optional(),
+        "member-edit": z.string().optional(),
+        "member-readonly": z.string().optional(),
+        visitor: z.string().optional(),
+        anonymous: z.string().optional(),
+        agent: z.string().optional(),
+    })
+        .strict()
+        .optional()
+        .default({}),
+    describe: z.record(z.string(), z.string().max(200)).optional(),
+})
+    .strict()
+    .superRefine((r, ctx) => {
+    // A default naming a role the app does not have is the stale-override bug
+    // waiting to happen, and it is free to catch here.
+    for (const [kind, role] of Object.entries(r.default ?? {})) {
+        // `inherit` (an agent takes the role of whoever it acts for) and `none`
+        // (this app has no word for that kind of caller, so no rule can match
+        // them) are the PLATFORM's two sentinels, not app roles. `none` is what
+        // `resolveAppRole` itself returns for an unmapped kind — refusing an
+        // author for writing down exactly what the platform produces was a
+        // disagreement between the validator and the resolver (2026-09-11).
+        if (role && role !== "inherit" && role !== "none" && !r.vocabulary.includes(role)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["default", kind],
+                message: `"${role}" is not in this app's vocabulary (${r.vocabulary.join(", ")})`,
+            });
+        }
+    }
+    for (const role of Object.keys(r.describe ?? {})) {
+        if (!r.vocabulary.includes(role)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["describe", role],
+                message: `"${role}" is described but not in the vocabulary`,
+            });
+        }
+    }
+});
 export const PluginManifestSchema = z.object({
     manifestVersion: z.literal(PLUGIN_MANIFEST_VERSION),
     /** Directory name under src/plugins/. Kebab-case. */
@@ -63,12 +183,15 @@ export const PluginManifestSchema = z.object({
         url: z.string().optional(),
     })
         .optional(),
-    /** Tasks the BROWSER may kick via /api/inngest/send-event. */
-    kickableTasks: z.array(z.string()).optional().default([]),
+    /** Tasks the BROWSER may kick via /api/inngest/send-event. Array or name→access. */
+    kickableTasks: surfaceList(/^[a-z][a-zA-Z0-9_-]*$/),
     /** Push-ingress endpoints — POST|GET /api/plugins/<id>/webhook/<name>. */
     webhooks: z.array(z.string().regex(/^[a-z][a-z0-9-]*$/)).optional().default([]),
-    /** Server ops — POST /api/plugins/<id>/op/<name> (platform-gated). */
-    ops: z.array(z.string().regex(/^[a-z][a-z0-9_-]*$/)).optional().default([]),
+    /** Server ops — POST /api/plugins/<id>/op/<name>. Array or name→access. */
+    ops: surfaceList(/^[a-z][a-z0-9_-]*$/),
+    /** Server routes the app brings with it — `pluginServer.routes` in server.ts, mounted at
+     * `/api/plugins/<id>/route/<name>` on install (GET and POST; may stream). */
+    routes: surfaceList(/^[a-z][a-z0-9_-]*$/),
     /** Poll cadences for durable tasks (the offline-safe pull lane). */
     pollTasks: z
         .array(z.object({
@@ -83,6 +206,8 @@ export const PluginManifestSchema = z.object({
         .optional(),
     /** Reserved for the review/consent flow. */
     scopes: z.array(z.string()).optional().default([]),
+    /** The app's own role vocabulary (see PluginRolesSchema). */
+    roles: PluginRolesSchema.optional(),
     /**
      * Tools of OTHER apps in the workspace this plugin's UI may invoke through
      * `useWorkspaceTools()` — "<applicationType>:<tool base name>", e.g.
@@ -133,4 +258,92 @@ export const PluginManifestSchema = z.object({
         .strict())
         .optional()
         .default([]),
-});
+    /**
+     * SLOTS this app needs filled (S9). `contract` names what must stand there
+     * ("stock/v1"); the OWNER picks which app fills it, and the platform checks
+     * at bind time that the provider really has every tool, event and table the
+     * contract requires. A required slot nothing fills refuses at the seam
+     * (`not-bound`); an optional one is simply absent.
+     */
+    uses: z
+        .record(z.string().regex(/^[a-z][a-z0-9-]*$/), z
+        .object({
+        contract: z.string().regex(/^[a-z][a-z0-9-]*\/v\d+$/),
+        label: z.string().min(1).max(60).optional(),
+        optional: z.boolean().optional(),
+    })
+        .strict())
+        .optional(),
+    /**
+     * What this app OFFERS other apps, per contract id. A claim, checked at bind
+     * time against what the app actually has — a manifest that names a tool the
+     * app does not mint refuses the binding rather than failing later inside
+     * someone's order.
+     */
+    provides: z
+        .record(z.string().regex(/^[a-z][a-z0-9-]*\/v\d+$/), z
+        .object({
+        tools: z.array(z.string()).optional(),
+        events: z.array(z.string()).optional(),
+        models: z.array(z.string()).optional(),
+    })
+        .strict())
+        .optional(),
+    /**
+     * The app's realtime TOPICS, and who hears each (forge-sdk-spec-and-tests
+     * §A1.3.5). `audience` is `all` (default — the instance's channel), `viewer`
+     * (one channel per person) or `role:<name>`; `mayAddress` names the roles
+     * allowed to aim a message at someone else. The platform mints a token per
+     * channel, so a customer is never handed the staff channel or another
+     * customer's — it is not filtered on arrival, it is never issued.
+     * `esoul-sdk/audience` is the one decision both sides use.
+     */
+    channel: z
+        .object({
+        topics: z.record(z.string().regex(/^[a-z][a-z0-9-]*$/), z
+            .object({
+            audience: z.union([z.literal("all"), z.literal("viewer"), z.string().regex(/^role:[a-z][a-z0-9-]*$/)]).optional(),
+            mayAddress: z.array(z.string()).optional(),
+            description: z.string().max(200).optional(),
+        })
+            .strict()),
+    })
+        .strict()
+        .optional(),
+    /**
+     * The app's own TABLES (forge-sdk-spec-and-tests §A1.3.4). Shape only: the
+     * rule compiler (`db/compile-rules.ts`) is what validates a field type, a
+     * rule's principals and a sealed column, and it says which key was wrong.
+     *
+     * It is declared HERE because a schema that does not know a block SILENTLY
+     * DROPS it — `z.object` strips what it has no field for. The install path
+     * parses through this schema, so for one evening an app installed from its
+     * own repository arrived with `db: undefined`, the job skipped its
+     * schema step without a word, and the app was live with no tables
+     * (2026-09-11, found by driving it). Hence `.strict()` below: a block this
+     * platform does not understand refuses the install instead of vanishing.
+     */
+    db: z
+        .record(z.string().regex(/^[A-Z][A-Za-z0-9]*$/), z
+        .object({
+        scope: z.enum(["instance", "workspace", "user"]).optional(),
+        owner: z.literal("creator").optional(),
+        fields: z.record(z.string().regex(/^[a-z][A-Za-z0-9]*$/), z.string()),
+        sealed: z.array(z.string()).optional(),
+        unique: z.array(z.array(z.string())).optional(),
+        // A plain group is a btree; an object names a kind — `contains` for
+        // a list field, `text` for substring search (docs/14).
+        indexes: z
+            .array(z.union([
+            z.array(z.string()),
+            z.object({ fields: z.array(z.string()).min(1), kind: z.enum(["btree", "contains", "text"]).optional() }).strict(),
+        ]))
+            .optional(),
+        rules: z.record(z.string(), z.unknown()).optional(),
+    })
+        .strict())
+        .optional(),
+})
+    // A manifest key the platform does not know is a REFUSAL, never a silent
+    // drop: the block the author wrote would not run, and nothing would say so.
+    .strict();

package/dist/roles.d.ts

@@ -0,0 +1,43 @@
+/**
+ * THE role mapping — one table, one implementation.
+ *
+ * An app declares its own words for the people who use it (`customer`,
+ * `staff`), and the platform has its own (`owner`, `editor`, `viewer`). Turning
+ * one into the other is three lines, which is exactly why it was about to
+ * exist twice: once in the host's viewer builder and once in the SDK's test
+ * helpers. Two implementations of one mapping is the shape of bug where a
+ * read-only member is `staff` in an author's unit test and `viewer` in
+ * production, and every rule naming `staff` quietly changes meaning between
+ * the two.
+ *
+ * So it lives in the package (the half an author installs) and the host reads
+ * it from here — the same single-sourcing as the manifest schema.
+ */
+/** What the platform knows about a caller, as a key into an app's `default` map. */
+export type RoleKindKey = "owner" | "member-edit" | "member-readonly" | "visitor" | "anonymous" | "agent";
+export interface PluginRoleVocabulary {
+    /** Every word this app uses. A role outside it is not a role. */
+    vocabulary: string[];
+    /** Which word each kind of caller gets by default. */
+    default: Partial<Record<RoleKindKey, string>>;
+}
+/** The key for a caller, given their kind and (for a member) their access. */
+export declare function roleKeyFor(kind: "owner" | "member" | "visitor" | "anonymous" | "agent" | "internal", accessType?: "readonly" | "edit" | null): RoleKindKey;
+/**
+ * The app's word for this caller.
+ *
+ * `platformRole` is the platform's own answer (`appRoles[nodeId] ?? defaultRole`).
+ * Three rules, in order:
+ *   1. No vocabulary → the platform's word passes through, so nothing that
+ *      exists today moves.
+ *   2. The platform's word IS one of the app's → the owner's per-app override
+ *      wins, which is what the override is for.
+ *   3. Otherwise the app's default for this kind — and if that names something
+ *      outside the vocabulary (a stale override, a role dropped in an update),
+ *      `"none"`, which no rule can match. Never a word no rule mentions.
+ */
+export declare function resolveAppRole(args: {
+    roles?: PluginRoleVocabulary | null;
+    platformRole: string;
+    key: RoleKindKey;
+}): string;

package/dist/roles.js

@@ -0,0 +1,56 @@
+/**
+ * THE role mapping — one table, one implementation.
+ *
+ * An app declares its own words for the people who use it (`customer`,
+ * `staff`), and the platform has its own (`owner`, `editor`, `viewer`). Turning
+ * one into the other is three lines, which is exactly why it was about to
+ * exist twice: once in the host's viewer builder and once in the SDK's test
+ * helpers. Two implementations of one mapping is the shape of bug where a
+ * read-only member is `staff` in an author's unit test and `viewer` in
+ * production, and every rule naming `staff` quietly changes meaning between
+ * the two.
+ *
+ * So it lives in the package (the half an author installs) and the host reads
+ * it from here — the same single-sourcing as the manifest schema.
+ */
+/** The key for a caller, given their kind and (for a member) their access. */
+export function roleKeyFor(kind, accessType) {
+    switch (kind) {
+        case "owner":
+            return "owner";
+        case "member":
+            return accessType === "readonly" ? "member-readonly" : "member-edit";
+        case "visitor":
+            return "visitor";
+        case "anonymous":
+            return "anonymous";
+        case "agent":
+            return "agent";
+        case "internal":
+            // The app's own code acts with the owner's reach; `internal` bypasses
+            // rules anyway, so the word it carries only ever shows up in a log.
+            return "owner";
+    }
+}
+/**
+ * The app's word for this caller.
+ *
+ * `platformRole` is the platform's own answer (`appRoles[nodeId] ?? defaultRole`).
+ * Three rules, in order:
+ *   1. No vocabulary → the platform's word passes through, so nothing that
+ *      exists today moves.
+ *   2. The platform's word IS one of the app's → the owner's per-app override
+ *      wins, which is what the override is for.
+ *   3. Otherwise the app's default for this kind — and if that names something
+ *      outside the vocabulary (a stale override, a role dropped in an update),
+ *      `"none"`, which no rule can match. Never a word no rule mentions.
+ */
+export function resolveAppRole(args) {
+    const { roles, platformRole, key } = args;
+    if (!roles || !roles.vocabulary?.length)
+        return platformRole;
+    if (roles.vocabulary.includes(platformRole))
+        return platformRole;
+    const mapped = roles.default?.[key];
+    return mapped && roles.vocabulary.includes(mapped) ? mapped : "none";
+}

package/dist/server.d.ts

@@ -12,6 +12,20 @@ export interface PluginWebhookContext {
     /** Raw request — read body/headers; VERIFY THE PROVIDER'S SIGNATURE
      * YOURSELF (timing-safe!). The platform does no auth on webhooks. */
     request: Request;
+    /**
+     * The shared secret an operator configured for THIS plugin's webhooks, or
+     * null. Compare it with `timingSafeEqual`; refuse when it is null rather
+     * than falling back to a default, or an unconfigured deployment accepts
+     * anyone's POST.
+     *
+     * It exists because a webhook must verify its caller and the secret has to
+     * come from somewhere — and an app reading `process.env` itself is exactly
+     * what the import wall refuses (it found this: the demo plugin was doing it).
+     * The PLATFORM reads the environment and names the variable, so an operator
+     * knows what to set: `PLUGIN_<ID>_WEBHOOK_TOKEN`, id upper-snaked
+     * (`todo-plugin` → `PLUGIN_TODO_PLUGIN_WEBHOOK_TOKEN`).
+     */
+    secret: string | null;
     method: string;
     pluginId: string;
     hookName: string;
@@ -20,6 +34,39 @@ export interface PluginWebhookContext {
     sendInngestEvent(name: string, data: Record<string, unknown>): Promise<void>;
 }
 export type PluginWebhookHandler = (ctx: PluginWebhookContext) => Promise<Response>;
+/**
+ * WHO is calling. MIRRORS the host (src/lib/plugins/viewer.ts).
+ *
+ * The platform resolves it before your handler runs and it is the ONLY
+ * identity you get: an app cannot read cookies or headers (the import wall
+ * refuses the modules that would let it), so there is nothing to forge and
+ * nothing to get wrong. Branch on `role` for what your app means by this
+ * person; `viewerIds` is for scoping rows to whoever made them.
+ */
+export type PluginViewerKind = "owner" | "member" | "visitor" | "anonymous" | "agent" | "internal";
+export interface PluginViewer {
+    kind: PluginViewerKind;
+    /** The esoul account, when there is one. */
+    userId: string | null;
+    /**
+     * Every id this person has acted under — the guest cookie, the account, and
+     * every guest id linked to it at login. Scope a row to its creator against
+     * this SET, not against `userId`, and an order placed before signing in
+     * stays theirs afterwards. Server-side only; never reaches the browser.
+     */
+    viewerIds: string[];
+    /** Your app's own word for this caller, from the manifest's `roles`. */
+    role: string;
+    /** May this caller change the workspace at all? */
+    canWrite: boolean;
+    /** The public share they arrived through, if any. */
+    shareId: string | null;
+    /** Set when `kind === "agent"` — the person the run acts for. */
+    agent?: {
+        runId?: string;
+        onBehalfOf: Omit<PluginViewer, "agent">;
+    };
+}
 export interface PluginOpContext {
     pluginId: string;
     opName: string;
@@ -29,13 +76,116 @@ export interface PluginOpContext {
     /** The instance's bound connection (or null). Resolve credentials via
      * getPluginConnectionCredentials. */
     cloudConnectionId: string | null;
+    /** WHO is calling — resolved by the platform, never by you. */
+    viewer: PluginViewer;
     /** Caller-supplied args — validate before use. */
     args: unknown;
+    /**
+     * Publish on one of your channel's topics (S8). WHO HEARS IT is the topic's
+     * `audience` in your manifest: `all` reaches anyone watching the app,
+     * `viewer` only the person it concerns, `role:<name>` only that desk.
+     *
+     * Unaddressed, a message goes where the topic says — a `viewer` topic to the
+     * CALLER's own channel, which is what "your order was placed" wants. `to`
+     * aims it somewhere else, and aiming is a separate permission: this caller
+     * may address only itself unless the topic's `mayAddress` names its role.
+     * Your own tasks always may.
+     */
+    notify(topic: string, data: unknown, opts?: {
+        to?: {
+            viewerIds: string[];
+        } | {
+            role: string;
+        };
+    }): Promise<void>;
+    /**
+     * RECORD SOMETHING ON YOUR OWN TIMELINE, from the server half.
+     *
+     * The fold is for what is shared, small and worth scrubbing. Until this
+     * existed, only the UI could put anything there — so a shop whose products
+     * were added by its AGENT had a catalogue and no departments, because the
+     * departments were only recorded by the owner's form (2026-09-12). Anything
+     * a person can cause through your UI, an agent can cause through a tool, and
+     * the server is the only place that sees both.
+     *
+     * The event is your own (`eventName` from your schema), it goes through the
+     * platform's spine — your `dataCreator` mints, your reducer folds, triggers
+     * fire — and it is recorded against THIS instance. Give it a change id you
+     * can derive again (`product:<id>`, never a random one) so a retry, or the
+     * UI's own optimistic dispatch of the same fact, is a no-op.
+     */
+    emit(eventName: string, eventData: Record<string, unknown>): Promise<void>;
+    /**
+     * The apps standing in this app's SLOTS (manifest `uses`), by slot name
+     * (S9). A slot the owner has not filled is ABSENT — `ctx.apps.stock?.call(…)`
+     * reads as the question it is, and a required slot that must be filled
+     * should refuse with `not-bound` rather than pretend.
+     *
+     * What a slot reaches is the CONTRACT's tools, not the provider's whole
+     * toolkit, and the caller travels: the provider's own rules meet the actual
+     * person. Writes never cross directly — the provider's tools are the only
+     * writers of its tables, which is how a ledger keeps refusing to oversell.
+     */
+    apps: Record<string, {
+        nodeId: string;
+        applicationType: string;
+        via: string;
+        state(): Promise<Record<string, unknown>>;
+        call(tool: string, args?: Record<string, unknown>): Promise<{
+            ok: boolean;
+            text: string;
+        }>;
+    }>;
+}
+/**
+ * WHO IS THIS, IN WORDS. The caller's own name and email, for an app with a
+ * reason to ask — a receipt, an address form they should not retype.
+ *
+ * SERVER ONLY, and only ever about the CALLER: there is no argument for whose
+ * profile to read, so an app cannot look up a person who is not talking to it.
+ * Null for anyone without an account. One database read: call it where you
+ * need it, not on every request.
+ */
+export declare function viewerProfile(_viewer: PluginViewer): Promise<ViewerProfile | null>;
+export interface ViewerProfile {
+    userId: string;
+    email: string | null;
+    name: string | null;
+    picture: string | null;
 }
 export type PluginOpHandler = (ctx: PluginOpContext) => Promise<unknown>;
+/**
+ * A server ROUTE the app brings with it: `GET|POST /api/plugins/<id>/route/<name>?nodeId=…`
+ * (declared in plugin.json `routes`). Unlike an op it owns the whole Response — it may
+ * stream (Server-Sent Events via `sseStream`), set headers, return bytes. The platform
+ * resolves the instance and the caller's access before the handler runs; the handler
+ * never sees an unauthenticated request. It runs where the platform's own API routes
+ * run (Fluid compute, minutes-long invocations allowed), so a clock, a poller or a
+ * long-poll can live here — for as long as ONE request lasts. Anything that must
+ * outlive a request is a task (docs/07).
+ */
+export interface PluginRouteContext {
+    pluginId: string;
+    routeName: string;
+    method: "GET" | "POST";
+    request: Request;
+    searchParams: URLSearchParams;
+    workspaceId: string;
+    nodeId: string;
+    instanceName: string;
+    applicationType: string;
+    cloudConnectionId: string | null;
+    /** The caller may mutate this workspace (a viewer of a public share may not). */
+    canWrite: boolean;
+    /** WHO is calling — the same resolved identity every other seam receives. */
+    viewer: PluginViewer;
+}
+export type PluginRouteHandler = (ctx: PluginRouteContext) => Promise<Response>;
 export interface PluginServerModule {
     webhooks?: Record<string, PluginWebhookHandler>;
     ops?: Record<string, PluginOpHandler>;
+    /** routeName → handler, for names declared in plugin.json `routes`. */
+    routes?: Record<string, PluginRouteHandler>;
 }
 export type PluginConnectionCredentials = {
     kind: "oauth2";
@@ -50,6 +200,28 @@ export type PluginConnectionCredentials = {
  * refreshes expiring OAuth tokens). HOST-ONLY.
  */
 export declare function getPluginConnectionCredentials(_connectionId: string, _pluginId: string): Promise<PluginConnectionCredentials>;
+/**
+ * The client for the tables YOUR manifest declared (`db`). Hand it any server
+ * context — an op's, a route's, a task's — and get back a client whose reads
+ * are already scoped to this instance and this caller, and whose writes refuse
+ * what the rules refuse. You write no access checks; you cannot forget one.
+ *
+ *   const db = await pluginDb<ShopDb>(ctx);          // ShopDb from ./.esoul/db
+ *   const mine = await db.order.findMany({ orderBy: { createdAt: "desc" } });
+ *
+ * `across: "owned-instances"` (the owner, across their shops) and `across:
+ * "my-rows"` (an account, across every instance) are read-only reaches.
+ * HOST-ONLY: in a unit test use `memoryDb(manifest)` from `esoul-sdk/testing`.
+ */
+export declare function pluginDb<T = unknown>(_ctx: {
+    pluginId: string;
+    workspaceId: string;
+    nodeId: string;
+    viewer: PluginViewer;
+}, _reach?: {
+    across?: "owned-instances" | "my-rows";
+    viaBinding?: boolean;
+}): Promise<T>;
 export interface EmitPluginAppEventArgs {
     source: {
         pluginId: string;
@@ -187,3 +359,13 @@ export declare function filesForOp(_ctx: {
     workspaceId: string;
     nodeId?: string;
 }): Promise<FilesApi>;
+/**
+ * A Server-Sent Events response. `run` gets `send(event, data)` and the request's
+ * abort signal; return when done (or when the signal fires — the client left). A
+ * heartbeat comment every 15 s keeps proxies from closing an idle stream. Real code,
+ * not host-provided: streaming is the web platform's.
+ */
+export declare function sseStream(run: (send: (event: string, data: unknown) => void, signal: AbortSignal) => Promise<void>, opts?: {
+    signal?: AbortSignal;
+    heartbeatMs?: number;
+}): Response;

package/dist/server.js

@@ -8,6 +8,18 @@
  * Inside the host, `esoul-sdk/server` is aliased to the real
  * implementations.
  */
+/**
+ * WHO IS THIS, IN WORDS. The caller's own name and email, for an app with a
+ * reason to ask — a receipt, an address form they should not retype.
+ *
+ * SERVER ONLY, and only ever about the CALLER: there is no argument for whose
+ * profile to read, so an app cannot look up a person who is not talking to it.
+ * Null for anyone without an account. One database read: call it where you
+ * need it, not on every request.
+ */
+export function viewerProfile(_viewer) {
+    return hostOnly("viewerProfile");
+}
 const hostOnly = (name) => {
     throw new Error(`${name} runs only inside the ExternalSoul host (the app aliases esoul-sdk to its real implementations). In unit tests, mock this module.`);
 };
@@ -18,6 +30,22 @@ const hostOnly = (name) => {
 export function getPluginConnectionCredentials(_connectionId, _pluginId) {
     return hostOnly("getPluginConnectionCredentials");
 }
+/**
+ * The client for the tables YOUR manifest declared (`db`). Hand it any server
+ * context — an op's, a route's, a task's — and get back a client whose reads
+ * are already scoped to this instance and this caller, and whose writes refuse
+ * what the rules refuse. You write no access checks; you cannot forget one.
+ *
+ *   const db = await pluginDb<ShopDb>(ctx);          // ShopDb from ./.esoul/db
+ *   const mine = await db.order.findMany({ orderBy: { createdAt: "desc" } });
+ *
+ * `across: "owned-instances"` (the owner, across their shops) and `across:
+ * "my-rows"` (an account, across every instance) are read-only reaches.
+ * HOST-ONLY: in a unit test use `memoryDb(manifest)` from `esoul-sdk/testing`.
+ */
+export function pluginDb(_ctx, _reach) {
+    return hostOnly("pluginDb");
+}
 /**
  * Cross-app events: dispatch the TARGET app's own events through the
  * platform spine (target's dataCreator mints; triggers fire; every event is
@@ -56,3 +84,55 @@ export function pluginFiles(_ctx) {
 export function filesForOp(_ctx) {
     return hostOnly("filesForOp");
 }
+/**
+ * A Server-Sent Events response. `run` gets `send(event, data)` and the request's
+ * abort signal; return when done (or when the signal fires — the client left). A
+ * heartbeat comment every 15 s keeps proxies from closing an idle stream. Real code,
+ * not host-provided: streaming is the web platform's.
+ */
+export function sseStream(run, opts) {
+    const enc = new TextEncoder();
+    const ac = new AbortController();
+    opts?.signal?.addEventListener("abort", () => ac.abort(), { once: true });
+    const stream = new ReadableStream({
+        start(controller) {
+            let closed = false;
+            const write = (chunk) => {
+                if (closed)
+                    return;
+                try {
+                    controller.enqueue(enc.encode(chunk));
+                }
+                catch {
+                    closed = true;
+                }
+            };
+            const send = (event, data) => write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+            const beat = setInterval(() => write(": keep-alive\n\n"), Math.max(1_000, opts?.heartbeatMs ?? 15_000));
+            const finish = () => {
+                clearInterval(beat);
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    controller.close();
+                }
+                catch {
+                    /* already closed */
+                }
+            };
+            ac.signal.addEventListener("abort", finish, { once: true });
+            write(": open\n\n");
+            run(send, ac.signal).then(finish, (err) => {
+                send("error", { message: err instanceof Error ? err.message : String(err) });
+                finish();
+            });
+        },
+        cancel() {
+            ac.abort();
+        },
+    });
+    return new Response(stream, {
+        headers: { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-cache, no-transform", Connection: "keep-alive", "X-Accel-Buffering": "no" },
+    });
+}