@nodaro/sdk 2.29.0 → 2.32.0

package/dist/entries/jobs.d.ts

@@ -0,0 +1,252 @@
+import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.js';
+import '@nodaro/shared/apps';
+import '@nodaro/shared/organizations';
+
+/**
+ * A job's lifecycle status. Hand-copied mirror of `JOB_STATUSES` in the
+ * platform's `backend/src/lib/job-status.ts` — nothing links the two at build
+ * time, so a new member has to be added here in the same change.
+ *
+ * `pending_review` is IN-FLIGHT, NOT TERMINAL: a job policy registered by the
+ * deployment held the output for a human reviewer. Treat it like `processing`
+ * in a `switch` — keep waiting, do not re-run — and it resolves to `completed`
+ * (approved), `failed` (rejected, carrying an `error_hint` with
+ * `kind: "policy-block"`) or `cancelled` (a held job is cancellable like any
+ * in-flight job). `credit_status` reads `"reserved"` for the whole hold. Only
+ * appears on deployments that register a job policy; `runAndWait` throws
+ * {@link JobHeldError} on the first held tick rather than waiting it out.
+ */
+type JobStatus = "pending" | "queued" | "processing" | "pending_review" | "completed" | "failed" | "cancelled";
+/**
+ * A PROVIDER's verdict: the model's own safety filter refused the output.
+ * `class` distinguishes a deterministic block (copyright/likeness — retrying
+ * the same request never helps) from `safety`, whose filter is known to be
+ * non-deterministic for some models: `retried` says whether the worker
+ * already spent its one extra attempt, and `suggestedProvider` — present
+ * only when the catalog declares a fallback for the model that failed — is a
+ * real model id the SAME prompt/references can be retried on.
+ */
+type SafetyBlockHint = {
+    kind: "safety-block";
+    class: "copyright" | "likeness" | "safety";
+    retried: boolean;
+    suggestedProvider?: string;
+};
+/**
+ * A NODARO-side verdict, not a provider's: a job policy registered by the
+ * deployment rejected the request (`hookPoint: "request"` — nothing ran, and
+ * the call itself failed with {@link JobBlockedError}) or the finished output
+ * (`hookPoint: "result"` — the result was blocked and never published).
+ *
+ * `reason` is USER-SAFE BY CONTRACT — the platform guarantees the policy's
+ * machine text (scores, labels) never reaches it — so show it to the person
+ * who made the request as-is. `policyId` identifies the deployment's policy,
+ * not a Nodaro product feature. Only occurs on deployments that register a
+ * job policy.
+ */
+type PolicyBlockHint = {
+    kind: "policy-block";
+    policyId: string;
+    reason: string;
+    hookPoint: "request" | "result";
+};
+/**
+ * A job's `jobs.error_hint` (migration 376) — a user-safe, machine-readable
+ * failure verdict, so a caller can act on it without parsing `error_message`
+ * prose. One column, two verdict sources; `kind` is the discriminant.
+ *
+ * HAND-COPIED MIRROR of `ErrorHint` in the platform's
+ * `backend/src/lib/safety-block.ts` (which names this file in its own
+ * comment). Nothing links the two at build time: a new arm there has to be
+ * pasted here verbatim in the same change, with a changeset.
+ * `packages/client/dist/index.d.ts` is REBUILT, never hand-edited.
+ */
+type JobErrorHint = SafetyBlockHint | PolicyBlockHint;
+/**
+ * The billing lifecycle of a job's credit reservation — `usage_logs.status`
+ * for the job's `usage_log_id`. `null` when the job has no usage log (e.g. a
+ * free run) or hasn't reserved credits yet.
+ */
+type CreditStatus = "reserved" | "committed" | "refunded";
+/** A job owner's rating of their job — set with {@link JobsResource.rate}. */
+type JobRating = "good" | "bad";
+/**
+ * The `rating` filter of {@link JobsResource.list}: one rating, any rating
+ * (`"rated"`) or none (`"unrated"`).
+ */
+type JobRatingFilter = JobRating | "rated" | "unrated";
+/**
+ * Job record returned to non-admin SDK consumers. Field names are snake_case
+ * to match the wire format (per the OpenAPI fix in Phase 1).
+ *
+ * Sensitive fields stripped server-side for non-admin callers:
+ * `provider`, `provider_cost`, `display_cost`, `credits_actual`. USD
+ * pricing is admin-only across api/sdk/mcp — non-admin consumers see
+ * only the `credits` abstraction. Server-only nested job data (including
+ * Recast's private remux base) is stripped for every caller, including admins.
+ */
+interface Job {
+    id: string;
+    status: JobStatus;
+    progress: number;
+    user_id: string;
+    input_data: unknown;
+    output_data: unknown;
+    error_message: string | null;
+    /** Present on a failed job the worker classified as a provider
+     *  content-policy block (`kind: "safety-block"`) or that a deployment's job
+     *  policy rejected (`kind: "policy-block"`); absent/null otherwise.
+     *  User-safe by construction — narrow on `kind` before reading the rest. */
+    error_hint?: JobErrorHint | null;
+    /** PR9: the job's credit reservation lifecycle, derived server-side from
+     *  `usage_logs.status`. `null` when there is no usage log to report. Never
+     *  changes the meaning of `credits` (the reserved amount) below. */
+    credit_status?: CreditStatus | null;
+    /** The credits HELD when the job was accepted. Never changes — a job can
+     *  settle below it; read {@link Job.credits_charged} for what it cost. */
+    credits: number | null;
+    /**
+     * What the job actually cost once its hold settled. Can be lower than
+     * `credits` (the unused part goes back to the balance), `0` when the hold was
+     * refunded, `null` while the job is still running or when it reserved
+     * nothing of its own. Sum this — not `credits` — to total spend. Returned by
+     * `get()` and `list()`.
+     */
+    credits_charged?: number | null;
+    job_type: string | null;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+    /**
+     * Provenance: which kind of caller created the job — one of
+     * `"internal" | "mcp" | "app" | "cli" | "sdk" | "extension" | "web" | "api"`.
+     * `source_detail` narrows it (origin host, `extension/<name>` label,
+     * `sdk/<version>`, MCP client name, developer-app id). Descriptive only;
+     * lets a library view label or filter media by origin.
+     */
+    source?: string | null;
+    source_detail?: string | null;
+    /** The generation session this job was born in (the `sessionId` sent with
+     *  the generation request), or null. See `client.sessions`. */
+    session_id?: string | null;
+    /**
+     * Whether the job's owner favorited it (`client.gallery.toggleFavorite`).
+     * Returned by `get()` and `list()`. Absent from an older server, and when
+     * the server could not read it for a moment — treat absent as unknown,
+     * never as `false`.
+     */
+    favorited?: boolean;
+    /**
+     * The owner's rating of the job ({@link JobsResource.rate}), or `null` when
+     * unrated. Returned by `get()` and `list()`; absent like `favorited`.
+     */
+    rating?: JobRating | null;
+}
+interface CancelJobResult {
+    success: true;
+    cancelled: number;
+}
+interface DeleteJobResult {
+    success: true;
+}
+interface ListJobsParams {
+    /** One status or several (a job matching any of them). An unknown status is a 400. */
+    status?: JobStatus | readonly JobStatus[];
+    /** Exact match on `input_data.type` — the route that created the job
+     *  (`"llm-structured"`, `"video-analysis"`, …). One value or several (up to 20). */
+    type?: string | readonly string[];
+    /** Exact match on `input_data.origin` — the client app that sent it. */
+    origin?: string;
+    /** `true`: only jobs you favorited; `false`: only jobs you did not. */
+    favorited?: boolean;
+    /** Your rating: `"good"`, `"bad"`, any (`"rated"`) or none (`"unrated"`). */
+    rating?: JobRatingFilter;
+    /** The jobs of one generate-image batch (`count` / `models`) — its `batchId`. */
+    batchId?: string;
+    /** Page size, 1–100 (server default 50). */
+    limit?: number;
+    /** The previous page's `next`. */
+    cursor?: string;
+}
+/** What {@link JobsResource.rate} answers: the job's rating now. */
+interface RateJobResult {
+    data: {
+        jobId: string;
+        rating: JobRating | null;
+    };
+}
+interface ListJobsPage {
+    /**
+     * A page may hold fewer than `limit` rows — even none — and still carry a
+     * `next`. Page on `next`, never on `data.length`.
+     */
+    data: Job[];
+    /** Pass back as `cursor` for the next page; `null` on the last one. */
+    next: string | null;
+}
+/**
+ * Lean job status returned by `GET /v1/jobs/:id/status`. Skips the
+ * `input_data` JSONB and cost columns. Its `output_data` still goes
+ * through the server-only nested-field redaction. Intended for poll loops that
+ * only need progress/output/error, and when the job finished.
+ */
+interface JobStatusResult {
+    id: string;
+    status: JobStatus;
+    progress?: number;
+    output_data?: unknown;
+    error_message?: string | null;
+    /** PR9: see {@link Job.error_hint}. */
+    error_hint?: JobErrorHint | null;
+    /** PR9: see {@link Job.credit_status}. */
+    credit_status?: CreditStatus | null;
+    /** When the job finished, on the server's clock; null until it has. */
+    completed_at?: string | null;
+}
+declare class JobsResource {
+    private client;
+    constructor(client: NodaroClientCore);
+    /** Get a single job by ID. */
+    get(id: string): Promise<{
+        data: Job;
+    }>;
+    /**
+     * Your jobs, newest first (`GET /v1/jobs`), cursor-paginated. `type` and
+     * `origin` filter on the job's own `input_data`, which every job carries —
+     * a client app lists its runs with `{ type: "llm-structured", origin: "studio" }`.
+     * `status` and `type` take one value or a list; `favorited` and `rating`
+     * filter on your own marks. Every filter combines with AND, and each job
+     * carries `favorited` and `rating`.
+     */
+    list(params?: ListJobsParams): Promise<ListJobsPage>;
+    /**
+     * Rate one of your jobs `"good"` or `"bad"`, or clear the rating with
+     * `null` (`PUT /v1/jobs/:id/rating`). Only the job's owner rates it — anyone
+     * else's job is a `NotFoundError`. The rating reads back as `Job.rating`
+     * and filters {@link list}. OAuth apps need the `assets:write` scope.
+     */
+    rate(id: string, rating: JobRating | null): Promise<RateJobResult>;
+    /**
+     * Get the lean status of a single job (poll-loop friendly).
+     * Hits `GET /v1/jobs/:id/status` — returns only id/status/progress/
+     * output_data/error_message, with far less wire/CPU cost than `get()`.
+     * Same auth + ownership semantics as {@link get}.
+     */
+    getStatus(id: string): Promise<{
+        data: JobStatusResult;
+    }>;
+    /**
+     * Cancel a job. Server route is `POST /v1/jobs/:jobId/cancel`.
+     * Refunds any reserved credit holds.
+     */
+    cancel(id: string): Promise<CancelJobResult>;
+    /**
+     * Delete a job and the private media it produced. Server route is
+     * `DELETE /v1/jobs/:jobId`. Only the job's owner (or an admin) may delete it;
+     * a job that is still running is deleted as-is — cancel it first when its
+     * worker should stop ({@link cancel}).
+     */
+    delete(id: string): Promise<DeleteJobResult>;
+}
+
+export { type CancelJobResult, type CreditStatus, type DeleteJobResult, type Job, type JobErrorHint, type JobRating, type JobRatingFilter, type JobStatus, type JobStatusResult, JobsResource, type ListJobsPage, type ListJobsParams, type PolicyBlockHint, type RateJobResult, type SafetyBlockHint };

