@shopify/shopify-api 12.3.0 → 13.0.0

package/future/flags.ts

@@ -0,0 +1,58 @@
+import {type ShopifyLogger} from '../lib/logger';
+import {type ConfigInterface} from '../lib/base-types';
+
+/**
+ * Future flags are used to enable features that are not yet available by default.
+ */
+export interface FutureFlags {
+  /**
+   * Enable support for managed pricing, so apps can check for payments without needing a billing config.
+   */
+  unstable_managedPricingSupport?: boolean;
+
+  /**
+   * Change the CustomerAddress classes to expose a `is_default` property instead of `default` when fetching data. This
+   * resolves a conflict with the default() method in that class.
+   */
+  customerAddressDefaultFix?: boolean;
+}
+
+/**
+ * Configuration option for future flags.
+ */
+export type FutureFlagOptions = FutureFlags | undefined;
+
+export type FeatureEnabled<
+  Future extends FutureFlagOptions,
+  Flag extends keyof FutureFlags,
+> = Future extends FutureFlags
+  ? Future[Flag] extends true
+    ? true
+    : false
+  : false;
+
+export function logDisabledFutureFlags(
+  config: ConfigInterface,
+  logger: ShopifyLogger,
+) {
+  if (!config._logDisabledFutureFlags) {
+    return;
+  }
+
+  const logFlag = (flag: string, message: string) =>
+    logger.info(`Future flag ${flag} is disabled.\n\n  ${message}\n`);
+
+  if (!config.future?.customerAddressDefaultFix) {
+    logFlag(
+      'customerAddressDefaultFix',
+      "Enable this flag to change the CustomerAddress classes to expose a 'is_default' property instead of 'default' when fetching data.",
+    );
+  }
+
+  if (!config.future?.unstable_managedPricingSupport) {
+    logFlag(
+      'unstable_managedPricingSupport',
+      'Enable this flag to support managed pricing, so apps can check for payments without needing a billing config. Learn more at https://shopify.dev/docs/apps/launch/billing/managed-pricing',
+    );
+  }
+}

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

@@ -0,0 +1,10 @@
+import {ApiVersion} from '../types';
+
+export const DOMAIN = 'test-shop.myshopify.io';
+export const ACCESS_TOKEN = 'access-token';
+export const GRAPHQL_BASE_REQUEST = {
+  method: 'POST',
+  domain: DOMAIN,
+  path: `/admin/api/${ApiVersion.July25}/graphql.json`,
+  headers: {'X-Shopify-Access-Token': ACCESS_TOKEN},
+};

package/lib/__test-helpers__/index.ts

@@ -0,0 +1,6 @@
+export {toMatchMadeHttpRequest} from './to-match-made-http-request';
+export {
+  DOMAIN,
+  ACCESS_TOKEN,
+  GRAPHQL_BASE_REQUEST,
+} from './graphql-base-request';

package/lib/__test-helpers__/to-match-made-http-request.ts

@@ -0,0 +1,80 @@
+import type {MatcherFunction} from 'expect';
+
+import {mockTestRequests} from '../../adapters/mock/mock_test_requests';
+import {canonicalizeHeaders} from '../../runtime';
+
+interface ExpectRequestParams {
+  method: string;
+  domain: string;
+  path: string;
+  query?: string;
+  headers?: Record<string, any>;
+  data?: string | Record<string, any> | null;
+  attempts?: number;
+}
+
+export const toMatchMadeHttpRequest: MatcherFunction = ({
+  method,
+  domain,
+  path,
+  query = '',
+  headers = {},
+  data = undefined,
+  attempts = 1,
+}: ExpectRequestParams) => {
+  const searchHeaders = canonicalizeHeaders(headers as any);
+  const searchUrl = new URL(
+    `https://${domain}${path}${query ? `?${query}` : ''}`,
+  );
+
+  // We compare the sorted query items, so we can expect arguments in a different order
+  const searchQueryItems = Array.from(searchUrl.searchParams.entries()).sort();
+  const cleanSearchUrl = searchUrl.toString().split('?')[0];
+
+  for (let i = 0; i < attempts; i++) {
+    const matchingRequest = mockTestRequests.getRequest();
+    if (!matchingRequest) {
+      throw new Error(
+        `No request was made, but expected ${JSON.stringify(
+          {method, domain, path},
+          undefined,
+          2,
+        )}`,
+      );
+    }
+
+    const requestUrl = new URL(matchingRequest!.url);
+    const requestQueryItems = Array.from(
+      requestUrl.searchParams.entries(),
+    ).sort();
+    const cleanRequestUrl = requestUrl.toString().split('?')[0];
+
+    expect(matchingRequest).not.toBeNull();
+    expect(matchingRequest!.method).toEqual(method);
+    expect(matchingRequest!.headers).toMatchObject(searchHeaders);
+    expect(cleanRequestUrl).toEqual(cleanSearchUrl);
+    expect(requestQueryItems).toEqual(searchQueryItems);
+
+    if (data) {
+      if (
+        typeof data === 'string' ||
+        data.constructor.name === 'StringContaining'
+      ) {
+        expect(matchingRequest!.body).toEqual(data);
+      } else {
+        const requestBody =
+          typeof matchingRequest!.body === 'string'
+            ? JSON.parse(matchingRequest!.body)
+            : matchingRequest!.body;
+        expect(requestBody).toMatchObject(data);
+      }
+    } else {
+      expect(matchingRequest!.body).toBeFalsy();
+    }
+  }
+
+  return {
+    message: () => '',
+    pass: true,
+  };
+};

