@html-css-to-image/client 0.9.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') {
@@ -133,7 +152,7 @@ export class HtmlCssToImageClient {
133
152
  const params = new URLSearchParams();
134
153
  params.append('url', request.url);
135
154
  Object.entries(request)
136
- .filter(([key, _]) => key !== 'url' && key !== 'format' && key != 'pdf_options' && key !== 'dedupe_duration_s' && key !== '__type')
155
+ .filter(([key, _]) => key !== 'url' && key !== 'format' && key != 'pdf_options' && key !== 'dedupe_duration_s' && key !== 'request_overrides' && key !== '__type')
137
156
  .sort((a, b) => a[0].localeCompare(b[0]))
138
157
  .forEach(([key, value]) => {
139
158
  if (value !== undefined && value !== null && (value !== false || key === 'transparent_background')) {
@@ -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,5 +1,5 @@
1
- export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, CreateUrlImageRequest, PDFOptions } from './types/request.js';
2
- export type { ColorSchemeType, MediaType, PdfMargins, PdfValueInput, PdfValueWithUnits, PdfUnit, RenderImageFormat } from './types/request.js';
1
+ export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, TemplatedBatchImageOptions, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
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';
5
5
  export type { FetchFunction } from './HtmlCssToImageClient.js';
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
- export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, CreateUrlImageRequest, PDFOptions } 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';
@@ -2,6 +2,32 @@ export type ColorSchemeType = 'light' | 'dark';
2
2
  export type PdfUnit = 'px' | 'in' | 'cm' | 'mm';
3
3
  export type MediaType = 'print' | 'screen';
4
4
  export type RenderImageFormat = 'png' | 'jpg' | 'webp' | 'pdf';
5
+ export declare enum RequestOverrideResourceType {
6
+ Beacon = "beacon",
7
+ Document = "document",
8
+ Stylesheet = "stylesheet",
9
+ Image = "image",
10
+ ImageSet = "image_set",
11
+ Media = "media",
12
+ Font = "font",
13
+ Script = "script",
14
+ TextTrack = "text_track",
15
+ Xhr = "xhr",
16
+ Fetch = "fetch",
17
+ EventSource = "event_source",
18
+ Manifest = "manifest",
19
+ Ping = "ping",
20
+ Img = "img",
21
+ Other = "other"
22
+ }
23
+ export declare enum RequestOverrideAction {
24
+ Block = "block"
25
+ }
26
+ export interface RequestOverride {
27
+ action: RequestOverrideAction.Block;
28
+ url?: string;
29
+ resource_types?: RequestOverrideResourceType[];
30
+ }
5
31
  export interface PdfValueWithUnits {
6
32
  value: number;
7
33
  unit: PdfUnit;
@@ -100,7 +126,7 @@ export declare abstract class BaseCreateImageRequest {
100
126
  */
101
127
  dedupe_duration_s?: number;
102
128
  /**
103
- * Disable Twemoji fallback rendering.
129
+ * HTML/CSS images use Twemoji by default; true disables it. URL images inject Twemoji only when explicitly false; omission or true leaves the page's emoji handling unchanged.
104
130
  */
105
131
  disable_twemoji?: boolean;
106
132
  /**
@@ -131,6 +157,8 @@ export declare abstract class BaseCreateImageRequest {
131
157
  * Select an organization proxy for rendering.
132
158
  */
133
159
  proxy_id?: string;
160
+ /** Block matching browser network requests. Requires a paid plan. */
161
+ request_overrides?: RequestOverride[];
134
162
  /**
135
163
  * Save rendered images to one of the organization's configured storage destinations.
136
164
  */
@@ -250,3 +278,15 @@ export declare class CreateTemplatedImageRequest<T = Record<string, any>> {
250
278
  template_values: T;
251
279
  constructor(init?: Partial<CreateTemplatedImageRequest<T>>);
252
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
+ }
@@ -1,3 +1,26 @@
1
+ export var RequestOverrideResourceType;
2
+ (function (RequestOverrideResourceType) {
3
+ RequestOverrideResourceType["Beacon"] = "beacon";
4
+ RequestOverrideResourceType["Document"] = "document";
5
+ RequestOverrideResourceType["Stylesheet"] = "stylesheet";
6
+ RequestOverrideResourceType["Image"] = "image";
7
+ RequestOverrideResourceType["ImageSet"] = "image_set";
8
+ RequestOverrideResourceType["Media"] = "media";
9
+ RequestOverrideResourceType["Font"] = "font";
10
+ RequestOverrideResourceType["Script"] = "script";
11
+ RequestOverrideResourceType["TextTrack"] = "text_track";
12
+ RequestOverrideResourceType["Xhr"] = "xhr";
13
+ RequestOverrideResourceType["Fetch"] = "fetch";
14
+ RequestOverrideResourceType["EventSource"] = "event_source";
15
+ RequestOverrideResourceType["Manifest"] = "manifest";
16
+ RequestOverrideResourceType["Ping"] = "ping";
17
+ RequestOverrideResourceType["Img"] = "img";
18
+ RequestOverrideResourceType["Other"] = "other";
19
+ })(RequestOverrideResourceType || (RequestOverrideResourceType = {}));
20
+ export var RequestOverrideAction;
21
+ (function (RequestOverrideAction) {
22
+ RequestOverrideAction["Block"] = "block";
23
+ })(RequestOverrideAction || (RequestOverrideAction = {}));
1
24
  export class PDFOptions {
2
25
  /**
3
26
  * Whether background graphics should be printed in the PDF output.
@@ -80,7 +103,7 @@ export class BaseCreateImageRequest {
80
103
  */
81
104
  dedupe_duration_s;
82
105
  /**
83
- * Disable Twemoji fallback rendering.
106
+ * HTML/CSS images use Twemoji by default; true disables it. URL images inject Twemoji only when explicitly false; omission or true leaves the page's emoji handling unchanged.
84
107
  */
85
108
  disable_twemoji;
86
109
  /**
@@ -111,6 +134,8 @@ export class BaseCreateImageRequest {
111
134
  * Select an organization proxy for rendering.
112
135
  */
113
136
  proxy_id;
137
+ /** Block matching browser network requests. Requires a paid plan. */
138
+ request_overrides;
114
139
  /**
115
140
  * Save rendered images to one of the organization's configured storage destinations.
116
141
  */
@@ -240,3 +265,17 @@ export class CreateTemplatedImageRequest {
240
265
  Object.assign(this, init);
241
266
  }
242
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.9.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",