@luna-editor/embedded-sdk

Embedded SDK for Luna Editor - integrate scenario player into your applications.

Installation

npm install @luna-editor/embedded-sdk @luna-editor/engine
# or
yarn add @luna-editor/embedded-sdk @luna-editor/engine
# or
bun add @luna-editor/embedded-sdk @luna-editor/engine

Quick Start

1. Wrap your app with LunaProvider

import { LunaProvider } from '@luna-editor/embedded-sdk';

function App() {
  return (
    <LunaProvider
      config={{
        workId: "your-work-id",
        token: "emb_your_token_here",
        apiUrl: "https://your-luna-instance.com"
      }}
    >
      <YourApp />
    </LunaProvider>
  );
}

2. Use hooks to fetch data

import { usePublishedScenario } from '@luna-editor/embedded-sdk';
import { Player } from '@luna-editor/engine';

function ScenarioPlayer({ scenarioId }: { scenarioId: string }) {
  const { data: scenario, isLoading, error } = usePublishedScenario(scenarioId);

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!scenario) return <div>Scenario not found</div>;

  return <Player scenario={scenario} />;
}

API Reference

LunaProvider

Provider component that must wrap your application.

Props:

• config: LunaSdkConfig - SDK configuration
  • workId: string - Your work ID
  • token: string - Embedded API token (starts with emb_)
  • apiUrl?: string - Luna Editor API URL (default: http://localhost:3000)
• queryClient?: QueryClient - Optional React Query client
• children: ReactNode - Your app components

Hooks

usePublishedScenario(scenarioId: string)

Fetch a published scenario by ID.

Returns: UseQueryResult<PublishedScenario>

usePublishedScenarios()

Fetch all published scenarios for the work.

Returns: UseQueryResult<PublishedScenarioListItem[]>

useInstalledPlugins()

Fetch installed plugins for the work.

Returns: UseQueryResult<InstalledPlugin[]>

useSettings(schema, key, defaultValue)

Manage settings with Zod validation and localStorage persistence.

Parameters:

• schema: ZodType - Zod schema for validation
• key: string - Storage key
• defaultValue: T - Default settings value

Returns: [settings, setSettings, resetSettings]

Example:

import { useSettings } from '@luna-editor/embedded-sdk';
import { z } from 'zod';

const playerSettingsSchema = z.object({
  volume: z.number().min(0).max(1),
  autoPlay: z.boolean(),
  textSpeed: z.number().min(1).max(10),
});

function PlayerSettings() {
  const [settings, setSettings, resetSettings] = useSettings(
    playerSettingsSchema,
    'player-settings',
    { volume: 0.8, autoPlay: false, textSpeed: 5 }
  );

  return (
    <div>
      <label>
        Volume: {settings.volume}
        <input
          type="range"
          min="0"
          max="1"
          step="0.1"
          value={settings.volume}
          onChange={(e) => setSettings({ 
            ...settings, 
            volume: parseFloat(e.target.value) 
          })}
        />
      </label>
      <button onClick={resetSettings}>Reset to Defaults</button>
    </div>
  );
}

useSettingsUpdate(schema, key, defaultValue)

Similar to useSettings but returns an update function for partial updates.

Returns: [settings, updateSettings, resetSettings]

Example:

const [settings, updateSettings] = useSettingsUpdate(
  playerSettingsSchema,
  'player-settings',
  { volume: 0.8, autoPlay: false }
);

// Partial update
updateSettings({ volume: 0.5 });

LunaSdk Class

Low-level SDK class for non-React usage.

import { LunaSdk } from '@luna-editor/embedded-sdk';

const sdk = new LunaSdk({
  workId: "your-work-id",
  token: "emb_your_token_here",
  apiUrl: "https://your-luna-instance.com"
});

// Fetch scenario
const scenario = await sdk.getPublishedScenario("scenario-id");

// List scenarios
const scenarios = await sdk.listPublishedScenarios();

// Get plugins
const plugins = await sdk.getInstalledPlugins();

TypeScript Support

This package includes full TypeScript definitions.

License

MIT