refactor(api): Plan API

* refactor plan Discount * add misssing visibility * add union type for Usage-based RateCard price
openmeterio · Nov 7, 2024 · 05f18f5 · 05f18f5
1 parent b0c4884
commit 05f18f5
Show file tree

Hide file tree

Showing 9 changed files with 1,886 additions and 2,197 deletions.
diff --git a/api/api.gen.go b/api/api.gen.go
diff --git a/api/client/go/client.gen.go b/api/client/go/client.gen.go
diff --git a/api/openapi.yaml b/api/openapi.yaml
diff --git a/api/spec/src/productcatalog/discounts.tsp b/api/spec/src/productcatalog/discounts.tsp
@@ -47,6 +47,14 @@ model DiscountPercentage {
   @minValue(0)
   @maxValue(100)
   percentage: float;
+
+  /**
+   * The rate cards that the discount applies to.
+   * When not specified, the discount applies to all rate cards.
+   */
+  @visibility("read", "create", "update")
+  @summary("Discounted RateCards")
+  rateCards?: Key[];
 }
 
 // NOTE(chrisgacsal): amount discount is going to be implemented in future releases
@@ -86,66 +94,3 @@ model DiscountPercentage {
 //   @summary("Usage")
 //   usage: float64;
 // }
-
-/**
- * A discount on plan. One of: percentage or amount.
- */
-@friendlyName("AppliedDiscount")
-@discriminator("type")
-union AppliedDiscount {
-  @summary("Percentage discount")
-  percentage: AppliedDiscountPercentage,
-
-  // @summary("Amount discount")
-  // amount: AppliedDiscountAmount,
-
-  // @summary("Usage discount")
-  // usage: AppliedDiscountUsage,
-}
-
-alias RateCardKey = Key;
-
-/**
- * Percentage discount on plan.
- */
-@friendlyName("AppliedDiscountPercentage")
-model AppliedDiscountPercentage {
-  ...DiscountPercentage;
-
-  /**
-   * The rate cards that the discount applies to.
-   * When not specified, the discount applies to all rate cards.
-   */
-  @summary("Applies To")
-  appliesTo?: RateCardKey[];
-}
-
-// /**
-//  * Percentage discount on plan.
-//  */
-// @friendlyName("AppliedDiscountUsage")
-// model AppliedDiscountUsage {
-//   ...DiscountUsage;
-
-//   /**
-//    * The rate cards that the discount applies to.
-//    * When not specified, the discount applies to all rate cards.
-//    */
-//   @summary("Applies To")
-//   appliesTo?: RateCardKey[];
-// }
-
-// /**
-//  * Amount discount on plan.
-//  */
-// @friendlyName("AppliedDiscountAmount")
-// model AppliedDiscountAmount {
-//   ...DiscountAmount;
-
-//   /**
-//    * The rate cards that the discount applies to.
-//    * When not specified, the discount applies to all rate cards.
-//    */
-//   @summary("Applies To")
-//   appliesTo?: RateCardKey[];
-// }
diff --git a/api/spec/src/productcatalog/plan.tsp b/api/spec/src/productcatalog/plan.tsp
@@ -52,18 +52,21 @@ model Plan {
   /**
    * The currency code of the plan.
    */
+  @visibility("read", "create")
   @summary("Currency")
   currency: CurrencyCode = "USD";
 
   /**
    * The date and time when the plan becomes effective. When not specified, the plan is a draft.
    */
+  @visibility("read")
   @summary("Effective start date")
   effectiveFrom?: DateTime;
 
   /**
    * The date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.
    */
+  @visibility("read")
   @summary("Effective end date")
   effectiveTo?: DateTime;
 
@@ -83,6 +86,7 @@ model Plan {
    * The plan phase or pricing ramp allows changing a plan's rate cards over time as a subscription progresses.
    * A phase switch occurs only at the end of a billing period, ensuring that a single subscription invoice will not include charges from different phase prices.
    */
+  @visibility("read", "create", "update")
   @summary("Plan phases")
   @minItems(1)
   phases: PlanPhase[];
@@ -98,17 +102,20 @@ model PlanPhase {
   /**
    * Unique key among the plan phases. Used to reference the phase in the subscription & plan.
    */
+  @visibility("read", "create")
   key: Key;
 
   /**
    * The rate cards of the plan.
    */
+  @visibility("read", "create", "update")
   @summary("Rate cards")
   rateCards: RateCard[];
 
   /**
    * The time after which the plan starts compared to subscription start
    */
+  @visibility("read", "create", "update")
   @summary("Start after")
   @encode(DurationKnownEncoding.ISO8601)
   @example(duration.fromISO("P1Y1D"))
@@ -117,8 +124,9 @@ model PlanPhase {
   /**
    * The discounts on the plan.
    */
+  @visibility("read", "create", "update")
   @summary("Discounts")
-  discounts?: AppliedDiscount[];
+  discounts?: Discount[];
 
   // /**
   //  * Predefined overrides of the plan that can apply changes to the rate cards, discounts, and other properties based on the selected variant.
@@ -182,9 +190,9 @@ model PlanVariantOverridePreset {
   };
 
   /*
-   * The discount on the plan.
+   * The discounts on the plan.
    */
-  discount?: AppliedDiscount;
+  discounts?: Discount[];
 }
 
 /**

diff --git a/api/spec/src/productcatalog/prices.tsp b/api/spec/src/productcatalog/prices.tsp
@@ -55,7 +55,7 @@ union PricePaymentTerm {
  */
 @friendlyName("FlatPrice")
 model FlatPrice {
-  @visibility("read", "create")
+  @visibility("read", "create", "update")
   type: PriceType.flat;
 
   /**
@@ -76,6 +76,7 @@ model FlatPriceWithPaymentTerm {
    * The payment term of the flat price.
    * Defaults to in advance.
    */
+  @visibility("read", "create", "update")
   paymentTerm?: PricePaymentTerm = PricePaymentTerm.inAdvance;
 }
 
@@ -84,7 +85,7 @@ model FlatPriceWithPaymentTerm {
  */
 @friendlyName("UnitPrice")
 model UnitPrice {
-  @visibility("read", "create")
+  @visibility("read", "create", "update")
   type: PriceType.unit;
 
   /**
@@ -108,7 +109,7 @@ enum TieredPriceMode {
  */
 @friendlyName("TieredPrice")
 model TieredPrice {
-  @visibility("read", "create")
+  @visibility("read", "create", "update")
   type: PriceType.tiered;
 
   /**

diff --git a/api/spec/src/productcatalog/ratecards.tsp b/api/spec/src/productcatalog/ratecards.tsp
@@ -94,6 +94,18 @@ model RateCardFlatFee {
   // discount?: DiscountPercentage | DiscountAmount;
 }
 
+/**
+ * The price of the usage based rate card.
+ */
+@friendlyName("RateCardUsageBasedPrice")
+@discriminator("type")
+@oneOf
+union RateCardUsageBasedPrice {
+  flat: FlatPriceWithPaymentTerm,
+  unit: UnitPriceWithCommitments,
+  tiered: TieredPriceWithCommitments,
+}
+
 /**
  * A usage-based rate card defines a price based on usage.
  */
@@ -109,18 +121,12 @@ model RateCardUsageBased {
   @encode(DurationKnownEncoding.ISO8601)
   billingCadence: duration;
 
-  /**
+  /*
    * The price of the rate card.
    * When null, the feature or service is free.
    */
   @visibility("read", "create", "update")
-  @summary("Price")
-  @example(#{ type: PriceType.unit, amount: "0.01", minimumAmount: "100" })
-  price:
-    | UnitPriceWithCommitments
-    | TieredPriceWithCommitments
-    | FlatPriceWithPaymentTerm
-    | null;
+  price: RateCardUsageBasedPrice | null;
 
   // NOTE(chrisgacsal): discount on RateCard level going to be implemented in upcoming releases
   // /**

diff --git a/api/spec/src/productcatalog/routes.tsp b/api/spec/src/productcatalog/routes.tsp
@@ -78,6 +78,15 @@ interface Plans {
     @extension("x-go-type", "string")
     @path
     planId: PlanIdOrKey,
+
+    /**
+     * Include latest version of the Plan instead of the version with
+     *
+     * Usage: `?includeLatest=true`
+     */
+    @query
+    @example(true)
+    includeLatest?: boolean = false,
   ): Plan | OpenMeter.NotFoundError | OpenMeter.CommonErrors;
 
   /**
@@ -93,7 +102,7 @@ interface Plans {
   } | OpenMeter.NotFoundError | OpenMeter.CommonErrors;
 
   /**
-   * Publish a new plan.
+   * Publish a plan version.
    */
   @post
   @route("/{planId}/publish")
@@ -105,13 +114,13 @@ interface Plans {
   } | OpenMeter.NotFoundError | OpenMeter.CommonErrors;
 
   /**
-   * Unpublish a new plan.
+   * Archive a plan version.
    */
   @post
-  @route("/{planId}/unpublish")
+  @route("/{planId}/archive")
   @sharedRoute
-  @operationId("unpublishPlan")
-  @summary("Unpublish plan")
+  @operationId("archivePlan")
+  @summary("Archive plan version")
   unpublish(@path planId: ULID): {
     @statusCode _: 204;
   } | OpenMeter.NotFoundError | OpenMeter.CommonErrors;
@@ -123,7 +132,7 @@ interface Plans {
   @post
   @route("/{planIdOrKey}/next")
   @sharedRoute
-  @operationId("newDraftPlan")
+  @operationId("nextPlan")
   @summary("New draft plan")
   next(
     @extension("x-go-type", "string")
@@ -161,7 +170,7 @@ interface PlanPhases {
    * Create new phase in plan.
    */
   @post
-  @operationId("createPlanPhases")
+  @operationId("createPlanPhase")
   @summary("Create new phase in plan")
   create(
     @path planId: ULID,
@@ -175,7 +184,7 @@ interface PlanPhases {
    * Update phase in plan.
    */
   @put
-  @operationId("updatePlanPhases")
+  @operationId("updatePlanPhase")
   @summary("Update phase in plan")
   update(
     @path planId: ULID,
@@ -189,7 +198,7 @@ interface PlanPhases {
    * Get phase in plan.
    */
   @get
-  @operationId("getPlanPhases")
+  @operationId("getPlanPhase")
   @summary("Get phase for plan")
   get(
     @path planId: ULID,
@@ -202,7 +211,7 @@ interface PlanPhases {
    * Once a phase is deleted it cannot be undeleted.
    */
   @delete
-  @operationId("deletePlanPhases")
+  @operationId("deletePlanPhase")
   @summary("Delete phase for plan")
   delete(@path planId: ULID, @path planPhaseKey: Key): {
     @statusCode _: 204;

diff --git a/api/spec/src/productcatalog/subscription.tsp b/api/spec/src/productcatalog/subscription.tsp
@@ -105,8 +105,8 @@ model SubscriptionPhaseCreate {
   /**
    * The discounts on the plan.
    */
-  @summary("Discount")
-  discounts?: AppliedDiscount[];
+  @summary("Discounts")
+  discounts?: Discount[];
 }
 
 /**