feat(ProgressiveBilling): Expose lifetime usage GET and PUT (#266)

src/resources/subscription_lifetime_usage.yaml

@@ -0,0 +1,53 @@
+parameters:
+  - name: external_id
+    in: path
+    description: External ID of the existing subscription
+    required: true
+    schema:
+      type: string
+      example: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"
+get:
+  tags:
+    - subscriptions
+  summary: Retrive subscription lifetime usage
+  description: This endpoint enables the retrieval of the lifetime usage of a subscription.
+  operationId: getSubscriptionLifetimeUsage
+  responses:
+    "200":
+      description: Subscription lifetime usage
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/LifetimeUsage.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "404":
+      $ref: "../responses/NotFound.yaml"
+put:
+  tags:
+    - subscriptions
+  summary: Update a subscription lifetime usage
+  description: This endpoint allows you to update the lifetime usage of a subscription.
+  operationId: updateSubscriptionLifetimeUsage
+  requestBody:
+    description: Update the lifetime usage of a subscription
+    content:
+      application/json:
+        schema:
+          $ref: "../schemas/LifetimeUsageInput.yaml"
+    required: true
+  responses:
+    "200":
+      description: Subscription lifetime usage updated
+      content:
+        application/json:
+          schema:
+            $ref: "../schemas/LifetimeUsage.yaml"
+    "400":
+      $ref: "../responses/BadRequest.yaml"
+    "401":
+      $ref: "../responses/Unauthorized.yaml"
+    "404":
+      $ref: "../responses/NotFound.yaml"
+    "422":
+      $ref: "../responses/UnprocessableEntity.yaml"

src/schemas/LifetimeUsage.yaml

@@ -0,0 +1,6 @@
+type: object
+required:
+  - lifetime_usage
+properties:
+  lifetime_usage:
+    $ref: "./LifetimeUsageObject.yaml"

src/schemas/LifetimeUsageInput.yaml

@@ -0,0 +1,13 @@
+type: object
+required:
+  - lifetime_usage
+properties:
+  lifetime_usage:
+    type: object
+    required:
+      - external_historical_usage_amount_cents
+    properties:
+      external_historical_usage_amount_cents:
+        type: integer
+        example: 100
+        description: The historical usage amount in cents for the subscription (provided by your own application).

src/schemas/LifetimeUsageObject.yaml

@@ -0,0 +1,52 @@
+type: object
+required:
+  - lago_id
+  - lago_subscription_id
+  - external_subscription_id
+  - external_historical_usage_amount_cents
+  - invoiced_usage_amount_cents
+  - current_usage_amount_cents
+  - from_datetime
+  - to_datetime
+properties:
+  lago_id:
+    type: string
+    format: "uuid"
+    example: "1a901a90-1a90-1a90-1a90-1a901a901a90"
+    description: Unique identifier assigned to the lifetime usage record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the lifetime usage record within the Lago system
+  lago_subscription_id:
+    type: string
+    format: "uuid"
+    example: "1a901a90-1a90-1a90-1a90-1a901a901a90"
+    description: Unique identifier assigned to the subscription record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription record within the Lago system
+  external_subscription_id:
+    type: string
+    example: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"
+    description: The subscription external unique identifier (provided by your own application).
+  external_historical_usage_amount_cents:
+    type: integer
+    example: 100
+    description: The historical usage amount in cents for the subscription (provided by your own application).
+  invoiced_usage_amount_cents:
+    type: integer
+    example: 100
+    description: The total invoiced usage amount in cents for the subscription.
+  current_usage_amount_cents:
+    type: integer
+    example: 100
+    description: The current usage amount in cents for the subscription on the current billing period.
+  from_datetime:
+    type: string
+    format: date-time
+    example: "2024-01-01T00:00:00Z"
+    description: The recording start date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format.
+  to_datetime:
+    type: string
+    format: date-time
+    example: "2024-12-31T23:59:59Z"
+    description: The recording end date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format.
+  usage_thresholds:
+    type: array
+    description: Array of usage thresholds attached to the subscription's plan.
+    items:
+      $ref: "./LifetimeUsageThresholdObject.yaml"

src/schemas/LifetimeUsageThresholdObject.yaml

@@ -0,0 +1,20 @@
+type: object
+required:
+  - amount_cents
+  - completion_ratio
+  - reached_at
+properties:
+  amount_cents:
+    type: integer
+    description: The usage threshold amount in cents.
+    example: 100
+  completion_ratio:
+    type: number
+    description: The completion ratio of the usage threshold.
+    example: 0.5
+  reached_at:
+    type: string
+    format: date-time
+    description: The date and time when the usage threshold was reached. The date and time must be in ISO 8601 format.
+    example: "2024-01-01T00:00:00Z"
+    nullable: true

src/schemas/_index.yaml

@@ -152,6 +152,14 @@ GrossRevenueObject:
   $ref: "./GrossRevenueObject.yaml"
 GrossRevenues:
   $ref: "./GrossRevenues.yaml"
+LifetimeUsage:
+  $ref: "./LifetimeUsage.yaml"
+LifetimeUsageInput:
+  $ref: "./LifetimeUsageInput.yaml"
+LifetimeUsageObject:
+  $ref: "./LifetimeUsageObject.yaml"
+LifetimeUsageThresholdObject:
+  $ref: "./LifetimeUsageThresholdObject.yaml"
 MinimumCommitmentInput:
   $ref: "./MinimumCommitmentInput.yaml"
 MinimumCommitmentObject: