# Yemaya C++ SDK

The official C++ SDK for the Yemaya platform - end-to-end movie and game
creation with AI-powered tools.

## Requirements

- C++17 or later
- CMake 3.16 or later
- OpenSSL (for HTTPS support)

## Building

```bash
mkdir build && cd build
cmake ..
cmake --build .
```

### Build Options

- `YEMAYA_BUILD_TESTS` - Build tests (default: ON)
- `YEMAYA_BUILD_EXAMPLES` - Build examples (default: ON)
- `YEMAYA_BUILD_DOCS` - Build documentation (default: OFF)

```bash
cmake -DYEMAYA_BUILD_TESTS=OFF ..
```

## Installation

```bash
cmake --install . --prefix /usr/local
```

The installed CMake package can then be consumed from another project:

```cmake
find_package(yemaya CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE yemaya::yemaya)
```

## Quick Start

```cpp
#include <yemaya/yemaya.hpp>
#include <iostream>

int main() {
    // Create client from environment (YEMAYA_API_KEY)
    auto client = yemaya::Client::from_env();

    // Or with explicit API key
    // yemaya::Client client("your-api-key");

    // Create a project
    auto project = client.projects().create({
        .name = "My Game",
        .type = yemaya::ProjectType::Game,
        .description = "An awesome game"
    });

    std::cout << "Created: " << project.name << std::endl;

    // Work with project resources
    auto ctx = client.project(project.id);

    // Create assets, scenes, characters
    auto scene = ctx.scenes().create({
        .name = "Level 1"
    });

    auto character = ctx.characters().create({
        .name = "Hero",
        .role = "main"
    });

    // AI generation
    auto response = client.ai().generate_text(
        "Write a backstory for a medieval knight"
    );

    return 0;
}
```

## Configuration

### Environment Variables