package/dist/entries/jobs.js

@@ -0,0 +1,4 @@
+import '../chunk-I3TYBAOX.js';
+export { JobsResource } from '../chunk-E5BM4BLO.js';
+//# sourceMappingURL=jobs.js.map
+//# sourceMappingURL=jobs.js.map

package/dist/entries/jobs.js.map

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

package/dist/entries/library.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+require('../chunk-5UQNMNUE.cjs');
+var chunk2DZWWIJ4_cjs = require('../chunk-2DZWWIJ4.cjs');
+
+
+
+Object.defineProperty(exports, "LibraryResource", {
+  enumerable: true,
+  get: function () { return chunk2DZWWIJ4_cjs.LibraryResource; }
+});
+//# sourceMappingURL=library.cjs.map
+//# sourceMappingURL=library.cjs.map

package/dist/entries/library.cjs.map

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

package/dist/entries/library.d.cts

@@ -0,0 +1,109 @@
+import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.cjs';
+import '@nodaro/shared/apps';
+import '@nodaro/shared/organizations';
+
+/**
+ * A media asset in the caller's library (`GET /v1/library`). Mirrors the route's
+ * camelCase row shape (`backend/src/routes/library.ts`), the source of truth —
+ * keep in sync if that response changes. Covers BOTH uploaded files and saved
+ * generations; `type` discriminates the media kind.
+ */
+interface LibraryAsset {
+    readonly id: string;
+    /** Media kind — filter the list with the same values via `type`. */
+    readonly type: "image" | "video" | "audio";
+    /** Display filename (server override or the original); `null` if unknown. */
+    readonly filename: string | null;
+    readonly mimeType: string | null;
+    readonly sizeBytes: number | null;
+    /** Public R2 URL of the asset. */
+    readonly url: string;
+    /** Generated thumbnail URL (images/video); `null` for audio or when absent. */
+    readonly thumbnailUrl: string | null;
+    readonly metadata: Record<string, unknown>;
+    /** True when promoted to the shared (admin) library. */
+    readonly isLibraryItem: boolean;
+    /** How the asset entered storage (e.g. "manual_upload" | "generated"). */
+    readonly uploadSource: string;
+    /**
+     * WHICH SURFACE the media came from — `"internal" | "mcp" | "app" | "cli" |
+     * "sdk" | "extension" | "web" | "api"`. Distinct from `uploadSource`, which
+     * says how it entered storage (uploaded vs generated), not who was calling.
+     * `null` on assets created before origin tracking existed — render as
+     * "unknown", don't infer.
+     */
+    readonly source: string | null;
+    /** Specific identity within `source` (origin host, `extension/<name>`, `sdk/<version>`, MCP client, app id). */
+    readonly sourceDetail: string | null;
+    /**
+     * The job that made the file, when known: `null` for an upload or once that
+     * job's history was deleted. Optional because servers before this field
+     * leave it out.
+     */
+    readonly jobId?: string | null;
+    readonly createdAt: string;
+}
+interface ListLibraryParams {
+    /** Filter by media kind; `"all"` (default) returns every kind. */
+    readonly type?: "all" | "image" | "video" | "audio";
+    /**
+     * Search words: only the assets whose filename contains every word (split
+     * on spaces, the first 5), ignoring case. Each word is matched as written
+     * (`%`, `_` and `*` are not wildcards); blank means no search; up to 200
+     * characters.
+     */
+    readonly q?: string;
+    /**
+     * @deprecated Use `q`. The original name of the filename search, still
+     * accepted; when both are given, `q` is sent and `search` is not.
+     */
+    readonly search?: string;
+    /** Page size, 1–100 (default 40). */
+    readonly limit?: number;
+    /** Opaque cursor from a prior page's `nextCursor` (fetches the next page). */
+    readonly cursor?: string;
+    /**
+     * `true` → EVERY asset the caller owns (the "Storage" view: uploads +
+     * generations, regardless of the in-library flag). `false` (default) → only
+     * assets explicitly saved to the library plus shared items (the in-editor
+     * Media Library picker).
+     */
+    readonly owned?: boolean;
+    /**
+     * Filter to media that originated from one surface (see
+     * {@link LibraryAsset.source}) — e.g. `"extension"` for everything a
+     * browser extension produced. Assets predating origin tracking have a null
+     * source and match no value, so they appear only when this is omitted.
+     */
+    readonly source?: "internal" | "mcp" | "app" | "cli" | "sdk" | "extension" | "web" | "api";
+}
+interface ListLibraryResult {
+    readonly data: LibraryAsset[];
+    /** Pass back as `cursor` for the next page; `null` when there are no more. */
+    readonly nextCursor: string | null;
+    /** Exact total (first page only — omitted on cursor-paged requests). */
+    readonly totalCount?: number;
+}
+/**
+ * Library — the caller's media assets (uploaded files + saved generations).
+ *
+ * Read surface over `GET /v1/library`: a cursor-paginated, type-filterable,
+ * filename-searchable list. This is the "bring from your media" source for
+ * pickers that also offer upload + in-production stills. Writes (saving a
+ * generation, promoting/removing) stay on their dedicated routes — not exposed
+ * here until a consumer needs them.
+ */
+declare class LibraryResource {
+    private client;
+    constructor(client: NodaroClientCore);
+    /**
+     * `GET /v1/library` → a page of the caller's media assets (newest first) plus
+     * a `nextCursor`. Pass the returned `nextCursor` back as `cursor` for the next
+     * page. Filter by `type` and search the filename with `q`; `owned: true`
+     * returns the full Storage set (uploads + generations), the default only
+     * library-saved + shared items.
+     */
+    list(params?: ListLibraryParams): Promise<ListLibraryResult>;
+}
+
+export { type LibraryAsset, LibraryResource, type ListLibraryParams, type ListLibraryResult };

