Eve library

Yemaya SDKs

Other

Revision 1

On this page

Official client libraries for integrating with the Yemaya API.

Table of Contents#


Available SDKs#

Language Package Version Status
TypeScript/JavaScript @yemaya/sdk 1.0.0 Stable
Python yemaya 1.0.0 Stable
Go github.com/yemaya/yemaya-go 1.0.0 Stable
Ruby yemaya 0.1.0 Beta
PHP yemaya/yemaya-php 0.1.0 Beta
C# Yemaya.SDK 0.1.0 Beta
Java io.yemaya:sdk 0.1.0 Beta

TypeScript/JavaScript SDK#

Installation#

bash
# npm
npm install @yemaya/sdk

# yarn
yarn add @yemaya/sdk

# pnpm
pnpm add @yemaya/sdk

Quick Start#

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

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

// List projects
const projects = await client.projects.list();

// Create a project
const project = await client.projects.create({
  name: 'My Project',
  type: 'film',
  visibility: 'private',
});

// Get a specific project
const project = await client.projects.get('prj_abc123');

// Update a project
const updated = await client.projects.update('prj_abc123', {
  name: 'Updated Name',
});

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

Configuration Options#

typescript
const client = new YemayaClient({
  // Authentication (choose one)
  apiKey: 'your-api-key',
  accessToken: 'your-access-token',

  // Optional configuration
  baseUrl: 'https://api.yemaya.io',  // Custom API URL
  version: 'v1',                       // API version
  timeout: 30000,                      // Request timeout (ms)
  retries: 3,                          // Auto-retry count
  debug: false,                        // Enable debug logging

  // Custom fetch implementation
  fetch: customFetch,

  // Request interceptors
  onRequest: (config) => {
    console.log('Request:', config.url);
    return config;
  },
  onResponse: (response) => {
    console.log('Response:', response.status);
    return response;
  },
  onError: (error) => {
    console.error('Error:', error);
    throw error;
  },
});

Resource Examples#

Authentication#

typescript
// Login
const session = await client.auth.login({
  email: 'user@example.com',
  password: 'password',
});

// Use the returned tokens
client.setAccessToken(session.accessToken);

// Refresh token
const newSession = await client.auth.refresh({
  refreshToken: session.refreshToken,
});

// Logout
await client.auth.logout();

Users#

typescript
// Get current user
const me = await client.users.me();

// Update profile
const updated = await client.users.update({
  name: 'New Name',
  bio: 'My bio',
});

// Get user by ID
const user = await client.users.get('usr_abc123');

Assets#

typescript
// Upload an asset
const asset = await client.assets.upload('prj_abc123', {
  file: fileBuffer,          // Buffer or Blob
  name: 'my-image.png',
  type: 'image',
  metadata: {
    width: 1920,
    height: 1080,
  },
});

// List assets
const assets = await client.assets.list('prj_abc123', {
  type: 'image',
  limit: 20,
});

// Download asset
const blob = await client.assets.download('ast_abc123');

AI Generation#

typescript
// Start generation
const generation = await client.ai.generate({
  type: 'text',
  prompt: 'Write a movie synopsis',
  model: 'claude-3-opus',
  options: {
    maxTokens: 1000,
    temperature: 0.7,
  },
});

// Wait for completion (streaming)
for await (const chunk of client.ai.stream(generation.id)) {
  process.stdout.write(chunk.text);
}

// Or poll for result
const result = await client.ai.waitForCompletion(generation.id);

Webhooks#

typescript
// Create webhook
const webhook = await client.webhooks.create({
  url: 'https://your-app.com/webhook',
  events: ['project.created', 'asset.uploaded'],
  secret: 'your-secret',
});

// Verify webhook signature (in your handler)
import { verifyWebhookSignature } from '@yemaya/sdk';

const isValid = verifyWebhookSignature(
  requestBody,
  signature,
  'your-secret'
);

Pagination#

typescript
// Automatic pagination
const allProjects = await client.projects.list().all();

// Manual pagination
let page = await client.projects.list({ limit: 20 });

