@greensecurity/javascript-sdk 0.46.0 → 0.47.0-beta.1

package/src/sdk/apps.ts

@@ -0,0 +1,568 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { appsAddAppDeveloper } from "../funcs/appsAddAppDeveloper.js";
+import { appsCloseAppDevSession } from "../funcs/appsCloseAppDevSession.js";
+import { appsCreateAppDevSession } from "../funcs/appsCreateAppDevSession.js";
+import { appsDeleteAppSecret } from "../funcs/appsDeleteAppSecret.js";
+import { appsFindAppSecret } from "../funcs/appsFindAppSecret.js";
+import { appsHeartbeatAppDevSession } from "../funcs/appsHeartbeatAppDevSession.js";
+import { appsListAppActivations } from "../funcs/appsListAppActivations.js";
+import { appsListAppDevelopers } from "../funcs/appsListAppDevelopers.js";
+import { appsListAppSecrets } from "../funcs/appsListAppSecrets.js";
+import { appsListAppVersions } from "../funcs/appsListAppVersions.js";
+import { appsPublishAppManifest } from "../funcs/appsPublishAppManifest.js";
+import { appsRemoveAppDeveloper } from "../funcs/appsRemoveAppDeveloper.js";
+import { appsRotateAppWebhookEndpointSecret } from "../funcs/appsRotateAppWebhookEndpointSecret.js";
+import { appsSetAppSecret } from "../funcs/appsSetAppSecret.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as components from "../models/components/index.js";
+import * as operations from "../models/operations/index.js";
+import { unwrapAsync } from "../types/fp.js";
+import { PageIterator, unwrapResultIterator } from "../types/operations.js";
+
+export class Apps extends ClientSDK {
+  /**
+   * List your app's activations
+   *
+   * @remarks
+   * Lists the activations (installations) of the apps your service account belongs to: which
+   * app, what each installation covers, and when it was made. A back-end-only app has no UI to
+   * be handed an activation id, so this is where its backend finds the `activation_id` it passes
+   * to `POST /oauth/token` with `grant_type=client_credentials` to get an installation token for
+   * one installation.
+   *
+   * To hear about installs as they happen, declare `webhooks` in your app's manifest: your app's
+   * own endpoint then receives `MarketplaceAppActivation.created`, `.updated` and `.destroyed`
+   * for every installation, the first one included. Use this list to reconcile, on start-up and
+   * after any delivery you could not process.
+   *
+   * Sorted by `id` unless `sort` says otherwise, ascending unless `desc` is set.
+   *
+   * **Permissions.** Accepts only the app service account's own unscoped token, as
+   * `Authorization: Bearer`: its permanent token, or an access token from `client_credentials`
+   * issued without `activation_id` or `scope`. App tokens (`gsu_`, `gsi_`, `gsd_`, and the
+   * `gsdr_` refresh token) are refused with `403` — an installation token acts as the same service
+   * account but is narrowed to one installation — and so is a token narrowed with `scope`. A
+   * `token` query parameter is refused with `401`, even alongside the header. A user that is not
+   * the service account of any app gets `403`.
+   */
+  async listAppActivations(
+    request: operations.ListAppActivationsRequest,
+    options?: RequestOptions,
+  ): Promise<
+    PageIterator<operations.ListAppActivationsResponse, { page: number }>
+  > {
+    return unwrapResultIterator(appsListAppActivations(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Rotate your app's webhook signing secret
+   *
+   * @remarks
+   * Issues a new signing secret for your app's own webhook endpoint (the one its manifest's
+   * `webhooks` declares) and returns it. This is the only way to obtain the secret, and the only
+   * response that ever carries it.
+   *
+   * Call it once after the first publish that adds `webhooks`: the endpoint is created with a
+   * secret nobody has seen, so deliveries fail your signature check until you rotate. Each retry
+   * is signed again when it is sent, so a delivery still being retried (for about 50 minutes after
+   * it was first sent) verifies once you have the new secret; reconcile anything older with
+   * `GET /marketplace/activations`. Call it again whenever you want to replace the secret or have lost it. After the
+   * first rotation, the secret being replaced keeps signing for 24 hours, next to the new one, so
+   * you can deploy the new secret without rejecting deliveries already on their way.
+   *
+   * Changing `webhooks.url` or `webhooks.events` in a later publish keeps the secret.
+   *
+   * **Permissions.** Accepts only the app service account's own unscoped token, as
+   * `Authorization: Bearer`: its permanent token, or an access token from `client_credentials`
+   * issued without `activation_id` or `scope`. App tokens (`gsu_`, `gsi_`, `gsd_`, and the
+   * `gsdr_` refresh token) and a token narrowed with `scope` are refused with `403`. A `token`
+   * query parameter is refused with `401`, even alongside the header. An app the caller is not the
+   * service account of reads as `404`, the same as one that does not exist.
+   */
+  async rotateAppWebhookEndpointSecret(
+    request:
+      operations.RotateAppWebhookEndpointSecretRotateAppWebhookEndpointSecretRequest,
+    options?: RequestOptions,
+  ): Promise<components.AppWebhookEndpointSecret> {
+    return unwrapAsync(appsRotateAppWebhookEndpointSecret(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * List app secrets
+   *
+   * @remarks
+   * Lists the secrets in one scope of your app's activation. Payloads are never included; use
+   * `GET /apps/secrets/find` with `expand=payload` to read one. Expired secrets are not
+   * listed.
+   *
+   * Sorted by `name` unless `sort` says otherwise, ascending unless `desc` is set.
+   *
+   * **Permissions.** Send one of these as `Authorization: Bearer`; any other token is refused
+   * with `403`.
+   *
+   * - **An app token**: an app user token (`gsu_`) or an app installation token (`gsi_`). The
+   *   activation comes from the token, so leave `activation_id` out; if you send it, it must be
+   *   the token's own activation (`403` otherwise). Either token may read the `installation`
+   *   scope. For the `user` scope:
+   *   - an app user token reaches only its own user (`user_id` may be left out);
+   *   - an installation token the host minted for one of your views reaches only that view's
+   *     viewer (`user_id` may be left out);
+   *   - an installation token from `client_credentials` reaches any user its activation
+   *     covers, and `user_id` is required.
+   * - **Your app's service account**: its permanent token, or a short-lived OAuth access token
+   *   issued to it without `scope` (by `client_credentials` without `activation_id`, or by the
+   *   `refresh_token` grant). A token issued with `scope` is refused with `403`, and any other
+   *   kind of token, such as a one-time sign-in link token, with `403` "This kind of token may
+   *   not access app secrets". It has no activation of its own, so `activation_id` is required
+   *   (`422` without it) and must be one of your app's activations (`403` otherwise). Its `user`
+   *   scope reaches any user the activation covers, and `user_id` is required.
+   *
+   * A `user_id` that does not exist and one the token may not reach get the same `403` "This
+   * credential may not access secrets of that user", so the endpoint never reveals which user
+   * ids exist.
+   *
+   * Whatever the token, your app must hold the platform permission `app_secrets.write`: list
+   * it in the manifest's `permissions` and upload. Until then every Secret Store call is
+   * refused with `403` "This app has not been granted app_secrets.write." For the service
+   * account this is checked before `activation_id` is looked at, so an app without the
+   * permission gets that answer whether or not it sent an `activation_id`.
+   *
+   * Every response carries `Cache-Control: no-store`, errors included, so no cache keeps a
+   * secret.
+   */
+  async listAppSecrets(
+    request: operations.ListAppSecretsRequest,
+    options?: RequestOptions,
+  ): Promise<
+    PageIterator<operations.ListAppSecretsResponse, { page: number }>
+  > {
+    return unwrapResultIterator(appsListAppSecrets(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Set an app secret
+   *
+   * @remarks
+   * Creates a secret, or replaces the payload and expiry of the secret with the same `name`
+   * in the same scope. Secrets are encrypted at rest and belong to one activation of your
+   * app: the app token's own activation, or the `activation_id` the service account sends.
+   * Removing that activation, or changing what it covers (its app, or the site, system,
+   * facility, company or user it is installed for), deletes all of its secrets.
+   *
+   * Each scope holds at most 25 secrets, and a payload is at most 8192 bytes once UTF-8
+   * encoded (fewer characters than that if it has multi-byte ones). `expires_at`, when
+   * given, must be in the future and less than 100 years away.
+   *
+   * **Permissions.** Send one of these as `Authorization: Bearer`; any other token is refused
+   * with `403`.
+   *
+   * - **An app token**: an app user token (`gsu_`) or an app installation token (`gsi_`). The
+   *   activation comes from the token, so leave `activation_id` out; if you send it, it must be
+   *   the token's own activation (`403` otherwise). Either token may write to the `installation`
+   *   scope. For the `user` scope:
+   *   - an app user token reaches only its own user (`user_id` may be left out);
+   *   - an installation token the host minted for one of your views reaches only that view's
+   *     viewer (`user_id` may be left out);
+   *   - an installation token from `client_credentials` reaches any user its activation
+   *     covers, and `user_id` is required.
+   * - **Your app's service account**: its permanent token, or a short-lived OAuth access token
+   *   issued to it without `scope` (by `client_credentials` without `activation_id`, or by the
+   *   `refresh_token` grant). A token issued with `scope` is refused with `403`, and any other
+   *   kind of token, such as a one-time sign-in link token, with `403` "This kind of token may
+   *   not access app secrets". It has no activation of its own, so `activation_id` is required
+   *   (`422` without it) and must be one of your app's activations (`403` otherwise). Its `user`
+   *   scope reaches any user the activation covers, and `user_id` is required.
+   *
+   * A `user_id` that does not exist and one the token may not reach get the same `403` "This
+   * credential may not access secrets of that user", so the endpoint never reveals which user
+   * ids exist.
+   *
+   * Whatever the token, your app must hold the platform permission `app_secrets.write`: list
+   * it in the manifest's `permissions` and upload. Until then every Secret Store call is
+   * refused with `403` "This app has not been granted app_secrets.write." For the service
+   * account this is checked before `activation_id` is looked at, so an app without the
+   * permission gets that answer whether or not it sent an `activation_id`.
+   *
+   * Every response carries `Cache-Control: no-store`, errors included, so no cache keeps a
+   * secret.
+   */
+  async setAppSecret(
+    request: components.AppSecretSetRequest,
+    options?: RequestOptions,
+  ): Promise<components.AppSecret> {
+    return unwrapAsync(appsSetAppSecret(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Find an app secret
+   *
+   * @remarks
+   * Returns the secret with `name` in the given scope. The payload is only included when you
+   * ask for it with `expand=payload`, so a lookup that only needs to know the secret exists
+   * never moves the value. An expired secret is reported as not found.
+   *
+   * **Permissions.** Send one of these as `Authorization: Bearer`; any other token is refused
+   * with `403`.
+   *
+   * - **An app token**: an app user token (`gsu_`) or an app installation token (`gsi_`). The
+   *   activation comes from the token, so leave `activation_id` out; if you send it, it must be
+   *   the token's own activation (`403` otherwise). Either token may read the `installation`
+   *   scope. For the `user` scope:
+   *   - an app user token reaches only its own user (`user_id` may be left out);
+   *   - an installation token the host minted for one of your views reaches only that view's
+   *     viewer (`user_id` may be left out);
+   *   - an installation token from `client_credentials` reaches any user its activation
+   *     covers, and `user_id` is required.
+   * - **Your app's service account**: its permanent token, or a short-lived OAuth access token
+   *   issued to it without `scope` (by `client_credentials` without `activation_id`, or by the
+   *   `refresh_token` grant). A token issued with `scope` is refused with `403`, and any other
+   *   kind of token, such as a one-time sign-in link token, with `403` "This kind of token may
+   *   not access app secrets". It has no activation of its own, so `activation_id` is required
+   *   (`422` without it) and must be one of your app's activations (`403` otherwise). Its `user`
+   *   scope reaches any user the activation covers, and `user_id` is required.
+   *
+   * A `user_id` that does not exist and one the token may not reach get the same `403` "This
+   * credential may not access secrets of that user", so the endpoint never reveals which user
+   * ids exist.
+   *
+   * Whatever the token, your app must hold the platform permission `app_secrets.write`: list
+   * it in the manifest's `permissions` and upload. Until then every Secret Store call is
+   * refused with `403` "This app has not been granted app_secrets.write." For the service
+   * account this is checked before `activation_id` is looked at, so an app without the
+   * permission gets that answer whether or not it sent an `activation_id`.
+   *
+   * Every response carries `Cache-Control: no-store`, errors included, so no cache keeps a
+   * secret.
+   */
+  async findAppSecret(
+    request: operations.FindAppSecretRequest,
+    options?: RequestOptions,
+  ): Promise<components.AppSecret> {
+    return unwrapAsync(appsFindAppSecret(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Delete an app secret
+   *
+   * @remarks
+   * Deletes the secret with `name` in the given scope, and returns it with `deleted: true`.
+   *
+   * **Permissions.** Send one of these as `Authorization: Bearer`; any other token is refused
+   * with `403`.
+   *
+   * - **An app token**: an app user token (`gsu_`) or an app installation token (`gsi_`). The
+   *   activation comes from the token, so leave `activation_id` out; if you send it, it must be
+   *   the token's own activation (`403` otherwise). Either token may delete from the `installation`
+   *   scope. For the `user` scope:
+   *   - an app user token reaches only its own user (`user_id` may be left out);
+   *   - an installation token the host minted for one of your views reaches only that view's
+   *     viewer (`user_id` may be left out);
+   *   - an installation token from `client_credentials` reaches any user its activation
+   *     covers, and `user_id` is required.
+   * - **Your app's service account**: its permanent token, or a short-lived OAuth access token
+   *   issued to it without `scope` (by `client_credentials` without `activation_id`, or by the
+   *   `refresh_token` grant). A token issued with `scope` is refused with `403`, and any other
+   *   kind of token, such as a one-time sign-in link token, with `403` "This kind of token may
+   *   not access app secrets". It has no activation of its own, so `activation_id` is required
+   *   (`422` without it) and must be one of your app's activations (`403` otherwise). Its `user`
+   *   scope reaches any user the activation covers, and `user_id` is required.
+   *
+   * A `user_id` that does not exist and one the token may not reach get the same `403` "This
+   * credential may not access secrets of that user", so the endpoint never reveals which user
+   * ids exist.
+   *
+   * Whatever the token, your app must hold the platform permission `app_secrets.write`: list
+   * it in the manifest's `permissions` and upload. Until then every Secret Store call is
+   * refused with `403` "This app has not been granted app_secrets.write." For the service
+   * account this is checked before `activation_id` is looked at, so an app without the
+   * permission gets that answer whether or not it sent an `activation_id`.
+   *
+   * Every response carries `Cache-Control: no-store`, errors included, so no cache keeps a
+   * secret.
+   */
+  async deleteAppSecret(
+    request: components.AppSecretDeleteRequest,
+    options?: RequestOptions,
+  ): Promise<components.AppSecretDeleted> {
+    return unwrapAsync(appsDeleteAppSecret(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Publish an app manifest
+   *
+   * @remarks
+   * Publishes a new version of your marketplace app's manifest: its listing, the permissions
+   * it requests, its UI bundle and views, and the extra origins its sandbox may reach.
+   * `apps-cli upload` calls it after checking that the hosted bundle matches your local
+   * build.
+   *
+   * Every submission is reviewed against the app's last accepted version, and the response's
+   * `status` says what became of it: `accepted`, `screening` (the network sources it adds are
+   * being checked), `pending_review` (it adds a sensitive permission and waits for a Green
+   * Security admin) or `rejected`, with `review_reasons`. A rejection still answers `200`, with
+   * `success` false. Only an accepted version replaces the permissions granted to the app, and
+   * new installations get it. An installation it adds nothing for uses it from the next time
+   * its views are opened; one it adds permissions or network sources for keeps its version
+   * until one of its admins approves the new ones. So publish only once the bundle at
+   * `ui_extensions.bundle.url` is live and matches `integrity`, and keep earlier bundles
+   * hosted. An upload that repeats the last accepted manifest exactly changes nothing.
+   *
+   * Leave out `ui_extensions` to publish a back-end-only app, one with no views that works
+   * only through its service account (see the second example). With a `version`, the
+   * manifest may only send installers to a view it has: `post_install_action.type`
+   * `app_settings_view` needs a `settings` view, and `app_main_view` needs a view for a
+   * viewport other than `settings`, or the manifest is refused with `422`. So an app whose
+   * only view is `settings` uses `app_settings_view`, and a back-end-only app uses `url` or
+   * leaves `post_install_action` out. Left out, the action follows the app's views:
+   * `app_main_view`, `app_settings_view` for a settings-only app, or no post-install step for
+   * a back-end-only app.
+   *
+   * Each permission must be an existing Green Security permission or a platform permission
+   * such as `app_secrets.write` (see `AppManifestPermission`). A manifest that names any
+   * other permission is refused with `400` "Permission '<name>' not found." and writes
+   * nothing: the app, its role and its role's permissions are left as they were.
+   *
+   * **Permissions.** Accepts the app service account's permanent token, or a developer CLI
+   * token (`gsd_`) of a user who is an `owner` or `developer` of the app, as
+   * `Authorization: Bearer`. App user and installation tokens are refused.
+   */
+  async publishAppManifest(
+    request: components.AppManifest,
+    options?: RequestOptions,
+  ): Promise<operations.PublishAppManifestPublishAppManifestOk> {
+    return unwrapAsync(appsPublishAppManifest(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * List app developers
+   *
+   * @remarks
+   * Lists the users who may publish, preview and manage this app with the developer CLI,
+   * oldest first. An app has at most 100 developers.
+   *
+   * **Permissions.** Accepts the app service account's permanent token, or a developer CLI
+   * token (`gsd_`) of an `owner` of the app, as `Authorization: Bearer`. Anyone else, including
+   * a `developer` who is not an owner, is told the app does not exist (`404`).
+   */
+  async listAppDevelopers(
+    request: operations.ListAppDevelopersRequest,
+    options?: RequestOptions,
+  ): Promise<
+    PageIterator<operations.ListAppDevelopersResponse, { page: number }>
+  > {
+    return unwrapResultIterator(appsListAppDevelopers(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Add an app developer
+   *
+   * @remarks
+   * Makes a user an `owner` or `developer` of the app. Adding a user who is already on the
+   * list changes their role; demoting the app's last owner is refused with `409`, and so is
+   * adding a `developer` to an app that has no owner yet. Otherwise the response is `200`
+   * with the developer.
+   *
+   * The user must already be covered by an installation of the app. An app has at most 100
+   * developers: adding one more is refused with `422`, as is a request that does not send
+   * exactly one of `user_id` and `email`.
+   *
+   * **Permissions.** Accepts the app service account's permanent token, or a developer CLI
+   * token (`gsd_`) of an `owner` of the app, as `Authorization: Bearer`. Anyone else is told
+   * the app does not exist (`404`).
+   */
+  async addAppDeveloper(
+    request: operations.AddAppDeveloperRequest,
+    options?: RequestOptions,
+  ): Promise<components.AppDeveloper> {
+    return unwrapAsync(appsAddAppDeveloper(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Remove an app developer
+   *
+   * @remarks
+   * Removes a user from the app's developers and closes their dev sessions for it. The app's
+   * last `owner` cannot be removed (`409`).
+   *
+   * **Permissions.** Accepts the app service account's permanent token, or a developer CLI
+   * token (`gsd_`) of an `owner` of the app, as `Authorization: Bearer`. Anyone else is told
+   * the app does not exist (`404`).
+   */
+  async removeAppDeveloper(
+    request: operations.RemoveAppDeveloperRequest,
+    options?: RequestOptions,
+  ): Promise<components.DeleteApiResponse> {
+    return unwrapAsync(appsRemoveAppDeveloper(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * List app versions with installation counts
+   *
+   * @remarks
+   * Lists every uploaded version of the app, with the review status of each and the number of
+   * installations that run it. `apps-cli status` shows the same information.
+   *
+   * The response is an object keyed by version string, in the order the versions were first
+   * uploaded. Every version is listed, including versions that are in review or
+   * rejected, which no installation runs. An app that hasn't been uploaded since review began has
+   * no versions yet, and the response is `{}`.
+   *
+   * A version that's uploaded more than once has one key. Its `status` is the status of the
+   * latest upload, and its counts cover every installation that runs an accepted upload of that
+   * version. A manifest without a `version` is listed under the key `""`.
+   *
+   * Each installation counts under the version it runs, which is the version its administrators
+   * last approved (see [Existing installations keep their version](/apps/security-and-review#existing-installations-keep-their-version)).
+   * **Site-wide installations aren't counted.** An installation for a whole site covers every
+   * user, company, facility, and health system in it, so the counts leave it out.
+   *
+   * **Permissions.** Accepts the app service account's permanent token, or the developer CLI
+   * token (`gsd_`, from `apps-cli login`) of an `owner` or `developer` of the app, as
+   * `Authorization: Bearer`. Any other app token gets `403`. Anyone else gets `404`, the same
+   * response as for an app id that doesn't exist. That includes a developer signed in with a
+   * browser session.
+   */
+  async listAppVersions(
+    request: operations.ListAppVersionsRequest,
+    options?: RequestOptions,
+  ): Promise<{ [k: string]: components.AppVersionInstalls }> {
+    return unwrapAsync(appsListAppVersions(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Start a dev session
+   *
+   * @remarks
+   * Registers a dev session, which is what `gs-apps dev` does on start. While the session is
+   * active, the Green Security app loads your views from the CLI's dev server at `origin`
+   * instead of the published bundle, for you only: other users of the same tenant keep
+   * seeing the published version. Every build the dev server announces must be signed with
+   * the private half of `public_key_jwk`.
+   *
+   * Starting a session closes any earlier session of yours for the same app. A session lasts
+   * 12 hours and counts as inactive after 2 minutes without a heartbeat, so call
+   * `POST /apps/{app_id}/dev-sessions/{id}/heartbeat` every 30 seconds.
+   *
+   * A `422` means a field failed validation: `origin`, `server_token`, `public_key_jwk` or
+   * `manifest` is malformed, `manifest` changes a field a dev session may not (see
+   * `AppDevManifest`), or several installations cover you and `activation_id` was left out.
+   *
+   * The response never includes `server_token`: you generated it, so keep your own copy.
+   *
+   * Dev sessions are available on staging, and in production only for apps an administrator
+   * has enabled dev preview for; otherwise this endpoint answers `403`.
+   *
+   * **Permissions.** Requires a developer CLI token (`gsd_`, from `gs-apps login`) of an
+   * `owner` or `developer` of the app, as `Authorization: Bearer`. Any other token, including
+   * your own session token and the app's service account token, is refused with `403`. An app
+   * you are not a developer of is reported as not found.
+   */
+  async createAppDevSession(
+    request: operations.CreateAppDevSessionRequest,
+    options?: RequestOptions,
+  ): Promise<components.DevSession> {
+    return unwrapAsync(appsCreateAppDevSession(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Close a dev session
+   *
+   * @remarks
+   * Closes a dev session, which is what `apps-cli dev` does on exit. The Green Security app
+   * goes back to the published bundle once the session has ended. Closing a session that
+   * is already closed or expired succeeds too.
+   *
+   * **Permissions.** Requires the developer CLI token (`gsd_`) of the developer who started
+   * the session, as `Authorization: Bearer`. Another developer's session is reported as not
+   * found.
+   */
+  async closeAppDevSession(
+    request: operations.CloseAppDevSessionRequest,
+    options?: RequestOptions,
+  ): Promise<components.DeleteApiResponse> {
+    return unwrapAsync(appsCloseAppDevSession(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Keep a dev session alive
+   *
+   * @remarks
+   * Marks a dev session as still running. Call it every 30 seconds; a session with no
+   * heartbeat for 2 minutes is treated as inactive and the host stops using it until the next
+   * heartbeat. A heartbeat does not extend the 12-hour lifetime.
+   *
+   * Access is checked again on every heartbeat. A `404` means the session was closed,
+   * expired or replaced by a newer one, or you are no longer a developer of the app; a `403`
+   * means dev preview has been switched off for the app. Either way the session is closed:
+   * start a new one with `POST /apps/{app_id}/dev-sessions` once the cause is resolved.
+   *
+   * **Permissions.** Requires the developer CLI token (`gsd_`) of the developer who started
+   * the session, as `Authorization: Bearer`. Another developer's session is reported as not
+   * found.
+   */
+  async heartbeatAppDevSession(
+    request: operations.HeartbeatAppDevSessionRequest,
+    options?: RequestOptions,
+  ): Promise<operations.HeartbeatAppDevSessionHeartbeatAppDevSessionOk> {
+    return unwrapAsync(appsHeartbeatAppDevSession(
+      this,
+      request,
+      options,
+    ));
+  }
+}

package/src/sdk/companies.ts

@@ -77,6 +77,9 @@ export class Companies extends ClientSDK {
    * @remarks
    * Lists companies available to the caller as minimal lookup summaries for list and typeahead UIs.
    *
+   * For a vendor, the list holds the active companies on the vendor's site: the companies the
+   * vendor can add as managing companies. Other callers see the companies they can view.
+   *
    * **Permissions.** Requires the `companies.view` permission.
    */
   async lookupCompanies(

package/src/sdk/events.ts

@@ -210,15 +210,16 @@ export class Events extends ClientSDK {
    * **Permissions.** Requires a valid token. This endpoint is not gated on a named permission:
    * the caller's role and their relationship to the record decide what the endpoint returns.
    *
-   * Returns `Invite` items with the `invite.event` and `invite.invitee` scopes already applied,
-   * so `event` is the expanded `{ id, name }` summary instead of a bare id, and `invitee` is
-   * populated—the appointment and the recipient this list has always named. This endpoint
-   * takes no `expand` parameter; the endpoint always applies both scopes.
-   * SDK builds earlier than `0.55.0-beta.1` receive the older `PendingInvitation` shape instead, which
+   * Returns `Invite` items with the `invite.event`, `invite.invitee`, `event.location` and
+   * `event.creator` scopes already applied. So `event` is the expanded summary instead of a bare
+   * id, with the appointment's dates, flags, notes, location and organizer, and `invitee` is
+   * populated with the recipient's name and thumbnail—what this list has always published. This
+   * endpoint takes no `expand` parameter; the endpoint always applies these scopes.
+   * SDK builds earlier than `0.46.0-beta.1` receive the older `PendingInvitation` shape instead, which
    * embeds the appointment.
    *
-   * The boundary is the prerelease build `0.55.0-beta.1`, not the `0.55.0` release, so
-   * `0.55.0-beta.1` itself already receives `Invite`. See the `Invite` schema for exactly how a
+   * The boundary is the prerelease build `0.46.0-beta.1`, not the `0.46.0` release, so
+   * `0.46.0-beta.1` itself already receives `Invite`. See the `Invite` schema for exactly how a
    * build compares against it.
    */
   async listPendingInvitations(
@@ -243,15 +244,16 @@ export class Events extends ClientSDK {
    * **Permissions.** Requires a valid token. This endpoint is not gated on a named permission.
    * The caller's role and their relationship to the record decide what the response includes.
    *
-   * Returns `Event` items with the `event.creator` and `event.invitees` scopes already applied,
-   * so the server populates `event_creator`, `event_creator_img_url` and `invitees`—the fields this
-   * feed has always carried. SDK builds below `0.55.0-beta.1` receive the older `Feed` shape
-   * instead, in which `facility` and `department` are name strings, not ids; the server
-   * chooses by the `X-SDK-User-Agent` header the SDK sends, so an existing client keeps the
-   * shape it was generated against until you regenerate it.
+   * Returns `Event` items with the `event.creator`, `event.invitees`, `event.facility` and
+   * `event.department` scopes already applied, so the server populates `event_creator`,
+   * `event_creator_img_url` and `invitees`, and `facility` and `department` are `{ id, name }`
+   * summaries—the fields this feed has always carried. SDK builds below `0.46.0-beta.1`
+   * receive the older `Feed` shape instead, in which `facility` and `department` are name
+   * strings, not ids; the server chooses by the `X-SDK-User-Agent` header the SDK sends, so an
+   * existing client keeps the shape it was generated against until you regenerate it.
    *
-   * The boundary is the prerelease build `0.55.0-beta.1`, not the `0.55.0` release, so
-   * `0.55.0-beta.1` itself already receives `Event`. See the `Event` schema for exactly how the server compares a
+   * The boundary is the prerelease build `0.46.0-beta.1`, not the `0.46.0` release, so
+   * `0.46.0-beta.1` itself already receives `Event`. See the `Event` schema for exactly how the server compares a
    * build against it.
    */
   async listFeed(
@@ -275,13 +277,14 @@ export class Events extends ClientSDK {
    * the caller's role and their relationship to the record decide what the endpoint returns.
    *
    * Returns `Event` items with the `event.location`, `event.attendees`, `event.viewer_invite`,
-   * `event.creator` and `event.invitees` scopes already applied, so `location`, `attendees`,
-   * `event_creator`, `event_creator_img_url` and `invitees` are populated and `status` carries
-   * the reader's own outstanding invite. SDK builds earlier than `0.55.0-beta.1` receive the older
+   * `event.creator`, `event.invitees`, `event.facility` and `event.department` scopes already
+   * applied, so `location`, `attendees`, `event_creator`, `event_creator_img_url` and `invitees`
+   * are populated, `facility` and `department` are `{ id, name }` summaries, and `status` carries
+   * the reader's own outstanding invite. SDK builds earlier than `0.46.0-beta.1` receive the older
    * `StandingAppointment` shape instead.
    *
-   * The boundary is the prerelease build `0.55.0-beta.1`, not the `0.55.0` release, so
-   * `0.55.0-beta.1` itself already receives `Event`. See the `Event` schema for exactly how a
+   * The boundary is the prerelease build `0.46.0-beta.1`, not the `0.46.0` release, so
+   * `0.46.0-beta.1` itself already receives `Event`. See the `Event` schema for exactly how a
    * build compares against it.
    */
   async listStandingAppointments(