react-shopwave-connect 0.1.1 → 0.2.0

package/dist/server/index.cjs

@@ -0,0 +1,260 @@
+
+//#region src/server/errors.ts
+var ShopwaveAuthError = class extends Error {
+	code;
+	status;
+	/** Raw response body from the auth server, if any. Never contains our secret. */
+	body;
+	constructor(code, message, details = {}) {
+		super(message, details.cause !== void 0 ? { cause: details.cause } : void 0);
+		this.name = "ShopwaveAuthError";
+		this.code = code;
+		this.status = details.status;
+		this.body = details.body;
+	}
+	/**
+	* True when the auth server rejected the grant itself (bad/expired code or
+	* refresh token) rather than failing for a transient reason. Callers should
+	* treat the user as logged out.
+	*/
+	get isInvalidGrant() {
+		return (this.code === "token_exchange_failed" || this.code === "token_refresh_failed") && this.status !== void 0 && this.status >= 400 && this.status < 500;
+	}
+};
+
+//#endregion
+//#region src/server/token.ts
+/** Shopwave API error id meaning "access token expired / invalid". */
+const SHOPWAVE_TOKEN_EXPIRED_ERROR_ID = 908;
+/**
+* Converts a token-endpoint response into a {@link ShopwaveToken}.
+* Returns `null` when the response has no access token.
+*
+* @param previous  the token being refreshed; its refresh token is kept when
+*                  the server doesn't send a new one.
+*/
+function tokenFromResponse(response, previous, now = Date.now()) {
+	if (!response || typeof response.access_token !== "string" || !response.access_token) return null;
+	const expiresIn = Number(response.expires_in);
+	return {
+		accessToken: response.access_token,
+		refreshToken: typeof response.refresh_token === "string" && response.refresh_token || previous?.refreshToken,
+		tokenType: typeof response.token_type === "string" && response.token_type || "OAuth",
+		expiresAt: Number.isFinite(expiresIn) && expiresIn > 0 ? now + expiresIn * 1e3 : void 0
+	};
+}
+/**
+* Reads a token from session storage. Accepts both the current shape and the
+* legacy raw response that older apps (e.g. AdminUI ≤ 0.1) stored directly in
+* the session, so existing sessions survive an upgrade.
+*/
+function normalizeStoredToken(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const t = raw;
+	if (typeof t.accessToken === "string" && t.accessToken) return {
+		accessToken: t.accessToken,
+		refreshToken: typeof t.refreshToken === "string" ? t.refreshToken : void 0,
+		tokenType: typeof t.tokenType === "string" && t.tokenType ? t.tokenType : "OAuth",
+		expiresAt: typeof t.expiresAt === "number" ? t.expiresAt : void 0
+	};
+	if (typeof t.access_token === "string" && t.access_token) return {
+		accessToken: t.access_token,
+		refreshToken: typeof t.refresh_token === "string" ? t.refresh_token : void 0,
+		tokenType: typeof t.token_type === "string" && t.token_type ? t.token_type : "OAuth"
+	};
+	return null;
+}
+/**
+* True when the token has passed its expiry (minus `skewSeconds`).
+* Tokens without a known expiry are treated as valid.
+*
+* Shopwave only issues a new access token once the old one has actually
+* expired, so the default skew is 0 — refreshing early just returns the same
+* token.
+*/
+function isTokenExpired(token, { skewSeconds = 0, now = Date.now() } = {}) {
+	if (token.expiresAt === void 0) return false;
+	return now >= token.expiresAt - skewSeconds * 1e3;
+}
+/** `Authorization` header value, e.g. `OAuth 111ad…`. */
+function authorizationHeader(token) {
+	return `${token.tokenType || "OAuth"} ${token.accessToken}`;
+}
+/**
+* True when a Shopwave API response means "your access token is no longer
+* valid": HTTP 401, or the API error 908 in the response envelope.
+* Use it to trigger a forced refresh + a single retry.
+*/
+function isExpiredTokenResponse(status, body) {
+	if (status === 401) return true;
+	const errors = body?.api?.message?.errors;
+	if (!errors || typeof errors !== "object") return false;
+	return Object.entries(errors).some(([key, value]) => key === String(SHOPWAVE_TOKEN_EXPIRED_ERROR_ID) || Number(value?.id) === SHOPWAVE_TOKEN_EXPIRED_ERROR_ID);
+}
+
+//#endregion
+//#region src/server/oauth.ts
+const REQUIRED_KEYS = [
+	"authServerUrl",
+	"clientId",
+	"clientSecret",
+	"redirectUri"
+];
+/** Throws a readable error when required settings are missing. */
+function assertOAuthConfig(config) {
+	const missing = REQUIRED_KEYS.filter((k) => !config?.[k]);
+	if (missing.length > 0) throw new ShopwaveAuthError("config_invalid", `Shopwave auth is missing required settings: ${missing.join(", ")}`);
+}
+function trimSlash(url) {
+	return url.replace(/\/+$/, "");
+}
+/**
+* Creates a framework-agnostic Shopwave OAuth client (authorization-code flow
+* with a client secret — the Shopwave auth server does not support PKCE, so
+* this must run on a server).
+*
+* Config is validated lazily on first use, so creating the client at module
+* scope doesn't break builds where env vars aren't present.
+*/
+function createShopwaveOAuth(config) {
+	const endpoints = {
+		login: config.endpoints?.login ?? "/login",
+		token: config.endpoints?.token ?? "/oauth/token",
+		logout: config.endpoints?.logout ?? "/logout"
+	};
+	const base = () => {
+		assertOAuthConfig(config);
+		return trimSlash(config.authServerUrl);
+	};
+	const commonParams = (redirectUri) => new URLSearchParams({
+		access_type: config.accessType ?? "online",
+		redirect_uri: redirectUri,
+		response_type: "code",
+		client_id: config.clientId,
+		scope: config.scope ?? "application"
+	});
+	async function postToken(fields, errorCode) {
+		const url = `${base()}${endpoints.token}`;
+		const doFetch = config.fetch ?? globalThis.fetch;
+		let body;
+		if (config.tokenRequestFormat === "multipart") {
+			const fd = new FormData();
+			for (const [k, v] of Object.entries(fields)) fd.append(k, v);
+			body = fd;
+		} else body = new URLSearchParams(fields);
+		let response;
+		try {
+			response = await doFetch(url, {
+				method: "POST",
+				body,
+				headers: { Accept: "application/json" },
+				cache: "no-store"
+			});
+		} catch (cause) {
+			throw new ShopwaveAuthError("network_error", `Could not reach the Shopwave auth server`, { cause });
+		}
+		const text = await response.text();
+		if (!response.ok) throw new ShopwaveAuthError(errorCode, `Shopwave auth server returned ${response.status} for ${fields.grant_type}`, {
+			status: response.status,
+			body: text.slice(0, 2e3)
+		});
+		try {
+			return JSON.parse(text);
+		} catch (cause) {
+			throw new ShopwaveAuthError("token_response_invalid", "Token response was not JSON", {
+				status: response.status,
+				body: text.slice(0, 2e3),
+				cause
+			});
+		}
+	}
+	return {
+		config,
+		buildLoginUrl({ state } = {}) {
+			const params = commonParams(config.redirectUri);
+			if (state) params.set("state", state);
+			return `${base()}${endpoints.login}?${params.toString()}`;
+		},
+		buildLogoutUrl({ redirectUri } = {}) {
+			const params = commonParams(redirectUri ?? config.postLogoutRedirectUri ?? config.redirectUri);
+			return `${base()}${endpoints.logout}?${params.toString()}`;
+		},
+		async exchangeCode(code) {
+			if (!code) throw new ShopwaveAuthError("token_exchange_failed", "Missing authorization code");
+			const token = tokenFromResponse(await postToken({
+				code,
+				redirect_uri: config.redirectUri,
+				client_id: config.clientId,
+				client_secret: config.clientSecret,
+				scope: config.scope ?? "application",
+				grant_type: "authorization_code"
+			}, "token_exchange_failed"));
+			if (!token) throw new ShopwaveAuthError("token_response_invalid", "Token response had no access_token");
+			return token;
+		},
+		async refreshToken(tokenOrRefreshToken) {
+			const previous = typeof tokenOrRefreshToken === "string" ? {
+				accessToken: "",
+				refreshToken: tokenOrRefreshToken,
+				tokenType: "OAuth"
+			} : tokenOrRefreshToken;
+			if (!previous.refreshToken) throw new ShopwaveAuthError("token_refresh_failed", "No refresh token available", { status: 400 });
+			const token = tokenFromResponse(await postToken({
+				refresh_token: previous.refreshToken,
+				redirect_uri: config.redirectUri,
+				client_id: config.clientId,
+				client_secret: config.clientSecret,
+				grant_type: "refresh_token"
+			}, "token_refresh_failed"), previous);
+			if (!token) throw new ShopwaveAuthError("token_response_invalid", "Refresh response had no access_token");
+			return token;
+		}
+	};
+}
+
+//#endregion
+//#region src/server/returnTo.ts
+/**
+* Helpers for the round trip through the auth server.
+*/
+/**
+* Only allows same-origin relative paths ("/products?tab=1"). Anything that
+* could send the user to another site after login — absolute URLs,
+* protocol-relative "//evil.com", backslash tricks, control characters —
+* falls back to `fallback`.
+*/
+function sanitizeReturnTo(value, fallback = "/") {
+	if (typeof value !== "string" || value.length === 0 || value.length > 2048) return fallback;
+	if (!/^\/(?![/\\])/.test(value)) return fallback;
+	if (/[\u0000-\u001f\u007f]/.test(value)) return fallback;
+	if (value.includes("\\")) return fallback;
+	return value;
+}
+/** Random, URL-safe value for the OAuth `state` parameter (128 bits, hex). */
+function createState() {
+	const bytes = new Uint8Array(16);
+	globalThis.crypto.getRandomValues(bytes);
+	return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Constant-time string comparison for state values. */
+function safeEqual(a, b) {
+	if (typeof a !== "string" || typeof b !== "string" || a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}
+
+//#endregion
+exports.SHOPWAVE_TOKEN_EXPIRED_ERROR_ID = SHOPWAVE_TOKEN_EXPIRED_ERROR_ID;
+exports.ShopwaveAuthError = ShopwaveAuthError;
+exports.assertOAuthConfig = assertOAuthConfig;
+exports.authorizationHeader = authorizationHeader;
+exports.createShopwaveOAuth = createShopwaveOAuth;
+exports.createState = createState;
+exports.isExpiredTokenResponse = isExpiredTokenResponse;
+exports.isTokenExpired = isTokenExpired;
+exports.normalizeStoredToken = normalizeStoredToken;
+exports.safeEqual = safeEqual;
+exports.sanitizeReturnTo = sanitizeReturnTo;
+exports.tokenFromResponse = tokenFromResponse;
+//# sourceMappingURL=index.cjs.map

package/dist/server/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["body: URLSearchParams | FormData","response: Response"],"sources":["../../src/server/errors.ts","../../src/server/token.ts","../../src/server/oauth.ts","../../src/server/returnTo.ts"],"sourcesContent":["/**\n * Error thrown by the server-side auth helpers.\n *\n * `code` is stable and safe to branch on; `status` is the HTTP status returned\n * by the Shopwave auth server when there was one.\n */\nexport type ShopwaveAuthErrorCode =\n  | \"config_invalid\"\n  | \"token_exchange_failed\"\n  | \"token_refresh_failed\"\n  | \"token_response_invalid\"\n  | \"network_error\";\n\nexport class ShopwaveAuthError extends Error {\n  readonly code: ShopwaveAuthErrorCode;\n  readonly status?: number;\n  /** Raw response body from the auth server, if any. Never contains our secret. */\n  readonly body?: string;\n\n  constructor(\n    code: ShopwaveAuthErrorCode,\n    message: string,\n    details: { status?: number; body?: string; cause?: unknown } = {}\n  ) {\n    super(message, details.cause !== undefined ? { cause: details.cause } : undefined);\n    this.name = \"ShopwaveAuthError\";\n    this.code = code;\n    this.status = details.status;\n    this.body = details.body;\n  }\n\n  /**\n   * True when the auth server rejected the grant itself (bad/expired code or\n   * refresh token) rather than failing for a transient reason. Callers should\n   * treat the user as logged out.\n   */\n  get isInvalidGrant(): boolean {\n    return (\n      (this.code === \"token_exchange_failed\" || this.code === \"token_refresh_failed\") &&\n      this.status !== undefined &&\n      this.status >= 400 &&\n      this.status < 500\n    );\n  }\n}\n","/**\n * Token model + helpers shared by every server-side integration.\n *\n * The Shopwave auth server returns (snake_case):\n *   { access_token, refresh_token, token_type: \"OAuth\", expires_in: 43200 }\n *\n * We store a normalised, camelCase shape with an absolute expiry so any\n * request can decide whether the token is still usable without extra state.\n */\n\nexport interface ShopwaveToken {\n  accessToken: string;\n  /** Long-lived; the Shopwave server does not rotate it on refresh. */\n  refreshToken?: string;\n  /** Scheme used in the Authorization header. Shopwave uses \"OAuth\". */\n  tokenType: string;\n  /** Absolute expiry, epoch milliseconds. Undefined if the server didn't say. */\n  expiresAt?: number;\n}\n\n/** Raw token response from `POST {authServer}/oauth/token`. */\nexport interface ShopwaveTokenResponse {\n  access_token?: string;\n  refresh_token?: string;\n  token_type?: string;\n  expires_in?: number | string;\n  [key: string]: unknown;\n}\n\n/** Shopwave API error id meaning \"access token expired / invalid\". */\nexport const SHOPWAVE_TOKEN_EXPIRED_ERROR_ID = 908;\n\n/**\n * Converts a token-endpoint response into a {@link ShopwaveToken}.\n * Returns `null` when the response has no access token.\n *\n * @param previous  the token being refreshed; its refresh token is kept when\n *                  the server doesn't send a new one.\n */\nexport function tokenFromResponse(\n  response: ShopwaveTokenResponse,\n  previous?: ShopwaveToken,\n  now: number = Date.now()\n): ShopwaveToken | null {\n  if (!response || typeof response.access_token !== \"string\" || !response.access_token) {\n    return null;\n  }\n\n  const expiresIn = Number(response.expires_in);\n\n  return {\n    accessToken: response.access_token,\n    refreshToken:\n      (typeof response.refresh_token === \"string\" && response.refresh_token) ||\n      previous?.refreshToken,\n    tokenType: (typeof response.token_type === \"string\" && response.token_type) || \"OAuth\",\n    expiresAt: Number.isFinite(expiresIn) && expiresIn > 0 ? now + expiresIn * 1000 : undefined,\n  };\n}\n\n/**\n * Reads a token from session storage. Accepts both the current shape and the\n * legacy raw response that older apps (e.g. AdminUI ≤ 0.1) stored directly in\n * the session, so existing sessions survive an upgrade.\n */\nexport function normalizeStoredToken(raw: unknown): ShopwaveToken | null {\n  if (!raw || typeof raw !== \"object\") return null;\n  const t = raw as Record<string, unknown>;\n\n  if (typeof t.accessToken === \"string\" && t.accessToken) {\n    return {\n      accessToken: t.accessToken,\n      refreshToken: typeof t.refreshToken === \"string\" ? t.refreshToken : undefined,\n      tokenType: typeof t.tokenType === \"string\" && t.tokenType ? t.tokenType : \"OAuth\",\n      expiresAt: typeof t.expiresAt === \"number\" ? t.expiresAt : undefined,\n    };\n  }\n\n  if (typeof t.access_token === \"string\" && t.access_token) {\n    // Legacy shape: we don't know when it was issued, so no expiresAt.\n    // It will be refreshed reactively when the API reports it expired.\n    return {\n      accessToken: t.access_token,\n      refreshToken: typeof t.refresh_token === \"string\" ? t.refresh_token : undefined,\n      tokenType: typeof t.token_type === \"string\" && t.token_type ? t.token_type : \"OAuth\",\n    };\n  }\n\n  return null;\n}\n\n/**\n * True when the token has passed its expiry (minus `skewSeconds`).\n * Tokens without a known expiry are treated as valid.\n *\n * Shopwave only issues a new access token once the old one has actually\n * expired, so the default skew is 0 — refreshing early just returns the same\n * token.\n */\nexport function isTokenExpired(\n  token: ShopwaveToken,\n  { skewSeconds = 0, now = Date.now() }: { skewSeconds?: number; now?: number } = {}\n): boolean {\n  if (token.expiresAt === undefined) return false;\n  return now >= token.expiresAt - skewSeconds * 1000;\n}\n\n/** `Authorization` header value, e.g. `OAuth 111ad…`. */\nexport function authorizationHeader(token: ShopwaveToken): string {\n  return `${token.tokenType || \"OAuth\"} ${token.accessToken}`;\n}\n\n/**\n * True when a Shopwave API response means \"your access token is no longer\n * valid\": HTTP 401, or the API error 908 in the response envelope.\n * Use it to trigger a forced refresh + a single retry.\n */\nexport function isExpiredTokenResponse(status: number, body?: unknown): boolean {\n  if (status === 401) return true;\n  const errors = (body as { api?: { message?: { errors?: Record<string, { id?: number }> } } })\n    ?.api?.message?.errors;\n  if (!errors || typeof errors !== \"object\") return false;\n  return Object.entries(errors).some(\n    ([key, value]) =>\n      key === String(SHOPWAVE_TOKEN_EXPIRED_ERROR_ID) ||\n      Number(value?.id) === SHOPWAVE_TOKEN_EXPIRED_ERROR_ID\n  );\n}\n","import { ShopwaveAuthError } from \"./errors\";\nimport { tokenFromResponse, type ShopwaveToken, type ShopwaveTokenResponse } from \"./token\";\n\n/**\n * Per-app OAuth settings. Everything that differs between Shopwave apps lives\n * here; the flow itself is identical for all of them.\n */\nexport interface ShopwaveOAuthConfig {\n  /** e.g. `https://secure.merchantstack.com` (no trailing slash needed). */\n  authServerUrl: string;\n  clientId: string;\n  /** Server-side only. Never expose it to the browser. */\n  clientSecret: string;\n  /**\n   * The callback URL registered for this client on the auth server, e.g.\n   * `https://admin.example.com/auth`. Must match exactly.\n   */\n  redirectUri: string;\n  /** Where the auth server sends the user after logout. Defaults to `redirectUri`. */\n  postLogoutRedirectUri?: string;\n  /** Defaults to `\"application\"`. */\n  scope?: string;\n  /** Defaults to `\"online\"`. */\n  accessType?: string;\n  /**\n   * Body encoding for `POST /oauth/token`. Defaults to standard\n   * `application/x-www-form-urlencoded`; `\"multipart\"` sends `FormData`.\n   */\n  tokenRequestFormat?: \"urlencoded\" | \"multipart\";\n  /** Auth-server paths. Defaults match Shopwave: `/login`, `/oauth/token`, `/logout`. */\n  endpoints?: { login?: string; token?: string; logout?: string };\n  /** Custom fetch (tests, proxies). Defaults to global `fetch`. */\n  fetch?: typeof fetch;\n}\n\nexport interface ShopwaveOAuthClient {\n  readonly config: Readonly<ShopwaveOAuthConfig>;\n  /** URL to send the browser to so the user can sign in. */\n  buildLoginUrl(params?: { state?: string }): string;\n  /** URL to send the browser to so the auth server ends its own session. */\n  buildLogoutUrl(params?: { redirectUri?: string }): string;\n  /** Exchanges the `?code=` from the callback for tokens (server-to-server). */\n  exchangeCode(code: string): Promise<ShopwaveToken>;\n  /**\n   * Gets a fresh access token. Shopwave keeps the same refresh token, so the\n   * returned token carries the previous refresh token when none is sent back.\n   */\n  refreshToken(token: ShopwaveToken | string): Promise<ShopwaveToken>;\n}\n\nconst REQUIRED_KEYS = [\"authServerUrl\", \"clientId\", \"clientSecret\", \"redirectUri\"] as const;\n\n/** Throws a readable error when required settings are missing. */\nexport function assertOAuthConfig(config: Partial<ShopwaveOAuthConfig>): asserts config is ShopwaveOAuthConfig {\n  const missing = REQUIRED_KEYS.filter((k) => !config?.[k]);\n  if (missing.length > 0) {\n    throw new ShopwaveAuthError(\n      \"config_invalid\",\n      `Shopwave auth is missing required settings: ${missing.join(\", \")}`\n    );\n  }\n}\n\nfunction trimSlash(url: string): string {\n  return url.replace(/\\/+$/, \"\");\n}\n\n/**\n * Creates a framework-agnostic Shopwave OAuth client (authorization-code flow\n * with a client secret — the Shopwave auth server does not support PKCE, so\n * this must run on a server).\n *\n * Config is validated lazily on first use, so creating the client at module\n * scope doesn't break builds where env vars aren't present.\n */\nexport function createShopwaveOAuth(config: ShopwaveOAuthConfig): ShopwaveOAuthClient {\n  const endpoints = {\n    login: config.endpoints?.login ?? \"/login\",\n    token: config.endpoints?.token ?? \"/oauth/token\",\n    logout: config.endpoints?.logout ?? \"/logout\",\n  };\n\n  const base = () => {\n    assertOAuthConfig(config);\n    return trimSlash(config.authServerUrl);\n  };\n\n  const commonParams = (redirectUri: string) =>\n    new URLSearchParams({\n      access_type: config.accessType ?? \"online\",\n      redirect_uri: redirectUri,\n      response_type: \"code\",\n      client_id: config.clientId,\n      scope: config.scope ?? \"application\",\n    });\n\n  async function postToken(\n    fields: Record<string, string>,\n    errorCode: \"token_exchange_failed\" | \"token_refresh_failed\"\n  ): Promise<ShopwaveTokenResponse> {\n    const url = `${base()}${endpoints.token}`;\n    const doFetch = config.fetch ?? globalThis.fetch;\n\n    let body: URLSearchParams | FormData;\n    if (config.tokenRequestFormat === \"multipart\") {\n      const fd = new FormData();\n      for (const [k, v] of Object.entries(fields)) fd.append(k, v);\n      body = fd;\n    } else {\n      body = new URLSearchParams(fields);\n    }\n\n    let response: Response;\n    try {\n      response = await doFetch(url, {\n        method: \"POST\",\n        body,\n        headers: { Accept: \"application/json\" },\n        cache: \"no-store\",\n      } as RequestInit);\n    } catch (cause) {\n      throw new ShopwaveAuthError(\"network_error\", `Could not reach the Shopwave auth server`, { cause });\n    }\n\n    const text = await response.text();\n    if (!response.ok) {\n      throw new ShopwaveAuthError(\n        errorCode,\n        `Shopwave auth server returned ${response.status} for ${fields.grant_type}`,\n        { status: response.status, body: text.slice(0, 2000) }\n      );\n    }\n\n    try {\n      return JSON.parse(text) as ShopwaveTokenResponse;\n    } catch (cause) {\n      throw new ShopwaveAuthError(\"token_response_invalid\", \"Token response was not JSON\", {\n        status: response.status,\n        body: text.slice(0, 2000),\n        cause,\n      });\n    }\n  }\n\n  return {\n    config,\n\n    buildLoginUrl({ state } = {}) {\n      const params = commonParams(config.redirectUri);\n      if (state) params.set(\"state\", state);\n      return `${base()}${endpoints.login}?${params.toString()}`;\n    },\n\n    buildLogoutUrl({ redirectUri } = {}) {\n      const params = commonParams(redirectUri ?? config.postLogoutRedirectUri ?? config.redirectUri);\n      return `${base()}${endpoints.logout}?${params.toString()}`;\n    },\n\n    async exchangeCode(code) {\n      if (!code) {\n        throw new ShopwaveAuthError(\"token_exchange_failed\", \"Missing authorization code\");\n      }\n      const json = await postToken(\n        {\n          code,\n          redirect_uri: config.redirectUri,\n          client_id: config.clientId,\n          client_secret: config.clientSecret,\n          scope: config.scope ?? \"application\",\n          grant_type: \"authorization_code\",\n        },\n        \"token_exchange_failed\"\n      );\n      const token = tokenFromResponse(json);\n      if (!token) {\n        throw new ShopwaveAuthError(\"token_response_invalid\", \"Token response had no access_token\");\n      }\n      return token;\n    },\n\n    async refreshToken(tokenOrRefreshToken) {\n      const previous =\n        typeof tokenOrRefreshToken === \"string\"\n          ? ({ accessToken: \"\", refreshToken: tokenOrRefreshToken, tokenType: \"OAuth\" } as ShopwaveToken)\n          : tokenOrRefreshToken;\n\n      if (!previous.refreshToken) {\n        throw new ShopwaveAuthError(\"token_refresh_failed\", \"No refresh token available\", { status: 400 });\n      }\n\n      const json = await postToken(\n        {\n          refresh_token: previous.refreshToken,\n          redirect_uri: config.redirectUri,\n          client_id: config.clientId,\n          client_secret: config.clientSecret,\n          grant_type: \"refresh_token\",\n        },\n        \"token_refresh_failed\"\n      );\n      const token = tokenFromResponse(json, previous);\n      if (!token) {\n        throw new ShopwaveAuthError(\"token_response_invalid\", \"Refresh response had no access_token\");\n      }\n      return token;\n    },\n  };\n}\n","/**\n * Helpers for the round trip through the auth server.\n */\n\n/**\n * Only allows same-origin relative paths (\"/products?tab=1\"). Anything that\n * could send the user to another site after login — absolute URLs,\n * protocol-relative \"//evil.com\", backslash tricks, control characters —\n * falls back to `fallback`.\n */\nexport function sanitizeReturnTo(value: unknown, fallback = \"/\"): string {\n  if (typeof value !== \"string\" || value.length === 0 || value.length > 2048) {\n    return fallback;\n  }\n  // Must start with a single \"/\" not followed by \"/\" or \"\\\".\n  if (!/^\\/(?![/\\\\])/.test(value)) return fallback;\n  // No control characters (CR/LF header injection, tabs, NUL, …).\n  // eslint-disable-next-line no-control-regex\n  if (/[\\u0000-\\u001f\\u007f]/.test(value)) return fallback;\n  if (value.includes(\"\\\\\")) return fallback;\n  return value;\n}\n\n/** Random, URL-safe value for the OAuth `state` parameter (128 bits, hex). */\nexport function createState(): string {\n  const bytes = new Uint8Array(16);\n  globalThis.crypto.getRandomValues(bytes);\n  return Array.from(bytes, (b) => b.toString(16).padStart(2, \"0\")).join(\"\");\n}\n\n/** Constant-time string comparison for state values. */\nexport function safeEqual(a: string, b: string): boolean {\n  if (typeof a !== \"string\" || typeof b !== \"string\" || a.length !== b.length) return false;\n  let diff = 0;\n  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);\n  return diff === 0;\n}\n"],"mappings":";;AAaA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,AAAS;CACT,AAAS;;CAET,AAAS;CAET,YACE,MACA,SACA,UAA+D,EAAE,EACjE;AACA,QAAM,SAAS,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,OAAO,GAAG,OAAU;AAClF,OAAK,OAAO;AACZ,OAAK,OAAO;AACZ,OAAK,SAAS,QAAQ;AACtB,OAAK,OAAO,QAAQ;;;;;;;CAQtB,IAAI,iBAA0B;AAC5B,UACG,KAAK,SAAS,2BAA2B,KAAK,SAAS,2BACxD,KAAK,WAAW,UAChB,KAAK,UAAU,OACf,KAAK,SAAS;;;;;;;ACXpB,MAAa,kCAAkC;;;;;;;;AAS/C,SAAgB,kBACd,UACA,UACA,MAAc,KAAK,KAAK,EACF;AACtB,KAAI,CAAC,YAAY,OAAO,SAAS,iBAAiB,YAAY,CAAC,SAAS,aACtE,QAAO;CAGT,MAAM,YAAY,OAAO,SAAS,WAAW;AAE7C,QAAO;EACL,aAAa,SAAS;EACtB,cACG,OAAO,SAAS,kBAAkB,YAAY,SAAS,iBACxD,UAAU;EACZ,WAAY,OAAO,SAAS,eAAe,YAAY,SAAS,cAAe;EAC/E,WAAW,OAAO,SAAS,UAAU,IAAI,YAAY,IAAI,MAAM,YAAY,MAAO;EACnF;;;;;;;AAQH,SAAgB,qBAAqB,KAAoC;AACvE,KAAI,CAAC,OAAO,OAAO,QAAQ,SAAU,QAAO;CAC5C,MAAM,IAAI;AAEV,KAAI,OAAO,EAAE,gBAAgB,YAAY,EAAE,YACzC,QAAO;EACL,aAAa,EAAE;EACf,cAAc,OAAO,EAAE,iBAAiB,WAAW,EAAE,eAAe;EACpE,WAAW,OAAO,EAAE,cAAc,YAAY,EAAE,YAAY,EAAE,YAAY;EAC1E,WAAW,OAAO,EAAE,cAAc,WAAW,EAAE,YAAY;EAC5D;AAGH,KAAI,OAAO,EAAE,iBAAiB,YAAY,EAAE,aAG1C,QAAO;EACL,aAAa,EAAE;EACf,cAAc,OAAO,EAAE,kBAAkB,WAAW,EAAE,gBAAgB;EACtE,WAAW,OAAO,EAAE,eAAe,YAAY,EAAE,aAAa,EAAE,aAAa;EAC9E;AAGH,QAAO;;;;;;;;;;AAWT,SAAgB,eACd,OACA,EAAE,cAAc,GAAG,MAAM,KAAK,KAAK,KAA6C,EAAE,EACzE;AACT,KAAI,MAAM,cAAc,OAAW,QAAO;AAC1C,QAAO,OAAO,MAAM,YAAY,cAAc;;;AAIhD,SAAgB,oBAAoB,OAA8B;AAChE,QAAO,GAAG,MAAM,aAAa,QAAQ,GAAG,MAAM;;;;;;;AAQhD,SAAgB,uBAAuB,QAAgB,MAAyB;AAC9E,KAAI,WAAW,IAAK,QAAO;CAC3B,MAAM,SAAU,MACZ,KAAK,SAAS;AAClB,KAAI,CAAC,UAAU,OAAO,WAAW,SAAU,QAAO;AAClD,QAAO,OAAO,QAAQ,OAAO,CAAC,MAC3B,CAAC,KAAK,WACL,QAAQ,OAAO,gCAAgC,IAC/C,OAAO,OAAO,GAAG,KAAK,gCACzB;;;;;AC5EH,MAAM,gBAAgB;CAAC;CAAiB;CAAY;CAAgB;CAAc;;AAGlF,SAAgB,kBAAkB,QAA6E;CAC7G,MAAM,UAAU,cAAc,QAAQ,MAAM,CAAC,SAAS,GAAG;AACzD,KAAI,QAAQ,SAAS,EACnB,OAAM,IAAI,kBACR,kBACA,+CAA+C,QAAQ,KAAK,KAAK,GAClE;;AAIL,SAAS,UAAU,KAAqB;AACtC,QAAO,IAAI,QAAQ,QAAQ,GAAG;;;;;;;;;;AAWhC,SAAgB,oBAAoB,QAAkD;CACpF,MAAM,YAAY;EAChB,OAAO,OAAO,WAAW,SAAS;EAClC,OAAO,OAAO,WAAW,SAAS;EAClC,QAAQ,OAAO,WAAW,UAAU;EACrC;CAED,MAAM,aAAa;AACjB,oBAAkB,OAAO;AACzB,SAAO,UAAU,OAAO,cAAc;;CAGxC,MAAM,gBAAgB,gBACpB,IAAI,gBAAgB;EAClB,aAAa,OAAO,cAAc;EAClC,cAAc;EACd,eAAe;EACf,WAAW,OAAO;EAClB,OAAO,OAAO,SAAS;EACxB,CAAC;CAEJ,eAAe,UACb,QACA,WACgC;EAChC,MAAM,MAAM,GAAG,MAAM,GAAG,UAAU;EAClC,MAAM,UAAU,OAAO,SAAS,WAAW;EAE3C,IAAIA;AACJ,MAAI,OAAO,uBAAuB,aAAa;GAC7C,MAAM,KAAK,IAAI,UAAU;AACzB,QAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,OAAO,CAAE,IAAG,OAAO,GAAG,EAAE;AAC5D,UAAO;QAEP,QAAO,IAAI,gBAAgB,OAAO;EAGpC,IAAIC;AACJ,MAAI;AACF,cAAW,MAAM,QAAQ,KAAK;IAC5B,QAAQ;IACR;IACA,SAAS,EAAE,QAAQ,oBAAoB;IACvC,OAAO;IACR,CAAgB;WACV,OAAO;AACd,SAAM,IAAI,kBAAkB,iBAAiB,4CAA4C,EAAE,OAAO,CAAC;;EAGrG,MAAM,OAAO,MAAM,SAAS,MAAM;AAClC,MAAI,CAAC,SAAS,GACZ,OAAM,IAAI,kBACR,WACA,iCAAiC,SAAS,OAAO,OAAO,OAAO,cAC/D;GAAE,QAAQ,SAAS;GAAQ,MAAM,KAAK,MAAM,GAAG,IAAK;GAAE,CACvD;AAGH,MAAI;AACF,UAAO,KAAK,MAAM,KAAK;WAChB,OAAO;AACd,SAAM,IAAI,kBAAkB,0BAA0B,+BAA+B;IACnF,QAAQ,SAAS;IACjB,MAAM,KAAK,MAAM,GAAG,IAAK;IACzB;IACD,CAAC;;;AAIN,QAAO;EACL;EAEA,cAAc,EAAE,UAAU,EAAE,EAAE;GAC5B,MAAM,SAAS,aAAa,OAAO,YAAY;AAC/C,OAAI,MAAO,QAAO,IAAI,SAAS,MAAM;AACrC,UAAO,GAAG,MAAM,GAAG,UAAU,MAAM,GAAG,OAAO,UAAU;;EAGzD,eAAe,EAAE,gBAAgB,EAAE,EAAE;GACnC,MAAM,SAAS,aAAa,eAAe,OAAO,yBAAyB,OAAO,YAAY;AAC9F,UAAO,GAAG,MAAM,GAAG,UAAU,OAAO,GAAG,OAAO,UAAU;;EAG1D,MAAM,aAAa,MAAM;AACvB,OAAI,CAAC,KACH,OAAM,IAAI,kBAAkB,yBAAyB,6BAA6B;GAapF,MAAM,QAAQ,kBAXD,MAAM,UACjB;IACE;IACA,cAAc,OAAO;IACrB,WAAW,OAAO;IAClB,eAAe,OAAO;IACtB,OAAO,OAAO,SAAS;IACvB,YAAY;IACb,EACD,wBACD,CACoC;AACrC,OAAI,CAAC,MACH,OAAM,IAAI,kBAAkB,0BAA0B,qCAAqC;AAE7F,UAAO;;EAGT,MAAM,aAAa,qBAAqB;GACtC,MAAM,WACJ,OAAO,wBAAwB,WAC1B;IAAE,aAAa;IAAI,cAAc;IAAqB,WAAW;IAAS,GAC3E;AAEN,OAAI,CAAC,SAAS,aACZ,OAAM,IAAI,kBAAkB,wBAAwB,8BAA8B,EAAE,QAAQ,KAAK,CAAC;GAapG,MAAM,QAAQ,kBAVD,MAAM,UACjB;IACE,eAAe,SAAS;IACxB,cAAc,OAAO;IACrB,WAAW,OAAO;IAClB,eAAe,OAAO;IACtB,YAAY;IACb,EACD,uBACD,EACqC,SAAS;AAC/C,OAAI,CAAC,MACH,OAAM,IAAI,kBAAkB,0BAA0B,uCAAuC;AAE/F,UAAO;;EAEV;;;;;;;;;;;;;;ACpMH,SAAgB,iBAAiB,OAAgB,WAAW,KAAa;AACvE,KAAI,OAAO,UAAU,YAAY,MAAM,WAAW,KAAK,MAAM,SAAS,KACpE,QAAO;AAGT,KAAI,CAAC,eAAe,KAAK,MAAM,CAAE,QAAO;AAGxC,KAAI,wBAAwB,KAAK,MAAM,CAAE,QAAO;AAChD,KAAI,MAAM,SAAS,KAAK,CAAE,QAAO;AACjC,QAAO;;;AAIT,SAAgB,cAAsB;CACpC,MAAM,QAAQ,IAAI,WAAW,GAAG;AAChC,YAAW,OAAO,gBAAgB,MAAM;AACxC,QAAO,MAAM,KAAK,QAAQ,MAAM,EAAE,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,KAAK,GAAG;;;AAI3E,SAAgB,UAAU,GAAW,GAAoB;AACvD,KAAI,OAAO,MAAM,YAAY,OAAO,MAAM,YAAY,EAAE,WAAW,EAAE,OAAQ,QAAO;CACpF,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,IAAK,SAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,EAAE;AAC5E,QAAO,SAAS"}

package/dist/server/index.d.cts

@@ -0,0 +1,177 @@
+//#region src/server/token.d.ts
+/**
+ * Token model + helpers shared by every server-side integration.
+ *
+ * The Shopwave auth server returns (snake_case):
+ *   { access_token, refresh_token, token_type: "OAuth", expires_in: 43200 }
+ *
+ * We store a normalised, camelCase shape with an absolute expiry so any
+ * request can decide whether the token is still usable without extra state.
+ */
+interface ShopwaveToken {
+  accessToken: string;
+  /** Long-lived; the Shopwave server does not rotate it on refresh. */
+  refreshToken?: string;
+  /** Scheme used in the Authorization header. Shopwave uses "OAuth". */
+  tokenType: string;
+  /** Absolute expiry, epoch milliseconds. Undefined if the server didn't say. */
+  expiresAt?: number;
+}
+/** Raw token response from `POST {authServer}/oauth/token`. */
+interface ShopwaveTokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  token_type?: string;
+  expires_in?: number | string;
+  [key: string]: unknown;
+}
+/** Shopwave API error id meaning "access token expired / invalid". */
+declare const SHOPWAVE_TOKEN_EXPIRED_ERROR_ID = 908;
+/**
+ * Converts a token-endpoint response into a {@link ShopwaveToken}.
+ * Returns `null` when the response has no access token.
+ *
+ * @param previous  the token being refreshed; its refresh token is kept when
+ *                  the server doesn't send a new one.
+ */
+declare function tokenFromResponse(response: ShopwaveTokenResponse, previous?: ShopwaveToken, now?: number): ShopwaveToken | null;
+/**
+ * Reads a token from session storage. Accepts both the current shape and the
+ * legacy raw response that older apps (e.g. AdminUI ≤ 0.1) stored directly in
+ * the session, so existing sessions survive an upgrade.
+ */
+declare function normalizeStoredToken(raw: unknown): ShopwaveToken | null;
+/**
+ * True when the token has passed its expiry (minus `skewSeconds`).
+ * Tokens without a known expiry are treated as valid.
+ *
+ * Shopwave only issues a new access token once the old one has actually
+ * expired, so the default skew is 0 — refreshing early just returns the same
+ * token.
+ */
+declare function isTokenExpired(token: ShopwaveToken, {
+  skewSeconds,
+  now
+}?: {
+  skewSeconds?: number;
+  now?: number;
+}): boolean;
+/** `Authorization` header value, e.g. `OAuth 111ad…`. */
+declare function authorizationHeader(token: ShopwaveToken): string;
+/**
+ * True when a Shopwave API response means "your access token is no longer
+ * valid": HTTP 401, or the API error 908 in the response envelope.
+ * Use it to trigger a forced refresh + a single retry.
+ */
+declare function isExpiredTokenResponse(status: number, body?: unknown): boolean;
+//#endregion
+//#region src/server/oauth.d.ts
+/**
+ * Per-app OAuth settings. Everything that differs between Shopwave apps lives
+ * here; the flow itself is identical for all of them.
+ */
+interface ShopwaveOAuthConfig {
+  /** e.g. `https://secure.merchantstack.com` (no trailing slash needed). */
+  authServerUrl: string;
+  clientId: string;
+  /** Server-side only. Never expose it to the browser. */
+  clientSecret: string;
+  /**
+   * The callback URL registered for this client on the auth server, e.g.
+   * `https://admin.example.com/auth`. Must match exactly.
+   */
+  redirectUri: string;
+  /** Where the auth server sends the user after logout. Defaults to `redirectUri`. */
+  postLogoutRedirectUri?: string;
+  /** Defaults to `"application"`. */
+  scope?: string;
+  /** Defaults to `"online"`. */
+  accessType?: string;
+  /**
+   * Body encoding for `POST /oauth/token`. Defaults to standard
+   * `application/x-www-form-urlencoded`; `"multipart"` sends `FormData`.
+   */
+  tokenRequestFormat?: "urlencoded" | "multipart";
+  /** Auth-server paths. Defaults match Shopwave: `/login`, `/oauth/token`, `/logout`. */
+  endpoints?: {
+    login?: string;
+    token?: string;
+    logout?: string;
+  };
+  /** Custom fetch (tests, proxies). Defaults to global `fetch`. */
+  fetch?: typeof fetch;
+}
+interface ShopwaveOAuthClient {
+  readonly config: Readonly<ShopwaveOAuthConfig>;
+  /** URL to send the browser to so the user can sign in. */
+  buildLoginUrl(params?: {
+    state?: string;
+  }): string;
+  /** URL to send the browser to so the auth server ends its own session. */
+  buildLogoutUrl(params?: {
+    redirectUri?: string;
+  }): string;
+  /** Exchanges the `?code=` from the callback for tokens (server-to-server). */
+  exchangeCode(code: string): Promise<ShopwaveToken>;
+  /**
+   * Gets a fresh access token. Shopwave keeps the same refresh token, so the
+   * returned token carries the previous refresh token when none is sent back.
+   */
+  refreshToken(token: ShopwaveToken | string): Promise<ShopwaveToken>;
+}
+/** Throws a readable error when required settings are missing. */
+declare function assertOAuthConfig(config: Partial<ShopwaveOAuthConfig>): asserts config is ShopwaveOAuthConfig;
+/**
+ * Creates a framework-agnostic Shopwave OAuth client (authorization-code flow
+ * with a client secret — the Shopwave auth server does not support PKCE, so
+ * this must run on a server).
+ *
+ * Config is validated lazily on first use, so creating the client at module
+ * scope doesn't break builds where env vars aren't present.
+ */
+declare function createShopwaveOAuth(config: ShopwaveOAuthConfig): ShopwaveOAuthClient;
+//#endregion
+//#region src/server/returnTo.d.ts
+/**
+ * Helpers for the round trip through the auth server.
+ */
+/**
+ * Only allows same-origin relative paths ("/products?tab=1"). Anything that
+ * could send the user to another site after login — absolute URLs,
+ * protocol-relative "//evil.com", backslash tricks, control characters —
+ * falls back to `fallback`.
+ */
+declare function sanitizeReturnTo(value: unknown, fallback?: string): string;
+/** Random, URL-safe value for the OAuth `state` parameter (128 bits, hex). */
+declare function createState(): string;
+/** Constant-time string comparison for state values. */
+declare function safeEqual(a: string, b: string): boolean;
+//#endregion
+//#region src/server/errors.d.ts
+/**
+ * Error thrown by the server-side auth helpers.
+ *
+ * `code` is stable and safe to branch on; `status` is the HTTP status returned
+ * by the Shopwave auth server when there was one.
+ */
+type ShopwaveAuthErrorCode = "config_invalid" | "token_exchange_failed" | "token_refresh_failed" | "token_response_invalid" | "network_error";
+declare class ShopwaveAuthError extends Error {
+  readonly code: ShopwaveAuthErrorCode;
+  readonly status?: number;
+  /** Raw response body from the auth server, if any. Never contains our secret. */
+  readonly body?: string;
+  constructor(code: ShopwaveAuthErrorCode, message: string, details?: {
+    status?: number;
+    body?: string;
+    cause?: unknown;
+  });
+  /**
+   * True when the auth server rejected the grant itself (bad/expired code or
+   * refresh token) rather than failing for a transient reason. Callers should
+   * treat the user as logged out.
+   */
+  get isInvalidGrant(): boolean;
+}
+//#endregion
+export { SHOPWAVE_TOKEN_EXPIRED_ERROR_ID, ShopwaveAuthError, type ShopwaveAuthErrorCode, type ShopwaveOAuthClient, type ShopwaveOAuthConfig, type ShopwaveToken, type ShopwaveTokenResponse, assertOAuthConfig, authorizationHeader, createShopwaveOAuth, createState, isExpiredTokenResponse, isTokenExpired, normalizeStoredToken, safeEqual, sanitizeReturnTo, tokenFromResponse };
+//# sourceMappingURL=index.d.cts.map

