@pixeasy/customizer 0.0.9-beta.0 → 0.0.10-beta.0

package/README.md

@@ -2,13 +2,13 @@
 
 Framework-agnostic SDK to embed the Pixeasy customizer in Angular, React, Vue, or any ESM app.
 
-## Install
+## Installation
 
 ```bash
 npm install @pixeasy/customizer
 ```
 
-## Quick start
+## Quick Start
 
 ```ts
 import { createPixeasyBuilder } from '@pixeasy/customizer';
@@ -23,60 +23,160 @@ builder.open({
 });
 ```
 
-`container` can be an element id (`string`) or an `HTMLElement`.
+**Note:** `container` can be a CSS selector string (element id) or an `HTMLElement` reference.
 
-## API
+## API Reference
 
 ### `createPixeasyBuilder()`
 
-Returns an instance of `PixeasyBuilder`.
+Creates and returns a new `PixeasyBuilder` instance. You can create multiple builder instances if needed.
+
+```ts
+const builder = createPixeasyBuilder();
+```
 
 ### `PixeasyBuilder.open(options)`
 
+Opens the customizer with the specified configuration.
+
+#### Options
+
 ```ts
 type PixeasyOpenOptions = {
-  container: string | HTMLElement;
-  apiKey: string;
-  productId: string;
-  locale?: string;
-  theme?: string;
-  readonly?: boolean;
+  // Required
+  container: string | HTMLElement; // CSS selector or DOM element to mount the customizer
+  apiKey: string; // Your API key (format: dk_xxx_yyy)
+  productId: string; // Product ID (UUID format)
+
+  // Optional
+  predesignId?: string; // Load a pre-designed template
+  submissionNumber?: string; // Load an existing submission for editing
+  locale?: string; // Language/locale code (e.g., 'en', 'fr', 'de')
+  theme?: string; // Theme name or color scheme
+  readonly?: boolean; // Set to true to disable editing (view-only mode)
 };
 ```
 
-### `PixeasyBuilder` events
+#### Option Details
+
+| Option             | Type                    | Required | Description                                                                           |
+| ------------------ | ----------------------- | -------- | ------------------------------------------------------------------------------------- |
+| `container`        | `string \| HTMLElement` | Yes      | Target container to mount the customizer. If string, treated as element ID.           |
+| `apiKey`           | `string`                | Yes      | Your Pixeasy API key for authentication.                                              |
+| `productId`        | `string`                | Yes      | UUID of the product to customize.                                                     |
+| `predesignId`      | `string`                | No       | Load a pre-designed template/predesign. Useful for template-based workflows.          |
+| `submissionNumber` | `string`                | No       | Load an existing submission for editing or review. Use with `readonly` for view-only. |
+| `locale`           | `string`                | No       | Set the UI language. Examples: `'en'`, `'fr'`, `'de'`, `'es'`.                        |
+| `theme`            | `string`                | No       | Apply a theme or color scheme to the customizer UI.                                   |
+| `readonly`         | `boolean`               | No       | Enable view-only mode. Prevents editing and submission. Perfect for order review.     |
 
-All events can be subscribed via `builder.on(name, handler)`.
+### Events
 
-| Event | When it fires | Payload |
-| --- | --- | --- |
-| `manifest-loaded` | After the customizer manifest is loaded successfully for the current `productId`. | `ManifestLoadedEventDetail` |
-| `sdk-ready` | After the customizer finishes its initial load and is ready for interaction. | `SdkReadyEventDetail` |
-| `submission:success` | Fires when a submission request succeeds. | `SubmissionSuccessEventDetail` |
-| `submission:failed` | Fires when a submission request fails (API error or network/exception). | `SubmissionFailedEventDetail` |
-| `error` | When the runtime reports an error (invalid config, manifest load failure, asset load failure, or unexpected runtime error). | `ErrorEventDetail` |
-| `closed` | When you call `builder.close()` (the element is removed and listeners are detached). | `undefined` |
+All events can be subscribed using `builder.on(eventName, handler)`.
 
