@nodaro/sdk 2.29.0 → 2.31.0

package/dist/chunk-LKH5M44B.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resources/workspaces.ts"],"names":[],"mappings":"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","file":"chunk-LKH5M44B.cjs","sourcesContent":["import type {\n  JoinCodeView,\n  MemberStatus,\n  OrgPage,\n  UsageLogEntry,\n  UsageQuery,\n  UsageReport,\n  WorkspaceMemberView,\n  WorkspaceRole,\n  WorkspaceSettings,\n  WorkspaceSummary,\n  WorkspaceView,\n} from \"@nodaro/shared/organizations\"\nimport type { NodaroClientCore } from \"../core.js\"\n\n/**\n * Workspaces — the inner tenancy axis, where work actually lives.\n *\n * Selecting a workspace and belonging to one are different things, and this\n * resource is only about the second. Use {@link NodaroClient.withWorkspace}\n * to decide which workspace a REQUEST acts in; these methods read and change\n * the workspaces themselves.\n */\n\nexport interface CreateWorkspaceInput {\n  name: string\n  slug?: string\n  description?: string\n  settings?: WorkspaceSettings\n}\n\nexport class WorkspacesResource {\n  constructor(private client: NodaroClientCore) {}\n\n  /**\n   * Every workspace this account belongs to, across all its organizations.\n   *\n   * An identity read: a stale workspace binding cannot lock a caller out of\n   * it, which is what makes it safe to call when a selection has gone bad.\n   *\n   * Byte-for-byte the list `GET /v1/me` carries, so a client reconciles\n   * against one truth rather than two. That is why these are SUMMARIES —\n   * enough to render a switcher, not the full view; use {@link get} for that.\n   */\n  list(): Promise<{ data: WorkspaceSummary[]; lastWorkspaceId: string | null }> {\n    return this.client.request(\"GET\", \"/v1/workspaces\")\n  }\n\n  listForOrg(orgId: string, opts: { includeArchived?: boolean } = {}): Promise<{ data: WorkspaceView[] }> {\n    return this.client.request(\"GET\", `/v1/orgs/${encodeURIComponent(orgId)}/workspaces`, {\n      query: { includeArchived: opts.includeArchived },\n    })\n  }\n\n  get(id: string): Promise<{ data: WorkspaceView }> {\n    return this.client.request(\"GET\", `/v1/workspaces/${encodeURIComponent(id)}`)\n  }\n\n  create(orgId: string, input: CreateWorkspaceInput): Promise<{ data: WorkspaceView }> {\n    return this.client.request(\"POST\", `/v1/orgs/${encodeURIComponent(orgId)}/workspaces`, { body: input })\n  }\n\n  update(\n    id: string,\n    input: { name?: string; description?: string | null; settings?: WorkspaceSettings },\n  ): Promise<{ data: WorkspaceView }> {\n    return this.client.request(\"PATCH\", `/v1/workspaces/${encodeURIComponent(id)}`, { body: input })\n  }\n\n  /**\n   * Archive or restore. Archiving is REVERSIBLE and destroys nothing: the\n   * workspace stops accepting new work and stays fully readable, which is\n   * what a finished class term needs and a delete would not survive.\n   */\n  setArchived(id: string, archived: boolean): Promise<{ data: WorkspaceView }> {\n    return this.client.request(\n      \"POST\",\n      `/v1/workspaces/${encodeURIComponent(id)}/${archived ? \"archive\" : \"unarchive\"}`,\n    )\n  }\n\n  // -- members --------------------------------------------------------------\n\n  listMembers(id: string, opts: { cursor?: string; limit?: number } = {}): Promise<OrgPage<WorkspaceMemberView>> {\n    return this.client.request(\"GET\", `/v1/workspaces/${encodeURIComponent(id)}/members`, {\n      query: { ...opts },\n    })\n  }\n\n  /** Add someone who is ALREADY in the organization. To bring in a new person, invite them. */\n  addMember(id: string, input: { userId: string; role: WorkspaceRole }): Promise<{ data: WorkspaceMemberView }> {\n    return this.client.request(\"POST\", `/v1/workspaces/${encodeURIComponent(id)}/members`, { body: input })\n  }\n\n  updateMember(\n    id: string,\n    userId: string,\n    input: { role?: WorkspaceRole; status?: MemberStatus; creditCap?: number | null },\n  ): Promise<{ data: WorkspaceMemberView }> {\n    return this.client.request(\n      \"PATCH\",\n      `/v1/workspaces/${encodeURIComponent(id)}/members/${encodeURIComponent(userId)}`,\n      { body: input },\n    )\n  }\n\n  removeMember(id: string, userId: string): Promise<{ data: { removed: boolean } }> {\n    return this.client.request(\n      \"DELETE\",\n      `/v1/workspaces/${encodeURIComponent(id)}/members/${encodeURIComponent(userId)}`,\n    )\n  }\n\n  // -- join codes -----------------------------------------------------------\n\n  /** The workspace's join code, or `null` if none has been created. Admins only. */\n  getJoinCode(id: string): Promise<{ data: JoinCodeView | null }> {\n    return this.client.request(\"GET\", `/v1/workspaces/${encodeURIComponent(id)}/join-code`)\n  }\n\n  /**\n   * Rotate, enable or disable the code. Rotating invalidates the old one\n   * immediately — that is the point of it, and anyone still holding a link\n   * with the old code will be refused.\n   */\n  actOnJoinCode(id: string, action: \"rotate\" | \"enable\" | \"disable\"): Promise<{ data: JoinCodeView }> {\n    return this.client.request(\"POST\", `/v1/workspaces/${encodeURIComponent(id)}/join-code`, {\n      body: { action },\n    })\n  }\n\n  /**\n   * Join by code. Another way IN, so a stale workspace binding must not block\n   * it — the server treats this as an identity route for that reason.\n   */\n  join(code: string): Promise<{ data: { orgId: string; workspaceId: string } }> {\n    return this.client.request(\"POST\", \"/v1/workspaces/join\", { body: { code } })\n  }\n\n  // -- usage ----------------------------------------------------------------\n\n  /**\n   * Credits by member, model or day for this workspace. A plain member sees\n   * their OWN runs (the report is self-narrowed and `groupBy: \"member\"` is\n   * refused); a workspace admin sees everyone and may filter `userId`.\n   * Inclusive dates, IANA `tz` (default UTC), ≤ 366 days (default last 30).\n   */\n  usage(\n    id: string,\n    opts: Omit<UsageQuery, \"cursor\" | \"limit\" | \"workspaceId\" | \"groupBy\"> & { groupBy?: \"member\" | \"model\" | \"day\" } = {},\n  ): Promise<{ data: UsageReport }> {\n    return this.client.request(\"GET\", `/v1/workspaces/${encodeURIComponent(id)}/usage`, { query: { ...opts } })\n  }\n\n  /** The individual runs behind a report, newest first, cursor-paged. */\n  usageRows(id: string, opts: Omit<UsageQuery, \"groupBy\" | \"workspaceId\"> = {}): Promise<OrgPage<UsageLogEntry>> {\n    return this.client.request(\"GET\", `/v1/workspaces/${encodeURIComponent(id)}/usage`, { query: { ...opts, groupBy: \"none\" } })\n  }\n\n  /** The same report (or the rows, with `groupBy: \"none\"`) as CSV text. */\n  usageCsv(id: string, opts: Omit<UsageQuery, \"cursor\" | \"limit\" | \"workspaceId\"> = {}): Promise<string> {\n    return this.client.requestText(\"GET\", `/v1/workspaces/${encodeURIComponent(id)}/usage`, { query: { ...opts, format: \"csv\" } })\n  }\n}\n"]}

