@plitzi/sdk-server 0.32.25 → 0.33.1

package/dist/helpers/compress.js

@@ -1,17 +1,53 @@
 import { brotliCompressSync, constants, gzipSync } from "node:zlib";
 //#region src/helpers/compress.ts
-var MIN_SIZE = 1024;
-var selectEncoding = (acceptEncoding) => {
-	if (!acceptEncoding) return "identity";
-	if (acceptEncoding.includes("br")) return "br";
-	if (acceptEncoding.includes("gzip")) return "gzip";
-	return "identity";
+/** What the server does when the deployment says nothing: Brotli where the client takes it, gzip otherwise. */
+var DEFAULT_COMPRESSION = {
+	encodings: ["br", "gzip"],
+	threshold: 1024,
+	brotliQuality: 4,
+	gzipLevel: 6
 };
-var compressBody = (body, encoding) => {
-	if (encoding === "identity" || body.length < MIN_SIZE) return body;
+/**
+* The deployment's compression policy, with the gaps filled in. `false` means never compress, and is expressed as
+* an empty encoding list so there is one shape downstream rather than a boolean to re-test at every use.
+*/
+var resolveCompression = (config) => {
+	if (config === false) return {
+		...DEFAULT_COMPRESSION,
+		encodings: []
+	};
+	return {
+		...DEFAULT_COMPRESSION,
+		...config
+	};
+};
+/**
+* What the client will accept, as a set of tokens it did NOT refuse.
+*
+* `q=0` is a refusal, and the header is the one place a client can say "not Brotli" — a proxy that mangles it, an
+* old client that decodes it wrongly. Matching on substrings alone honoured the offer and ignored the refusal,
+* which is the one way this can produce a body the caller cannot read.
+*/
+var acceptedEncodings = (acceptEncoding) => {
+	const accepted = /* @__PURE__ */ new Set();
+	for (const part of acceptEncoding.split(",")) {
+		const [token, ...params] = part.trim().split(";");
+		const quality = params.map((param) => /^\s*q=([\d.]+)\s*$/iu.exec(param)).find((match) => match !== null)?.[1];
+		if (quality === void 0 || Number(quality) > 0) accepted.add(token.trim().toLowerCase());
+	}
+	return accepted;
+};
+/** The first encoding this server prefers that the client actually takes. `*` counts as taking anything. */
+var selectEncoding = (acceptEncoding, compression = DEFAULT_COMPRESSION) => {
+	if (!acceptEncoding || compression.encodings.length === 0) return "identity";
+	const accepted = acceptedEncodings(acceptEncoding);
+	return compression.encodings.find((encoding) => accepted.has(encoding) || accepted.has("*")) ?? "identity";
+};
+var compressBody = (body, encoding, compression = DEFAULT_COMPRESSION) => {
+	if (encoding === "identity" || body.length < compression.threshold) return body;
 	const buf = Buffer.from(body, "utf-8");
-	if (encoding === "br") return brotliCompressSync(buf, { params: { [constants.BROTLI_PARAM_QUALITY]: 4 } });
-	return gzipSync(buf, { level: 6 });
+	if (encoding === "br") return brotliCompressSync(buf, { params: { [constants.BROTLI_PARAM_QUALITY]: compression.brotliQuality } });
+	return gzipSync(buf, { level: compression.gzipLevel });
 };
 //#endregion
-export { compressBody, selectEncoding };
+export { DEFAULT_COMPRESSION, compressBody, resolveCompression, selectEncoding };

package/dist/helpers/offlineDataLoader.d.ts

@@ -0,0 +1,11 @@
+import { OfflineDataRaw } from '@plitzi/sdk-shared';
+export type OfflineDataLoader = () => Promise<OfflineDataRaw | undefined>;
+/**
+ * One read of the space per request, however many things ask for it.
+ *
+ * The page render and the RSC read both need the schema and are deliberately started in parallel, so neither can
+ * hand its result to the other. Sharing the promise is what makes that safe: whichever asks first begins the read
+ * and the other joins it. It holds the promise, not the value — there is no cache here and nothing to invalidate,
+ * because it lives exactly as long as the request that made it.
+ */
+export declare const createOfflineDataLoader: (read: OfflineDataLoader) => OfflineDataLoader;

package/dist/helpers/offlineDataLoader.js

@@ -0,0 +1,15 @@
+//#region src/helpers/offlineDataLoader.ts
+/**
+* One read of the space per request, however many things ask for it.
+*
+* The page render and the RSC read both need the schema and are deliberately started in parallel, so neither can
+* hand its result to the other. Sharing the promise is what makes that safe: whichever asks first begins the read
+* and the other joins it. It holds the promise, not the value — there is no cache here and nothing to invalidate,
+* because it lives exactly as long as the request that made it.
+*/
+var createOfflineDataLoader = (read) => {
+	let pending;
+	return () => pending ??= read();
+};
+//#endregion
+export { createOfflineDataLoader };

package/dist/helpers/resolveDebugMode.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a render may expose debugging: the panel, element ids in the markup, the store.
+ *
+ * An SSR page loads the same SDK a client-rendered one does, so it follows the same rule: the page's `debugMode`
+ * authorizes it (`devMode` when the server did not say otherwise), and the 'plitzi_debug' cookie is only the
+ * visitor's preference within that — it exists so the SSR render matches what the client hydrates with. Being
+ * client-owned, the cookie can turn debugging off, never on: otherwise any visitor of a published site could set it
+ * and get the debug render.
+ */
+export declare const resolveDebugMode: (authorized: boolean | undefined, debugCookie: string | undefined) => boolean;

package/dist/helpers/resolveDebugMode.js

@@ -0,0 +1,13 @@
+//#region src/helpers/resolveDebugMode.ts
+/**
+* Whether a render may expose debugging: the panel, element ids in the markup, the store.
+*
+* An SSR page loads the same SDK a client-rendered one does, so it follows the same rule: the page's `debugMode`
+* authorizes it (`devMode` when the server did not say otherwise), and the 'plitzi_debug' cookie is only the
+* visitor's preference within that — it exists so the SSR render matches what the client hydrates with. Being
+* client-owned, the cookie can turn debugging off, never on: otherwise any visitor of a published site could set it
+* and get the debug render.
+*/
+var resolveDebugMode = (authorized, debugCookie) => Boolean(authorized) && debugCookie !== "false";
+//#endregion
+export { resolveDebugMode };

package/dist/index.d.ts

@@ -1,2 +1,16 @@
-export * from './src/index.js'
-export {}
+export { createServer, resolveServices } from './core/createServer';
+export { registerHealthCheck, buildHealthPayload } from './core/health';
+export { consoleLogger, renderLogEvent } from './helpers/serverLog';
+export type { HealthCheckApp, HealthIdentity } from './core/health';
+export { createJsonAdapters } from './adapters/jsonAdapters';
+export { createAuthAdapters } from './adapters/authAdapters';
+export { createMemoryDraftStore, takeDraftOverride } from './modules/ssr/preview';
+export { PREVIEW_TOKEN_PARAM } from './core/previewToken';
+export { resolveRscData } from './modules/rsc/resolveRscData';
+export { fetchConnectorRecords, rebaseMedia, writeConnectorRecord, createConnectorResolver } from './modules/connectors';
+export type { JsonAdaptersConfig } from './adapters/jsonAdapters';
+export type { AuthAdapters, AuthAdaptersConfig } from './adapters/authAdapters';
+export type { RscElementResolver, RscResolveContext, ResolveRscDataOptions } from './modules/rsc/resolveRscData';
+export type { ConnectorAuth, ConnectorCredential, ConnectorEndpoints, ConnectorFilter, ConnectorLookups, ConnectorManifest, ConnectorManifestDraft, ConnectorPageInfo, ConnectorPagination, ConnectorQuery, ConnectorReadEndpoint, ConnectorRecord, ConnectorResponseMapping, ConnectorResult, ProviderPagination } from './modules/connectors';
+export type { ResolvedServices } from './core/createServer';
+export type { BaseContext, PipelineExtensions, SSRContext, Stage } from './core/http/types';

package/dist/index.js

@@ -1,23 +1,12 @@
-import { buildAgentGuide } from "./modules/mcp/helpers/agentPrompt.js";
-import { consoleLogger, renderLogEvent } from "./helpers/serverLog.js";
-import { operation } from "./modules/mcp/tools/operations/index.js";
-import { apply, applyShape } from "./modules/mcp/tools/apply/index.js";
-import { read, readShape } from "./modules/mcp/tools/read.js";
-import { search, searchShape } from "./modules/mcp/tools/search.js";
-import { validate, validateShape } from "./modules/mcp/tools/validate.js";
-import { tools } from "./modules/mcp/tools/index.js";
-import { bindTools, getAllowedModes, isCallToolResult, isToolActive, resolveToolHandler, toolResponseErr, toolResponseFromResult, toolResponseOk, zodToJsonSchema } from "./modules/ai/toolkit.js";
-import { createMcpServer } from "./modules/mcp/server.js";
-import { handleMcp, readMcpBody, serveMcp } from "./modules/mcp/handler.js";
-import { createHttpPreviewClient } from "./modules/mcp/previewClient.js";
-import { PREVIEW_TOKEN_PARAM } from "./modules/mcp/constants.js";
-import { createHttpScreenshotClient } from "./modules/mcp/screenshotClient.js";
-import { createMemoryDraftStore, createPreview } from "./modules/ssr/preview.js";
-import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
-import { createMCPServer } from "./core/server/mcpServer.js";
+import { PREVIEW_TOKEN_PARAM } from "./core/previewToken.js";
+import { createMemoryDraftStore, takeDraftOverride } from "./modules/ssr/preview.js";
+import { fetchConnectorRecords, rebaseMedia, writeConnectorRecord } from "./modules/connectors/engine.js";
 import { resolveServices } from "./core/services/resolve.js";
-import { createSSRServer } from "./core/server/pageServer.js";
+import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
 import { createServer } from "./core/createServer.js";
+import { consoleLogger, renderLogEvent } from "./helpers/serverLog.js";
 import { createJsonAdapters } from "./adapters/jsonAdapters.js";
-import AIEngine from "./modules/ai/AIEngine.js";
-export { AIEngine, PREVIEW_TOKEN_PARAM, apply, applyShape, bindTools, buildAgentGuide, buildHealthPayload, consoleLogger, createHttpPreviewClient, createHttpScreenshotClient, createJsonAdapters, createMCPServer, createMcpServer, createMemoryDraftStore, createPreview, createSSRServer, createServer, getAllowedModes, handleMcp, isCallToolResult, isToolActive, operation, read, readMcpBody, readShape, registerHealthCheck, renderLogEvent, resolveServices, resolveToolHandler, search, searchShape, serveMcp, toolResponseErr, toolResponseFromResult, toolResponseOk, tools, validate, validateShape, zodToJsonSchema };
+import { createAuthAdapters } from "./adapters/authAdapters.js";
+import { resolveRscData } from "./modules/rsc/resolveRscData.js";
+import { createConnectorResolver } from "./modules/connectors/resolver.js";
+export { PREVIEW_TOKEN_PARAM, buildHealthPayload, consoleLogger, createAuthAdapters, createConnectorResolver, createJsonAdapters, createMemoryDraftStore, createServer, fetchConnectorRecords, rebaseMedia, registerHealthCheck, renderLogEvent, resolveRscData, resolveServices, takeDraftOverride, writeConnectorRecord };

package/dist/kernel.d.ts

@@ -0,0 +1,41 @@
+/** The HTTP kernel: everything needed to stand up a Plitzi server that is NOT a page server, and nothing else.
+ *
+ *  Import it as `@plitzi/sdk-server/kernel`. The package root is a barrel over the render path (SSR, RSC,
+ *  plugins, React), and ESM re-exports load eagerly — so a sibling server package that pulled `createHttpServer`
+ *  from there would load that whole graph. This entry's closure is the dispatcher, the transports and the base
+ *  stages: no React, no template, no plugin manager.
+ *
+ *  A server built on it supplies its own pipeline; `@plitzi/sdk-mcp` is the in-tree example. */
+export { createHttpServer } from './core/server/baseServer';
+export { makeHandler } from './core/http/dispatcher';
+export { healthStage } from './core/http/stages/health';
+export { configStaticStage, publicDirStage, wellKnownStage } from './core/http/stages/static';
+export { buildHealthPayload, registerHealthCheck } from './core/health';
+export { clientIp, parseRequest, readRawBody, requestOrigin } from './core/requestParser';
+export { clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies } from './core/auth/session';
+export { SCOPES, authFailureMessage, createTokens, userIdOf } from './core/auth/tokens';
+export { createCarriers, presentedOrigin } from './core/auth/credentials';
+export { ANY_DOMAIN, corsOrigins, domainAllowed, frameAncestors, hostnameOf, normalizeDomain } from './core/auth/domains';
+export { createIdentity } from './core/auth/identity';
+export { checkPermission, checkSpaceAccess, createAuthorizer, requirementFor } from './core/auth/authorize';
+export { createAuth } from './core/auth/createAuth';
+export { createAuthApi } from './core/auth/api';
+export { applySessionOutcome, authPolicyRules, authRoutes } from './core/auth/routes';
+export { createSpaceTokenApi } from './core/auth/spaceTokens';
+export { BUILT_IN_PROVIDERS, OAuthFailure, createSocialAuth, requestProfileJson } from './core/auth/oauth';
+export { consoleLogger, renderLogEvent } from './helpers/serverLog';
+export { PREVIEW_TOKEN_PARAM } from './core/previewToken';
+export type { HttpServerParts } from './core/server/baseServer';
+export type { BuildContext } from './core/http/dispatcher';
+export type { HealthCheckApp, HealthIdentity } from './core/health';
+export type { BaseContext, PipelineExtensions, SSRContext, Stage } from './core/http/types';
+export type { CookieCarrier, CookieSink, SessionCookieParams, SessionCookies } from './core/auth/session';
+export type { CredentialCarrier } from './core/auth/credentials';
+export type { Actor, ActorResult, Grant, GrantOptions, GrantResult, Identity, IdentityAdapters, IdentityConfig, SpaceMembership, StoredSpaceToken } from './core/auth/identity';
+export type { AuthPolicy, AuthorizeResult, Authorizer, MembershipFacts, PathMatcher, PermissionCheck, Requirement, SpaceAccessCheck } from './core/auth/authorize';
+export type { AuthRequest, AuthRoute } from './core/auth/routes';
+export type { Auth, AuthConfig } from './core/auth/createAuth';
+export type { CompletedFlow, OAuthFailureReason, OAuthProfile, OAuthProvider, OAuthProviderConfig, SocialAuth, SocialAuthAdapters, SocialAuthConfig, StartedFlow } from './core/auth/oauth';
+export type { AccountAccess, AccountAdapters, AccountRecord, AuthApi, AuthApiConfig, AuthOutcome } from './core/auth/api';
+export type { SpaceTokenAdapters, SpaceTokenApi, SpaceTokenContext, SpaceTokenOutcome, SpaceTokenRecord, SpaceTokenSummary } from './core/auth/spaceTokens';
+export type { AuthFailure, RefreshTokenPayload, SpaceScope, SpaceTokenOptions, SpaceTokenPayload, TokenConfig, TokenScope, Tokens, UserTokenPayload, VerifyResult, WidgetTokenPayload } from './core/auth/tokens';

package/dist/kernel.js

@@ -0,0 +1,22 @@
+import { clientIp, parseRequest, readRawBody, requestOrigin } from "./core/requestParser.js";
+import { createHttpServer } from "./core/server/baseServer.js";
+import { PREVIEW_TOKEN_PARAM } from "./core/previewToken.js";
+import { makeHandler } from "./core/http/dispatcher.js";
+import { clearFlowCookie, clearSessionCookies, createSessionCookies, isLocalHost, readFlowCookie, readRefreshToken, readSessionToken, sessionCookieParams, sessionHintValue, writeFlowCookie, writeSessionCookies } from "./core/auth/session.js";
+import { buildHealthPayload, registerHealthCheck } from "./core/health.js";
+import { healthStage } from "./core/http/stages/health.js";
+import { configStaticStage, publicDirStage, wellKnownStage } from "./core/http/stages/static.js";
+import { consoleLogger, renderLogEvent } from "./helpers/serverLog.js";
+import { SCOPES, authFailureMessage, createTokens, userIdOf } from "./core/auth/tokens.js";
+import { createCarriers, presentedOrigin } from "./core/auth/credentials.js";
+import { ANY_DOMAIN, corsOrigins, domainAllowed, frameAncestors, hostnameOf, normalizeDomain } from "./core/auth/domains.js";
+import { createIdentity } from "./core/auth/identity.js";
+import { checkPermission, checkSpaceAccess, createAuthorizer, requirementFor } from "./core/auth/authorize.js";
+import { createAuthApi } from "./core/auth/api.js";
+import { applySessionOutcome, authPolicyRules, authRoutes } from "./core/auth/routes.js";
+import { createAuth } from "./core/auth/createAuth.js";
+import { createSpaceTokenApi } from "./core/auth/spaceTokens.js";
+import { OAuthFailure } from "./core/auth/oauth/types.js";
+import { requestProfileJson } from "./core/auth/oauth/client.js";
+import { BUILT_IN_PROVIDERS, createSocialAuth } from "./core/auth/oauth/index.js";
+export { ANY_DOMAIN, BUILT_IN_PROVIDERS, OAuthFailure, PREVIEW_TOKEN_PARAM, SCOPES, applySessionOutcome, authFailureMessage, authPolicyRules, authRoutes, buildHealthPayload, checkPermission, checkSpaceAccess, clearFlowCookie, clearSessionCookies, clientIp, configStaticStage, consoleLogger, corsOrigins, createAuth, createAuthApi, createAuthorizer, createCarriers, createHttpServer, createIdentity, createSessionCookies, createSocialAuth, createSpaceTokenApi, createTokens, domainAllowed, frameAncestors, healthStage, hostnameOf, isLocalHost, makeHandler, normalizeDomain, parseRequest, presentedOrigin, publicDirStage, readFlowCookie, readRawBody, readRefreshToken, readSessionToken, registerHealthCheck, renderLogEvent, requestOrigin, requestProfileJson, requirementFor, sessionCookieParams, sessionHintValue, userIdOf, wellKnownStage, writeFlowCookie, writeSessionCookies };

package/dist/middlewares/spaceDeployment.d.ts

@@ -0,0 +1,2 @@
+import { SSRMiddleware, SSRPageAdapters } from '@plitzi/sdk-shared';
+export declare const spaceDeploymentMiddleware: (adapters: SSRPageAdapters) => SSRMiddleware;

package/dist/middlewares/spaceDeployment.js

@@ -3,12 +3,13 @@ var spaceDeploymentMiddleware = (adapters) => {
 	return async (req, res, next) => {
 		const deployment = await adapters.getSpaceDeployment(req);
 		req.ctx.spaceDeployment = deployment;
-		const { spaceId, error } = deployment;
+		const { spaceId, error, frameAncestors } = deployment;
 		if (spaceId == null || error) {
 			res.setStatus(error?.code ?? 404);
 			res.send(error?.message ?? "Space not found");
 			return;
 		}
+		if (frameAncestors && frameAncestors.length > 0) res.setHeader("Content-Security-Policy", `frame-ancestors ${frameAncestors.join(" ")}`);
 		await next();
 	};
 };

package/dist/modules/actions/handler.d.ts

@@ -0,0 +1,11 @@
+import { ConnectorLookups } from '../connectors/resolver';
+import { SSRPageServerConfig, SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+/**
+ * Handles POST /_action — the write counterpart of the RSC read endpoint.
+ *
+ * The browser names an **element**, never a connector or a URL. The element must exist in the published schema,
+ * be server-driven and declare a connector, and the connector must declare the action. That chain is what stops
+ * the endpoint from being a general-purpose proxy into the customer's backend: nothing reachable here is
+ * reachable that the page itself does not already do.
+ */
+export declare const handleAction: (req: SSRRequest, res: SSRResponseHelpers, config: SSRPageServerConfig, lookups: ConnectorLookups) => Promise<void>;

package/dist/modules/actions/handler.js

@@ -0,0 +1,77 @@
+import { writeConnectorRecord } from "../connectors/engine.js";
+//#region src/modules/actions/handler.ts
+var parseBody = (body) => {
+	if (!body) return;
+	try {
+		const parsed = JSON.parse(body);
+		return parsed !== null && typeof parsed === "object" ? parsed : void 0;
+	} catch {
+		return;
+	}
+};
+var fail = (res, status, error) => {
+	res.setStatus(status);
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	res.send(JSON.stringify({ error }));
+};
+/**
+* Handles POST /_action — the write counterpart of the RSC read endpoint.
+*
+* The browser names an **element**, never a connector or a URL. The element must exist in the published schema,
+* be server-driven and declare a connector, and the connector must declare the action. That chain is what stops
+* the endpoint from being a general-purpose proxy into the customer's backend: nothing reachable here is
+* reachable that the page itself does not already do.
+*/
+var handleAction = async (req, res, config, lookups) => {
+	const { environment = "main", spaceId, revision = 0 } = req.ctx.spaceDeployment ?? {};
+	if (typeof spaceId !== "number") {
+		fail(res, 400, "Invalid space deployment");
+		return;
+	}
+	const body = parseBody(req.body);
+	const action = body?.action;
+	if (!body?.elementId || !action) {
+		fail(res, 400, "Expected { elementId, action, values }");
+		return;
+	}
+	const element = (await config.adapters.getOfflineData(spaceId, environment, revision))?.schema.flat[body.elementId];
+	if (!element || element.definition.runtime !== "server") {
+		fail(res, 404, "Unknown provider element");
+		return;
+	}
+	const { connector: connectorId, resource } = element.attributes;
+	if (!connectorId) {
+		fail(res, 400, "Element has no connector");
+		return;
+	}
+	const manifest = await lookups.getConnector(spaceId, connectorId);
+	if (!manifest) {
+		fail(res, 404, "Unknown connector");
+		return;
+	}
+	if (!manifest.endpoints.write?.[action]) {
+		fail(res, 405, `Connector does not allow "${action}"`);
+		return;
+	}
+	const credential = manifest.credential && lookups.getCredential ? await lookups.getCredential(spaceId, manifest.credential) : void 0;
+	try {
+		const record = await writeConnectorRecord({
+			manifest,
+			credential,
+			action,
+			resource,
+			recordId: body.recordId,
+			values: body.values,
+			fetchImpl: lookups.fetchImpl
+		});
+		res.setStatus(200);
+		res.setHeader("Content-Type", "application/json; charset=utf-8");
+		res.setHeader("Cache-Control", "no-store");
+		res.send(JSON.stringify({ record: record ?? null }));
+	} catch (err) {
+		console.error("[Action] connector write failed:", err);
+		fail(res, 502, "Connector write failed");
+	}
+};
+//#endregion
+export { handleAction };

package/dist/modules/connectors/engine.d.ts

@@ -0,0 +1,42 @@
+import { ConnectorCredential, ConnectorManifest, ConnectorQuery, ConnectorRecord, ConnectorResult } from './types';
+export type FetchConnectorOptions = {
+    manifest: ConnectorManifest;
+    /** Which read endpoint to execute. Defaults to `list`, the one an element addresses when it names none. */
+    endpoint?: string;
+    credential?: ConnectorCredential;
+    query?: ConnectorQuery;
+    /** Injected so tests — and a future edge runtime — can supply their own transport. */
+    fetchImpl?: typeof fetch;
+};
+export type WriteConnectorOptions = {
+    manifest: ConnectorManifest;
+    credential?: ConnectorCredential;
+    /** Name of the write endpoint to execute, as declared in the manifest. */
+    action: string;
+    resource?: string;
+    recordId?: string;
+    values?: Record<string, unknown>;
+    fetchImpl?: typeof fetch;
+};
+/**
+ * Rebases the relative media paths a CMS returns (`/uploads/cover.jpg`) onto the manifest's media host.
+ *
+ * The rule is keyed on the property name, not on the value: a body field whose text happens to start with a slash
+ * must never be rewritten, and only a name ending in `url`, `src` or `href` claims to hold a location. Protocol
+ * relative values are already absolute enough and are left alone.
+ */
+export declare const rebaseMedia: (value: unknown, baseUrl: string) => unknown;
+/**
+ * Executes one connector read and normalizes the response into records + page info.
+ *
+ * Everything provider-specific — the endpoint, the auth header, where the array lives, how paging is expressed —
+ * comes from the manifest, so a new CMS is configuration rather than code.
+ */
+export declare const fetchConnectorRecords: ({ manifest, endpoint, credential, query, fetchImpl }: FetchConnectorOptions) => Promise<ConnectorResult>;
+/**
+ * Executes one connector write.
+ *
+ * An action the manifest does not declare is refused rather than inferred: a connector is read-only until its
+ * owner says otherwise, so a form can never reach a provider that was never meant to be written to.
+ */
+export declare const writeConnectorRecord: ({ manifest, credential, action, resource, recordId, values, fetchImpl }: WriteConnectorOptions) => Promise<ConnectorRecord | undefined>;

package/dist/modules/connectors/engine.js

@@ -0,0 +1,221 @@
+import { getByPath } from "./getByPath.js";
+import { BODYLESS_METHODS, DEFAULT_READ_ENDPOINT, EMPTY_RESPONSE_METHODS } from "@plitzi/sdk-shared/connectors";
+import { processTwig } from "@plitzi/sdk-shared/helpers/twigWrapper";
+//#region src/modules/connectors/engine.ts
+var DEFAULT_LIMIT = 10;
+/** Only scalars can become a URL fragment, a header or a record key. Anything else is treated as absent. */
+var toScalar = (value) => {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+};
+var render = (template, variables) => toScalar(processTwig(template, variables)) ?? "";
+var renderEntries = (entries, variables) => Object.entries(entries).reduce((acum, [key, template]) => {
+	const value = render(template, variables);
+	if (value !== "" && !value.includes("{{")) acum[key] = value;
+	return acum;
+}, {});
+var isTemplate = (value) => typeof value === "string" && value.includes("{{");
+/**
+* Resolves a filter's own field and value before the operator template ever sees them.
+*
+* A detail page filters on `{{routeParams.slug}}`; without this pass that token reaches the CMS verbatim and the
+* page matches nothing — or worse, the token is dropped and the query returns the whole collection, so an
+* arbitrary record renders at a URL that addressed a specific one.
+*
+* `unresolved` reports a template that produced nothing. The caller answers with an empty result rather than a
+* broader query: a page that cannot identify its record has no record, and that is a 404, not a different post.
+*/
+var resolveFilters = (filters, variables) => filters.reduce((acum, filter) => {
+	const field = isTemplate(filter.field) ? render(filter.field, variables) : filter.field;
+	const value = isTemplate(filter.value) ? render(filter.value, variables) : filter.value;
+	if (!field || field.includes("{{") || value === "" || typeof value === "string" && value.includes("{{")) {
+		acum.unresolved = true;
+		return acum;
+	}
+	acum.resolved.push({
+		...filter,
+		field,
+		value
+	});
+	return acum;
+}, {
+	resolved: [],
+	unresolved: false
+});
+/** Turns a filter into `key=value` query entries through the manifest's operator templates. */
+var renderFilters = (filters, operators, variables) => filters.reduce((acum, filter) => {
+	const template = operators?.[filter.operator];
+	if (!template) return acum;
+	const rendered = render(template, {
+		...variables,
+		field: filter.field,
+		value: filter.value
+	});
+	const separator = rendered.indexOf("=");
+	if (separator === -1) return acum;
+	acum[rendered.slice(0, separator)] = rendered.slice(separator + 1);
+	return acum;
+}, {});
+/** A relative media path is only ever carried by a key that names a location. */
+var MEDIA_KEY = /(url|src|href)$/i;
+/**
+* Rebases the relative media paths a CMS returns (`/uploads/cover.jpg`) onto the manifest's media host.
+*
+* The rule is keyed on the property name, not on the value: a body field whose text happens to start with a slash
+* must never be rewritten, and only a name ending in `url`, `src` or `href` claims to hold a location. Protocol
+* relative values are already absolute enough and are left alone.
+*/
+var rebaseMedia = (value, baseUrl) => {
+	if (Array.isArray(value)) return value.map((item) => rebaseMedia(item, baseUrl));
+	if (value === null || typeof value !== "object") return value;
+	return Object.entries(value).reduce((acum, [key, item]) => {
+		if (typeof item === "string" && MEDIA_KEY.test(key) && item.startsWith("/") && !item.startsWith("//")) {
+			acum[key] = `${baseUrl.replace(/\/+$/, "")}${item}`;
+			return acum;
+		}
+		acum[key] = rebaseMedia(item, baseUrl);
+		return acum;
+	}, {});
+};
+/** Builds the outbound headers and, for query-carried schemes, mutates `url` with the auth parameter. */
+var applyAuth = (connection, variables, url) => {
+	const headers = renderEntries(connection.headers ?? {}, variables);
+	if (!connection.auth) return headers;
+	const value = render(connection.auth.value, variables);
+	if (connection.auth.in === "header") headers[connection.auth.name] = value;
+	else url.searchParams.set(connection.auth.name, value);
+	return headers;
+};
+var buildPageInfo = (records, total, offset, limit, nextCursor) => {
+	const to = offset + records.length;
+	const hasNextPage = total === void 0 ? records.length === limit : to < total;
+	return {
+		hasPrevPage: offset > 0,
+		hasNextPage,
+		prevCursor: "",
+		nextCursor: hasNextPage ? nextCursor : "",
+		from: offset,
+		to,
+		total: total ?? to,
+		page: Math.floor(offset / Math.max(limit, 1)) + 1,
+		pageCount: total === void 0 ? 0 : Math.ceil(total / Math.max(limit, 1))
+	};
+};
+/** The window a query addressed, when it is known before the provider is called (or instead of calling it). */
+var emptyResult = (offset, limit) => ({
+	records: [],
+	pageInfo: buildPageInfo([], 0, offset, limit, "")
+});
+var toRecords = (items, mapping) => items.reduce((acum, item, index) => {
+	if (item === null || typeof item !== "object") return acum;
+	const id = toScalar(getByPath(item, mapping.idPath ?? "id"));
+	const values = getByPath(item, mapping.valuesPath ?? ".");
+	acum.push({
+		id: id ?? String(index),
+		values: values !== null && typeof values === "object" ? values : {}
+	});
+	return acum;
+}, []);
+/**
+* Executes one connector read and normalizes the response into records + page info.
+*
+* Everything provider-specific — the endpoint, the auth header, where the array lives, how paging is expressed —
+* comes from the manifest, so a new CMS is configuration rather than code.
+*/
+var fetchConnectorRecords = async ({ manifest, endpoint = DEFAULT_READ_ENDPOINT, credential = {}, query = {}, fetchImpl = fetch }) => {
+	const { endpoints, ...connection } = manifest;
+	const read = Object.hasOwn(endpoints.read, endpoint) ? endpoints.read[endpoint] : void 0;
+	if (!read) throw new Error(`Connector ${connection.id} has no read endpoint named "${endpoint}"`);
+	const limit = query.limit ?? DEFAULT_LIMIT;
+	const offset = query.offset ?? 0;
+	const variables = {
+		credential,
+		resource: query.resource ?? "",
+		limit,
+		offset,
+		page: query.page ?? Math.floor(offset / limit) + 1,
+		cursor: query.cursor ?? "",
+		routeParams: query.routeParams ?? {},
+		queryParams: query.queryParams ?? {},
+		params: {
+			...query.queryParams,
+			...query.routeParams
+		}
+	};
+	const { resolved, unresolved } = resolveFilters(query.filters ?? [], variables);
+	if (unresolved) return emptyResult(offset, limit);
+	const url = new URL(render(read.path, variables), connection.baseUrl);
+	Object.entries({
+		...renderEntries(read.query ?? {}, variables),
+		...renderFilters(resolved, connection.operators, variables)
+	}).forEach(([key, value]) => url.searchParams.set(key, value));
+	const method = read.method ?? "GET";
+	const headers = {
+		...applyAuth(connection, variables, url),
+		...renderEntries(read.headers ?? {}, variables)
+	};
+	const sendsBody = !BODYLESS_METHODS.includes(method);
+	if (sendsBody) headers["Content-Type"] = "application/json";
+	const response = await fetchImpl(url.toString(), {
+		method,
+		headers,
+		body: sendsBody ? JSON.stringify(renderEntries(read.body ?? {}, variables)) : void 0
+	});
+	if (!response.ok) throw new Error(`Connector ${connection.id} responded ${response.status} for ${url.pathname}`);
+	const payload = await response.json();
+	const rawItems = getByPath(payload, read.itemsPath);
+	const items = Array.isArray(rawItems) ? rawItems : [];
+	const rawTotal = read.totalPath ? getByPath(payload, read.totalPath) : void 0;
+	const total = typeof rawTotal === "number" ? rawTotal : void 0;
+	const mediaBaseUrl = connection.media?.baseUrl;
+	const records = toRecords(items, read).map((record) => mediaBaseUrl ? {
+		...record,
+		values: rebaseMedia(record.values, mediaBaseUrl)
+	} : record);
+	return {
+		records,
+		pageInfo: buildPageInfo(records, total, offset, limit, String(offset + records.length))
+	};
+};
+/** Nests the payload the way the provider expects it: `data` produces `{ data: values }`. */
+var wrapBody = (values, bodyPath) => {
+	if (!bodyPath || bodyPath === ".") return values;
+	return bodyPath.split(".").reduceRight((acum, key) => ({ [key]: acum }), values);
+};
+/**
+* Executes one connector write.
+*
+* An action the manifest does not declare is refused rather than inferred: a connector is read-only until its
+* owner says otherwise, so a form can never reach a provider that was never meant to be written to.
+*/
+var writeConnectorRecord = async ({ manifest, credential = {}, action, resource, recordId, values = {}, fetchImpl = fetch }) => {
+	const { endpoints, ...connection } = manifest;
+	const operation = endpoints.write?.[action];
+	if (!operation) throw new Error(`Connector ${connection.id} does not allow "${action}"`);
+	const variables = {
+		credential,
+		resource: resource ?? "",
+		id: recordId ?? "",
+		values
+	};
+	const url = new URL(render(operation.path, variables), connection.baseUrl);
+	Object.entries(renderEntries(operation.query ?? {}, variables)).forEach(([key, value]) => url.searchParams.set(key, value));
+	const headers = {
+		...applyAuth(connection, variables, url),
+		...renderEntries(operation.headers ?? {}, variables)
+	};
+	headers["Content-Type"] = "application/json";
+	const response = await fetchImpl(url.toString(), {
+		method: operation.method,
+		headers,
+		body: BODYLESS_METHODS.includes(operation.method) ? void 0 : JSON.stringify(wrapBody(values, operation.bodyPath))
+	});
+	if (!response.ok) throw new Error(`Connector ${connection.id} responded ${response.status} for ${action} on ${url.pathname}`);
+	if (EMPTY_RESPONSE_METHODS.includes(operation.method) || response.status === 204) return;
+	const mapping = operation.response ?? {};
+	const payload = await response.json();
+	const item = getByPath(payload, mapping.itemsPath === void 0 ? "." : mapping.itemsPath);
+	return toRecords(Array.isArray(item) ? item : [item], mapping)[0];
+};
+//#endregion
+export { fetchConnectorRecords, rebaseMedia, writeConnectorRecord };

package/dist/modules/connectors/getByPath.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reads a dot path out of an arbitrary JSON response (`data.items`, `meta.pagination.total`). Kept local and
+ * dependency-free on purpose: the equivalent helper in plitzi-ui would drag the UI bundle into the request path.
+ *
+ * A path of `.` or an empty path returns the value itself, which is how a manifest says "the response *is* the
+ * array" or "the record *is* its own values".
+ */
+export declare const getByPath: (source: unknown, path?: string) => unknown;