Client API Reference

import { EditorProvider } from '@eide/foir-editor-sdk';
 
function App() {
  return (
    <EditorProvider
      parentOrigin="https://app.foir.dev"
      onInit={(init) => console.log('Editor initialized', init.modelKey)}
      onSaveResult={(success, error) => {
        if (!success) console.error('Save failed:', error);
      }}
    >
      <MyEditor />
    </EditorProvider>
  );
}

interface EditorProviderProps {
  children: ReactNode;
  parentOrigin?: string;
  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;
}

import { useEditor } from '@eide/foir-editor-sdk';
 
function MyEditor() {
  const {
    isReady,
    init,
    theme,
    client,
    updateField,
    updateValues,
    requestSave,
    requestPublish,
    requestOperation,
    resize,
    setDirty,
    requestNavigate,
    configMode,
    selectedFieldKeys,
    selectableFields,
    localeContext,
  } = useEditor();
 
  if (!isReady) return null;
  // ...
}

interface EditorContextValue {
  isReady: boolean;
  init: EditorInit | null;
  theme: 'light' | 'dark';
  client: PlatformClient;
  updateValues: (values: Record<string, unknown>) => void;
  updateField: (path: string, value: unknown) => void;
  requestSave: () => void;
  requestPublish: () => void;
  requestOperation: (
    operationKey: string,
    input?: Record<string, unknown>,
    options?: { mode?: 'sync' | 'async' }
  ) => Promise<{
    success: boolean;
    result?: unknown;
    error?: { code: string; message: string };
  }>;
  resize: (height: number) => void;
  setDirty: (isDirty: boolean) => void;
  requestNavigate: (path: string) => void;
  configMode: 'editor' | 'sidebar';
  selectedFieldKeys: string[];
  selectableFields: Array<{ key: string; label: string; type: string }>;
  localeContext: LocaleContext | null;
}

import { useAutoResize } from '@eide/foir-editor-sdk';
 
function MyEditor() {
  const containerRef = useAutoResize({ minHeight: 600 });
 
  return <div ref={containerRef}>Your editor content here</div>;
}

interface UseAutoResizeOptions {
  /** Minimum height to report. @default 400 */
  minHeight?: number;
  /** Debounce delay in milliseconds. @default 100 */
  debounce?: number;
  /** Whether auto-resize is enabled. @default true */
  enabled?: boolean;
}

import { createPlatformClient } from '@eide/foir-editor-sdk';
 
const client = createPlatformClient({
  apiUrl: 'https://api.foir.io/graphql',
  apiKey: 'sk_test_...',
});
 
const { data } = await client.query<{ product: { title: string } }>(
  `query GetProduct($id: ID!) { product(id: $id) { title } }`,
  { id: '123' }
);

interface PlatformClientOptions {
  /** GraphQL endpoint URL. */
  apiUrl: string;
  /** API key for authentication. */
  apiKey: string;
}

interface PlatformClient {
  query<T = Record<string, unknown>>(
    query: string,
    variables?: Record<string, unknown>
  ): Promise<GraphQLResponse<T>>;
}

interface GraphQLResponse<T = Record<string, unknown>> {
  data: T | null;
  errors?: GraphQLError[];
}
 
interface GraphQLError {
  message: string;
  locations?: Array<{ line: number; column: number }>;
  path?: Array<string | number>;
  extensions?: Record<string, unknown>;
}

class PlatformClientError extends Error {
  status?: number;
  response?: unknown;
}

interface EditorInit {
  /** Current record field values. */
  values: Record<string, unknown>;
  /** Record metadata (e.g., timestamps, status). */
  metadata?: Record<string, unknown>;
  /** The model key for this record (e.g., 'product', 'redirect'). */
  modelKey: string;
  /** The record ID. Empty string for new records. */
  recordId: string;
  /** Human-readable natural key (slug, handle, etc.). */
  naturalKey?: string;
  /** Current version ID, or null for unversioned records. */
  versionId: string | null;
  /** Current variant key, or null if not using variants. */
  variantKey: string | null;
  /** Current locale code, or null. */
  locale: string | null;
  /** The model's field schema definition. */
  schema: unknown;
  /** Whether the record is editable or view-only. */
  mode: 'edit' | 'readonly';
  /** Current admin theme. */
  theme: 'light' | 'dark';
  /** API key for platform GraphQL requests. */
  apiKey: string;
  /** Platform API GraphQL endpoint URL. */
  apiUrl: string;
  /** Config connection domain (e.g., my-store.myshopify.com). */
  connectionDomain?: string;
  /** How this editor is rendered: 'editor' (main area) 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 for translation workflows (sidebar mode). */
  localeContext?: LocaleContext | null;
}

interface LocaleContext {
  /** The locale currently being edited. */
  currentLocale: string;
  /** The source/default locale to translate from. */
  sourceLocale: string;
  /** Whether the user is actively in a translation workflow. */
  isTranslating: boolean;
  /** All available locales for this project. */
  locales: Array<{
    code: string;
    displayName: string;
    isDefault: boolean;
  }>;
}

import {
  isValidEditorMessage,
  isValidHostMessage,
  PROTOCOL_VERSION, // '1.0'
} from '@eide/foir-editor-sdk';