package/lib/auth/decode-host.ts

@@ -0,0 +1,3 @@
+export function decodeHost(host: string): string {
+  return atob(host);
+}

package/lib/auth/get-embedded-app-url.ts

@@ -0,0 +1,53 @@
+import * as ShopifyErrors from '../error';
+import {ConfigInterface} from '../base-types';
+import {abstractConvertRequest} from '../../runtime/http';
+import {sanitizeHost} from '../utils/shop-validator';
+
+import {decodeHost} from './decode-host';
+import {GetEmbeddedAppUrlParams} from './types';
+
+export type GetEmbeddedAppUrl = (
+  params: GetEmbeddedAppUrlParams,
+) => Promise<string>;
+
+export type BuildEmbeddedAppUrl = (host: string) => string;
+
+export function getEmbeddedAppUrl(config: ConfigInterface): GetEmbeddedAppUrl {
+  return async ({...adapterArgs}: GetEmbeddedAppUrlParams): Promise<string> => {
+    const request = await abstractConvertRequest(adapterArgs);
+
+    if (!request) {
+      throw new ShopifyErrors.MissingRequiredArgument(
+        'getEmbeddedAppUrl requires a request object argument',
+      );
+    }
+
+    if (!request.url) {
+      throw new ShopifyErrors.InvalidRequestError(
+        'Request does not contain a URL',
+      );
+    }
+
+    const url = new URL(request.url, `https://${request.headers.host}`);
+    const host = url.searchParams.get('host');
+
+    if (typeof host !== 'string') {
+      throw new ShopifyErrors.InvalidRequestError(
+        'Request does not contain a host query parameter',
+      );
+    }
+
+    return buildEmbeddedAppUrl(config)(host);
+  };
+}
+
+export function buildEmbeddedAppUrl(
+  config: ConfigInterface,
+): BuildEmbeddedAppUrl {
+  return (host: string): string => {
+    sanitizeHost(config)(host, true);
+    const decodedHost = decodeHost(host);
+
+    return `https://${decodedHost}/apps/${config.apiKey}`;
+  };
+}

package/lib/auth/index.ts

