needle-cloud 2.4.6 → 2.5.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _logto_browser from '@logto/browser';
 import { UserScope } from '@logto/browser';
+import * as _needle_tools_cloud_sdk_types from '@needle-tools/cloud-sdk/types';
 import Stripe from 'stripe';
 
 /**
@@ -35,9 +36,9 @@ type LogtoUserCustomData$1 = {
 declare namespace Auth {
     /** @param {boolean} _debug */
     function setDebug(_debug: boolean): void;
-    let baseUrl: string;
-    let redirectUri: string;
-    let postSignOutRedirectUri: string;
+    let baseUrl: any;
+    let redirectUri: any;
+    let postSignOutRedirectUri: any;
     /**
      * Register a callback to be called when the authentication state changes
      * @param {Function} callback - The callback to register
@@ -126,15 +127,7 @@ type AuthInitOpts = {
     debug?: boolean;
 };
 
-/**
- * Basic web component for login/logout
- */
-declare class NeedleLoginButton extends HTMLButtonElement {
-    connectedCallback(): void;
-    __unsubscribeOnChange: Function;
-    disconnectedCallback(): void;
-    __update(): void;
-}
+declare let NeedleLoginButton: any;
 
 /**
  * The authentication token
@@ -291,6 +284,23 @@ type AIChatSyncResponse = {
     chat_url?: string,
 }
 
+/** Options for a one-shot completion (POST /v1/ai/completions). */
+type AICompletionOptions = {
+    /** System prompt. Counts toward the 32k char input cap together with the message. */
+    system?: string,
+    /** Requested output ceiling in tokens; the server clamps it. */
+    max_tokens?: number,
+    signal?: AbortSignal,
+}
+
+/** Response of a one-shot completion (POST /v1/ai/completions). */
+type AICompletionResponse = {
+    text: string,
+    /** The model that served the completion (server-resolved). */
+    model: string,
+    token_usage: AiTokenUsageInfo,
+}
+
 /**
  * Discriminated union for events yielded by the SSE chat stream.
  *
@@ -385,6 +395,15 @@ type ToolDefinition$1 = {
     name: string,
     description: string,
     inputSchema: Record<string, any>,
+    /**
+     * What the tool TOUCHES — drives the server's origin gate (#127):
+     * `scene` (the inspected scene; offered on any page), `local` (the user's
+     * machine — files/exec) and `account` (the cloud account) are withheld
+     * from chats running on untrusted origins. Omitted = the server falls
+     * back to judging by the registering source; anything beyond the scene
+     * should declare itself.
+     */
+    capability?: "scene" | "local" | "account",
 }
 
 /**
@@ -417,6 +436,23 @@ type ToolRequestOutcome = {
     images?: Array<{ url: string, detail?: ImageDetail }>,
 }
 
+/** Options for `connectToolWebSocket()`. */
+/**
+ * The minimal WebSocket surface `connectToolWebSocket` uses — small on purpose so a
+ * relayed/bridged transport is easy to implement (e.g. one whose real socket lives in
+ * a browser-extension service worker, to escape the host page's CSP).
+ */
+type WebSocketLike = {
+    /** WebSocket.OPEN (1) is the only state compared. */
+    readonly readyState: number,
+    send(data: string): void,
+    close(code?: number, reason?: string): void,
+    onopen: ((ev?: any) => any) | null,
+    onmessage: ((ev: { data: any }) => any) | null,
+    onclose: ((ev?: any) => any) | null,
+    onerror: ((ev?: any) => any) | null,
+}
+
 
 // ─── ChatSession Types ──────────────────────────────────────────────
 
@@ -447,6 +483,11 @@ type ChatSessionOptions$1 = {
     toolReadyTimeout?: number,
     /** Use personal chat context instead of team. Defaults to false (team). */
     personal?: boolean,
+    /**
+     * How the tool socket is opened — see {@link ToolConnectionOptions.createWebSocket}.
+     * Defaults to `new WebSocket`; the chrome extension passes a SW-relayed socket.
+     */
+    createWebSocket?: (url: string) => WebSocketLike,
 }
 
 /**
@@ -493,6 +534,14 @@ type ChatSessionHandle$1 = {
     interruptChat(slug: string): Promise<void>,
     /** Read chat history for a slug. */
     readChat(slug: string, options?: { offset?: number, limit?: number }): Promise<AIChatGETResponse>,
