@wix/auto_sdk_app-management_apps 1.0.0 → 1.0.1

package/build/cjs/index.typings.d.ts

@@ -12,7 +12,9 @@ interface V1App {
      */
     _id?: string | null;
     /**
-     * The display name of the application, shown to users and in App Market after publication. This is separate from the app namespace, slug, and code identifier.
+     * The display name shown to users and in App Market after publication, separate from the namespace, slug, and code identifier.
+     * On creation and update, `<`, `>`, double quotes, and apostrophes are escaped as
+     * `&lt;`, `&gt;`, `&quot;`, and `&apos;`. Responses contain the escaped value, which can be longer than the submitted name.
      * @maxLength 50
      */
     name?: string;
@@ -22,16 +24,25 @@ interface V1App {
      * @format GUID
      */
     accountId?: string | null;
-    /** Secrets for authentication and webhooks. */
+    /**
+     * Secrets for authentication and webhooks. Omitted from Get App responses by default.
+     * To retrieve them, include `APP_SECRETS` in Get App's `additionalFields`.
+     * Requires authorization to access the app's secrets.
+     */
     appSecrets?: AppSecrets;
     /**
-     * App namespace, combining an account or company identifier with an app-name component. For example, `@example-company/bookings-helper`.
+     * App namespace, combining an account or company identifier with an app-name component.
+     * For example, `@example-company/bookings-helper`.
+     * Assign it once through Set Namespace after creating the app. Don't supply it to Create App
+     * or Update App. Set Namespace fails if the app already has a namespace.
      * @minLength 1
      * @maxLength 150
      */
     namespace?: string | null;
     /**
-     * A JavaScript-compatible name for referencing the app in code, separate from its display name, namespace, and slug.
+     * An identifier for referencing the app in code, separate from its display name, namespace, and slug.
+     * Must start with a letter, underscore, or dollar sign; remaining characters can also include digits.
+     * JavaScript reserved words aren't rejected. Choose a non-reserved identifier if using this value as a JavaScript variable name.
      * Unique for non-companion apps. Companion apps return the shared value `companionApp`; use `id` to uniquely identify an app.
      * For example, the namespace `@app-builder/my-cool-app` can be represented by the code identifier `AppBuilderMyCoolApp`.
      * @minLength 3
@@ -40,7 +51,12 @@ interface V1App {
     codeIdentifier?: string | null;
     /** The state of the application. */
     status?: StatusWithLiterals;
-    /** Revision of the app. Changes each time the app is modified. */
+    /**
+     * Revision number, which increments by 1 each time the app is updated.
+     * To prevent conflicting changes, supply the current revision when calling Update App.
+     * Retrieve the latest revision through Get App before updating.
+     * Ignored when creating an app.
+     */
     revision?: string | null;
     /**
      * A human-readable, URL-friendly identifier for the app.
@@ -51,7 +67,9 @@ interface V1App {
     /** URLs used by the app's OAuth flow. */
     appUrls?: AppUrls;
     /**
-     * Identity of the user or app that created the app, including its source template when applicable.
+     * Identity and creation channel of the user or app that created the app, including its source template when applicable.
+     * Create App derives `id` and `type` from the caller's identity, replacing any supplied values.
+     * You can supply `sourceTemplateId` during creation. Creator information can't be changed through Update App.
      * @immutable
      */
     createdBy?: CreatedBy;
@@ -67,7 +85,7 @@ interface V1App {
      * @readonly
      */
     _updatedDate?: Date | null;
-    /** Changes not yet included in a released app version, grouped by type. */
+    /** Event-based tracking of unreleased changes, grouped by type. Updates asynchronously; see each flag for its tracking scope. */
     unreleasedChanges?: UnreleasedChanges;
     /** Indicates whether this app is a companion app assigned to a specific site or account. */
     companionApp?: boolean | null;
@@ -75,6 +93,8 @@ interface V1App {
 interface AppSecrets {
     /**
      * App authentication secret. Keep this value in a secure backend secret store.
+     * During rotation, this field contains the previous secret while both secrets exist.
+     * After the previous secret is retired, this field contains the replacement secret.
      * @readonly
      * @format GUID
      */
@@ -86,7 +106,8 @@ interface AppSecrets {
      */
     webhookPublicKey?: string;
     /**
-     * Additional authentication secret used during rotation. Present while the app has two secrets.
+     * Replacement authentication secret used during rotation. Present while the app has two secrets.
+     * After the previous secret is retired, this value moves to `appSecret` and this field is cleared.
      * @readonly
      * @format GUID
      */
@@ -132,44 +153,66 @@ interface AppUrls {
 }
 interface CreatedBy {
     /**
-     * ID of the user or app that created the app.
+     * Creator ID derived from the caller's identity; a supplied value is replaced during creation.
+     * Identifies a user for `USER`, `CODE_GEN`, and `APP_BUILDER_SELF_HOSTED`, or an app for `APP`.
      * @format GUID
      */
     _id?: string;
-    /** Type of identity that created the app. */
+    /** Creator identity or creation channel, derived from the caller's identity rather than a supplied value. */
     type?: CreatedByTypeWithLiterals;
     /**
-     * ID of the template used to create the app, when applicable.
+     * ID of the source template, when applicable. Can be supplied to Create App.
      * @format GUID
      */
     sourceTemplateId?: string | null;
 }
 declare enum CreatedByType {
+    /** Created by a user; `id` is the user's ID. */
     USER = "USER",
+    /** Created by an app; `id` is the app's ID. */
     APP = "APP",
+    /** Created through code generation; `id` is the initiating user's ID. */
     CODE_GEN = "CODE_GEN",
+    /** Created through the self-hosted app builder; `id` is the initiating user's ID. */
     APP_BUILDER_SELF_HOSTED = "APP_BUILDER_SELF_HOSTED"
 }
 /** @enumType */
 type CreatedByTypeWithLiterals = CreatedByType | 'USER' | 'APP' | 'CODE_GEN' | 'APP_BUILDER_SELF_HOSTED';
 interface InstallationPreferences extends InstallationPreferencesOpenButtonOptionsOneOf {
-    /** Component to open when `openButtonAction` is `OPEN_COMPONENT_ID`. */
+    /** Component to open. Supply `componentId` when `openButtonAction` is `OPEN_COMPONENT_ID`. */
     openComponentIdOptions?: OpenComponentId;
-    /** Destination for the user after installing the app. */
+    /**
+     * Preferred destination after installing an app with both editor and dashboard components.
+     * A recognized dashboard page in `postInstallationComponentId` takes precedence over this preference.
+     * Otherwise, `DASHBOARD` selects the dashboard and `EDITOR` selects the editor.
+     * On sites without an editor, `EDITOR` falls back to the dashboard.
+     * `UNKNOWN_REDIRECT_TARGET` leaves the default installation navigation unchanged.
+     */
     overridePostInstallationRedirect?: RedirectTargetWithLiterals;
     /**
-     * ID of the component the user is redirected to after installing the app.
+     * Optional ID of the app's dashboard page to open after installation.
+     * A recognized dashboard page takes precedence over `overridePostInstallationRedirect`.
+     * If omitted or not recognized as a dashboard page, navigation uses the redirect preference
+     * or the default installation flow. This field doesn't select an editor component.
      * @format GUID
      */
     postInstallationComponentId?: string | null;
-    /** Action performed when the user selects the app's Open button after installation. */
+    /**
+     * Action performed when the user selects the app's Open button after installation.
+     * For `OPEN_COMPONENT_ID`, supply `openComponentIdOptions.componentId`.
+     * `UNKNOWN_ACTION` means no explicit component-opening action is selected.
+     */
     openButtonAction?: OpenButtonActionWithLiterals;
-    /** Action required before the app can be uninstalled. */
+    /**
+     * Custom warning shown when a user tries to uninstall the app.
+     * Select `NO_ACTION` for no custom warning; `NONE_ACTION` represents an unspecified preference.
+     * The product and shipping values select warning text, rather than performing cleanup.
+     */
     uninstallAction?: UninstallActionsWithLiterals;
 }
 /** @oneof */
 interface InstallationPreferencesOpenButtonOptionsOneOf {
-    /** Component to open when `openButtonAction` is `OPEN_COMPONENT_ID`. */
+    /** Component to open. Supply `componentId` when `openButtonAction` is `OPEN_COMPONENT_ID`. */
     openComponentIdOptions?: OpenComponentId;
 }
 declare enum ShowConsentBehaviour {
@@ -180,14 +223,19 @@ declare enum ShowConsentBehaviour {
 /** @enumType */
 type ShowConsentBehaviourWithLiterals = ShowConsentBehaviour | 'DEFAULT_BEHAVIOUR' | 'SHOW_CONSENT' | 'SKIP_CONSENT';
 declare enum RedirectTarget {
+    /** Use the default installation navigation. */
     UNKNOWN_REDIRECT_TARGET = "UNKNOWN_REDIRECT_TARGET",
+    /** Prefer the site dashboard for an app with editor and dashboard components. */
     DASHBOARD = "DASHBOARD",
+    /** Prefer the editor; use the dashboard on sites without an editor. */
     EDITOR = "EDITOR"
 }
 /** @enumType */
 type RedirectTargetWithLiterals = RedirectTarget | 'UNKNOWN_REDIRECT_TARGET' | 'DASHBOARD' | 'EDITOR';
 declare enum OpenButtonAction {
+    /** No explicit component-opening action is selected. */
     UNKNOWN_ACTION = "UNKNOWN_ACTION",
+    /** Open the component specified by `openComponentIdOptions.componentId`. */
     OPEN_COMPONENT_ID = "OPEN_COMPONENT_ID"
 }
 /** @enumType */
@@ -204,23 +252,41 @@ interface OpenComponentId {
     componentId?: string;
 }
 declare enum UninstallActions {
+    /** Unspecified warning preference. Use `NO_ACTION` to explicitly select no custom warning. */
     NONE_ACTION = "NONE_ACTION",
+    /** Show the standard uninstall message without a custom warning. Default when no preference is stored. */
     NO_ACTION = "NO_ACTION",
+    /** Warn users to remove all products associated with the app from their store. */
     REMOVE_ALL_PRODUCT = "REMOVE_ALL_PRODUCT",
+    /** Warn users that shipping to regions served only by the app will be removed from checkout. */
     SHIPPING_RATES_REGION = "SHIPPING_RATES_REGION"
 }
 /** @enumType */
 type UninstallActionsWithLiterals = UninstallActions | 'NONE_ACTION' | 'NO_ACTION' | 'REMOVE_ALL_PRODUCT' | 'SHIPPING_RATES_REGION';
+/**
+ * Event-based tracking of changes not yet included in a released app version.
+ * Flags update asynchronously and reset when a production app version is created or updated.
+ */
 interface UnreleasedChanges {
-    /** Indicate components changes (create, update, delete) */
+    /** Whether components have unreleased creation, update, or deletion changes. */
     componentsChanges?: boolean;
-    /** Indicate app translations changes (create, update) */
+    /** Whether app translations have unreleased creation or update changes. */
     appTranslationsChanges?: boolean;
-    /** Indicate components translations changes (create, update) */
+    /**
+     * Whether component translations have unreleased update changes.
+     * Component-translation creation events currently aren't reflected in this flag.
+     */
     componentsTranslationChanges?: boolean;
-    /** Indicate app permissions changes (create, update, delete) */
+    /**
+     * Whether app permissions have unreleased creation or update changes.
+     * Permission-deletion events currently aren't reflected in this flag.
+     */
     appPermissionsChanges?: boolean;
-    /** Indicate app entity field changes (name, slug, namespace, codeIdentifier, partiallyConsumable) */
+    /**
+     * Whether app identity fields have unreleased changes, such as `name`, `slug`, `namespace`, and `codeIdentifier`.
+     * Doesn't track changes to `appUrls` or `installationPreferences`.
+     * Updates asynchronously after the app's update event; the update response may not yet reflect this flag.
+     */
     appEntityChanges?: boolean;
 }
 interface AppComponentMetadata {
@@ -412,7 +478,7 @@ interface AccountInfo {
 }
 interface AppOwnerChangedEvent {
     /**
-     * Id of the App to update
+     * App ID.
      * @format GUID
      */
     appId?: string;
@@ -428,16 +494,16 @@ interface AppOwnerChangedEvent {
     previousAccountId?: string;
 }
 interface CreateAppRequest {
-    /** App to be created */
+    /** App to create. */
     app: V1App;
 }
 interface CreateAppResponse {
-    /** The created App */
+    /** Created app. */
     app?: V1App;
 }
 interface GetAppRequest {
     /**
-     * Id of the App to retrieve
+     * App ID.
      * @format GUID
      */
     appId: string;
@@ -458,31 +524,31 @@ declare enum RequestedFields {
 /** @enumType */
 type RequestedFieldsWithLiterals = RequestedFields | 'APP_SECRETS';
 interface GetAppResponse {
-    /** The retrieved App */
+    /** Retrieved app. */
     app?: V1App;
 }
 interface UpdateAppRequest {
-    /** App to be updated, may be partial */
+    /** App to update. Specify the app ID, current revision, and fields to change. */
     app: V1App;
 }
 interface UpdateAppResponse {
-    /** The updated App */
+    /** Updated app. */
     app?: V1App;
 }
 interface GenerateSlugRequest {
     /**
-     * Id of the App to update
+     * App ID.
      * @format GUID
      */
     appId: string;
 }
 interface GenerateSlugResponse {
-    /** The modified app */
+    /** App with its generated or existing slug. */
     app?: V1App;
 }
 interface RenameSlugRequest {
     /**
-     * Id of the App to update
+     * App ID.
      * @format GUID
      */
     appId?: string;
@@ -494,12 +560,12 @@ interface RenameSlugRequest {
     newSlug?: string;
 }
 interface RenameSlugResponse {
-    /** The modified app */
+    /** App with its slug updated to the requested `newSlug`. */
     app?: V1App;
 }
 interface RenameCodeIdentifierRequest {
     /**
-     * Id of the App to update
+     * App ID.
      * @format GUID
      */
     appId?: string;
@@ -511,12 +577,12 @@ interface RenameCodeIdentifierRequest {
     newCodeIdentifier?: string;
 }
 interface RenameCodeIdentifierResponse {
-    /** The modified app */
+    /** App with its updated code identifier. */
     app?: V1App;
 }
 interface GetNamespaceSuggestionRequest {
     /**
-     * The id of the application
+     * App ID.
      * @format GUID
      */
     appId: string;
@@ -532,12 +598,12 @@ declare enum NamespaceType {
 /** @enumType */
 type NamespaceTypeWithLiterals = NamespaceType | 'ACCOUNT' | 'COMPANY';
 interface GetNamespaceSuggestionResponse {
-    /** The suggested namespace */
+    /** Suggested namespace. */
     namespace?: string;
 }
 interface GetNamespaceSuggestionByNameRequest {
     /**
-     * The name of the application
+     * App display name used to derive a namespace suggestion.
      * @maxLength 50
      */
     name: string;
@@ -546,7 +612,7 @@ interface GetNamespaceSuggestionByNameRequest {
 }
 interface GetNamespaceSuggestionByNameResponse {
     /**
-     * The suggested namespace
+     * Suggested namespace.
      * @minLength 1
      * @maxLength 150
      */
@@ -554,12 +620,12 @@ interface GetNamespaceSuggestionByNameResponse {
 }
 interface SetNamespaceRequest {
     /**
-     * Id of the App to update
+     * App ID.
      * @format GUID
      */
     appId: string;
     /**
-     * Name used to derive the app's namespace component, at most 50 characters before normalization.
+     * Name used to derive the app's namespace component.
      * Lowercased; runs of non-alphanumeric characters (including spaces and underscores) become hyphens, with leading/trailing separators removed.
      * For example, `Bookings Helper` and `Bookings_Helper` become `bookings-helper`. If no letters or digits remain, uses `untitled`.
      * Subject to the reserved-name restrictions documented on Set Namespace. For permitted Wix-owned apps, `wix` is removed before normalization.
@@ -595,7 +661,7 @@ interface SuggestCodeIdentifierResponse {
 }
 interface SetCodeIdentifierRequest {
     /**
-     * Id of the App to update
+     * App ID.
      * @format GUID
      */
     appId?: string;
@@ -775,7 +841,7 @@ interface Cursors {
 }
 interface SetPrivateAppRequest {
     /**
-     * Id of the App to update
+     * App ID.
      * @format GUID
      */
     appId?: string;
@@ -785,7 +851,7 @@ interface SetPrivateAppRequest {
     revision?: string;
 }
 interface SetPrivateAppResponse {
-    /** The modified app */
+    /** App with its `privateApp` setting updated to the requested value. */
     app?: V1App;
 }
 interface AppChangedEvent {
@@ -874,7 +940,7 @@ interface AppSlugChanged {
 }
 interface SetAppOwnerRequest {
     /**
-     * Id of the App to update
+     * App ID.
      * @format GUID
      */
     appId?: string;
@@ -887,7 +953,7 @@ interface SetAppOwnerRequest {
     revision?: string;
 }
 interface SetAppOwnerResponse {
-    /** The modified app */
+    /** App owned by the requested `accountId`. */
     app?: V1App;
 }
 interface AppUrlsChangedInOldServiceEvent extends AppUrlsChangedInOldServiceEventChangedUrlOneOf {
@@ -896,7 +962,7 @@ interface AppUrlsChangedInOldServiceEvent extends AppUrlsChangedInOldServiceEven
     /** redirect uris */
     redirectUriMessage?: RedirectUrlMessage;
     /**
-     * Id of the App to update
+     * App ID.
      * @format GUID
      */
     appId?: string;
@@ -918,7 +984,7 @@ interface RedirectUrlMessage {
 }
 interface CreateSecondarySecretRequest {
     /**
-     * ID of the App to update
+     * App ID.
      * @format GUID
      */
     appId: string;
@@ -942,7 +1008,7 @@ interface ActivateSecondarySecretResponse {
 }
 interface RotateSecretRequest {
     /**
-     * ID of the App to update
+     * App ID.
      * @format GUID
      */
     appId?: string;
@@ -953,7 +1019,7 @@ interface RotateSecretResponse {
 }
 interface RollbackSecretRequest {
     /**
-     * ID of the App to update
+     * App ID.
      * @format GUID
      */
     appId?: string;
@@ -964,24 +1030,24 @@ interface RollbackSecretResponse {
 }
 interface RevokeSecretRequest {
     /**
-     * ID of the App to update
+     * App ID.
      * @format GUID
      */
     appId: string;
-    /** Which of the two secrets to get rid of */
+    /** Credential to revoke. The app must have both a previous and a replacement secret. */
     secretToRevoke: SecretToRevokeWithLiterals;
 }
-/** Which of the App's two secrets to get rid of */
+/** Credential to revoke during app-secret rotation. */
 declare enum SecretToRevoke {
-    /** The secret the App had before the second one was created */
+    /** Switch signing to the replacement secret and schedule retirement of the previous secret. */
     PREVIOUS_SECRET = "PREVIOUS_SECRET",
-    /** The second secret that was created most recently */
+    /** Discard the replacement secret and restore signing with the previous secret. */
     NEW_SECRET = "NEW_SECRET"
 }
 /** @enumType */
 type SecretToRevokeWithLiterals = SecretToRevoke | 'PREVIOUS_SECRET' | 'NEW_SECRET';
 interface RevokeSecretResponse {
-    /** Scheduled retirement time of the previous secret. Set only for PREVIOUS_SECRET; omitted for NEW_SECRET. */
+    /** Scheduled retirement time of the previous secret. Returned for `PREVIOUS_SECRET` and omitted for `NEW_SECRET`. Use the latest returned timestamp. */
     previousSecretRevokeAt?: Date | null;
 }
 /** payload for kafka event for this version on app submit */
@@ -1176,13 +1242,13 @@ interface AssociateServiceAppResponse {
  * Setting `companionApp` to `true` is restricted to authorized companion-app provisioning services.
  * A supplied `slug` is ignored except for authorized companion-app provisioning callers; use Generate Slug after creation.
  * A supplied `codeIdentifier` must not contain `wix` (case-insensitive).
- * @param app - App to be created
+ * @param app - App to create.
  * @public
  * @documentationMaturity preview
  * @requiredField app
  * @permissionId DEV_CENTER.MANAGE_APPS
  * @permissionId DEV_CENTER.CREATE_APP
- * @returns The created App
+ * @returns Created app.
  * @fqn wix.devcenter.apps.v1.AppsService.CreateApp
  */
 declare function createApp(app: V1App): Promise<NonNullablePaths<V1App, `name` | `appSecrets.appSecret` | `appSecrets.webhookPublicKey` | `appSecrets.secondarySecretActive` | `status` | `appUrls.redirectUris` | `createdBy._id` | `createdBy.type` | `installationPreferences.openComponentIdOptions.componentId` | `installationPreferences.overridePostInstallationRedirect` | `installationPreferences.openButtonAction` | `installationPreferences.uninstallAction` | `unreleasedChanges.componentsChanges` | `unreleasedChanges.appTranslationsChanges` | `unreleasedChanges.componentsTranslationChanges` | `unreleasedChanges.appPermissionsChanges` | `unreleasedChanges.appEntityChanges`, 2>>;
@@ -1190,13 +1256,13 @@ declare function createApp(app: V1App): Promise<NonNullablePaths<V1App, `name` |
  * Retrieves an app by ID. App secrets are omitted by default.
  * To include `appSecrets`, add `APP_SECRETS` to `additionalFields`.
  * Retrieving secrets requires authorization to access the app's secrets.
- * @param appId - Id of the App to retrieve
+ * @param appId - App ID.
  * @public
  * @documentationMaturity preview
  * @requiredField appId
  * @permissionId WIX_DEVELOPERS.READ_APPS
  * @permissionId DEV_CENTER.READ_APPS
- * @returns The retrieved App
+ * @returns Retrieved app.
  * @fqn wix.devcenter.apps.v1.AppsService.GetApp
  */
 declare function getApp(appId: string, options?: GetAppOptions): Promise<NonNullablePaths<V1App, `name` | `appSecrets.appSecret` | `appSecrets.webhookPublicKey` | `appSecrets.secondarySecretActive` | `status` | `appUrls.redirectUris` | `createdBy._id` | `createdBy.type` | `installationPreferences.openComponentIdOptions.componentId` | `installationPreferences.overridePostInstallationRedirect` | `installationPreferences.openButtonAction` | `installationPreferences.uninstallAction` | `unreleasedChanges.componentsChanges` | `unreleasedChanges.appTranslationsChanges` | `unreleasedChanges.componentsTranslationChanges` | `unreleasedChanges.appPermissionsChanges` | `unreleasedChanges.appEntityChanges`, 2>>;
@@ -1219,7 +1285,7 @@ interface GetAppOptions {
  *
  * This method cannot update `appSecrets`, `accountId`, `namespace`, `slug`, `createdBy`,
  * `companionApp`, or `codeIdentifier`. Including any of these fields or their nested fields in the
- * update mask causes the entire request to fail; they are not silently ignored.
+ * request causes the entire request to fail; they aren't silently ignored.
  * Use Set Namespace to assign a namespace and Generate Slug to generate a slug. To rotate app
  * secrets, use Create Secondary Secret and Revoke Secret. This method does not support changing
  * the owning account, creator, companion-app designation, or code identifier.
@@ -1234,7 +1300,7 @@ interface GetAppOptions {
  * @permissionId DEV_CENTER.MODIFY_APP_PROPERTIES
  * @permissionId DEV_CENTER.WIX_BLOCKS_REQUESTS
  * @permissionId DEV_CENTER.WRITE_APP
- * @returns The updated App
+ * @returns Updated app.
  * @fqn wix.devcenter.apps.v1.AppsService.UpdateApp
  */
 declare function updateApp(_id: string, app: NonNullablePaths<UpdateApp, `revision`, 0>): Promise<NonNullablePaths<V1App, `name` | `appSecrets.appSecret` | `appSecrets.webhookPublicKey` | `appSecrets.secondarySecretActive` | `status` | `appUrls.redirectUris` | `createdBy._id` | `createdBy.type` | `installationPreferences.openComponentIdOptions.componentId` | `installationPreferences.overridePostInstallationRedirect` | `installationPreferences.openButtonAction` | `installationPreferences.uninstallAction` | `unreleasedChanges.componentsChanges` | `unreleasedChanges.appTranslationsChanges` | `unreleasedChanges.componentsTranslationChanges` | `unreleasedChanges.appPermissionsChanges` | `unreleasedChanges.appEntityChanges`, 2>>;
@@ -1245,7 +1311,9 @@ interface UpdateApp {
      */
     _id?: string | null;
     /**
-     * The display name of the application, shown to users and in App Market after publication. This is separate from the app namespace, slug, and code identifier.
+     * The display name shown to users and in App Market after publication, separate from the namespace, slug, and code identifier.
+     * On creation and update, `<`, `>`, double quotes, and apostrophes are escaped as
+     * `&lt;`, `&gt;`, `&quot;`, and `&apos;`. Responses contain the escaped value, which can be longer than the submitted name.
      * @maxLength 50
      */
     name?: string;
@@ -1255,16 +1323,25 @@ interface UpdateApp {
      * @format GUID
      */
     accountId?: string | null;
-    /** Secrets for authentication and webhooks. */
+    /**
+     * Secrets for authentication and webhooks. Omitted from Get App responses by default.
+     * To retrieve them, include `APP_SECRETS` in Get App's `additionalFields`.
+     * Requires authorization to access the app's secrets.
+     */
     appSecrets?: AppSecrets;
     /**
-     * App namespace, combining an account or company identifier with an app-name component. For example, `@example-company/bookings-helper`.
+     * App namespace, combining an account or company identifier with an app-name component.
+     * For example, `@example-company/bookings-helper`.
+     * Assign it once through Set Namespace after creating the app. Don't supply it to Create App
+     * or Update App. Set Namespace fails if the app already has a namespace.
      * @minLength 1
      * @maxLength 150
      */
     namespace?: string | null;
     /**
-     * A JavaScript-compatible name for referencing the app in code, separate from its display name, namespace, and slug.
+     * An identifier for referencing the app in code, separate from its display name, namespace, and slug.
+     * Must start with a letter, underscore, or dollar sign; remaining characters can also include digits.
+     * JavaScript reserved words aren't rejected. Choose a non-reserved identifier if using this value as a JavaScript variable name.
      * Unique for non-companion apps. Companion apps return the shared value `companionApp`; use `id` to uniquely identify an app.
      * For example, the namespace `@app-builder/my-cool-app` can be represented by the code identifier `AppBuilderMyCoolApp`.
      * @minLength 3
@@ -1273,7 +1350,12 @@ interface UpdateApp {
     codeIdentifier?: string | null;
     /** The state of the application. */
     status?: StatusWithLiterals;
-    /** Revision of the app. Changes each time the app is modified. */
+    /**
+     * Revision number, which increments by 1 each time the app is updated.
+     * To prevent conflicting changes, supply the current revision when calling Update App.
+     * Retrieve the latest revision through Get App before updating.
+     * Ignored when creating an app.
+     */
     revision?: string | null;
     /**
      * A human-readable, URL-friendly identifier for the app.
@@ -1284,7 +1366,9 @@ interface UpdateApp {
     /** URLs used by the app's OAuth flow. */
     appUrls?: AppUrls;
     /**
-     * Identity of the user or app that created the app, including its source template when applicable.
+     * Identity and creation channel of the user or app that created the app, including its source template when applicable.
+     * Create App derives `id` and `type` from the caller's identity, replacing any supplied values.
+     * You can supply `sourceTemplateId` during creation. Creator information can't be changed through Update App.
      * @immutable
      */
     createdBy?: CreatedBy;
@@ -1300,7 +1384,7 @@ interface UpdateApp {
      * @readonly
      */
     _updatedDate?: Date | null;
-    /** Changes not yet included in a released app version, grouped by type. */
+    /** Event-based tracking of unreleased changes, grouped by type. Updates asynchronously; see each flag for its tracking scope. */
     unreleasedChanges?: UnreleasedChanges;
     /** Indicates whether this app is a companion app assigned to a specific site or account. */
     companionApp?: boolean | null;
@@ -1310,7 +1394,7 @@ interface UpdateApp {
  * Does not generate a slug for companion apps; a companion app without a slug is returned unchanged.
  * When generating a slug, the stored app name must not contain `wix` for non-Wix apps (case-insensitive).
  * The exact names `google`, `facebook`, and `amazon` require privileged authorization (case-insensitive).
- * @param appId - Id of the App to update
+ * @param appId - App ID.
  * @public
  * @documentationMaturity preview
  * @requiredField appId
@@ -1327,7 +1411,7 @@ declare function generateSlug(appId: string): Promise<NonNullablePaths<GenerateS
  * The exact names `google`, `facebook`, and `amazon` require privileged authorization (case-insensitive).
  * If the base namespace is already used, suggests an alternative with a numeric suffix. Suggestions do not reserve a namespace.
  * Set Namespace derives its own namespace from `appName` without automatically adding a collision suffix. Choose a different `appName` and retry if it conflicts.
- * @param appId - The id of the application
+ * @param appId - App ID.
  * @public
  * @documentationMaturity preview
  * @requiredField appId
@@ -1348,7 +1432,7 @@ interface GetNamespaceSuggestionOptions {
  * The exact names `google`, `facebook`, and `amazon` require privileged authorization (case-insensitive).
  * If the base namespace is already used, suggests an alternative with a numeric suffix. Suggestions do not reserve a namespace.
  * Set Namespace derives its own namespace from `appName` without automatically adding a collision suffix. Choose a different `appName` and retry if it conflicts.
- * @param name - The name of the application
+ * @param name - App display name used to derive a namespace suggestion.
  * @public
  * @documentationMaturity preview
  * @requiredField name
@@ -1367,8 +1451,8 @@ interface GetNamespaceSuggestionByNameOptions {
  * The exact names `google`, `facebook`, and `amazon` require privileged authorization (case-insensitive).
  * Unlike namespace suggestions, this method does not automatically add a suffix when the derived namespace is already used.
  * Suggestions are not reservations; on a collision, choose a different `appName` and retry.
- * @param appId - Id of the App to update
- * @param appName - Name used to derive the app's namespace component, at most 50 characters before normalization.
+ * @param appId - App ID.
+ * @param appName - Name used to derive the app's namespace component.
  * Lowercased; runs of non-alphanumeric characters (including spaces and underscores) become hyphens, with leading/trailing separators removed.
  * For example, `Bookings Helper` and `Bookings_Helper` become `bookings-helper`. If no letters or digits remain, uses `untitled`.
  * Subject to the reserved-name restrictions documented on Set Namespace. For permitted Wix-owned apps, `wix` is removed before normalization.
@@ -1391,7 +1475,7 @@ interface SetNamespaceOptions {
  * (adding one here would break consistent-audience-for-shared-permission across all of them).
  * Renaming the permission would change who is actually authorized, so it stays as-is —
  * the real check is the MANUAL validateUpdateAppPermission(...) in code.
- * @param appId - ID of the App to update
+ * @param appId - App ID.
  * @public
  * @documentationMaturity preview
  * @requiredField appId
@@ -1408,8 +1492,8 @@ interface CreateSecondarySecretOptions {
  * (adding one here would break consistent-audience-for-shared-permission across all of them).
  * Renaming the permission would change who is actually authorized, so it stays as-is —
  * the real check is the MANUAL validateUpdateAppPermission(...) in code.
- * @param appId - ID of the App to update
- * @param secretToRevoke - Which of the two secrets to get rid of
+ * @param appId - App ID.
+ * @param secretToRevoke - Credential to revoke. The app must have both a previous and a replacement secret.
  * @public
  * @documentationMaturity preview
  * @requiredField appId