@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.
- package/CHANGELOG.md +21 -0
- package/dist/{chunk-P3ZDE6LZ.js → chunk-IW7DXXGY.js} +103 -2
- package/dist/index.cjs +149 -17
- package/dist/index.d.cts +47 -3
- package/dist/index.d.ts +47 -3
- package/dist/index.js +41 -16
- package/dist/react.cjs +127 -4
- package/dist/react.d.cts +6 -1
- package/dist/react.d.ts +6 -1
- package/dist/react.js +25 -3
- package/dist/{websocket-Cy0Y29CW.d.cts → websocket-CvN0UU2j.d.cts} +65 -1
- package/dist/{websocket-Cy0Y29CW.d.ts → websocket-CvN0UU2j.d.ts} +65 -1
- package/package.json +1 -1
|
@@ -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 };
|