@syntrologie/runtime-sdk 0.2.0

package/dist/overlays/schema.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+export const SelectorZ = z.union([
+    z.object({ type: z.literal('data'), key: z.string(), value: z.string().optional() }),
+    z.object({ type: z.literal('css'), value: z.string() }),
+    z.object({ type: z.literal('aria'), role: z.string().optional(), label: z.string().optional() }),
+    z.object({ type: z.literal('shadow-css'), value: z.string() }),
+    z.object({ type: z.literal('ref'), el: z.any() }) // runtime-only
+]);
+export const TooltipStepZ = z.object({
+    kind: z.literal('tooltip'),
+    id: z.string(),
+    anchor: SelectorZ,
+    content: z.object({ title: z.string().optional(), body: z.string() }),
+    placement: z.enum(['top', 'bottom', 'left', 'right', 'auto']).optional(),
+    offsetPx: z.number().optional(),
+    blocking: z.boolean().optional(),
+    trigger: z.enum(['immediate', 'hover', 'click']).optional(),
+    dismiss: z.object({
+        onEsc: z.boolean().optional(),
+        closeButton: z.boolean().optional(),
+        timeoutMs: z.number().optional()
+    }).optional()
+});
+export const HighlightStepZ = z.object({
+    kind: z.literal('highlight'),
+    id: z.string(),
+    anchor: SelectorZ,
+    copy: z.string().optional(),
+    ring: z.object({ paddingPx: z.number().optional(), radiusPx: z.number().optional() }).optional(),
+    scrim: z.object({ opacity: z.number().optional() }).optional(),
+    ringColor: z.string().optional(),
+    blocking: z.boolean().optional(),
+    dismiss: z.object({
+        onClickOutside: z.boolean().optional(),
+        onEsc: z.boolean().optional(),
+        timeoutMs: z.number().optional()
+    }).optional()
+});
+export const CanvasRecipeZ = z.object({
+    id: z.string(),
+    version: z.number(),
+    routes: z.array(z.string()).optional(),
+    steps: z.array(z.union([TooltipStepZ, HighlightStepZ]))
+});
+export function validateRecipe(json) {
+    return CanvasRecipeZ.parse(json);
+}
+//# sourceMappingURL=schema.js.map

package/dist/overlays/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/overlays/schema.ts"],"names":[],"mappings":"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"}

package/dist/overlays/types.d.ts

@@ -0,0 +1,68 @@
+export type Selector = {
+    type: 'data';
+    key: string;
+    value?: string;
+} | {
+    type: 'css';
+    value: string;
+} | {
+    type: 'aria';
+    role?: string;
+    label?: string;
+} | {
+    type: 'shadow-css';
+    value: string;
+} | {
+    type: 'ref';
+    el?: HTMLElement;
+};
+export type TooltipStep = {
+    kind: 'tooltip';
+    id: string;
+    anchor: Selector;
+    content: {
+        title?: string;
+        body: string;
+    };
+    placement?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    offsetPx?: number;
+    blocking?: boolean;
+    trigger?: 'immediate' | 'hover' | 'click';
+    dismiss?: {
+        onEsc?: boolean;
+        closeButton?: boolean;
+        timeoutMs?: number;
+    };
+};
+export type HighlightStep = {
+    kind: 'highlight';
+    id: string;
+    anchor: Selector;
+    copy?: string;
+    ring?: {
+        paddingPx?: number;
+        radiusPx?: number;
+    };
+    scrim?: {
+        opacity?: number;
+    };
+    ringColor?: string;
+    blocking?: boolean;
+    dismiss?: {
+        onClickOutside?: boolean;
+        onEsc?: boolean;
+        timeoutMs?: number;
+    };
+};
+export type CanvasRecipe = {
+    id: string;
+    version: number;
+    routes?: string[];
+    steps: Array<TooltipStep | HighlightStep>;
+};
+export type OverlayContext = {
+    overlayRoot: HTMLElement;
+    resolve: (sel: Selector) => Promise<HTMLElement | null>;
+    onEvent: (name: string, payload?: any) => void;
+    canvasHost?: HTMLElement | null;
+};

package/dist/overlays/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/overlays/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/overlays/types.ts"],"names":[],"mappings":""}

package/dist/react.d.ts

