@nodaro/sdk 2.29.0 → 2.32.0

package/dist/entries/gallery.d.cts

@@ -0,0 +1,85 @@
+import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.cjs';
+import '@nodaro/shared/apps';
+import '@nodaro/shared/organizations';
+
+type GalleryMediaType = "image" | "video" | "audio";
+/**
+ * One gallery card (`GET /v1/gallery`): a completed generation with media.
+ * Mirrors the route's item shape — never whose it is.
+ */
+interface GalleryItem {
+    /** The job id — pass it to `toggleFavorite`, or `client.jobs.get`. */
+    readonly id: string;
+    readonly type: GalleryMediaType;
+    /** The kind of job that made it (`generate-image`, `image-to-video`, …). */
+    readonly jobName: string;
+    readonly outputUrl: string;
+    readonly thumbnailUrl: string | null;
+    /** When the job completed. */
+    readonly createdAt: string;
+    readonly prompt: string | null;
+    readonly model: string | null;
+    /** A private 720p Preview render (Apply EDL at proxy quality). Present only when true. */
+    readonly preview?: true;
+}
+interface BrowseGalleryParams {
+    /** Only this media kind. */
+    readonly type?: GalleryMediaType;
+    /**
+     * Only this person's work. Your own id lists your own items, private ones
+     * included; anyone else's lists their public ones.
+     */
+    readonly userId?: string;
+    /**
+     * With YOUR OWN `userId` (from `client.me()`): only the items you
+     * favorited. Anyone else's favorites are refused — `UnauthorizedError`
+     * without a token, `ForbiddenError` with another person's `userId` or none.
+     */
+    readonly favoritesOnly?: boolean;
+    /** Page size, 1–50 (default 20). */
+    readonly limit?: number;
+    /** The previous page's `nextCursor`. */
+    readonly cursor?: string;
+}
+interface GalleryPage {
+    readonly data: GalleryItem[];
+    /** Pass back as `cursor` for the next page; `null` on the last one. */
+    readonly nextCursor: string | null;
+    /** Counted on the first page only (no cursor). */
+    readonly totalCount?: number;
+}
+/** What {@link GalleryResource.toggleFavorite} answers: whether the job is now a favorite. */
+interface ToggleFavoriteResult {
+    readonly favorited: boolean;
+}
+/**
+ * Gallery — the public gallery of completed generations, and your favorites.
+ *
+ * A favorite is a bookmark on a generation: one of your own, or anyone's in
+ * the public gallery. Your jobs carry it as `Job.favorited`, and
+ * `client.jobs.list({ favorited: true })` lists them. Not available on a
+ * deployment that hides the gallery (the routes answer 404 there).
+ */
+declare class GalleryResource {
+    private client;
+    constructor(client: NodaroClientCore);
+    /**
+     * `GET /v1/gallery` → a page of the public gallery, newest first (no auth
+     * needed), or one person's work with `userId`.
+     */
+    browse(params?: BrowseGalleryParams): Promise<GalleryPage>;
+    /**
+     * Favorite a job, or un-favorite it when it already is
+     * (`POST /v1/gallery/favorite`). You can favorite your own jobs and public
+     * ones; another person's private job is a `NotFoundError`. OAuth apps need
+     * the `assets:write` scope.
+     */
+    toggleFavorite(jobId: string): Promise<ToggleFavoriteResult>;
+    /**
+     * Your favorited job ids, newest first (`GET /v1/gallery/favorites`). OAuth
+     * apps need the `assets:read` or `jobs:read` scope.
+     */
+    favorites(): Promise<string[]>;
+}
+
+export { type BrowseGalleryParams, type GalleryItem, type GalleryMediaType, type GalleryPage, GalleryResource, type ToggleFavoriteResult };

package/dist/entries/gallery.d.ts

