@plitzi/sdk-server 0.32.24 → 0.33.0

package/dist/src/modules/mcp/proxy/config.d.ts

@@ -1,17 +0,0 @@
-import { ResourceProxy, ResourceProxySettings } from './types';
-import { SSRRequest, SSRServerConfig } from '@plitzi/sdk-shared';
-export declare const PROXY_PATH = "/__proxy";
-/** What this deployment serves at its widget endpoint, or undefined when it serves none. A secret is what turns it
- *  on: without one the endpoint could not tell its own widgets' URLs from anyone else's, and an unsigned fetcher
- *  on a public origin is an open proxy. */
-export declare const proxySettings: (config: SSRServerConfig) => ResourceProxySettings | undefined;
-/** The endpoint as a widget must address it: absolute, because the page runs on the host's origin and a relative
- *  URL there points at the host. Falls back to the origin this request came in on, which is the right one whenever
- *  the MCP server owns its sub-domain; a deployment reached under a different public name sets `proxy.baseUrl`.
- *  The grants it mints carry the fingerprint of THIS request's credential, so they belong to this connection. */
-export declare const requestProxy: (config: SSRServerConfig, req: SSRRequest) => ResourceProxy | undefined;
-/** The proxy THIS tool may use, or undefined — the single place that decides it, so a tool cannot reach the
- *  endpoint by being wired to it later. A render authors a throwaway widget, so rewriting its URLs is invisible
- *  and lasts as long as the widget does; a tool that WRITES a space (plitzi_apply) would persist those URLs into
- *  content the user owns, which is why it is not on the list unless a deployment puts it there deliberately. */
-export declare const proxyForTool: (proxy: ResourceProxy | undefined, tool: string) => ResourceProxy | undefined;

package/dist/src/modules/mcp/proxy/fetch.d.ts

@@ -1,18 +0,0 @@
-import { ProxyKind } from './types';
-export type FetchFailure = {
-    ok: false;
-    status: number;
-    reason: string;
-};
-export type FetchSuccess = {
-    ok: true;
-    contentType: string;
-    contentLength?: number;
-    body: Response['body'];
-};
-export type FetchResult = FetchFailure | FetchSuccess;
-/** Fetch a remote resource on the widget's behalf. Redirects are followed by hand rather than by fetch, because
- *  each hop is a new host that has to pass the same guard — an allowed URL that redirects into the private network
- *  would otherwise walk straight through it. (It is also what makes the redirect-based image services work at
- *  all: the sandbox loses the redirect, this does not.) */
-export declare const fetchResource: (target: string, kind: ProxyKind, maxBytes: number) => Promise<FetchResult>;

package/dist/src/modules/mcp/proxy/grant.d.ts

@@ -1,23 +0,0 @@
-import { ProxyKind, ResourceProxy } from './types';
-/** What a widget was granted. The kind is signed in too, so a URL minted for an image cannot be replayed as an
- *  API call (they answer with different content types, cache rules and request headers). */
-export type Grant = {
-    kind: ProxyKind;
-    target: string;
-};
-/** Mint the URL a widget will load this target from: this server's endpoint, carrying the target, the kind it was
- *  granted for, when the grant stops working and which connection minted it — all covered by one signature. */
-export declare const grantUrl: (target: string, proxy: ResourceProxy, kind?: ProxyKind) => string;
-/** What this endpoint was asked to fetch, or undefined when the parameter is missing, malformed, expired or not
- *  signed here — which is what keeps it from being an open proxy for anyone who finds it: it serves the URLs this
- *  server rewrote, for as long as it said, and nothing else.
- *
- *  Takes the parameter as the query parser hands it over — decoded exactly once, which is the form that was
- *  signed. Decoding it again would corrupt every target that legitimately carries a percent-escape (an API URL
- *  with a nested URL in its query) and reject it as unsigned. */
-export declare const readGrant: (param: string | undefined, secret: string) => Grant | undefined;
-export declare const PROXY_PARAM = "i";
-/** Is this URL one the widget can already reach? Absolute http(s) URLs are the ones a sandbox CSP blocks;
- *  `data:`/`blob:` carry their own bytes, and a relative URL has no origin to reach in the first place. */
-export declare const isRemote: (url: string) => boolean;
-export declare const isGranted: (url: string, proxy: ResourceProxy) => boolean;