package/dist/chunk-LLNNHLCE.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=chunk-LLNNHLCE.cjs.map
+//# sourceMappingURL=chunk-LLNNHLCE.cjs.map

package/dist/chunk-LLNNHLCE.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-LLNNHLCE.cjs"}

package/dist/chunk-LWZLWSXD.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=chunk-LWZLWSXD.cjs.map
+//# sourceMappingURL=chunk-LWZLWSXD.cjs.map

package/dist/chunk-LWZLWSXD.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-LWZLWSXD.cjs"}

package/dist/chunk-M6Y5TOYE.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-M6Y5TOYE.js.map
+//# sourceMappingURL=chunk-M6Y5TOYE.js.map

package/dist/chunk-M6Y5TOYE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-M6Y5TOYE.js"}

package/dist/chunk-MBFUMWI5.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+// src/resources/shots.ts
+var ShotsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Create a shot record. Returns the new shot's id — an unguessable
+   *  capability string that doubles as the share-link path segment. */
+  create(input = {}) {
+    return this.client.request("POST", "/v1/shots", { body: input });
+  }
+  /** Read a shot. Public shots are readable by anyone holding the id;
+   *  private shots resolve only for their owner (404 otherwise). */
+  get(id) {
+    return this.client.request("GET", `/v1/shots/${encodeURIComponent(id)}`);
+  }
+  /** Update an owned shot (any subset of fields, e.g. a visibility toggle). */
+  update(id, input) {
+    return this.client.request("PATCH", `/v1/shots/${encodeURIComponent(id)}`, { body: input });
+  }
+  /** Delete an owned shot. */
+  async delete(id) {
+    await this.client.request("DELETE", `/v1/shots/${encodeURIComponent(id)}`);
+  }
+};
+
+exports.ShotsResource = ShotsResource;
+//# sourceMappingURL=chunk-MBFUMWI5.cjs.map
+//# sourceMappingURL=chunk-MBFUMWI5.cjs.map

package/dist/chunk-MBFUMWI5.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resources/shots.ts"],"names":[],"mappings":";;;AA4DO,IAAM,gBAAN,MAAoB;AAAA,EACzB,YAAoB,MAAA,EAA0B;AAA1B,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAA2B;AAAA,EAA3B,MAAA;AAAA;AAAA;AAAA,EAIpB,MAAA,CAAO,KAAA,GAAyB,EAAC,EAA4B;AAC3D,IAAA,OAAO,IAAA,CAAK,OAAO,OAAA,CAAQ,MAAA,EAAQ,aAAa,EAAE,IAAA,EAAM,OAAO,CAAA;AAAA,EACjE;AAAA;AAAA;AAAA,EAIA,IAAI,EAAA,EAAqC;AACvC,IAAA,OAAO,IAAA,CAAK,OAAO,OAAA,CAAQ,KAAA,EAAO,aAAa,kBAAA,CAAmB,EAAE,CAAC,CAAA,CAAE,CAAA;AAAA,EACzE;AAAA;AAAA,EAGA,MAAA,CAAO,IAAY,KAAA,EAAiD;AAClE,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,OAAA,CAAQ,OAAA,EAAS,CAAA,UAAA,EAAa,kBAAA,CAAmB,EAAE,CAAC,CAAA,CAAA,EAAI,EAAE,IAAA,EAAM,KAAA,EAAO,CAAA;AAAA,EAC5F;AAAA;AAAA,EAGA,MAAM,OAAO,EAAA,EAA2B;AACtC,IAAA,MAAM,IAAA,CAAK,OAAO,OAAA,CAAQ,QAAA,EAAU,aAAa,kBAAA,CAAmB,EAAE,CAAC,CAAA,CAAE,CAAA;AAAA,EAC3E;AACF","file":"chunk-MBFUMWI5.cjs","sourcesContent":["import type { NodaroClientCore } from \"../core.js\"\n\n/**\n * Cine shots — the Share → Remix record behind `/s/:id` share links.\n * Mirrors the backend's `/v1/shots` wire contract (`shots.ts::toWire`);\n * types are declared here so the SDK stays dependency-free — same\n * convention as `ModelSummary` / `PickerCatalog`.\n */\n\n/** An `@`-mention entity reference captured in the shot's prompt state. */\nexport interface ShotEntityRef {\n  entitySlug: string\n  variantSlug?: string\n  role?: string\n  kind?: \"character\" | \"location\" | \"object\" | \"creature\"\n}\n\nexport type ShotMode = \"single\" | \"multi-shot\" | \"frame-to-motion\" | \"storyboard\"\n\nexport interface Shot {\n  id: string\n  mode: ShotMode\n  /** Opaque picker/builder selection state — round-tripped verbatim. */\n  selectionState: Record<string, unknown>\n  freeText?: string\n  negativePrompt?: string\n  assembledPrompt?: string\n  perModelPrompts?: Record<string, string>\n  models?: string[]\n  entityRefs?: ShotEntityRef[]\n  resultUrls?: string[]\n  visibility: \"private\" | \"public\"\n  schemaVersion: number\n  ownerId: string\n  createdAt: string\n  updatedAt: string\n}\n\nexport interface CreateShotInput {\n  mode?: ShotMode\n  selectionState?: Record<string, unknown>\n  freeText?: string\n  negativePrompt?: string\n  assembledPrompt?: string\n  perModelPrompts?: Record<string, string>\n  /** Video model ids the shot targets (max 16). */\n  models?: string[]\n  entityRefs?: ShotEntityRef[]\n  /**\n   * Result media URLs (max 32). Must be plain public http(s) URLs — the\n   * backend rejects signed URLs so a token can never leak into a share\n   * record.\n   */\n  resultUrls?: string[]\n  /** Rows default to private; sharing is an explicit \"make public\" action. */\n  visibility?: \"private\" | \"public\"\n}\n\nexport type UpdateShotInput = CreateShotInput\n\nexport class ShotsResource {\n  constructor(private client: NodaroClientCore) {}\n\n  /** Create a shot record. Returns the new shot's id — an unguessable\n   *  capability string that doubles as the share-link path segment. */\n  create(input: CreateShotInput = {}): Promise<{ id: string }> {\n    return this.client.request(\"POST\", \"/v1/shots\", { body: input })\n  }\n\n  /** Read a shot. Public shots are readable by anyone holding the id;\n   *  private shots resolve only for their owner (404 otherwise). */\n  get(id: string): Promise<{ shot: Shot }> {\n    return this.client.request(\"GET\", `/v1/shots/${encodeURIComponent(id)}`)\n  }\n\n  /** Update an owned shot (any subset of fields, e.g. a visibility toggle). */\n  update(id: string, input: UpdateShotInput): Promise<{ shot: Shot }> {\n    return this.client.request(\"PATCH\", `/v1/shots/${encodeURIComponent(id)}`, { body: input })\n  }\n\n  /** Delete an owned shot. */\n  async delete(id: string): Promise<void> {\n    await this.client.request(\"DELETE\", `/v1/shots/${encodeURIComponent(id)}`)\n  }\n}\n"]}