-Note: `manifest-loaded`, `sdk-ready`, `submission:success`, `submission:failed`, and `error` originate as DOM `CustomEvent`s from the `<pixeasy-customizer>` element; `closed` is emitted by `PixeasyBuilder`.
+| Event                | When it fires                                                                                | Payload                        |
+| -------------------- | -------------------------------------------------------------------------------------------- | ------------------------------ |
+| `manifest-loaded`    | After the product manifest loads successfully.                                               | `ManifestLoadedEventDetail`    |
+| `sdk-ready`          | After the customizer initializes and is ready for interaction.                               | `SdkReadyEventDetail`          |
+| `submission:success` | After a successful submission.                                                               | `SubmissionSuccessEventDetail` |
+| `submission:failed`  | When submission fails (API error, network issue, or validation error).                       | `SubmissionFailedEventDetail`  |
+| `error`              | When a runtime error occurs (invalid config, manifest load failed, asset load failed, etc.). | `ErrorEventDetail`             |
+| `closed`             | When the customizer is closed via `builder.close()`.                                         | `undefined`                    |
 
-Usage:
+#### Event Payload Types
+
+```ts
+// Fires after manifest is loaded
+interface ManifestLoadedEventDetail {
+  productId: string;
+  manifestMeta?: {
+    version?: string;
+  } | null;
+}
+
+// Fires when SDK is ready for use
+interface SdkReadyEventDetail {
+  productId: string;
+}
+
+// Fires on successful submission
+interface SubmissionSuccessEventDetail {
+  productId?: string;
+  views?: string[]; // Generated views/angles
+  submissionNumber: string; // Unique submission identifier
+}
+
+// Fires when submission fails
+interface SubmissionFailedEventDetail {
+  productId?: string;
+  views?: string[];
+  message: string; // Error message
+  errors?: string[]; // Detailed error list
+}
+
+// Fires on SDK errors
+interface ErrorEventDetail {
+  code: 'INVALID_CONFIG' | 'MANIFEST_LOAD_FAILED' | 'ASSET_LOAD_FAILED' | 'RUNTIME_ERROR';
+  message: string;
+}
+```
+
+#### Event Subscription Example
 
 ```ts
 import { SDK_EVENTS } from '@pixeasy/customizer';
 
+const builder = createPixeasyBuilder();
+
+builder.open({
+  container: 'pixeasyBuilder',
+  apiKey: 'dk_xxx_yyy',
+  productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+});
+
+// Subscribe to events
 builder
-  .on(SDK_EVENTS.MANIFEST_LOADED, (event) => console.log('manifest-loaded', event))
-  .on(SDK_EVENTS.SDK_READY, (event) => console.log(event.productId))
-  .on(SDK_EVENTS.SUBMISSION_SUCCESS, (event) => console.log(event.submissionNumber))
-  .on(SDK_EVENTS.SUBMISSION_FAILED, (event) => console.error(event.message))
-  .on(SDK_EVENTS.ERROR, (event) => console.error(event.code, event.message))
-  .on(SDK_EVENTS.CLOSED, () => console.log('closed'));
+  .on(SDK_EVENTS.MANIFEST_LOADED, (event) => {
+    console.log('Manifest loaded for product:', event.productId);
+  })
+  .on(SDK_EVENTS.SDK_READY, (event) => {
+    console.log('Customizer is ready!', event.productId);
+  })
+  .on(SDK_EVENTS.SUBMISSION_SUCCESS, (event) => {
+    console.log('Submission successful:', event.submissionNumber);
+    console.log('Generated views:', event.views);
+  })
+  .on(SDK_EVENTS.SUBMISSION_FAILED, (event) => {
+    console.error('Submission failed:', event.message);
+    if (event.errors) {
+      console.error('Errors:', event.errors);
+    }
+  })
+  .on(SDK_EVENTS.ERROR, (event) => {
+    console.error(`Error [${event.code}]:`, event.message);
+  })
+  .on(SDK_EVENTS.CLOSED, () => {
+    console.log('Customizer closed');
+  });
 ```
 
-## Framework examples
+#### Unsubscribing from Events
+
+```ts
+const handleSuccess = (event) => console.log('Success:', event.submissionNumber);
+
+builder.on(SDK_EVENTS.SUBMISSION_SUCCESS, handleSuccess);
+
+// Later, remove the listener
+builder.off(SDK_EVENTS.SUBMISSION_SUCCESS, handleSuccess);
+```
+
+## Framework Examples
 
 ### React
 