+    /**
+     * Reattach to an ACTIVE generation for this chat (after a dropped SSE
+     * connection). The server keeps generating and replays every buffered
+     * event from the start, then streams live. Returns `null` when no
+     * generation is running — the caller decides between resending (nothing
+     * arrived) and reading the finished answer via `readChat`.
+     */
+    reconnectChat(slug: string): Promise<AsyncGenerator<ChatStreamEvent> | null>,
     /** List recent chats. */
     listChats(): Promise<RecentChatsResponse$1>,
     /**
@@ -542,8 +591,32 @@ type ChatSessionSendOptions$1 = {
  */
 /**
  * @param {Array<Filelike>} files
- * @param {{org?:string|null} & { name?:string, abort?:AbortSignal, authToken?:string|null }} opts
- * @returns {Promise<{error:string} | {job_id:string, content_id:string, url?:string | null, skipped?:boolean}>}
+ * @param {{org?:string|null} & { name?:string, abort?:AbortSignal, authToken?:string|null, type?:"upload"|"deployment",
+ *   content_id?:string, thumbnail?:File,
+ *   metadata?:import("@needle-tools/cloud-sdk/types").JobMetadata }} opts
+ *   `metadata` records where this upload came from — the change that produced it, what
+ *   built it, and anything else you want to keep with it. It shows on the version in
+ *   Needle Cloud, and is visible to your team only. `source` and `runner` are open
+ *   shapes, and you can add your own fields alongside them:
+ *
+ *     metadata: {
+ *         source: { type: "unity", id: sceneGuid, label: "MainScene.unity" },
+ *         client: { name: "my-app", version: "1.2.3" },
+ *     }
+ *
+ *   Up to 8 KB in total; `source.message` up to 200 characters. Send a display name
+ *   rather than an email address — email fields are rejected.
+ *   `thumbnail` is set as the content
+ *   item's picture after the upload lands — pass your own render (a canvas blob, a
+ *   screenshot) when your app knows better than a generated preview what the asset looks
+ *   like. JPEG/PNG/WebP up to 5 MB. A thumbnail that fails to upload does NOT fail the
+ *   upload: the result carries `thumbnail_error` instead.
+ *   `content_id` targets an EXISTING content item:
+ *   the upload lands as a new version of it (deployment redeploys). It never
+ *   CREATES an item under that id — an unknown/foreign id is a 404 from
+ *   upload/begin. Without it, the server mints an identifier (or reuses an
+ *   org-scoped item whose NAME matches — the CLI redeploy behavior).
+ * @returns {Promise<{error:string} | {job_id:string, content_id:string, url?:string | null, skipped?:boolean, thumbnail_error?:string}>}
  */
 declare function uploadFiles(files: Array<Filelike>, opts: {
     org?: string | null;
@@ -551,6 +624,10 @@ declare function uploadFiles(files: Array<Filelike>, opts: {
     name?: string;
     abort?: AbortSignal;
     authToken?: string | null;
+    type?: "upload" | "deployment";
+    content_id?: string;
+    thumbnail?: File;
+    metadata?: _needle_tools_cloud_sdk_types.JobMetadata;
 }): Promise<{
     error: string;
 } | {
@@ -558,6 +635,7 @@ declare function uploadFiles(files: Array<Filelike>, opts: {
     content_id: string;
     url?: string | null;
     skipped?: boolean;
+    thumbnail_error?: string;
 }>;
 type Filelike = {
     name: string;
@@ -728,6 +806,17 @@ declare function listChats(opts?: ChatAuthOpts): Promise<RecentChatsResponse>;
  * @returns {Promise<import("@needle-tools/cloud-sdk/types/api.ai.js").ChatSessionHandle>}
  */
 declare function createChatSession(options?: ChatSessionOptions$1, authOpts?: ChatAuthOpts): Promise<ChatSessionHandle$1>;
+/**
+ * One-shot AI completion — a single request/response with no chat session,
+ * history or tools (POST /v1/ai/completions). For small tasks like generating
+ * a revision description. Billed to the org's monthly AI token quota.
+ *
+ * @param {string} message
+ * @param {import("@needle-tools/cloud-sdk/types/api.ai.js").AICompletionOptions} [options]
+ * @param {ChatAuthOpts} [authOpts]
+ * @returns {Promise<import("@needle-tools/cloud-sdk/types/api.ai.js").AICompletionResponse>}
+ */
+declare function aiComplete(message: string, options?: AICompletionOptions, authOpts?: ChatAuthOpts): Promise<AICompletionResponse>;
 type ChatAuthOpts = {
     org?: string;
     authToken?: string;
@@ -784,7 +873,7 @@ type JobModel = {
     /**
      * Parameters is a JSON object that contains the parameters for the job
      */
-    parameters?: UploadParameters | OptimizationParameters | AiMaterialParameters | HdriCompressParameters | SplatCompressParameters | null;
+    parameters?: UploadParameters | OptimizationParameters | AiMaterialParameters | Ai3dAssetParameters | HdriCompressParameters | SplatCompressParameters | null;
 
     triggered_by?: TriggerType;
     /**
@@ -804,7 +893,7 @@ type JobModel = {
     error?: string | null;
 };
 
-type JobType = "upload" | "conversion" | "optimization" | "deployment" | "ai-material" | "hdri-compress" | "splat-compress" | (string & {});
+type JobType = "upload" | "conversion" | "optimization" | "deployment" | "ai-material" | "ai-3d-asset" | "hdri-compress" | "splat-compress" | (string & {});
 type JobStatus = "new" | "pending" | "running" | "completed" | "failed" | "canceled" | "stalled";
 declare type OptimizationParameters = {
     /** The job identifier to optimize (injected by createJob) */
@@ -864,6 +953,87 @@ declare type AiMaterialParameters = {
     seed?: number,
 }
 
+/** Quality tier for 3D asset generation.
+ *  - `draft` — fastest and cheapest. Geometry with a base color texture.
+ *  - `standard` — adds physically based material maps (metallic, roughness, normal).
+ *    Requires a commercial plan. */
+declare type Asset3dQuality = "draft" | "standard";
+
+/** Parameters for the `ai-3d-asset` job — generates a 3D model (GLB) from a text prompt. */
+declare type Ai3dAssetParameters = {
+    /** The job identifier (injected by createJob) */
+    job_identifier?: string,
+    /** Describe the object you want. One object, not a scene — e.g.
+     *  "a weathered wooden crate with iron bands". Max 2000 characters. */
+    prompt: string,
+    /** A richer description derived from `prompt`, filled in for you and used for the
+     *  actual generation. Set by the server — requests that include it are rejected. */
+    expanded_prompt?: string,
+    /** Quality tier (default: `standard`). */
+    quality?: Asset3dQuality,
+    /** Target polygon count. Leave unset to let the generator choose.
+     *  Accepted range: 40000–1500000. */
+    face_count?: number,
+    /** Optional idempotency key. Two requests with the same prompt and the same key
+     *  return the same asset instead of generating a second one. When omitted, every
+     *  request generates a new asset. */
+    request_key?: string,
+    /** Reserved — image-guided generation is not available yet and passing this is
+     *  rejected. Present so adding it later does not change this type. */
+    image_url?: string,
+    /** Reserved — see `image_url`. */
+    image_urls?: string[],
+}
+
+
+
+/**
+ * Provenance for a job — what produced it. Optional on job creation; shown on the version
+ * row in the Cloud UI so an asset answers "where did this come from?".
+ *
+ * Deliberately NOT git-shaped. `source` names whatever system the input came from and
+ * `runner` whatever executed it; git is one `source.type` among many, and a DCC export or
+ * a hosted runner fits the same slots. The generic fields (`label`, `author`, `message`,
+ * `url`) are what the UI renders, so a producer nobody has written yet still displays
+ * something useful.
+ */
+declare type JobMetadata = {
+    /** Where the INPUT came from. */
+    source?: {
+        /** `"git"`, `"unity"`, `"blender"`, … — open on purpose. */
+        type?: string,
+        /** Stable id within that system: a commit sha, an asset guid, a document id. */
+        id?: string,
+        /** Short label for display when the specific fields don't tell the story. */
+        label?: string,
+        /** Link back to it — the commit, the asset page, the document. */
+        url?: string,
+        /** Display name of whoever authored the change. Email addresses are rejected. */
+        author?: string,
+        /** One short line: a commit subject, an export note. Max 200 characters. */
+        message?: string,
+        /** System-specific extras (branch, tag, repository, project, scene, …). */
+        [key: string]: unknown,
+    },
+    /** What EXECUTED the job — a CI runner, a workstation, a service. */
+    runner?: {
+        /** `"github-actions"`, `"gitlab-ci"`, `"local"`, … — open on purpose. */
+        type?: string,
+        /** Run id within that system. */
+        id?: string,
+        /** Link to the run. */
+        url?: string,
+        /** Who or what set it off. */
+        actor?: string,
+        /** `"push"`, `"pull_request"`, `"manual"`, `"schedule"`, … */
+        event?: string,
+    },
+    /** What talked to the API. */
+    client?: { name?: string, version?: string },
+    /** Your own keys. */
+    [key: string]: unknown,
+}
+
 // #region Tone mapping
 
 /**
@@ -1146,6 +1316,14 @@ type ContentVersion = {
 
     /** Derived variants (optimizations, deployments, AI generations) */
     variants: ContentVariant[],
+
+    /**
+     * Where this version came from — the change that produced it, and what ran it.
+     *
+     * Only present when whoever created it supplied provenance, so treat it as optional
+     * everywhere. Visible to your team only; it is never part of a public listing.
+     */
+    metadata?: JobMetadata,
 } & ContentProcessingState
 
 /** A derived variant produced from an upload (optimization, deployment, etc). */
@@ -1327,6 +1505,10 @@ type ContentListResponse = {
 // change on one side, decide whether the other side needs the same change.
 // Public is intentionally slimmer — no internal IDs (user, updated_by, etc.),
 // no per-file enumeration, no labels/variants/processing-state.
+//
+// `metadata` (provenance) is DELIBERATELY absent here and must stay absent: it carries
+// branch names, CI run urls and author names. Adding it to a public type would leak all
+// of that to anonymous callers. See plans/job-metadata.md.
 
 /** One version of a public content item.
  *  Each version exposes a single entrypoint URL — relative file references
@@ -1425,6 +1607,36 @@ type ListPublicContentResponse = {
     /** Cursor to fetch the next page; omitted when there are no more items. */
     next_cursor?: string;
 };
+// #endregion
+
+
+// #region Content mutations — PATCH, DELETE, restore
+
+/** Request body for PATCH /v1/content/:identifier */
+type UpdateContentRequestBody = {
+    /** Content title (1-255 chars) */
+    title?: string;
+    /** Content description (max 512 chars) */
+    description?: string;
+    /** Set or clear password protection (null = remove). Requires commercial license. */
+    password?: string | null;
+    /** Comma-separated tags (max 512 chars total, each tag < 50 chars, max 40 tags) */
+    tags?: string | null;
+    /** Public visibility — when true, content is readable by anyone (authenticated or not)
+     *  via the public discovery API. UI for setting this is currently gated by a frontend
+     *  feature flag; the API itself does not enforce additional restrictions. */
+    is_public?: boolean;
+    /** Viewer presentation settings (lighting, tone mapping, background).
+     *  Pass `null` to clear; omit to leave unchanged. */
+    presentation?: PresentationV1 | null;
+    /** Thumbnail upload request — server returns presigned URL in response */
+    upload_thumbnail?: {
+        name: string;
+        content_size: number;
+        content_type: string;
+        content_md5: string;
+    };
+};
 
 /**
  * List publicly discoverable content items on Needle Cloud.
@@ -1490,6 +1702,91 @@ declare function getContent(identifier: string, opts?: {
     org?: string;
     authToken?: string;
 }): Promise<GetContentDetailResponse>;
+/**
+ * Update a content item's metadata, and optionally set its thumbnail.
+ *
+ * Pass a `thumbnail` File — a canvas render, a screenshot, whatever your app produced —
+ * and it is uploaded and set as the item's picture. Useful when the client knows better
+ * than a generated preview what the asset actually looks like. JPEG, PNG or WebP, up to
+ * 5 MB.
+ *
+ * Only the fields you pass are changed; anything you leave out stays as it is. Note that
+ * a field you DO pass replaces the stored value outright — there is no merging, and
+ * (today) no way to undo it.
+ *
+ * Visibility settings (password protection, public listing) are deliberately not
+ * accepted here — see {@link REFUSED_FIELDS}.
+ *
+ * Auth: uses the browser session (`Auth.requestAccessToken(org)`) unless an explicit
+ * `authToken` is passed — hosts that manage tokens themselves pass one and skip the
+ * Auth singleton.
+ *
+ * @param {string} identifier - The content item identifier
+ * @param {{ thumbnail?: File, org?: string, authToken?: string }
+ *   & Omit<import("@needle-tools/cloud-sdk/types/api.content").UpdateContentRequestBody,
+ *          "upload_thumbnail" | "password" | "is_public">} data
+ * @returns {Promise<{ success: boolean }>}
+ *
+ * @example
+ *   import { updateContent } from "needle-cloud";
+ *   await updateContent("abc123", { title: "Baked Crate", tags: "baked,crate" });
+ *
+ * @example
+ *   // Use your own render as the thumbnail
+ *   const blob = await new Promise(r => canvas.toBlob(r, "image/png"));
+ *   const thumbnail = new File([blob], "preview.png", { type: "image/png" });
+ *   await updateContent("abc123", { thumbnail });
+ */
+declare function updateContent(identifier: string, data: {
+    thumbnail?: File;
+    org?: string;
+    authToken?: string;
+} & Omit<UpdateContentRequestBody, "upload_thumbnail" | "password" | "is_public">): Promise<{
+    success: boolean;
+}>;
+
+/**
+ * Generate a 3D model from a text prompt and wait until it is ready.
+ *
+ * Describe a single object — "a weathered wooden crate with iron bands" — rather than
+ * a scene. The prompt is enriched server-side before generation, so short prompts are
+ * fine. Generating a 3D asset requires a paid plan and counts against the plan's
+ * monthly allowance.
+ *
+ * Resolves once the model is ready and returns it as a GLB you can hand straight to a
+ * loader, or save. Pass `download: false` if you only want the job and will fetch the
+ * result later.
+ *
+ * Auth: uses the browser session (`Auth.requestAccessToken(org)`) unless an explicit
+ * `authToken` is passed — hosts that manage tokens themselves pass one and skip the
+ * Auth singleton.
+ *
+ * @param {import("@needle-tools/cloud-sdk/types").Ai3dAssetRequestParameters
+ *   & import("@needle-tools/cloud-sdk/types").Generate3dAssetOptions
+ *   & { org?: string, authToken?: string, signal?: AbortSignal }} opts
+ * @returns {Promise<{ job: import("@needle-tools/cloud-sdk/types").JobModel, glb?: ArrayBuffer, filename?: string }>}
+ *
+ * @example
+ *   import { generate3dAsset } from "needle-cloud";
+ *   const { glb, filename } = await generate3dAsset({ prompt: "a wooden crate" });
+ *
+ * @example
+ *   // Higher quality, with progress
+ *   const { glb } = await generate3dAsset({
+ *       prompt: "a brass telescope on a tripod",
+ *       quality: "standard",
+ *       onProgress: ({ status, progress }) => console.log(status, progress),
+ *   });
+ */
+declare function generate3dAsset(opts: _needle_tools_cloud_sdk_types.Ai3dAssetRequestParameters & _needle_tools_cloud_sdk_types.Generate3dAssetOptions & {
+    org?: string;
+    authToken?: string;
+    signal?: AbortSignal;
+}): Promise<{
+    job: _needle_tools_cloud_sdk_types.JobModel;
+    glb?: ArrayBuffer;
+    filename?: string;
+}>;
 
 /**
  * @internal Needle editor cloud projects — versioned revisions of OPAQUE
@@ -1541,6 +1838,32 @@ interface ProjectRevisionInfo {
     actor: string;
     /** ISO timestamp */
     timestamp: string | null;
+    /** hash of the revision's `.needle/thumbnail.jpg` manifest entry — fetch
+     * via blobs/download for a per-revision preview; null when the revision
+     * carried no thumbnail */
+    thumbnail?: string | null;
+    /** byte length of the document blob — revisions LISTING only (null when
+     * the blob is unexpectedly absent) */
+    size?: number | null;
+    /** total bytes of the folder files riding this revision (manifest sum;
+     * blobs are shared/deduped — footprint, not storage cost) */
+    filesSize?: number | null;
+    /** short human handle ("client-review") — user-editable via revisions/update */
+    label?: string | null;
+    /** what changed in this revision — user-written (a generated default may
+     * fill it later; user text wins by being set) */
+    description?: string | null;
+}
+
+/** PARTIAL revision metadata update: absent = keep, null = clear */
+interface UpdateProjectRevisionRequest {
+    /** project id (public handle) */
+    project: string;
+    revision: number;
+    /** 1-64 characters, or null to clear */
+    label?: string | null;
+    /** max 4000 characters, or null to clear */
+    description?: string | null;
 }
 
 interface CreateProjectResponse {
@@ -1756,18 +2079,24 @@ declare function checkProjectBlobs(hashes: readonly string[], opts?: {
     missing: string[];
 }>;
 /**
- * @internal Presigned PUT url for one file blob.
+ * @internal Presigned PUT url for one file blob. A provided filename rides
+ * the storage metadata; the response's `contentType` (derived from it) is
+ * signed into the url — the PUT must send that exact Content-Type header.
  * @param {string} hash
  * @param {number} size
  * @param {{ org?: string, authToken?: string }} [opts]
- * @returns {Promise<{ url: string, key: string }>}
+ * @param {{ filename?: string }} [meta]
+ * @returns {Promise<{ url: string, key: string, contentType?: string }>}
  */
 declare function requestProjectBlobUpload(hash: string, size: number, opts?: {
     org?: string;
     authToken?: string;
+}, meta?: {
+    filename?: string;
 }): Promise<{
     url: string;
     key: string;
+    contentType?: string;
 }>;
 /**
  * @internal Complete (HEAD-verify + index) an uploaded file blob.
@@ -1807,6 +2136,90 @@ declare function listProjectRevisions(project: string, opts?: {
 }): Promise<{
     revisions: ProjectRevisionInfo[];
 }>;
+/**
+ * @internal Label/description a revision — partial patch (absent = keep, null = clear).
+ * @param {import("@needle-tools/cloud-sdk/types/api.projects").UpdateProjectRevisionRequest} request
+ * @param {{ org?: string, authToken?: string }} [opts]
+ * @returns {Promise<import("@needle-tools/cloud-sdk/types/api.projects").ProjectRevisionInfo>}
+ */
+declare function updateProjectRevision(request: UpdateProjectRevisionRequest, opts?: {
+    org?: string;
+    authToken?: string;
+}): Promise<ProjectRevisionInfo>;
+/**
+ * @internal Deploy attempts of a project: `contentId` = the CURRENT deployment
+ * identity (newest completed attempt), `attempts` = per-revision history
+ * (status/error from the upload job, url = per-job site link).
+ * @param {string} project
+ * @param {{ org?: string, authToken?: string }} [opts]
+ */
+declare function getProjectDeployments(project: string, opts?: {
+    org?: string;
+    authToken?: string;
+}): Promise<any>;
+/**
+ * @internal Record a deploy attempt (write-back after uploadFiles returned the
+ * content_id/job_id). Idempotent per job_id.
+ * @param {{ project: string, content_id: string, job_id: string, revision?: number | null }} request
+ * @param {{ org?: string, authToken?: string }} [opts]
+ */
+declare function recordProjectDeployment(request: {
+    project: string;
+    content_id: string;
+    job_id: string;
+    revision?: number | null;
+}, opts?: {
+    org?: string;
+    authToken?: string;
+}): Promise<any>;
+/**
+ * @internal Promote a pushed project asset to a content item — server-side,
+ * bytes stay in the org blob pool and are served in place; the promotion row
+ * marks the asset used/exposed. Path = asset identity (re-promote versions
+ * the same item; unchanged returns type "exists").
+ * @param {{ project: string, path: string, revision?: number | null }} request
+ * @param {{ org?: string, authToken?: string }} [opts]
+ * @returns {Promise<{ type: "promoted" | "exists", content_id: string, job_id: string, url: string | null }>}
+ */
+declare function promoteProjectAsset(request: {
+    project: string;
+    path: string;
+    revision?: number | null;
+}, opts?: {
+    org?: string;
+    authToken?: string;
+}): Promise<{
+    type: "promoted" | "exists";
+    content_id: string;
+    job_id: string;
+    url: string | null;
+}>;
+/**
+ * @internal Promotion attempts of a project (the used/exposed listing) —
+ * status/error from the upload job, newest first.
+ * @param {string} project
+ * @param {{ org?: string, authToken?: string }} [opts]
+ */
+declare function getProjectPromotions(project: string, opts?: {
+    org?: string;
+    authToken?: string;
+}): Promise<{
+    attempts: Array<{
+        path: string;
+        hash: string;
+        revision: number | null;
+        contentId: string;
+        jobId: string;
+        createdAt: string | null;
+        actor: string;
+        status: string | null;
+        error: string | null;
+        url: string | null;
+        editUrl: string | null;
+        thumbnailUrl: string | null;
+        contentType: string | null;
+    }>;
+}>;
 
 /**
  * Start the checkout process
@@ -1819,11 +2232,96 @@ declare function startCheckoutSession(args: {
     status: number;
 }>;
 
+/**
+ * Public price lookup. Deliberately kept in its own module, free of any auth
+ * import: this call needs no token, and `../auth` reads `window` at module scope
+ * — so importing it here would make a price lookup impossible in a service
+ * worker or a node test, neither of which has a `window`.
+ *
+ * @typedef {import("@needle-tools/cloud-sdk/types").ProductInformation} ProductInformation
+ * @typedef {import("@needle-tools/cloud-sdk/types").GetProductInformationOptions} GetProductInformationOptions
+ */
+/**
+ * What a product costs right now, for display: amount, currency, and the sale
+ * fields when one is running (`original` for a strikethrough, `label`,
+ * `expires_at`). Amounts are in MAJOR currency units (29 means €29).
+ *
+ * Pass the same `price` you pass to `checkoutProduct` — showing one price and
+ * charging another is exactly what that parameter prevents.
+ *
+ * Resolves `null` when the product is unknown or the API is unreachable, so a
+ * caller can simply omit the price: a missing price should never take down a buy
+ * button that otherwise works.
+ *
+ * @param {string} product product name, e.g. "Needle Inspector"
+ * @param {GetProductInformationOptions} [options]
+ * @returns {Promise<ProductInformation | null>}
+ */
+declare function getProductInformation(product: string, options?: GetProductInformationOptions): Promise<ProductInformation | null>;
+/**
+ * Public price lookup. Deliberately kept in its own module, free of any auth
+ * import: this call needs no token, and `../auth` reads `window` at module scope
+ * — so importing it here would make a price lookup impossible in a service
+ * worker or a node test, neither of which has a `window`.
+ */
+type ProductInformation = _needle_tools_cloud_sdk_types.ProductInformation;
+/**
+ * Public price lookup. Deliberately kept in its own module, free of any auth
+ * import: this call needs no token, and `../auth` reads `window` at module scope
+ * — so importing it here would make a price lookup impossible in a service
+ * worker or a node test, neither of which has a `window`.
+ */
+type GetProductInformationOptions = _needle_tools_cloud_sdk_types.GetProductInformationOptions;
+
+/**
+ * Purchase flow BY PRODUCT NAME.
+ *
+ * The older `startCheckoutSession` takes a Stripe `price_id`, so every caller has
+ * to know Stripe's internal ids. These two work from the product name the rest of
+ * the product surface already uses ("needle_inspector"), and they are a matched
+ * pair: query the price with `getProductInformation` (payment.info.js — kept
+ * auth-free so it also works without a `window`), charge it with
+ * {@link checkoutProduct}, passing the same `price` to both so the number shown
+ * is the number charged.
+ *
+ * @typedef {import("@needle-tools/cloud-sdk/types").CheckoutProductOptions} CheckoutProductOptions
+ */
+/**
+ * Start a checkout for a product and return the Stripe URL to send the buyer to.
+ *
+ * Returns the url rather than navigating, so the caller decides: a web app can
+ * assign `location.href`, an editor can open a tab and poll for the license on
+ * focus. Resolves `null` when checkout could not be created (not signed in, or
+ * the API is unreachable).
+ *
+ * Authenticated: the server derives the buyer from the token, which is what makes
+ * prefilling — and locking — the checkout email safe.
+ *
+ * @param {string} product product name, e.g. "needle_inspector"
+ * @param {CheckoutProductOptions} [options]
+ * @returns {Promise<{ url: string } | null>}
+ */
+declare function checkoutProduct(product: string, options?: CheckoutProductOptions): Promise<{
+    url: string;
+} | null>;
+/**
+ * Purchase flow BY PRODUCT NAME.
+ *
+ * The older `startCheckoutSession` takes a Stripe `price_id`, so every caller has
+ * to know Stripe's internal ids. These two work from the product name the rest of
+ * the product surface already uses ("needle_inspector"), and they are a matched
+ * pair: query the price with `getProductInformation` (payment.info.js — kept
+ * auth-free so it also works without a `window`), charge it with
+ * {@link checkoutProduct}, passing the same `price` to both so the number shown
+ * is the number charged.
+ */
+type CheckoutProductOptions = _needle_tools_cloud_sdk_types.CheckoutProductOptions;
+
 declare namespace AuthScopes {
     let Basic: UserScope[];
     let Payment: string[];
     let All: string[];
 }
 
-export { Auth, AuthScopes, NeedleLoginButton, archiveProject, checkProjectBlobs, cloneProject, completeProjectBlobUpload, createChatSession, createProject, deleteProject, getContent, getDeployments, getProjectHead, getPublicContent, getUserLicenses, listChats, listContent, listProjectRevisions, listProjects, listPublicContent, ownsProduct, pullProjectRevision, pushProjectRevision, requestProjectBlobDownload, requestProjectBlobUpload, restoreProject, startCheckoutSession, unarchiveProject, updateProject, uploadFiles };
+export { Auth, AuthScopes, NeedleLoginButton, aiComplete, archiveProject, checkProjectBlobs, checkoutProduct, cloneProject, completeProjectBlobUpload, createChatSession, createProject, deleteProject, generate3dAsset, getContent, getDeployments, getProductInformation, getProjectDeployments, getProjectHead, getProjectPromotions, getPublicContent, getUserLicenses, listChats, listContent, listProjectRevisions, listProjects, listPublicContent, ownsProduct, promoteProjectAsset, pullProjectRevision, pushProjectRevision, recordProjectDeployment, requestProjectBlobDownload, requestProjectBlobUpload, restoreProject, startCheckoutSession, unarchiveProject, updateContent, updateProject, updateProjectRevision, uploadFiles };
 export type { AuthData, AuthInitOpts, ChatAuthOpts, ChatSessionHandle, ChatSessionOptions, ChatSessionSendOptions, Deployment, Filelike, LogtoUserCustomData, RecentChatsResponse, ResourceUrl, ToolDefinition, UserInfoResponse };