@@ -0,0 +1,85 @@
+import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.js';
+import '@nodaro/shared/apps';
+import '@nodaro/shared/organizations';
+
+type GalleryMediaType = "image" | "video" | "audio";
+/**
+ * One gallery card (`GET /v1/gallery`): a completed generation with media.
+ * Mirrors the route's item shape — never whose it is.
+ */
+interface GalleryItem {
+    /** The job id — pass it to `toggleFavorite`, or `client.jobs.get`. */
+    readonly id: string;
+    readonly type: GalleryMediaType;
+    /** The kind of job that made it (`generate-image`, `image-to-video`, …). */
+    readonly jobName: string;
+    readonly outputUrl: string;
+    readonly thumbnailUrl: string | null;
+    /** When the job completed. */
+    readonly createdAt: string;
+    readonly prompt: string | null;
+    readonly model: string | null;
+    /** A private 720p Preview render (Apply EDL at proxy quality). Present only when true. */
+    readonly preview?: true;
+}
+interface BrowseGalleryParams {
+    /** Only this media kind. */
+    readonly type?: GalleryMediaType;
+    /**
+     * Only this person's work. Your own id lists your own items, private ones
+     * included; anyone else's lists their public ones.
+     */
+    readonly userId?: string;
+    /**
+     * With YOUR OWN `userId` (from `client.me()`): only the items you
+     * favorited. Anyone else's favorites are refused — `UnauthorizedError`
+     * without a token, `ForbiddenError` with another person's `userId` or none.
+     */
+    readonly favoritesOnly?: boolean;
+    /** Page size, 1–50 (default 20). */
+    readonly limit?: number;
+    /** The previous page's `nextCursor`. */
+    readonly cursor?: string;
+}
+interface GalleryPage {
+    readonly data: GalleryItem[];
+    /** Pass back as `cursor` for the next page; `null` on the last one. */
+    readonly nextCursor: string | null;
+    /** Counted on the first page only (no cursor). */
+    readonly totalCount?: number;
+}
+/** What {@link GalleryResource.toggleFavorite} answers: whether the job is now a favorite. */
+interface ToggleFavoriteResult {
+    readonly favorited: boolean;
+}
+/**
+ * Gallery — the public gallery of completed generations, and your favorites.
+ *
+ * A favorite is a bookmark on a generation: one of your own, or anyone's in
+ * the public gallery. Your jobs carry it as `Job.favorited`, and
+ * `client.jobs.list({ favorited: true })` lists them. Not available on a
+ * deployment that hides the gallery (the routes answer 404 there).
+ */
+declare class GalleryResource {
+    private client;
+    constructor(client: NodaroClientCore);
+    /**
+     * `GET /v1/gallery` → a page of the public gallery, newest first (no auth
+     * needed), or one person's work with `userId`.
+     */
+    browse(params?: BrowseGalleryParams): Promise<GalleryPage>;
+    /**
+     * Favorite a job, or un-favorite it when it already is
+     * (`POST /v1/gallery/favorite`). You can favorite your own jobs and public
+     * ones; another person's private job is a `NotFoundError`. OAuth apps need
+     * the `assets:write` scope.
+     */
+    toggleFavorite(jobId: string): Promise<ToggleFavoriteResult>;
+    /**
+     * Your favorited job ids, newest first (`GET /v1/gallery/favorites`). OAuth
+     * apps need the `assets:read` or `jobs:read` scope.
+     */
+    favorites(): Promise<string[]>;
+}
+
+export { type BrowseGalleryParams, type GalleryItem, type GalleryMediaType, type GalleryPage, GalleryResource, type ToggleFavoriteResult };

package/dist/entries/gallery.js

@@ -0,0 +1,4 @@
+import '../chunk-C22RJDW3.js';
+export { GalleryResource } from '../chunk-JDEZHITT.js';
+//# sourceMappingURL=gallery.js.map
+//# sourceMappingURL=gallery.js.map

package/dist/entries/gallery.js.map

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

package/dist/entries/jobs.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+require('../chunk-EHRWTYGR.cjs');
+var chunk3QBH2VE2_cjs = require('../chunk-3QBH2VE2.cjs');
+
+
+
+Object.defineProperty(exports, "JobsResource", {
+  enumerable: true,
+  get: function () { return chunk3QBH2VE2_cjs.JobsResource; }
+});
+//# sourceMappingURL=jobs.cjs.map
+//# sourceMappingURL=jobs.cjs.map

package/dist/entries/jobs.cjs.map

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

package/dist/entries/jobs.d.cts

@@ -0,0 +1,252 @@
+import { N as NodaroClientCore } from '../developer-apps-zSQXWmEG.cjs';
+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 };