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