@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 +17 -0
- package/dist/HtmlCssToImageClient.d.ts +3 -1
- package/dist/HtmlCssToImageClient.js +20 -1
- package/dist/IHtmlCssToImageClient.d.ts +2 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/types/request.d.ts +41 -1
- package/dist/types/request.js +40 -1
- package/package.json +1 -1
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';
|
package/dist/types/request.d.ts
CHANGED
|
@@ -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
|
-
*
|
|
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
|
+
}
|
package/dist/types/request.js
CHANGED
|
@@ -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
|
-
*
|
|
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.
|
|
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",
|