package/dist/entries/library.d.ts

@@ -0,0 +1,109 @@
+import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.js';
+import '@nodaro/shared/apps';
+import '@nodaro/shared/organizations';
+
+/**
+ * A media asset in the caller's library (`GET /v1/library`). Mirrors the route's
+ * camelCase row shape (`backend/src/routes/library.ts`), the source of truth —
+ * keep in sync if that response changes. Covers BOTH uploaded files and saved
+ * generations; `type` discriminates the media kind.
+ */
+interface LibraryAsset {
+    readonly id: string;
+    /** Media kind — filter the list with the same values via `type`. */
+    readonly type: "image" | "video" | "audio";
+    /** Display filename (server override or the original); `null` if unknown. */
+    readonly filename: string | null;
+    readonly mimeType: string | null;
+    readonly sizeBytes: number | null;
+    /** Public R2 URL of the asset. */
+    readonly url: string;
+    /** Generated thumbnail URL (images/video); `null` for audio or when absent. */
+    readonly thumbnailUrl: string | null;
+    readonly metadata: Record<string, unknown>;
+    /** True when promoted to the shared (admin) library. */
+    readonly isLibraryItem: boolean;
+    /** How the asset entered storage (e.g. "manual_upload" | "generated"). */
+    readonly uploadSource: string;
+    /**
+     * WHICH SURFACE the media came from — `"internal" | "mcp" | "app" | "cli" |
+     * "sdk" | "extension" | "web" | "api"`. Distinct from `uploadSource`, which
+     * says how it entered storage (uploaded vs generated), not who was calling.
+     * `null` on assets created before origin tracking existed — render as
+     * "unknown", don't infer.
+     */
+    readonly source: string | null;
+    /** Specific identity within `source` (origin host, `extension/<name>`, `sdk/<version>`, MCP client, app id). */
+    readonly sourceDetail: string | null;
+    /**
+     * The job that made the file, when known: `null` for an upload or once that
+     * job's history was deleted. Optional because servers before this field
+     * leave it out.
+     */
+    readonly jobId?: string | null;
+    readonly createdAt: string;
+}
+interface ListLibraryParams {
+    /** Filter by media kind; `"all"` (default) returns every kind. */
+    readonly type?: "all" | "image" | "video" | "audio";
+    /**
+     * Search words: only the assets whose filename contains every word (split
+     * on spaces, the first 5), ignoring case. Each word is matched as written
+     * (`%`, `_` and `*` are not wildcards); blank means no search; up to 200
+     * characters.
+     */
+    readonly q?: string;
+    /**
+     * @deprecated Use `q`. The original name of the filename search, still
+     * accepted; when both are given, `q` is sent and `search` is not.
+     */
+    readonly search?: string;
+    /** Page size, 1–100 (default 40). */
+    readonly limit?: number;
+    /** Opaque cursor from a prior page's `nextCursor` (fetches the next page). */
+    readonly cursor?: string;
+    /**
+     * `true` → EVERY asset the caller owns (the "Storage" view: uploads +
+     * generations, regardless of the in-library flag). `false` (default) → only
+     * assets explicitly saved to the library plus shared items (the in-editor
+     * Media Library picker).
+     */
+    readonly owned?: boolean;
+    /**
+     * Filter to media that originated from one surface (see
+     * {@link LibraryAsset.source}) — e.g. `"extension"` for everything a
+     * browser extension produced. Assets predating origin tracking have a null
+     * source and match no value, so they appear only when this is omitted.
+     */
+    readonly source?: "internal" | "mcp" | "app" | "cli" | "sdk" | "extension" | "web" | "api";
+}
+interface ListLibraryResult {
+    readonly data: LibraryAsset[];
+    /** Pass back as `cursor` for the next page; `null` when there are no more. */
+    readonly nextCursor: string | null;
+    /** Exact total (first page only — omitted on cursor-paged requests). */
+    readonly totalCount?: number;
+}
+/**
+ * Library — the caller's media assets (uploaded files + saved generations).
+ *
+ * Read surface over `GET /v1/library`: a cursor-paginated, type-filterable,
+ * filename-searchable list. This is the "bring from your media" source for
+ * pickers that also offer upload + in-production stills. Writes (saving a
+ * generation, promoting/removing) stay on their dedicated routes — not exposed
+ * here until a consumer needs them.
+ */
+declare class LibraryResource {
+    private client;
+    constructor(client: NodaroClientCore);
+    /**
+     * `GET /v1/library` → a page of the caller's media assets (newest first) plus
+     * a `nextCursor`. Pass the returned `nextCursor` back as `cursor` for the next
+     * page. Filter by `type` and search the filename with `q`; `owned: true`
+     * returns the full Storage set (uploads + generations), the default only
+     * library-saved + shared items.
+     */
+    list(params?: ListLibraryParams): Promise<ListLibraryResult>;
+}
+
+export { type LibraryAsset, LibraryResource, type ListLibraryParams, type ListLibraryResult };

