@swell/apps-sdk 2.0.0-alpha.5 → 2.0.0-alpha.7

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.
Files changed (38) hide show
  1. package/README.md +129 -0
  2. package/dist/component-frame.html +13 -0
  3. package/dist/components-client.d.cts +85 -0
  4. package/dist/components-client.d.ts +85 -0
  5. package/dist/components-client.js +196 -0
  6. package/dist/components-focus.d.cts +2 -0
  7. package/dist/components-focus.d.ts +2 -0
  8. package/dist/components-focus.js +68 -0
  9. package/dist/components-frame.d.cts +18 -0
  10. package/dist/components-frame.d.ts +18 -0
  11. package/dist/components-frame.js +251 -0
  12. package/dist/components-host.d.cts +60 -0
  13. package/dist/components-host.d.ts +60 -0
  14. package/dist/components-host.js +315 -0
  15. package/dist/components-payment.d.cts +11 -0
  16. package/dist/components-payment.d.ts +11 -0
  17. package/dist/components-payment.js +52 -0
  18. package/dist/components-placement.d.cts +18 -0
  19. package/dist/components-placement.d.ts +18 -0
  20. package/dist/components-placement.js +131 -0
  21. package/dist/components-protocol.d.cts +89 -0
  22. package/dist/components-protocol.d.ts +89 -0
  23. package/dist/components-protocol.js +20 -0
  24. package/dist/components-types.d.cts +84 -0
  25. package/dist/components-types.d.ts +84 -0
  26. package/dist/components-types.js +1 -0
  27. package/dist/components.d.cts +6 -0
  28. package/dist/components.d.ts +6 -0
  29. package/dist/components.js +2 -0
  30. package/dist/index.d.cts +1 -1
  31. package/dist/index.d.ts +1 -1
  32. package/dist/request-context.d.cts +4 -0
  33. package/dist/request-context.d.ts +4 -0
  34. package/dist/request-context.js +4 -0
  35. package/dist/version.d.cts +1 -1
  36. package/dist/version.d.ts +1 -1
  37. package/dist/version.js +1 -1
  38. package/package.json +11 -1
