/*
 * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
 */

import { subscriptionsActivateSubscription } from "../funcs/subscriptions-activate-subscription.js";
import { subscriptionsAddSubscriptionAddon } from "../funcs/subscriptions-add-subscription-addon.js";
import { subscriptionsCancelSubscriptionSchedule } from "../funcs/subscriptions-cancel-subscription-schedule.js";
import { subscriptionsCancelSubscription } from "../funcs/subscriptions-cancel-subscription.js";
import { subscriptionsCreateSubscriptionLineItem } from "../funcs/subscriptions-create-subscription-line-item.js";
import { subscriptionsCreateSubscription } from "../funcs/subscriptions-create-subscription.js";
import { subscriptionsDeleteSubscriptionLineItem } from "../funcs/subscriptions-delete-subscription-line-item.js";
import { subscriptionsExecuteSubscriptionChange } from "../funcs/subscriptions-execute-subscription-change.js";
import { subscriptionsExecuteSubscriptionModify } from "../funcs/subscriptions-execute-subscription-modify.js";
import { subscriptionsExecuteSubscriptionPlanChangeV2 } from "../funcs/subscriptions-execute-subscription-plan-change-v2.js";
import { subscriptionsGetSubscriptionAddonAssociations } from "../funcs/subscriptions-get-subscription-addon-associations.js";
import { subscriptionsGetSubscriptionEntitlements } from "../funcs/subscriptions-get-subscription-entitlements.js";
import { subscriptionsGetSubscriptionSchedule } from "../funcs/subscriptions-get-subscription-schedule.js";
import { subscriptionsGetSubscriptionUpcomingGrants } from "../funcs/subscriptions-get-subscription-upcoming-grants.js";
import { subscriptionsGetSubscriptionUsage } from "../funcs/subscriptions-get-subscription-usage.js";
import { subscriptionsGetSubscriptionV2 } from "../funcs/subscriptions-get-subscription-v2.js";
import { subscriptionsGetSubscription } from "../funcs/subscriptions-get-subscription.js";
import { subscriptionsListAllSubscriptionSchedules } from "../funcs/subscriptions-list-all-subscription-schedules.js";
import { subscriptionsListSubscriptionSchedules } from "../funcs/subscriptions-list-subscription-schedules.js";
import { subscriptionsPreviewSubscriptionChange } from "../funcs/subscriptions-preview-subscription-change.js";
import { subscriptionsPreviewSubscriptionModify } from "../funcs/subscriptions-preview-subscription-modify.js";
import { subscriptionsPreviewSubscriptionPlanChangeV2 } from "../funcs/subscriptions-preview-subscription-plan-change-v2.js";
import { subscriptionsQuerySubscriptionLineItems } from "../funcs/subscriptions-query-subscription-line-items.js";
import { subscriptionsQuerySubscription } from "../funcs/subscriptions-query-subscription.js";
import { subscriptionsRemoveSubscriptionAddon } from "../funcs/subscriptions-remove-subscription-addon.js";
import { subscriptionsUpdateSubscriptionLineItem } from "../funcs/subscriptions-update-subscription-line-item.js";
import { subscriptionsUpdateSubscription } from "../funcs/subscriptions-update-subscription.js";
import { ClientSDK, RequestOptions } from "../lib/sdks.js";
import { unwrapAsync } from "../types/fp.js";
import * as models from "./models/index.js";