while (page.hasMore) {
  for (const project of page.data) {
    console.log(project.name);
  }
  page = await page.next();
}

// Async iterator
for await (const project of client.projects.list()) {
  console.log(project.name);
}

Error Handling#

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

try {
  await client.projects.create({ /* invalid data */ });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.errors);
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof YemayaError) {
    console.error(`API error: ${error.code} - ${error.message}`);
  }
}

TypeScript Support#

The SDK includes full TypeScript types:

typescript
import type { Project, User, Asset, GenerationResult } from '@yemaya/sdk';

async function getProjectInfo(id: string): Promise<Project> {
  return client.projects.get(id);
}

Python SDK#

Installation#

bash
pip install yemaya

Quick Start#

python
from yemaya import YemayaClient

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

# List projects
projects = client.projects.list()

# Create a project
project = client.projects.create(
    name="My Project",
    type="film",
    visibility="private"
)

# Get a specific project
project = client.projects.get("prj_abc123")

# Update a project
updated = client.projects.update("prj_abc123", name="Updated Name")

# Delete a project
client.projects.delete("prj_abc123")

Async Support#

python
from yemaya import AsyncYemayaClient
import asyncio

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

    # All methods are async
    projects = await client.projects.list()

    # Concurrent requests
    results = await asyncio.gather(
        client.projects.get("prj_1"),
        client.projects.get("prj_2"),
        client.projects.get("prj_3"),
    )

asyncio.run(main())

Configuration#

python
client = YemayaClient(
    api_key="your-api-key",
    base_url="https://api.yemaya.io",
    version="v1",
    timeout=30.0,
    max_retries=3,
)

# With token auth
client = YemayaClient(access_token="your-token")

Resource Examples#

Authentication#

python
# Login
session = client.auth.login(
    email="user@example.com",
    password="password"
)

# Use returned tokens
client = YemayaClient(access_token=session.access_token)

# Refresh token
new_session = client.auth.refresh(refresh_token=session.refresh_token)

Assets#

python
# Upload from file
with open("image.png", "rb") as f:
    asset = client.assets.upload(
        project_id="prj_abc123",
        file=f,
        name="my-image.png",
        type="image"
    )

# Upload from bytes
asset = client.assets.upload(
    project_id="prj_abc123",
    file=image_bytes,
    name="generated.png",
    type="image"
)

# List assets
assets = client.assets.list("prj_abc123", type="image", limit=20)

AI Generation#

python
# Start generation
generation = client.ai.generate(
    type="text",
    prompt="Write a movie synopsis",
    model="claude-3-opus",
    options={"max_tokens": 1000, "temperature": 0.7}
)

# Stream results
for chunk in client.ai.stream(generation.id):
    print(chunk.text, end="", flush=True)

# Or wait for completion
result = client.ai.wait_for_completion(generation.id)
print(result.content)

Pagination#

python
# Get all results (auto-pagination)
all_projects = client.projects.list().all()

# Manual pagination
page = client.projects.list(limit=20)
while page.has_more:
    for project in page.data:
        print(project.name)
    page = page.next()

# Iterator
for project in client.projects.list():
    print(project.name)

Error Handling#

python
from yemaya import YemayaError, RateLimitError, ValidationError

try:
    client.projects.create(name="")
