@shopify/shopify-api 12.2.0 → 13.0.0

package/lib/base-types.ts

@@ -0,0 +1,161 @@
+import {FutureFlagOptions} from '../future/flags';
+import {ShopifyRestResources} from '../rest/types';
+
+import {AuthScopes} from './auth/scopes';
+import {BillingConfig} from './billing/types';
+import {ApiVersion, DomainTransformation, LogSeverity} from './types';
+
+/**
+ * A function used by the library to log events related to Shopify.
+ */
+export type LogFunction = (severity: LogSeverity, msg: string) => void;
+
+export interface ConfigParams<
+  Resources extends ShopifyRestResources = ShopifyRestResources,
+  Future extends FutureFlagOptions = FutureFlagOptions,
+> {
+  /**
+   * The API key for your app.
+   *
+   * Also known as Client ID in your Partner Dashboard.
+   */
+  apiKey?: string;
+  /**
+   * The API secret key for your app.
+   *
+   * Also known as Client Secret in your Partner Dashboard.
+   */
+  apiSecretKey: string;
+  /**
+   * The scopes your app needs to access the API. Not required if using Shopify managed installation.
+   */
+  scopes?: string[] | AuthScopes;
+  /**
+   * The host name of your app.
+   */
+  hostName: string;
+  /**
+   * The scheme to use for the app host.
+   */
+  hostScheme?: 'http' | 'https';
+  /**
+   * The API version to use.
+   */
+  apiVersion: ApiVersion;
+  /**
+   * Whether the app is embedded in the Shopify admin.
+   */
+  isEmbeddedApp: boolean;
+  /**
+   * Whether the app is a Shopify admin custom store app.
+   *
+   * @link https://shopify.dev/docs/apps/distribution
+   */
+  isCustomStoreApp?: boolean;
+  /**
+   * An app-wide API access token.
+   *
+   * Only applies to custom apps.
+   */
+  adminApiAccessToken?: string;
+  /**
+   * The user agent prefix to use for API requests.
+   */
+  userAgentPrefix?: string;
+  /**
+   * An app-wide API access token for the storefront API.
+   *
+   * Only applies to custom apps.
+   */
+  privateAppStorefrontAccessToken?: string;
+  /**
+   * Custom domain transformations for split-domain architectures.
+   *
+   * Transformations are applied in order. The first matching transformation is used.
+   * If no transformation matches, the domain is validated as-is.
+   *
+   * @example
+   * // Simple template-based transformation
+   * domainTransformations: [{
+   *   match: /^([a-zA-Z0-9][a-zA-Z0-9-_]*)\.my\.shop\.dev$/,
+   *   transform: '$1.dev-api.shop.dev'
+   * }]
+   *
+   * @example
+   * // Function-based transformation with custom logic
+   * domainTransformations: [{
+   *   match: /^([^.]+)\.ui\.example\.com$/,
+   *   transform: (matches) => {
+   *     const shopName = matches[1];
+   *     return shopName.startsWith('test-')
+   *       ? `${shopName}.api-staging.example.com`
+   *       : `${shopName}.api.example.com`;
+   *   }
+   * }]
+   */
+  domainTransformations?: DomainTransformation[];
+  /**
+   * Billing configurations for the app.
+   */
+  billing?: BillingConfig;
+  /**
+   * REST resources to access the Admin API.
+   *
+   * You can import these from `@shopify/shopify-api/rest/admin/*`.
+   */
+  restResources?: Resources;
+  /**
+   * Customization options for Shopify logs.
+   */
+  logger?: {
+    /**
+     * A custom log function.
+     */
+    log?: LogFunction;
+    /**
+     * The minimum severity level to log.
+     */
+    level?: LogSeverity;
+    /**
+     * Whether to log HTTP requests.
+     */
+    httpRequests?: boolean;
+    /**
+     * Whether to log timestamps.
+     */
+    timestamps?: boolean;
+  };
+  /**
+   * Future flags to include for this app.
+   */
+  future?: Future;
+  /**
+   * Whether to log disabled future flags at startup.
+   *
+   * @private
+   */
+  _logDisabledFutureFlags?: boolean;
+  /**
+   * Whether the app is initialised for local testing.
+   */
+  isTesting?: boolean;
+}
+
+export type ConfigInterface<Params extends ConfigParams = ConfigParams> = Omit<
+  Params,
+  'restResources' | 'scopes'
+> & {
+  apiKey: string;
+  hostScheme: 'http' | 'https';
+  scopes?: AuthScopes;
+  isCustomStoreApp: boolean;
+  billing?: BillingConfig;
+  logger: {
+    log: LogFunction;
+    level: LogSeverity;
+    httpRequests: boolean;
+    timestamps: boolean;
+  };
+  future: FutureFlagOptions;
+  isTesting?: boolean;
+};

