@bluemoonfoundry/daz-ts 0.0.0-stage → 0.1.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.
Files changed (75) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +377 -2
  3. package/dist/animation.d.ts +129 -0
  4. package/dist/animation.js +276 -0
  5. package/dist/batch.d.ts +118 -0
  6. package/dist/batch.js +186 -0
  7. package/dist/bone.d.ts +50 -0
  8. package/dist/bone.js +66 -0
  9. package/dist/camera.d.ts +61 -0
  10. package/dist/camera.js +120 -0
  11. package/dist/cinematics.d.ts +188 -0
  12. package/dist/cinematics.js +165 -0
  13. package/dist/client.d.ts +399 -0
  14. package/dist/client.js +769 -0
  15. package/dist/dforce.d.ts +15 -0
  16. package/dist/dforce.js +36 -0
  17. package/dist/element.d.ts +51 -0
  18. package/dist/element.js +141 -0
  19. package/dist/exceptions.d.ts +124 -0
  20. package/dist/exceptions.js +173 -0
  21. package/dist/geometry.d.ts +81 -0
  22. package/dist/geometry.js +433 -0
  23. package/dist/index.d.ts +50 -0
  24. package/dist/index.js +36 -0
  25. package/dist/light.d.ts +24 -0
  26. package/dist/light.js +40 -0
  27. package/dist/lighting.d.ts +120 -0
  28. package/dist/lighting.js +107 -0
  29. package/dist/material.d.ts +27 -0
  30. package/dist/material.js +63 -0
  31. package/dist/materials.d.ts +107 -0
  32. package/dist/materials.js +165 -0
  33. package/dist/math3.d.ts +204 -0
  34. package/dist/math3.js +502 -0
  35. package/dist/modifier.d.ts +14 -0
  36. package/dist/modifier.js +24 -0
  37. package/dist/morph.d.ts +11 -0
  38. package/dist/morph.js +24 -0
  39. package/dist/node.d.ts +196 -0
  40. package/dist/node.js +447 -0
  41. package/dist/polling.d.ts +24 -0
  42. package/dist/polling.js +50 -0
  43. package/dist/pose.d.ts +82 -0
  44. package/dist/pose.js +295 -0
  45. package/dist/poses.d.ts +54 -0
  46. package/dist/poses.js +40 -0
  47. package/dist/property.d.ts +64 -0
  48. package/dist/property.js +125 -0
  49. package/dist/render.d.ts +242 -0
  50. package/dist/render.js +811 -0
  51. package/dist/renderApi.d.ts +124 -0
  52. package/dist/renderApi.js +235 -0
  53. package/dist/result.d.ts +15 -0
  54. package/dist/result.js +1 -0
  55. package/dist/scene.d.ts +154 -0
  56. package/dist/scene.js +584 -0
  57. package/dist/sceneEvents.d.ts +63 -0
  58. package/dist/sceneEvents.js +102 -0
  59. package/dist/sceneState.d.ts +167 -0
  60. package/dist/sceneState.js +430 -0
  61. package/dist/scriptBuilder.d.ts +41 -0
  62. package/dist/scriptBuilder.js +72 -0
  63. package/dist/shotGeometry.d.ts +49 -0
  64. package/dist/shotGeometry.js +76 -0
  65. package/dist/skeleton.d.ts +120 -0
  66. package/dist/skeleton.js +561 -0
  67. package/dist/timeline.d.ts +24 -0
  68. package/dist/timeline.js +39 -0
  69. package/dist/undo.d.ts +24 -0
  70. package/dist/undo.js +45 -0
  71. package/dist/version.d.ts +31 -0
  72. package/dist/version.js +36 -0
  73. package/dist/viewport.d.ts +58 -0
  74. package/dist/viewport.js +239 -0
  75. package/package.json +52 -4
