@buildcores/render-client 1.2.0 → 1.4.0

package/dist/api.d.ts

@@ -1,9 +1,12 @@
-import { RenderBuildRequest, AvailablePartsResponse, ApiConfig, PartCategory, GetAvailablePartsOptions } from "./types";
+import { RenderBuildRequest, AvailablePartsResponse, ApiConfig, PartCategory, GetAvailablePartsOptions, BuildResponse, PartsResponse, RenderByShareCodeOptions, RenderByShareCodeJobResponse, RenderByShareCodeResponse } from "./types";
 declare const API_BASE_URL = "https://www.renderapi.buildcores.com";
 export declare const API_ENDPOINTS: {
     readonly RENDER_BUILD_EXPERIMENTAL: "/render-build-experimental";
     readonly RENDER_BUILD: "/render-build";
     readonly AVAILABLE_PARTS: "/available-parts";
+    readonly BUILD: "/build";
+    readonly PARTS: "/parts";
+    readonly RENDER_BY_SHARE_CODE: "/render-by-share-code";
 };
 export interface RenderBuildResponse {
     /**
@@ -78,4 +81,86 @@ export declare const renderBuild: (request: RenderBuildRequest, config: ApiConfi
 }) => Promise<RenderBuildAsyncResponse>;
 export declare const renderSpriteExperimental: (request: RenderBuildRequest, config: ApiConfig) => Promise<RenderSpriteResponse>;
 export declare const getAvailableParts: (category: PartCategory, config: ApiConfig, options?: GetAvailablePartsOptions) => Promise<AvailablePartsResponse>;
+/**
+ * Fetch a build by its share code.
+ * Returns build metadata and parts organized by category.
+ *
+ * @param shareCode - The share code of the build to fetch
+ * @param config - API configuration (environment, auth token)
+ * @returns Promise with build details including parts
+ *
+ * @example
+ * ```tsx
+ * const build = await getBuildByShareCode('abc123xyz', {
+ *   environment: 'prod',
+ *   authToken: 'your-api-key'
+ * });
+ *
+ * console.log(build.name); // "My Gaming PC"
+ * console.log(build.parts.CPU); // ["7xjqsomhr"]
+ *
+ * // Use the parts directly with BuildRender
+ * <BuildRender parts={{ parts: build.parts }} size={500} apiConfig={config} />
+ * ```
+ */
+export declare const getBuildByShareCode: (shareCode: string, config: ApiConfig) => Promise<BuildResponse>;
+/**
+ * Fetch part details by their BuildCores IDs.
+ *
+ * @param partIds - Array of BuildCores part IDs to fetch
+ * @param config - API configuration (environment, auth token)
+ * @returns Promise with part details
+ *
+ * @example
+ * ```tsx
+ * const response = await getPartsByIds(['7xjqsomhr', 'z7pyphm9k'], {
+ *   environment: 'prod',
+ *   authToken: 'your-api-key'
+ * });
+ *
+ * response.parts.forEach(part => {
+ *   console.log(`${part.name} (${part.category})`);
+ * });
+ * ```
+ */
+export declare const getPartsByIds: (partIds: string[], config: ApiConfig) => Promise<PartsResponse>;
+/**
+ * Create a render job for a build by its share code.
+ * Returns the job ID for polling status.
+ *
+ * @param shareCode - The share code of the build to render
+ * @param config - API configuration (environment, auth token)
+ * @param options - Render options (format, dimensions, profile)
+ * @returns Promise with job creation response
+ */
+export declare const createRenderByShareCodeJob: (shareCode: string, config: ApiConfig, options?: Omit<RenderByShareCodeOptions, "pollIntervalMs" | "timeoutMs">) => Promise<RenderByShareCodeJobResponse>;
+/**
+ * Render a build by its share code.
+ * This is a convenience function that creates a render job and polls until completion.
+ *
+ * @param shareCode - The share code of the build to render
+ * @param config - API configuration (environment, auth token)
+ * @param options - Render options including polling configuration
+ * @returns Promise with the final render URL
+ *
+ * @example
+ * ```tsx
+ * // Simple usage - just pass share code
+ * const result = await renderByShareCode('abc123xyz', {
+ *   environment: 'prod',
+ *   authToken: 'your-api-key'
+ * });
+ * console.log(result.videoUrl); // URL to rendered video
+ *
+ * // With custom options
+ * const result = await renderByShareCode('abc123xyz', config, {
+ *   format: 'sprite',
+ *   width: 1920,
+ *   height: 1080,
+ *   profile: 'cinematic',
+ *   timeoutMs: 180000 // 3 minute timeout
+ * });
+ * ```
+ */
+export declare const renderByShareCode: (shareCode: string, config: ApiConfig, options?: RenderByShareCodeOptions) => Promise<RenderByShareCodeResponse>;
 export { API_BASE_URL };

package/dist/hooks/useSpriteRender.d.ts

@@ -17,4 +17,31 @@ export interface UseSpriteRenderOptions {
      */
     mode?: "async" | "experimental";
 }
-export declare const useSpriteRender: (parts: RenderBuildRequest, apiConfig: ApiConfig, onLoadStart?: () => void, options?: UseSpriteRenderOptions) => UseSpriteRenderReturn;
+/**
+ * Grid settings for render composition
+ */
+export interface RenderGridSettings {
+    cellThickness?: number;
+    sectionThickness?: number;
+    color?: string;
+    fadeDistance?: number;
+    renderOrder?: number;
+}
+/**
+ * Input for sprite rendering - either parts (creates new build) or shareCode (uses existing build)
+ */
+export type SpriteRenderInput = {
+    type: 'parts';
+    parts: RenderBuildRequest;
+    showGrid?: boolean;
+    cameraOffsetX?: number;
+    gridSettings?: RenderGridSettings;
+} | {
+    type: 'shareCode';
+    shareCode: string;
+    profile?: 'cinematic' | 'flat' | 'fast';
+    showGrid?: boolean;
+    cameraOffsetX?: number;
+    gridSettings?: RenderGridSettings;
+};
+export declare const useSpriteRender: (input: RenderBuildRequest | SpriteRenderInput, apiConfig: ApiConfig, onLoadStart?: () => void, options?: UseSpriteRenderOptions) => UseSpriteRenderReturn;

package/dist/hooks/useZoomPan.d.ts

@@ -0,0 +1,16 @@
+import { type TouchEvent as ReactTouchEvent, type WheelEvent as ReactWheelEvent } from "react";
+interface UseZoomOptions {
+    displayWidth?: number;
+    displayHeight?: number;
+    minScale?: number;
+    maxScale?: number;
+}
+interface UseZoomReturn {
+    scale: number;
+    isPinching: boolean;
+    handleWheel: (event: ReactWheelEvent<Element>) => void;
+    handleTouchStart: (event: ReactTouchEvent<HTMLCanvasElement>) => boolean;
+    reset: () => void;
+}
+export declare const useZoomPan: ({ displayWidth, displayHeight, minScale, maxScale, }?: UseZoomOptions) => UseZoomReturn;
+export {};

package/dist/index.d.ts

@@ -131,6 +131,9 @@ interface BuildRenderProps {
      * This object defines which PC components should be included in the 3D sprite render.
      * Each part category contains an array with a single part ID that will be rendered.
      *
+     * **Note**: If `shareCode` is provided, it will be used instead of `parts`.
+     * Using `shareCode` preserves the build's interactive state (including case fan slot placements).
+     *
      * **Current Limitation**: Only 1 part per category is supported. Arrays must contain
      * exactly one part ID per category. Future versions will support multiple parts per category.
      *
@@ -152,7 +155,26 @@ interface BuildRenderProps {
      * <SpriteRender parts={parts} size={300} />
      * ```
      */
-    parts: RenderBuildRequest;
+    parts?: RenderBuildRequest;
+    /**
+     * Share code of an existing build to render.
+     *
+     * When provided, the build will be rendered using its existing interactive state,
+     * which includes case fan slot placements. This is preferred over `parts` when
+     * rendering builds that have already been configured with case fans.
+     *
+     * If both `shareCode` and `parts` are provided, `shareCode` takes precedence.
+     *
+     * @example
+     * ```tsx
+     * <BuildRender
+     *   shareCode="abc123xyz"
+     *   size={500}
+     *   apiConfig={{ environment: 'prod', authToken: 'your-token' }}
+     * />
+     * ```
+     */
+    shareCode?: string;
     /**
      * Width and height in pixels. If only `size` is provided, both width and height use it.
      * If `width`/`height` are provided, they override `size` individually.
@@ -202,6 +224,22 @@ interface BuildRenderProps {
      * @default 0.2
      */
     touchSensitivity?: number;
+    /**
+     * Show grid in render.
+     * Works for both parts and shareCode rendering.
+     */
+    showGrid?: boolean;
+    /**
+     * Camera offset X for composition.
+     * Positive values shift the build to the right, leaving room for text overlay on the left.
+     * Works for both parts and shareCode rendering.
+     */
+    cameraOffsetX?: number;
+    /**
+     * Grid appearance settings for thicker/more visible grid in renders.
+     * Works for both parts and shareCode rendering.
+     */
+    gridSettings?: GridSettings;
 }
 /**
  * API configuration for environment and authentication
@@ -271,7 +309,9 @@ declare enum PartCategory {
     /** PC Case - The enclosure that houses all components */
     PCCase = "PCCase",
     /** CPU Cooler - Air or liquid cooling for the processor */
-    CPUCooler = "CPUCooler"
+    CPUCooler = "CPUCooler",
+    /** Case Fans - Additional cooling fans for the case */
+    CaseFan = "CaseFan"
 }
 /**
  * Request structure for rendering a PC build.
@@ -368,6 +408,46 @@ interface RenderBuildRequest {
      * ```
      */
     height?: number;
+    /**
+     * Render quality profile that controls visual effects and rendering speed.
+     *
+     * - **cinematic**: All effects enabled (shadows, ambient occlusion, bloom) for highest quality
+     * - **flat**: No effects for clean, simple product shots
+     * - **fast**: Minimal rendering for fastest processing speed
+     *
+     * @example
+     * ```tsx
+     * const request: RenderBuildRequest = {
+     *   parts: { CPU: ["7xjqsomhr"] },
+     *   profile: 'cinematic'  // High quality with all effects
+     * };
+     * ```
+     *
+     * @example Fast rendering
+     * ```tsx
+     * const request: RenderBuildRequest = {
+     *   parts: { CPU: ["7xjqsomhr"] },
+     *   profile: 'fast'  // Quick render, minimal effects
+     * };
+     * ```
+     */
+    profile?: 'cinematic' | 'flat' | 'fast';
+    /**
+     * Whether to show the 3D grid in the render.
+     * Defaults to true for cinematic profile, false otherwise.
+     */
+    showGrid?: boolean;
+    /**
+     * Horizontal offset for the camera view.
+     * Positive values shift the build to the right, leaving room for text overlay on the left.
+     * Range: -0.3 to 0.3
+     */
+    cameraOffsetX?: number;
+    /**
+     * Custom grid appearance settings.
+     * Only applies when showGrid is true.
+     */
+    gridSettings?: GridSettings;
 }
 /**
  * Response structure containing all available parts for each category.
@@ -465,6 +545,130 @@ interface GetAvailablePartsOptions {
     /** Number of parts to skip for pagination (default 0) */
     skip?: number;
 }
+/**
+ * Extended part details including category information
+ */
+interface PartDetailsWithCategory {
+    /** Unique part identifier (BuildCores ID) */
+    id: string;
+    /** Human-readable part name */
+    name: string;
+    /** URL to part image (may be null) */
+    image: string | null;
+    /** Part category */
+    category: PartCategory;
+}
+/**
+ * Response from the get build by share code endpoint.
+ * Contains build metadata and parts organized by category.
+ *
+ * @example
+ * ```tsx
+ * const build = await getBuildByShareCode('abc123xyz', config);
+ * console.log(build.name); // "My Gaming PC"
+ * console.log(build.parts.CPU); // ["7xjqsomhr"]
+ * console.log(build.partDetails.CPU[0].name); // "AMD Ryzen 7 9800X3D"
+ * ```
+ */
+interface BuildResponse {
+    /** The share code of the build */
+    shareCode: string;
+    /** Build name/title */
+    name: string;
+    /** Build description */
+    description: string;
+    /**
+     * Part IDs mapped by category.
+     * Use these IDs directly with RenderBuildRequest.
+     */
+    parts: {
+        [K in PartCategory]?: string[];
+    };
+    /**
+     * Detailed part information mapped by category.
+     * Includes name, image URL, and category for each part.
+     */
+    partDetails: {
+        [K in PartCategory]?: PartDetailsWithCategory[];
+    };
+}
+/**
+ * Response from the get parts by IDs endpoint.
+ *
+ * @example
+ * ```tsx
+ * const response = await getPartsByIds(['7xjqsomhr', 'z7pyphm9k'], config);
+ * response.parts.forEach(part => {
+ *   console.log(`${part.name} (${part.category})`);
+ * });
+ * ```
+ */
+interface PartsResponse {
+    /** Array of part details */
+    parts: PartDetailsWithCategory[];
+}
+/**
+ * Grid appearance settings for renders
+ */
+interface GridSettings {
+    /** Grid cell line thickness (default: 0.6) */
+    cellThickness?: number;
+    /** Grid section line thickness (default: 1.2) */
+    sectionThickness?: number;
+    /** Grid color as hex string (default: #6f6f6f) */
+    color?: string;
+    /** Distance at which grid starts to fade (default: 3) */
+    fadeDistance?: number;
+    /** Render order for depth sorting (default: 0, use -1 to render before other objects) */
+    renderOrder?: number;
+}
+/**
+ * Options for rendering a build by share code
+ */
+interface RenderByShareCodeOptions {
+    /** Output format - video (MP4) or sprite (WebP sprite sheet) */
+    format?: "video" | "sprite";
+    /** Desired canvas pixel width (256-8192) */
+    width?: number;
+    /** Desired canvas pixel height (256-8192) */
+    height?: number;
+    /** Render quality profile */
+    profile?: "cinematic" | "flat" | "fast";
+    /** Show grid in render (default: true for cinematic profile) */
+    showGrid?: boolean;
+    /** Camera offset X for composition (positive = shift build right to leave room for text overlay) */
+    cameraOffsetX?: number;
+    /** Grid appearance settings (for thicker/more visible grid in renders) */
+    gridSettings?: GridSettings;
+    /** Polling interval in milliseconds (default: 1500) */
+    pollIntervalMs?: number;
+    /** Timeout in milliseconds (default: 120000 = 2 minutes) */
+    timeoutMs?: number;
+}
+/**
+ * Response from the render by share code endpoint (job creation).
+ */
+interface RenderByShareCodeJobResponse {
+    /** Unique job identifier for polling status */
+    job_id: string;
+    /** Current job status */
+    status: "queued" | "processing" | "completed" | "error";
+    /** The share code of the build being rendered */
+    share_code: string;
+}
+/**
+ * Final response after render by share code completes.
+ *
+ * @example
+ * ```tsx
+ * const result = await renderByShareCode('abc123xyz', config);
+ * // Use result.videoUrl to display the rendered video
+ * ```
+ */
+interface RenderByShareCodeResponse {
+    /** URL to the rendered video or sprite sheet */
+    videoUrl: string;
+}
 
 declare const BuildRender: React.FC<BuildRenderProps>;
 
@@ -542,7 +746,34 @@ interface UseSpriteRenderOptions {
      */
     mode?: "async" | "experimental";
 }
-declare const useSpriteRender: (parts: RenderBuildRequest, apiConfig: ApiConfig, onLoadStart?: () => void, options?: UseSpriteRenderOptions) => UseSpriteRenderReturn;
+/**
+ * Grid settings for render composition
+ */
+interface RenderGridSettings {
+    cellThickness?: number;
+    sectionThickness?: number;
+    color?: string;
+    fadeDistance?: number;
+    renderOrder?: number;
+}
+/**
+ * Input for sprite rendering - either parts (creates new build) or shareCode (uses existing build)
+ */
+type SpriteRenderInput = {
+    type: 'parts';
+    parts: RenderBuildRequest;
+    showGrid?: boolean;
+    cameraOffsetX?: number;
+    gridSettings?: RenderGridSettings;
+} | {
+    type: 'shareCode';
+    shareCode: string;
+    profile?: 'cinematic' | 'flat' | 'fast';
+    showGrid?: boolean;
+    cameraOffsetX?: number;
+    gridSettings?: RenderGridSettings;
+};
+declare const useSpriteRender: (input: RenderBuildRequest | SpriteRenderInput, apiConfig: ApiConfig, onLoadStart?: () => void, options?: UseSpriteRenderOptions) => UseSpriteRenderReturn;
 
 interface DragIconProps {
     width?: number;
@@ -571,6 +802,9 @@ declare const API_ENDPOINTS: {
     readonly RENDER_BUILD_EXPERIMENTAL: "/render-build-experimental";
     readonly RENDER_BUILD: "/render-build";
     readonly AVAILABLE_PARTS: "/available-parts";
+    readonly BUILD: "/build";
+    readonly PARTS: "/parts";
+    readonly RENDER_BY_SHARE_CODE: "/render-by-share-code";
 };
 interface RenderBuildResponse {
     /**
@@ -622,6 +856,88 @@ declare const buildHeaders: (config: ApiConfig) => Record<string, string>;
 declare const renderBuildExperimental: (request: RenderBuildRequest, config: ApiConfig) => Promise<RenderBuildResponse>;
 declare const renderSpriteExperimental: (request: RenderBuildRequest, config: ApiConfig) => Promise<RenderSpriteResponse>;
 declare const getAvailableParts: (category: PartCategory, config: ApiConfig, options?: GetAvailablePartsOptions) => Promise<AvailablePartsResponse>;
+/**
+ * Fetch a build by its share code.
+ * Returns build metadata and parts organized by category.
+ *
+ * @param shareCode - The share code of the build to fetch
+ * @param config - API configuration (environment, auth token)
+ * @returns Promise with build details including parts
+ *
+ * @example
+ * ```tsx
+ * const build = await getBuildByShareCode('abc123xyz', {
+ *   environment: 'prod',
+ *   authToken: 'your-api-key'
+ * });
+ *
+ * console.log(build.name); // "My Gaming PC"
+ * console.log(build.parts.CPU); // ["7xjqsomhr"]
+ *
+ * // Use the parts directly with BuildRender
+ * <BuildRender parts={{ parts: build.parts }} size={500} apiConfig={config} />
+ * ```
+ */
+declare const getBuildByShareCode: (shareCode: string, config: ApiConfig) => Promise<BuildResponse>;
+/**
+ * Fetch part details by their BuildCores IDs.
+ *
+ * @param partIds - Array of BuildCores part IDs to fetch
+ * @param config - API configuration (environment, auth token)
+ * @returns Promise with part details
+ *
+ * @example
+ * ```tsx
+ * const response = await getPartsByIds(['7xjqsomhr', 'z7pyphm9k'], {
+ *   environment: 'prod',
+ *   authToken: 'your-api-key'
+ * });
+ *
+ * response.parts.forEach(part => {
+ *   console.log(`${part.name} (${part.category})`);
+ * });
+ * ```
+ */
+declare const getPartsByIds: (partIds: string[], config: ApiConfig) => Promise<PartsResponse>;
+/**
+ * Create a render job for a build by its share code.
+ * Returns the job ID for polling status.
+ *
+ * @param shareCode - The share code of the build to render
+ * @param config - API configuration (environment, auth token)
+ * @param options - Render options (format, dimensions, profile)
+ * @returns Promise with job creation response
+ */
+declare const createRenderByShareCodeJob: (shareCode: string, config: ApiConfig, options?: Omit<RenderByShareCodeOptions, "pollIntervalMs" | "timeoutMs">) => Promise<RenderByShareCodeJobResponse>;
+/**
+ * Render a build by its share code.
+ * This is a convenience function that creates a render job and polls until completion.
+ *
+ * @param shareCode - The share code of the build to render
+ * @param config - API configuration (environment, auth token)
+ * @param options - Render options including polling configuration
+ * @returns Promise with the final render URL
+ *
+ * @example
+ * ```tsx
+ * // Simple usage - just pass share code
+ * const result = await renderByShareCode('abc123xyz', {
+ *   environment: 'prod',
+ *   authToken: 'your-api-key'
+ * });
+ * console.log(result.videoUrl); // URL to rendered video
+ *
+ * // With custom options
+ * const result = await renderByShareCode('abc123xyz', config, {
+ *   format: 'sprite',
+ *   width: 1920,
+ *   height: 1080,
+ *   profile: 'cinematic',
+ *   timeoutMs: 180000 // 3 minute timeout
+ * });
+ * ```
+ */
+declare const renderByShareCode: (shareCode: string, config: ApiConfig, options?: RenderByShareCodeOptions) => Promise<RenderByShareCodeResponse>;
 
-export { API_BASE_URL, API_ENDPOINTS, BuildRender, BuildRenderVideo, DragIcon, InstructionTooltip, LoadingErrorOverlay, PartCategory, arePartsEqual, buildApiUrl, buildHeaders, calculateCircularFrame, calculateCircularTime, getAvailableParts, renderBuildExperimental, renderSpriteExperimental, useBouncePatternProgress, useBuildRender, useSpriteRender, useSpriteScrubbing, useVideoScrubbing };
-export type { ApiConfig, AvailablePartsResponse, BuildRenderProps, BuildRenderVideoProps, GetAvailablePartsOptions, PartDetails, RenderAPIService, RenderBuildRequest, RenderBuildResponse, RenderSpriteResponse, UseBuildRenderOptions, UseBuildRenderReturn, UseSpriteRenderOptions, UseSpriteRenderReturn };
+export { API_BASE_URL, API_ENDPOINTS, BuildRender, BuildRenderVideo, DragIcon, InstructionTooltip, LoadingErrorOverlay, PartCategory, arePartsEqual, buildApiUrl, buildHeaders, calculateCircularFrame, calculateCircularTime, createRenderByShareCodeJob, getAvailableParts, getBuildByShareCode, getPartsByIds, renderBuildExperimental, renderByShareCode, renderSpriteExperimental, useBouncePatternProgress, useBuildRender, useSpriteRender, useSpriteScrubbing, useVideoScrubbing };
+export type { ApiConfig, AvailablePartsResponse, BuildRenderProps, BuildRenderVideoProps, BuildResponse, GetAvailablePartsOptions, GridSettings, PartDetails, PartDetailsWithCategory, PartsResponse, RenderAPIService, RenderBuildRequest, RenderBuildResponse, RenderByShareCodeJobResponse, RenderByShareCodeOptions, RenderByShareCodeResponse, RenderSpriteResponse, SpriteRenderInput, UseBuildRenderOptions, UseBuildRenderReturn, UseSpriteRenderOptions, UseSpriteRenderReturn };