@html-css-to-image/client 0.8.0 → 0.10.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
@@ -37,7 +37,8 @@ import { CreateHtmlCssImageRequest } from '@html-css-to-image/client';
37
37
  const request = new CreateHtmlCssImageRequest({
38
38
  html: '<h1>Hello World</h1>',
39
39
  css: 'h1 { color: blue; }',
40
- google_fonts: ['Roboto']
40
+ google_fonts: ['Roboto'],
41
+ format: 'webp'
41
42
  });
42
43
 
43
44
  const result = await client.createImage(request);
@@ -112,7 +113,7 @@ These methods are handy when you have a lot of content that may never be rendere
112
113
  ```typescript
113
114
  const signedUrl = client.generateTemplatedImageUrl('your_template_id', {
114
115
  title: 'Dynamic Title'
115
- });
116
+ }, undefined, 'webp');
116
117
 
117
118
  console.log('Signed URL:', signedUrl);
118
119
  ```
@@ -131,6 +132,7 @@ const this_item = {
131
132
  };
132
133
  const url_request = new CreateUrlImageRequest({
133
134
  url: `https://website.com/_social/${this_item.id}?updated_at=${this_item.updated_at.valueOf()}`,
135
+ format: 'webp',
134
136
  viewport_width: 600,
135
137
  viewport_height: 200});
136
138
  const signedUrl = client.generateCreateAndRenderUrl(url_request);
@@ -149,6 +151,7 @@ import { CreateTemplatedImageRequest } from '@html-css-to-image/client';
149
151
 
