@shopify/shopify-api 12.2.0 → 13.0.0

package/lib/types.ts

@@ -0,0 +1,173 @@
+export enum LogSeverity {
+  Error,
+  Warning,
+  Info,
+  Debug,
+}
+
+export enum ApiVersion {
+  October24 = '2024-10',
+  January25 = '2025-01',
+  April25 = '2025-04',
+  July25 = '2025-07',
+  October25 = '2025-10',
+  January26 = '2026-01',
+  April26 = '2026-04',
+  Unstable = 'unstable',
+}
+
+export const LIBRARY_NAME = 'Shopify API Library';
+
+/* eslint-disable @shopify/typescript-prefer-pascal-case-enums */
+export enum ShopifyHeader {
+  AccessToken = 'X-Shopify-Access-Token',
+  ApiVersion = 'X-Shopify-API-Version',
+  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',
+  EventId = 'X-Shopify-Event-Id',
+  StorefrontPrivateToken = 'Shopify-Storefront-Private-Token',
+  StorefrontSDKVariant = 'X-SDK-Variant',
+  StorefrontSDKVersion = 'X-SDK-Version',
+}
+/* eslint-enable @shopify/typescript-prefer-pascal-case-enums */
+
+export const ShopifyEventsHeader = {
+  Hmac: 'shopify-hmac-sha256',
+  Topic: 'shopify-topic',
+  Domain: 'shopify-shop-domain',
+  ApiVersion: 'shopify-api-version',
+  EventId: 'shopify-event-id',
+  Handle: 'shopify-handle',
+  Action: 'shopify-action',
+  ResourceId: 'shopify-resource-id',
+  TriggeredAt: 'shopify-triggered-at',
+} as const;
+
+export enum ClientType {
+  Rest = 'rest',
+  Graphql = 'graphql',
+}
+
+export const privacyTopics: string[] = [
+  'CUSTOMERS_DATA_REQUEST',
+  'CUSTOMERS_REDACT',
+  'SHOP_REDACT',
+];
+
+export enum BillingInterval {
+  OneTime = 'ONE_TIME',
+  Every30Days = 'EVERY_30_DAYS',
+  Annual = 'ANNUAL',
+  Usage = 'USAGE',
+}
+
+export type RecurringBillingIntervals = Exclude<
+  BillingInterval,
+  BillingInterval.OneTime
+>;
+
+export enum BillingReplacementBehavior {
+  ApplyImmediately = 'APPLY_IMMEDIATELY',
+  ApplyOnNextBillingCycle = 'APPLY_ON_NEXT_BILLING_CYCLE',
+  Standard = 'STANDARD',
+}
+
+export enum StatusCode {
+  Continue = 100,
+  SwitchingProtocols = 101,
+  Ok = 200,
+  Created = 201,
+  Accepted = 202,
+  NonAuthoritativeInformation = 203,
+  NoContent = 204,
+  ResetContent = 205,
+  PartialContent = 206,
+  MultipleChoices = 300,
+  MovedPermanently = 301,
+  Found = 302,
+  SeeOther = 303,
+  NotModified = 304,
+  UseProxy = 305,
+  TemporaryRedirect = 307,
+  BadRequest = 400,
+  Unauthorized = 401,
+  PaymentRequired = 402,
+  Forbidden = 403,
+  NotFound = 404,
+  MethodNotAllowed = 405,
+  NotAcceptable = 406,
+  ProxyAuthenticationRequired = 407,
+  RequestTimeout = 408,
+  Conflict = 409,
+  Gone = 410,
+  LengthRequired = 411,
+  PreconditionFailed = 412,
+  RequestEntityTooLarge = 413,
+  RequestUriTooLong = 414,
+  UnsupportedMediaType = 415,
+  RequestedRangeNotSatisfiable = 416,
+  ExpectationFailed = 417,
+  ImATeapot = 418,
+  UnprocessableEntity = 422,
+  TooManyRequests = 429,
+  InternalServerError = 500,
+  NotImplemented = 501,
+  BadGateway = 502,
+  ServiceUnavailable = 503,
+  GatewayTimeout = 504,
+  HttpVersionNotSupported = 505,
+}
+
+export enum Method {
+  Get = 'GET',
+  Post = 'POST',
+  Put = 'PUT',
+  Patch = 'PATCH',
+  Delete = 'DELETE',
+  Head = 'HEAD',
+  Options = 'OPTIONS',
+  Connect = 'CONNECT',
+}
+
+/**
+ * Configuration for transforming shop domains in split-domain architectures.
+ *
+ * @example
+ * // Template-based transformation
+ * {
+ *   match: /^([a-zA-Z0-9][a-zA-Z0-9-_]*)\.my\.shop\.dev$/,
+ *   transform: '$1.dev-api.shop.dev'
+ * }
+ *
+ * @example
+ * // Function-based transformation
+ * {
+ *   match: /^([^.]+)\.ui\.example\.com$/,
+ *   transform: (matches) => `${matches[1]}.api.example.com`
+ * }
+ */
+export interface DomainTransformation {
+  /**
+   * Pattern to match against shop domains (source domain).
+   * Can be a RegExp or string (converted to RegExp internally).
+   */
+  match: RegExp | string;
+
+  /**
+   * Transformation function or template string.
+   * - Template string: Uses $1, $2, etc. for capture group substitution
+   * - Function: Receives regex match groups and returns transformed domain
+   */
+  transform: ((matches: RegExpMatchArray) => string | null) | string;
+
+  /**
+   * Whether this transformation should also apply to host validation.
+   * @default true
+   */
+  includeHost?: boolean;
+}

package/lib/utils/domain-transformer.ts

@@ -0,0 +1,130 @@
+import {ConfigInterface} from '../base-types';
+import {logger} from '../logger';
+
+/**
+ * Applies configured domain transformations to a shop URL.
+ * Returns transformed domain or original if no transformation matches.
+ *
+ * @param shopUrl - The shop URL to transform
+ * @param config - Configuration object containing domain transformations
+ * @returns Transformed shop URL or original if no transformation matches
+ *
+ * @example
+ * const config = {
+ *   domainTransformations: [{
+ *     match: /^([a-zA-Z0-9-_]+)\.my\.shop\.dev$/,
+ *     transform: '$1.dev-api.shop.dev'
+ *   }]
+ * };
+ * applyDomainTransformations('shop1.my.shop.dev', config);
+ * // Returns: 'shop1.dev-api.shop.dev'
+ */
+export function applyDomainTransformations(
+  shopUrl: string,
+  config: ConfigInterface,
+): string | null {
+  if (
+    !config.domainTransformations ||
+    config.domainTransformations.length === 0
+  ) {
+    return shopUrl;
+  }
+
+  for (const transformation of config.domainTransformations) {
+    const regex =
+      typeof transformation.match === 'string'
+        ? new RegExp(transformation.match)
+        : transformation.match;
+
+    const matches = shopUrl.match(regex);
+
+    if (!matches) {
+      continue;
+    }
+
+    if (typeof transformation.transform === 'function') {
+      return transformation.transform(matches);
+    }
+
+    let result = transformation.transform;
+    matches.forEach((match, index) => {
+      result = result.replace(new RegExp(`\\$${index}`, 'g'), match || '');
+    });
+
+    return result;
+  }
+
+  return shopUrl;
+}
+
+/**
+ * Extracts all domains (source and target) from transformations for validation.
+ * Uses heuristics to extract domain patterns from regex source.
+ *
+ * **Supported regex patterns:**
+ * - Simple literal domains with escaped dots: `\.example\.com`
+ * - Patterns with anchors: `^([a-zA-Z0-9-_]+)\.example\.com$`
+ * - Character classes in subdomains: `^[a-z0-9-]+\.example\.com$`
+ *
+ * **Unsupported regex patterns:**
+ * - Optional groups: `(\.staging)?\.example\.com$` - May not extract correctly
+ * - Character classes in domain part: `\.api[0-9]\.example\.com$` - May not extract correctly
+ * - Complex alternations: `\.(dev|staging)\.example\.com$` - May not extract correctly
+ * - Nested groups in domain part - May not extract correctly
+ *
+ * When using unsupported patterns, domain extraction will fail and be logged at debug level.
+ *
+ * @param config - Configuration object containing domain transformations
+ * @returns Array of domain regex patterns
+ *
+ * @example
+ * const config = {
+ *   domainTransformations: [{
+ *     match: /^([a-zA-Z0-9-_]+)\.my\.shop\.dev$/,
+ *     transform: '$1.dev-api.shop.dev'
+ *   }]
+ * };
+ * getTransformationDomains(config);
+ * // Returns: ['my\\.shop\\.dev', 'dev-api\\.shop\\.dev']
+ */
+export function getTransformationDomains(config: ConfigInterface): string[] {
+  const domains: string[] = [];
+  const log = logger(config);
+
+  if (!config.domainTransformations) {
+    return domains;
+  }
+
+  const transformations = config.domainTransformations;
+
+  for (const transformation of transformations) {
+    const regex =
+      typeof transformation.match === 'string'
+        ? new RegExp(transformation.match)
+        : transformation.match;
+
+    const domainPattern = regex.source.match(/\\\.([\\.\w-]+)\$?$/);
+
+    if (domainPattern) {
+      domains.push(domainPattern[1]);
+    } else {
+      log.debug(
+        `Failed to extract domain pattern from regex: ${regex.source}. This may indicate an unsupported regex pattern (e.g., optional groups, character classes in domain part, complex alternations).`,
+      );
+    }
+
+    if (typeof transformation.transform !== 'string') {
+      continue;
+    }
+
+    const templateDomainMatch =
+      transformation.transform.match(/\$\d+\.([.\w-]+)$/);
+
+    if (templateDomainMatch) {
+      const escapedDomain = templateDomainMatch[1].replace(/\./g, '\\.');
+      domains.push(escapedDomain);
+    }
+  }
+
+  return domains;
+}

