@declarion/embed 0.1.92

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Stable, machine-readable embed error codes. A host may branch on
+ * `error.code`; the strings are part of the public contract.
+ */
+export declare const EMBED_ERROR_CODES: {
+    /**
+     * A required `createDeclarionEmbed` option is missing or malformed
+     * (`container`, `declarionOrigin`, `route`, `getToken`). Raised
+     * synchronously before the iframe is created.
+     */
+    readonly invalidOptions: "invalid-options";
+    /**
+     * The host's `getToken` callback rejected, threw, or resolved to a value
+     * that is not `{ token: string, expires_at: string }`.
+     */
+    readonly getTokenFailed: "get-token-failed";
+    /**
+     * No `ready` frame arrived from the iframe within the post-mount timeout.
+     * The usual causes are a `declarionOrigin` mismatch (the iframe loaded a
+     * different origin, or never loaded) or framing denied by the Declarion CSP
+     * (the host origin is not in `DECLARION_FRAME_ANCESTORS`). A slow `getToken`
+     * does NOT cause this - the timer is cleared as soon as `ready` arrives.
+     */
+    readonly handshakeTimeout: "handshake-timeout";
+    /**
+     * The iframe asked the host to reload it (`reload-required`) - asset drift
+     * or a terminal auth failure inside the iframe.
+     */
+    readonly reloadRequired: "reload-required";
+};
+/** The union of all embed error code strings. */
+export type EmbedErrorCode = (typeof EMBED_ERROR_CODES)[keyof typeof EMBED_ERROR_CODES];
+/**
+ * A typed embed error. Always passed to the host `onError` callback and
+ * always also written to `console.error` with the `[declarion-embed]`
+ * prefix, so a misconfiguration is never silent.
+ *
+ * `cause` carries the originating error when one exists (e.g. the rejection
+ * value from `getToken`), preserving the stack for debugging.
+ */
+export declare class EmbedError extends Error {
+    /** The stable, machine-readable error code. */
+    readonly code: EmbedErrorCode;
+    constructor(code: EmbedErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/inbound.d.ts

@@ -0,0 +1,29 @@
+import { type EmbedMessage } from "./protocol";
+/**
+ * The classification of an inbound `message` event after validation.
+ *
+ * - `valid`: a trusted, shape-correct, version-matched embed frame.
+ * - `protocol-mismatch`: origin + source are trusted, but the `protocol`
+ *   version differs. The caller logs a warning; the frame is not acted on.
+ * - `rejected`: not a trusted embed frame (wrong origin, missing/foreign
+ *   `source`, malformed envelope). The caller drops it silently.
+ */
+export type InboundClassification = {
+    kind: "valid";
+    message: EmbedMessage;
+} | {
+    kind: "protocol-mismatch";
+    received: unknown;
+} | {
+    kind: "rejected";
+};
+/**
+ * Validate and classify an inbound `message` event against the trusted
+ * `declarionOrigin`.
+ *
+ * Returns `rejected` for anything that is not a trusted embed frame - the
+ * caller drops those with no logging. Returns `protocol-mismatch` when the
+ * frame is trusted but on a different protocol version. Returns `valid` with
+ * the typed envelope otherwise.
+ */
+export declare function classifyInboundMessage(event: MessageEvent, declarionOrigin: string): InboundClassification;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createDeclarionEmbed } from "./core";
+export type { DeclarionEmbedOptions, DeclarionEmbedHandle, EmbedNavigationContract, EmbedNavigateEvent, EmbedEvent, EmbedToken, EmbedGetToken, EmbedTheme, } from "./types";
+export { EmbedError, EMBED_ERROR_CODES } from "./errors";
+export type { EmbedErrorCode } from "./errors";
+export { EMBED_MESSAGE_SOURCE, EMBED_MESSAGE_TYPES, EMBED_PROTOCOL_VERSION, } from "./protocol";
+export type { EmbedMessage, EmbedMessageType, EmbedMessagePayloadMap, EmbedReadyPayload, EmbedSetTokenPayload, EmbedTokenExpiredPayload, EmbedReloadRequiredPayload, EmbedResizedPayload, EmbedNavigationPayload, EmbedDirtyChangedPayload, EmbedNavigatePayload, EmbedSetThemePayload, } from "./protocol";

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as e, i as t, n, o as r, r as i, t as a } from "./core.js";
+export { n as EMBED_ERROR_CODES, t as EMBED_MESSAGE_SOURCE, e as EMBED_MESSAGE_TYPES, r as EMBED_PROTOCOL_VERSION, i as EmbedError, a as createDeclarionEmbed };

