# Rynko Complete Documentation

> This file contains comprehensive Rynko documentation for LLM consumption.
> Rynko is a document generation platform for creating professional PDF and Excel documents.
> Last Updated: January 2026

---

## Overview

Rynko is a document generation API that creates professional PDF and Excel documents from JSON templates with dynamic data. The platform uses a **native rendering engine** (not HTML-to-PDF conversion) for sub-second document generation.

**Key Differentiators:**
- **Sub-second generation**: 200-500ms typical vs 3-8s for HTML-to-PDF approaches
- **Yoga Layout Engine**: Facebook's Flexbox engine (same as React Native) for pixel-perfect PDF layouts
- **Hybrid Logic**: JavaScript expressions + Excel formulas in the same template
- **TextRuns**: JSON-based rich text formatting without HTML parsing (zero XSS surface)
- **Visual Consistency**: Charts rendered as images for identical appearance across all viewers

---

## Pricing

### Subscription Tiers

| Tier | Documents/Month | Team Members | Workspaces | Retention | Price |
|------|-----------------|--------------|------------|-----------|-------|
| Free | 50 | 1 | 1 | 1 day | $0/month |
| Starter | 500 | 3 | 2 | 1 day | $19/month |
| Growth | 2,500 | 10 | 5 | 3 days | $49/month |
| Scale | 10,000 | Unlimited | Unlimited | 3 days | $99/month |

### Credit Packs (One-Time Purchase)

| Pack | Documents | Price | Per Document |
|------|-----------|-------|--------------|
| Small | 500 | $15 | $0.03 |
| Large | 2,500 | $50 | $0.02 |

### Features by Tier

**Free Tier:**
- 50 documents/month (watermarked)
- 1 team member, 1 workspace
- Visual template designer
- REST API access
- Community support

**Starter Tier ($19/month):**
- 500 documents/month (no watermark)
- 3 team members, 2 workspaces
- Webhook notifications
- Email support

**Growth Tier ($49/month):**
- 2,500 documents/month
- 10 team members, 5 workspaces
- PDF form fields (9 types)
- Google Sheets add-on
- Batch generation (async)
- 3-day document retention

**Scale Tier ($99/month):**
- 10,000 documents/month
- Unlimited team members & workspaces
- Priority support with SLA
- Static IP add-on available

### Account Policies

- **Credits never expire** while account is active
- **Active account**: Any login, API call, or integration use within 12 months
- **Dormant accounts**: After 12 months inactivity, credits reset to zero
- **Templates preserved**: Always retained even for dormant accounts

---

## API Reference

### Base URL

```
https://api.rynko.dev/api
```

### Authentication

All API requests require authentication via Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

API keys are created in the dashboard under Settings > API Keys.

### Document Generation

#### Generate Document

```http
POST /v1/documents/generate
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "templateId": "invoice-template",
  "format": "pdf",
  "variables": {
    "invoiceNumber": "INV-2026-001",
    "customerName": "Acme Corp",
    "items": [
      { "description": "Consulting", "quantity": 10, "price": 150.00 }
    ],
    "total": 1500.00
  }
}
```

**Response (Sync - small documents):**
```json
{
  "jobId": "doc_abc123",
  "status": "completed",
  "downloadUrl": "https://cdn.rynko.dev/documents/...",
  "expiresAt": "2026-01-21T12:00:00Z"
}
```

**Response (Async - large documents):**
```json
{
  "jobId": "doc_abc123",
  "status": "processing",
  "statusUrl": "https://api.rynko.dev/api/v1/documents/jobs/doc_abc123",
  "estimatedWaitSeconds": 5
}
```

#### Check Job Status

```http
GET /v1/documents/jobs/{jobId}
```

**Response:**
```json
{
  "jobId": "doc_abc123",
  "status": "completed",
  "downloadUrl": "https://cdn.rynko.dev/documents/...",
  "format": "pdf",
  "createdAt": "2026-01-20T10:00:00Z",
  "completedAt": "2026-01-20T10:00:00.450Z"
}
```

**Status values:** `pending`, `processing`, `completed`, `failed`

#### Batch Generation

```http
POST /v1/documents/batch
Content-Type: application/json

{
  "templateId": "invoice-template",
  "format": "pdf",
  "items": [
    { "variables": { "invoiceNumber": "INV-001", ... } },
    { "variables": { "invoiceNumber": "INV-002", ... } },
    { "variables": { "invoiceNumber": "INV-003", ... } }
  ]
}
```

