npm package: @katspeax/alchemist-sdk
Description: Official SDK for the KatSpeax Alchemist API — truth-to-product creative pipeline
Latest version: 0.1.0

# @katspeax/alchemist-sdk

Official TypeScript SDK for the KatSpeax Alchemist API. Truth-to-product creative pipeline — generate content, design products, clone voices, edit video, and push to commerce. All from code.

## Install

```bash
npm install @katspeax/alchemist-sdk
```

## Quick Start

```ts
import { Alchemist } from '@katspeax/alchemist-sdk'

const alchemist = new Alchemist({ apiKey: 'ks_live_...' })

// Generate content -> design a card -> create an Etsy listing
const { contents } = await alchemist.contentCore.generate({
  prompt: 'grief and grace',
  tone: 'Tender',
  count: 1,
})

const { design_id } = await alchemist.design.generate({
  content: contents[0].text,
  product_type: 'greeting_card_5x7',
})

const listing = await alchemist.commerce.createListing({
  product_id: design_id,
  platform: 'etsy',
})
```

## Engines

### Content Core

| Method | Description |
|--------|-------------|
| `contentCore.generate(params)` | Generate truth-grade content from a creative prompt |
| `contentCore.refine(params)` | Refine content with a direction ("more tender", "shorter") |
| `contentCore.score(params)` | Score content for voice alignment and quality |

### Design

| Method | Description |
|--------|-------------|
| `design.generate(params)` | Generate a product design from content and config |
| `design.render(params)` | Render a design to SVG, PNG, or PDF |
| `design.mockup(params)` | Generate a product mockup image |
| `design.smartResize(params)` | Resize a design to multiple product types at once |

### Voice

| Method | Description |
|--------|-------------|
| `voice.tts(params)` | Convert text to speech audio |
| `voice.clone(params)` | Clone a voice from a sample and synthesize speech |
| `voice.spokenWord(params)` | Generate spoken word audio with optional music |

### Video

| Method | Description |
|--------|-------------|
| `video.edit(params)` | Edit a video with natural language instructions |
| `video.reframe(params)` | Reframe a video to a different aspect ratio |
| `video.batchReframe(params)` | Reframe to multiple ratios in one call |

### Content

| Method | Description |
|--------|-------------|
| `content.repurpose(params)` | Repurpose content for multiple social platforms |

### Commerce

| Method | Description |
|--------|-------------|
| `commerce.createListing(params)` | Create an e-commerce listing (Etsy, Amazon, Shopify, Printify) |

### Brand

| Method | Description |
|--------|-------------|
| `brand.getConfig()` | Get current brand voice rules, colors, fonts |
| `brand.updateConfig(updates)` | Update brand configuration |
| `brand.audit(params)` | Audit text against brand voice rules |

## Error Handling

```ts
import { Alchemist, AlchemistError } from '@katspeax/alchemist-sdk'

const alchemist = new Alchemist({ apiKey: 'ks_live_...' })

try {
  const result = await alchemist.contentCore.generate({ prompt: 'love and loss' })
} catch (err) {
  if (err instanceof AlchemistError) {
    console.error(`API error (${err.status}): ${err.message} [${err.code}]`)
  }
}
```

## Configuration

```ts
const alchemist = new Alchemist({
  apiKey: 'ks_live_...',         // Required
  baseUrl: 'https://api.katspeax.com',  // Optional (default)
  timeout: 30000,                // Optional, ms (default: 30000)
})
```

## Full Documentation

[https://docs.katspeax.com](https://docs.katspeax.com)

## License

MIT