@knowledge-stack/ksapi 1.79.1 → 1.80.1

package/.openapi-generator/FILES

@@ -161,6 +161,7 @@ docs/StepInput.md
 docs/StepKind.md
 docs/StepOutput.md
 docs/SubmitFeedbackRequest.md
+docs/SubmitSubscriptionResponse.md
 docs/SubscriptionPlanResponse.md
 docs/SubscriptionsApi.md
 docs/SubtreeChunkGroup.md
@@ -396,6 +397,7 @@ src/models/StepInput.ts
 src/models/StepKind.ts
 src/models/StepOutput.ts
 src/models/SubmitFeedbackRequest.ts
+src/models/SubmitSubscriptionResponse.ts
 src/models/SubscriptionPlanResponse.ts
 src/models/SubtreeChunkGroup.ts
 src/models/SubtreeChunksResponse.ts

package/README.md

@@ -1,4 +1,4 @@
-# @knowledge-stack/ksapi@1.79.1
+# @knowledge-stack/ksapi@1.80.1
 
 A TypeScript SDK client for the localhost API.
 
@@ -344,6 +344,7 @@ All URIs are relative to *http://localhost:8000*
 - [StepKind](docs/StepKind.md)
 - [StepOutput](docs/StepOutput.md)
 - [SubmitFeedbackRequest](docs/SubmitFeedbackRequest.md)
+- [SubmitSubscriptionResponse](docs/SubmitSubscriptionResponse.md)
 - [SubscriptionPlanResponse](docs/SubscriptionPlanResponse.md)
 - [SubtreeChunkGroup](docs/SubtreeChunkGroup.md)
 - [SubtreeChunksResponse](docs/SubtreeChunksResponse.md)