@@ -0,0 +1,399 @@
1
+ import type { ExecutionResult } from "./result.js";
2
+ import { type VersionCheck } from "./version.js";
3
+ /** Base name safe to join under a download directory (no separators, no `..`). */
4
+ export declare function safeArtifactFilename(name: string): string;
5
+ /**
6
+ * Parse a Server-Sent-Events HTTP response body into `{event, data}` pairs.
7
+ *
8
+ * Lines starting with `:` are keepalive comments and are skipped. An event
9
+ * block with no explicit `event:` line defaults to `"message"`, matching
10
+ * the SSE specification. Lines may end in LF, CRLF or CR, as the
11
+ * specification allows; DazScriptServer itself sends LF. An unterminated
12
+ * event at the end of the stream is discarded, as the specification requires.
13
+ *
14
+ * Stopping early (`break`, `return`, or a thrown error) cancels the body, so
15
+ * the connection closes instead of staying open until the server ends it.
16
+ */
17
+ export declare function parseSseStream(response: Response): AsyncGenerator<{
18
+ event: string;
19
+ data: string;
20
+ }>;
21
+ /** Options accepted by the {@link DazClient} constructor. */
22
+ export interface DazClientOptions {
23
+ /** Hostname or IP address of the Script Server. Default `"127.0.0.1"`. */
24
+ host?: string;
25
+ /** Listening port of the Script Server. Default `18811`. */
26
+ port?: number;
27
+ /**
28
+ * API token. Pass `""` to disable authentication, or omit/`null` to
29
+ * auto-load from `~/.daz3d/dazscriptserver_token.txt`.
30
+ */
31
+ token?: string | null;
32
+ /** Per-request HTTP timeout in milliseconds. Default `30000`. */
33
+ timeoutMs?: number;
34
+ }
35
+ /** Options accepted by "submit"-style methods that support busy-retry. */
36
+ export interface RetryOptions {
37
+ /**
38
+ * If `true`, transparently retry with backoff when the server reports
39
+ * `StudioBusyError`/`ConcurrencyLimitError`, instead of raising immediately.
40
+ */
41
+ retryOnBusy?: boolean;
42
+ /**
43
+ * Maximum total seconds to retry when `retryOnBusy` is `true`, before
44
+ * re-throwing the busy error.
45
+ */
46
+ maxWait?: number;
47
+ }
48
+ /** Options accepted by {@link DazClient.renderSubmit}. */
49
+ export interface RenderSubmitOptions extends RetryOptions {
50
+ figure?: string;
51
+ morphs?: Record<string, number>;
52
+ figures?: Array<{
53
+ name: string | null;
54
+ morphs?: Record<string, number>;
55
+ }>;
56
+ width?: number;
57
+ height?: number;
58
+ camera?: string;
59
+ engine?: string;
60
+ iraySamples?: number;
61
+ resetMorphs?: boolean;
62
+ }
63
+ /** Options accepted by {@link DazClient.streamRenderProgress} and {@link DazClient.streamSceneEvents}. */
64
+ export interface StreamOptions {
65
+ /**
66
+ * Maximum lifetime of the whole stream in milliseconds, not just time to
67
+ * first byte: when it elapses the connection is aborted and the pending
68
+ * read (including one inside {@link parseSseStream}) rejects with
69
+ * `DazTimeoutError`. Omit for no limit.
70
+ */
71
+ timeoutMs?: number;
72
+ /** Aborts the connection (and any pending read) when signalled. */
73
+ signal?: AbortSignal;
74
+ }
75
+ /** A route listed by `GET /capabilities`. Paths use `{id}` placeholders. */
76
+ export interface CapabilityRoute {
77
+ method: string;
78
+ path: string;
79
+ auth: boolean;
80
+ kind?: "json" | "sse" | "binary";
81
+ /** Companion-plugin routes only: class name of the registering QObject. */
82
+ owner?: string;
83
+ }
84
+ /**
85
+ * Document returned by `GET /capabilities` (schema_version 1). Clients must
86
+ * ignore unknown keys; feature flags and limits may gain entries over time.
87
+ */
88
+ export interface ServerCapabilities {
89
+ schema_version: number;
90
+ /** Changes only when the schema, route table or feature flags change. */
91
+ compatibility_hash: string;
92
+ server: {
93
+ name: string;
94
+ version: string;
95
+ };
96
+ studio: {
97
+ version: string;
98
+ sdk_version: string;
99
+ sdk_major: number;
100
+ qt_version: string;
101
+ qt_build_version: string;
102
+ };
103
+ routes: CapabilityRoute[];
104
+ plugin_routes: CapabilityRoute[];
105
+ features: Record<string, boolean>;
106
+ limits: Record<string, number>;
107
+ rate_limit: {
108
+ enabled: boolean;
109
+ max_requests: number;
110
+ window_seconds: number;
111
+ applies_to: string;
112
+ };
113
+ security: {
114
+ auth_enabled: boolean;
115
+ auth_headers: string[];
116
+ ip_whitelist_enabled: boolean;
117
+ };
118
+ render_engines: {
119
+ registered: {
120
+ class_name: string;
121
+ name: string;
122
+ active: boolean;
123
+ }[];
124
+ /** Values `renderSubmit({ engine })` accepts right now. */
125
+ selectable: string[];
126
+ active_class: string | null;
127
+ /** "snapshot" when the server answered from its cache because Studio was busy. */
128
+ source: "live" | "snapshot";
129
+ read_at: string;
130
+ };
131
+ }
132
+ /**
133
+ * An output a job declared, as listed by `GET /artifacts/{id}`. The same
134
+ * fields minus the file metadata appear in the job's
135
+ * `observation.output_manifest.outputs`.
136
+ */
137
+ export interface Artifact {
138
+ /** Stable ID (position in the manifest). */
139
+ artifact_id: string;
140
+ /** Download path, `/artifacts/{requestId}/{artifact_id}`. */
141
+ url: string;
142
+ /** Host filesystem path as declared by the job. */
143
+ path: string;
144
+ /** Declared kind; render jobs use `"render"` and `"frame"`. */
145
+ kind?: string;
146
+ label?: string;
147
+ metadata?: Record<string, unknown>;
148
+ /** The declared path is an absolute, existing regular file. */
149
+ available: boolean;
150
+ /** Size in bytes, or `null` when unavailable. */
151
+ size: number | null;
152
+ content_type: string;
153
+ filename: string;
154
+ }
155
+ /** Response of `GET /artifacts/{id}`. */
156
+ export interface ArtifactList {
157
+ success: boolean;
158
+ request_id: string;
159
+ status: string;
160
+ count: number;
161
+ artifacts: Artifact[];
162
+ }
163
+ /**
164
+ * Status of an async request (`openapi.yaml` `RequestStatus`).
165
+ *
166
+ * Final: `completed`, `failed`, `cancelled`, `completed_after_cancel_request`,
167
+ * `completed_after_stale`. Not final: `cancel_requested` (cancel asked while
168
+ * the script was running; scripts can't be interrupted) and `stale` (running
169
+ * past the Stuck Job Timeout; reported with `success: false` and ends
170
+ * long-polls, but changes to the real outcome if the script returns).
171
+ * `cancelled` means the work really stopped: it never started, or a render
172
+ * was aborted.
173
+ */
174
+ export type RequestStatus = "queued" | "running" | "cancel_requested" | "stale" | "completed" | "failed" | "cancelled" | "completed_after_cancel_request" | "completed_after_stale";
175
+ /** The final {@link RequestStatus} values; a request in one of these never changes again. */
176
+ export declare const FINAL_REQUEST_STATUSES: ReadonlySet<RequestStatus>;
177
+ /** Body of `DELETE /requests/{id}` and `POST /render/{id}/cancel`. */
178
+ export interface CancelResponse {
179
+ request_id: string;
180
+ /** `cancelled` only when the request was still queued; otherwise its current status. Poll it for the real outcome. */
181
+ status: "cancelled" | "cancel_requested" | "stale";
182
+ message: string;
183
+ cancel_requested_at: string;
184
+ /** Present only when `status` is `cancelled`. */
185
+ cancelled_at?: string;
186
+ }
187
+ /** Options accepted by {@link DazClient.downloadArtifact}. */
188
+ export interface DownloadArtifactOptions {
189
+ /** Inclusive byte range `[start, end]`; omit `end` for "to the end of the file". */
190
+ range?: [number, number?];
191
+ }
192
+ /**
193
+ * HTTP client for the DAZ Studio Script Server.
194
+ *
195
+ * Handles authentication, request serialization, and response mapping for
196
+ * all server endpoints. The token is loaded automatically from
197
+ * `~/.daz3d/dazscriptserver_token.txt` when `token` is omitted.
198
+ *
199
+ * Unlike dazpy (which needs separate `DazClient`/`AsyncDazClient` classes
200
+ * for Python's sync/async split), a single `DazClient` covers both cases
201
+ * via `async`/`await`.
202
+ */
203
+ export declare class DazClient {
204
+ private readonly baseUrl;
205
+ private readonly token;
206
+ private readonly timeoutMs;
207
+ constructor(options?: DazClientOptions);
208
+ private get headers();
209
+ /**
210
+ * `fetch` with `timeoutMs` (default: the client's) bounding the whole
211
+ * exchange, body included: the body is read into memory before the timer is
212
+ * cleared, so callers' `resp.json()`/`resp.text()` can't hang afterwards.
213
+ * Pass `stream: true` to get the live body back instead (only
214
+ * time-to-headers is bounded then), for downloads that shouldn't be buffered.
215
+ */
216
+ private fetchWithTimeout;
217
+ private post;
218
+ private get;
219
+ private delete_;
220
+ private withBusyRetry;
221
+ /**
222
+ * Execute a DazScript string synchronously.
223
+ *
224
+ * @param script - DazScript source code to execute.
225
+ * @param args - Optional value passed into the script as `getArguments()[0]`. Must be JSON-serializable.
226
+ */
227
+ execute(script: string, args?: unknown, opts?: RetryOptions): Promise<ExecutionResult>;
228
+ /**
229
+ * Execute a `.dsa` script file that resides on the DAZ Studio host.
230
+ *
231
+ * @param scriptFile - Absolute path to the `.dsa` file on the server host.
232
+ * @param args - Optional argument passed to the script.
233
+ */
234
+ executeFile(scriptFile: string, args?: unknown, opts?: RetryOptions): Promise<ExecutionResult>;
235
+ /**
236
+ * Submit a script for asynchronous execution and return immediately.
237
+ *
238
+ * @returns The server-assigned `requestId`. Use it with {@link getRequestStatus}
239
+ * or {@link getRequestResult} to poll for the outcome.
240
+ */
241
+ executeAsyncSubmit(script: string, args?: unknown, opts?: RetryOptions): Promise<string>;
242
+ /**
243
+ * Submit a host-side `.dsa` file for asynchronous execution.
244
+ *
245
+ * The file is loaded by DAZ Studio when the queued job starts, preserving
246
+ * its filename for `getScriptFileName()` and relative `include()` calls.
247
+ */
248
+ executeFileAsyncSubmit(scriptFile: string, args?: unknown, opts?: RetryOptions): Promise<string>;
249
+ /**
250
+ * Submit multiple operations as one async request (one queue slot, one script).
251
+ *
252
+ * @param operations - `{bodyLines, resultExpression}` pairs — same shape as {@link Batch.addOperation}'s arguments.
253
+ * @returns The server-assigned `requestId`. Poll it like any other async
254
+ * request; the result's `result` field is a dict keyed `"_r0"`, `"_r1"`, ... in submission order.
255
+ */
256
+ executeBatchAsync(operations: Array<{
257
+ bodyLines: string[];
258
+ resultExpression: string;
259
+ }>, args?: unknown): Promise<string>;
260
+ /**
261
+ * Return the current status of an async request.
262
+ *
263
+ * @returns A dict with at least a `status` key: a {@link RequestStatus}, or
264
+ * `"not_found"`. `cancel_requested` and `stale` are not final: a running
265
+ * script can't be interrupted, so once it returns the status changes to its
266
+ * real outcome.
267
+ */
268
+ getRequestStatus(requestId: string): Promise<Record<string, unknown>>;
269
+ /**
270
+ * Fetch the result of a completed async request.
271
+ *
272
+ * @param wait - If `true`, the server long-polls until the request completes or `waitTimeout` is reached.
273
+ * @param waitTimeout - Maximum seconds the server should wait (only relevant when `wait` is `true`).
274
+ */
275
+ getRequestResult(requestId: string, wait?: boolean, waitTimeout?: number): Promise<Record<string, unknown>>;
276
+ /**
277
+ * List all tracked async requests (script and render) with their status.
278
+ *
279
+ * @param status - Optional filter: any {@link RequestStatus} (e.g. `"running"`, `"cancel_requested"`).
280
+ */
281
+ listRequests(status?: RequestStatus): Promise<Record<string, unknown>>;
282
+ /**
283
+ * Cancel a script or render request and return the server's response.
284
+ *
285
+ * Render requests (`rnd-` IDs) go to `POST /render/{id}/cancel`; others to
286
+ * `DELETE /requests/{id}`. A queued request comes back `cancelled`; a
287
+ * running one comes back `cancel_requested` (or `stale`), so poll it for
288
+ * the real outcome.
289
+ *
290
+ * @throws {DazError} If the server rejects the cancel (e.g. unknown request).
291
+ */
292
+ cancelRequestDetail(requestId: string): Promise<CancelResponse>;
293
+ /**
294
+ * Cancel a queued or running async request.
295
+ *
296
+ * @returns `true` if the server accepted the cancel, `false` otherwise. A
297
+ * queued request is cancelled at once; a running one only becomes
298
+ * `cancel_requested` (scripts can't be interrupted), so poll the request
299
+ * for its real outcome.
300
+ */
301
+ cancelRequest(requestId: string): Promise<boolean>;
302
+ /** Submit a render job and return immediately. */
303
+ renderSubmit(outputPath: string, opts?: RenderSubmitOptions): Promise<Record<string, unknown>>;
304
+ /** Submit a batch render job (multiple variants sharing optional defaults) and return immediately. */
305
+ renderBatchSubmit(variants: Array<Record<string, unknown>>, base?: Record<string, unknown>, opts?: RetryOptions): Promise<Record<string, unknown>>;
306
+ /** Submit an animation render job spanning a frame range and return immediately. */
307
+ renderAnimationSubmit(outputPath: string, startFrame: number, endFrame: number, opts?: RetryOptions & {
308
+ framePadding?: number;
309
+ width?: number;
310
+ height?: number;
311
+ camera?: string;
312
+ engine?: string;
313
+ }): Promise<Record<string, unknown>>;
314
+ /** Cancel a queued or running render job. */
315
+ cancelRender(requestId: string): Promise<boolean>;
316
+ /**
317
+ * Open an SSE stream. The timeout and the caller's signal stay attached to
318
+ * the returned body, so they bound reading the stream, not just connecting.
319
+ */
320
+ private openStream;
321
+ /**
322
+ * Open the SSE progress stream for a render request.
323
+ *
324
+ * @returns The raw streaming `Response` on success, or `null` if the server
325
+ * answers with any other non-auth status (e.g. 404: no such render, or a
326
+ * server without the endpoint), so callers can fall back to polling. Pass
327
+ * the result to {@link parseSseStream} to consume it, and let the body
328
+ * drain or cancel the reader.
329
+ * @throws {AuthenticationError} On HTTP 401/403.
330
+ * @throws {ConnectionError} If the server can't be reached.
331
+ * @throws {DazTimeoutError} If `opts.timeoutMs` elapses (also from reads of the body).
332
+ */
333
+ streamRenderProgress(requestId: string, opts?: StreamOptions): Promise<Response | null>;
334
+ /**
335
+ * Open the SSE stream for general scene-change events (`GET /scene/events`).
336
+ *
337
+ * @param categories - Optional subset of event categories to subscribe to
338
+ * (`"node"`, `"skeleton"`, `"light"`, `"camera"`, `"selection"`, `"scene"`,
339
+ * `"time"`, `"render"`). Omit to subscribe to all categories.
340
+ * @param opts - Stream lifetime / abort signal. With no `timeoutMs` the
341
+ * stream stays open until the caller stops reading — the server sends a
342
+ * keepalive comment every 15 seconds.
343
+ * @returns The raw streaming `Response`, or `null` on a non-auth, non-200 status.
344
+ * @throws {AuthenticationError} On HTTP 401/403.
345
+ * @throws {ConnectionError} If the server can't be reached.
346
+ * @throws {DazTimeoutError} If `opts.timeoutMs` elapses (also from reads of the body).
347
+ */
348
+ streamSceneEvents(categories?: string[], opts?: StreamOptions): Promise<Response | null>;
349
+ /** Return the server status dict from `GET /status`. */
350
+ status(): Promise<Record<string, unknown>>;
351
+ /**
352
+ * Check the plugin's version (from `GET /status`) against
353
+ * {@link MIN_SERVER_VERSION}. daz-ts never runs this on its own, so call it
354
+ * once after connecting if you want to warn users about an old plugin.
355
+ * Throws only what {@link status} throws: an incompatible plugin comes back
356
+ * as `compatible: false` with upgrade advice in `message`.
357
+ */
358
+ checkServerVersion(): Promise<VersionCheck>;
359
+ /** Return the health check dict from `GET /health`. */
360
+ health(): Promise<Record<string, unknown>>;
361
+ /** Return the metrics dict from `GET /metrics`. */
362
+ metrics(): Promise<Record<string, unknown>>;
363
+ /**
364
+ * Return the server's capabilities document from `GET /capabilities`:
365
+ * versions, routes, feature flags, current limits and the render engines
366
+ * registered right now. Servers that predate the endpoint answer 404, which
367
+ * throws a `DazError`; 401/403 throw `AuthenticationError`, and 503 before
368
+ * the server has a snapshot throws `StudioBusyError`.
369
+ */
370
+ /**
371
+ * List the files an async job declared (`GET /artifacts/{id}`): outputs
372
+ * from its `reportFile` plus the image(s) a render job wrote, each with
373
+ * size, content type and availability. Use with {@link downloadArtifact}
374
+ * when the client can't see DAZ Studio's filesystem.
375
+ */
376
+ listArtifacts(requestId: string): Promise<ArtifactList>;
377
+ /**
378
+ * Download one declared artifact (`GET /artifacts/{id}/{artifact_id}`).
379
+ * Returns the bytes, or, when `dest` is given, streams them into that file
380
+ * and returns its path. `range` sends an HTTP `Range` header (206 reply).
381
+ * Rejections throw {@link ArtifactError}; 401/403 throw `AuthenticationError`.
382
+ */
383
+ downloadArtifact(requestId: string, artifactId: string | number, opts?: DownloadArtifactOptions): Promise<Buffer>;
384
+ downloadArtifact(requestId: string, artifactId: string | number, dest: string, opts?: DownloadArtifactOptions): Promise<string>;
385
+ /**
386
+ * Download every available artifact of a job into `destDir`, named
387
+ * `<artifact_id>_<filename>` so equal base names can't collide. Returns the
388
+ * written paths in manifest order.
389
+ */
390
+ downloadArtifacts(requestId: string, destDir: string): Promise<string[]>;
391
+ capabilities(): Promise<ServerCapabilities>;
392
+ /**
393
+ * Save a copy of the scene to `path` without changing the scene's current
394
+ * file or dirty state (like "Save a Copy As..."). See dazpy's
395
+ * `DazScene.save_copy` for the copy-vs-serialize tradeoff this makes
396
+ * server-side.
397
+ */
398
+ sceneSaveCopy(path: string): Promise<Record<string, unknown>>;
399
+ }