package/dist/protocol.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The `source` discriminator stamped on every embed frame. Both the host SDK
+ * and the iframe filter inbound traffic on this value so unrelated
+ * `postMessage` frames (browser extensions, other widgets) are ignored.
+ */
+export declare const EMBED_MESSAGE_SOURCE: "declarion-embed";
+/**
+ * The protocol version this SDK speaks. Bumped only on a breaking
+ * envelope/payload change. The SDK warns when the iframe reports a different
+ * version (see the diagnostics path).
+ */
+export declare const EMBED_PROTOCOL_VERSION: 1;
+/**
+ * Every protocol message `type`. The object key is the camelCase name used in
+ * code; the value is the on-wire string. Events (iframe -> host) are past
+ * tense; commands (host -> iframe) are imperative. This SDK is the HOST side:
+ * it RECEIVES the iframe-to-host events and SENDS the host-to-iframe commands.
+ */
+export declare const EMBED_MESSAGE_TYPES: {
+    /** iframe -> host: SDK mounted, requests the first token. */
+    readonly ready: "ready";
+    /** host -> iframe: deliver or refresh the embed token. */
+    readonly setToken: "set-token";
+    /** iframe -> host: token rejected or near expiry. */
+    readonly tokenExpired: "token-expired";
+    /** iframe -> host: the iframe must be reloaded. */
+    readonly reloadRequired: "reload-required";
+    /** iframe -> host: embed content height changed. */
+    readonly resized: "resized";
+    /** iframe -> host: `self` mode internal navigation happened. */
+    readonly navigated: "navigated";
+    /** iframe -> host: `delegated` mode navigation requested, iframe stayed. */
+    readonly navigationRequested: "navigation-requested";
+    /** iframe -> host: the embedded screen's unsaved-edits state flipped. */
+    readonly dirtyChanged: "dirty-changed";
+    /** host -> iframe: drive the iframe to a screen (deep-linking). */
+    readonly navigate: "navigate";
+    /** host -> iframe: runtime theme switch. */
+    readonly setTheme: "set-theme";
+};
+/** The union of all on-wire message `type` strings. */
+export type EmbedMessageType = (typeof EMBED_MESSAGE_TYPES)[keyof typeof EMBED_MESSAGE_TYPES];
+/** `ready` payload: empty - the frame itself is the signal. */
+export type EmbedReadyPayload = Record<string, never>;
+/** `set-token` payload: the embed token and its absolute expiry. */
+export interface EmbedSetTokenPayload {
+    /** The scoped, refresh-less embed JWT. */
+    readonly token: string;
+    /** RFC 3339 expiry timestamp of the token. */
+    readonly expires_at: string;
+}
+/** `token-expired` payload: empty - the host re-mints via `getToken`. */
+export type EmbedTokenExpiredPayload = Record<string, never>;
+/** `reload-required` payload: a human-readable reason for the reload. */
+export interface EmbedReloadRequiredPayload {
+    /** Why the iframe must be reloaded (asset drift, terminal auth failure). */
+    readonly reason: string;
+}
+/** `resized` payload: the measured content height in CSS pixels. */
+export interface EmbedResizedPayload {
+    /** Content height in CSS pixels. */
+    readonly height: number;
+}
+/**
+ * `navigated` / `navigation-requested` payload: the screen route and, when
+ * resolvable, the bound entity code and record id.
+ *
+ * `entity` and `recordId` are optional: a `custom` screen has no entity, and
+ * a list route has no record id.
+ */
+export interface EmbedNavigationPayload {
+    /** The Declarion screen route path the navigation targets. */
+    readonly route: string;
+    /** The bound entity code, when the route resolves to one. */
+    readonly entity?: string;
+    /** The record id, when the route is a detail route with an id. */
+    readonly recordId?: string;
+}
+/**
+ * `dirty-changed` payload: whether the embedded screen currently has unsaved
+ * edits. The host tracks this so it can guard its own navigation (its menu,
+ * a host-initiated `navigate`) before moving the iframe away from a dirty
+ * screen - the iframe never pops a dialog for host-driven navigation.
+ */
+export interface EmbedDirtyChangedPayload {
+    /** True when the embedded screen has unsaved edits. */
+    readonly dirty: boolean;
+}
+/** `navigate` payload: the route the host drives the iframe to. */
+export interface EmbedNavigatePayload {
+    /** The Declarion screen route the host wants opened. */
+    readonly route: string;
+}
+/** `set-theme` payload: the theme the host switches the iframe to. */
+export interface EmbedSetThemePayload {
+    /** The requested theme. */
+    readonly theme: EmbedTheme;
+}
+/** The theme hint carried on the `theme` URL param and `set-theme` frame. */
+export type EmbedTheme = "light" | "dark";
+/**
+ * Maps each message type to its payload shape. Used to type the inbound
+ * classifier and the outbound sender so the payload is checked against the
+ * message type.
+ */
+export interface EmbedMessagePayloadMap {
+    [EMBED_MESSAGE_TYPES.ready]: EmbedReadyPayload;
+    [EMBED_MESSAGE_TYPES.setToken]: EmbedSetTokenPayload;
+    [EMBED_MESSAGE_TYPES.tokenExpired]: EmbedTokenExpiredPayload;
+    [EMBED_MESSAGE_TYPES.reloadRequired]: EmbedReloadRequiredPayload;
+    [EMBED_MESSAGE_TYPES.resized]: EmbedResizedPayload;
+    [EMBED_MESSAGE_TYPES.navigated]: EmbedNavigationPayload;
+    [EMBED_MESSAGE_TYPES.navigationRequested]: EmbedNavigationPayload;
+    [EMBED_MESSAGE_TYPES.dirtyChanged]: EmbedDirtyChangedPayload;
+    [EMBED_MESSAGE_TYPES.navigate]: EmbedNavigatePayload;
+    [EMBED_MESSAGE_TYPES.setTheme]: EmbedSetThemePayload;
+}
+/**
+ * The wire envelope. Every embed frame is exactly this shape: a fixed
+ * `source` + `protocol` pair, a discriminating `type`, and the typed
+ * `payload` for that type.
+ */
+export interface EmbedMessage<T extends EmbedMessageType = EmbedMessageType> {
+    readonly source: typeof EMBED_MESSAGE_SOURCE;
+    readonly protocol: typeof EMBED_PROTOCOL_VERSION;
+    readonly type: T;
+    readonly payload: EmbedMessagePayloadMap[T];
+}

package/dist/react.d.ts

