@shopify/shopify-api 13.1.0 → 14.0.1

package/lib/__test-helpers__/graphql-base-request.ts

@@ -5,6 +5,6 @@ export const ACCESS_TOKEN = 'access-token';
 export const GRAPHQL_BASE_REQUEST = {
   method: 'POST',
   domain: DOMAIN,
-  path: `/admin/api/${ApiVersion.July25}/graphql.json`,
+  path: `/admin/api/${ApiVersion.July26}/graphql.json`,
   headers: {'X-Shopify-Access-Token': ACCESS_TOKEN},
 };

package/lib/auth/oauth/create-session.ts

@@ -31,7 +31,7 @@ export function createSession({
     new Date(Date.now() + expires_in * 1000);
 
   const getOnlineSessionProperties = (responseBody: OnlineAccessResponse) => {
-    const {access_token, scope, ...rest} = responseBody;
+    const {access_token: _access_token, scope: _scope, ...rest} = responseBody;
     const sessionId = config.isEmbeddedApp
       ? getJwtSessionId(config)(
           shop,

package/lib/auth/oauth/oauth.ts

@@ -217,11 +217,15 @@ export function callback(config: ConfigInterface): OAuthCallback {
     });
 
     if (!config.isEmbeddedApp) {
+      const cookiePath =
+        typeof config.cookiePath === 'function'
+          ? config.cookiePath(session)
+          : (config.cookiePath ?? '/');
       await cookies.setAndSign(SESSION_COOKIE_NAME, session.id, {
         expires: session.expires,
         sameSite: 'lax',
         secure: true,
-        path: '/',
+        path: cookiePath,
       });
     }
 

package/lib/base-types.ts

@@ -3,6 +3,7 @@ import {ShopifyRestResources} from '../rest/types';
 
 import {AuthScopes} from './auth/scopes';
 import {BillingConfig} from './billing/types';
+import {Session} from './session/session';
 import {ApiVersion, DomainTransformation, LogSeverity} from './types';
 
 /**
@@ -135,6 +136,33 @@ export interface ConfigParams<
    * @private
    */
   _logDisabledFutureFlags?: boolean;
+  /**
+   * The path to use for the OAuth session cookie in non-embedded apps.
+   *
+   * By default the cookie is written with `path: '/'`, making it domain-wide.
+   * This means that when a user authenticates multiple shops in separate tabs,
+   * each OAuth callback overwrites the previous cookie, causing all tabs to use
+   * the most-recently-authenticated shop.
+   *
+   * Set this to a string or a function returning a string to scope the cookie to
+   * a URL path prefix that is unique per shop. The browser will then maintain
+   * one cookie per shop and deliver only the matching one per request.
+   *
+   * **Requirement:** the configured path must match the actual URL structure of
+   * your app — e.g. if each shop lives under `/shops/:shop/`, use that prefix.
+   * The library cannot derive this automatically.
+   *
+   * @example
+   * // Static path (single-shop apps or apps with no shop-specific routing)
+   * cookiePath: '/'
+   *
+   * @example
+   * // Factory function (multi-shop non-embedded apps)
+   * cookiePath: (session) => `/shops/${session.shop}/`
+   *
+   * @defaultValue `'/'`
+   */
+  cookiePath?: string | ((session: Session) => string);
   /**
    * Whether the app is initialised for local testing.
    */

package/lib/billing/types.ts

@@ -66,8 +66,7 @@ export interface BillingConfigSubscriptionPlanDiscount {
 }
 
 export type BillingConfigItem =
-  | BillingConfigOneTimePlan
-  | BillingConfigSubscriptionLineItemPlan;
+  BillingConfigOneTimePlan | BillingConfigSubscriptionLineItemPlan;
 
 // Type this as an interface to improve TSDoc support for it.
 
@@ -590,8 +589,7 @@ export interface SinglePaymentResponse {
 }
 
 export type RequestResponseData =
-  | AppSubscriptionCreate
-  | AppPurchaseOneTimeCreate;
+  AppSubscriptionCreate | AppPurchaseOneTimeCreate;
 
 export interface SubscriptionResponse {
   currentAppInstallation?: ActiveSubscriptions;

package/lib/clients/common.ts

@@ -25,6 +25,86 @@ export function getUserAgent(config: ConfigInterface): string {
   return userAgentPrefix;
 }
 
+const REDACTED_LOG_VALUE = '****';
+
+// These headers carry reusable credentials and must not reach the logs.
+const SENSITIVE_LOG_HEADERS = new Set([
+  'authorization',
+  'cookie',
+  'set-cookie',
+  'shopify-storefront-private-token',
+  'x-shopify-access-token',
+  'x-shopify-storefront-access-token',
+]);
+
+function sanitizeHeaderValue(name: string, value: unknown): unknown {
+  return SENSITIVE_LOG_HEADERS.has(name.toLowerCase())
+    ? REDACTED_LOG_VALUE
+    : value;
+}
+
+// Keep the original serialized shape of request headers. A Headers instance
+// has no own enumerable properties, so it stays opaque here, the same as
+// JSON.stringify shows it.
+function sanitizeHeaders(headers: any): any {
+  if (!headers || typeof headers !== 'object') {
+    return headers;
+  }
+
+  if (Array.isArray(headers)) {
+    return headers.map((header) =>
+      Array.isArray(header)
+        ? [header[0], sanitizeHeaderValue(header[0], header[1])]
+        : header,
+    );
+  }
+
+  return Object.fromEntries(
+    Object.entries(headers).map(([name, value]) => [
+      name,
+      sanitizeHeaderValue(name, value),
+    ]),
+  );
+}
+
+// Response headers were always enumerated in the log, so keep that and
+// redact the credential values.
+function sanitizeEnumerableHeaders(headers: any): any {
+  if (typeof headers?.entries === 'function' && !Array.isArray(headers)) {
+    return Object.fromEntries(
+      [...headers.entries()].map(([name, value]: [string, string]) => [
+        name,
+        sanitizeHeaderValue(name, value),
+      ]),
+    );
+  }
+
+  return sanitizeHeaders(headers);
+}
+
+function sanitizeRequestParams<T>(requestParams: T): T {
+  if (Array.isArray(requestParams)) {
+    return requestParams.map((param) =>
+      param && typeof param === 'object' && 'headers' in param
+        ? {...param, headers: sanitizeHeaders(param.headers)}
+        : param,
+    ) as T;
+  }
+
+  if (
+    requestParams &&
+    typeof requestParams === 'object' &&
+    'headers' in requestParams
+  ) {
+    return {
+      ...requestParams,
+      headers: sanitizeHeaders((requestParams as {headers: any}).headers),
+    };
+  }
+
+  return requestParams;
+}
+
 function serializeResponse(response: Response | any) {
   if (!response) {
     return {error: 'No response object provided'};
@@ -42,10 +122,8 @@ function serializeResponse(response: Response | any) {
       url,
     };
 
-    if (headers?.entries) {
-      serialized.headers = Object.fromEntries(headers.entries());
-    } else if (headers) {
-      serialized.headers = headers;
+    if (headers) {
+      serialized.headers = sanitizeEnumerableHeaders(headers);
     }
 
     return serialized;
@@ -61,7 +139,9 @@ export function clientLoggerFactory(config: ConfigInterface) {
         case 'HTTP-Response': {
           const responseLog: HTTPResponseLog['content'] = logContent.content;
           logger(config).debug('Received response for HTTP request', {
-            requestParams: JSON.stringify(responseLog.requestParams),
+            requestParams: JSON.stringify(
+              sanitizeRequestParams(responseLog.requestParams),
+            ),
             response: JSON.stringify(serializeResponse(responseLog.response)),
           });
           break;
@@ -69,7 +149,9 @@ export function clientLoggerFactory(config: ConfigInterface) {
         case 'HTTP-Retry': {
           const responseLog: HTTPRetryLog['content'] = logContent.content;
           logger(config).debug('Retrying HTTP request', {
-            requestParams: JSON.stringify(responseLog.requestParams),
+            requestParams: JSON.stringify(
+              sanitizeRequestParams(responseLog.requestParams),
+            ),
             retryAttempt: responseLog.retryAttempt,
             maxRetries: responseLog.maxRetries,
             response: responseLog.lastResponse
@@ -84,7 +166,9 @@ export function clientLoggerFactory(config: ConfigInterface) {
           logger(config).debug(
             'Received response containing Deprecated GraphQL Notice',
             {
-              requestParams: JSON.stringify(responseLog.requestParams),
+              requestParams: JSON.stringify(
+                sanitizeRequestParams(responseLog.requestParams),
+              ),
               deprecationNotice: responseLog.deprecationNotice,
             },
           );

package/lib/config.ts

@@ -53,7 +53,7 @@ export function validateConfig<Params extends ConfigParams>(
     throw new ShopifyError(
       `Cannot initialize Shopify API Library. Missing values for: ${missing.join(
         ', ',
-      )}. For apiVersion, please specify an explicit API version (e.g., ApiVersion.July25). See https://shopify.dev/docs/api/usage/versioning for more information.`,
+      )}. For apiVersion, please specify an explicit API version (e.g., ApiVersion.July26). See https://shopify.dev/docs/api/usage/versioning for more information.`,
     );
   }
 
@@ -85,7 +85,7 @@ export function validateConfig<Params extends ConfigParams>(
     isCustomStoreApp: isCustomStoreApp ?? config.isCustomStoreApp,
     adminApiAccessToken: adminApiAccessToken ?? config.adminApiAccessToken,
     userAgentPrefix: userAgentPrefix ?? config.userAgentPrefix,
-    logger: {...config.logger, ...(logger || {})},
+    logger: {...config.logger, ...logger},
     privateAppStorefrontAccessToken:
       privateAppStorefrontAccessToken ?? config.privateAppStorefrontAccessToken,
     billing: billing ?? config.billing,

package/lib/types.ts

@@ -14,6 +14,7 @@ export enum ApiVersion {
   January26 = '2026-01',
   April26 = '2026-04',
   July26 = '2026-07',
+  October26 = '2026-10',
   Unstable = 'unstable',
 }
 
@@ -26,7 +27,6 @@ export enum ShopifyHeader {
   Domain = 'X-Shopify-Shop-Domain',
   Hmac = 'X-Shopify-Hmac-Sha256',
   Topic = 'X-Shopify-Topic',
-  SubTopic = 'X-Shopify-Sub-Topic',
   WebhookId = 'X-Shopify-Webhook-Id',
   Name = 'X-Shopify-Name',
   TriggeredAt = 'X-Shopify-Triggered-At',

package/lib/utils/fetch-request.ts

@@ -3,6 +3,18 @@ import {LogSeverity} from '../types';
 import {abstractFetch} from '../../runtime';
 import {ConfigInterface} from '../base-types';
 
+const OAUTH_TOKEN_ENDPOINT_PATH = '/admin/oauth/access_token';
+
+// Token endpoint bodies carry OAuth secrets, so they must not reach the logs.
+// When the URL does not parse, fail closed and keep the body out of the logs.
+function canLogRequestBody(url: string): boolean {
+  try {
+    return new URL(url).pathname !== OAUTH_TOKEN_ENDPOINT_PATH;
+  } catch {
+    return false;
+  }
+}
+
 export function fetchRequestFactory(config: ConfigInterface) {
   return async function fetchRequest(
     url: string,
@@ -16,7 +28,7 @@ export function fetchRequestFactory(config: ConfigInterface) {
       log.debug('Making HTTP request', {
         method: options?.method || 'GET',
         url,
-        ...(options?.body && {body: options?.body}),
+        ...(options?.body && canLogRequestBody(url) && {body: options.body}),
       });
     }
 

package/lib/utils/hmac-validator.ts

@@ -23,8 +23,15 @@ import {
 } from './types';
 
 const HMAC_TIMESTAMP_PERMITTED_CLOCK_TOLERANCE_SEC = 90;
+const APP_PROXY_SINGLE_VALUE_PARAMS = new Set([
+  'hmac',
+  'shop',
+  'signature',
+  'timestamp',
+]);
 
 export type HMACSignator = 'admin' | 'appProxy';
+type HmacQuery = AuthQuery | URLSearchParams;
 
 export interface ValidateParams extends AdapterArgs {
   /**
@@ -63,7 +70,7 @@ export function generateLocalHmac(config: ConfigInterface) {
     params: AuthQuery,
     signator: HMACSignator = 'admin',
   ): Promise<string> => {
-    const {hmac, signature, ...query} = params;
+    const {hmac: _hmac, signature: _signature, ...query} = params;
 
     const queryString =
       signator === 'admin'
@@ -76,30 +83,73 @@ export function generateLocalHmac(config: ConfigInterface) {
 
 export function validateHmac(config: ConfigInterface) {
   return async (
-    query: AuthQuery,
+    query: HmacQuery,
     {signator}: {signator: HMACSignator} = {signator: 'admin'},
   ): Promise<boolean> => {
-    if (signator === 'admin' && !query.hmac) {
+    const normalizedQuery = normalizeQuery(query, signator);
+
+    if (signator === 'admin' && !normalizedQuery.hmac) {
       throw new ShopifyErrors.InvalidHmacError(
         'Query does not contain an HMAC value.',
       );
     }
 
-    if (signator === 'appProxy' && !query.signature) {
+    if (signator === 'appProxy' && !normalizedQuery.signature) {
       throw new ShopifyErrors.InvalidHmacError(
         'Query does not contain a signature value.',
       );
     }
 
-    validateHmacTimestamp(query);
+    validateHmacTimestamp(normalizedQuery);
 
-    const hmac = signator === 'appProxy' ? query.signature : query.hmac;
-    const localHmac = await generateLocalHmac(config)(query, signator);
+    const hmac =
+      signator === 'appProxy'
+        ? normalizedQuery.signature
+        : normalizedQuery.hmac;
+    const localHmac = await generateLocalHmac(config)(
+      normalizedQuery,
+      signator,
+    );
 
     return safeCompare(hmac as string, localHmac);
   };
 }
 
+function normalizeQuery(query: HmacQuery, signator: HMACSignator): AuthQuery {
+  if (!(query instanceof URLSearchParams)) {
+    if (signator === 'appProxy') {
+      for (const key of APP_PROXY_SINGLE_VALUE_PARAMS) {
+        if (Array.isArray(query[key])) {
+          throw new ShopifyErrors.InvalidHmacError(
+            `Query parameter "${key}" must not appear more than once.`,
+          );
+        }
+      }
+    }
+
+    return query;
+  }
+
+  const normalizedQuery = Object.create(null) as AuthQuery;
+  for (const [key, value] of query.entries()) {
+    const existingValue = normalizedQuery[key];
+    if (existingValue === undefined) {
+      normalizedQuery[key] = value;
+    } else if (
+      signator === 'appProxy' &&
+      APP_PROXY_SINGLE_VALUE_PARAMS.has(key)
+    ) {
+      throw new ShopifyErrors.InvalidHmacError(
+        `Query parameter "${key}" must not appear more than once.`,
+      );
+    } else {
+      normalizedQuery[key] = `${existingValue},${value}`;
+    }
+  }
+
+  return normalizedQuery;
+}
+
 export async function validateHmacString(
   config: ConfigInterface,
   data: string,
@@ -151,8 +201,28 @@ export function validateHmacFromRequestFactory(config: ConfigInterface) {
 }
 
 function validateHmacTimestamp(query: AuthQuery) {
+  const {timestamp} = query;
+
+  if (
+    timestamp === undefined ||
+    timestamp === null ||
+    Array.isArray(timestamp)
+  ) {
+    throw new ShopifyErrors.InvalidHmacError(
+      'HMAC timestamp is missing or invalid',
+    );
+  }
+
+  const parsedTimestamp = Number(timestamp);
+
+  if (!Number.isInteger(parsedTimestamp)) {
+    throw new ShopifyErrors.InvalidHmacError(
+      'HMAC timestamp is missing or invalid',
+    );
+  }
+
   if (
-    Math.abs(getCurrentTimeInSec() - Number(query.timestamp)) >
+    Math.abs(getCurrentTimeInSec() - parsedTimestamp) >
     HMAC_TIMESTAMP_PERMITTED_CLOCK_TOLERANCE_SEC
   ) {
     throw new ShopifyErrors.InvalidHmacError(

package/lib/utils/processed-query.ts

@@ -47,7 +47,7 @@ export default class ProcessedQuery {
   }
 
   stringify(omitQuestionMark = false): string {
-    const queryString = this.processedQuery.toString();
+    const queryString = this.processedQuery.toString().replace(/\+/g, '%20');
     return omitQuestionMark ? queryString : `?${queryString}`;
   }
 }

package/lib/version.ts

@@ -1 +1 @@
-export const SHOPIFY_API_LIBRARY_VERSION = '13.1.0';
+export const SHOPIFY_API_LIBRARY_VERSION = '14.0.1';

package/lib/webhooks/process.ts

@@ -143,7 +143,7 @@ async function callWebhookHandlers(
         response,
       });
     }
-    const {webhookId, subTopic} = webhookCheck;
+    const {webhookId} = webhookCheck;
 
     try {
       await handler.callback(
@@ -152,7 +152,6 @@ async function callWebhookHandlers(
         rawBody,
         webhookId,
         webhookCheck.apiVersion,
-        ...(subTopic ? subTopic : ''),
         context,
       );
     } catch (error) {

package/lib/webhooks/register.ts

@@ -414,11 +414,6 @@ function buildMutation(
       params.metafieldNamespaces = JSON.stringify(handler.metafieldNamespaces);
     }
 
-    if (handler.subTopic) {
-      const subTopicString = `subTopic: "${handler.subTopic}",`;
-      mutationArguments.MUTATION_PARAMS = subTopicString;
-    }
-
     const paramsString = Object.entries(params)
       .map(([key, value]) => `${key}: ${value}`)
       .join(', ');

package/lib/webhooks/types.ts

@@ -17,7 +17,6 @@ export const WEBHOOK_HEADER_NAMES = {
     domain: ShopifyHeader.Domain,
     apiVersion: ShopifyHeader.ApiVersion,
     webhookId: ShopifyHeader.WebhookId,
-    subTopic: ShopifyHeader.SubTopic,
     name: ShopifyHeader.Name,
     triggeredAt: ShopifyHeader.TriggeredAt,
     eventId: ShopifyHeader.EventId,
@@ -48,7 +47,6 @@ export type WebhookHandlerFunction = (
   body: string,
   webhookId: string,
   apiVersion?: string,
-  subTopic?: string,
   context?: any,
 ) => Promise<void>;
 
@@ -56,7 +54,6 @@ interface BaseWebhookHandler {
   id?: string;
   includeFields?: string[];
   metafieldNamespaces?: string[];
-  subTopic?: string;
   context?: any;
 }
 
@@ -127,9 +124,7 @@ interface WebhookPubSubEndpoint {
 }
 
 type WebhookEndpoint =
-  | WebhookHttpEndpoint
-  | WebhookEventBridgeEndpoint
-  | WebhookPubSubEndpoint;
+  WebhookHttpEndpoint | WebhookEventBridgeEndpoint | WebhookPubSubEndpoint;
 
 export interface WebhookCheckResponseNode<
   T = {
@@ -185,7 +180,6 @@ interface BaseWebhookFields {
 export interface WebhooksWebhookFields extends BaseWebhookFields {
   webhookType: typeof WebhookType.Webhooks;
   webhookId: string;
-  subTopic?: string;
   name?: string;
   eventId?: string;
 }

package/lib/webhooks/validate.ts

@@ -133,9 +133,6 @@ function checkWebhooksHeaders(
     webhookId: webhookId!,
   };
 
-  const subTopic = getHeader(headers, headerNames.subTopic);
-  if (subTopic) fields.subTopic = subTopic;
-
   const name = getHeader(headers, headerNames.name);
   if (name) fields.name = name;
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shopify/shopify-api",
-  "version": "13.1.0",
+  "version": "14.0.1",
   "description": "Shopify API Library for Node - accelerate development with support for authentication, graphql proxy, webhooks",
   "types": "./dist/ts/lib/index.d.ts",
   "module": "./dist/esm/lib/index.mjs",
   "main": "./dist/cjs/lib/index.js",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "exports": {
     ".": {
@@ -71,24 +71,24 @@
     "Storefront API"
   ],
   "dependencies": {
-    "@shopify/admin-api-client": "^1.1.2",
-    "@shopify/graphql-client": "^1.4.2",
-    "@shopify/storefront-api-client": "^1.0.10",
+    "@shopify/admin-api-client": "^2.0.0",
+    "@shopify/graphql-client": "^2.0.0",
+    "@shopify/storefront-api-client": "^2.0.0",
     "compare-versions": "^6.1.1",
-    "isbot": "^5.1.40",
+    "isbot": "^5.2.0",
     "jose": "^5.9.6",
     "lossless-json": "^4.3.0",
     "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20260605.1",
+    "@cloudflare/workers-types": "^4.20260702.1",
     "@types/express": "^5.0.6",
     "express": "^5.2.1",
     "jest-environment-miniflare": "^2.14.4",
-    "miniflare": "^4.20260601.0",
-    "rollup": "^4.59.0",
+    "miniflare": "^4.20260708.1",
+    "rollup": "^4.62.2",
     "supertest": "^7.2.2",
-    "wrangler": "^4.82.2"
+    "wrangler": "^4.111.0"
   },
   "files": [
     "dist/*",
@@ -112,7 +112,6 @@
     "pretest:adapters": "pnpm rollup -c adapters/__e2etests__/rollup.test-apps.config.js",
     "test:adapters": "jest --selectProjects adapters:mock adapters:node adapters:cf-worker adapters:web-api",
     "test:rest_resources": "jest --selectProjects rest_resources",
-    "lint": "eslint .",
     "test:dev": "jest --selectProjects library",
     "build": "pnpm rollup -c rollup.config.js && pnpm tsc -p ./tsconfig.build.json",
     "tsc": "tsc",