@shopify/shopify-api 12.2.0 → 13.0.0

package/lib/config.ts

@@ -0,0 +1,131 @@
+import {ShopifyError} from './error';
+import {ConfigInterface, ConfigParams} from './base-types';
+import {LogSeverity} from './types';
+import {AuthScopes} from './auth/scopes';
+import {logger as createLogger} from './logger';
+
+export function validateConfig<Params extends ConfigParams>(
+  params: Params,
+): ConfigInterface<Params> {
+  const config = {
+    apiKey: '',
+    apiSecretKey: '',
+    hostName: '',
+    hostScheme: 'https',
+    isEmbeddedApp: true,
+    isCustomStoreApp: false,
+    logger: {
+      log: defaultLogFunction,
+      level: LogSeverity.Info,
+      httpRequests: false,
+      timestamps: false,
+    },
+    future: {},
+    _logDisabledFutureFlags: true,
+  } as ConfigInterface<Params>;
+
+  // Make sure that the essential params actually have content in them
+  const mandatory: (keyof Params)[] = [
+    'apiSecretKey',
+    'hostName',
+    'apiVersion',
+  ];
+  if (!('isCustomStoreApp' in params) || !params.isCustomStoreApp) {
+    mandatory.push('apiKey');
+  }
+  if ('isCustomStoreApp' in params && params.isCustomStoreApp) {
+    if (
+      !('adminApiAccessToken' in params) ||
+      params.adminApiAccessToken?.length === 0
+    ) {
+      mandatory.push('adminApiAccessToken');
+    }
+  }
+
+  const missing: (keyof Params)[] = [];
+  mandatory.forEach((key) => {
+    if (!notEmpty(params[key])) {
+      missing.push(key);
+    }
+  });
+
+  if (missing.length) {
+    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.`,
+    );
+  }
+
+  const {
+    hostScheme,
+    isCustomStoreApp,
+    adminApiAccessToken,
+    userAgentPrefix,
+    logger,
+    privateAppStorefrontAccessToken,
+    billing,
+    future,
+    ...mandatoryParams
+  } = params;
+
+  let scopes;
+  if (params.scopes === undefined) {
+    scopes = undefined;
+  } else if (params.scopes instanceof AuthScopes) {
+    scopes = params.scopes;
+  } else {
+    scopes = new AuthScopes(params.scopes);
+  }
+
+  Object.assign(config, mandatoryParams, {
+    hostName: params.hostName.replace(/\/$/, ''),
+    scopes,
+    hostScheme: hostScheme ?? config.hostScheme,
+    isCustomStoreApp: isCustomStoreApp ?? config.isCustomStoreApp,
+    adminApiAccessToken: adminApiAccessToken ?? config.adminApiAccessToken,
+    userAgentPrefix: userAgentPrefix ?? config.userAgentPrefix,
+    logger: {...config.logger, ...(logger || {})},
+    privateAppStorefrontAccessToken:
+      privateAppStorefrontAccessToken ?? config.privateAppStorefrontAccessToken,
+    billing: billing ?? config.billing,
+    future: future ?? config.future,
+  });
+
+  if (
+    config.isCustomStoreApp &&
+    params.adminApiAccessToken === params.apiSecretKey
+  ) {
+    createLogger(config).warning(
+      "adminApiAccessToken is set to the same value as apiSecretKey. adminApiAccessToken should be set to the Admin API access token for custom store apps; apiSecretKey should be set to the custom store app's API secret key.",
+    );
+  }
+
+  return config;
+}
+
+function notEmpty<T>(value: T): value is NonNullable<T> {
+  if (value == null) {
+    return false;
+  }
+  return typeof value === 'string' || Array.isArray(value)
+    ? value.length > 0
+    : true;
+}
+
+function defaultLogFunction(severity: LogSeverity, message: string): void {
+  switch (severity) {
+    case LogSeverity.Debug:
+      console.debug(message);
+      break;
+    case LogSeverity.Info:
+      console.log(message);
+      break;
+    case LogSeverity.Warning:
+      console.warn(message);
+      break;
+    case LogSeverity.Error:
+      console.error(message);
+      break;
+  }
+}

package/lib/error.ts

@@ -0,0 +1,128 @@
+import {AdapterResponse} from '../runtime/http/types';
+
+export class ShopifyError extends Error {
+  constructor(message?: string) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class InvalidHmacError extends ShopifyError {}
+export class InvalidShopError extends ShopifyError {}
+export class InvalidHostError extends ShopifyError {}
+export class InvalidJwtError extends ShopifyError {}
+export class MissingJwtTokenError extends ShopifyError {}
+export class InvalidDeliveryMethodError extends ShopifyError {}
+
+export class SafeCompareError extends ShopifyError {}
+export class PrivateAppError extends ShopifyError {}
+
+export class HttpRequestError extends ShopifyError {}
+export class HttpMaxRetriesError extends ShopifyError {}
+
+interface HttpResponseData {
+  code: number;
+  statusText: string;
+  body?: Record<string, unknown>;
+  headers?: Record<string, unknown>;
+}
+
+interface HttpResponseErrorParams extends HttpResponseData {
+  message: string;
+}
+export class HttpResponseError<
+  ResponseType extends HttpResponseData = HttpResponseData,
+> extends ShopifyError {
+  readonly response: ResponseType;
+
+  constructor({
+    message,
+    code,
+    statusText,
+    body,
+    headers,
+  }: HttpResponseErrorParams) {
+    super(message);
+    this.response = {
+      code,
+      statusText,
+      body,
+      headers,
+    } as ResponseType;
+  }
+}
+export class HttpRetriableError<
+  ResponseType extends HttpResponseData = HttpResponseData,
+> extends HttpResponseError<ResponseType> {}
+export class HttpInternalError extends HttpRetriableError {}
+
+interface HttpThrottlingErrorData extends HttpResponseData {
+  retryAfter?: number;
+}
+interface HttpThrottlingErrorParams extends HttpThrottlingErrorData {
+  message: string;
+}
+export class HttpThrottlingError extends HttpRetriableError<HttpThrottlingErrorData> {
+  constructor({retryAfter, ...params}: HttpThrottlingErrorParams) {
+    super(params);
+    this.response.retryAfter = retryAfter;
+  }
+}
+
+export class RestResourceError extends ShopifyError {}
+
+interface GraphqlQueryErrorParams {
+  message: string;
+  response: Record<string, unknown>;
+  headers?: Record<string, unknown>;
+  body?: Record<string, any>;
+}
+
+export class GraphqlQueryError extends ShopifyError {
+  readonly response: Record<string, unknown>;
+  readonly headers?: Record<string, unknown>;
+  readonly body?: Record<string, any>;
+
+  constructor({message, response, headers, body}: GraphqlQueryErrorParams) {
+    super(message);
+    this.response = response;
+    this.headers = headers;
+    this.body = body;
+  }
+}
+
+export class InvalidOAuthError extends ShopifyError {}
+export class BotActivityDetected extends ShopifyError {}
+export class CookieNotFound extends ShopifyError {}
+export class InvalidSession extends ShopifyError {}
+
+interface InvalidWebhookParams {
+  message: string;
+  response: AdapterResponse;
+}
+export class InvalidWebhookError extends ShopifyError {
+  readonly response: AdapterResponse;
+
+  constructor({message, response}: InvalidWebhookParams) {
+    super(message);
+    this.response = response;
+  }
+}
+export class MissingWebhookCallbackError extends InvalidWebhookError {}
+export class SessionStorageError extends ShopifyError {}
+export class MissingRequiredArgument extends ShopifyError {}
+export class UnsupportedClientType extends ShopifyError {}
+export class InvalidRequestError extends ShopifyError {}
+interface BillingErrorParams {
+  message: string;
+  errorData: any;
+}
+export class BillingError extends ShopifyError {
+  readonly errorData: any;
+
+  constructor({message, errorData}: BillingErrorParams) {
+    super(message);
+    this.errorData = errorData;
+  }
+}
+export class FeatureDeprecatedError extends ShopifyError {}

package/lib/flow/index.ts

@@ -0,0 +1,11 @@
+import {ConfigInterface} from '../base-types';
+
+import {validateFactory} from './validate';
+
+export function shopifyFlow(config: ConfigInterface) {
+  return {
+    validate: validateFactory(config),
+  };
+}
+
+export type ShopifyFlow = ReturnType<typeof shopifyFlow>;

package/lib/flow/validate.ts

@@ -0,0 +1,21 @@
+import {
+  HmacValidationType,
+  ValidationInvalid,
+  ValidationValid,
+  ValidateParams,
+} from '../utils/types';
+import {validateHmacFromRequestFactory} from '../utils/hmac-validator';
+import {ConfigInterface} from '../base-types';
+
+export function validateFactory(config: ConfigInterface) {
+  return async function validate({
+    rawBody,
+    ...adapterArgs
+  }: ValidateParams): Promise<ValidationInvalid | ValidationValid> {
+    return validateHmacFromRequestFactory(config)({
+      type: HmacValidationType.Flow,
+      rawBody,
+      ...adapterArgs,
+    });
+  };
+}

package/lib/fulfillment-service/index.ts

@@ -0,0 +1,11 @@
+import {ConfigInterface} from '../base-types';
+
+import {validateFactory} from './validate';
+
+export function fulfillmentService(config: ConfigInterface) {
+  return {
+    validate: validateFactory(config),
+  };
+}
+
+export type FulfillmentService = ReturnType<typeof fulfillmentService>;

package/lib/fulfillment-service/validate.ts

@@ -0,0 +1,21 @@
+import {ConfigInterface} from '../base-types';
+import {validateHmacFromRequestFactory} from '../utils/hmac-validator';
+import {
+  HmacValidationType,
+  ValidateParams,
+  ValidationInvalid,
+  ValidationValid,
+} from '../utils/types';
+
+export function validateFactory(config: ConfigInterface) {
+  return async function validate({
+    rawBody,
+    ...adapterArgs
+  }: ValidateParams): Promise<ValidationInvalid | ValidationValid> {
+    return validateHmacFromRequestFactory(config)({
+      type: HmacValidationType.FulfillmentService,
+      rawBody,
+      ...adapterArgs,
+    });
+  };
+}

package/lib/index.ts

@@ -0,0 +1,109 @@
+import {loadRestResources} from '../rest/load-rest-resources';
+import {ShopifyRestResources} from '../rest/types';
+import {abstractRuntimeString} from '../runtime/platform';
+import {FutureFlagOptions, logDisabledFutureFlags} from '../future/flags';
+
+import {ConfigParams, ConfigInterface} from './base-types';
+import {validateConfig} from './config';
+import {clientClasses, ShopifyClients} from './clients';
+import {shopifyAuth, ShopifyAuth} from './auth';
+import {shopifySession, ShopifySession} from './session';
+import {shopifyUtils, ShopifyUtils} from './utils';
+import {shopifyWebhooks, ShopifyWebhooks} from './webhooks';
+import {shopifyBilling, ShopifyBilling} from './billing';
+import {logger, ShopifyLogger} from './logger';
+import {SHOPIFY_API_LIBRARY_VERSION} from './version';
+import {restClientClass} from './clients/admin/rest/client';
+import {ShopifyFlow, shopifyFlow} from './flow';
+import {FulfillmentService, fulfillmentService} from './fulfillment-service';
+
+export * from './error';
+export * from './session/classes';
+
+export * from '../rest/types';
+export * from './types';
+export * from './base-types';
+export * from './auth/types';
+export * from './billing/types';
+export * from './clients/types';
+export * from './session/types';
+export * from './webhooks/types';
+export * from './utils/types';
+
+export interface Shopify<
+  Params extends ConfigParams = ConfigParams,
+  Resources extends ShopifyRestResources = ShopifyRestResources,
+  Future extends FutureFlagOptions = FutureFlagOptions,
+> {
+  config: ConfigInterface<Params>;
+  clients: ShopifyClients;
+  auth: ShopifyAuth;
+  session: ShopifySession;
+  utils: ShopifyUtils;
+
+  /**
+   * Functions for working with webhooks.
+   *
+   * Most of these functions are used for interacting with shop-specific webhooks.
+   * Unless your app needs different webhooks for different shops, we recommend using app-specific webhooks instead:
+   *
+   * {@link https://shopify.dev/docs/apps/build/webhooks/subscribe#app-specific-subscriptions}
+   *
+   * If you use only app-specific webhooks, the only function you will need is `shopify.webhooks.validate`.
+   */
+  webhooks: ShopifyWebhooks;
+  billing: ShopifyBilling<Future>;
+  logger: ShopifyLogger;
+  rest: Resources;
+  flow: ShopifyFlow;
+  fulfillmentService: FulfillmentService;
+}
+
+export function shopifyApi<
+  Params extends ConfigParams<Resources, Future>,
+  Resources extends ShopifyRestResources,
+  Future extends FutureFlagOptions,
+>({
+  future,
+  restResources,
+  ...config
+}: {future?: Future; restResources?: Resources} & Params): Shopify<
+  Params,
+  Resources,
+  Future
+> {
+  const libConfig = {...config, future, restResources};
+  const validatedConfig = validateConfig(libConfig);
+
+  const shopify = {
+    config: validatedConfig,
+    clients: clientClasses(validatedConfig),
+    auth: shopifyAuth(validatedConfig),
+    session: shopifySession(validatedConfig),
+    utils: shopifyUtils(validatedConfig),
+    webhooks: shopifyWebhooks(validatedConfig),
+    billing: shopifyBilling(validatedConfig),
+    flow: shopifyFlow(validatedConfig),
+    fulfillmentService: fulfillmentService(validatedConfig),
+    logger: logger(validatedConfig),
+    rest: {} as Resources,
+  };
+
+  if (restResources) {
+    shopify.rest = loadRestResources({
+      resources: restResources,
+      config: validatedConfig,
+      RestClient: restClientClass({config: validatedConfig}),
+    });
+  }
+
+  shopify.logger
+    .info(
+      `version ${SHOPIFY_API_LIBRARY_VERSION}, environment ${abstractRuntimeString()}`,
+    )
+    .catch((err) => console.log(err));
+
+  logDisabledFutureFlags(validatedConfig, shopify.logger);
+
+  return shopify as Shopify<Params, Resources, Future>;
+}

package/lib/logger/index.ts

@@ -0,0 +1,43 @@
+import {compare} from 'compare-versions';
+
+import {LogSeverity} from '../types';
+import {ConfigInterface} from '../base-types';
+import {FeatureDeprecatedError} from '../error';
+import {SHOPIFY_API_LIBRARY_VERSION} from '../version';
+
+import {log, LoggerFunction} from './log';
+import {LogContext} from './types';
+
+export function logger(config: ConfigInterface) {
+  const logFunction = log(config);
+
+  return {
+    log: logFunction,
+    debug: async (message: string, context: LogContext = {}) =>
+      logFunction(LogSeverity.Debug, message, context),
+    info: async (message: string, context: LogContext = {}) =>
+      logFunction(LogSeverity.Info, message, context),
+    warning: async (message: string, context: LogContext = {}) =>
+      logFunction(LogSeverity.Warning, message, context),
+    error: async (message: string, context: LogContext = {}) =>
+      logFunction(LogSeverity.Error, message, context),
+    deprecated: deprecated(logFunction),
+  };
+}
+
+export type ShopifyLogger = ReturnType<typeof logger>;
+
+function deprecated(logFunction: LoggerFunction) {
+  return function (version: string, message: string): void {
+    if (compare(SHOPIFY_API_LIBRARY_VERSION, version, '>=')) {
+      throw new FeatureDeprecatedError(
+        `Feature was deprecated in version ${version}`,
+      );
+    }
+
+    return logFunction(
+      LogSeverity.Warning,
+      `[Deprecated | ${version}] ${message}`,
+    );
+  };
+}

package/lib/logger/log.ts

@@ -0,0 +1,60 @@
+import {LogSeverity} from '../types';
+import {ConfigInterface} from '../base-types';
+
+import {LogContext} from './types';
+
+export type LoggerFunction = (
+  severity: LogSeverity,
+  message: string,
+  context?: Record<string, any>,
+) => void;
+
+export function log(config: ConfigInterface): LoggerFunction {
+  return function (
+    severity: LogSeverity,
+    message: string,
+    context: LogContext = {},
+  ): void {
+    if (severity > config.logger.level) {
+      return;
+    }
+
+    const prefix: string[] = [];
+
+    if (config.logger.timestamps) {
+      prefix.push(`${new Date().toISOString().slice(0, -5)}Z`);
+    }
+
+    let packageString = context.package || 'shopify-api';
+    delete context.package;
+
+    switch (severity) {
+      case LogSeverity.Debug:
+        packageString = `${packageString}/DEBUG`;
+        break;
+      case LogSeverity.Info:
+        packageString = `${packageString}/INFO`;
+        break;
+      case LogSeverity.Warning:
+        packageString = `${packageString}/WARNING`;
+        break;
+      case LogSeverity.Error:
+        packageString = `${packageString}/ERROR`;
+        break;
+    }
+
+    prefix.push(packageString);
+
+    const contextParts: string[] = [];
+    Object.entries(context).forEach(([key, value]) => {
+      contextParts.push(`${key}: ${value}`);
+    });
+
+    let suffix = '';
+    if (contextParts.length > 0) {
+      suffix = ` | {${contextParts.join(', ')}}`;
+    }
+
+    config.logger.log(severity, `[${prefix.join('] [')}] ${message}${suffix}`);
+  };
+}

package/lib/logger/types.ts

@@ -0,0 +1 @@
+export type LogContext = Record<string, any>;

package/lib/session/classes.ts

@@ -0,0 +1 @@
+export {Session} from './session';

package/lib/session/decode-session-token.ts

@@ -0,0 +1,44 @@
+import * as jose from 'jose';
+
+import {ConfigInterface} from '../base-types';
+import * as ShopifyErrors from '../error';
+import {getHMACKey} from '../utils/get-hmac-key';
+
+import {JwtPayload} from './types';
+
+const JWT_PERMITTED_CLOCK_TOLERANCE = 10;
+
+export interface DecodeSessionTokenOptions {
+  checkAudience?: boolean;
+}
+
+export function decodeSessionToken(config: ConfigInterface) {
+  return async (
+    token: string,
+    {checkAudience = true}: DecodeSessionTokenOptions = {},
+  ): Promise<JwtPayload> => {
+    let payload: JwtPayload;
+    try {
+      payload = (
+        await jose.jwtVerify(token, getHMACKey(config.apiSecretKey), {
+          algorithms: ['HS256'],
+          clockTolerance: JWT_PERMITTED_CLOCK_TOLERANCE,
+        })
+      ).payload as unknown as JwtPayload;
+    } catch (error) {
+      throw new ShopifyErrors.InvalidJwtError(
+        `Failed to parse session token '${token}': ${error.message}`,
+      );
+    }
+
+    // The exp and nbf fields are validated by the JWT library
+
+    if (checkAudience && payload.aud !== config.apiKey) {
+      throw new ShopifyErrors.InvalidJwtError(
+        'Session token had invalid API key',
+      );
+    }
+
+    return payload;
+  };
+}

package/lib/session/index.ts

@@ -0,0 +1,21 @@
+import {ConfigInterface} from '../base-types';
+
+import {decodeSessionToken} from './decode-session-token';
+import {
+  customAppSession,
+  getCurrentSessionId,
+  getJwtSessionId,
+  getOfflineId,
+} from './session-utils';
+
+export function shopifySession(config: ConfigInterface) {
+  return {
+    customAppSession: customAppSession(config),
+    getCurrentId: getCurrentSessionId(config),
+    getOfflineId: getOfflineId(config),
+    getJwtSessionId: getJwtSessionId(config),
+    decodeSessionToken: decodeSessionToken(config),
+  };
+}
+
+export type ShopifySession = ReturnType<typeof shopifySession>;