package/lib/utils/fetch-request.ts

@@ -0,0 +1,35 @@
+import {logger} from '../logger';
+import {LogSeverity} from '../types';
+import {abstractFetch} from '../../runtime';
+import {ConfigInterface} from '../base-types';
+
+export function fetchRequestFactory(config: ConfigInterface) {
+  return async function fetchRequest(
+    url: string,
+    options?: RequestInit,
+  ): Promise<Response> {
+    const log = logger(config);
+    const doLog =
+      config.logger.httpRequests && config.logger.level === LogSeverity.Debug;
+
+    if (doLog) {
+      log.debug('Making HTTP request', {
+        method: options?.method || 'GET',
+        url,
+        ...(options?.body && {body: options?.body}),
+      });
+    }
+
+    const response = await abstractFetch(url, options);
+
+    if (doLog) {
+      log.debug('HTTP request completed', {
+        method: options?.method || 'GET',
+        url,
+        status: response.status,
+      });
+    }
+
+    return response;
+  };
+}

package/lib/utils/get-hmac-key.ts

@@ -0,0 +1,8 @@
+export function getHMACKey(key: string): Uint8Array {
+  const arrayBuffer = new Uint8Array(key.length);
+  for (let i = 0, keyLen = key.length; i < keyLen; i++) {
+    arrayBuffer[i] = key.charCodeAt(i);
+  }
+
+  return arrayBuffer;
+}

package/lib/utils/hmac-validator.ts