@@ -0,0 +1,52 @@
+import {ConfigInterface} from '../base-types';
+
+import {OAuthBegin, OAuthCallback, begin, callback} from './oauth/oauth';
+import {Nonce, nonce} from './oauth/nonce';
+import {SafeCompare, safeCompare} from './oauth/safe-compare';
+import {
+  getEmbeddedAppUrl,
+  buildEmbeddedAppUrl,
+  GetEmbeddedAppUrl,
+  BuildEmbeddedAppUrl,
+} from './get-embedded-app-url';
+import {TokenExchange, tokenExchange} from './oauth/token-exchange';
+import {ClientCredentials, clientCredentials} from './oauth/client-credentials';
+import {RefreshToken, refreshToken} from './oauth/refresh-token';
+import {
+  migrateToExpiringToken,
+  MigrateToExpiringToken,
+} from './oauth/migrate-to-expiring-token';
+
+export {AuthScopes} from './scopes';
+
+export function shopifyAuth<Config extends ConfigInterface>(
+  config: Config,
+): ShopifyAuth {
+  const shopify = {
+    begin: begin(config),
+    callback: callback(config),
+    nonce,
+    safeCompare,
+    getEmbeddedAppUrl: getEmbeddedAppUrl(config),
+    buildEmbeddedAppUrl: buildEmbeddedAppUrl(config),
+    tokenExchange: tokenExchange(config),
+    migrateToExpiringToken: migrateToExpiringToken(config),
+    refreshToken: refreshToken(config),
+    clientCredentials: clientCredentials(config),
+  } as ShopifyAuth;
+
+  return shopify;
+}
+
+export interface ShopifyAuth {
+  begin: OAuthBegin;
+  callback: OAuthCallback;
+  nonce: Nonce;
+  safeCompare: SafeCompare;
+  getEmbeddedAppUrl: GetEmbeddedAppUrl;
+  buildEmbeddedAppUrl: BuildEmbeddedAppUrl;
+  tokenExchange: TokenExchange;
+  migrateToExpiringToken: MigrateToExpiringToken;
+  refreshToken: RefreshToken;
+  clientCredentials: ClientCredentials;
+}

package/lib/auth/oauth/client-credentials.ts

@@ -0,0 +1,59 @@
+import {ConfigInterface} from '../../base-types';
+import {throwFailedRequest} from '../../clients/common';
+import {DataType} from '../../clients/types';
+import {Session} from '../../session/session';
+import {fetchRequestFactory} from '../../utils/fetch-request';
+import {sanitizeShop} from '../../utils/shop-validator';
+
+import {createSession} from './create-session';
+import {AccessTokenResponse} from './types';
+
+export interface ClientCredentialsParams {
+  shop: string;
+}
+
+const ClientCredentialsGrantType = 'client_credentials';
+
+export type ClientCredentials = (
+  params: ClientCredentialsParams,
+) => Promise<{session: Session}>;
+
+export function clientCredentials(config: ConfigInterface): ClientCredentials {
+  return async ({shop}: ClientCredentialsParams) => {
+    const cleanShop = sanitizeShop(config)(shop, true)!;
+
+    const requestConfig = {
+      method: 'POST',
+      body: JSON.stringify({
+        client_id: config.apiKey,
+        client_secret: config.apiSecretKey,
+        grant_type: ClientCredentialsGrantType,
+      }),
+      headers: {
+        'Content-Type': DataType.JSON,
+        Accept: DataType.JSON,
+      },
+    };
+
+    const postResponse = await fetchRequestFactory(config)(
+      `https://${cleanShop}/admin/oauth/access_token`,
+      requestConfig,
+    );
+
+    const responseData = (await postResponse.json()) as AccessTokenResponse;
+
+    if (!postResponse.ok) {
+      throwFailedRequest(responseData, false, postResponse);
+    }
+
+    return {
+      session: createSession({
+        accessTokenResponse: responseData,
+        shop: cleanShop,
+        // We need to keep this as an empty string as our template DB schemas have this required
+        state: '',
+        config,
+      }),
+    };
+  };
+}

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