- `YEMAYA_API_KEY` - Your Yemaya API key
- `YEMAYA_BASE_URL` - API base URL (default: https://api.yemaya.dev)
- `YEMAYA_DEBUG` - Enable debug logging (1, true, yes)
- `YEMAYA_TIMEOUT` - Request timeout in seconds
- `YEMAYA_MAX_RETRIES` - Maximum retry attempts

### Programmatic Configuration

```cpp
yemaya::Config config("your-api-key");
config.set_base_url("https://custom.api.com")
      .set_timeout(yemaya::TimeoutConfig(
          std::chrono::seconds{10},  // connect
          std::chrono::seconds{60},  // read
          std::chrono::seconds{60}   // write
      ))
      .set_retry(yemaya::RetryConfig(5, std::chrono::milliseconds{1000}))
      .set_debug(true);

yemaya::Client client(config);
```

## API Resources

### Projects

```cpp
// List projects
auto projects = client.projects().list({
    .page = 1,
    .per_page = 20,
    .status = yemaya::ProjectStatus::Active
});

// Get a project
auto project = client.projects().get("proj_123");

// Create a project
auto project = client.projects().create({
    .name = "My Project",
    .type = yemaya::ProjectType::Movie,
    .description = "A great movie"
});

// Update a project
client.projects().update("proj_123", {
    .name = "Updated Name",
    .status = yemaya::ProjectStatus::Active
});

// Delete a project
client.projects().remove("proj_123");

// Archive a project
client.projects().archive("proj_123");

// Duplicate a project
auto copy = client.projects().duplicate("proj_123", "Project Copy");
```

### Assets

```cpp
auto ctx = client.project("proj_123");

// List assets
auto assets = ctx.assets().list({
    .type = yemaya::AssetType::Texture
});

// Upload a file
auto asset = ctx.assets().upload(
    "/path/to/texture.png",
    "Ground Texture",
    yemaya::AssetType::Texture
);

// Download an asset
auto data = ctx.assets().download("asset_123");

// Download to file
ctx.assets().download_to_file("asset_123", "/path/to/output.png");

// Get versions
auto versions = ctx.assets().get_versions("asset_123");

// Revert to version
ctx.assets().revert_to_version("asset_123", 2);
```

### Scenes

```cpp
auto ctx = client.project("proj_123");

// Create a scene
auto scene = ctx.scenes().create({
    .name = "Opening Scene",
    .settings = yemaya::SceneSettings{
        .ambient_color = "#404040",
        .fog_enabled = true
    }
});

// Add objects
auto obj = ctx.scenes().add_object(scene.id, {
    .name = "Player Spawn",
    .position = {0.0, 0.0, 0.0}
});

// Update object
ctx.scenes().update_object(scene.id, obj.id, {
    .position = yemaya::Vec3{10.0, 0.0, 5.0}
});

// Reorder scenes
ctx.scenes().reorder({"scene_3", "scene_1", "scene_2"});
```

### Characters

```cpp
auto ctx = client.project("proj_123");

// Create a character
auto character = ctx.characters().create({
    .name = "Hero",
    .role = "main",
    .appearance = yemaya::CharacterAppearance{
        .height = 1.8,
        .hair_color = "brown"
    },
    .personality = yemaya::CharacterPersonality{
        .traits = {"brave", "kind"},
        .motivations = {"save the world"}
    }
});

// Link assets
ctx.characters().link_model("char_123", "model_asset_id");
ctx.characters().link_voice("char_123", "voice_asset_id");

// Generate backstory with AI
auto updated = ctx.characters().generate_backstory(
    "char_123",
    "dramatic",  // style
    "detailed"   // length
);
```

### AI Generation

```cpp
// Text generation
auto response = client.ai().generate_text(
    "Write a fantasy story opening",
    yemaya::AIModel::Claude3Opus,
    0.7,     // temperature
    2000     // max_tokens
);

// Image generation
auto image = client.ai().generate_image(
    "A magical forest at sunset",
    yemaya::AIModel::Dalle3,
    "dark elements",  // negative prompt
    "fantasy",        // style
    "16:9"           // aspect ratio
);

// Code generation
auto code = client.ai().generate_code(
    "Create a player movement script",
    yemaya::AIModel::Claude3Opus,
    "cpp"  // language
);

// List models
auto models = client.ai().list_models();
```

## Error Handling

```cpp
#include <yemaya/error.hpp>

try {
    auto project = client.projects().get("invalid_id");
} catch (const yemaya::NotFoundError& e) {
    std::cerr << "Not found: " << e.what() << std::endl;
} catch (const yemaya::AuthenticationError& e) {
    std::cerr << "Auth failed: " << e.what() << std::endl;
} catch (const yemaya::RateLimitError& e) {
    std::cerr << "Rate limited. Retry after: "
              << e.retry_after().value_or(60) << "s" << std::endl;
} catch (const yemaya::ValidationError& e) {
    std::cerr << "Validation error: " << e.what() << std::endl;
    if (e.field()) {
        std::cerr << "Field: " << *e.field() << std::endl;
    }
} catch (const yemaya::APIError& e) {
    std::cerr << "API error [" << e.status_code() << "]: "
              << e.what() << std::endl;
} catch (const yemaya::ConnectionError& e) {
    std::cerr << "Connection failed: " << e.what() << std::endl;
} catch (const yemaya::Error& e) {
    std::cerr << "Error: " << e.what() << std::endl;
}
```

## Game Engine Integration

The SDK is designed for easy integration with game engines:

### Unreal Engine

```cpp
// In your game module
#include <yemaya/yemaya.hpp>

void UYemayaSubsystem::Initialize(FSubsystemCollectionBase& Collection) {
    FString ApiKey = FPlatformMisc::GetEnvironmentVariable(TEXT("YEMAYA_API_KEY"));
    Client = MakeUnique<yemaya::Client>(TCHAR_TO_UTF8(*ApiKey));
}
```

### Godot (GDExtension)

```cpp
#include <yemaya/yemaya.hpp>
#include <godot_cpp/classes/node.hpp>

class YemayaNode : public godot::Node {
    std::unique_ptr<yemaya::Client> client;

    void _ready() override {
        client = std::make_unique<yemaya::Client>(
            yemaya::Config::from_env()
        );
    }
};
```

## Testing

```bash
cd build
ctest --output-on-failure
```

## License

MIT License - see LICENSE for details.