@matterfact/embed 0.13.0 → 0.16.0

package/dist/react.d.cts

@@ -159,6 +159,44 @@ type MatterfactEvent = {
     source: 'user' | 'context';
 };
 
+interface MatterfactAuthProviderProps {
+    /**
+     * Publishable key (`pk_…`) identifying this embed app. Public and origin-scoped —
+     * meant to sit in HTML. Every `MatterfactAgent`/`MatterfactArtifact`/`MatterfactDoc`
+     * under this provider inherits it, so you set it once here rather than on each child.
+     */
+    publishableKey: string;
+    /**
+     * Origin serving the matterfact widgets (the app that hosts `/embed/*`). Defaults to
+     * production. This is the ONE place to set it — every child inherits it, and the
+     * `widgetOrigin` prop on `MatterfactAgent`/`MatterfactArtifact` is deprecated in
+     * favour of setting it here.
+     */
+    widgetOrigin?: string;
+    /**
+     * HOST-AUTH PASSTHROUGH (trusted first-party embeds). Return a token this matterfact
+     * deployment already trusts — the host app's Entra/Firebase token, whatever its auth
+     * provider verifies — and every child iframe signs in SILENTLY with it, no separate
+     * sign-in. The provider brokers it: when a child needs auth it asks the provider,
+     * which calls this and hands the token back (over `postMessage`, pinned to the widget
+     * origin). Called on demand so the token can be fresh; may be async. Omit for the
+     * standard interactive sign-in.
+     */
+    getAuthToken?: () => string | null | Promise<string | null>;
+    /** Colour theme applied to every child widget. Falls back to `'auto'`. */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Unified telemetry hook, fired for every embed lifecycle moment (`ready`, `auth`,
+     * `error`, …) across the children — pipe the whole embed into your own observability
+     * from one place. Never blocks or breaks a widget; a throw here is swallowed.
+     */
+    onEvent?: (e: MatterfactEvent) => void;
+    /** The embed components (`MatterfactAgent`/`MatterfactArtifact`/`MatterfactDoc`) that
+     *  inherit this provider's config. */
+    children: React.ReactNode;
+}
+declare function MatterfactAuthProvider({ publishableKey, widgetOrigin, getAuthToken, theme, onEvent, children, }: MatterfactAuthProviderProps): react_jsx_runtime.JSX.Element;
+
 /**
  * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
  * `window.XH` by hoist-runtime.ts) into the context/snapshot shapes context.ts sends
@@ -239,12 +277,25 @@ interface HostToolDef {
 }
 
 interface MatterfactAgentProps {
-    /** Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped. */
-    publishableKey: string;
-    /** Origin serving the widget (the matterfact app). Defaults to production. */
+    /**
+     * Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped.
+     *
+     * Optional here ONLY because it can instead come from an ancestor
+     * `MatterfactAuthProvider` (`prop ?? context`) — one of the two must supply it,
+     * or the component throws at mount.
+     */
+    publishableKey?: string;
+    /**
+     * Origin serving the widget (the matterfact app). Defaults to production.
+     *
+     * @deprecated Prefer setting this once on `<MatterfactAuthProvider>` and letting
+     * every `<MatterfactAgent>`/`<MatterfactArtifact>` underneath inherit it. Still
+     * fully supported standalone (no provider) — resolved as `prop ?? context ?? default`.
+     */
     widgetOrigin?: string;
     /** Label for THIS embedding, for per-surface usage/history attribution. */
     surface?: string;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'light' | 'dark' | 'auto';
     /**
      * HOST-AUTH PASSTHROUGH (trusted first-party embeds only). Return a token this
@@ -252,6 +303,8 @@ interface MatterfactAgentProps {
      * token, whatever its auth provider verifies — and the widget signs in SILENTLY with
      * it, no separate sign-in. Called on demand so the token can be fresh. Omit for the
      * standard popup/inline sign-in (third-party hosts).
+     *
+     * Resolved as `prop ?? MatterfactAuthProvider's getAuthToken`.
      */
     getAuthToken?: () => string | null | Promise<string | null>;
     /**
@@ -356,25 +409,125 @@ interface MatterfactAgentProps {
      */
     onEvent?: (e: MatterfactEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey: publishableKeyProp, widgetOrigin: widgetOriginProp, surface, theme: themeProp, getAuthToken: getAuthTokenProp, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
-    /** The artifact's slug/name. */
-    slug: string;
+    /** The artifact's name (its slug). */
+    name?: string;
+    /**
+     * @deprecated Use `name` instead. Still accepted as an alias — `name` wins
+     * when both are given.
+     */
+    slug?: string;
     /** The artifact owner's email — same as the Share dialog's `?owner=` param. */
     owner: string;
-    /** The artifact's read-only capability token — same as the Share dialog's `?t=` param. */
-    token: string;
-    /** Origin serving the widget (the matterfact app). Defaults to production. */
+    /**
+     * The artifact's read-only capability token — same as the Share dialog's `?t=`
+     * param. This is the standalone share-link path.
+     *
+     * @deprecated Prefer an ancestor `MatterfactAuthProvider` instead: with no
+     * `token`, the iframe authenticates the same way `MatterfactAgent` does — the
+     * provider's publishable key (`?k=`) plus the host page's origin (`?o=`) —
+     * instead of a share-link capability token. `token` still wins when both a
+     * token and a provider are present.
+     */
+    token?: string;
+    /**
+     * Origin serving the widget (the matterfact app). Defaults to production.
+     *
+     * @deprecated Prefer setting this once on `<MatterfactAuthProvider>` and
+     * letting every `<MatterfactAgent>`/`<MatterfactArtifact>` underneath inherit
+     * it. Still fully supported standalone (no provider) — resolved as
+     * `prop ?? context ?? default`.
+     */
     widgetOrigin?: string;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'auto' | 'light' | 'dark';
+    /** Applied to the `<iframe>` element the artifact renders into. */
     className?: string;
+    /** Applied to the `<iframe>` element. Merged over the default fill. */
     style?: React.CSSProperties;
+    /**
+     * Drive the artifact's declared params from your page — the company it's about, the
+     * time window, the peer set. View-only: a param change re-renders the artifact from
+     * data it already has, and never re-queries or runs the agent.
+     *
+     * Pass your whole param state; the component works out what actually changed and
+     * pushes only that. That matters, because a push is authoritative for every key it
+     * names: re-asserting a param the reader has since changed in the artifact's own
+     * control bar would silently overwrite their choice. Dropping a key stops driving it
+     * and leaves its current value alone — there is no "unset".
+     *
+     * NOTE: `MatterfactAgent`'s `setArtifactParams` steers artifacts rendered INSIDE the
+     * chat. This prop steers THIS artifact. They are different iframes; neither reaches
+     * the other.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Fired when a param changes inside the artifact — `'user'` when the reader used its
+     * control bar, `'context'` when a bound param followed the host page's context.
+     *
+     * Never fires for your own `params` pushes, so feeding this straight back into the
+     * `params` prop cannot loop.
+     */
+    onParamsChange?: (params: Record<string, unknown>, source: 'user' | 'context') => void;
 }
 /**
  * Render a matterfact artifact inline in a host page. Chrome-free, cross-origin. When a
  * MatterfactAgent is embedded on the same page, the loader sees this iframe and both
  * makes the agent aware of it and (via its token) lets the agent read its data.
+ *
+ * Two auth modes, `token` wins when both are available:
+ *  - TOKEN mode (`token` given): a standalone share link, `?t=`. This is the LIVE
+ *    third-party embed path — its `src` format must stay byte-identical.
+ *  - SESSION mode (no `token`, an ancestor `MatterfactAuthProvider` is present):
+ *    tokenless, `?k=<publishableKey>&o=<host origin>`, the same authentication
+ *    `MatterfactAgent` uses.
+ * With neither, there is no way for the iframe to authenticate, so no iframe is
+ * built at all — matching the "incomplete link" placeholder the embed artifact
+ * page itself renders for a missing owner/token.
+ */
+declare function MatterfactArtifact({ name: nameProp, slug, owner, token, widgetOrigin: widgetOriginProp, theme: themeProp, className, style, params, onParamsChange, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
+/** The two live-drivable doc params, mirroring `EmbedDocumentPage`'s `HostDocParams`. */
+type MatterfactDocParams = {
+    ticker?: string;
+    version?: string;
+};
+interface MatterfactDocProps {
+    /** The document catalog key (`EmbedDocumentPage`'s `?key=`). Fixed at mount — not
+     *  drivable via `params`, unlike `ticker`/`version`. */
+    docKey: string;
+    /** Initial ticker, seeds the iframe's `?ticker=` query param. */
+    ticker?: string;
+    /** Initial version. Always sent explicitly on the iframe `src` — defaults to
+     *  `'latest'` rather than being omitted, so the doc page never has to guess. */
+    version?: 'latest' | `${number}-${number}-${number}`;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
+    theme?: 'auto' | 'light' | 'dark';
+    /**
+     * Drive the document's ticker/version from your page after mount. Pass your whole
+     * param state; only the keys that actually changed since the last render are pushed
+     * to the iframe (as `host.docParams`), and the full set is re-sent once the iframe
+     * loads. A push is authoritative for every key it names — dropping a key stops
+     * driving it, it does not reset it. Omit this prop entirely for a static document
+     * whose ticker/version never change after mount.
+     */
+    params?: MatterfactDocParams;
+    /** Applied to the `<iframe>` element the document renders into. */
+    className?: string;
+    /** Applied to the `<iframe>` element. Merged over the default fill. */
+    style?: React.CSSProperties;
+}
+/**
+ * Render a matterfact catalog document inline in a host page — the `MatterfactArtifact`
+ * counterpart for a published document/report instead of an artifact board.
+ *
+ * ALWAYS session-authed: there's no standalone share-token mode the way
+ * `MatterfactArtifact` has, so an ancestor `MatterfactAuthProvider` is required. With
+ * none present (or a provider with no `publishableKey`), there's no way for the
+ * iframe to authenticate — matching `MatterfactArtifact`'s own no-token-no-provider
+ * decision, no iframe is built at all; the same "incomplete link" placeholder shape
+ * is rendered instead of throwing.
  */
-declare function MatterfactArtifact({ slug, owner, token, widgetOrigin, theme, className, style, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
+declare function MatterfactDoc({ docKey, ticker, version, theme: themeProp, params, className, style, }: MatterfactDocProps): react_jsx_runtime.JSX.Element;
 
-export { type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps };
+export { type HoistActionsConfig, type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps, MatterfactAuthProvider, type MatterfactAuthProviderProps, MatterfactDoc, type MatterfactDocParams, type MatterfactDocProps };

package/dist/react.d.ts

@@ -159,6 +159,44 @@ type MatterfactEvent = {
     source: 'user' | 'context';
 };
 
+interface MatterfactAuthProviderProps {
+    /**
+     * Publishable key (`pk_…`) identifying this embed app. Public and origin-scoped —
+     * meant to sit in HTML. Every `MatterfactAgent`/`MatterfactArtifact`/`MatterfactDoc`
+     * under this provider inherits it, so you set it once here rather than on each child.
+     */
+    publishableKey: string;
+    /**
+     * Origin serving the matterfact widgets (the app that hosts `/embed/*`). Defaults to
+     * production. This is the ONE place to set it — every child inherits it, and the
+     * `widgetOrigin` prop on `MatterfactAgent`/`MatterfactArtifact` is deprecated in
+     * favour of setting it here.
+     */
+    widgetOrigin?: string;
+    /**
+     * HOST-AUTH PASSTHROUGH (trusted first-party embeds). Return a token this matterfact
+     * deployment already trusts — the host app's Entra/Firebase token, whatever its auth
+     * provider verifies — and every child iframe signs in SILENTLY with it, no separate
+     * sign-in. The provider brokers it: when a child needs auth it asks the provider,
+     * which calls this and hands the token back (over `postMessage`, pinned to the widget
+     * origin). Called on demand so the token can be fresh; may be async. Omit for the
+     * standard interactive sign-in.
+     */
+    getAuthToken?: () => string | null | Promise<string | null>;
+    /** Colour theme applied to every child widget. Falls back to `'auto'`. */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Unified telemetry hook, fired for every embed lifecycle moment (`ready`, `auth`,
+     * `error`, …) across the children — pipe the whole embed into your own observability
+     * from one place. Never blocks or breaks a widget; a throw here is swallowed.
+     */
+    onEvent?: (e: MatterfactEvent) => void;
+    /** The embed components (`MatterfactAgent`/`MatterfactArtifact`/`MatterfactDoc`) that
+     *  inherit this provider's config. */
+    children: React.ReactNode;
+}
+declare function MatterfactAuthProvider({ publishableKey, widgetOrigin, getAuthToken, theme, onEvent, children, }: MatterfactAuthProviderProps): react_jsx_runtime.JSX.Element;
+
 /**
  * The Hoist adapter — a pure transform from a `HoistRuntime` (already read out of
  * `window.XH` by hoist-runtime.ts) into the context/snapshot shapes context.ts sends
@@ -239,12 +277,25 @@ interface HostToolDef {
 }
 
 interface MatterfactAgentProps {
-    /** Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped. */
-    publishableKey: string;
-    /** Origin serving the widget (the matterfact app). Defaults to production. */
+    /**
+     * Publishable key (`pk_…`) identifying this embed app. Public, origin-scoped.
+     *
+     * Optional here ONLY because it can instead come from an ancestor
+     * `MatterfactAuthProvider` (`prop ?? context`) — one of the two must supply it,
+     * or the component throws at mount.
+     */
+    publishableKey?: string;
+    /**
+     * Origin serving the widget (the matterfact app). Defaults to production.
+     *
+     * @deprecated Prefer setting this once on `<MatterfactAuthProvider>` and letting
+     * every `<MatterfactAgent>`/`<MatterfactArtifact>` underneath inherit it. Still
+     * fully supported standalone (no provider) — resolved as `prop ?? context ?? default`.
+     */
     widgetOrigin?: string;
     /** Label for THIS embedding, for per-surface usage/history attribution. */
     surface?: string;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'light' | 'dark' | 'auto';
     /**
      * HOST-AUTH PASSTHROUGH (trusted first-party embeds only). Return a token this
@@ -252,6 +303,8 @@ interface MatterfactAgentProps {
      * token, whatever its auth provider verifies — and the widget signs in SILENTLY with
      * it, no separate sign-in. Called on demand so the token can be fresh. Omit for the
      * standard popup/inline sign-in (third-party hosts).
+     *
+     * Resolved as `prop ?? MatterfactAuthProvider's getAuthToken`.
      */
     getAuthToken?: () => string | null | Promise<string | null>;
     /**
@@ -356,25 +409,125 @@ interface MatterfactAgentProps {
      */
     onEvent?: (e: MatterfactEvent) => void;
 }
-declare function MatterfactAgent({ publishableKey, widgetOrigin, surface, theme, getAuthToken, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
+declare function MatterfactAgent({ publishableKey: publishableKeyProp, widgetOrigin: widgetOriginProp, surface, theme: themeProp, getAuthToken: getAuthTokenProp, getPageContext, inline, className, style, pageContext, dev, actions, sitemap, artifacts, resolve, tools, onToolEvent, onEvent, }: MatterfactAgentProps): react_jsx_runtime.JSX.Element | null;
 interface MatterfactArtifactProps {
-    /** The artifact's slug/name. */
-    slug: string;
+    /** The artifact's name (its slug). */
+    name?: string;
+    /**
+     * @deprecated Use `name` instead. Still accepted as an alias — `name` wins
+     * when both are given.
+     */
+    slug?: string;
     /** The artifact owner's email — same as the Share dialog's `?owner=` param. */
     owner: string;
-    /** The artifact's read-only capability token — same as the Share dialog's `?t=` param. */
-    token: string;
-    /** Origin serving the widget (the matterfact app). Defaults to production. */
+    /**
+     * The artifact's read-only capability token — same as the Share dialog's `?t=`
+     * param. This is the standalone share-link path.
+     *
+     * @deprecated Prefer an ancestor `MatterfactAuthProvider` instead: with no
+     * `token`, the iframe authenticates the same way `MatterfactAgent` does — the
+     * provider's publishable key (`?k=`) plus the host page's origin (`?o=`) —
+     * instead of a share-link capability token. `token` still wins when both a
+     * token and a provider are present.
+     */
+    token?: string;
+    /**
+     * Origin serving the widget (the matterfact app). Defaults to production.
+     *
+     * @deprecated Prefer setting this once on `<MatterfactAuthProvider>` and
+     * letting every `<MatterfactAgent>`/`<MatterfactArtifact>` underneath inherit
+     * it. Still fully supported standalone (no provider) — resolved as
+     * `prop ?? context ?? default`.
+     */
     widgetOrigin?: string;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
     theme?: 'auto' | 'light' | 'dark';
+    /** Applied to the `<iframe>` element the artifact renders into. */
     className?: string;
+    /** Applied to the `<iframe>` element. Merged over the default fill. */
     style?: React.CSSProperties;
+    /**
+     * Drive the artifact's declared params from your page — the company it's about, the
+     * time window, the peer set. View-only: a param change re-renders the artifact from
+     * data it already has, and never re-queries or runs the agent.
+     *
+     * Pass your whole param state; the component works out what actually changed and
+     * pushes only that. That matters, because a push is authoritative for every key it
+     * names: re-asserting a param the reader has since changed in the artifact's own
+     * control bar would silently overwrite their choice. Dropping a key stops driving it
+     * and leaves its current value alone — there is no "unset".
+     *
+     * NOTE: `MatterfactAgent`'s `setArtifactParams` steers artifacts rendered INSIDE the
+     * chat. This prop steers THIS artifact. They are different iframes; neither reaches
+     * the other.
+     */
+    params?: Record<string, unknown>;
+    /**
+     * Fired when a param changes inside the artifact — `'user'` when the reader used its
+     * control bar, `'context'` when a bound param followed the host page's context.
+     *
+     * Never fires for your own `params` pushes, so feeding this straight back into the
+     * `params` prop cannot loop.
+     */
+    onParamsChange?: (params: Record<string, unknown>, source: 'user' | 'context') => void;
 }
 /**
  * Render a matterfact artifact inline in a host page. Chrome-free, cross-origin. When a
  * MatterfactAgent is embedded on the same page, the loader sees this iframe and both
  * makes the agent aware of it and (via its token) lets the agent read its data.
+ *
+ * Two auth modes, `token` wins when both are available:
+ *  - TOKEN mode (`token` given): a standalone share link, `?t=`. This is the LIVE
+ *    third-party embed path — its `src` format must stay byte-identical.
+ *  - SESSION mode (no `token`, an ancestor `MatterfactAuthProvider` is present):
+ *    tokenless, `?k=<publishableKey>&o=<host origin>`, the same authentication
+ *    `MatterfactAgent` uses.
+ * With neither, there is no way for the iframe to authenticate, so no iframe is
+ * built at all — matching the "incomplete link" placeholder the embed artifact
+ * page itself renders for a missing owner/token.
+ */
+declare function MatterfactArtifact({ name: nameProp, slug, owner, token, widgetOrigin: widgetOriginProp, theme: themeProp, className, style, params, onParamsChange, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
+/** The two live-drivable doc params, mirroring `EmbedDocumentPage`'s `HostDocParams`. */
+type MatterfactDocParams = {
+    ticker?: string;
+    version?: string;
+};
+interface MatterfactDocProps {
+    /** The document catalog key (`EmbedDocumentPage`'s `?key=`). Fixed at mount — not
+     *  drivable via `params`, unlike `ticker`/`version`. */
+    docKey: string;
+    /** Initial ticker, seeds the iframe's `?ticker=` query param. */
+    ticker?: string;
+    /** Initial version. Always sent explicitly on the iframe `src` — defaults to
+     *  `'latest'` rather than being omitted, so the doc page never has to guess. */
+    version?: 'latest' | `${number}-${number}-${number}`;
+    /** Resolved as `prop ?? MatterfactAuthProvider's theme ?? 'auto'`. */
+    theme?: 'auto' | 'light' | 'dark';
+    /**
+     * Drive the document's ticker/version from your page after mount. Pass your whole
+     * param state; only the keys that actually changed since the last render are pushed
+     * to the iframe (as `host.docParams`), and the full set is re-sent once the iframe
+     * loads. A push is authoritative for every key it names — dropping a key stops
+     * driving it, it does not reset it. Omit this prop entirely for a static document
+     * whose ticker/version never change after mount.
+     */
+    params?: MatterfactDocParams;
+    /** Applied to the `<iframe>` element the document renders into. */
+    className?: string;
+    /** Applied to the `<iframe>` element. Merged over the default fill. */
+    style?: React.CSSProperties;
+}
+/**
+ * Render a matterfact catalog document inline in a host page — the `MatterfactArtifact`
+ * counterpart for a published document/report instead of an artifact board.
+ *
+ * ALWAYS session-authed: there's no standalone share-token mode the way
+ * `MatterfactArtifact` has, so an ancestor `MatterfactAuthProvider` is required. With
+ * none present (or a provider with no `publishableKey`), there's no way for the
+ * iframe to authenticate — matching `MatterfactArtifact`'s own no-token-no-provider
+ * decision, no iframe is built at all; the same "incomplete link" placeholder shape
+ * is rendered instead of throwing.
  */
-declare function MatterfactArtifact({ slug, owner, token, widgetOrigin, theme, className, style, }: MatterfactArtifactProps): react_jsx_runtime.JSX.Element;
+declare function MatterfactDoc({ docKey, ticker, version, theme: themeProp, params, className, style, }: MatterfactDocProps): react_jsx_runtime.JSX.Element;
 
-export { type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps };
+export { type HoistActionsConfig, type HostResolvers, type HostToolDef, MatterfactAgent, type MatterfactAgentProps, MatterfactArtifact, type MatterfactArtifactProps, MatterfactAuthProvider, type MatterfactAuthProviderProps, MatterfactDoc, type MatterfactDocParams, type MatterfactDocProps };