@@ -0,0 +1,74 @@
+import {Session} from '../../session/session';
+import {ConfigInterface} from '../../base-types';
+import {logger} from '../../logger';
+import {getJwtSessionId, getOfflineId} from '../../session/session-utils';
+
+import {
+  AccessTokenResponse,
+  OnlineAccessResponse,
+  OnlineAccessInfo,
+  OfflineAccessResponse,
+} from './types';
+
+export function createSession({
+  config,
+  accessTokenResponse,
+  shop,
+  state,
+}: {
+  config: ConfigInterface;
+  accessTokenResponse: AccessTokenResponse;
+  shop: string;
+  state: string;
+}): Session {
+  const associatedUser = (accessTokenResponse as OnlineAccessResponse)
+    .associated_user;
+  const isOnline = Boolean(associatedUser);
+
+  logger(config).info('Creating new session', {shop, isOnline});
+
+  const getSessionExpiration = (expires_in: number) =>
+    new Date(Date.now() + expires_in * 1000);
+
+  const getOnlineSessionProperties = (responseBody: OnlineAccessResponse) => {
+    const {access_token, scope, ...rest} = responseBody;
+    const sessionId = config.isEmbeddedApp
+      ? getJwtSessionId(config)(
+          shop,
+          `${(rest as OnlineAccessInfo).associated_user.id}`,
+        )
+      : crypto.randomUUID();
+
+    return {
+      id: sessionId,
+      onlineAccessInfo: rest,
+      expires: getSessionExpiration(rest.expires_in),
+    };
+  };
+
+  const getOfflineSessionProperties = (responseBody: OfflineAccessResponse) => {
+    const {expires_in, refresh_token, refresh_token_expires_in} = responseBody;
+    return {
+      id: getOfflineId(config)(shop),
+      ...(expires_in && {expires: getSessionExpiration(expires_in)}),
+      ...(refresh_token &&
+        refresh_token_expires_in && {
+          refreshToken: refresh_token,
+          refreshTokenExpires: getSessionExpiration(refresh_token_expires_in),
+        }),
+    };
+  };
+
+  return new Session({
+    shop,
+    state,
+    isOnline,
+    accessToken: accessTokenResponse.access_token,
+    scope: accessTokenResponse.scope,
+    ...(isOnline
+      ? getOnlineSessionProperties(accessTokenResponse as OnlineAccessResponse)
+      : getOfflineSessionProperties(
+          accessTokenResponse as OfflineAccessResponse,
+        )),
+  });
+}

package/lib/auth/oauth/migrate-to-expiring-token.ts

@@ -0,0 +1,69 @@
+import {ConfigInterface} from '../../base-types';
+import {throwFailedRequest} from '../../clients/common';
+import {DataType} from '../../clients/types';
+import {Session} from '../../session/session';
+import {fetchRequestFactory} from '../../utils/fetch-request';
+import {sanitizeShop} from '../../utils/shop-validator';
+
+import {createSession} from './create-session';
+import {RequestedTokenType} from './token-exchange';
+import {AccessTokenResponse} from './types';
+
+const TokenExchangeGrantType =
+  'urn:ietf:params:oauth:grant-type:token-exchange';
+
+export interface MigrateToExpiringTokenParams {
+  shop: string;
+  nonExpiringOfflineAccessToken: string;
+}
+
+export type MigrateToExpiringToken = (
+  params: MigrateToExpiringTokenParams,
+) => Promise<{session: Session}>;
+
+export function migrateToExpiringToken(
+  config: ConfigInterface,
+): MigrateToExpiringToken {
+  return async ({
+    shop,
+    nonExpiringOfflineAccessToken,
+  }: MigrateToExpiringTokenParams) => {
+    const body = {
+      client_id: config.apiKey,
+      client_secret: config.apiSecretKey,
+      grant_type: TokenExchangeGrantType,
+      subject_token: nonExpiringOfflineAccessToken,
+      subject_token_type: RequestedTokenType.OfflineAccessToken,
+      requested_token_type: RequestedTokenType.OfflineAccessToken,
+      expiring: '1',
+    };
+
+    const cleanShop = sanitizeShop(config)(shop, true)!;
+
+    const postResponse = await fetchRequestFactory(config)(
+      `https://${cleanShop}/admin/oauth/access_token`,
+      {
+        method: 'POST',
+        body: JSON.stringify(body),
+        headers: {
+          'Content-Type': DataType.JSON,
+          Accept: DataType.JSON,
+        },
+      },
+    );
+
+    if (!postResponse.ok) {
+      throwFailedRequest(await postResponse.json(), false, postResponse);
+    }
+
+    return {
+      session: createSession({
+        accessTokenResponse: await postResponse.json<AccessTokenResponse>(),
+        shop: cleanShop,
+        // We need to keep this as an empty string as our template DB schemas have this required
+        state: '',
+        config,
+      }),
+    };
+  };
+}

package/lib/auth/oauth/nonce.ts

@@ -0,0 +1,15 @@
+export type Nonce = () => string;
+
+export function nonce(): string {
+  const length = 15;
+
+  const bytes = crypto.getRandomValues(new Uint8Array(length));
+
+  const nonce = bytes
+    .map((byte: number) => {
+      return byte % 10;
+    })
+    .join('');
+
+  return nonce;
+}