licensekit-ruby 0.1.0.alpha.1 → 1.0.0

data/openapi/openapi.yaml

@@ -28,6 +28,8 @@ tags:
     description: Management operations for scoped API keys.
   - name: events
     description: Management operations for audit and event feeds.
+  - name: ops
+    description: Management operations for operational summaries and error reporting.
   - name: webhooks
     description: Management operations for webhook endpoints and delivery state.
   - name: licenses
@@ -215,7 +217,79 @@ components:
         - license:write
         - device:write
         - event:read
+        - ops:read
+        - report:read
+        - report:export
         - webhook:write
+    ReportKind:
+      type: string
+      enum:
+        - usage-summary
+        - usage-ledger
+        - license-audit
+        - customer-summary
+        - subscription-settlement
+    ReportExportFormat:
+      type: string
+      enum:
+        - json
+        - csv
+        - pdf
+    ReportExportCreateRequest:
+      type: object
+      required:
+        - report_kind
+      properties:
+        report_kind:
+          $ref: "#/components/schemas/ReportKind"
+        format:
+          $ref: "#/components/schemas/ReportExportFormat"
+        filters:
+          type: object
+          additionalProperties: true
+    ReportExportMetadata:
+      type: object
+      required:
+        - id
+        - report_kind
+        - format
+        - status
+        - filters
+        - digest
+        - artifact_digest
+        - content_type
+        - created_by
+        - created_at
+        - updated_at
+        - download_url
+      properties:
+        id:
+          type: string
+        report_kind:
+          $ref: "#/components/schemas/ReportKind"
+        format:
+          $ref: "#/components/schemas/ReportExportFormat"
+        status:
+          type: string
+        filters:
+          type: object
+          additionalProperties: true
+        digest:
+          type: string
+        artifact_digest:
+          type: string
+        content_type:
+          type: string
+        created_by:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+        download_url:
+          type: string
     LicenseType:
       type: string
       enum:
@@ -3434,6 +3508,645 @@ paths:
           $ref: "#/components/responses/UnauthorizedManagement"
         "403":
           $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/activities:
