@plitzi/sdk-shared 0.32.25 → 0.33.0

package/dist/store/index.mjs

@@ -1,5 +1,6 @@
-import { createStoreHook as e } from "@plitzi/nexus/react";
+import e, { DEFAULT_RENDER_SETTINGS as t, useRenderOverride as n } from "./renderSettings.mjs";
+import { createStoreHook as r } from "@plitzi/nexus/react";
 //#region src/store/index.ts
-var { useStore: t, useStoreSync: n, useStoreGetter: r, useStoreSetter: i } = e(), { useStore: a, useStoreSync: o, useStoreGetter: s, useStoreSetter: c } = e(), { useStore: l, useStoreSync: u, useStoreGetter: d, useStoreSetter: f } = e();
+var { useStore: i, useStoreSync: a, useStoreGetter: o, useStoreSetter: s } = r(), { useStore: c, useStoreSync: l, useStoreGetter: u, useStoreSetter: d } = r(), { useStore: f, useStoreSync: p, useStoreGetter: m, useStoreSetter: h } = r();
 //#endregion
-export { l as useBuilderStore, d as useBuilderStoreGetter, f as useBuilderStoreSetter, u as useBuilderStoreSync, t as useCommonStore, r as useCommonStoreGetter, i as useCommonStoreSetter, n as useCommonStoreSync, a as useSdkStore, s as useSdkStoreGetter, c as useSdkStoreSetter, o as useSdkStoreSync };
+export { t as DEFAULT_RENDER_SETTINGS, f as useBuilderStore, m as useBuilderStoreGetter, h as useBuilderStoreSetter, p as useBuilderStoreSync, i as useCommonStore, o as useCommonStoreGetter, s as useCommonStoreSetter, a as useCommonStoreSync, n as useRenderOverride, e as useRenderSettings, c as useSdkStore, u as useSdkStoreGetter, d as useSdkStoreSetter, l as useSdkStoreSync };

package/dist/store/renderSettings.d.ts

@@ -0,0 +1,26 @@
+import { RenderSettings } from '../types';
+/** The surface a schema renders on when nobody said otherwise: a live, non-debug space rendered in place. Each surface
+ *  seeds `render` at its own store root with these plus whatever it actually is (the builder, for one, is not
+ *  preview by default) — this is the floor, so no read site carries its own idea of the default. */
+export declare const DEFAULT_RENDER_SETTINGS: Required<RenderSettings>;
+/** Reads `render` from the nearest store, filled in. Returns every key defined, so call sites destructure without
+ *  restating a default — and a tree that never seeded it (a standalone element, a test) still renders.
+ *
+ *  A nested scope that seeds `render` SHADOWS the whole slice — reads do not fall through key by key, whichever way
+ *  they are written — so a subtree that overrides one flag must restate the rest ({@link useRenderOverride}). */
+declare const useRenderSettings: () => Required<RenderSettings>;
+/** Builds the value for a `<StoreProvider>` that renders a subtree under different settings — the builder's preview
+ *  pane being preview whatever the editor's own toggle says. Carries the surrounding settings over explicitly,
+ *  because the scope shadows the slice: what an override leaves out is NOT inherited, it is lost.
+ *
+ *  `overrides` has to be referentially stable (a module-level constant), like any memo input. */
+export declare const useRenderOverride: (overrides: RenderSettings) => {
+    render: {
+        previewMode: boolean;
+        debugMode: boolean;
+        renderMode: import('..').RenderMode;
+        environment: import('..').Environment;
+        isHydrating: boolean;
+    };
+};
+export default useRenderSettings;

package/dist/store/renderSettings.mjs

