@usethrottle/subscriptions 2.0.0 → 3.0.0

package/dist/{errors-Bloar0hq.d.ts → errors-CfjKk5CU.d.ts}

@@ -1,5 +1,5 @@
 import { CSSProperties, ReactNode } from 'react';
-import { ThrottleError } from '@usethrottle/errors';
+import { ThrottleError, ThrottleErrorArgs } from '@usethrottle/errors';
 
 type SubscriptionStatus = 'active' | 'paused' | 'cancelled' | 'past_due' | 'trialing' | 'unpaid' | 'completed';
 type SubscriptionInterval = 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'yearly' | 'custom';
@@ -24,6 +24,8 @@ interface Subscription {
     /** When the final installment succeeded. Set only on `completed`. */
     completedAt: string | null;
     amount: number;
+    /** #688 — number of seats. Per-seat price is `amount`; the period charge is `amount × quantity`. Defaults to 1. */
+    quantity: number;
     currency: string;
     currentPeriodStart: string;
     currentPeriodEnd: string;
@@ -42,9 +44,42 @@ interface Subscription {
     taxAddressSnapshot?: SubscriptionTaxAddress | null;
     /** `checkout` when captured at signup, `manual` once a merchant edited it. */
     taxAddressSource?: 'checkout' | 'manual' | null;
+    /**
+     * Set by the renewal job when renewals are failing (`system_error`) or when
+     * a card was charged but the renewal could not be recorded (`orphan_charge`
+     * — renewals are paused until Throttle support resolves it). `null` when
+     * nothing is wrong.
+     */
+    renewalIssue: SubscriptionRenewalIssue | null;
+    /**
+     * Present only on the response from `changePlan()` / `changeQuantity()` —
+     * how much of the old plan's unused time credited the new charge.
+     */
+    proration?: SubscriptionProration | null;
     createdAt?: string;
     updatedAt?: string;
 }
+interface SubscriptionRenewalIssue {
+    kind: 'system_error' | 'orphan_charge';
+    /** Stable code; `message` is its fixed, merchant-safe sentence. */
+    reason: 'tax_quote_failed' | 'internal_error' | 'record_failed';
+    count: number;
+    firstAt?: string;
+    lastAt: string;
+    message: string;
+    alertedAt?: string | null;
+    charge?: {
+        transactionId: string | null;
+        amount: number;
+        currency: string;
+        periodStart?: string;
+    } | null;
+}
+interface SubscriptionProration {
+    creditCents?: number;
+    chargedCents?: number;
+    fullAmount?: number;
+}
 interface SubscriptionTaxAddress {
     addressLine1?: string | null;
     addressLine2?: string | null;
@@ -137,9 +172,52 @@ interface CancelSubscriptionInput {
     id: string;
     atPeriodEnd?: boolean;
 }
-interface ChangePlanInput extends UpdateSubscriptionInput {
+/**
+ * `changePlan()`'s input, mirroring `POST /api/v1/subscriptions/{id}/change-plan`:
+ * a real plan change, prorated and charged when `effective: 'now'`. For the
+ * old term-only edit (rename a plan, correct an amount, with no proration or
+ * charge), use `update()` instead — see its migration note in the 3.0.0
+ * changeset.
+ */
+interface ChangePlanInput {
     id: string;
     planReference: string;
+    planName?: string;
+    interval?: SubscriptionInterval;
+    intervalUnit?: SubscriptionIntervalUnit;
+    intervalCount?: number;
+    amount: number;
+    /** `'now'` prorates and charges immediately; `'period_end'` schedules it, charging nothing today. */
+    effective: 'now' | 'period_end';
+}
+/** `changeQuantity()`'s input, mirroring `POST /api/v1/subscriptions/{id}/change-quantity`. */
+interface ChangeQuantityInput {
+    quantity: number;
+    /** `'now'` prorates and charges immediately; `'period_end'` schedules it, charging nothing today. */
+    effective: 'now' | 'period_end';
+}
+/** `recordUsage()`'s input, mirroring `POST /api/v1/subscriptions/{id}/usage`. */
+interface RecordUsageInput {
+    kind: string;
+    unitCount: number;
+    unitPriceCents: number;
+}
+/** A usage item recorded against a subscription's current billing period. */
+interface SubscriptionUsageItem {
+    id: string;
+    subscriptionId: string;
+    kind: string;
+    unitCount: number;
+    unitPriceCents: number;
+    totalCents: number;
+    periodStart: string;
+    periodEnd: string;
+    createdAt: string;
+}
+/** `waivePeriod()`'s input, mirroring `POST /api/v1/subscriptions/{id}/waive-period`. */
+interface WaivePeriodInput {
+    /** Required: the only record of why the period was not collected. */
+    reason: string;
 }
 interface RecurringIntent {
     plan: string;
@@ -287,12 +365,17 @@ interface SubscriptionsClientContract {
     get(id: string): Promise<Subscription>;
     update(id: string, input: UpdateSubscriptionInput): Promise<Subscription>;
     changePlan(input: ChangePlanInput): Promise<Subscription>;
+    changeQuantity(id: string, input: ChangeQuantityInput): Promise<Subscription>;
     pause(id: string): Promise<Subscription>;
     resume(id: string): Promise<Subscription>;
     cancel(id: string, input?: {
         atPeriodEnd?: boolean;
         refund?: 'none' | 'prorated' | 'last_cycle';
     }): Promise<Subscription>;
+    retryCharge(id: string): Promise<Subscription>;
+    waivePeriod(id: string, input: WaivePeriodInput): Promise<Subscription>;
+    recordUsage(id: string, input: RecordUsageInput): Promise<SubscriptionUsageItem>;
+    listUsage(id: string): Promise<SubscriptionUsageItem[]>;
     createCheckoutSession(input: CreateCheckoutSessionInput): Promise<CheckoutSession>;
     checkTrialEligibility(input: TrialEligibilityInput): Promise<TrialEligibilityResult>;
     getCustomerByExternalId(externalId: string): Promise<Customer | null>;
@@ -311,8 +394,50 @@ declare class SubscriptionsClient implements SubscriptionsClientContract {
     create(input: CreateSubscriptionInput): Promise<Subscription>;
     list(params?: ListSubscriptionsParams): Promise<PaginatedSubscriptions>;
     get(id: string): Promise<Subscription>;
+    /**
+     * A term-only edit: rename the plan, correct the cadence or the amount on
+     * the row — no proration, no charge, no period reset. Mirrors
+     * `PATCH /api/v1/subscriptions/{id}`. This is what `changePlan()` did
+     * before 3.0.0; use `changePlan()` now for an actual plan change.
+     */
     update(id: string, input: UpdateSubscriptionInput): Promise<Subscription>;
+    /**
+     * A real plan change: prorated and charged immediately when
+     * `effective: 'now'`, or scheduled for period end with no charge today.
+     * Mirrors `POST /api/v1/subscriptions/{id}/change-plan`. The resolved
+     * subscription carries `proration` when the server computed one.
+     *
+     * This is NOT the old `changePlan()` (a PATCH-style term edit with no
+     * proration and no charge) — use `update()` for that.
+     */
     changePlan(input: ChangePlanInput): Promise<Subscription>;
+    /**
+     * Change the seat quantity: prorated and charged immediately when
+     * `effective: 'now'`, or scheduled for period end with no charge today.
+     * Mirrors `POST /api/v1/subscriptions/{id}/change-quantity`.
+     */
+    changeQuantity(id: string, input: ChangeQuantityInput): Promise<Subscription>;
+    /**
+     * Charge a past-due subscription's card again now, instead of waiting for
+     * the next scheduled dunning retry. Mirrors
+     * `POST /api/v1/subscriptions/{id}/retry-charge`.
+     */
+    retryCharge(id: string): Promise<Subscription>;
+    /**
+     * Forgive the current past-due period — the merchant is not collecting it.
+     * Mirrors `POST /api/v1/subscriptions/{id}/waive-period`.
+     */
+    waivePeriod(id: string, input: WaivePeriodInput): Promise<Subscription>;
+    /**
+     * Record (upsert) a usage item for the subscription's current billing
+     * period. Mirrors `POST /api/v1/subscriptions/{id}/usage`.
+     */
+    recordUsage(id: string, input: RecordUsageInput): Promise<SubscriptionUsageItem>;
+    /**
+     * List usage items recorded for the subscription's current billing period.
+     * Mirrors `GET /api/v1/subscriptions/{id}/usage`.
+     */
+    listUsage(id: string): Promise<SubscriptionUsageItem[]>;
     pause(id: string): Promise<Subscription>;
     resume(id: string): Promise<Subscription>;
     cancel(id: string, input?: {
@@ -352,7 +477,8 @@ declare class ThrottleSubscriptionsError extends ThrottleError {
         message: string;
         statusCode: number;
         details?: unknown;
+        responseHeaders?: ThrottleErrorArgs['responseHeaders'];
     });
 }
 
-export { type TrialEligibilityResult as A, createSubscriptionsClient as B, type CancelSubscriptionInput as C, type DunningBannerProps as D, type ListSubscriptionsParams as L, type MutationState as M, type PaginatedSubscriptions as P, type QueryOptions as Q, type RecurringIntent as R, type Subscription as S, type ThrottleEnvelope as T, type UpdateSubscriptionInput as U, type ChangePlanInput as a, type CheckoutCollectInput as b, type CheckoutCustomerInput as c, type CheckoutSession as d, type CreateCheckoutSessionInput as e, type CreateSubscriptionInput as f, type Customer as g, type CustomerPaymentMethod as h, type Pagination as i, type QueryState as j, type SubscriptionFetcher as k, type SubscriptionInterval as l, type SubscriptionIntervalUnit as m, type SubscriptionInvoiceRefund as n, type SubscriptionProviderProps as o, type SubscriptionSort as p, type SubscriptionStatus as q, type SubscriptionStatusBadgeProps as r, type SubscriptionTaxAddress as s, SubscriptionsClient as t, type SubscriptionsClientContract as u, type SubscriptionsClientOptions as v, ThrottleSubscriptionsError as w, type TrialCountdownProps as x, type TrialEligibilityInput as y, type TrialEligibilityReason as z };
+export { type SubscriptionsClientOptions as A, ThrottleSubscriptionsError as B, type CancelSubscriptionInput as C, type DunningBannerProps as D, type TrialCountdownProps as E, type TrialEligibilityInput as F, type TrialEligibilityReason as G, type TrialEligibilityResult as H, createSubscriptionsClient as I, type ListSubscriptionsParams as L, type MutationState as M, type PaginatedSubscriptions as P, type QueryOptions as Q, type RecordUsageInput as R, type Subscription as S, type ThrottleEnvelope as T, type UpdateSubscriptionInput as U, type WaivePeriodInput as W, type ChangePlanInput as a, type ChangeQuantityInput as b, type CheckoutCollectInput as c, type CheckoutCustomerInput as d, type CheckoutSession as e, type CreateCheckoutSessionInput as f, type CreateSubscriptionInput as g, type Customer as h, type CustomerPaymentMethod as i, type Pagination as j, type QueryState as k, type RecurringIntent as l, type SubscriptionFetcher as m, type SubscriptionInterval as n, type SubscriptionIntervalUnit as o, type SubscriptionInvoiceRefund as p, type SubscriptionProration as q, type SubscriptionProviderProps as r, type SubscriptionRenewalIssue as s, type SubscriptionSort as t, type SubscriptionStatus as u, type SubscriptionStatusBadgeProps as v, type SubscriptionTaxAddress as w, type SubscriptionUsageItem as x, SubscriptionsClient as y, type SubscriptionsClientContract as z };

package/dist/index.cjs

@@ -85,6 +85,7 @@ function normalizeSubscription(raw) {
     paymentsMade: Number(raw?.paymentsMade ?? 0),
     completedAt: optionalIsoDateString(raw?.completedAt),
     amount: Number(raw?.amount ?? 0),
+    quantity: Number(raw?.quantity ?? 1),
     currency: optionalString(raw?.currency) ?? "USD",
     currentPeriodStart: requiredDateString(
       raw?.currentPeriodStart,
@@ -101,10 +102,47 @@ function normalizeSubscription(raw) {
     pausedAt: optionalDateString(raw?.pausedAt),
     cancelledAt: optionalDateString(raw?.cancelledAt),
     metadata: objectOrEmpty(raw?.metadata),
+    renewalIssue: normalizeRenewalIssue(raw?.renewalIssue),
+    proration: raw?.proration ? {
+      creditCents: raw.proration.creditCents,
+      chargedCents: raw.proration.chargedCents,
+      fullAmount: raw.proration.fullAmount
+    } : void 0,
     createdAt: optionalDateString(raw?.createdAt) ?? void 0,
     updatedAt: optionalDateString(raw?.updatedAt) ?? void 0
   };
 }
+function normalizeRenewalIssue(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  return {
+    kind: raw.kind,
+    reason: raw.reason,
+    count: Number(raw.count ?? 0),
+    firstAt: optionalString(raw.firstAt) ?? void 0,
+    lastAt: requiredString(raw.lastAt, "subscription.renewalIssue.lastAt"),
+    message: raw.message ?? "",
+    alertedAt: optionalDateString(raw.alertedAt),
+    charge: raw.charge ? {
+      transactionId: optionalString(raw.charge.transactionId),
+      amount: Number(raw.charge.amount ?? 0),
+      currency: optionalString(raw.charge.currency) ?? "USD",
+      periodStart: optionalString(raw.charge.periodStart) ?? void 0
+    } : null
+  };
+}
+function normalizeUsageItem(raw) {
+  return {
+    id: requiredString(raw?.id, "usageItem.id"),
+    subscriptionId: requiredString(raw?.subscriptionId, "usageItem.subscriptionId"),
+    kind: raw?.kind ?? "",
+    unitCount: Number(raw?.unitCount ?? 0),
+    unitPriceCents: Number(raw?.unitPriceCents ?? 0),
+    totalCents: Number(raw?.totalCents ?? 0),
+    periodStart: requiredDateString(raw?.periodStart, "usageItem.periodStart"),
+    periodEnd: requiredDateString(raw?.periodEnd, "usageItem.periodEnd"),
+    createdAt: requiredDateString(raw?.createdAt, "usageItem.createdAt")
+  };
+}
 function normalizeCustomer(raw) {
   if (!raw) return null;
   return {
@@ -243,7 +281,8 @@ var SubscriptionsClient = class {
           code: json.error?.code ?? "unknown_error",
           message: json.error?.message ?? `HTTP ${res.status}`,
           statusCode: res.status,
-          details: json.error?.details
+          details: json.error?.details,
+          responseHeaders: res.headers
         });
       }
       return json;
@@ -299,6 +338,12 @@ var SubscriptionsClient = class {
     );
     return normalizeSubscription(data);
   }
+  /**
+   * A term-only edit: rename the plan, correct the cadence or the amount on
+   * the row — no proration, no charge, no period reset. Mirrors
+   * `PATCH /api/v1/subscriptions/{id}`. This is what `changePlan()` did
+   * before 3.0.0; use `changePlan()` now for an actual plan change.
+   */
   async update(id, input) {
     const data = await this.request(
       "PATCH",
@@ -307,9 +352,92 @@ var SubscriptionsClient = class {
     );
     return normalizeSubscription(data);
   }
-  changePlan(input) {
+  /**
+   * A real plan change: prorated and charged immediately when
+   * `effective: 'now'`, or scheduled for period end with no charge today.
+   * Mirrors `POST /api/v1/subscriptions/{id}/change-plan`. The resolved
+   * subscription carries `proration` when the server computed one.
+   *
+   * This is NOT the old `changePlan()` (a PATCH-style term edit with no
+   * proration and no charge) — use `update()` for that.
+   */
+  async changePlan(input) {
     const { id, ...body } = input;
-    return this.update(id, body);
+    const data = await this.request(
+      "POST",
+      `/api/v1/subscriptions/${encodeURIComponent(id)}/change-plan`,
+      {
+        planReference: body.planReference,
+        planName: body.planName,
+        interval: body.interval,
+        intervalUnit: body.intervalUnit,
+        intervalCount: body.intervalCount,
+        amount: body.amount,
+        effective: body.effective
+      }
+    );
+    return normalizeSubscription(data);
+  }
+  /**
+   * Change the seat quantity: prorated and charged immediately when
+   * `effective: 'now'`, or scheduled for period end with no charge today.
+   * Mirrors `POST /api/v1/subscriptions/{id}/change-quantity`.
+   */
+  async changeQuantity(id, input) {
+    const data = await this.request(
+      "POST",
+      `/api/v1/subscriptions/${encodeURIComponent(id)}/change-quantity`,
+      { quantity: input.quantity, effective: input.effective }
+    );
+    return normalizeSubscription(data);
+  }
+  /**
+   * Charge a past-due subscription's card again now, instead of waiting for
+   * the next scheduled dunning retry. Mirrors
+   * `POST /api/v1/subscriptions/{id}/retry-charge`.
+   */
+  async retryCharge(id) {
+    const data = await this.request(
+      "POST",
+      `/api/v1/subscriptions/${encodeURIComponent(id)}/retry-charge`
+    );
+    return normalizeSubscription(data);
+  }
+  /**
+   * Forgive the current past-due period — the merchant is not collecting it.
+   * Mirrors `POST /api/v1/subscriptions/{id}/waive-period`.
+   */
+  async waivePeriod(id, input) {
+    const data = await this.request(
+      "POST",
+      `/api/v1/subscriptions/${encodeURIComponent(id)}/waive-period`,
+      { reason: input.reason }
+    );
+    return normalizeSubscription(data);
+  }
+  /**
+   * Record (upsert) a usage item for the subscription's current billing
+   * period. Mirrors `POST /api/v1/subscriptions/{id}/usage`.
+   */
+  async recordUsage(id, input) {
+    const data = await this.request(
+      "POST",
+      `/api/v1/subscriptions/${encodeURIComponent(id)}/usage`,
+      { kind: input.kind, unitCount: input.unitCount, unitPriceCents: input.unitPriceCents }
+    );
+    return normalizeUsageItem(data);
+  }
+  /**
+   * List usage items recorded for the subscription's current billing period.
+   * Mirrors `GET /api/v1/subscriptions/{id}/usage`.
+   */
+  async listUsage(id) {
+    const envelope = await this.requestEnvelope(
+      "GET",
+      `/api/v1/subscriptions/${encodeURIComponent(id)}/usage`
+    );
+    const items = envelope.items ?? [];
+    return items.map(normalizeUsageItem);
   }
   async pause(id) {
     const data = await this.request(