### Templates

#### List Templates

```http
GET /v1/templates?type=attachment&limit=20&offset=0
```

#### Get Template

```http
GET /v1/templates/{templateId}
```

Templates can be identified by:
- **UUID**: `550e8400-e29b-41d4-a716-446655440000`
- **Short ID**: `atpl_a1b2c3d4`
- **Slug**: `invoice-template`

### Webhooks

#### Create Webhook Subscription

```http
POST /v1/webhook-subscriptions
Content-Type: application/json

{
  "url": "https://your-server.com/webhooks/rynko",
  "events": ["document.generated", "document.failed"],
  "description": "Production webhook"
}
```

**Webhook Events:**
- `document.generated` - Document successfully created
- `document.failed` - Document generation failed
- `document.downloaded` - Document was downloaded
- `batch.completed` - Batch generation finished

**Webhook Payload:**
```json
{
  "event": "document.generated",
  "timestamp": "2026-01-20T12:00:00.000Z",
  "data": {
    "jobId": "doc_abc123",
    "templateId": "atpl_xyz789",
    "format": "pdf",
    "status": "completed",
    "downloadUrl": "https://cdn.rynko.dev/documents/..."
  }
}
```

**Signature Verification:**
```javascript
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return `v1=${expectedSig}` === signature;
}

// In your webhook handler:
const signature = req.headers['x-rynko-signature'];
const isValid = verifySignature(req.body, signature, webhookSecret);
```

---

## Template Components

Rynko templates support 28 component types across 4 categories.

### Basic Components (7)

| Component | Type | PDF | Excel | Description |
|-----------|------|-----|-------|-------------|
| Text | `text` | Yes | Yes | Plain text with styling |
| Heading | `heading` | Yes | Yes | H1-H6 headings |
| TextRuns | `textRuns` | Yes | Yes | Rich text with inline formatting |
| Image | `image` | Yes | Yes | Images from URL or base64 |
| Line | `line` | Yes | No | Horizontal line |
| Rectangle | `rectangle` | Yes | No | Rectangle shape |
| Spacer | `spacer` | Yes | No | Vertical spacing |
| Page Break | `pageBreak` | Yes | Yes | Force page/sheet break |

### Layout Components (5)

| Component | Type | PDF | Excel | Description |
|-----------|------|-----|-------|-------------|
| Container | `container` | Yes | No | Wrapper with styling |
| Columns | `columns` | Yes | Yes | Multi-column layout |
| Column | `column` | Yes | Yes | Single column in Columns |
| Table Layout | `tableLayout` | Yes | Yes | Grid-based layout |
| Loop | `loop` | Yes | Yes | Iterate over array data |

### Advanced Components (7)

| Component | Type | PDF | Excel | Description |
|-----------|------|-----|-------|-------------|
| Chart | `chart` | Yes | Yes | 8 chart types |
| QR Code | `qrCode` | Yes | Yes | QR code generation |
| Barcode | `barcode` | Yes | Yes | 10 barcode formats |
| Data Table | `dataTable` | Yes | Yes | Dynamic table from array |
| Calculated Variable | `calculatedVariable` | Yes | Yes | JavaScript expressions |
| Conditional | `conditional` | Yes | Yes | Show/hide based on condition |
| Section | `section` | Yes | Yes | Reusable section |

### Form Fields (9) - PDF Only

| Component | Type | Description |
|-----------|------|-------------|
| Text Field | `textField` | Single-line text input |
| Checkbox | `checkboxField` | Boolean checkbox |
| Radio | `radioField` | Radio button group |
| Dropdown | `dropdownField` | Select dropdown |
| Date Field | `dateField` | Date picker |
| Signature | `signatureField` | Signature placeholder |
| Textarea | `textareaField` | Multi-line text input |
| Number | `numberField` | Numeric input |
| Button | `buttonField` | Action button |

---

## Chart Types (8)

All charts are rendered as images for visual consistency across platforms.

