api/spec/packages/aip/src/subscriptions/operations.tsp

import "@typespec/http";
import "@typespec/openapi";
import "@typespec/openapi3";
import "../shared/index.tsp";
import "../common/error.tsp";
import "../common/pagination.tsp";
import "../common/parameters.tsp";
import "./subscription.tsp";
import "./subscriptionaddon.tsp";

using TypeSpec.Http;
using TypeSpec.OpenAPI;

namespace Subscriptions;

/**
 * Request for canceling a subscription.
 */
@friendlyName("BillingSubscriptionCancel")
model SubscriptionCancel {
  /**
   * If not provided the subscription is canceled immediately.
   */
  timing?: SubscriptionEditTiming = SubscriptionEditTimingEnum.Immediate;
}

/**
 * Request for changing a subscription.
 */
@friendlyName("BillingSubscriptionChange")
model SubscriptionChange {
  ...OmitProperties<SubscriptionCreate, "customer_id" | "customer_key">;

  /**
   * Timing configuration for the change, when the change should take effect. For
   * changing a subscription, the accepted values depend on the subscription
   * configuration.
   */
  timing: SubscriptionEditTiming;
}

/**
 * Response for changing a subscription.
 */
@friendlyName("BillingSubscriptionChangeResponse")
model SubscriptionChangeResponse {
  /**
   * The current subscription before the change.
   */
  current: Subscription;

  /**
   * The new state of the subscription after the change.
   */
  next: Subscription;
}

/**
 * Filter options for listing subscriptions.
 */
#suppress "@openmeter/api-spec-aip/repeated-prefix-grouping" "plan_id and plan_key should not be grouped"
@friendlyName("ListSubscriptionsParamsFilter")
model ListSubscriptionsParamsFilter {
  #suppress "@openmeter/api-spec-aip/doc-decorator" "shared model"
  id?: Common.ULIDFieldFilter;
  #suppress "@openmeter/api-spec-aip/doc-decorator" "shared model"
  customer_id?: Common.ULIDFieldFilter;
  #suppress "@openmeter/api-spec-aip/doc-decorator" "shared model"
  status?: Common.StringFieldFilterExact;
  #suppress "@openmeter/api-spec-aip/doc-decorator" "shared model"
  plan_id?: Common.ULIDFieldFilter;
  #suppress "@openmeter/api-spec-aip/doc-decorator" "shared model"
  plan_key?: Common.StringFieldFilterExact;
}

interface SubscriptionsOperations {
  @post
  @operationId("create-subscription")
  @summary("Create subscription")
  create(@body subscription: SubscriptionCreate):
    | Shared.CreateResponse<Subscription>
    | Common.NotFound
    | Common.Conflict
    | Common.ErrorResponses;

  @get
  @operationId("list-subscriptions")
  @summary("List subscriptions")
  list(
    ...Common.PagePaginationQuery,

    /**
     * Sort subscriptions returned in the response. Supported sort attributes are:
     *
     * - `id`
     * - `active_from` (default)
     * - `active_to`
     *
     * The `asc` suffix is optional as the default sort order is ascending. The `desc`
     * suffix is used to specify a descending order.
     */
    @query(#{ name: "sort" })
    sort?: Common.SortQuery,

    /**
     * Filter subscriptions.
     */
    @query(#{ style: "deepObject", explode: true })
    filter?: ListSubscriptionsParamsFilter,
  ):
    | Shared.PagePaginatedResponse<Subscription>
    | Common.NotFound
    | Common.ErrorResponses;

  @get
  @operationId("get-subscription")
  @summary("Get subscription")
  get(@path subscriptionId: Shared.ULID):
    | Shared.GetResponse<Subscription>
    | Common.NotFound
    | Common.ErrorResponses;

  /**
   * Cancels the subscription. Will result in a scheduling conflict if there are
   * other subscriptions scheduled to start after the cancelation time.
   */
  @post
  @operationId("cancel-subscription")
  @summary("Cancel subscription")
  @route("/{subscriptionId}/cancel")
  cancel(@path subscriptionId: Shared.ULID, @body body: SubscriptionCancel):
    | Shared.UpdateResponse<Subscription>
    | Common.NotFound
    | Common.Conflict
    | Common.ErrorResponses;

  /**
   * Unschedules the subscription cancelation.
   */
  @post
  @operationId("unschedule-cancelation")
  @summary("Unschedule subscription cancelation")
  @route("/{subscriptionId}/unschedule-cancelation")
  unscheduleCancelation(@path subscriptionId: Shared.ULID):
    | Shared.UpdateResponse<Subscription>
    | Common.NotFound
    | Common.Conflict
    | Common.ErrorResponses;

  /**
   * Closes a running subscription and starts a new one according to the
   * specification. Can be used for upgrades, downgrades, and plan changes.
   */
  @post
  @operationId("change-subscription")
  @summary("Change subscription")
  @route("/{subscriptionId}/change")
  change(
    @path subscriptionId: Shared.ULID,

    @body
    body: SubscriptionChange,
  ):
    | SubscriptionChangeResponse
    | Common.NotFound
    | Common.Conflict
    | Common.ErrorResponses;
}

interface SubscriptionAddonOperations {
  /**
   * Add add-on to a subscription.
   */
  @post
  @operationId("create-subscription-addon")
  @summary("Create a new subscription add-on")
  @extension(Shared.UnstableExtension, true)
  @extension(Shared.InternalExtension, true)
  create(
    @path subscriptionId: Shared.ULID,
    @body request: Shared.CreateRequest<SubscriptionAddon>,
  ):
    | Shared.CreateResponse<SubscriptionAddon>
    | Common.ErrorResponses
    | Common.NotFound
    | Common.Conflict;

  /**
   * List the add-ons of a subscription.
   */
  @get
  @operationId("list-subscription-addons")
  @summary("List subscription addons")
  @extension(Shared.UnstableExtension, true)
  list(
    @path subscriptionId: Shared.ULID,
    ...Common.PagePaginationQuery,

    /**
     * Sort subscription addons returned in the response. Supported sort attributes
     * are:
     *
     * - `id`
     * - `created_at` (default)
     * - `updated_at`
     *
     * The `asc` suffix is optional as the default sort order is ascending. The `desc`
     * suffix is used to specify a descending order.
     */
    @query(#{ name: "sort" })
    sort?: Common.SortQuery,
  ):
    | Shared.PagePaginatedResponse<SubscriptionAddon>
    | Common.NotFound
    | Common.ErrorResponses;

  /**
   * Get an add-on association for a subscription.
   */
  @get
  @route("/{subscriptionAddonId}")
  @operationId("get-subscription-addon")
  @summary("Get add-on association for subscription")
  @extension(Shared.UnstableExtension, true)
  getAddon(
    @path subscriptionId: Shared.ULID,
    @path subscriptionAddonId: Shared.ULID,
  ):
    | Shared.GetResponse<SubscriptionAddon>
    | Common.ErrorResponses
    | Common.NotFound;
}