package/lib/billing/cancel.ts

@@ -0,0 +1,61 @@
+import {ConfigInterface} from '../base-types';
+import {graphqlClientClass} from '../clients/admin';
+import {BillingError, GraphqlQueryError} from '../error';
+
+import {
+  AppSubscription,
+  BillingCancel,
+  BillingCancelParams,
+  CancelResponse,
+  APP_SUBSCRIPTION_FRAGMENT,
+} from './types';
+
+const CANCEL_MUTATION = `
+  ${APP_SUBSCRIPTION_FRAGMENT}
+  mutation appSubscriptionCancel($id: ID!, $prorate: Boolean) {
+    appSubscriptionCancel(id: $id, prorate: $prorate) {
+      appSubscription {
+        ...AppSubscriptionFragment
+      }
+      userErrors {
+        field
+        message
+      }
+    }
+  }
+`;
+
+export function cancel(config: ConfigInterface): BillingCancel {
+  return async function (
+    subscriptionInfo: BillingCancelParams,
+  ): Promise<AppSubscription> {
+    const {session, subscriptionId, prorate = true} = subscriptionInfo;
+
+    const GraphqlClient = graphqlClientClass({config});
+    const client = new GraphqlClient({session});
+
+    try {
+      const response = await client.request<CancelResponse>(CANCEL_MUTATION, {
+        variables: {id: subscriptionId, prorate},
+      });
+
+      if (response.data?.appSubscriptionCancel?.userErrors.length) {
+        throw new BillingError({
+          message: 'Error while canceling a subscription',
+          errorData: response.data?.appSubscriptionCancel?.userErrors,
+        });
+      }
+
+      return response.data?.appSubscriptionCancel?.appSubscription!;
+    } catch (error) {
+      if (error instanceof GraphqlQueryError) {
+        throw new BillingError({
+          message: error.message,
+          errorData: error.response?.errors,
+        });
+      } else {
+        throw error;
+      }
+    }
+  };
+}

package/lib/billing/check.ts