@@ -0,0 +1,27 @@
+import type { ReactElement, Ref } from "react";
+import type { DeclarionEmbedHandle, DeclarionEmbedOptions } from "./types";
+/**
+ * Props for `<DeclarionEmbed />`.
+ *
+ * Every `createDeclarionEmbed` option except `container` is accepted as a
+ * prop - the component owns the container element. `className` and `style`
+ * style that container `<div>`.
+ */
+export interface DeclarionEmbedProps extends Omit<DeclarionEmbedOptions, "container"> {
+    /** Optional class applied to the container element wrapping the iframe. */
+    readonly className?: string;
+    /** Optional inline style applied to the container element. */
+    readonly style?: React.CSSProperties;
+}
+/**
+ * `<DeclarionEmbed />` - the React binding for `@declarion/embed`.
+ *
+ * Accepts the same options as `createDeclarionEmbed` (minus `container`,
+ * which the component owns) and forwards a `DeclarionEmbedHandle` ref.
+ */
+export declare const DeclarionEmbed: (props: DeclarionEmbedProps & {
+    ref?: Ref<DeclarionEmbedHandle>;
+}) => ReactElement;
+export type { DeclarionEmbedOptions, DeclarionEmbedHandle, EmbedNavigationContract, EmbedNavigateEvent, EmbedEvent, EmbedToken, EmbedGetToken, EmbedTheme, } from "./types";
+export { EmbedError, EMBED_ERROR_CODES } from "./errors";
+export type { EmbedErrorCode } from "./errors";

package/dist/react.js

