@shopify/shopify-api 12.2.0 → 13.0.0

package/lib/clients/admin/types.ts

@@ -0,0 +1,37 @@
+import {ClientResponse, SearchParams} from '@shopify/admin-api-client';
+
+import {ApiVersion} from '../../types';
+import {Session} from '../../session/session';
+import {Headers} from '../../../runtime';
+
+export interface PageInfoParams {
+  path: string;
+  query: SearchParams;
+}
+
+export interface PageInfo {
+  limit: string;
+  fields?: string[];
+  previousPageUrl?: string;
+  nextPageUrl?: string;
+  prevPage?: PageInfoParams;
+  nextPage?: PageInfoParams;
+}
+
+export interface RestRequestReturn<T = any> {
+  body: T;
+  headers: Headers;
+  pageInfo?: PageInfo;
+}
+
+export interface RestClientParams {
+  session: Session;
+  apiVersion?: ApiVersion;
+}
+
+export interface GraphQLClientResponse<TData = any> extends Omit<
+  ClientResponse<TData>,
+  'headers'
+> {
+  headers?: Headers;
+}

package/lib/clients/common.ts

@@ -0,0 +1,186 @@
+import {
+  HTTPResponseLog,
+  HTTPRetryLog,
+  HTTPResponseGraphQLDeprecationNotice,
+  LogContent,
+} from '@shopify/admin-api-client';
+
+import * as ShopifyErrors from '../error';
+import {LIBRARY_NAME, StatusCode} from '../types';
+import {ConfigInterface} from '../base-types';
+import {SHOPIFY_API_LIBRARY_VERSION} from '../version';
+import {
+  abstractRuntimeString,
+  canonicalizeHeaders,
+  getHeader,
+} from '../../runtime';
+import {logger} from '../logger';
+
+export function getUserAgent(config: ConfigInterface): string {
+  let userAgentPrefix = `${LIBRARY_NAME} v${SHOPIFY_API_LIBRARY_VERSION} | ${abstractRuntimeString()}`;
+  if (config.userAgentPrefix) {
+    userAgentPrefix = `${config.userAgentPrefix} | ${userAgentPrefix}`;
+  }
+
+  return userAgentPrefix;
+}
+
+function serializeResponse(response: Response | any) {
+  if (!response) {
+    return {error: 'No response object provided'};
+  }
+
+  try {
+    const {status, statusText, ok, redirected, type, url, headers} = response;
+
+    const serialized: any = {
+      status,
+      statusText,
+      ok,
+      redirected,
+      type,
+      url,
+    };
+
+    if (headers?.entries) {
+      serialized.headers = Object.fromEntries(headers.entries());
+    } else if (headers) {
+      serialized.headers = headers;
+    }
+
+    return serialized;
+  } catch {
+    return response;
+  }
+}
+
+export function clientLoggerFactory(config: ConfigInterface) {
+  return (logContent: LogContent) => {
+    if (config.logger.httpRequests) {
+      switch (logContent.type) {
+        case 'HTTP-Response': {
+          const responseLog: HTTPResponseLog['content'] = logContent.content;
+          logger(config).debug('Received response for HTTP request', {
+            requestParams: JSON.stringify(responseLog.requestParams),
+            response: JSON.stringify(serializeResponse(responseLog.response)),
+          });
+          break;
+        }
+        case 'HTTP-Retry': {
+          const responseLog: HTTPRetryLog['content'] = logContent.content;
+          logger(config).debug('Retrying HTTP request', {
+            requestParams: JSON.stringify(responseLog.requestParams),
+            retryAttempt: responseLog.retryAttempt,
+            maxRetries: responseLog.maxRetries,
+            response: responseLog.lastResponse
+              ? JSON.stringify(serializeResponse(responseLog.lastResponse))
+              : 'undefined',
+          });
+          break;
+        }
+        case 'HTTP-Response-GraphQL-Deprecation-Notice': {
+          const responseLog: HTTPResponseGraphQLDeprecationNotice['content'] =
+            logContent.content;
+          logger(config).debug(
+            'Received response containing Deprecated GraphQL Notice',
+            {
+              requestParams: JSON.stringify(responseLog.requestParams),
+              deprecationNotice: responseLog.deprecationNotice,
+            },
+          );
+          break;
+        }
+        default: {
+          logger(config).debug(`HTTP request event: ${logContent.content}`);
+          break;
+        }
+      }
+    }
+  };
+}
+
+export function throwFailedRequest(
+  body: any,
+  atMaxRetries: boolean,
+  response?: Response,
+): never {
+  if (typeof response === 'undefined') {
+    const message = body?.errors?.message ?? '';
+    throw new ShopifyErrors.HttpRequestError(
+      `Http request error, no response available: ${message}`,
+    );
+  }
+
+  const responseHeaders = canonicalizeHeaders(
+    Object.fromEntries(response.headers.entries() ?? []),
+  );
+
+  if (response.status === StatusCode.Ok && body.errors.graphQLErrors) {
+    throw new ShopifyErrors.GraphqlQueryError({
+      message:
+        body.errors.graphQLErrors?.[0].message ?? 'GraphQL operation failed',
+      response: response as Record<string, any>,
+      headers: responseHeaders,
+      body: body as Record<string, any>,
+    });
+  }
+
+  const errorMessages: string[] = [];
+  if (body.errors) {
+    errorMessages.push(JSON.stringify(body.errors, null, 2));
+  }
+  const xRequestId = getHeader(responseHeaders, 'x-request-id');
+  if (xRequestId) {
+    errorMessages.push(
+      `If you report this error, please include this id: ${xRequestId}`,
+    );
+  }
+
+  const errorMessage = errorMessages.length
+    ? `:\n${errorMessages.join('\n')}`
+    : '';
+  const code = response.status;
+  const statusText = response.statusText;
+
+  switch (true) {
+    case response.status === StatusCode.TooManyRequests: {
+      if (atMaxRetries) {
+        throw new ShopifyErrors.HttpMaxRetriesError(
+          'Attempted the maximum number of retries for HTTP request.',
+        );
+      } else {
+        const retryAfter = getHeader(responseHeaders, 'Retry-After');
+        throw new ShopifyErrors.HttpThrottlingError({
+          message: `Shopify is throttling requests ${errorMessage}`,
+          code,
+          statusText,
+          body,
+          headers: responseHeaders,
+          retryAfter: retryAfter ? parseFloat(retryAfter) : undefined,
+        });
+      }
+    }
+    case response.status >= StatusCode.InternalServerError:
+      if (atMaxRetries) {
+        throw new ShopifyErrors.HttpMaxRetriesError(
+          'Attempted the maximum number of retries for HTTP request.',
+        );
+      } else {
+        throw new ShopifyErrors.HttpInternalError({
+          message: `Shopify internal error${errorMessage}`,
+          code,
+          statusText,
+          body,
+          headers: responseHeaders,
+        });
+      }
+    default:
+      throw new ShopifyErrors.HttpResponseError({
+        message: `Received an error response (${response.status} ${response.statusText}) from Shopify${errorMessage}`,
+        code,
+        statusText,
+        body,
+        headers: responseHeaders,
+      });
+  }
+}