@@ -0,0 +1,157 @@
+import {FutureFlagOptions} from '../../future/flags';
+import {ConfigInterface} from '../base-types';
+import {graphqlClientClass, GraphqlClient} from '../clients/admin';
+import {BillingError} from '../error';
+
+import {
+  AppSubscription,
+  BillingCheck,
+  BillingCheckParams,
+  BillingCheckResponse,
+  BillingCheckResponseObject,
+  CurrentAppInstallation,
+  CurrentAppInstallations,
+  OneTimePurchase,
+  APP_SUBSCRIPTION_FRAGMENT,
+} from './types';
+import {convertLineItems} from './utils';
+
+interface SubscriptionMeetsCriteriaParams {
+  subscription: AppSubscription;
+  isTest?: boolean;
+  plans?: string | string[];
+}
+
+interface PurchaseMeetsCriteriaParams {
+  purchase: OneTimePurchase;
+  isTest?: boolean;
+  plans?: string | string[];
+}
+
+interface InternalParams {
+  client: GraphqlClient;
+  isTest?: boolean;
+  plans?: string | string[];
+}
+
+export function check<
+  Config extends ConfigInterface,
+  Future extends FutureFlagOptions = Config['future'],
+>(config: Config): BillingCheck<Future> {
+  return async function check<Params extends BillingCheckParams<Future>>(
+    params: Params,
+  ): Promise<BillingCheckResponse<Params, Future>> {
+    if (!config.future?.unstable_managedPricingSupport && !config.billing) {
+      throw new BillingError({
+        message: 'Attempted to look for purchases without billing configs',
+        errorData: [],
+      });
+    }
+
+    const {session, isTest = true, plans} = params;
+    const returnObject =
+      (params as BillingCheckParams<{unstable_managedPricingSupport: false}>)
+        .returnObject ?? false;
+
+    const GraphqlClient = graphqlClientClass({config});
+    const client = new GraphqlClient({session});
+
+    const payments = await assessPayments({client, isTest, plans});
+
+    if (config.future?.unstable_managedPricingSupport || returnObject) {
+      return payments as BillingCheckResponse<Params, Future>;
+    } else {
+      return payments.hasActivePayment as BillingCheckResponse<Params, Future>;
+    }
+  };
+}
+
+export async function assessPayments({
+  client,
+  isTest,
+  plans,
+}: InternalParams): Promise<BillingCheckResponseObject> {
+  const returnValue: BillingCheckResponseObject = {
+    hasActivePayment: false,
+    oneTimePurchases: [],
+    appSubscriptions: [],
+  };
+
+  let installation: CurrentAppInstallation;
+  let endCursor: string | null = null;
+  do {
+    const currentInstallations = await client.request<CurrentAppInstallations>(
+      HAS_PAYMENTS_QUERY,
+      {variables: {endCursor}},
+    );
+
+    installation = currentInstallations.data?.currentAppInstallation!;
+    installation.activeSubscriptions.forEach((subscription) => {
+      if (subscriptionMeetsCriteria({subscription, isTest, plans})) {
+        returnValue.hasActivePayment = true;
+        if (subscription.lineItems) {
+          subscription.lineItems = convertLineItems(subscription.lineItems);
+        }
+        returnValue.appSubscriptions.push(subscription);
+      }
+    });
+    installation.oneTimePurchases.edges.forEach(({node: purchase}) => {
+      if (purchaseMeetsCriteria({purchase, isTest, plans})) {
+        returnValue.hasActivePayment = true;
+        returnValue.oneTimePurchases.push(purchase);
+      }
+    });
+
+    endCursor = installation.oneTimePurchases.pageInfo.endCursor;
+  } while (installation?.oneTimePurchases.pageInfo.hasNextPage);
+
+  return returnValue;
+}
+
+function subscriptionMeetsCriteria({
+  subscription,
+  isTest,
+  plans,
+}: SubscriptionMeetsCriteriaParams): boolean {
+  return (
+    (typeof plans === 'undefined' || plans.includes(subscription.name)) &&
+    (isTest || !subscription.test)
+  );
+}
+
+function purchaseMeetsCriteria({
+  purchase,
+  isTest,
+  plans,
+}: PurchaseMeetsCriteriaParams): boolean {
+  return (
+    (typeof plans === 'undefined' || plans.includes(purchase.name)) &&
+    (isTest || !purchase.test) &&
+    purchase.status === 'ACTIVE'
+  );
+}
+
+const HAS_PAYMENTS_QUERY = `
+  ${APP_SUBSCRIPTION_FRAGMENT}
+  query appSubscription($endCursor: String) {
+    currentAppInstallation {
+      activeSubscriptions {
+        ...AppSubscriptionFragment
+      }
+      oneTimePurchases(first: 250, sortKey: CREATED_AT, after: $endCursor) {
+        edges {
+          node {
+            id
+            name
+            test
+            status
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+`;

package/lib/billing/create-usage-record.ts

