@html-css-to-image/client 0.6.0 → 0.7.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.
@@ -135,6 +135,18 @@ export class HtmlCssToImageClient {
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
  });
@@ -167,6 +167,27 @@ export declare class CreateUrlImageRequest extends BaseCreateImageRequest {
167
167
  * Use this to override existing styles or customize specific elements.
168
168
  */
169
169
  css?: string;
170
+ /**
171
+ * Custom HTTP headers for top-level requests to the requested URL's origin
172
+ * and any additional_header_origins.
173
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/
174
+ */
175
+ headers?: Record<string, string>;
176
+ /**
177
+ * Additional exact HTTP or HTTPS origins allowed to receive custom headers.
178
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/#additional-header-origins
179
+ */
180
+ additional_header_origins?: string[];
181
+ /**
182
+ * Also send custom headers with subrequests to allowed origins.
183
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/#include-headers-on-subrequests
184
+ */
185
+ include_headers_on_subrequests?: boolean;
186
+ /**
187
+ * Add X-HCTI-SCREENSHOT: 1 to the top-level page request.
188
+ * @see https://docs.htmlcsstoimage.com/parameters/identify_as_hcti/
189
+ */
190
+ identify_as_hcti?: boolean;
170
191
  /**
171
192
  * Indicates whether the screenshot should capture the entire webpage in full height.
172
193
  *
@@ -153,6 +153,27 @@ export class CreateUrlImageRequest extends BaseCreateImageRequest {
153
153
  * Use this to override existing styles or customize specific elements.
154
154
  */
155
155
  css;
156
+ /**
157
+ * Custom HTTP headers for top-level requests to the requested URL's origin
158
+ * and any additional_header_origins.
159
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/
160
+ */
161
+ headers;
162
+ /**
163
+ * Additional exact HTTP or HTTPS origins allowed to receive custom headers.
164
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/#additional-header-origins
165
+ */
166
+ additional_header_origins;
167
+ /**
168
+ * Also send custom headers with subrequests to allowed origins.
169
+ * @see https://docs.htmlcsstoimage.com/parameters/headers/#include-headers-on-subrequests
170
+ */
171
+ include_headers_on_subrequests;
172
+ /**
173
+ * Add X-HCTI-SCREENSHOT: 1 to the top-level page request.
174
+ * @see https://docs.htmlcsstoimage.com/parameters/identify_as_hcti/
175
+ */
176
+ identify_as_hcti;
156
177
  /**
157
178
  * Indicates whether the screenshot should capture the entire webpage in full height.
158
179
  *
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.7.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",