@knowledge-stack/ksapi 1.80.0 → 1.81.0

package/docs/TenantSettingsUpdate.md

@@ -9,6 +9,7 @@ Name | Type
 ------------ | -------------
 `language` | [SupportedLanguage](SupportedLanguage.md)
 `description` | string
+`industry` | string
 `timezone` | string
 `brandName` | string
 `brandColor` | string
@@ -24,6 +25,7 @@ import type { TenantSettingsUpdate } from '@knowledge-stack/ksapi'
 const example = {
   "language": null,
   "description": null,
+  "industry": null,
   "timezone": null,
   "brandName": null,
   "brandColor": null,

package/docs/UserResponse.md

@@ -14,6 +14,8 @@ Name | Type
 `currentTenantId` | string
 `currentTenantRole` | [TenantUserRole](TenantUserRole.md)
 `defaultTenantId` | string
+`jobTitle` | string
+`onboardingCompletedAt` | Date
 
 ## Example
 
@@ -30,6 +32,8 @@ const example = {
   "currentTenantId": null,
   "currentTenantRole": null,
   "defaultTenantId": null,
+  "jobTitle": null,
+  "onboardingCompletedAt": null,
 } satisfies UserResponse
 
 console.log(example)

package/docs/UsersApi.md

@@ -5,7 +5,10 @@ All URIs are relative to *http://localhost:8000*
 | Method | HTTP request | Description |
 |------------- | ------------- | -------------|
 | [**getMe**](UsersApi.md#getme) | **GET** /v1/users/me | Get Me Handler |
+| [**skipOnboarding**](UsersApi.md#skiponboarding) | **POST** /v1/users/me/onboarding/skip | Skip Onboarding Handler |
 | [**updateMe**](UsersApi.md#updateme) | **PATCH** /v1/users | Update Me Handler |
+| [**updateOnboardingCompany**](UsersApi.md#updateonboardingcompany) | **PATCH** /v1/users/me/onboarding/company | Update Onboarding Company Handler |
+| [**updateOnboardingProfile**](UsersApi.md#updateonboardingprofile) | **PATCH** /v1/users/me/onboarding/profile | Update Onboarding Profile Handler |
 
 
 
@@ -80,6 +83,77 @@ No authorization required
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
 
+## skipOnboarding
+
+> UserResponse skipOnboarding(authorization, ksUat)
+
+Skip Onboarding Handler
+
+Mark onboarding complete without writing any profile/company fields.  Idempotent — calling this after onboarding is already complete returns the current state unchanged (the CRUD only stamps the timestamp when it is NULL).
+
+### Example
+
+```ts
+import {
+  Configuration,
+  UsersApi,
+} from '@knowledge-stack/ksapi';
+import type { SkipOnboardingRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const api = new UsersApi();
+
+  const body = {
+    // string (optional)
+    authorization: authorization_example,
+    // string (optional)
+    ksUat: ksUat_example,
+  } satisfies SkipOnboardingRequest;
+
+  try {
+    const data = await api.skipOnboarding(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
+| **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
+
+### Return type
+
+[**UserResponse**](UserResponse.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
 ## updateMe
 
 > UserResponse updateMe(updateUserRequest, authorization, ksUat)
@@ -153,3 +227,151 @@ No authorization required
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
+
+## updateOnboardingCompany
+
+> UserResponse updateOnboardingCompany(onboardingCompanyRequest, authorization, ksUat)
+
+Update Onboarding Company Handler
+
+Step 1 of onboarding: tenant-wide company info.  Writes ``industry`` and ``description`` into the current tenant\'s settings JSONB. Restricted to OWNER and ADMIN — invited USERs see a pre-filled, read-only step on the frontend instead.  Does not mark onboarding complete; the user finishes via the profile step. Re-running while the wizard is still open overwrites prior values; once onboarding has been completed/skipped, this endpoint returns 409. Post-onboarding edits go through PATCH /v1/tenants/{id}.
+
+### Example
+
+```ts
+import {
+  Configuration,
+  UsersApi,
+} from '@knowledge-stack/ksapi';
+import type { UpdateOnboardingCompanyRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const api = new UsersApi();
+
+  const body = {
+    // OnboardingCompanyRequest
+    onboardingCompanyRequest: ...,
+    // string (optional)
+    authorization: authorization_example,
+    // string (optional)
+    ksUat: ksUat_example,
+  } satisfies UpdateOnboardingCompanyRequest;
+
+  try {
+    const data = await api.updateOnboardingCompany(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **onboardingCompanyRequest** | [OnboardingCompanyRequest](OnboardingCompanyRequest.md) |  | |
+| **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
+| **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
+
+### Return type
+
+[**UserResponse**](UserResponse.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+- **Content-Type**: `application/json`
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+
+## updateOnboardingProfile
+
+> UserResponse updateOnboardingProfile(onboardingProfileRequest, authorization, ksUat)
+
+Update Onboarding Profile Handler
+
+Step 2 (final) of onboarding: per-user profile for the current tenant.  Writes name to the User row (global) and job_title to the TenantUser row (per-tenant), then stamps ``onboarding_completed_at`` on the membership. Returns 409 if onboarding has already been completed or skipped — post-onboarding edits go through PATCH /v1/users (name) or a future per-membership profile endpoint (job_title).
+
+### Example
+
+```ts
+import {
+  Configuration,
+  UsersApi,
+} from '@knowledge-stack/ksapi';
+import type { UpdateOnboardingProfileRequest } from '@knowledge-stack/ksapi';
+
+async function example() {
+  console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
+  const api = new UsersApi();
+
+  const body = {
+    // OnboardingProfileRequest
+    onboardingProfileRequest: ...,
+    // string (optional)
+    authorization: authorization_example,
+    // string (optional)
+    ksUat: ksUat_example,
+  } satisfies UpdateOnboardingProfileRequest;
+
+  try {
+    const data = await api.updateOnboardingProfile(body);
+    console.log(data);
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+// Run the test
+example().catch(console.error);
+```
+
+### Parameters
+
+
+| Name | Type | Description  | Notes |
+|------------- | ------------- | ------------- | -------------|
+| **onboardingProfileRequest** | [OnboardingProfileRequest](OnboardingProfileRequest.md) |  | |
+| **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
+| **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
+
+### Return type
+
+[**UserResponse**](UserResponse.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+- **Content-Type**: `application/json`
+- **Accept**: `application/json`
+
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+| **200** | Successful Response |  -  |
+| **422** | Validation Error |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+

package/package.json

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

package/src/apis/AgentApi.ts

@@ -64,7 +64,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] 
@@ -76,7 +76,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>;
@@ -150,7 +150,7 @@ export class AgentApi extends runtime.BaseAPI implements AgentApiInterface {
     }
 
     /**
-     * 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
      */
     async agentAskRaw(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AskResponse>> {
@@ -161,7 +161,7 @@ export class AgentApi extends runtime.BaseAPI implements AgentApiInterface {
     }
 
     /**
-     * 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
      */
     async agentAsk(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AskResponse> {

package/src/apis/SubscriptionsApi.ts

@@ -17,18 +17,18 @@ import * as runtime from '../runtime';
 import type {
   ChangeSubscriptionRequest,
   HTTPValidationError,
+  SubmitSubscriptionResponse,
   SubscriptionPlanResponse,
-  TenantResponse,
 } from '../models/index';
 import {
     ChangeSubscriptionRequestFromJSON,
     ChangeSubscriptionRequestToJSON,
     HTTPValidationErrorFromJSON,
     HTTPValidationErrorToJSON,
+    SubmitSubscriptionResponseFromJSON,
+    SubmitSubscriptionResponseToJSON,
     SubscriptionPlanResponseFromJSON,
     SubscriptionPlanResponseToJSON,
-    TenantResponseFromJSON,
-    TenantResponseToJSON,
 } from '../models/index';
 
 export interface ChangeTenantSubscriptionRequest {
@@ -65,7 +65,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 
@@ -76,13 +76,13 @@ 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
@@ -165,21 +165,21 @@ export class SubscriptionsApi extends runtime.BaseAPI implements SubscriptionsAp
     }
 
     /**
-     * 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
      */
-    async changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<TenantResponse>> {
+    async changeTenantSubscriptionRaw(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SubmitSubscriptionResponse>> {
         const requestOptions = await this.changeTenantSubscriptionRequestOpts(requestParameters);
         const response = await 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
      */
-    async changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<TenantResponse> {
+    async changeTenantSubscription(requestParameters: ChangeTenantSubscriptionRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SubmitSubscriptionResponse> {
         const response = await this.changeTenantSubscriptionRaw(requestParameters, initOverrides);
         return await response.value();
     }