package/lib/clients/graphql_proxy/graphql_proxy.ts

@@ -0,0 +1,39 @@
+import {ConfigInterface} from '../../base-types';
+import * as ShopifyErrors from '../../error';
+import {graphqlClientClass} from '../admin';
+
+import {GraphqlProxy} from './types';
+
+export function graphqlProxy(config: ConfigInterface): GraphqlProxy {
+  return async ({session, rawBody}) => {
+    if (!session.accessToken) {
+      throw new ShopifyErrors.InvalidSession(
+        'Cannot proxy query. Session not authenticated.',
+      );
+    }
+
+    const GraphqlClient = graphqlClientClass({config});
+    const client = new GraphqlClient({session});
+
+    if (!rawBody) {
+      throw new ShopifyErrors.MissingRequiredArgument('Query missing.');
+    }
+
+    let query: string;
+    let variables: Record<string, any> | undefined;
+    if (typeof rawBody === 'string') {
+      query = rawBody;
+    } else {
+      query = rawBody.query;
+      variables = rawBody.variables;
+    }
+
+    if (!query) {
+      throw new ShopifyErrors.MissingRequiredArgument('Query missing.');
+    }
+
+    const response = await client.request(query, {variables});
+
+    return {body: response, headers: {}};
+  };
+}

package/lib/clients/graphql_proxy/types.ts

@@ -0,0 +1,11 @@
+import {Session} from '../../session/session';
+import type {RequestReturn} from '../types';
+
+export interface GraphqlProxyParams {
+  session: Session;
+  rawBody: string | Record<string, any>;
+}
+
+export type GraphqlProxy = (
+  params: GraphqlProxyParams,
+) => Promise<RequestReturn>;

package/lib/clients/index.ts

@@ -0,0 +1,18 @@
+import {ConfigInterface} from '../base-types';
+
+import {restClientClass, graphqlClientClass} from './admin';
+import {storefrontClientClass} from './storefront';
+import {graphqlProxy} from './graphql_proxy/graphql_proxy';
+import {ShopifyClients} from './types';
+
+export type {ShopifyClients} from './types';
+
+export function clientClasses(config: ConfigInterface): ShopifyClients {
+  return {
+    // We don't pass in the HttpClient because the RestClient inherits from it, and goes through the same setup process
+    Rest: restClientClass({config}),
+    Graphql: graphqlClientClass({config}),
+    Storefront: storefrontClientClass({config}),
+    graphqlProxy: graphqlProxy(config),
+  };
+}