package/dist/entries/library.js

@@ -0,0 +1,4 @@
+import '../chunk-A3THLBFG.js';
+export { LibraryResource } from '../chunk-P6E4QDJN.js';
+//# sourceMappingURL=library.js.map
+//# sourceMappingURL=library.js.map

package/dist/entries/library.js.map

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

package/dist/entries/llm.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+require('../chunk-TRCENAIY.cjs');
+var chunkSS3B6PHT_cjs = require('../chunk-SS3B6PHT.cjs');
+
+
+
+Object.defineProperty(exports, "LlmResource", {
+  enumerable: true,
+  get: function () { return chunkSS3B6PHT_cjs.LlmResource; }
+});
+//# sourceMappingURL=llm.cjs.map
+//# sourceMappingURL=llm.cjs.map

package/dist/entries/llm.cjs.map

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

package/dist/entries/llm.d.cts

@@ -0,0 +1,98 @@
+import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.cjs';
+import '@nodaro/shared/apps';
+import '@nodaro/shared/organizations';
+
+/**
+ * Structured LLM output — `POST /v1/llm/structured` and its asynchronous
+ * twin. The platform supplies the model lane, forced JSON-Schema output with
+ * validation and error-fed retries, the job row and the credit lifecycle; the
+ * caller supplies its own system prompt and schema (an app-owned vocabulary
+ * the platform cannot know — Nodaro Studio's production plan is the first).
+ */
+interface LlmStructuredInput {
+    /** The system prompt (≤ 100,000 chars). */
+    system: string;
+    /** The user turn (1–100,000 chars). */
+    input: string;
+    /** A JSON Schema OBJECT (`type: "object"`, ≤ 64 KB, ≤ 20 levels) in the
+     *  keyword subset the server converts — see the API guide. */
+    jsonSchema: Record<string, unknown>;
+    /** Names the forced-output tool the provider sees (≤ 64 chars). */
+    schemaName?: string;
+    llmModel?: string;
+    reasoningEffort?: string;
+    /** Invalid answers fed back with their error before the call fails (0–3, default 2). */
+    maxRetries?: number;
+    /** Your app's slug — attribution only; `jobs.list({ origin })` finds the rows. */
+    origin?: string;
+    advancedMode?: boolean;
+    temperature?: number;
+    maxTokens?: number;
+}
+interface LlmStructuredResult<T = unknown> {
+    jobId: string;
+    output: T;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+interface LlmStructuredJobInput extends LlmStructuredInput {
+    /** Display label stored on the job (≤ 120 chars) — a run list's row title. */
+    label?: string;
+    /** Draft FROM this video: the platform analyzes it first (`POST
+     *  /v1/video-analysis`, a separate job you own) and appends the analysis
+     *  to `input` before the LLM call. */
+    videoUrl?: string;
+    /** Analysis options, handed to the analysis route unchanged (its tiers). */
+    videoAnalysis?: {
+        llmModel?: string;
+        selectionMode?: "choose" | "combine";
+    };
+    /** Draft from THIS finished `video-analysis` job of yours instead of
+     *  analyzing `videoUrl` again: no second analysis, no second analysis
+     *  charge — a retry after a failed draft, another model, different
+     *  notes. `videoUrl` may still ride beside it as the record of the source.
+     *  422 when the job is not yours, does not exist, or is not a finished,
+     *  readable video analysis (`analysis_not_found` / `not_analysis` /
+     *  `analysis_failed` / `analysis_not_ready` / `invalid_analysis` — never a
+     *  404, which means the route itself is absent). Not combinable with
+     *  `videoAnalysis`. */
+    analysisJobId?: string;
+}
+/** `output_data` of an `llm-structured` job as it progresses: `stage` while
+ *  running (`analyzing` only for movie runs), then the result. */
+interface LlmStructuredJobOutput<T = unknown> {
+    stage?: "analyzing" | "drafting";
+    output?: T;
+    inputTokens?: number;
+    outputTokens?: number;
+    analysisJobId?: string;
+    analysisCredits?: number;
+}
+declare class LlmResource {
+    private client;
+    constructor(client: NodaroClientCore);
+    /**
+     * Synchronous forced-schema completion (`POST /v1/llm/structured`). A call
+     * can run several minutes — longer than the client's default 60 s
+     * `timeoutMs`; construct the client with a larger `timeoutMs` for this
+     * call, or use {@link LlmResource.structuredJob}.
+     */
+    structured<T = unknown>(input: LlmStructuredInput): Promise<LlmStructuredResult<T>>;
+    /**
+     * The same call as a job (`POST /v1/llm/structured/jobs`): answers `{ jobId }`
+     * at once. Poll `jobs.getStatus(jobId)` — `output_data` is an
+     * {@link LlmStructuredJobOutput}; `error_message` says why a run failed.
+     * `jobs.list({ type: "llm-structured", origin })` finds every run later.
+     * Throws `NotFoundError` on a platform that predates the route. An instance
+     * that proxies its LLM calls to nodaro.ai answers `503 provider_unavailable`
+     * permanently — the SDK surfaces that as a generic `NodaroError` with the
+     * same code; treat it as unavailable here, not as transient.
+     */
+    structuredJob(input: LlmStructuredJobInput): Promise<{
+        jobId: string;
+    }>;
+}
+
+export { LlmResource, type LlmStructuredInput, type LlmStructuredJobInput, type LlmStructuredJobOutput, type LlmStructuredResult };