@@ -0,0 +1,50 @@
+import { n as e, r as t, t as n } from "./core.js";
+import { forwardRef as r, useEffect as i, useImperativeHandle as a, useRef as o } from "react";
+import { jsx as s } from "react/jsx-runtime";
+//#region src/react.tsx
+function c(e) {
+	return [
+		e.declarionOrigin,
+		e.route,
+		e.navigation ?? "self"
+	].join("\0");
+}
+function l(e, t) {
+	let { className: r, style: l } = e, u = o(null), d = o(null), f = o(e);
+	return f.current = e, i(() => {
+		let e = u.current;
+		if (!e) return;
+		let t = n({
+			container: e,
+			declarionOrigin: f.current.declarionOrigin,
+			route: f.current.route,
+			navigation: f.current.navigation,
+			theme: f.current.theme,
+			title: f.current.title,
+			debug: f.current.debug,
+			getToken: () => f.current.getToken(),
+			onReady: () => f.current.onReady?.(),
+			onError: (e) => f.current.onError?.(e),
+			onNavigate: (e) => f.current.onNavigate?.(e),
+			onEvent: (e) => f.current.onEvent?.(e)
+		});
+		return d.current = t, () => {
+			t.destroy(), d.current = null;
+		};
+	}, [c(e)]), i(() => {
+		e.theme && d.current?.setTheme(e.theme);
+	}, [e.theme]), a(t, () => ({
+		navigate: (e) => d.current?.navigate(e),
+		setTheme: (e) => d.current?.setTheme(e),
+		destroy: () => d.current?.destroy()
+	}), []), /* @__PURE__ */ s("div", {
+		ref: u,
+		className: r,
+		style: l
+	});
+}
+var u = r(l);
+//#endregion
+export { u as DeclarionEmbed, e as EMBED_ERROR_CODES, t as EmbedError };
+
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","names":[],"sources":["../src/react.tsx"],"sourcesContent":["// `@declarion/embed/react` - the React binding.\n//\n// `<DeclarionEmbed />` wraps `createDeclarionEmbed` (the dependency-free\n// core) in a React component, managing the embed lifecycle across mount,\n// prop change, and unmount. React is a peer dependency of THIS entry only;\n// the core entry (`@declarion/embed`) stays dependency-free.\n\nimport { useEffect, useImperativeHandle, useRef } from \"react\";\nimport type { ForwardedRef, ReactElement, Ref } from \"react\";\nimport { forwardRef } from \"react\";\nimport { createDeclarionEmbed } from \"./core\";\nimport type {\n  DeclarionEmbedHandle,\n  DeclarionEmbedOptions,\n} from \"./types\";\n\n/**\n * Props for `<DeclarionEmbed />`.\n *\n * Every `createDeclarionEmbed` option except `container` is accepted as a\n * prop - the component owns the container element. `className` and `style`\n * style that container `<div>`.\n */\nexport interface DeclarionEmbedProps\n  extends Omit<DeclarionEmbedOptions, \"container\"> {\n  /** Optional class applied to the container element wrapping the iframe. */\n  readonly className?: string;\n  /** Optional inline style applied to the container element. */\n  readonly style?: React.CSSProperties;\n}\n\n/**\n * The set of props that, when changed, MUST rebuild the embed: a different\n * Declarion deployment, route, navigation contract, or token source means a\n * different iframe. Theme is intentionally excluded - it is applied live via\n * the handle's `setTheme` without a rebuild.\n */\nfunction rebuildKey(props: DeclarionEmbedProps): string {\n  return [\n    props.declarionOrigin,\n    props.route,\n    props.navigation ?? \"self\",\n  ].join(\"\\u0000\");\n}\n\n/**\n * Embed a Declarion screen as a white-label iframe.\n *\n * The component creates the embed on mount, rebuilds it when the deployment,\n * route, or navigation contract changes, and destroys it on unmount. A\n * `ref` exposes the imperative `DeclarionEmbedHandle` (`navigate`,\n * `setTheme`, `destroy`) for hosts that drive the iframe directly.\n *\n * `getToken` and the callback props are read through a ref, so passing a\n * fresh inline `getToken` on every render does NOT rebuild the iframe.\n */\nfunction DeclarionEmbedComponent(\n  props: DeclarionEmbedProps,\n  ref: ForwardedRef<DeclarionEmbedHandle>,\n): ReactElement {\n  const { className, style } = props;\n  const containerRef = useRef<HTMLDivElement | null>(null);\n  const handleRef = useRef<DeclarionEmbedHandle | null>(null);\n\n  // Latest props, read by the stable callbacks handed to the core. This\n  // keeps `getToken` / `onReady` / `onError` / `onNavigate` / `onEvent`\n  // current without rebuilding the iframe when an inline closure changes.\n  const propsRef = useRef(props);\n  propsRef.current = props;\n\n  const key = rebuildKey(props);\n\n  useEffect(() => {\n    const container = containerRef.current;\n    if (!container) return undefined;\n\n    const handle = createDeclarionEmbed({\n      container,\n      // `propsRef.current` is always the latest props snapshot - React updates\n      // the ref during render, before this effect runs - so these read\n      // correctly on both the initial mount and a key-triggered rebuild.\n      declarionOrigin: propsRef.current.declarionOrigin,\n      route: propsRef.current.route,\n      navigation: propsRef.current.navigation,\n      theme: propsRef.current.theme,\n      title: propsRef.current.title,\n      debug: propsRef.current.debug,\n      // The callbacks delegate through `propsRef` so the latest closure\n      // always runs, even though the embed was built once.\n      getToken: () => propsRef.current.getToken(),\n      onReady: () => propsRef.current.onReady?.(),\n      onError: (error) => propsRef.current.onError?.(error),\n      onNavigate: (event) => propsRef.current.onNavigate?.(event),\n      onEvent: (event) => propsRef.current.onEvent?.(event),\n    });\n    handleRef.current = handle;\n\n    return () => {\n      handle.destroy();\n      handleRef.current = null;\n    };\n    // `key` changes only when the deployment, route, or navigation contract\n    // changes - exactly the props that require a fresh iframe.\n  }, [key]);\n\n  // Apply a live theme change without a rebuild.\n  useEffect(() => {\n    if (props.theme) {\n      handleRef.current?.setTheme(props.theme);\n    }\n  }, [props.theme]);\n\n  // Expose the imperative handle. The wrapper stays valid across rebuilds:\n  // it always delegates to the current `handleRef`.\n  useImperativeHandle(\n    ref,\n    (): DeclarionEmbedHandle => ({\n      navigate: (route) => handleRef.current?.navigate(route),\n      setTheme: (theme) => handleRef.current?.setTheme(theme),\n      destroy: () => handleRef.current?.destroy(),\n    }),\n    [],\n  );\n\n  return <div ref={containerRef} className={className} style={style} />;\n}\n\n/**\n * `<DeclarionEmbed />` - the React binding for `@declarion/embed`.\n *\n * Accepts the same options as `createDeclarionEmbed` (minus `container`,\n * which the component owns) and forwards a `DeclarionEmbedHandle` ref.\n */\nexport const DeclarionEmbed = forwardRef(DeclarionEmbedComponent) as (\n  props: DeclarionEmbedProps & { ref?: Ref<DeclarionEmbedHandle> },\n) => ReactElement;\n\n// Re-export the option, handle, event, and protocol types so a React host\n// imports everything from the single `@declarion/embed/react` entry.\nexport type {\n  DeclarionEmbedOptions,\n  DeclarionEmbedHandle,\n  EmbedNavigationContract,\n  EmbedNavigateEvent,\n  EmbedEvent,\n  EmbedToken,\n  EmbedGetToken,\n  EmbedTheme,\n} from \"./types\";\nexport { EmbedError, EMBED_ERROR_CODES } from \"./errors\";\nexport type { EmbedErrorCode } from \"./errors\";\n"],"mappings":";;;;AAqCA,SAAS,EAAW,GAAoC;CACtD,OAAO;EACL,EAAM;EACN,EAAM;EACN,EAAM,cAAc;CACtB,EAAE,KAAK,IAAQ;AACjB;AAaA,SAAS,EACP,GACA,GACc;CACd,IAAM,EAAE,cAAW,aAAU,GACvB,IAAe,EAA8B,IAAI,GACjD,IAAY,EAAoC,IAAI,GAKpD,IAAW,EAAO,CAAK;CAyD7B,OAxDA,EAAS,UAAU,GAInB,QAAgB;EACd,IAAM,IAAY,EAAa;EAC/B,IAAI,CAAC,GAAW;EAEhB,IAAM,IAAS,EAAqB;GAClC;GAIA,iBAAiB,EAAS,QAAQ;GAClC,OAAO,EAAS,QAAQ;GACxB,YAAY,EAAS,QAAQ;GAC7B,OAAO,EAAS,QAAQ;GACxB,OAAO,EAAS,QAAQ;GACxB,OAAO,EAAS,QAAQ;GAGxB,gBAAgB,EAAS,QAAQ,SAAS;GAC1C,eAAe,EAAS,QAAQ,UAAU;GAC1C,UAAU,MAAU,EAAS,QAAQ,UAAU,CAAK;GACpD,aAAa,MAAU,EAAS,QAAQ,aAAa,CAAK;GAC1D,UAAU,MAAU,EAAS,QAAQ,UAAU,CAAK;EACtD,CAAC;EAGD,OAFA,EAAU,UAAU,SAEP;GAEX,AADA,EAAO,QAAQ,GACf,EAAU,UAAU;EACtB;CAGF,GAAG,CAjCS,EAAW,CAiCnB,CAAG,CAAC,GAGR,QAAgB;EACd,AAAI,EAAM,SACR,EAAU,SAAS,SAAS,EAAM,KAAK;CAE3C,GAAG,CAAC,EAAM,KAAK,CAAC,GAIhB,EACE,UAC6B;EAC3B,WAAW,MAAU,EAAU,SAAS,SAAS,CAAK;EACtD,WAAW,MAAU,EAAU,SAAS,SAAS,CAAK;EACtD,eAAe,EAAU,SAAS,QAAQ;CAC5C,IACA,CAAC,CACH,GAEO,kBAAC,OAAD;EAAK,KAAK;EAAyB;EAAkB;CAAQ,CAAA;AACtE;AAQA,IAAa,IAAiB,EAAW,CAAuB"}

