@cympotek/3d-transfer-sdk 1.0.0 → 1.0.1

package/README.md

@@ -8,6 +8,7 @@ TypeScript SDK for Mobius 3D Transfer API - Convert images to 3D models using AI
 - Support for multiple frameworks (Vite, Next.js, Expo, Node.js)
 - Environment variable based configuration
 - Axios-based HTTP client
+- **React ModelViewer component** for displaying 3D GLB models
 
 ## Installation
 
@@ -117,11 +118,17 @@ async function convertImageTo3D(imageFile: File) {
       path: { requestId },
     });
 
-    status = statusResponse.data.data.status;
-    console.log('Status:', status);
+    const data = statusResponse.data.data;
+    status = data.status;
+    console.log('Status:', status, 'Phase:', data.phase, 'Progress:', data.progress);
+
+    // 2D preview is available when phase changes to 3d_generation
+    if (data.result?.preview_2d_url) {
+      console.log('2D Preview ready:', data.result.preview_2d_url);
+    }
 
     if (status === 'COMPLETED') {
-      result = statusResponse.data.data.result;
+      result = data.result;
     }
   }
 
@@ -135,20 +142,63 @@ async function convertImageTo3D(imageFile: File) {
 }
 ```
 
-### React/Next.js Example
+## React Components
+
+### ModelViewer
+
+The SDK includes a React component for displaying 3D GLB/GLTF models using Google's [model-viewer](https://modelviewer.dev/) web component.
+
+```tsx
+import { ModelViewer } from '@cympotek/3d-transfer-sdk/react';
+
+function My3DViewer() {
+  return (
+    <ModelViewer
+      src="https://example.com/model.glb"
+      alt="3D Model"
+      cameraControls
+      autoRotate
+      style={{ width: '100%', height: '400px' }}
+    />
+  );
+}
+```
+
+#### ModelViewer Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | *required* | URL to the GLB/GLTF model file |
+| `alt` | `string` | `'3D Model'` | Alt text for accessibility |
+| `cameraControls` | `boolean` | `true` | Enable camera controls (pan, zoom, rotate) |
+| `autoRotate` | `boolean` | `true` | Enable auto rotation |
+| `shadowIntensity` | `number` | `1` | Shadow intensity (0-1) |
+| `poster` | `string` | - | Poster image URL to show while loading |
+| `className` | `string` | - | CSS class name |
+| `style` | `CSSProperties` | - | Inline styles |
+| `loading` | `'auto' \| 'lazy' \| 'eager'` | `'auto'` | Loading strategy |
+| `reveal` | `'auto' \| 'manual'` | `'auto'` | Reveal strategy |
+| `onLoad` | `() => void` | - | Callback when model is loaded |
+| `onError` | `(error: Error) => void` | - | Callback when error occurs |
+
+#### Complete React Example with ModelViewer
 
 ```tsx
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import {
   createTransfer3DClient,
   getTransfer3dStyles,
   initiateTransfer3dConversion,
   getTransfer3dStatus,
 } from '@cympotek/3d-transfer-sdk';
