@canveletedotcom/sdk 2.0.0

package/README.md

@@ -0,0 +1,143 @@
+# Canvelete TypeScript SDK
+
+Official TypeScript client library for the [Canvelete](https://www.canvelete.com) API.
+
+## Installation
+
+```bash
+npm install @canvelete/sdk
+```
+
+## Quick Start
+
+```typescript
+import { CanveleteClient } from '@canvelete/sdk';
+
+// Initialize client with API key
+const client = new CanveleteClient({
+  apiKey: 'cvt_your_api_key_here'
+});
+
+// List designs
+const designs = await client.designs.list();
+console.log(`Found ${designs.data.length} designs`);
+
+// Create a design
+const design = await client.designs.create({
+  name: 'My Design',
+  canvasData: {
+    elements: [
+      {
+        type: 'text',
+        text: 'Hello Canvelete!',
+        x: 100,
+        y: 100,
+        fontSize: 48
+      }
+    ]
+  },
+  width: 1920,
+  height: 1080
+});
+
+// Render the design
+const imageData = await client.render.create({
+  designId: design.data.id,
+  format: 'png',
+  outputFile: 'output.png'
+});
+```
+
+## API Reference
+
+### Designs
+
+```typescript
+// List with pagination
+const designs = await client.designs.list({ page: 1, limit: 20 });
+
+// Iterate all (auto-pagination)
+for await (const design of client.designs.iterateAll()) {
+  console.log(design.name);
+}
+
+// Create
+const design = await client.designs.create({ name: 'New Design', canvasData: {...} });
+
+// Get
+const design = await client.designs.get('design_id');
+
+// Update
+const updated = await client.designs.update('design_id', { name: 'Updated' });
+
+// Delete
+await client.designs.delete('design_id');
+```
+
+### Templates
+
+```typescript
+// List templates
+const templates = await client.templates.list({ search: 'certificate' });
+
+// Iterate all
+for await (const template of client.templates.iterateAll()) {
+  console.log(template.name);
+}
+```
+
+### Render
+
+```typescript
+// Render to file
+await client.render.create({
+  templateId: 'template_id',
+  dynamicData: { name: 'John Doe', date: '2024-01-01' },
+  format: 'pdf',
+  outputFile: 'certificate.pdf'
+});
+
+// Get binary data
+const imageBuffer = await client.render.create({
+  designId: 'design_id',
+  format: 'png'
+});
+```
+
+### API Keys
+
+```typescript
+// List keys
+const keys = await client.apiKeys.list();
+
+// Create new key
+const newKey = await client.apiKeys.create({ name: 'Production Key' });
+console.log(`Save this: ${newKey.data.key}`); // Shown only once!
+```
+
+## Error Handling
+
+```typescript
+import {
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  ValidationError
+} from '@canvelete/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`);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Main Canvelete API Client
+ */
+import { DesignsResource } from './resources/designs';
+import { TemplatesResource } from './resources/templates';
+import { RenderResource } from './resources/render';
+import { APIKeysResource } from './resources/apiKeys';
+import { CanvasResource } from './resources/canvas';
+import { AssetsResource } from './resources/assets';
+import { UsageResource } from './resources/usage';
+import { BillingResource } from './resources/billing';
+import type { ClientOptions } from './types';
+export interface RequestOptions {
+    params?: Record<string, string>;
+    json?: Record<string, any>;
+    binary?: boolean;
+}
+export declare class CanveleteClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    designs: DesignsResource;
+    templates: TemplatesResource;
+    render: RenderResource;
+    apiKeys: APIKeysResource;
+    canvas: CanvasResource;
+    assets: AssetsResource;
+    usage: UsageResource;
+    billing: BillingResource;
+    /**
+     * Initialize the Canvelete client
+     */
+    constructor(options?: ClientOptions);
+    /**
+     * Get authentication headers
+     */
+    private getAuthHeaders;
+    /**
+     * Make an authenticated API request
+     */
+    request<T>(method: string, endpoint: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Handle HTTP error responses
+     */
+    private handleResponseErrors;
+}

package/dist/client.js

