@clipwright/sdk 0.60.0 → 0.62.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/dist/index.js CHANGED
@@ -1,21 +1,13 @@
1
- import { AD_GUIDE_PATH, adGuide, createFilmDraftInput, checkFilmInput, filmCheck, FILM_DRAFT_CHECK_PATH, FILM_DRAFT_FILES_PATH, FILM_DRAFT_PATH, FILM_DRAFTS_PATH, FILM_GUIDE_PATH, FILM_KIT_PATH, filmGuide, filmKit, filmKitQuery, filmDraft, putFilmFilesInput, FILM_HEROES_PATH, FILM_HEROES_QUOTE_PATH, filmHeroInput, FILM_RENDERS_PATH, FILM_RENDERS_QUOTE_PATH, FILM_RUN_PATH, FILM_STILLS_PATH, FILM_STILLS_QUOTE_PATH, FILM_VOICES_PATH, FILM_VOICES_QUOTE_PATH, filmRenderInput, filmRun, filmStillsInput, filmVoiceInput, ownAgentQuote, account as accountSchema, ACTORS_PATH, actorDefaults, actorDefaultsPath, actorItemPath, actorsResponse, BRAND_EXTRACT_PATH, BRAND_KIT_PATH, BRAND_STYLE_PROPOSE_PATH, BRAND_STYLES_PATH, brandKitWithStyles, brandStyle, brandStyleProposal, proposeBrandStyleInput, saveBrandStyleInput, extractBrandResponse, CREATE_ACTOR_QUOTE_PATH, CREATE_ACTOR_RUN_PATH, createActorQuote, FACELESS_QUOTE_PATH, FACELESS_RUN_PATH, facelessQuoteResponse, GENERATION_MODELS_PATH, GENERATE_IMAGE_QUOTE_PATH, GENERATE_IMAGE_RUN_PATH, GENERATE_VIDEO_QUOTE_PATH, GENERATE_VIDEO_RUN_PATH, generateImageRequest, generateVideoRequest, generationModels, generationQuote, FEEDBACK_PATH, feedbackRequest, feedbackResponse, PRICES_PATH, pricesResponseRead, TEMPLATE_SOUNDS_PATH, templateSoundsList, MOVES_PATH, motionMovesList, REFERENCE_ANALYSES_PATH, REFERENCE_ANALYSIS_PATH, REFERENCE_ANALYSIS_QUOTE_PATH, analysisQuoteResponse, analyzeReferenceRequest, referenceAnalysisRead, referenceAnalysisQuery, runQuery, CREATOR_PROFILES_PATH, CREATOR_PROFILE_PATH, CREATOR_PROFILE_QUOTE_PATH, analyzeCreatorRequest, creatorProfileQuote, creatorProfileRead, creatorProfileQuery, TREND_SEARCHES_PATH, TREND_SEARCH_PATH, TREND_SEARCH_QUOTE_PATH, findTrendsInput, TREND_NICHES_PATH, trendNichesRead, trendSearchQuote, trendSearchRead, trendSearchQuery, makeFacelessInput, agentFailureReport, isRetryableFailure, parseApiFailure, PUBLIC_API_BASE_URL, retryDelayMs, run as runSchema, runRead as runReadSchema, runEditPath, runEditRead, PUBLIC_WORKFLOWS_PATH, PUBLIC_WORKFLOW_PATH, WORKFLOW_PLANS_PATH, WORKFLOW_PLAN_PATH, WORKFLOW_REFERENCE_REMAKE_PATH, WORKFLOW_REVISIONS_PATH, WORKFLOW_APPROVE_PATH, WORKFLOW_QUOTE_PATH, WORKFLOW_RUN_PATH, runShotsPath, runShotsRead, revisionQuoteRead, revisionRequest, runRevisionsPath, runRevisionsQuotePath, candidateQuoteRead, candidateRequest, runCandidatesPath, runCandidatesQuotePath, runCandidatesRead, isTerminal, FAILED_STATE, quoteResponse, RETRY_AFTER_HEADER, UPLOADS_PATH, UPLOAD_IMPORT_PATH, UPLOAD_INTENTS_PATH, UPLOAD_ITEM_PATH, uploadIntentResponse, uploadItemRead, uploadListRead, uploadResponse, ASSET_BYTES_PATH, ASSET_ITEM_PATH, ASSETS_PATH, runMediaPath, assetItemRead, assetListRead, assetRead, voicesResponse, } from "@clipwright/core";
1
+ import { AD_GUIDE_PATH, AD_PATH, ADS_PATH, adRecord, createAdInput, updateAdInput, adGuide, adGuideQuery, createFilmDraftInput, checkFilmInput, filmCheck, FILM_DRAFT_CHECK_PATH, FILM_DRAFT_FILES_PATH, FILM_DRAFT_PATH, FILM_DRAFTS_PATH, FILM_GUIDE_PATH, FILM_KIT_PATH, filmGuide, filmKit, filmKitQuery, filmDraft, putFilmFilesInput, FILM_HEROES_PATH, FILM_HEROES_QUOTE_PATH, filmHeroInput, FILM_EDITS_PATH, FILM_EDITS_QUOTE_PATH, filmEditInput, TAKE_CHECKS_PATH, TAKE_CHECKS_QUOTE_PATH, TAKE_FRAMES_PATH, TAKE_FRAMES_QUOTE_PATH, takeCheckInput, takeFramesInput, FILM_RENDERS_PATH, FILM_RENDERS_QUOTE_PATH, FILM_RUN_PATH, FILM_STILLS_PATH, FILM_STILLS_QUOTE_PATH, FILM_VOICES_PATH, FILM_VOICES_QUOTE_PATH, filmRenderInput, filmRun, filmStillsInput, filmVoiceInput, ownAgentQuote, account as accountSchema, ACTORS_PATH, actorDefaults, actorDefaultsPath, actorItemPath, actorsResponse, BRAND_EXTRACT_PATH, BRAND_KIT_PATH, BRAND_STYLE_PROPOSE_PATH, BRAND_STYLES_PATH, brandKitWithStyles, brandStyle, brandStyleProposal, proposeBrandStyleInput, saveBrandStyleInput, extractBrandResponse, CREATE_ACTOR_QUOTE_PATH, CREATE_ACTOR_RUN_PATH, createActorQuote, FACELESS_QUOTE_PATH, FACELESS_RUN_PATH, facelessQuoteResponse, GENERATION_MODELS_PATH, GENERATE_IMAGE_QUOTE_PATH, GENERATE_IMAGE_RUN_PATH, GENERATE_VIDEO_QUOTE_PATH, GENERATE_VIDEO_RUN_PATH, generateImageRequest, generateVideoRequest, generationModels, generationQuote, FEEDBACK_PATH, feedbackRequest, feedbackResponse, PRICES_PATH, pricesResponseRead, TEMPLATE_SOUNDS_PATH, templateSoundsList, MOVES_PATH, motionMovesList, REFERENCE_ANALYSES_PATH, REFERENCE_ANALYSIS_PATH, REFERENCE_ANALYSIS_QUOTE_PATH, analysisQuoteResponse, analyzeReferenceRequest, referenceAnalysisRead, referenceAnalysisQuery, runQuery, CREATOR_PROFILES_PATH, CREATOR_PROFILE_PATH, CREATOR_PROFILE_QUOTE_PATH, analyzeCreatorRequest, creatorProfileQuote, creatorProfileRead, creatorProfileQuery, TREND_SEARCHES_PATH, TREND_SEARCH_PATH, TREND_SEARCH_QUOTE_PATH, findTrendsInput, TREND_NICHES_PATH, trendNichesRead, trendSearchQuote, trendSearchRead, trendSearchQuery, makeFacelessInput, agentFailureReport, isRetryableFailure, parseApiFailure, PUBLIC_API_BASE_URL, retryDelayMs, run as runSchema, runRead as runReadSchema, runEditPath, runEditRead, PUBLIC_WORKFLOWS_PATH, PUBLIC_WORKFLOW_PATH, WORKFLOW_PLANS_PATH, WORKFLOW_PLAN_PATH, WORKFLOW_REFERENCE_REMAKE_PATH, WORKFLOW_REVISIONS_PATH, WORKFLOW_APPROVE_PATH, WORKFLOW_QUOTE_PATH, WORKFLOW_RUN_PATH, runShotsPath, runShotsRead, revisionQuoteRead, revisionRequest, runRevisionsPath, runRevisionsQuotePath, candidateQuoteRead, candidateRequest, runCandidatesPath, runCandidatesQuotePath, runCandidatesRead, isTerminal, FAILED_STATE, quoteResponse, RETRY_AFTER_HEADER, UPLOADS_PATH, UPLOAD_IMPORT_PATH, UPLOAD_INTENTS_PATH, UPLOAD_ITEM_PATH, uploadIntentResponse, uploadItemRead, uploadListRead, uploadResponse, ASSET_BYTES_PATH, ASSET_ITEM_PATH, ASSETS_PATH, runMediaPath, assetItemRead, assetListRead, assetRead, voicesResponse, } from "@clipwright/core";
2
2
  import { actorIdempotencyKeyFor, candidateIdempotencyKeyFor, facelessIdempotencyKeyFor, generationIdempotencyKeyFor, idempotencyKeyFor, ownAgentIdempotencyKeyFor, revisionIdempotencyKeyFor, uploadRequestIdempotencyKeyFor, assetBytesIdempotencyKeyFor, assetRequestIdempotencyKeyFor, } from "@clipwright/core/idempotency";
