@swell/apps-sdk 2.0.0-alpha.1 → 2.0.0-alpha.2

package/README.md

@@ -2,7 +2,7 @@
 
 The Swell Apps SDK is a TypeScript library for building server-side Swell apps. It
 provides access to the Backend and Storefront APIs, along with helpers for app
-configuration, customer sessions and staff identity.
+configuration, customer sessions and store user identity.
 
 Use it in Swell-hosted apps, Cloudflare Workers or Node.js servers. For browser
 applications, use [`swell-js`](https://github.com/swellstores/swell-js).
@@ -23,9 +23,9 @@ Version 2 replaces the 1.x theme API. Existing theme applications should remain
 
 ### Request context
 
-Swell supplies the current store's configuration, credentials and staff identity with
-each request. Verify this context once, then reuse it to create clients and check staff
-access. Use the same pattern for Swell-hosted and self-hosted frontends.
+Swell supplies the current store's configuration, credentials and store user identity
+with each request. Verify this context once, then reuse it to create clients and check
+store user access. Use the same pattern for Swell-hosted and self-hosted frontends.
 
 ```ts
 import { verifySwellContext } from '@swell/apps-sdk';
@@ -96,16 +96,17 @@ swell.init(config.storeId, config.publicKey, config);
 
 Send only this public config to the browser; the request context contains server credentials.
 
-### Staff identity
+### Store users
 
-Use `requireStaff` to check that a request belongs to a staff member of the current
-store before applying your application's permission checks:
+A store user is someone signed in to the store's Swell dashboard. Use
+`requireStoreUser` to check that a request belongs to one before applying your
+application's permission checks:
 
 ```ts
-import { requireStaff } from '@swell/apps-sdk';
+import { requireStoreUser } from '@swell/apps-sdk';
 
-const staff = requireStaff(context); // { userId, storeId }, or a 401 SwellError.
-const optionalStaff = context.staff; // null for a visitor; no exception needed.
+const storeUser = requireStoreUser(context); // { userId, storeId }, or a 401 SwellError.
+const optional = context.storeUser; // null for a visitor; no exception needed.
 ```
 
 ## API reference
@@ -186,27 +187,28 @@ Node compatibility should pass their bindings as `env`.
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `SWELL_VERIFY_HEADERS` | enabled | Set exactly `"false"` to skip signature verification during local development. |
-| `SWELL_HEADERS_JWKS_URL` | `https://swell.store/.well-known/jwks.json` | Override the verification-key endpoint; its origin must match the token's issuer. |
+| `SWELL_HEADERS_JWKS_URL` | `https://swell.store/.well-known/jwks.json` | Override the verification-key endpoint. |
 
 For local development against a local Swell instance, put `SWELL_VERIFY_HEADERS=false`
 in `.dev.vars`. Remove it or set it to `"true"` to restore verification. Token structure
 and claim validation still apply, but the context is no longer authenticated: anyone
-who can reach the frontend directly can supply forged context, including staff identity.
+who can reach the frontend directly can supply forged context, including a store user.
 Use this bypass only for local development.
 
 For server integrations, construct `SwellBackendAPI` with explicit credentials and
 `createStorefrontClient` with explicit public configuration. These clients do not
-require an HTTP request or staff identity.
+require an HTTP request or a store user.
 
-### Staff identity
+### Store users
 
-`requireStaff(context)` returns `{ userId, storeId }` or throws `SwellError` with
-status 401 and code `staff_required`. For optional staff access, read `context.staff`,
-which is null for visitors.
+`requireStoreUser(context)` returns `{ userId, storeId }` or throws `SwellError` with
+status 401 and code `store_user_required`. For optional access, read
+`context.storeUser`, which is null for visitors.
 
-Staff includes any signed-in dashboard user of the store, including partners and Swell
-support. Swell's proxy handles staff authentication and write-origin checks; your
-application decides what each staff member may do.
+A store user is anyone signed in to the store's dashboard, including partners and Swell
+support, who may not appear in the store's own user list. Swell's proxy handles their
+authentication and write-origin checks; your application decides what each store user
+may do.
 
 ### Errors
 

package/dist/index.d.cts

@@ -7,5 +7,5 @@ export { SwellBackendAPI } from './backend.cjs';
 export type { BackendOptions, SwellCollection, SwellData, TransactionOperation, TransactionOptions } from './backend.cjs';
 export { SwellError } from './error.cjs';
 export type { SwellErrorOptions } from './error.cjs';
-export { requireStaff } from './staff.cjs';
-export type { StaffIdentity } from './staff.cjs';
+export { requireStoreUser } from './store-user.cjs';
+export type { StoreUser } from './store-user.cjs';

package/dist/index.d.ts

@@ -7,5 +7,5 @@ export { SwellBackendAPI } from './backend.js';
 export type { BackendOptions, SwellCollection, SwellData, TransactionOperation, TransactionOptions } from './backend.js';
 export { SwellError } from './error.js';
 export type { SwellErrorOptions } from './error.js';
-export { requireStaff } from './staff.js';
-export type { StaffIdentity } from './staff.js';
+export { requireStoreUser } from './store-user.js';
+export type { StoreUser } from './store-user.js';

package/dist/index.js

@@ -3,4 +3,4 @@ export { getStorefrontConfig } from './context.js';
 export { verifySwellContext } from './request-context.js';
 export { SwellBackendAPI } from './backend.js';
 export { SwellError } from './error.js';
-export { requireStaff } from './staff.js';
+export { requireStoreUser } from './store-user.js';

package/dist/request-context.d.cts

@@ -1,5 +1,5 @@
 import type { HeaderReader } from './context.cjs';
-import type { StaffIdentity } from './staff.cjs';
+import type { StoreUser } from './store-user.cjs';
 export interface SwellHeadersEnv {
     SWELL_VERIFY_HEADERS?: string;
     SWELL_HEADERS_JWKS_URL?: string;
@@ -26,12 +26,12 @@ export interface SwellRequestContext {
     readonly publicKey?: string;
     readonly requestId?: string;
     readonly vaultUrl?: string;
-    readonly staff: Readonly<StaffIdentity> | null;
+    readonly storeUser: Readonly<StoreUser> | null;
     /** False only when trusted runtime configuration explicitly disables verification. */
     readonly signatureVerified: boolean;
 }
 /**
  * Resolves Swell-Context once per request. Uses ES256 and a pinned JWKS endpoint;
- * never discovers keys from the request. No fallback to plain headers or staff cookies.
+ * never discovers keys from the request. No fallback to plain headers or dashboard cookies.
  */
 export declare function verifySwellContext(headers: HeaderReader, options?: VerifySwellContextOptions): Promise<SwellRequestContext>;

package/dist/request-context.d.ts

@@ -1,5 +1,5 @@
 import type { HeaderReader } from './context.js';
-import type { StaffIdentity } from './staff.js';
+import type { StoreUser } from './store-user.js';
 export interface SwellHeadersEnv {
     SWELL_VERIFY_HEADERS?: string;
     SWELL_HEADERS_JWKS_URL?: string;
@@ -26,12 +26,12 @@ export interface SwellRequestContext {
     readonly publicKey?: string;
     readonly requestId?: string;
     readonly vaultUrl?: string;
-    readonly staff: Readonly<StaffIdentity> | null;
+    readonly storeUser: Readonly<StoreUser> | null;
     /** False only when trusted runtime configuration explicitly disables verification. */
     readonly signatureVerified: boolean;
 }
 /**
  * Resolves Swell-Context once per request. Uses ES256 and a pinned JWKS endpoint;
- * never discovers keys from the request. No fallback to plain headers or staff cookies.
+ * never discovers keys from the request. No fallback to plain headers or dashboard cookies.
  */
 export declare function verifySwellContext(headers: HeaderReader, options?: VerifySwellContextOptions): Promise<SwellRequestContext>;

package/dist/request-context.js

@@ -15,14 +15,13 @@ function object(value) {
 }
 /**
  * Resolves Swell-Context once per request. Uses ES256 and a pinned JWKS endpoint;
- * never discovers keys from the request. No fallback to plain headers or staff cookies.
+ * never discovers keys from the request. No fallback to plain headers or dashboard cookies.
  */
 export async function verifySwellContext(headers, options = {}) {
     const runtime = globalThis;
     const env = options.env ?? runtime.process?.env ?? {};
     const verify = env.SWELL_VERIFY_HEADERS !== 'false';
     const jwksUrl = validateUrl(env.SWELL_HEADERS_JWKS_URL ?? 'https://swell.store/.well-known/jwks.json', 'SWELL_HEADERS_JWKS_URL');
-    const issuer = new URL(jwksUrl).origin;
     for (const field of ['appId', 'storeId']) {
         if (options[field] !== undefined)
             requireString(options[field], field);
@@ -63,9 +62,6 @@ export async function verifySwellContext(headers, options = {}) {
             throw invalidContext();
         if (payload.nbf !== undefined && (typeof payload.nbf !== 'number' || !Number.isFinite(payload.nbf) || payload.nbf > now + 5))
             throw invalidContext();
-        requireString(payload.iss, 'iss');
-        if (verify && payload.iss !== issuer)
-            throw invalidContext();
         for (const field of ['store_id', 'app_id', 'installation_id'])
             requireString(payload[field], field);
         if (payload.aud !== payload.app_id || (options.appId !== undefined && payload.aud !== options.appId) ||
@@ -75,11 +71,11 @@ export async function verifySwellContext(headers, options = {}) {
             if (payload[field] != null)
                 requireString(payload[field], field);
         }
-        let staff = null;
+        let storeUser = null;
         if (payload.admin !== null) {
             object(payload.admin);
             requireString(payload.admin.user_id, 'admin.user_id');
-            staff = Object.freeze({ userId: payload.admin.user_id, storeId: payload.store_id });
+            storeUser = Object.freeze({ userId: payload.admin.user_id, storeId: payload.store_id });
         }
         return Object.freeze({
             storeId: payload.store_id, appId: payload.app_id,
@@ -90,7 +86,7 @@ export async function verifySwellContext(headers, options = {}) {
             accessToken: headers.get('Swell-Access-Token') ?? undefined,
             publicKey: headers.get('Swell-Public-Key') ?? undefined,
             requestId: headers.get('Swell-Request-ID') ?? undefined,
-            vaultUrl, staff, signatureVerified: verify,
+            vaultUrl, storeUser, signatureVerified: verify,
         });
     }
     catch {

package/dist/{staff.d.cts → store-user.d.cts}

@@ -1,7 +1,7 @@
 import type { SwellRequestContext } from './request-context.cjs';
-export interface StaffIdentity {
+export interface StoreUser {
     readonly userId: string;
     readonly storeId: string;
 }
 /** Identity only; any dashboard role counts. The proxy owns write-origin checks; the app owns permissions. */
-export declare function requireStaff(context: SwellRequestContext): StaffIdentity;
+export declare function requireStoreUser(context: SwellRequestContext): StoreUser;

package/dist/{staff.d.ts → store-user.d.ts}

@@ -1,7 +1,7 @@
 import type { SwellRequestContext } from './request-context.js';
-export interface StaffIdentity {
+export interface StoreUser {
     readonly userId: string;
     readonly storeId: string;
 }
 /** Identity only; any dashboard role counts. The proxy owns write-origin checks; the app owns permissions. */
-export declare function requireStaff(context: SwellRequestContext): StaffIdentity;
+export declare function requireStoreUser(context: SwellRequestContext): StoreUser;

package/dist/store-user.js

@@ -0,0 +1,7 @@
+import { SwellError } from './error.js';
+/** Identity only; any dashboard role counts. The proxy owns write-origin checks; the app owns permissions. */
+export function requireStoreUser(context) {
+    if (!context.storeUser)
+        throw new SwellError('Store user required', { status: 401, code: 'store_user_required' });
+    return context.storeUser;
+}

package/dist/version.d.cts

@@ -1 +1 @@
-export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.1";
+export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.2";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.1";
+export declare const USER_AGENT = "swell-apps-sdk/2.0.0-alpha.2";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Replaced with the package version by the build.
-export const USER_AGENT = 'swell-apps-sdk/2.0.0-alpha.1';
+export const USER_AGENT = 'swell-apps-sdk/2.0.0-alpha.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swell/apps-sdk",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.2",
   "description": "Server SDK for Swell apps.",
   "type": "module",
   "license": "MIT",

package/dist/staff.js

@@ -1,7 +0,0 @@
-import { SwellError } from './error.js';
-/** Identity only; any dashboard role counts. The proxy owns write-origin checks; the app owns permissions. */
-export function requireStaff(context) {
-    if (!context.staff)
-        throw new SwellError('Staff identity required', { status: 401, code: 'staff_required' });
-    return context.staff;
-}