npm package: @luna-editor/embedded-sdk
Description: Embedded SDK for Luna Editor - integrate scenario player into your applications
Author: Luna Editor Team
Latest version: 0.3.0

# @luna-editor/embedded-sdk

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

## Installation

```bash
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

```tsx
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

```tsx
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:**

```tsx
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:**

```tsx
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.

```tsx
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