3
3
  import { createWorkflowPlan, saveWorkflowPlan, approveWorkflowPlan, launchWorkflow, planReferenceRemakeRequest, workflowCatalogResponseRead, workflowMethodResponseRead, workflowPlanRead, workflowQuoteBindingRead, workflowLaunchResponseRead, workflowRunRead, workflowRunIdentityRead } from '@clipwright/core/workflows';
4
4
  import { resolveClientId } from "./client-id.js";
5
5
  import { tolerant } from "./tolerant.js";
6
- /** Production API by default; shared with core so every surface names one address. */
7
6
  const DEFAULT_BASE_URL = PUBLIC_API_BASE_URL;
8
7
  const workflowPath = (pattern, id) => pattern.replace(':id', encodeURIComponent(id));
9
- /** Default polling deadline: several times the expected render time. */
10
8
  const DEFAULT_MAX_WAIT_MS = 600_000;
11
- /** Default per-request timeout. Node's `fetch` has none, so a silent */
12
- /** accepted connection would hang forever. */
13
9
  const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
14
- /** Max delay of ONE `setTimeout` (2^31−1 ms); a larger value fires after 0 ms. */
15
- /** A platform limit, so it lives here and not in core. */
16
10
  const MAX_TIMER_DELAY_MS = 2_147_483_647;
17
- /** Milliseconds, or a loud rejection: silently defaulting a `NaN` would hide */
18
- /** a misconfiguration. `undefined` means "not set" and takes the fallback. */
19
11
  function positiveMs(value, fallback, name) {
20
12
  if (value === undefined)
21
13
  return fallback;
@@ -24,15 +16,9 @@ function positiveMs(value, fallback, name) {
24
16
  }
25
17
  return value;
26
18
  }