package/lib/clients/storefront/client.ts

@@ -0,0 +1,164 @@
+import {
+  StorefrontApiClient,
+  StorefrontOperations,
+  ClientResponse,
+  createStorefrontApiClient,
+  ReturnData,
+  ApiClientRequestOptions,
+} from '@shopify/storefront-api-client';
+
+import {ApiVersion} from '../../types';
+import {logger} from '../../logger';
+import * as ShopifyErrors from '../../error';
+import {MissingRequiredArgument} from '../../error';
+import type {
+  GraphqlClientParams,
+  GraphqlParams,
+  GraphqlQueryOptions,
+  RequestReturn,
+} from '../types';
+import {ConfigInterface} from '../../base-types';
+import {Session} from '../../session/session';
+import {abstractFetch} from '../../../runtime';
+import {clientLoggerFactory, getUserAgent, throwFailedRequest} from '../common';
+
+interface GraphqlClientClassParams {
+  config: ConfigInterface;
+}
+
+export class StorefrontClient {
+  public static config: ConfigInterface;
+
+  readonly session: Session;
+  readonly client: StorefrontApiClient;
+  readonly apiVersion?: ApiVersion;
+
+  constructor(params: GraphqlClientParams) {
+    const config = this.storefrontClass().config;
+
+    if (!config.isCustomStoreApp && !params.session.accessToken) {
+      throw new ShopifyErrors.MissingRequiredArgument(
+        'Missing access token when creating GraphQL client',
+      );
+    }
+
+    if (params.apiVersion) {
+      const message =
+        params.apiVersion === config.apiVersion
+          ? `Storefront client has a redundant API version override to the default ${params.apiVersion}`
+          : `Storefront client overriding default API version ${config.apiVersion} with ${params.apiVersion}`;
+
+      logger(config).debug(message);
+    }
+
+    let accessToken: string | undefined;
+    if (config.isCustomStoreApp) {
+      accessToken = config.privateAppStorefrontAccessToken;
+
+      if (!accessToken) {
+        throw new MissingRequiredArgument(
+          'Custom store apps must set the privateAppStorefrontAccessToken property to call the Storefront API.',
+        );
+      }
+    } else {
+      accessToken = params.session.accessToken;
+
+      if (!accessToken) {
+        throw new MissingRequiredArgument('Session missing access token.');
+      }
+    }
+
+    this.session = params.session;
+    this.apiVersion = params.apiVersion;
+    this.client = createStorefrontApiClient({
+      privateAccessToken: accessToken,
+      apiVersion: this.apiVersion ?? config.apiVersion,
+      storeDomain: this.session.shop,
+      customFetchApi: abstractFetch,
+      logger: clientLoggerFactory(config),
+      clientName: getUserAgent(config),
+    });
+  }
+
+  public async query<T = undefined>(
+    params: GraphqlParams,
+  ): Promise<RequestReturn<T>> {
+    logger(this.storefrontClass().config).deprecated(
+      '12.0.0',
+      'The query method is deprecated, and was replaced with the request method.\n' +
+        'See the migration guide: https://github.com/Shopify/shopify-app-js/blob/main/packages/apps/shopify-api/docs/migrating-to-v9.md#using-the-new-clients.',
+    );
+
+    if (
+      (typeof params.data === 'string' && params.data.length === 0) ||
+      Object.entries(params.data).length === 0
+    ) {
+      throw new ShopifyErrors.MissingRequiredArgument('Query missing.');
+    }
+
+    let operation: string;
+    let variables: Record<string, any> | undefined;
+    if (typeof params.data === 'string') {
+      operation = params.data;
+    } else {
+      operation = params.data.query;
+      variables = params.data.variables;
+    }
+
+    const headers = Object.fromEntries(
+      Object.entries(params?.extraHeaders ?? {}).map(([key, value]) => [
+        key,
+        Array.isArray(value) ? value.join(', ') : value.toString(),
+      ]),
+    );
+
+    const response = await this.request<T>(operation, {
+      headers,
+      retries: params.tries ? params.tries - 1 : undefined,
+      variables,
+    });
+
+    return {body: response as T, headers: {}};
+  }
+
+  public async request<
+    T = undefined,
+    Operation extends keyof Operations = string,
+    Operations extends StorefrontOperations = StorefrontOperations,
+  >(
+    operation: Operation,
+    options?: GraphqlQueryOptions<Operation, Operations>,
+  ): Promise<
+    ClientResponse<T extends undefined ? ReturnData<Operation, Operations> : T>
+  > {
+    const response = await this.client.request<T, Operation>(operation, {
+      apiVersion: this.apiVersion || this.storefrontClass().config.apiVersion,
+      ...(options as ApiClientRequestOptions<Operation, StorefrontOperations>),
+    });
+
+    if (response.errors) {
+      const fetchResponse = response.errors.response;
+
+      throwFailedRequest(response, (options?.retries ?? 0) > 0, fetchResponse);
+    }
+
+    return response;
+  }
+
+  private storefrontClass() {
+    return this.constructor as typeof StorefrontClient;
+  }
+}
+
+export function storefrontClientClass(params: GraphqlClientClassParams) {
+  const {config} = params;
+  class NewStorefrontClient extends StorefrontClient {
+    public static config = config;
+  }
+
+  Reflect.defineProperty(NewStorefrontClient, 'name', {
+    value: 'StorefrontClient',
+  });
+
+  return NewStorefrontClient as typeof StorefrontClient;
+}

