@buildcores/render-client 1.3.0 → 1.4.1

package/dist/index.js

@@ -149,6 +149,9 @@ const API_ENDPOINTS = {
     RENDER_BUILD_EXPERIMENTAL: "/render-build-experimental",
     RENDER_BUILD: "/render-build",
     AVAILABLE_PARTS: "/available-parts",
+    BUILD: "/build",
+    PARTS: "/parts",
+    RENDER_BY_SHARE_CODE: "/render-by-share-code",
 };
 // API URL helpers
 const buildApiUrl = (endpoint, config) => {
@@ -210,6 +213,10 @@ const createRenderBuildJob = async (request, config) => {
         ...(request.height !== undefined ? { height: request.height } : {}),
         // Include profile if provided
         ...(request.profile ? { profile: request.profile } : {}),
+        // Include composition settings
+        ...(request.showGrid !== undefined ? { showGrid: request.showGrid } : {}),
+        ...(request.cameraOffsetX !== undefined ? { cameraOffsetX: request.cameraOffsetX } : {}),
+        ...(request.gridSettings ? { gridSettings: request.gridSettings } : {}),
     };
     const response = await fetch(buildApiUrl(API_ENDPOINTS.RENDER_BUILD, config), {
         method: "POST",
@@ -315,6 +322,169 @@ const getAvailableParts = async (category, config, options) => {
     }
     return (await response.json());
 };
+// ============================================
+// Build and Parts API Functions
+// ============================================
+/**
+ * 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} />
+ * ```
+ */
+const getBuildByShareCode = async (shareCode, config) => {
+    const url = buildApiUrl(`${API_ENDPOINTS.BUILD}/${encodeURIComponent(shareCode)}`, config);
+    const response = await fetch(url, {
+        method: "GET",
+        headers: buildHeaders(config),
+    });
+    if (response.status === 404) {
+        throw new Error("Build not found");
+    }
+    if (!response.ok) {
+        throw new Error(`Get build by share code failed: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+};
+/**
+ * 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})`);
+ * });
+ * ```
+ */
+const getPartsByIds = async (partIds, config) => {
+    const url = buildApiUrl(API_ENDPOINTS.PARTS, config);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: buildHeaders(config),
+        body: JSON.stringify({ ids: partIds }),
+    });
+    if (!response.ok) {
+        throw new Error(`Get parts by IDs failed: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+};
+/**
+ * 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
+ */
+const createRenderByShareCodeJob = async (shareCode, config, options) => {
+    const url = buildApiUrl(API_ENDPOINTS.RENDER_BY_SHARE_CODE, config);
+    const body = {
+        shareCode,
+        ...(options?.format ? { format: options.format } : {}),
+        ...(options?.width !== undefined ? { width: options.width } : {}),
+        ...(options?.height !== undefined ? { height: options.height } : {}),
+        ...(options?.profile ? { profile: options.profile } : {}),
+        ...(options?.showGrid !== undefined ? { showGrid: options.showGrid } : {}),
+        ...(options?.cameraOffsetX !== undefined ? { cameraOffsetX: options.cameraOffsetX } : {}),
+        ...(options?.gridSettings ? { gridSettings: options.gridSettings } : {}),
+    };
+    const response = await fetch(url, {
+        method: "POST",
+        headers: buildHeaders(config),
+        body: JSON.stringify(body),
+    });
+    if (response.status === 404) {
+        throw new Error("Build not found");
+    }
+    if (!response.ok) {
+        throw new Error(`Create render job failed: ${response.status} ${response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!data?.job_id) {
+        throw new Error("Create render job failed: missing job_id in response");
+    }
+    return data;
+};
+/**
+ * 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
+ * });
+ * ```
+ */
+const renderByShareCode = async (shareCode, config, options) => {
+    const pollIntervalMs = options?.pollIntervalMs ?? 1500;
+    const timeoutMs = options?.timeoutMs ?? 120000; // 2 minutes default
+    const { job_id } = await createRenderByShareCodeJob(shareCode, config, options);
+    const start = Date.now();
+    // Poll until completed or error or timeout
+    for (;;) {
+        const status = await getRenderBuildStatus(job_id, config);
+        if (status.status === "completed") {
+            const requestedFormat = options?.format ?? "video";
+            const finalUrl = requestedFormat === "sprite"
+                ? status.sprite_url || status.url || undefined
+                : status.video_url || status.url || undefined;
+            if (!finalUrl) {
+                throw new Error("Render job completed but no URL returned");
+            }
+            return { videoUrl: finalUrl };
+        }
+        if (status.status === "error") {
+            throw new Error(status.error || "Render job failed");
+        }
+        if (Date.now() - start > timeoutMs) {
+            throw new Error("Timed out waiting for render job to complete");
+        }
+        await sleep(pollIntervalMs);
+    }
+};
 
 /**
  * Enum defining all available PC part categories that can be rendered.
@@ -355,6 +525,8 @@ exports.PartCategory = void 0;
     PartCategory["PCCase"] = "PCCase";
     /** CPU Cooler - Air or liquid cooling for the processor */
     PartCategory["CPUCooler"] = "CPUCooler";
+    /** Case Fans - Additional cooling fans for the case */
+    PartCategory["CaseFan"] = "CaseFan";
 })(exports.PartCategory || (exports.PartCategory = {}));
 
 /**
@@ -447,20 +619,47 @@ const useBuildRender = (parts, apiConfig, onLoadStart, options) => {
     };
 };
 
-const useSpriteRender = (parts, apiConfig, onLoadStart, options) => {
+const useSpriteRender = (input, apiConfig, onLoadStart, options) => {
     const [spriteSrc, setSpriteSrc] = react.useState(null);
     const [isRenderingSprite, setIsRenderingSprite] = react.useState(false);
     const [renderError, setRenderError] = react.useState(null);
     const [spriteMetadata, setSpriteMetadata] = react.useState(null);
-    const previousPartsRef = react.useRef(null);
-    const fetchRenderSprite = react.useCallback(async (currentParts) => {
+    const previousInputRef = react.useRef(null);
+    // Normalize input to SpriteRenderInput format
+    const normalizedInput = 'type' in input ? input : { type: 'parts', parts: input };
+    const fetchRenderSprite = react.useCallback(async (currentInput) => {
         try {
             setIsRenderingSprite(true);
             setRenderError(null);
             onLoadStart?.();
+            // Handle share code rendering - uses existing build with proper interactive state
+            if (currentInput.type === 'shareCode') {
+                const { videoUrl: spriteUrl } = await renderByShareCode(currentInput.shareCode, apiConfig, {
+                    format: 'sprite',
+                    profile: currentInput.profile,
+                    showGrid: currentInput.showGrid,
+                    cameraOffsetX: currentInput.cameraOffsetX,
+                    gridSettings: currentInput.gridSettings
+                });
+                setSpriteSrc((prevSrc) => {
+                    if (prevSrc && prevSrc.startsWith("blob:")) {
+                        URL.revokeObjectURL(prevSrc);
+                    }
+                    return spriteUrl;
+                });
+                setSpriteMetadata({ cols: 12, rows: 6, totalFrames: 72 });
+                return;
+            }
+            // Handle parts-based rendering (creates new build)
+            const currentParts = currentInput.parts;
             const mode = options?.mode ?? "async";
             if (mode === "experimental") {
-                const response = await renderSpriteExperimental(currentParts, apiConfig);
+                const response = await renderSpriteExperimental({
+                    ...currentParts,
+                    showGrid: currentInput.showGrid,
+                    cameraOffsetX: currentInput.cameraOffsetX,
+                    gridSettings: currentInput.gridSettings,
+                }, apiConfig);
                 const objectUrl = URL.createObjectURL(response.sprite);
                 // Clean up previous sprite URL before setting new one
                 setSpriteSrc((prevSrc) => {
@@ -478,7 +677,13 @@ const useSpriteRender = (parts, apiConfig, onLoadStart, options) => {
             }
             else {
                 // Async job-based flow: request sprite format and use returned URL
-                const { videoUrl: spriteUrl } = await renderBuild({ ...currentParts, format: "sprite" }, apiConfig);
+                const { videoUrl: spriteUrl } = await renderBuild({
+                    ...currentParts,
+                    format: "sprite",
+                    showGrid: currentInput.showGrid,
+                    cameraOffsetX: currentInput.cameraOffsetX,
+                    gridSettings: currentInput.gridSettings,
+                }, apiConfig);
                 setSpriteSrc((prevSrc) => {
                     if (prevSrc && prevSrc.startsWith("blob:")) {
                         URL.revokeObjectURL(prevSrc);
@@ -496,15 +701,39 @@ const useSpriteRender = (parts, apiConfig, onLoadStart, options) => {
             setIsRenderingSprite(false);
         }
     }, [apiConfig, onLoadStart, options?.mode]);
-    // Effect to call API when parts content changes (using custom equality check)
+    // Check if inputs are equal
+    const areInputsEqual = (a, b) => {
+        if (!a)
+            return false;
+        if (a.type !== b.type)
+            return false;
+        if (a.type === 'shareCode' && b.type === 'shareCode') {
+            // Compare grid settings (shallow comparison of properties)
+            const gridSettingsEqual = JSON.stringify(a.gridSettings ?? {}) === JSON.stringify(b.gridSettings ?? {});
+            return a.shareCode === b.shareCode &&
+                a.profile === b.profile &&
+                a.showGrid === b.showGrid &&
+                a.cameraOffsetX === b.cameraOffsetX &&
+                gridSettingsEqual;
+        }
+        if (a.type === 'parts' && b.type === 'parts') {
+            // Compare grid settings (shallow comparison of properties)
+            const gridSettingsEqual = JSON.stringify(a.gridSettings ?? {}) === JSON.stringify(b.gridSettings ?? {});
+            return arePartsEqual(a.parts, b.parts) &&
+                a.showGrid === b.showGrid &&
+                a.cameraOffsetX === b.cameraOffsetX &&
+                gridSettingsEqual;
+        }
+        return false;
+    };
+    // Effect to call API when input changes
     react.useEffect(() => {
-        const shouldFetch = previousPartsRef.current === null ||
-            !arePartsEqual(previousPartsRef.current, parts);
+        const shouldFetch = !areInputsEqual(previousInputRef.current, normalizedInput);
         if (shouldFetch) {
-            previousPartsRef.current = parts;
-            fetchRenderSprite(parts);
+            previousInputRef.current = normalizedInput;
+            fetchRenderSprite(normalizedInput);
         }
-    }, [parts, fetchRenderSprite]);
+    }, [normalizedInput, fetchRenderSprite]);
     // Cleanup effect for component unmount
     react.useEffect(() => {
         return () => {
@@ -668,7 +897,7 @@ const useZoomPan = ({ displayWidth, displayHeight, minScale = 1, maxScale = 4, }
     };
 };
 
-const BuildRender = ({ parts, width, height, size, apiConfig, useSpriteRenderOptions, mouseSensitivity = 0.2, touchSensitivity = 0.2, }) => {
+const BuildRender = ({ parts, shareCode, width, height, size, apiConfig, useSpriteRenderOptions, mouseSensitivity = 0.2, touchSensitivity = 0.2, showGrid, cameraOffsetX, gridSettings, }) => {
     const canvasRef = react.useRef(null);
     const containerRef = react.useRef(null);
     const [img, setImg] = react.useState(null);
@@ -676,8 +905,28 @@ const BuildRender = ({ parts, width, height, size, apiConfig, useSpriteRenderOpt
     const [bouncingAllowed, setBouncingAllowed] = react.useState(false);
     const displayW = width ?? size ?? 300;
     const displayH = height ?? size ?? 300;
+    // Build the render input - prefer shareCode if provided (preserves interactive state like case fan slots)
+    const renderInput = react.useMemo(() => {
+        if (shareCode) {
+            return {
+                type: 'shareCode',
+                shareCode,
+                profile: parts?.profile,
+                showGrid,
+                cameraOffsetX,
+                gridSettings,
+            };
+        }
+        return {
+            type: 'parts',
+            parts: parts,
+            showGrid,
+            cameraOffsetX,
+            gridSettings,
+        };
+    }, [shareCode, parts, showGrid, cameraOffsetX, gridSettings]);
     // Use custom hook for sprite rendering
-    const { spriteSrc, isRenderingSprite, renderError, spriteMetadata } = useSpriteRender(parts, apiConfig, undefined, useSpriteRenderOptions);
+    const { spriteSrc, isRenderingSprite, renderError, spriteMetadata } = useSpriteRender(renderInput, apiConfig, undefined, useSpriteRenderOptions);
     const { value: progressValue, isBouncing } = useBouncePatternProgress(bouncingAllowed);
     const total = spriteMetadata ? spriteMetadata.totalFrames : 72;
     const cols = spriteMetadata ? spriteMetadata.cols : 12;
@@ -1012,8 +1261,12 @@ exports.buildApiUrl = buildApiUrl;
 exports.buildHeaders = buildHeaders;
 exports.calculateCircularFrame = calculateCircularFrame;
 exports.calculateCircularTime = calculateCircularTime;
+exports.createRenderByShareCodeJob = createRenderByShareCodeJob;
 exports.getAvailableParts = getAvailableParts;
+exports.getBuildByShareCode = getBuildByShareCode;
+exports.getPartsByIds = getPartsByIds;
 exports.renderBuildExperimental = renderBuildExperimental;
+exports.renderByShareCode = renderByShareCode;
 exports.renderSpriteExperimental = renderSpriteExperimental;
 exports.useBouncePatternProgress = useBouncePatternProgress;
 exports.useBuildRender = useBuildRender;