needle-cloud 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -335,7 +335,21 @@ type ChatSessionHandle$1 = {
     readonly chatUrl: string | null,
     /** Whether the WebSocket tool connection is active. Always false if no tools were provided. */
     readonly toolsConnected: boolean,
-    /** Close the session (WebSocket + cleanup). */
+    /**
+     * Stable identity of the underlying tool connection. `null` when the
+     * session has no tools (HTTP-only). Used by the server to route tool
+     * requests back to this specific session.
+     */
+    readonly instanceId: string | null,
+    /**
+     * Close the session (WebSocket + cleanup).
+     *
+     * **Node / CLI consumers MUST call this before exit** when the
+     * session was created with tools (i.e. holds an open WebSocket) —
+     * otherwise the open socket keeps Node's event loop alive and the
+     * process will hang. See `ToolConnectionHandle.close()` for the
+     * full lifecycle notes. Browsers handle this automatically.
+     */
     close(): void,
 }
 
@@ -537,6 +551,152 @@ type ChatSessionHandle = ChatSessionHandle$1;
 type ChatSessionSendOptions = ChatSessionSendOptions$1;
 type ToolDefinition = ToolDefinition$1;
 
+// #region Content type / format constants
+/** All known content types. Runtime array for validation. */
+declare const CONTENT_TYPES: readonly ["3d-asset", "material", "deployment", "hdri"];
+/** Semantic content type — what kind of asset this is (3D model, material, deployed website, HDRI environment). */
+type ContentType = typeof CONTENT_TYPES[number];
+
+/** All known content formats. Runtime array for validation. */
+declare const CONTENT_FORMATS: readonly ["glb", "gltf", "usd", "usda", "usdz", "obj", "fbx", "vrm", "stl", "textures", "html", "exr", "pmrem"];
+/** File format — e.g. `glb`, `usdz`, `gltf`, `exr` (HDRI source), `pmrem` (engine-ready HDRI KTX2). */
+type ContentFormat = typeof CONTENT_FORMATS[number];
+// #endregion
+
+
+// #region Public content — GET /v1/public/content
+// Phase 3.1d. Anonymous, no auth. Only items with is_public=true.
+
+// NOTE: PublicContentItem / PublicContentDetail / PublicContentVersion are the
+// *anonymous* counterpart to the auth-required types above (ContentListItem,
+// GetContentDetailResponse, ContentVersion). Keep them aligned: when fields
+// 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.
+
+/** One version of a public content item.
+ *  Each version exposes a single entrypoint URL — relative file references
+ *  (e.g. `./model.bin`) are resolved automatically when fetched. */
+type PublicContentVersion = {
+    /** Stable identifier for this version. */
+    identifier: string;
+    /** ISO 8601 timestamp. */
+    created_at: string;
+    /** ISO 8601 timestamp — last time this version was touched. */
+    updated_at: string;
+    /** Filename of the main entrypoint within the version. */
+    entrypoint: string;
+    /** URL to the entrypoint file — what consumers should load. */
+    url: string;
+    /** Total size of the version in bytes. */
+    size: number | null;
+    /** Base64-encoded MD5 of the entrypoint file. Use for integrity / cache keys. */
+    md5: string | null;
+    /** Semantic content type for this version (may differ from the item-level type for derived variants). */
+    content_type: ContentType | null;
+    /** File format (e.g. `glb`, `gltf`). */
+    content_format: ContentFormat | null;
+    /** Pixel width for image content (HDRI / PNG / JPEG / WebP / KTX2). Null otherwise. */
+    width: number | null;
+    /** Pixel height. See `width`. */
+    height: number | null;
+};
+
+/**
+ * A single content item in a public discovery listing.
+ */
+type PublicContentItem = {
+    identifier: string;
+    /** Display name. */
+    title: string;
+    description: string | null;
+    tags: string[] | null;
+    /** Semantic content type (e.g. `material`, `3d-asset`, `deployment`). */
+    content_type: ContentType | null;
+    /** All formats available across versions (e.g. `["glb"]` or `["glb", "textures"]`). */
+    content_formats: ContentFormat[];
+    /** URL for the thumbnail image, when one is available. */
+    thumbnail_url: string | null;
+    /** ISO 8601 timestamp. */
+    created_at: string;
+    /** ISO 8601 timestamp. */
+    updated_at: string;
+    /** Whether this content requires a password to be viewed. */
+    is_password_protected: boolean;
+    /** Linkable URL for this content. For deployments this is the live website URL;
+     *  for other content types it points at the asset's entrypoint file.
+     *  This is the URL to *reference* / link to. It is NOT a "download the whole asset"
+     *  URL — progressive formats (glTF, USD, …) only fetch the entrypoint here;
+     *  dependent files are resolved relatively by the consuming runtime. */
+    url: string | null;
+    /** Standalone viewer URL. Open in a browser to view the asset interactively.
+     *  Omitted for `content_type === "deployment"` (use `url` instead). */
+    view_url?: string | null;
+    /** Iframe-friendly embed URL. Drop into an `<iframe src="…">` to embed the asset
+     *  on a page. Omitted for `content_type === "deployment"` (use `url` instead). */
+    embed_url?: string | null;
+};
+
+/** Full detail for a public content item — adds version information to the list shape. */
+type PublicContentDetail = PublicContentItem & {
+    versions: PublicContentVersion[];
+};
+
+/** Query parameters for GET /v1/public/content */
+type ListPublicContentQuery = {
+    /** Filter by content type */
+    content_type?: ContentType;
+    /** Filter by content format */
+    content_format?: ContentFormat;
+    /** Filter to content owned by a single Needle Cloud team. The team id
+     *  is shown on the team's details page at `https://cloud.needle.tools/team/<id>`. */
+    org_id?: string;
+    /** Substring match against identifier, title, description, and tags. */
+    search?: string;
+    /** Page size (default 20, max 100) */
+    limit?: number;
+    /** Opaque cursor from a previous response. When omitted, returns the first page. */
+    cursor?: string;
+    /** Include password-protected items in the listing. Default: false (excluded).
+     *  Opt-in for the niche "teaser" pattern where the owner wants the metadata
+     *  publicly discoverable but viewing requires a password. */
+    include_protected?: boolean;
+};
+
+/** Response from GET /v1/public/content */
+type ListPublicContentResponse = {
+    items: PublicContentItem[];
+    /** Cursor to fetch the next page; omitted when there are no more items. */
+    next_cursor?: string;
+};
+
+/**
+ * List publicly discoverable content items on Needle Cloud.
+ *
+ * Anonymous — no auth required. The production endpoint is baked into the
+ * build so callers don't need to know about `baseUrl`.
+ *
+ * @param {import("@needle-tools/cloud-sdk/types/api.content").ListPublicContentQuery} [query]
+ * @returns {Promise<import("@needle-tools/cloud-sdk/types/api.content").ListPublicContentResponse>}
+ *
+ * @example
+ *   import { listPublicContent } from "needle-cloud";
+ *   const { items, next_cursor } = await listPublicContent({ content_type: "material", limit: 20 });
+ */
+declare function listPublicContent(query?: ListPublicContentQuery): Promise<ListPublicContentResponse>;
+/**
+ * Fetch the full detail (versions, urls, ...) of a single publicly discoverable
+ * content item by its identifier. Anonymous — no auth required.
+ *
+ * @param {string} identifier
+ * @returns {Promise<import("@needle-tools/cloud-sdk/types/api.content").PublicContentDetail>}
+ *
+ * @example
+ *   import { getPublicContent } from "needle-cloud";
+ *   const item = await getPublicContent("a1b2c3");
+ */
+declare function getPublicContent(identifier: string): Promise<PublicContentDetail>;
+
 /**
  * Start the checkout process
  * @param {{ price_id:string }} args
@@ -554,5 +714,5 @@ declare namespace AuthScopes {
     let All: string[];
 }
 
-export { Auth, AuthScopes, NeedleLoginButton, createChatSession, getDeployments, getUserLicenses, listChats, ownsProduct, startCheckoutSession, uploadFiles };
+export { Auth, AuthScopes, NeedleLoginButton, createChatSession, getDeployments, getPublicContent, getUserLicenses, listChats, listPublicContent, ownsProduct, startCheckoutSession, uploadFiles };
 export type { AuthData, AuthInitOpts, ChatAuthOpts, ChatSessionHandle, ChatSessionOptions, ChatSessionSendOptions, Deployment, Filelike, LogtoUserCustomData, RecentChatsResponse, ResourceUrl, ToolDefinition, UserInfoResponse };