feat(subs): define timing settings and start defining period resets

openmeterio · Feb 4, 2025 · d889891 · d889891
1 parent c7886c1
commit d889891
Show file tree

Hide file tree

Showing 49 changed files with 2,868 additions and 1,714 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.cloud.yaml b/api/openapi.cloud.yaml
@@ -7153,11 +7153,10 @@ paths:
             schema:
               type: object
               properties:
-                effectiveDate:
-                  type: string
-                  format: date-time
+                timing:
+                  allOf:
+                    - $ref: '#/components/schemas/SubscriptionTiming'
                   description: If not provided the subscription is canceled immediately.
-                  example: '2023-01-01T01:01:01.001Z'
   /api/v1/subscriptions/{subscriptionId}/change:
     post:
       operationId: changeSubscription
@@ -9233,35 +9232,43 @@ components:
     CustomSubscriptionChange:
       type: object
       required:
-        - activeFrom
+        - timing
         - customPlan
       properties:
-        activeFrom:
-          type: string
-          format: date-time
-          description: '[RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.'
-          example: '2023-01-01T01:01:01.001Z'
+        timing:
+          allOf:
+            - $ref: '#/components/schemas/SubscriptionTiming'
+          description: |-
+            Timing configuration for the change, when the change should take effect.
+            For creating a subscription, only specifying an exact time is supported.
+            For changing a subscription, the accepted values depend on the subscription configuration.
         customPlan:
-          $ref: '#/components/schemas/CustomPlanInput'
+          allOf:
+            - $ref: '#/components/schemas/CustomPlanInput'
+          description: The custom plan description which defines the Subscription.
       description: Change a custom subscription.
     CustomSubscriptionCreate:
       type: object
       required:
-        - activeFrom
+        - timing
         - customPlan
         - customerId
       properties:
-        activeFrom:
-          type: string
-          format: date-time
-          description: '[RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.'
-          example: '2023-01-01T01:01:01.001Z'
+        timing:
+          allOf:
+            - $ref: '#/components/schemas/SubscriptionTiming'
+          description: |-
+            Timing configuration for the change, when the change should take effect.
+            For creating a subscription, only specifying an exact time is supported.
+            For changing a subscription, the accepted values depend on the subscription configuration.
         customPlan:
-          $ref: '#/components/schemas/CustomPlanInput'
+          allOf:
+            - $ref: '#/components/schemas/CustomPlanInput'
+          description: The custom plan description which defines the Subscription.
         customerId:
           type: string
           pattern: ^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$
-          description: ULID (Universally Unique Lexicographically Sortable Identifier).
+          description: The ID of the customer.
           example: 01G65Z755AFWAKHE12NY0CQ9FH
       description: Create a custom subscription.
     Customer:
@@ -14163,53 +14170,73 @@ components:
     PlanSubscriptionChange:
       type: object
       required:
+        - timing
         - plan
-        - activeFrom
         - name
       properties:
+        timing:
+          allOf:
+            - $ref: '#/components/schemas/SubscriptionTiming'
+          description: |-
+            Timing configuration for the change, when the change should take effect.
+            For creating a subscription, only specifying an exact time is supported.
+            For changing a subscription, the accepted values depend on the subscription configuration.
         alignment:
-          $ref: '#/components/schemas/Alignment'
+          allOf:
+            - $ref: '#/components/schemas/Alignment'
+          description: What alignment settings the subscription should have.
         metadata:
-          $ref: '#/components/schemas/Metadata'
+          allOf:
+            - $ref: '#/components/schemas/Metadata'
+          description: Arbitrary metadata associated with the subscription.
         plan:
-          $ref: '#/components/schemas/PlanReferenceInput'
-        activeFrom:
-          type: string
-          format: date-time
-          description: '[RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.'
-          example: '2023-01-01T01:01:01.001Z'
+          allOf:
+            - $ref: '#/components/schemas/PlanReferenceInput'
+          description: The plan reference to change to.
         name:
           type: string
+          description: The name of the Subscription.
         description:
           type: string
+          description: Description for the Subscription.
       description: Change subscription based on plan.
     PlanSubscriptionCreate:
       type: object
       required:
+        - timing
         - plan
-        - activeFrom
         - name
         - customerId
       properties:
+        timing:
+          allOf:
+            - $ref: '#/components/schemas/SubscriptionTiming'
+          description: |-
+            Timing configuration for the change, when the change should take effect.
+            For creating a subscription, only specifying an exact time is supported.
+            For changing a subscription, the accepted values depend on the subscription configuration.
         alignment:
-          $ref: '#/components/schemas/Alignment'
+          allOf:
+            - $ref: '#/components/schemas/Alignment'
+          description: What alignment settings the subscription should have.
         metadata:
-          $ref: '#/components/schemas/Metadata'
+          allOf:
+            - $ref: '#/components/schemas/Metadata'
+          description: Arbitrary metadata associated with the subscription.
         plan:
-          $ref: '#/components/schemas/PlanReferenceInput'
-        activeFrom:
-          type: string
-          format: date-time
-          description: '[RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.'
-          example: '2023-01-01T01:01:01.001Z'
+          allOf:
+            - $ref: '#/components/schemas/PlanReferenceInput'
+          description: The plan reference to change to.
         name:
           type: string
+          description: The name of the Subscription.
         description:
           type: string
+          description: Description for the Subscription.
         customerId:
           type: string
           pattern: ^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$
-          description: ULID (Universally Unique Lexicographically Sortable Identifier).
+          description: The ID of the customer.
           example: 01G65Z755AFWAKHE12NY0CQ9FH
       description: Create subscription based on plan.
     PortalToken:
@@ -15225,10 +15252,12 @@ components:
         current:
           allOf:
             - $ref: '#/components/schemas/Subscription'
+          description: The current subscription before the change.
           title: Current subscription
         next:
           allOf:
             - $ref: '#/components/schemas/SubscriptionExpanded'
+          description: The new state of the subscription after the change.
           title: The subscription it will be changed to
       description: Response body for subscription change.
     SubscriptionCreate:
@@ -15265,6 +15294,7 @@ components:
           add_phase: '#/components/schemas/EditSubscriptionAddPhase'
           remove_phase: '#/components/schemas/EditSubscriptionRemovePhase'
           stretch_phase: '#/components/schemas/EditSubscriptionStretchPhase'
+      description: The operation to be performed on the subscription.
     SubscriptionExpanded:
       type: object
       required:
@@ -15649,6 +15679,25 @@ components:
         - SubscriptionStatusActive
         - SubscriptionStatusInactive
         - SubscriptionStatusCanceled
+    SubscriptionTiming:
+      oneOf:
+        - $ref: '#/components/schemas/SubscriptionTimingEnum'
+        - type: string
+          format: date-time
+          description: '[RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.'
+          example: '2023-01-01T01:01:01.001Z'
+      description: |-
+        Subscription edit timing defined when the changes should take effect.
+        If the provided configuration is not supported by the subscription, an error will be returned.
+    SubscriptionTimingEnum:
+      type: string
+      enum:
+        - immediate
+        - next_billing_cycle
+      description: |-
+        Subscription edit timing.
+        When immediate, the requested changes take effect immediately.
+        When nextBillingCycle, the requested changes take effect at the next billing cycle.
     SvixOperationalWebhookRequest:
       type: object
       required: