@plitzi/sdk-shared 0.32.25 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @plitzi/sdk-shared
 
+## 0.33.0
+
+### Minor Changes
+
+- v0.33.0
+
 ## 0.32.25
 
 ### Patch Changes

package/dist/auth/authFailureLink.d.ts

@@ -0,0 +1,9 @@
+import { ErrorLink } from '@apollo/client/link/error';
+/**
+ * Turns a GraphQL transport refusal into a session signal. A session dies at the server — revoked from another
+ * device, an account deactivated — and the client finds out from whichever request happens to be refused next. This
+ * is what makes that request count for something instead of surfacing as one failed query.
+ *
+ * Only transport-level refusals are read: a GraphQL error inside a 200 is the schema's business, not the session's.
+ */
+export declare const createAuthFailureLink: (uri?: string) => ErrorLink;

package/dist/auth/authFailureLink.mjs

@@ -0,0 +1,20 @@
+import { authFailureFromResponse as e, reportAuthFailure as t } from "./failureChannel.mjs";
+import { ServerError as n } from "@apollo/client";
+import { ErrorLink as r } from "@apollo/client/link/error";
+//#region src/auth/authFailureLink.ts
+var i = (e) => {
+	try {
+		return JSON.parse(e);
+	} catch {
+		return;
+	}
+}, a = (a) => new r(({ error: r }) => {
+	if (!n.is(r)) return;
+	let o = e(r.statusCode, i(r.bodyText));
+	o && t({
+		reason: o,
+		url: a
+	});
+});
+//#endregion
+export { a as createAuthFailureLink };

package/dist/auth/failureChannel.d.ts

@@ -0,0 +1,31 @@
+import { AuthFailureReason } from '../types';
+export type AuthFailureSignal = {
+    reason: AuthFailureReason;
+    /** The request that was refused. Auth listens only to refusals from its own backend — see `sameRegistrableDomain`. */
+    url?: string;
+};
+export type AuthFailureListener = (signal: AuthFailureSignal) => void;
+/**
+ * Says that a backend refused a credential. A session can end between two checks — revoked from another device, an
+ * account deactivated — and the first thing that notices is whatever request got refused, not a timer. Reporting it
+ * here is how the network layers tell auth that reality moved on, without either knowing about the other.
+ */
+export declare const reportAuthFailure: (signal: AuthFailureSignal) => void;
+export declare const onAuthFailure: (listener: AuthFailureListener) => (() => void);
+/**
+ * What an HTTP refusal means for the session. Stated once, because the provider and the network layers must not
+ * disagree about which refusals are renewable.
+ *
+ * A backend that names the reason (Plitzi's API answers `reason` on every 401) is believed. One that says nothing
+ * gets the benefit of the doubt — an unexplained 401 is treated as renewable, so a stale access token costs one
+ * refused renewal instead of signing out a session that was still good. Nothing below 401 or above 499 is an answer
+ * about the session at all: a 5xx means the backend failed, not that the caller is a stranger.
+ */
+export declare const authFailureFromResponse: (status: number, body?: unknown) => AuthFailureReason | undefined;
+/**
+ * Whether two URLs belong to the same site, by registrable domain rather than exact origin: a deployment spreads one
+ * auth universe over several hosts (`api.example.com`, `server.example.com`), and a refusal from any of them is about
+ * the same session. Across sites it is the opposite — a space that authenticates against its owner's backend must not
+ * lose its session because Plitzi's API refused something.
+ */
+export declare const sameRegistrableDomain: (a?: string, b?: string) => boolean;

package/dist/auth/failureChannel.mjs

@@ -0,0 +1,26 @@
+//#region src/auth/failureChannel.ts
+var e = /* @__PURE__ */ new Set(), t = (t) => {
+	for (let n of e) n(t);
+}, n = (t) => (e.add(t), () => e.delete(t)), r = [
+	"missing",
+	"expired",
+	"revoked",
+	"inactive",
+	"malformed",
+	"outdated",
+	"network"
+], i = (e, t) => {
+	if (e < 400 || e >= 500 || e !== 401 && e !== 403) return;
+	let n = t?.reason;
+	return typeof n == "string" && r.includes(n) ? n : e === 403 ? "inactive" : "expired";
+}, a = (e) => /([^.]+\.[^.]+)$/.exec(e)?.[1] ?? e, o = (e, t) => {
+	if (!e || !t) return !1;
+	try {
+		let n = typeof window > "u" ? void 0 : window.location.href;
+		return a(new URL(e, n).hostname) === a(new URL(t, n).hostname);
+	} catch {
+		return !1;
+	}
+};
+//#endregion
+export { i as authFailureFromResponse, n as onAuthFailure, t as reportAuthFailure, o as sameRegistrableDomain };

package/dist/auth/index.d.ts

@@ -0,0 +1,3 @@
+export { createAuthFailureLink } from './authFailureLink';
+export { authFailureFromResponse, onAuthFailure, reportAuthFailure, sameRegistrableDomain } from './failureChannel';
+export type { AuthFailureListener, AuthFailureSignal } from './failureChannel';

package/dist/auth/index.mjs

@@ -0,0 +1,3 @@
+import { authFailureFromResponse as e, onAuthFailure as t, reportAuthFailure as n, sameRegistrableDomain as r } from "./failureChannel.mjs";
+import { createAuthFailureLink as i } from "./authFailureLink.mjs";
+export { e as authFailureFromResponse, i as createAuthFailureLink, t as onAuthFailure, n as reportAuthFailure, r as sameRegistrableDomain };

package/dist/connectors/constants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Values shared by the builder and the engine.
+ *
+ * They live here rather than beside the manifest types because they are values, not types: importing them from the
+ * package barrel would pull the whole barrel — and plitzi-ui with it — into the server process.
+ */
+/** The read endpoint an element addresses when it names none. */
+export declare const DEFAULT_READ_ENDPOINT = "list";
+/** The HTTP vocabulary a connector can use. A declarative REST client has no business narrowing it further. */
+export declare const CONNECTOR_HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+/**
+ * Methods that carry no request body.
+ *
+ * `DELETE` is here because sending a body with one is legal but widely mishandled by servers and proxies; a
+ * connector that needs to identify what to delete says so through the path or the query string instead.
+ */
+export declare const BODYLESS_METHODS: readonly string[];
+/** Methods that return nothing worth mapping, so a write using one resolves to no record. */
+export declare const EMPTY_RESPONSE_METHODS: readonly string[];
+/**
+ * Names offered to a new endpoint, in order.
+ *
+ * A connector's second read is far more often a single-record fetch than anything else, and its third a search —
+ * so the panel suggests the name the author was going to type. Past the list it falls back to a numbered name
+ * rather than inventing vocabulary nobody asked for.
+ */
+export declare const READ_ENDPOINT_NAMES: readonly ["list", "detail", "search"];
+export declare const WRITE_ENDPOINT_NAMES: readonly ["create", "update", "delete"];

package/dist/connectors/constants.mjs

@@ -0,0 +1,29 @@
+//#region src/connectors/constants.ts
+var e = "list", t = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+], n = [
+	"GET",
+	"HEAD",
+	"OPTIONS",
+	"DELETE"
+], r = [
+	"HEAD",
+	"OPTIONS",
+	"DELETE"
+], i = [
+	"list",
+	"detail",
+	"search"
+], a = [
+	"create",
+	"update",
+	"delete"
+];
+//#endregion
+export { n as BODYLESS_METHODS, t as CONNECTOR_HTTP_METHODS, e as DEFAULT_READ_ENDPOINT, r as EMPTY_RESPONSE_METHODS, i as READ_ENDPOINT_NAMES, a as WRITE_ENDPOINT_NAMES };

package/dist/connectors/index.d.ts

@@ -0,0 +1,7 @@
+export { BODYLESS_METHODS, CONNECTOR_HTTP_METHODS, DEFAULT_READ_ENDPOINT, EMPTY_RESPONSE_METHODS, READ_ENDPOINT_NAMES, WRITE_ENDPOINT_NAMES } from './constants';
+export { connectorTokens, getConnectorTokens } from './manifestTokens';
+export { connectorPresets, emptyManifest } from './presets';
+export { validateConnectorManifest } from './validateManifest';
+export type { ConnectorPreset } from './presets';
+export type { ConnectorToken, ConnectorTokenScope } from './manifestTokens';
+export type { ConnectorManifestIssue, ConnectorManifestReport } from './validateManifest';

