@swell/apps-sdk 2.1.0 → 2.1.1
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 +14 -0
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/request-context.d.cts +16 -1
- package/dist/request-context.d.ts +16 -1
- package/dist/request-context.js +21 -0
- package/dist/version.d.cts +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -37,6 +37,20 @@ const context = await verifySwellContext(request.headers, {
|
|
|
37
37
|
|
|
38
38
|
When an app component makes the request, `context.surface` says where it runs: `'admin'`, `'checkout'` or `'storefront'`. Treat `'storefront'` and `'checkout'` calls like public routes; check `context.surface === 'admin'` before doing anything that only a merchant may do.
|
|
39
39
|
|
|
40
|
+
### Storefront requests
|
|
41
|
+
|
|
42
|
+
A storefront app block calls its app through Swell: from the page through the storefront's app proxy (`/.swell/apps/<app_id>/<path>` on the storefront's own address, forwarded to your frontend's `/app-api/storefront/<path>`), or from a block component with `props.fetch`. Either way the context says which storefront it came from, so the app needs no list of allowed origins:
|
|
43
|
+
|
|
44
|
+
```ts
|
|
45
|
+
import { isStorefrontRequest, verifySwellContext } from '@swell/apps-sdk';
|
|
46
|
+
|
|
47
|
+
const context = await verifySwellContext(request.headers, { appId: 'my_app' });
|
|
48
|
+
if (!isStorefrontRequest(context)) return new Response(null, { status: 403 });
|
|
49
|
+
// context.storeId, context.storefrontId, context.storefrontHost, context.accountId, context.mode
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`isStorefrontRequest` is true when `surface` is `'storefront'` and the context names a storefront. It proves the request came through one of the store's storefronts, not who sent it: storefront pages are public, so rate-limit these routes, and check that `accountId` (the logged-in customer, `undefined` for a visitor) owns any private data you return. `storefrontHost` is the address the shopper used, custom domains included; `mode` is `'live'`, `'preview'` or `'editor'`.
|
|
53
|
+
|
|
40
54
|
In a server component, pass `await headers()`. Keep the context and clients on the
|
|
41
55
|
server, scoped to the incoming request.
|
|
42
56
|
|
package/dist/index.d.cts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import './guard.cjs';
|
|
2
2
|
export { getStorefrontConfig } from './context.cjs';
|
|
3
3
|
export type { HeaderReader } from './context.cjs';
|
|
4
|
-
export { verifySwellContext } from './request-context.cjs';
|
|
5
|
-
export type { SwellRequestContext, SwellHeadersEnv, SwellSurface, VerifySwellContextOptions } from './request-context.cjs';
|
|
4
|
+
export { isStorefrontRequest, verifySwellContext } from './request-context.cjs';
|
|
5
|
+
export type { SwellRequestContext, SwellHeadersEnv, SwellStorefrontMode, SwellSurface, VerifySwellContextOptions } from './request-context.cjs';
|
|
6
6
|
export { verifySwellWebhook } from './webhook.cjs';
|
|
7
7
|
export type { SwellWebhook, VerifySwellWebhookOptions } from './webhook.cjs';
|
|
8
8
|
export { SwellBackendAPI } from './backend.cjs';
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import './guard.js';
|
|
2
2
|
export { getStorefrontConfig } from './context.js';
|
|
3
3
|
export type { HeaderReader } from './context.js';
|
|
4
|
-
export { verifySwellContext } from './request-context.js';
|
|
5
|
-
export type { SwellRequestContext, SwellHeadersEnv, SwellSurface, VerifySwellContextOptions } from './request-context.js';
|
|
4
|
+
export { isStorefrontRequest, verifySwellContext } from './request-context.js';
|
|
5
|
+
export type { SwellRequestContext, SwellHeadersEnv, SwellStorefrontMode, SwellSurface, VerifySwellContextOptions } from './request-context.js';
|
|
6
6
|
export { verifySwellWebhook } from './webhook.js';
|
|
7
7
|
export type { SwellWebhook, VerifySwellWebhookOptions } from './webhook.js';
|
|
8
8
|
export { SwellBackendAPI } from './backend.js';
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import './guard.js';
|
|
2
2
|
export { getStorefrontConfig } from './context.js';
|
|
3
|
-
export { verifySwellContext } from './request-context.js';
|
|
3
|
+
export { isStorefrontRequest, verifySwellContext } from './request-context.js';
|
|
4
4
|
export { verifySwellWebhook } from './webhook.js';
|
|
5
5
|
export { SwellBackendAPI } from './backend.js';
|
|
6
6
|
export { SwellError } from './error.js';
|
|
@@ -2,6 +2,8 @@ import type { HeaderReader } from './context.cjs';
|
|
|
2
2
|
import type { StoreUser } from './store-user.cjs';
|
|
3
3
|
/** Where an app component made the request from. */
|
|
4
4
|
export type SwellSurface = 'admin' | 'checkout' | 'storefront';
|
|
5
|
+
/** A storefront request's deployment mode. */
|
|
6
|
+
export type SwellStorefrontMode = 'live' | 'preview' | 'editor';
|
|
5
7
|
export interface SwellHeadersEnv {
|
|
6
8
|
SWELL_VERIFY_HEADERS?: string;
|
|
7
9
|
SWELL_HEADERS_JWKS_URL?: string;
|
|
@@ -22,8 +24,14 @@ export interface SwellRequestContext {
|
|
|
22
24
|
readonly installationId: string;
|
|
23
25
|
readonly environmentId?: string;
|
|
24
26
|
readonly storefrontId?: string;
|
|
25
|
-
/** Set when an app component made the request. */
|
|
27
|
+
/** Set when an app component made the request, or the storefront app proxy forwarded it ('storefront'). */
|
|
26
28
|
readonly surface?: SwellSurface;
|
|
29
|
+
/** The storefront host the shopper used (custom domains included), on storefront requests. */
|
|
30
|
+
readonly storefrontHost?: string;
|
|
31
|
+
/** The logged-in customer on a storefront request. Says who is logged in, not what they may see. */
|
|
32
|
+
readonly accountId?: string;
|
|
33
|
+
/** The storefront's deployment mode on a storefront request. */
|
|
34
|
+
readonly mode?: SwellStorefrontMode;
|
|
27
35
|
readonly apiHost: string;
|
|
28
36
|
readonly adminUrl: string;
|
|
29
37
|
readonly accessToken?: string;
|
|
@@ -39,3 +47,10 @@ export interface SwellRequestContext {
|
|
|
39
47
|
* never discovers keys from the request. No fallback to plain headers or dashboard cookies.
|
|
40
48
|
*/
|
|
41
49
|
export declare function verifySwellContext(headers: HeaderReader, options?: VerifySwellContextOptions): Promise<SwellRequestContext>;
|
|
50
|
+
/**
|
|
51
|
+
* True for a request a shopper's storefront page made through Swell: the storefront app proxy, or a storefront app
|
|
52
|
+
* block's component. It says which store and storefront the request came from (`storeId`, `storefrontId`,
|
|
53
|
+
* `storefrontHost`), so an app needs no list of allowed origins. It does not identify a person: treat the request as
|
|
54
|
+
* public, and check `accountId` before returning a customer's data.
|
|
55
|
+
*/
|
|
56
|
+
export declare function isStorefrontRequest(context: SwellRequestContext): boolean;
|
|
@@ -2,6 +2,8 @@ import type { HeaderReader } from './context.js';
|
|
|
2
2
|
import type { StoreUser } from './store-user.js';
|
|
3
3
|
/** Where an app component made the request from. */
|
|
4
4
|
export type SwellSurface = 'admin' | 'checkout' | 'storefront';
|
|
5
|
+
/** A storefront request's deployment mode. */
|
|
6
|
+
export type SwellStorefrontMode = 'live' | 'preview' | 'editor';
|
|
5
7
|
export interface SwellHeadersEnv {
|
|
6
8
|
SWELL_VERIFY_HEADERS?: string;
|
|
7
9
|
SWELL_HEADERS_JWKS_URL?: string;
|
|
@@ -22,8 +24,14 @@ export interface SwellRequestContext {
|
|
|
22
24
|
readonly installationId: string;
|
|
23
25
|
readonly environmentId?: string;
|
|
24
26
|
readonly storefrontId?: string;
|
|
25
|
-
/** Set when an app component made the request. */
|
|
27
|
+
/** Set when an app component made the request, or the storefront app proxy forwarded it ('storefront'). */
|
|
26
28
|
readonly surface?: SwellSurface;
|
|
29
|
+
/** The storefront host the shopper used (custom domains included), on storefront requests. */
|
|
30
|
+
readonly storefrontHost?: string;
|
|
31
|
+
/** The logged-in customer on a storefront request. Says who is logged in, not what they may see. */
|
|
32
|
+
readonly accountId?: string;
|
|
33
|
+
/** The storefront's deployment mode on a storefront request. */
|
|
34
|
+
readonly mode?: SwellStorefrontMode;
|
|
27
35
|
readonly apiHost: string;
|
|
28
36
|
readonly adminUrl: string;
|
|
29
37
|
readonly accessToken?: string;
|
|
@@ -39,3 +47,10 @@ export interface SwellRequestContext {
|
|
|
39
47
|
* never discovers keys from the request. No fallback to plain headers or dashboard cookies.
|
|
40
48
|
*/
|
|
41
49
|
export declare function verifySwellContext(headers: HeaderReader, options?: VerifySwellContextOptions): Promise<SwellRequestContext>;
|
|
50
|
+
/**
|
|
51
|
+
* True for a request a shopper's storefront page made through Swell: the storefront app proxy, or a storefront app
|
|
52
|
+
* block's component. It says which store and storefront the request came from (`storeId`, `storefrontId`,
|
|
53
|
+
* `storefrontHost`), so an app needs no list of allowed origins. It does not identify a person: treat the request as
|
|
54
|
+
* public, and check `accountId` before returning a customer's data.
|
|
55
|
+
*/
|
|
56
|
+
export declare function isStorefrontRequest(context: SwellRequestContext): boolean;
|
package/dist/request-context.js
CHANGED
|
@@ -2,6 +2,9 @@ import { requireString, validateUrl } from './context.js';
|
|
|
2
2
|
import { SwellError } from './error.js';
|
|
3
3
|
import { getVerificationKey } from './jwks.js';
|
|
4
4
|
const SURFACES = ['admin', 'checkout', 'storefront'];
|
|
5
|
+
const MODES = ['live', 'preview', 'editor'];
|
|
6
|
+
// host[:port], lowercase: what Swell puts in storefront_host
|
|
7
|
+
const HOST_RE = /^[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?(?::\d{1,5})?$/;
|
|
5
8
|
function invalidContext() {
|
|
6
9
|
return new SwellError('Missing or invalid Swell context', { status: 401, code: 'invalid_swell_context' });
|
|
7
10
|
}
|
|
@@ -74,6 +77,12 @@ export async function verifySwellContext(headers, options = {}) {
|
|
|
74
77
|
}
|
|
75
78
|
if (payload.surface != null && !SURFACES.includes(payload.surface))
|
|
76
79
|
throw invalidContext();
|
|
80
|
+
if (payload.storefront_host != null && (typeof payload.storefront_host !== 'string' || !HOST_RE.test(payload.storefront_host)))
|
|
81
|
+
throw invalidContext();
|
|
82
|
+
if (payload.account_id != null)
|
|
83
|
+
requireString(payload.account_id, 'account_id');
|
|
84
|
+
if (payload.mode != null && !MODES.includes(payload.mode))
|
|
85
|
+
throw invalidContext();
|
|
77
86
|
let storeUser = null;
|
|
78
87
|
if (payload.admin !== null) {
|
|
79
88
|
object(payload.admin);
|
|
@@ -86,6 +95,9 @@ export async function verifySwellContext(headers, options = {}) {
|
|
|
86
95
|
environmentId: payload.environment_id ?? undefined,
|
|
87
96
|
storefrontId: payload.storefront_id ?? undefined,
|
|
88
97
|
surface: payload.surface ?? undefined,
|
|
98
|
+
storefrontHost: payload.storefront_host ?? undefined,
|
|
99
|
+
accountId: payload.account_id ?? undefined,
|
|
100
|
+
mode: payload.mode ?? undefined,
|
|
89
101
|
apiHost: validateUrl(payload.api_host, 'api_host'), adminUrl: validateUrl(payload.admin_url, 'admin_url'),
|
|
90
102
|
accessToken: headers.get('Swell-Access-Token') ?? undefined,
|
|
91
103
|
publicKey: headers.get('Swell-Public-Key') ?? undefined,
|
|
@@ -97,3 +109,12 @@ export async function verifySwellContext(headers, options = {}) {
|
|
|
97
109
|
throw invalidContext();
|
|
98
110
|
}
|
|
99
111
|
}
|
|
112
|
+
/**
|
|
113
|
+
* True for a request a shopper's storefront page made through Swell: the storefront app proxy, or a storefront app
|
|
114
|
+
* block's component. It says which store and storefront the request came from (`storeId`, `storefrontId`,
|
|
115
|
+
* `storefrontHost`), so an app needs no list of allowed origins. It does not identify a person: treat the request as
|
|
116
|
+
* public, and check `accountId` before returning a customer's data.
|
|
117
|
+
*/
|
|
118
|
+
export function isStorefrontRequest(context) {
|
|
119
|
+
return context.surface === 'storefront' && typeof context.storefrontId === 'string' && context.storefrontId.length > 0;
|
|
120
|
+
}
|
package/dist/version.d.cts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const USER_AGENT = "swell-apps-sdk/2.1.
|
|
1
|
+
export declare const USER_AGENT = "swell-apps-sdk/2.1.1";
|
package/dist/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const USER_AGENT = "swell-apps-sdk/2.1.
|
|
1
|
+
export declare const USER_AGENT = "swell-apps-sdk/2.1.1";
|
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.1.
|
|
2
|
+
export const USER_AGENT = 'swell-apps-sdk/2.1.1';
|