+import { ModelViewer } from '@cympotek/3d-transfer-sdk/react';
 
 export function ImageTo3DConverter() {
   const [status, setStatus] = useState<string>('idle');
-  const [modelUrl, setModelUrl] = useState<string | null>(null);
+  const [progress, setProgress] = useState(0);
+  const [preview2dUrl, setPreview2dUrl] = useState<string | null>(null);
+  const [glbUrl, setGlbUrl] = useState<string | null>(null);
+  const [webViewUrl, setWebViewUrl] = useState<string | null>(null);
 
   const handleConvert = async (file: File, style: string) => {
     const client = createTransfer3DClient();
@@ -169,10 +219,23 @@ export function ImageTo3DConverter() {
         path: { requestId },
       });
 
-      if (statusData.data.status === 'COMPLETED') {
-        setModelUrl(statusData.data.result.model_3d_url);
+      const result = statusData.data;
+      setProgress(result.progress || 0);
+
+      // Web view URL for viewing on main site
+      if (result.web_view_url) {
+        setWebViewUrl(result.web_view_url);
+      }
+
+      // 2D preview becomes available during 3D generation phase
+      if (result.result?.preview_2d_url) {
+        setPreview2dUrl(result.result.preview_2d_url);
+      }
+
+      if (result.status === 'COMPLETED') {
+        setGlbUrl(result.result.glb_url);
         setStatus('completed');
-      } else if (statusData.data.status === 'FAILED') {
+      } else if (result.status === 'FAILED') {
         setStatus('failed');
       } else {
         setTimeout(pollStatus, 2000);
@@ -184,8 +247,36 @@ export function ImageTo3DConverter() {
 
   return (
     <div>
-      <p>Status: {status}</p>
-      {modelUrl && <a href={modelUrl}>Download 3D Model</a>}
+      <p>Status: {status} ({progress}%)</p>
+
+      {/* Link to view progress on main site */}
+      {webViewUrl && (
+        <a href={webViewUrl} target="_blank" rel="noopener noreferrer">
+          View on main site
+        </a>
+      )}
+
+      {/* 2D styled preview */}
+      {preview2dUrl && (
+        <div>
+          <h3>2D Style Preview</h3>
+          <img src={preview2dUrl} alt="2D Preview" />
+        </div>
+      )}
+
+      {/* 3D Model Viewer */}
+      {glbUrl && (
+        <div>
+          <h3>3D Model</h3>
+          <ModelViewer
+            src={glbUrl}
+            alt="Generated 3D Model"
+            cameraControls
+            autoRotate
+            style={{ width: '100%', height: '400px' }}
+          />
+        </div>
+      )}
     </div>
   );
 }
@@ -261,18 +352,29 @@ Get the status of a conversion request.
   data: {
     request_id: string;
     status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED';
-    phase: '2d_style_transfer' | '3d_generation';
+    phase: '2d_style_transfer' | '3d_generation_pending' | '3d_generation';
     progress: number;  // 0-100
+    web_view_url: string;  // URL to view progress on main site
     result?: {
-      preview_2d_url: string;
-      model_3d_url: string;
-      glb_url: string;
+      preview_2d_url: string;  // Available when 2D transfer completes
+      model_3d_url: string;    // Available when fully completed
+      glb_url: string;         // GLB file URL (same as model_3d_url)
     };
     error?: string;  // Present if status is FAILED
   }
 }
 ```
 
+## Conversion Phases
+
+| Phase | Progress | Description |
+|-------|----------|-------------|
+| `2d_style_transfer` | 0-50% | Image is being styled with AI |
+| `3d_generation_pending` | 50% | 2D complete, waiting for 3D to start |
+| `3d_generation` | 50-100% | 3D model is being generated |
+
+**Note:** The `preview_2d_url` becomes available when the phase changes to `3d_generation_pending` or `3d_generation`, allowing you to show the styled image while the 3D model is still being generated.
+
 ## Status Values
 
 | Status | Description |
@@ -293,6 +395,9 @@ import type {
   GetTransfer3dStatusData,
   GetTransfer3dStatusResponse,
 } from '@cympotek/3d-transfer-sdk';
+
+// React component types
+import type { ModelViewerProps } from '@cympotek/3d-transfer-sdk/react';
 ```
 
 ## Error Handling
@@ -319,25 +424,21 @@ try {
 }
 ```
 
-## Regenerating the SDK
+## Demo Application
 
-This SDK is auto-generated from the OpenAPI specification. To regenerate:
+A complete React demo application is available in the [examples/react-demo](https://github.com/cympotek/mobius-frontier/tree/main/builds/3d-transfer-sdk/examples/react-demo) directory.
+
+To run the demo:
 
 ```bash
-# In the mobius-frontier project root
-make sdk-3d-transfer
+cd examples/react-demo
+pnpm install
+cp .env.example .env  # Configure your API URL and token
+pnpm dev
 ```
 
-## OpenAPI Specification
-
-The OpenAPI spec is included in this package at `openapi.json`. You can use it to:
-- Generate clients for other languages
-- Import into API testing tools (Postman, Insomnia)
-- Generate documentation
-
 ## Support
 
-- [API Documentation](https://api.localhost/docs/api)
 - [GitHub Issues](https://github.com/cympotek/mobius-frontier/issues)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cympotek/3d-transfer-sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "TypeScript SDK for Mobius 3D Transfer API - Convert images to 3D models",
   "type": "module",
   "main": "dist/index.js",