27
- /** An unparseable server response, distinct from rejected input: after */
28
- /** `POST /run` the run may already exist and be charged. */
29
19
  export class ClipwrightResponseError extends Error {
30
- /** Path whose response failed to parse. */
31
20
  path;
32
- /** Whether the request may already have changed state (created a run, spent credits). */
33
21
  mayHaveTakenEffect;
34
- /** `false` means delivery is unconfirmed, not that it failed: HTTP cannot */
35
- /** tell a lost request from a lost response. */
36
22
  deliveryConfirmed;
37
23
  constructor(path, mayHaveTakenEffect, cause, deliveryConfirmed = true) {
38
24
  super(ClipwrightResponseError.#describe(path, mayHaveTakenEffect, deliveryConfirmed), { cause });
@@ -41,11 +27,8 @@ export class ClipwrightResponseError extends Error {
41
27
  this.mayHaveTakenEffect = mayHaveTakenEffect;
42
28
  this.deliveryConfirmed = deliveryConfirmed;
43
29
  }
44
- /** Three messages because the money differs; none blames the server, since a */
45
- /** gateway or CDN may have sent the off-contract response. */
46
30
  static #describe(path, mayHaveTakenEffect, deliveryConfirmed) {
47
31
  if (!mayHaveTakenEffect) {
48
- // About money only: a call on this branch may still have stored something, a draft for one.
49
32
  const free = "No run was created and no credits were spent, and a retry creates no run and spends none.";
50
33
  return deliveryConfirmed
51
34
  ? `The response to ${path} did not match the Clipwright contract. ${free}`
@@ -67,25 +50,17 @@ function parseResponse(schema, body, path, mayHaveTakenEffect) {
67
50
  throw new ClipwrightResponseError(path, mayHaveTakenEffect, cause);
68
51
  }
69
52
  }
70
- /** Attempt number → idempotency key suffix. A different key is a different paid */
71
- /** render, so garbage such as `NaN` is rejected instead of passed through. */
72
53
  function attemptSuffix(attempt) {
73
54
  if (attempt === undefined)
74
55
  return 1;
75
- // `isSafeInteger`: beyond the safe range distinct numbers collapse into one,
76
- // and a requested new render would silently return the old run.
77
56
  if (!Number.isSafeInteger(attempt) || attempt < 1) {
78
57
  throw new TypeError(`attempt must be a positive integer (1, 2, 3, …), got ${String(attempt)}. ` +
79
58
  "It selects which paid run to deduplicate against, so a wrong value can start a second render.");
80
59
  }
81
60
  return attempt;
82
61
  }
83
- /** Sleep of any length as a CHAIN of timers: clamping would send the next */
84
- /** request earlier than the server allowed. */
85
62
  function sleep(ms) {
86
63
  return new Promise((resolve) => {
87
- // A non-number must end the sleep: with `NaN` the loop would schedule
88
- // timers forever and keep the process alive.
89
64
  let left = Number.isFinite(ms) ? Math.max(ms, 0) : 0;
90
65
  const tick = () => {
91
66
  if (left <= 0) {
@@ -99,32 +74,23 @@ function sleep(ms) {
99
74
  tick();
100
75
  });
101
76
  }
102
- /** An API refusal with status, code and server-set pause intact. The shape */
103
- /** comes from core, so SDK, CLI and MCP answer "retry or not" identically. */
104
77
  export class ClipwrightApiError extends Error {
105
- /** Parsed refusal: kind, numbers, pause. Shape comes from core. */
106
78
  failure;
107
79
  status;
108
- /** Refusal code; `http_<status>` for foreign bodies without one. */
109
80
  code;
110
- /** Server-set pause in seconds; `undefined` if the server named none. */
111
81
  retryAfterSeconds;
112
82
  constructor(failure) {
113
83
  super(failure.message);
114
84
  this.name = "ClipwrightApiError";
115
85
  this.failure = failure;
116
86
  this.status = failure.status;
117
- // Code and pause come from the shared report, so CLI and MCP name one
118
- // refusal with the same words.
119
87
  const report = agentFailureReport(failure);
120
88
  this.code = report.code;
121
89
  this.retryAfterSeconds = report.retry_after_seconds;
122
90
  }
123
- /** Whether repeating the same call makes sense. Core decides, not this surface. */
124
91
  get retryable() {
125
92
  return isRetryableFailure(this.failure);
126
93
  }
127
- /** The refusal expanded for an agent: numbers, instruction, retry flag. */
128
94
  report() {
129
95
  return agentFailureReport(this.failure);
130
96
  }
@@ -134,13 +100,10 @@ export class ClipwrightClient {
134
100
  #baseUrl;
135
101
  #pollIntervalMs;
136
102
  #requestTimeoutMs;
137
- /** Resolved lazily on first run start: the MCP server builds the client at */
138
- /** import, and a read-only HOME must not break tools that never need it. */
139
103
  #clientId;
140
104
  constructor(opts) {
141
105
  this.#apiKey = opts.apiKey;
142
106
  if (opts.clientId !== undefined) {
143
- // A blank id would key every caller's runs alike; refused here rather than resolved from disk.
144
107
  if (opts.clientId.trim().length === 0)
145
108
  throw new TypeError("clientId must be a non-empty string");
146
109
  this.#clientId = opts.clientId;
@@ -149,29 +112,17 @@ export class ClipwrightClient {
149
112
  this.#pollIntervalMs = positiveMs(opts.pollIntervalMs, 5_000, "pollIntervalMs");
150
113
  this.#requestTimeoutMs = positiveMs(opts.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS, "requestTimeoutMs");
151
114
  }
152
- /** Lazy resolve and cache of the install identity (see `#clientId`). */
153
115
  #getClientId() {
154
116
  if (this.#clientId === undefined) {
155
117
  this.#clientId = resolveClientId();
156
118
  }
157
119
  return this.#clientId;
158
120
  }
159
- /** One API request. The body is read as text, not `res.json()`: a proxy may */
160
- /** return HTML, and the status must decide before the body is parsed. */
161
- async #request(path,
162
- /** Whether THIS call could change server state; only the caller knows. */
163
- mayHaveTakenEffect, init,
164
- /** A request the server holds on purpose (a waiting read) gets at least this long. */
165
- atLeastMs = 0) {
166
- // Anything failing after send is reported alike: a failed `fetch` does not
167
- // disprove delivery, so a paid path says "unknown".
121
+ async #request(path, mayHaveTakenEffect, init, atLeastMs = 0) {
168
122
  let res;
169
- // Cancellation reaches the network: a per-request timeout plus the caller's
170
- // signal, pulled out of `init` so it cannot bypass the timeout.
171
123
  const { signal: callerSignal, ...rest } = init ?? {};
172
124
  const timeout = AbortSignal.timeout(Math.max(this.#requestTimeoutMs, atLeastMs));
173
125
  const signal = callerSignal ? AbortSignal.any([callerSignal, timeout]) : timeout;
174
- // Every caller passes a body as a string or bytes; the key is read as `fetch` sends it, in any letter case.
175
126
  const credential = typeof this.#apiKey === "string" ? this.#apiKey : this.#apiKey({
176
127
  method: (rest.method ?? "GET").toUpperCase(),
177
128
  path,
@@ -190,25 +141,18 @@ export class ClipwrightClient {
190
141
  });
191
142
  }
192
143
  catch (cause) {
193
- // On free paths the network error stays itself: its own message (DNS,
194
- // refused connection) is more useful than our wrapper.
195
144
  if (!mayHaveTakenEffect)
196
145
  throw cause;
197
146
  throw new ClipwrightResponseError(path, true, cause, false);
198
147
  }
199
- // Headers are read before the body, which may never finish arriving.
200
148
  const retryAfterHeader = res.headers.get(RETRY_AFTER_HEADER);
201
149
  let bodyText;
202
150
  try {
203
151
  bodyText = await res.text();
204
152
  }
205
153
  catch (cause) {
206
- // A broken body read must not erase a known status: a 429 while polling
207
- // stays retryable instead of abandoning a paid run.
208
154
  if (!res.ok) {
209
- throw new ClipwrightApiError(
210
- // `undefined`, not an empty string: the body is unavailable, not empty.
211
- parseApiFailure({ status: res.status, bodyText: undefined, retryAfterHeader }));
155
+ throw new ClipwrightApiError(parseApiFailure({ status: res.status, bodyText: undefined, retryAfterHeader }));
212
156
  }
213
157
  throw new ClipwrightResponseError(path, mayHaveTakenEffect, cause);
214
158
  }
@@ -219,20 +163,15 @@ export class ClipwrightClient {
219
163
  retryAfterHeader,
220
164
  }));
221
165
  }
222
- // 204 means "no body" (actor deletion answers so); parsing the empty string
223
- // would report a contract violation that never happened.
224
166
  if (res.status === 204)
225
167
  return undefined;
226
168
  try {
227
169
  return JSON.parse(bodyText);
228
170
  }
229
171
  catch (cause) {
230
- // Same class as a schema failure: a non-JSON body is also an off-contract
231
- // response and must carry the "may have been charged" warning.
232
172
  throw new ClipwrightResponseError(path, mayHaveTakenEffect, cause);
233
173
  }
234
174
  }
235
- /** Cost estimate; spends no credits. */
236
175
  async quoteUgc(input) {
237
176
  const body = await this.#request("/v1/skills/make_ugc/quote", false, {
238
177
  method: "POST",
@@ -240,15 +179,11 @@ export class ClipwrightClient {
240
179
  });
241
180
  return parseResponse(quoteResponse, body, "/v1/skills/make_ugc/quote", false);
242
181
  }
243
- /** Starts a render and returns the run at once (state=queued). The key is built */
244
- /** here with an always-present `:N` suffix, so MCP and CLI dedupe alike. */
245
182
  async startUgc(input, opts) {
246
183
  return this.#startUgc(input, opts);
247
184
  }
248
- /** `signal` is internal only: the `makeUgc` deadline also aborts the start. */
249
185
  async #startUgc(input, opts, signal) {
250
186
  const key = opts?.idempotencyKey ?? `${idempotencyKeyFor(input, this.#getClientId())}:${attemptSuffix(opts?.attempt)}`;
251
- // `true`: once sent, the run may have been created and charged.
252
187
  const body = await this.#request("/v1/skills/make_ugc/run", true, {
253
188
  method: "POST",
254
189
  body: JSON.stringify(input),
@@ -257,7 +192,6 @@ export class ClipwrightClient {
257
192
  });
258
193
  return parseResponse(runSchema, body, "/v1/skills/make_ugc/run", true);
259
194
  }
260
- /** Uploads an image; returns its reference for later runs. */
261
195
  async uploadImage(bytes, mediaType) {
262
196
  const body = await this.#request(UPLOADS_PATH, true, {
263
197
  method: "POST",
@@ -266,11 +200,9 @@ export class ClipwrightClient {
266
200
  });
267
201
  return parseResponse(uploadResponse, body, UPLOADS_PATH, true);
268
202
  }
269
- /** The account's uploads a revision still takes, newest first, each with a link signed now and its `usable_until`. Free. */
270
203
  async listUploads() {
271
204
  return parseResponse(uploadListRead, await this.#request(UPLOADS_PATH, false), UPLOADS_PATH, false);
272
205
  }
273
- /** The server downloads a public https PNG or JPEG into an upload. Free; a repeat within a day answers the same upload. */
274
206
  async importUpload(url) {
275
207
  const input = { url };
276
208
  const body = await this.#request(UPLOAD_IMPORT_PATH, true, {
@@ -280,7 +212,6 @@ export class ClipwrightClient {
280
212
  });
281
213
  return parseResponse(uploadResponse, body, UPLOAD_IMPORT_PATH, true);
282
214
  }
283
- /** A presigned PUT for a local file of the declared type, size and sha256; the upload is usable once the PUT lands. Free. */
284
215
  async createUpload(input) {
285
216
  const body = await this.#request(UPLOAD_INTENTS_PATH, true, {
286
217
  method: "POST",
@@ -289,17 +220,13 @@ export class ClipwrightClient {
289
220
  });
290
221
  return parseResponse(uploadIntentResponse, body, UPLOAD_INTENTS_PATH, true);
291
222
  }