@@ -0,0 +1,11 @@
1
+ export interface PaymentActionsOptions {
2
+ vaultUrl: string;
3
+ publicKey: string;
4
+ gateway: string;
5
+ /** The current cart's account, read at call time */
6
+ accountId: () => string | undefined;
7
+ }
8
+ export declare function paymentActions(options: PaymentActionsOptions): {
9
+ createIntent: (data: unknown) => Promise<unknown>;
10
+ getIntent: (data: unknown) => Promise<unknown>;
11
+ };
@@ -0,0 +1,11 @@
1
+ export interface PaymentActionsOptions {
2
+ vaultUrl: string;
3
+ publicKey: string;
4
+ gateway: string;
5
+ /** The current cart's account, read at call time */
6
+ accountId: () => string | undefined;
7
+ }
8
+ export declare function paymentActions(options: PaymentActionsOptions): {
9
+ createIntent: (data: unknown) => Promise<unknown>;
10
+ getIntent: (data: unknown) => Promise<unknown>;
11
+ };
@@ -0,0 +1,52 @@
1
+ // Payment intents of payment components, through the vault exactly as swell-js sends them
2
+ const TIMEOUT_MS = 20_000;
3
+ function serialize(key, value, out) {
4
+ if (Array.isArray(value)) {
5
+ value.forEach((item, index) => serialize(`${key}[${item !== null && typeof item === 'object' ? index : ''}]`, item, out));
6
+ }
7
+ else if (value !== null && typeof value === 'object') {
8
+ for (const [name, item] of Object.entries(value))
9
+ serialize(`${key}[${name}]`, item, out);
10
+ }
11
+ else if (value !== undefined) {
12
+ out.push(`${encodeURIComponent(key)}=${encodeURIComponent(value === null ? '' : String(value))}`);
13
+ }
14
+ }
15
+ async function vaultRequest(options, method, intent) {
16
+ const accountId = options.accountId();
17
+ const data = { gateway: options.gateway, ...(accountId ? { account_id: accountId } : {}), intent };
18
+ const query = [];
19
+ serialize('$jsonp', { method, callback: 'none' }, query);
20
+ serialize('$data', data, query);
21
+ serialize('$key', options.publicKey, query);
22
+ // AbortSignal.timeout is missing in Safari before 16
23
+ const controller = new AbortController();
24
+ const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
25
+ let result;
26
+ try {
27
+ const response = await fetch(`${options.vaultUrl.replace(/\/+$/, '')}/intent?${query.join('&')}`, { signal: controller.signal });
28
+ result = (await response.json());
29
+ }
30
+ catch (error) {
31
+ if (error?.name === 'AbortError')
32
+ throw new Error('Request timed out after 20 seconds');
33
+ throw error;
34
+ }
35
+ finally {
36
+ clearTimeout(timer);
37
+ }
38
+ if (result?.$error)
39
+ throw new Error(result.$error);
40
+ if (!result || (result.$status ?? 0) >= 300)
41
+ throw new Error('A connection error occurred while making the request');
42
+ const errors = result.$data?.errors;
43
+ if (errors)
44
+ throw new Error(Object.values(errors)[0]?.message || 'Unknown error');
45
+ return result.$data;
46
+ }
47
+ export function paymentActions(options) {
48
+ return {
49
+ createIntent: (data) => vaultRequest(options, 'post', data),
50
+ getIntent: (data) => vaultRequest(options, 'get', data),
51
+ };
52
+ }
@@ -0,0 +1,18 @@
1
+ import type { Rect } from './components-protocol.cjs';
2
+ export interface PlacedFrame {
3
+ readonly iframe: HTMLIFrameElement;
4
+ /** Sizes the placeholder, which the iframe fills, to the component's height. */
5
+ setHeight(height: number): void;
6
+ /** Covers the viewport while the component shows a modal. Returns the placeholder position. */
7
+ setOverlay(on: boolean): Rect;
8
+ destroy(): void;
9
+ }
10
+ /**
11
+ * Puts the component iframe in the placeholder, so it lays out, stacks, clips and takes focus like any other
12
+ * element of the host page. For overlay the iframe enters the top layer as a manual popover: it covers the
13
+ * viewport above everything else and escapes its ancestors' opacity, transform, filter and overflow, without
14
+ * moving in the DOM (a moved iframe reloads). Without the Popover API it is a fixed box with the top z-index,
15
+ * which a transformed or filtered ancestor still confines. During overlay the rest of the page is inert and
16
+ * does not scroll.
17
+ */
18
+ export declare function placeFrame(placeholder: HTMLElement, src: string, title: string, onOverlayRect: (rect: Rect) => void): PlacedFrame;
@@ -0,0 +1,18 @@
1
+ import type { Rect } from './components-protocol.js';
2
+ export interface PlacedFrame {
3
+ readonly iframe: HTMLIFrameElement;
4
+ /** Sizes the placeholder, which the iframe fills, to the component's height. */
5
+ setHeight(height: number): void;
6
+ /** Covers the viewport while the component shows a modal. Returns the placeholder position. */
7
+ setOverlay(on: boolean): Rect;
8
+ destroy(): void;
9
+ }
10
+ /**
11
+ * Puts the component iframe in the placeholder, so it lays out, stacks, clips and takes focus like any other
12
+ * element of the host page. For overlay the iframe enters the top layer as a manual popover: it covers the
13
+ * viewport above everything else and escapes its ancestors' opacity, transform, filter and overflow, without
14
+ * moving in the DOM (a moved iframe reloads). Without the Popover API it is a fixed box with the top z-index,
15
+ * which a transformed or filtered ancestor still confines. During overlay the rest of the page is inert and
16
+ * does not scroll.
17
+ */
18
+ export declare function placeFrame(placeholder: HTMLElement, src: string, title: string, onOverlayRect: (rect: Rect) => void): PlacedFrame;
@@ -0,0 +1,131 @@
1
+ // A plain block that fills the placeholder. During overlay the iframe is also a popover: these inline styles keep
2
+ // the user agent's popover border, padding and colors off it
3
+ const IN_FLOW = {
4
+ display: 'block', position: 'static', inset: 'auto', margin: '0', padding: '0', border: '0',
5
+ width: '100%', height: '100%', 'max-width': 'none', 'max-height': 'none', overflow: 'visible',
6
+ background: 'transparent', 'color-scheme': 'normal', 'z-index': 'auto',
7
+ };
8
+ // The z-index only matters without the Popover API: the top layer is above every z-index
9
+ const COVER = { position: 'fixed', inset: '0px', width: '100vw', height: '100vh', 'z-index': '2147483647' };
10
+ function rectOf(element) {
11
+ const { top, left, width } = element.getBoundingClientRect();
12
+ return { top, left, width };
13
+ }
14
+ /**
15
+ * Puts the component iframe in the placeholder, so it lays out, stacks, clips and takes focus like any other
16
+ * element of the host page. For overlay the iframe enters the top layer as a manual popover: it covers the
17
+ * viewport above everything else and escapes its ancestors' opacity, transform, filter and overflow, without
18
+ * moving in the DOM (a moved iframe reloads). Without the Popover API it is a fixed box with the top z-index,
19
+ * which a transformed or filtered ancestor still confines. During overlay the rest of the page is inert and
20
+ * does not scroll.
21
+ */
22
+ export function placeFrame(placeholder, src, title, onOverlayRect) {
23
+ const document = placeholder.ownerDocument;
24
+ const window = document.defaultView;
25
+ if (!window)
26
+ throw new Error('Component placeholder must be attached to a window');
27
+ const iframe = document.createElement('iframe');
28
+ iframe.src = src;
29
+ iframe.title = title;
30
+ iframe.setAttribute('allow', 'payment *; publickey-credentials-get *');
31
+ const style = (styles) => {
32
+ for (const name in styles)
33
+ iframe.style.setProperty(name, styles[name]);
34
+ };
35
+ style(IN_FLOW);
36
+ // No height until the component reports one: an iframe without a height is 150px
37
+ placeholder.style.height = '0px';
38
+ placeholder.appendChild(iframe);
39
+ let overlay = false;
40
+ let frame = 0;
41
+ let lastRect = '';
42
+ let savedOverflow = null;
43
+ // Elements made inert for the overlay, restored after it; elements that were inert already are left alone
44
+ let inerted = [];
45
+ const keyOf = (rect) => `${rect.top}:${rect.left}:${rect.width}`;
46
+ const follow = () => {
47
+ const rect = rectOf(placeholder);
48
+ const key = keyOf(rect);
49
+ if (key !== lastRect) {
50
+ lastRect = key;
51
+ onOverlayRect(rect);
52
+ }
53
+ frame = window.requestAnimationFrame(follow);
54
+ };
55
+ // Everything beside the iframe's ancestors: focus and clicks cannot reach the page under the overlay
56
+ const inertRest = () => {
57
+ for (let node = iframe; node.parentElement && node !== document.body; node = node.parentElement) {
58
+ for (const sibling of Array.from(node.parentElement.children)) {
59
+ if (sibling === node || sibling.hasAttribute('inert'))
60
+ continue;
61
+ sibling.setAttribute('inert', '');
62
+ inerted.push(sibling);
63
+ }
64
+ }
65
+ };
66
+ const lockScroll = (lock) => {
67
+ const root = document.documentElement;
68
+ if (lock && savedOverflow === null) {
69
+ savedOverflow = root.style.overflow;
70
+ root.style.overflow = 'hidden';
71
+ }
72
+ if (!lock && savedOverflow !== null) {
73
+ root.style.overflow = savedOverflow;
74
+ savedOverflow = null;
75
+ }
76
+ };
77
+ // The iframe is a popover only during overlay, so host styles for [popover] never reach it in the page.
78
+ // showPopover throws for an iframe out of the page or already shown; the overlay styles apply either way
79
+ const popover = (show) => {
80
+ if (show)
81
+ iframe.setAttribute('popover', 'manual');
82
+ const toggle = show ? iframe.showPopover : iframe.hidePopover;
83
+ try {
84
+ if (typeof toggle === 'function')
85
+ toggle.call(iframe);
86
+ }
87
+ catch {
88
+ // Out of the page, or already in that state
89
+ }
90
+ if (!show)
91
+ iframe.removeAttribute('popover');
92
+ };
93
+ const release = () => {
94
+ window.cancelAnimationFrame(frame);
95
+ for (const element of inerted)
96
+ element.removeAttribute('inert');
97
+ inerted = [];
98
+ lockScroll(false);
99
+ };
100
+ return {
101
+ iframe,
102
+ setHeight(height) {
103
+ placeholder.style.height = `${height}px`;
104
+ },
105
+ setOverlay(on) {
106
+ const rect = rectOf(placeholder);
107
+ if (on === overlay)
108
+ return rect;
109
+ overlay = on;
110
+ if (on) {
111
+ style(COVER);
112
+ popover(true);
113
+ lockScroll(true);
114
+ inertRest();
115
+ lastRect = keyOf(rect);
116
+ frame = window.requestAnimationFrame(follow);
117
+ }
118
+ else {
119
+ release();
120
+ popover(false);
121
+ style(IN_FLOW);
122
+ }
123
+ return rect;
124
+ },
125
+ destroy() {
126
+ release();
127
+ iframe.remove();
128
+ placeholder.style.height = '';
129
+ },
130
+ };
131
+ }
@@ -0,0 +1,89 @@
1
+ export declare const PROTOCOL = "swell:component";
2
+ /**
3
+ * Protocol evolution: changes within version 1 are additive. Both sides ignore message types and
4
+ * fields they do not know, so new messages and fields need no version change. A breaking change
5
+ * (a removed or renamed message or field, or a changed meaning) needs a new version.
6
+ */
7
+ export declare const PROTOCOL_VERSION = 1;
8
+ export declare const TOKEN_HEADER = "Swell-Component-Token";
9
+ /** Placeholder position in the host viewport. */
10
+ export interface Rect {
11
+ readonly top: number;
12
+ readonly left: number;
13
+ readonly width: number;
14
+ }
15
+ /** Component props as sent over postMessage: data only. */
16
+ export interface WireProps {
17
+ value: unknown;
18
+ context: unknown;
19
+ params: Record<string, unknown>;
20
+ settings: Record<string, unknown>;
21
+ locale: string;
22
+ readonly: boolean;
23
+ }
24
+ export type HostMessage = {
25
+ type: 'init';
26
+ props: WireProps;
27
+ token: string | null;
28
+ actions?: string[];
29
+ } | {
30
+ type: 'update';
31
+ props: Partial<WireProps>;
32
+ } | {
33
+ type: 'token';
34
+ token: string | null;
35
+ } | {
36
+ type: 'event';
37
+ call: number;
38
+ name: string;
39
+ data: unknown;
40
+ } | {
41
+ type: 'reply';
42
+ call: number;
43
+ result?: unknown;
44
+ error?: string;
45
+ } | {
46
+ type: 'rect';
47
+ rect: Rect;
48
+ } | {
49
+ type: 'focus';
50
+ };
51
+ export type FrameMessage = {
52
+ type: 'hello';
53
+ } | {
54
+ type: 'ready';
55
+ } | {
56
+ type: 'change';
57
+ value: unknown;
58
+ } | {
59
+ type: 'validity';
60
+ error: string | null;
61
+ } | {
62
+ type: 'resize';
63
+ height: number;
64
+ } | {
65
+ type: 'overlay';
66
+ on: boolean;
67
+ } | {
68
+ type: 'result';
69
+ call: number;
70
+ result?: unknown;
71
+ error?: string;
72
+ } | {
73
+ type: 'call';
74
+ call: number;
75
+ name: string;
76
+ data: unknown;
77
+ } | {
78
+ type: 'error';
79
+ message: string;
80
+ };
81
+ interface Envelope {
82
+ $swell: typeof PROTOCOL;
83
+ v: number;
84
+ channel: string;
85
+ }
86
+ export declare function wrap<T extends HostMessage | FrameMessage>(channel: string, message: T): T & Envelope;
87
+ /** The message when it belongs to this protocol version and channel, otherwise null. */
88
+ export declare function unwrap<T extends HostMessage | FrameMessage>(data: unknown, channel: string): T | null;
89
+ export {};
@@ -0,0 +1,89 @@
1
+ export declare const PROTOCOL = "swell:component";
2
+ /**
3
+ * Protocol evolution: changes within version 1 are additive. Both sides ignore message types and
4
+ * fields they do not know, so new messages and fields need no version change. A breaking change
5
+ * (a removed or renamed message or field, or a changed meaning) needs a new version.
6
+ */
7
+ export declare const PROTOCOL_VERSION = 1;
8
+ export declare const TOKEN_HEADER = "Swell-Component-Token";
9
+ /** Placeholder position in the host viewport. */
10
+ export interface Rect {
11
+ readonly top: number;
12
+ readonly left: number;
13
+ readonly width: number;
14
+ }
15
+ /** Component props as sent over postMessage: data only. */
16
+ export interface WireProps {
17
+ value: unknown;
18
+ context: unknown;
19
+ params: Record<string, unknown>;
20
+ settings: Record<string, unknown>;
21
+ locale: string;
22
+ readonly: boolean;
23
+ }
24
+ export type HostMessage = {
25
+ type: 'init';
26
+ props: WireProps;
27
+ token: string | null;
28
+ actions?: string[];
29
+ } | {
30
+ type: 'update';
31
+ props: Partial<WireProps>;
32
+ } | {
33
+ type: 'token';
34
+ token: string | null;
35
+ } | {
36
+ type: 'event';
37
+ call: number;
38
+ name: string;
39
+ data: unknown;
40
+ } | {
41
+ type: 'reply';
42
+ call: number;
43
+ result?: unknown;
44
+ error?: string;
45
+ } | {
46
+ type: 'rect';
47
+ rect: Rect;
48
+ } | {
49
+ type: 'focus';
50
+ };
51
+ export type FrameMessage = {
52
+ type: 'hello';
53
+ } | {
54
+ type: 'ready';
55
+ } | {
56
+ type: 'change';
57
+ value: unknown;
58
+ } | {
59
+ type: 'validity';
60
+ error: string | null;
61
+ } | {
62
+ type: 'resize';
63
+ height: number;
64
+ } | {
65
+ type: 'overlay';
66
+ on: boolean;
67
+ } | {
68
+ type: 'result';
69
+ call: number;
70
+ result?: unknown;
71
+ error?: string;
72
+ } | {
73
+ type: 'call';
74
+ call: number;
75
+ name: string;
76
+ data: unknown;
77
+ } | {
78
+ type: 'error';
79
+ message: string;
80
+ };
81
+ interface Envelope {
82
+ $swell: typeof PROTOCOL;
83
+ v: number;
84
+ channel: string;
85
+ }
86
+ export declare function wrap<T extends HostMessage | FrameMessage>(channel: string, message: T): T & Envelope;
87
+ /** The message when it belongs to this protocol version and channel, otherwise null. */
88
+ export declare function unwrap<T extends HostMessage | FrameMessage>(data: unknown, channel: string): T | null;
89
+ export {};
@@ -0,0 +1,20 @@
1
+ export const PROTOCOL = 'swell:component';
2
+ /**
3
+ * Protocol evolution: changes within version 1 are additive. Both sides ignore message types and
4
+ * fields they do not know, so new messages and fields need no version change. A breaking change
5
+ * (a removed or renamed message or field, or a changed meaning) needs a new version.
6
+ */
7
+ export const PROTOCOL_VERSION = 1;
8
+ export const TOKEN_HEADER = 'Swell-Component-Token';
9
+ export function wrap(channel, message) {
10
+ return { ...message, $swell: PROTOCOL, v: PROTOCOL_VERSION, channel };
11
+ }
12
+ /** The message when it belongs to this protocol version and channel, otherwise null. */
13
+ export function unwrap(data, channel) {
14
+ if (!data || typeof data !== 'object')
15
+ return null;
16
+ const envelope = data;
17
+ if (envelope.$swell !== PROTOCOL || envelope.v !== PROTOCOL_VERSION || envelope.channel !== channel || typeof envelope.type !== 'string')
18
+ return null;
19
+ return data;
20
+ }
@@ -0,0 +1,84 @@
1
+ /** Props every app component receives. Places differ only in what they put into them. */
2
+ export interface ComponentProps<TValue = unknown, TContext = Record<string, unknown>> {
3
+ /** Bound value, when the place provides one. */
4
+ readonly value: TValue;
5
+ setValue(value: TValue): void;
6
+ /** Data of the place, provided by the host. */
7
+ readonly context: TContext;
8
+ /** Configuration from the usage site. */
9
+ readonly params: Readonly<Record<string, unknown>>;
10
+ /** The app's public settings. */
11
+ readonly settings: Readonly<Record<string, unknown>>;
12
+ readonly locale: string;
13
+ readonly readonly: boolean;
14
+ setValidity(error: string | null): void;
15
+ /** fetch that adds the component token to requests to the frame's own origin. */
16
+ readonly fetch: typeof fetch;
17
+ /**
18
+ * Handles a host event. Only the first handler registered for an event runs, and its result
19
+ * (or thrown error) answers the host's `emit`; later handlers for the same event are not called.
20
+ */
21
+ on(event: string, handler: (data: unknown) => unknown): () => void;
22
+ /**
23
+ * Calls an action the host offers, such as `createIntent` for payment components, and resolves
24
+ * with its result. Rejects with the host's error, or with `Unknown host action "<name>"`.
25
+ */
26
+ call<T = unknown>(name: string, data?: unknown): Promise<T>;
27
+ }
28
+ /** Optional static metadata a component file exports as `config`. */
29
+ export interface ComponentConfig {
30
+ readonly description?: string;
31
+ /** Makes the component the UI of an extension of the app's swell.json. A string is the legacy swell.app contract. */
32
+ readonly extension?: {
33
+ readonly id: string;
34
+ };
35
+ /** Host places the component opts into. */
36
+ readonly targets?: readonly {
37
+ readonly id: ComponentTarget;
38
+ }[];
39
+ }
40
+ /** Module the CLI builds for each component. */
41
+ export interface ComponentModule {
42
+ /** The frame reports the component ready once a returned promise resolves. */
43
+ mount(root: HTMLElement, props: ComponentProps): void | Promise<void>;
44
+ update(root: HTMLElement, props: ComponentProps): void | Promise<void>;
45
+ unmount(root: HTMLElement): void;
46
+ }
47
+ /** Data a host passes to a component. Values must be structured-cloneable. */
48
+ export interface ComponentInput<TValue = unknown, TContext = Record<string, unknown>> {
49
+ value?: TValue;
50
+ context?: TContext;
51
+ params?: Record<string, unknown>;
52
+ readonly?: boolean;
53
+ locale?: string;
54
+ }
55
+ /** Short-lived platform token. `expires` is in epoch seconds. */
56
+ export interface ComponentToken {
57
+ readonly token: string;
58
+ readonly expires: number;
59
+ }
60
+ /** A host place id. The SDK knows no list: the platform defines places and validates ids on push. */
61
+ export type ComponentTarget = string;
62
+ export interface PaymentMethodInfo {
63
+ readonly id: string;
64
+ readonly name?: string;
65
+ readonly mode?: string;
66
+ }
67
+ export interface PaymentContext<TCart extends object = Record<string, unknown>> {
68
+ readonly cart: TCart & {
69
+ readonly account_id?: string;
70
+ readonly currency?: string;
71
+ readonly capture_total?: number;
72
+ };
73
+ readonly method?: PaymentMethodInfo;
74
+ }
75
+ export interface PaymentSubmitData {
76
+ readonly billing: Record<string, unknown>;
77
+ }
78
+ export interface PaymentRedirectData {
79
+ readonly params: Record<string, string>;
80
+ }
81
+ /** What a payment component's `submit` and `redirect` handlers return: merged into the cart's billing. */
82
+ export interface PaymentSubmitResult {
83
+ readonly billing: Record<string, unknown>;
84
+ }
@@ -0,0 +1,84 @@
1
+ /** Props every app component receives. Places differ only in what they put into them. */
2
+ export interface ComponentProps<TValue = unknown, TContext = Record<string, unknown>> {
3
+ /** Bound value, when the place provides one. */
4
+ readonly value: TValue;
5
+ setValue(value: TValue): void;
6
+ /** Data of the place, provided by the host. */
7
+ readonly context: TContext;
8
+ /** Configuration from the usage site. */
9
+ readonly params: Readonly<Record<string, unknown>>;
10
+ /** The app's public settings. */
11
+ readonly settings: Readonly<Record<string, unknown>>;
12
+ readonly locale: string;
13
+ readonly readonly: boolean;
14
+ setValidity(error: string | null): void;
15
+ /** fetch that adds the component token to requests to the frame's own origin. */
16
+ readonly fetch: typeof fetch;
17
+ /**
18
+ * Handles a host event. Only the first handler registered for an event runs, and its result
19
+ * (or thrown error) answers the host's `emit`; later handlers for the same event are not called.
20
+ */
21
+ on(event: string, handler: (data: unknown) => unknown): () => void;
22
+ /**
23
+ * Calls an action the host offers, such as `createIntent` for payment components, and resolves
24
+ * with its result. Rejects with the host's error, or with `Unknown host action "<name>"`.
25
+ */
26
+ call<T = unknown>(name: string, data?: unknown): Promise<T>;
27
+ }
28
+ /** Optional static metadata a component file exports as `config`. */
29
+ export interface ComponentConfig {
30
+ readonly description?: string;
31
+ /** Makes the component the UI of an extension of the app's swell.json. A string is the legacy swell.app contract. */
32
+ readonly extension?: {
33
+ readonly id: string;
34
+ };
35
+ /** Host places the component opts into. */
36
+ readonly targets?: readonly {
37
+ readonly id: ComponentTarget;
38
+ }[];
39
+ }
40
+ /** Module the CLI builds for each component. */
41
+ export interface ComponentModule {
42
+ /** The frame reports the component ready once a returned promise resolves. */
43
+ mount(root: HTMLElement, props: ComponentProps): void | Promise<void>;
44
+ update(root: HTMLElement, props: ComponentProps): void | Promise<void>;
45
+ unmount(root: HTMLElement): void;
46
+ }
47
+ /** Data a host passes to a component. Values must be structured-cloneable. */
48
+ export interface ComponentInput<TValue = unknown, TContext = Record<string, unknown>> {
49
+ value?: TValue;
50
+ context?: TContext;
51
+ params?: Record<string, unknown>;
52
+ readonly?: boolean;
53
+ locale?: string;
54
+ }
55
+ /** Short-lived platform token. `expires` is in epoch seconds. */
56
+ export interface ComponentToken {
57
+ readonly token: string;
58
+ readonly expires: number;
59
+ }
60
+ /** A host place id. The SDK knows no list: the platform defines places and validates ids on push. */
61
+ export type ComponentTarget = string;
62
+ export interface PaymentMethodInfo {
63
+ readonly id: string;
64
+ readonly name?: string;
65
+ readonly mode?: string;
66
+ }
67
+ export interface PaymentContext<TCart extends object = Record<string, unknown>> {
68
+ readonly cart: TCart & {
69
+ readonly account_id?: string;
70
+ readonly currency?: string;
71
+ readonly capture_total?: number;
72
+ };
73
+ readonly method?: PaymentMethodInfo;
74
+ }
75
+ export interface PaymentSubmitData {
76
+ readonly billing: Record<string, unknown>;
77
+ }
78
+ export interface PaymentRedirectData {
79
+ readonly params: Record<string, string>;
80
+ }
81
+ /** What a payment component's `submit` and `redirect` handlers return: merged into the cart's billing. */
82
+ export interface PaymentSubmitResult {
83
+ readonly billing: Record<string, unknown>;
84
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,6 @@
1
+ export type { ComponentConfig, ComponentInput, ComponentModule, ComponentProps, ComponentTarget, ComponentToken, PaymentContext, PaymentMethodInfo, PaymentRedirectData, PaymentSubmitData, PaymentSubmitResult } from './components-types.cjs';
2
+ export { createComponents } from './components-client.cjs';
3
+ export type { Components, ComponentsOptions, MountOptions, NamedMountOptions, PlaceComponent, TargetMountOptions, TargetHandle } from './components-client.cjs';
4
+ export type { ComponentHandle } from './components-host.cjs';
5
+ export { startComponentFrame } from './components-frame.cjs';
6
+ export type { FrameOptions } from './components-frame.cjs';
@@ -0,0 +1,6 @@
1
+ export type { ComponentConfig, ComponentInput, ComponentModule, ComponentProps, ComponentTarget, ComponentToken, PaymentContext, PaymentMethodInfo, PaymentRedirectData, PaymentSubmitData, PaymentSubmitResult } from './components-types.js';
2
+ export { createComponents } from './components-client.js';
3
+ export type { Components, ComponentsOptions, MountOptions, NamedMountOptions, PlaceComponent, TargetMountOptions, TargetHandle } from './components-client.js';
4
+ export type { ComponentHandle } from './components-host.js';
5
+ export { startComponentFrame } from './components-frame.js';
6
+ export type { FrameOptions } from './components-frame.js';
@@ -0,0 +1,2 @@
1
+ export { createComponents } from './components-client.js';
2
+ export { startComponentFrame } from './components-frame.js';
package/dist/index.d.cts CHANGED
@@ -2,7 +2,7 @@ import './guard.cjs';
2
2
  export { getStorefrontConfig } from './context.cjs';
3
3
  export type { HeaderReader } from './context.cjs';
4
4
  export { verifySwellContext } from './request-context.cjs';
5
- export type { SwellRequestContext, SwellHeadersEnv, VerifySwellContextOptions } from './request-context.cjs';
5
+ export type { SwellRequestContext, SwellHeadersEnv, SwellSurface, VerifySwellContextOptions } from './request-context.cjs';
6
6
  export { SwellBackendAPI } from './backend.cjs';
7
7
  export type { BackendOptions, SwellCollection, SwellData, TransactionOperation, TransactionOptions } from './backend.cjs';
8
8
  export { SwellError } from './error.cjs';
package/dist/index.d.ts CHANGED
@@ -2,7 +2,7 @@ import './guard.js';
2
2
  export { getStorefrontConfig } from './context.js';
3
3
  export type { HeaderReader } from './context.js';
4
4
  export { verifySwellContext } from './request-context.js';
5
- export type { SwellRequestContext, SwellHeadersEnv, VerifySwellContextOptions } from './request-context.js';
5
+ export type { SwellRequestContext, SwellHeadersEnv, SwellSurface, VerifySwellContextOptions } from './request-context.js';
6
6
  export { SwellBackendAPI } from './backend.js';
7
7
  export type { BackendOptions, SwellCollection, SwellData, TransactionOperation, TransactionOptions } from './backend.js';
8
8
  export { SwellError } from './error.js';