package/dist/server.d.ts

@@ -0,0 +1,66 @@
+import type { EmbedToken } from "./types";
+/**
+ * Options for `createEmbedSession`. `apiKey`, `declarionOrigin`, and the
+ * three identity fields are required; `ttlSeconds` and `permissions` are
+ * optional and forwarded to the action unchanged.
+ */
+export interface CreateEmbedSessionOptions {
+    /**
+     * The exact origin of the Declarion deployment, e.g.
+     * `https://app.example.com`. The action call is `${declarionOrigin}` +
+     * `/api/actions/auth.create_embed_session`.
+     */
+    readonly declarionOrigin: string;
+    /**
+     * The `dk:`-prefixed Declarion API key. The trust anchor for the mint
+     * call. MUST be held server-side only; never ship it to a browser.
+     */
+    readonly apiKey: string;
+    /** Tenant code; MUST match the API key's active tenant. */
+    readonly tenantCode: string;
+    /** Email of the target user the iframe runs as (host identity assertion). */
+    readonly userEmail: string;
+    /** Code of the Declarion screen to embed. */
+    readonly screenCode: string;
+    /**
+     * Token lifetime in seconds. Defaults to 600. The deployment caps it at
+     * 900 and raises values below 60 to 60.
+     */
+    readonly ttlSeconds?: number;
+    /**
+     * Extra permission allow-list. Every entry MUST be held by the target
+     * user; wildcards are rejected by the deployment.
+     */
+    readonly permissions?: readonly string[];
+    /**
+     * Optional `AbortSignal` to cancel the mint request (e.g. a host request
+     * timeout). Forwarded to `fetch`.
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * The error thrown when `auth.create_embed_session` does not return a
+ * session. Carries the deployment's machine-readable error `code` (e.g.
+ * `EMBED_NOT_API_KEY`, `FORBIDDEN`) and the HTTP status so the host backend
+ * can branch on the failure.
+ */
+export declare class EmbedSessionError extends Error {
+    /** The Declarion error code, or `null` when the response had none. */
+    readonly code: string | null;
+    /** The HTTP status of the action response. */
+    readonly status: number;
+    constructor(message: string, status: number, code: string | null);
+}
+/**
+ * Mint a short-lived, scoped embed session token for a host-asserted user.
+ *
+ * Calls `POST /api/actions/auth.create_embed_session` on the Declarion
+ * deployment, authenticating with the server-held `dk:` API key, and returns
+ * the `{ token, expires_at }` the host hands to the iframe (typically as the
+ * `getToken` result of `createDeclarionEmbed` / `<DeclarionEmbed />`).
+ *
+ * Throws `EmbedSessionError` on any non-success response, carrying the
+ * deployment's error code and HTTP status.
+ */
+export declare function createEmbedSession(options: CreateEmbedSessionOptions): Promise<EmbedToken>;
+export type { EmbedToken } from "./types";

package/dist/server.js

@@ -0,0 +1,50 @@
+//#region src/server.ts
+var e = "auth.create_embed_session", t = "/api/actions", n = 600, r = class e extends Error {
+	code;
+	status;
+	constructor(t, n, r) {
+		super(t), this.name = "EmbedSessionError", this.code = r, this.status = n, Object.setPrototypeOf(this, e.prototype);
+	}
+};
+function i(e) {
+	if (typeof e != "object" || !e) return !1;
+	let t = e;
+	return typeof t.token == "string" && t.token !== "" && typeof t.expires_at == "string" && t.expires_at !== "";
+}
+async function a(a) {
+	let o = `${new URL(a.declarionOrigin).origin}${t}/${e}`, s = {
+		tenant_code: a.tenantCode,
+		user_email: a.userEmail,
+		screen_code: a.screenCode,
+		ttl_seconds: a.ttlSeconds ?? n
+	};
+	a.permissions && a.permissions.length > 0 && (s.permissions = a.permissions);
+	let c = await fetch(o, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			authorization: a.apiKey
+		},
+		body: JSON.stringify(s),
+		signal: a.signal
+	}), l;
+	try {
+		l = await c.json();
+	} catch {
+		throw new r(`auth.create_embed_session returned a non-JSON response (HTTP ${c.status}).`, c.status, null);
+	}
+	if (!c.ok) {
+		let e = l, t = e.error?.code ?? null;
+		throw new r(e.error?.message ?? `auth.create_embed_session failed with HTTP ${c.status}.`, c.status, t);
+	}
+	let u = l.result;
+	if (!i(u)) throw new r("auth.create_embed_session returned a malformed result: expected { token, expires_at }.", c.status, null);
+	return {
+		token: u.token,
+		expires_at: u.expires_at
+	};
+}
+//#endregion
+export { r as EmbedSessionError, a as createEmbedSession };
+
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["// `@declarion/embed/server` - the Node-side mint helper.\n//\n// `createEmbedSession` performs the authenticated\n// `POST /api/actions/auth.create_embed_session` call so the host backend\n// writes one typed call instead of a hand-rolled HTTP request.\n//\n// This entry is SEPARATE from the browser core (`@declarion/embed`) and the\n// React binding (`@declarion/embed/react`) for one security reason: the\n// `dk:` API key is a backend-to-backend credential and MUST NEVER reach a\n// browser. Keeping it in its own entry means a frontend bundle that imports\n// `@declarion/embed` or `@declarion/embed/react` cannot pull the key path.\n//\n// The helper uses the global `fetch` (Node 18+, the platform's pinned Node\n// is 24) so it stays dependency-free.\n\nimport type { EmbedToken } from \"./types\";\n\n/** The fully-qualified action code for minting an embed session. */\nconst EMBED_SESSION_ACTION = \"auth.create_embed_session\";\n\n/** Path of the generic action dispatcher on a Declarion deployment. */\nconst ACTIONS_PATH = \"/api/actions\";\n\n/** Default token lifetime (seconds) when the host does not request one. */\nconst DEFAULT_TTL_SECONDS = 600;\n\n/**\n * Options for `createEmbedSession`. `apiKey`, `declarionOrigin`, and the\n * three identity fields are required; `ttlSeconds` and `permissions` are\n * optional and forwarded to the action unchanged.\n */\nexport interface CreateEmbedSessionOptions {\n  /**\n   * The exact origin of the Declarion deployment, e.g.\n   * `https://app.example.com`. The action call is `${declarionOrigin}` +\n   * `/api/actions/auth.create_embed_session`.\n   */\n  readonly declarionOrigin: string;\n  /**\n   * The `dk:`-prefixed Declarion API key. The trust anchor for the mint\n   * call. MUST be held server-side only; never ship it to a browser.\n   */\n  readonly apiKey: string;\n  /** Tenant code; MUST match the API key's active tenant. */\n  readonly tenantCode: string;\n  /** Email of the target user the iframe runs as (host identity assertion). */\n  readonly userEmail: string;\n  /** Code of the Declarion screen to embed. */\n  readonly screenCode: string;\n  /**\n   * Token lifetime in seconds. Defaults to 600. The deployment caps it at\n   * 900 and raises values below 60 to 60.\n   */\n  readonly ttlSeconds?: number;\n  /**\n   * Extra permission allow-list. Every entry MUST be held by the target\n   * user; wildcards are rejected by the deployment.\n   */\n  readonly permissions?: readonly string[];\n  /**\n   * Optional `AbortSignal` to cancel the mint request (e.g. a host request\n   * timeout). Forwarded to `fetch`.\n   */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * The error thrown when `auth.create_embed_session` does not return a\n * session. Carries the deployment's machine-readable error `code` (e.g.\n * `EMBED_NOT_API_KEY`, `FORBIDDEN`) and the HTTP status so the host backend\n * can branch on the failure.\n */\nexport class EmbedSessionError extends Error {\n  /** The Declarion error code, or `null` when the response had none. */\n  readonly code: string | null;\n  /** The HTTP status of the action response. */\n  readonly status: number;\n\n  constructor(message: string, status: number, code: string | null) {\n    super(message);\n    this.name = \"EmbedSessionError\";\n    this.code = code;\n    this.status = status;\n    Object.setPrototypeOf(this, EmbedSessionError.prototype);\n  }\n}\n\n/** The action dispatcher's success envelope: `{ status, result, ... }`. */\ninterface ActionSuccessEnvelope {\n  readonly status?: string;\n  readonly result?: unknown;\n}\n\n/** The action dispatcher's error envelope: `{ error: { message, code } }`. */\ninterface ActionErrorEnvelope {\n  readonly error?: { readonly message?: string; readonly code?: string };\n}\n\n/** Narrow an unknown parsed body to a valid `{ token, expires_at }` result. */\nfunction isEmbedToken(value: unknown): value is EmbedToken {\n  if (typeof value !== \"object\" || value === null) return false;\n  const token = value as Partial<EmbedToken>;\n  return (\n    typeof token.token === \"string\" &&\n    token.token !== \"\" &&\n    typeof token.expires_at === \"string\" &&\n    token.expires_at !== \"\"\n  );\n}\n\n/**\n * Mint a short-lived, scoped embed session token for a host-asserted user.\n *\n * Calls `POST /api/actions/auth.create_embed_session` on the Declarion\n * deployment, authenticating with the server-held `dk:` API key, and returns\n * the `{ token, expires_at }` the host hands to the iframe (typically as the\n * `getToken` result of `createDeclarionEmbed` / `<DeclarionEmbed />`).\n *\n * Throws `EmbedSessionError` on any non-success response, carrying the\n * deployment's error code and HTTP status.\n */\nexport async function createEmbedSession(\n  options: CreateEmbedSessionOptions,\n): Promise<EmbedToken> {\n  const origin = new URL(options.declarionOrigin).origin;\n  const url = `${origin}${ACTIONS_PATH}/${EMBED_SESSION_ACTION}`;\n\n  const body: Record<string, unknown> = {\n    tenant_code: options.tenantCode,\n    user_email: options.userEmail,\n    screen_code: options.screenCode,\n    ttl_seconds: options.ttlSeconds ?? DEFAULT_TTL_SECONDS,\n  };\n  if (options.permissions && options.permissions.length > 0) {\n    body.permissions = options.permissions;\n  }\n\n  const response = await fetch(url, {\n    method: \"POST\",\n    headers: {\n      \"content-type\": \"application/json\",\n      // The `dk:` API key travels in the Authorization header. The action\n      // handler requires `AuthMethod == \"apikey\"`; a cookie or Basic auth\n      // cannot mint an embed session.\n      authorization: options.apiKey,\n    },\n    body: JSON.stringify(body),\n    signal: options.signal,\n  });\n\n  // Parse the JSON body once; both the success and the error envelope are\n  // JSON. A non-JSON body (a proxy error page) is surfaced as a generic\n  // failure carrying the HTTP status.\n  let parsed: unknown;\n  try {\n    parsed = await response.json();\n  } catch {\n    throw new EmbedSessionError(\n      `auth.create_embed_session returned a non-JSON response ` +\n        `(HTTP ${response.status}).`,\n      response.status,\n      null,\n    );\n  }\n\n  if (!response.ok) {\n    const errorBody = parsed as ActionErrorEnvelope;\n    const code = errorBody.error?.code ?? null;\n    const message =\n      errorBody.error?.message ??\n      `auth.create_embed_session failed with HTTP ${response.status}.`;\n    throw new EmbedSessionError(message, response.status, code);\n  }\n\n  const result = (parsed as ActionSuccessEnvelope).result;\n  if (!isEmbedToken(result)) {\n    throw new EmbedSessionError(\n      \"auth.create_embed_session returned a malformed result: expected \" +\n        \"{ token, expires_at }.\",\n      response.status,\n      null,\n    );\n  }\n\n  return { token: result.token, expires_at: result.expires_at };\n}\n\nexport type { EmbedToken } from \"./types\";\n"],"mappings":";AAkBA,IAAM,IAAuB,6BAGvB,IAAe,gBAGf,IAAsB,KAgDf,IAAb,MAAa,UAA0B,MAAM;CAE3C;CAEA;CAEA,YAAY,GAAiB,GAAgB,GAAqB;EAKhE,AAJA,MAAM,CAAO,GACb,KAAK,OAAO,qBACZ,KAAK,OAAO,GACZ,KAAK,SAAS,GACd,OAAO,eAAe,MAAM,EAAkB,SAAS;CACzD;AACF;AAcA,SAAS,EAAa,GAAqC;CACzD,IAAI,OAAO,KAAU,aAAY,GAAgB,OAAO;CACxD,IAAM,IAAQ;CACd,OACE,OAAO,EAAM,SAAU,YACvB,EAAM,UAAU,MAChB,OAAO,EAAM,cAAe,YAC5B,EAAM,eAAe;AAEzB;AAaA,eAAsB,EACpB,GACqB;CAErB,IAAM,IAAM,GADG,IAAI,IAAI,EAAQ,eAAe,EAAE,SACxB,EAAa,GAAG,KAElC,IAAgC;EACpC,aAAa,EAAQ;EACrB,YAAY,EAAQ;EACpB,aAAa,EAAQ;EACrB,aAAa,EAAQ,cAAc;CACrC;CACA,AAAI,EAAQ,eAAe,EAAQ,YAAY,SAAS,MACtD,EAAK,cAAc,EAAQ;CAG7B,IAAM,IAAW,MAAM,MAAM,GAAK;EAChC,QAAQ;EACR,SAAS;GACP,gBAAgB;GAIhB,eAAe,EAAQ;EACzB;EACA,MAAM,KAAK,UAAU,CAAI;EACzB,QAAQ,EAAQ;CAClB,CAAC,GAKG;CACJ,IAAI;EACF,IAAS,MAAM,EAAS,KAAK;CAC/B,QAAQ;EACN,MAAM,IAAI,EACR,gEACW,EAAS,OAAO,KAC3B,EAAS,QACT,IACF;CACF;CAEA,IAAI,CAAC,EAAS,IAAI;EAChB,IAAM,IAAY,GACZ,IAAO,EAAU,OAAO,QAAQ;EAItC,MAAM,IAAI,EAFR,EAAU,OAAO,WACjB,8CAA8C,EAAS,OAAO,IAC3B,EAAS,QAAQ,CAAI;CAC5D;CAEA,IAAM,IAAU,EAAiC;CACjD,IAAI,CAAC,EAAa,CAAM,GACtB,MAAM,IAAI,EACR,0FAEA,EAAS,QACT,IACF;CAGF,OAAO;EAAE,OAAO,EAAO;EAAO,YAAY,EAAO;CAAW;AAC9D"}