292
- /** One upload with a fresh link; after `createUpload` it also confirms the PUT. Free. */
293
223
  async getUpload(uploadIdValue) {
294
224
  const path = UPLOAD_ITEM_PATH.replace(":id", encodeURIComponent(uploadIdValue));
295
225
  return parseResponse(uploadItemRead, await this.#request(path, false), path, false);
296
226
  }
297
- /** Deletes an upload: unusable at once, its file erased later. The answer is 204 with no body, a repeat too. Free. */
298
227
  async deleteUpload(uploadIdValue) {
299
228
  await this.#request(UPLOAD_ITEM_PATH.replace(":id", encodeURIComponent(uploadIdValue)), true, { method: "DELETE" });
300
229
  }
301
- /** Saves an asset of the account from a generation, an upload, a url, base64 or a PUT. Free; a repeat within a day answers the */
302
- /** same asset. A clip by url and a PUT answer a pending asset: read it with `getAsset` until its state is ready or failed. */
303
230
  async createAsset(input) {
304
231
  const body = await this.#request(ASSETS_PATH, true, {
305
232
  method: "POST",
@@ -308,8 +235,6 @@ export class ClipwrightClient {
308
235
  });
309
236
  return parseResponse(assetItemRead, body, ASSETS_PATH, true);
310
237
  }