except ValidationError as e:
    print(f"Validation failed: {e.errors}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except YemayaError as e:
    print(f"API error: {e.code} - {e.message}")

Type Hints#

The Python SDK includes type hints for all methods:

python
from yemaya.types import Project, User, Asset

def get_project_info(client: YemayaClient, id: str) -> Project:
    return client.projects.get(id)

Go SDK#

Installation#

bash
go get github.com/yemaya/yemaya-go

Quick Start#

go
package main

import (
    "fmt"
    "github.com/yemaya/yemaya-go"
)

func main() {
    client := yemaya.NewClient(yemaya.Config{
        APIKey: "your-api-key",
    })

    // List projects
    projects, err := client.Projects.List(nil)
    if err != nil {
        panic(err)
    }

    // Create a project
    project, err := client.Projects.Create(&yemaya.CreateProjectParams{
        Name:       "My Project",
        Type:       "film",
        Visibility: "private",
    })

    // Get a specific project
    project, err := client.Projects.Get("prj_abc123")

    // Update a project
    project, err := client.Projects.Update("prj_abc123", &yemaya.UpdateProjectParams{
        Name: "Updated Name",
    })

    // Delete a project
    err = client.Projects.Delete("prj_abc123")
}

Configuration#

go
client := yemaya.NewClient(yemaya.Config{
    APIKey:   "your-api-key",
    BaseURL:  "https://api.yemaya.io",
    Version:  "v1",
    Timeout:  30 * time.Second,
    Retries:  3,
    Debug:    false,
})

// With token auth
client := yemaya.NewClient(yemaya.Config{
    AccessToken: "your-token",
})

Resource Examples#

go
// Authentication
session, err := client.Auth.Login(&yemaya.LoginParams{
    Email:    "user@example.com",
    Password: "password",
})

// Assets
file, _ := os.Open("image.png")
asset, err := client.Assets.Upload("prj_abc123", &yemaya.UploadParams{
    File: file,
    Name: "my-image.png",
    Type: "image",
})

// AI Generation
gen, err := client.AI.Generate(&yemaya.GenerateParams{
    Type:   "text",
    Prompt: "Write a synopsis",
    Model:  "claude-3-opus",
})

// Wait for result
result, err := client.AI.WaitForCompletion(gen.ID)

Pagination#

go
// Manual pagination
iter := client.Projects.List(&yemaya.ListParams{Limit: 20})

for iter.Next() {
    project := iter.Current()
    fmt.Println(project.Name)
}

if err := iter.Err(); err != nil {
    panic(err)
}

// Get all
projects, err := client.Projects.List(nil).All()

Error Handling#

go
project, err := client.Projects.Get("invalid-id")
if err != nil {
    var apiErr *yemaya.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("API error: %s - %s\n", apiErr.Code, apiErr.Message)

        if apiErr.Status == 429 {
            time.Sleep(time.Duration(apiErr.RetryAfter) * time.Second)
        }
    }
}

Code Generation#

Generate client code from the OpenAPI specification:

Using OpenAPI Generator#

bash
# Install OpenAPI Generator
npm install -g @openapitools/openapi-generator-cli

# Generate TypeScript client
openapi-generator-cli generate \
  -i https://api.yemaya.io/openapi.json \
  -g typescript-fetch \
  -o ./generated/typescript

# Generate Python client
openapi-generator-cli generate \
  -i https://api.yemaya.io/openapi.json \
  -g python \
  -o ./generated/python

# Generate Go client
openapi-generator-cli generate \
  -i https://api.yemaya.io/openapi.json \
  -g go \
  -o ./generated/go

Supported Generators#

Language Generator
TypeScript typescript-fetch, typescript-axios
Python python, python-aiohttp
Go go
Ruby ruby
PHP php
Java java
C# csharp, csharp-netcore
Kotlin kotlin
Swift swift5
Rust rust

Using Yemaya CLI#

bash
# Install CLI
npm install -g @yemaya/cli

# Generate SDK
yemaya codegen typescript --output ./sdk
yemaya codegen python --output ./sdk
yemaya codegen go --output ./sdk

# Generate all languages
yemaya codegen all --output ./sdk

Community SDKs#

These SDKs are maintained by the community:

Language Package Maintainer
Rust yemaya-rs @rustdev
Elixir yemaya_ex @elixirdev
Kotlin yemaya-kt @kotlindev
Swift Yemaya @swiftdev

Note: Community SDKs are not officially supported. Use at your own risk.


SDK Development#

Contributing#

We welcome contributions! See our contribution guide.

Feature Requests#

Open an issue on GitHub or email sdk@yemaya.io.


Support#

  • Documentation: https://docs.yemaya.io/sdk
  • GitHub Issues: https://github.com/yemaya/yemaya/issues
  • Discord: https://discord.gg/yemaya
  • Email: sdk@yemaya.io