@inklok/api-spec 7.9.1 → 7.9.3

package/openapi.yaml

@@ -8,7 +8,7 @@ info:
     Authenticate using an API key or bearer token, then use the resources below to manage
     templates, agreements, documents, and signing. For your first integration, start with
     the Quick Start guide.
-  version: "7.9.1"
+  version: "7.9.3"
   contact:
     name: Inklok API Support
     email: support@inklok.com
@@ -486,7 +486,7 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/MeBillingSeatsUpdateRequest'
+              $ref: '#/components/schemas/MeBillingSeatsApplyRequest'
       responses:
         '200':
           description: Successfully updated seats
@@ -528,6 +528,45 @@ paths:
         '500':
           $ref: '#/components/responses/InternalServerError'
 
+  /me/billing/seats/preview:
+    post:
+      operationId: previewMeBillingSeats
+      summary: Preview an additional-seat change for the current account
+      x-internal: true
+      x-visibility: internal
+      description: |
+        Previews the Paddle financial impact of changing the Additional Seat
+        subscription item quantity without applying the subscription mutation.
+      tags:
+        - Me
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MeBillingSeatsPreviewRequest'
+      responses:
+        '200':
+          description: Successfully previewed the seat change
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MeBillingSeatsPreviewResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '502':
+          $ref: '#/components/responses/BadGateway'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailable'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
   /platform/overview:
     get:
       operationId: getPlatformOverview
@@ -713,7 +752,8 @@ paths:
       summary: Get Platform API usage health
       x-visibility: internal
       description: |
-        Returns a small operational API usage health view for platform administrators.
+        Returns a small operational published-API usage health view for platform administrators.
+        Cognito-authenticated first-party application traffic is excluded.
         This endpoint uses existing usage counters and does not expose customer-facing analytics.
       x-required-global-roles: [PLATFORM_ADMIN]
       tags:
@@ -739,6 +779,16 @@ paths:
               - usagePercentage
             default: throttleCount
           description: Sort order for returned organizations.
+        - in: query
+          name: filter
+          schema:
+            type: string
+            enum:
+              - all
+              - throttled
+              - approaching
+            default: all
+          description: Optional status subset. Approaching means non-throttled organizations at 60% usage or higher.
         - in: query
           name: limit
           schema:
@@ -3982,15 +4032,142 @@ components:
           nullable: true
           minimum: 0
 
-    MeBillingSeatsUpdateRequest:
+    MeBillingSeatsPreviewRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - additionalSeats
+      properties:
+        additionalSeats:
+          type: integer
+          minimum: 0
+
+    MeBillingSeatsApplyRequest:
       type: object
       additionalProperties: false
       required:
         - additionalSeats
+        - previewToken
       properties:
         additionalSeats:
           type: integer
           minimum: 0
+        previewToken:
+          type: string
+          description: Signed token returned by the seat-change preview endpoint.
+
+    MeBillingSeatsPreviewResponse:
+      type: object
+      additionalProperties: false
+      required:
+        - accountId
+        - subscriptionId
+        - currentAdditionalSeats
+        - proposedAdditionalSeats
+        - currentEffectiveSeatLimit
+        - proposedEffectiveSeatLimit
+        - direction
+        - prorationBillingMode
+        - memberLimitWarning
+        - immediateAdjustment
+        - nextRecurringAmount
+        - nextBillingDate
+        - billingCycle
+        - previewToken
+      properties:
+        accountId:
+          type: string
+        subscriptionId:
+          type: string
+        currentAdditionalSeats:
+          type: integer
+          minimum: 0
+        proposedAdditionalSeats:
+          type: integer
+          minimum: 0
+        currentEffectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        proposedEffectiveSeatLimit:
+          type: integer
+          nullable: true
+          minimum: 0
+        direction:
+          type: string
+          enum: [increase, decrease, unchanged]
+        prorationBillingMode:
+          type: string
+          enum: [prorated_immediately, prorated_next_billing_period]
+        memberLimitWarning:
+          type: object
+          nullable: true
+          additionalProperties: false
+          required:
+            - activeMembers
+            - proposedEffectiveSeatLimit
+            - overBy
+          properties:
+            activeMembers:
+              type: integer
+              minimum: 0
+            proposedEffectiveSeatLimit:
+              type: integer
+              minimum: 0
+            overBy:
+              type: integer
+              minimum: 1
+        immediateAdjustment:
+          type: object
+          additionalProperties: false
+          required:
+            - amount
+            - currencyCode
+            - kind
+          properties:
+            amount:
+              type: integer
+              description: Signed minor-unit amount. Positive charges now; negative credits now; zero means no immediate payment.
+            currencyCode:
+              type: string
+              nullable: true
+            kind:
+              type: string
+              enum: [charge, credit, none]
+        nextRecurringAmount:
+          type: object
+          additionalProperties: false
+          required:
+            - amount
+            - currencyCode
+          properties:
+            amount:
+              type: integer
+              nullable: true
+              description: Minor-unit recurring subscription total from Paddle preview.
+            currencyCode:
+              type: string
+              nullable: true
+        nextBillingDate:
+          type: string
+          format: date-time
+          nullable: true
+        billingCycle:
+          type: object
+          additionalProperties: false
+          required:
+            - interval
+            - frequency
+          properties:
+            interval:
+              type: string
+              enum: [day, week, month, year, unknown]
+            frequency:
+              type: integer
+              nullable: true
+              minimum: 1
+        previewToken:
+          type: string
 
     MeBillingResponse:
       type: object
@@ -4903,10 +5080,13 @@ components:
       required:
         - window
         - sort
+        - filter
         - limit
         - nextCursor
         - organizations
         - totalOrganizations
+        - totalThrottledOrganizations
+        - totalApproachingLimitOrganizations
         - dataSource
         - generatedAt
       properties:
@@ -4922,6 +5102,12 @@ components:
           enum:
             - throttleCount
             - usagePercentage
+        filter:
+          type: string
+          enum:
+            - all
+            - throttled
+            - approaching
         limit:
           type: integer
           minimum: 1
@@ -4935,6 +5121,12 @@ components:
         totalOrganizations:
           type: integer
           minimum: 0
+        totalThrottledOrganizations:
+          type: integer
+          minimum: 0
+        totalApproachingLimitOrganizations:
+          type: integer
+          minimum: 0
         dataSource:
           type: object
           required:
@@ -4959,9 +5151,9 @@ components:
               enum:
                 - peak_minute
                 - daily_capacity
-      generatedAt:
-        type: string
-        format: date-time
+        generatedAt:
+          type: string
+          format: date-time
 
     PlatformBillingActivityType:
       type: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklok/api-spec",
-  "version": "7.9.1",
+  "version": "7.9.3",
   "description": "Canonical OpenAPI specification for the Inklok public API.",
   "main": "openapi.yaml",
   "license": "MIT",