# SDK Tutorials

Complete tutorials for using the Yemaya SDKs.

## Available SDKs

| Language              | Package       | Installation                            |
| --------------------- | ------------- | --------------------------------------- |
| TypeScript/JavaScript | `@yemaya/sdk` | `npm install @yemaya/sdk`               |
| Python                | `yemaya`      | `pip install yemaya`                    |
| C++                   | `yemaya-cpp`  | See [C++ Installation](#c-installation) |

---

## TypeScript SDK

### Installation

```bash
npm install @yemaya/sdk
# or
pnpm add @yemaya/sdk
# or
yarn add @yemaya/sdk
```

### Quick Start

```typescript
import { YemayaClient } from '@yemaya/sdk';

// Initialize client
const client = new YemayaClient({
  apiKey: 'your-api-key',
  // or use access token
  // accessToken: 'your-jwt-token'
});

// Create a project
const project = await client.projects.create({
  name: 'My Game',
  type: 'game',
});

// Generate 3D model
const job = await client.threeD.generate({
  prompt: 'A cartoon cat character',
  quality: 'high',
});

// Wait for completion
const result = await job.waitForCompletion();
console.log('Model URL:', result.assets.glb);
```

### Authentication

```typescript
// API Key authentication (recommended for server-side)
const client = new YemayaClient({
  apiKey: process.env.YEMAYA_API_KEY,
});

// JWT authentication (for client-side after login)
const client = new YemayaClient({
  accessToken: userSession.accessToken,
  refreshToken: userSession.refreshToken,
  onTokenRefresh: (tokens) => {
    // Save new tokens
    saveSession(tokens);
  },
});

// Login to get tokens
const tokens = await YemayaClient.login({
  email: 'user@example.com',
  password: 'password',
});
```

### Projects

```typescript
// List projects
const projects = await client.projects.list({
  status: 'active',
  type: 'game',
  page: 1,
  limit: 20,
});

// Create project
const project = await client.projects.create({
  name: 'My New Game',
  description: 'An adventure game',
  type: 'game',
  settings: {
    targetPlatforms: ['pc', 'switch'],
    gameEngine: 'godot',
  },
});

// Get project
const details = await client.projects.get('proj_abc123');

// Update project
await client.projects.update('proj_abc123', {
  name: 'Updated Name',
});

// Delete project
await client.projects.delete('proj_abc123');

// Duplicate project
const copy = await client.projects.duplicate('proj_abc123', {
  name: 'Project Copy',
  includeAssets: true,
});
```

### Assets

```typescript
// List assets
const assets = await client.assets.list('proj_abc123', {
  type: 'model',
  folder: 'characters',
});

// Upload asset
const asset = await client.assets.upload('proj_abc123', {
  file: fs.readFileSync('model.fbx'),
  name: 'Hero Character',
  folder: 'characters',
  tags: ['character', 'hero'],
  onProgress: (progress) => {
    console.log(`Uploading: ${progress}%`);
  },
});

// Download asset
const blob = await client.assets.download('proj_abc123', 'ast_abc123');
fs.writeFileSync('downloaded.fbx', blob);

// Get asset versions
const versions = await client.assets.getVersions('proj_abc123', 'ast_abc123');

// Create new version
await client.assets.createVersion('proj_abc123', 'ast_abc123', {
  file: fs.readFileSync('model_v2.fbx'),
  changelog: 'Updated animations',
});
```

### 3D Generation

```typescript
// Text-to-3D
const job = await client.threeD.generate({
  prompt: 'A low-poly sword with glowing runes',
  provider: 'meshy',
  quality: 'high',
  style: 'stylized',
});

// Monitor progress
job.on('progress', (progress) => {
  console.log(`Progress: ${progress}%`);
});

// Wait for result
const result = await job.waitForCompletion();

// Access generated assets
console.log('GLB:', result.assets.glb);
console.log('FBX:', result.assets.fbx);
console.log('Thumbnail:', result.thumbnail);

// Image-to-3D
const imageJob = await client.threeD.generateFromImage({
  image: fs.readFileSync('reference.png'),
  quality: 'high',
  autoRig: true,
  rigType: 'humanoid',
});

// Batch generation
const batchJob = await client.threeD.batch(
  [
    { prompt: 'A wooden chair' },
    { prompt: 'A wooden table' },
    { prompt: 'A wooden cabinet' },
  ],
  {
    quality: 'standard',
    style: 'realistic',
  }
);

const results = await batchJob.waitForCompletion();
```

### Audio

```typescript
// Generate music
const musicJob = await client.audio.generateMusic({
  prompt: 'Epic orchestral battle theme',
  genre: 'orchestral',
  duration: 120,
  tempo: 140,
});

const music = await musicJob.waitForCompletion();
console.log('Music URL:', music.audioUrl);

// Voice synthesis
const voice = await client.audio.synthesize({
  text: 'Welcome, brave adventurer!',
  voiceId: 'voice_fantasy_male',
  emotion: 'excited',
});

console.log('Voice URL:', voice.audioUrl);

// Generate sound effects
const sfx = await client.audio.generateSFX({
  description: 'Sword clash with metallic ring',
  duration: 2,
  style: 'realistic',
});
```

### NPCs

```typescript
// Create NPC
const npc = await client.npcs.create({
  name: 'Elena Brightwood',
  role: 'merchant',
  projectId: 'proj_abc123',
  personality: {
    traits: ['friendly', 'shrewd'],
    values: ['fairness', 'prosperity'],
  },
  background: {
    occupation: 'General goods merchant',
    history: 'Former adventurer turned shopkeeper',
  },
});

// Chat with NPC
const response = await client.npcs.chat(npc.npcId, {
  playerId: 'player_001',
  message: 'Do you have any healing potions?',
  context: {
    location: 'shop',
    timeOfDay: 'morning',
  },
});

console.log('NPC says:', response.response);
console.log('Emotion:', response.emotion);

// Get NPC memories
const memories = await client.npcs.getMemories(npc.npcId, {
  playerId: 'player_001',
  limit: 10,
});
```

### Real-Time (WebSocket)

```typescript
// Connect to WebSocket
const realtime = client.realtime();

await realtime.connect();

// Subscribe to events
realtime.subscribe('project:proj_abc123');

// Listen for events
realtime.on('asset.uploaded', (data) => {
  console.log('New asset:', data.assetId);
});

realtime.on('generation.progress', (data) => {
  console.log(`Job ${data.jobId}: ${data.progress}%`);
});

realtime.on('generation.completed', (data) => {
  console.log('Completed:', data.jobId);
});

// Disconnect when done
realtime.disconnect();
```

### Autonomous Pipelines

```typescript
// Create autonomous project
const autonomousProject = await client.autonomous.createProject({
  type: 'game',
  prompt: 'A cozy farming simulation with anime-style graphics',
  autonomyLevel: 'guided',
  quality: 'high',
});

// Subscribe to updates
const subscription = client.autonomous.subscribe(autonomousProject.id);

subscription.on('phaseCompleted', (phase) => {
  console.log(`Completed phase: ${phase.name}`);
});

subscription.on('interventionRequired', async (intervention) => {
  console.log('Intervention needed:', intervention.reason);

  // Resolve intervention
  await client.autonomous.resolveIntervention(intervention.id, {
    selectedOption: intervention.options[0].id,
  });
});

// Wait for completion
const result = await client.autonomous.waitForCompletion(autonomousProject.id);

// Download builds
const builds = await client.autonomous.getBuilds(autonomousProject.id);
```

---

## Python SDK

### Installation

```bash
pip install yemaya
```

### Quick Start

```python
from yemaya import YemayaClient

# Initialize client
client = YemayaClient(api_key="your-api-key")

# Create a project
project = client.projects.create(
    name="My Game",
    type="game"
)

# Generate 3D model
job = client.three_d.generate(
    prompt="A cartoon cat character",
    quality="high"
)

# Wait for completion
result = job.wait_for_completion()
print(f"Model URL: {result.assets['glb']}")
```

### Authentication

```python
# API Key authentication
client = YemayaClient(api_key=os.environ["YEMAYA_API_KEY"])

# JWT authentication
client = YemayaClient(
    access_token=session["access_token"],
    refresh_token=session["refresh_token"]
)

# Login to get tokens
tokens = YemayaClient.login(
    email="user@example.com",
    password="password"
)
```

### Projects

```python
# List projects
projects = client.projects.list(
    status="active",
    type="game",
    page=1,
    limit=20
)

for project in projects.data:
    print(f"- {project.name}")

# Create project
project = client.projects.create(
    name="My New Game",
    description="An adventure game",
    type="game",
    settings={
        "targetPlatforms": ["pc", "switch"],
        "gameEngine": "godot"
    }
)

# Update project
client.projects.update(
    project_id="proj_abc123",
    name="Updated Name"
)
```

### Assets

```python
# Upload asset
with open("model.fbx", "rb") as f:
    asset = client.assets.upload(
        project_id="proj_abc123",
        file=f,
        name="Hero Character",
        folder="characters"
    )

# Download asset
data = client.assets.download(
    project_id="proj_abc123",
    asset_id="ast_abc123"
)

with open("downloaded.fbx", "wb") as f:
    f.write(data)
```

### 3D Generation

```python
# Text-to-3D
job = client.three_d.generate(
    prompt="A low-poly sword with glowing runes",
    provider="meshy",
    quality="high"
)

# Wait with progress callback
def on_progress(progress):
    print(f"Progress: {progress}%")

result = job.wait_for_completion(on_progress=on_progress)

print(f"GLB: {result.assets['glb']}")

# Batch generation
batch_job = client.three_d.batch(
    prompts=[
        "A wooden chair",
        "A wooden table",
        "A wooden cabinet"
    ],
    quality="standard"
)

results = batch_job.wait_for_completion()
```

### Audio

```python
# Generate music
music_job = client.audio.generate_music(
    prompt="Epic orchestral battle theme",
    genre="orchestral",
    duration=120
)

music = music_job.wait_for_completion()
print(f"Music URL: {music.audio_url}")

# Voice synthesis
voice = client.audio.synthesize(
    text="Welcome, brave adventurer!",
    voice_id="voice_fantasy_male",
    emotion="excited"
)
```

### Async Support

```python
import asyncio
from yemaya import AsyncYemayaClient

async def main():
    client = AsyncYemayaClient(api_key="your-api-key")

    # Async operations
    projects = await client.projects.list()

    # Concurrent generation
    jobs = await asyncio.gather(
        client.three_d.generate(prompt="A sword"),
        client.three_d.generate(prompt="A shield"),
        client.three_d.generate(prompt="A helmet")
    )

    # Wait for all
    results = await asyncio.gather(*[
        job.wait_for_completion() for job in jobs
    ])

asyncio.run(main())
```

---

## React Integration

### useYemaya Hook

```tsx
import { useYemaya, YemayaProvider } from '@yemaya/sdk/react';

// Wrap app with provider
function App() {
  return (
    <YemayaProvider apiKey="your-api-key">
      <MyComponent />
    </YemayaProvider>
  );
}

// Use in components
function MyComponent() {
  const { client, isConnected } = useYemaya();

  const [projects, setProjects] = useState([]);

  useEffect(() => {
    client.projects.list().then(setProjects);
  }, [client]);

  return (
    <div>
      <h1>Projects</h1>
      {projects.map((p) => (
        <div key={p.id}>{p.name}</div>
      ))}
    </div>
  );
}
```

### useGenerate3D Hook

```tsx
import { useGenerate3D } from '@yemaya/sdk/react';

function ModelGenerator() {
  const { generate, isLoading, progress, result, error } = useGenerate3D();

  const handleGenerate = () => {
    generate({
      prompt: 'A cartoon cat',
      quality: 'high',
    });
  };

  return (
    <div>
      <button onClick={handleGenerate} disabled={isLoading}>
        Generate
      </button>

      {isLoading && <p>Generating... {progress}%</p>}
      {error && <p>Error: {error.message}</p>}
      {result && <model-viewer src={result.assets.glb} />}
    </div>
  );
}
```

### useRealtime Hook

```tsx
import { useRealtime } from '@yemaya/sdk/react';

function ProjectUpdates({ projectId }) {
  const { subscribe, on } = useRealtime();

  useEffect(() => {
    subscribe(`project:${projectId}`);

    const unsubscribe = on('asset.uploaded', (data) => {
      console.log('New asset:', data);
    });

    return unsubscribe;
  }, [projectId, subscribe, on]);

  return <div>Listening for updates...</div>;
}
```

---

## Error Handling

### TypeScript

```typescript
import { YemayaError, RateLimitError, ValidationError } from '@yemaya/sdk';

try {
  await client.projects.create({ name: '' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Validation errors:', error.details);
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after: ${error.retryAfter}s`);
    await sleep(error.retryAfter * 1000);
  } else if (error instanceof YemayaError) {
    console.log(`API Error: ${error.code} - ${error.message}`);
  } else {
    throw error;
  }
}
```

### Python

```python
from yemaya.exceptions import (
    YemayaError,
    RateLimitError,
    ValidationError
)

try:
    client.projects.create(name="")
except ValidationError as e:
    print(f"Validation errors: {e.details}")
except RateLimitError as e:
    print(f"Retry after: {e.retry_after}s")
    time.sleep(e.retry_after)
except YemayaError as e:
    print(f"API Error: {e.code} - {e.message}")
```

---

## See Also

- [API Examples](./examples.md)
- [API Reference](./endpoints/README.md)
- [Webhook Integration](./webhooks.md)
