npm - @plitzi/sdk-shared - Versions diffs - 0.33.2 → 0.34.1 - Mend

@plitzi/sdk-shared 0.33.2 → 0.34.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (204) hide show

package/dist/types/ServerTypes.d.ts CHANGED Viewed

@@ -1,8 +1,9 @@
+import { ActionEntry, ActionLimits, ActionRejectReason, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionTaskDescriptor, ActionTriggerType } from './ActionTypes';
 import { Environment } from './CommonTypes';
 import { ConnectorEntry } from './ConnectorTypes';
 import { Schema } from './SchemaTypes';
 import { AnalyticsConfig, OfflineDataRaw } from './SdkTypes';
-import { Style } from './StyleTypes';
+import { FontHead, Style } from './StyleTypes';
 import { IncomingHttpHeaders } from 'node:http';
 import { FC } from 'react';
 export type ServerEnvironment = 'development' | 'production' | 'staging' | 'local';
@@ -33,7 +34,11 @@ export type SSRResponseHelpers = {
      *  several, and collapsing them into one string would produce a single malformed cookie. */
     setHeader: (name: string, value: string | string[]) => void;
     setStatus: (code: number) => void;
-    send: (body: string) => void;
+    /**
+     * A `Buffer` is sent byte for byte and never compressed: it is how a binary reaches the wire — a font file, an
+     * image — and what it holds is usually compressed already. A string keeps the encoding negotiation.
+     */
+    send: (body: string | Buffer) => void;
     write: (chunk: string | Buffer) => void;
     end: () => void;
 };
@@ -46,7 +51,18 @@ export type SSRCredential = {
     provider: string;
     data: unknown;
 };
-export type PluginAction = 'copy' | 'compile' | 'download';
+/**
+ * How a plugin's build reaches the page.
+ *
+ * `copy`, `compile` and `download` all end with a file on this server's disk, which is also what lets the SSR
+ * render import the component and put its output in the HTML. `cdn` deliberately does not: the published URL is
+ * handed straight to the browser and the plugin renders on the client only.
+ *
+ * That trade is worth taking for a plugin this server did not build. Importing a third-party bundle into the
+ * render process means the bundle's own copy of React runs inside the renderer, and two copies of React is an
+ * invalid hook call — a crash that takes the whole page down rather than the one component.
+ */
+export type PluginAction = 'copy' | 'compile' | 'download' | 'cdn';
 export type PluginSourceFile<T = Record<string, unknown>> = {
     js: string;
     css?: string;
@@ -74,9 +90,19 @@ export type PluginEntry = {
     filePath?: string;
     css?: string;
     props: Record<string, unknown>;
+    /**
+     * Whether the SSR render actually included this plugin's own output.
+     *
+     * False for a plugin served straight from its CDN, and for one whose server-side import failed. Either way the
+     * client must not render it on the hydration pass: the markup would not be in the document React is hydrating
+     * against, and the mismatch throws away the whole tree it happens in.
+     */
+    ssr?: boolean;
 };
 export type SSRTemplateProps = {
     title?: string;
+    /** Meta description for the document, and the share-preview text derived from it. */
+    description?: string;
     jsPath?: string;
     cssPath?: string;
     builderJsPath?: string;
@@ -90,15 +116,52 @@ export type SSRTemplateProps = {
     /** When true the client-side <script> block is omitted — useful for inspecting raw SSR HTML. */
     ssrOnly?: boolean;
     debugMode?: boolean;
+    /**
+     * The theme class this document wears on `<html>` — `dark`, `light`, or nothing at all.
+     *
+     * The theme is kept in a cookie, so the server that renders the document already knows it: the page arrives
+     * painted correctly, with no blocking script in the head and no first paint in the other theme. Empty is not a
+     * failure — it is `system`, and the stylesheet's `prefers-color-scheme` queries answer it.
+     */
+    themeClass?: string;
+    /**
+     * The document's web fonts: `fontsToHead(style.fonts, ...)` from this package.
+     *
+     * In the template rather than left to the SDK because a page paints before its JavaScript exists. A face
+     * requested at hydration arrives after the text it is for has already been drawn in a fallback, which is a
+     * reflow the visitor watches happen.
+     */
+    fonts?: FontHead;
+};
+/**
+ * How a store-relative font path becomes a URL a browser can fetch.
+ *
+ * A space's manifest stores paths, never absolute URLs: the same space is rendered by Plitzi's cloud from a CDN,
+ * by a self-hosted server from its own disk, and by a static export from wherever it was published to. Baking one
+ * of those origins into the document would send every other deployment asking Plitzi for its customer's fonts.
+ */
+export type SSRFontsConfig = {
+    /** Prefix joined to each path, e.g. `/fonts` or `https://cdn.example.com/fonts`. Default: `/fonts`. */
+    baseUrl?: string;
+    /**
+     * A directory this server serves the uploaded files from, under `/fonts/*`.
+     *
+     * The self-hosting answer, and the reason `baseUrl` defaults to a path rather than an origin: with a directory
+     * here a deployment needs no object storage, no credentials and no network to serve its customers' fonts. A
+     * cloud deployment leaves it out and points `baseUrl` at its CDN instead.
+     */
+    dir?: string;
 };
 export type SSRPlugin = {
     component: FC;
     props: Record<string, unknown>;
 };
 /** What a space token is worth. `render` is the public credential every published site embeds — it is readable
- *  by anyone who views the page, so it may only read. `agent` is the delegated grant an MCP connector receives
- *  after a member consents, and is the only bearer that may write without a session behind it. */
-export type SpaceScope = 'render' | 'agent';
+ *  by anyone who views the page, so it may only read, and only from the origins it declares. `host` is that same
+ *  read access for a SERVER that renders the space as its own (self-hosting): secret rather than published, since
+ *  a server has no browser origin for the allowlist to check. `agent` is the delegated grant an MCP connector
+ *  receives after a member consents, and is the only bearer that may write without a session behind it. */
+export type SpaceScope = 'render' | 'agent' | 'host';
 /** A resolved space token: which space, what the bearer may do, and (for `agent`) the member who consented.
  *  `canWrite` is computed by the consumer from its own authorization model — the MCP never derives it. */
 export type SSRGrant = {
@@ -220,9 +283,9 @@ export type SSRAdapters = {
     /** Which space, environment and revision a request resolves to. Optional here for the same reason as
      *  `getOfflineData`: MCP resolves its space from the request token (`getGrant`), never from the host. */
     getSpaceDeployment?: (req: SSRRequest) => Promise<SSRSpaceDeployment>;
-    /** Persist a space mutated by the mcp-ai `apply` tool. Implementations must recompute derived caches
-     *  (notably `style.cache`) before storing. When omitted, mcp-ai runs read/preview/validate only and
-     *  `apply` reports `persisted: false`. */
+    /** Persist a space mutated by the mcp-ai `apply` tool — store it as given; derived caches (notably `style.cache`)
+     *  arrive already compiled. When omitted, mcp-ai runs read/preview/validate only and `apply` reports
+     *  `persisted: false`. */
     saveOfflineData?: (spaceId: number, environment: string, data: OfflineDataRaw) => Promise<void>;
     /** Resolve the grant the MCP request operates under, from the verified `Authorization` bearer. The consumer
      *  owns the JWT secret and the authorization model, so it decides here; the MCP service stays stateless.
@@ -249,10 +312,25 @@ export type SSRAdapters = {
     saveConnector?: (spaceId: number, entry: ConnectorEntry) => Promise<void>;
     /** Remove one connector by its identifier. Omitted alongside `saveConnector` for a read-only deployment. */
     deleteConnector?: (spaceId: number, connectorId: string) => Promise<void>;
+    /** Read every server action configured for the space, so the MCP can list them and author flows against them.
+     *  Space-level server-side state like connectors: the documents name credentials, connectors and steps, so this
+     *  must never feed a browser payload. When omitted, the MCP's action resource is empty. */
+    getActions?: (spaceId: number) => Promise<ActionEntry[] | undefined>;
+    /** The server tasks a flow can be built from — what THIS deployment can run, which is the SDK's built-ins plus
+     *  whatever tasks it registered. Shaped as `ActionTaskDescriptor` in `@plitzi/sdk-server/actions`. Without it an
+     *  agent authoring an action is guessing at the step vocabulary. */
+    getActionTasks?: (spaceId: number) => Promise<ActionTaskDescriptor[] | undefined>;
+    /** Create or replace one action, keyed by `entry.id`. When omitted, action ops apply in memory only and `apply`
+     *  reports `persisted: false`. */
+    saveAction?: (spaceId: number, entry: ActionEntry) => Promise<void>;
+    /** Remove one action by its identifier. Omitted alongside `saveAction` for a read-only deployment. */
+    deleteAction?: (spaceId: number, actionId: string) => Promise<void>;
     /** Persist the element schema mutated by the MCP `apply` tool. When omitted, `apply` reports `persisted: false`. */
     saveSchema?: (spaceId: number, environment: Environment, schema: Schema) => Promise<void>;
-    /** Persist the style document mutated by the MCP `apply` tool. Implementations must recompute `style.cache`
-     *  before storing. When omitted, `apply` reports `persisted: false`. */
+    /** Persist the style document mutated by the MCP `apply` tool — store it as given. `style.cache` arrives already
+     *  compiled: the renderer serves that string and nothing else, so recomputing it is not a detail to delegate, and
+     *  asking every deployment to remember it was one bug each of them could write alone. When omitted, `apply`
+     *  reports `persisted: false`. */
     saveStyle?: (spaceId: number, environment: Environment, style: Style) => Promise<void>;
     /** Who this request carries, if anyone. The adapter reads the credential and resolves it; the cookie it arrived
      *  in was written by the server, from {@link SSRAuthCookie}. */
@@ -363,17 +441,130 @@ export interface SSRRscContext {
      */
     loadOfflineData: () => Promise<OfflineDataRaw | undefined>;
 }
+/**
+ * Which published version of a space is asking.
+ *
+ * Absent means the live one — the document the builder edits. Present means a page PUBLISHED at that revision,
+ * which must read the private documents it was published against: a page shipped yesterday running whatever the
+ * action says today, or reading through a manifest since pointed at a different API, is the discrepancy
+ * versioning exists to remove.
+ *
+ * One type for actions and connectors, because it is one concept: a version of a space.
+ */
+export type SpaceRevision = {
+    environment: Environment;
+    revision: number;
+};
+/**
+ * How the server reaches a space's actions, and what it may run.
+ *
+ * Typed loosely for the same reason `ConnectorLookupsConfig` is — the document is executed by
+ * `@plitzi/sdk-server`'s actions module and the shared types stay free of its internals. Shaped as `ActionLookups`
+ * there.
+ */
+export type ActionLookupsConfig = {
+    getAction: (spaceId: number, actionId: string, at?: SpaceRevision) => Promise<unknown>;
+    listActions?: (spaceId: number, at?: SpaceRevision) => Promise<unknown[]>;
+    getCredential?: (spaceId: number, identifier: string) => Promise<Record<string, string> | undefined>;
+    getConnector?: (spaceId: number, connectorId: string, at?: SpaceRevision) => Promise<unknown>;
+};
 export type SSRActionConfig = {
-    /** URL path for the write endpoint. Defaults to '/_action'. */
+    /** URL path for the write endpoint, and the base for the action-addressed routes. Defaults to '/_action'. */
     path?: string;
-    /** Connector manifest and credential lookups. Without them the endpoint stays inert: a write can only be
-     *  authorized against a manifest, and there is nothing to authorize against. Shaped as `ConnectorLookups`
-     *  in `@plitzi/sdk-server`; typed loosely here so the shared types stay free of the server's internals. */
-    lookups?: {
-        getConnector: (spaceId: number, connectorId: string) => Promise<unknown>;
-        getCredential?: (spaceId: number, identifier: string) => Promise<Record<string, string> | undefined>;
-        fetchImpl?: typeof fetch;
+    /**
+     * Supplying these is what turns server actions on: without a way to read a document there is nothing to run, and
+     * the endpoint keeps answering element-addressed connector writes alone.
+     */
+    lookups?: ActionLookupsConfig;
+    /** Deployment-owned tasks, shaped as `ActionTask` in `@plitzi/sdk-server/actions`. Validated at boot. */
+    tasks?: unknown[];
+    /** Ceilings for every run this server accepts. A document may tighten them, never widen them. */
+    limits?: ActionLimits;
+    /**
+     * Concurrency ceilings.
+     *
+     * `perSpace`/`perProcess` count CALLS — a click, a webhook, a schedule — where one run is somebody asking for
+     * work and one space's callers must not starve another's. A `render` is counted only by `renderPerProcess`,
+     * because it arrives because people are reading the page: a ceiling per space there would refuse the five
+     * hundredth visitor of a page that is simply doing well.
+     */
+    concurrency?: {
+        perSpace?: number;
+        perProcess?: number;
+        renderPerProcess?: number;
+    };
+    /** Inbound webhooks are public by construction, so they are counted per caller per minute. Default 60. */
+    rateLimit?: {
+        webhookPerMinute?: number;
     };
+    /**
+     * Database engines a flow may reach, shaped as `ActionDbDriver` in `@plitzi/sdk-server/actions`.
+     *
+     * Omitted leaves the `db.query` task unregistered entirely. What a driver connects to is always a database the
+     * SPACE declared as a credential — never this deployment's own, which no credential a space holds can name.
+     */
+    dbDrivers?: unknown[];
+    /**
+     * Called once per run that STARTED — completed, failed or aborted — for a deployment that keeps a record.
+     * Shaped as `ActionRunRecord` in `@plitzi/sdk-server/actions`.
+     *
+     * A refused request is not a run and is not reported here; it goes to {@link SSRActionConfig.onReject}.
+     */
+    onRun?: (record: ActionRunRecord) => void | Promise<void>;
+    /**
+     * Called once per request that was REFUSED before it became a run — a webhook whose signature did not verify, a
+     * caller over the rate limit, an action nobody may start. Shaped as `ActionRejectRecord`.
+     *
+     * Its own hook because it answers a different question from `onRun`: runs are history, refusals are a fault
+     * report, and the one that matters most — a signature that does not match — is otherwise indistinguishable
+     * from the integration simply never firing. Everything is reported; which refusals are worth keeping (a
+     * duplicate delivery is a polite retry, not a fault) is the deployment's to decide.
+     */
+    onReject?: (record: ActionRejectRecord) => void | Promise<void>;
+    /**
+     * Replaying a finished run's answer to a caller that asks again with the same key, for this many milliseconds.
+     *
+     * Off unless set, and it only ever applies to a key the CALLER named — an `idempotencyKey` on the call or the
+     * delivery id a webhook sender stamps. Single-flight already refuses a retry that arrives while the first run
+     * is going; this is for the one that arrives after it finished, which is how every provider retries.
+     */
+    idempotency?: {
+        replayTtlMs?: number;
+    };
+    /**
+     * Where the `kv` tasks keep things — shaped as `ActionKvAdapter` in `@plitzi/sdk-server/actions`.
+     *
+     * Five operations over strings, with no rule to obey: Redis, Memcached, a table, whatever this deployment
+     * already runs. How a counter BEHAVES — the key prefixing, the JSON round trip, and the rule that a window's
+     * lifetime is set once by whoever created it — belongs to the server, not to the thing it writes into.
+     *
+     * Omitted leaves an in-process Map, which counts only its own replica. That is fine for one; for a cluster it is
+     * a rate limit that multiplies by the number of them, so a multi-replica deployment supplies a shared one.
+     */
+    kv?: {
+        get: (key: string) => Promise<string | undefined>;
+        set: (key: string, value: string, ttlSeconds?: number) => Promise<void>;
+        delete: (key: string) => Promise<void>;
+        increment: (key: string, amount: number) => Promise<number>;
+        expire: (key: string, ttlSeconds: number) => Promise<void>;
+    };
+};
+/**
+ * How the server reaches a space's connectors: the manifest that describes one, and the credential it authenticates
+ * with. Shaped as `ConnectorLookups` in `@plitzi/sdk-server`; typed loosely here so the shared types stay free of the
+ * server's internals.
+ *
+ * Top-level, and not under `action`, because BOTH directions need them. Supplying them is what makes the write
+ * endpoint able to authorize a write — a write can only be checked against a manifest — and it is also all the server
+ * needs to answer a server-driven element's READ, so `adapters.getRscData` is derived from them unless a deployment
+ * supplies its own. They lived under `action` when writes were the only caller, which left every deployment building
+ * that read half by hand out of `createConnectorResolver` and `resolveRscData` — from these very lookups, passed a
+ * second time.
+ */
+export type ConnectorLookupsConfig = {
+    getConnector: (spaceId: number, connectorId: string, at?: SpaceRevision) => Promise<unknown>;
+    getCredential?: (spaceId: number, identifier: string) => Promise<Record<string, string> | undefined>;
+    fetchImpl?: typeof fetch;
 };
 export type SSRHealthConfig = {
     path?: string;
@@ -414,6 +605,18 @@ export type SSRRscConfig = {
     path?: string;
     /** Server-side cache TTL for RSC responses in milliseconds. Defaults to 30 000. Set to 0 to disable. */
     cacheTtlMs?: number;
+    /**
+     * How long ONE server element may take before the page is answered without it. Defaults to 5 000.
+     *
+     * It is the page's ceiling, and it wins over the producer's own: an action may be allowed ten seconds of its
+     * own (`action.limits.timeoutMs`) and still be cut off here, because a section is worth waiting for only as
+     * long as the visitor is. Whichever is tighter decides, and now that the budget CANCELS what it stops waiting
+     * for, being cut here ends the run rather than leaving it to finish for nobody.
+     *
+     * Raise it for a deployment whose sections are genuinely slow and worth the wait; lower it to keep a page fast
+     * at the cost of showing more empty sections when a provider is having a bad day.
+     */
+    elementTimeoutMs?: number;
 };
 /** What every log event carries, whatever layer it came from. */
 type ServerLogEventBase = {
@@ -459,15 +662,59 @@ export type McpResourceLogEvent = ServerLogEventBase & {
     /** The resource URI that was read, e.g. 'plitzi://element/hero_1'. */
     name: string;
 };
+/** One server action run that STARTED — completed, failed or aborted.
+ *
+ *  Its own event rather than a line on the request that triggered it, for the same reason a tool call is: the
+ *  request is answered either way, and a run started by a schedule or a webhook has a request that says nothing
+ *  about it. Where the request log answers "was this call served", this answers "what did the flow do".
+ *
+ *  Carries the SHAPE of the run and never its data: which steps ran and how each ended, never what they
+ *  returned. A refused run is absent by design — a 409 is not a run, and logging one buries the real ones under
+ *  retries. */
+export type ActionRunLogEvent = ServerLogEventBase & {
+    kind: 'run';
+    /** The action's identifier, as the space stores it. */
+    name: string;
+    spaceId: number;
+    environment: Environment;
+    /** What started it: a page call, a webhook, a schedule, a render, a trigger the deployment mounted. */
+    trigger: ActionTriggerType;
+    status: ActionRunStatus;
+    /** Who asked, when a session carried it. Absent for a webhook, a schedule or an anonymous visitor. */
+    userId?: number;
+    /** Each step as `action:status`, in order — enough to see where a flow stopped without keeping what it held. */
+    steps: string[];
+};
+/** One request that was REFUSED before it became a run — a webhook whose signature did not verify, a caller over
+ *  its rate limit, an action nobody may start.
+ *
+ *  Separate from {@link ActionRunLogEvent} because it is a different question: that one says what a flow did,
+ *  this one says why a flow never happened. It is the only place an integration that is failing at the door
+ *  shows up at all — the request log answers 401 and says nothing about which check refused it.
+ *
+ *  `durationMs` is 0 and `ok` is always false: nothing ran, and a refusal is not a success on anybody's dashboard. */
+export type ActionRejectLogEvent = ServerLogEventBase & {
+    kind: 'reject';
+    /** The action's identifier, as the request named it — it need not exist. */
+    name: string;
+    spaceId: number;
+    environment: Environment;
+    trigger: ActionTriggerType;
+    /** Which check refused it. */
+    reason: ActionRejectReason;
+    /** Who asked, as the transport identifies them — a session subject or an address. */
+    callerId?: string;
+};
 /** Everything a Plitzi server reports about the work it does, as ONE stream: the HTTP requests it answers, plus
- *  the MCP tool calls and resource reads that happen inside them. Wire a single sink via `SSRServerConfig.logger`
- *  and switch on `kind` — a consumer can render it, ship it to a dashboard or drop the kinds it does not want.
+ *  the MCP tool calls, resource reads and server-action runs that happen inside them. Wire a single sink via
+ *  `SSRServerConfig.logger` and switch on `kind` — a consumer can render it, ship it to a dashboard or drop the
+ *  kinds it does not want.
  *
  *  Payload-free by construction: no headers, cookies, tokens nor request body ever reach an event, query values
- *  are stripped from paths and tool arguments are reduced to their shape. Two fields are NOT anonymous and a
- *  consumer shipping these events must handle them accordingly: `clientIp` on a request event, and the request
- *  path, which is kept verbatim because it is what makes the log usable. */
-export type ServerLogEvent = ServerRequestLogEvent | McpToolLogEvent | McpResourceLogEvent;
+ *  are stripped from paths, tool arguments are reduced to their shape and a run to its steps. Two fields are NOT
+ *  anonymous and a consumer shipping these events must handle them accordingly: `clientIp` on a request event, and
+ *  the request path, which is kept verbatim because it is what makes the log usable. */
+export type ServerLogEvent = ServerRequestLogEvent | McpToolLogEvent | McpResourceLogEvent | ActionRunLogEvent | ActionRejectLogEvent;
 /** The sink a consumer provides to receive every {@link ServerLogEvent} (see `SSRServerConfig.logger`). */
 export type ServerLogger = (event: ServerLogEvent) => void;
 export type SSRServerConfig = {
@@ -502,6 +749,8 @@ export type SSRServerConfig = {
     pluginsTtlMs?: number;
     /** Auto-download and cache plugins declared in the schema's offlineData.plugins list. Default: true. */
     autoLoadSchemaPlugins?: boolean;
+    /** Where this deployment serves the font files a space uploaded — see {@link SSRFontsConfig}. */
+    fonts?: SSRFontsConfig;
     /** Omit client-side JS from the rendered page — useful for verifying SSR HTML without hydration. Default: false. */
     ssrOnly?: boolean;
     /** Stream HTML to the client as React renders, reducing TTFB. Default: false. */
@@ -516,6 +765,9 @@ export type SSRServerConfig = {
     rsc?: SSRRscConfig;
     /** Write endpoint for server-driven providers. Absent means the server serves reads only. */
     action?: SSRActionConfig;
+    /** Connector manifest and credential lookups — see {@link ConnectorLookupsConfig}. They serve the RSC read path
+     *  and the `/_action` write endpoint alike; without them neither can reach a connector. */
+    connectors?: ConnectorLookupsConfig;
     /** Receives a {@link ServerLogEvent} for every HTTP request this server answers — whatever stage answered it
      *  and whatever the outcome — plus every MCP tool call and resource read inside those requests. Without it the
      *  server reports nothing per request (the MCP events still reach the console when `MCP_DEBUG=1`). */
@@ -630,14 +882,34 @@ export type OAuthGrantTarget = {
  *  for them. The SDK owns the protocol (discovery, registration, PKCE, code exchange); the consumer owns identity
  *  and issues a token its own `adapters.getGrant` will accept back. */
 export type OAuthAdapters = {
-    /** Verify the credentials typed into the consent screen. Return undefined to re-show the form with an error —
-     *  never throw for a wrong password. */
-    authenticate: (credentials: {
-        username: string;
-        password: string;
-    }) => Promise<OAuthUser | undefined>;
+    /**
+     * Who the browser making this request already is, from whatever session it carries.
+     *
+     * This server has no sign-in of its own: it reads an existing session and sends anyone it cannot identify to
+     * {@link OAuthConfig.signInUrl}, which brings them back. That is what lets a deployment have ONE sign-in screen
+     * for every surface — and it is what makes SSO somebody else's problem, because whatever established the
+     * session is no longer this flow's business.
+     *
+     * It replaced a username/password form this server used to render and check itself. Two sign-ins against one
+     * account store is two places to add a provider, to rate-limit, and to get a password check subtly wrong.
+     *
+     * Return undefined for "nobody is signed in". Never throw for that — an unreadable session is the ordinary
+     * first visit.
+     */
+    identify: (req: SSRRequest) => Promise<OAuthUser | undefined>;
     /** What this user may grant access to. An empty list ends the flow with `access_denied`. */
     grantTargets: (user: OAuthUser) => Promise<OAuthGrantTarget[]>;
+    /**
+     * End whatever session {@link OAuthAdapters.identify} was reading, so the person can connect as somebody else.
+     *
+     * Optional, and its absence is what takes the offer off the grant screen: a deployment that cannot end a session
+     * from here should not show a button that pretends to. Clear the cookies on `res` and revoke at the source —
+     * forgetting the cookie alone leaves the credential working for anyone who already copied it.
+     *
+     * Whoever reaches that screen arrived from another application, so this is the only way out of the wrong account
+     * that does not mean abandoning the connection and starting over from the host.
+     */
+    signOut?: (req: SSRRequest, res: SSRResponseHelpers) => void | Promise<void>;
     /** Mint the bearer the client will send on every MCP request. Return undefined to deny the grant. */
     issueToken: (user: OAuthUser, target: OAuthGrantTarget) => Promise<{
         token: string;
@@ -657,7 +929,7 @@ export type OAuthGuestConfig = {
     /** Who the grant is issued as. Defaults to `{ id: 'guest', label: 'Guest' }`. */
     user?: OAuthUser;
 };
-/** What the built-in consent screen shows around the form. Ignored when `renderConsent` replaces the page. */
+/** What the grant screen shows around the form. */
 export type OAuthBranding = {
     /** Shown as the heading, e.g. 'Plitzi'. Defaults to 'Plitzi'. */
     productName?: string;
@@ -666,26 +938,46 @@ export type OAuthBranding = {
     /** Extra CSS appended to the page's own, for a deployment that wants its own look without replacing the page. */
     css?: string;
 };
-/** Everything the consent screen needs to render itself, for a deployment that replaces the built-in page. Return
- *  a full HTML document; the SDK serves it as-is and reads the same form fields back. */
+/**
+ * Everything the GRANT screen needs to render itself.
+ *
+ * One screen, and deliberately only one: this server asks what to connect, never who somebody is. Signing in
+ * happens on {@link OAuthConfig.signInUrl}, wherever the deployment keeps it.
+ */
 export type OAuthConsentView = {
-    /** 'credentials' asks for username + password; 'target' asks which space to grant, after a successful login. */
-    step: 'credentials' | 'target';
     /** Where the form must POST to (the authorize endpoint). */
     action: string;
     /** Hidden fields the form MUST round-trip verbatim, or the flow cannot be resumed. */
     hidden: Record<string, string>;
-    /** Offered on the 'target' step only. */
+    /** What this account may grant. Empty for a visitor who has not signed in, who is offered `guest` instead. */
     targets: OAuthGrantTarget[];
-    /** Offered on the 'credentials' step when the deployment allows a guest connection. The form must submit a
-     *  `guest` field for it (any non-empty value), which is what tells the server to skip authentication. */
+    /**
+     * Offered when the deployment allows a guest connection. The form submits a `guest` field for it (any non-empty
+     * value), which is what tells the server to grant the guest target rather than a chosen one.
+     *
+     * It is the reason an unidentified visitor is shown this screen at all rather than being sent straight to
+     * sign-in: a guest has no session and never will, so a redirect they cannot come back from would take the
+     * option away entirely.
+     */
     guest?: {
         label: string;
         description?: string;
     };
-    /** Who logged in, on the 'target' step. */
+    /** Who is signed in. Absent for a visitor taking the guest connection. */
     user?: OAuthUser;
-    /** A message to show the user, e.g. after a failed login. */
+    /** Where to send somebody who wants to sign in first. Shown when `user` is absent. */
+    signInUrl?: string;
+    /**
+     * Whether to offer "use another account" — shown only when the deployment can act on it, which means it supplied
+     * {@link OAuthAdapters.signOut}.
+     *
+     * A submit BUTTON in the same form rather than a link, and that is not decoration. Ending a session is a state
+     * change, so it may not hang off a URL anything can navigate to: a `<img src>` on any page on the internet would
+     * then be able to sign a visitor out. Posting it here keeps it a same-origin form submission carrying the request
+     * back, exactly like granting does.
+     */
+    canSwitchUser?: boolean;
+    /** A message to show the user. */
     error?: string;
     branding: OAuthBranding;
 };
@@ -715,16 +1007,60 @@ export type OAuthConfig = {
     /** Offer a connection that needs no account — see {@link OAuthGuestConfig}. Omit to require sign-in. */
     guest?: OAuthGuestConfig;
     branding?: OAuthBranding;
-    /** Replaces the built-in consent screen — return a full HTML document for the given step. */
-    renderConsent?: (view: OAuthConsentView) => string | Promise<string>;
+    /**
+     * The sign-in screen this server sends unidentified visitors to.
+     *
+     * The whole authorization request rides along as a `redirect` query param, so signing in is an ordinary
+     * navigation that lands back on the `/authorize` it left — this server keeps no session of its own for a flow
+     * that is one page long.
+     *
+     * Required, because {@link OAuthAdapters.identify} is: a server that does not check passwords and has nowhere
+     * to send somebody who has not signed in cannot start the flow at all.
+     */
+    signInUrl: string;
+    /**
+     * Hand the client the credential `issueToken` minted, instead of an opaque handle to it.
+     *
+     * Off by default, which is right whenever the credential is worth more than the connection — a space token
+     * reaches the platform, and a client that never holds one cannot leak one. Turn it ON when the credential IS
+     * what the client should hold: a native app granted the person's own session is holding exactly what a browser
+     * holds, and wrapping it costs a store read on every request and gives a second thing to revoke.
+     */
+    directTokens?: boolean;
 };
 /** A short-TTL, one-shot store for unsaved draft offline-data behind a preview token. The SDK ships an
  *  in-memory default (fine for a single replica); a multi-replica deployment injects a shared (e.g. Redis)
  *  implementation so a preview URL resolves on whichever replica the browser lands on. `take` consumes the
  *  token so a preview URL is not replayable. */
+/**
+ * How long a stashed draft lives, and whether looking at it uses it up.
+ *
+ * `reusable: false` is the capture path: one token, one render, gone — a URL that leaks buys nobody a second look.
+ * `reusable: true` is somebody ITERATING: they reload, they open devtools, they navigate to the next page and back,
+ * and a token consumed by the first of those turns the whole loop into "mint another one". Same store, same secret,
+ * same expiry; the only difference is whether the read deletes it.
+ */
+export type DraftPutOptions = {
+    ttlMs: number;
+    reusable?: boolean;
+};
+/** A stashed draft, and whether the read that resolved it left it there. */
+export type DraftEntry = {
+    data: OfflineDataRaw;
+    reusable: boolean;
+};
 export type DraftStore = {
-    put: (token: string, data: OfflineDataRaw, ttlMs: number) => void | Promise<void>;
-    take: (token: string) => (OfflineDataRaw | undefined) | Promise<OfflineDataRaw | undefined>;
+    put: (token: string, data: OfflineDataRaw, options: DraftPutOptions) => void | Promise<void>;
+    /**
+     * Resolves a draft, consuming it unless it was stored as reusable.
+     *
+     * It answers WHICH it was, rather than leaving the caller to infer it from a second read: the render that resolved
+     * a session is the one that has to remember it for the rest of the visit, and "did this token survive" is a fact
+     * the store holds and nobody else does.
+     */
+    take: (token: string) => (DraftEntry | undefined) | Promise<DraftEntry | undefined>;
+    /** Ends a reusable draft before its TTL — what "stop previewing" does. A token that is not there is not an error. */
+    drop: (token: string) => void | Promise<void>;
 };
 /** Draft-preview config for the MCP visual-preview tools. When enabled, an internal endpoint at `path`
  *  (guarded by `secret`) applies unsaved edits to a clone, stashes the resulting offline-data under a
@@ -735,7 +1071,15 @@ export type SSRPreviewConfig = {
     path?: string;
     /** Shared secret required in the `x-preview-secret` header; requests without it are rejected. */
     secret?: string;
-    /** Token time-to-live in milliseconds. Default 60000. */
+    /** One-shot token time-to-live in milliseconds. Default 60000. */
     ttlMs?: number;
+    /**
+     * How long a REUSABLE draft session lives, in milliseconds. Default 900000 (fifteen minutes).
+     *
+     * Longer than a one-shot token because it is measured against a person's attention rather than an HTTP round trip,
+     * and short anyway: a draft is unsaved work that only its author should be looking at, and every minute it stays
+     * resolvable is a minute a copied URL keeps working.
+     */
+    sessionTtlMs?: number;
 };
 export {};

package/dist/types/SpaceTypes.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { ActionDocument } from './ActionTypes';
 import { Environment } from './CommonTypes';
 import { ConnectorManifestDraft } from './ConnectorTypes';
 export type SpaceCredentialProvider = 's3' | 'r2' | 'ssr' | 'custom';
@@ -16,6 +17,21 @@ export type SpaceConnector = {
     createdAt: number;
     updatedAt: number;
 };
+/**
+ * A server action as the builder sees it.
+ *
+ * The document is server-side state — it names credentials, connectors and steps — so this shape exists for the
+ * editor and the API that maintains it, never for a published page. What reaches a visitor is the action's
+ * identifier and its input/output fields, derived server-side.
+ */
+export type SpaceAction = {
+    id: number;
+    identifier: string;
+    name: string;
+    document: ActionDocument;
+    createdAt: number;
+    updatedAt: number;
+};
 export type SpaceCredential = {
     identifier: string;
     name: string;