@html-css-to-image/client 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -237,3 +237,20 @@ const client = new HtmlCssToImageClient(apiId, apiKey, fetch);
237
237
 
238
238
  > [!TIP]
239
239
  > Get started for free at [htmlcsstoimage.com](https://htmlcsstoimage.com).
240
+
241
+ ## Templated image batches
242
+
243
+ Create images from one or more templates with shared defaults and ordered variations:
244
+
245
+ ```typescript
246
+ import {TemplatedBatchImageOptions} from '@html-css-to-image/client';
247
+
248
+ const result = await client.createTemplatedImageBatch([
249
+ new TemplatedBatchImageOptions({template_values: {title: 'First'}}),
250
+ new TemplatedBatchImageOptions({template_id: 't-other', template_values: {title: 'Second'}})
251
+ ], new TemplatedBatchImageOptions({template_id: 't-card', template_version: 3, format: 'webp'}));
252
+ ```
253
+
254
+ Omitted fields inherit defaults. Supplying a template ID resets the inherited version; omit its version to use latest. Template value objects merge recursively on the API; arrays, scalars, and explicit null values replace defaults. Results preserve input order and identical images reuse existing assets. Each merged values object must be nonempty and satisfy its template's required variables.
255
+
256
+ See the [API reference](https://docs.htmlcsstoimage.com/getting-started/using-the-api/#batch-templated-image-creation) for plan limits and examples.
@@ -1,5 +1,5 @@
1
1
  import type { IHtmlCssToImageClient } from "./IHtmlCssToImageClient.js";
2
- import { CreateTemplatedImageRequest } from "./types/request.js";
2
+ import { CreateTemplatedImageRequest, TemplatedBatchImageOptions } from "./types/request.js";
3
3
  import type { CreateHtmlCssImageRequest, CreateUrlImageRequest, RenderImageFormat } from "./types/request.js";
4
4
  import type { CreateImageBatchResponse, CreateImageResponse, DeleteImageResponse } from "./types/response.js";
5
5
  export type FetchFunction = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
@@ -16,6 +16,8 @@ export declare class HtmlCssToImageClient implements IHtmlCssToImageClient {
16
16
  deleteImageBatch(imageIds: readonly string[]): Promise<DeleteImageResponse>;
17
17
  private mapToInternal;
18
18
  createImageBatch<T extends CreateHtmlCssImageRequest | CreateUrlImageRequest>(variations: T[], default_options?: T): Promise<CreateImageBatchResponse>;
19
+ /** Create a template batch, preserving variation order and leaving merging to the API. */
20
+ createTemplatedImageBatch<T = Record<string, any>>(variations: TemplatedBatchImageOptions<T>[], default_options?: TemplatedBatchImageOptions<T>): Promise<CreateImageBatchResponse>;
19
21
  generateTemplatedImageUrl<T extends Record<string, any>>(templateIdOrRequest: string | CreateTemplatedImageRequest<T>, templateValues?: T, templateVersion?: number, format?: RenderImageFormat): string;
20
22
  generateCreateAndRenderUrl(request: CreateUrlImageRequest): string;
21
23
  private responseToType;
@@ -93,6 +93,25 @@ export class HtmlCssToImageClient {
93
93
  });
94
94
  return await this.responseToType(response);
95
95
  }
96
+ /** Create a template batch, preserving variation order and leaving merging to the API. */
97
+ async createTemplatedImageBatch(variations, default_options) {
98
+ if (variations.length === 0) {
99
+ return { success: true, images: [] };
100
+ }
101
+ // Select only public batch fields, including when passed a single-image request.
102
+ const map = (options) => ({
103
+ template_id: options.template_id,
104
+ template_version: options.template_version,
105
+ template_values: options.template_values,
106
+ format: options.format
107
+ });
108
+ const response = await this.fetch(`${this.baseUrl}/v1/image/batch/templated`, {
109
+ method: 'POST',
110
+ headers: { 'Authorization': this.authHeader, 'Content-Type': 'application/json' },
111
+ body: JSON.stringify({ variations: variations.map(map), default_options: default_options ? map(default_options) : undefined })
112
+ });
113
+ return await this.responseToType(response);
114
+ }
96
115
  generateTemplatedImageUrl(templateIdOrRequest, templateValues, templateVersion, format) {
97
116
  let request;
98
117
  if (typeof templateIdOrRequest === 'string') {
@@ -1,9 +1,11 @@
1
+ import type { TemplatedBatchImageOptions } from "./types/request.js";
1
2
  import type { CreateHtmlCssImageRequest, CreateTemplatedImageRequest, CreateUrlImageRequest, RenderImageFormat } from "./types/request.js";
2
3
  import type { CreateImageBatchResponse, CreateImageResponse, DeleteImageResponse } from "./types/response.js";
3
4
  export interface IHtmlCssToImageClient {
4
5
  createImage(request: CreateHtmlCssImageRequest | CreateUrlImageRequest | CreateTemplatedImageRequest): Promise<CreateImageResponse>;
5
6
  createImageBatch<T extends CreateHtmlCssImageRequest | CreateUrlImageRequest>(variations: T[], default_options?: T): Promise<CreateImageBatchResponse>;
6
7
  deleteImage(imageId: string): Promise<DeleteImageResponse>;
8
+ createTemplatedImageBatch<T = Record<string, any>>(variations: TemplatedBatchImageOptions<T>[], default_options?: TemplatedBatchImageOptions<T>): Promise<CreateImageBatchResponse>;
7
9
  deleteImageBatch(imageIds: readonly string[]): Promise<DeleteImageResponse>;
8
10
  generateCreateAndRenderUrl(request: CreateUrlImageRequest): string;
9
11
  generateTemplatedImageUrl<T extends Record<string, any>>(template_id: string, template_values: T, template_version?: number, format?: RenderImageFormat): string;
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
1
+ export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, TemplatedBatchImageOptions, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
2
2
  export type { ColorSchemeType, MediaType, PdfMargins, PdfValueInput, PdfValueWithUnits, PdfUnit, RenderImageFormat, RequestOverride } from './types/request.js';
3
3
  export type { CreateImageBatchResponse, CreateImageBatchSuccessResponse, CreateImageErrorResponse, CreateImageResponse, CreateImageSuccessResponse, DeleteImageResponse, DeleteImageSuccessResponse, ValidationError } from './types/response.js';
4
4
  export { HtmlCssToImageClient } from './HtmlCssToImageClient.js';
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
- export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
1
+ export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, TemplatedBatchImageOptions, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
2
2
  export { HtmlCssToImageClient } from './HtmlCssToImageClient.js';
@@ -278,3 +278,15 @@ export declare class CreateTemplatedImageRequest<T = Record<string, any>> {
278
278
  template_values: T;
279
279
  constructor(init?: Partial<CreateTemplatedImageRequest<T>>);
280
280
  }
281
+ /** Shared defaults or one variation in a templated image batch. */
282
+ export declare class TemplatedBatchImageOptions<T = Record<string, any>> {
283
+ /** Omit to inherit the default template. Supplying an ID resets the inherited version. */
284
+ template_id?: string;
285
+ /** Inherits the default version, or uses latest when a template_id is supplied. */
286
+ template_version?: number;
287
+ /** Objects merge recursively; arrays, scalars, and explicit null values replace defaults. */
288
+ template_values?: T;
289
+ /** File format of the returned URL; omitted values inherit the default format. */
290
+ format?: RenderImageFormat;
291
+ constructor(init?: Partial<TemplatedBatchImageOptions<T>>);
292
+ }
@@ -265,3 +265,17 @@ export class CreateTemplatedImageRequest {
265
265
  Object.assign(this, init);
266
266
  }
267
267
  }
268
+ /** Shared defaults or one variation in a templated image batch. */
269
+ export class TemplatedBatchImageOptions {
270
+ /** Omit to inherit the default template. Supplying an ID resets the inherited version. */
271
+ template_id;
272
+ /** Inherits the default version, or uses latest when a template_id is supplied. */
273
+ template_version;
274
+ /** Objects merge recursively; arrays, scalars, and explicit null values replace defaults. */
275
+ template_values;
276
+ /** File format of the returned URL; omitted values inherit the default format. */
277
+ format;
278
+ constructor(init) {
279
+ Object.assign(this, init);
280
+ }
281
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@html-css-to-image/client",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "type": "module",
5
5
  "description": "Lightweight TypeScript client for the HTML/CSS to Image API. Generate images from HTML/CSS, URLs, or templates in your TypeScript or JavaScript projects.",
6
6
  "main": "dist/index.js",