150
152
  const result = await client.createImage(new CreateTemplatedImageRequest({
151
153
  template_id: 'your_template_id',
154
+ format: 'jpg',
152
155
  template_values: {
153
156
  title: 'Hello from Template',
154
157
  subtitle: 'This is a dynamic value'
@@ -165,6 +168,7 @@ import { CreateHtmlCssImageRequest, PDFOptions } from '@html-css-to-image/client
165
168
 
166
169
  const request = new CreateHtmlCssImageRequest({
167
170
  html: '<h1>This will be a PDF</h1>',
171
+ format: 'pdf',
168
172
  pdf_options: new PDFOptions({
169
173
  // Use numbers for pixels (default)
170
174
  // Or use an object for specific units (in, cm, mm, px)
@@ -193,7 +197,8 @@ const variations = [
193
197
  ];
194
198
 
195
199
  const defaults = new CreateHtmlCssImageRequest({
196
- css: 'h1 { color: red; }'
200
+ css: 'h1 { color: red; }',
201
+ format: 'webp'
197
202
  });
198
203
 
199
204
  const result = await client.createImageBatch(variations, defaults);
@@ -1,6 +1,6 @@
1
1
  import type { IHtmlCssToImageClient } from "./IHtmlCssToImageClient.js";
2
2
  import { CreateTemplatedImageRequest } from "./types/request.js";
3
- import type { CreateHtmlCssImageRequest, CreateUrlImageRequest } from "./types/request.js";
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>;
6
6
  export declare class HtmlCssToImageClient implements IHtmlCssToImageClient {
@@ -16,7 +16,7 @@ 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
- generateTemplatedImageUrl<T extends Record<string, any>>(templateIdOrRequest: string | CreateTemplatedImageRequest<T>, templateValues?: T, templateVersion?: number): string;
19
+ generateTemplatedImageUrl<T extends Record<string, any>>(templateIdOrRequest: string | CreateTemplatedImageRequest<T>, templateValues?: T, templateVersion?: number, format?: RenderImageFormat): string;
20
20
  generateCreateAndRenderUrl(request: CreateUrlImageRequest): string;
21
21
  private responseToType;
22
22
  private responseToDeleteImageResponse;
@@ -93,13 +93,14 @@ export class HtmlCssToImageClient {
93
93
  });
94
94
  return await this.responseToType(response);
95
95
  }
96
- generateTemplatedImageUrl(templateIdOrRequest, templateValues, templateVersion) {
96
+ generateTemplatedImageUrl(templateIdOrRequest, templateValues, templateVersion, format) {
97
97
  let request;
98
98
  if (typeof templateIdOrRequest === 'string') {
99
99
  request = new CreateTemplatedImageRequest({
100
100
  template_id: templateIdOrRequest,
101
101
  template_values: templateValues || {},
102
- template_version: templateVersion
102
+ template_version: templateVersion,
103
+ format
103
104
  });
104
105
  }
105
106
  else {
@@ -125,13 +126,14 @@ export class HtmlCssToImageClient {
125
126
  }
126
127
  const queryString = params.toString();
127
128
  const token = this.generateHmacToken(queryString);
128
- return `${this.baseUrl}/v1/image/${request.template_id}/${token}${queryString ? '?' : ''}${queryString}`;
129
+ const formatPath = request.format ? `/${request.format}` : '';
130
+ return `${this.baseUrl}/v1/image/${request.template_id}/${token}${formatPath}${queryString ? '?' : ''}${queryString}`;
129
131
  }
130
132
  generateCreateAndRenderUrl(request) {
131
133
  const params = new URLSearchParams();
132
134
  params.append('url', request.url);
133
135
  Object.entries(request)
134
- .filter(([key, _]) => key !== 'url' && key != 'pdf_options' && key !== 'dedupe_duration_s' && key !== '__type')
136
+ .filter(([key, _]) => key !== 'url' && key !== 'format' && key != 'pdf_options' && key !== 'dedupe_duration_s' && key !== 'request_overrides' && key !== '__type')
135
137
  .sort((a, b) => a[0].localeCompare(b[0]))
136
138
  .forEach(([key, value]) => {
137
139
  if (value !== undefined && value !== null && (value !== false || key === 'transparent_background')) {
@@ -152,7 +154,8 @@ export class HtmlCssToImageClient {
152
154
  });
153
155
  const queryString = params.toString();
154
156
  const token = this.generateHmacToken(queryString);
155
- return `${this.baseUrl}/v1/image/create-and-render/${this.apiId}/${token}?${queryString}`;
157
+ const formatPath = request.format ? `/${request.format}` : '';
158
+ return `${this.baseUrl}/v1/image/create-and-render/${this.apiId}/${token}${formatPath}?${queryString}`;
156
159
  }
157
160
  async responseToType(response) {
158
161
  let response_json;
@@ -1,4 +1,4 @@
1
- import type { CreateHtmlCssImageRequest, CreateTemplatedImageRequest, CreateUrlImageRequest } from "./types/request.js";
1
+ import type { CreateHtmlCssImageRequest, CreateTemplatedImageRequest, CreateUrlImageRequest, RenderImageFormat } from "./types/request.js";
2
2
  import type { CreateImageBatchResponse, CreateImageResponse, DeleteImageResponse } from "./types/response.js";
3
3
  export interface IHtmlCssToImageClient {
4
4
  createImage(request: CreateHtmlCssImageRequest | CreateUrlImageRequest | CreateTemplatedImageRequest): Promise<CreateImageResponse>;
@@ -6,6 +6,6 @@ export interface IHtmlCssToImageClient {
6
6
  deleteImage(imageId: string): Promise<DeleteImageResponse>;
7
7
  deleteImageBatch(imageIds: readonly string[]): Promise<DeleteImageResponse>;
8
8
  generateCreateAndRenderUrl(request: CreateUrlImageRequest): string;
9
- generateTemplatedImageUrl<T extends Record<string, any>>(template_id: string, template_values: T, template_version?: number): string;
9
+ generateTemplatedImageUrl<T extends Record<string, any>>(template_id: string, template_values: T, template_version?: number, format?: RenderImageFormat): string;
10
10
  generateTemplatedImageUrl(request: CreateTemplatedImageRequest): string;
11
11
  }
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 } from './types/request.js';
1
+ export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, 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, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
2
2
  export { HtmlCssToImageClient } from './HtmlCssToImageClient.js';
@@ -1,6 +1,33 @@
1
1
  export type ColorSchemeType = 'light' | 'dark';
2
2
  export type PdfUnit = 'px' | 'in' | 'cm' | 'mm';
3
3
  export type MediaType = 'print' | 'screen';
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
+ }
4
31
  export interface PdfValueWithUnits {
5
32
  value: number;
6
33
  unit: PdfUnit;
@@ -44,6 +71,18 @@ export declare class PDFOptions {
44
71
  constructor(init?: Partial<PDFOptions>);
45
72
  }
46
73
  export declare abstract class BaseCreateImageRequest {
74
+ /**
75
+ * The file format used in the URL returned by the image creation request.
76
+ *
77
+ * This option is supported for HTML/CSS and URL requests, including batch
78
+ * requests. It only changes the extension of the initially returned URL;
79
+ * it does not change the stored image definition or prevent the image from
80
+ * being rendered in another supported format. When omitted, the API
81
+ * returns its default image URL.
82
+ *
83
+ * @see https://docs.htmlcsstoimage.com/getting-started/using-the-api/#file-formats
84
+ */
85
+ format?: RenderImageFormat;
47
86
  /**
48
87
  * A CSS selector to target a specific element on the page.
49
88
  * The API will crop the image to the dimensions of this element.
@@ -87,7 +126,7 @@ export declare abstract class BaseCreateImageRequest {
87
126
  */
88
127
  dedupe_duration_s?: number;
89
128
  /**
90
- * 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.
91
130
  */
92
131
  disable_twemoji?: boolean;
93
132
  /**
@@ -118,6 +157,8 @@ export declare abstract class BaseCreateImageRequest {
118
157
  * Select an organization proxy for rendering.
119
158
  */
120
159
  proxy_id?: string;
160
+ /** Block matching browser network requests. Requires a paid plan. */
161
+ request_overrides?: RequestOverride[];
121
162
  /**
122
163
  * Save rendered images to one of the organization's configured storage destinations.
123
164
  */
@@ -212,6 +253,17 @@ export declare class CreateUrlImageRequest extends BaseCreateImageRequest {
212
253
  }
213
254
  export declare class CreateTemplatedImageRequest<T = Record<string, any>> {
214
255
  readonly __type: "templated";
256
+ /**
257
+ * The file format used in the URL returned by the image creation request.
258
+ *
259
+ * This only changes the extension of the initially returned URL; it does
260
+ * not change the stored image definition or prevent the image from being
261
+ * rendered in another supported format. When omitted, the API returns its
262
+ * default image URL.
263
+ *
264
+ * @see https://docs.htmlcsstoimage.com/getting-started/using-the-api/#file-formats
265
+ */
266
+ format?: RenderImageFormat;
215
267
  /**
216
268
  * Identifies the specific template to be used.
217
269
  */
@@ -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.
@@ -25,6 +48,18 @@ export class PDFOptions {
25
48
  }
26
49
  }
27
50
  export class BaseCreateImageRequest {
51
+ /**
52
+ * The file format used in the URL returned by the image creation request.
53
+ *
54
+ * This option is supported for HTML/CSS and URL requests, including batch
55
+ * requests. It only changes the extension of the initially returned URL;
56
+ * it does not change the stored image definition or prevent the image from
57
+ * being rendered in another supported format. When omitted, the API
58
+ * returns its default image URL.
59
+ *
60
+ * @see https://docs.htmlcsstoimage.com/getting-started/using-the-api/#file-formats
61
+ */
62
+ format;
28
63
  /**
29
64
  * A CSS selector to target a specific element on the page.
30
65
  * The API will crop the image to the dimensions of this element.
@@ -68,7 +103,7 @@ export class BaseCreateImageRequest {
68
103
  */
69
104
  dedupe_duration_s;
70
105
  /**
71
- * 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.
72
107
  */
73
108
  disable_twemoji;
74
109
  /**
@@ -99,6 +134,8 @@ export class BaseCreateImageRequest {
99
134
  * Select an organization proxy for rendering.
100
135
  */
101
136
  proxy_id;
137
+ /** Block matching browser network requests. Requires a paid plan. */
138
+ request_overrides;
102
139
  /**
103
140
  * Save rendered images to one of the organization's configured storage destinations.
104
141
  */
@@ -201,6 +238,17 @@ export class CreateUrlImageRequest extends BaseCreateImageRequest {
201
238
  }
202
239
  export class CreateTemplatedImageRequest {
203
240
  __type = 'templated';
241
+ /**
242
+ * The file format used in the URL returned by the image creation request.
243
+ *
244
+ * This only changes the extension of the initially returned URL; it does
245
+ * not change the stored image definition or prevent the image from being
246
+ * rendered in another supported format. When omitted, the API returns its
247
+ * default image URL.
248
+ *
249
+ * @see https://docs.htmlcsstoimage.com/getting-started/using-the-api/#file-formats
250
+ */
251
+ format;
204
252
  /**
205
253
  * Identifies the specific template to be used.
206
254
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@html-css-to-image/client",
3
- "version": "0.8.0",
3
+ "version": "0.10.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",