@@ -0,0 +1,99 @@
+/**
+ * React bindings for the Syntro SDK.
+ *
+ * Usage:
+ * ```tsx
+ * import { SyntroProvider, useSyntro } from '@syntrologie/runtime-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <SyntroProvider token="syn_xxx">
+ *       <MyApp />
+ *     </SyntroProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const { canvas, experiments, telemetry, isReady } = useSyntro();
+ *   // ...
+ * }
+ * ```
+ */
+import { type ReactNode } from "react";
+import { type SyntroInitOptions, type SyntroInitResult } from "./bootstrap";
+import type { SmartCanvasHandle } from "./api";
+import type { ExperimentClient } from "./experiments/types";
+import type { TelemetryClient } from "./telemetry/types";
+export interface SyntroContextValue {
+    /** The SmartCanvas handle */
+    canvas: SmartCanvasHandle | null;
+    /** The experiment client */
+    experiments: ExperimentClient | null;
+    /** The telemetry client */
+    telemetry: TelemetryClient | null;
+    /** Whether the SDK has finished initializing */
+    isReady: boolean;
+    /** Any error that occurred during initialization */
+    error: Error | null;
+}
+export interface SyntroProviderProps {
+    /**
+     * The Syntro token containing all credentials.
+     */
+    token: string;
+    /**
+     * Optional canvas configuration overrides.
+     */
+    canvasOptions?: SyntroInitOptions["canvas"];
+    /**
+     * Children to render.
+     */
+    children: ReactNode;
+    /**
+     * Called when initialization completes.
+     */
+    onReady?: (result: SyntroInitResult) => void;
+    /**
+     * Called when initialization fails.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Provider component that initializes the Syntro SDK.
+ *
+ * Place this at the root of your app or at the top of any subtree
+ * that needs access to the SDK.
+ */
+export declare function SyntroProvider({ token, canvasOptions, children, onReady, onError, }: SyntroProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the Syntro SDK.
+ *
+ * Must be used within a SyntroProvider.
+ *
+ * @returns The SDK context containing canvas, experiments, telemetry, and status
+ */
+export declare function useSyntro(): SyntroContextValue;
+/**
+ * Hook to check if the SDK is ready.
+ *
+ * Shorthand for `useSyntro().isReady`.
+ */
+export declare function useSyntroReady(): boolean;
+/**
+ * Hook to access the experiment client.
+ *
+ * @returns The experiment client, or null if not configured
+ */
+export declare function useSyntroExperiments(): ExperimentClient | null;
+/**
+ * Hook to access the telemetry client.
+ *
+ * @returns The telemetry client, or null if not configured
+ */
+export declare function useSyntroTelemetry(): TelemetryClient | null;
+/**
+ * Hook to access the canvas handle.
+ *
+ * @returns The canvas handle, or null if not ready
+ */
+export declare function useSyntroCanvas(): SmartCanvasHandle | null;

package/dist/react.js

@@ -0,0 +1,119 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React bindings for the Syntro SDK.
+ *
+ * Usage:
+ * ```tsx
+ * import { SyntroProvider, useSyntro } from '@syntrologie/runtime-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <SyntroProvider token="syn_xxx">
+ *       <MyApp />
+ *     </SyntroProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const { canvas, experiments, telemetry, isReady } = useSyntro();
+ *   // ...
+ * }
+ * ```
+ */
+import { createContext, useContext, useEffect, useState, useRef, } from "react";
+import { Syntro } from "./bootstrap";
+const SyntroContext = createContext(null);
+/**
+ * Provider component that initializes the Syntro SDK.
+ *
+ * Place this at the root of your app or at the top of any subtree
+ * that needs access to the SDK.
+ */
+export function SyntroProvider({ token, canvasOptions, children, onReady, onError, }) {
+    const [state, setState] = useState({
+        canvas: null,
+        experiments: null,
+        telemetry: null,
+        isReady: false,
+        error: null,
+    });
+    const initRef = useRef(false);
+    const handleRef = useRef(null);
+    useEffect(() => {
+        if (!token || initRef.current)
+            return;
+        initRef.current = true;
+        Syntro.init({ token, canvas: canvasOptions })
+            .then((result) => {
+            var _a, _b;
+            handleRef.current = result.canvas;
+            setState({
+                canvas: result.canvas,
+                experiments: (_a = result.experiments) !== null && _a !== void 0 ? _a : null,
+                telemetry: (_b = result.telemetry) !== null && _b !== void 0 ? _b : null,
+                isReady: true,
+                error: null,
+            });
+            onReady === null || onReady === void 0 ? void 0 : onReady(result);
+        })
+            .catch((err) => {
+            const error = err instanceof Error ? err : new Error(String(err));
+            setState((prev) => ({ ...prev, error, isReady: true }));
+            onError === null || onError === void 0 ? void 0 : onError(error);
+        });
+        return () => {
+            if (handleRef.current) {
+                handleRef.current.destroy();
+                handleRef.current = null;
+            }
+        };
+    }, [token]);
+    return (_jsx(SyntroContext.Provider, { value: state, children: children }));
+}
+/**
+ * Hook to access the Syntro SDK.
+ *
+ * Must be used within a SyntroProvider.
+ *
+ * @returns The SDK context containing canvas, experiments, telemetry, and status
+ */
+export function useSyntro() {
+    const context = useContext(SyntroContext);
+    if (!context) {
+        throw new Error("useSyntro must be used within a SyntroProvider");
+    }
+    return context;
+}
+/**
+ * Hook to check if the SDK is ready.
+ *
+ * Shorthand for `useSyntro().isReady`.
+ */
+export function useSyntroReady() {
+    return useSyntro().isReady;
+}
+/**
+ * Hook to access the experiment client.
+ *
+ * @returns The experiment client, or null if not configured
+ */
+export function useSyntroExperiments() {
+    return useSyntro().experiments;
+}
+/**
+ * Hook to access the telemetry client.
+ *
+ * @returns The telemetry client, or null if not configured
+ */
+export function useSyntroTelemetry() {
+    return useSyntro().telemetry;
+}
+/**
+ * Hook to access the canvas handle.
+ *
+ * @returns The canvas handle, or null if not ready
+ */
+export function useSyntroCanvas() {
+    return useSyntro().canvas;
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}