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

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.
@@ -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,46 @@
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
+ /** Optional static metadata a component file exports as `config`. */
24
+ export interface ComponentConfig {
25
+ readonly description?: string;
26
+ }
27
+ /** Module the CLI builds for each component. */
28
+ export interface ComponentModule {
29
+ /** The frame reports the component ready once a returned promise resolves. */
30
+ mount(root: HTMLElement, props: ComponentProps): void | Promise<void>;
31
+ update(root: HTMLElement, props: ComponentProps): void | Promise<void>;
32
+ unmount(root: HTMLElement): void;
33
+ }
34
+ /** Data a host passes to a component. Values must be structured-cloneable. */
35
+ export interface ComponentInput<TValue = unknown, TContext = Record<string, unknown>> {
36
+ value?: TValue;
37
+ context?: TContext;
38
+ params?: Record<string, unknown>;
39
+ readonly?: boolean;
40
+ locale?: string;
41
+ }
42
+ /** Short-lived platform token. `expires` is in epoch seconds. */
43
+ export interface ComponentToken {
44
+ readonly token: string;
45
+ readonly expires: number;
46
+ }
@@ -0,0 +1,46 @@
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
+ /** Optional static metadata a component file exports as `config`. */
24
+ export interface ComponentConfig {
25
+ readonly description?: string;
26
+ }
27
+ /** Module the CLI builds for each component. */
28
+ export interface ComponentModule {
29
+ /** The frame reports the component ready once a returned promise resolves. */
30
+ mount(root: HTMLElement, props: ComponentProps): void | Promise<void>;
31
+ update(root: HTMLElement, props: ComponentProps): void | Promise<void>;
32
+ unmount(root: HTMLElement): void;
33
+ }
34
+ /** Data a host passes to a component. Values must be structured-cloneable. */
35
+ export interface ComponentInput<TValue = unknown, TContext = Record<string, unknown>> {
36
+ value?: TValue;
37
+ context?: TContext;
38
+ params?: Record<string, unknown>;
39
+ readonly?: boolean;
40
+ locale?: string;
41
+ }
42
+ /** Short-lived platform token. `expires` is in epoch seconds. */
43
+ export interface ComponentToken {
44
+ readonly token: string;
45
+ readonly expires: number;
46
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,6 @@
1
+ export type { ComponentConfig, ComponentInput, ComponentModule, ComponentProps, ComponentToken } from './components-types.cjs';
2
+ export { createComponents } from './components-client.cjs';
3
+ export type { Components, ComponentsOptions, MountOptions } 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, ComponentToken } from './components-types.js';
2
+ export { createComponents } from './components-client.js';
3
+ export type { Components, ComponentsOptions, MountOptions } 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';
@@ -1,5 +1,7 @@
1
1
  import type { HeaderReader } from './context.cjs';
2
2
  import type { StoreUser } from './store-user.cjs';