package/dist/server/index.d.ts

@@ -0,0 +1,177 @@
+//#region src/server/token.d.ts
+/**
+ * Token model + helpers shared by every server-side integration.
+ *
+ * The Shopwave auth server returns (snake_case):
+ *   { access_token, refresh_token, token_type: "OAuth", expires_in: 43200 }
+ *
+ * We store a normalised, camelCase shape with an absolute expiry so any
+ * request can decide whether the token is still usable without extra state.
+ */
+interface ShopwaveToken {
+  accessToken: string;
+  /** Long-lived; the Shopwave server does not rotate it on refresh. */
+  refreshToken?: string;
+  /** Scheme used in the Authorization header. Shopwave uses "OAuth". */
+  tokenType: string;
+  /** Absolute expiry, epoch milliseconds. Undefined if the server didn't say. */
+  expiresAt?: number;
+}
+/** Raw token response from `POST {authServer}/oauth/token`. */
+interface ShopwaveTokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  token_type?: string;
+  expires_in?: number | string;
+  [key: string]: unknown;
+}
+/** Shopwave API error id meaning "access token expired / invalid". */
+declare const SHOPWAVE_TOKEN_EXPIRED_ERROR_ID = 908;
+/**
+ * Converts a token-endpoint response into a {@link ShopwaveToken}.
+ * Returns `null` when the response has no access token.
+ *
+ * @param previous  the token being refreshed; its refresh token is kept when
+ *                  the server doesn't send a new one.
+ */
+declare function tokenFromResponse(response: ShopwaveTokenResponse, previous?: ShopwaveToken, now?: number): ShopwaveToken | null;
+/**
+ * Reads a token from session storage. Accepts both the current shape and the
+ * legacy raw response that older apps (e.g. AdminUI ≤ 0.1) stored directly in
+ * the session, so existing sessions survive an upgrade.
+ */
+declare function normalizeStoredToken(raw: unknown): ShopwaveToken | null;
+/**
+ * True when the token has passed its expiry (minus `skewSeconds`).
+ * Tokens without a known expiry are treated as valid.
+ *
+ * Shopwave only issues a new access token once the old one has actually
+ * expired, so the default skew is 0 — refreshing early just returns the same
+ * token.
+ */
+declare function isTokenExpired(token: ShopwaveToken, {
+  skewSeconds,
+  now
+}?: {
+  skewSeconds?: number;
+  now?: number;
+}): boolean;
+/** `Authorization` header value, e.g. `OAuth 111ad…`. */
+declare function authorizationHeader(token: ShopwaveToken): string;
+/**
+ * True when a Shopwave API response means "your access token is no longer
+ * valid": HTTP 401, or the API error 908 in the response envelope.
+ * Use it to trigger a forced refresh + a single retry.
+ */
+declare function isExpiredTokenResponse(status: number, body?: unknown): boolean;
+//#endregion
+//#region src/server/oauth.d.ts
+/**
+ * Per-app OAuth settings. Everything that differs between Shopwave apps lives
+ * here; the flow itself is identical for all of them.
+ */
+interface ShopwaveOAuthConfig {
+  /** e.g. `https://secure.merchantstack.com` (no trailing slash needed). */
+  authServerUrl: string;
+  clientId: string;
+  /** Server-side only. Never expose it to the browser. */
+  clientSecret: string;
+  /**
+   * The callback URL registered for this client on the auth server, e.g.
+   * `https://admin.example.com/auth`. Must match exactly.
+   */
+  redirectUri: string;
+  /** Where the auth server sends the user after logout. Defaults to `redirectUri`. */
+  postLogoutRedirectUri?: string;
+  /** Defaults to `"application"`. */
+  scope?: string;
+  /** Defaults to `"online"`. */
+  accessType?: string;
+  /**
+   * Body encoding for `POST /oauth/token`. Defaults to standard
+   * `application/x-www-form-urlencoded`; `"multipart"` sends `FormData`.
+   */
+  tokenRequestFormat?: "urlencoded" | "multipart";
+  /** Auth-server paths. Defaults match Shopwave: `/login`, `/oauth/token`, `/logout`. */
+  endpoints?: {
+    login?: string;
+    token?: string;
+    logout?: string;
+  };
+  /** Custom fetch (tests, proxies). Defaults to global `fetch`. */
+  fetch?: typeof fetch;
+}
+interface ShopwaveOAuthClient {
+  readonly config: Readonly<ShopwaveOAuthConfig>;
+  /** URL to send the browser to so the user can sign in. */
+  buildLoginUrl(params?: {
+    state?: string;
+  }): string;
+  /** URL to send the browser to so the auth server ends its own session. */
+  buildLogoutUrl(params?: {
+    redirectUri?: string;
+  }): string;
+  /** Exchanges the `?code=` from the callback for tokens (server-to-server). */
+  exchangeCode(code: string): Promise<ShopwaveToken>;
+  /**
+   * Gets a fresh access token. Shopwave keeps the same refresh token, so the
+   * returned token carries the previous refresh token when none is sent back.
+   */
+  refreshToken(token: ShopwaveToken | string): Promise<ShopwaveToken>;
+}
+/** Throws a readable error when required settings are missing. */
+declare function assertOAuthConfig(config: Partial<ShopwaveOAuthConfig>): asserts config is ShopwaveOAuthConfig;
+/**
+ * Creates a framework-agnostic Shopwave OAuth client (authorization-code flow
+ * with a client secret — the Shopwave auth server does not support PKCE, so
+ * this must run on a server).
+ *
+ * Config is validated lazily on first use, so creating the client at module
+ * scope doesn't break builds where env vars aren't present.
+ */
+declare function createShopwaveOAuth(config: ShopwaveOAuthConfig): ShopwaveOAuthClient;
+//#endregion
+//#region src/server/returnTo.d.ts
+/**
+ * Helpers for the round trip through the auth server.
+ */
+/**
+ * Only allows same-origin relative paths ("/products?tab=1"). Anything that
+ * could send the user to another site after login — absolute URLs,
+ * protocol-relative "//evil.com", backslash tricks, control characters —
+ * falls back to `fallback`.
+ */
+declare function sanitizeReturnTo(value: unknown, fallback?: string): string;
+/** Random, URL-safe value for the OAuth `state` parameter (128 bits, hex). */
+declare function createState(): string;
+/** Constant-time string comparison for state values. */
+declare function safeEqual(a: string, b: string): boolean;
+//#endregion
+//#region src/server/errors.d.ts
+/**
+ * Error thrown by the server-side auth helpers.
+ *
+ * `code` is stable and safe to branch on; `status` is the HTTP status returned
+ * by the Shopwave auth server when there was one.
+ */
+type ShopwaveAuthErrorCode = "config_invalid" | "token_exchange_failed" | "token_refresh_failed" | "token_response_invalid" | "network_error";
+declare class ShopwaveAuthError extends Error {
+  readonly code: ShopwaveAuthErrorCode;
+  readonly status?: number;
+  /** Raw response body from the auth server, if any. Never contains our secret. */
+  readonly body?: string;
+  constructor(code: ShopwaveAuthErrorCode, message: string, details?: {
+    status?: number;
+    body?: string;
+    cause?: unknown;
+  });
+  /**
+   * True when the auth server rejected the grant itself (bad/expired code or
+   * refresh token) rather than failing for a transient reason. Callers should
+   * treat the user as logged out.
+   */
+  get isInvalidGrant(): boolean;
+}
+//#endregion
+export { SHOPWAVE_TOKEN_EXPIRED_ERROR_ID, ShopwaveAuthError, type ShopwaveAuthErrorCode, type ShopwaveOAuthClient, type ShopwaveOAuthConfig, type ShopwaveToken, type ShopwaveTokenResponse, assertOAuthConfig, authorizationHeader, createShopwaveOAuth, createState, isExpiredTokenResponse, isTokenExpired, normalizeStoredToken, safeEqual, sanitizeReturnTo, tokenFromResponse };
+//# sourceMappingURL=index.d.ts.map