@html-css-to-image/client 0.6.0 → 0.8.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
@@ -55,8 +55,15 @@ if (result.success) {
55
55
  import { CreateUrlImageRequest } from '@html-css-to-image/client';
56
56
 
57
57
  const request = new CreateUrlImageRequest({
58
- url: 'https://example.com',
58
+ url: 'https://example.com/private-report',
59
59
  css: '.cookie-banner { display: none; }',
60
+ headers: {
61
+ Authorization: 'Bearer short-lived-token',
62
+ 'X-Preview-Mode': 'enabled'
63
+ },
64
+ additional_header_origins: ['https://api.example.com'],
65
+ include_headers_on_subrequests: true,
66
+ identify_as_hcti: true,
60
67
  full_screen: true
61
68
  });
62
69
 
@@ -67,6 +74,8 @@ if (result.success) {
67
74
  }
68
75
  ```
69
76
 
77
+ Custom `headers` are restricted to the requested URL's origin. Set `include_headers_on_subrequests: true` when same-origin resources also require them, and use `additional_header_origins` to allow an exact cross-origin scheme, host, and port. See the [custom headers documentation](https://docs.htmlcsstoimage.com/parameters/headers/) for the complete request formats and security guidance.
78
+
70
79
  ### Delete Images
71
80
 
72
81
  Delete one or more existing images from HCTI and clear them from the CDN using their image IDs.
@@ -129,6 +138,8 @@ const signedUrl = client.generateCreateAndRenderUrl(url_request);
129
138
  // now it's safe to use signedUrl on the frontend in a meta or img tag, without exposing your API key, and it will be kept updated as the updated_at changes.
130
139
  ```
131
140
 
141
+ The helper serializes custom headers as repeated `headers=name:value` query parameters and each `additional_header_origins` entry as a repeated query parameter. Do not include secrets in signed URLs because the header values remain visible in the URL.
142
+
132
143
  ### Using Templates
133
144
 
134
145
  If you have created a template for your account, you can generate an image by passing your template ID and the data for your variables.
@@ -131,10 +131,22 @@ export class HtmlCssToImageClient {
131
131
  const params = new URLSearchParams();
132
132
  params.append('url', request.url);
133
133
  Object.entries(request)
134
- .filter(([key, _]) => key !== 'url' && key != 'pdf_options' && key !== '__type')
134
+ .filter(([key, _]) => key !== 'url' && key != 'pdf_options' && key !== 'dedupe_duration_s' && key !== '__type')
135
135
  .sort((a, b) => a[0].localeCompare(b[0]))
136
136
  .forEach(([key, value]) => {
137
137
  if (value !== undefined && value !== null && (value !== false || key === 'transparent_background')) {
138
+ if (key === 'headers') {
139
+ Object.entries(value).forEach(([name, headerValue]) => {
140
+ params.append('headers', `${name}:${headerValue}`);
141
+ });
142
+ return;
143
+ }
144
+ if (key === 'additional_header_origins') {
145
+ value.forEach(origin => {
146
+ params.append('additional_header_origins', origin);
147
+ });
148
+ return;
149
+ }
138
150
  params.append(key, value.toString());
139
151
  }
140
152
  });
@@ -78,6 +78,14 @@ export declare abstract class BaseCreateImageRequest {
78
78
  * Ensure the image is only ever rendered and saved one time.
79
79
  */
80
80
  max_render_once?: boolean;
81
+ /**
82
+ * Reuse an identical image created within this many seconds without consuming image credits.
83
+ * HTML/CSS defaults vary by plan, while URL requests default to 0. Set to 0 to disable deduplication.
84
+ * This applies only to standard single-image POST creation requests. It does not apply to image
85
+ * batch requests and is not included in signed create-and-render URLs generated by the client.
86
+ * @see https://docs.htmlcsstoimage.com/parameters/dedupe_duration_s/
87
+ */
88
+ dedupe_duration_s?: number;
81
89
  /**
82
90
  * Disable Twemoji fallback rendering.
83
91
  */
@@ -167,6 +175,27 @@ export declare class CreateUrlImageRequest extends BaseCreateImageRequest {
167
175
  * Use this to override existing styles or customize specific elements.
168
176
  */
169
177
  css?: string;
178
+ /**
179
+ * Custom HTTP headers for top-level requests to the requested URL's origin
180
+ * and any additional_header_origins.
181
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/
182
+ */
183
+ headers?: Record<string, string>;
184
+ /**
185
+ * Additional exact HTTP or HTTPS origins allowed to receive custom headers.
186
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/#additional-header-origins
187
+ */
188
+ additional_header_origins?: string[];
189
+ /**
190
+ * Also send custom headers with subrequests to allowed origins.
191
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/#include-headers-on-subrequests
192
+ */
193
+ include_headers_on_subrequests?: boolean;
194
+ /**
195
+ * Add X-HCTI-SCREENSHOT: 1 to the top-level page request.
196
+ * @see https://docs.htmlcsstoimage.com/parameters/identify_as_hcti/
197
+ */
198
+ identify_as_hcti?: boolean;
170
199
  /**
171
200
  * Indicates whether the screenshot should capture the entire webpage in full height.
172
201
  *
@@ -59,6 +59,14 @@ export class BaseCreateImageRequest {
59
59
  * Ensure the image is only ever rendered and saved one time.
60
60
  */
61
61
  max_render_once;
62
+ /**
63
+ * Reuse an identical image created within this many seconds without consuming image credits.
64
+ * HTML/CSS defaults vary by plan, while URL requests default to 0. Set to 0 to disable deduplication.
65
+ * This applies only to standard single-image POST creation requests. It does not apply to image
66
+ * batch requests and is not included in signed create-and-render URLs generated by the client.
67
+ * @see https://docs.htmlcsstoimage.com/parameters/dedupe_duration_s/
68
+ */
69
+ dedupe_duration_s;
62
70
  /**
63
71
  * Disable Twemoji fallback rendering.
64
72
  */
@@ -153,6 +161,27 @@ export class CreateUrlImageRequest extends BaseCreateImageRequest {
153
161
  * Use this to override existing styles or customize specific elements.
154
162
  */
155
163
  css;
164
+ /**
165
+ * Custom HTTP headers for top-level requests to the requested URL's origin
166
+ * and any additional_header_origins.
167
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/
168
+ */
169
+ headers;
170
+ /**
171
+ * Additional exact HTTP or HTTPS origins allowed to receive custom headers.
172
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/#additional-header-origins
173
+ */
174
+ additional_header_origins;
175
+ /**
176
+ * Also send custom headers with subrequests to allowed origins.
177
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/#include-headers-on-subrequests
178
+ */
179
+ include_headers_on_subrequests;
180
+ /**
181
+ * Add X-HCTI-SCREENSHOT: 1 to the top-level page request.
182
+ * @see https://docs.htmlcsstoimage.com/parameters/identify_as_hcti/
183
+ */
184
+ identify_as_hcti;
156
185
  /**
157
186
  * Indicates whether the screenshot should capture the entire webpage in full height.
158
187
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@html-css-to-image/client",
3
- "version": "0.6.0",
3
+ "version": "0.8.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",