export class Subscriptions extends ClientSDK {
  /**
   * Create subscription
   *
   * @remarks
   * Use when onboarding a customer to a plan or starting a new subscription. Ideal for draft subscriptions (activate later) or active from start.
   */
  async createSubscription(
    request: models.CreateSubscriptionRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionResponse> {
    return unwrapAsync(subscriptionsCreateSubscription(
      this,
      request,
      options,
    ));
  }

  /**
   * Add addon to subscription
   *
   * @remarks
   * Deprecated: use POST /subscriptions/{id}/modify/execute with type "addon" and action "add", which also supports previewing the proration charge first.
   * Use when adding an optional product or add-on to an existing subscription (e.g. extra storage or support tier).
   *
   * @deprecated method: This will be removed in a future release, please migrate away from it as soon as possible.
   */
  async addSubscriptionAddon(
    request: models.AddAddonRequest,
    options?: RequestOptions,
  ): Promise<models.AddAddonToSubscriptionResponse> {
    return unwrapAsync(subscriptionsAddSubscriptionAddon(
      this,
      request,
      options,
    ));
  }

  /**
   * Remove addon from subscription
   *
   * @remarks
   * Deprecated: use POST /subscriptions/{id}/modify/execute with type "addon" and action "remove", which also supports previewing the proration credit first.
   * Use when removing an add-on from a subscription (e.g. downgrade or opt-out).
   *
   * @deprecated method: This will be removed in a future release, please migrate away from it as soon as possible.
   */
  async removeSubscriptionAddon(
    request: models.RemoveAddonRequest,
    options?: RequestOptions,
  ): Promise<models.SuccessResponse> {
    return unwrapAsync(subscriptionsRemoveSubscriptionAddon(
      this,
      request,
      options,
    ));
  }

  /**
   * Search subscription line items
   *
   * @remarks
   * List subscription line items with a JSON filter (subscription, customer, price, pagination, expand=prices, etc.).
   */
  async querySubscriptionLineItems(
    request: models.SubscriptionLineItemFilter,
    options?: RequestOptions,
  ): Promise<models.ListSubscriptionLineItemsResponse> {
    return unwrapAsync(subscriptionsQuerySubscriptionLineItems(
      this,
      request,
      options,
    ));
  }

  /**
   * Update subscription line item
   *
   * @remarks
   * Use when changing a subscription line item (e.g. quantity or price). Implemented by ending the current line and creating a new one for clean billing.
   */
  async updateSubscriptionLineItem(
    id: string,
    body: models.UpdateSubscriptionLineItemRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionLineItemResponse> {
    return unwrapAsync(subscriptionsUpdateSubscriptionLineItem(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Delete subscription line item
   *
   * @remarks
   * Use when removing a charge or seat from a subscription (e.g. downgrade). Line item ends; retained for history but no longer billed.
   */
  async deleteSubscriptionLineItem(
    id: string,
    body: models.DeleteSubscriptionLineItemRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionLineItemResponse> {
    return unwrapAsync(subscriptionsDeleteSubscriptionLineItem(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Query subscriptions
   *
   * @remarks
   * Use when listing or searching subscriptions (e.g. admin view or customer subscription list). Returns a paginated list; supports filtering by customer, plan, status.
   */
  async querySubscription(
    request: models.SubscriptionFilter,
    options?: RequestOptions,
  ): Promise<models.ListSubscriptionsResponse> {
    return unwrapAsync(subscriptionsQuerySubscription(
      this,
      request,
      options,
    ));
  }

  /**
   * Get usage by subscription
   *
   * @remarks
   * Use when showing usage for a subscription (e.g. in a portal or for overage checks). Supports time range and filters.
   */
  async getSubscriptionUsage(
    request: models.GetUsageBySubscriptionRequest,
    options?: RequestOptions,
  ): Promise<models.GetUsageBySubscriptionResponse> {
    return unwrapAsync(subscriptionsGetSubscriptionUsage(
      this,
      request,
      options,
    ));
  }

  /**
   * Get subscription
   *
   * @remarks
   * Use when you need to load a single subscription (e.g. for a billing portal or to check status).
   */
  async getSubscription(
    id: string,
    options?: RequestOptions,
  ): Promise<models.SubscriptionResponse> {
    return unwrapAsync(subscriptionsGetSubscription(
      this,
      id,
      options,
    ));
  }

  /**
   * Update subscription
   *
   * @remarks
   * Use when changing subscription details (e.g. quantity, billing anchor, or parent). Supports partial update; send "" to clear parent_subscription_id.
   */
  async updateSubscription(
    id: string,
    body: models.UpdateSubscriptionRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionResponse> {
    return unwrapAsync(subscriptionsUpdateSubscription(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Activate draft subscription
   *
   * @remarks
   * Use when turning a draft subscription live (e.g. after collecting payment or completing setup). Once activated, billing and entitlements apply.
   */
  async activateSubscription(
    id: string,
    body: models.ActivateDraftSubscriptionRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionResponse> {
    return unwrapAsync(subscriptionsActivateSubscription(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Get active addon associations
   *
   * @remarks
   * Use when listing which add-ons are currently attached to a subscription (e.g. for display or editing).
   */
  async getSubscriptionAddonAssociations(
    id: string,
    options?: RequestOptions,
  ): Promise<Array<models.AddonAssociationResponse>> {
    return unwrapAsync(subscriptionsGetSubscriptionAddonAssociations(
      this,
      id,
      options,
    ));
  }

  /**
   * Cancel subscription
   *
   * @remarks
   * Use when a customer churns or downgrades. Supports immediate or end-of-period cancellation and proration. Ideal for self-serve or support-driven cancellations.
   */
  async cancelSubscription(
    id: string,
    body: models.CancelSubscriptionRequest,
    options?: RequestOptions,
  ): Promise<models.CancelSubscriptionResponse> {
    return unwrapAsync(subscriptionsCancelSubscription(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Execute subscription plan change
   *
   * @remarks
   * Use when applying a plan change (e.g. upgrade or downgrade). Executes proration and generates invoice or credit as needed.
   */
  async executeSubscriptionChange(
    id: string,
    body: models.SubscriptionChangeRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionChangeExecuteResponse> {
    return unwrapAsync(subscriptionsExecuteSubscriptionChange(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Preview subscription plan change
   *
   * @remarks
   * Use when showing a customer the cost of a plan change before they confirm (e.g. upgrade/downgrade preview with proration).
   */
  async previewSubscriptionChange(
    id: string,
    body: models.SubscriptionChangeRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionChangePreviewResponse> {
    return unwrapAsync(subscriptionsPreviewSubscriptionChange(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Execute a plan change (v2, swap in place)
   *
   * @remarks
   * Change a subscription's plan in place. Subscription id, billing anchor and period bounds are preserved; line items are sliced and settled in one transaction.
   *
   * change_at controls timing. Omitted or 'immediate' applies the change now. 'end_of_period' records a pending schedule that executes at the subscription's current period end: the response returns is_scheduled, schedule_id and scheduled_at instead of a completed change, and nothing is swapped or billed until the boundary.
   *
   * scheduled_at is resolved from the subscription's current period end at request time. If that period end is already in the past (a backdated start date, a resumed pause, or worker downtime can all leave a subscription behind), the change is due immediately and fires on the next billing scan rather than a period away — inspect scheduled_at to see this.
   *
   * Only one plan change may be pending per subscription. By default (on_conflict_policies.on_pending_schedule = 'reject') a second request returns 400; cancel the existing schedule via POST /subscriptions/schedules/{schedule_id}/cancel first. Pending schedules are listable via GET /subscriptions/{id}/schedules.
   *
   * Set on_conflict_policies.on_pending_schedule to 'supersede' to replace the queued change instead: the pending schedule is cancelled and this request applied in the same transaction, so both land or neither does. The cancelled schedule ids are returned in superseded_schedules, and preview reports the same list without writing.
   */
  async executeSubscriptionPlanChangeV2(
    id: string,
    body: models.SubscriptionChangeV2Request,
    options?: RequestOptions,
  ): Promise<models.SubscriptionChangeV2Response> {
    return unwrapAsync(subscriptionsExecuteSubscriptionPlanChangeV2(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Preview a plan change (v2, swap in place)
   *
   * @remarks
   * Preview a subscription plan change without writing. Swap-in-place: subscription id, billing anchor and period bounds are preserved.
   */
  async previewSubscriptionPlanChangeV2(
    id: string,
    body: models.SubscriptionChangeV2Request,
    options?: RequestOptions,
  ): Promise<models.SubscriptionChangeV2Response> {
    return unwrapAsync(subscriptionsPreviewSubscriptionPlanChangeV2(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Get subscription entitlements
   *
   * @remarks
   * Use when checking what features or limits a subscription has (e.g. entitlement checks or feature gating). Optional feature_ids to filter.
   */
  async getSubscriptionEntitlements(
    id: string,
    featureIds?: Array<string> | undefined,
    options?: RequestOptions,
  ): Promise<models.SubscriptionEntitlementsResponse> {
    return unwrapAsync(subscriptionsGetSubscriptionEntitlements(
      this,
      id,
      featureIds,
      options,
    ));
  }

  /**
   * Get upcoming credit grant applications
   *
   * @remarks
   * Use when showing upcoming or pending credits for a subscription (e.g. in a portal or for forecasting).
   */
  async getSubscriptionUpcomingGrants(
    id: string,
    options?: RequestOptions,
  ): Promise<models.ListCreditGrantApplicationsResponse> {
    return unwrapAsync(subscriptionsGetSubscriptionUpcomingGrants(
      this,
      id,
      options,
    ));
  }

  /**
   * Create subscription line item
   *
   * @remarks
   * Use when adding a new charge or seat to a subscription (e.g. extra seat or one-time add). Supports price_id or inline price.
   */
  async createSubscriptionLineItem(
    id: string,
    body: models.CreateSubscriptionLineItemRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionLineItemResponse> {
    return unwrapAsync(subscriptionsCreateSubscriptionLineItem(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Execute subscription modification
   *
   * @remarks
   * Execute a mid-cycle subscription modification (inheritance, quantity change, grouped invoicing, trial end, coupon, tax, or addon add/remove).
   */
  async executeSubscriptionModify(
    id: string,
    body: models.ExecuteSubscriptionModifyRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionModifyResponse> {
    return unwrapAsync(subscriptionsExecuteSubscriptionModify(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Preview subscription modification
   *
   * @remarks
   * Preview the impact of a mid-cycle subscription modification (inheritance, quantity change, grouped invoicing, trial end, coupon, tax, or addon add/remove) without committing changes.
   */
  async previewSubscriptionModify(
    id: string,
    body: models.ExecuteSubscriptionModifyRequest,
    options?: RequestOptions,
  ): Promise<models.SubscriptionModifyResponse> {
    return unwrapAsync(subscriptionsPreviewSubscriptionModify(
      this,
      id,
      body,
      options,
    ));
  }

  /**
   * Get subscription (V2)
   *
   * @remarks
   * Use when you need a subscription with related data (line items, prices, plan). Supports expand for detailed payloads without extra round-trips.
   */
  async getSubscriptionV2(
    id: string,
    expand?: string | undefined,
    options?: RequestOptions,
  ): Promise<models.SubscriptionResponseV2> {
    return unwrapAsync(subscriptionsGetSubscriptionV2(
      this,
      id,
      expand,
      options,
    ));
  }

  /**
   * List all subscription schedules
   *
   * @remarks
   * Use when listing or searching scheduled changes across subscriptions (e.g. admin view). Returns schedules with optional filtering.
   */
  async listAllSubscriptionSchedules(
    pendingOnly?: boolean | undefined,
    subscriptionId?: string | undefined,
    limit?: number | undefined,
    offset?: number | undefined,
    options?: RequestOptions,
  ): Promise<models.GetPendingSchedulesResponse> {
    return unwrapAsync(subscriptionsListAllSubscriptionSchedules(
      this,
      pendingOnly,
      subscriptionId,
      limit,
      offset,
      options,
    ));
  }

  /**
   * Get subscription schedule
   *
   * @remarks
   * Use when you need to load a single scheduled change (e.g. to show when a plan change or renewal takes effect).
   */
  async getSubscriptionSchedule(
    id: string,
    options?: RequestOptions,
  ): Promise<models.SubscriptionScheduleResponse> {
    return unwrapAsync(subscriptionsGetSubscriptionSchedule(
      this,
      id,
      options,
    ));
  }

  /**
   * Cancel subscription schedule
   *
   * @remarks
   * Use when cancelling a scheduled change (e.g. customer changed mind). Identify by schedule ID in path or by subscription ID + schedule type in body.
   */
  async cancelSubscriptionSchedule(
    scheduleId: string,
    body?: models.CancelScheduleRequest | undefined,
    options?: RequestOptions,
  ): Promise<models.CancelScheduleResponse> {
    return unwrapAsync(subscriptionsCancelSubscriptionSchedule(
      this,
      scheduleId,
      body,
      options,
    ));
  }

  /**
   * List subscription schedules
   *
   * @remarks
   * Use when listing scheduled changes for a subscription (e.g. upcoming plan change or renewal). Returns all schedules for that subscription.
   */
  async listSubscriptionSchedules(
    subscriptionId: string,
    options?: RequestOptions,
  ): Promise<models.GetPendingSchedulesResponse> {
    return unwrapAsync(subscriptionsListSubscriptionSchedules(
      this,
      subscriptionId,
      options,
    ));
  }
}