;
}
+/**
+ * Build a `fetch` mock that returns the given responses in order. Once the list
+ * is exhausted, the last response is repeated (handy for retry tests).
+ */
export function createMockFetch(responses: MockResponse[]) {
let callIndex = 0;
return vi.fn().mockImplementation(async () => {
@@ -13,90 +18,130 @@ export function createMockFetch(responses: MockResponse[]) {
return {
ok: response.status >= 200 && response.status < 300,
status: response.status,
+ statusText: response.statusText || '',
json: async () => response.body,
- body: response.body,
headers: new Headers(response.headers || {}),
};
});
}
-export function createMockStreamFetch(status: number, chunks: string[]) {
- return vi.fn().mockImplementation(async () => {
- const stream = new ReadableStream({
- start(controller) {
- chunks.forEach((chunk) => {
- controller.enqueue(new TextEncoder().encode(chunk));
- });
- controller.close();
- },
- });
-
- return {
- ok: status >= 200 && status < 300,
- status,
- body: stream,
- headers: new Headers({}),
- };
- });
-}
+// --- Real-shape response fixtures (live-verified against api.pictify.io) ---
-export const mockRenderResult = {
- imageUrl: 'https://cdn.pictify.io/renders/abc123.png',
- renderId: 'render_abc123',
- width: 1200,
- height: 630,
- size: 45678,
- format: 'png',
- renderTime: 234,
+/** `POST /image` → `{ url, id, createdAt }` */
+export const mockImageResult = {
+ url: 'https://media.pictify.io/abc123-1780877013849.png',
+ id: 'abc123-1780877013849',
+ createdAt: '2026-06-08T00:03:33.951Z',
};
-export const mockTemplate = {
- id: 'tmpl_abc123',
- name: 'OG Image Template',
- description: 'Template for Open Graph images',
- width: 1200,
- height: 630,
- variables: [
- { name: 'title', type: 'string', required: true },
- { name: 'description', type: 'string', required: false },
+/** `POST /templates/:uid/render` → results[] envelope (single layout) */
+export const mockRenderResult = {
+ results: [
+ {
+ layout: 'default',
+ url: 'https://media.pictify.io/template-renders/render123.png',
+ width: 600,
+ height: 200,
+ format: 'png',
+ name: 'Default',
+ id: 'RENDER123',
+ createdAt: '2026-06-08T00:03:21.992Z',
+ },
],
- previewUrl: 'https://cdn.pictify.io/previews/tmpl_abc123.png',
- createdAt: '2024-01-15T10:30:00Z',
- updatedAt: '2024-01-15T10:30:00Z',
+ errors: [],
+ totalLayouts: 1,
+ totalRendered: 1,
+ totalErrors: 0,
+ templateUid: 'XL13XACH2V',
};
-export const mockBatchResult = {
+/** Multi-layout render: one success + one error entry */
+export const mockLayoutsRenderResult = {
results: [
{
- index: 0,
- success: true,
- variables: ['title'],
- results: [
- {
- layout: 'default',
- name: 'Default',
- url: 'https://cdn.pictify.io/renders/abc123.png',
- width: 1200,
- height: 630,
- format: 'png',
- id: 'img_abc123',
- },
- ],
- errors: [],
+ layout: 'default',
+ url: 'https://media.pictify.io/template-renders/default123.png',
+ width: 600,
+ height: 200,
+ format: 'png',
+ name: 'Default',
+ id: 'DEFAULT123',
+ createdAt: '2026-06-08T00:03:21.992Z',
},
],
- totalTime: 500,
- successCount: 1,
- failedCount: 0,
+ errors: [{ layout: 'bogus-layout', error: "Layout 'bogus-layout' not found" }],
+ totalLayouts: 2,
+ totalRendered: 1,
+ totalErrors: 1,
+ templateUid: 'XL13XACH2V',
+};
+
+/** `POST /gif` → `{ gif: {...}, _meta }` */
+export const mockGifResponse = {
+ gif: {
+ url: 'https://media.pictify.io/gif123-1780877036774.gif',
+ uid: 'gif123-1780877036774',
+ width: 400,
+ height: 200,
+ animationLength: 2000,
+ },
+ _meta: { processingTime: 5273 },
+};
+
+/** `POST /templates/:uid/batch-render` → 202 `{ batchId, status, totalItems, message }` */
+export const mockBatchSubmitResult = {
+ batchId: 'batch_LA7U9OUEYT1I234I',
+ status: 'pending',
+ totalItems: 2,
+ message: 'Batch job created successfully',
+};
+
+/** `GET /templates/batch/:batchId/results` → status + per-item records (NO urls) */
+export const mockBatchResults = {
+ batchId: 'batch_LA7U9OUEYT1I234I',
+ status: 'completed',
+ progress: 100,
+ totalItems: 2,
+ completedItems: 2,
+ failedItems: 0,
+ results: [
+ { index: 0, success: true, variables: ['name', 'company'] },
+ { index: 1, success: true, variables: ['name', 'company'] },
+ ],
+ errors: [],
+ createdAt: '2026-06-08T00:03:59.172Z',
+ startedAt: '2026-06-08T00:03:59.854Z',
+ completedAt: '2026-06-08T00:04:02.204Z',
+};
+
+/** `GET /templates/:uid` / `POST /templates` → `{ template }` envelope */
+export const mockTemplateResponse = {
+ template: {
+ uid: 'XL13XACH2V',
+ name: 'SDK Repoint Test Template',
+ html: 'Hello {{name}} from {{company}}
',
+ width: 600,
+ height: 200,
+ engine: 'html',
+ outputFormat: 'image',
+ variables: ['name', 'company'],
+ variableDefinitions: [
+ { name: 'name', type: 'text', defaultValue: '', validation: { required: false } },
+ { name: 'company', type: 'text', defaultValue: '', validation: { required: false } },
+ ],
+ createdAt: '2026-06-07T23:56:43.669Z',
+ },
};
-export const mockGifResult = {
- gifUrl: 'https://cdn.pictify.io/renders/abc123.gif',
- renderId: 'render_abc123',
- width: 800,
- height: 600,
- size: 123456,
- frameCount: 3,
- duration: 300,
- renderTime: 1234,
+/** `GET /templates` → `{ templates, pagination }` */
+export const mockListTemplatesResult = {
+ templates: [mockTemplateResponse.template],
+ pagination: {
+ page: 1,
+ limit: 12,
+ total: 1,
+ totalPages: 1,
+ hasNext: false,
+ hasPrev: false,
+ },
};
diff --git a/src/__tests__/integration/client.integration.test.ts b/src/__tests__/integration/client.integration.test.ts
new file mode 100644
index 0000000..24bf8c6
--- /dev/null
+++ b/src/__tests__/integration/client.integration.test.ts
@@ -0,0 +1,266 @@
+/**
+ * Integration tests — exercise every public method against the REAL Pictify API.
+ *
+ * SKIPPED unless PICTIFY_API_KEY is set, so they're safe in the default test run
+ * (they collect, then skip). These make real network calls and create real
+ * renders, which consumes quota — keep the set tight.
+ *
+ * Run live:
+ *
+ * PICTIFY_API_KEY=sk_xxx PICTIFY_TEMPLATE_ID=XL13XACH2V \
+ * npx vitest run src/__tests__/integration
+ *
+ * Optional overrides:
+ * PICTIFY_BASE_URL — non-prod API base (default: https://api.pictify.io)
+ * PICTIFY_TEMPLATE_ID — a template UID in your account (variables: name, company).
+ * Also accepts the legacy PICTIFY_TEST_TEMPLATE_ID.
+ * When unset, template-dependent cases skip.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { Pictify } from '../../client';
+import { PictifyError, TemplateNotFoundError } from '../../errors';
+import type {
+ ImageResult,
+ RenderResult,
+ GifRenderResult,
+ BatchRenderResult,
+ BatchResults,
+ Template,
+ ListTemplatesResult,
+} from '../../types';
+
+const API_KEY = process.env.PICTIFY_API_KEY;
+const BASE_URL = process.env.PICTIFY_BASE_URL || 'https://api.pictify.io';
+const TEMPLATE_ID =
+ process.env.PICTIFY_TEMPLATE_ID || process.env.PICTIFY_TEST_TEMPLATE_ID;
+
+// Real renders (especially GIFs) can be slow; give each case headroom.
+const NETWORK_TIMEOUT = 90_000;
+
+const describeIfKey = describe.skipIf(!API_KEY);
+const itIfTemplate = (API_KEY && TEMPLATE_ID ? it : it.skip) as typeof it;
+
+const URL_RE = /^https?:\/\//;
+
+describeIfKey('Pictify integration (live API)', () => {
+ let client: Pictify;
+
+ beforeAll(() => {
+ // Non-null assertion is safe: the suite is skipped when API_KEY is absent.
+ client = new Pictify({ apiKey: API_KEY!, baseUrl: BASE_URL });
+ });
+
+ describe('renderHtml()', () => {
+ it(
+ 'renders a PNG from raw HTML and returns a real URL',
+ async () => {
+ const result: ImageResult = await client.renderHtml({
+ html: 'Integration test
',
+ width: 600,
+ height: 300,
+ });
+ expect(result.url).toMatch(URL_RE);
+ expect(result.id).toBeTruthy();
+ expect(result.createdAt).toBeTruthy();
+ // eslint-disable-next-line no-console
+ console.log('[integration] renderHtml ->', result.url);
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+
+ describe('renderUrl()', () => {
+ it(
+ 'screenshots a live URL and returns a real URL',
+ async () => {
+ const result: ImageResult = await client.renderUrl({
+ url: 'https://example.com',
+ width: 800,
+ height: 600,
+ });
+ expect(result.url).toMatch(URL_RE);
+ // eslint-disable-next-line no-console
+ console.log('[integration] renderUrl ->', result.url);
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+
+ describe('render() — template', () => {
+ itIfTemplate(
+ 'renders a single image from the template with {name, company}',
+ async () => {
+ const result: RenderResult = await client.render({
+ templateId: TEMPLATE_ID!,
+ variables: { name: 'Ada', company: 'Pictify' },
+ format: 'png',
+ });
+ expect(Array.isArray(result.results)).toBe(true);
+ expect(result.results.length).toBeGreaterThan(0);
+ expect(result.url).toMatch(URL_RE);
+ expect(result.templateUid).toBe(TEMPLATE_ID);
+ // eslint-disable-next-line no-console
+ console.log('[integration] render ->', result.url);
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+
+ describe('renderLayouts()', () => {
+ itIfTemplate(
+ 'renders `default` and routes a bogus layout into errors[]',
+ async () => {
+ const result: RenderResult = await client.renderLayouts({
+ templateId: TEMPLATE_ID!,
+ variables: { name: 'Ada', company: 'Pictify' },
+ layouts: ['default', 'definitely-not-a-real-layout'],
+ });
+ expect(Array.isArray(result.results)).toBe(true);
+ // 'default' should render successfully...
+ const defaultItem = result.results.find((r) => r.layout === 'default');
+ expect(defaultItem?.url).toMatch(URL_RE);
+ // ...and the bogus layout should land in errors[].
+ expect(result.errors.length).toBeGreaterThan(0);
+ expect(result.errors.some((e) => e.layout === 'definitely-not-a-real-layout')).toBe(
+ true
+ );
+ // eslint-disable-next-line no-console
+ console.log(
+ '[integration] renderLayouts -> default:',
+ defaultItem?.url,
+ '| errors:',
+ result.errors.map((e) => e.layout)
+ );
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+
+ describe('renderGif()', () => {
+ it(
+ 'renders an animated GIF from raw HTML',
+ async () => {
+ const result: GifRenderResult = await client.renderGif({
+ html:
+ '' +
+ 'gif test
',
+ width: 400,
+ height: 200,
+ quality: 'low',
+ });
+ expect(result.url).toMatch(URL_RE);
+ expect(result.uid).toBeTruthy();
+ expect(result.animationLength).toBeGreaterThan(0);
+ // eslint-disable-next-line no-console
+ console.log('[integration] renderGif ->', result.url);
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+
+ describe('listTemplates()', () => {
+ it(
+ 'returns { templates, pagination }',
+ async () => {
+ const result: ListTemplatesResult = await client.listTemplates({ limit: 5 });
+ expect(Array.isArray(result.templates)).toBe(true);
+ expect(result.pagination).toBeTruthy();
+ expect(typeof result.pagination.total).toBe('number');
+ // eslint-disable-next-line no-console
+ console.log(
+ '[integration] listTemplates -> total:',
+ result.pagination.total,
+ '| page size:',
+ result.templates.length
+ );
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+
+ describe('getTemplate()', () => {
+ itIfTemplate(
+ 'returns the unwrapped template by uid',
+ async () => {
+ const template: Template = await client.getTemplate(TEMPLATE_ID!);
+ expect(template.uid).toBe(TEMPLATE_ID);
+ expect(template).not.toHaveProperty('template'); // already unwrapped
+ // eslint-disable-next-line no-console
+ console.log('[integration] getTemplate ->', template.uid, template.name);
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+
+ describe('createTemplate()', () => {
+ it(
+ 'creates a throwaway html template and returns a uid',
+ async () => {
+ const template: Template = await client.createTemplate({
+ html: 'Hi {{firstName}}
',
+ name: `SDK integration throwaway ${Date.now()}`,
+ width: 400,
+ height: 150,
+ });
+ expect(template.uid).toBeTruthy();
+ // Variables auto-extracted from {{firstName}}.
+ const names = (template.variableDefinitions || []).map((v) => v.name);
+ expect(names).toContain('firstName');
+ // eslint-disable-next-line no-console
+ console.log('[integration] createTemplate -> uid:', template.uid);
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+
+ describe('renderBatch() + getBatchResults()', () => {
+ itIfTemplate(
+ 'submits a batch (returns batchId) and polls results once',
+ async () => {
+ const submit: BatchRenderResult = await client.renderBatch({
+ templateId: TEMPLATE_ID!,
+ variableSets: [
+ { name: 'A', company: 'X' },
+ { name: 'B', company: 'Y' },
+ ],
+ format: 'png',
+ });
+ expect(submit.batchId).toBeTruthy();
+ expect(submit.totalItems).toBe(2);
+ // eslint-disable-next-line no-console
+ console.log('[integration] renderBatch -> batchId:', submit.batchId, submit.status);
+
+ // Poll once. The job may still be pending — assert tolerantly.
+ const results: BatchResults = await client.getBatchResults(submit.batchId);
+ expect(results.batchId).toBe(submit.batchId);
+ expect(results.totalItems).toBe(2);
+ expect(
+ ['pending', 'processing', 'completed', 'partial', 'failed', 'cancelled']
+ ).toContain(results.status);
+ // eslint-disable-next-line no-console
+ console.log(
+ '[integration] getBatchResults -> status:',
+ results.status,
+ '| completed:',
+ results.completedItems
+ );
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+
+ describe('error path (live)', () => {
+ it(
+ 'throws TemplateNotFoundError for a non-existent template',
+ async () => {
+ const err = await client
+ .getTemplate('definitely-not-a-real-template-id-xyz')
+ .catch((e) => e);
+ expect(err).toBeInstanceOf(PictifyError);
+ expect(err).toBeInstanceOf(TemplateNotFoundError);
+ },
+ NETWORK_TIMEOUT
+ );
+ });
+});
diff --git a/src/client.ts b/src/client.ts
index 532d67c..f2142cb 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -1,13 +1,20 @@
import {
PictifyConfig,
+ RenderHtmlOptions,
+ RenderUrlOptions,
+ ImageResult,
RenderOptions,
+ RenderLayoutsOptions,
RenderResult,
+ GifRenderOptions,
+ GifRenderResult,
BatchRenderOptions,
BatchRenderResult,
+ BatchResults,
Template,
- HTMLRenderOptions,
- GIFRenderOptions,
- GIFRenderResult,
+ ListTemplatesOptions,
+ ListTemplatesResult,
+ CreateTemplateOptions,
} from './types';
import {
PictifyError,
@@ -15,29 +22,38 @@ import {
NetworkError,
TimeoutError,
createErrorFromResponse,
+ ApiErrorBody,
} from './errors';
const DEFAULT_BASE_URL = 'https://api.pictify.io';
const DEFAULT_TIMEOUT = 30000;
const DEFAULT_RETRIES = 3;
+const SDK_VERSION = '1.0.0';
/**
- * Pictify client for generating images from HTML templates
+ * Pictify client — generate images, PDFs, and GIFs from raw HTML, live URLs,
+ * and reusable templates via the Pictify API.
*
* @example
* ```typescript
* import { Pictify } from '@pictify/sdk';
*
- * const pictify = new Pictify({
- * apiKey: process.env.PICTIFY_API_KEY
+ * const pictify = new Pictify({ apiKey: process.env.PICTIFY_API_KEY! });
+ *
+ * // Render raw HTML to a PNG
+ * const image = await pictify.renderHtml({
+ * html: 'Hello World
',
+ * width: 1200,
+ * height: 630,
* });
+ * console.log(image.url);
*
+ * // Render a template
* const result = await pictify.render({
- * templateId: 'your-template-id',
- * variables: { title: 'Hello World' }
+ * templateId: 'your-template-uid',
+ * variables: { name: 'Ada', company: 'Pictify' },
* });
- *
- * console.log(result.imageUrl);
+ * console.log(result.url); // results[0].url
* ```
*/
export class Pictify {
@@ -57,302 +73,314 @@ export class Pictify {
this.retries = config.retries ?? DEFAULT_RETRIES;
}
+ // ---------------------------------------------------------------------------
+ // Image rendering (POST /image)
+ // ---------------------------------------------------------------------------
+
+ /**
+ * Render an image (or PDF) directly from HTML.
+ *
+ * `POST /image` — returns `{ url, id, createdAt }`.
+ *
+ * @example
+ * ```typescript
+ * const image = await pictify.renderHtml({
+ * html: 'Hello
',
+ * css: 'div { color: blue; }',
+ * width: 1200,
+ * height: 630,
+ * format: 'png',
+ * });
+ * console.log(image.url);
+ * ```
+ */
+ async renderHtml(options: RenderHtmlOptions): Promise {
+ const html = options.css
+ ? `${options.html}`
+ : options.html;
+
+ return this.request('/image', {
+ method: 'POST',
+ body: {
+ html,
+ width: options.width,
+ height: options.height,
+ selector: options.selector,
+ fileExtension: options.format || 'png',
+ },
+ });
+ }
+
+ /**
+ * Screenshot a live URL.
+ *
+ * `POST /image` with `url` — returns `{ url, id, createdAt }`.
+ *
+ * @example
+ * ```typescript
+ * const image = await pictify.renderUrl({
+ * url: 'https://example.com',
+ * width: 1280,
+ * height: 720,
+ * });
+ * console.log(image.url);
+ * ```
+ */
+ async renderUrl(options: RenderUrlOptions): Promise {
+ return this.request('/image', {
+ method: 'POST',
+ body: {
+ url: options.url,
+ width: options.width,
+ height: options.height,
+ selector: options.selector,
+ fileExtension: options.format || 'png',
+ },
+ });
+ }
+
+ // ---------------------------------------------------------------------------
+ // Template rendering (POST /templates/:uid/render)
+ // ---------------------------------------------------------------------------
+
/**
- * Render an image from a template
+ * Render a single image (or PDF) from a template.
*
- * @param options - Render options including template ID and variables
- * @returns Render result with image URL or buffer
+ * `POST /templates/:uid/render` — returns the `results[]` envelope with a
+ * convenience `url` getter (`results[0]?.url`).
*
* @example
* ```typescript
* const result = await pictify.render({
* templateId: 'og-image-template',
- * variables: {
- * title: 'My Blog Post',
- * description: 'A great article about something'
- * },
+ * variables: { title: 'My Post', author: 'Ada' },
* format: 'png',
- * width: 1200,
- * height: 630
* });
+ * console.log(result.url);
* ```
*/
async render(options: RenderOptions): Promise {
const body: Record = {
- templateId: options.templateId,
variables: options.variables || {},
format: options.format || 'png',
+ quality: options.quality,
width: options.width,
height: options.height,
- deviceScaleFactor: options.deviceScaleFactor,
- transparent: options.transparent,
- quality: options.quality,
- download: options.download,
};
-
- if (options.layout) {
- body.layout = options.layout;
- }
- if (options.layouts) {
- body.layouts = options.layouts;
- }
-
- const response = await this.request('/render', {
- method: 'POST',
- body,
- });
-
- return this.normalizeRenderResult(response);
+ if (options.layout) body.layout = options.layout;
+ if (options.layouts) body.layouts = options.layouts;
+
+ const response = await this.request>(
+ `/templates/${encodeURIComponent(options.templateId)}/render`,
+ { method: 'POST', body }
+ );
+ return this.withUrlGetter(response);
}
/**
- * Render multiple layout variants of a template in a single call
+ * Render multiple layout variants of a template in a single call.
*
- * @param options - Render options with required `layouts` array
- * @returns Render result containing one entry per layout in `results`
+ * `POST /templates/:uid/render` with `layouts` — returns one `results[]` item
+ * per successful layout; missing/invalid layouts appear in `errors[]`.
*
* @example
* ```typescript
* const result = await pictify.renderLayouts({
* templateId: 'og-image-template',
- * variables: { title: 'Hello World' },
- * layouts: ['landscape', 'square', 'story']
+ * variables: { title: 'Hello' },
+ * layouts: ['default', 'square', 'story'],
* });
- *
- * for (const item of result.results) {
- * console.log(`${item.layout}: ${item.url}`);
- * }
+ * for (const item of result.results) console.log(item.layout, item.url);
* ```
*/
- async renderLayouts(
- options: RenderOptions & { layouts: string[] }
- ): Promise {
+ async renderLayouts(options: RenderLayoutsOptions): Promise {
return this.render(options);
}
+ // ---------------------------------------------------------------------------
+ // GIF rendering (POST /gif)
+ // ---------------------------------------------------------------------------
+
/**
- * Render an image and return it as a readable stream
+ * Render an animated GIF from raw HTML, a live URL, or a template.
+ *
+ * `POST /gif` — the `{ gif: {...} }` envelope is flattened to
+ * `{ url, uid, width, height, animationLength }`. Provide exactly one source:
+ * `html`, `url`, or `templateId`.
*
- * @param options - Render options
- * @returns Readable stream of image data
+ * @example
+ * ```typescript
+ * const gif = await pictify.renderGif({
+ * html: 'Hi
',
+ * width: 400,
+ * height: 200,
+ * quality: 'medium',
+ * });
+ * console.log(gif.url);
+ * ```
*/
- async renderStream(options: Omit): Promise {
- const response = await this.rawRequest('/render/stream', {
+ async renderGif(options: GifRenderOptions): Promise {
+ const body: Record = {
+ width: options.width,
+ height: options.height,
+ quality: options.quality || 'medium',
+ };
+ if (options.html) body.html = options.html;
+ if (options.url) body.url = options.url;
+ if (options.templateId) body.template = options.templateId;
+ if (options.variables) body.variables = options.variables;
+
+ const response = await this.request<{ gif: GifRenderResult }>('/gif', {
method: 'POST',
- body: {
- templateId: options.templateId,
- variables: options.variables || {},
- format: options.format || 'png',
- width: options.width,
- height: options.height,
- deviceScaleFactor: options.deviceScaleFactor,
- transparent: options.transparent,
- quality: options.quality,
- },
+ body,
});
-
- if (!response.body) {
- throw new NetworkError('No response body received');
- }
-
- return response.body as unknown as NodeJS.ReadableStream;
+ return response.gif;
}
+ // ---------------------------------------------------------------------------
+ // Batch rendering (async)
+ // ---------------------------------------------------------------------------
+
/**
- * Render multiple images in a single batch request
+ * Submit an async batch render of a template across many variable sets.
*
- * @param options - Batch render options
- * @returns Batch render results
+ * `POST /templates/:uid/batch-render` — returns `{ batchId, status, totalItems }`
+ * immediately (HTTP 202). Poll {@link Pictify.getBatchResults} to track progress.
+ *
+ * Rendered URLs are NOT returned by the poll endpoint — they are delivered via
+ * the `render.completed` webhook.
*
* @example
* ```typescript
- * const results = await pictify.renderBatch({
+ * const job = await pictify.renderBatch({
* templateId: 'product-card',
- * items: products.map(p => ({
- * variables: { name: p.name, price: p.price }
- * }))
+ * variableSets: products.map((p) => ({ name: p.name, price: p.price })),
* });
+ * const status = await pictify.getBatchResults(job.batchId);
* ```
*/
async renderBatch(options: BatchRenderOptions): Promise {
- if (options.items.length > 500) {
- throw new PictifyError(
- 'Batch size cannot exceed 500 items',
- 'INVALID_VARIABLES',
- 400
- );
- }
-
const body: Record = {
- templateId: options.templateId,
- items: options.items,
+ variableSets: options.variableSets,
format: options.format || 'png',
- width: options.width,
- height: options.height,
+ quality: options.quality,
+ concurrency: options.concurrency,
};
+ if (options.layout) body.layout = options.layout;
+ if (options.layouts) body.layouts = options.layouts;
- if (options.layout) {
- body.layout = options.layout;
- }
- if (options.layouts) {
- body.layouts = options.layouts;
- }
+ return this.request(
+ `/templates/${encodeURIComponent(options.templateId)}/batch-render`,
+ { method: 'POST', body }
+ );
+ }
- const response = await this.request('/render/batch', {
- method: 'POST',
- body,
- });
+ /**
+ * Get the status, progress, and per-item results of a batch job.
+ *
+ * `GET /templates/batch/:batchId/results`. Results carry `{ index, success,
+ * variables }` (and `error` on failures) but NOT rendered URLs.
+ */
+ async getBatchResults(batchId: string): Promise {
+ return this.request(
+ `/templates/batch/${encodeURIComponent(batchId)}/results`,
+ { method: 'GET' }
+ );
+ }
+
+ // ---------------------------------------------------------------------------
+ // Template CRUD
+ // ---------------------------------------------------------------------------
- return response;
+ /**
+ * Get a single template by its UID.
+ *
+ * `GET /templates/:uid` — unwraps the `{ template }` envelope.
+ */
+ async getTemplate(templateId: string): Promise {
+ const response = await this.request<{ template: Template }>(
+ `/templates/${encodeURIComponent(templateId)}`,
+ { method: 'GET' }
+ );
+ return response.template;
}
/**
- * Render an image directly from HTML without using a template
+ * List templates in your account.
*
- * @param options - HTML render options
- * @returns Render result with image URL or buffer
+ * `GET /templates` — returns `{ templates, pagination }`.
*
* @example
* ```typescript
- * const result = await pictify.renderHtml({
- * html: 'Hello World
',
- * css: 'div { color: blue; }',
- * width: 1200,
- * height: 630
- * });
+ * const { templates, pagination } = await pictify.listTemplates({ limit: 20 });
* ```
*/
- async renderHtml(options: HTMLRenderOptions): Promise {
- const response = await this.request('/render/html', {
- method: 'POST',
- body: {
- html: options.html,
- css: options.css,
- format: options.format || 'png',
- width: options.width || 1200,
- height: options.height || 630,
- deviceScaleFactor: options.deviceScaleFactor,
- transparent: options.transparent,
- quality: options.quality,
- download: options.download,
- },
+ async listTemplates(options: ListTemplatesOptions = {}): Promise {
+ const query = new URLSearchParams();
+ if (options.page !== undefined) query.set('page', String(options.page));
+ if (options.limit !== undefined) query.set('limit', String(options.limit));
+ if (options.sort !== undefined) query.set('sort', options.sort);
+ const qs = query.toString();
+
+ return this.request(`/templates${qs ? `?${qs}` : ''}`, {
+ method: 'GET',
});
-
- return response;
}
/**
- * Render an animated GIF from a template or raw HTML
+ * Create a template from HTML. Variables are auto-discovered from
+ * `{{variableName}}` tokens in the HTML body.
*
- * @param options - GIF render options with frames
- * @returns GIF render result with URL or buffer
+ * `POST /templates` — unwraps the `{ template }` envelope.
*
* @example
* ```typescript
- * const result = await pictify.renderGif({
- * templateId: 'animation-template',
- * frames: [
- * { variables: { text: 'Frame 1' } },
- * { variables: { text: 'Frame 2' } },
- * { variables: { text: 'Frame 3' } }
- * ],
- * delay: 500,
- * loop: 0
+ * const template = await pictify.createTemplate({
+ * html: 'Hi {{firstName}}
',
+ * name: 'Welcome Card',
+ * width: 600,
+ * height: 200,
* });
+ * console.log(template.uid);
* ```
*/
- async renderGif(options: GIFRenderOptions): Promise {
- if (options.frames.length === 0) {
- throw new PictifyError(
- 'At least one frame is required',
- 'INVALID_FRAMES',
- 400
- );
- }
-
- if (options.frames.length > 100) {
- throw new PictifyError(
- 'GIF cannot exceed 100 frames',
- 'INVALID_FRAMES',
- 400
- );
- }
-
- const response = await this.request('/render/gif', {
+ async createTemplate(options: CreateTemplateOptions): Promise {
+ const response = await this.request<{ template: Template }>('/templates', {
method: 'POST',
body: {
- templateId: options.templateId,
html: options.html,
- css: options.css,
- frames: options.frames,
+ name: options.name,
width: options.width,
height: options.height,
- delay: options.delay || 100,
- loop: options.loop ?? 0,
- quality: options.quality,
+ variableDefinitions: options.variableDefinitions,
+ outputFormat: options.outputFormat,
},
});
-
- return response;
+ return response.template;
}
- /**
- * Get details about a template
- *
- * @param templateId - The template ID
- * @returns Template details including variables
- */
- async getTemplate(templateId: string): Promise {
- return this.request(`/templates/${templateId}`, {
- method: 'GET',
- });
- }
+ // ---------------------------------------------------------------------------
+ // Internals
+ // ---------------------------------------------------------------------------
/**
- * List all templates in your account
- *
- * @returns Array of templates
+ * Attach a non-enumerable `url` convenience getter (`results[0]?.url`) to a
+ * template render response.
*/
- async listTemplates(): Promise {
- const response = await this.request<{ templates: Template[] }>('/templates', {
- method: 'GET',
+ private withUrlGetter(response: Omit): RenderResult {
+ Object.defineProperty(response, 'url', {
+ get(this: Omit) {
+ return this.results?.[0]?.url;
+ },
+ enumerable: false,
+ configurable: true,
});
- return response.templates;
- }
-
- /**
- * Normalize the API response to provide backward-compatible fields.
- * Sets top-level `url`, `imageUrl`, `width`, `height`, `format`, and `renderId`
- * from the first item in `results[]` so that existing code continues to work.
- */
- private normalizeRenderResult(response: RenderResult): RenderResult {
- // If the response already has `results`, add backward-compat getters
- if (response.results && response.results.length > 0) {
- const first = response.results[0];
- if (!response.url) {
- response.url = first.url;
- }
- if (!response.imageUrl) {
- response.imageUrl = first.url;
- }
- if (!response.renderId) {
- response.renderId = first.id;
- }
- if (!response.width) {
- response.width = first.width;
- }
- if (!response.height) {
- response.height = first.height;
- }
- if (!response.format) {
- response.format = first.format;
- }
- }
- return response;
+ return response as RenderResult;
}
/**
- * Make an authenticated request to the API
+ * Make an authenticated JSON request, parsing the body and mapping HTTP
+ * errors to typed PictifyErrors.
*/
private async request(
endpoint: string,
@@ -362,17 +390,29 @@ export class Pictify {
}
): Promise {
const response = await this.rawRequest(endpoint, options);
- const data = await response.json();
+
+ let data: unknown = null;
+ try {
+ data = await response.json();
+ } catch {
+ // Non-JSON or empty body — leave data null.
+ }
if (!response.ok) {
- throw createErrorFromResponse(response.status, data);
+ throw createErrorFromResponse(
+ response.status,
+ data as ApiErrorBody,
+ response.statusText
+ );
}
return data as T;
}
/**
- * Make a raw request to the API
+ * Make a raw fetch request with auth headers, timeout, and retry on 5xx /
+ * network failures. JSON bodies have `undefined` fields stripped so the API
+ * sees only the fields the caller actually set.
*/
private async rawRequest(
endpoint: string,
@@ -382,13 +422,16 @@ export class Pictify {
}
): Promise {
const url = `${this.baseUrl}${endpoint}`;
-
const headers: Record = {
Authorization: `Bearer ${this.apiKey}`,
'Content-Type': 'application/json',
- 'User-Agent': '@pictify/sdk/1.0.0',
+ 'User-Agent': `@pictify/sdk/${SDK_VERSION}`,
};
+ const serializedBody = options.body
+ ? JSON.stringify(this.stripUndefined(options.body))
+ : undefined;
+
let lastError: Error | null = null;
for (let attempt = 0; attempt <= this.retries; attempt++) {
@@ -396,37 +439,39 @@ export class Pictify {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), this.timeout);
- const response = await fetch(url, {
- method: options.method,
- headers,
- body: options.body ? JSON.stringify(options.body) : undefined,
- signal: controller.signal,
- });
-
- clearTimeout(timeoutId);
+ let response: Response;
+ try {
+ response = await fetch(url, {
+ method: options.method,
+ headers,
+ body: serializedBody,
+ signal: controller.signal,
+ });
+ } finally {
+ clearTimeout(timeoutId);
+ }
- // Don't retry on client errors (4xx)
+ // Don't retry on client errors (4xx) — return for typed mapping.
if (response.status >= 400 && response.status < 500) {
return response;
}
- // Retry on server errors (5xx)
- if (response.status >= 500) {
+ // Retry on server errors (5xx).
+ if (response.status >= 500 && attempt < this.retries) {
lastError = new Error(`Server error: ${response.status}`);
- if (attempt < this.retries) {
- await this.sleep(Math.pow(2, attempt) * 1000);
- continue;
- }
+ await this.sleep(Math.pow(2, attempt) * 1000);
+ continue;
}
return response;
} catch (error) {
if (error instanceof Error) {
- if (error.name === 'AbortError') {
- lastError = new TimeoutError();
- } else {
- lastError = new NetworkError(error.message);
- }
+ lastError =
+ error.name === 'AbortError'
+ ? new TimeoutError()
+ : new NetworkError(error.message);
+ } else {
+ lastError = new NetworkError('Request failed');
}
if (attempt < this.retries) {
@@ -439,7 +484,18 @@ export class Pictify {
throw lastError || new NetworkError('Request failed after retries');
}
+ private stripUndefined(obj: Record): Record {
+ const out: Record = {};
+ for (const [key, value] of Object.entries(obj)) {
+ if (value !== undefined) out[key] = value;
+ }
+ return out;
+ }
+
private sleep(ms: number): Promise {
return new Promise((resolve) => setTimeout(resolve, ms));
}
}
+
+// Re-export PictifyError so consumers can `import { Pictify, PictifyError }`.
+export { PictifyError };
diff --git a/src/errors.ts b/src/errors.ts
index 85de3f0..ee20dfb 100644
--- a/src/errors.ts
+++ b/src/errors.ts
@@ -1,5 +1,25 @@
import { PictifyErrorCode } from './types';
+/**
+ * Shape of an error response body from the Pictify API.
+ *
+ * There is no unified error envelope: image/GIF endpoints return `{ error, code }`,
+ * while template/CRUD endpoints return `{ message }` or `{ message, errors }`.
+ * The SDK reads both keys.
+ */
+export interface ApiErrorBody {
+ /** Error message (image/GIF endpoints) */
+ error?: string;
+ /** Error message (template/CRUD/auth endpoints) */
+ message?: string;
+ /** Backend error code (e.g. "quota_exceeded") */
+ code?: string;
+ /** Field-level validation errors (422 responses) */
+ errors?: unknown;
+ /** Additional context */
+ [key: string]: unknown;
+}
+
/**
* Base error class for Pictify SDK errors
*/
@@ -31,7 +51,7 @@ export class PictifyError extends Error {
}
/**
- * Error thrown when authentication fails
+ * Error thrown when authentication fails (HTTP 401)
*/
export class AuthenticationError extends PictifyError {
constructor(message: string = 'Invalid or missing API key') {
@@ -41,17 +61,17 @@ export class AuthenticationError extends PictifyError {
}
/**
- * Error thrown when a template is not found
+ * Error thrown when a template is not found (HTTP 404)
*/
export class TemplateNotFoundError extends PictifyError {
- constructor(templateId: string) {
- super(`Template not found: ${templateId}`, 'TEMPLATE_NOT_FOUND', 404);
+ constructor(message: string = 'Template not found') {
+ super(message, 'TEMPLATE_NOT_FOUND', 404);
this.name = 'TemplateNotFoundError';
}
}
/**
- * Error thrown when rate limit is exceeded
+ * Error thrown when the rate limit is exceeded (HTTP 429 without a quota code)
*/
export class RateLimitError extends PictifyError {
/** When the rate limit resets */
@@ -59,7 +79,7 @@ export class RateLimitError extends PictifyError {
/** Number of requests remaining */
public readonly remaining?: number;
- constructor(message: string, resetAt?: Date, remaining?: number) {
+ constructor(message: string = 'Rate limit exceeded', resetAt?: Date, remaining?: number) {
super(message, 'RATE_LIMIT_EXCEEDED', 429);
this.name = 'RateLimitError';
this.resetAt = resetAt;
@@ -68,27 +88,42 @@ export class RateLimitError extends PictifyError {
}
/**
- * Error thrown when quota is exceeded
+ * Error thrown when the render quota is exceeded (HTTP 402, or 429 with a quota code)
*/
export class QuotaExceededError extends PictifyError {
- constructor(message: string = 'Monthly render quota exceeded') {
- super(message, 'QUOTA_EXCEEDED', 402);
+ constructor(message: string = 'Render quota exceeded', statusCode: number = 402) {
+ super(message, 'QUOTA_EXCEEDED', statusCode);
this.name = 'QuotaExceededError';
}
}
/**
- * Error thrown when render fails
+ * Error thrown when a render fails or input validation fails (HTTP 422,
+ * and non-quota 4xx). Carries field-level `errors` from the API when present.
*/
export class RenderError extends PictifyError {
- constructor(message: string, details?: Record) {
- super(message, 'RENDER_FAILED', 500, details);
+ /** Field-level validation errors returned by the API (422 responses) */
+ public readonly errors?: unknown;
+
+ constructor(message: string, details?: Record, statusCode: number = 422) {
+ super(message, 'RENDER_FAILED', statusCode, details);
this.name = 'RenderError';
+ this.errors = details?.errors;
+ }
+}
+
+/**
+ * Error thrown when the server fails (HTTP 5xx)
+ */
+export class ServerError extends PictifyError {
+ constructor(message: string, statusCode: number = 500, details?: Record) {
+ super(message, 'SERVER_ERROR', statusCode, details);
+ this.name = 'ServerError';
}
}
/**
- * Error thrown when network request fails
+ * Error thrown when a network request fails
*/
export class NetworkError extends PictifyError {
constructor(message: string) {
@@ -98,7 +133,7 @@ export class NetworkError extends PictifyError {
}
/**
- * Error thrown when request times out
+ * Error thrown when a request times out
*/
export class TimeoutError extends PictifyError {
constructor(message: string = 'Request timed out') {
@@ -108,31 +143,50 @@ export class TimeoutError extends PictifyError {
}
/**
- * Maps HTTP status codes to error classes
+ * Map an HTTP error response to a typed PictifyError.
+ *
+ * Message resolution: `body.error ?? body.message ?? statusText`.
+ *
+ * Status mapping:
+ * - 401 → AuthenticationError
+ * - 402 → QuotaExceededError
+ * - 404 → TemplateNotFoundError
+ * - 422 → RenderError (validation; includes `body.errors`)
+ * - 429 → QuotaExceededError when `code === 'quota_exceeded'`, else RateLimitError
+ * - other 4xx → RenderError
+ * - 5xx → ServerError
*/
export function createErrorFromResponse(
statusCode: number,
- body: { message?: string; code?: string; details?: Record }
+ body: ApiErrorBody | undefined | null,
+ statusText: string = ''
): PictifyError {
- const message = body.message || 'An unexpected error occurred';
+ const safeBody: ApiErrorBody = body || {};
+ const message =
+ safeBody.error ?? safeBody.message ?? (statusText || 'An unexpected error occurred');
+ const details: Record = { ...safeBody };
switch (statusCode) {
case 401:
return new AuthenticationError(message);
+ case 402:
+ return new QuotaExceededError(message, 402);
case 404:
- return new PictifyError(message, 'TEMPLATE_NOT_FOUND', 404, body.details);
+ return new TemplateNotFoundError(message);
+ case 422:
+ return new RenderError(message, details, 422);
case 429:
+ if (safeBody.code === 'quota_exceeded') {
+ return new QuotaExceededError(message, 429);
+ }
return new RateLimitError(message);
- case 402:
- return new QuotaExceededError(message);
- case 400:
- return new PictifyError(message, 'INVALID_VARIABLES', 400, body.details);
- case 500:
- case 502:
- case 503:
- case 504:
- return new RenderError(message, body.details);
default:
- return new PictifyError(message, 'UNKNOWN_ERROR', statusCode, body.details);
+ if (statusCode >= 500) {
+ return new ServerError(message, statusCode, details);
+ }
+ if (statusCode >= 400) {
+ return new RenderError(message, details, statusCode);
+ }
+ return new PictifyError(message, 'UNKNOWN_ERROR', statusCode, details);
}
}
diff --git a/src/index.ts b/src/index.ts
index 4a3c8b9..9338e07 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,25 +1,29 @@
/**
* Pictify Node.js SDK
*
- * Official SDK for generating images from HTML templates using the Pictify API.
+ * Official SDK for generating images, PDFs, and GIFs from HTML, live URLs, and
+ * reusable templates using the Pictify API.
*
* @example
* ```typescript
* import { Pictify } from '@pictify/sdk';
*
- * const pictify = new Pictify({
- * apiKey: process.env.PICTIFY_API_KEY
+ * const pictify = new Pictify({ apiKey: process.env.PICTIFY_API_KEY! });
+ *
+ * // Raw HTML → image
+ * const image = await pictify.renderHtml({
+ * html: 'Hello World
',
+ * width: 1200,
+ * height: 630,
* });
+ * console.log(image.url);
*
+ * // Template → image
* const result = await pictify.render({
- * templateId: 'your-template-id',
- * variables: {
- * title: 'Hello World',
- * subtitle: 'Generated with Pictify'
- * }
+ * templateId: 'your-template-uid',
+ * variables: { title: 'Hello World' },
* });
- *
- * console.log('Image URL:', result.imageUrl);
+ * console.log(result.url);
* ```
*
* @packageDocumentation
diff --git a/src/types.ts b/src/types.ts
index 88ffc5c..835d8fa 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -13,76 +13,101 @@ export interface PictifyConfig {
}
/**
- * Image output formats supported by Pictify
+ * Image output formats supported by Pictify template renders.
+ * The `/image` endpoint additionally accepts these via `format` (mapped to `fileExtension`).
*/
-export type ImageFormat = 'png' | 'jpg' | 'jpeg' | 'webp' | 'gif' | 'pdf';
+export type ImageFormat = 'png' | 'jpg' | 'jpeg' | 'webp' | 'pdf';
/**
- * Options for rendering an image
+ * GIF quality presets accepted by the `/gif` endpoint.
*/
-export interface RenderOptions {
- /** The ID of the template to use */
- templateId: string;
- /** Variables to inject into the template */
- variables?: Record;
- /** Output format (default: png) */
+export type GifQuality = 'low' | 'medium' | 'high';
+
+/**
+ * Options for rendering an image directly from HTML (`POST /image`).
+ */
+export interface RenderHtmlOptions {
+ /** Raw HTML content to render */
+ html: string;
+ /**
+ * Optional CSS. Injected into the HTML inside a