@shopify/shopify-api 12.3.0 → 13.0.0

package/lib/webhooks/register.ts

@@ -0,0 +1,522 @@
+import {graphqlClientClass, GraphqlClient} from '../clients/admin';
+import {InvalidDeliveryMethodError, ShopifyError} from '../error';
+import {logger} from '../logger';
+import {privacyTopics} from '../types';
+import {ConfigInterface} from '../base-types';
+import {Session} from '../session/session';
+
+import {addHostToCallbackUrl, getHandlers, handlerIdentifier} from './registry';
+import {queryTemplate} from './query-template';
+import {
+  WebhookRegistry,
+  RegisterReturn,
+  WebhookHandler,
+  WebhookCheckResponse,
+  DeliveryMethod,
+  WebhookCheckResponseNode,
+  WebhookOperation,
+  RegisterResult,
+  RegisterParams,
+} from './types';
+
+interface RegisterTopicParams {
+  config: ConfigInterface;
+  session: Session;
+  topic: string;
+  existingHandlers: WebhookHandler[];
+  handlers: WebhookHandler[];
+}
+
+interface RunMutationsParams {
+  config: ConfigInterface;
+  client: GraphqlClient;
+  topic: string;
+  handlers: WebhookHandler[];
+  operation: WebhookOperation;
+}
+
+interface RunMutationParams {
+  config: ConfigInterface;
+  client: GraphqlClient;
+  topic: string;
+  handler: WebhookHandler;
+  operation: WebhookOperation;
+}
+
+export function register(
+  config: ConfigInterface,
+  webhookRegistry: WebhookRegistry,
+) {
+  return async function register({
+    session,
+  }: RegisterParams): Promise<RegisterReturn> {
+    const log = logger(config);
+    log.info('Registering webhooks', {shop: session.shop});
+
+    const registerReturn: RegisterReturn = Object.keys(webhookRegistry).reduce(
+      (acc: RegisterReturn, topic) => {
+        acc[topic] = [];
+        return acc;
+      },
+      {},
+    );
+
+    const existingHandlers = await getExistingHandlers(config, session);
+
+    log.debug(
+      `Existing topics: [${Object.keys(existingHandlers).join(', ')}]`,
+      {shop: session.shop},
+    );
+
+    for (const topic in webhookRegistry) {
+      if (!Object.prototype.hasOwnProperty.call(webhookRegistry, topic)) {
+        continue;
+      }
+
+      if (privacyTopics.includes(topic)) {
+        continue;
+      }
+
+      registerReturn[topic] = await registerTopic({
+        config,
+        session,
+        topic,
+        existingHandlers: existingHandlers[topic] || [],
+        handlers: getHandlers(webhookRegistry)(topic),
+      });
+
+      // Remove this topic from the list of existing handlers so we have a list of leftovers
+      delete existingHandlers[topic];
+    }
+
+    // Delete any leftover handlers
+    for (const topic in existingHandlers) {
+      if (!Object.prototype.hasOwnProperty.call(existingHandlers, topic)) {
+        continue;
+      }
+
+      const GraphqlClient = graphqlClientClass({config});
+      const client = new GraphqlClient({session});
+
+      registerReturn[topic] = await runMutations({
+        config,
+        client,
+        topic,
+        handlers: existingHandlers[topic],
+        operation: WebhookOperation.Delete,
+      });
+    }
+
+    return registerReturn;
+  };
+}
+
+async function getExistingHandlers(
+  config: ConfigInterface,
+  session: Session,
+): Promise<WebhookRegistry> {
+  const GraphqlClient = graphqlClientClass({config});
+  const client = new GraphqlClient({session});
+
+  const existingHandlers: WebhookRegistry = {};
+
+  let hasNextPage: boolean;
+  let endCursor: string | null = null;
+  do {
+    const query = buildCheckQuery(endCursor);
+
+    const response = await client.request<WebhookCheckResponse>(query);
+
+    response.data?.webhookSubscriptions?.edges.forEach(
+      (edge: WebhookCheckResponseNode) => {
+        const handler = buildHandlerFromNode(edge);
+
+        if (!existingHandlers[edge.node.topic]) {
+          existingHandlers[edge.node.topic] = [];
+        }
+
+        existingHandlers[edge.node.topic].push(handler);
+      },
+    );
+
+    endCursor = response.data?.webhookSubscriptions?.pageInfo.endCursor!;
+    hasNextPage = response.data?.webhookSubscriptions?.pageInfo.hasNextPage!;
+  } while (hasNextPage);
+
+  return existingHandlers;
+}
+
+function buildCheckQuery(endCursor: string | null) {
+  return queryTemplate(TEMPLATE_GET_HANDLERS, {
+    END_CURSOR: JSON.stringify(endCursor),
+  });
+}
+
+function buildHandlerFromNode(edge: WebhookCheckResponseNode): WebhookHandler {
+  const endpoint = edge.node.endpoint;
+
+  let handler: WebhookHandler;
+
+  switch (endpoint.__typename) {
+    case 'WebhookHttpEndpoint':
+      handler = {
+        deliveryMethod: DeliveryMethod.Http,
+        callbackUrl: endpoint.callbackUrl,
+        // This is a dummy for now because we don't really care about it
+        callback: async () => {},
+      };
+      break;
+    case 'WebhookEventBridgeEndpoint':
+      handler = {
+        deliveryMethod: DeliveryMethod.EventBridge,
+        arn: endpoint.arn,
+      };
+      break;
+    case 'WebhookPubSubEndpoint':
+      handler = {
+        deliveryMethod: DeliveryMethod.PubSub,
+        pubSubProject: endpoint.pubSubProject,
+        pubSubTopic: endpoint.pubSubTopic,
+      };
+      break;
+  }
+
+  // Set common fields
+  handler.id = edge.node.id;
+  handler.includeFields = edge.node.includeFields;
+  handler.metafieldNamespaces = edge.node.metafieldNamespaces;
+
+  // Sort the array fields to make them cheaper to compare later on
+  handler.includeFields?.sort();
+  handler.metafieldNamespaces?.sort();
+
+  return handler;
+}
+
+async function registerTopic({
+  config,
+  session,
+  topic,
+  existingHandlers,
+  handlers,
+}: RegisterTopicParams): Promise<RegisterResult[]> {
+  let registerResults: RegisterResult[] = [];
+
+  const {toCreate, toUpdate, toDelete} = categorizeHandlers(
+    config,
+    existingHandlers,
+    handlers,
+  );
+
+  const GraphqlClient = graphqlClientClass({config});
+  const client = new GraphqlClient({session});
+
+  let operation = WebhookOperation.Create;
+  registerResults = registerResults.concat(
+    await runMutations({config, client, topic, operation, handlers: toCreate}),
+  );
+
+  operation = WebhookOperation.Update;
+  registerResults = registerResults.concat(
+    await runMutations({config, client, topic, operation, handlers: toUpdate}),
+  );
+
+  operation = WebhookOperation.Delete;
+  registerResults = registerResults.concat(
+    await runMutations({config, client, topic, operation, handlers: toDelete}),
+  );
+
+  return registerResults;
+}
+
+type HandlersByKey = Record<string, WebhookHandler>;
+
+function categorizeHandlers(
+  config: ConfigInterface,
+  existingHandlers: WebhookHandler[],
+  handlers: WebhookHandler[],
+) {
+  const handlersByKey = handlers.reduce((acc: HandlersByKey, value) => {
+    acc[handlerIdentifier(config, value)] = value;
+    return acc;
+  }, {});
+  const existingHandlersByKey = existingHandlers.reduce(
+    (acc: HandlersByKey, value) => {
+      acc[handlerIdentifier(config, value)] = value;
+      return acc;
+    },
+    {},
+  );
+
+  const toCreate: HandlersByKey = {...handlersByKey};
+  const toUpdate: HandlersByKey = {};
+  const toDelete: HandlersByKey = {};
+  for (const existingKey in existingHandlersByKey) {
+    if (
+      !Object.prototype.hasOwnProperty.call(existingHandlersByKey, existingKey)
+    ) {
+      continue;
+    }
+
+    const existingHandler = existingHandlersByKey[existingKey];
+    const handler = handlersByKey[existingKey];
+
+    if (existingKey in handlersByKey) {
+      delete toCreate[existingKey];
+
+      if (!areHandlerFieldsEqual(existingHandler, handler)) {
+        toUpdate[existingKey] = handler;
+        toUpdate[existingKey].id = existingHandler.id;
+      }
+    } else {
+      toDelete[existingKey] = existingHandler;
+    }
+  }
+
+  return {
+    toCreate: Object.values(toCreate),
+    toUpdate: Object.values(toUpdate),
+    toDelete: Object.values(toDelete),
+  };
+}
+function areHandlerFieldsEqual(
+  arr1: WebhookHandler,
+  arr2: WebhookHandler,
+): boolean {
+  const includeFieldsEqual = arraysEqual(
+    arr1.includeFields || [],
+    arr2.includeFields || [],
+  );
+  const metafieldNamespacesEqual = arraysEqual(
+    arr1.metafieldNamespaces || [],
+    arr2.metafieldNamespaces || [],
+  );
+
+  return includeFieldsEqual && metafieldNamespacesEqual;
+}
+
+function arraysEqual(arr1: any[], arr2: any[]): boolean {
+  if (arr1.length !== arr2.length) {
+    return false;
+  }
+
+  for (let i = 0; i < arr1.length; i++) {
+    if (arr1[i] !== arr2[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+async function runMutations({
+  config,
+  client,
+  topic,
+  handlers,
+  operation,
+}: RunMutationsParams): Promise<RegisterResult[]> {
+  const registerResults: RegisterResult[] = [];
+
+  for (const handler of handlers) {
+    registerResults.push(
+      await runMutation({config, client, topic, handler, operation}),
+    );
+  }
+
+  return registerResults;
+}
+
+async function runMutation({
+  config,
+  client,
+  topic,
+  handler,
+  operation,
+}: RunMutationParams): Promise<RegisterResult> {
+  let registerResult: RegisterResult;
+
+  logger(config).debug(`Running webhook mutation`, {topic, operation});
+
+  try {
+    const query = buildMutation(config, topic, handler, operation);
+
+    const result = await client.request(query);
+
+    registerResult = {
+      deliveryMethod: handler.deliveryMethod,
+      success: isSuccess(result, handler, operation),
+      result,
+      operation,
+    };
+  } catch (error) {
+    if (error instanceof InvalidDeliveryMethodError) {
+      registerResult = {
+        deliveryMethod: handler.deliveryMethod,
+        success: false,
+        result: {message: error.message},
+        operation,
+      };
+    } else {
+      throw error;
+    }
+  }
+
+  return registerResult;
+}
+
+function buildMutation(
+  config: ConfigInterface,
+  topic: string,
+  handler: WebhookHandler,
+  operation: WebhookOperation,
+): string {
+  const params: Record<string, string> = {};
+
+  let identifier: string;
+  if (handler.id) {
+    identifier = `id: "${handler.id}"`;
+  } else {
+    identifier = `topic: ${topic}`;
+  }
+
+  const mutationArguments = {
+    MUTATION_NAME: getMutationName(handler, operation),
+    IDENTIFIER: identifier,
+    MUTATION_PARAMS: '',
+  };
+
+  if (operation !== WebhookOperation.Delete) {
+    switch (handler.deliveryMethod) {
+      case DeliveryMethod.Http:
+        params.callbackUrl = `"${addHostToCallbackUrl(
+          config,
+          handler.callbackUrl,
+        )}"`;
+        break;
+      case DeliveryMethod.EventBridge:
+        params.arn = `"${handler.arn}"`;
+        break;
+      case DeliveryMethod.PubSub:
+        params.pubSubProject = `"${handler.pubSubProject}"`;
+        params.pubSubTopic = `"${handler.pubSubTopic}"`;
+        break;
+      default:
+        throw new InvalidDeliveryMethodError(
+          `Unrecognized delivery method '${(handler as any).deliveryMethod}'`,
+        );
+    }
+
+    if (handler.includeFields) {
+      params.includeFields = JSON.stringify(handler.includeFields);
+    }
+    if (handler.metafieldNamespaces) {
+      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(', ');
+
+    mutationArguments.MUTATION_PARAMS += `webhookSubscription: {${paramsString}}`;
+  }
+
+  return queryTemplate(TEMPLATE_MUTATION, mutationArguments);
+}
+
+function getMutationName(
+  handler: WebhookHandler,
+  operation: WebhookOperation,
+): string {
+  switch (operation) {
+    case WebhookOperation.Create:
+      return `${getEndpoint(handler)}Create`;
+    case WebhookOperation.Update:
+      return `${getEndpoint(handler)}Update`;
+    case WebhookOperation.Delete:
+      return 'webhookSubscriptionDelete';
+    default:
+      throw new ShopifyError(`Unrecognized operation '${operation}'`);
+  }
+}
+
+function getEndpoint(handler: WebhookHandler): string {
+  switch (handler.deliveryMethod) {
+    case DeliveryMethod.Http:
+      return 'webhookSubscription';
+    case DeliveryMethod.EventBridge:
+      return 'eventBridgeWebhookSubscription';
+    case DeliveryMethod.PubSub:
+      return 'pubSubWebhookSubscription';
+    default:
+      throw new ShopifyError(
+        `Unrecognized delivery method '${(handler as any).deliveryMethod}'`,
+      );
+  }
+}
+
+function isSuccess(
+  result: any,
+  handler: WebhookHandler,
+  operation: WebhookOperation,
+): boolean {
+  const mutationName = getMutationName(handler, operation);
+
+  return Boolean(
+    result.data &&
+    result.data[mutationName] &&
+    result.data[mutationName].userErrors.length === 0,
+  );
+}
+
+export const TEMPLATE_GET_HANDLERS = `query shopifyApiReadWebhookSubscriptions {
+  webhookSubscriptions(
+    first: 250,
+    after: {{END_CURSOR}},
+  ) {
+    edges {
+      node {
+        id
+        topic
+        includeFields
+        metafieldNamespaces
+        endpoint {
+          __typename
+          ... on WebhookHttpEndpoint {
+            callbackUrl
+          }
+          ... on WebhookEventBridgeEndpoint {
+            arn
+          }
+          ... on WebhookPubSubEndpoint {
+            pubSubProject
+            pubSubTopic
+          }
+        }
+      }
+    }
+    pageInfo {
+      endCursor
+      hasNextPage
+    }
+  }
+}`;
+
+export const TEMPLATE_MUTATION = `
+  mutation shopifyApiCreateWebhookSubscription {
+    {{MUTATION_NAME}}(
+      {{IDENTIFIER}},
+      {{MUTATION_PARAMS}}
+    ) {
+      userErrors {
+        field
+        message
+      }
+    }
+  }
+`;

package/lib/webhooks/registry.ts

@@ -0,0 +1,127 @@
+import {InvalidDeliveryMethodError} from '../error';
+import {ConfigInterface} from '../base-types';
+import {logger} from '../logger';
+
+import {
+  AddHandlersParams,
+  DeliveryMethod,
+  WebhookHandler,
+  WebhookRegistry,
+} from './types';
+
+export function registry(): WebhookRegistry {
+  return {};
+}
+
+export function topicForStorage(topic: string): string {
+  return topic.toUpperCase().replace(/\/|\./g, '_');
+}
+
+export function addHandlers(
+  config: ConfigInterface,
+  webhookRegistry: WebhookRegistry,
+) {
+  return function addHandlers(handlersToAdd: AddHandlersParams) {
+    for (const [topic, handlers] of Object.entries(handlersToAdd)) {
+      const topicKey = topicForStorage(topic);
+
+      if (Array.isArray(handlers)) {
+        for (const handler of handlers) {
+          mergeOrAddHandler(config, webhookRegistry, topicKey, handler);
+        }
+      } else {
+        mergeOrAddHandler(config, webhookRegistry, topicKey, handlers);
+      }
+    }
+  };
+}
+
+export function getTopicsAdded(webhookRegistry: WebhookRegistry) {
+  return function getTopicsAdded(): string[] {
+    return Object.keys(webhookRegistry);
+  };
+}
+
+export function getHandlers(webhookRegistry: WebhookRegistry) {
+  return function getHandlers(topic: string): WebhookHandler[] {
+    return webhookRegistry[topicForStorage(topic)] || [];
+  };
+}
+
+export function handlerIdentifier(
+  config: ConfigInterface,
+  handler: WebhookHandler,
+): string {
+  const prefix = handler.deliveryMethod;
+
+  switch (handler.deliveryMethod) {
+    case DeliveryMethod.Http:
+      return `${prefix}_${addHostToCallbackUrl(config, handler.callbackUrl)}`;
+    case DeliveryMethod.EventBridge:
+      return `${prefix}_${handler.arn}`;
+    case DeliveryMethod.PubSub:
+      return `${prefix}_${handler.pubSubProject}:${handler.pubSubTopic}`;
+    default:
+      throw new InvalidDeliveryMethodError(
+        `Unrecognized delivery method '${(handler as any).deliveryMethod}'`,
+      );
+  }
+}
+
+export function addHostToCallbackUrl(
+  config: ConfigInterface,
+  callbackUrl: string,
+): string {
+  if (callbackUrl.startsWith('/')) {
+    return `${config.hostScheme}://${config.hostName}${callbackUrl}`;
+  } else {
+    return callbackUrl;
+  }
+}
+
+function mergeOrAddHandler(
+  config: ConfigInterface,
+  webhookRegistry: WebhookRegistry,
+  topic: string,
+  handler: WebhookHandler,
+) {
+  const log = logger(config);
+
+  handler.includeFields?.sort();
+  handler.metafieldNamespaces?.sort();
+
+  if (!(topic in webhookRegistry)) {
+    webhookRegistry[topic] = [handler];
+    return;
+  }
+
+  const identifier = handlerIdentifier(config, handler);
+
+  for (const index in webhookRegistry[topic]) {
+    if (!Object.prototype.hasOwnProperty.call(webhookRegistry[topic], index)) {
+      continue;
+    }
+
+    const existingHandler = webhookRegistry[topic][index];
+    const existingIdentifier = handlerIdentifier(config, existingHandler);
+
+    if (identifier !== existingIdentifier) {
+      continue;
+    }
+
+    if (handler.deliveryMethod === DeliveryMethod.Http) {
+      log.info(
+        `Detected multiple handlers for '${topic}', webhooks.process will call them sequentially`,
+      );
+      break;
+    } else {
+      throw new InvalidDeliveryMethodError(
+        `Can only add multiple handlers for a topic when deliveryMethod is Http. Please be sure that you used addHandler method once after creating ShopifyApi instance in your app.  Invalid handler: ${JSON.stringify(
+          handler,
+        )}`,
+      );
+    }
+  }
+
+  webhookRegistry[topic].push(handler);
+}