@nodaro/sdk 2.29.0 → 2.32.0

package/dist/entries/locations.d.cts

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