@@ -0,0 +1,184 @@
+import {ConfigInterface} from '../base-types';
+import {BillingError, GraphqlQueryError} from '../error';
+import {GraphqlClient, graphqlClientClass} from '../clients/admin';
+
+import {
+  AppSubscription,
+  BillingCreateUsageRecord,
+  BillingCreateUsageRecordParams,
+  UsageRecord,
+  UsageRecordCreateResponse,
+  Money,
+} from './types';
+import {assessPayments} from './check';
+import {
+  convertAppRecurringPricingMoney,
+  convertAppUsagePricingMoney,
+} from './utils';
+
+interface InternalParams {
+  client: GraphqlClient;
+  isTest?: boolean;
+}
+
+interface CreateUsageRecordVariables {
+  description: string;
+  price: Money;
+  subscriptionLineItemId: string;
+  idempotencyKey?: string;
+}
+
+const CREATE_USAGE_RECORD_MUTATION = `
+mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
+  appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
+    userErrors {
+      field
+      message
+    }
+    appUsageRecord {
+      id
+      description
+      idempotencyKey
+      price {
+        amount
+        currencyCode
+      }
+      subscriptionLineItem {
+        id
+        plan {
+          pricingDetails {
+            ... on AppUsagePricing {
+              balanceUsed {
+                amount
+                currencyCode
+              }
+              cappedAmount {
+                amount
+                currencyCode
+              }
+              terms
+            }
+          }
+        }
+      }
+    }
+  }
+}
+`;
+
+export function createUsageRecord(
+  config: ConfigInterface,
+): BillingCreateUsageRecord {
+  return async function createUsageRecord(
+    usageRecordInfo: BillingCreateUsageRecordParams,
+  ): Promise<UsageRecord> {
+    const {
+      session,
+      subscriptionLineItemId,
+      description,
+      price,
+      idempotencyKey,
+      isTest = true,
+    } = usageRecordInfo;
+
+    const GraphqlClient = graphqlClientClass({config});
+    const client = new GraphqlClient({session});
+
+    // If a subscription line item ID is not passed, we will query Shopify
+    // for an active usage subscription line item ID
+    const usageSubscriptionLineItemId = subscriptionLineItemId
+      ? subscriptionLineItemId
+      : await getUsageRecordSubscriptionLineItemId({client, isTest});
+
+    const variables: CreateUsageRecordVariables = {
+      description,
+      price,
+      subscriptionLineItemId: usageSubscriptionLineItemId,
+    };
+    if (idempotencyKey) {
+      variables.idempotencyKey = idempotencyKey;
+    }
+
+    try {
+      const response = await client.request<UsageRecordCreateResponse>(
+        CREATE_USAGE_RECORD_MUTATION,
+        {
+          variables,
+        },
+      );
+      if (response.data?.appUsageRecordCreate?.userErrors.length) {
+        throw new BillingError({
+          message: 'Error while creating a usage record',
+          errorData: response.data?.appUsageRecordCreate?.userErrors,
+        });
+      }
+
+      const appUsageRecord =
+        response.data?.appUsageRecordCreate?.appUsageRecord!;
+      convertAppRecurringPricingMoney(appUsageRecord.price);
+      convertAppUsagePricingMoney(
+        appUsageRecord.subscriptionLineItem.plan.pricingDetails,
+      );
+
+      return appUsageRecord;
+    } catch (error) {
+      if (error instanceof GraphqlQueryError) {
+        throw new BillingError({
+          message: error.message,
+          errorData: error.response?.errors,
+        });
+      } else {
+        throw error;
+      }
+    }
+  };
+}
+
+async function getUsageRecordSubscriptionLineItemId({
+  client,
+  isTest,
+}: InternalParams): Promise<string> {
+  const payments = await assessPayments({client, isTest});
+
+  if (!payments.hasActivePayment) {
+    throw new BillingError({
+      message: 'No active payment found',
+      errorData: [],
+    });
+  }
+  if (!payments.appSubscriptions.length) {
+    throw new BillingError({
+      message: 'No active subscriptions found',
+      errorData: [],
+    });
+  }
+  if (payments.appSubscriptions) {
+    const usageSubscriptionLineItemId = getUsageLineItemId(
+      payments.appSubscriptions,
+    );
+    return usageSubscriptionLineItemId;
+  }
+  throw new BillingError({
+    message: 'Unable to find active subscription line item',
+    errorData: [],
+  });
+}
+
+function getUsageLineItemId(subscriptions: AppSubscription[]): string {
+  for (const subscription of subscriptions) {
+    // An app can have only one active subscription
+    if (subscription.status === 'ACTIVE' && subscription.lineItems) {
+      // An app can have only one usage subscription line item
+      for (const lineItem of subscription.lineItems) {
+        if ('balanceUsed' in lineItem.plan.pricingDetails) {
+          return lineItem.id;
+        }
+      }
+    }
+  }
+
+  throw new BillingError({
+    message: 'No active usage subscription found',
+    errorData: [],
+  });
+}

package/lib/billing/index.ts

@@ -0,0 +1,25 @@
+import {ConfigInterface} from '../base-types';
+import {FutureFlagOptions} from '../../future/flags';
+
+import {check} from './check';
+import {request} from './request';
+import {cancel} from './cancel';
+import {subscriptions} from './subscriptions';
+import {createUsageRecord} from './create-usage-record';
+import {updateUsageCappedAmount} from './update-usage-subscription-capped-amount';
+import {ShopifyBilling} from './types';
+
+export type {ShopifyBilling} from './types';
+
+export function shopifyBilling<Future extends FutureFlagOptions>(
+  config: ConfigInterface,
+): ShopifyBilling<Future> {
+  return {
+    check: check(config),
+    request: request(config),
+    cancel: cancel(config),
+    subscriptions: subscriptions(config),
+    createUsageRecord: createUsageRecord(config),
+    updateUsageCappedAmount: updateUsageCappedAmount(config),
+  };
+}