@knowledge-stack/ksapi 1.163.0 → 2.4.2

package/docs/WorkflowRunsApi.md

@@ -909,7 +909,7 @@ example().catch(console.error);
 
 Workflow Run Callback Handler
 
-Terminal-state write seam for the in-process agent runner.  The gating Temporal activities ``mark_run_completed_activity`` and ``mark_run_failed_activity`` authenticate as the triggering user (via ``assume_user``) and POST here. Only the user who triggered the run (or OWNER/ADMIN) may write its terminal state. The handler is idempotent: a callback against an already-terminal row returns ``already_terminal`` and the activity-level retry treats it as a no-op.
+Terminal-state write seam for the in-process agent runner.  The gating Temporal activities ``mark_run_completed_activity`` and ``mark_run_failed_activity`` authenticate as the triggering user (via ``assume_user``) and POST here. Only the user who triggered the run (or OWNER/ADMIN) may write its terminal state. The handler is idempotent: a callback against an already-terminal row returns ``already_terminal`` and the activity-level retry treats it as a no-op.  On the first terminal transition it emails the run\'s triggering user (``run.user_id``) a completion or failure notification. Only already-loaded columns are captured in-session; recipient/language lookups and the send run post-commit and best-effort, so a rolled-back transaction never notifies and a notification failure never fails the callback.
 
 ### Example
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowledge-stack/ksapi",
-  "version": "1.163.0",
+  "version": "2.4.2",
   "description": "OpenAPI client for @knowledge-stack/ksapi",
   "author": "OpenAPI-Generator",
   "repository": {

package/src/apis/BillingApi.ts

@@ -0,0 +1,142 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management.  ## Integrating (RPA / machine clients)  **Base URL.** Knowledge Stack is self-hosted — point at your own deployment host (see `servers`). The `localhost` entry is for local development only.  **Authentication.** Send `Authorization: Bearer <api-key>` on every request. Mint an API key once via `POST /v1/api-keys` from a signed-in browser session; the raw `sk-user-...` secret is returned **only** at creation, so store it then. A key inherits its owning user\'s live tenant role and path permissions — create RPA keys from a least-privilege user, and set `expires_at` for rotation. The `ks_uat` cookie scheme is browser-only and cannot be used by headless clients.  **Async work is polled, not pushed.** There are no outbound webhooks. - `POST /v1/documents/ingest` returns `201` immediately with a `workflow_id`;   poll `GET /v1/system-jobs/document_versions/{workflow_id}` until `status` is   terminal (anything other than `pending`/`processing`). The `Location` response   header points at this poll resource. - `POST /v1/workflow-runs/{run_id}/start` returns `202`; poll   `GET /v1/workflow-runs/{run_id}` until `execution_state` is `COMPLETED` or   `FAILED`. The `Location` header points at the run resource. - `POST /v1/agent/ask` is **synchronous** — it blocks until the agent finishes   and returns the answer inline. Use a generous HTTP timeout.  **Pagination.** List endpoints accept `limit`/`offset` and return `{items, total, limit, offset}`.  **Errors.** Every non-2xx body is `{detail, code, request_id}`. `code` is a stable value from a closed set (see the `ErrorResponse` schema\'s `code` enum) — branch on it rather than parsing `detail`. Quota rejections return `429` with a `Retry-After` header; transient lock contention returns a retryable `503`. Quote `request_id` (also the `x-request-id` response header) to support.  **Idempotency.** `POST /v1/workflow-runs` accepts an `idempotency_key` to dedupe retried run creation. `agent/ask` charges one message *before* running and does not refund a client-cancelled call. 
+ *
+ * The version of the OpenAPI document: 0.1.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+import * as runtime from '../runtime';
+import type {
+  ErrorResponse,
+  HTTPValidationError,
+  PaginatedResponseBillingPaymentResponse,
+} from '../models/index';
+import {
+    ErrorResponseFromJSON,
+    ErrorResponseToJSON,
+    HTTPValidationErrorFromJSON,
+    HTTPValidationErrorToJSON,
+    PaginatedResponseBillingPaymentResponseFromJSON,
+    PaginatedResponseBillingPaymentResponseToJSON,
+} from '../models/index';
+
+export interface ListBillingPaymentsRequest {
+    tenantId: string;
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * BillingApi - interface
+ * 
+ * @export
+ * @interface BillingApiInterface
+ */
+export interface BillingApiInterface {
+    /**
+     * Creates request options for listBillingPayments without sending the request
+     * @param {string} tenantId 
+     * @param {number} [limit] Number of items per page
+     * @param {number} [offset] Number of items to skip
+     * @throws {RequiredError}
+     * @memberof BillingApiInterface
+     */
+    listBillingPaymentsRequestOpts(requestParameters: ListBillingPaymentsRequest): Promise<runtime.RequestOpts>;
+
+    /**
+     * Newest-first payment history for the tenant (OWNER/ADMIN only).  Backs the billing page\'s receipts list. ``invoice_url`` links the Stripe-hosted invoice when the payment ran through Stripe; CN (Ping++) payments render an in-app receipt from the row itself.
+     * @summary List Billing Payments Handler
+     * @param {string} tenantId 
+     * @param {number} [limit] Number of items per page
+     * @param {number} [offset] Number of items to skip
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     * @memberof BillingApiInterface
+     */
+    listBillingPaymentsRaw(requestParameters: ListBillingPaymentsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<PaginatedResponseBillingPaymentResponse>>;
+
+    /**
+     * Newest-first payment history for the tenant (OWNER/ADMIN only).  Backs the billing page\'s receipts list. ``invoice_url`` links the Stripe-hosted invoice when the payment ran through Stripe; CN (Ping++) payments render an in-app receipt from the row itself.
+     * List Billing Payments Handler
+     */
+    listBillingPayments(requestParameters: ListBillingPaymentsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<PaginatedResponseBillingPaymentResponse>;
+
+}
+
+/**
+ * 
+ */
+export class BillingApi extends runtime.BaseAPI implements BillingApiInterface {
+
+    /**
+     * Creates request options for listBillingPayments without sending the request
+     */
+    async listBillingPaymentsRequestOpts(requestParameters: ListBillingPaymentsRequest): Promise<runtime.RequestOpts> {
+        if (requestParameters['tenantId'] == null) {
+            throw new runtime.RequiredError(
+                'tenantId',
+                'Required parameter "tenantId" was null or undefined when calling listBillingPayments().'
+            );
+        }
+
+        const queryParameters: any = {};
+
+        if (requestParameters['limit'] != null) {
+            queryParameters['limit'] = requestParameters['limit'];
+        }
+
+        if (requestParameters['offset'] != null) {
+            queryParameters['offset'] = requestParameters['offset'];
+        }
+
+        const headerParameters: runtime.HTTPHeaders = {};
+
+        if (this.configuration && this.configuration.accessToken) {
+            const token = this.configuration.accessToken;
+            const tokenString = await token("bearerAuth", []);
+
+            if (tokenString) {
+                headerParameters["Authorization"] = `Bearer ${tokenString}`;
+            }
+        }
+
+        let urlPath = `/v1/tenants/{tenant_id}/billing/payments`;
+        urlPath = urlPath.replace(`{${"tenant_id"}}`, encodeURIComponent(String(requestParameters['tenantId'])));
+
+        return {
+            path: urlPath,
+            method: 'GET',
+            headers: headerParameters,
+            query: queryParameters,
+        };
+    }
+
+    /**
+     * Newest-first payment history for the tenant (OWNER/ADMIN only).  Backs the billing page\'s receipts list. ``invoice_url`` links the Stripe-hosted invoice when the payment ran through Stripe; CN (Ping++) payments render an in-app receipt from the row itself.
+     * List Billing Payments Handler
+     */
+    async listBillingPaymentsRaw(requestParameters: ListBillingPaymentsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<PaginatedResponseBillingPaymentResponse>> {
+        const requestOptions = await this.listBillingPaymentsRequestOpts(requestParameters);
+        const response = await this.request(requestOptions, initOverrides);
+
+        return new runtime.JSONApiResponse(response, (jsonValue) => PaginatedResponseBillingPaymentResponseFromJSON(jsonValue));
+    }
+
+    /**
+     * Newest-first payment history for the tenant (OWNER/ADMIN only).  Backs the billing page\'s receipts list. ``invoice_url`` links the Stripe-hosted invoice when the payment ran through Stripe; CN (Ping++) payments render an in-app receipt from the row itself.
+     * List Billing Payments Handler
+     */
+    async listBillingPayments(requestParameters: ListBillingPaymentsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<PaginatedResponseBillingPaymentResponse> {
+        const response = await this.listBillingPaymentsRaw(requestParameters, initOverrides);
+        return await response.value();
+    }
+
+}

package/src/apis/DocumentVersionsApi.ts

@@ -193,7 +193,7 @@ export interface DocumentVersionsApiInterface {
     createDocumentVersionRequestOpts(requestParameters: CreateDocumentVersionRequest): Promise<runtime.RequestOpts>;
 
     /**
-     * Create a new version for a document.  The version number is automatically incremented from the highest existing version.
+     * Create a new version for a document.  Requires an active document checkout held by the caller. Acquire one via ``POST /v1/documents/{id}/checkout`` first and release it after; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  The version number is automatically incremented from the highest existing version.
      * @summary Create Document Version Handler
      * @param {string} documentId Document ID
      * @param {*} [options] Override http request option.
@@ -203,7 +203,7 @@ export interface DocumentVersionsApiInterface {
     createDocumentVersionRaw(requestParameters: CreateDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<DocumentVersionResponse>>;
 
     /**
-     * Create a new version for a document.  The version number is automatically incremented from the highest existing version.
+     * Create a new version for a document.  Requires an active document checkout held by the caller. Acquire one via ``POST /v1/documents/{id}/checkout`` first and release it after; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  The version number is automatically incremented from the highest existing version.
      * Create Document Version Handler
      */
     createDocumentVersion(requestParameters: CreateDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<DocumentVersionResponse>;
@@ -217,7 +217,7 @@ export interface DocumentVersionsApiInterface {
     deleteDocumentVersionRequestOpts(requestParameters: DeleteDocumentVersionRequest): Promise<runtime.RequestOpts>;
 
     /**
-     * Delete a document version by its ID.  Cannot delete the active version of a document.
+     * Delete a document version by its ID.  Requires an active document checkout held by the caller on the **parent document** (the version itself carries no lock). Acquire one via ``POST /v1/documents/{id}/checkout`` first; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  Cannot delete the active version of a document.
      * @summary Delete Document Version Handler
      * @param {string} versionId DocumentVersion ID
      * @param {*} [options] Override http request option.
@@ -227,7 +227,7 @@ export interface DocumentVersionsApiInterface {
     deleteDocumentVersionRaw(requestParameters: DeleteDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>>;
 
     /**
-     * Delete a document version by its ID.  Cannot delete the active version of a document.
+     * Delete a document version by its ID.  Requires an active document checkout held by the caller on the **parent document** (the version itself carries no lock). Acquire one via ``POST /v1/documents/{id}/checkout`` first; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  Cannot delete the active version of a document.
      * Delete Document Version Handler
      */
     deleteDocumentVersion(requestParameters: DeleteDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void>;
@@ -615,7 +615,7 @@ export class DocumentVersionsApi extends runtime.BaseAPI implements DocumentVers
     }
 
     /**
-     * Create a new version for a document.  The version number is automatically incremented from the highest existing version.
+     * Create a new version for a document.  Requires an active document checkout held by the caller. Acquire one via ``POST /v1/documents/{id}/checkout`` first and release it after; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  The version number is automatically incremented from the highest existing version.
      * Create Document Version Handler
      */
     async createDocumentVersionRaw(requestParameters: CreateDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<DocumentVersionResponse>> {
@@ -626,7 +626,7 @@ export class DocumentVersionsApi extends runtime.BaseAPI implements DocumentVers
     }
 
     /**
-     * Create a new version for a document.  The version number is automatically incremented from the highest existing version.
+     * Create a new version for a document.  Requires an active document checkout held by the caller. Acquire one via ``POST /v1/documents/{id}/checkout`` first and release it after; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  The version number is automatically incremented from the highest existing version.
      * Create Document Version Handler
      */
     async createDocumentVersion(requestParameters: CreateDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<DocumentVersionResponse> {
@@ -670,7 +670,7 @@ export class DocumentVersionsApi extends runtime.BaseAPI implements DocumentVers
     }
 
     /**
-     * Delete a document version by its ID.  Cannot delete the active version of a document.
+     * Delete a document version by its ID.  Requires an active document checkout held by the caller on the **parent document** (the version itself carries no lock). Acquire one via ``POST /v1/documents/{id}/checkout`` first; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  Cannot delete the active version of a document.
      * Delete Document Version Handler
      */
     async deleteDocumentVersionRaw(requestParameters: DeleteDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>> {
@@ -681,7 +681,7 @@ export class DocumentVersionsApi extends runtime.BaseAPI implements DocumentVers
     }
 
     /**
-     * Delete a document version by its ID.  Cannot delete the active version of a document.
+     * Delete a document version by its ID.  Requires an active document checkout held by the caller on the **parent document** (the version itself carries no lock). Acquire one via ``POST /v1/documents/{id}/checkout`` first; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  Cannot delete the active version of a document.
      * Delete Document Version Handler
      */
     async deleteDocumentVersion(requestParameters: DeleteDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void> {

package/src/apis/DocumentsApi.ts

@@ -436,7 +436,7 @@ export interface DocumentsApiInterface {
     ingestDocumentVersionRequestOpts(requestParameters: IngestDocumentVersionRequest): Promise<runtime.RequestOpts>;
 
     /**
-     * Upload a new file for an existing document, creating a new version and triggering ingestion.  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\'s active_version) and the old version\'s Qdrant points are deactivated.  Returns 201 immediately with the Temporal ``workflow_id``. Ingestion runs in the background — poll ``GET /v1/system-jobs/document_versions/{workflow_id}`` (also given in the ``Location`` header) until ``status`` is terminal.
+     * Upload a new file for an existing document, creating a new version and triggering ingestion.  Requires an active document checkout held by the caller. Acquire one via ``POST /v1/documents/{id}/checkout`` first and release it after; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\'s active_version) and the old version\'s Qdrant points are deactivated.  Returns 201 immediately with the Temporal ``workflow_id``. Ingestion runs in the background — poll ``GET /v1/system-jobs/document_versions/{workflow_id}`` (also given in the ``Location`` header) until ``status`` is terminal.
      * @summary Ingest Document Version Handler
      * @param {string} documentId Document ID
      * @param {Blob} file 
@@ -453,7 +453,7 @@ export interface DocumentsApiInterface {
     ingestDocumentVersionRaw(requestParameters: IngestDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<IngestDocumentResponse>>;
 
     /**
-     * Upload a new file for an existing document, creating a new version and triggering ingestion.  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\'s active_version) and the old version\'s Qdrant points are deactivated.  Returns 201 immediately with the Temporal ``workflow_id``. Ingestion runs in the background — poll ``GET /v1/system-jobs/document_versions/{workflow_id}`` (also given in the ``Location`` header) until ``status`` is terminal.
+     * Upload a new file for an existing document, creating a new version and triggering ingestion.  Requires an active document checkout held by the caller. Acquire one via ``POST /v1/documents/{id}/checkout`` first and release it after; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\'s active_version) and the old version\'s Qdrant points are deactivated.  Returns 201 immediately with the Temporal ``workflow_id``. Ingestion runs in the background — poll ``GET /v1/system-jobs/document_versions/{workflow_id}`` (also given in the ``Location`` header) until ``status`` is terminal.
      * Ingest Document Version Handler
      */
     ingestDocumentVersion(requestParameters: IngestDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<IngestDocumentResponse>;
@@ -1261,7 +1261,7 @@ export class DocumentsApi extends runtime.BaseAPI implements DocumentsApiInterfa
     }
 
     /**
-     * Upload a new file for an existing document, creating a new version and triggering ingestion.  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\'s active_version) and the old version\'s Qdrant points are deactivated.  Returns 201 immediately with the Temporal ``workflow_id``. Ingestion runs in the background — poll ``GET /v1/system-jobs/document_versions/{workflow_id}`` (also given in the ``Location`` header) until ``status`` is terminal.
+     * Upload a new file for an existing document, creating a new version and triggering ingestion.  Requires an active document checkout held by the caller. Acquire one via ``POST /v1/documents/{id}/checkout`` first and release it after; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\'s active_version) and the old version\'s Qdrant points are deactivated.  Returns 201 immediately with the Temporal ``workflow_id``. Ingestion runs in the background — poll ``GET /v1/system-jobs/document_versions/{workflow_id}`` (also given in the ``Location`` header) until ``status`` is terminal.
      * Ingest Document Version Handler
      */
     async ingestDocumentVersionRaw(requestParameters: IngestDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<IngestDocumentResponse>> {
@@ -1272,7 +1272,7 @@ export class DocumentsApi extends runtime.BaseAPI implements DocumentsApiInterfa
     }
 
     /**
-     * Upload a new file for an existing document, creating a new version and triggering ingestion.  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\'s active_version) and the old version\'s Qdrant points are deactivated.  Returns 201 immediately with the Temporal ``workflow_id``. Ingestion runs in the background — poll ``GET /v1/system-jobs/document_versions/{workflow_id}`` (also given in the ``Location`` header) until ``status`` is terminal.
+     * Upload a new file for an existing document, creating a new version and triggering ingestion.  Requires an active document checkout held by the caller. Acquire one via ``POST /v1/documents/{id}/checkout`` first and release it after; otherwise this returns 409 Conflict (\"A document checkout is required to edit this document.\").  Creates a new document version (incrementing the highest version number), uploads the file to S3, and starts the ingestion workflow. Upon successful ingestion, the new version is automatically activated (set as the document\'s active_version) and the old version\'s Qdrant points are deactivated.  Returns 201 immediately with the Temporal ``workflow_id``. Ingestion runs in the background — poll ``GET /v1/system-jobs/document_versions/{workflow_id}`` (also given in the ``Location`` header) until ``status`` is terminal.
      * Ingest Document Version Handler
      */
     async ingestDocumentVersion(requestParameters: IngestDocumentVersionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<IngestDocumentResponse> {

package/src/apis/SubscriptionsApi.ts

@@ -16,28 +16,27 @@
 import * as runtime from '../runtime';
 import type {
   ChangeSubscriptionRequest,
+  CheckoutResponse,
   ErrorResponse,
   HTTPValidationError,
-  SubmitSubscriptionResponse,
-  SubscriptionPlanResponse,
+  TenantSubscriptionResponse,
 } from '../models/index';
 import {
     ChangeSubscriptionRequestFromJSON,
     ChangeSubscriptionRequestToJSON,
+    CheckoutResponseFromJSON,
+    CheckoutResponseToJSON,
     ErrorResponseFromJSON,
     ErrorResponseToJSON,
     HTTPValidationErrorFromJSON,
     HTTPValidationErrorToJSON,
-    SubmitSubscriptionResponseFromJSON,
-    SubmitSubscriptionResponseToJSON,
-    SubscriptionPlanResponseFromJSON,
-    SubscriptionPlanResponseToJSON,
+    TenantSubscriptionResponseFromJSON,
+    TenantSubscriptionResponseToJSON,
 } from '../models/index';
 
 export interface ChangeTenantSubscriptionRequest {
     tenantId: string;
     changeSubscriptionRequest: ChangeSubscriptionRequest;
-    idempotencyKey?: string | null;
 }
 
 export interface GetTenantSubscriptionRequest {
@@ -55,29 +54,27 @@ export interface SubscriptionsApiInterface {
      * Creates request options for changeTenantSubscription without sending the request
      * @param {string} tenantId 
      * @param {ChangeSubscriptionRequest} changeSubscriptionRequest 
-     * @param {string} [idempotencyKey] 
      * @throws {RequiredError}
      * @memberof SubscriptionsApiInterface
      */
     changeTenantSubscriptionRequestOpts(requestParameters: ChangeTenantSubscriptionRequest): Promise<runtime.RequestOpts>;
 
     /**
-     * Submit a subscription change (mock-Stripe).  OWNER-only on the target tenant. Validates the request (tenant + plan exist, ``num_seats`` within bounds), submits the (mock-)Stripe subscription update, and returns 202. The plan/seat write is NOT applied here — that happens in ``POST /webhooks/stripe/subscription`` after Stripe confirms the change.  Async two-hop workflow per ``docs/billing_additional_limits.md`` §\"Async payment workflow\": the dev environment exercises the same submit/webhook split as production will when the real Stripe SDK replaces the log-line stub in ``notify_billing``.  Optional ``Idempotency-Key`` request header is forwarded to Stripe verbatim (clients that retry the same logical operation MUST send the same value across attempts; Stripe collapses duplicates server- side). Absent the header, the server generates a fresh ``uuid4()`` per call and emits a warning — but only when a Stripe call is actually about to fire (i.e. the validation passed AND the change is not a no-op). Warning before validation would false-positive on every 4xx and on every redundant submit.  **Header value lands in structured logs.** The header value is forwarded into the ``stripe.update_subscription`` log event\'s ``idempotency_key`` field (and into the eventual real Stripe call). Use opaque random IDs (e.g. ``uuid4()``); do NOT pass user identifiers, tokens, or other sensitive material as the ``Idempotency-Key`` header.
+     * Start a subscription change (OWNER only).  Priced plan → validates the request, creates a provider checkout (Stripe Checkout redirect / Ping++ charge credential), and returns it — nothing is written until the provider\'s webhook confirms payment. Free plan → applied immediately for unbilled tenants, or scheduled for period end when a billed subscription is active (Stripe: ``cancel_at_period_end``; Ping++ prepay simply isn\'t renewed). Re-picking the current plan/seats while a Stripe cancellation is scheduled resumes the renewal. Deployments with no payment provider configured return 501 for priced checkouts (billing is optional — local-first).
      * @summary Change Tenant Subscription Handler
      * @param {string} tenantId 
      * @param {ChangeSubscriptionRequest} changeSubscriptionRequest 
-     * @param {string} [idempotencyKey] 
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      * @memberof SubscriptionsApiInterface
      */
-    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SubmitSubscriptionResponse>>;
+    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<CheckoutResponse>>;
 
     /**
-     * Submit a subscription change (mock-Stripe).  OWNER-only on the target tenant. Validates the request (tenant + plan exist, ``num_seats`` within bounds), submits the (mock-)Stripe subscription update, and returns 202. The plan/seat write is NOT applied here — that happens in ``POST /webhooks/stripe/subscription`` after Stripe confirms the change.  Async two-hop workflow per ``docs/billing_additional_limits.md`` §\"Async payment workflow\": the dev environment exercises the same submit/webhook split as production will when the real Stripe SDK replaces the log-line stub in ``notify_billing``.  Optional ``Idempotency-Key`` request header is forwarded to Stripe verbatim (clients that retry the same logical operation MUST send the same value across attempts; Stripe collapses duplicates server- side). Absent the header, the server generates a fresh ``uuid4()`` per call and emits a warning — but only when a Stripe call is actually about to fire (i.e. the validation passed AND the change is not a no-op). Warning before validation would false-positive on every 4xx and on every redundant submit.  **Header value lands in structured logs.** The header value is forwarded into the ``stripe.update_subscription`` log event\'s ``idempotency_key`` field (and into the eventual real Stripe call). Use opaque random IDs (e.g. ``uuid4()``); do NOT pass user identifiers, tokens, or other sensitive material as the ``Idempotency-Key`` header.
+     * Start a subscription change (OWNER only).  Priced plan → validates the request, creates a provider checkout (Stripe Checkout redirect / Ping++ charge credential), and returns it — nothing is written until the provider\'s webhook confirms payment. Free plan → applied immediately for unbilled tenants, or scheduled for period end when a billed subscription is active (Stripe: ``cancel_at_period_end``; Ping++ prepay simply isn\'t renewed). Re-picking the current plan/seats while a Stripe cancellation is scheduled resumes the renewal. Deployments with no payment provider configured return 501 for priced checkouts (billing is optional — local-first).
      * Change Tenant Subscription Handler
      */
-    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SubmitSubscriptionResponse>;
+    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<CheckoutResponse>;
 
     /**
      * Creates request options for getTenantSubscription without sending the request
@@ -88,20 +85,20 @@ export interface SubscriptionsApiInterface {
     getTenantSubscriptionRequestOpts(requestParameters: GetTenantSubscriptionRequest): Promise<runtime.RequestOpts>;
 
     /**
-     * Read the tenant\'s current subscription plan, including private tiers.  Any active member of the tenant can read. This is the only path that surfaces private (custom enterprise) plans to non-admin users — ``GET /public/subscriptions`` filters them out, but tenants on a private plan still need to see their own caps. Returns the full plan body (id, name, caps, max_seats, public flag, timestamps).  Returns 404 when the user is not a member of the tenant — same response shape as a non-existent tenant so we don\'t leak existence to outsiders.
+     * Read the tenant\'s current subscription: plan body + period state.  Any active member of the tenant can read. This is the only path that surfaces private (custom enterprise) plans to non-admin users — ``GET /public/subscriptions`` filters them out, but tenants on a private plan still need to see their own caps. The period fields let the FE render renewal/expiry state (billed subscriptions carry the paid-through date; unbilled ones a 100-year horizon), and ``will_renew`` distinguishes an auto-renewing Stripe subscription from one whose cancellation is scheduled (or a prepay/unbilled period that simply runs out).  Returns 404 when the user is not a member of the tenant — same response shape as a non-existent tenant so we don\'t leak existence to outsiders.
      * @summary Get Tenant Subscription Handler
      * @param {string} tenantId 
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      * @memberof SubscriptionsApiInterface
      */
-    getTenantSubscriptionRaw(requestParameters: GetTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SubscriptionPlanResponse>>;
+    getTenantSubscriptionRaw(requestParameters: GetTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<TenantSubscriptionResponse>>;
 
     /**
-     * Read the tenant\'s current subscription plan, including private tiers.  Any active member of the tenant can read. This is the only path that surfaces private (custom enterprise) plans to non-admin users — ``GET /public/subscriptions`` filters them out, but tenants on a private plan still need to see their own caps. Returns the full plan body (id, name, caps, max_seats, public flag, timestamps).  Returns 404 when the user is not a member of the tenant — same response shape as a non-existent tenant so we don\'t leak existence to outsiders.
+     * Read the tenant\'s current subscription: plan body + period state.  Any active member of the tenant can read. This is the only path that surfaces private (custom enterprise) plans to non-admin users — ``GET /public/subscriptions`` filters them out, but tenants on a private plan still need to see their own caps. The period fields let the FE render renewal/expiry state (billed subscriptions carry the paid-through date; unbilled ones a 100-year horizon), and ``will_renew`` distinguishes an auto-renewing Stripe subscription from one whose cancellation is scheduled (or a prepay/unbilled period that simply runs out).  Returns 404 when the user is not a member of the tenant — same response shape as a non-existent tenant so we don\'t leak existence to outsiders.
      * Get Tenant Subscription Handler
      */
-    getTenantSubscription(requestParameters: GetTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SubscriptionPlanResponse>;
+    getTenantSubscription(requestParameters: GetTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<TenantSubscriptionResponse>;
 
 }
 
@@ -134,10 +131,6 @@ export class SubscriptionsApi extends runtime.BaseAPI implements SubscriptionsAp
 
         headerParameters['Content-Type'] = 'application/json';
 
-        if (requestParameters['idempotencyKey'] != null) {
-            headerParameters['Idempotency-Key'] = String(requestParameters['idempotencyKey']);
-        }
-
         if (this.configuration && this.configuration.accessToken) {
             const token = this.configuration.accessToken;
             const tokenString = await token("bearerAuth", []);
@@ -160,21 +153,21 @@ export class SubscriptionsApi extends runtime.BaseAPI implements SubscriptionsAp
     }
 
     /**
-     * Submit a subscription change (mock-Stripe).  OWNER-only on the target tenant. Validates the request (tenant + plan exist, ``num_seats`` within bounds), submits the (mock-)Stripe subscription update, and returns 202. The plan/seat write is NOT applied here — that happens in ``POST /webhooks/stripe/subscription`` after Stripe confirms the change.  Async two-hop workflow per ``docs/billing_additional_limits.md`` §\"Async payment workflow\": the dev environment exercises the same submit/webhook split as production will when the real Stripe SDK replaces the log-line stub in ``notify_billing``.  Optional ``Idempotency-Key`` request header is forwarded to Stripe verbatim (clients that retry the same logical operation MUST send the same value across attempts; Stripe collapses duplicates server- side). Absent the header, the server generates a fresh ``uuid4()`` per call and emits a warning — but only when a Stripe call is actually about to fire (i.e. the validation passed AND the change is not a no-op). Warning before validation would false-positive on every 4xx and on every redundant submit.  **Header value lands in structured logs.** The header value is forwarded into the ``stripe.update_subscription`` log event\'s ``idempotency_key`` field (and into the eventual real Stripe call). Use opaque random IDs (e.g. ``uuid4()``); do NOT pass user identifiers, tokens, or other sensitive material as the ``Idempotency-Key`` header.
+     * Start a subscription change (OWNER only).  Priced plan → validates the request, creates a provider checkout (Stripe Checkout redirect / Ping++ charge credential), and returns it — nothing is written until the provider\'s webhook confirms payment. Free plan → applied immediately for unbilled tenants, or scheduled for period end when a billed subscription is active (Stripe: ``cancel_at_period_end``; Ping++ prepay simply isn\'t renewed). Re-picking the current plan/seats while a Stripe cancellation is scheduled resumes the renewal. Deployments with no payment provider configured return 501 for priced checkouts (billing is optional — local-first).
      * Change Tenant Subscription Handler
      */
-    async changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SubmitSubscriptionResponse>> {
+    async changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<CheckoutResponse>> {
         const requestOptions = await this.changeTenantSubscriptionRequestOpts(requestParameters);
         const response = await this.request(requestOptions, initOverrides);
 
-        return new runtime.JSONApiResponse(response, (jsonValue) => SubmitSubscriptionResponseFromJSON(jsonValue));
+        return new runtime.JSONApiResponse(response, (jsonValue) => CheckoutResponseFromJSON(jsonValue));
     }
 
     /**
-     * Submit a subscription change (mock-Stripe).  OWNER-only on the target tenant. Validates the request (tenant + plan exist, ``num_seats`` within bounds), submits the (mock-)Stripe subscription update, and returns 202. The plan/seat write is NOT applied here — that happens in ``POST /webhooks/stripe/subscription`` after Stripe confirms the change.  Async two-hop workflow per ``docs/billing_additional_limits.md`` §\"Async payment workflow\": the dev environment exercises the same submit/webhook split as production will when the real Stripe SDK replaces the log-line stub in ``notify_billing``.  Optional ``Idempotency-Key`` request header is forwarded to Stripe verbatim (clients that retry the same logical operation MUST send the same value across attempts; Stripe collapses duplicates server- side). Absent the header, the server generates a fresh ``uuid4()`` per call and emits a warning — but only when a Stripe call is actually about to fire (i.e. the validation passed AND the change is not a no-op). Warning before validation would false-positive on every 4xx and on every redundant submit.  **Header value lands in structured logs.** The header value is forwarded into the ``stripe.update_subscription`` log event\'s ``idempotency_key`` field (and into the eventual real Stripe call). Use opaque random IDs (e.g. ``uuid4()``); do NOT pass user identifiers, tokens, or other sensitive material as the ``Idempotency-Key`` header.
+     * Start a subscription change (OWNER only).  Priced plan → validates the request, creates a provider checkout (Stripe Checkout redirect / Ping++ charge credential), and returns it — nothing is written until the provider\'s webhook confirms payment. Free plan → applied immediately for unbilled tenants, or scheduled for period end when a billed subscription is active (Stripe: ``cancel_at_period_end``; Ping++ prepay simply isn\'t renewed). Re-picking the current plan/seats while a Stripe cancellation is scheduled resumes the renewal. Deployments with no payment provider configured return 501 for priced checkouts (billing is optional — local-first).
      * Change Tenant Subscription Handler
      */
-    async changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SubmitSubscriptionResponse> {
+    async changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<CheckoutResponse> {
         const response = await this.changeTenantSubscriptionRaw(requestParameters, initOverrides);
         return await response.value();
     }
@@ -215,21 +208,21 @@ export class SubscriptionsApi extends runtime.BaseAPI implements SubscriptionsAp
     }
 
     /**
-     * Read the tenant\'s current subscription plan, including private tiers.  Any active member of the tenant can read. This is the only path that surfaces private (custom enterprise) plans to non-admin users — ``GET /public/subscriptions`` filters them out, but tenants on a private plan still need to see their own caps. Returns the full plan body (id, name, caps, max_seats, public flag, timestamps).  Returns 404 when the user is not a member of the tenant — same response shape as a non-existent tenant so we don\'t leak existence to outsiders.
+     * Read the tenant\'s current subscription: plan body + period state.  Any active member of the tenant can read. This is the only path that surfaces private (custom enterprise) plans to non-admin users — ``GET /public/subscriptions`` filters them out, but tenants on a private plan still need to see their own caps. The period fields let the FE render renewal/expiry state (billed subscriptions carry the paid-through date; unbilled ones a 100-year horizon), and ``will_renew`` distinguishes an auto-renewing Stripe subscription from one whose cancellation is scheduled (or a prepay/unbilled period that simply runs out).  Returns 404 when the user is not a member of the tenant — same response shape as a non-existent tenant so we don\'t leak existence to outsiders.
      * Get Tenant Subscription Handler
      */
-    async getTenantSubscriptionRaw(requestParameters: GetTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SubscriptionPlanResponse>> {
+    async getTenantSubscriptionRaw(requestParameters: GetTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<TenantSubscriptionResponse>> {
         const requestOptions = await this.getTenantSubscriptionRequestOpts(requestParameters);
         const response = await this.request(requestOptions, initOverrides);
 
-        return new runtime.JSONApiResponse(response, (jsonValue) => SubscriptionPlanResponseFromJSON(jsonValue));
+        return new runtime.JSONApiResponse(response, (jsonValue) => TenantSubscriptionResponseFromJSON(jsonValue));
     }
 
     /**
-     * Read the tenant\'s current subscription plan, including private tiers.  Any active member of the tenant can read. This is the only path that surfaces private (custom enterprise) plans to non-admin users — ``GET /public/subscriptions`` filters them out, but tenants on a private plan still need to see their own caps. Returns the full plan body (id, name, caps, max_seats, public flag, timestamps).  Returns 404 when the user is not a member of the tenant — same response shape as a non-existent tenant so we don\'t leak existence to outsiders.
+     * Read the tenant\'s current subscription: plan body + period state.  Any active member of the tenant can read. This is the only path that surfaces private (custom enterprise) plans to non-admin users — ``GET /public/subscriptions`` filters them out, but tenants on a private plan still need to see their own caps. The period fields let the FE render renewal/expiry state (billed subscriptions carry the paid-through date; unbilled ones a 100-year horizon), and ``will_renew`` distinguishes an auto-renewing Stripe subscription from one whose cancellation is scheduled (or a prepay/unbilled period that simply runs out).  Returns 404 when the user is not a member of the tenant — same response shape as a non-existent tenant so we don\'t leak existence to outsiders.
      * Get Tenant Subscription Handler
      */
-    async getTenantSubscription(requestParameters: GetTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SubscriptionPlanResponse> {
+    async getTenantSubscription(requestParameters: GetTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<TenantSubscriptionResponse> {
         const response = await this.getTenantSubscriptionRaw(requestParameters, initOverrides);
         return await response.value();
     }

package/src/apis/TenantsApi.ts

@@ -191,7 +191,7 @@ export interface TenantsApiInterface {
     deleteTenantRequestOpts(requestParameters: DeleteTenantRequest): Promise<runtime.RequestOpts>;
 
     /**
-     * Delete a tenant.  Requires OWNER role in the tenant. Deletes the tenant\'s LiteLLM team/keys and S3 bucket after the DB transaction commits.
+     * Delete a tenant.  Requires OWNER role in the tenant. Refused (409) while a provider-billed subscription is live — deleting the tenant would not stop Stripe/Ping++ from charging for it; the OWNER must downgrade to free (or let the prepay period expire) first. Deletes the tenant\'s LiteLLM team/keys and S3 bucket after the DB transaction commits.
      * @summary Delete Tenant
      * @param {string} tenantId 
      * @param {*} [options] Override http request option.
@@ -201,7 +201,7 @@ export interface TenantsApiInterface {
     deleteTenantRaw(requestParameters: DeleteTenantRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>>;
 
     /**
-     * Delete a tenant.  Requires OWNER role in the tenant. Deletes the tenant\'s LiteLLM team/keys and S3 bucket after the DB transaction commits.
+     * Delete a tenant.  Requires OWNER role in the tenant. Refused (409) while a provider-billed subscription is live — deleting the tenant would not stop Stripe/Ping++ from charging for it; the OWNER must downgrade to free (or let the prepay period expire) first. Deletes the tenant\'s LiteLLM team/keys and S3 bucket after the DB transaction commits.
      * Delete Tenant
      */
     deleteTenant(requestParameters: DeleteTenantRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void>;
@@ -621,7 +621,7 @@ export class TenantsApi extends runtime.BaseAPI implements TenantsApiInterface {
     }
 
     /**
-     * Delete a tenant.  Requires OWNER role in the tenant. Deletes the tenant\'s LiteLLM team/keys and S3 bucket after the DB transaction commits.
+     * Delete a tenant.  Requires OWNER role in the tenant. Refused (409) while a provider-billed subscription is live — deleting the tenant would not stop Stripe/Ping++ from charging for it; the OWNER must downgrade to free (or let the prepay period expire) first. Deletes the tenant\'s LiteLLM team/keys and S3 bucket after the DB transaction commits.
      * Delete Tenant
      */
     async deleteTenantRaw(requestParameters: DeleteTenantRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>> {
@@ -632,7 +632,7 @@ export class TenantsApi extends runtime.BaseAPI implements TenantsApiInterface {
     }
 
     /**
-     * Delete a tenant.  Requires OWNER role in the tenant. Deletes the tenant\'s LiteLLM team/keys and S3 bucket after the DB transaction commits.
+     * Delete a tenant.  Requires OWNER role in the tenant. Refused (409) while a provider-billed subscription is live — deleting the tenant would not stop Stripe/Ping++ from charging for it; the OWNER must downgrade to free (or let the prepay period expire) first. Deletes the tenant\'s LiteLLM team/keys and S3 bucket after the DB transaction commits.
      * Delete Tenant
      */
     async deleteTenant(requestParameters: DeleteTenantRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void> {