@@ -0,0 +1,188 @@
+import {logger} from '../logger';
+import {ShopifyHeader} from '../types';
+import {
+  AdapterArgs,
+  abstractConvertRequest,
+  getHeader,
+} from '../../runtime/http';
+import {ConfigInterface} from '../base-types';
+import {createSHA256HMAC} from '../../runtime/crypto';
+import {HashFormat} from '../../runtime/crypto/types';
+import {AuthQuery} from '../auth/oauth/types';
+import * as ShopifyErrors from '../error';
+import {safeCompare} from '../auth/oauth/safe-compare';
+import {WEBHOOK_HEADER_NAMES, WebhookTypeValue} from '../webhooks/types';
+
+import ProcessedQuery from './processed-query';
+import {
+  ValidationErrorReason,
+  ValidationInvalid,
+  HmacValidationType,
+  ValidationValid,
+  ValidationErrorReasonType,
+} from './types';
+
+const HMAC_TIMESTAMP_PERMITTED_CLOCK_TOLERANCE_SEC = 90;
+
+export type HMACSignator = 'admin' | 'appProxy';
+
+export interface ValidateParams extends AdapterArgs {
+  /**
+   * The type of validation to perform, either 'flow' or 'webhook'.
+   */
+  type: HmacValidationType;
+  /**
+   * The raw body of the request.
+   */
+  rawBody: string;
+  /**
+   * The webhook type for header selection (optional, only for webhooks).
+   */
+  webhookType?: WebhookTypeValue;
+}
+
+function stringifyQueryForAdmin(query: AuthQuery): string {
+  const processedQuery = new ProcessedQuery();
+  Object.keys(query)
+    .sort((val1, val2) => val1.localeCompare(val2))
+    .forEach((key: string) => processedQuery.put(key, query[key]));
+
+  return processedQuery.stringify(true);
+}
+
+function stringifyQueryForAppProxy(query: AuthQuery): string {
+  return Object.entries(query)
+    .sort(([val1], [val2]) => val1.localeCompare(val2))
+    .reduce((acc, [key, value]) => {
+      return `${acc}${key}=${Array.isArray(value) ? value.join(',') : value}`;
+    }, '');
+}
+
+export function generateLocalHmac(config: ConfigInterface) {
+  return async (
+    params: AuthQuery,
+    signator: HMACSignator = 'admin',
+  ): Promise<string> => {
+    const {hmac, signature, ...query} = params;
+
+    const queryString =
+      signator === 'admin'
+        ? stringifyQueryForAdmin(query)
+        : stringifyQueryForAppProxy(query);
+
+    return createSHA256HMAC(config.apiSecretKey, queryString, HashFormat.Hex);
+  };
+}
+
+export function validateHmac(config: ConfigInterface) {
+  return async (
+    query: AuthQuery,
+    {signator}: {signator: HMACSignator} = {signator: 'admin'},
+  ): Promise<boolean> => {
+    if (signator === 'admin' && !query.hmac) {
+      throw new ShopifyErrors.InvalidHmacError(
+        'Query does not contain an HMAC value.',
+      );
+    }
+
+    if (signator === 'appProxy' && !query.signature) {
+      throw new ShopifyErrors.InvalidHmacError(
+        'Query does not contain a signature value.',
+      );
+    }
+
+    validateHmacTimestamp(query);
+
+    const hmac = signator === 'appProxy' ? query.signature : query.hmac;
+    const localHmac = await generateLocalHmac(config)(query, signator);
+
+    return safeCompare(hmac as string, localHmac);
+  };
+}
+
+export async function validateHmacString(
+  config: ConfigInterface,
+  data: string,
+  hmac: string,
+  format: HashFormat,
+) {
+  const localHmac = await createSHA256HMAC(config.apiSecretKey, data, format);
+
+  return safeCompare(hmac, localHmac);
+}
+
+export function getCurrentTimeInSec() {
+  return Math.trunc(Date.now() / 1000);
+}
+
+export function validateHmacFromRequestFactory(config: ConfigInterface) {
+  return async function validateHmacFromRequest({
+    type,
+    rawBody,
+    webhookType,
+    ...adapterArgs
+  }: ValidateParams): Promise<ValidationInvalid | ValidationValid> {
+    const request = await abstractConvertRequest(adapterArgs);
+    if (!rawBody.length) {
+      return fail(ValidationErrorReason.MissingBody, type, config);
+    }
+
+    // Use appropriate header based on webhook type
+    const hmacHeaderName = webhookType
+      ? WEBHOOK_HEADER_NAMES[webhookType].hmac
+      : ShopifyHeader.Hmac;
+
+    const hmac = getHeader(request.headers, hmacHeaderName);
+    if (!hmac) {
+      return fail(ValidationErrorReason.MissingHmac, type, config);
+    }
+    const validHmac = await validateHmacString(
+      config,
+      rawBody,
+      hmac,
+      HashFormat.Base64,
+    );
+    if (!validHmac) {
+      return fail(ValidationErrorReason.InvalidHmac, type, config);
+    }
+
+    return succeed(type, config);
+  };
+}
+
+function validateHmacTimestamp(query: AuthQuery) {
+  if (
+    Math.abs(getCurrentTimeInSec() - Number(query.timestamp)) >
+    HMAC_TIMESTAMP_PERMITTED_CLOCK_TOLERANCE_SEC
+  ) {
+    throw new ShopifyErrors.InvalidHmacError(
+      'HMAC timestamp is outside of the tolerance range',
+    );
+  }
+}
+
+async function fail(
+  reason: ValidationErrorReasonType,
+  type: HmacValidationType,
+  config: ConfigInterface,
+): Promise<ValidationInvalid> {
+  const log = logger(config);
+  await log.debug(`${type} request is not valid`, {reason});
+
+  return {
+    valid: false,
+    reason,
+  };
+}
+
+async function succeed(
+  type: HmacValidationType,
+  config: ConfigInterface,
+): Promise<ValidationValid> {
+  const log = logger(config);
+  await log.debug(`${type} request is valid`);
+
+  return {
+    valid: true,
+  };
+}

package/lib/utils/index.ts

@@ -0,0 +1,23 @@
+import {ConfigInterface} from '../base-types';
+
+import {sanitizeShop, sanitizeHost} from './shop-validator';
+import {validateHmac} from './hmac-validator';
+import {versionCompatible, versionPriorTo} from './version-compatible';
+import {
+  shopAdminUrlToLegacyUrl,
+  legacyUrlToShopAdminUrl,
+} from './shop-admin-url-helper';
+
+export function shopifyUtils(config: ConfigInterface) {
+  return {
+    sanitizeShop: sanitizeShop(config),
+    sanitizeHost: sanitizeHost(config),
+    validateHmac: validateHmac(config),
+    versionCompatible: versionCompatible(config),
+    versionPriorTo: versionPriorTo(config),
+    shopAdminUrlToLegacyUrl,
+    legacyUrlToShopAdminUrl,
+  };
+}
+
+export type ShopifyUtils = ReturnType<typeof shopifyUtils>;

package/lib/utils/processed-query.ts

@@ -0,0 +1,53 @@
+export default class ProcessedQuery {
+  static stringify(keyValuePairs?: Record<string, any>): string {
+    if (!keyValuePairs || Object.keys(keyValuePairs).length === 0) return '';
+
+    return new ProcessedQuery().putAll(keyValuePairs).stringify();
+  }
+
+  processedQuery: URLSearchParams;
+
+  constructor() {
+    this.processedQuery = new URLSearchParams();
+  }
+
+  putAll(keyValuePairs: Record<string, any>): ProcessedQuery {
+    Object.entries(keyValuePairs).forEach(([key, value]: [string, any]) =>
+      this.put(key, value),
+    );
+    return this;
+  }
+
+  put(key: string, value: any): void {
+    if (Array.isArray(value)) {
+      this.putArray(key, value);
+    } else if (value?.constructor === Object) {
+      this.putObject(key, value);
+    } else {
+      this.putSimple(key, value);
+    }
+  }
+
+  putArray(key: string, value: (string | number)[]): void {
+    value.forEach((arrayValue) =>
+      this.processedQuery.append(`${key}[]`, `${arrayValue}`),
+    );
+  }
+
+  putObject(key: string, value: object): void {
+    Object.entries(value).forEach(
+      ([entry, entryValue]: [string, string | number]) => {
+        this.processedQuery.append(`${key}[${entry}]`, `${entryValue}`);
+      },
+    );
+  }
+
+  putSimple(key: string, value: string | number): void {
+    this.processedQuery.append(key, `${value}`);
+  }
+
+  stringify(omitQuestionMark = false): string {
+    const queryString = this.processedQuery.toString();
+    return omitQuestionMark ? queryString : `?${queryString}`;
+  }
+}