@plitzi/plitzi-sdk 0.32.25 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @plitzi/plitzi-sdk
 
+## 0.33.0
+
+### Minor Changes
+
+- v0.33.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @plitzi/sdk-auth@0.33.0
+  - @plitzi/sdk-dev-tools@0.33.0
+  - @plitzi/sdk-elements@0.33.0
+  - @plitzi/sdk-event-bridge@0.33.0
+  - @plitzi/sdk-interactions@0.33.0
+  - @plitzi/sdk-navigation@0.33.0
+  - @plitzi/sdk-plugins@0.33.0
+  - @plitzi/sdk-schema@0.33.0
+  - @plitzi/sdk-shared@0.33.0
+  - @plitzi/sdk-style@0.33.0
+  - @plitzi/sdk-variables@0.33.0
+
 ## 0.32.25
 
 ### Patch Changes

package/dist/App.d.ts

@@ -1,4 +1,4 @@
-import { Environment, EventBridgeContextValue, OfflineDataRaw, RenderMode, Server, RuntimeStateInstance, SSRRenderResult } from '@plitzi/sdk-shared';
+import { AnalyticsConfig, Environment, EventBridgeContextValue, OfflineDataRaw, RenderMode, Server, RuntimeStateInstance } from '@plitzi/sdk-shared';
 import { ReactNode } from 'react';
 export type AppProps = {
     className?: string;
@@ -19,10 +19,11 @@ export type AppProps = {
      *  own (an MCP widget rendered inside a chat, a component mounted in a host app). */
     branding?: boolean;
     externalStyle?: string;
+    /** Reporting channel for this render — see {@link AnalyticsConfig}. Absent means report nothing. */
+    analytics?: AnalyticsConfig;
     state?: Record<string, unknown>;
     onInitStateManager?: (instance: RuntimeStateInstance) => void;
     onInitEventBridge?: (instance: EventBridgeContextValue) => void;
-    ssrResult?: SSRRenderResult;
 };
 declare const App: ({ className, children, webKey, server, renderMode, debugMode: debugModeProp, state, ...sdkProps }: AppProps) => import("react").JSX.Element;
 export default App;

package/dist/index.d.ts

@@ -10,10 +10,12 @@ import { default as ReplicaProvider } from '@plitzi/sdk-elements/Element/Replica
 import { default as RootElement } from '@plitzi/sdk-elements/Element/RootElement';
 import { default as ComponentContext } from '@plitzi/sdk-shared/elements/ComponentContext';
 import { PlitziServiceProvider } from '@plitzi/sdk-shared/hooks/usePlitziServiceContext';
+import { useSdkStore } from '@plitzi/sdk-shared/store';
+import { track } from './modules/Analytics';
 import { ElementContextValue } from '@plitzi/sdk-elements/Element/ElementContext';
 import { default as EventBridge } from '@plitzi/sdk-event-bridge';
 import { default as InteractionsManager } from '@plitzi/sdk-interactions/InteractionsManager';
-import { Element, Schema, Style, ComponentPluginFC, ComponentPlugin, InteractionCallback, InteractionCallbackParamValues, Environment, EventBridgeContextValue, OfflineDataRaw, RenderMode, Server, RuntimeStateInstance, SSRRenderResult, PlitziServiceContextValue as BasePlitziServiceContextValue } from '@plitzi/sdk-shared';
+import { AnalyticsConfig, Element, Schema, Style, ComponentPluginFC, ComponentPlugin, InteractionCallback, InteractionCallbackParamValues, Environment, EventBridgeContextValue, OfflineDataRaw, RenderMode, Server, RuntimeStateInstance, PlitziServiceContextValue as BasePlitziServiceContextValue } from '@plitzi/sdk-shared';
 import { ReactNode } from 'react';
 export declare function render(widgetContainer: string, params?: PlitziSdkProps, plugins?: Record<string, {
     component: ComponentPlugin;
@@ -44,8 +46,10 @@ export type PlitziSdkProps = {
     branding?: boolean;
     externalStyle?: string;
     sdkDevToolsStylePath?: string;
+    /** Where this render reports SPA navigations and interactions, and with what key. Injected by a server that
+     *  renders the page; derived from `server` + `webKey` for a client-side render; absent means report nothing. */
+    analytics?: AnalyticsConfig;
     state?: Record<string, unknown>;
-    ssrResult?: SSRRenderResult;
 };
 declare const PlitziSdk: {
     ({ debugMode, isHydrating, children, webKey, environment, renderMode, ...otherProps }: PlitziSdkProps): import("react").JSX.Element;
@@ -53,8 +57,8 @@ declare const PlitziSdk: {
 };
 type PlitziServiceContextValue = BasePlitziServiceContextValue<InstanceType<typeof EventBridge>, InstanceType<typeof InteractionsManager>>;
 declare const usePlitziServiceContext: () => PlitziServiceContextValue;
-export { ComponentProvider, ComponentContext, usePlitziServiceContext, PlitziServiceProvider, RootElement, withElement, JsxManager, PluginManager, sdkComponents, PluginRemote, ReplicaProvider, useElement, useRscData };
-export type { ElementContextValue, Element, Schema, Style, ComponentPlugin, ComponentPluginFC, PlitziServiceContextValue, OfflineDataRaw, InteractionCallback, InteractionCallbackParamValues };
+export { track, useSdkStore as useStore, ComponentProvider, ComponentContext, usePlitziServiceContext, PlitziServiceProvider, RootElement, withElement, JsxManager, PluginManager, sdkComponents, PluginRemote, ReplicaProvider, useElement, useRscData };
+export type { AnalyticsConfig, ElementContextValue, Element, Schema, Style, ComponentPlugin, ComponentPluginFC, PlitziServiceContextValue, OfflineDataRaw, InteractionCallback, InteractionCallbackParamValues };
 export declare const version: string;
 export declare const getStateManager: () => RuntimeStateInstance;
 export declare const getEventBridge: () => EventBridgeContextValue;

package/dist/index.html

@@ -58,7 +58,7 @@
         'plitzi',
         {
           webKey:
-            'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7InNwYWNlSWQiOjF9LCJpc3MiOiJodHRwczovL3NlcnZlci5wbGl0emkubG9jYWwiLCJhdWQiOlsiaHR0cHM6Ly9hcHAucGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9zc3IucGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9zZXJ2ZXIucGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9hcGkucGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9tY3AucGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9hcHAucGxpdHppLmxvY2FsOjMwMDAiLCJodHRwczovL2FwcC5wbGl0emkubG9jYWw6MzAwMSIsImh0dHBzOi8vd2Vic2l0ZS5wbGl0emkuYXBwIl0sInZlcnNpb24iOjEsImV4cCI6MTc4NzUxNzU3OSwiaWF0IjoxNzg0ODg3NTgzLCJuYmYiOjE3ODQ4ODc1ODN9.p5IEtdMhZrpampKtiWVuAUI6keMAAqtXmpdgL10A-6k',
+            'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwib3JpZ2lucyI6WyJodHRwczovL3dlYnNpdGUucGxpdHppLmFwcCIsImh0dHBzOi8vcGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9hcHAucGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9hcHAucGxpdHppLmxvY2FsOjMwMDAiLCJodHRwczovL2FwcC5wbGl0emkubG9jYWw6MzAwMSIsImh0dHBzOi8vc3NyLnBsaXR6aS5sb2NhbCIsImh0dHBzOi8vc2VydmVyLnBsaXR6aS5sb2NhbCIsImh0dHA6Ly9sb2NhbGhvc3Q6MzAwMCIsImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MCIsImh0dHA6Ly8xMjcuMC4wLjE6ODA4MCJdLCJpc3MiOiJodHRwczovL3NlcnZlci5wbGl0emkubG9jYWwiLCJhdWQiOlsiaHR0cHM6Ly9wbGl0emkubG9jYWwiLCJodHRwczovL2FwcC5wbGl0emkubG9jYWwiLCJodHRwczovL2FwcC5wbGl0emkubG9jYWw6MzAwMCIsImh0dHBzOi8vYXBwLnBsaXR6aS5sb2NhbDozMDAxIiwiaHR0cHM6Ly9hcGkucGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9zc3IucGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9zZXJ2ZXIucGxpdHppLmxvY2FsIiwiaHR0cHM6Ly9tY3AucGxpdHppLmxvY2FsIl0sInNjb3BlIjoic3BhY2U6cmVuZGVyIiwiaWF0IjoxNzg2NjU5NTg5LCJqdGkiOiJjMjRhZjMwN2Q1YTgzZmNjIiwibmJmIjoxNzg2NjU5NTg5fQ.q3-yIi5TmY8SLghX5q3jpN2qqsGJbDIF9dcVJvfLbfY',
           environment: 'main',
           revision: 0,
           renderMode: 'raw',

package/dist/modules/Analytics/AnalyticsReporter.d.ts

@@ -0,0 +1,16 @@
+import { AnalyticsConfig } from '@plitzi/sdk-shared';
+export type AnalyticsReporterProps = {
+    analytics?: AnalyticsConfig;
+};
+/**
+ * Renders nothing; reports what only the browser can see.
+ *
+ * It exists at all because the server sees a visit once — the SSR render, or the schema fetch of a
+ * client-side render — and then never again, however long the visitor stays or however many routes they move
+ * through. Those are this component's, along with named interactions.
+ *
+ * `firstViewCounted` is the seam between the two: when the server already counted this page load, the first
+ * render here would be the same view a second time, so it is skipped and only subsequent routes are reported.
+ */
+declare const AnalyticsReporter: ({ analytics }: AnalyticsReporterProps) => null;
+export default AnalyticsReporter;

package/dist/modules/Analytics/createReporter.d.ts

@@ -0,0 +1,37 @@
+import { AnalyticsConfig } from '@plitzi/sdk-shared';
+export type ReporterEvent = {
+    id: string;
+    type: 'render' | 'interaction' | 'custom';
+    ts: number;
+    page: {
+        path: string;
+        title?: string;
+    };
+    ref?: {
+        referrer?: string;
+        utm?: Record<string, string>;
+    };
+    name?: string;
+    props?: Record<string, string | number | boolean>;
+};
+export type Reporter = {
+    /** A page came into view — the first paint of a client-side render, or an SPA route change. */
+    trackRender: () => void;
+    /** A named thing the visitor did. */
+    track: (name: string, props?: Record<string, string | number | boolean>) => void;
+    /** Sends whatever is queued. Called on a full batch, on a timer, and when the page goes away. */
+    flush: () => void;
+    /** Stops the timer and sends what is left. */
+    stop: () => void;
+};
+/**
+ * The browser's half of analytics: SPA route changes, named interactions, and the first view of a render the
+ * server never saw. It reports what only the browser knows, and it is trusted with nothing else — the page
+ * views behind an invoice are counted server-side, at the SSR render and the schema fetch, where a visitor
+ * has no say. So a hostile client here can pollute a dashboard, never a bill.
+ *
+ * Events are batched and sent with `sendBeacon`, which survives the page going away — the flush on
+ * `visibilitychange` is the only one that reliably runs on a real navigation, and it is exactly the one that
+ * `fetch` would have lost.
+ */
+export declare const createReporter: (config: AnalyticsConfig, batchSize?: number, flushIntervalMs?: number) => Reporter;

package/dist/modules/Analytics/index.d.ts

@@ -0,0 +1,3 @@
+export { default as AnalyticsReporter } from './AnalyticsReporter';
+export { track } from './reporterRegistry';
+export type { Reporter } from './createReporter';

package/dist/modules/Analytics/reporterRegistry.d.ts

@@ -0,0 +1,6 @@
+import { Reporter } from './createReporter';
+export declare const setReporter: (reporter: Reporter | undefined) => void;
+export declare const getReporter: () => Reporter | undefined;
+/** Reports a named interaction. A no-op when this render reports nothing (an offline export, an embedded
+ *  widget, a deployment with no collector configured) — never an error a page has to guard against. */
+export declare const track: (name: string, props?: Record<string, string | number | boolean>) => void;

package/dist/modules/Analytics/reporterRegistry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/App/AppMain.d.ts

@@ -1,4 +1,4 @@
-import { Environment, Server, RenderMode, RuntimeStateInstance, EventBridgeContextValue, OfflineDataRaw, SSRRenderResult } from '@plitzi/sdk-shared';
+import { AnalyticsConfig, Environment, Server, RenderMode, RuntimeStateInstance, EventBridgeContextValue, OfflineDataRaw } from '@plitzi/sdk-shared';
 export type AppMainProps = {
     revision?: number;
     webKey?: string;
@@ -17,10 +17,10 @@ export type AppMainProps = {
     previewMode?: boolean;
     debugMode?: boolean;
     branding?: boolean;
+    analytics?: AnalyticsConfig;
     state?: Record<string, unknown>;
     onInitStateManager?: (instance: RuntimeStateInstance) => void;
     onInitEventBridge?: (instance: EventBridgeContextValue) => void;
-    ssrResult?: SSRRenderResult;
 };
-declare const AppMain: ({ revision, webKey, webId, environment, currentPageId, server, isHydrating, offlineMode, offlineData, offlineDataType, instanceId, renderMode, sdkStylePath, sdkDevToolsStylePath, previewMode, debugMode, onInitEventBridge, onInitStateManager, ssrResult, ...sdkProps }: AppMainProps) => import("react").JSX.Element;
+declare const AppMain: ({ revision, webKey, webId, environment, currentPageId, server, isHydrating, offlineMode, offlineData, offlineDataType, instanceId, renderMode, sdkStylePath, sdkDevToolsStylePath, previewMode, debugMode, analytics, onInitEventBridge, onInitStateManager, ...sdkProps }: AppMainProps) => import("react").JSX.Element;
 export default AppMain;

package/dist/modules/App/useDebugShortcut.d.ts

@@ -0,0 +1,13 @@
+export type UseDebugShortcutProps = {
+    /** The page's own authorization — the `debugMode` the SDK was mounted with, never anything the visitor can set. */
+    authorized: boolean;
+    onToggle: () => void;
+};
+/**
+ * shift+F12 shows or hides the dev tools on a page that was already allowed to show them; it cannot grant that
+ * permission. The environment is deliberately not part of the rule — whoever mounts the SDK may well want to debug a
+ * production space — but a visitor of a site that never asked for debugging must not reach the panel, the element
+ * ids or the store by knowing the shortcut.
+ */
+declare const useDebugShortcut: ({ authorized, onToggle }: UseDebugShortcutProps) => void;
+export default useDebugShortcut;

package/dist/modules/App/useDebugShortcut.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/Navigation/NavigationProvider.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode } from 'react';
+export type NavigationProviderProps = {
+    children: ReactNode;
+    currentPageId?: string;
+};
+declare const NavigationProvider: ({ children, currentPageId: currentPageIdProp }: NavigationProviderProps) => string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+export default NavigationProvider;

package/dist/modules/Network/NetworkContextProvider.d.ts

@@ -1,4 +1,4 @@
-import { Environment, OfflineDataRaw, Server } from '@plitzi/sdk-shared';
+import { OfflineDataRaw, Server } from '@plitzi/sdk-shared';
 import { ReactNode } from 'react';
 export type NetworkContextProviderProps = {
     children: ReactNode;
@@ -8,11 +8,9 @@ export type NetworkContextProviderProps = {
     webId: number;
     userKey?: string;
     instanceId?: string;
-    environment?: Environment;
     offlineMode?: boolean;
     offlineData?: OfflineDataRaw;
     offlineDataType?: 'json' | 'yaml';
-    debugMode?: boolean;
 };
-declare const NetworkContextProvider: ({ children, server, revision, webKey, webId, userKey, instanceId, environment, offlineMode, offlineData, offlineDataType, debugMode }: NetworkContextProviderProps) => import("react").JSX.Element | null;
+declare const NetworkContextProvider: ({ children, server, revision, webKey, webId, userKey, instanceId, offlineMode, offlineData, offlineDataType }: NetworkContextProviderProps) => import("react").JSX.Element | null;
 export default NetworkContextProvider;

package/dist/modules/Plugins/PluginsContextProvider.d.ts

@@ -1,9 +1,8 @@
-import { ComponentDefinition, RenderMode } from '@plitzi/sdk-shared';
+import { ComponentDefinition } from '@plitzi/sdk-shared';
 export type PluginsContextProviderProps = {
     children: React.ReactNode;
-    renderMode?: RenderMode;
     plugins?: Record<string, ComponentDefinition>;
     sdkStylePath?: string;
 };
-declare const PluginsContextProvider: ({ children, renderMode, plugins: pluginsProp, sdkStylePath }: PluginsContextProviderProps) => import("react").JSX.Element;
+declare const PluginsContextProvider: ({ children, plugins: pluginsProp, sdkStylePath }: PluginsContextProviderProps) => import("react").JSX.Element;
 export default PluginsContextProvider;

package/dist/modules/Sdk/Sdk.d.ts

@@ -1,11 +1,6 @@
-import { Environment, RenderMode, Server } from '@plitzi/sdk-shared';
+import { Server } from '@plitzi/sdk-shared';
 export type SdkProps = {
-    renderMode?: RenderMode;
     externalStyle?: string;
-    environment?: Environment;
-    isHydrating?: boolean;
-    previewMode?: boolean;
-    debugMode?: boolean;
     /** Shows the "Made in Plitzi" link over the rendered space. Off for embeds that are not a Plitzi site of their
      *  own — an MCP widget inside a chat, a component mounted in a host app. */
     branding?: boolean;
@@ -13,7 +8,7 @@ export type SdkProps = {
     server?: Server;
 };
 declare const Sdk: {
-    ({ renderMode, externalStyle, environment, previewMode, isHydrating, debugMode, branding, sdkStylePath, server }: SdkProps): import("react").JSX.Element;
+    ({ externalStyle, branding, sdkStylePath, server }: SdkProps): import("react").JSX.Element;
     Plugin: (_props: import('./SdkPlugin').SdkPluginProps) => undefined;
 };
 export default Sdk;