package/dist/connectors/index.mjs

@@ -0,0 +1,5 @@
+import { BODYLESS_METHODS as e, CONNECTOR_HTTP_METHODS as t, DEFAULT_READ_ENDPOINT as n, EMPTY_RESPONSE_METHODS as r, READ_ENDPOINT_NAMES as i, WRITE_ENDPOINT_NAMES as a } from "./constants.mjs";
+import { connectorTokens as o, getConnectorTokens as s } from "./manifestTokens.mjs";
+import { connectorPresets as c, emptyManifest as l } from "./presets.mjs";
+import { validateConnectorManifest as u } from "./validateManifest.mjs";
+export { e as BODYLESS_METHODS, t as CONNECTOR_HTTP_METHODS, n as DEFAULT_READ_ENDPOINT, r as EMPTY_RESPONSE_METHODS, i as READ_ENDPOINT_NAMES, a as WRITE_ENDPOINT_NAMES, c as connectorPresets, o as connectorTokens, l as emptyManifest, s as getConnectorTokens, u as validateConnectorManifest };

package/dist/connectors/manifestTokens.d.ts

@@ -0,0 +1,17 @@
+export type ConnectorTokenScope = 'request' | 'filter' | 'write';
+export type ConnectorToken = {
+    /** Written into a template as `{{value}}`. A trailing `.` marks a namespace whose keys the author names. */
+    value: string;
+    description: string;
+    scopes: ConnectorTokenScope[];
+};
+/**
+ * Every variable the engine binds when it renders a manifest template.
+ *
+ * This is the engine's contract stated once, so the builder can offer it as completions instead of asking authors
+ * to learn it from a preset. A token missing here is a token the author cannot discover — keep it in step with the
+ * `variables` maps in `fetchConnectorRecords` and `writeConnectorRecord`.
+ */
+export declare const connectorTokens: ConnectorToken[];
+export declare const getConnectorTokens: (scope: ConnectorTokenScope) => ConnectorToken[];
+export default connectorTokens;

package/dist/connectors/manifestTokens.mjs

@@ -0,0 +1,70 @@
+//#region src/connectors/manifestTokens.ts
+var e = [
+	{
+		value: "resource",
+		description: "Content type the element asked for, e.g. the \"articles\" in /api/articles.",
+		scopes: ["request", "write"]
+	},
+	{
+		value: "limit",
+		description: "Page size the element asked for.",
+		scopes: ["request"]
+	},
+	{
+		value: "offset",
+		description: "Records to skip. Zero-based; use it for offset paging.",
+		scopes: ["request"]
+	},
+	{
+		value: "page",
+		description: "Page number. One-based; use it for page paging.",
+		scopes: ["request"]
+	},
+	{
+		value: "cursor",
+		description: "Token the previous response returned. Use it for cursor paging.",
+		scopes: ["request"]
+	},
+	{
+		value: "credential.",
+		description: "A key from the credential this connector resolves, e.g. credential.token.",
+		scopes: ["request", "write"]
+	},
+	{
+		value: "routeParams.",
+		description: "A parameter from the page URL, e.g. routeParams.slug for /blog/:slug.",
+		scopes: ["request", "filter"]
+	},
+	{
+		value: "queryParams.",
+		description: "A parameter from the query string, e.g. queryParams.tag for ?tag=news.",
+		scopes: ["request", "filter"]
+	},
+	{
+		value: "params.",
+		description: "Route and query parameters merged, route winning. Handy when either may carry the value.",
+		scopes: ["request", "filter"]
+	},
+	{
+		value: "field",
+		description: "The field a filter targets. Only inside an operator template.",
+		scopes: ["filter"]
+	},
+	{
+		value: "value",
+		description: "The value a filter compares. Only inside an operator template.",
+		scopes: ["filter"]
+	},
+	{
+		value: "id",
+		description: "The record being written to. Only inside a write path.",
+		scopes: ["write"]
+	},
+	{
+		value: "values.",
+		description: "A field of the record being written.",
+		scopes: ["write"]
+	}
+], t = (t) => e.filter((e) => e.scopes.includes(t));
+//#endregion
+export { e as connectorTokens, e as default, t as getConnectorTokens };

package/dist/connectors/presets.d.ts