311
- /** Saves a local PNG or JPEG (10 MB) or MP4 (32 MB) as an asset; `rights_confirmed` states you may use the people and works in it, */
312
- /** `analysis_only` keeps it for analyzeReference alone. A clip answers a pending asset that is checked before use. Free. */
313
238
  async createAssetFromBytes(bytes, mediaType, meta) {
314
239
  const analysis = "analysis_only" in meta && meta.analysis_only === true;
315
240
  const query = new URLSearchParams({ role: meta.role, name: meta.name, ...(analysis ? { analysis_only: "true" } : { rights_confirmed: "true" }) })
@@ -319,40 +244,30 @@ export class ClipwrightClient {
319
244
  const body = await this.#request(path, true, { method: "POST", body: bytes, headers: { "Content-Type": mediaType, "Idempotency-Key": key } });
320
245
  return parseResponse(assetItemRead, body, ASSET_BYTES_PATH, true);
321
246
  }
322
- /** The account's live assets, newest first, with its usage of the caps. Free. */
323
247
  async listAssets(query = {}) {
324
248
  const search = new URLSearchParams(Object.entries(query).flatMap(([key, value]) => (value === undefined ? [] : [[key, String(value)]]))).toString();
325
249
  const path = search === "" ? ASSETS_PATH : `${ASSETS_PATH}?${search}`;
326
250
  return parseResponse(assetListRead, await this.#request(path, false), ASSETS_PATH, false);
327
251
  }
328
- /** One asset with a link signed now, or its pending state; after a PUT this read hands the file to processing. Free. */
329
252
  async getAsset(assetIdValue) {
330
253
  const path = ASSET_ITEM_PATH.replace(":id", encodeURIComponent(assetIdValue));
331
254
  return parseResponse(assetItemRead, await this.#request(path, false), path, false);
332
255
  }
333
- /** A new name or role for an asset. Free. */
334
256
  async updateAsset(assetIdValue, patch) {
335
257
  const path = ASSET_ITEM_PATH.replace(":id", encodeURIComponent(assetIdValue));
336
258
  return parseResponse(assetRead, await this.#request(path, true, { method: "POST", body: JSON.stringify(patch) }), path, true);
337
259
  }
338
- /** Deletes an asset; the answer is 204 with no body. Free. */
339
260
  async deleteAsset(assetIdValue) {
340
261
  await this.#request(ASSET_ITEM_PATH.replace(":id", encodeURIComponent(assetIdValue)), true, { method: "DELETE" });
341
262
  }
342
- /** Deletes the files of a finished run; the run and its charge stay. The answer is 204 with no body, a repeat too. Free. */
343
263
  async deleteRunMedia(runIdValue) {
344
264
  await this.#request(runMediaPath(runIdValue), true, { method: "DELETE" });
345
265
  }
346
- /** Curated voice catalog for `voice`/`voice_id`; other voices stay reachable by raw `voice_id`. */
347
266
  async listVoices(filters = {}) {
348
- // Keys pass as is: the server rejects an unknown one (`unknown_field`); the client does not strip it.
349
267
  const query = new URLSearchParams(Object.entries(filters).flatMap(([key, value]) => (value === undefined ? [] : [[key, String(value)]]))).toString();
350
268
  const body = await this.#request(query === "" ? "/v1/voices" : `/v1/voices?${query}`, false);
351
- // Parsed with the server's own schema, so a malformed body fails here and
352
- // not later in the caller.
353
269
  return parseResponse(voicesResponse, body, "/v1/voices", false).voices;
354
270
  }
355
- /** Account state via `GET /v1/account`. Free. */
356
271
  async getAccount() {
357
272
  const body = await this.#request("/v1/account", false);
358
273
  return parseResponse(accountSchema, body, "/v1/account", false);
@@ -370,35 +285,28 @@ export class ClipwrightClient {
370
285
  const body = await this.#request(path, false, { method: "POST", body: JSON.stringify(input) });
371
286
  return parseResponse(actorDefaults, body, path, false);
372
287
  }
373
- /** The account's saved design DNA (#1122), `null` when none is saved, and its saved styles (#1364). */
374
288
  async getBrandKit() {
375
289
  return parseResponse(brandKitWithStyles, await this.#request(BRAND_KIT_PATH, false), BRAND_KIT_PATH, false);
376
290
  }
377
- /** Saves the account's design DNA, or clears it with `null`; spends no credits. The saved script voice stays as it is. */
378
291
  async setBrandKit(design) {
379
292
  return this.saveBrandKit({ design });
380
293
  }
381
- /** Saves each part of the brand kit given: design DNA, script voice or both; `null` clears a part, an omitted one stays. Free. */
382
294
  async saveBrandKit(input) {
383
295
  const body = await this.#request(BRAND_KIT_PATH, false, { method: "POST", body: JSON.stringify(input) });
384
296
  return parseResponse(brandKitWithStyles, body, BRAND_KIT_PATH, false);
385
297
  }
386
- /** A style proposed from a finished analysis of a video you like, for the customer to confirm; spends no credits. */
387
298
  async proposeBrandStyle(input) {
388
299
  const body = await this.#request(BRAND_STYLE_PROPOSE_PATH, false, { method: "POST", body: JSON.stringify(proposeBrandStyleInput.parse(input)) });
389
300
  return parseResponse(brandStyleProposal, body, BRAND_STYLE_PROPOSE_PATH, false);
390
301
  }
391
- /** Saves a confirmed style by name beside the brand kit, replacing one of that name; spends no credits. */
392
302
  async saveBrandStyle(input) {
393
303
  const body = await this.#request(BRAND_STYLES_PATH, false, { method: "POST", body: JSON.stringify(saveBrandStyleInput.parse(input)) });
394
304
  return parseResponse(brandStyle, body, BRAND_STYLES_PATH, false);
395
305
  }
396
- /** A proposed design DNA read from a public site, for the customer to confirm; spends no credits. */
397
306
  async extractBrand(url) {
398
307
  const body = await this.#request(BRAND_EXTRACT_PATH, false, { method: "POST", body: JSON.stringify({ url }) });
399
308
  return parseResponse(extractBrandResponse, body, BRAND_EXTRACT_PATH, false);
400
309
  }
401
- /** `create_actor` estimate; spends no credits. */
402
310
  async quoteActor(input) {
403
311
  const body = await this.#request(CREATE_ACTOR_QUOTE_PATH, false, {
404
312
  method: "POST",
@@ -406,12 +314,9 @@ export class ClipwrightClient {
406
314
  });
407
315
  return parseResponse(createActorQuote, body, CREATE_ACTOR_QUOTE_PATH, false);
408
316
  }
409
- /** Starts `create_actor`; returns the run at once (state=queued), like `startUgc`. */
410
- /** The key uses its own schema: the `make_ugc` one would strip actor fields. */
411
317
  async createActor(input, opts) {
412
318
  const key = opts?.idempotencyKey ??
413
319
  `${actorIdempotencyKeyFor(input, this.#getClientId())}:${attemptSuffix(opts?.attempt)}`;
414
- // `true`: once sent, the run may have been created and charged.
415
320
  const body = await this.#request(CREATE_ACTOR_RUN_PATH, true, {
416
321
  method: "POST",
417
322
  body: JSON.stringify(input),
@@ -419,7 +324,6 @@ export class ClipwrightClient {
419
324
  });
420
325
  return parseResponse(runSchema, body, CREATE_ACTOR_RUN_PATH, true);
421
326
  }
422
- /** `make_faceless` estimate; spends no credits. Mismatched script/brief is refused before sending. */
423
327
  async quoteFaceless(input) {
424
328
  const parsed = makeFacelessInput.parse(input);
425
329
  const body = await this.#request(FACELESS_QUOTE_PATH, false, {
@@ -428,12 +332,10 @@ export class ClipwrightClient {
428
332
  });
429
333
  return parseResponse(facelessQuoteResponse, body, FACELESS_QUOTE_PATH, false);
430
334
  }
431
- /** Starts `make_faceless`; returns the run at once (state=queued), keyed like `createActor`. */
432
335
  async startFaceless(input, opts) {
433
336
  const parsed = makeFacelessInput.parse(input);
434
337
  const key = opts?.idempotencyKey ??
435
338
  `${facelessIdempotencyKeyFor(parsed, this.#getClientId())}:${attemptSuffix(opts?.attempt)}`;
436
- // `true`: once sent, the run may have been created and charged.
437
339
  const body = await this.#request(FACELESS_RUN_PATH, true, {
438
340
  method: "POST",
439
341
  body: JSON.stringify(parsed),
@@ -441,23 +343,18 @@ export class ClipwrightClient {
441
343
  });
442
344
  return parseResponse(runSchema, body, FACELESS_RUN_PATH, true);
443
345
  }
444
- /** What a revision of a run would change and cost; spends no credits. Read tolerantly, as the shots are. */
445
346
  async quoteRevision(runId, request) {
446
347
  const parsed = revisionRequest.parse(request);
447
348
  const path = runRevisionsQuotePath(runId);
448
349
  const body = await this.#request(path, false, { method: "POST", body: JSON.stringify(parsed) });
449
350
  return parseResponse(revisionQuoteRead, body, path, false);
450
351
  }
451
- /** Starts a revision: a new run, returned at once (state=queued). The same request and attempt send the same key, */
452
- /** so a resend returns the first run; `attempt: 2` starts a deliberate second one. */
453
352
  async startRevision(runId, request, opts) {
454
353
  const parsed = revisionRequest.parse(request);
455
354
  const key = opts?.idempotencyKey ??
456
355
  `${revisionIdempotencyKeyFor(runId, parsed, this.#getClientId())}:${attemptSuffix(opts?.attempt)}`;
457
356
  const path = runRevisionsPath(runId);
458
- // `true`: once sent, the run may have been created and its credits held.
459
357
  const body = await this.#request(path, true, { method: "POST", body: JSON.stringify(parsed), headers: { "Idempotency-Key": key } });
460
- // Read as `#getRun` reads: a billing unit of a newer server must not throw after the credits are held.
461
358
  const read = tolerant(runReadSchema).safeParse(body);
462
359
  if (read.success)
463
360
  return read.data;
@@ -465,20 +362,16 @@ export class ClipwrightClient {
465
362
  throw new ClipwrightResponseError(path, true, read.error);
466
363
  return body;
467
364
  }
468
- /** What one shot candidate would cost; spends no credits. Read tolerantly, as a revision quote is. */
469
365
  async quoteCandidate(runId, request) {
470
366
  const parsed = candidateRequest.parse(request);
471
367
  const path = runCandidatesQuotePath(runId);
472
368
  const body = await this.#request(path, false, { method: "POST", body: JSON.stringify(parsed) });
473
369
  return parseResponse(candidateQuoteRead, body, path, false);
474
370
  }
475
- /** Starts a shot candidate: a new run, returned at once (state=queued). The key is the run and the request with */
476
- /** its `take`, so a resend returns the first run; `take: 2` makes a deliberate second candidate. */
477
371
  async createCandidate(runId, request, opts) {
478
372
  const parsed = candidateRequest.parse(request);
479
373
  const key = opts?.idempotencyKey ?? candidateIdempotencyKeyFor(runId, parsed, this.#getClientId());
480
374
  const path = runCandidatesPath(runId);
481
- // `true`: once sent, the run may have been created and its unit held.
482
375
  const body = await this.#request(path, true, { method: "POST", body: JSON.stringify(parsed), headers: { "Idempotency-Key": key } });
483
376
  const read = tolerant(runReadSchema).safeParse(body);
484
377
  if (read.success)
@@ -487,48 +380,36 @@ export class ClipwrightClient {
487
380
  throw new ClipwrightResponseError(path, true, read.error);
488
381
  return body;
489
382
  }
490
- /** The shot candidates of a run's family, oldest first, each with its state, charge and preview. Free. */
491
383
  async listCandidates(runId) {
492
384
  const path = runCandidatesPath(runId);
493
385
  return parseResponse(runCandidatesRead, await this.#request(path, false), path, false);
494
386
  }
495
- /** The generation models with their measured shapes and prices. Free. */
496
387
  async listGenerationModels() {
497
388
  return parseResponse(generationModels, await this.#request(GENERATION_MODELS_PATH, false), GENERATION_MODELS_PATH, false);
498
389
  }
499
- /** The price of every action in credits, a fixed number per unit or a formula. Free, and answered without a key. */
500
390
  async listPrices() {
501
391
  return parseResponse(pricesResponseRead, await this.#request(PRICES_PATH, false), PRICES_PATH, false);
502
392
  }
503
- /** The template sounds a make_ugc run may name per beat, with each beat's default. Free. */
504
393
  async listTemplateSounds() {
505
394
  return parseResponse(templateSoundsList, await this.#request(TEMPLATE_SOUNDS_PATH, false), TEMPLATE_SOUNDS_PATH, false);
506
395
  }
507
- /** The catalogue of moves to put on lines of a script (#1175), filtered and paged; short lines unless detail full or names. Free. */
508
396
  async listMoves(filters = {}) {
509
397
  const query = new URLSearchParams(Object.entries(filters).flatMap(([key, value]) => (value === undefined ? [] : [[key, String(value)]]))).toString();
510
398
  const path = query === "" ? MOVES_PATH : `${MOVES_PATH}?${query}`;
511
399
  return parseResponse(motionMovesList, await this.#request(path, false), MOVES_PATH, false);
512
400
  }
513
- /** What analyzeReference would hold and charge for this asset now: 0 when a live analysis of it would answer. Free. */
514
401
  async quoteAnalysis(request) {
515
402
  const body = await this.#request(REFERENCE_ANALYSIS_QUOTE_PATH, false, { method: "POST", body: JSON.stringify(analyzeReferenceRequest.parse(request)) });
516
403
  return parseResponse(analysisQuoteResponse, body, REFERENCE_ANALYSIS_QUOTE_PATH, false);
517
404
  }
518
- /** Starts reading an MP4 asset into a reference profile, answered at once (state=queued); the same asset answers the */
519
- /** same analysis unless it failed, so a retry needs no key. Paid: the price is held now and charged once it succeeds. */
520
405
  async analyzeReference(request) {
521
406
  const body = await this.#request(REFERENCE_ANALYSES_PATH, true, { method: "POST", body: JSON.stringify(analyzeReferenceRequest.parse(request)) });
522
407
  return parseResponse(referenceAnalysisRead, body, REFERENCE_ANALYSES_PATH, true);
523
408
  }
524
- /** Tells Clipwright what is missing, confusing, wrong or slow; we read every one. Free; the same feedback within 24 h */
525
- /** answers the same feedback_id, so a retry files nothing twice. */
526
409
  async sendFeedback(request) {
527
410
  const body = await this.#request(FEEDBACK_PATH, true, { method: "POST", body: JSON.stringify(feedbackRequest.parse(request)) });
528
411
  return parseResponse(feedbackResponse, body, FEEDBACK_PATH, true);
529
412
  }
530
- /** One reference analysis: queued, analyzing, succeeded with its profile and warnings, or failed with its error. Free. */
531
- /** `frames_from`/`frames_to` page its one-a-second frames; `wait_seconds` (≤ 50) lets the server hold the read until it finishes. */
532
413
  async getReferenceAnalysis(analysisIdValue, query = {}) {
533
414
  const item = REFERENCE_ANALYSIS_PATH.replace(":id", encodeURIComponent(analysisIdValue)), parsed = referenceAnalysisQuery.parse(query);
534
415
  const search = new URLSearchParams(Object.entries(parsed)
@@ -536,18 +417,14 @@ export class ClipwrightClient {
536
417
  const path = search === "" ? item : `${item}?${search}`;
537
418
  return parseResponse(referenceAnalysisRead, await this.#request(path, false, undefined, ((parsed.wait_seconds ?? 0) + 15) * 1000), item, false);
538
419
  }
539
- /** What analyzeCreator would hold and charge for this link now: 0 when a recent profile of the same creator would answer. Free. */
540
420
  async quoteCreatorProfile(request) {
541
421
  const body = await this.#request(CREATOR_PROFILE_QUOTE_PATH, false, { method: "POST", body: JSON.stringify(analyzeCreatorRequest.parse(request)) });
542
422
  return parseResponse(creatorProfileQuote, body, CREATOR_PROFILE_QUOTE_PATH, false);
543
423
  }
544
- /** Starts a creator's profile from a profile or video link, answered at once (state=queued); the same creator within an hour */
545
- /** answers the same profile, so a retry needs no key. Paid: the price is held now and charged once it succeeds. */
546
424
  async analyzeCreator(request) {
547
425
  const body = await this.#request(CREATOR_PROFILES_PATH, true, { method: "POST", body: JSON.stringify(analyzeCreatorRequest.parse(request)) });
548
426
  return parseResponse(creatorProfileRead, body, CREATOR_PROFILES_PATH, true);
549
427
  }
550
- /** One creator profile; `wait_seconds` (≤ 50) lets the server hold the read until it finishes. Free. */
551
428
  async getCreatorProfile(profileIdValue, query = {}) {
552
429
  const item = CREATOR_PROFILE_PATH.replace(":id", encodeURIComponent(profileIdValue)), parsed = creatorProfileQuery.parse(query);
553
430
  const search = new URLSearchParams(Object.entries(parsed)
@@ -555,32 +432,24 @@ export class ClipwrightClient {
555
432
  const path = search === "" ? item : `${item}?${search}`;
556
433
  return parseResponse(creatorProfileRead, await this.#request(path, false, undefined, ((parsed.wait_seconds ?? 0) + 15) * 1000), item, false);
557
434
  }
558
- /** Deletes a finished creator profile; its run and charge stay. The answer is 204 with no body, a repeat too. Free. */
559
435
  async deleteCreatorProfile(profileIdValue) {
560
436
  await this.#request(CREATOR_PROFILE_PATH.replace(":id", encodeURIComponent(profileIdValue)), true, { method: "DELETE" });
561
437
  }
562
- /** What findTrends would hold and charge for this query now: 0 when a search of the same query from the last hour would answer. Free. */
563
- /** Without keywords it prices the primary saved niche. */
564
438
  async quoteTrends(request) {
565
439
  const body = await this.#request(TREND_SEARCH_QUOTE_PATH, false, { method: "POST", body: JSON.stringify(findTrendsInput.parse(request)) });
566
440
  return parseResponse(trendSearchQuote, body, TREND_SEARCH_QUOTE_PATH, false);
567
441
  }
568
- /** Starts a search for reels on a topic, answered at once (state=queued); the same query within an hour answers the same search, so a */
569
- /** retry needs no key. Paid: held now, charged once it succeeds. Without keywords: the primary saved niche, named in the answer. */
570
442
  async findTrends(request) {
571
443
  const body = await this.#request(TREND_SEARCHES_PATH, true, { method: "POST", body: JSON.stringify(findTrendsInput.parse(request)) });
572
444
  return parseResponse(trendSearchRead, body, TREND_SEARCHES_PATH, true);
573
445
  }
574
- /** The account's saved niches, the primary first. Free. */
575
446
  async getTrendNiches() {
576
447
  return parseResponse(trendNichesRead, await this.#request(TREND_NICHES_PATH, false), TREND_NICHES_PATH, false);
577
448
  }
578
- /** Saves the account's niches, at most three, replacing the saved list; [] clears it. Free. */
579
449
  async setTrendNiches(input) {
580
450
  const body = await this.#request(TREND_NICHES_PATH, false, { method: "POST", body: JSON.stringify(input) });
581
451
  return parseResponse(trendNichesRead, body, TREND_NICHES_PATH, false);
582
452
  }
583
- /** One topic search; `wait_seconds` (≤ 50) lets the server hold the read until it finishes. Free. */
584
453
  async getTrendSearch(searchIdValue, query = {}) {
585
454
  const item = TREND_SEARCH_PATH.replace(":id", encodeURIComponent(searchIdValue)), parsed = trendSearchQuery.parse(query);
586
455
  const search = new URLSearchParams(Object.entries(parsed)
@@ -588,77 +457,92 @@ export class ClipwrightClient {
588
457
  const path = search === "" ? item : `${item}?${search}`;
589
458
  return parseResponse(trendSearchRead, await this.#request(path, false, undefined, ((parsed.wait_seconds ?? 0) + 15) * 1000), item, false);
590
459
  }
591
- /** A new film draft for your own agent's scene code, under the account's brand theme frozen now. Free. */
592
460
  async createFilmDraft(request = {}) {
593
461
  const body = await this.#request(FILM_DRAFTS_PATH, true, { method: "POST", body: JSON.stringify(createFilmDraftInput.parse(request)) });
594
462
  return parseResponse(filmDraft, body, FILM_DRAFTS_PATH, true);
595
463
  }
596
- /** One live film draft of the account. Free. */
597
464
  async getFilmDraft(draftIdValue) {
598
465
  const path = FILM_DRAFT_PATH.replace(":id", encodeURIComponent(draftIdValue));
599
466
  return parseResponse(filmDraft, await this.#request(path, false), path, false);
600
467
  }
601
- /** A change to a draft's files, anchors, sounds or captions on the revision you read; a stale revision is refused with 409. Free. */
602
468
  async putFilmFiles(draftIdValue, request) {
603
469
  const path = FILM_DRAFT_FILES_PATH.replace(":id", encodeURIComponent(draftIdValue));
604
470
  const body = await this.#request(path, true, { method: "POST", body: JSON.stringify(putFilmFilesInput.parse(request)) });
605
471
  return parseResponse(filmDraft, body, path, true);
606
472
  }
607
- /** The checks stills and the render run before money, on a draft revision (with unsaved changes laid over it) and a delivered voice: refusals
608
- * as `file:line`, warnings, each anchor's second and the voice's end. Free; a stale revision is refused with 409. */
609
473
  async checkFilm(draftIdValue, request) {
610
474
  const path = FILM_DRAFT_CHECK_PATH.replace(":id", encodeURIComponent(draftIdValue));
611
475
  const body = await this.#request(path, true, { method: "POST", body: JSON.stringify(checkFilmInput.parse(request)) });
612
476
  return parseResponse(filmCheck, body, path, true);
613
477
  }
614
- /** What stills of a draft revision would hold, and how many of them are free; spends no credits. */
615
478
  async quoteStills(request) {
616
479
  return this.#quoteFilm(FILM_STILLS_QUOTE_PATH, filmStillsInput.parse(request));
617
480
  }
618
- /** Stills of a draft revision on a delivered voice, gated first; a draft's first stills in any 24 hours are free, the rest charged per still drawn.
619
- * Returns at once; read it with getFilmRun. */
620
481
  async previewStills(request, opts) {
621
482
  return this.#startFilm("film_stills", FILM_STILLS_PATH, filmStillsInput.parse(request), opts);
622
483
  }
623
- /** What a voice for this text would hold; spends no credits. */
624
484
  async quoteVoice(request) {
625
485
  return this.#quoteFilm(FILM_VOICES_QUOTE_PATH, filmVoiceInput.parse(request));
626
486
  }
627
- /** A voice with word timings, charged per second delivered. Returns at once; read it with getFilmRun. */
628
487
  async makeVoice(request, opts) {
629
488
  return this.#startFilm("film_voice", FILM_VOICES_PATH, filmVoiceInput.parse(request), opts);
630
489
  }
631
- /** What rendering a draft revision on a voice would hold; spends no credits. */
632
490
  async quoteRender(request) {
633
491
  return this.#quoteFilm(FILM_RENDERS_QUOTE_PATH, filmRenderInput.parse(request));
634
492
  }
635
- /** The film rendered from a draft revision on a delivered voice, charged by its length only when delivered. Returns at once. */
636
493
  async renderFilm(request, opts) {
637
494
  return this.#startFilm("film_render", FILM_RENDERS_PATH, filmRenderInput.parse(request), opts);
638
495
  }
639
- /** What making a hero would hold: every pose; spends no credits. */
640
496
  async quoteFilmHero(request) {
641
497
  return this.#quoteFilm(FILM_HEROES_QUOTE_PATH, filmHeroInput.parse(request));
642
498
  }
643
- /** A hero's poses, saved as the account's mascot, charged per pose published. Returns at once; read it with getFilmRun. */
644
499
  async makeFilmHero(request, opts) {
645
500
  return this.#startFilm("film_hero", FILM_HEROES_PATH, filmHeroInput.parse(request), opts);
646
501
  }
647
- /** The explainer guide, its method appendix and the scene kit's file list. Free. */
502
+ async quoteEdit(request) {
503
+ return this.#quoteFilm(FILM_EDITS_QUOTE_PATH, filmEditInput.parse(request));
504
+ }
505
+ async renderEdit(request, opts) {
506
+ return this.#startFilm("film_edit", FILM_EDITS_PATH, filmEditInput.parse(request), opts);
507
+ }
508
+ async quoteTakeFrames(request) {
509
+ return this.#quoteFilm(TAKE_FRAMES_QUOTE_PATH, takeFramesInput.parse(request));
510
+ }
511
+ async takeFrames(request, opts) {
512
+ return this.#startFilm("film_take_frames", TAKE_FRAMES_PATH, takeFramesInput.parse(request), opts);
513
+ }
514
+ async quoteTakeCheck(request) {
515
+ return this.#quoteFilm(TAKE_CHECKS_QUOTE_PATH, takeCheckInput.parse(request));
516
+ }
517
+ async checkTake(request, opts) {
518
+ return this.#startFilm("film_take_check", TAKE_CHECKS_PATH, takeCheckInput.parse(request), opts);
519
+ }
648
520
  async getFilmGuide() {
649
521
  return parseResponse(filmGuide, await this.#request(FILM_GUIDE_PATH, false), FILM_GUIDE_PATH, false);
650
522
  }
651
- /** The ad guide for make_ugc: the word → device catalogue and the rules of an ad. Free. */
652
- async getAdGuide() {
653
- return parseResponse(adGuide, await this.#request(AD_GUIDE_PATH, false), AD_GUIDE_PATH, false);
523
+ async getAdGuide(query = {}) {
524
+ const { section } = adGuideQuery.parse(query);
525
+ const path = section ? `${AD_GUIDE_PATH}?section=${encodeURIComponent(section)}` : AD_GUIDE_PATH;
526
+ return parseResponse(adGuide, await this.#request(path, false), path, false);
527
+ }
528
+ async createAd(request) {
529
+ const body = await this.#request(ADS_PATH, true, { method: "POST", body: JSON.stringify(createAdInput.parse(request)) });
530
+ return parseResponse(adRecord, body, ADS_PATH, true);
531
+ }
532
+ async updateAd(adIdValue, request) {
533
+ const path = AD_PATH.replace(":id", encodeURIComponent(adIdValue));
534
+ const body = await this.#request(path, true, { method: "POST", body: JSON.stringify(updateAdInput.parse(request)) });
535
+ return parseResponse(adRecord, body, path, true);
536
+ }
537
+ async getAd(adIdValue) {
538
+ const path = AD_PATH.replace(":id", encodeURIComponent(adIdValue));
539
+ return parseResponse(adRecord, await this.#request(path, false), path, false);
654
540
  }
655
- /** The scene kit's files with its reference film, or one of them. Free. */
656
541
  async getFilmKit(query = {}) {
657
542
  const { path: file } = filmKitQuery.parse(query);
658
543
  const path = file ? `${FILM_KIT_PATH}?path=${encodeURIComponent(file)}` : FILM_KIT_PATH;
659
544
  return parseResponse(filmKit, await this.#request(path, false), path, false);
660
545
  }
661
- /** One own-agent run of the account and what it delivered. Free. */
662
546
  async getFilmRun(runIdValue) {
663
547
  const path = FILM_RUN_PATH.replace(":id", encodeURIComponent(runIdValue));
664
548
  return parseResponse(filmRun, await this.#request(path, false), path, false);
@@ -668,23 +552,18 @@ export class ClipwrightClient {
668
552
  }
669
553
  async #startFilm(skill, path, request, opts) {
670
554
  const key = opts?.idempotencyKey ?? `${ownAgentIdempotencyKeyFor(skill, request, this.#getClientId())}:${attemptSuffix(opts?.attempt)}`;
671
- // `true`: once sent, the run may have been created and its credits held.
672
555
  const body = await this.#request(path, true, { method: "POST", body: JSON.stringify(request), headers: { "Idempotency-Key": key } });
673
556
  return parseResponse(filmRun, body, path, true);
674
557
  }
675
- /** What one image would cost and its size; spends no credits. */
676
558
  async quoteImage(request) {
677
559
  return this.#quoteGeneration(GENERATE_IMAGE_QUOTE_PATH, generateImageRequest.parse(request));
678
560
  }
679
- /** Starts an image generation, returned at once (state=queued); the same request and attempt return the same run. */
680
561
  async generateImage(request, opts) {
681
562
  return this.#startGeneration("generate_image", GENERATE_IMAGE_RUN_PATH, generateImageRequest.parse(request), opts);
682
563
  }
683
- /** What one clip would cost and its size; spends no credits. */
684
564
  async quoteVideo(request) {
685
565
  return this.#quoteGeneration(GENERATE_VIDEO_QUOTE_PATH, generateVideoRequest.parse(request));
686
566
  }
687
- /** Starts a clip generation, returned at once (state=queued); the same request and attempt return the same run. */
688
567
  async generateVideo(request, opts) {
689
568
  return this.#startGeneration("generate_video", GENERATE_VIDEO_RUN_PATH, generateVideoRequest.parse(request), opts);
690
569
  }
@@ -693,7 +572,6 @@ export class ClipwrightClient {
693
572
  }
694
573
  async #startGeneration(skill, path, request, opts) {
695
574
  const key = opts?.idempotencyKey ?? `${generationIdempotencyKeyFor(skill, request, this.#getClientId())}:${attemptSuffix(opts?.attempt)}`;
696
- // `true`: once sent, the run may have been created and its credits held.
697
575
  const body = await this.#request(path, true, { method: "POST", body: JSON.stringify(request), headers: { "Idempotency-Key": key } });
698
576
  const read = tolerant(runReadSchema).safeParse(body);
699
577
  if (read.success)
@@ -702,12 +580,9 @@ export class ClipwrightClient {
702
580
  throw new ClipwrightResponseError(path, true, read.error);
703
581
  return body;
704
582
  }
705
- /** Deletes a personal actor. The answer is 204 with no body. */
706
583
  async deleteActor(id) {
707
584
  await this.#request(actorItemPath(id), true, { method: "DELETE" });
708
585
  }
709
- /** Reads a run tolerantly, falling back to the raw body for a newer server stage. */
710
- /** `wait_seconds` (≤ 50) lets the server hold the read until the run ends; `signal` cancels it. */
711
586
  async getRun(runId, opts = {}) {
712
587
  const { signal, ...query } = opts;
713
588
  return this.#getRun(runId, signal, runQuery.parse(query).wait_seconds);
@@ -733,7 +608,6 @@ export class ClipwrightClient {
733
608
  const parsed = createWorkflowPlan.parse(input), path = WORKFLOW_PLANS_PATH;
734
609
  return parseResponse(workflowPlanRead, await this.#request(path, false, { method: 'POST', body: JSON.stringify(parsed) }), path, false);
735
610
  }
736
- /** Free: the server compiles a reference profile, or the analysis_id that holds one, and the accepted script into a new plan, or with plan_id and base_version into a draft revision of it; warnings name what it does not reproduce. */
737
611
  async planReferenceRemake(input) {
738
612
  const parsed = planReferenceRemakeRequest.parse(input), path = WORKFLOW_REFERENCE_REMAKE_PATH;
739
613
  return parseResponse(workflowPlanRead, await this.#request(path, false, { method: 'POST', body: JSON.stringify(parsed) }), path, false);
@@ -767,69 +641,48 @@ export class ClipwrightClient {
767
641
  throw new ClipwrightResponseError(path, true, new Error('Workflow receipt must identify the requested purchase'));
768
642
  return result;
769
643
  }
770
- /** The shots of a run, read tolerantly: a kind, action or line of a newer server still parses. Free. */
771
644
  async getRunShots(runId) {
772
645
  const path = runShotsPath(runId);
773
646
  return parseResponse(runShotsRead, await this.#request(path, false), path, false);
774
647
  }
775
- /** The draft of a run's edit, read as tolerantly. Version 0 is a run with nothing stored. Free. */
776
648
  async getRunEdit(runId) {
777
649
  const path = runEditPath(runId);
778
650
  return parseResponse(runEditRead, await this.#request(path, false), path, false);
779
651
  }
780
- /** Saves the draft against the version it was read at; charges nothing. One request, never repeated */
781
- /** here: after a lost answer the same save answers `edit_conflict`, and a read of the draft tells why. */
782
652
  async saveRunEdit(runId, input) {
783
653
  const path = runEditPath(runId);
784
- // `false`: a save creates no run and reserves no credits, which is what that flag warns about.
785
654
  const body = await this.#request(path, false, {
786
655
  method: "POST",
787
656
  body: JSON.stringify({ base_version: input.base_version, document: input.document }),
788
657
  });
789
658
  return parseResponse(runEditRead, body, path, false);
790
659
  }
791
- /** Start plus polling to a terminal state. `maxWaitMs` is one deadline that */
792
- /** aborts both the pause and the request itself. */
793
660
  async makeUgc(input, opts, onProgress) {
794
661
  const maxWaitMs = positiveMs(opts?.maxWaitMs, DEFAULT_MAX_WAIT_MS, "maxWaitMs");
795
662
  const deadline = Date.now() + maxWaitMs;
796
- // The deadline as an abort signal, capped like `sleep`.
797
663
  const callDeadline = AbortSignal.timeout(Math.min(maxWaitMs, MAX_TIMER_DELAY_MS));
798
- // Widened to `RunRead` for the tolerant `getRun`. A start aborted by the
799
- // deadline propagates as is: the run may have been charged.
800
664
  let current = await this.#startUgc(input, { attempt: opts?.attempt }, callDeadline);
801
- // Pause before the NEXT poll; a refused poll replaces it with the server's.
802
665
  let nextDelayMs = this.#pollIntervalMs;
803
- // Kept only to explain a timeout: throttled and merely slow runs differ.
804
666
  let lastRetried;
805
- /** One timeout message for both places the deadline fires. */
806
667
  const timedOut = () => new Error(`makeUgc timed out after ${maxWaitMs}ms; run ${current.run_id} is still ` +
807
668
  `${current.state}. Poll it later with getRun("${current.run_id}").` +
808
669
  (lastRetried === undefined
809
670
  ? ""
810
671
  : ` The last status check was refused with HTTP ${lastRetried.status}: ` +
811
672
  `${lastRetried.message}`));
812
- // Shared `isTerminal`: an unknown server state is polled until `maxWaitMs`
813
- // and ends in a clean timeout with `run_id`, not an endless loop.
814
673
  while (!isTerminal(current.state)) {
815
- // One deadline per call, never reset by a retry; otherwise a chain of 429s
816
- // would extend the wait forever.
817
674
  const remaining = deadline - Date.now();
818
675
  if (remaining <= 0)
819
676
  throw timedOut();
820
677
  await sleep(Math.min(nextDelayMs, remaining));
821
678
  try {
822
- // Preserve makeUgc's legacy result type and its existing permissive native read fallback.
823
679
  current = await this.#getRun(current.run_id, callDeadline);
824
680
  nextDelayMs = this.#pollIntervalMs;
825
681
  onProgress?.(current);
826
682
  }
827
683
  catch (error) {
828
- // A deadline that aborts the poll itself is the same timeout.
829
684
  if (callDeadline.aborted && !(error instanceof ClipwrightApiError))
830
685
  throw timedOut();
831
- // A refused poll is not a failed run: retry only what core calls
832
- // retryable; 402 and other 4xx propagate at once.
833
686
  if (!(error instanceof ClipwrightApiError) || !isRetryableFailure(error.failure)) {
834
687
  throw error;
835
688
  }
@@ -837,8 +690,6 @@ export class ClipwrightClient {
837
690
  nextDelayMs = retryDelayMs(error.failure, this.#pollIntervalMs);
838
691
  }
839
692
  }
840
- // Outcome by core's named constant, not an array index that reordering
841
- // could silently invert.
842
693
  if (current.state === FAILED_STATE) {
843
694
  throw new Error(current.error ?? "run failed");
844
695
  }
@@ -846,4 +697,3 @@ export class ClipwrightClient {
846
697
  }
847
698
  }
848
699
  export { resolveClientId } from "./client-id.js";
849
- //# sourceMappingURL=index.js.map