+    get:
+      operationId: listActivities
+      tags: [reporting]
+      summary: List normalized reporting activities
+      x-required-scopes: ["report:read"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/CursorParam"
+        - $ref: "#/components/parameters/LimitParam"
+        - in: query
+          name: from
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: to
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: action
+          schema:
+            type: string
+        - in: query
+          name: source
+          schema:
+            type: string
+        - in: query
+          name: product_id
+          schema:
+            type: string
+        - in: query
+          name: customer_id
+          schema:
+            type: string
+        - in: query
+          name: license_id
+          schema:
+            type: string
+        - in: query
+          name: order_id
+          schema:
+            type: string
+        - in: query
+          name: subscription_id
+          schema:
+            type: string
+        - in: query
+          name: feature_code
+          schema:
+            type: string
+        - in: query
+          name: request_id
+          schema:
+            type: string
+        - in: query
+          name: result_class
+          schema:
+            type: string
+        - in: query
+          name: status_code
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: Reporting activity feed page.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, page_info, meta]
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                  page_info:
+                    $ref: "#/components/schemas/EventPageInfo"
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/reports/usage-summary:
+    get:
+      operationId: getUsageSummary
+      tags: [reporting]
+      summary: Get grouped usage totals
+      x-required-scopes: ["report:read"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/LimitParam"
+        - in: query
+          name: from
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: to
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: group_by
+          schema:
+            type: string
+        - in: query
+          name: bucket
+          schema:
+            type: string
+            enum: [1h, 1d]
+        - in: query
+          name: product_id
+          schema:
+            type: string
+        - in: query
+          name: customer_id
+          schema:
+            type: string
+        - in: query
+          name: license_id
+          schema:
+            type: string
+        - in: query
+          name: order_id
+          schema:
+            type: string
+        - in: query
+          name: subscription_id
+          schema:
+            type: string
+        - in: query
+          name: feature_code
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Grouped usage summary.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, meta]
+                properties:
+                  data:
+                    type: object
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/reports/usage-ledger:
+    get:
+      operationId: listUsageLedger
+      tags: [reporting]
+      summary: List row-level usage ledger entries
+      x-required-scopes: ["report:read"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/CursorParam"
+        - $ref: "#/components/parameters/LimitParam"
+        - in: query
+          name: from
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: to
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: action
+          schema:
+            type: string
+        - in: query
+          name: product_id
+          schema:
+            type: string
+        - in: query
+          name: customer_id
+          schema:
+            type: string
+        - in: query
+          name: license_id
+          schema:
+            type: string
+        - in: query
+          name: order_id
+          schema:
+            type: string
+        - in: query
+          name: subscription_id
+          schema:
+            type: string
+        - in: query
+          name: feature_code
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Usage ledger page.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, page_info, meta]
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                  page_info:
+                    $ref: "#/components/schemas/EventPageInfo"
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/reports/license-audit:
+    get:
+      operationId: getLicenseAuditReport
+      tags: [reporting]
+      summary: Get a license audit report
+      x-required-scopes: ["report:read"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/LimitParam"
+        - in: query
+          name: license_id
+          required: true
+          schema:
+            type: string
+        - in: query
+          name: from
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: to
+          schema:
+            type: string
+            format: date-time
+      responses:
+        "200":
+          description: License audit report.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, meta]
+                properties:
+                  data:
+                    type: object
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/reports/customer-summary:
+    get:
+      operationId: getCustomerSummary
+      tags: [reporting]
+      summary: Get customer-level reporting summary
+      x-required-scopes: ["report:read"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/LimitParam"
+        - in: query
+          name: customer_id
+          required: true
+          schema:
+            type: string
+        - in: query
+          name: from
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: to
+          schema:
+            type: string
+            format: date-time
+      responses:
+        "200":
+          description: Customer summary report.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, meta]
+                properties:
+                  data:
+                    type: object
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/reports/subscription-settlement:
+    get:
+      operationId: getSubscriptionSettlement
+      tags: [reporting]
+      summary: Get subscription or order settlement summary
+      x-required-scopes: ["report:read"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/LimitParam"
+        - in: query
+          name: subscription_id
+          schema:
+            type: string
+        - in: query
+          name: order_id
+          schema:
+            type: string
+        - in: query
+          name: from
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: to
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: group_by
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Settlement summary.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, meta]
+                properties:
+                  data:
+                    type: object
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/reports/exports:
+    post:
+      operationId: createReportExport
+      tags: [reporting]
+      summary: Create a frozen report export
+      x-required-scopes: ["report:export"]
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ReportExportCreateRequest"
+      responses:
+        "201":
+          description: Report export created.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, meta]
+                properties:
+                  data:
+                    $ref: "#/components/schemas/ReportExportMetadata"
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/reports/exports/{id}:
+    get:
+      operationId: getReportExport
+      tags: [reporting]
+      summary: Get report export metadata
+      x-required-scopes: ["report:export"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Report export metadata.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, meta]
+                properties:
+                  data:
+                    $ref: "#/components/schemas/ReportExportMetadata"
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/reports/exports/{id}/download:
+    get:
+      operationId: downloadReportExport
+      tags: [reporting]
+      summary: Download a frozen report export snapshot
+      x-required-scopes: ["report:export"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Stored report export snapshot.
+          content:
+            application/json:
+              schema:
+                type: object
+            text/csv:
+              schema:
+                type: string
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/ops/summary:
+    get:
+      operationId: getOpsSummary
+      tags: [ops]
+      summary: Get operational summary cards
+      x-required-scopes: ["ops:read"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: query
+          name: from
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: to
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: product_id
+          schema:
+            type: string
+        - in: query
+          name: customer_id
+          schema:
+            type: string
+        - in: query
+          name: license_id
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Operational summary.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, meta]
+                properties:
+                  data:
+                    type: object
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/ops/runtime-errors:
+    get:
+      operationId: listRuntimeErrorGroups
+      tags: [ops]
+      summary: List grouped runtime error counts
+      x-required-scopes: ["ops:read"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/LimitParam"
+        - in: query
+          name: from
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: to
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: product_id
+          schema:
+            type: string
+        - in: query
+          name: customer_id
+          schema:
+            type: string
+        - in: query
+          name: license_id
+          schema:
+            type: string
+        - in: query
+          name: app_version
+          schema:
+            type: string
+        - in: query
+          name: endpoint
+          schema:
+            type: string
+            enum:
+              - activate
+              - validate
+              - check
+              - consume
+              - offline
+              - deactivate
+              - floating_checkout
+              - floating_checkin
+              - floating_heartbeat
+        - in: query
+          name: group_by
+          schema:
+            type: string
+          description: Comma-separated dimensions from `time`, `endpoint`, `reason_code`, `result_class`.
+        - in: query
+          name: bucket
+          schema:
+            type: string
+            enum: [5m, 15m, 1h, 1d]
+      responses:
+        "200":
+          description: Runtime error groups.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, meta]
+                properties:
+                  data:
+                    type: object
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
+  /api/v1/ops/webhook-health:
+    get:
+      operationId: getWebhookHealth
+      tags: [ops]
+      summary: Get webhook queue and failure health
+      x-required-scopes: ["ops:read"]
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/LimitParam"
+        - in: query
+          name: from
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: to
+          schema:
+            type: string
+            format: date-time
+        - in: query
+          name: endpoint_id
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Webhook health summary and grouped failures.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data, meta]
+                properties:
+                  data:
+                    type: object
+                  meta:
+                    $ref: "#/components/schemas/ResponseMeta"
+        "400":
+          $ref: "#/components/responses/InvalidQuery"
+        "401":
+          $ref: "#/components/responses/UnauthorizedManagement"
+        "403":
+          $ref: "#/components/responses/ForbiddenScope"
   /api/v1/webhooks:
     get:
       operationId: listWebhookEndpoints