@@ -0,0 +1,22 @@
+import { ConnectorManifestDraft } from '../types/ConnectorTypes';
+/**
+ * Starting manifests for the APIs people actually run.
+ *
+ * A connector is a declarative REST client, so the presets cover both ends of what that means: the CMSs whose
+ * response shapes are worth remembering, and a plain REST service for everything else. Every field stays editable
+ * — a preset that goes stale because a vendor changed a response shape is fixed by editing a row, never by
+ * shipping a release, which is the entire reason connectors are data.
+ *
+ * They live in shared code because both authors read them: the builder panel offers them as a starting point, and
+ * an agent writing a connector through the MCP reads them as the worked examples of how a real provider expresses
+ * paging, filters and its response shape. One copy, so neither learns a shape the other has since fixed.
+ */
+export type ConnectorPreset = {
+    id: string;
+    label: string;
+    /** What the connector needs from its credential, so the panel can say which keys to fill in. */
+    credentialKeys: string[];
+    manifest: ConnectorManifestDraft;
+};
+export declare const connectorPresets: ConnectorPreset[];
+export declare const emptyManifest: ConnectorManifestDraft;

package/dist/connectors/presets.mjs

@@ -0,0 +1,220 @@
+//#region src/connectors/presets.ts
+var e = {
+	id: "blank",
+	label: "Blank",
+	credentialKeys: [],
+	manifest: {
+		baseUrl: "",
+		endpoints: { read: { list: {
+			path: "/{{resource}}",
+			idPath: "id"
+		} } },
+		pagination: "offset",
+		operators: { eq: "{{field}}={{value}}" }
+	}
+}, t = [
+	e,
+	{
+		id: "rest",
+		label: "REST API",
+		credentialKeys: ["token"],
+		manifest: {
+			baseUrl: "https://api.example.com",
+			auth: {
+				in: "header",
+				name: "Authorization",
+				value: "Bearer {{credential.token}}"
+			},
+			endpoints: {
+				read: {
+					list: {
+						path: "/{{resource}}",
+						query: {
+							limit: "{{limit}}",
+							offset: "{{offset}}"
+						},
+						idPath: "id"
+					},
+					detail: {
+						path: "/{{resource}}/{{routeParams.id}}",
+						idPath: "id"
+					}
+				},
+				write: {
+					create: {
+						method: "POST",
+						path: "/{{resource}}"
+					},
+					update: {
+						method: "PUT",
+						path: "/{{resource}}/{{id}}"
+					},
+					delete: {
+						method: "DELETE",
+						path: "/{{resource}}/{{id}}"
+					}
+				}
+			},
+			pagination: "offset",
+			operators: { eq: "{{field}}={{value}}" }
+		}
+	},
+	{
+		id: "strapi",
+		label: "Strapi v5",
+		credentialKeys: ["token"],
+		manifest: {
+			baseUrl: "https://cms.example.com",
+			auth: {
+				in: "header",
+				name: "Authorization",
+				value: "Bearer {{credential.token}}"
+			},
+			endpoints: {
+				read: { list: {
+					path: "/api/{{resource}}",
+					query: {
+						"pagination[start]": "{{offset}}",
+						"pagination[limit]": "{{limit}}",
+						populate: "*"
+					},
+					itemsPath: "data",
+					totalPath: "meta.pagination.total",
+					idPath: "documentId",
+					valuesPath: "."
+				} },
+				write: {
+					create: {
+						method: "POST",
+						path: "/api/{{resource}}",
+						bodyPath: "data",
+						response: {
+							itemsPath: "data",
+							idPath: "documentId"
+						}
+					},
+					update: {
+						method: "PUT",
+						path: "/api/{{resource}}/{{id}}",
+						bodyPath: "data",
+						response: {
+							itemsPath: "data",
+							idPath: "documentId"
+						}
+					},
+					delete: {
+						method: "DELETE",
+						path: "/api/{{resource}}/{{id}}"
+					}
+				}
+			},
+			pagination: "offset",
+			operators: {
+				eq: "filters[{{field}}][$eq]={{value}}",
+				ne: "filters[{{field}}][$ne]={{value}}",
+				contains: "filters[{{field}}][$containsi]={{value}}",
+				gt: "filters[{{field}}][$gt]={{value}}",
+				lt: "filters[{{field}}][$lt]={{value}}"
+			},
+			media: { baseUrl: "https://cms.example.com" }
+		}
+	},
+	{
+		id: "wordpress",
+		label: "WordPress (REST)",
+		credentialKeys: [],
+		manifest: {
+			baseUrl: "https://blog.example.com",
+			endpoints: { read: { list: {
+				path: "/wp-json/wp/v2/{{resource}}",
+				query: {
+					per_page: "{{limit}}",
+					page: "{{page}}"
+				},
+				idPath: "id"
+			} } },
+			pagination: "page",
+			operators: {
+				eq: "{{field}}={{value}}",
+				contains: "search={{value}}"
+			}
+		}
+	},
+	{
+		id: "directus",
+		label: "Directus",
+		credentialKeys: ["token"],
+		manifest: {
+			baseUrl: "https://cms.example.com",
+			auth: {
+				in: "header",
+				name: "Authorization",
+				value: "Bearer {{credential.token}}"
+			},
+			endpoints: {
+				read: { list: {
+					path: "/items/{{resource}}",
+					query: {
+						offset: "{{offset}}",
+						limit: "{{limit}}",
+						meta: "filter_count"
+					},
+					itemsPath: "data",
+					totalPath: "meta.filter_count",
+					idPath: "id"
+				} },
+				write: {
+					create: {
+						method: "POST",
+						path: "/items/{{resource}}",
+						response: { itemsPath: "data" }
+					},
+					update: {
+						method: "PATCH",
+						path: "/items/{{resource}}/{{id}}",
+						response: { itemsPath: "data" }
+					},
+					delete: {
+						method: "DELETE",
+						path: "/items/{{resource}}/{{id}}"
+					}
+				}
+			},
+			pagination: "offset",
+			operators: {
+				eq: "filter[{{field}}][_eq]={{value}}",
+				ne: "filter[{{field}}][_neq]={{value}}",
+				contains: "filter[{{field}}][_contains]={{value}}"
+			},
+			media: { baseUrl: "https://cms.example.com/assets" }
+		}
+	},
+	{
+		id: "contentful",
+		label: "Contentful (CDA)",
+		credentialKeys: ["token", "spaceId"],
+		manifest: {
+			baseUrl: "https://cdn.contentful.com",
+			endpoints: { read: { list: {
+				path: "/spaces/{{credential.spaceId}}/environments/master/entries",
+				query: {
+					access_token: "{{credential.token}}",
+					content_type: "{{resource}}",
+					skip: "{{offset}}",
+					limit: "{{limit}}"
+				},
+				itemsPath: "items",
+				totalPath: "total",
+				idPath: "sys.id",
+				valuesPath: "fields"
+			} } },
+			pagination: "offset",
+			operators: {
+				eq: "fields.{{field}}={{value}}",
+				contains: "fields.{{field}}[match]={{value}}"
+			}
+		}
+	}
+], n = e.manifest;
+//#endregion
+export { t as connectorPresets, n as emptyManifest };