package/lib/clients/storefront/index.ts

@@ -0,0 +1 @@
+export {StorefrontClient, storefrontClientClass} from './client';

package/lib/clients/types.ts

@@ -0,0 +1,126 @@
+import {
+  AllOperations,
+  ApiClientRequestOptions,
+  SearchParams,
+} from '@shopify/admin-api-client';
+
+import {Session} from '../session/session';
+import type {ApiVersion, Method} from '../types';
+import {Headers} from '../../runtime/http';
+
+import {GraphqlClient} from './admin/graphql/client';
+import {StorefrontClient} from './storefront/client';
+import type {GraphqlProxy} from './graphql_proxy/types';
+import {RestClient} from './admin/rest/client';
+
+export * from './admin/types';
+export * from './graphql_proxy/types';
+
+export interface ClientArgs {
+  session: Session;
+  apiVersion?: ApiVersion;
+  retries?: number;
+}
+
+/**
+ * Headers to be sent with the request.
+ */
+export type HeaderParams = Record<string, string | number | string[]>;
+
+/* eslint-disable @shopify/typescript-prefer-pascal-case-enums */
+export enum DataType {
+  JSON = 'application/json',
+  GraphQL = 'application/graphql',
+  URLEncoded = 'application/x-www-form-urlencoded',
+}
+
+/* eslint-enable @shopify/typescript-prefer-pascal-case-enums */
+
+export interface GetRequestParams {
+  /**
+   * The path to the resource, relative to the API version root.
+   */
+  path: string;
+  /**
+   * The type of data expected in the response.
+   */
+  type?: DataType;
+  /**
+   * The request body.
+   */
+  data?: Record<string, any> | string;
+  /**
+   * Query parameters to be sent with the request.
+   */
+  query?: SearchParams;
+  /**
+   * Additional headers to be sent with the request.
+   */
+  extraHeaders?: HeaderParams;
+  /**
+   * The maximum number of times the request can be made if it fails with a throttling or server error.
+   */
+  tries?: number;
+}
+
+export type PostRequestParams = GetRequestParams & {
+  data: Record<string, any> | string;
+};
+
+export type PutRequestParams = PostRequestParams;
+
+export type DeleteRequestParams = GetRequestParams;
+
+export type RequestParams = (GetRequestParams | PostRequestParams) & {
+  method: Method;
+};
+
+export interface RequestReturn<T = unknown> {
+  /**
+   * The response body.
+   */
+  body: T;
+  /**
+   * The response headers.
+   */
+  headers: Headers;
+}
+
+export type GraphqlParams = Omit<PostRequestParams, 'path' | 'type'>;
+
+export interface GraphqlClientParams {
+  session: Session;
+  apiVersion?: ApiVersion;
+}
+
+export interface GraphqlQueryOptions<
+  Operation extends keyof Operations,
+  Operations extends AllOperations,
+> {
+  /**
+   * The variables to include in the operation.
+   */
+  variables?: ApiClientRequestOptions<Operation, Operations>['variables'];
+  /**
+   * Additional headers to be sent with the request.
+   */
+  headers?: Record<string, string | number>;
+  /**
+   * The maximum number of times to retry the request if it fails with a throttling or server error.
+   */
+  retries?: number;
+  /**
+   * An optional AbortSignal to cancel the request.
+   */
+  signal?: AbortSignal;
+}
+
+export {GraphqlClient} from './admin/graphql/client';
+export {RestClient} from './admin/rest/client';
+
+export interface ShopifyClients {
+  Rest: typeof RestClient;
+  Graphql: typeof GraphqlClient;
+  Storefront: typeof StorefrontClient;
+  graphqlProxy: GraphqlProxy;
+}