Add billing support

CHANGELOG.md

@@ -7,6 +7,7 @@ and adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+- Add support for billing to the library [#449](https://github.com/Shopify/shopify-api-node/pull/449)
 - Allow dynamically typing the body of REST and GraphQL request responses, so callers don't need to cast it [#447](https://github.com/Shopify/shopify-api-node/pull/447)
 
 ## [5.0.1] - 2022-08-03

README.md

@@ -51,5 +51,6 @@ You can follow our [getting started guide](docs/), which will provide instructio
 - [Webhooks](docs/usage/webhooks.md)
   - [Register a Webhook](docs/usage/webhooks.md#register-a-webhook)
   - [Process a Webhook](docs/usage/webhooks.md#process-a-webhook)
+- [Billing](docs/usage/billing.md)
 - [Known issues and caveats](docs/issues.md)
   - [Notes on session handling](docs/issues.md#notes-on-session-handling)

docs/README.md

@@ -22,6 +22,7 @@ You can follow our getting started guide, which will provide instructions on how
 - [Webhooks](usage/webhooks.md)
   - [Register a Webhook](usage/webhooks.md#register-a-webhook)
   - [Process a Webhook](usage/webhooks.md#process-a-webhook)
+- [Billing](docs/usage/billing.md)
 - [Create a `CustomSessionStorage` Solution](usage/customsessions.md)
   - [Usage Example with Redis](usage/customsessions.md#example-usage)
 - [Known issues and caveats](issues.md)

docs/usage/billing.md

@@ -0,0 +1,74 @@
+# Billing for your app
+
+Some partners might wish to charge merchants for using their app.
+Shopify provides API endpoints that enable apps to trigger purchases in the Shopify platform, so that apps don't need to implement their own billing features.
+
+This library provides support for billing apps by:
+
+1. Checking if the store has already paid for the app
+1. Triggering a payment if not
+
+Learn more about billing in [our documentation](https://shopify.dev/apps/billing).
+
+## Setting up for billing
+
+To trigger the billing behaviour, you should set the `BILLING` value when calling `Shopify.Context.initialize`.
+This setting is an object containing the following values:
+
+| Parameter      | Type              | Required? | Default Value | Notes                                                              |
+| -------------- | ----------------- | :-------: | :-----------: | ------------------------------------------------------------------ |
+| `chargeName`   | `string`          |    Yes    |       -       | The charge name to display to the merchant                         |
+| `amount`       | `number`          |    Yes    |       -       | The amount to charge                                               |
+| `currencyCode` | `string`          |    Yes    |       -       | The currency to charge, currently only `"USD"` is supported        |
+| `interval`     | `BillingInterval` |    Yes    |       -       | The interval for purchases, one of the BillingInterval enum values |
+
+`BillingInterval` values:
+
+- `OneTime`
+- `Every30Days`
+- `Annual`
+
+## Checking for payment
+
+The main method for billing is `Shopify.Billing.check`.
+This method will take in the following parameters:
+
+| Parameter | Type      | Required? | Default Value | Notes                                 |
+| --------- | --------- | :-------: | :-----------: | ------------------------------------- |
+| `session` | `Session` |    Yes    |       -       | The `Session` for the current request |
+| `isTest`  | `boolean` |    Yes    |       -       | Whether this is a test purchase       |
+
+And return the following:
+
+| Parameter         | Type                   | Notes                                               |
+| ----------------- | ---------------------- | --------------------------------------------------- |
+| `hasPayment`      | `boolean`              | Whether the store has already paid for the app      |
+| `confirmationUrl` | `string` / `undefined` | The URL to redirect to if payment is still required |
+
+Here's a typical example of how to use `check`:
+
+```ts
+const {hasPayment, confirmationUrl} = Shopify.Billing.check({
+  session,
+  isTest: true,
+});
+
+if (!hasPayment) {
+  return redirect(confirmationUrl);
+}
+
+// Proceed with app logic
+```
+
+## When should the app check for payment
+
+It's important to note that billing requires a session to access the API, which means that the app must actually be installed before it can request payment.
+
+With the `check` method, your app can block access to specific endpoints, or to the app as a whole.
+If you're gating access to the entire app, you should check for billing:
+
+1. After OAuth completes, once you get the session back from `Shopify.Auth.validateAuthCallback`. This allows you to ensure billing takes place immediately after the app is installed.
+   - Note that the merchant may refuse the payment at this point, but the app will already be installed. If your app is using offline tokens, sessions will be unique to a shop, so you can also use the latest session to check for access in full page loads.
+1. When validating requests from the frontend. Since the check requires API access, you can only run it in requests that work with `Shopify.Utils.loadCurrentSession`.
+
+[Back to guide index](../README.md)

src/base-types.ts

@@ -1,5 +1,6 @@
 import {AuthScopes} from './auth/scopes';
 import {SessionStorage} from './auth/session/session_storage';
+import {BillingSettings} from './billing/types';
 
 export interface ContextParams {
   API_KEY: string;
@@ -15,6 +16,7 @@ export interface ContextParams {
   USER_AGENT_PREFIX?: string;
   PRIVATE_APP_STOREFRONT_ACCESS_TOKEN?: string;
   CUSTOM_SHOP_DOMAINS?: (RegExp | string)[];
+  BILLING?: BillingSettings;
 }
 
 export enum ApiVersion {

src/billing/__tests__/check.test.ts

@@ -0,0 +1,259 @@
+import {Session} from '../../auth/session/session';
+import {Context} from '../../context';
+import {BillingError} from '../../error';
+import {check} from '../check';
+import {BillingInterval} from '../types';
+
+import {
+  TEST_CHARGE_NAME,
+  CONFIRMATION_URL,
+  EMPTY_SUBSCRIPTIONS,
+  EXISTING_ONE_TIME_PAYMENT,
+  EXISTING_ONE_TIME_PAYMENT_WITH_PAGINATION,
+  EXISTING_INACTIVE_ONE_TIME_PAYMENT,
+  EXISTING_SUBSCRIPTION,
+  PURCHASE_ONE_TIME_RESPONSE,
+  PURCHASE_SUBSCRIPTION_RESPONSE,
+  PURCHASE_ONE_TIME_RESPONSE_WITH_USER_ERRORS,
+  PURCHASE_SUBSCRIPTION_RESPONSE_WITH_USER_ERRORS,
+} from './check_responses';
+
+describe('check', () => {
+  const session = new Session('1234', 'test-shop.myshopify.io', '1234', true);
+  session.accessToken = 'access-token';
+  session.scope = Context.SCOPES.toString();
+
+  describe('with non-recurring config', () => {
+    beforeEach(() => {
+      Context.BILLING = {
+        amount: 5,
+        chargeName: TEST_CHARGE_NAME,
+        currencyCode: 'USD',
+        interval: BillingInterval.OneTime,
+      };
+    });
+
+    [true, false].forEach((isTest) =>
+      test(`requests a single payment if there is none (isTest: ${isTest})`, async () => {
+        fetchMock.mockResponses(
+          EMPTY_SUBSCRIPTIONS,
+          PURCHASE_ONE_TIME_RESPONSE,
+        );
+
+        const response = await check({
+          session,
+          isTest,
+        });
+
+        expect(response).toEqual({
+          hasPayment: false,
+          confirmationUrl: CONFIRMATION_URL,
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(fetchMock).toHaveBeenNthCalledWith(
+          1,
+          expect.anything(),
+          expect.objectContaining({
+            body: expect.stringContaining('oneTimePurchases'),
+            headers: expect.objectContaining({
+              'X-Shopify-Access-Token': session.accessToken,
+            }),
+          }),
+        );
+
+        const parsedBody = JSON.parse(
+          fetchMock.mock.calls[1][1]!.body!.toString(),
+        );
+        expect(parsedBody).toMatchObject({
+          query: expect.stringContaining('appPurchaseOneTimeCreate'),
+          variables: expect.objectContaining({test: isTest}),
+        });
+      }),
+    );
+
+    test('does not request payment if there is one', async () => {
+      fetchMock.mockResponses(EXISTING_ONE_TIME_PAYMENT);
+
+      const response = await check({
+        session,
+        isTest: true,
+      });
+
+      expect(response).toEqual({
+        hasPayment: true,
+        confirmationUrl: undefined,
+      });
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(fetchMock).toHaveBeenNthCalledWith(
+        1,
+        expect.anything(),
+        expect.objectContaining({
+          body: expect.stringContaining('oneTimePurchases'),
+        }),
+      );
+    });
+
+    test('ignores non-active payments', async () => {
+      fetchMock.mockResponses(
+        EXISTING_INACTIVE_ONE_TIME_PAYMENT,
+        PURCHASE_ONE_TIME_RESPONSE,
+      );
+
+      const response = await check({
+        session,
+        isTest: true,
+      });
+
+      expect(response).toEqual({
+        hasPayment: false,
+        confirmationUrl: CONFIRMATION_URL,
+      });
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(fetchMock).toHaveBeenNthCalledWith(
+        1,
+        expect.anything(),
+        expect.objectContaining({
+          body: expect.stringContaining('oneTimePurchases'),
+        }),
+      );
+      expect(fetchMock).toHaveBeenNthCalledWith(
+        2,
+        expect.anything(),
+        expect.objectContaining({
+          body: expect.stringContaining('appPurchaseOneTimeCreate'),
+        }),
+      );
+    });
+
+    test('paginates until a payment is found', async () => {
+      fetchMock.mockResponses(...EXISTING_ONE_TIME_PAYMENT_WITH_PAGINATION);
+
+      const response = await check({
+        session,
+        isTest: true,
+      });
+
+      expect(response).toEqual({
+        hasPayment: true,
+        confirmationUrl: undefined,
+      });
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+
+      let parsedBody = JSON.parse(fetchMock.mock.calls[0][1]!.body!.toString());
+      expect(parsedBody).toMatchObject({
+        query: expect.stringContaining('oneTimePurchases'),
+        variables: expect.objectContaining({endCursor: null}),
+      });
+
+      parsedBody = JSON.parse(fetchMock.mock.calls[1][1]!.body!.toString());
+      expect(parsedBody).toMatchObject({
+        query: expect.stringContaining('oneTimePurchases'),
+        variables: expect.objectContaining({endCursor: 'end_cursor'}),
+      });
+    });
+
+    test('throws on userErrors', async () => {
+      fetchMock.mockResponses(
+        EMPTY_SUBSCRIPTIONS,
+        PURCHASE_ONE_TIME_RESPONSE_WITH_USER_ERRORS,
+      );
+
+      await expect(() =>
+        check({
+          session,
+          isTest: true,
+        }),
+      ).rejects.toThrow(BillingError);
+
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('with recurring config', () => {
+    beforeEach(() => {
+      Context.BILLING = {
+        amount: 5,
+        chargeName: TEST_CHARGE_NAME,
+        currencyCode: 'USD',
+        interval: BillingInterval.Every30Days,
+      };
+    });
+
+    [true, false].forEach((isTest) =>
+      test(`requests a subscription if there is none (isTest: ${isTest})`, async () => {
+        fetchMock.mockResponses(
+          EMPTY_SUBSCRIPTIONS,
+          PURCHASE_SUBSCRIPTION_RESPONSE,
+        );
+
+        const response = await check({
+          session,
+          isTest,
+        });
+
+        expect(response).toEqual({
+          hasPayment: false,
+          confirmationUrl: CONFIRMATION_URL,
+        });
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(fetchMock).toHaveBeenNthCalledWith(
+          1,
+          expect.anything(),
+          expect.objectContaining({
+            body: expect.stringContaining('activeSubscriptions'),
+            headers: expect.objectContaining({
+              'X-Shopify-Access-Token': session.accessToken,
+            }),
+          }),
+        );
+
+        const parsedBody = JSON.parse(
+          fetchMock.mock.calls[1][1]!.body!.toString(),
+        );
+        expect(parsedBody).toMatchObject({
+          query: expect.stringContaining('appSubscriptionCreate'),
+          variables: expect.objectContaining({test: isTest}),
+        });
+      }),
+    );
+
+    test('does not request subscription if there is one', async () => {
+      fetchMock.mockResponses(EXISTING_SUBSCRIPTION);
+
+      const response = await check({
+        session,
+        isTest: true,
+      });
+
+      expect(response).toEqual({
+        hasPayment: true,
+        confirmationUrl: undefined,
+      });
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      expect(fetchMock).toHaveBeenNthCalledWith(
+        1,
+        expect.anything(),
+        expect.objectContaining({
+          body: expect.stringContaining('activeSubscriptions'),
+        }),
+      );
+    });
+
+    test('throws on userErrors', async () => {
+      fetchMock.mockResponses(
+        EMPTY_SUBSCRIPTIONS,
+        PURCHASE_SUBSCRIPTION_RESPONSE_WITH_USER_ERRORS,
+      );
+
+      await expect(() =>
+        check({
+          session,
+          isTest: true,
+        }),
+      ).rejects.toThrow(BillingError);
+
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+  });
+});