esoul-sdk 0.4.0 → 0.7.0

package/dist/db/schema-gen.js

@@ -0,0 +1,363 @@
+/* ───────────────────────────── naming ─────────────────────────────────── */
+/** `ShipAddress` → `ship_address`; `Order` → `order`. */
+export function snakeCase(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+        .toLowerCase();
+}
+/** The Prisma model name: `plugin_shop_min__Order`. */
+export function prismaModelName(applicationType, model) {
+    return `${applicationType}__${model}`;
+}
+/** The table it maps to: `plugin_shop_min__order`. */
+export function prismaTableName(applicationType, model) {
+    return `${applicationType}__${snakeCase(model)}`;
+}
+/* ───────────────────────── the Prisma fragment ────────────────────────── */
+const PRISMA_SCALAR = {
+    string: "String",
+    text: "String",
+    int: "Int",
+    float: "Float",
+    boolean: "Boolean",
+    datetime: "DateTime",
+    json: "Json",
+    ref: "String",
+};
+function prismaDefault(field) {
+    if (field.default === undefined || field.list)
+        return null;
+    switch (field.type) {
+        case "string":
+        case "text":
+            return `@default(${JSON.stringify(String(field.default))})`;
+        case "int":
+        case "float":
+            return `@default(${Number(field.default)})`;
+        case "boolean":
+            return `@default(${field.default ? "true" : "false"})`;
+        default:
+            // A default on json/datetime/ref has no Prisma spelling worth guessing;
+            // the client applies it on create, which is where it matters.
+            return null;
+    }
+}
+function platformColumns(scope) {
+    return [
+        { name: "id", type: "String", attrs: "@id @default(uuid())" },
+        { name: "workspaceId", type: "String", attrs: "" },
+        // A user-scoped row belongs to an account, not an instance; the memory
+        // client stores null there and the database must accept the same row.
+        { name: "nodeId", type: scope === "user" ? "String?" : "String", attrs: "" },
+        { name: "ownerId", type: "String?", attrs: "" },
+        { name: "createdBy", type: "Json?", attrs: "" },
+        { name: "createdAt", type: "DateTime", attrs: "@default(now())" },
+        { name: "updatedAt", type: "DateTime", attrs: "@updatedAt" },
+        { name: "deletedAt", type: "DateTime?", attrs: "" },
+    ];
+}
+function declaredColumn(name, field, sealed) {
+    const base = sealed ? "String" : PRISMA_SCALAR[field.type];
+    // Prisma scalar lists are never optional and carry no scalar default.
+    const type = field.list ? `${base}[]` : field.optional ? `${base}?` : base;
+    const def = sealed ? null : prismaDefault(field);
+    return { name, type, attrs: def ?? "" };
+}
+function scopeColumn(scope) {
+    return scope === "user" ? "ownerId" : scope === "workspace" ? "workspaceId" : "nodeId";
+}
+function indexGroups(model) {
+    const lead = scopeColumn(model.scope);
+    const out = [];
+    const seen = new Set();
+    const push = (fields, kind = "btree") => {
+        const key = `${kind}:${fields.join(",")}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ fields, kind });
+    };
+    // The scope index every query starts from.
+    push(model.scope === "instance" ? ["workspaceId", "nodeId"] : [lead]);
+    if (model.ownedByCreator && model.scope !== "user")
+        push(["ownerId"]);
+    // Declared groups, `unique` first then `indexes`, each led by the scope
+    // column. A group that already names the lead column is not doubled.
+    for (const group of model.unique)
+        push([lead, ...group.filter((c) => c !== lead)]);
+    for (const idx of model.indexes) {
+        // A GIN index (a list or a trigram search) is single-column and NOT
+        // scope-led: without `btree_gin` it cannot lead with the scope column, so
+        // Postgres bitmap-ANDs it with the scope index instead.
+        if (idx.kind === "btree")
+            push([lead, ...idx.fields.filter((c) => c !== lead)]);
+        else
+            push([...idx.fields], idx.kind);
+    }
+    return out;
+}
+/**
+ * One `@@index(...)` argument list. A trigram index needs the operator class
+ * spelled out (`gin_trgm_ops`) — that is what makes `contains` an index lookup
+ * rather than a scan — and Prisma emits both forms as the SQL we emit below,
+ * which is what keeps the fragment and the DDL in step.
+ */
+function prismaIndexArgs(g) {
+    // QUALIFIED. `pg_trgm` installs its operator class in `public`, and DDL that
+    // runs with a different search_path (the db-test harness makes a throwaway
+    // schema and does exactly that) cannot resolve a bare `gin_trgm_ops`:
+    // `operator class "gin_trgm_ops" does not exist for access method "gin"`.
+    // Measured 2026-09-12 against the real database.
+    if (g.kind === "text")
+        return `[${g.fields[0]}(ops: raw("public.gin_trgm_ops"))], type: Gin`;
+    if (g.kind === "contains")
+        return `[${g.fields.join(", ")}], type: Gin`;
+    return `[${g.fields.join(", ")}]`;
+}
+function renderModel(model, applicationType) {
+    const cols = [
+        ...platformColumns(model.scope),
+        ...Object.keys(model.fields).map((name) => declaredColumn(name, model.fields[name], model.sealed.includes(name))),
+    ];
+    const nameW = Math.max(...cols.map((c) => c.name.length));
+    const typeW = Math.max(...cols.map((c) => c.type.length));
+    const lines = cols.map((c) => {
+        const head = `  ${c.name.padEnd(nameW)} ${c.type.padEnd(typeW)}`;
+        return (c.attrs ? `${head} ${c.attrs}` : head).trimEnd();
+    });
+    const idx = indexGroups(model).map((g) => `  @@index(${prismaIndexArgs(g)})`);
+    return [
+        `model ${prismaModelName(applicationType, model.name)} {`,
+        ...lines,
+        "",
+        ...idx,
+        `  @@map(${JSON.stringify(prismaTableName(applicationType, model.name))})`,
+        "}",
+    ].join("\n");
+}
+/**
+ * The Prisma schema fragment for one app — every model, platform columns
+ * first, scope-led indexes, mapped to a prefixed table. No datasource and no
+ * generator: this is a FRAGMENT that joins the platform's schema folder.
+ */
+export function prismaFragment(rules, opts) {
+    const models = Object.keys(rules.models).map((name) => rules.models[name]);
+    const body = models.map((m) => renderModel(m, opts.applicationType)).join("\n\n");
+    return [
+        `/// AUTO-GENERATED from plugin "${rules.pluginId}" (plugin.json \`db\`) — DO NOT EDIT.`,
+        `/// Regenerated by \`yarn plugins:sync\`. Tables are prefixed \`${opts.applicationType}__\`;`,
+        "/// every row carries the platform's scope columns; indexes lead with the scope column;",
+        "/// declared `unique` groups are plain indexes (uniqueness is enforced among live rows by the client).",
+        "",
+        body,
+        "",
+    ].join("\n");
+}
+/* ─────────────────────────── the typings ──────────────────────────────── */
+const TS_SCALAR = {
+    string: "string",
+    text: "string",
+    int: "number",
+    float: "number",
+    boolean: "boolean",
+    datetime: "Date",
+    json: "unknown",
+    ref: "string",
+};
+function rowFieldType(field) {
+    const base = TS_SCALAR[field.type];
+    if (field.list)
+        return `${base}[]`;
+    return field.optional ? `${base} | null` : base;
+}
+function createFieldType(field) {
+    const base = TS_SCALAR[field.type];
+    if (field.list)
+        return `${base}[]`;
+    return field.optional ? `${base} | null` : base;
+}
+function quoteKey(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+function renderRows(model) {
+    const platform = [
+        "  id: string;",
+        "  workspaceId: string;",
+        `  nodeId: ${model.scope === "user" ? "string | null" : "string"};`,
+        "  ownerId: string | null;",
+        "  createdAt: Date;",
+        "  updatedAt: Date;",
+    ];
+    const declared = Object.keys(model.fields).map((n) => `  ${quoteKey(n)}: ${rowFieldType(model.fields[n])};`);
+    return [`export interface ${model.name}Row {`, ...platform, ...declared, "}"].join("\n");
+}
+function renderCreate(model) {
+    const declared = Object.keys(model.fields).map((n) => {
+        const f = model.fields[n];
+        const optional = f.optional || f.default !== undefined || f.list;
+        return `  ${quoteKey(n)}${optional ? "?" : ""}: ${createFieldType(f)};`;
+    });
+    return [`export interface ${model.name}Create {`, ...declared, "}"].join("\n");
+}
+function renderFilterable(model) {
+    const keys = model.filterable.map((k) => JSON.stringify(k)).join(" | ");
+    return `export type ${model.name}Filterable = ${keys || "never"};`;
+}
+/**
+ * The `.esoul/db.d.ts` for one app: a `<Model>Row` and `<Model>Create` per
+ * model, a `<Model>Filterable` union that is exactly the compiled `filterable`
+ * list (so `where` and `orderBy` on an unindexed field are compile errors —
+ * the runtime rule, landed in the editor), and one `Collection` shape mirroring
+ * the memory client's method surface. Everything an author calls is typed with
+ * their own names; nothing here knows the table prefix.
+ */
+export function dbTypings(rules, opts) {
+    const models = Object.keys(rules.models).map((name) => rules.models[name]);
+    const parts = [
+        `/** AUTO-GENERATED from plugin "${rules.pluginId}" (plugin.json \`db\`) — DO NOT EDIT. Regenerated by \`yarn plugins:sync\`. */`,
+        "",
+        "export type Scalar = string | number | boolean | Date | null;",
+        "export type Filter<V> =",
+        "  | V",
+        "  | { in: V[] }",
+        "  | { notIn: V[] }",
+        "  | { not: V }",
+        "  | { gt: V }",
+        "  | { gte: V }",
+        "  | { lt: V }",
+        "  | { lte: V }",
+        "  | { contains: string };",
+        "/** A LIST field takes one question: does it hold this? (a `contains` index answers it) */",
+        "export type ListFilter<V> = { has: V };",
+        "/** Only INDEXED fields may be filtered — the generator emits the union per model. */",
+        "export type Where<T, K extends keyof T> = {",
+        "  [P in K]?: T[P] extends readonly (infer E)[] ? ListFilter<E> : T[P] extends Scalar ? Filter<T[P]> : never;",
+        "};",
+        "export type OrderBy<K extends string> = { [P in K]?: \"asc\" | \"desc\" };",
+        "",
+        "export interface FindManyArgs<T, K extends keyof T & string> {",
+        "  where?: Where<T, K>;",
+        "  orderBy?: OrderBy<K> | OrderBy<K>[];",
+        "  take?: number;",
+        "  skip?: number;",
+        "  cursor?: { id: string };",
+        "  includeDeleted?: boolean;",
+        "}",
+        "export interface AggregateArgs<T, K extends keyof T & string> {",
+        "  where?: Where<T, K>;",
+        "  _count?: true;",
+        "  _sum?: Partial<Record<keyof T & string, true>>;",
+        "  _avg?: Partial<Record<keyof T & string, true>>;",
+        "  _min?: Partial<Record<keyof T & string, true>>;",
+        "  _max?: Partial<Record<keyof T & string, true>>;",
+        "}",
+        "export interface GroupByArgs<T, K extends keyof T & string> extends AggregateArgs<T, K> {",
+        "  by: K[];",
+        "}",
+        "",
+        "export interface Collection<Row, Create, K extends keyof Row & string> {",
+        "  findMany(args?: FindManyArgs<Row, K>): Promise<Row[]>;",
+        "  findFirst(args?: FindManyArgs<Row, K>): Promise<Row | null>;",
+        "  findUnique(args: { where: { id: string }; includeDeleted?: boolean }): Promise<Row | null>;",
+        "  count(args?: { where?: Where<Row, K>; includeDeleted?: boolean }): Promise<number>;",
+        "  aggregate(args?: AggregateArgs<Row, K>): Promise<Record<string, unknown>>;",
+        "  groupBy(args: GroupByArgs<Row, K>): Promise<Record<string, unknown>[]>;",
+        "  create(args: { data: Create }): Promise<Row>;",
+        "  createMany(args: { data: Create[] }): Promise<{ count: number }>;",
+        "  update(args: { where: { id: string }; data: Partial<Create> }): Promise<Row>;",
+        "  updateMany(args: { where?: Where<Row, K>; data: Partial<Create> }): Promise<{ count: number }>;",
+        "  upsert(args: { where: { id: string }; create: Create; update: Partial<Create> }): Promise<Row>;",
+        "  delete(args: { where: { id: string } }): Promise<Row>;",
+        "  deleteMany(args?: { where?: Where<Row, K> }): Promise<{ count: number }>;",
+        "}",
+        "",
+    ];
+    for (const m of models) {
+        parts.push(renderRows(m), renderCreate(m), renderFilterable(m), "");
+    }
+    parts.push(`export interface ${opts.typeName} {`);
+    for (const m of models) {
+        parts.push(`  ${quoteKey(m.key)}: Collection<${m.name}Row, ${m.name}Create, ${m.name}Filterable>;`);
+    }
+    parts.push(`  $transaction<T>(fn: (tx: ${opts.typeName}) => Promise<T>): Promise<T>;`, "}", "");
+    return parts.join("\n");
+}
+/** The compiled artefact as the bytes `.esoul/rules.json` holds. */
+export function rulesJson(rules) {
+    return JSON.stringify(rules, null, 2) + "\n";
+}
+const SQL_OF_PRISMA = {
+    String: "TEXT",
+    Int: "INTEGER",
+    Float: "DOUBLE PRECISION",
+    Boolean: "BOOLEAN",
+    DateTime: "TIMESTAMP(3)",
+    Json: "JSONB",
+};
+function sqlColumn(c) {
+    const list = c.type.endsWith("[]");
+    const optional = c.type.endsWith("?");
+    const base = c.type.replace(/\[\]$|\?$/, "");
+    const sql = SQL_OF_PRISMA[base];
+    if (!sql)
+        throw new Error(`[schema-gen] no SQL type for Prisma ${base}`);
+    let def = null;
+    const m = /@default\((.*)\)/.exec(c.attrs);
+    if (m) {
+        const raw = m[1];
+        if (raw === "now()")
+            def = "CURRENT_TIMESTAMP";
+        else if (raw === "uuid()")
+            def = null; // the client mints ids; Prisma's DDL carries no default either
+        else if (/^".*"$/.test(raw))
+            def = `'${JSON.parse(raw).replace(/'/g, "''")}'`;
+        else
+            def = raw; // a number or true/false
+    }
+    // Prisma emits a scalar list WITHOUT `NOT NULL` (an absent list is an empty
+    // one, not a null), so a list column must not carry the constraint either —
+    // or the planner would read a difference against the live table forever.
+    return { name: c.name, type: list ? `${sql}[]` : sql, nullable: optional || list, default: def };
+}
+/** Prisma's index name: `<table>_<col>_<col>_idx`. */
+export function indexName(table, columns) {
+    return `${table}_${columns.join("_")}_idx`;
+}
+/** Every table an app declares, as columns and indexes — the input to the planner and the emitter. */
+export function tableSpecs(rules, opts) {
+    return Object.keys(rules.models).map((name) => {
+        const model = rules.models[name];
+        const table = prismaTableName(opts.applicationType, model.name);
+        const cols = [
+            ...platformColumns(model.scope),
+            ...Object.keys(model.fields).map((f) => declaredColumn(f, model.fields[f], model.sealed.includes(f))),
+        ];
+        return {
+            name: table,
+            columns: cols.map(sqlColumn),
+            indexes: indexGroups(model).map((g) => ({ name: indexName(table, g.fields), columns: g.fields, kind: g.kind })),
+        };
+    });
+}
+const q = (ident) => `"${ident}"`;
+function columnDef(c) {
+    return `${q(c.name)} ${c.type}${c.nullable ? "" : " NOT NULL"}${c.default !== null ? ` DEFAULT ${c.default}` : ""}`;
+}
+export function createTableSql(t) {
+    return [`CREATE TABLE ${q(t.name)} (`, ...t.columns.map((c) => `    ${columnDef(c)},`), "", `    CONSTRAINT ${q(`${t.name}_pkey`)} PRIMARY KEY ("id")`, ");"].join("\n");
+}
+export function createIndexSql(table, idx) {
+    if (idx.kind === "text")
+        return `CREATE INDEX ${q(idx.name)} ON ${q(table)} USING GIN (${q(idx.columns[0])} public.gin_trgm_ops);`;
+    if (idx.kind === "contains")
+        return `CREATE INDEX ${q(idx.name)} ON ${q(table)} USING GIN (${idx.columns.map(q).join(", ")});`;
+    return `CREATE INDEX ${q(idx.name)} ON ${q(table)}(${idx.columns.map(q).join(", ")});`;
+}
+export function addColumnSql(table, c) {
+    return `ALTER TABLE ${q(table)} ADD COLUMN ${columnDef(c)};`;
+}
+/** The whole script for a fresh install: tables first, then every index — Prisma's order. */
+export function ddlStatements(specs) {
+    return [...specs.map(createTableSql), ...specs.flatMap((t) => t.indexes.map((i) => createIndexSql(t.name, i)))];
+}

package/dist/helpers.d.ts

@@ -31,7 +31,54 @@ export declare function incompleteStateNotice(args: {
  * side rides the session. Throws the op's honest error — relay it, never
  * swallow it.
  */
+/**
+ * The public share this page is being viewed through, or null.
+ *
+ * A customer browsing a shop is on `/share/<id>` — they have no workspace
+ * session at all, so the platform needs the share id to know which door they
+ * are standing at before it will let them reach a `public` op or route. Read
+ * from the URL rather than plumbed through the app, because the URL is the one
+ * thing that is true on every surface without the app having to care.
+ *
+ * A share reached through `/u/<handle>` or a custom domain resolves its share
+ * server-side and is NOT in the path. The platform tells the page which share
+ * it is standing on (`window.__esoulShareId`, written by the frame that
+ * renders the app), and that is read first. The day this was left to the app
+ * ("pass `shareId` yourself there") a shop published as a homepage answered
+ * `forbidden` to every visitor (2026-09-12): an app cannot know a thing only
+ * the platform resolved.
+ */
+export declare function currentShareId(): string | null;
+/**
+ * VIEW AS, from the browser's side. In a Forge preview the board's switcher
+ * writes a persona onto the window; every call the app's UI makes then carries
+ * it, so the server sees the same pretend person the screen shows. Absent
+ * outside a preview: the platform never reads it, and the header is not sent.
+ */
+export declare function previewPersona(): string | null;
 export declare function callPluginOp<T = unknown>(pluginId: string, op: string, nodeId: string, args?: unknown): Promise<T>;
+/**
+ * What a failed op call throws. It CARRIES the platform's refusal code, so a
+ * UI can tell `login-required` (raise the sign-in wall) from `forbidden` (an
+ * error) — `useSignInWall().raise(err)` reads exactly this. A bare `Error`
+ * dropped the code, and the wall never rose (found by the first S6 drive).
+ */
+export declare class PluginCallError extends Error {
+    /** HTTP status of the answer. */
+    readonly status: number;
+    /** `forbidden` | `login-required` | `not-bound` | `rate-limited` | `invalid`, when the platform said which. */
+    readonly code?: string;
+    /** Where to send the browser to sign in (`login-required` only). */
+    readonly signInPath?: string;
+    /** The author's explanation — present only in a workbench box. */
+    readonly detail?: string;
+    constructor(message: string, args: {
+        status: number;
+        code?: string;
+        signInPath?: string;
+        detail?: string;
+    });
+}
 /**
  * Constant-time string compare for webhook secrets/signatures. A plain
  * `===` leaks length/prefix timing; use THIS in every webhook handler.
@@ -58,3 +105,8 @@ export declare function kickPluginTask(args: {
     ok: boolean;
     status: number;
 }>;
+/**
+ * The URL of one of your server routes (docs/06) for one instance — what an
+ * `EventSource` or `fetch` in your UI opens. Same origin; the session rides along.
+ */
+export declare function pluginRouteUrl(pluginId: string, routeName: string, nodeId: string, params?: Record<string, string | number | boolean>): string;

package/dist/helpers.js

@@ -57,25 +57,100 @@ export function incompleteStateNotice(args) {
  * side rides the session. Throws the op's honest error — relay it, never
  * swallow it.
  */
+/**
+ * The public share this page is being viewed through, or null.
+ *
+ * A customer browsing a shop is on `/share/<id>` — they have no workspace
+ * session at all, so the platform needs the share id to know which door they
+ * are standing at before it will let them reach a `public` op or route. Read
+ * from the URL rather than plumbed through the app, because the URL is the one
+ * thing that is true on every surface without the app having to care.
+ *
+ * A share reached through `/u/<handle>` or a custom domain resolves its share
+ * server-side and is NOT in the path. The platform tells the page which share
+ * it is standing on (`window.__esoulShareId`, written by the frame that
+ * renders the app), and that is read first. The day this was left to the app
+ * ("pass `shareId` yourself there") a shop published as a homepage answered
+ * `forbidden` to every visitor (2026-09-12): an app cannot know a thing only
+ * the platform resolved.
+ */
+export function currentShareId() {
+    if (typeof window === "undefined")
+        return null;
+    const told = window.__esoulShareId;
+    if (typeof told === "string" && told)
+        return told;
+    const m = /^\/share\/([^/?#]+)/.exec(window.location.pathname);
+    return m ? decodeURIComponent(m[1]) : null;
+}
+/**
+ * VIEW AS, from the browser's side. In a Forge preview the board's switcher
+ * writes a persona onto the window; every call the app's UI makes then carries
+ * it, so the server sees the same pretend person the screen shows. Absent
+ * outside a preview: the platform never reads it, and the header is not sent.
+ */
+export function previewPersona() {
+    if (typeof window === "undefined")
+        return null;
+    if (!window.location.pathname.includes("/internal/plugin-preview"))
+        return null;
+    const p = window.__esoulPreviewViewer;
+    return typeof p === "string" && p ? p : null;
+}
+const PREVIEW_VIEWER_HEADER = "x-esoul-preview-viewer";
+function previewViewerHeaders() {
+    const p = previewPersona();
+    return p ? { [PREVIEW_VIEWER_HEADER]: p } : {};
+}
 export async function callPluginOp(pluginId, op, nodeId, args) {
-    const serverBase = typeof window === "undefined"
-        ? process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000"
-        : "";
-    const headers = { "Content-Type": "application/json" };
-    if (typeof window === "undefined" && process.env.INTERNAL_TOOL_SECRET) {
+    const onServer = typeof window === "undefined";
+    const serverBase = onServer ? process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000" : "";
+    const headers = { "Content-Type": "application/json", ...previewViewerHeaders() };
+    if (onServer && process.env.INTERNAL_TOOL_SECRET) {
         headers["x-esoul-internal-secret"] = process.env.INTERNAL_TOOL_SECRET;
     }
-    const res = await fetch(`${serverBase}/api/plugins/${pluginId}/op/${op}`, {
+    // A Forge preview serves ops on its own lean route over the workbench store (docs/10).
+    const inPreview = onServer ? process.env.WORKBENCH_STORE === "1" : window.location.pathname.includes("/internal/plugin-preview");
+    const res = await fetch(inPreview ? `${serverBase}/internal/plugin-preview/op/${pluginId}/${op}` : `${serverBase}/api/plugins/${pluginId}/op/${op}`, {
         method: "POST",
         headers,
-        body: JSON.stringify({ nodeId, args }),
+        body: JSON.stringify({ nodeId, args, ...(currentShareId() ? { shareId: currentShareId() } : {}) }),
     });
     const body = (await res.json().catch(() => null));
     if (!res.ok || !body?.ok) {
-        throw new Error(body?.error ?? `plugin op ${pluginId}/${op} failed (HTTP ${res.status})`);
+        throw new PluginCallError(body?.error ?? `plugin op ${pluginId}/${op} failed (HTTP ${res.status})`, {
+            status: res.status,
+            code: body?.code,
+            signInPath: body?.signInPath,
+            detail: body?.detail,
+        });
     }
     return body.result;
 }
+/**
+ * What a failed op call throws. It CARRIES the platform's refusal code, so a
+ * UI can tell `login-required` (raise the sign-in wall) from `forbidden` (an
+ * error) — `useSignInWall().raise(err)` reads exactly this. A bare `Error`
+ * dropped the code, and the wall never rose (found by the first S6 drive).
+ */
+export class PluginCallError extends Error {
+    /** HTTP status of the answer. */
+    status;
+    /** `forbidden` | `login-required` | `not-bound` | `rate-limited` | `invalid`, when the platform said which. */
+    code;
+    /** Where to send the browser to sign in (`login-required` only). */
+    signInPath;
+    /** The author's explanation — present only in a workbench box. */
+    detail;
+    constructor(message, args) {
+        super(message);
+        this.name = "PluginCallError";
+        this.status = args.status;
+        this.code = args.code;
+        this.signInPath = args.signInPath;
+        this.detail = args.detail;
+    }
+}
 /* ── webhook secret comparison ──────────────────────────────────────── */
 /**
  * Constant-time string compare for webhook secrets/signatures. A plain
@@ -101,10 +176,13 @@ export function timingSafeEqual(a, b) {
 export async function kickPluginTask(args) {
     const onServer = typeof window === "undefined";
     const base = onServer ? (process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000") : "";
-    const headers = { "Content-Type": "application/json" };
+    const headers = { "Content-Type": "application/json", ...previewViewerHeaders() };
     if (onServer && process.env.INTERNAL_TOOL_SECRET)
         headers["x-esoul-internal-secret"] = process.env.INTERNAL_TOOL_SECRET;
-    const res = await fetch(`${base}/api/inngest/send-event`, {
+    // A Forge preview has no Inngest: its dev server runs the task in-process behind the same
+    // ctx contract, kicked through the preview's own route. Same app code, a different transport.
+    const inPreview = onServer ? process.env.WORKBENCH_STORE === "1" : window.location.pathname.includes("/internal/plugin-preview");
+    const res = await fetch(inPreview ? `${base}/internal/plugin-preview/kick` : `${base}/api/inngest/send-event`, {
         method: "POST",
         headers,
         body: JSON.stringify({
@@ -120,3 +198,21 @@ export async function kickPluginTask(args) {
     });
     return { ok: res.ok, status: res.status };
 }
+/**
+ * The URL of one of your server routes (docs/06) for one instance — what an
+ * `EventSource` or `fetch` in your UI opens. Same origin; the session rides along.
+ */
+export function pluginRouteUrl(pluginId, routeName, nodeId, params) {
+    const share = currentShareId();
+    const persona = previewPersona();
+    const q = new URLSearchParams({
+        nodeId,
+        ...(share ? { shareId: share } : {}),
+        ...(persona ? { viewer: persona } : {}),
+        ...Object.fromEntries(Object.entries(params ?? {}).map(([k, v]) => [k, String(v)])),
+    });
+    const inPreview = typeof window !== "undefined" && window.location.pathname.includes("/internal/plugin-preview");
+    return inPreview
+        ? `/internal/plugin-preview/route/${encodeURIComponent(pluginId)}/${encodeURIComponent(routeName)}?${q.toString()}`
+        : `/api/plugins/${encodeURIComponent(pluginId)}/route/${encodeURIComponent(routeName)}?${q.toString()}`;
+}

package/dist/index.d.ts

@@ -2,6 +2,11 @@ export * from "./types.js";
 export * from "./manifest.js";
 export * from "./helpers.js";
 export * from "./files.js";
+export * from "./bindings.js";
+/** WHO hears a realtime message (S8): topic audiences, and who may aim one. */
+export * from "./audience.js";
+/** The app's own words for the platform's kinds of caller (S3). */
+export * from "./roles.js";
 /** Id minting for dataCreators; an app depends on the SDK, not on nanoid. */
 export { nanoid } from "nanoid";
 /**

package/dist/index.js

@@ -2,6 +2,11 @@ export * from "./types.js";
 export * from "./manifest.js";
 export * from "./helpers.js";
 export * from "./files.js";
+export * from "./bindings.js";
+/** WHO hears a realtime message (S8): topic audiences, and who may aim one. */
+export * from "./audience.js";
+/** The app's own words for the platform's kinds of caller (S3). */
+export * from "./roles.js";
 /** Id minting for dataCreators; an app depends on the SDK, not on nanoid. */
 export { nanoid } from "nanoid";
 /**