@@ -0,0 +1,132 @@
+/**
+ * Main Canvelete API Client
+ */
+import { DesignsResource } from './resources/designs';
+import { TemplatesResource } from './resources/templates';
+import { RenderResource } from './resources/render';
+import { APIKeysResource } from './resources/apiKeys';
+import { CanvasResource } from './resources/canvas';
+import { AssetsResource } from './resources/assets';
+import { UsageResource } from './resources/usage';
+import { BillingResource } from './resources/billing';
+import { CanveleteError, AuthenticationError, ValidationError, NotFoundError, RateLimitError, ServerError, InsufficientScopeError, } from './errors';
+export class CanveleteClient {
+    /**
+     * Initialize the Canvelete client
+     */
+    constructor(options = {}) {
+        this.apiKey = options.apiKey || '';
+        this.baseUrl = (options.baseUrl || 'https://www.canvelete.com').replace(/\/$/, '');
+        this.timeout = options.timeout || 30000;
+        // Initialize resource handlers
+        this.designs = new DesignsResource(this);
+        this.templates = new TemplatesResource(this);
+        this.render = new RenderResource(this);
+        this.apiKeys = new APIKeysResource(this);
+        // Initialize new resources
+        this.canvas = new CanvasResource(this);
+        this.assets = new AssetsResource(this);
+        this.usage = new UsageResource(this);
+        this.billing = new BillingResource(this);
+    }
+    /**
+     * Get authentication headers
+     */
+    getAuthHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': 'canvelete-ts/2.0.0',
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        else {
+            throw new AuthenticationError('No API key provided');
+        }
+        return headers;
+    }
+    /**
+     * Make an authenticated API request
+     */
+    async request(method, endpoint, options = {}) {
+        let url = `${this.baseUrl}${endpoint}`;
+        const headers = this.getAuthHeaders();
+        // Add query parameters
+        if (options.params) {
+            const searchParams = new URLSearchParams(options.params);
+            url = `${url}?${searchParams}`;
+        }
+        // Build request options
+        const requestOptions = {
+            method,
+            headers,
+        };
+        // Add JSON body
+        if (options.json) {
+            requestOptions.body = JSON.stringify(options.json);
+        }
+        // Add timeout via AbortController
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        requestOptions.signal = controller.signal;
+        try {
+            const response = await fetch(url, requestOptions);
+            clearTimeout(timeoutId);
+            await this.handleResponseErrors(response);
+            // Return binary data for render endpoints
+            if (options.binary) {
+                return await response.arrayBuffer();
+            }
+            // Parse JSON response
+            return await response.json();
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new CanveleteError(`Request timeout after ${this.timeout}ms`);
+            }
+            if (error instanceof CanveleteError) {
+                throw error;
+            }
+            throw new CanveleteError(`Request failed: ${error.message}`);
+        }
+    }
+    /**
+     * Handle HTTP error responses
+     */
+    async handleResponseErrors(response) {
+        if (response.status < 400) {
+            return;
+        }
+        let message = `HTTP ${response.status}`;
+        try {
+            const errorData = await response.json();
+            message = errorData.error || errorData.message || message;
+        }
+        catch {
+            // Ignore JSON parse errors
+        }
+        // Map status codes to exceptions
+        switch (response.status) {
+            case 401:
+                throw new AuthenticationError(message, 401, response);
+            case 403:
+                if (message.toLowerCase().includes('scope')) {
+                    throw new InsufficientScopeError(message, 403, response);
+                }
+                throw new AuthenticationError(message, 403, response);
+            case 404:
+                throw new NotFoundError(message, 404, response);
+            case 422:
+                throw new ValidationError(message, 422, response);
+            case 429:
+                const retryAfter = response.headers.get('Retry-After');
+                throw new RateLimitError(message, retryAfter ? parseInt(retryAfter) : null, 429, response);
+            default:
+                if (response.status >= 500) {
+                    throw new ServerError(message, response.status, response);
+                }
+                throw new CanveleteError(message, response.status, response);
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Custom error classes for Canvelete SDK
+ */
+export declare class CanveleteError extends Error {
+    statusCode: number | null;
+    response: Response | null;
+    constructor(message: string, statusCode?: number | null, response?: Response | null);
+}
+export declare class AuthenticationError extends CanveleteError {
+    constructor(message: string, statusCode?: number | null, response?: Response | null);
+}
+export declare class ValidationError extends CanveleteError {
+    constructor(message: string, statusCode?: number | null, response?: Response | null);
+}
+export declare class NotFoundError extends CanveleteError {
+    constructor(message: string, statusCode?: number | null, response?: Response | null);
+}
+export declare class RateLimitError extends CanveleteError {
+    retryAfter: number | null;
+    constructor(message: string, retryAfter?: number | null, statusCode?: number | null, response?: Response | null);
+}
+export declare class ServerError extends CanveleteError {
+    constructor(message: string, statusCode?: number | null, response?: Response | null);
+}
+export declare class InsufficientScopeError extends CanveleteError {
+    constructor(message: string, statusCode?: number | null, response?: Response | null);
+}

package/dist/errors.js

@@ -0,0 +1,48 @@
+/**
+ * Custom error classes for Canvelete SDK
+ */
+export class CanveleteError extends Error {
+    constructor(message, statusCode = null, response = null) {
+        super(message);
+        this.name = 'CanveleteError';
+        this.statusCode = statusCode;
+        this.response = response;
+    }
+}
+export class AuthenticationError extends CanveleteError {
+    constructor(message, statusCode = null, response = null) {
+        super(message, statusCode, response);
+        this.name = 'AuthenticationError';
+    }
+}
+export class ValidationError extends CanveleteError {
+    constructor(message, statusCode = null, response = null) {
+        super(message, statusCode, response);
+        this.name = 'ValidationError';
+    }
+}
+export class NotFoundError extends CanveleteError {
+    constructor(message, statusCode = null, response = null) {
+        super(message, statusCode, response);
+        this.name = 'NotFoundError';
+    }
+}
+export class RateLimitError extends CanveleteError {
+    constructor(message, retryAfter = null, statusCode = null, response = null) {
+        super(message, statusCode, response);
+        this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
+    }
+}
+export class ServerError extends CanveleteError {
+    constructor(message, statusCode = null, response = null) {
+        super(message, statusCode, response);
+        this.name = 'ServerError';
+    }
+}
+export class InsufficientScopeError extends CanveleteError {
+    constructor(message, statusCode = null, response = null) {
+        super(message, statusCode, response);
+        this.name = 'InsufficientScopeError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Canvelete TypeScript SDK
+ * Official TypeScript client library for the Canvelete API
+ */
+export { CanveleteClient } from './client';
+export type { RequestOptions } from './client';
+export * from './errors';
+export * from './types';
+export * from './resources';

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * Canvelete TypeScript SDK
+ * Official TypeScript client library for the Canvelete API
+ */
+export { CanveleteClient } from './client';
+export * from './errors';
+export * from './types';
+export * from './resources';

package/dist/resources/apiKeys.d.ts

@@ -0,0 +1,22 @@
+import type { CanveleteClient } from '../client';
+import type { APIKey, PaginatedResponse } from '../types';
+export interface ListAPIKeysOptions {
+    page?: number;
+    limit?: number;
+}
+export interface CreateAPIKeyData {
+    name: string;
+    scopes?: string[];
+    expiresAt?: string;
+}
+export interface CreateAPIKeyResponse {
+    data: APIKey & {
+        key: string;
+    };
+}
+export declare class APIKeysResource {
+    private client;
+    constructor(client: CanveleteClient);
+    list(options?: ListAPIKeysOptions): Promise<PaginatedResponse<APIKey>>;
+    create(data: CreateAPIKeyData): Promise<CreateAPIKeyResponse>;
+}

package/dist/resources/apiKeys.js

@@ -0,0 +1,15 @@
+export class APIKeysResource {
+    constructor(client) {
+        this.client = client;
+    }
+    async list(options = {}) {
+        const params = {
+            page: String(options.page || 1),
+            limit: String(options.limit || 20),
+        };
+        return await this.client.request('GET', '/api/automation/api-keys', { params });
+    }
+    async create(data) {
+        return await this.client.request('POST', '/api/automation/api-keys', { json: data });
+    }
+}

package/dist/resources/assets.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Assets resource for managing user assets and searching stock content
+ */
+import type { CanveleteClient } from '../client';
+import type { PaginatedResponse } from '../types';
+export interface Asset {
+    id: string;
+    name: string;
+    type: 'IMAGE' | 'FONT' | 'VIDEO' | 'AUDIO';
+    url: string;
+    format?: string;
+    size?: number;
+    width?: number;
+    height?: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface StockImage {
+    id: string;
+    tags: string;
+    previewURL: string;
+    webformatURL: string;
+    largeImageURL: string;
+    imageWidth: number;
+    imageHeight: number;
+}
+export interface Icon {
+    id: string;
+    name: string;
+    url: string;
+    tags?: string[];
+}
+export interface Font {
+    family: string;
+    variants: string[];
+    category?: string;
+}
+export interface ListAssetsOptions {
+    page?: number;
+    limit?: number;
+    type?: 'IMAGE' | 'FONT' | 'VIDEO' | 'AUDIO';
+}
+export interface SearchOptions {
+    query: string;
+    page?: number;
+    perPage?: number;
+}
+export declare class AssetsResource {
+    private client;
+    constructor(client: CanveleteClient);
+    /**
+     * List user's uploaded assets
+     */
+    list(options?: ListAssetsOptions): Promise<PaginatedResponse<Asset>>;
+    /**
+     * Get a specific asset by ID
+     */
+    get(assetId: string): Promise<{
+        data: Asset;
+    }>;
+    /**
+     * Delete an asset
+     */
+    delete(assetId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Search for stock images from Pixabay
+     */
+    searchStockImages(options: SearchOptions): Promise<{
+        data: StockImage[];
+    }>;
+    /**
+     * Search for icons
+     */
+    searchIcons(options: SearchOptions): Promise<{
+        data: Icon[];
+    }>;
+    /**
+     * Search for clipart
+     */
+    searchClipart(options: SearchOptions & {
+        tag?: string;
+    }): Promise<{
+        data: any[];
+    }>;
+    /**
+     * Search for illustrations
+     */
+    searchIllustrations(options: SearchOptions & {
+        category?: string;
+    }): Promise<{
+        data: any[];
+    }>;
+    /**
+     * List available fonts
+     */
+    listFonts(category?: string): Promise<{
+        data: Font[];
+    }>;
+}

package/dist/resources/assets.js

@@ -0,0 +1,93 @@
+/**
+ * Assets resource for managing user assets and searching stock content
+ */
+export class AssetsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List user's uploaded assets
+     */
+    async list(options = {}) {
+        const params = {
+            page: String(options.page || 1),
+            limit: String(options.limit || 20),
+        };
+        if (options.type) {
+            params.type = options.type;
+        }
+        return await this.client.request('GET', '/api/assets/library', { params });
+    }
+    /**
+     * Get a specific asset by ID
+     */
+    async get(assetId) {
+        return await this.client.request('GET', `/api/assets/${assetId}`);
+    }
+    /**
+     * Delete an asset
+     */
+    async delete(assetId) {
+        return await this.client.request('DELETE', `/api/assets/${assetId}`);
+    }
+    /**
+     * Search for stock images from Pixabay
+     */
+    async searchStockImages(options) {
+        const params = {
+            query: options.query,
+            page: String(options.page || 1),
+            perPage: String(options.perPage || 20),
+        };
+        return await this.client.request('GET', '/api/assets/stock-images', { params });
+    }
+    /**
+     * Search for icons
+     */
+    async searchIcons(options) {
+        const params = {
+            query: options.query,
+            page: String(options.page || 1),
+            perPage: String(options.perPage || 20),
+        };
+        return await this.client.request('GET', '/api/assets/icons', { params });
+    }
+    /**
+     * Search for clipart
+     */
+    async searchClipart(options) {
+        const params = {
+            query: options.query,
+            page: String(options.page || 1),
+            perPage: String(options.perPage || 20),
+        };
+        if (options.tag) {
+            params.tag = options.tag;
+        }
+        return await this.client.request('GET', '/api/assets/clipart', { params });
+    }
+    /**
+     * Search for illustrations
+     */
+    async searchIllustrations(options) {
+        const params = {
+            query: options.query,
+            page: String(options.page || 1),
+            perPage: String(options.perPage || 20),
+        };
+        if (options.category) {
+            params.category = options.category;
+        }
+        return await this.client.request('GET', '/api/assets/illustrations', { params });
+    }
+    /**
+     * List available fonts
+     */
+    async listFonts(category) {
+        const params = {};
+        if (category) {
+            params.category = category;
+        }
+        return await this.client.request('GET', '/api/assets/fonts', { params });
+    }
+}