package/dist/chunk-MEKI37WI.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-MEKI37WI.js.map
+//# sourceMappingURL=chunk-MEKI37WI.js.map

package/dist/chunk-MEKI37WI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-MEKI37WI.js"}

package/dist/chunk-MQ74AKA2.cjs

@@ -0,0 +1,200 @@
+'use strict';
+
+var entities = require('@nodaro/shared/entities');
+
+// src/resources/locations.ts
+var LocationsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * List the caller's locations. By default returns active locations only;
+   * pass `archived: true` to fetch soft-deleted rows for an "archive" view,
+   * and `q` to keep the ones whose name or description contains it.
+   */
+  list(params = {}) {
+    const query = {};
+    if (params.archived) query.archived = "true";
+    if (params.q) query.q = params.q;
+    if (params.limit !== void 0) query.limit = String(params.limit);
+    if (params.cursor) query.cursor = params.cursor;
+    return this.client.request("GET", "/v1/locations", { query });
+  }
+  /**
+   * Convenience wrapper for `list({ archived: true })`. Returns soft-deleted
+   * rows so callers can drive a UI "Archived" tab without re-encoding the
+   * query param. Mirrors `ObjectsResource.listArchived`.
+   *
+   * `archived` is omitted from the param type — it's always set to `true` here.
+   */
+  listArchived(params = {}) {
+    return this.list({ ...params, archived: true });
+  }
+  /**
+   * Fetch a single location including in-flight asset job state. Soft-deleted
+   * (archived) rows are returned by id intentionally so canvas nodes that
+   * hold a stale `locationDbId` keep loading.
+   */
+  async get(id) {
+    const res = await this.client.request(
+      "GET",
+      `/v1/locations/${encodeURIComponent(id)}`
+    );
+    return { ...res, canonicalDescription: res.canonicalDescription || null };
+  }
+  /**
+   * Create a new location. `name` + `nodeId` are required — the route 400s
+   * otherwise. Returns the new row's id.
+   *
+   * Note: the underlying route is the same `POST /v1/locations` upsert that
+   * powers `update()`. This convenience wrapper enforces the INSERT-required
+   * fields at the type level and never sends an `id`.
+   */
+  create(data) {
+    return this.client.request("POST", "/v1/locations", { body: data });
+  }
+  /**
+   * Update a location. Only the fields you pass are written — undefined keys
+   * are NOT touched on the row. Worker-owned asset buckets are intentionally
+   * not exposed on this surface (see `UpdateLocationInput` for the rationale).
+   *
+   * Optimistic-concurrency: pass `expectedUpdatedAt` to require the row's
+   * `updated_at` still matches; on mismatch the route returns 409
+   * `concurrent_modification`. The SDK surfaces that as a generic
+   * `NodaroError` with the same code.
+   */
+  update(id, data) {
+    return this.client.request("POST", "/v1/locations", {
+      body: { id, ...data }
+    });
+  }
+  /**
+   * Soft-delete (archive) a location. The row is hidden from `list()` by
+   * default but still loadable via `get(id)` so canvas nodes pointing at it
+   * keep working. Restore with `restore(id)`.
+   */
+  delete(id) {
+    return this.client.request("DELETE", `/v1/locations/${encodeURIComponent(id)}`);
+  }
+  /**
+   * Un-archive a location. If the original name now collides (case-
+   * insensitive) with an active row, the server auto-suffixes "(restored)"
+   * and returns the effective name.
+   */
+  restore(id) {
+    return this.client.request("POST", `/v1/locations/${encodeURIComponent(id)}/restore`);
+  }
+  /**
+   * Fire `POST /v1/generate-location` to produce one or more candidate main
+   * images. With `count > 1`, all jobs are reserved up-front before any
+   * is enqueued — mid-batch failures roll back atomically.
+   *
+   * When `attachToLocationId` is set AND `count === 1`, the worker writes
+   * the result directly to the row's `source_image_url`; otherwise you must
+   * call `approveMainImage()` after picking a candidate.
+   */
+  async generate(data) {
+    const res = await this.client.request(
+      "POST",
+      "/v1/generate-location",
+      { body: data }
+    );
+    const jobIds = res.jobIds ?? (res.jobId ? [res.jobId] : []);
+    return res.jobId ? { jobIds, jobId: res.jobId } : { jobIds };
+  }
+  /**
+   * Fire `POST /v1/generate-location-asset` to produce a single variant.
+   * When the studio path is set (`attachToLocationId` + `attachToColumn` +
+   * `attachName`), the worker appends `{ name: attachName, url: <result> }`
+   * to the named JSONB array column on completion.
+   */
+  generateAsset(data) {
+    return this.client.request("POST", "/v1/generate-location-asset", { body: data });
+  }
+  /**
+   * Fire `POST /v1/generate-surround-continuation` to produce one seamless 360°
+   * ring view as an i2i continuation of `referenceImageUrl`. The platform builds
+   * the half-carry composite, paints the missing half, and color-harmonizes it
+   * to the carried half (no tonal seam; carried half stays pixel-exact). When the
+   * studio path is set, the worker appends the result to the location's bucket.
+   */
+  generateSurroundContinuation(data) {
+    return this.client.request("POST", "/v1/generate-surround-continuation", { body: data });
+  }
+  /**
+   * Fire `POST /v1/generate-location-motion` to animate the location's
+   * establishing shot into an atmospheric motion clip. Image-to-video, single
+   * clip per call; the attach column is hardcoded to `atmosphere_motions`
+   * server-side (locations have a single motion bucket so the caller doesn't
+   * supply `attachToColumn`). When the studio path is set
+   * (`attachToLocationId` + `attachName`), the worker appends
+   * `{ name: attachName, url: <result> }` to the row's `atmosphere_motions`
+   * column on completion.
+   */
+  generateMotion(data) {
+    return this.client.request("POST", "/v1/generate-location-motion", { body: data });
+  }
+  /**
+   * Atomically remove ONE asset take (every entry matching `url`) from a
+   * worker-owned bucket column — `POST /v1/locations/:id/remove-asset`. The
+   * worker-owned buckets are deliberately not writable through `update()`
+   * (a stale snapshot would race concurrent worker appends), so deleting a
+   * take — e.g. a 360° surround view being regenerated — goes through this
+   * single-statement server-side filter instead. 404s (`NotFoundError`) when
+   * the url isn't in that bucket or the location isn't yours.
+   */
+  removeAsset(id, data) {
+    return this.client.request(
+      "POST",
+      `/v1/locations/${encodeURIComponent(id)}/remove-asset`,
+      { body: data }
+    );
+  }
+  /**
+   * Approve a completed `generate-location` job as the location's main image.
+   * Sets `source_image_url` and fires the LLM caption (Claude Sonnet vision)
+   * inline. Returns the new main-image URL plus the caption.
+   *
+   * Caption-failure semantics: the route still sends `""` on LLM sub-failure,
+   * but the SDK normalizes `""` → `null` here so `canonicalDescription` carries
+   * the same `string | null` semantics as characters. The main image is still
+   * set; call `recaption()` to retry.
+   */
+  async approveMainImage(id, candidateJobId) {
+    const res = await this.client.request(
+      "POST",
+      `/v1/locations/${encodeURIComponent(id)}/approve-main-image`,
+      { body: { candidateJobId } }
+    );
+    return { sourceImageUrl: res.sourceImageUrl, canonicalDescription: res.canonicalDescription || null };
+  }
+  /**
+   * Re-fire the LLM caption against the location's current main image. 502s
+   * on LLM failure (unlike `approveMainImage` which preserves the side-effect
+   * and returns ""); returns 400 `no_source_image` if no main image is set
+   * yet.
+   */
+  recaption(id) {
+    return this.client.request(
+      "POST",
+      `/v1/locations/${encodeURIComponent(id)}/llm-caption`
+    );
+  }
+};
+
+Object.defineProperty(exports, "LOCATION_ASSET_TYPES", {
+  enumerable: true,
+  get: function () { return entities.LOCATION_ASSET_TYPES; }
+});
+Object.defineProperty(exports, "LOCATION_ATTACH_COLUMNS", {
+  enumerable: true,
+  get: function () { return entities.LOCATION_ATTACH_COLUMNS; }
+});
+Object.defineProperty(exports, "SURROUND_DIRECTIONS", {
+  enumerable: true,
+  get: function () { return entities.SURROUND_DIRECTIONS; }
+});
+exports.LocationsResource = LocationsResource;
+//# sourceMappingURL=chunk-MQ74AKA2.cjs.map
+//# sourceMappingURL=chunk-MQ74AKA2.cjs.map