3
+ /** Where an app component made the request from. */
4
+ export type SwellSurface = 'admin' | 'checkout' | 'storefront';
3
5
  export interface SwellHeadersEnv {
4
6
  SWELL_VERIFY_HEADERS?: string;
5
7
  SWELL_HEADERS_JWKS_URL?: string;
@@ -20,6 +22,8 @@ export interface SwellRequestContext {
20
22
  readonly installationId: string;
21
23
  readonly environmentId?: string;
22
24
  readonly storefrontId?: string;
25
+ /** Set when an app component made the request. */
26
+ readonly surface?: SwellSurface;
23
27
  readonly apiHost: string;
24
28
  readonly adminUrl: string;
25
29
  readonly accessToken?: string;
@@ -1,5 +1,7 @@
1
1
  import type { HeaderReader } from './context.js';
2
2
  import type { StoreUser } from './store-user.js';
3
+ /** Where an app component made the request from. */
4
+ export type SwellSurface = 'admin' | 'checkout' | 'storefront';
3
5
  export interface SwellHeadersEnv {
4
6
  SWELL_VERIFY_HEADERS?: string;
5
7
  SWELL_HEADERS_JWKS_URL?: string;
@@ -20,6 +22,8 @@ export interface SwellRequestContext {
20
22
  readonly installationId: string;
21
23
  readonly environmentId?: string;
22
24
  readonly storefrontId?: string;
25
+ /** Set when an app component made the request. */
26
+ readonly surface?: SwellSurface;
23
27
  readonly apiHost: string;
24
28
  readonly adminUrl: string;
25
29
  readonly accessToken?: string;
@@ -1,6 +1,7 @@
1
1
  import { requireString, validateUrl } from './context.js';
2
2
  import { SwellError } from './error.js';
3
3
  import { getVerificationKey } from './jwks.js';
4
+ const SURFACES = ['admin', 'checkout', 'storefront'];
4
5
  function invalidContext() {
5
6
  return new SwellError('Missing or invalid Swell context', { status: 401, code: 'invalid_swell_context' });
6
7
  }
@@ -71,6 +72,8 @@ export async function verifySwellContext(headers, options = {}) {
71
72
  if (payload[field] != null)
72
73
  requireString(payload[field], field);
73
74
  }
75
+ if (payload.surface != null && !SURFACES.includes(payload.surface))
76
+ throw invalidContext();
74
77
  let storeUser = null;
75
78
  if (payload.admin !== null) {
76
79
  object(payload.admin);
@@ -82,6 +85,7 @@ export async function verifySwellContext(headers, options = {}) {
82
85
  installationId: payload.installation_id,
83
86
  environmentId: payload.environment_id ?? undefined,
84
87
  storefrontId: payload.storefront_id ?? undefined,
88
+ surface: payload.surface ?? undefined,
85
89
  apiHost: validateUrl(payload.api_host, 'api_host'), adminUrl: validateUrl(payload.admin_url, 'admin_url'),
86
90
  accessToken: headers.get('Swell-Access-Token') ?? undefined,
87
91
  publicKey: headers.get('Swell-Public-Key') ?? undefined,
@@ -1 +1 @@
1
- export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.5";
1
+ export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.6";
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.5";
1
+ export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.6";
package/dist/version.js CHANGED
@@ -1,2 +1,2 @@
1
1
  // Replaced with the package version by the build.
2
- export const USER_AGENT = 'swell-apps-sdk/2.0.0-alpha.5';
2
+ export const USER_AGENT = 'swell-apps-sdk/2.0.0-alpha.6';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@swell/apps-sdk",
3
- "version": "2.0.0-alpha.5",
3
+ "version": "2.0.0-alpha.6",
4
4
  "description": "Server SDK for Swell apps.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -18,6 +18,7 @@
18
18
  "test:package": "node scripts/verify-package.mjs",
19
19
  "test:boundaries": "node scripts/verify-boundaries.mjs",
20
20
  "test:worker": "node scripts/verify-worker.mjs",
21
+ "test:browser": "npm run build && node scripts/verify-components-browser.mjs",
21
22
  "verify": "npm test && npm run typecheck && npm run test:package && npm run test:boundaries && npm run test:worker"
22
23
  },
23
24
  "peerDependencies": {
@@ -25,7 +26,9 @@
25
26
  },
26
27
  "devDependencies": {
27
28
  "esbuild": "0.24.2",
29
+ "happy-dom": "20.14.5",
28
30
  "miniflare": "5.20260911.1-alpha",
31
+ "playwright": "1.63.0",
29
32
  "swell-js": "5.9.2",
30
33
  "typescript": "5.7.3"
31
34
  },
@@ -51,6 +54,13 @@
51
54
  "node": "./dist/storefront.js",
52
55
  "browser": "./dist/browser-refusal.js",
53
56
  "default": "./dist/storefront.js"
57
+ },
58
+ "./components": {
59
+ "types": {
60
+ "import": "./dist/components.d.ts",
61
+ "require": "./dist/components.d.cts"
62
+ },
63
+ "default": "./dist/components.js"
54
64
  }
55
65
  },
56
66
  "sideEffects": [