package/dist/types.d.ts

@@ -0,0 +1,136 @@
+import type { EmbedDirtyChangedPayload, EmbedNavigationPayload, EmbedReloadRequiredPayload, EmbedResizedPayload, EmbedTheme } from "./protocol";
+import type { EmbedError } from "./errors";
+/**
+ * The navigation contract for an embedded iframe (Section 1, Decision 16).
+ *
+ * - `self` (default): the iframe navigates internally between Declarion
+ *   screen routes and emits `navigated` so the host can mirror its own URL,
+ *   breadcrumb, and back button.
+ * - `delegated`: the iframe never moves; it emits `navigation-requested` and
+ *   the host decides what to open.
+ */
+export type EmbedNavigationContract = "self" | "delegated";
+/**
+ * A token the host hands to the embedded iframe. Returned by `getToken` and
+ * delivered to the iframe in the `set-token` frame.
+ */
+export interface EmbedToken {
+    /** The scoped, refresh-less embed JWT minted by `auth.create_embed_session`. */
+    readonly token: string;
+    /** RFC 3339 absolute expiry timestamp of the token. */
+    readonly expires_at: string;
+}
+/**
+ * The async host callback that owns the entire embed token lifecycle
+ * (Decision 23). The SDK calls it on mount and again on every
+ * `token-expired` frame; the host backend mints a fresh token via
+ * `auth.create_embed_session` and the SDK delivers it to the iframe. The
+ * developer never handles token refresh manually.
+ */
+export type EmbedGetToken = () => Promise<EmbedToken>;
+/**
+ * A protocol event surfaced to the generic `onEvent` callback. One variant
+ * per inbound iframe-to-host message the host may observe. The host-to-iframe
+ * frames (`set-token`, `navigate`, `set-theme`) are SDK outputs, not events,
+ * and are intentionally absent.
+ */
+export type EmbedEvent = {
+    readonly type: "ready";
+} | {
+    readonly type: "token-expired";
+} | {
+    readonly type: "reload-required";
+    readonly payload: EmbedReloadRequiredPayload;
+} | {
+    readonly type: "resized";
+    readonly payload: EmbedResizedPayload;
+} | {
+    readonly type: "navigated";
+    readonly payload: EmbedNavigationPayload;
+} | {
+    readonly type: "navigation-requested";
+    readonly payload: EmbedNavigationPayload;
+} | {
+    readonly type: "dirty-changed";
+    readonly payload: EmbedDirtyChangedPayload;
+};
+/**
+ * A navigation event surfaced to the `onNavigate` callback. `mode` records
+ * which protocol frame produced it: `self` for `navigated` (the
+ * iframe already moved), `delegated` for `navigation-requested` (the iframe
+ * stayed and the host must open the route).
+ */
+export interface EmbedNavigateEvent {
+    /** Which navigation frame produced this event. */
+    readonly mode: EmbedNavigationContract;
+    /** The Declarion screen route the navigation targets. */
+    readonly route: string;
+    /** The bound entity code, when the route resolves to one. */
+    readonly entity?: string;
+    /** The record id, when the route is a detail route with an id. */
+    readonly recordId?: string;
+}
+/**
+ * The options accepted by `createDeclarionEmbed` and the `<DeclarionEmbed />`
+ * React binding (Section 7 Core API table).
+ */
+export interface DeclarionEmbedOptions {
+    /** DOM element that receives the iframe. The SDK appends the iframe to it. */
+    readonly container: HTMLElement;
+    /**
+     * The exact origin the Declarion deployment is served from
+     * (`https://app.example.com`). Used to build the iframe `src` and to
+     * exact-match every inbound `postMessage` frame.
+     */
+    readonly declarionOrigin: string;
+    /** The Declarion screen route to embed (the iframe's initial route). */
+    readonly route: string;
+    /**
+     * The async host callback returning a fresh embed token. Called on mount
+     * and on every `token-expired` frame. See `EmbedGetToken`.
+     */
+    readonly getToken: EmbedGetToken;
+    /**
+     * Navigation contract for this iframe. `"self"` (default) or
+     * `"delegated"`; sets the `nav` URL param.
+     */
+    readonly navigation?: EmbedNavigationContract;
+    /** Initial theme hint, applied before the iframe's first paint. */
+    readonly theme?: EmbedTheme;
+    /** The iframe `title` attribute. Defaults to a sensible label. */
+    readonly title?: string;
+    /** When true, logs the handshake and every protocol frame to the console. */
+    readonly debug?: boolean;
+    /**
+     * Fired once the embed has authenticated - the first token has been
+     * delivered to the iframe after the `ready` handshake. The SDK has no
+     * iframe-render signal, so this is the earliest point the host can treat
+     * the embedded screen as live.
+     */
+    readonly onReady?: () => void;
+    /** Fired on misconfiguration with a typed, actionable `EmbedError`. */
+    readonly onError?: (error: EmbedError) => void;
+    /** Fired for `navigated` (`self`) and `navigation-requested` (`delegated`). */
+    readonly onNavigate?: (event: EmbedNavigateEvent) => void;
+    /** Generic callback fired for every inbound protocol event. */
+    readonly onEvent?: (event: EmbedEvent) => void;
+}
+/**
+ * The imperative handle returned by `createDeclarionEmbed`. The host keeps
+ * it to drive the iframe and to tear it down.
+ */
+export interface DeclarionEmbedHandle {
+    /**
+     * Drive the iframe to a Declarion screen route (deep-linking). Works in
+     * both navigation contracts.
+     */
+    navigate(route: string): void;
+    /** Switch the iframe theme at runtime. */
+    setTheme(theme: EmbedTheme): void;
+    /**
+     * Tear down the embed: detach the `message` listener, stop pending timers,
+     * and remove the iframe from the container. Idempotent.
+     */
+    destroy(): void;
+}
+export type { EmbedTheme } from "./protocol";

