@snowcone-app/sdk 0.25.0 → 0.27.0

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.
@@ -211,6 +211,14 @@ interface PlacementSettings {
211
211
  }
212
212
  interface WebSocketConfig {
213
213
  productId: string;
214
+ /**
215
+ * Ask the box for frame flow control: it keeps at most `window` un-acked frames per mockup and coalesces the rest
216
+ * (latest wins), so a slow link or a slow screen never queues a backlog behind Cloudflare. ONLY for a client that
217
+ * calls {@link RealtimeMockupService.ackFrame} when it has drawn a frame: every frame must be acked (the service
218
+ * acks superseded and stale-dropped frames itself). Dormant on a box that does not negotiate it (config_received
219
+ * without `acks`).
220
+ */
221
+ acks?: boolean;
214
222
  mockupIds: string[];
215
223
  variantId: string;
216
224
  shop: string;
@@ -311,6 +319,10 @@ interface MockupResult {
311
319
  * (see {@link RealtimeMockupService.getLatestSentVersions}).
312
320
  */
313
321
  versions?: Record<string, number>;
322
+ /** Frame sequence number (per socket, increasing; boxes with flow control). Ack it with ackFrame once drawn. */
323
+ seq?: number;
324
+ /** Older frames of this mockup the box dropped in favour of this one (flow control, latest wins). */
325
+ coalesced?: number;
314
326
  /** Server-side render time in ms */
315
327
  renderMs?: number;
316
328
  /** Time from blob received to render start in ms */
@@ -352,6 +364,17 @@ interface MockupResult {
352
364
  }
353
365
  interface WebSocketMessage {
354
366
  type: string;
367
+ /** config_received: frame flow control the box agreed to (only when the config asked for acks). */
368
+ acks?: {
369
+ window: number;
370
+ timeoutMs?: number;
371
+ };
372
+ /** Frame sequence number (mockup_rendered, mockup_frame, ack_timeout). */
373
+ seq?: number;
374
+ /** Older frames of this mockup dropped in favour of this one (flow control). */
375
+ coalesced?: number;
376
+ /** E_RT_ACK_BAD: why the ack was rejected. */
377
+ reason?: string;
355
378
  sessionId?: string;
356
379
  mockups?: MockupResult[];
357
380
  imageUrl?: string;
@@ -428,7 +451,18 @@ interface RealtimeRenderError {
428
451
  */
429
452
  mockupId?: string;
430
453
  }
454
+ /** Frame flow control as negotiated with the box (null: not asked, or the box does not support it). */
455
+ interface RealtimeAcksState {
456
+ window: number;
457
+ timeoutMs: number;
458
+ /** Frames the box gave up waiting for (E_RT_ACK_TIMEOUT): a frame the client never acked within timeoutMs. */
459
+ timeouts: number;
460
+ /** Acks the box rejected (E_RT_ACK_BAD): a client protocol fault. */
461
+ badAcks: number;
462
+ }
431
463
  interface RealtimeMockupState {
464
+ /** Frame flow control, when negotiated (see WebSocketConfig.acks). */
465
+ acks: RealtimeAcksState | null;
432
466
  isConnected: boolean;
433
467
  sessionId: string | null;
434
468
  /** Render node that answered the handshake (`connected.box`); null until
@@ -471,6 +505,15 @@ interface RealtimeMockupCallbacks {
471
505
  */
472
506
  onError?: (error: string, detail: RealtimeRenderError) => void;
473
507
  onLog?: (message: string, type: 'info' | 'sent' | 'received') => void;
508
+ /** A flow-control fault: the box timed out waiting for an ack (E_RT_ACK_TIMEOUT) or rejected one (E_RT_ACK_BAD).
509
+ * Never a picture refusal and never the session's renderError: the frames keep coming. */
510
+ onAckFault?: (fault: {
511
+ code: 'E_RT_ACK_TIMEOUT' | 'E_RT_ACK_BAD';
512
+ mockupId?: string;
513
+ seq?: number;
514
+ reason?: string;
515
+ message: string;
516
+ }) => void;
474
517
  }
475
518
  declare class RealtimeMockupService {
476
519
  private wsUrl;
@@ -502,6 +545,12 @@ declare class RealtimeMockupService {
502
545
  private tokenProvider?;
503
546
  private pendingFrames;
504
547
  private liveObjectUrls;
548
+ private acks;
549
+ private ackedSeq;
550
+ private newestSeq;
551
+ private pendingAcks;
552
+ private ackFlushScheduled;
553
+ private supersededFrameUrls;
505
554
  private renewTimer;
506
555
  private isConnecting;
507
556
  private connectAttempt;
@@ -590,6 +639,21 @@ declare class RealtimeMockupService {
590
639
  * E_RERENDER_INCOMPLETE | E_RERENDER_RATE_LIMITED). Never changes the
591
640
  * session's mockupIds.
592
641
  */
642
+ /**
643
+ * True when `url` was a ws-delivered frame for a mockup and a newer frame for that mockup has since arrived (the SDK
644
+ * revoked the old one). A consumer whose load of `url` failed uses this to tell supersession (the newer frame is
645
+ * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
646
+ */
647
+ isFrameSuperseded(url: string): boolean;
648
+ /**
649
+ * The client is done with frame `seq` of `mockupId`: drawn on screen, superseded, not shown by any element, or
650
+ * failed. Cumulative per mockup. A no-op unless flow control was negotiated (see WebSocketConfig.acks). Acks are
651
+ * batched into one frame_ack message per animation frame.
652
+ */
653
+ ackFrame(mockupId: string, seq: number): boolean;
654
+ private flushAcks;
655
+ /** Whether frame flow control is active on this session (negotiated with the box for the current config). */
656
+ isAcking(): boolean;
593
657
  rerender(mockupIds: string[]): boolean;
594
658
  getLastSentVersion(): number;
595
659
  sendColorBlob(placement: string, hexColor: string): boolean;
@@ -604,4 +668,4 @@ declare class RealtimeMockupService {
604
668
  clearMockups(): void;
605
669
  }
606
670
 
607
- export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v };
671
+ export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v, type RealtimeAcksState as w };
@@ -211,6 +211,14 @@ interface PlacementSettings {
211
211
  }
212
212
  interface WebSocketConfig {
213
213
  productId: string;
214
+ /**
215
+ * Ask the box for frame flow control: it keeps at most `window` un-acked frames per mockup and coalesces the rest
216
+ * (latest wins), so a slow link or a slow screen never queues a backlog behind Cloudflare. ONLY for a client that
217
+ * calls {@link RealtimeMockupService.ackFrame} when it has drawn a frame: every frame must be acked (the service
218
+ * acks superseded and stale-dropped frames itself). Dormant on a box that does not negotiate it (config_received
219
+ * without `acks`).
220
+ */
221
+ acks?: boolean;
214
222
  mockupIds: string[];
215
223
  variantId: string;
216
224
  shop: string;
@@ -311,6 +319,10 @@ interface MockupResult {
311
319
  * (see {@link RealtimeMockupService.getLatestSentVersions}).
312
320
  */
313
321
  versions?: Record<string, number>;
322
+ /** Frame sequence number (per socket, increasing; boxes with flow control). Ack it with ackFrame once drawn. */
323
+ seq?: number;
324
+ /** Older frames of this mockup the box dropped in favour of this one (flow control, latest wins). */
325
+ coalesced?: number;
314
326
  /** Server-side render time in ms */
315
327
  renderMs?: number;
316
328
  /** Time from blob received to render start in ms */
@@ -352,6 +364,17 @@ interface MockupResult {
352
364
  }
353
365
  interface WebSocketMessage {
354
366
  type: string;
367
+ /** config_received: frame flow control the box agreed to (only when the config asked for acks). */
368
+ acks?: {
369
+ window: number;
370
+ timeoutMs?: number;
371
+ };
372
+ /** Frame sequence number (mockup_rendered, mockup_frame, ack_timeout). */
373
+ seq?: number;
374
+ /** Older frames of this mockup dropped in favour of this one (flow control). */
375
+ coalesced?: number;
376
+ /** E_RT_ACK_BAD: why the ack was rejected. */
377
+ reason?: string;
355
378
  sessionId?: string;
356
379
  mockups?: MockupResult[];
357
380
  imageUrl?: string;
@@ -428,7 +451,18 @@ interface RealtimeRenderError {
428
451
  */
429
452
  mockupId?: string;
430
453
  }
454
+ /** Frame flow control as negotiated with the box (null: not asked, or the box does not support it). */
455
+ interface RealtimeAcksState {
456
+ window: number;
457
+ timeoutMs: number;
458
+ /** Frames the box gave up waiting for (E_RT_ACK_TIMEOUT): a frame the client never acked within timeoutMs. */
459
+ timeouts: number;
460
+ /** Acks the box rejected (E_RT_ACK_BAD): a client protocol fault. */
461
+ badAcks: number;
462
+ }
431
463
  interface RealtimeMockupState {
464
+ /** Frame flow control, when negotiated (see WebSocketConfig.acks). */
465
+ acks: RealtimeAcksState | null;
432
466
  isConnected: boolean;
433
467
  sessionId: string | null;
434
468
  /** Render node that answered the handshake (`connected.box`); null until
@@ -471,6 +505,15 @@ interface RealtimeMockupCallbacks {
471
505
  */
472
506
  onError?: (error: string, detail: RealtimeRenderError) => void;
473
507
  onLog?: (message: string, type: 'info' | 'sent' | 'received') => void;
508
+ /** A flow-control fault: the box timed out waiting for an ack (E_RT_ACK_TIMEOUT) or rejected one (E_RT_ACK_BAD).
509
+ * Never a picture refusal and never the session's renderError: the frames keep coming. */
510
+ onAckFault?: (fault: {
511
+ code: 'E_RT_ACK_TIMEOUT' | 'E_RT_ACK_BAD';
512
+ mockupId?: string;
513
+ seq?: number;
514
+ reason?: string;
515
+ message: string;
516
+ }) => void;
474
517
  }
475
518
  declare class RealtimeMockupService {
476
519
  private wsUrl;
@@ -502,6 +545,12 @@ declare class RealtimeMockupService {
502
545
  private tokenProvider?;
503
546
  private pendingFrames;
504
547
  private liveObjectUrls;
548
+ private acks;
549
+ private ackedSeq;
550
+ private newestSeq;
551
+ private pendingAcks;
552
+ private ackFlushScheduled;
553
+ private supersededFrameUrls;
505
554
  private renewTimer;
506
555
  private isConnecting;
507
556
  private connectAttempt;
@@ -590,6 +639,21 @@ declare class RealtimeMockupService {
590
639
  * E_RERENDER_INCOMPLETE | E_RERENDER_RATE_LIMITED). Never changes the
591
640
  * session's mockupIds.
592
641
  */
642
+ /**
643
+ * True when `url` was a ws-delivered frame for a mockup and a newer frame for that mockup has since arrived (the SDK
644
+ * revoked the old one). A consumer whose load of `url` failed uses this to tell supersession (the newer frame is
645
+ * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
646
+ */
647
+ isFrameSuperseded(url: string): boolean;
648
+ /**
649
+ * The client is done with frame `seq` of `mockupId`: drawn on screen, superseded, not shown by any element, or
650
+ * failed. Cumulative per mockup. A no-op unless flow control was negotiated (see WebSocketConfig.acks). Acks are
651
+ * batched into one frame_ack message per animation frame.
652
+ */
653
+ ackFrame(mockupId: string, seq: number): boolean;
654
+ private flushAcks;
655
+ /** Whether frame flow control is active on this session (negotiated with the box for the current config). */
656
+ isAcking(): boolean;
593
657
  rerender(mockupIds: string[]): boolean;
594
658
  getLastSentVersion(): number;
595
659
  sendColorBlob(placement: string, hexColor: string): boolean;
@@ -604,4 +668,4 @@ declare class RealtimeMockupService {
604
668
  clearMockups(): void;
605
669
  }
606
670
 
607
- export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v };
671
+ export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v, type RealtimeAcksState as w };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.25.0",
3
+ "version": "0.27.0",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",