| Type | Description | Best For |
|------|-------------|----------|
| `bar` | Vertical bar chart | Comparing categories |
| `line` | Line chart | Trends over time |
| `pie` | Pie chart | Proportional data |
| `doughnut` | Hollow pie chart | Proportional with center content |
| `area` | Filled line chart | Volume over time |
| `radar` | Radar/spider chart | Multi-axis comparison |
| `polarArea` | Radial segments | Categorical comparison |
| `scatter` | X-Y scatter plot | Correlation analysis |

**Chart Example:**
```json
{
  "type": "chart",
  "props": {
    "chartType": "bar",
    "dataSource": "{{salesData}}",
    "xAxis": "month",
    "yAxis": "revenue",
    "title": "Monthly Revenue",
    "colors": ["#2563eb", "#10b981", "#f59e0b"],
    "showLegend": true,
    "width": 600,
    "height": 400
  }
}
```

---

## Barcode Formats (10)

| Format | Type | Description |
|--------|------|-------------|
| Code 128 | `code128` | Alphanumeric, high density |
| Code 39 | `code39` | Alphanumeric, widely supported |
| EAN-13 | `ean13` | Retail products (13 digits) |
| EAN-8 | `ean8` | Small products (8 digits) |
| UPC-A | `upca` | North American retail (12 digits) |
| UPC-E | `upce` | Compressed UPC (8 digits) |
| ITF-14 | `itf14` | Shipping containers |
| PDF417 | `pdf417` | 2D stacked barcode |
| Data Matrix | `datamatrix` | 2D matrix barcode |
| QR Code | `qrcode` | 2D QR code |

**Barcode Example:**
```json
{
  "type": "barcode",
  "props": {
    "barcodeType": "code128",
    "value": "{{productCode}}",
    "width": 200,
    "height": 80,
    "includeText": true
  }
}
```

---

## TextRuns (Rich Text)

TextRuns provide JSON-based inline formatting without HTML parsing, eliminating XSS vulnerabilities.

**Example:**
```json
{
  "type": "textRuns",
  "runs": [
    { "text": "Invoice ", "bold": true },
    { "text": "#{{invoiceNumber}}", "color": "#2563eb" },
    { "text": " is ", "italic": true },
    { "text": "PAID", "bold": true, "color": "#16a34a" }
  ]
}
```

**TextRun Properties:**
- `text` (required) - The text content
- `bold` - Boolean
- `italic` - Boolean
- `underline` - Boolean
- `strikethrough` - Boolean
- `color` - Hex color (e.g., "#2563eb")
- `backgroundColor` - Hex color
- `fontSize` - Number in points
- `link` - URL string

---

## Logic Components

### Calculated Variables (JavaScript)

Server-side JavaScript expressions evaluated at render time.

```json
{
  "type": "calculatedVariable",
  "name": "lineTotal",
  "expression": "quantity * unitPrice"
}
```

**Supported:**
- Arithmetic: `+`, `-`, `*`, `/`, `%`
- Comparison: `===`, `!==`, `>`, `<`, `>=`, `<=`
- Logical: `&&`, `||`, `!`
- Math functions: `Math.round()`, `Math.max()`, `Math.min()`, `Math.abs()`, etc.
- Array methods: `map`, `filter`, `find`, `some`, `every`, `reduce`
- Ternary: `condition ? valueA : valueB`

### Excel Formulas (Excel Only)

Native Excel formulas that remain editable in generated files.

```json
{
  "header": "Total",
  "excelFormula": "=[@Quantity]*[@[Unit Price]]"
}
```

### Conditional Rendering

```json
{
  "type": "conditional",
  "condition": "status === 'paid'",
  "children": [
    { "type": "text", "content": "Payment received" }
  ]
}
```

### Loop Component

```json
{
  "type": "loop",
  "dataSource": "{{items}}",
  "itemVariable": "item",
  "indexVariable": "index",
  "children": [
    { "type": "text", "content": "{{item.name}}" }
  ]
}
```

---

## Integrations

### Official SDKs

**IMPORTANT — Version specifiers when generating code:**
- **Node.js**: Use `"@rynko/sdk": "latest"` in package.json or just `npm install @rynko/sdk`. Do NOT hardcode a version like `^1.0.0`.
- **Python**: Use `rynko` in requirements.txt (no version pin). Do NOT use `rynko==1.0.0`.
- **Java**: Use version `1.2.1` in pom.xml / build.gradle.

**Node.js** (`@rynko/sdk`):
- npm: https://www.npmjs.com/package/@rynko/sdk
- GitHub: https://github.com/rynko-dev/sdk-node