+#### Basic Usage
+
 ```tsx
 import { useEffect } from 'react';
 import { createPixeasyBuilder } from '@pixeasy/customizer';
@@ -85,42 +185,293 @@ import '@pixeasy/customizer/styles.css';
 export function CustomizerHost() {
   useEffect(() => {
     const builder = createPixeasyBuilder();
+
     builder.open({
       container: 'pixeasyBuilder',
       apiKey: 'dk_xxx_yyy',
       productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
     });
+
+    return () => builder.close();
+  }, []);
+
+  return <div id="pixeasyBuilder" />;
+}
+```
+
+#### Advanced Usage with Events
+
+```tsx
+import { useEffect } from 'react';
+import { createPixeasyBuilder, SDK_EVENTS } from '@pixeasy/customizer';
+import '@pixeasy/customizer/styles.css';
+
+export function CustomizerWithEvents() {
+  useEffect(() => {
+    const builder = createPixeasyBuilder();
+
+    builder
+      .on(SDK_EVENTS.SDK_READY, () => {
+        console.log('Customizer ready');
+      })
+      .on(SDK_EVENTS.SUBMISSION_SUCCESS, (event) => {
+        console.log('Submission successful:', event.submissionNumber);
+        // Handle success - e.g., show confirmation, redirect, etc.
+      })
+      .on(SDK_EVENTS.ERROR, (event) => {
+        console.error('Error occurred:', event.message);
+      })
+      .open({
+        container: 'pixeasyBuilder',
+        apiKey: 'dk_xxx_yyy',
+        productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+        locale: 'en',
+        theme: 'dark',
+      });
+
     return () => builder.close();
   }, []);
 
+  return <div id="pixeasyBuilder" style={{ width: '100%', height: '100vh' }} />;
+}
+```
+
+#### Load Existing Submission
+
+```tsx
+import { useEffect } from 'react';
+import { createPixeasyBuilder, SDK_EVENTS } from '@pixeasy/customizer';
+import '@pixeasy/customizer/styles.css';
+
+export function EditSubmission({ submissionNumber }: { submissionNumber: string }) {
+  useEffect(() => {
+    const builder = createPixeasyBuilder();
+
+    builder
+      .on(SDK_EVENTS.SUBMISSION_SUCCESS, (event) => {
+        console.log('Updated submission:', event.submissionNumber);
+      })
+      .open({
+        container: 'pixeasyBuilder',
+        apiKey: 'dk_xxx_yyy',
+        productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+        submissionNumber: submissionNumber, // Load for editing
+      });
+
+    return () => builder.close();
+  }, [submissionNumber]);
+
+  return <div id="pixeasyBuilder" />;
+}
+```
+
+#### View-Only Mode
+
+```tsx
+import { useEffect } from 'react';
+import { createPixeasyBuilder } from '@pixeasy/customizer';
+import '@pixeasy/customizer/styles.css';
+
+export function ViewSubmission({ submissionNumber }: { submissionNumber: string }) {
+  useEffect(() => {
+    const builder = createPixeasyBuilder();
+
+    builder.open({
+      container: 'pixeasyBuilder',
+      apiKey: 'dk_xxx_yyy',
+      productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+      submissionNumber: submissionNumber,
+      readonly: true, // Enable view-only mode
+    });
+
+    return () => builder.close();
+  }, [submissionNumber]);
+
   return <div id="pixeasyBuilder" />;
 }
 ```
 
 ### Vue
 
+#### Basic Usage
+
 ```ts
 import { onMounted, onBeforeUnmount } from 'vue';
 import { createPixeasyBuilder } from '@pixeasy/customizer';
 import '@pixeasy/customizer/styles.css';
 
-const builder = createPixeasyBuilder();
+export default {
+  setup() {
+    const builder = createPixeasyBuilder();
 
-onMounted(() => {
-  builder.open({
-    container: 'pixeasyBuilder',
-    apiKey: 'dk_xxx_yyy',
-    productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
-  });
-});
+    onMounted(() => {
+      builder.open({
+        container: 'pixeasyBuilder',
+        apiKey: 'dk_xxx_yyy',
+        productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+      });
+    });
+
+    onBeforeUnmount(() => builder.close());
 
-onBeforeUnmount(() => builder.close());
+    return {};
+  },
+};
+```
+
+#### With Events and Options
+
+```ts
+import { onMounted, onBeforeUnmount } from 'vue';
+import { createPixeasyBuilder, SDK_EVENTS } from '@pixeasy/customizer';
+import '@pixeasy/customizer/styles.css';
+
+export default {
+  props: {
+    submissionNumber: [String, null],
+  },
+  setup(props) {
+    const builder = createPixeasyBuilder();
+
+    onMounted(() => {
+      builder
+        .on(SDK_EVENTS.SDK_READY, () => {
+          console.log('Customizer initialized');
+        })
+        .on(SDK_EVENTS.SUBMISSION_SUCCESS, (event) => {
+          console.log('Saved:', event.submissionNumber);
+        })
+        .open({
+          container: 'pixeasyBuilder',
+          apiKey: 'dk_xxx_yyy',
+          productId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+          submissionNumber: props.submissionNumber || undefined,
+          locale: 'en',
+        });
+    });
+
+    onBeforeUnmount(() => builder.close());
+
+    return {};
+  },
+};
 ```
 
 ## Exports
 
-- `createPixeasyBuilder`
-- `PixeasyBuilder`
-- `definePixeasyCustomizerElement`
-- typed options/events (`PixeasyOpenOptions`, `ManifestLoadedEventDetail`, etc.)
-- stylesheet export: `@pixeasy/customizer/styles.css`
+The package exports the following:
+
+### Classes & Functions
+
+- **`createPixeasyBuilder()`** - Factory function to create a new `PixeasyBuilder` instance
+- **`PixeasyBuilder`** - Main class for managing the customizer lifecycle
+- **`definePixeasyCustomizerElement()`** - Registers the `<pixeasy-customizer>` custom element (auto-called internally)
+- **`generateThumbnails()`** - Utility function to generate product thumbnails from SVG and 3D models
+
+### Types
+
+- **`PixeasyOpenOptions`** - Configuration object for `builder.open()`
+- **`SdkElementConfig`** - Base configuration interface
+- **`ManifestLoadedEventDetail`** - Payload for manifest-loaded event
+- **`SdkReadyEventDetail`** - Payload for sdk-ready event
+- **`SubmissionSuccessEventDetail`** - Payload for submission:success event
+- **`SubmissionFailedEventDetail`** - Payload for submission:failed event
+- **`ErrorEventDetail`** - Payload for error event
+- **`SDK_EVENTS`** - Enum of all available event names
+- **`BuilderEventName`** - Type-safe event name type
+- **`ThumbnailView`** - View types for thumbnail generation ('front' | 'right' | 'back' | 'left')
+- **`GeneratedThumbnail`** - Thumbnail generation result
+
+### Stylesheets
+
+- **`@pixeasy/customizer/styles.css`** - Required stylesheet (import once in your app)
+
+## Common Use Cases
+
+### Create a New Design from Scratch
+
+```ts
+builder.open({
+  container: 'pixeasyBuilder',
+  apiKey: 'dk_xxx_yyy',
+  productId: 'product-uuid',
+});
+```
+
+### Use a Template/Predesign
+
+```ts
+builder.open({
+  container: 'pixeasyBuilder',
+  apiKey: 'dk_xxx_yyy',
+  productId: 'product-uuid',
+  predesignId: 'predesign-uuid', // Start with a pre-designed template
+});
+```
+
+### Edit an Existing Submission
+
+```ts
+builder.open({
+  container: 'pixeasyBuilder',
+  apiKey: 'dk_xxx_yyy',
+  productId: 'product-uuid',
+  submissionNumber: 'SUB-12345', // Load existing submission
+});
+```
+
+### Review Order (Read-Only)
+
+```ts
+builder.open({
+  container: 'pixeasyBuilder',
+  apiKey: 'dk_xxx_yyy',
+  productId: 'product-uuid',
+  submissionNumber: 'SUB-12345',
+  readonly: true, // Disable editing
+});
+```
+
+### Multi-Language Support
+
+```ts
+builder.open({
+  container: 'pixeasyBuilder',
+  apiKey: 'dk_xxx_yyy',
+  productId: 'product-uuid',
+  locale: 'de', // German, or 'fr', 'es', etc.
+});
+```
+
+## Best Practices
+
+1. **Always import styles** - Include the CSS stylesheet once in your app:
+
+   ```ts
+   import '@pixeasy/customizer/styles.css';
+   ```
+
+2. **Handle errors gracefully** - Always subscribe to the `error` event:
+
+   ```ts
+   builder.on(SDK_EVENTS.ERROR, (event) => {
+     console.error(`Error [${event.code}]: ${event.message}`);
+     // Show user-friendly error message
+   });
+   ```
+
+3. **Validate API key and Product ID** - These are required for the customizer to function:
+
+   ```ts
+   if (!apiKey || !productId) {
+     throw new Error('Missing required configuration');
+   }
+   ```
+
+4. **Clean up on unmount** - Always call `builder.close()` when the component unmounts to prevent memory leaks
+
+5. **Use events for flow control** - Subscribe to `submission:success` to handle post-submission actions
+
+6. **Handle locale properly** - Set the locale to match user preferences before opening
+
+7. **Use readonly mode for reviews** - Enable `readonly: true` when showing past submissions or previews

