refactor(entitlement): update V2 API to better conform to new standards (#3401)

Author: GAlexIHU

api/api.gen.go

@@ -29,7 +29,7 @@ interface CustomerEntitlements {
   @operationId("createCustomerEntitlementV2")
   post(
     @path customerIdOrKey: ULIDOrExternalKey,
-    @body entitlement: OpenMeter.Entitlements.EntitlementCreateInputs,
+    @body entitlement: EntitlementV2CreateInputs,
   ): {
     @statusCode _: 201;
     @body body: EntitlementV2;
@@ -88,7 +88,7 @@ interface CustomerEntitlements {
   override(
     @path customerIdOrKey: ULIDOrExternalKey,
     @path entitlementIdOrFeatureKey: ULIDOrExternalKey,
-    @body entitlement: EntitlementCreateInputs,
+    @body entitlement: EntitlementV2CreateInputs,
   ):
     | {
         @statusCode _: 201;
@@ -117,7 +117,7 @@ interface CustomerEntitlement {
     ...OpenMeter.QueryPagination,
     ...OpenMeter.QueryLimitOffset,
     ...OpenMeter.QueryOrdering<GrantOrderBy>,
-  ): OpenMeter.PaginatedResponse<Grant> | OpenMeter.CommonErrors;
+  ): OpenMeter.PaginatedResponse<GrantV2> | OpenMeter.CommonErrors;
 
   /**
    * Grants define a behavior of granting usage for a metered entitlement. They can have complicated recurrence and rollover rules, thanks to which you can define a wide range of access patterns with a single grant, in most cases you don't have to periodically create new grants. You can only issue grants for active metered entitlements.
@@ -139,10 +139,10 @@ interface CustomerEntitlement {
   createCustomerEntitlementGrant(
     @path customerIdOrKey: ULIDOrExternalKey,
     @path entitlementIdOrFeatureKey: ULIDOrKey,
-    @body grant: GrantCreateInput,
+    @body grant: GrantCreateInputV2,
   ): {
     @statusCode _: 201;
-    @body body: Grant;
+    @body body: GrantV2;
   } | OpenMeter.CommonErrors | OpenMeter.ConflictError;
 
   /**

api/client/go/client.gen.go

@@ -87,6 +87,17 @@ union EntitlementV2 {
   boolean: EntitlementBooleanV2,
 }
 
+/**
+ * Create inputs for entitlement
+ */
+@discriminated(#{ envelope: "none", discriminatorPropertyName: "type" })
+@friendlyName("EntitlementV2CreateInputs")
+union EntitlementV2CreateInputs {
+  metered: EntitlementMeteredV2CreateInputs,
+  static: EntitlementStaticCreateInputs,
+  boolean: EntitlementBooleanCreateInputs,
+}
+
 /**
  * Customer fields for entitlements
  */
@@ -105,6 +116,70 @@ model EntitlementCustomerFields {
   customerId: ULID;
 }
 
+/**
+ * Issue after reset
+ */
+@friendlyName("IssueAfterReset")
+model IssueAfterReset {
+  /**
+   * The initial grant amount
+   */
+  @summary("Initial grant amount")
+  @minValue(0)
+  amount: float64;
+
+  /**
+   * The priority of the issue after reset
+   */
+  @summary("Issue grant after reset priority")
+  @minValue(1)
+  @maxValue(255)
+  priority?: uint8 = 1;
+}
+
+/**
+ * Create inputs for metered entitlement
+ */
+@friendlyName("EntitlementMeteredV2CreateInputs")
+model EntitlementMeteredV2CreateInputs {
+  ...OmitProperties<
+    OpenMeter.Entitlements.EntitlementMeteredCreateInputs,
+    "isUnlimited" | "issueAfterReset" | "issueAfterResetPriority"
+  >;
+
+  /**
+   * You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance.
+   * If an amount is specified here, a grant will be created alongside the entitlement with the specified amount.
+   * That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here.
+   * Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same.
+   */
+  #deprecated "Use issue.Amount instead, will be removed in next major version."
+  @minValue(0)
+  @summary("Initial grant amount")
+  issueAfterReset?: float64;
+
+  /**
+   * Defines the grant priority for the default grant.
+   */
+  #deprecated "Use issue.Priority instead, will be removed in next major version."
+  @minValue(1)
+  @maxValue(255)
+  @summary("Issue grant after reset priority")
+  issueAfterResetPriority?: uint8 = 1;
+
+  /**
+   * Issue after reset
+   */
+  @summary("Issue after reset")
+  issue?: IssueAfterReset;
+
+  /**
+   * Grants
+   */
+  @summary("Grants")
+  grants?: GrantCreateInputV2[];
+}
+
 /**
  * Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems.
  * Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage).
@@ -113,7 +188,7 @@ model EntitlementCustomerFields {
 model EntitlementMeteredV2 {
   type: EntitlementType.metered;
   ...OmitProperties<
-    EntitlementMeteredCreateInputs,
+    EntitlementMeteredV2CreateInputs,
 
       | "type"
       | "measureUsageFrom"
@@ -122,6 +197,7 @@ model EntitlementMeteredV2 {
       | "featureKey"
       | "featureId"
       | "currentUsagePeriod"
+      | "grants"
   >;
   ...OmitProperties<
     EntitlementSharedFields,

api/client/javascript/src/client/schemas.ts

@@ -0,0 +1,90 @@
+import "@typespec/http";
+import "@typespec/rest";
+import "@typespec/openapi3";
+import "..";
+import "../..";
+
+namespace OpenMeter.Entitlements.V2;
+
+/**
+ * The grant.
+ */
+@friendlyName("EntitlementGrantV2")
+model GrantV2 {
+  ...ResourceTimestamps;
+  ...OmitProperties<GrantCreateInputV2, "recurrence">;
+
+  /**
+   * Readonly unique ULID identifier.
+   */
+  @example("01ARZ3NDEKTSV4RRFFQ69G5FAV")
+  @visibility(Lifecycle.Read)
+  id: ULID;
+
+  /**
+   * The unique entitlement ULID that the grant is associated with.
+   */
+  @example("01ARZ3NDEKTSV4RRFFQ69G5FAV")
+  @visibility(Lifecycle.Read)
+  entitlementId: string;
+
+  /**
+   * The next time the grant will recurr.
+   */
+  @example(DateTime.fromISO("2023-01-01T01:01:01.001Z"))
+  nextRecurrence?: DateTime;
+
+  /**
+   * The time the grant expires.
+   */
+  @example(DateTime.fromISO("2023-01-01T01:01:01.001Z"))
+  @visibility(Lifecycle.Read)
+  expiresAt?: DateTime;
+
+  /**
+   * The time the grant was voided.
+   */
+  @example(DateTime.fromISO("2023-01-01T01:01:01.001Z"))
+  voidedAt?: DateTime;
+
+  /**
+   * The recurrence period of the grant.
+   */
+  recurrence?: RecurringPeriod;
+}
+
+/**
+ * The grant creation input.
+ */
+@friendlyName("EntitlementGrantCreateInputV2")
+model GrantCreateInputV2 {
+  ...OmitProperties<
+    OpenMeter.Entitlements.GrantCreateInput,
+    "maxRolloverAmount" | "metadata" | "expiration"
+  >;
+
+  /**
+   * Grants are rolled over at reset, after which they can have a different balance compared to what they had before the reset. The default value equals grant amount.
+   * Balance after the reset is calculated as: Balance_After_Reset = MIN(MaxRolloverAmount, MAX(Balance_Before_Reset, MinRolloverAmount))
+   */
+  @example(100.0)
+  maxRolloverAmount?: float64;
+
+  /**
+   * The grant expiration definition. If no expiration is provided, the grant can be active indefinitely.
+   */
+  expiration?: ExpirationPeriod;
+
+  /**
+   * The grant metadata.
+   */
+  #deprecated "Use annotations instead, will be removed in next major version."
+  @example(#{ stripePaymentId: "pi_4OrAkhLvyihio9p51h9iiFnB" })
+  metadata?: Metadata;
+
+  /**
+   * The grant metadata.
+   */
+  @example(#{ stripePaymentId: "pi_4OrAkhLvyihio9p51h9iiFnB" })
+  annotations?: Annotations;
+}

api/client/javascript/src/zod/index.ts

@@ -45,5 +45,5 @@ interface Grants {
     ...OpenMeter.QueryPagination,
     ...OpenMeter.QueryLimitOffset,
     ...OpenMeter.QueryOrdering<GrantOrderBy>,
-  ): OpenMeter.PaginatedResponse<Grant> | OpenMeter.CommonErrors;
+  ): OpenMeter.PaginatedResponse<GrantV2> | OpenMeter.CommonErrors;
 }