@plitzi/sdk-shared 0.37.1 → 0.37.3

package/dist/types/CommonTypes.d.ts

@@ -1,4 +1,5 @@
 import { User } from './AuthTypes';
+import { RealtimeTransport } from './RealtimeTypes';
 import { SSRRenderResult, SSRRscData } from './ServerTypes';
 export type Environment = 'production' | 'staging' | 'development' | 'main';
 export type Server<T extends Record<string, unknown> = Record<string, unknown>> = {
@@ -44,6 +45,11 @@ export type ServerSSR = {
      *  is what tells a client flow that a `serverAction` step has nowhere to run, rather than letting it fail per
      *  click. A static export publishes nothing here and the step reports itself inert. */
     actionPath?: string;
+    /** Path where this origin's realtime channels answer. Published only by a server that mounts them: its absence is
+     *  what keeps a `channel` element closed in the builder, an embed or a static export. */
+    realtimePath?: string;
+    /** How pages connect to them — a stream (`sse`, when absent) or a socket (`websocket`). */
+    realtimeTransport?: RealtimeTransport;
     /** Channel the SSR render writes its response into (status, redirect). Server-side only and by reference: it never
      *  crosses to the browser, and nothing subscribes to it. */
     renderResult?: SSRRenderResult;

package/dist/types/FunctionTypes.d.ts

@@ -0,0 +1,52 @@
+import { InteractionCallbackParam } from './InteractionTypes';
+/**
+ * A space's own functions, as everything outside the runner sees them: the builder, the CLI, the MCP and the
+ * platform that stores them. The contract the code itself is written against is `@plitzi/sdk-server/functions`.
+ */
+/** One task the functions declare: everything but its code — what the catalog shows and a step is drawn from. */
+export type FunctionTaskManifest = {
+    namespace: string;
+    action: string;
+    title: string;
+    description?: string;
+    params: Record<string, InteractionCallbackParam<Record<string, unknown>>>;
+};
+/** What a space's functions declare, read from the bundle when it is saved: its tasks, routes and reachable hosts. */
+export type FunctionsManifest = {
+    hosts: string[];
+    tasks: FunctionTaskManifest[];
+    /** The route keys, `'GET /board-assets/:board/:asset'`, as declared. */
+    routes: string[];
+};
+/** One reason functions were not saved, where it is — what an editor underlines. */
+export type FunctionsProblem = {
+    file?: string;
+    line?: number;
+    column?: number;
+    message: string;
+};
+/** The live draft: the source files, which copy of them this is, and what they declared when last saved. */
+export type FunctionsDraft = {
+    /** `{ "index.ts": "…", "lib/feed.ts": "…" }`. */
+    files: Record<string, string>;
+    /** Hand it back as `base` when saving: a draft that moved on since is refused rather than overwritten. */
+    version: string;
+    manifest: FunctionsManifest | null;
+};
+/** Why nothing was built: the draft moved on since the copy this save started from. */
+export type FunctionsRefusal = {
+    status: 409;
+    error: string;
+    limit: 'version';
+};
+export type FunctionsSaveResult = {
+    ok: true;
+    version: string;
+    manifest: FunctionsManifest;
+} | {
+    ok: false;
+    problems: FunctionsProblem[];
+} | {
+    ok: false;
+    refusal: FunctionsRefusal;
+};

package/dist/types/PluginTypes.d.ts

@@ -101,7 +101,6 @@ export type PluginsContextValue = {
     assets: Record<string, Asset>;
     plugins: Record<string, ComponentDefinition>;
     dispatchPlugins?: unknown;
-    fetch?: (filter: object, cursor: string, limit: number) => Promise<unknown>;
     add?: (pluginType: string, resource?: string) => Promise<boolean>;
     setSettings?: (pluginType: string, attribute: string, value: string) => Promise<boolean>;
     getSettings?: (pluginType: string, attribute?: string, defaultValue?: string | number | boolean) => ComponentDefinition['settings'] | string | number | boolean;

package/dist/types/RealtimeTypes.d.ts

@@ -0,0 +1,94 @@
+import { ActionAccess } from './ActionTypes';
+/**
+ * One kind of channel a space offers, declared under a topic PATTERN — `board:{id}` is every board, each its own topic.
+ *
+ * A topic no pattern of the space matches is refused, by the server and at authoring: a page cannot open a channel
+ * nobody decided should exist.
+ */
+export type ChannelDeclaration = {
+    /** Who may subscribe and publish — the access vocabulary actions use. */
+    access: ActionAccess;
+    /**
+     * Who may send: `clients` (pages publish directly — cursors, reactions, what is cheap and ephemeral) or `server`
+     * (only a flow's `realtime.publish` — what was validated and saved first). `clients` when absent.
+     */
+    publish?: 'clients' | 'server';
+    /** Whether members announce themselves — who is here, and what they are pointing at. */
+    presence?: boolean;
+    /**
+     * Whether a page needs a GRANT to open a topic of it: a token a flow's `realtime.grant` issued for that exact topic —
+     * after checking a password, an invitation, an order's owner, whatever decides who is in. Without one the topic is
+     * refused, however well its name is known; `access` still applies on top. For a private room, a customer's order,
+     * a locked board.
+     */
+    grant?: boolean;
+    /** The largest `data` a page may send, as JSON bytes. 4 KB when absent. */
+    maxMessageBytes?: number;
+    /** How many messages one connection may send a second. 30 when absent. */
+    messagesPerSecond?: number;
+};
+export type ChannelDeclarations = Record<string, ChannelDeclaration>;
+/** Who sent a message, as the SERVER knows them: a page cannot say it is someone else. */
+export type RealtimeSender = {
+    /** The connection, as the server named it — stable for as long as the page stays connected. */
+    from: string;
+    /** The signed-in visitor, when the connection carries a session. */
+    user?: {
+        id: number;
+        name: string;
+    };
+};
+/**
+ * A message, as every subscriber receives it.
+ *
+ * `type` and `data` are the sender's own vocabulary; everything else is stamped by the server. Types starting with
+ * `$` are the channel's own: `$presence` (a member's state) and `$leave` (a member gone).
+ */
+export type RealtimeMessage = RealtimeSender & {
+    topic: string;
+    type: string;
+    data: unknown;
+    /** Server time, in milliseconds. */
+    at: number;
+};
+/** What a page sends to publish: the secret its connection was given, and the message. */
+export type RealtimePublishRequest = {
+    token: string;
+    topic: string;
+    type: string;
+    data: unknown;
+};
+/**
+ * How messages move between the processes and replicas of a deployment — transport only, strings in and out.
+ *
+ * Everything a channel DOES (who may, how big, how often, who sent it) is decided above it, once, for every
+ * deployment. In memory for one self-hosted process and its workers; Redis, NATS or a cloud service for a fleet.
+ */
+export type PubSubAdapter = {
+    /** Delivers `message` to every subscriber of `topic`, in this process and every other sharing the adapter. */
+    publish: (topic: string, message: string) => Promise<void>;
+    /** Calls `listener` for each message on `topic` until the returned function is called. */
+    subscribe: (topic: string, listener: (message: string) => void) => Promise<() => Promise<void>>;
+};
+/**
+ * How a page connects: a Server-Sent Events stream it publishes to with requests, or one WebSocket both ways.
+ *
+ * The stream works through anything that passes HTTP; the socket sends a message as a frame instead of a request,
+ * which is what a page publishing a cursor twenty times a second wants. A page told to use the socket falls back to
+ * the stream on its own where one cannot open (behind HTTP/2, a proxy that drops upgrades).
+ */
+export type RealtimeTransport = 'sse' | 'websocket';
+/** A server's realtime channels. On by default; `false` turns the endpoint off. */
+export type SSRRealtimeConfig = {
+    /** How messages reach the other processes and replicas. In memory (and across workers) when absent. */
+    pubsub?: PubSubAdapter;
+    /** Where pages connect. `/_realtime` when absent. */
+    path?: string;
+    /** How pages connect. `sse` when absent; both are always served, this is what pages are told to use. */
+    transport?: RealtimeTransport;
+    /**
+     * Origins, besides the server's own, whose pages may open a WebSocket here (`https://app.example.com`). A
+     * socket carries the visitor's cookies from any site, so every other origin is refused.
+     */
+    allowedOrigins?: string[];
+} | false;

package/dist/types/SchemaTypes.d.ts

@@ -1,4 +1,5 @@
 import { InteractionCallbackParamValues, InteractionCallbackType } from './InteractionTypes';
+import { ChannelDeclarations } from './RealtimeTypes';
 import { Style } from './StyleTypes';
 import { RuleGroup } from '@plitzi/plitzi-ui/QueryBuilder';
 export type ElementRuntime = 'server' | 'client' | 'shared';
@@ -44,6 +45,15 @@ export type ElementBinding = {
     enabled?: boolean;
     to: string;
 };
+/**
+ * What a trigger does when it fires again while the flow it started is still running.
+ *
+ * - `skip` (the default): the new firing is ignored — what keeps a double click from submitting twice.
+ * - `parallel`: every firing runs its own flow, at the same time.
+ * - `queue`: every firing runs, one after another, in the order they came — none lost, none overlapping.
+ */
+export type WhileRunning = 'skip' | 'parallel' | 'queue';
+export declare const WHILE_RUNNING_MODES: readonly WhileRunning[];
 export type ElementInteraction<T extends Record<string, unknown> = Record<string, unknown>> = {
     id: string;
     title: string;
@@ -57,6 +67,8 @@ export type ElementInteraction<T extends Record<string, unknown> = Record<string
     flowId: string;
     enabled: boolean;
     when?: RuleGroup;
+    /** On a trigger only: what a firing does while this flow is still running. `skip` when absent. */
+    whileRunning?: WhileRunning;
 };
 export type ElementDefinition = {
     rootId: Element['id'];
@@ -123,7 +135,30 @@ export type Schema = {
     settings: {
         keepState?: boolean;
         stateStorage?: 'localStorage' | 'sessionStorage';
+        /**
+         * Keys of `runtime.state` that are never kept, even with `keepState` on: they are not written, not brought back,
+         * and a value one of them already holds survives the moment the rest is restored. For state that must start fresh
+         * on every visit — a demo, a panel somebody left open, a step of a walkthrough. Top-level keys, as `setState`
+         * writes them.
+         */
+        transientState?: string[];
+        /**
+         * Keys of `runtime.state` the first paint depends on — the tool a toolbar shows, a name in an avatar — kept in a
+         * cookie as well as in `stateStorage`, so the server renders with them and the page does not swap them in after
+         * hydration. Small values only: the cookie travels with every request and holds at most a few kilobytes. Needs
+         * `keepState`; a key cannot be both painted and transient. Top-level keys, as `setState` writes them.
+         */
+        paintedState?: string[];
         customCss: string;
+        /**
+         * The roles a signed-in visitor may hold in this space, each with the permissions it gives:
+         * `{ author: ['postPublish'] }`. They are what an action's `access: 'role'` and a page's `can()` are answered from
+         * — a visitor holds exactly the permissions of their roles here, never those of their account anywhere else.
+         *
+         * Declared by the space, so they are published, versioned and exported with it. WHO holds which is not: that is a
+         * list of people, kept by the platform the space runs on, and never part of a document anybody can read.
+         */
+        visitorRoles?: Record<string, string[]>;
         /** `basic` covers any HTTP+JSON backend by configuration; anything else is a name someone registered. */
         userProvider?: 'basic' | 'custom' | '' | (string & {});
         tokenStorage?: 'localStorage' | 'sessionStorage' | '';
@@ -151,6 +186,13 @@ export type Schema = {
          * session itself, which is the case whenever `loginUrl` is your own API.
          */
         sessionExchangeUrl?: string;
+        /**
+         * Where a sign-in that owed a second factor is completed: a password the backend answered with `mfaRequired` and
+         * an `mfaToken` resolves `auth.login` to `{ ok: false, reason: 'mfa', mfaToken }`, and `auth.login` with `mode:
+         * 'mfa'` posts `{ mfaToken, code }` here and adopts the session it answers with. Leave empty when the backend has
+         * no second factor.
+         */
+        mfaUrl?: string;
         /**
          * What to do on a page that requires a session while the stored one is being re-checked. `optimistic` (the
          * default) renders from the stored session and signs out if the check disagrees; `strict` waits for the answer,
@@ -167,6 +209,18 @@ export type Schema = {
          * `false` there cannot be turned around from here. Never `devMode`, which makes a deployment a development server.
          */
         debugMode?: boolean;
+        /**
+         * Values the space computes once and reads everywhere, by name: `{ xp: '{{ state.favourites|length * 10 }}' }` is
+         * read as `{{ computed.xp }}` in any binding, attribute or step. Each is a template over the global sources and the
+         * values declared before it (`computed.<earlier>`), re-evaluated when any of them changes. A template that is one
+         * `{{ expression }}` gives its value (a number, a list); anything else gives text.
+         */
+        computed?: Record<string, string>;
+        /**
+         * The realtime channels the space offers, by topic pattern: `{ 'board:{id}': { access: { mode: 'public' } } }`.
+         * A page subscribes to and publishes on a topic one of them matches, and on nothing else.
+         */
+        channels?: ChannelDeclarations;
     };
     rsc?: SchemaRsc;
     pages: Element['id'][];

package/dist/types/SchemaTypes.mjs

@@ -0,0 +1,8 @@
+//#region src/types/SchemaTypes.ts
+var e = [
+	"skip",
+	"parallel",
+	"queue"
+];
+//#endregion
+export { e as WHILE_RUNNING_MODES };