package/dist/chunk-MQ74AKA2.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resources/locations.ts"],"names":[],"mappings":"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","file":"chunk-MQ74AKA2.cjs","sourcesContent":["import type { CharacterAspectRatio, SurroundDirection, LocationAssetType, LocationAttachColumn } from \"@nodaro/shared/entities\"\nexport type { LocationAssetType, LocationAttachColumn, CharacterAspectRatio, SurroundDirection } from \"@nodaro/shared/entities\"\nexport { LOCATION_ASSET_TYPES, LOCATION_ATTACH_COLUMNS, SURROUND_DIRECTIONS } from \"@nodaro/shared/entities\"\nimport type { NodaroClientCore } from \"../core.js\"\nimport type { GenerationSessionParams } from \"./nodes.js\"\n\n/**\n * Re-export the shared `LocationAssetType` / `LocationAttachColumn` unions and\n * their runtime tuples so SDK consumers don't have to add `@nodaro/shared` as a\n * second dependency just to typecheck the `assetType` / `attachToColumn`\n * fields. Single source of truth lives in `@nodaro/shared/entity-prompts`.\n *\n * `CharacterAspectRatio` is re-exported alongside them — `generateMotion`'s\n * `aspectRatio` field reuses the same 4-value enum (1:1 / 3:4 / 16:9 / 9:16)\n * as characters; the route enforces this with `z.enum(CHARACTER_ASPECT_OPTIONS)`.\n */\n\n/**\n * Reference-photo kind discriminator — the mood-board roles a user can attach\n * to a location. Mirrors the `reference_photos.kind` Zod enum in\n * `backend/src/routes/locations.ts`. `other` is the free-form bucket.\n */\nexport type LocationReferencePhotoKind =\n  | \"wide\"\n  | \"interior\"\n  | \"exterior\"\n  | \"detail\"\n  | \"moodBoard\"\n  | \"other\"\n\nexport interface LocationReferencePhoto {\n  url: string\n  kind: LocationReferencePhotoKind\n}\n\n/**\n * A location record returned by Nodaro's REST API. Mirrors the camelCase\n * shape produced by `backend/src/routes/locations.ts::toCamel()`.\n *\n * Asset buckets (`timeOfDay`, `weather`, `angles`, `lighting`, `seasons`,\n * `atmosphereMotions`) are independent JSONB arrays keyed by a human-readable\n * variant name (e.g. `\"dawn\"`, `\"clear\"`, `\"wide\"`). Each entry's `url` points\n * at an R2-hosted asset.\n *\n * Identity-foundation fields:\n *   - `referencePhotos` — caller-supplied mood-board refs (cap 20).\n *   - `canonicalDescription` — ~80–120-word LLM-authored visual caption,\n *     populated by `approveMainImage()` / `recaption()`. The wire still sends\n *     `\"\"` on caption sub-failure (the breaking wire change is deferred to a\n *     major bump), but `get()` normalizes `\"\"` → `null` so consumers see the\n *     same `string | null` semantics as characters.\n *   - `styleLock` — whether asset gens should anchor to the canonical style\n *     captured at approval time. Defaults to `true` on new rows.\n */\nexport interface Location {\n  id: string\n  userId: string\n  nodeId: string\n  projectId: string | null\n  name: string\n  description: string | null\n  category: string | null\n  style: string | null\n  sourceImageUrl: string | null\n  /** MODEL_CATALOG image-model id the main image was generated with (or `null`).\n   *  Set on create + editable via the update route. */\n  imageProvider: string | null\n  timeOfDay: Array<{ name: string; url: string }>\n  weather: Array<{ name: string; url: string }>\n  angles: Array<{ name: string; url: string }>\n  lighting: Array<{ name: string; url: string }>\n  seasons: Array<{ name: string; url: string }>\n  atmosphereMotions: Array<{ name: string; url: string }>\n  /** Named Location Boards — dense reference sheets, one per variant/mood\n   *  (the `generate-image/location-board` factory preset rendered from the\n   *  location's images). A first-class bucket: community publish snapshots it\n   *  and clone hands the consumer their own copy to extend. Defaults to `[]`.\n   *  `type` marks an image-collage `\"identity\"` sheet vs a plain `\"looks\"`\n   *  board; `sourceImages` are the R2 URLs it was collaged from. Both optional\n   *  + backward-compatible (legacy boards have neither). */\n  boards?: Array<{ name: string; url: string; type?: \"looks\" | \"identity\"; sourceImages?: string[] }> | null\n  referencePhotos: LocationReferencePhoto[]\n  /** `null` when no caption is set (or the LLM caption sub-failed) — the wire\n   *  sends `\"\"`, normalized to `null` in `get()` to match character semantics. */\n  canonicalDescription: string | null\n  styleLock: boolean\n  /** The user's chosen DEFAULT asset take per variant (Studio version history).\n   *  OPAQUE map: key `\"<bucket>:<variant>\"` (e.g. `\"timeOfDay:dawn\"`) → the chosen\n   *  asset URL (one already present in that bucket). Stored verbatim — keys are\n   *  NOT normalized; soft-capped server-side at 200 keys / 2048-char values\n   *  (overflow dropped silently). Defaults to `{}`. */\n  selectedAssetByVariant?: Record<string, string> | null\n  deletedAt: string | null\n  createdAt: string\n  updatedAt: string\n}\n\n/**\n * GET /v1/locations/:id appends a `pendingJobs` bucket the studio uses to\n * rehydrate spinners after a reload. Optional on the SDK surface — it doesn't\n * appear on `list()` rows.\n */\nexport interface LocationDetail extends Location {\n  pendingJobs?: Array<{\n    jobId: string\n    assetType: string\n    name: string\n    status: string\n  }>\n  /**\n   * Completed candidate main images for this location whose URL differs from\n   * the current `sourceImageUrl`, newest first (max 5). Surfaced so a\n   * \"pick from N\" UI can offer alternatives the user can promote via\n   * `approveMainImage(id, jobId)`; until they pick, the current main image is\n   * left untouched. Mirrors `CharacterDetail.previousCandidates`. Optional -\n   * absent on `list()` rows, present (possibly empty) on `get()`.\n   */\n  previousCandidates?: Array<{\n    jobId: string\n    url: string\n    createdAt: string\n  }>\n}\n\n/**\n * Body for `client.locations.create()`. Mirrors the INSERT branch of\n * `upsertLocationBody` in `backend/src/routes/locations.ts`. `name` + `nodeId`\n * are required on create.\n */\nexport interface CreateLocationInput {\n  nodeId: string\n  name: string\n  description?: string\n  category?: string\n  style?: string\n  workflowId?: string\n  projectId?: string\n  sourceImageUrl?: string\n  /** Persistent image-model id (a MODEL_CATALOG image model). Validated\n   *  server-side — unknown / non-image / \"\" is stored as `null`. */\n  imageProvider?: string | null\n  referencePhotos?: LocationReferencePhoto[]\n  canonicalDescription?: string\n  styleLock?: boolean\n  /** The user's chosen DEFAULT asset take per variant. OPAQUE\n   *  `\"<bucket>:<variant>\"` → chosen-URL map; a write REPLACES the whole map.\n   *  Keys stored verbatim; soft-capped server-side at 200 keys / 2048-char values. */\n  selectedAssetByVariant?: Record<string, string>\n}\n\n/**\n * Body for `client.locations.update()`. Mirrors the UPDATE branch of\n * `upsertLocationBody` in `backend/src/routes/locations.ts`.\n *\n * Worker-owned asset buckets (`timeOfDay`/`weather`/`angles`/`lighting`/\n * `seasons`/`atmosphereMotions`) are deliberately omitted — the route drops\n * them on UPDATE so a Studio auto-save with a stale snapshot cannot clobber\n * the worker's atomic `append_location_asset()` writes.\n *\n * `expectedUpdatedAt` is the optimistic-concurrency token: when present, the\n * UPDATE only succeeds if the row's `updated_at` still matches; on mismatch\n * the route returns 409 so the studio can re-fetch + merge.\n */\nexport interface UpdateLocationInput {\n  name?: string\n  description?: string\n  category?: string\n  style?: string\n  sourceImageUrl?: string\n  /** Persistent image-model id (a MODEL_CATALOG image model). Validated\n   *  server-side — unknown / non-image / \"\" is stored as `null`. */\n  imageProvider?: string | null\n  referencePhotos?: LocationReferencePhoto[]\n  canonicalDescription?: string\n  styleLock?: boolean\n  /** The user's chosen DEFAULT asset take per variant. OPAQUE\n   *  `\"<bucket>:<variant>\"` → chosen-URL map; a write REPLACES the whole map\n   *  (omit to leave untouched). Keys stored verbatim; soft-capped server-side\n   *  at 200 keys / 2048-char values. */\n  selectedAssetByVariant?: Record<string, string>\n  /** Named Location Boards (see `Location.boards`) — whole-array replace,\n   *  USER-owned (unlike the worker-owned buckets it flows through UPDATE).\n   *  Server caps: 24 boards, 200-char names, 30 sourceImages per board. */\n  boards?: Array<{ name: string; url: string; type?: \"looks\" | \"identity\"; sourceImages?: string[] }>\n  /** ISO-8601 timestamp recording when PII consent was captured for this location. */\n  piiConsentAt?: string\n  expectedUpdatedAt?: string\n}\n\nexport interface UpdateLocationResult {\n  id: string\n  updatedAt: string\n}\n\nexport interface ListLocationsParams {\n  /** When true, return archived locations instead of active ones. */\n  archived?: boolean\n  /**\n   * Search words: only the locations whose name or description contains\n   * every word (split on spaces, the first 5), in any order, ignoring case.\n   * Each word is matched as written (`%`, `_` and `*` are not wildcards;\n   * punctuation is kept); blank means no search; up to 200 characters.\n   * Combines with the other filters and with `cursor` paging.\n   */\n  q?: string\n  /**\n   * Max rows to return (cap 500). OPT-IN: omitted, the server returns the\n   * full legacy listing with no `nextCursor`; supplied, the response is one\n   * page plus `nextCursor` — keep passing it back until it is `null`.\n   */\n  limit?: number\n  /** Opaque cursor from a prior page's `nextCursor` (fetches the next page). */\n  cursor?: string\n}\n\n/**\n * Input for `client.locations.generate()` — fires the\n * `POST /v1/generate-location` route. Produces 1–10 candidate\n * establishing shots; each lands as one `jobs` row in `pending` state and\n * is then enqueued for the worker.\n *\n * When `attachToLocationId` is set AND `count === 1`, the worker writes the\n * resulting URL directly to `locations.source_image_url` on completion —\n * caller doesn't need a separate `approveMainImage` call. Multi-candidate\n * batches MUST go through explicit approval so the user picks the winner.\n */\nexport interface GenerateLocationInput extends GenerationSessionParams {\n  name: string\n  description?: string\n  userPrompt?: string\n  category?: \"indoor\" | \"outdoor\" | \"urban\" | \"nature\" | \"fantasy\" | \"sci-fi\" | \"historical\" | \"futuristic\" | \"other\"\n  style?: \"realistic\" | \"anime\" | \"3d-pixar\" | \"illustration\"\n  sourceImageUrl?: string\n  provider?: string\n  /** Number of candidate images to generate (1–10; server-validated). */\n  count?: number\n  /** Auto-attach the result to this location row (single-candidate only). */\n  attachToLocationId?: string\n  /**\n   * Credit-affecting quality tier (e.g. `\"high\"` for gpt-image). Priced like\n   * generate-image (composite ids such as `gpt-image:high`); values the chosen\n   * model doesn't support are ignored server-side, never rejected.\n   */\n  quality?: string\n  /**\n   * Credit-affecting output resolution (e.g. `\"2K\"` / `\"4K\"` / `\"2 MP\"`).\n   * Priced like generate-image (composite ids such as `nano-banana-pro:4K`);\n   * values the chosen model doesn't support are ignored server-side, never\n   * rejected.\n   */\n  resolution?: string\n}\n\n/**\n * `generate()` response — `jobIds` is ALWAYS present (the harmonized contract,\n * matching characters). `jobId` is a deprecated back-compat alias populated only\n * on `count === 1`; prefer `jobIds`. (Will be removed on the next major.)\n */\nexport interface GenerateLocationResult {\n  jobIds: string[]\n  /** @deprecated count===1 back-compat alias — use `jobIds`. */\n  jobId?: string\n}\n\n/**\n * Input for `client.locations.generateAsset()` — fires the\n * `POST /v1/generate-location-asset` route. Produces a single\n * timeOfDay / weather / seasons / angles / lighting / custom variant.\n *\n * When all three studio-path fields are set (`attachToLocationId` +\n * `attachToColumn` + `attachName`), the worker appends\n * `{ name: attachName, url: <result> }` to the named JSONB array column on\n * the user's location row on completion. `attachToColumn` is REQUIRED for\n * `assetType === \"custom\"` — the worker can't infer the bucket from the\n * asset type.\n */\nexport interface GenerateLocationAssetInput extends GenerationSessionParams {\n  assetType: LocationAssetType\n  variant: string\n  name: string\n  description?: string\n  userPrompt?: string\n  category?: string\n  style?: \"realistic\" | \"anime\" | \"3d-pixar\" | \"illustration\"\n  sourceImageUrl?: string\n  provider?: string\n  /** Optional framing override (the same 4-value enum as `generateMotion`).\n   *  Absent = the image model's default. The studio's 360° surround path pins\n   *  `\"16:9\"` so every ring view matches the establishing shot's frame. */\n  aspectRatio?: CharacterAspectRatio\n  attachToLocationId?: string\n  attachToColumn?: LocationAttachColumn\n  attachName?: string\n  /**\n   * Credit-affecting quality tier (e.g. `\"high\"` for gpt-image). Values the\n   * chosen model doesn't support are ignored server-side, never rejected.\n   */\n  quality?: string\n  /**\n   * Credit-affecting output resolution (e.g. `\"2K\"` / `\"4K\"` / `\"2 MP\"`).\n   * Values the chosen model doesn't support are ignored server-side, never\n   * rejected.\n   */\n  resolution?: string\n}\n\n/**\n * Input for `client.locations.generateSurroundContinuation()` — fires the\n * `POST /v1/generate-surround-continuation` route. Generates one seamless 360°\n * ring view as an image-to-image continuation of `referenceImageUrl` (the\n * previous ring view, or the establishing shot for the first ring).\n *\n * The platform owns the whole pipeline: it builds the half-carry composite\n * server-side (carry the reference's trailing half into the new frame's leading\n * half per `direction`, gray the rest), paints the gray region, then\n * color-harmonizes the painted half to the carried half so there is no tonal\n * seam down the frame's center. The carried half stays pixel-exact, so a\n * panorama viewer stitching adjacent ring views stays geometrically seamless.\n *\n * When the studio path is set (`attachToLocationId` + `attachToColumn` +\n * `attachName`), the worker appends `{ name: attachName, url: <result> }` to the\n * location's bucket (studio uses `attachToColumn: \"angles\"`,\n * `attachName: \"Surround 45°\"`).\n */\nexport interface GenerateSurroundContinuationInput extends GenerationSessionParams {\n  /** The previous ring view to continue from (i2i anchor). */\n  referenceImageUrl: string\n  /** Carry/paint axis: turn right, turn left, tilt up, or tilt down. Tilts\n   *  render the sky/ground (a thin horizon strip), not a horizontal continuation. */\n  direction: SurroundDirection\n  /** Ring angle (45, 90, …) — stored on the result as metadata. */\n  degrees?: number\n  /** Fraction of the frame carried from the reference. Omitted ⇒ per-direction\n   *  default (0.5 for a pan, 0.12 thin strip for a tilt). */\n  carriedFraction?: number\n  /** Upscale/denoise the result before it's chained as the next reference, to\n   *  slow cumulative softening down a long ring chain. Default false. */\n  refine?: boolean\n  /** Refine model when `refine` is set. `recraft-upscale` (1 cr, default) or\n   *  `topaz-image-upscale` (3 cr). */\n  refineProvider?: \"recraft-upscale\" | \"topaz-image-upscale\"\n  /** Optional free-form scene hint woven into the fill prompt. */\n  userPrompt?: string\n  /** Image model. Defaults to the platform's general image model (`gpt-image-2`). */\n  provider?: string\n  /** Studio pins `\"16:9\"` so every ring view matches the establishing frame. */\n  aspectRatio?: CharacterAspectRatio\n  attachToLocationId?: string\n  attachToColumn?: LocationAttachColumn\n  attachName?: string\n}\n\n/**\n * Input for `client.locations.generateMotion()` — fires the\n * `POST /v1/generate-location-motion` route. Produces a single atmospheric\n * motion clip (drifting fog, snowfall, rolling waves, etc.) animated FROM a\n * static establishing-shot image.\n *\n * Mirrors `client.characters.generateMotion()` minus the character-specific\n * fields (gender / baseOutfit / realLifeRefs). The route hardcodes the attach\n * column to `atmosphere_motions` — callers supply `attachToLocationId` +\n * `attachName` only.\n *\n * `sourceImageUrl` is REQUIRED — image-to-video needs a source frame and the\n * route has no fallback (no `source_image_url` column to pull from on the\n * locations row; the studio path supplies the canonical establishing-shot URL\n * explicitly).\n *\n * When the studio path is set (`attachToLocationId` + `attachName`), the\n * worker appends `{ name: attachName, url: <result> }` to the location row's\n * `atmosphere_motions` JSONB column on completion.\n */\nexport interface GenerateLocationMotionInput extends GenerationSessionParams {\n  motionPrompt: string\n  sourceImageUrl: string\n  provider?: string\n  name: string\n  category?: string\n  style?: \"realistic\" | \"anime\" | \"3d-pixar\" | \"illustration\"\n  canonicalDescription?: string\n  attachToLocationId?: string\n  attachName?: string\n  /**\n   * Optional aspect ratio override. Defaults to 16:9 server-side via\n   * `resolveLocationAspectRatio` (locations are cinematic establishing shots).\n   * One of the 4-value `CharacterAspectRatio` union — locations reuse the\n   * character aspect enum since the supported ratios are identical.\n   */\n  aspectRatio?: CharacterAspectRatio\n}\n\nexport interface ApproveMainImageResult {\n  sourceImageUrl: string\n  /**\n   * LLM-authored caption. `null` when the LLM caption sub-failed — the wire\n   * sends `\"\"`, normalized to `null` here so consumers see the same\n   * `string | null` semantics as characters. The main image is still set; call\n   * `recaption()` to retry.\n   */\n  canonicalDescription: string | null\n}\n\nexport interface RecaptionLocationResult {\n  canonicalDescription: string\n}\n\nexport class LocationsResource {\n  constructor(private client: NodaroClientCore) {}\n\n  /**\n   * List the caller's locations. By default returns active locations only;\n   * pass `archived: true` to fetch soft-deleted rows for an \"archive\" view,\n   * and `q` to keep the ones whose name or description contains it.\n   */\n  list(params: ListLocationsParams = {}): Promise<{ locations: Location[]; nextCursor?: string | null }> {\n    const query: Record<string, string | undefined> = {}\n    if (params.archived) query.archived = \"true\"\n    if (params.q) query.q = params.q\n    if (params.limit !== undefined) query.limit = String(params.limit)\n    if (params.cursor) query.cursor = params.cursor\n    return this.client.request(\"GET\", \"/v1/locations\", { query })\n  }\n\n  /**\n   * Convenience wrapper for `list({ archived: true })`. Returns soft-deleted\n   * rows so callers can drive a UI \"Archived\" tab without re-encoding the\n   * query param. Mirrors `ObjectsResource.listArchived`.\n   *\n   * `archived` is omitted from the param type — it's always set to `true` here.\n   */\n  listArchived(params: Omit<ListLocationsParams, \"archived\"> = {}): Promise<{ locations: Location[]; nextCursor?: string | null }> {\n    return this.list({ ...params, archived: true })\n  }\n\n  /**\n   * Fetch a single location including in-flight asset job state. Soft-deleted\n   * (archived) rows are returned by id intentionally so canvas nodes that\n   * hold a stale `locationDbId` keep loading.\n   */\n  async get(id: string): Promise<LocationDetail> {\n    const res = await this.client.request<LocationDetail>(\n      \"GET\",\n      `/v1/locations/${encodeURIComponent(id)}`,\n    )\n    // Normalize the wire `\"\"` caption (DB null / LLM sub-failure) → null so\n    // consumers see the same `string | null` semantics as characters. New\n    // object — never mutate the response.\n    return { ...res, canonicalDescription: res.canonicalDescription || null }\n  }\n\n  /**\n   * Create a new location. `name` + `nodeId` are required — the route 400s\n   * otherwise. Returns the new row's id.\n   *\n   * Note: the underlying route is the same `POST /v1/locations` upsert that\n   * powers `update()`. This convenience wrapper enforces the INSERT-required\n   * fields at the type level and never sends an `id`.\n   */\n  create(data: CreateLocationInput): Promise<{ id: string }> {\n    return this.client.request(\"POST\", \"/v1/locations\", { body: data })\n  }\n\n  /**\n   * Update a location. Only the fields you pass are written — undefined keys\n   * are NOT touched on the row. Worker-owned asset buckets are intentionally\n   * not exposed on this surface (see `UpdateLocationInput` for the rationale).\n   *\n   * Optimistic-concurrency: pass `expectedUpdatedAt` to require the row's\n   * `updated_at` still matches; on mismatch the route returns 409\n   * `concurrent_modification`. The SDK surfaces that as a generic\n   * `NodaroError` with the same code.\n   */\n  update(id: string, data: UpdateLocationInput): Promise<UpdateLocationResult> {\n    return this.client.request(\"POST\", \"/v1/locations\", {\n      body: { id, ...data },\n    })\n  }\n\n  /**\n   * Soft-delete (archive) a location. The row is hidden from `list()` by\n   * default but still loadable via `get(id)` so canvas nodes pointing at it\n   * keep working. Restore with `restore(id)`.\n   */\n  delete(id: string): Promise<{ success: true; archived: true }> {\n    return this.client.request(\"DELETE\", `/v1/locations/${encodeURIComponent(id)}`)\n  }\n\n  /**\n   * Un-archive a location. If the original name now collides (case-\n   * insensitive) with an active row, the server auto-suffixes \"(restored)\"\n   * and returns the effective name.\n   */\n  restore(id: string): Promise<{ id: string; name: string }> {\n    return this.client.request(\"POST\", `/v1/locations/${encodeURIComponent(id)}/restore`)\n  }\n\n  /**\n   * Fire `POST /v1/generate-location` to produce one or more candidate main\n   * images. With `count > 1`, all jobs are reserved up-front before any\n   * is enqueued — mid-batch failures roll back atomically.\n   *\n   * When `attachToLocationId` is set AND `count === 1`, the worker writes\n   * the result directly to the row's `source_image_url`; otherwise you must\n   * call `approveMainImage()` after picking a candidate.\n   */\n  async generate(data: GenerateLocationInput): Promise<GenerateLocationResult> {\n    const res = await this.client.request<{ jobId?: string; jobIds?: string[] }>(\n      \"POST\", \"/v1/generate-location\", { body: data },\n    )\n    // Tolerate the legacy `{ jobId }`-only shape (older server): synthesize jobIds.\n    const jobIds = res.jobIds ?? (res.jobId ? [res.jobId] : [])\n    return res.jobId ? { jobIds, jobId: res.jobId } : { jobIds }\n  }\n\n  /**\n   * Fire `POST /v1/generate-location-asset` to produce a single variant.\n   * When the studio path is set (`attachToLocationId` + `attachToColumn` +\n   * `attachName`), the worker appends `{ name: attachName, url: <result> }`\n   * to the named JSONB array column on completion.\n   */\n  generateAsset(data: GenerateLocationAssetInput): Promise<{ jobId: string }> {\n    return this.client.request(\"POST\", \"/v1/generate-location-asset\", { body: data })\n  }\n\n  /**\n   * Fire `POST /v1/generate-surround-continuation` to produce one seamless 360°\n   * ring view as an i2i continuation of `referenceImageUrl`. The platform builds\n   * the half-carry composite, paints the missing half, and color-harmonizes it\n   * to the carried half (no tonal seam; carried half stays pixel-exact). When the\n   * studio path is set, the worker appends the result to the location's bucket.\n   */\n  generateSurroundContinuation(data: GenerateSurroundContinuationInput): Promise<{ jobId: string }> {\n    return this.client.request(\"POST\", \"/v1/generate-surround-continuation\", { body: data })\n  }\n\n  /**\n   * Fire `POST /v1/generate-location-motion` to animate the location's\n   * establishing shot into an atmospheric motion clip. Image-to-video, single\n   * clip per call; the attach column is hardcoded to `atmosphere_motions`\n   * server-side (locations have a single motion bucket so the caller doesn't\n   * supply `attachToColumn`). When the studio path is set\n   * (`attachToLocationId` + `attachName`), the worker appends\n   * `{ name: attachName, url: <result> }` to the row's `atmosphere_motions`\n   * column on completion.\n   */\n  generateMotion(data: GenerateLocationMotionInput): Promise<{ jobId: string }> {\n    return this.client.request(\"POST\", \"/v1/generate-location-motion\", { body: data })\n  }\n\n  /**\n   * Atomically remove ONE asset take (every entry matching `url`) from a\n   * worker-owned bucket column — `POST /v1/locations/:id/remove-asset`. The\n   * worker-owned buckets are deliberately not writable through `update()`\n   * (a stale snapshot would race concurrent worker appends), so deleting a\n   * take — e.g. a 360° surround view being regenerated — goes through this\n   * single-statement server-side filter instead. 404s (`NotFoundError`) when\n   * the url isn't in that bucket or the location isn't yours.\n   */\n  removeAsset(\n    id: string,\n    data: { column: LocationAttachColumn; url: string },\n  ): Promise<{ removed: true }> {\n    return this.client.request(\n      \"POST\",\n      `/v1/locations/${encodeURIComponent(id)}/remove-asset`,\n      { body: data },\n    )\n  }\n\n  /**\n   * Approve a completed `generate-location` job as the location's main image.\n   * Sets `source_image_url` and fires the LLM caption (Claude Sonnet vision)\n   * inline. Returns the new main-image URL plus the caption.\n   *\n   * Caption-failure semantics: the route still sends `\"\"` on LLM sub-failure,\n   * but the SDK normalizes `\"\"` → `null` here so `canonicalDescription` carries\n   * the same `string | null` semantics as characters. The main image is still\n   * set; call `recaption()` to retry.\n   */\n  async approveMainImage(id: string, candidateJobId: string): Promise<ApproveMainImageResult> {\n    const res = await this.client.request<{ sourceImageUrl: string; canonicalDescription: string | null }>(\n      \"POST\",\n      `/v1/locations/${encodeURIComponent(id)}/approve-main-image`,\n      { body: { candidateJobId } },\n    )\n    // Normalize the wire `\"\"` (LLM sub-failure) → null; build a new object\n    // rather than mutating the response.\n    return { sourceImageUrl: res.sourceImageUrl, canonicalDescription: res.canonicalDescription || null }\n  }\n\n  /**\n   * Re-fire the LLM caption against the location's current main image. 502s\n   * on LLM failure (unlike `approveMainImage` which preserves the side-effect\n   * and returns \"\"); returns 400 `no_source_image` if no main image is set\n   * yet.\n   */\n  recaption(id: string): Promise<RecaptionLocationResult> {\n    return this.client.request(\n      \"POST\",\n      `/v1/locations/${encodeURIComponent(id)}/llm-caption`,\n    )\n  }\n}\n"]}