package/dist/url.d.ts

@@ -0,0 +1,43 @@
+import type { EmbedNavigationContract, EmbedTheme } from "./types";
+/** Query-param names that make up the embed URL contract. */
+export declare const EMBED_PARAM_EMBED = "embed";
+export declare const EMBED_PARAM_PARENT_ORIGIN = "parent_origin";
+export declare const EMBED_PARAM_THEME = "theme";
+export declare const EMBED_PARAM_NAV = "nav";
+/** Default navigation contract when the host does not set `navigation`. */
+export declare const DEFAULT_NAVIGATION_CONTRACT: EmbedNavigationContract;
+/** Inputs needed to build the iframe `src`. */
+export interface BuildEmbedSrcInput {
+    /** The Declarion deployment origin (`https://app.example.com`). */
+    readonly declarionOrigin: string;
+    /** The Declarion screen route to embed. */
+    readonly route: string;
+    /**
+     * The host page's own origin. Becomes `parent_origin` so the iframe knows
+     * exactly which origin may exchange `postMessage` frames with it.
+     */
+    readonly parentOrigin: string;
+    /** Navigation contract; becomes the `nav` param. */
+    readonly navigation: EmbedNavigationContract;
+    /** Optional initial theme; becomes the `theme` param when set. */
+    readonly theme?: EmbedTheme;
+}
+/**
+ * Build the absolute iframe `src` URL for an embedded Declarion screen.
+ *
+ * The `route` is resolved as a path against `declarionOrigin`; the four
+ * embed params are appended. `parent_origin` is the host's own origin so the
+ * iframe restricts its `postMessage` traffic to exactly that origin.
+ *
+ * Throws when `declarionOrigin` is not a parseable absolute origin - callers
+ * convert that into a typed `EmbedError` before raising it to the host.
+ */
+export declare function buildEmbedSrc(input: BuildEmbedSrcInput): string;
+/**
+ * Resolve a Declarion screen route to an absolute URL for a runtime
+ * `navigate` frame. The host passes a route string; the iframe consumes the
+ * route as-is, so this only normalizes it against the deployment origin for
+ * the host's own bookkeeping. Returns the input unchanged when it cannot be
+ * resolved (the iframe tolerates a relative route).
+ */
+export declare function resolveRoute(declarionOrigin: string, route: string): string;