package/dist/connectors/validateManifest.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The one connector-manifest validator.
+ *
+ * Three places decide whether a manifest is fit to store — the builder panel, the MCP write ops and the GraphQL
+ * mutation that persists it — and a manifest is only ever wrong in one way, so the rules live here rather than
+ * being restated (and drifting) at each entry point. The server runs it last, on whatever JSON actually arrived,
+ * which is why the input is `unknown`: it validates a document, it does not assume one.
+ *
+ * Errors are what the engine cannot recover from at request time; warnings are what will work but probably does
+ * not do what the author meant. Nothing here reaches the network — it is a pure inspection of the document.
+ */
+export type ConnectorManifestIssue = {
+    /** Dotted path into the manifest, e.g. `endpoints.read.list.path`. */
+    path: string;
+    message: string;
+    hint?: string;
+};
+export type ConnectorManifestReport = {
+    valid: boolean;
+    errors: ConnectorManifestIssue[];
+    warnings: ConnectorManifestIssue[];
+};
+/**
+ * Validates a connector manifest document (a `ConnectorManifestDraft`; a stored `id` is ignored).
+ *
+ * Give it whatever you have — parsed JSON, an editor's working copy, a GraphQL argument. It never throws.
+ */
+export declare const validateConnectorManifest: (input: unknown) => ConnectorManifestReport;