@@ -0,0 +1,39 @@
+import { useCommonStore as e } from "./index.mjs";
+import { useMemo as t } from "react";
+//#region src/store/renderSettings.ts
+var n = {
+	previewMode: !0,
+	debugMode: !1,
+	renderMode: "raw",
+	environment: "main",
+	isHydrating: !1
+}, r = () => {
+	let [[r, i, a, o, s]] = e([
+		"render.previewMode",
+		"render.debugMode",
+		"render.renderMode",
+		"render.environment",
+		"render.isHydrating"
+	]);
+	return t(() => ({
+		previewMode: r ?? n.previewMode,
+		debugMode: i ?? n.debugMode,
+		renderMode: a ?? n.renderMode,
+		environment: o ?? n.environment,
+		isHydrating: s ?? n.isHydrating
+	}), [
+		r,
+		i,
+		a,
+		o,
+		s
+	]);
+}, i = (e) => {
+	let n = r();
+	return t(() => ({ render: {
+		...n,
+		...e
+	} }), [n, e]);
+};
+//#endregion
+export { n as DEFAULT_RENDER_SETTINGS, r as default, i as useRenderOverride };

package/dist/types/AuthTypes.d.ts

@@ -9,14 +9,44 @@ export type User = {
 export type TokenResult = {
     errors?: Record<string, unknown>;
     accessToken: string;
+    /** Unix seconds. Seconds rather than milliseconds because that is what a JWT `exp` and every OAuth2 response use. */
     expiresAt: number | null;
     refreshToken: string | null;
+    /** Unix seconds the refresh token dies at, when the backend says. Renewal is impossible past it. */
+    refreshExpiresAt?: number | null;
+};
+export type AuthState = 'init' | 'initLoading' | 'authenticating' | 'authenticated' | 'guest';
+/**
+ * Why a credential was refused, as reported by the auth backend (Plitzi's API answers it in `reason` on every 401).
+ * The distinction that matters to a client is renewable versus not: `expired` asks for a refresh, `revoked`,
+ * `inactive` and `missing` end the session, and `network` is not an answer at all — it must never sign anyone out.
+ */
+export type AuthFailureReason = 'missing' | 'expired' | 'revoked' | 'inactive' | 'malformed' | 'outdated' | 'network';
+/** What an auth backend hands back from a grant (login, refresh) or an identity call. Both halves are optional:
+ *  a backend may answer a refresh with tokens alone, or an identity call with a user alone. */
+export type AuthGrant<U = Record<string, unknown>> = {
+    user?: U;
+    token?: TokenResult;
+};
+export type AuthResult<U = Record<string, unknown>> = ({
+    ok: true;
+} & AuthGrant<U>) | {
+    ok: false;
+    reason: AuthFailureReason;
 };
 export type AuthContextValue = {
-    login: (...args: unknown[]) => Promise<TokenResult | undefined>;
-    refresh: (...args: unknown[]) => Promise<TokenResult | undefined>;
+    /** The credentials your login endpoint expects. Values arrive from interaction parameters, hence `unknown`. */
+    login: (params: Record<string, unknown>) => Promise<TokenResult | undefined>;
+    refresh: (params?: Record<string, unknown>) => Promise<TokenResult | undefined>;
     can: (permission: string) => boolean;
-    logout: (...args: unknown[]) => Promise<void>;
+    logout: () => Promise<void>;
+    /** Ask the backend whether the session still stands, renewing it if that is what it takes. Resolves to the
+     *  outcome, so a caller that needs certainty (a guarded action) can await it instead of trusting the last check. */
+    revalidate: (force?: boolean) => Promise<boolean>;
+    /** Report that the backend refused a credential — the `reason` from a 401. `expired` triggers a silent renewal,
+     *  anything terminal ends the session. This is how an app tells auth that reality moved on between checks. */
+    invalidate: (reason?: AuthFailureReason) => void;
+    state: AuthState;
     authenticated: boolean;
     user?: {
         details?: {

package/dist/types/BuilderTypes.d.ts

@@ -10,6 +10,20 @@ export type Template = {
     schema: Schema;
     style: Style;
 };
+export type SubscriptionCollaboratorElement = {
+    elementId: string;
+    rootId: string;
+};
+export type SubscriptionCollaboratorPointer = {
+    rootId: string;
+    anchorId?: string;
+    x: number;
+    y: number;
+};
+export type SubscriptionCollaboratorElementState = {
+    hovered?: SubscriptionCollaboratorElement;
+    selected?: SubscriptionCollaboratorElement;
+};
 export type SubscriptionCollaborator = {
     color: string;
     user: {
@@ -17,4 +31,5 @@ export type SubscriptionCollaborator = {
         surName: string;
     };
     instanceId: string;
+    elementState?: SubscriptionCollaboratorElementState;
 };

package/dist/types/CollectionTypes.d.ts

@@ -19,7 +19,9 @@ export type CollectionField = {
 };
 export type CollectionRecord = {
     id: string;
-    values: Record<string, string | number | boolean>;
+    /** Provider-shaped values. Not flat: external CMSs carry components, relations and localized objects, and a
+     *  record must be able to hold them unchanged. */
+    values: Record<string, unknown>;
     status: 'draft' | 'published' | 'archived';
     createdAt: number;
     updatedAt: number;
@@ -34,51 +36,3 @@ export type Collection = {
     fields: Record<string, CollectionField>;
     records: CollectionRecord[];
 };
-export type BuilderCollectionContextValue = {
-    collections: Record<string, Collection>;
-    fetchCollections: (filter: string, cursor?: string, limit?: number, append?: Collection[], store?: boolean) => Promise<{
-        edges: CollectionRaw[];
-        pageInfo: PageInfo;
-    } | undefined>;
-    fetchCollection: (id: string, recordsFilter: string, store?: boolean) => Promise<CollectionRaw | undefined>;
-    addCollection: (name: string, namePlural: string, description: string, privacy: Collection['privacy'], fields: Collection['fields']) => Promise<Collection | undefined>;
-    updateCollection: (id: string, name: string, namePlural: string, description: string, privacy: Collection['privacy'], fields: Collection['fields']) => Promise<Collection | undefined>;
-    removeCollection: (id: string) => Promise<boolean>;
-    fetchRecords: (collectionId: string, filter?: string | object, cursor?: string, limit?: number, append?: CollectionRecord[], store?: boolean) => Promise<{
-        pageInfo: PageInfo;
-        edges: CollectionRecord[];
-    } | undefined>;
-    fetchRecord: (collectionId: string, id: string, store?: boolean) => Promise<CollectionRecord | undefined>;
-    addRecord: (collectionId: string, status: CollectionRecord['status'], values: CollectionRecord['values'], updateStore?: boolean) => Promise<CollectionRecord | undefined>;
-    updateRecord: (collectionId: string, recordId: string, status: CollectionRecord['status'], values: CollectionRecord['values'], updateStore?: boolean) => Promise<CollectionRecord | undefined>;
-    removeRecord: (collectionId: string, recordId: string, updateStore?: boolean) => Promise<boolean>;
-};
-export type SdkCollectionContextValue = {
-    collections: Record<string, Collection>;
-    fetchCollections: (filter: string, cursor?: string, limit?: number) => Promise<{
-        edges: CollectionRaw[];
-        pageInfo: PageInfo;
-    } | undefined>;
-    fetchCollection: (id: string, recordsFilter: string) => Promise<CollectionRaw | undefined>;
-    fetchRecords: (collectionId: string, filter?: string | object, cursor?: string, limit?: number) => Promise<{
-        pageInfo: PageInfo;
-        edges: CollectionRecord[];
-    } | undefined>;
-    fetchRecord: (collectionId: string, id: string) => Promise<CollectionRecord | undefined>;
-    addRecord: (collectionId: string, status: CollectionRecord['status'], values: CollectionRecord['values'], updateStore?: boolean) => Promise<CollectionRecord | undefined>;
-    updateRecord: (collectionId: string, recordId: string, status: CollectionRecord['status'], values: CollectionRecord['values'], updateStore?: boolean) => Promise<CollectionRecord | undefined>;
-    removeRecord: (collectionId: string, recordId: string, updateStore?: boolean) => Promise<boolean>;
-};
-export type CollectionContextValue<T extends 'builder' | 'sdk' = 'sdk'> = T extends 'builder' ? BuilderCollectionContextValue : SdkCollectionContextValue;
-export type CollectionRaw = {
-    id: string;
-    name: string;
-    namePlural: string;
-    description: string;
-    privacy: 'public' | 'private';
-    fields: Record<string, CollectionField>;
-    records: {
-        pageInfo: PageInfo;
-        edges: CollectionRecord[];
-    };
-};

package/dist/types/CommonTypes.d.ts

@@ -1,5 +1,5 @@
 import { User } from './AuthTypes';
-import { SSRRscData } from './ServerTypes';
+import { SSRRenderResult, SSRRscData } from './ServerTypes';
 export type Environment = 'production' | 'staging' | 'development' | 'main';
 export type Server<T extends Record<string, unknown> = Record<string, unknown>> = {
     apiServer: string;
@@ -17,7 +17,22 @@ export type Server<T extends Record<string, unknown> = Record<string, unknown>>
     user?: {
         details?: User;
         accessToken?: string | Promise<string>;
+        /** Unix seconds the session token dies at, so a hydrated page schedules its renewal without decoding anything. */
+        expiresAt?: number;
     };
-    rscData?: SSRRscData;
+    ssr?: ServerSSR;
 } & T;
+/** What the rendering server hands over for THIS render, consumed once at the SDK root and not read from here again:
+ *  the RSC bootstrap is projected into the store (`rsc`), which is where the live payload lives from then on. The
+ *  rest of `Server` is long-lived configuration — endpoints, session — and stays readable anywhere. */
+export type ServerSSR = {
+    /** Path where this origin answers RSC refreshes. Published only by a server that actually mounts the endpoint, so
+     *  its absence is what tells a client-only render (embed, builder, offline widget) not to fetch. */
+    rscPath?: string;
+    /** The payload that server already resolved for this page, so the first render costs no request. */
+    rscData?: SSRRscData;
+    /** 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;
+};
 export type RenderMode = 'raw' | 'iframe' | 'shadow' | 'widget';

package/dist/types/ConnectorTypes.d.ts

@@ -0,0 +1,147 @@
+import { CollectionField } from './CollectionTypes';
+/** How the provider walks result windows. Cursor providers echo their own token back through `nextCursor`. */
+export type ConnectorPagination = 'offset' | 'page' | 'cursor';
+export type ConnectorAuth = {
+    in: 'header' | 'query';
+    name: string;
+    /** Template resolved against the credential, e.g. `Bearer {{credential.token}}`. */
+    value: string;
+};
+/** Where a read endpoint's records and counts sit inside this provider's response. */
+export type ConnectorResponseMapping = {
+    /** Where the records array lives in the response. Omitted means the response is the array. */
+    itemsPath?: string;
+    /** Where the total count lives. Omitted means the count is unknown and paging relies on page size. */
+    totalPath?: string;
+    /** Where a record's id lives, relative to the record. Defaults to `id`. */
+    idPath?: string;
+    /** Where a record's values live, relative to the record. `.` (default) means the record itself. */
+    valuesPath?: string;
+};
+/**
+ * The HTTP verb an endpoint uses.
+ *
+ * The full REST vocabulary, on both reads and writes: what separates the two is what the endpoint is *for* — only
+ * writes are reachable through `/_action` — not which verb it happens to use. Search reads through POST, upsert
+ * writes through PUT, and an integration that cannot say so is a CMS client, not a REST one.
+ */
+export type ConnectorHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/** A request that returns records. */
+export type ConnectorReadEndpoint = ConnectorResponseMapping & {
+    /** Template appended to `baseUrl`, e.g. `/api/{{resource}}`. */
+    path: string;
+    /** Defaults to `GET`. Any verb is allowed: reading through POST is how most search endpoints work. */
+    method?: ConnectorHttpMethod;
+    /** Query parameters, values templated. Entries resolving to empty are dropped. */
+    query?: Record<string, string>;
+    /** Headers for this endpoint only, merged over the connection's own. */
+    headers?: Record<string, string>;
+    /** Body sent when `method` is POST. Values are templated; `{{values}}` carries the submitted record. */
+    body?: Record<string, string>;
+    /** Paging style for this endpoint, when it differs from the connection default. */
+    pagination?: ConnectorPagination;
+};
+/**
+ * A request that changes something.
+ *
+ * Writes are a separate map from reads rather than one map keyed by method: only these are reachable through
+ * `/_action`, so a read can never be invoked as a mutation, and a write can never be mounted as a data source.
+ */
+export type ConnectorWriteEndpoint = {
+    method: ConnectorHttpMethod;
+    /** Template appended to `baseUrl`, e.g. `/api/{{resource}}/{{id}}`. */
+    path: string;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    /** Wraps the submitted values, e.g. `data` produces `{ "data": { … } }`. Omitted sends them at the root. */
+    bodyPath?: string;
+    /** Where the written record sits in the response, when the caller wants it back. */
+    response?: ConnectorResponseMapping;
+};
+/**
+ * Every request the connector knows how to make, named by the author.
+ *
+ * Both sides are open maps, not a fixed `list` plus `create`/`update`/`delete`: a connector is a declarative REST
+ * client, and an API has as many operations as it has. The CMS case is just the one where the read is called
+ * `list` and the writes happen to be named after CRUD.
+ *
+ * They are nested under `endpoints` rather than sitting beside `auth`, `operators` and `media` because those
+ * describe the connection and apply to every call, while these describe individual calls.
+ */
+export type ConnectorEndpoints = {
+    read: Record<string, ConnectorReadEndpoint>;
+    /** Absent or empty means read-only: an undeclared write is refused rather than guessed. */
+    write?: Record<string, ConnectorWriteEndpoint>;
+};
+/**
+ * A connector is data, not code: everything a provider needs is declared here and interpreted by the engine, so
+ * adding a CMS never means shipping a new adapter. This document is server-side state — it names endpoints and an
+ * auth scheme and must never reach the browser.
+ *
+ * It lives in shared types because the builder authors the same document the server executes; keeping two copies in
+ * step by hand is how a manifest ends up describing an endpoint that the engine does not read.
+ */
+export type ConnectorManifest = {
+    id: string;
+    /** Identifier of the credential to resolve. The secret itself is never part of the manifest. */
+    credential?: string;
+    baseUrl: string;
+    auth?: ConnectorAuth;
+    /** Static headers, values templated. */
+    headers?: Record<string, string>;
+    endpoints: ConnectorEndpoints;
+    pagination?: ConnectorPagination;
+    /** Operator templates keyed by operator name, e.g. `{ eq: 'filters[{{field}}][$eq]={{value}}' }`. */
+    operators?: Record<string, string>;
+    /** Base for relative media URLs returned by the provider. See `rebaseMedia` for exactly which values it rewrites. */
+    media?: {
+        baseUrl?: string;
+    };
+    /** Field types, the only part of a connector the browser is allowed to see (it drives typed bindings). */
+    fields?: Record<string, CollectionField['type']>;
+    /** Escape hatch for data feeding templates whose bound paths cannot be determined statically. */
+    projection?: 'full';
+};
+/**
+ * What the builder authors.
+ *
+ * `id` is missing on purpose: a connector's identity belongs to the row that stores it, and a document that carries
+ * its own id can disagree with the one it was fetched by. The store stamps it on read.
+ */
+export type ConnectorManifestDraft = Omit<ConnectorManifest, 'id'>;
+/**
+ * A connector as a server-side reader hands it over: the identity a provider element stores, the human name, and
+ * the manifest itself.
+ *
+ * Distinct from the builder's `SpaceConnector`, which also carries the storage row's numeric id and timestamps —
+ * a reader that had to invent those could answer from nothing but the database, and the MCP writes connectors
+ * through the same shape it reads them by.
+ */
+export type ConnectorEntry = {
+    /** The identifier a provider element stores in its `connector` attribute. Unique within the space. */
+    id: string;
+    name: string;
+    manifest: ConnectorManifest;
+};
+export type ConnectorFilter = {
+    field: string;
+    operator: string;
+    value: string | number | boolean;
+};
+export type ConnectorQuery = {
+    /** Content type / collection name substituted into the path template. */
+    resource?: string;
+    limit?: number;
+    offset?: number;
+    page?: number;
+    cursor?: string;
+    filters?: ConnectorFilter[];
+    routeParams?: Record<string, string | undefined>;
+    queryParams?: Record<string, string>;
+};
+export type ConnectorRecord = {
+    id: string;
+    values: Record<string, unknown>;
+};
+/** Resolved credential material. Values are interpolated into templates as `{{credential.<key>}}`. */
+export type ConnectorCredential = Record<string, string>;

package/dist/types/DevToolsTypes.d.ts

@@ -3,7 +3,7 @@ import { NavigationStatus } from './NavigationTypes';
 import { ElementInteraction } from './SchemaTypes';
 import { ReactNode } from 'react';
 export type LogType = 'info' | 'warning' | 'danger' | 'success' | 'custom';
-export type LogCategory = 'navigation' | 'interactions' | 'store';
+export type LogCategory = 'navigation' | 'interactions' | 'store' | 'network';
 export type LogNavigation = {
     category: 'navigation';
     params: {
@@ -18,7 +18,10 @@ export type LogEventBridge = {
 export type LogInteraction = {
     category: 'interactions';
     params: {
+        /** The SOURCE a global callback or utility named — `space`, `state` — not the element it ran on. */
         elementId: string;
+        /** The idRef of the element the interaction fired on. What tells two identical-looking entries apart. */
+        elementRef?: string;
         startTime: number;
         endTime: number;
         node: ElementInteraction;
@@ -35,10 +38,22 @@ export type LogStore = {
         next: unknown;
     };
 };
-export type LogParams = LogNavigation['params'] | LogInteraction['params'] | LogEventBridge['params'] | LogStore['params'];
+/** Something that arrived from the server and was not what it claimed to be — a space event failing its schema. */
+export type LogNetwork = {
+    category: 'network';
+    params: {
+        event: string;
+        issues: {
+            path: string;
+            message: string;
+        }[];
+        payload?: unknown;
+    };
+};
+export type LogParams = LogNavigation['params'] | LogInteraction['params'] | LogEventBridge['params'] | LogStore['params'] | LogNetwork['params'];
 export type Log = {
     logType: string;
     message: ReactNode;
     time?: string;
-} & (LogInteraction | LogNavigation | LogEventBridge | LogStore);
+} & (LogInteraction | LogNavigation | LogEventBridge | LogStore | LogNetwork);
 export type ProviderCallback = (...args: unknown[]) => Record<string, unknown>;

package/dist/types/InteractionTypes.d.ts

@@ -1,7 +1,7 @@
 import { ElementInteraction } from './SchemaTypes';
 import { RuleValue } from '@plitzi/plitzi-ui/QueryBuilder';
 export type InteractionCallbackType = 'trigger' | 'globalCallback' | 'callback' | 'utility';
-export type InteractionStatus = 'completed' | 'skipped';
+export type InteractionStatus = 'completed' | 'skipped' | 'failed';
 export type InteractionNodeStatus = 'success' | 'failed' | 'skipped' | 'disabled';
 export type InteractionPostCallback<T extends Record<string, unknown> = Record<string, unknown>> = (params: InteractionCallbackParamValues<T>, callbackResult?: unknown) => unknown;
 export type PostCallbackNode<T extends Record<string, unknown> = Record<string, unknown>> = {

package/dist/types/McpTypes/index.d.ts

@@ -54,7 +54,3 @@ export type McpTool = {
     };
     handler?: McpToolHandler;
 };
-export type McpServerConfig = {
-    enabled?: boolean;
-    path?: string;
-};

package/dist/types/NavigationTypes.d.ts

@@ -1,13 +1,3 @@
-import { Helmet } from '@dr.pogodin/react-helmet';
 export type NavigationStatus = 'authenticated' | 'normal' | 'redirect' | 'notFound' | 'accessDenied';
 export type QueryParams = Record<string, string[] | string | undefined>;
 export type RouteParams = Record<string, string[] | string | undefined>;
-export type NavigationContextValue = {
-    Helmet?: typeof Helmet;
-    navigate: (url: string, isExternal?: boolean) => void;
-    urlSearchParams?: URLSearchParams;
-    routeParams: RouteParams;
-    queryParams: QueryParams;
-    hostname?: string;
-    currentPageId: string;
-};

package/dist/types/SchemaTypes.d.ts

@@ -7,8 +7,6 @@ export type SchemaRsc = {
     enabled?: boolean;
     /** Wire protocol for RSC updates. 'json' is the default (data-only). 'stream' uses the RSC wire format (requires react-server condition). */
     transport?: 'json' | 'stream';
-    /** Path for the RSC endpoint. Defaults to '/_rsc'. */
-    path?: string;
 };
 export type DropPosition = 'top' | 'bottom' | 'left' | 'right' | 'inside' | 'custom';
 export type BindingCategory = 'attributes' | 'style' | 'initialState';
@@ -98,9 +96,8 @@ export type Schema = {
         keepState?: boolean;
         stateStorage?: 'localStorage' | 'sessionStorage';
         customCss: string;
-        userProvider?: 'auth0' | 'basic' | 'custom' | '';
-        auth0Domain?: string;
-        auth0ClientId?: string;
+        /** `basic` covers any HTTP+JSON backend by configuration; anything else is a name someone registered. */
+        userProvider?: 'basic' | 'custom' | '' | (string & {});
         tokenStorage?: 'localStorage' | 'sessionStorage' | '';
         loginUrl?: string;
         userUrl?: string;
@@ -108,7 +105,32 @@ export type Schema = {
         logoutUrl?: string;
         detailsPath?: string;
         tokenPath?: string;
+        refreshTokenPath?: string;
         expirationTimePath?: string;
+        refreshExpirationTimePath?: string;
+        /**
+         * Name of a readable (non-httpOnly) cookie your backend sets alongside its session cookie, whose value is
+         * `<access expiry>.<refresh expiry>` in unix seconds. It carries no credential — only when the session dies —
+         * and it is what lets a page answer "is anyone signed in here?" with no request at all, including the answer
+         * "no". Without it, a first load with empty storage has to ask the backend to find out.
+         */
+        sessionHintCookie?: string;
+        /**
+         * Where to hand a credential this browser obtained on its own, so the rendering server can establish a session
+         * of its own for it. Declaring it is how a space says "my sign-in happens in the browser" — a client-side
+         * identity provider (Auth0 and the like) leaves the server rendering pages as a guest while the browser knows
+         * who this is, and the page changes under the visitor as it hydrates. Leave empty when your backend issues the
+         * session itself, which is the case whenever `loginUrl` is your own API.
+         */
+        sessionExchangeUrl?: 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,
+         * trading a round trip for never showing a signed-in page to someone whose session has just ended.
+         */
+        sessionGate?: 'optimistic' | 'strict';
+        /** How old a confirmation may get before the SDK re-checks on the next focus. Defaults to 300. */
+        sessionRevalidateSeconds?: number;
     };
     rsc?: SchemaRsc;
     pages: Element['id'][];

package/dist/types/SdkTypes.d.ts

@@ -1,4 +1,3 @@
-import { Collection } from './CollectionTypes';
 import { ComponentDefinition } from './ElementTypes';
 import { PluginRaw } from './PluginTypes';
 import { Schema } from './SchemaTypes';
@@ -9,8 +8,26 @@ export type OfflineDataRaw = {
     style: Style;
     plugins?: PluginRaw[];
     segments?: Record<string, Segment>;
-    collections?: Record<string, Collection>;
 };
 export type OfflineData = Omit<OfflineDataRaw, 'plugins'> & {
     plugins: Record<string, ComponentDefinition>;
 };
+/**
+ * Where the browser reports what it can only see from the browser — SPA route changes, interactions, the
+ * visitor's country/device — and the credential it reports with.
+ *
+ * The page view that BILLS is never counted from here: a key that ships inside a public page is a key anyone
+ * can replay, so quota is metered at the two server-side chokepoints that cost the deployment real bandwidth
+ * (the SSR render, and the schema fetch a client-side render makes). This channel feeds the analytics plane
+ * only. A render with no config reports nothing at all, which is what an offline export or an embedded widget
+ * gets.
+ */
+export type AnalyticsConfig = {
+    /** Collector base URL, e.g. `https://api.example.com/v1/collect`. Batches POST to `${endpoint}/batch`. */
+    endpoint: string;
+    /** Public per-space ingest key, sent as `x-plitzi-ingest-key`. */
+    key: string;
+    /** The server already counted this page load, so the first render must not be reported again. Set by SSR;
+     *  a purely client-side render leaves it off and reports its own first view. */
+    firstViewCounted?: boolean;
+};