@foir/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,394 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Public type definitions for the Editor SDK.
+ */
+
+/** Data provided by the host when the editor initializes. */
+interface EditorInit {
+    values: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    modelKey: string;
+    recordId: string;
+    naturalKey?: string;
+    versionId: string | null;
+    variantKey: string | null;
+    locale: string | null;
+    schema: unknown;
+    mode: 'edit' | 'readonly';
+    theme: 'light' | 'dark';
+    /** Secret API key for public API access. */
+    apiKey: string;
+    /** Public API GraphQL endpoint URL (provided by host). */
+    apiUrl: string;
+    /** Config connection domain (e.g. my-store.myshopify.com) */
+    connectionDomain?: string;
+    /** How this editor is rendered in the admin UI. */
+    configMode?: 'editor' | 'sidebar';
+    /** Currently selected field keys (sidebar mode). */
+    selectedFieldKeys?: string[];
+    /** Available fields for selection (sidebar mode). */
+    selectableFields?: Array<{
+        key: string;
+        label: string;
+        type: string;
+    }>;
+    /** Locale context (sidebar mode). */
+    localeContext?: LocaleContext | null;
+}
+/** Locale context passed by the host for sidebar editors. */
+interface LocaleContext {
+    currentLocale: string;
+    sourceLocale: string;
+    isTranslating: boolean;
+    locales: Array<{
+        code: string;
+        displayName: string;
+        isDefault: boolean;
+    }>;
+}
+/** Value exposed by the EditorProvider context. */
+interface EditorContextValue {
+    /** Whether the editor has received init data from the host. */
+    isReady: boolean;
+    /** Initial data from the host (available after init). */
+    init: EditorInit | null;
+    /** Current host theme. */
+    theme: 'light' | 'dark';
+    /** Platform GraphQL client (available after init). */
+    client: PlatformClient;
+    /** Send complete form values to the host (full replacement). */
+    updateValues: (values: Record<string, unknown>) => void;
+    /** Send a single field update to the host. */
+    updateField: (path: string, value: unknown) => void;
+    /** Request the host to save the current values. */
+    requestSave: () => void;
+    /** Request the host to publish the current version. */
+    requestPublish: () => void;
+    /** Report iframe height for auto-resize. */
+    resize: (height: number) => void;
+    /** Report dirty state (unsaved changes). */
+    setDirty: (isDirty: boolean) => void;
+    /** Request the host to navigate to an admin path. */
+    requestNavigate: (path: string) => void;
+    /** Request the host to execute a platform operation. Returns the result.
+     * `mode` controls whether the platform waits for the operation to complete
+     * ('sync') or returns immediately after queueing ('async'). Defaults to 'sync'. */
+    requestOperation: (operationKey: string, input?: Record<string, unknown>, options?: {
+        mode?: 'sync' | 'async';
+    }) => Promise<{
+        success: boolean;
+        result?: unknown;
+        error?: {
+            code: string;
+            message: string;
+        };
+    }>;
+    /** Editor mode ('editor' or 'sidebar'). */
+    configMode: 'editor' | 'sidebar';
+    /** Currently selected field keys (sidebar mode). */
+    selectedFieldKeys: string[];
+    /** Available fields for selection (sidebar mode). */
+    selectableFields: Array<{
+        key: string;
+        label: string;
+        type: string;
+    }>;
+    /** Locale context (sidebar mode). */
+    localeContext: LocaleContext | null;
+}
+/** Options for creating a PlatformClient. */
+interface PlatformClientOptions {
+    /** GraphQL endpoint URL. */
+    apiUrl: string;
+    /** API key for authentication. */
+    apiKey: string;
+}
+/** A minimal GraphQL error shape. */
+interface GraphQLError {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+/** Response shape from a GraphQL query/mutation. */
+interface GraphQLResponse<T = Record<string, unknown>> {
+    data: T | null;
+    errors?: GraphQLError[];
+}
+/** Fetch-based GraphQL client for platform API calls. */
+interface PlatformClient {
+    /** Execute a GraphQL query or mutation. */
+    query<T = Record<string, unknown>>(query: string, variables?: Record<string, unknown>): Promise<GraphQLResponse<T>>;
+}
+
+interface EditorProviderProps {
+    children: ReactNode;
+    /**
+     * Parent window origin for postMessage validation.
+     * Must be an explicit origin (e.g., 'https://admin.example.com').
+     * Falls back to VITE_PARENT_ORIGIN or NEXT_PUBLIC_PARENT_ORIGIN env var.
+     */
+    parentOrigin?: string;
+    /**
+     * Platform API URL for GraphQL requests.
+     * Falls back to VITE_API_URL or NEXT_PUBLIC_API_URL env var.
+     */
+    apiUrl?: string;
+    onInit?: (init: EditorInit) => void;
+    onValuesChanged?: (values: Record<string, unknown>) => void;
+    onVariantChanged?: (variantKey: string, values: Record<string, unknown>) => void;
+    onSaveResult?: (success: boolean, error?: string, versionId?: string) => void;
+    onPublishResult?: (success: boolean, error?: string) => void;
+    onThemeChanged?: (theme: 'light' | 'dark') => void;
+    onSelectionChanged?: (keys: string[], fields: Array<{
+        key: string;
+        label: string;
+        type: string;
+    }>) => void;
+    onLocaleChanged?: (locale: LocaleContext) => void;
+}
+declare function EditorProvider({ children, parentOrigin: parentOriginProp, apiUrl: apiUrlProp, onInit, onValuesChanged, onVariantChanged, onSaveResult, onPublishResult, onThemeChanged, onSelectionChanged, onLocaleChanged, }: EditorProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Access the Foir editor context.
+ *
+ * Must be used inside an `<EditorProvider>`.
+ *
+ * @example
+ * ```tsx
+ * function MyEditor() {
+ *   const { isReady, init, client, updateField, setDirty } = useEditor();
+ *   if (!isReady) return <p>Loading...</p>;
+ *   return <form>...</form>;
+ * }
+ * ```
+ */
+declare function useEditor(): EditorContextValue;
+
+interface UseAutoResizeOptions {
+    /** Minimum height to report (prevents too-small iframes). @default 400 */
+    minHeight?: number;
+    /** Debounce delay in milliseconds. @default 100 */
+    debounce?: number;
+    /** Whether auto-resize is enabled. @default true */
+    enabled?: boolean;
+}
+/**
+ * Automatically resize the host iframe based on content height.
+ *
+ * @returns A callback ref to attach to your root container element.
+ *
+ * @example
+ * ```tsx
+ * function MyEditor() {
+ *   const containerRef = useAutoResize({ minHeight: 600 });
+ *   return <div ref={containerRef}>...</div>;
+ * }
+ * ```
+ */
+declare function useAutoResize(options?: UseAutoResizeOptions): (node: HTMLDivElement | null) => void;
+
+/**
+ * Fetch-based GraphQL client for the EIDE platform API.
+ *
+ * Zero dependencies — uses the native Fetch API.
+ */
+
+/** Error thrown when a platform API request fails. */
+declare class PlatformClientError extends Error {
+    status?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, response?: unknown | undefined);
+}
+/**
+ * Create a PlatformClient instance.
+ *
+ * @example
+ * ```ts
+ * const client = createPlatformClient({
+ *   apiUrl: 'https://api.example.com/graphql',
+ *   apiKey: 'sk_test_...',
+ * });
+ *
+ * const { data } = await client.query(
+ *   `query GetProduct($id: ID!) { product(id: $id) { title } }`,
+ *   { id: '123' }
+ * );
+ * ```
+ */
+declare function createPlatformClient(options: PlatformClientOptions): PlatformClient;
+
+/**
+ * PostMessage protocol types between EIDE platform host and extension iframes.
+ *
+ * Inlined from the platform protocol to keep the SDK zero-dep.
+ */
+/**
+ * Messages sent FROM the platform host TO the iframe extension.
+ */
+type HostToEditorMessage = {
+    type: 'init';
+    payload: {
+        values: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+        modelKey: string;
+        recordId: string;
+        naturalKey?: string;
+        versionId: string | null;
+        variantKey: string | null;
+        locale: string | null;
+        schema: unknown;
+        mode: 'edit' | 'readonly';
+        theme: 'light' | 'dark';
+        apiKey: string;
+        apiUrl: string;
+        connectionDomain?: string;
+        configMode?: 'editor' | 'sidebar';
+        selectedFieldKeys?: string[];
+        selectableFields?: Array<{
+            key: string;
+            label: string;
+            type: string;
+        }>;
+        localeContext?: {
+            currentLocale: string;
+            sourceLocale: string;
+            isTranslating: boolean;
+            locales: Array<{
+                code: string;
+                displayName: string;
+                isDefault: boolean;
+            }>;
+        };
+    };
+} | {
+    type: 'values-changed';
+    payload: {
+        values: Record<string, unknown>;
+        source: 'remote';
+    };
+} | {
+    type: 'variant-changed';
+    payload: {
+        variantKey: string;
+        values: Record<string, unknown>;
+    };
+} | {
+    type: 'save-result';
+    payload: {
+        success: boolean;
+        error?: string;
+        versionId?: string;
+    };
+} | {
+    type: 'publish-result';
+    payload: {
+        success: boolean;
+        error?: string;
+    };
+} | {
+    type: 'theme-changed';
+    payload: {
+        theme: 'light' | 'dark';
+    };
+} | {
+    type: 'selection-changed';
+    payload: {
+        selectedFieldKeys: string[];
+        fields: Array<{
+            key: string;
+            label: string;
+            type: string;
+        }>;
+    };
+} | {
+    type: 'locale-changed';
+    payload: {
+        currentLocale: string;
+        sourceLocale: string;
+        isTranslating: boolean;
+        locales: Array<{
+            code: string;
+            displayName: string;
+            isDefault: boolean;
+        }>;
+    };
+} | {
+    type: 'operation-result';
+    payload: {
+        requestId: string;
+        success: boolean;
+        result?: unknown;
+        error?: {
+            code: string;
+            message: string;
+        };
+    };
+};
+/**
+ * Messages sent FROM the iframe extension TO the platform host.
+ */
+type EditorToHostMessage = {
+    type: 'ready';
+    payload: Record<string, never>;
+} | {
+    type: 'update-values';
+    payload: {
+        values: Record<string, unknown>;
+    };
+} | {
+    type: 'update-field';
+    payload: {
+        path: string;
+        value: unknown;
+    };
+} | {
+    type: 'request-save';
+    payload: Record<string, never>;
+} | {
+    type: 'request-publish';
+    payload: Record<string, never>;
+} | {
+    type: 'resize';
+    payload: {
+        height: number;
+    };
+} | {
+    type: 'dirty';
+    payload: {
+        isDirty: boolean;
+    };
+} | {
+    type: 'request-navigate';
+    payload: {
+        path: string;
+    };
+} | {
+    type: 'request-operation';
+    payload: {
+        operationKey: string;
+        input?: Record<string, unknown>;
+        requestId: string;
+        /** Execution mode: 'sync' waits for completion, 'async' queues and returns. */
+        mode?: 'sync' | 'async';
+    };
+};
+
+/**
+ * Runtime validation for postMessage payloads.
+ */
+
+/** Validate an incoming message from a custom editor iframe (editor -> host). */
+declare function isValidEditorMessage(data: unknown): data is EditorToHostMessage;
+/** Validate an incoming message from the platform host (host -> editor). */
+declare function isValidHostMessage(data: unknown): data is HostToEditorMessage;
+
+/** Protocol version for compatibility checks. */
+declare const PROTOCOL_VERSION = "1.0";
+
+export { type EditorContextValue, type EditorInit, EditorProvider, type EditorProviderProps, type EditorToHostMessage, type GraphQLError, type GraphQLResponse, type HostToEditorMessage, type LocaleContext, PROTOCOL_VERSION, type PlatformClient, PlatformClientError, type PlatformClientOptions, type UseAutoResizeOptions, createPlatformClient, isValidEditorMessage, isValidHostMessage, useAutoResize, useEditor };