SDKs
TypeScript / JavaScript

TypeScript / JavaScript SDK

Official TypeScript client for the Canvelete (opens in a new tab) API. Works with Node.js 14+ and modern browsers.

Installation

npm install @canveletedotcom/sdk

Or with yarn:

yarn add @canveletedotcom/sdk

Quick Start

import { CanveleteClient } from '@canveletedotcom/sdk';
 
const client = new CanveleteClient({
  apiKey: 'cvt_your_api_key'
});
 
// List designs
const designs = await client.designs.list();
console.log(`Found ${designs.data.length} designs`);
 
// Render a design
const result = await client.render.create({
  designId: 'design_123',
  format: 'png',
  dynamicData: { title: 'Hello World' },
  outputFile: 'output.png'
});

Authentication

API Key

const client = new CanveleteClient({
  apiKey: 'cvt_your_api_key'
});

Environment Variable

export CANVELETE_API_KEY="cvt_your_api_key"
const client = new CanveleteClient({
  apiKey: process.env.CANVELETE_API_KEY
});

Designs

List Designs

// Basic listing
const designs = await client.designs.list();
 
// With pagination
const designs = await client.designs.list({ page: 1, limit: 20 });
 
// Iterate all designs (auto-pagination)
for await (const design of client.designs.iterateAll()) {
  console.log(design.name);
}

Create Design

const design = await client.designs.create({
  name: 'My Design',
  width: 1920,
  height: 1080,
  canvasData: {
    elements: [
      {
        type: 'text',
        text: '{{title}}',
        x: 100,
        y: 100,
        fontSize: 48
      }
    ]
  }
});

Get, Update, Delete

// Get
const design = await client.designs.get('design_123');
 
// Update
const updated = await client.designs.update('design_123', {
  name: 'Updated Name'
});
 
// Delete
await client.designs.delete('design_123');

Rendering

Single Render

// Render to file
const result = await client.render.create({
  designId: 'design_123',
  format: 'png',
  quality: 90,
  dynamicData: { title: 'Hello World' },
  outputFile: 'output.png'
});
 
// Get binary data
const imageBuffer = await client.render.create({
  designId: 'design_123',
  format: 'png'
});

Render Options

const result = await client.render.create({
  designId: 'design_123',
  format: 'pdf',           // png, jpg, pdf, svg, webp
  quality: 95,             // 1-100
  width: 1200,             // Custom width
  height: 630,             // Custom height
  scale: 2.0,              // Scale factor
  dynamicData: {
    title: 'Hello',
    image: 'https://example.com/photo.jpg'
  }
});

Batch Rendering

const results = await client.render.batch([
  {
    designId: 'design_123',
    format: 'png',
    dynamicData: { name: 'Alice' }
  },
  {
    designId: 'design_123',
    format: 'png',
    dynamicData: { name: 'Bob' }
  }
]);
 
for (const result of results) {
  console.log(result.downloadUrl);
}

Templates

// List templates
const templates = await client.templates.list();
 
// Search templates
const templates = await client.templates.list({ search: 'certificate' });
 
// Get template
const template = await client.templates.get('template_123');
 
// Iterate all
for await (const template of client.templates.iterateAll()) {
  console.log(template.name);
}

API Keys

// List keys
const keys = await client.apiKeys.list();
 
// Create key
const newKey = await client.apiKeys.create({ name: 'Production Key' });
console.log(`Save this key: ${newKey.data.key}`); // Only shown once!

Error Handling

import {
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ValidationError
} from '@canveletedotcom/sdk';
 
try {
  const design = await client.designs.get('invalid_id');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error('Design not found');
  } else if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    console.error(`Invalid request: ${error.message}`);
  }
}

TypeScript Types

The SDK includes full TypeScript definitions:

import type {
  Design,
  Template,
  RenderOptions,
  RenderResult,
  ListOptions
} from '@canveletedotcom/sdk';
 
const options: RenderOptions = {
  designId: 'design_123',
  format: 'png',
  quality: 90
};

Configuration

const client = new CanveleteClient({
  apiKey: 'cvt_your_key',
  baseUrl: 'https://api.canvelete.com',  // Custom URL
  timeout: 60000,                         // Request timeout (ms)
  maxRetries: 3                           // Retry attempts
});

Support

PythonGo