package/index.d.ts

@@ -2,6 +2,7 @@ export interface SdkElementConfig {
   apiKey: string;
   productId: string;
   predesignId?: string;
+  submissionNumber?: string;
   locale?: string;
   theme?: string;
   readonly?: boolean;
@@ -52,30 +53,33 @@ export const SDK_EVENTS: {
 export type BuilderEventName = (typeof SDK_EVENTS)[keyof typeof SDK_EVENTS];
 export type UrlOrText = { type: 'url'; value: string } | { type: 'text'; value: string };
 
-
 export class PixeasyBuilder {
   open(options: PixeasyOpenOptions): this;
   on<K extends BuilderEventName>(
     name: K,
-    handler: (payload: {
-      [typeof SDK_EVENTS.MANIFEST_LOADED]: ManifestLoadedEventDetail;
-      [typeof SDK_EVENTS.SDK_READY]: SdkReadyEventDetail;
-      [typeof SDK_EVENTS.SUBMISSION_SUCCESS]: SubmissionSuccessEventDetail;
-      [typeof SDK_EVENTS.SUBMISSION_FAILED]: SubmissionFailedEventDetail;
-      [typeof SDK_EVENTS.ERROR]: ErrorEventDetail;
-      [typeof SDK_EVENTS.CLOSED]: undefined;
-    }[K]) => void,
+    handler: (
+      payload: {
+        [typeof SDK_EVENTS.MANIFEST_LOADED]: ManifestLoadedEventDetail;
+        [typeof SDK_EVENTS.SDK_READY]: SdkReadyEventDetail;
+        [typeof SDK_EVENTS.SUBMISSION_SUCCESS]: SubmissionSuccessEventDetail;
+        [typeof SDK_EVENTS.SUBMISSION_FAILED]: SubmissionFailedEventDetail;
+        [typeof SDK_EVENTS.ERROR]: ErrorEventDetail;
+        [typeof SDK_EVENTS.CLOSED]: undefined;
+      }[K],
+    ) => void,
   ): this;
   off<K extends BuilderEventName>(
     name: K,
-    handler: (payload: {
-      [typeof SDK_EVENTS.MANIFEST_LOADED]: ManifestLoadedEventDetail;
-      [typeof SDK_EVENTS.SDK_READY]: SdkReadyEventDetail;
-      [typeof SDK_EVENTS.SUBMISSION_SUCCESS]: SubmissionSuccessEventDetail;
-      [typeof SDK_EVENTS.SUBMISSION_FAILED]: SubmissionFailedEventDetail;
-      [typeof SDK_EVENTS.ERROR]: ErrorEventDetail;
-      [typeof SDK_EVENTS.CLOSED]: undefined;
-    }[K]) => void,
+    handler: (
+      payload: {
+        [typeof SDK_EVENTS.MANIFEST_LOADED]: ManifestLoadedEventDetail;
+        [typeof SDK_EVENTS.SDK_READY]: SdkReadyEventDetail;
+        [typeof SDK_EVENTS.SUBMISSION_SUCCESS]: SubmissionSuccessEventDetail;
+        [typeof SDK_EVENTS.SUBMISSION_FAILED]: SubmissionFailedEventDetail;
+        [typeof SDK_EVENTS.ERROR]: ErrorEventDetail;
+        [typeof SDK_EVENTS.CLOSED]: undefined;
+      }[K],
+    ) => void,
   ): this;
   close(): this;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixeasy/customizer",
-  "version": "0.0.9-beta.0",
+  "version": "0.0.10-beta.0",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {