@html-css-to-image/client 0.7.0 → 0.9.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 !== '__type')
136
+ .filter(([key, _]) => key !== 'url' && key !== 'format' && key != 'pdf_options' && key !== 'dedupe_duration_s' && 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
1
  export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, CreateUrlImageRequest, PDFOptions } from './types/request.js';
2
- export type { ColorSchemeType, MediaType, PdfMargins, PdfValueInput, PdfValueWithUnits, PdfUnit } from './types/request.js';
2
+ export type { ColorSchemeType, MediaType, PdfMargins, PdfValueInput, PdfValueWithUnits, PdfUnit, RenderImageFormat } 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';
@@ -1,6 +1,7 @@
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';
4
5
  export interface PdfValueWithUnits {
5
6
  value: number;
6
7
  unit: PdfUnit;
@@ -44,6 +45,18 @@ export declare class PDFOptions {
44
45
  constructor(init?: Partial<PDFOptions>);
45
46
  }
46
47
  export declare abstract class BaseCreateImageRequest {
48
+ /**
49
+ * The file format used in the URL returned by the image creation request.
50
+ *
51
+ * This option is supported for HTML/CSS and URL requests, including batch
52
+ * requests. It only changes the extension of the initially returned URL;
53
+ * it does not change the stored image definition or prevent the image from
54
+ * being rendered in another supported format. When omitted, the API
55
+ * returns its default image URL.
56
+ *
57
+ * @see https://docs.htmlcsstoimage.com/getting-started/using-the-api/#file-formats
58
+ */
59
+ format?: RenderImageFormat;
47
60
  /**
48
61
  * A CSS selector to target a specific element on the page.
49
62
  * The API will crop the image to the dimensions of this element.
@@ -78,6 +91,14 @@ export declare abstract class BaseCreateImageRequest {
78
91
  * Ensure the image is only ever rendered and saved one time.
79
92
  */
80
93
  max_render_once?: boolean;
94
+ /**
95
+ * Reuse an identical image created within this many seconds without consuming image credits.
96
+ * HTML/CSS defaults vary by plan, while URL requests default to 0. Set to 0 to disable deduplication.
97
+ * This applies only to standard single-image POST creation requests. It does not apply to image
98
+ * batch requests and is not included in signed create-and-render URLs generated by the client.
99
+ * @see https://docs.htmlcsstoimage.com/parameters/dedupe_duration_s/
100
+ */
101
+ dedupe_duration_s?: number;
81
102
  /**
82
103
  * Disable Twemoji fallback rendering.
83
104
  */
@@ -204,6 +225,17 @@ export declare class CreateUrlImageRequest extends BaseCreateImageRequest {
204
225
  }
205
226
  export declare class CreateTemplatedImageRequest<T = Record<string, any>> {
206
227
  readonly __type: "templated";
228
+ /**
229
+ * The file format used in the URL returned by the image creation request.
230
+ *
231
+ * This only changes the extension of the initially returned URL; it does
232
+ * not change the stored image definition or prevent the image from being
233
+ * rendered in another supported format. When omitted, the API returns its
234
+ * default image URL.
235
+ *
236
+ * @see https://docs.htmlcsstoimage.com/getting-started/using-the-api/#file-formats
237
+ */
238
+ format?: RenderImageFormat;
207
239
  /**
208
240
  * Identifies the specific template to be used.
209
241
  */
@@ -25,6 +25,18 @@ export class PDFOptions {
25
25
  }
26
26
  }
27
27
  export class BaseCreateImageRequest {
28
+ /**
29
+ * The file format used in the URL returned by the image creation request.
30
+ *
31
+ * This option is supported for HTML/CSS and URL requests, including batch
32
+ * requests. It only changes the extension of the initially returned URL;
33
+ * it does not change the stored image definition or prevent the image from
34
+ * being rendered in another supported format. When omitted, the API
35
+ * returns its default image URL.
36
+ *
37
+ * @see https://docs.htmlcsstoimage.com/getting-started/using-the-api/#file-formats
38
+ */
39
+ format;
28
40
  /**
29
41
  * A CSS selector to target a specific element on the page.
30
42
  * The API will crop the image to the dimensions of this element.
@@ -59,6 +71,14 @@ export class BaseCreateImageRequest {
59
71
  * Ensure the image is only ever rendered and saved one time.
60
72
  */
61
73
  max_render_once;
74
+ /**
75
+ * Reuse an identical image created within this many seconds without consuming image credits.
76
+ * HTML/CSS defaults vary by plan, while URL requests default to 0. Set to 0 to disable deduplication.
77
+ * This applies only to standard single-image POST creation requests. It does not apply to image
78
+ * batch requests and is not included in signed create-and-render URLs generated by the client.
79
+ * @see https://docs.htmlcsstoimage.com/parameters/dedupe_duration_s/
80
+ */
81
+ dedupe_duration_s;
62
82
  /**
63
83
  * Disable Twemoji fallback rendering.
64
84
  */
@@ -193,6 +213,17 @@ export class CreateUrlImageRequest extends BaseCreateImageRequest {
193
213
  }
194
214
  export class CreateTemplatedImageRequest {
195
215
  __type = 'templated';
216
+ /**
217
+ * The file format used in the URL returned by the image creation request.
218
+ *
219
+ * This only changes the extension of the initially returned URL; it does
220
+ * not change the stored image definition or prevent the image from being
221
+ * rendered in another supported format. When omitted, the API returns its
222
+ * default image URL.
223
+ *
224
+ * @see https://docs.htmlcsstoimage.com/getting-started/using-the-api/#file-formats
225
+ */
226
+ format;
196
227
  /**
197
228
  * Identifies the specific template to be used.
198
229
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@html-css-to-image/client",
3
- "version": "0.7.0",
3
+ "version": "0.9.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",