@@ -408,7 +409,7 @@ and is automatically generated by the
 [OpenAPI Generator](https://openapi-generator.tech) project:
 
 - API version: `0.1.0`
-- Package version: `1.79.1`
+- Package version: `1.80.1`
 - Generator version: `7.21.0`
 - Build package: `org.openapitools.codegen.languages.TypeScriptFetchClientCodegen`
 

package/dist/apis/AgentApi.d.ts

@@ -38,7 +38,7 @@ export interface AgentApiInterface {
      */
     agentAskRequestOpts(requestParameters: AgentAskRequest): Promise<runtime.RequestOpts>;
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * @summary Agent Ask Handler
      * @param {AskRequest} askRequest
      * @param {string} [authorization]
@@ -49,7 +49,7 @@ export interface AgentApiInterface {
      */
     agentAskRaw(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AskResponse>>;
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAsk(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AskResponse>;
@@ -88,12 +88,12 @@ export declare class AgentApi extends runtime.BaseAPI implements AgentApiInterfa
      */
     agentAskRequestOpts(requestParameters: AgentAskRequest): Promise<runtime.RequestOpts>;
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAskRaw(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AskResponse>>;
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAsk(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AskResponse>;

package/dist/apis/AgentApi.js

@@ -87,7 +87,7 @@ class AgentApi extends runtime.BaseAPI {
         });
     }
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAskRaw(requestParameters, initOverrides) {
@@ -98,7 +98,7 @@ class AgentApi extends runtime.BaseAPI {
         });
     }
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAsk(requestParameters, initOverrides) {

package/dist/apis/SubscriptionsApi.d.ts

@@ -10,7 +10,7 @@
  * Do not edit the class manually.
  */
 import * as runtime from '../runtime';
-import type { ChangeSubscriptionRequest, SubscriptionPlanResponse, TenantResponse } from '../models/index';
+import type { ChangeSubscriptionRequest, SubmitSubscriptionResponse, SubscriptionPlanResponse } from '../models/index';
 export interface ChangeTenantSubscriptionRequest {
     tenantId: string;
     changeSubscriptionRequest: ChangeSubscriptionRequest;
@@ -42,7 +42,7 @@ export interface SubscriptionsApiInterface {
      */
     changeTenantSubscriptionRequestOpts(requestParameters: ChangeTenantSubscriptionRequest): Promise<runtime.RequestOpts>;
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * @summary Change Tenant Subscription Handler
      * @param {string} tenantId
      * @param {ChangeSubscriptionRequest} changeSubscriptionRequest
@@ -53,12 +53,12 @@ export interface SubscriptionsApiInterface {
      * @throws {RequiredError}
      * @memberof SubscriptionsApiInterface
      */
-    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<TenantResponse>>;
+    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SubmitSubscriptionResponse>>;
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
-    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<TenantResponse>;
+    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SubmitSubscriptionResponse>;
     /**
      * Creates request options for getTenantSubscription without sending the request
      * @param {string} tenantId
@@ -94,15 +94,15 @@ export declare class SubscriptionsApi extends runtime.BaseAPI implements Subscri
      */
     changeTenantSubscriptionRequestOpts(requestParameters: ChangeTenantSubscriptionRequest): Promise<runtime.RequestOpts>;
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
-    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<TenantResponse>>;
+    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SubmitSubscriptionResponse>>;
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
-    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<TenantResponse>;
+    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SubmitSubscriptionResponse>;
     /**
      * Creates request options for getTenantSubscription without sending the request
      */

package/dist/apis/SubscriptionsApi.js

@@ -94,18 +94,18 @@ class SubscriptionsApi extends runtime.BaseAPI {
         });
     }
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
     changeTenantSubscriptionRaw(requestParameters, initOverrides) {
         return __awaiter(this, void 0, void 0, function* () {
             const requestOptions = yield this.changeTenantSubscriptionRequestOpts(requestParameters);
             const response = yield this.request(requestOptions, initOverrides);
-            return new runtime.JSONApiResponse(response, (jsonValue) => (0, index_1.TenantResponseFromJSON)(jsonValue));
+            return new runtime.JSONApiResponse(response, (jsonValue) => (0, index_1.SubmitSubscriptionResponseFromJSON)(jsonValue));
         });
     }
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
     changeTenantSubscription(requestParameters, initOverrides) {

package/dist/esm/apis/AgentApi.d.ts

@@ -38,7 +38,7 @@ export interface AgentApiInterface {
      */
     agentAskRequestOpts(requestParameters: AgentAskRequest): Promise<runtime.RequestOpts>;
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * @summary Agent Ask Handler
      * @param {AskRequest} askRequest
      * @param {string} [authorization]
@@ -49,7 +49,7 @@ export interface AgentApiInterface {
      */
     agentAskRaw(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AskResponse>>;
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAsk(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AskResponse>;
@@ -88,12 +88,12 @@ export declare class AgentApi extends runtime.BaseAPI implements AgentApiInterfa
      */
     agentAskRequestOpts(requestParameters: AgentAskRequest): Promise<runtime.RequestOpts>;
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAskRaw(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AskResponse>>;
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAsk(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AskResponse>;

package/dist/esm/apis/AgentApi.js

@@ -51,7 +51,7 @@ export class AgentApi extends runtime.BaseAPI {
         });
     }
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAskRaw(requestParameters, initOverrides) {
@@ -62,7 +62,7 @@ export class AgentApi extends runtime.BaseAPI {
         });
     }
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refunds on any failure between consume and ``handle.result()`` returning — pre-enqueue ``start_workflow`` raises and post-enqueue workflow failures both refund.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAsk(requestParameters, initOverrides) {

package/dist/esm/apis/SubscriptionsApi.d.ts

@@ -10,7 +10,7 @@
  * Do not edit the class manually.
  */
 import * as runtime from '../runtime';
-import type { ChangeSubscriptionRequest, SubscriptionPlanResponse, TenantResponse } from '../models/index';
+import type { ChangeSubscriptionRequest, SubmitSubscriptionResponse, SubscriptionPlanResponse } from '../models/index';
 export interface ChangeTenantSubscriptionRequest {
     tenantId: string;
     changeSubscriptionRequest: ChangeSubscriptionRequest;
@@ -42,7 +42,7 @@ export interface SubscriptionsApiInterface {
      */
     changeTenantSubscriptionRequestOpts(requestParameters: ChangeTenantSubscriptionRequest): Promise<runtime.RequestOpts>;
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * @summary Change Tenant Subscription Handler
      * @param {string} tenantId
      * @param {ChangeSubscriptionRequest} changeSubscriptionRequest
@@ -53,12 +53,12 @@ export interface SubscriptionsApiInterface {
      * @throws {RequiredError}
      * @memberof SubscriptionsApiInterface
      */
-    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<TenantResponse>>;
+    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SubmitSubscriptionResponse>>;
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
-    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<TenantResponse>;
+    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SubmitSubscriptionResponse>;
     /**
      * Creates request options for getTenantSubscription without sending the request
      * @param {string} tenantId
@@ -94,15 +94,15 @@ export declare class SubscriptionsApi extends runtime.BaseAPI implements Subscri
      */
     changeTenantSubscriptionRequestOpts(requestParameters: ChangeTenantSubscriptionRequest): Promise<runtime.RequestOpts>;
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
-    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<TenantResponse>>;
+    changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SubmitSubscriptionResponse>>;
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
-    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<TenantResponse>;
+    changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SubmitSubscriptionResponse>;
     /**
      * Creates request options for getTenantSubscription without sending the request
      */

package/dist/esm/apis/SubscriptionsApi.js

@@ -21,7 +21,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import * as runtime from '../runtime';
-import { ChangeSubscriptionRequestToJSON, SubscriptionPlanResponseFromJSON, TenantResponseFromJSON, } from '../models/index';
+import { ChangeSubscriptionRequestToJSON, SubmitSubscriptionResponseFromJSON, SubscriptionPlanResponseFromJSON, } from '../models/index';
 /**
  *
  */
@@ -58,18 +58,18 @@ export class SubscriptionsApi extends runtime.BaseAPI {
         });
     }
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
     changeTenantSubscriptionRaw(requestParameters, initOverrides) {
         return __awaiter(this, void 0, void 0, function* () {
             const requestOptions = yield this.changeTenantSubscriptionRequestOpts(requestParameters);
             const response = yield this.request(requestOptions, initOverrides);
-            return new runtime.JSONApiResponse(response, (jsonValue) => TenantResponseFromJSON(jsonValue));
+            return new runtime.JSONApiResponse(response, (jsonValue) => SubmitSubscriptionResponseFromJSON(jsonValue));
         });
     }
     /**
-     * Change the tenant\'s subscription plan and/or seat count.  OWNER-only on the target tenant. Covers three scenarios with one shape:   - Plan change (with optional seat-count change).   - Pure seat-count change (same plan, different ``num_seats``).   - No-op (same plan, same seats) — returns 200, performs no DB or     Stripe writes.  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 — retries in that case are NOT deduplicated. v1 mock-Stripe doesn\'t care, but the contract is in place for the real integration.
+     * 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.
      * Change Tenant Subscription Handler
      */
     changeTenantSubscription(requestParameters, initOverrides) {

package/dist/esm/models/DocumentResponse.d.ts

@@ -121,6 +121,12 @@ export interface DocumentResponse {
      * @memberof DocumentResponse
      */
     tags?: Array<TagResponse> | null;
+    /**
+     * Whether the current caller has write access to this document. Only populated by endpoints that compute it (e.g. folder contents).
+     * @type {boolean}
+     * @memberof DocumentResponse
+     */
+    canWrite?: boolean | null;
 }
 /**
  * @export

package/dist/esm/models/DocumentResponse.js

@@ -85,6 +85,7 @@ export function DocumentResponseFromJSONTyped(json, ignoreDiscriminator) {
         'createdAt': (new Date(json['created_at'])),
         'updatedAt': (new Date(json['updated_at'])),
         'tags': json['tags'] == null ? undefined : (json['tags'].map(TagResponseFromJSON)),
+        'canWrite': json['can_write'] == null ? undefined : json['can_write'],
     };
 }
 export function DocumentResponseToJSON(json) {
@@ -112,5 +113,6 @@ export function DocumentResponseToJSONTyped(value, ignoreDiscriminator = false)
         'created_at': value['createdAt'].toISOString(),
         'updated_at': value['updatedAt'].toISOString(),
         'tags': value['tags'] == null ? undefined : (value['tags'].map(TagResponseToJSON)),
+        'can_write': value['canWrite'],
     };
 }

package/dist/esm/models/FolderResponse.d.ts

@@ -88,6 +88,12 @@ export interface FolderResponse {
      * @memberof FolderResponse
      */
     tags?: Array<TagResponse> | null;
+    /**
+     * Whether the current caller has write access to this folder. Only populated by endpoints that compute it (e.g. folder contents).
+     * @type {boolean}
+     * @memberof FolderResponse
+     */
+    canWrite?: boolean | null;
 }
 /**
  * @export

package/dist/esm/models/FolderResponse.js

@@ -67,6 +67,7 @@ export function FolderResponseFromJSONTyped(json, ignoreDiscriminator) {
         'createdAt': (new Date(json['created_at'])),
         'updatedAt': (new Date(json['updated_at'])),
         'tags': json['tags'] == null ? undefined : (json['tags'].map(TagResponseFromJSON)),
+        'canWrite': json['can_write'] == null ? undefined : json['can_write'],
     };
 }
 export function FolderResponseToJSON(json) {
@@ -89,5 +90,6 @@ export function FolderResponseToJSONTyped(value, ignoreDiscriminator = false) {
         'created_at': value['createdAt'].toISOString(),
         'updated_at': value['updatedAt'].toISOString(),
         'tags': value['tags'] == null ? undefined : (value['tags'].map(TagResponseToJSON)),
+        'can_write': value['canWrite'],
     };
 }

package/dist/esm/models/MeteredQuotaStatus.d.ts

@@ -46,6 +46,12 @@ export interface MeteredQuotaStatus {
      * @memberof MeteredQuotaStatus
      */
     periodEnd: Date;
+    /**
+     * Persistent additional-quota balance for this metric. Unchanged by period rollover; decremented when included is exhausted, incremented on refund or top-up.
+     * @type {number}
+     * @memberof MeteredQuotaStatus
+     */
+    additionalBalance?: number;
 }
 export declare const MeteredQuotaStatusPropertyValidationAttributesMap: {
     [property: string]: {

package/dist/esm/models/MeteredQuotaStatus.js

@@ -42,6 +42,7 @@ export function MeteredQuotaStatusFromJSONTyped(json, ignoreDiscriminator) {
         'limit': json['limit'],
         'periodStart': (new Date(json['period_start'])),
         'periodEnd': (new Date(json['period_end'])),
+        'additionalBalance': json['additional_balance'] == null ? undefined : json['additional_balance'],
     };
 }
 export function MeteredQuotaStatusToJSON(json) {
@@ -57,5 +58,6 @@ export function MeteredQuotaStatusToJSONTyped(value, ignoreDiscriminator = false
         'limit': value['limit'],
         'period_start': value['periodStart'].toISOString(),
         'period_end': value['periodEnd'].toISOString(),
+        'additional_balance': value['additionalBalance'],
     };
 }

package/dist/esm/models/SubmitSubscriptionResponse.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management
+ *
+ * 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.
+ */
+/**
+ * Result envelope for the subscription-change submit endpoint.
+ *
+ * The endpoint returns immediately after the (mock-)Stripe charge is
+ * submitted; the actual plan/seat write happens later in the Stripe
+ * subscription webhook. ``submitted=True`` always when the route
+ * succeeds (errors raise via the global handler).
+ *
+ * ``noop=True`` indicates the tenant is already at the requested
+ * ``(plan, num_seats)`` — no Stripe call was issued, no webhook will
+ * arrive, and the user's account is unchanged. Symmetric with
+ * ``StripeWebhookAck.replayed`` so client UIs can render "already
+ * on this plan" rather than spinning a "waiting for webhook"
+ * indicator forever.
+ *
+ * ``idempotency_key`` echoes the value forwarded to Stripe — clients
+ * can store it to correlate the eventual webhook receipt with the
+ * original request, and re-send it verbatim on retries.
+ * @export
+ * @interface SubmitSubscriptionResponse
+ */
+export interface SubmitSubscriptionResponse {
+    /**
+     * Always True when the submit returns 202.
+     * @type {boolean}
+     * @memberof SubmitSubscriptionResponse
+     */
+    submitted: boolean;
+    /**
+     * True when the tenant was already at the target ``(plan, num_seats)`` — no Stripe call was made and no webhook will arrive.
+     * @type {boolean}
+     * @memberof SubmitSubscriptionResponse
+     */
+    noop: boolean;
+    /**
+     * Idempotency key forwarded to Stripe — sourced from the ``Idempotency-Key`` request header or a server-generated uuid4 when absent.
+     * @type {string}
+     * @memberof SubmitSubscriptionResponse
+     */
+    idempotencyKey: string;
+}
+export declare const SubmitSubscriptionResponsePropertyValidationAttributesMap: {
+    [property: string]: {
+        maxLength?: number;
+        minLength?: number;
+        pattern?: string;
+        maximum?: number;
+        exclusiveMaximum?: boolean;
+        minimum?: number;
+        exclusiveMinimum?: boolean;
+        multipleOf?: number;
+        maxItems?: number;
+        minItems?: number;
+        uniqueItems?: boolean;
+    };
+};
+/**
+ * Check if a given object implements the SubmitSubscriptionResponse interface.
+ */
+export declare function instanceOfSubmitSubscriptionResponse(value: object): value is SubmitSubscriptionResponse;
+export declare function SubmitSubscriptionResponseFromJSON(json: any): SubmitSubscriptionResponse;
+export declare function SubmitSubscriptionResponseFromJSONTyped(json: any, ignoreDiscriminator: boolean): SubmitSubscriptionResponse;
+export declare function SubmitSubscriptionResponseToJSON(json: any): SubmitSubscriptionResponse;
+export declare function SubmitSubscriptionResponseToJSONTyped(value?: SubmitSubscriptionResponse | null, ignoreDiscriminator?: boolean): any;