@pixeasy/customizer-stage 0.0.44 → 0.0.46

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -361,6 +361,8 @@ export default {
361
361
 
362
362
  ### Personalized Design Templates
363
363
 
364
+ For a complete third-party integration guide, including save-event payloads and the server webhook, see [Personalized template integration](docs/personalized-template-integration.md).
365
+
364
366
  The same npm package also registers `<pixeasy-personalized-customizer>`. This is a separate
365
367
  runtime from `<pixeasy-customizer>`: it loads the latest active published template assigned to
366
368
  the requested 2D product. Existing `createPixeasyBuilder()` integrations keep their behavior.
@@ -375,6 +377,11 @@ const personalizer = createPixeasyPersonalizedBuilder();
375
377
  personalizer.on(PERSONALIZED_CUSTOMIZER_EVENTS.READY, ({ version }) => {
376
378
  console.log('Published template version', version);
377
379
  });
380
+ personalizer.on(PERSONALIZED_CUSTOMIZER_EVENTS.CHANGED, (state) => {
381
+ // Fires for product, variant, and personalization changes.
382
+ // Use state.productId to update the product shown by your storefront.
383
+ console.log('Selected product', state.productId);
384
+ });
378
385
  personalizer.on(PERSONALIZED_CUSTOMIZER_EVENTS.APPLIED, (saved) => {
379
386
  // Store these credentials with the customer's account or order.
380
387
  // Save saved.designId and saved.editToken on your backend.
@@ -418,7 +425,8 @@ personalizer.open({
418
425
  ```
419
426
 
420
427
  The SDK loads the exact published template version used by the design and restores its values
421
- and image transforms. Applying again updates the same design and increments its revision.
428
+ and image transforms. Saving again currently creates a new submission with a new design ID,
429
+ submission number, and edit token; store the latest credentials from the event.
422
430
  `GET /public/personalized-designs/{designId}` requires the distributor API key and
423
431
  `X-Edit-Token` header; it can refresh expired export links.
424
432
 
@@ -471,6 +479,9 @@ The custom element also accepts `api-key`, `product-id`, `template-id`, optional
471
479
  attributes. The builder exposes `getDesignState()`, `getCanvasSvg()`, `getCanvasImage()`,
472
480
  and `close()`. The canvas export methods return the current product view with the design
473
481
  as SVG or a PNG data URL after rendering is ready; they return `null` before that.
482
+ The builders pass `apiKey` and `editToken` without adding DOM attributes. Existing
483
+ custom-element attributes remain supported and are removed when the element connects.
484
+ The browser still uses the API key in requests, so this only removes it from the DOM.
474
485
  `personalized:changed`
475
486
  fires as text or images change, `personalized:applied` fires after the design has been saved,
476
487
  and `personalized:error` reports loading failures. The design state contains template
@@ -0,0 +1,166 @@
1
+ # Personalized template integration
2
+
3
+ This guide is for a storefront or order system embedding the Pixeasy personalized template editor. It covers the browser SDK events, the result of **Save Design**, reopening a saved design, and the separate server webhook. The personalized editor is available through `@pixeasy/customizer-stage` (use the package name supplied for your environment).
4
+
5
+ ## Before you start
6
+
7
+ Obtain a distributor API key with `ProductRead`, `SubmissionCreate`, and `SubmissionRead` scopes, an active published personalized template, and a 2D product assigned to that template. Allow your storefront origin for the distributor API key. For server callbacks, configure the distributor's webhook URL and delay in Pixeasy; webhook delivery requires a reachable HTTPS endpoint that accepts JSON POST requests.
8
+
9
+ The SDK loads the published template at `GET /public/products/{productId}/personalized-design-templates/{templateId}` and the selected product details at `GET /public/products/{productId}/personalized-design-templates/{templateId}/product`, using `X-API-Key`. The `productId` passed to `open()` must be one of the template's enabled products. The shopper can then change products and variants offered by that template.
10
+
11
+ ## Embed the editor
12
+
13
+ ```bash
14
+ npm install @pixeasy/customizer-stage
15
+ ```
16
+
17
+ ```html
18
+ <div id="personalizer-canvas"></div>
19
+ <div id="personalizer-controls"></div>
20
+ ```
21
+
22
+ ```ts
23
+ import {
24
+ createPixeasyPersonalizedBuilder,
25
+ PERSONALIZED_CUSTOMIZER_EVENTS,
26
+ } from '@pixeasy/customizer-stage';
27
+ import '@pixeasy/customizer-stage/styles.css';
28
+
29
+ const editor = createPixeasyPersonalizedBuilder();
30
+
31
+ editor.on(PERSONALIZED_CUSTOMIZER_EVENTS.READY, ({ productId, templateId, version }) => {
32
+ console.log('Template ready', productId, templateId, version);
33
+ });
34
+
35
+ editor.on(PERSONALIZED_CUSTOMIZER_EVENTS.CHANGED, (state) => {
36
+ console.log('Selected product and variant', state.productId, state.variantId);
37
+ });
38
+
39
+ editor.on(PERSONALIZED_CUSTOMIZER_EVENTS.APPLIED, async (saved) => {
40
+ // Send this result to your own backend and associate it with the customer/order.
41
+ await fetch('/api/orders/current/personalized-design', {
42
+ method: 'POST',
43
+ headers: { 'Content-Type': 'application/json' },
44
+ body: JSON.stringify({
45
+ designId: saved.designId,
46
+ editToken: saved.editToken,
47
+ revision: saved.revision,
48
+ submissionNumber: saved.submissionNumber,
49
+ productId: saved.state.productId,
50
+ variantId: saved.state.variantId,
51
+ }),
52
+ });
53
+ });
54
+
55
+ editor.on(PERSONALIZED_CUSTOMIZER_EVENTS.ERROR, ({ message }) => {
56
+ console.error('Editor could not load', message);
57
+ });
58
+
59
+ editor.open({
60
+ container: 'personalizer-controls',
61
+ canvasContainerId: 'personalizer-canvas', // Optional; omit to keep the canvas inside the controls.
62
+ apiKey: 'dk_xxx_yyy',
63
+ userUniqueId: 'your-customer-id', // Optional; enables the customer's logo library.
64
+ productId: 'product-uuid',
65
+ templateId: 'template-uuid',
66
+ });
67
+ ```
68
+
69
+ `container` accepts an element ID or an `HTMLElement`; `canvasContainerId` is an element ID. Both elements must already exist and must be different. Optional `className` adds a class to the custom element. Optional `readonly` disables editing. Call `editor.close()` on unmount. `getDesignState()` returns the current state or `null` before initialization; `getCanvasSvg()` and `getCanvasImage()` return the current view or `null` before rendering. The canvas image is a PNG data URL.
70
+
71
+ You can also use the registered `<pixeasy-personalized-customizer>` element directly. Set `api-key`, `product-id`, and `template-id`; optional attributes include `user-unique-id`, `canvas-container-id`, `design-id`, `edit-token`, `submission-number`, and `readonly`. Listen for the same event names with `addEventListener`; their payload is in `CustomEvent.detail`. Events bubble and cross the element's shadow boundary.
72
+
73
+ ## Browser events
74
+
75
+ | Event | When | `detail` / builder callback argument |
76
+ | --- | --- | --- |
77
+ | `personalized:ready` | The published template and product have loaded. | `{ productId, templateId, version }` |
78
+ | `personalized:changed` | An editable value, selected product, or variant changes. | Current `PersonalizedDesignState` (see below). May fire repeatedly. |
79
+ | `personalized:applied` | **Save Design** has persisted successfully. | `PersonalizedAppliedDesign` (see below). Fires on each successful save, including after reopening a design. |
80
+ | `personalized:error` | Editor initialization or loading fails. | `{ message }`. Save failures are shown in the editor; do not rely on this event for save errors. |
81
+ | `personalized:closed` | The builder's `close()` is called. | `undefined`. This is a builder lifecycle event. |
82
+
83
+ `on(event, handler)` registers a handler and `off(event, handler)` removes it. Register handlers before `open()` so the initial ready event is not missed. For a direct custom element, use `event.detail` instead of the builder callback argument.
84
+
85
+ `PersonalizedDesignState` contains `productId`, optional `variantId`, `variantName`, and `variantColorCode`, `templateId`, `version`, `textValues`, `imageValues`, optional `imageNames`, `defaultAssetIds`, `imageOffsets`, `imageScales`, optional `imageAxisScales`, `imageRotations`, `imageCrops`, optional `cropDetails`, and `textStyles`. Keys in these maps are template field keys. Some image values can be data URLs; do not use `personalized:changed` as an order submission or log its full payload. The save event is the point at which a persistent design ID exists.
86
+
87
+ ## What Save Design returns
88
+
89
+ The editor validates required text/images, renders the active canvases and product previews, then calls `POST /public/personalized-designs/apply`. The API returns `designId`, `editToken`, `revision`, `submissionNumber`, `variantIdentifier`, `previews`, and `personalizationPlacements`. The SDK then requests `GET /public/personalized-designs/{designId}` with `X-API-Key` and `X-Edit-Token` to add the PDF URL and saved canvas export links. The resulting `personalized:applied` payload has this shape:
90
+
91
+ ```ts
92
+ interface PersonalizedAppliedDesign {
93
+ designId: string; // Same ID as the shared design submission / webhook submissionId.
94
+ editToken: string; // Secret required to reopen or retrieve this design.
95
+ revision: number; // Currently 1 for each new saved submission.
96
+ submissionNumber: string; // Human-readable submission reference.
97
+ variantIdentifier: string; // Selected product variant's external identifier.
98
+ previews: Array<{ viewType: string; url: string; width: number; height: number }>;
99
+ personalizationPlacements: Array<{
100
+ placementKey: string;
101
+ type: 'text' | 'logo';
102
+ value: string | null;
103
+ logoUrl: string | null;
104
+ snapshotId?: string | null;
105
+ }>;
106
+ pdfUrl: string;
107
+ canvases: Array<{ canvasKey: string; pngUrl: string; width: number; height: number }>;
108
+ state: PersonalizedDesignState;
109
+ savedState?: PersonalizedDesignState;
110
+ }
111
+ ```
112
+
113
+ `previews` are composed product or variant images. `personalizationPlacements` describe saved text/logo placement snapshots. `canvases` are per-canvas PNG exports with pixel dimensions. `state` is the editor state at save time; `savedState`, when present, is the state returned by the follow-up GET after server-side image references have been stored. `pdfUrl` may be empty while background PDF generation is pending. If that follow-up GET fails, save still succeeds and `personalized:applied` still fires: `pdfUrl` is empty, `savedState` is absent, and `canvases[].pngUrl` falls back to a PNG data URL. Preview and export URLs are temporary; fetch or refresh them when needed rather than treating them as permanent file locations.
114
+
115
+ Store `designId`, `editToken`, `revision`, `submissionNumber`, selected product/variant, and your own customer/order reference on **your server**. Treat the edit token as a customer secret. The browser event is for the current shopper session; it is not a server notification. Update your order association with the latest `designId` after every successful save.
116
+
117
+ To reopen a saved design, pass its `designId` and `editToken` to `open()` with the product and template. The SDK restores the exact published template version and saved values. **Saving again currently creates a new submission**, with a new `designId`, `submissionNumber`, and `editToken`; its revision starts at `1`. Keep the new credentials from the latest `personalized:applied` event. The previous submission remains a separate record. `GET /public/personalized-designs/{designId}` with `X-API-Key` and `X-Edit-Token` can refresh export links. `submissionNumber` is also an optional `open()` input for loading an existing submission; use the design ID plus edit token for the editable saved-design flow.
118
+
119
+ ## Server webhook
120
+
121
+ Configure the distributor's webhook URL in Pixeasy. When the production PDF is ready, the backend queues a JSON POST to that URL with `event: "design.submission.ready"`. The configured webhook delay applies to the first delivery. For this 2D personalized flow, a production SVG is not required. The webhook is asynchronous and may arrive after the browser save event, after the shopper leaves, or after a retry. A saved design does not guarantee a webhook: PDF processing must complete and a distributor webhook URL must be configured.
122
+
123
+ Example payload (IDs, URLs, and times are illustrative):
124
+
125
+ ```json
126
+ {
127
+ "event": "design.submission.ready",
128
+ "submissionId": "11111111-1111-1111-1111-111111111111",
129
+ "submissionNumber": "DS-000123",
130
+ "productId": "22222222-2222-2222-2222-222222222222",
131
+ "selectedVariantId": "33333333-3333-3333-3333-333333333333",
132
+ "variantIdentifier": "BLUE-L",
133
+ "status": "Completed",
134
+ "pdfUrl": "https://files.example/production.pdf",
135
+ "productionSvgUrl": null,
136
+ "previewUrls": ["https://files.example/front.png"],
137
+ "previews": [
138
+ { "viewType": "Front", "url": "https://files.example/front.png", "width": 1200, "height": 1200 }
139
+ ],
140
+ "overlays": [
141
+ {
142
+ "id": "44444444-4444-4444-4444-444444444444",
143
+ "type": "text",
144
+ "placementKey": "front-name",
145
+ "placementName": "Front name",
146
+ "textValue": "Jordan",
147
+ "value": "Jordan",
148
+ "imageUrl": null,
149
+ "logoUrl": null,
150
+ "renderWidth": 2.25,
151
+ "renderHeight": 0.5,
152
+ "designAreaSizeRanges": [],
153
+ "printableWidthInches": 10,
154
+ "printableHeightInches": 12
155
+ }
156
+ ],
157
+ "createdAt": "2026-11-18T10:15:30Z",
158
+ "completedAt": "2026-11-18T10:20:14Z"
159
+ }
160
+ ```
161
+
162
+ `submissionId` matches the SDK's `designId`; `submissionNumber` also links the two. `previewUrls` is the flat URL list; `previews` adds view type and pixel dimensions. `overlays` contains text and logo snapshots. For text, `textValue` and `value` contain the text. For logo, `imageUrl` and `logoUrl` contain the logo resource URL when available. Each overlay also has `placementKey`, optional `placementName`, optional render dimensions, printable dimensions in inches for 2D placements, and `designAreaSizeRanges` with size range names, sizes, default flag, and printable dimensions. Nullable fields can be `null`; arrays can be empty. `productionSvgUrl` is normally `null` for 2D submissions. Generated download links can expire.
163
+
164
+ Return a 2xx response promptly to acknowledge delivery. Non-2xx responses, timeouts, and transport failures are retried; the default maximum is five attempts with increasing delays. Process by `submissionId` and `event` idempotently because retries may repeat the same payload. The current delivery code sends JSON with `Content-Type: application/json`; it does not attach a webhook signature header. Protect your endpoint using your own network or URL controls as appropriate. A separate test callback uses `event: "design.submission.test"` with `distributorId` and `sentAt`; it does not carry a design.
165
+
166
+ The ready webhook is queued once per submission when a pending, retrying, or successful ready delivery already exists. Since each save currently creates a new submission, an edited and saved design can generate another ready webhook with a new `submissionId`. Use your latest stored design ID to identify the current version for an order. The webhook reports production readiness and artifacts, while the browser event reports the immediate saved design and edit credentials.
package/index.d.ts CHANGED
@@ -16,8 +16,10 @@ export interface PixeasyOpenOptions extends SdkElementConfig {
16
16
 
17
17
  export interface PersonalizedCustomizerOpenOptions {
18
18
  container: string | HTMLElement;
19
+ className?: string;
19
20
  canvasContainerId?: string;
20
21
  apiKey: string;
22
+ userUniqueId?: string;
21
23
  productId: string;
22
24
  templateId: string;
23
25
  readonly?: boolean;
@@ -30,18 +32,26 @@ export interface PersonalizedAppliedDesign {
30
32
  designId: string;
31
33
  editToken: string;
32
34
  revision: number;
35
+ submissionNumber: string;
36
+ variantIdentifier: string;
37
+ previews: Array<{ viewType: string; url: string; width: number; height: number }>;
38
+ personalizationPlacements: SubmissionPersonalizationPlacementDetail[];
33
39
  pdfUrl: string;
34
40
  canvases: Array<{ canvasKey: string; pngUrl: string; width: number; height: number }>;
35
41
  state: PersonalizedDesignState;
42
+ savedState?: PersonalizedDesignState;
36
43
  }
37
44
 
38
45
  export interface PersonalizedDesignState {
39
46
  productId: string;
40
47
  variantId?: string;
48
+ variantName?: string;
49
+ variantColorCode?: string;
41
50
  templateId: string;
42
51
  version: number;
43
52
  textValues: Record<string, string>;
44
53
  imageValues: Record<string, string[]>;
54
+ imageNames?: Record<string, string[]>;
45
55
  defaultAssetIds: Record<string, string[]>;
46
56
  imageOffsets: Record<string, { x: number; y: number }[]>;
47
57
  imageScales: Record<string, number[]>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pixeasy/customizer-stage",
3
- "version": "0.0.44",
3
+ "version": "0.0.46",
4
4
  "type": "module",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "publishConfig": {
@@ -27,6 +27,7 @@
27
27
  "pixeasy-customizer.css",
28
28
  "index.d.ts",
29
29
  "README.md",
30
+ "docs",
30
31
  "LICENSE",
31
32
  "assets",
32
33
  "media"