@html-css-to-image/client 0.11.0 → 1.0.1
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 +80 -0
- package/dist/HtmlCssToImageClient.d.ts +17 -3
- package/dist/HtmlCssToImageClient.js +82 -6
- package/dist/IHtmlCssToImageClient.d.ts +10 -3
- package/dist/index.d.ts +3 -2
- package/dist/index.js +1 -1
- package/dist/types/recording.d.ts +188 -0
- package/dist/types/recording.js +2 -0
- package/dist/types/request.d.ts +149 -0
- package/dist/types/request.js +156 -0
- package/dist/types/response.d.ts +30 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -94,6 +94,85 @@ const batchResult = await client.deleteImageBatch([
|
|
|
94
94
|
]);
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
+
## Recordings
|
|
98
|
+
|
|
99
|
+
Create MP4, WebM, or GIF recordings with `createRecording`. Use `CreateUrlRecordingRequest` for a public webpage or `CreateHtmlCssRecordingRequest` for HTML/CSS:
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
import {
|
|
103
|
+
CreateUrlRecordingRequest,
|
|
104
|
+
CreateHtmlCssRecordingRequest
|
|
105
|
+
} from '@html-css-to-image/client';
|
|
106
|
+
|
|
107
|
+
const result = await client.createRecording(new CreateUrlRecordingRequest({
|
|
108
|
+
url: 'https://example.com',
|
|
109
|
+
viewport_width: 1280,
|
|
110
|
+
viewport_height: 720,
|
|
111
|
+
duration_ms: 10000,
|
|
112
|
+
actions: [{type: 'simple_scroll'}],
|
|
113
|
+
output: {format: 'mp4'}
|
|
114
|
+
}));
|
|
115
|
+
|
|
116
|
+
if (result.success) {
|
|
117
|
+
// Embed or request this URL directly; it responds once the recording is ready.
|
|
118
|
+
console.log('Recording URL:', result.recording_url);
|
|
119
|
+
} else {
|
|
120
|
+
console.error('Error:', result.error);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const animation = await client.createRecording(new CreateHtmlCssRecordingRequest({
|
|
124
|
+
html: '<h1>Hello</h1>',
|
|
125
|
+
css: '@keyframes fade { from { opacity: 0; } to { opacity: 1; } } h1 { animation: fade 2s; font-family: Roboto; }',
|
|
126
|
+
google_fonts: ['Roboto'],
|
|
127
|
+
duration_ms: 3000,
|
|
128
|
+
duration_mode: 'fixed',
|
|
129
|
+
output: {format: 'gif', scale: 0.5}
|
|
130
|
+
}));
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Both request types share browser settings, triggers, ordered timeline actions, and output options. Optional settings use the API defaults. Recordings do not include audio.
|
|
134
|
+
|
|
135
|
+
Creation returns an ID, `status_url`, and `recording_url`. Embed the `recording_url` (in a `<video>` tag, or an `<img>` tag for GIFs) or request it directly; the request waits until the recording is ready, so there is no need to poll.
|
|
136
|
+
|
|
137
|
+
Checking status is optional and useful for workflows that track progress or failures:
|
|
138
|
+
|
|
139
|
+
```typescript
|
|
140
|
+
const status = await client.fetchRecordingStatus(result.id);
|
|
141
|
+
if (status.success) {
|
|
142
|
+
console.log('Recording status:', status.status);
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`fetchRecordingStatus` fetches the current state once; both HTTP 200 and 202 return `{success: true, ...}` with status information. The recording states `ready`, `failed`, and `cancelled` are terminal. A successful status fetch can report a failed recording, and a nonterminal recording can include an error from a previous attempt. A status this client version does not recognize, such as one added in a newer API version, is returned as `unknown`.
|
|
147
|
+
|
|
148
|
+
Triggers and actions are typed objects with a `type` discriminator. For example, wait until a page element appears, then click a button and hold the result:
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
const demo = await client.createRecording(new CreateUrlRecordingRequest({
|
|
152
|
+
url: 'https://example.com/demo',
|
|
153
|
+
duration_ms: 5000,
|
|
154
|
+
duration_mode: 'fixed',
|
|
155
|
+
trigger: {type: 'element_visible', selector: '#demo', timeout_ms: 2000},
|
|
156
|
+
actions: [
|
|
157
|
+
{type: 'click', selector: '#start', if_not_found: [{type: 'error'}]},
|
|
158
|
+
{type: 'stall', duration_ms: 1000}
|
|
159
|
+
]
|
|
160
|
+
}));
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Nested branches run on the API. For JavaScript actions, omitting `if_error` or setting it to `null` fails the recording on a script error; `if_error: []` ignores the error.
|
|
164
|
+
|
|
165
|
+
Delete recordings by ID, individually or in a batch:
|
|
166
|
+
|
|
167
|
+
```typescript
|
|
168
|
+
const deleted = await client.deleteRecording('recording-id');
|
|
169
|
+
const batchDeleted = await client.deleteRecordingBatch(['first-id', 'second-id']);
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Both delete methods return `{success: true}` when deletion is accepted, or the existing error response shape with `success: false`. `deleteRecordingBatch([])` returns `{success: true}` without making a request, as does `deleteImageBatch([])`.
|
|
173
|
+
|
|
174
|
+
See the [recording guide](https://docs.htmlcsstoimage.com/getting-started/recordings/), [actions reference](https://docs.htmlcsstoimage.com/parameters/actions/), and [trigger reference](https://docs.htmlcsstoimage.com/parameters/trigger/) for options and examples.
|
|
175
|
+
|
|
97
176
|
## Creating Image URLs
|
|
98
177
|
|
|
99
178
|
For use cases where you want to generate a URL on the server and use it safely on the client (without exposing your API key), you can generate a signed URL.
|
|
@@ -224,6 +303,7 @@ const client = new HtmlCssToImageClient(apiId, apiKey, fetch);
|
|
|
224
303
|
|
|
225
304
|
- **Full TypeScript support**: Strongly typed requests and responses.
|
|
226
305
|
- **HTML/CSS & URL Support**: Generate images from raw content or live websites.
|
|
306
|
+
- **Recordings**: Record HTML/CSS or webpages as MP4, WebM, or GIF with scripted interactions.
|
|
227
307
|
- **Templates**: Use your HCTI templates with dynamic data.
|
|
228
308
|
- **Signed URLs**: Securely generate image URLs with HMAC authentication.
|
|
229
309
|
- **PDF Support**: Comprehensive PDF generation options.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { IHtmlCssToImageClient } from "./IHtmlCssToImageClient.js";
|
|
2
2
|
import { CreateTemplatedImageRequest, TemplatedBatchImageOptions } from "./types/request.js";
|
|
3
|
-
import type { CreateHtmlCssImageRequest, CreateUrlImageRequest, RenderImageFormat } from "./types/request.js";
|
|
4
|
-
import type { CreateImageBatchResponse, CreateImageResponse, DeleteImageResponse } from "./types/response.js";
|
|
3
|
+
import type { CreateHtmlCssImageRequest, CreateHtmlCssRecordingRequest, CreateUrlImageRequest, CreateUrlRecordingRequest, RenderImageFormat } from "./types/request.js";
|
|
4
|
+
import type { CreateImageBatchResponse, CreateImageResponse, CreateRecordingResponse, DeleteImageResponse, DeleteRecordingResponse, RecordingStatusResponse } 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 {
|
|
7
7
|
private readonly apiId;
|
|
@@ -12,8 +12,21 @@ export declare class HtmlCssToImageClient implements IHtmlCssToImageClient {
|
|
|
12
12
|
constructor(apiId: string, apiKey: string, customFetch?: FetchFunction);
|
|
13
13
|
static fromEnv(): HtmlCssToImageClient;
|
|
14
14
|
createImage(request: CreateHtmlCssImageRequest | CreateUrlImageRequest | CreateTemplatedImageRequest): Promise<CreateImageResponse>;
|
|
15
|
+
/** Create an HTML/CSS or URL recording. The returned recording_url can be embedded or requested directly and waits until the recording is ready.
|
|
16
|
+
* @see https://docs.htmlcsstoimage.com/getting-started/recordings/
|
|
17
|
+
*/
|
|
18
|
+
createRecording(request: CreateHtmlCssRecordingRequest | CreateUrlRecordingRequest): Promise<CreateRecordingResponse>;
|
|
19
|
+
/** Fetch the current recording status once. HTTP 200 and 202 both return status information. Unrecognized statuses are returned as unknown.
|
|
20
|
+
* @see https://docs.htmlcsstoimage.com/management-api/recordings/
|
|
21
|
+
*/
|
|
22
|
+
fetchRecordingStatus(recordingId: string): Promise<RecordingStatusResponse>;
|
|
23
|
+
/** Delete a recording and clear its media from the CDN. */
|
|
24
|
+
deleteRecording(recordingId: string): Promise<DeleteRecordingResponse>;
|
|
25
|
+
/** Delete multiple recordings in one API call. An empty list succeeds without a request. */
|
|
26
|
+
deleteRecordingBatch(recordingIds: readonly string[]): Promise<DeleteRecordingResponse>;
|
|
15
27
|
deleteImage(imageId: string): Promise<DeleteImageResponse>;
|
|
16
28
|
deleteImageBatch(imageIds: readonly string[]): Promise<DeleteImageResponse>;
|
|
29
|
+
private mapRecordingToInternal;
|
|
17
30
|
private mapToInternal;
|
|
18
31
|
createImageBatch<T extends CreateHtmlCssImageRequest | CreateUrlImageRequest>(variations: T[], default_options?: T): Promise<CreateImageBatchResponse>;
|
|
19
32
|
/** Create a template batch, preserving variation order and leaving merging to the API. */
|
|
@@ -21,8 +34,9 @@ export declare class HtmlCssToImageClient implements IHtmlCssToImageClient {
|
|
|
21
34
|
generateTemplatedImageUrl<T extends Record<string, any>>(templateIdOrRequest: string | CreateTemplatedImageRequest<T>, templateValues?: T, templateVersion?: number, format?: RenderImageFormat): string;
|
|
22
35
|
generateCreateAndRenderUrl(request: CreateUrlImageRequest): string;
|
|
23
36
|
private responseToType;
|
|
24
|
-
private
|
|
37
|
+
private responseToDeleteResponse;
|
|
25
38
|
private mapHtmlCssToInternalRequest;
|
|
39
|
+
private mapGoogleFonts;
|
|
26
40
|
private mapUrlToInternalRequest;
|
|
27
41
|
private mapPDFOptionsToInternal;
|
|
28
42
|
private pdfValueWithUnitsToString;
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { CreateTemplatedImageRequest } from "./types/request.js";
|
|
2
|
+
import { knownRecordingStatuses } from "./types/recording.js";
|
|
2
3
|
import * as crypto from 'node:crypto';
|
|
3
4
|
export class HtmlCssToImageClient {
|
|
4
5
|
apiId;
|
|
@@ -38,6 +39,58 @@ export class HtmlCssToImageClient {
|
|
|
38
39
|
});
|
|
39
40
|
return await this.responseToType(response);
|
|
40
41
|
}
|
|
42
|
+
/** Create an HTML/CSS or URL recording. The returned recording_url can be embedded or requested directly and waits until the recording is ready.
|
|
43
|
+
* @see https://docs.htmlcsstoimage.com/getting-started/recordings/
|
|
44
|
+
*/
|
|
45
|
+
async createRecording(request) {
|
|
46
|
+
const internal_request = this.mapRecordingToInternal(request);
|
|
47
|
+
const response = await this.fetch(`${this.baseUrl}/v1/recording`, {
|
|
48
|
+
method: 'POST',
|
|
49
|
+
headers: {
|
|
50
|
+
'Authorization': this.authHeader,
|
|
51
|
+
'Content-Type': 'application/json',
|
|
52
|
+
},
|
|
53
|
+
body: JSON.stringify(internal_request),
|
|
54
|
+
});
|
|
55
|
+
return await this.responseToType(response);
|
|
56
|
+
}
|
|
57
|
+
/** Fetch the current recording status once. HTTP 200 and 202 both return status information. Unrecognized statuses are returned as unknown.
|
|
58
|
+
* @see https://docs.htmlcsstoimage.com/management-api/recordings/
|
|
59
|
+
*/
|
|
60
|
+
async fetchRecordingStatus(recordingId) {
|
|
61
|
+
const response = await this.fetch(`${this.baseUrl}/v1/recordings/${recordingId}/status`, {
|
|
62
|
+
method: 'GET',
|
|
63
|
+
headers: { 'Authorization': this.authHeader },
|
|
64
|
+
});
|
|
65
|
+
const result = await this.responseToType(response);
|
|
66
|
+
if (result.success && !knownRecordingStatuses.includes(result.status)) {
|
|
67
|
+
result.status = 'unknown';
|
|
68
|
+
}
|
|
69
|
+
return result;
|
|
70
|
+
}
|
|
71
|
+
/** Delete a recording and clear its media from the CDN. */
|
|
72
|
+
async deleteRecording(recordingId) {
|
|
73
|
+
const response = await this.fetch(`${this.baseUrl}/v1/recordings/${recordingId}`, {
|
|
74
|
+
method: 'DELETE',
|
|
75
|
+
headers: { 'Authorization': this.authHeader },
|
|
76
|
+
});
|
|
77
|
+
return await this.responseToDeleteResponse(response);
|
|
78
|
+
}
|
|
79
|
+
/** Delete multiple recordings in one API call. An empty list succeeds without a request. */
|
|
80
|
+
async deleteRecordingBatch(recordingIds) {
|
|
81
|
+
if (recordingIds.length === 0) {
|
|
82
|
+
return { success: true };
|
|
83
|
+
}
|
|
84
|
+
const response = await this.fetch(`${this.baseUrl}/v1/recordings/batch`, {
|
|
85
|
+
method: 'DELETE',
|
|
86
|
+
headers: {
|
|
87
|
+
'Authorization': this.authHeader,
|
|
88
|
+
'Content-Type': 'application/json',
|
|
89
|
+
},
|
|
90
|
+
body: JSON.stringify({ ids: recordingIds }),
|
|
91
|
+
});
|
|
92
|
+
return await this.responseToDeleteResponse(response);
|
|
93
|
+
}
|
|
41
94
|
async deleteImage(imageId) {
|
|
42
95
|
const response = await this.fetch(`${this.baseUrl}/v1/image/${encodeURIComponent(imageId)}`, {
|
|
43
96
|
method: 'DELETE',
|
|
@@ -45,9 +98,12 @@ export class HtmlCssToImageClient {
|
|
|
45
98
|
'Authorization': this.authHeader,
|
|
46
99
|
},
|
|
47
100
|
});
|
|
48
|
-
return await this.
|
|
101
|
+
return await this.responseToDeleteResponse(response);
|
|
49
102
|
}
|
|
50
103
|
async deleteImageBatch(imageIds) {
|
|
104
|
+
if (imageIds.length === 0) {
|
|
105
|
+
return { success: true };
|
|
106
|
+
}
|
|
51
107
|
const response = await this.fetch(`${this.baseUrl}/v1/image/batch`, {
|
|
52
108
|
method: 'DELETE',
|
|
53
109
|
headers: {
|
|
@@ -56,7 +112,24 @@ export class HtmlCssToImageClient {
|
|
|
56
112
|
},
|
|
57
113
|
body: JSON.stringify({ ids: imageIds }),
|
|
58
114
|
});
|
|
59
|
-
return await this.
|
|
115
|
+
return await this.responseToDeleteResponse(response);
|
|
116
|
+
}
|
|
117
|
+
mapRecordingToInternal(request) {
|
|
118
|
+
switch (request.__type) {
|
|
119
|
+
case 'html_css': {
|
|
120
|
+
const { __type, google_fonts, ...shared_request } = request;
|
|
121
|
+
return {
|
|
122
|
+
...shared_request,
|
|
123
|
+
google_fonts: google_fonts === null ? null : this.mapGoogleFonts(google_fonts),
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
case 'url': {
|
|
127
|
+
const { __type, ...shared_request } = request;
|
|
128
|
+
return shared_request;
|
|
129
|
+
}
|
|
130
|
+
default:
|
|
131
|
+
throw new Error("Unsupported request type");
|
|
132
|
+
}
|
|
60
133
|
}
|
|
61
134
|
mapToInternal(request, in_batch) {
|
|
62
135
|
switch (request.__type) {
|
|
@@ -195,7 +268,7 @@ export class HtmlCssToImageClient {
|
|
|
195
268
|
return { success: false, ...response_json };
|
|
196
269
|
}
|
|
197
270
|
}
|
|
198
|
-
async
|
|
271
|
+
async responseToDeleteResponse(response) {
|
|
199
272
|
if (response.ok) {
|
|
200
273
|
return { success: true };
|
|
201
274
|
}
|
|
@@ -214,14 +287,17 @@ export class HtmlCssToImageClient {
|
|
|
214
287
|
new_request = { ...shared_request };
|
|
215
288
|
}
|
|
216
289
|
new_request.pdf_options = this.mapPDFOptionsToInternal(pdf_options);
|
|
290
|
+
new_request.google_fonts = this.mapGoogleFonts(google_fonts);
|
|
291
|
+
return new_request;
|
|
292
|
+
}
|
|
293
|
+
mapGoogleFonts(google_fonts) {
|
|
217
294
|
if (google_fonts && google_fonts.length > 0) {
|
|
218
295
|
const processed_fonts = google_fonts
|
|
219
296
|
.map(font => font.trim().replace(/ /g, '+'))
|
|
220
297
|
.filter(font => font.length > 0);
|
|
221
|
-
|
|
222
|
-
new_request.google_fonts = unique_fonts.join('|');
|
|
298
|
+
return [...new Set(processed_fonts)].join('|');
|
|
223
299
|
}
|
|
224
|
-
return
|
|
300
|
+
return undefined;
|
|
225
301
|
}
|
|
226
302
|
mapUrlToInternalRequest(request, in_batch) {
|
|
227
303
|
const { pdf_options, __type, ...shared_request } = request;
|
|
@@ -1,7 +1,14 @@
|
|
|
1
|
-
import type { TemplatedBatchImageOptions } from "./types/request.js";
|
|
2
|
-
import type {
|
|
3
|
-
import type { CreateImageBatchResponse, CreateImageResponse, DeleteImageResponse } from "./types/response.js";
|
|
1
|
+
import type { CreateHtmlCssImageRequest, CreateHtmlCssRecordingRequest, CreateTemplatedImageRequest, CreateUrlImageRequest, CreateUrlRecordingRequest, RenderImageFormat, TemplatedBatchImageOptions } from "./types/request.js";
|
|
2
|
+
import type { CreateImageBatchResponse, CreateImageResponse, CreateRecordingResponse, DeleteImageResponse, DeleteRecordingResponse, RecordingStatusResponse } from "./types/response.js";
|
|
4
3
|
export interface IHtmlCssToImageClient {
|
|
4
|
+
/** Create an HTML/CSS or URL recording. Rendering may continue after creation. */
|
|
5
|
+
createRecording(request: CreateHtmlCssRecordingRequest | CreateUrlRecordingRequest): Promise<CreateRecordingResponse>;
|
|
6
|
+
/** Fetch lifecycle status once. Both HTTP 200 and 202 return status information. */
|
|
7
|
+
fetchRecordingStatus(recordingId: string): Promise<RecordingStatusResponse>;
|
|
8
|
+
/** Delete a recording and clear its media from the CDN. */
|
|
9
|
+
deleteRecording(recordingId: string): Promise<DeleteRecordingResponse>;
|
|
10
|
+
/** Delete multiple recordings in one API call. */
|
|
11
|
+
deleteRecordingBatch(recordingIds: readonly string[]): Promise<DeleteRecordingResponse>;
|
|
5
12
|
createImage(request: CreateHtmlCssImageRequest | CreateUrlImageRequest | CreateTemplatedImageRequest): Promise<CreateImageResponse>;
|
|
6
13
|
createImageBatch<T extends CreateHtmlCssImageRequest | CreateUrlImageRequest>(variations: T[], default_options?: T): Promise<CreateImageBatchResponse>;
|
|
7
14
|
deleteImage(imageId: string): Promise<DeleteImageResponse>;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, TemplatedBatchImageOptions, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
|
|
1
|
+
export { BaseCreateImageRequest, BaseCreateRecordingRequest, CreateHtmlCssRecordingRequest, CreateUrlRecordingRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, TemplatedBatchImageOptions, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
|
|
2
2
|
export type { ColorSchemeType, MediaType, PdfMargins, PdfValueInput, PdfValueWithUnits, PdfUnit, RenderImageFormat, RequestOverride } from './types/request.js';
|
|
3
|
-
export type { CreateImageBatchResponse, CreateImageBatchSuccessResponse, CreateImageErrorResponse, CreateImageResponse, CreateImageSuccessResponse, DeleteImageResponse, DeleteImageSuccessResponse, ValidationError } from './types/response.js';
|
|
3
|
+
export type { CreateRecordingResponse, CreateRecordingSuccessResponse, RecordingStatusResponse, RecordingStatusSuccessResponse, DeleteRecordingResponse, 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';
|
|
6
6
|
export type { IHtmlCssToImageClient } from './IHtmlCssToImageClient.js';
|
|
7
|
+
export type { RecordingFormat, RecordingDurationMode, RecordingStatus, RecordingMouseButton, RecordingOutputOptions, RecordingTrigger, RecordingImmediateTrigger, RecordingElementVisibleTrigger, RecordingFunctionCallTrigger, RecordingAction, RecordingSimpleScrollAction, RecordingScrollAction, RecordingStallAction, RecordingLocateSelectorAction, RecordingClickAction, RecordingExecuteJavaScriptAction, RecordingErrorAction, RecordingError, ScrollPosition, ScrollEasing, ScrollStep, ScrollTarget, PositionScrollTarget, CoordinatesScrollTarget, SelectorScrollTarget } from './types/recording.js';
|
package/dist/index.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export { BaseCreateImageRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, TemplatedBatchImageOptions, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
|
|
1
|
+
export { BaseCreateImageRequest, BaseCreateRecordingRequest, CreateHtmlCssRecordingRequest, CreateUrlRecordingRequest, CreateHtmlCssImageRequest, CreateTemplatedImageRequest, TemplatedBatchImageOptions, CreateUrlImageRequest, PDFOptions, RequestOverrideAction, RequestOverrideResourceType } from './types/request.js';
|
|
2
2
|
export { HtmlCssToImageClient } from './HtmlCssToImageClient.js';
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/** Recording media format. Recordings do not include audio. */
|
|
2
|
+
export type RecordingFormat = 'mp4' | 'webm' | 'gif';
|
|
3
|
+
/**
|
|
4
|
+
* How the requested duration controls the recording timeline:
|
|
5
|
+
* - fixed pads or cuts off at the requested duration.
|
|
6
|
+
* - target adjusts playback speed to fit the completed timeline.
|
|
7
|
+
* - at_least records for at least the requested duration, letting actions finish up to 90 seconds.
|
|
8
|
+
* - at_most stops when actions finish or the requested duration is reached (default).
|
|
9
|
+
* @see https://docs.htmlcsstoimage.com/parameters/duration_mode/
|
|
10
|
+
*/
|
|
11
|
+
export type RecordingDurationMode = 'fixed' | 'target' | 'at_least' | 'at_most';
|
|
12
|
+
/** Recording lifecycle states recognized by this client. ready, failed, and cancelled are terminal. */
|
|
13
|
+
export declare const knownRecordingStatuses: readonly ["processing", "pending_retry", "ready", "failed", "cancelled", "awaiting_render"];
|
|
14
|
+
/**
|
|
15
|
+
* Current recording lifecycle state. ready, failed, and cancelled are terminal.
|
|
16
|
+
* unknown is an unrecognized status from a newer API version.
|
|
17
|
+
* @see https://docs.htmlcsstoimage.com/management-api/recordings/
|
|
18
|
+
*/
|
|
19
|
+
export type RecordingStatus = typeof knownRecordingStatuses[number] | 'unknown';
|
|
20
|
+
/** Edge of the document or selected scroll container. */
|
|
21
|
+
export type ScrollPosition = 'top' | 'bottom' | 'left' | 'right';
|
|
22
|
+
export type RecordingMouseButton = 'left' | 'right' | 'middle' | 'back' | 'forward';
|
|
23
|
+
/** Easing curve for a scroll movement. */
|
|
24
|
+
export type ScrollEasing = 'linear' | 'ease_in_cubic' | 'ease_out_cubic' | 'ease_in_out_cubic' | 'ease_in_quad' | 'ease_out_quad' | 'ease_in_out_quad' | 'ease_in_quart' | 'ease_out_quart' | 'ease_in_out_quart' | 'ease_in_quint' | 'ease_out_quint' | 'ease_in_out_quint' | 'ease_in_sine' | 'ease_out_sine' | 'ease_in_out_sine' | 'ease_in_expo' | 'ease_out_expo' | 'ease_in_out_expo' | 'ease_in_circ' | 'ease_out_circ' | 'ease_in_out_circ' | 'ease_in_back' | 'ease_out_back' | 'ease_in_out_back' | 'ease_in_elastic' | 'ease_out_elastic' | 'ease_in_out_elastic' | 'ease_in_bounce' | 'ease_out_bounce' | 'ease_in_out_bounce';
|
|
25
|
+
/**
|
|
26
|
+
* Format, frame rate, and output size. The browser viewport is configured separately.
|
|
27
|
+
* @see https://docs.htmlcsstoimage.com/parameters/output/
|
|
28
|
+
*/
|
|
29
|
+
export interface RecordingOutputOptions {
|
|
30
|
+
/** Media format. Defaults to mp4. */
|
|
31
|
+
format?: RecordingFormat | null;
|
|
32
|
+
/** Frames per second. Defaults to 15 for GIF and 30 for video. GIF supports 10–50; video supports 10–120. */
|
|
33
|
+
fps?: number | null;
|
|
34
|
+
/** Scales captured pixels without changing page layout. Defaults to 1; 0.5 halves both dimensions. */
|
|
35
|
+
scale?: number | null;
|
|
36
|
+
}
|
|
37
|
+
/** Start recording immediately after page preparation. This is the default trigger. */
|
|
38
|
+
export interface RecordingImmediateTrigger {
|
|
39
|
+
type: 'immediate';
|
|
40
|
+
}
|
|
41
|
+
/** Wait for a matching element to become visible before recording. A timeout fails the recording. */
|
|
42
|
+
export interface RecordingElementVisibleTrigger {
|
|
43
|
+
type: 'element_visible';
|
|
44
|
+
/** CSS selector for the element to wait for. */
|
|
45
|
+
selector: string;
|
|
46
|
+
/** Maximum wait in milliseconds. Defaults to 1000; minimum 100. Plan limits apply. */
|
|
47
|
+
timeout_ms?: number;
|
|
48
|
+
}
|
|
49
|
+
/** Wait for the page to call window.RecordingReady(). A timeout fails the recording. */
|
|
50
|
+
export interface RecordingFunctionCallTrigger {
|
|
51
|
+
type: 'function_call';
|
|
52
|
+
/** Maximum wait in milliseconds. Defaults to 1000; minimum 100. Plan limits apply. */
|
|
53
|
+
timeout_ms?: number;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* When capture and timeline actions start, after page preparation.
|
|
57
|
+
* @see https://docs.htmlcsstoimage.com/parameters/trigger/
|
|
58
|
+
*/
|
|
59
|
+
export type RecordingTrigger = RecordingImmediateTrigger | RecordingElementVisibleTrigger | RecordingFunctionCallTrigger;
|
|
60
|
+
/** Scroll down repeatedly until reaching the bottom or the recording deadline. */
|
|
61
|
+
export interface RecordingSimpleScrollAction {
|
|
62
|
+
type: 'simple_scroll';
|
|
63
|
+
/** Duration of each movement in milliseconds. Defaults to 800. */
|
|
64
|
+
scroll_duration_ms?: number | null;
|
|
65
|
+
/** Pause between movements in milliseconds. Defaults to 400; 0 scrolls continuously. */
|
|
66
|
+
ms_between_scrolls?: number | null;
|
|
67
|
+
/** CSS pixels as a number, or a string such as '900px' or '50vh'. Omit or use null to use API defaults. */
|
|
68
|
+
scroll_distance?: number | string | null;
|
|
69
|
+
/** Movement easing. Omit or use null to use API defaults. */
|
|
70
|
+
easing?: ScrollEasing | null;
|
|
71
|
+
/** Time to hold at the bottom in milliseconds, limited by remaining recording time. Defaults to 0. */
|
|
72
|
+
stall_at_end_ms?: number | null;
|
|
73
|
+
}
|
|
74
|
+
/** Scroll through an ordered sequence of timed movements. */
|
|
75
|
+
export interface RecordingScrollAction {
|
|
76
|
+
type: 'scroll';
|
|
77
|
+
/** Scrollable container's CSS selector. Omit or use null to scroll the document. */
|
|
78
|
+
container_selector?: string | null;
|
|
79
|
+
/** Ordered movements. Supply at least one step. */
|
|
80
|
+
steps: ScrollStep[];
|
|
81
|
+
/** Fallback when the container is missing. Omitted, null, or empty skips this action. */
|
|
82
|
+
if_not_found?: RecordingAction[] | null;
|
|
83
|
+
}
|
|
84
|
+
/** Wait while capture and page activity continue. */
|
|
85
|
+
export interface RecordingStallAction {
|
|
86
|
+
type: 'stall';
|
|
87
|
+
/** Wait in milliseconds. The recording deadline can end it early. */
|
|
88
|
+
duration_ms?: number;
|
|
89
|
+
}
|
|
90
|
+
/** Find an element and run the corresponding branch. Each branch action supplies its own selector. */
|
|
91
|
+
export interface RecordingLocateSelectorAction {
|
|
92
|
+
type: 'locate_selector';
|
|
93
|
+
/** CSS selector to find. */
|
|
94
|
+
selector: string;
|
|
95
|
+
/** Maximum wait in milliseconds. Defaults to 0 for a single check. */
|
|
96
|
+
timeout_ms?: number;
|
|
97
|
+
/** Actions when found. Omitted, null, or empty continues with the parent sequence. */
|
|
98
|
+
if_found?: RecordingAction[] | null;
|
|
99
|
+
/** Actions when missing. Include an error action to fail the recording. */
|
|
100
|
+
if_not_found?: RecordingAction[] | null;
|
|
101
|
+
}
|
|
102
|
+
/** Find and click an element, scrolling it into view if needed. */
|
|
103
|
+
export interface RecordingClickAction {
|
|
104
|
+
type: 'click';
|
|
105
|
+
/** CSS selector of the element to click. */
|
|
106
|
+
selector: string;
|
|
107
|
+
/** Maximum wait in milliseconds. Defaults to 0 for a single check. */
|
|
108
|
+
timeout_ms?: number;
|
|
109
|
+
/** Fallback when missing. Omitted, null, or empty continues; use an error action to fail. */
|
|
110
|
+
if_not_found?: RecordingAction[] | null;
|
|
111
|
+
/** Mouse button. Defaults to left. */
|
|
112
|
+
button?: RecordingMouseButton | null;
|
|
113
|
+
/** Event click count, from 1 to 3. Defaults to 1; this does not repeat the action. */
|
|
114
|
+
count?: number | null;
|
|
115
|
+
/** Delay between mouse down and up, in milliseconds. Defaults to 0; maximum 5000. */
|
|
116
|
+
delay_ms?: number | null;
|
|
117
|
+
/** CSS pixels from the element's top-left. Supplying either offset makes the other default to 0. */
|
|
118
|
+
offset_x?: number | null;
|
|
119
|
+
/** CSS pixels from the element's top-left. Omit both offsets to use the default clickable point. */
|
|
120
|
+
offset_y?: number | null;
|
|
121
|
+
}
|
|
122
|
+
/** Run an async JavaScript function body in the page while recording. */
|
|
123
|
+
export interface RecordingExecuteJavaScriptAction {
|
|
124
|
+
type: 'execute_javascript';
|
|
125
|
+
/** Function body supporting await. Its return value is ignored. */
|
|
126
|
+
script: string;
|
|
127
|
+
/** Maximum execution time in milliseconds. Zero or omitted uses the page timeout; maximum 90000. */
|
|
128
|
+
timeout_ms?: number;
|
|
129
|
+
/** Omitted or null fails on script errors; [] ignores errors. A timeout does not undo side effects. */
|
|
130
|
+
if_error?: RecordingAction[] | null;
|
|
131
|
+
}
|
|
132
|
+
/** Fail the recording. This must be the last action in its array. */
|
|
133
|
+
export interface RecordingErrorAction {
|
|
134
|
+
type: 'error';
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Ordered timeline interactions. Nested branches return to their parent sequence on completion.
|
|
138
|
+
* @see https://docs.htmlcsstoimage.com/parameters/actions/
|
|
139
|
+
*/
|
|
140
|
+
export type RecordingAction = RecordingSimpleScrollAction | RecordingScrollAction | RecordingStallAction | RecordingLocateSelectorAction | RecordingClickAction | RecordingExecuteJavaScriptAction | RecordingErrorAction;
|
|
141
|
+
/** Scroll to an edge of the document or selected container. */
|
|
142
|
+
export interface PositionScrollTarget {
|
|
143
|
+
type: 'position';
|
|
144
|
+
/** Edge to scroll to. Defaults to top. */
|
|
145
|
+
position?: ScrollPosition;
|
|
146
|
+
}
|
|
147
|
+
/** Scroll to absolute CSS pixel coordinates within the document or selected container. */
|
|
148
|
+
export interface CoordinatesScrollTarget {
|
|
149
|
+
type: 'coordinates';
|
|
150
|
+
/** Horizontal position. Defaults to 0. */
|
|
151
|
+
x?: number;
|
|
152
|
+
/** Vertical position. Defaults to 0. */
|
|
153
|
+
y?: number;
|
|
154
|
+
}
|
|
155
|
+
/** Scroll to a matching element with optional offsets in CSS pixels. */
|
|
156
|
+
export interface SelectorScrollTarget {
|
|
157
|
+
type: 'selector';
|
|
158
|
+
selector: string;
|
|
159
|
+
/** Horizontal offset from the element. Defaults to 0. */
|
|
160
|
+
offset_x?: number;
|
|
161
|
+
/** Vertical offset from the element. Defaults to 0. */
|
|
162
|
+
offset_y?: number;
|
|
163
|
+
/** Fallback when missing. Omitted, null, or empty skips this movement and continues to the next step. */
|
|
164
|
+
if_not_found?: RecordingAction[] | null;
|
|
165
|
+
}
|
|
166
|
+
/** Destination for a scroll step within the document or selected container. */
|
|
167
|
+
export type ScrollTarget = PositionScrollTarget | CoordinatesScrollTarget | SelectorScrollTarget;
|
|
168
|
+
/** One timed movement in a scroll action. */
|
|
169
|
+
export interface ScrollStep {
|
|
170
|
+
to: ScrollTarget;
|
|
171
|
+
/** Required movement duration in milliseconds, at least 1. The recording deadline can cut it short. */
|
|
172
|
+
duration_ms: number;
|
|
173
|
+
/** Movement easing. Defaults to linear. */
|
|
174
|
+
easing?: ScrollEasing;
|
|
175
|
+
}
|
|
176
|
+
/** Error from a recording attempt. The lifecycle status determines whether processing will continue. */
|
|
177
|
+
export interface RecordingError {
|
|
178
|
+
/** Machine-readable failure code. */
|
|
179
|
+
code: string;
|
|
180
|
+
/** Human-readable failure details. */
|
|
181
|
+
message: string;
|
|
182
|
+
/** UTC timestamp as an ISO 8601 string. */
|
|
183
|
+
occurred_at: string;
|
|
184
|
+
/** Whether this kind of failure is eligible for retry. Status and the retry budget still apply. */
|
|
185
|
+
retryable: boolean;
|
|
186
|
+
/** Failing action's path, such as 'actions[1].if_found[0]', or null when unrelated to an action. */
|
|
187
|
+
action_path?: string | null;
|
|
188
|
+
}
|
package/dist/types/request.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { RecordingAction, RecordingDurationMode, RecordingOutputOptions, RecordingTrigger } from "./recording.js";
|
|
1
2
|
export type ColorSchemeType = 'light' | 'dark';
|
|
2
3
|
export type PdfUnit = 'px' | 'in' | 'cm' | 'mm';
|
|
3
4
|
export type MediaType = 'print' | 'screen';
|
|
@@ -290,3 +291,151 @@ export declare class TemplatedBatchImageOptions<T = Record<string, any>> {
|
|
|
290
291
|
format?: RenderImageFormat;
|
|
291
292
|
constructor(init?: Partial<TemplatedBatchImageOptions<T>>);
|
|
292
293
|
}
|
|
294
|
+
/**
|
|
295
|
+
* Shared browser settings and timeline options for recording HTML/CSS or a URL.
|
|
296
|
+
* Optional settings use the API defaults.
|
|
297
|
+
* @see https://docs.htmlcsstoimage.com/getting-started/recordings/
|
|
298
|
+
*/
|
|
299
|
+
export declare abstract class BaseCreateRecordingRequest {
|
|
300
|
+
/**
|
|
301
|
+
* Requested duration in milliseconds: 500–30000, or up to 90000 in target mode.
|
|
302
|
+
* duration_mode controls how actions fit into this duration.
|
|
303
|
+
* @see https://docs.htmlcsstoimage.com/parameters/duration_ms/
|
|
304
|
+
*/
|
|
305
|
+
duration_ms: number;
|
|
306
|
+
/**
|
|
307
|
+
* CSS to style HTML content or inject into a URL page after it loads.
|
|
308
|
+
* @see https://docs.htmlcsstoimage.com/parameters/css/
|
|
309
|
+
*/
|
|
310
|
+
css?: string | null;
|
|
311
|
+
/**
|
|
312
|
+
* Capture pixel density. Defaults to 2 for HTML/CSS and 1 for URL recordings.
|
|
313
|
+
* @see https://docs.htmlcsstoimage.com/parameters/device_scale/
|
|
314
|
+
*/
|
|
315
|
+
device_scale?: number | null;
|
|
316
|
+
/**
|
|
317
|
+
* Viewport height in CSS pixels. Supply both dimensions to set the recording size.
|
|
318
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
319
|
+
*/
|
|
320
|
+
viewport_height?: number | null;
|
|
321
|
+
/**
|
|
322
|
+
* Viewport width in CSS pixels. Supply both dimensions to set the recording size.
|
|
323
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
324
|
+
*/
|
|
325
|
+
viewport_width?: number | null;
|
|
326
|
+
/**
|
|
327
|
+
* Disable Twemoji for HTML/CSS when true. URL recordings inject it only when explicitly false.
|
|
328
|
+
* @see https://docs.htmlcsstoimage.com/parameters/disable_twemoji/
|
|
329
|
+
*/
|
|
330
|
+
disable_twemoji?: boolean | null;
|
|
331
|
+
/**
|
|
332
|
+
* Reuse an identical recording created within this many seconds. Set to 0 to disable deduplication.
|
|
333
|
+
* @see https://docs.htmlcsstoimage.com/parameters/dedupe_duration_s/
|
|
334
|
+
*/
|
|
335
|
+
dedupe_duration_s?: number | null;
|
|
336
|
+
/**
|
|
337
|
+
* Chrome's preferred light or dark color scheme while recording.
|
|
338
|
+
* @see https://docs.htmlcsstoimage.com/parameters/color_scheme/
|
|
339
|
+
*/
|
|
340
|
+
color_scheme?: ColorSchemeType | null;
|
|
341
|
+
/**
|
|
342
|
+
* Browser timezone as an IANA identifier, such as 'America/New_York'.
|
|
343
|
+
* @see https://docs.htmlcsstoimage.com/parameters/timezone/
|
|
344
|
+
*/
|
|
345
|
+
timezone?: string | null;
|
|
346
|
+
/** Enable mobile viewport behavior, including the page's viewport meta tag.
|
|
347
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
348
|
+
*/
|
|
349
|
+
viewport_mobile?: boolean | null;
|
|
350
|
+
/** Emulate landscape orientation.
|
|
351
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
352
|
+
*/
|
|
353
|
+
viewport_landscape?: boolean | null;
|
|
354
|
+
/** Emulate a viewport that supports touch events.
|
|
355
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
356
|
+
*/
|
|
357
|
+
viewport_touch?: boolean | null;
|
|
358
|
+
/** CSS media type used while recording.
|
|
359
|
+
* @see https://docs.htmlcsstoimage.com/parameters/media_type/
|
|
360
|
+
*/
|
|
361
|
+
media_type?: MediaType | null;
|
|
362
|
+
/** Organization proxy to use while recording.
|
|
363
|
+
* @see https://docs.htmlcsstoimage.com/guides/advanced/proxies/
|
|
364
|
+
*/
|
|
365
|
+
proxy_id?: string | null;
|
|
366
|
+
/** Storage destination to receive the recording.
|
|
367
|
+
* @see https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/
|
|
368
|
+
*/
|
|
369
|
+
storage_destination_id?: string | null;
|
|
370
|
+
/** Block matching browser requests while recording. Available on paid plans.
|
|
371
|
+
* @see https://docs.htmlcsstoimage.com/parameters/request_overrides/
|
|
372
|
+
*/
|
|
373
|
+
request_overrides?: RequestOverride[] | null;
|
|
374
|
+
/** When recording and actions start after page preparation. Defaults to immediate.
|
|
375
|
+
* @see https://docs.htmlcsstoimage.com/parameters/trigger/
|
|
376
|
+
*/
|
|
377
|
+
trigger?: RecordingTrigger | null;
|
|
378
|
+
/** Ordered interactions. Leave null or empty to record the page without interactions.
|
|
379
|
+
* @see https://docs.htmlcsstoimage.com/parameters/actions/
|
|
380
|
+
*/
|
|
381
|
+
actions?: RecordingAction[] | null;
|
|
382
|
+
/** Output format, frame rate, and scale. Defaults to MP4 at 30 fps without audio.
|
|
383
|
+
* @see https://docs.htmlcsstoimage.com/parameters/output/
|
|
384
|
+
*/
|
|
385
|
+
output?: RecordingOutputOptions | null;
|
|
386
|
+
/** How duration_ms limits the timeline. Defaults to at_most.
|
|
387
|
+
* @see https://docs.htmlcsstoimage.com/parameters/duration_mode/
|
|
388
|
+
*/
|
|
389
|
+
duration_mode?: RecordingDurationMode | null;
|
|
390
|
+
/** Wait to render until media or storage is requested. Defaults to false; does not reset deduplicated recordings.
|
|
391
|
+
* @see https://docs.htmlcsstoimage.com/parameters/defer_render/
|
|
392
|
+
*/
|
|
393
|
+
defer_render?: boolean | null;
|
|
394
|
+
/** Skip the preparation scroll that loads lazy content. Scrolling actions still run. Defaults to false.
|
|
395
|
+
* @see https://docs.htmlcsstoimage.com/parameters/skip_scroll_preload/
|
|
396
|
+
*/
|
|
397
|
+
skip_scroll_preload?: boolean | null;
|
|
398
|
+
protected constructor(init?: Partial<BaseCreateRecordingRequest>);
|
|
399
|
+
}
|
|
400
|
+
/** Record an HTML document or fragment with optional CSS and Google Fonts. */
|
|
401
|
+
export declare class CreateHtmlCssRecordingRequest extends BaseCreateRecordingRequest {
|
|
402
|
+
readonly __type: "html_css";
|
|
403
|
+
/** HTML document or fragment to record. Fragments are rendered in a wrapper document.
|
|
404
|
+
* @see https://docs.htmlcsstoimage.com/parameters/html/
|
|
405
|
+
*/
|
|
406
|
+
html: string;
|
|
407
|
+
/** Google Fonts to load. Set font-family in your CSS to use them.
|
|
408
|
+
* @see https://docs.htmlcsstoimage.com/parameters/google_fonts/
|
|
409
|
+
*/
|
|
410
|
+
google_fonts?: string[] | null;
|
|
411
|
+
constructor(init?: Partial<CreateHtmlCssRecordingRequest>);
|
|
412
|
+
}
|
|
413
|
+
/** Record a public HTTP or HTTPS webpage. */
|
|
414
|
+
export declare class CreateUrlRecordingRequest extends BaseCreateRecordingRequest {
|
|
415
|
+
readonly __type: "url";
|
|
416
|
+
/** Public HTTP or HTTPS URL to record.
|
|
417
|
+
* @see https://docs.htmlcsstoimage.com/parameters/url/
|
|
418
|
+
*/
|
|
419
|
+
url: string;
|
|
420
|
+
/** Attempt to hide cookie and consent banners before recording.
|
|
421
|
+
* @see https://docs.htmlcsstoimage.com/guides/advanced/blocking-cookie-banners/
|
|
422
|
+
*/
|
|
423
|
+
block_consent_banners?: boolean | null;
|
|
424
|
+
/** Add X-HCTI-SCREENSHOT: 1 to the top-level navigation.
|
|
425
|
+
* @see https://docs.htmlcsstoimage.com/parameters/identify_as_hcti/
|
|
426
|
+
*/
|
|
427
|
+
identify_as_hcti?: boolean | null;
|
|
428
|
+
/** Custom headers for top-level navigations to the URL's origin and additional_header_origins.
|
|
429
|
+
* @see https://docs.htmlcsstoimage.com/parameters/headers/
|
|
430
|
+
*/
|
|
431
|
+
headers?: Record<string, string> | null;
|
|
432
|
+
/** Additional exact HTTP or HTTPS origins allowed to receive custom headers.
|
|
433
|
+
* @see https://docs.htmlcsstoimage.com/parameters/headers/#additional-header-origins
|
|
434
|
+
*/
|
|
435
|
+
additional_header_origins?: string[] | null;
|
|
436
|
+
/** Send custom headers with subrequests to allowed origins. Defaults to false.
|
|
437
|
+
* @see https://docs.htmlcsstoimage.com/parameters/headers/#include-headers-on-subrequests
|
|
438
|
+
*/
|
|
439
|
+
include_headers_on_subrequests?: boolean | null;
|
|
440
|
+
constructor(init?: Partial<CreateUrlRecordingRequest>);
|
|
441
|
+
}
|
package/dist/types/request.js
CHANGED
|
@@ -279,3 +279,159 @@ export class TemplatedBatchImageOptions {
|
|
|
279
279
|
Object.assign(this, init);
|
|
280
280
|
}
|
|
281
281
|
}
|
|
282
|
+
/**
|
|
283
|
+
* Shared browser settings and timeline options for recording HTML/CSS or a URL.
|
|
284
|
+
* Optional settings use the API defaults.
|
|
285
|
+
* @see https://docs.htmlcsstoimage.com/getting-started/recordings/
|
|
286
|
+
*/
|
|
287
|
+
export class BaseCreateRecordingRequest {
|
|
288
|
+
/**
|
|
289
|
+
* Requested duration in milliseconds: 500–30000, or up to 90000 in target mode.
|
|
290
|
+
* duration_mode controls how actions fit into this duration.
|
|
291
|
+
* @see https://docs.htmlcsstoimage.com/parameters/duration_ms/
|
|
292
|
+
*/
|
|
293
|
+
duration_ms;
|
|
294
|
+
/**
|
|
295
|
+
* CSS to style HTML content or inject into a URL page after it loads.
|
|
296
|
+
* @see https://docs.htmlcsstoimage.com/parameters/css/
|
|
297
|
+
*/
|
|
298
|
+
css;
|
|
299
|
+
/**
|
|
300
|
+
* Capture pixel density. Defaults to 2 for HTML/CSS and 1 for URL recordings.
|
|
301
|
+
* @see https://docs.htmlcsstoimage.com/parameters/device_scale/
|
|
302
|
+
*/
|
|
303
|
+
device_scale;
|
|
304
|
+
/**
|
|
305
|
+
* Viewport height in CSS pixels. Supply both dimensions to set the recording size.
|
|
306
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
307
|
+
*/
|
|
308
|
+
viewport_height;
|
|
309
|
+
/**
|
|
310
|
+
* Viewport width in CSS pixels. Supply both dimensions to set the recording size.
|
|
311
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
312
|
+
*/
|
|
313
|
+
viewport_width;
|
|
314
|
+
/**
|
|
315
|
+
* Disable Twemoji for HTML/CSS when true. URL recordings inject it only when explicitly false.
|
|
316
|
+
* @see https://docs.htmlcsstoimage.com/parameters/disable_twemoji/
|
|
317
|
+
*/
|
|
318
|
+
disable_twemoji;
|
|
319
|
+
/**
|
|
320
|
+
* Reuse an identical recording created within this many seconds. Set to 0 to disable deduplication.
|
|
321
|
+
* @see https://docs.htmlcsstoimage.com/parameters/dedupe_duration_s/
|
|
322
|
+
*/
|
|
323
|
+
dedupe_duration_s;
|
|
324
|
+
/**
|
|
325
|
+
* Chrome's preferred light or dark color scheme while recording.
|
|
326
|
+
* @see https://docs.htmlcsstoimage.com/parameters/color_scheme/
|
|
327
|
+
*/
|
|
328
|
+
color_scheme;
|
|
329
|
+
/**
|
|
330
|
+
* Browser timezone as an IANA identifier, such as 'America/New_York'.
|
|
331
|
+
* @see https://docs.htmlcsstoimage.com/parameters/timezone/
|
|
332
|
+
*/
|
|
333
|
+
timezone;
|
|
334
|
+
/** Enable mobile viewport behavior, including the page's viewport meta tag.
|
|
335
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
336
|
+
*/
|
|
337
|
+
viewport_mobile;
|
|
338
|
+
/** Emulate landscape orientation.
|
|
339
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
340
|
+
*/
|
|
341
|
+
viewport_landscape;
|
|
342
|
+
/** Emulate a viewport that supports touch events.
|
|
343
|
+
* @see https://docs.htmlcsstoimage.com/parameters/viewport/
|
|
344
|
+
*/
|
|
345
|
+
viewport_touch;
|
|
346
|
+
/** CSS media type used while recording.
|
|
347
|
+
* @see https://docs.htmlcsstoimage.com/parameters/media_type/
|
|
348
|
+
*/
|
|
349
|
+
media_type;
|
|
350
|
+
/** Organization proxy to use while recording.
|
|
351
|
+
* @see https://docs.htmlcsstoimage.com/guides/advanced/proxies/
|
|
352
|
+
*/
|
|
353
|
+
proxy_id;
|
|
354
|
+
/** Storage destination to receive the recording.
|
|
355
|
+
* @see https://docs.htmlcsstoimage.com/guides/advanced/storage-destinations/
|
|
356
|
+
*/
|
|
357
|
+
storage_destination_id;
|
|
358
|
+
/** Block matching browser requests while recording. Available on paid plans.
|
|
359
|
+
* @see https://docs.htmlcsstoimage.com/parameters/request_overrides/
|
|
360
|
+
*/
|
|
361
|
+
request_overrides;
|
|
362
|
+
/** When recording and actions start after page preparation. Defaults to immediate.
|
|
363
|
+
* @see https://docs.htmlcsstoimage.com/parameters/trigger/
|
|
364
|
+
*/
|
|
365
|
+
trigger;
|
|
366
|
+
/** Ordered interactions. Leave null or empty to record the page without interactions.
|
|
367
|
+
* @see https://docs.htmlcsstoimage.com/parameters/actions/
|
|
368
|
+
*/
|
|
369
|
+
actions;
|
|
370
|
+
/** Output format, frame rate, and scale. Defaults to MP4 at 30 fps without audio.
|
|
371
|
+
* @see https://docs.htmlcsstoimage.com/parameters/output/
|
|
372
|
+
*/
|
|
373
|
+
output;
|
|
374
|
+
/** How duration_ms limits the timeline. Defaults to at_most.
|
|
375
|
+
* @see https://docs.htmlcsstoimage.com/parameters/duration_mode/
|
|
376
|
+
*/
|
|
377
|
+
duration_mode;
|
|
378
|
+
/** Wait to render until media or storage is requested. Defaults to false; does not reset deduplicated recordings.
|
|
379
|
+
* @see https://docs.htmlcsstoimage.com/parameters/defer_render/
|
|
380
|
+
*/
|
|
381
|
+
defer_render;
|
|
382
|
+
/** Skip the preparation scroll that loads lazy content. Scrolling actions still run. Defaults to false.
|
|
383
|
+
* @see https://docs.htmlcsstoimage.com/parameters/skip_scroll_preload/
|
|
384
|
+
*/
|
|
385
|
+
skip_scroll_preload;
|
|
386
|
+
constructor(init) {
|
|
387
|
+
Object.assign(this, init);
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
/** Record an HTML document or fragment with optional CSS and Google Fonts. */
|
|
391
|
+
export class CreateHtmlCssRecordingRequest extends BaseCreateRecordingRequest {
|
|
392
|
+
__type = 'html_css';
|
|
393
|
+
/** HTML document or fragment to record. Fragments are rendered in a wrapper document.
|
|
394
|
+
* @see https://docs.htmlcsstoimage.com/parameters/html/
|
|
395
|
+
*/
|
|
396
|
+
html;
|
|
397
|
+
/** Google Fonts to load. Set font-family in your CSS to use them.
|
|
398
|
+
* @see https://docs.htmlcsstoimage.com/parameters/google_fonts/
|
|
399
|
+
*/
|
|
400
|
+
google_fonts;
|
|
401
|
+
constructor(init) {
|
|
402
|
+
super();
|
|
403
|
+
Object.assign(this, init);
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
/** Record a public HTTP or HTTPS webpage. */
|
|
407
|
+
export class CreateUrlRecordingRequest extends BaseCreateRecordingRequest {
|
|
408
|
+
__type = 'url';
|
|
409
|
+
/** Public HTTP or HTTPS URL to record.
|
|
410
|
+
* @see https://docs.htmlcsstoimage.com/parameters/url/
|
|
411
|
+
*/
|
|
412
|
+
url;
|
|
413
|
+
/** Attempt to hide cookie and consent banners before recording.
|
|
414
|
+
* @see https://docs.htmlcsstoimage.com/guides/advanced/blocking-cookie-banners/
|
|
415
|
+
*/
|
|
416
|
+
block_consent_banners;
|
|
417
|
+
/** Add X-HCTI-SCREENSHOT: 1 to the top-level navigation.
|
|
418
|
+
* @see https://docs.htmlcsstoimage.com/parameters/identify_as_hcti/
|
|
419
|
+
*/
|
|
420
|
+
identify_as_hcti;
|
|
421
|
+
/** Custom headers for top-level navigations to the URL's origin and additional_header_origins.
|
|
422
|
+
* @see https://docs.htmlcsstoimage.com/parameters/headers/
|
|
423
|
+
*/
|
|
424
|
+
headers;
|
|
425
|
+
/** Additional exact HTTP or HTTPS origins allowed to receive custom headers.
|
|
426
|
+
* @see https://docs.htmlcsstoimage.com/parameters/headers/#additional-header-origins
|
|
427
|
+
*/
|
|
428
|
+
additional_header_origins;
|
|
429
|
+
/** Send custom headers with subrequests to allowed origins. Defaults to false.
|
|
430
|
+
* @see https://docs.htmlcsstoimage.com/parameters/headers/#include-headers-on-subrequests
|
|
431
|
+
*/
|
|
432
|
+
include_headers_on_subrequests;
|
|
433
|
+
constructor(init) {
|
|
434
|
+
super();
|
|
435
|
+
Object.assign(this, init);
|
|
436
|
+
}
|
|
437
|
+
}
|
package/dist/types/response.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { RecordingError, RecordingStatus } from "./recording.js";
|
|
1
2
|
export interface CreateImageSuccessResponse {
|
|
2
3
|
success: true;
|
|
3
4
|
id: string;
|
|
@@ -23,3 +24,32 @@ export interface DeleteImageSuccessResponse {
|
|
|
23
24
|
export type CreateImageBatchResponse = CreateImageBatchSuccessResponse | CreateImageErrorResponse;
|
|
24
25
|
export type CreateImageResponse = CreateImageSuccessResponse | CreateImageErrorResponse;
|
|
25
26
|
export type DeleteImageResponse = DeleteImageSuccessResponse | CreateImageErrorResponse;
|
|
27
|
+
/** Metadata returned when a recording is created or deduplicated. */
|
|
28
|
+
export interface CreateRecordingSuccessResponse {
|
|
29
|
+
success: true;
|
|
30
|
+
id: string;
|
|
31
|
+
/** Authenticated endpoint for fetching the current recording status. */
|
|
32
|
+
status_url: string;
|
|
33
|
+
/** Media URL, including the format extension. Embed or request it directly; it waits until the recording is ready. */
|
|
34
|
+
recording_url: string;
|
|
35
|
+
}
|
|
36
|
+
/** Recording lifecycle information returned by both HTTP 200 and 202. */
|
|
37
|
+
export interface RecordingStatusSuccessResponse {
|
|
38
|
+
success: true;
|
|
39
|
+
id: string;
|
|
40
|
+
recording_url: string;
|
|
41
|
+
status: RecordingStatus;
|
|
42
|
+
/** UTC timestamp as an ISO 8601 string. May change while status remains processing. */
|
|
43
|
+
status_entered_at: string;
|
|
44
|
+
/** Attempts started, including retries. */
|
|
45
|
+
attempt_count: number;
|
|
46
|
+
/** Duration of saved media in milliseconds, or null until measured. */
|
|
47
|
+
stored_duration_ms?: number | null;
|
|
48
|
+
/** When true, media is hosted only at the customer's storage destination. */
|
|
49
|
+
storage_destination_hcti_storage_disabled?: boolean | null;
|
|
50
|
+
/** Most recent attempt error. Check status to distinguish retrying from terminal failure. */
|
|
51
|
+
error?: RecordingError | null;
|
|
52
|
+
}
|
|
53
|
+
export type CreateRecordingResponse = CreateRecordingSuccessResponse | CreateImageErrorResponse;
|
|
54
|
+
export type RecordingStatusResponse = RecordingStatusSuccessResponse | CreateImageErrorResponse;
|
|
55
|
+
export type DeleteRecordingResponse = DeleteImageResponse;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@html-css-to-image/client",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.1",
|
|
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",
|