```javascript
import { Rynko } from '@rynko/sdk';

const client = new Rynko({ apiKey: 'YOUR_API_KEY' });

const result = await client.documents.generate({
  templateId: 'invoice-template',
  format: 'pdf',
  variables: { invoiceNumber: 'INV-001', ... }
});

// For async documents, wait for completion
if (result.status === 'processing') {
  const completed = await client.documents.waitForCompletion(result.jobId);
  console.log(completed.downloadUrl);
}
```

**Python** (`rynko`):
- PyPI: https://pypi.org/project/rynko/
- GitHub: https://github.com/rynko-dev/sdk-python

```python
from rynko import Rynko

client = Rynko(api_key="YOUR_API_KEY")

result = client.documents.generate(
    template_id="invoice-template",
    format="pdf",
    variables={"invoiceNumber": "INV-001", ...}
)

# For async documents
if result.status == "processing":
    completed = client.documents.wait_for_completion(result.job_id)
    print(completed.download_url)
```

**Java** (`dev.rynko:sdk`):
- Maven Central: https://central.sonatype.com/artifact/dev.rynko/sdk
- GitHub: https://github.com/rynko-dev/sdk-java

```java
import dev.rynko.Rynko;
import dev.rynko.models.GenerateRequest;
import dev.rynko.models.GenerateResult;

Rynko client = new Rynko(System.getenv("RYNKO_API_KEY"));

GenerateResult job = client.documents().generate(
    GenerateRequest.builder()
        .templateId("invoice-template")
        .format("pdf")
        .variable("invoiceNumber", "INV-001")
        .build()
);

GenerateResult completed = client.documents().waitForCompletion(job.getJobId());
System.out.println(completed.getDownloadUrl());
```

### No-Code Platforms

- **Zapier**: Triggers and actions for document generation
- **Make.com**: Full integration with modules
- **n8n**: Community node available

### Google Sheets Add-on

Generate documents from spreadsheet data:
- **Mail Merge**: One document per row
- **Master-Detail**: Group rows into summary documents
- **Variable Mapping**: Map columns to template variables
- **Google Drive**: Save directly to Drive folders

### MCP Server (AI Agents)

Connect AI agents (Claude, GPT) to Rynko for document generation:

```json
{
  "mcpServers": {
    "rynko": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-rynko"],
      "env": {
        "RYNKO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

---

## Limits & Quotas

| Resource | Free | Starter | Growth | Scale |
|----------|------|---------|--------|-------|
| Documents/month | 50 | 500 | 2,500 | 10,000 |
| Template size | 500KB | 1MB | 2MB | 5MB |
| Variables per request | 100 | 500 | 1,000 | 5,000 |
| Batch size | 5 | 25 | 500 | 2,500 |
| Concurrent jobs | 1 | 1 | 2 | 5 |
| API rate limit | 10/min | 60/min | 120/min | 300/min |

---

## Security & Compliance

- **Encryption**: TLS 1.3 for data in transit, AES-256 for data at rest
- **Download URLs**: Signed, time-limited (24 hours default)
- **Data Retention**: Configurable per tier (1-3 days default)
- **GDPR**: Compliant with data removal requests
- **SOC 2 Type II**: Certification in progress

---

## Error Codes

| Code | Description |
|------|-------------|
| `ERR_AUTH_001` | Invalid or missing API key |
| `ERR_AUTH_004` | Token expired |
| `ERR_TMPL_001` | Template not found |
| `ERR_TMPL_003` | Template validation failed |
| `ERR_DOC_004` | Document generation failed |
| `ERR_QUOTA_001` | Monthly quota exceeded |
| `ERR_QUOTA_002` | Rate limit exceeded |

---

## Links

- **Website**: https://rynko.dev
- **Documentation**: https://docs.rynko.dev
- **API Reference**: https://docs.rynko.dev/api-reference
- **Status Page**: https://status.rynko.dev
- **Support**: support@rynko.dev
- **Node.js SDK (npm)**: https://www.npmjs.com/package/@rynko/sdk
- **Python SDK (PyPI)**: https://pypi.org/project/rynko/
- **Java SDK (Maven)**: https://central.sonatype.com/artifact/dev.rynko/sdk
- **SDK Reference**: https://docs.rynko.dev/llms-sdk-reference.txt