package/dist/src/modules/mcp/proxy/guard.d.ts

@@ -1,6 +0,0 @@
-export declare const isPrivateAddress: (address: string) => boolean;
-/** Does this hostname resolve somewhere on the public internet? The endpoint fetches URLs an agent authored, so
- *  without this it would be a way to read whatever the pod itself can reach — the cluster's services, the cloud
- *  metadata endpoint, a database on the node. Both the literal address and every address the name resolves to are
- *  checked; a name that does not resolve is refused rather than handed to fetch. */
-export declare const isPublicHost: (hostname: string) => Promise<boolean>;

package/dist/src/modules/mcp/proxy/handler.d.ts

@@ -1,8 +0,0 @@
-import { ResourceProxySettings } from './types';
-import { SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
-/** Serve one external resource on behalf of a widget: check the grant this server signed, fetch the target, and
- *  stream it back under this origin — the one the CSP declares. Read-only, credential-free and CORS-open, because
- *  it answers the host's sandboxed iframe: a browser that has no origin of its own and can present nothing. The
- *  grant is what stands in for a caller identity — it is unforgeable, it names one target (or one host, for a
- *  templated API URL), it names the kind, it expires, and it carries the connection that minted it. */
-export declare const handleProxyRequest: (req: SSRRequest, res: SSRResponseHelpers, settings: ResourceProxySettings) => Promise<void>;

package/dist/src/modules/mcp/proxy/index.d.ts

@@ -1,7 +0,0 @@
-export { PROXY_PATH, proxyForTool, proxySettings, requestProxy } from './config';
-export { grantUrl, isGranted, isRemote, PROXY_PARAM, readGrant } from './grant';
-export { handleProxyRequest } from './handler';
-export { proxifyResources, rewriteText } from './rewrite';
-export { connectionId, sign, verify } from './sign';
-export { DEFAULT_PROXY_TOOLS } from './types';
-export type { ProxyKind, ResourceProxy, ResourceProxySettings } from './types';

package/dist/src/modules/mcp/proxy/rewrite.d.ts

@@ -1,13 +0,0 @@
-import { ResourceProxy } from './types';
-import { Schema, Style } from '@plitzi/sdk-shared';
-/** Rewrite every remote URL embedded in a string: `url(…)` in CSS, `src="…"` in markup, `![](…)` in markdown. */
-export declare const rewriteText: (text: string, proxy: ResourceProxy) => string;
-/** Point everything an authored widget loads from outside — images, media, fonts, and the data an apiContainer
- *  fetches — at this server's endpoint, in place. The AGENT never sees this: it authors the real URL and this runs
- *  afterwards, on the throwaway space a render builds (so nothing shared is mutated) and before the global style
- *  cache is compiled (so the concatenated CSS comes out already rewritten). Returns what could not be rewritten,
- *  which is the only part the model hears about. */
-export declare const proxifyResources: (space: {
-    schema: Schema;
-    style: Style;
-}, proxy: ResourceProxy) => string[];

package/dist/src/modules/mcp/proxy/sign.d.ts

@@ -1,6 +0,0 @@
-export declare const sign: (payload: string, secret: string) => string;
-export declare const verify: (payload: string, signature: string, secret: string) => boolean;
-/** A short, stable fingerprint of the MCP credential a request carried — the connection a grant belongs to.
- *  Derived through the same secret, so it identifies without echoing any part of the token; a request with no
- *  credential (the public widgets surface) gets the shared anonymous identity. */
-export declare const connectionId: (authorization: string | undefined, secret: string) => string;

package/dist/src/modules/mcp/proxy/types.d.ts

@@ -1,45 +0,0 @@
-/** What a widget is loading. Both ride the same endpoint but are not the same thing: an asset is immutable and
- *  cached hard, data is an API answer that must never be served stale, and each accepts its own content types. */
-export type ProxyKind = 'asset' | 'data';
-/** How a widget reaches ANYTHING outside its sandbox — an image, a font, a video, an API.
- *
- *  An MCP App runs in an iframe on the HOST's origin under a CSP the host builds from the domains this server
- *  declares, and that declaration belongs to the `ui://` RESOURCE: it is read (and may be cached) before any
- *  widget exists, the spec types `csp` as `never` on the tool meta, and plitzi_render is stateless, so the origins
- *  an agent is about to author can never be listed there. The one origin that CAN be declared up front is this
- *  server's own, so every external URL a render authored is rewritten to point here and this server fetches the
- *  original — which also settles the redirects, hotlink rules and missing CORS headers a null-origin sandbox
- *  cannot. Nothing is stored: the URL carries its own signed grant, so any replica answers any request. */
-export interface ResourceProxy {
-    /** Absolute endpoint the browser fetches from, e.g. `https://mcp.plitzi.app/__proxy`. */
-    endpoint: string;
-    /** Signs the grant, so the endpoint serves what this server rewrote and not whatever a caller asks for. */
-    secret: string;
-    /** Fingerprint of the MCP credential the render was called with (see `connectionId`). It is signed into every
-     *  URL, so the grants one connection minted are distinct from another's and a widget's URLs cannot be pooled. */
-    identity: string;
-    /** How long a minted URL stays valid, in seconds. A widget outlives the call that made it (it sits in the
-     *  conversation), so this is days rather than minutes — but not forever, so a leaked URL stops working. */
-    ttl: number;
-    /** The tools allowed to rewrite through this endpoint (see {@link DEFAULT_PROXY_TOOLS}). Carried here because
-     *  the decision is made once, where each tool's context is built. */
-    tools: readonly string[];
-}
-/** The tools a proxy may be handed to. `plitzi_render` alone by default, and that default is a guard, not a
- *  convenience: a render is a THROWAWAY widget, so rewriting its URLs changes nothing that outlives the call —
- *  while plitzi_apply writes to the user's real space, where a rewritten URL would be PERSISTED and the space
- *  would come to depend on this server's endpoint for content it owns. Nothing else should be added here without
- *  that being the intention. */
-export declare const DEFAULT_PROXY_TOOLS: string[];
-/** The endpoint's own side of the same feature: where it answers and what it will carry. */
-export interface ResourceProxySettings {
-    path: string;
-    secret: string;
-    maxBytes: number;
-    ttl: number;
-    /** Which tools rewrite their URLs through the endpoint (see {@link DEFAULT_PROXY_TOOLS}). */
-    tools: readonly string[];
-    /** Absolute base to build widget URLs from. Empty → the origin each request arrived on, which is right whenever
-     *  the MCP server owns its sub-domain. */
-    baseUrl?: string;
-}

package/dist/src/modules/mcp/resources/canonical.d.ts

@@ -1,6 +0,0 @@
-import { Env } from '../types';
-export declare const canonicalUri: (env: Env, uri: string) => string;
-/** Teachable message for a URI that read as null. Distinguishes a well-formed URI whose ref does not resolve (the
- *  resource may be stale/deleted) from a URI whose shape matches no template at all (malformed — echo the valid
- *  templates so the agent stops hand-building URIs). See RFC 0004 I2. */
-export declare const resourceErrorMessage: (env: Env, uri: string) => string;

package/dist/src/modules/mcp/resources/core.d.ts

@@ -1,5 +0,0 @@
-import { Space } from '../helpers';
-import { ResourceEnvelope } from '../types';
-/** Space-independent singletons: the usage guide, the observed type registry and the CSS property catalog.
- *  Returns undefined when the URI is not one of these, so the router falls through to the next resolver. */
-export declare const readCoreResource: (space: Space, uri: string) => ResourceEnvelope<unknown> | undefined;

package/dist/src/modules/mcp/resources/envelope.d.ts

@@ -1,10 +0,0 @@
-import { ResourceEnvelope } from '../types';
-/** Wrap any read projection with the version its optimistic-concurrency checks key on. */
-export declare const envelope: <T>(data: T) => ResourceEnvelope<T>;
-export declare const jsonContents: (uri: string, data: unknown) => {
-    contents: {
-        uri: string;
-        mimeType: string;
-        text: string;
-    }[];
-};

package/dist/src/modules/mcp/resources/index.d.ts

@@ -1,8 +0,0 @@
-export { readPublicResource, readResource, resourceVersion } from './router';
-export { registerResources } from './register';
-export { resourceErrorMessage } from './canonical';
-export { RENDER_GUIDE_URI, RENDER_TYPES_URI } from './renderGuide';
-export { buildTypeRegistry, cssProperties, cssShorthands, expandShorthand, isCssProperty, suggestCssProperty } from '../catalogs';
-export type { TypeInfo, TypePropInfo, TypeRegistry } from '../catalogs';
-export * from '../tools/operations/schema/translator';
-export * from '../tools/operations/style/translator';

package/dist/src/modules/mcp/resources/primer.d.ts

@@ -1,7 +0,0 @@
-import { Space } from '../helpers';
-import { Env, ResourceEnvelope } from '../types';
-/** The cold-start bundle: everything the guide says to read before the first write, in one round-trip.
- *  Summaries only — never full page/element trees (those are opened on demand), so it stays cheap even on a
- *  large space. Carries the condensed `guideQuickstart` (not the full guideText, which the agent reads on demand at
- *  plitzi://guide) to keep the bundle small. Returns undefined when the URI is not the primer. */
-export declare const readPrimerResource: (space: Space, env: Env, uri: string) => ResourceEnvelope<unknown> | undefined;

package/dist/src/modules/mcp/resources/register.d.ts

@@ -1,10 +0,0 @@
-import { McpLog, Space } from '../helpers';
-import { Env } from '../types';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-/** Register every resource on the MCP server: fixed listings plus templated per-item reads. The space is
- *  loaded lazily via getSpace, so listing resources never touches the store — only reading one does.
- *
- *  `hasSpace` is false when the connection reaches no space (a guest / widgets-only grant): the space-dependent
- *  families are then not registered at all, so the catalog the agent browses holds only what it can actually
- *  open — no listing that answers every read with the same refusal. */
-export declare const registerResources: (server: McpServer, getSpace: () => Promise<Space>, env: Env, log: McpLog, hasSpace: boolean) => void;

package/dist/src/modules/mcp/resources/renderGuide.d.ts

@@ -1,10 +0,0 @@
-import { McpLog } from '../helpers';
-import { ResourceEnvelope } from '../types';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare const RENDER_GUIDE_URI = "plitzi://render/guide";
-export declare const RENDER_TYPES_URI = "plitzi://render/types";
-/** The same two documents through the READ path (the router, hence plitzi_read), not only as MCP resources: an
- *  agent that reaches for the batch-read tool — the reflex the guide itself teaches — must not be told its own
- *  authoring guide does not exist. Space-independent, like the core singletons. */
-export declare const readRenderResource: (uri: string) => ResourceEnvelope<unknown> | undefined;
-export declare const registerRenderResources: (server: McpServer, log: McpLog) => void;

package/dist/src/modules/mcp/resources/router.d.ts

@@ -1,10 +0,0 @@
-import { Space } from '../helpers';
-import { Env, ResourceEnvelope } from '../types';
-/** Resolve a resource URI to its versioned envelope, or null if unknown / not found. */
-export declare const readResource: (space: Space, env: Env, rawUri: string) => ResourceEnvelope<unknown> | null;
-/** What a connection carrying NO space (a guest / widgets-only grant) can still read: the space-independent
- *  singletons and the render docs. Undefined for everything else, so the caller says the connection has no space
- *  instead of answering out of an empty one — an empty page list would read as "this space has no pages". */
-export declare const readPublicResource: (env: Env, rawUri: string) => ResourceEnvelope<unknown> | undefined;
-/** Current version of a resource, for optimistic-concurrency checks. Null when the URI is unknown. */
-export declare const resourceVersion: (space: Space, env: Env, uri: string) => string | null;

package/dist/src/modules/mcp/resources/schema.d.ts

@@ -1,5 +0,0 @@
-import { Space } from '../helpers';
-import { Env, ResourceEnvelope } from '../types';
-/** Element-schema reads: page listings/skeletons/styles, folders, single elements and schema variables. Returns
- *  undefined when the URI belongs to another domain, null when the shape is ours but the ref does not resolve. */
-export declare const readSchemaResource: (space: Space, env: Env, uri: string) => ResourceEnvelope<unknown> | null | undefined;

package/dist/src/modules/mcp/resources/style.d.ts

@@ -1,5 +0,0 @@
-import { Space } from '../helpers';
-import { Env, ResourceEnvelope } from '../types';
-/** Style-schema reads: definitions, global (per-type) styles and design-token variables by category. Returns
- *  undefined when the URI belongs to another domain, null when the shape is ours but the ref does not resolve. */
-export declare const readStyleResource: (space: Space, env: Env, uri: string) => ResourceEnvelope<unknown> | null | undefined;

package/dist/src/modules/mcp/screenshotClient.d.ts

@@ -1,13 +0,0 @@
-import { ScreenshotClient } from './types';
-export type HttpScreenshotClientConfig = {
-    /** Browser service that turns a URL into PNG(s): POST { url, viewports } → { images }. */
-    serviceUrl: string;
-    /** SSR base the browser navigates to; the page path and the one-shot `__pt` token are appended. */
-    renderBaseUrl: string;
-    /** Injectable fetch (tests / non-global runtimes). Defaults to the global fetch. */
-    fetchImpl?: typeof fetch;
-};
-/** Default `ScreenshotClient`: composes the navigable preview URL (renderBaseUrl + pagePath + `?__pt=token`) and
- *  POSTs it to the browser service. Any network/HTTP failure surfaces as `ok:false` so the tool can fall back to
- *  the HTML preview instead of hard-failing. */
-export declare const createHttpScreenshotClient: ({ serviceUrl, renderBaseUrl, fetchImpl }: HttpScreenshotClientConfig) => ScreenshotClient;

package/dist/src/modules/mcp/server.d.ts

@@ -1,31 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { ResourceProxy } from './proxy';
-import { PreviewClient, ScreenshotClient } from './types';
-import { SSRAdapters, ServerLogger } from '@plitzi/sdk-shared';
-/** The MCP service is stateless: every request resolves its own `spaceId` (from the request JWT) and reads the
- *  space fresh through the adapters — schema and style are two documents, read/written independently. The spaceId
- *  is resolved once per request, up front, because it decides what this connection IS: with a space, the full
- *  editing server; without one (no auth, a guest connection, a widgets-only grant), a widget server that offers
- *  only what works there. The space documents themselves still load lazily — the handshake and the listings never
- *  touch the store. */
-export interface McpServerContext {
-    adapters: SSRAdapters;
-    getSpaceId: () => Promise<number | undefined>;
-    /** How the visual-preview tools (plitzi_preview / plitzi_screenshot) reach the renderer. Absent → those tools
-     *  report PREVIEW_UNAVAILABLE, so an MCP-only deployment without a renderer still runs every other tool. */
-    preview?: PreviewClient;
-    /** The dedicated browser service for plitzi_screenshot. Absent → the tool is not registered (only the HTML
-     *  plitzi_preview is offered). */
-    screenshot?: ScreenshotClient;
-    /** Structured request-log sink. When set, every tool call and resource read emits an McpLogEvent to it (the
-     *  consumer renders them); otherwise logging falls back to the console when MCP_DEBUG=1. */
-    logger?: ServerLogger;
-    /** May the plitzi_render view paint from tool arguments the host is still streaming (see `mcpAi.renderStreaming`)?
-     *  Defaults to true. */
-    renderStreaming?: boolean;
-    /** Where a rendered widget loads everything external from (see `mcpAi.proxy`). It reaches two places: the render
-     *  tool, which rewrites the URLs the agent authored, and the App's CSP, which declares the origin those URLs
-     *  point at. Absent → neither happens, and a widget's resources load only where the host allows their origin. */
-    proxy?: ResourceProxy;
-}
-export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger, renderStreaming, proxy }: McpServerContext) => Promise<McpServer>;

package/dist/src/modules/mcp/tests/helpers.d.ts

@@ -1,13 +0,0 @@
-import { Space } from '../helpers';
-import { Operation } from '../tools';
-import { Persisters } from '../types';
-declare const buildSpace: () => Space;
-declare const capturing: (space: Space) => {
-    persisters: Persisters;
-    saved: () => Space;
-};
-declare const spaceWithRoute: () => Space;
-declare const varOp: (pageRef: string, type: string, value: string) => Operation;
-declare const scopeSpace: () => Space;
-declare const malformedSpace: () => Space;
-export { buildSpace, capturing, spaceWithRoute, varOp, scopeSpace, malformedSpace };

package/dist/src/modules/mcp/tools/apply/dispatch.d.ts

@@ -1,6 +0,0 @@
-import { Space } from '../../helpers';
-import { Env, MutationOutcome } from '../../types';
-import { Operation } from '../operations';
-/** Apply operations in order to the space (mutating it). Records which schema(s) changed so the caller can
- *  persist each independently. Stops collecting counts for a failed op but records its errors. */
-export declare const applyOperations: (space: Space, env: Env, ops: Operation[]) => MutationOutcome;