@sixtyninecommerce/admin 0.10.0 → 0.11.0

package/dist/subscriptions/index.js

@@ -0,0 +1,815 @@
+/**
+ * `admin.subscriptions`: subscription plans and the subscriptions sold on them (headless spec
+ * §9.2 `subscriptions`; plans W10-36, lifecycle W10-114). It reads subscriptions, manages plans,
+ * and runs the lifecycle and billing commands (purchase, pause/resume/cancel, payment recovery
+ * and reconciliation, renewal and settlement retries, price changes), each command that can
+ * charge, refund or change what a customer pays under one idempotency key per attempt (see
+ * `SubscriptionLifecycleCommands`).
+ *
+ * A plan is a store's template: a price per billing interval, the products each cycle ships, and
+ * the commitment rules. Changing or deleting a plan never changes a subscription already sold on
+ * it: each subscription keeps its own `recurringPrice` and products.
+ *
+ * **Money** is an integer in minor units of `currencyCode`. A plan's `price` and a subscription's
+ * `recurringPrice` are on the store's price basis (`readiness().pricesIncludeTax`: gross with VAT
+ * and shipping on a tax-inclusive store, net with net shipping otherwise). What a cycle actually
+ * charged (`billingCycles[].amount`, `upcomingPayment.amount`) is always gross.
+ *
+ * **Status words** are the meta catalog's `labels.subscription_status` keys (`active`,
+ * `past_due`, …): the SDK lower-cases the engine's enum, as it does a mandate's status. Every
+ * value set grows over time: treat a word this version does not name as one with no action.
+ *
+ * **Refusals** (`PlatformError`, by `code`) pass through as the engine sent them:
+ * `SUBSCRIPTION_PLAN_NOT_FOUND` (404), `SUBSCRIPTION_INPUT_INVALID` (400, the sentence names the
+ * value), `SUBSCRIPTION_PLAN_IN_USE` (422), `SUBSCRIPTION_PRODUCT_UNAVAILABLE` (422),
+ * `PLUGIN_ACCESS_DENIED` (403, the store has no subscriptions entitlement), and
+ * `HUB_HAS_NO_ORDERS` / `ORGANIZATION_WORKSPACE_NOT_A_STORE`. Another store's plan, subscription
+ * or customer is not found (a read answers null or an empty list), never served.
+ */
+import { idempotencyKey as mintIdempotencyKey, UpstreamError, ValidationError, } from '@sixtyninecommerce/core';
+import { assertDeleted, assertInstant, fieldOf } from '../catalog/types.js';
+import { redactionWatcher } from '../customer-data-redaction.js';
+/** The meta catalog's `labels.subscription_status` keys. */
+export const SUBSCRIPTION_STATUSES = [
+    'incomplete',
+    'trial',
+    'active',
+    'paused',
+    'past_due',
+    'cancelled',
+    'expired',
+    'completed',
+];
+const PLAN_FIELDS = /* GraphQL */ `
+  id
+  channelId
+  name
+  description
+  billingInterval
+  billingIntervalCount
+  currencyCode
+  price
+  trialDays
+  firstChargeTiming
+  customerChangeCutoffHours
+  minCycles
+  maxCycles
+  enabled
+  fulfillmentMode
+  shippingMethodId
+  activeSubscriptionCount
+  createdAt
+  updatedAt
+  variants {
+    id
+    variantId
+    quantity
+    position
+  }
+`;
+const LIST_FIELDS = /* GraphQL */ `
+  id
+  channelId
+  customerId
+  customerName
+  paidCycleCount
+  currencyCode
+  recurringPrice
+  billingInterval
+  billingIntervalCount
+  currentStatus
+  currentCycle
+  currentPeriodStart
+  currentPeriodEnd
+  nextRenewalAt
+  lastRenewedAt
+  cancelAtPeriodEnd
+  createdAt
+  attentionSummary
+  plan {
+    id
+    name
+    price
+    maxCycles
+  }
+  mandate {
+    id
+    provider
+    mandateMethod
+    mandateStatus
+  }
+`;
+const MANDATE_FIELDS = /* GraphQL */ `
+  id
+  channelId
+  customerId
+  provider
+  mandateMethod
+  mandateStatus
+  isDefault
+  createdAt
+  updatedAt
+`;
+export const SUBSCRIPTION_PLANS_QUERY = /* GraphQL */ `
+  query SubscriptionsPlansList($options: SubscriptionPlanListOptions) {
+    subscriptionPlans(options: $options) {
+      items {
+        ${PLAN_FIELDS}
+      }
+      totalItems
+    }
+  }
+`;
+export const SUBSCRIPTION_PLAN_QUERY = /* GraphQL */ `
+  query SubscriptionsPlansGet($id: ID!) {
+    subscriptionPlan(id: $id) {
+      ${PLAN_FIELDS}
+    }
+  }
+`;
+export const CREATE_SUBSCRIPTION_PLAN_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsPlansCreate($input: CreateSubscriptionPlanInput!) {
+    createSubscriptionPlan(input: $input) {
+      ${PLAN_FIELDS}
+    }
+  }
+`;
+export const UPDATE_SUBSCRIPTION_PLAN_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsPlansUpdate($id: ID!, $input: UpdateSubscriptionPlanInput!) {
+    updateSubscriptionPlan(id: $id, input: $input) {
+      ${PLAN_FIELDS}
+    }
+  }
+`;
+export const SET_SUBSCRIPTION_PLAN_VARIANTS_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsPlansSetVariants(
+    $planId: ID!
+    $variants: [SubscriptionPlanVariantInput!]!
+  ) {
+    setSubscriptionPlanVariants(planId: $planId, variants: $variants) {
+      ${PLAN_FIELDS}
+    }
+  }
+`;
+export const DELETE_SUBSCRIPTION_PLAN_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsPlansDelete($id: ID!) {
+    deleteSubscriptionPlan(id: $id) {
+      result
+      message
+    }
+  }
+`;
+export const SUBSCRIPTION_PLAN_PRICE_BREAKDOWN_QUERY = /* GraphQL */ `
+  query SubscriptionsPlansPriceBreakdown($input: SubscriptionPlanPriceBreakdownInput!) {
+    subscriptionPlanPriceBreakdown(input: $input) {
+      pricesIncludeTax
+      netAmount
+      taxAmount
+      grossAmount
+      currencyCode
+      zoneName
+    }
+  }
+`;
+export const SUBSCRIPTIONS_QUERY = /* GraphQL */ `
+  query SubscriptionsList($options: SubscriptionListOptions) {
+    subscriptions(options: $options) {
+      items {
+        ${LIST_FIELDS}
+      }
+      totalItems
+    }
+  }
+`;
+/** A billing cycle with its attempts, as `get` and the cycle commands answer it. */
+const CYCLE_FIELDS = /* GraphQL */ `
+  id cycleNumber dueAt periodStart periodEnd amount currencyCode paymentState settlementState
+  attentionReason orderId orderCode paidAt settledAt nextRetryAt
+  attempts {
+    id attemptNumber paymentState paymentProvider providerPaymentId providerSessionId
+    failureReason checkoutUrl nextRetryAt createdAt
+  }
+`;
+/** One subscription, as `get` and every lifecycle command that answers the subscription do. */
+const SUBSCRIPTION_FIELDS = /* GraphQL */ `
+  id
+  channelId
+  customerId
+  customerName
+  paidCycleCount
+  currencyCode
+  recurringPrice
+  billingInterval
+  billingIntervalCount
+  currentStatus
+  trialEndsAt
+  customerChangeCutoffHours
+  cutoffAt
+  cancellationRequested
+  cancellationEffectiveAt
+  earliestCancellationAt
+  remainingPaidCycles
+  committedPayment
+  resumeAt
+  retainedResumeAt
+  earliestResumeAt
+  paymentActionRequired
+  allowedActions { action allowed reason }
+  products { variantId quantity name sku }
+  upcomingPayment { purchaseId dueAt amount currencyCode state nextRetryAt checkoutUrl }
+  activity { id action actor reason createdAt }
+  billingCycles {
+    ${CYCLE_FIELDS}
+  }
+  notifications {
+    id event dueAt dispatchedAt failureCount lastError nextAttemptAt parkedAt parkedReason
+  }
+  currentCycle
+  minCycles
+  maxCycles
+  currentPeriodStart
+  currentPeriodEnd
+  nextRenewalAt
+  lastRenewedAt
+  cancelAtPeriodEnd
+  cancelAt
+  externalId
+  externalPlatform
+  createdAt
+  updatedAt
+  plan {
+    id
+    name
+    description
+    billingInterval
+    billingIntervalCount
+    currencyCode
+    price
+    trialDays
+    firstChargeTiming
+    customerChangeCutoffHours
+    enabled
+  }
+  mandate {
+    id
+    provider
+    mandateMethod
+    mandateStatus
+    isDefault
+  }
+  renewalHistory {
+    id
+    cycleNumber
+    cycleId
+    attemptNumber
+    paymentState
+    orderId
+    paymentProvider
+    providerPaymentId
+    amount
+    currencyCode
+    result
+    failureReason
+    retryCount
+    createdAt
+  }
+`;
+export const SUBSCRIPTION_QUERY = /* GraphQL */ `
+  query SubscriptionsGet($id: ID!) {
+    subscription(id: $id) {
+      ${SUBSCRIPTION_FIELDS}
+    }
+  }
+`;
+export const CUSTOMER_SUBSCRIPTIONS_QUERY = /* GraphQL */ `
+  query SubscriptionsForCustomer($customerId: ID!) {
+    customerSubscriptions(customerId: $customerId) {
+      ${LIST_FIELDS}
+    }
+  }
+`;
+export const CUSTOMER_MANDATES_QUERY = /* GraphQL */ `
+  query SubscriptionsMandates($customerId: ID!) {
+    customerMandates(customerId: $customerId) {
+      ${MANDATE_FIELDS}
+    }
+  }
+`;
+export const SUBSCRIPTION_CHANNEL_READINESS_QUERY = /* GraphQL */ `
+  query SubscriptionsReadiness {
+    subscriptionChannelReadiness {
+      pricesIncludeTax
+      storefrontUrlConfigured
+      managementUrlConfigured
+      providers {
+        code
+        configured
+        enabled
+      }
+    }
+  }
+`;
+const PURCHASE_FIELDS = /* GraphQL */ `
+  id
+  subscriptionId
+  state
+  checkoutUrl
+  expiresAt
+  currentStatus
+  paymentActionRequired
+  nextRenewalAt
+`;
+const RENEWAL_FIELDS = /* GraphQL */ `
+  id
+  cycleNumber
+  cycleId
+  attemptNumber
+  paymentState
+  orderId
+  paymentProvider
+  providerPaymentId
+  amount
+  currencyCode
+  result
+  failureReason
+  retryCount
+  createdAt
+`;
+export const SUBSCRIPTION_PURCHASE_PREVIEW_QUERY = /* GraphQL */ `
+  query SubscriptionsPurchasePreview(
+    $planId: ID!
+    $customerId: ID
+    $provider: String
+    $mandateId: ID
+  ) {
+    subscriptionPurchasePreview(
+      planId: $planId
+      customerId: $customerId
+      provider: $provider
+      mandateId: $mandateId
+    ) {
+      planId
+      planName
+      amount
+      pricesIncludeTax
+      netAmount
+      taxAmount
+      currencyCode
+      firstPaymentAt
+      firstChargeTiming
+      billingInterval
+      billingIntervalCount
+      trialDays
+      trialEndsAt
+      minCycles
+      maxCycles
+      customerChangeCutoffHours
+      cutoffAt
+      mandateVerificationAmount
+      products {
+        variantId
+        name
+        quantity
+      }
+    }
+  }
+`;
+export const START_SUBSCRIPTION_PURCHASE_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsPurchaseStart($input: SubscriptionPurchaseInput!) {
+    startSubscriptionPurchase(input: $input) {
+      ${PURCHASE_FIELDS}
+    }
+  }
+`;
+export const SUBSCRIPTION_PURCHASE_STATUS_QUERY = /* GraphQL */ `
+  query SubscriptionsPurchaseStatus($id: ID!) {
+    subscriptionPurchaseStatus(id: $id) {
+      ${PURCHASE_FIELDS}
+    }
+  }
+`;
+export const RECONCILE_SUBSCRIPTION_PURCHASE_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsPurchaseReconcile(
+    $id: ID!
+    $requestKey: String!
+    $investigationReason: String!
+    $providerReference: String
+    $reopen: Boolean
+  ) {
+    reconcileSubscriptionPurchase(
+      id: $id
+      requestKey: $requestKey
+      investigationReason: $investigationReason
+      providerReference: $providerReference
+      reopen: $reopen
+    )
+  }
+`;
+export const PREVIEW_SUBSCRIPTION_CHANGE_QUERY = /* GraphQL */ `
+  query SubscriptionsPreviewChange($id: ID!, $input: SubscriptionLifecycleCommand!) {
+    previewSubscriptionChange(id: $id, input: $input) {
+      allowed
+      reason
+      nextRenewalAt
+      cancellationEffectiveAt
+      committedPayment
+      remainingPaidCycles
+    }
+  }
+`;
+export const MANAGE_SUBSCRIPTION_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsManage($id: ID!, $input: SubscriptionLifecycleCommand!) {
+    manageSubscription(id: $id, input: $input) {
+      ${SUBSCRIPTION_FIELDS}
+    }
+  }
+`;
+export const REPLACE_SUBSCRIPTION_MANDATE_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsReplaceMandate($id: ID!, $input: SubscriptionPaymentActionInput!) {
+    replaceSubscriptionMandate(id: $id, input: $input) {
+      ${PURCHASE_FIELDS}
+    }
+  }
+`;
+export const RECOVER_SUBSCRIPTION_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsRecoverPayment($id: ID!, $input: SubscriptionPaymentActionInput!) {
+    recoverSubscriptionPayment(id: $id, input: $input) {
+      ${PURCHASE_FIELDS}
+    }
+  }
+`;
+export const RECONCILE_SUBSCRIPTION_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsReconcilePayment(
+    $id: ID!
+    $attemptId: ID!
+    $providerReference: String!
+    $requestKey: String!
+    $investigationReason: String!
+  ) {
+    reconcileSubscriptionPayment(
+      id: $id
+      attemptId: $attemptId
+      providerReference: $providerReference
+      requestKey: $requestKey
+      investigationReason: $investigationReason
+    ) {
+      ${SUBSCRIPTION_FIELDS}
+    }
+  }
+`;
+export const REOPEN_UNKNOWN_SUBSCRIPTION_PAYMENT_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsReopenUnknownPayment(
+    $id: ID!
+    $attemptId: ID!
+    $requestKey: String!
+    $investigationReason: String!
+  ) {
+    reopenUnknownSubscriptionPayment(
+      id: $id
+      attemptId: $attemptId
+      requestKey: $requestKey
+      investigationReason: $investigationReason
+    ) {
+      ${SUBSCRIPTION_FIELDS}
+    }
+  }
+`;
+export const RETRY_SUBSCRIPTION_RENEWAL_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsRetryRenewal($subscriptionId: ID!, $requestKey: String) {
+    retrySubscriptionRenewal(subscriptionId: $subscriptionId, requestKey: $requestKey) {
+      ${RENEWAL_FIELDS}
+    }
+  }
+`;
+export const RETRY_SUBSCRIPTION_SETTLEMENT_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsRetrySettlement($subscriptionId: ID!, $requestKey: String) {
+    retrySubscriptionSettlement(subscriptionId: $subscriptionId, requestKey: $requestKey) {
+      ${CYCLE_FIELDS}
+    }
+  }
+`;
+export const CLEAR_SUBSCRIPTION_CYCLE_ATTENTION_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsClearAttention($cycleId: ID!, $reason: String!, $requestKey: String) {
+    clearSubscriptionCycleAttention(cycleId: $cycleId, reason: $reason, requestKey: $requestKey) {
+      ${CYCLE_FIELDS}
+    }
+  }
+`;
+export const UPDATE_SUBSCRIPTION_PRICE_MUTATION = /* GraphQL */ `
+  mutation SubscriptionsUpdatePrice($id: ID!, $newPrice: Int!, $requestKey: String) {
+    updateSubscriptionPrice(id: $id, newPrice: $newPrice, requestKey: $requestKey) {
+      ${SUBSCRIPTION_FIELDS}
+    }
+  }
+`;
+function unexpected(field) {
+    return new UpstreamError({
+        code: 'UNEXPECTED_RESPONSE',
+        message: `The engine answered without "${field}".`,
+        status: 502,
+        service: 'vendure',
+    });
+}
+function invalid(message) {
+    return new ValidationError({
+        code: 'SUBSCRIPTION_INPUT_INVALID',
+        message,
+        status: 400,
+        service: 'vendure',
+    });
+}
+/** The engine's enums are upper-case; the SDK answers the meta catalog's lower-case words. */
+function lower(value) {
+    return typeof value === 'string' ? value.toLowerCase() : null;
+}
+function mandateOf(mandate) {
+    if (mandate === null)
+        return mandate;
+    return { ...mandate, mandateStatus: lower(mandate.mandateStatus) };
+}
+function subscriptionOf(wire) {
+    return {
+        ...wire,
+        currentStatus: lower(wire.currentStatus),
+        mandate: mandateOf(wire.mandate),
+    };
+}
+/** The caller's key for this attempt, or a fresh one (one key per attempt, never per call). */
+function keyOf(options) {
+    return options?.idempotencyKey ?? mintIdempotencyKey();
+}
+const CHANGE_ACTIONS = [
+    'pause',
+    'resume',
+    'skip',
+    'reschedule',
+    'undoCancellation',
+    'cancel',
+    'cancelImmediately',
+];
+/** The engine's `SubscriptionLifecycleCommand`, checked before anything is sent. */
+function commandOf(change, requestKey) {
+    if (!CHANGE_ACTIONS.includes(change.action)) {
+        throw invalid(`action must be one of ${CHANGE_ACTIONS.join(', ')}; got "${String(change.action)}".`);
+    }
+    assertInstant('date', change.date);
+    return {
+        action: change.action,
+        requestKey,
+        date: change.date ?? null,
+        reason: change.reason ?? null,
+        overrideReason: change.overrideReason ?? null,
+    };
+}
+function purchaseOf(wire) {
+    return { ...wire, currentStatus: lower(wire.currentStatus) };
+}
+export function createSubscriptionsModule(transport) {
+    /** A command that answers the subscription: mapped and marked like `get`. */
+    async function subscriptionAnswer(query, field, variables, call) {
+        const redaction = redactionWatcher();
+        const data = await transport.graphql({ api: 'admin', query, variables, onExtensions: redaction.onExtensions }, call);
+        const subscription = data?.[field];
+        if (subscription == null)
+            throw unexpected(field);
+        return redaction.mark(subscriptionOf(subscription));
+    }
+    const plans = {
+        async list(options) {
+            const { take, skip, enabled, ...call } = options ?? {};
+            const page = await fieldOf(transport, SUBSCRIPTION_PLANS_QUERY, 'subscriptionPlans', { options: { take, skip, enabled } }, call);
+            if (page == null)
+                throw unexpected('subscriptionPlans');
+            return page;
+        },
+        get: (planId, options) => fieldOf(transport, SUBSCRIPTION_PLAN_QUERY, 'subscriptionPlan', { id: planId }, options),
+        create: (input, options) => fieldOf(transport, CREATE_SUBSCRIPTION_PLAN_MUTATION, 'createSubscriptionPlan', { input }, options),
+        update: (planId, input, options) => fieldOf(transport, UPDATE_SUBSCRIPTION_PLAN_MUTATION, 'updateSubscriptionPlan', { id: planId, input }, options),
+        setVariants: (planId, variants, options) => fieldOf(transport, SET_SUBSCRIPTION_PLAN_VARIANTS_MUTATION, 'setSubscriptionPlanVariants', {
+            planId,
+            variants: variants.map(({ variantId, quantity }) => ({ variantId, quantity })),
+        }, options),
+        async delete(planId, options) {
+            const response = await fieldOf(transport, DELETE_SUBSCRIPTION_PLAN_MUTATION, 'deleteSubscriptionPlan', { id: planId }, options);
+            if (response == null)
+                throw unexpected('deleteSubscriptionPlan');
+            assertDeleted('SUBSCRIPTION_PLAN_NOT_DELETED', [response]);
+        },
+        priceBreakdown: (input, options) => fieldOf(transport, SUBSCRIPTION_PLAN_PRICE_BREAKDOWN_QUERY, 'subscriptionPlanPriceBreakdown', {
+            input: {
+                price: input.price,
+                variants: input.variants.map(({ variantId, quantity }) => ({ variantId, quantity })),
+                fulfillmentMode: input.fulfillmentMode,
+                shippingMethodId: input.shippingMethodId ?? null,
+            },
+        }, options),
+    };
+    return {
+        plans,
+        purchase: {
+            async preview(input, options) {
+                const preview = await fieldOf(transport, SUBSCRIPTION_PURCHASE_PREVIEW_QUERY, 'subscriptionPurchasePreview', {
+                    planId: input.planId,
+                    customerId: input.customerId,
+                    provider: input.provider ?? null,
+                    mandateId: input.mandateId ?? null,
+                }, options);
+                if (preview == null)
+                    throw unexpected('subscriptionPurchasePreview');
+                return preview;
+            },
+            async start(input, options) {
+                const key = keyOf(options);
+                const purchase = await fieldOf(transport, START_SUBSCRIPTION_PURCHASE_MUTATION, 'startSubscriptionPurchase', {
+                    input: {
+                        customerId: input.customerId,
+                        planId: input.planId,
+                        provider: input.provider ?? null,
+                        mandateId: input.mandateId ?? null,
+                        expectedAmount: input.expectedAmount ?? null,
+                        sendPaymentEmail: input.sendPaymentEmail ?? false,
+                        returnUrl: input.returnUrl ?? '',
+                        requestKey: key,
+                    },
+                }, { ...options, idempotencyKey: key });
+                if (purchase == null)
+                    throw unexpected('startSubscriptionPurchase');
+                return purchaseOf(purchase);
+            },
+            async status(purchaseId, options) {
+                const purchase = await fieldOf(transport, SUBSCRIPTION_PURCHASE_STATUS_QUERY, 'subscriptionPurchaseStatus', { id: purchaseId }, options);
+                if (purchase == null)
+                    throw unexpected('subscriptionPurchaseStatus');
+                return purchaseOf(purchase);
+            },
+            async reconcile(purchaseId, input, options) {
+                const key = keyOf(options);
+                const done = await fieldOf(transport, RECONCILE_SUBSCRIPTION_PURCHASE_MUTATION, 'reconcileSubscriptionPurchase', {
+                    id: purchaseId,
+                    requestKey: key,
+                    investigationReason: input.investigationReason,
+                    providerReference: input.providerReference ?? null,
+                    reopen: input.reopen ?? false,
+                }, { ...options, idempotencyKey: key });
+                if (done !== true)
+                    throw unexpected('reconcileSubscriptionPurchase');
+            },
+        },
+        async previewChange(subscriptionId, change, options) {
+            const preview = await fieldOf(transport, PREVIEW_SUBSCRIPTION_CHANGE_QUERY, 'previewSubscriptionChange', 
+            // A preview writes nothing; the engine's input type still requires a key.
+            { id: subscriptionId, input: commandOf(change, 'preview') }, options);
+            if (preview == null)
+                throw unexpected('previewSubscriptionChange');
+            return preview;
+        },
+        async manage(subscriptionId, change, options) {
+            // A JavaScript caller is not held to the type: a cancellation goes through `cancel`.
+            const action = change.action;
+            if (action === 'cancel' || action === 'cancelImmediately') {
+                throw invalid('A cancellation is made with `cancel`, not `manage`.');
+            }
+            const key = keyOf(options);
+            return subscriptionAnswer(MANAGE_SUBSCRIPTION_MUTATION, 'manageSubscription', { id: subscriptionId, input: commandOf(change, key) }, { ...options, idempotencyKey: key });
+        },
+        async cancel(subscriptionId, input, options) {
+            const key = keyOf(options);
+            const change = {
+                action: input?.immediately ? 'cancelImmediately' : 'cancel',
+                reason: input?.reason,
+                overrideReason: input?.overrideReason,
+            };
+            return subscriptionAnswer(MANAGE_SUBSCRIPTION_MUTATION, 'manageSubscription', { id: subscriptionId, input: commandOf(change, key) }, { ...options, idempotencyKey: key });
+        },
+        async replaceMandate(subscriptionId, input, options) {
+            const key = keyOf(options);
+            const purchase = await fieldOf(transport, REPLACE_SUBSCRIPTION_MANDATE_MUTATION, 'replaceSubscriptionMandate', {
+                id: subscriptionId,
+                input: { requestKey: key, provider: input.provider, returnUrl: input.returnUrl ?? '' },
+            }, { ...options, idempotencyKey: key });
+            if (purchase == null)
+                throw unexpected('replaceSubscriptionMandate');
+            return purchaseOf(purchase);
+        },
+        async recoverPayment(subscriptionId, input, options) {
+            const key = keyOf(options);
+            const purchase = await fieldOf(transport, RECOVER_SUBSCRIPTION_PAYMENT_MUTATION, 'recoverSubscriptionPayment', { id: subscriptionId, input: { requestKey: key, returnUrl: input?.returnUrl ?? '' } }, { ...options, idempotencyKey: key });
+            if (purchase == null)
+                throw unexpected('recoverSubscriptionPayment');
+            return purchaseOf(purchase);
+        },
+        async reconcilePayment(subscriptionId, input, options) {
+            const key = keyOf(options);
+            return subscriptionAnswer(RECONCILE_SUBSCRIPTION_PAYMENT_MUTATION, 'reconcileSubscriptionPayment', {
+                id: subscriptionId,
+                attemptId: input.attemptId,
+                providerReference: input.providerReference,
+                investigationReason: input.investigationReason,
+                requestKey: key,
+            }, { ...options, idempotencyKey: key });
+        },
+        async reopenUnknownPayment(subscriptionId, input, options) {
+            const key = keyOf(options);
+            return subscriptionAnswer(REOPEN_UNKNOWN_SUBSCRIPTION_PAYMENT_MUTATION, 'reopenUnknownSubscriptionPayment', {
+                id: subscriptionId,
+                attemptId: input.attemptId,
+                investigationReason: input.investigationReason,
+                requestKey: key,
+            }, { ...options, idempotencyKey: key });
+        },
+        async retryRenewal(subscriptionId, options) {
+            const key = keyOf(options);
+            const attempt = await fieldOf(transport, RETRY_SUBSCRIPTION_RENEWAL_MUTATION, 'retrySubscriptionRenewal', { subscriptionId, requestKey: key }, { ...options, idempotencyKey: key });
+            if (attempt == null)
+                throw unexpected('retrySubscriptionRenewal');
+            return attempt;
+        },
+        async retrySettlement(subscriptionId, options) {
+            const key = keyOf(options);
+            const cycle = await fieldOf(transport, RETRY_SUBSCRIPTION_SETTLEMENT_MUTATION, 'retrySubscriptionSettlement', { subscriptionId, requestKey: key }, { ...options, idempotencyKey: key });
+            if (cycle == null)
+                throw unexpected('retrySubscriptionSettlement');
+            return cycle;
+        },
+        async clearAttention(cycleId, reason, options) {
+            const key = keyOf(options);
+            const cycle = await fieldOf(transport, CLEAR_SUBSCRIPTION_CYCLE_ATTENTION_MUTATION, 'clearSubscriptionCycleAttention', { cycleId, reason, requestKey: key }, { ...options, idempotencyKey: key });
+            if (cycle == null)
+                throw unexpected('clearSubscriptionCycleAttention');
+            return cycle;
+        },
+        async updatePrice(subscriptionId, newPrice, options) {
+            if (!Number.isSafeInteger(newPrice) || newPrice < 1) {
+                throw invalid(`newPrice must be a positive integer in minor units; got ${String(newPrice)}.`);
+            }
+            const key = keyOf(options);
+            return subscriptionAnswer(UPDATE_SUBSCRIPTION_PRICE_MUTATION, 'updateSubscriptionPrice', { id: subscriptionId, newPrice, requestKey: key }, { ...options, idempotencyKey: key });
+        },
+        async list(options) {
+            const { search, needsAttention, status, customerId, planId, take, skip, ...call } = options ?? {};
+            if (status !== undefined && !SUBSCRIPTION_STATUSES.includes(status)) {
+                throw invalid(`status must be one of ${SUBSCRIPTION_STATUSES.join(', ')}; got "${String(status)}".`);
+            }
+            const redaction = redactionWatcher();
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SUBSCRIPTIONS_QUERY,
+                variables: {
+                    options: {
+                        search,
+                        needsAttention,
+                        status: status?.toUpperCase(),
+                        customerId,
+                        planId,
+                        take,
+                        skip,
+                    },
+                },
+                onExtensions: redaction.onExtensions,
+            }, call);
+            if (data?.subscriptions == null)
+                throw unexpected('subscriptions');
+            return {
+                items: data.subscriptions.items.map((item) => redaction.mark(subscriptionOf(item))),
+                totalItems: data.subscriptions.totalItems,
+            };
+        },
+        async get(subscriptionId, options) {
+            const redaction = redactionWatcher();
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SUBSCRIPTION_QUERY,
+                variables: { id: subscriptionId },
+                onExtensions: redaction.onExtensions,
+            }, options);
+            if (data == null || !Object.hasOwn(data, 'subscription'))
+                throw unexpected('subscription');
+            const subscription = data.subscription;
+            return subscription ? redaction.mark(subscriptionOf(subscription)) : null;
+        },
+        async forCustomer(customerId, options) {
+            const redaction = redactionWatcher();
+            const data = await transport.graphql({
+                api: 'admin',
+                query: CUSTOMER_SUBSCRIPTIONS_QUERY,
+                variables: { customerId },
+                onExtensions: redaction.onExtensions,
+            }, options);
+            if (data?.customerSubscriptions == null)
+                throw unexpected('customerSubscriptions');
+            return data.customerSubscriptions.map((item) => redaction.mark(subscriptionOf(item)));
+        },
+        async mandates(customerId, options) {
+            const mandates = await fieldOf(transport, CUSTOMER_MANDATES_QUERY, 'customerMandates', { customerId }, options);
+            if (mandates == null)
+                throw unexpected('customerMandates');
+            return mandates.map(mandateOf);
+        },
+        async readiness(options) {
+            const readiness = await fieldOf(transport, SUBSCRIPTION_CHANNEL_READINESS_QUERY, 'subscriptionChannelReadiness', {}, options);
+            if (readiness == null)
+                throw unexpected('subscriptionChannelReadiness');
+            return readiness;
+        },
+    };
+}