@greensecurity/javascript-sdk 0.46.0-beta.7 → 0.46.0-beta.9

package/src/models/components/tokenresponse.ts

@@ -0,0 +1,178 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { remap as remap$ } from "../../lib/primitives.js";
+import { safeParse } from "../../lib/schemas.js";
+import * as openEnums from "../../types/enums.js";
+import { OpenEnum } from "../../types/enums.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import * as types from "../../types/primitives.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+/**
+ * What kind of token was issued. Returned for app user, app installation and developer
+ *
+ * @remarks
+ * CLI tokens, including every CLI refresh; absent from the plain API token that
+ * `client_credentials` without `activation_id` and a service account's
+ * `refresh_token` return.
+ */
+export const IssuedTokenType = {
+  UrnGreensecurityTokenTypeAppUser: "urn:greensecurity:token-type:app_user",
+  UrnGreensecurityTokenTypeAppInstallation:
+    "urn:greensecurity:token-type:app_installation",
+  UrnGreensecurityTokenTypeDeveloperCli:
+    "urn:greensecurity:token-type:developer_cli",
+} as const;
+/**
+ * What kind of token was issued. Returned for app user, app installation and developer
+ *
+ * @remarks
+ * CLI tokens, including every CLI refresh; absent from the plain API token that
+ * `client_credentials` without `activation_id` and a service account's
+ * `refresh_token` return.
+ */
+export type IssuedTokenType = OpenEnum<typeof IssuedTokenType>;
+
+/**
+ * A successful `POST /oauth/token` response (RFC 6749 section 5.1, RFC 8693 section 2.2.1).
+ *
+ * @remarks
+ * Send `access_token` as `Authorization: Bearer <access_token>`; app and developer tokens
+ * are refused as a `?token=` query parameter.
+ *
+ * Which fields are present depends on the grant:
+ *
+ * | Grant | Fields |
+ * | --- | --- |
+ * | Token exchange, and `client_credentials` with `activation_id` | `access_token`, `issued_token_type`, `token_type`, `expires_in`, `scope`, `activation_id` |
+ * | Device code, and the apps CLI's `refresh_token` | `access_token`, `issued_token_type`, `token_type`, `expires_in`, `scope`, `refresh_token`, `refresh_token_expires_in` |
+ * | `client_credentials` without `activation_id` | `access_token`, `token_type`, `expires_in`, and `scope` only when the request sent one |
+ * | A service account's `refresh_token` | As `client_credentials` without `activation_id`, plus `refresh_token` |
+ */
+export type TokenResponse = {
+  /**
+   * The token. An app or developer token's prefix names its kind: `gsu_` for an app user
+   *
+   * @remarks
+   * token, `gsi_` for an app installation token, `gsd_` for a developer CLI token. These
+   * are shown only once and cannot be retrieved later. The access
+   * token of a `client_credentials` grant without `activation_id`, or of a service
+   * account's `refresh_token` grant, is an ordinary API token with no prefix.
+   */
+  accessToken: string;
+  /**
+   * What kind of token was issued. Returned for app user, app installation and developer
+   *
+   * @remarks
+   * CLI tokens, including every CLI refresh; absent from the plain API token that
+   * `client_credentials` without `activation_id` and a service account's
+   * `refresh_token` return.
+   */
+  issuedTokenType?: IssuedTokenType | undefined;
+  tokenType: "Bearer";
+  /**
+   * Seconds until the token expires: 900 (15 minutes) for every kind. A developer CLI
+   *
+   * @remarks
+   * token is capped at the end of its login (90 days after the device authorization), so
+   * near that end it can be less. Request a new token before then. Only the device grant
+   * and the `refresh_token` grant return a `refresh_token`.
+   */
+  expiresIn: number;
+  /**
+   * Space-delimited scopes the token carries. For an app user token these are the
+   *
+   * @remarks
+   * manifest permissions (`resource.action`) that the user's own role also grants; for an
+   * installation token, the app's manifest permissions; for a developer CLI token,
+   * `apps:develop`. A `scope` in the request narrows this further.
+   *
+   * A plain API access token (`client_credentials` without `activation_id`, or
+   * `refresh_token`) carries `scope` only when it was narrowed: when the request sent a
+   * `scope`, or when the refresh token it replaces was itself narrowed. Without it the
+   * token has every permission of the service account.
+   *
+   * A narrowed token (any app or developer token, or a plain API access token that
+   * carries `scope`) can only use its scope. An endpoint that names a permission
+   * outside it answers `403` ("App token doesn't have permission" for an app token,
+   * "Token scope doesn't permit this." for a plain one); an endpoint that checks no
+   * named permission answers `403` "This endpoint does not accept scoped tokens."
+   * unless it applies the scope itself. `GET /users/{id}` does, but returns no
+   * `user_token` to a narrowed token and refuses `expand=user.payment_profile` with
+   * `403`. A narrowed token is also refused as the `client_credentials` Bearer, as a
+   * `subject_token`, and as the credential for `POST /oauth/introspect` and
+   * `POST /oauth/revoke`.
+   */
+  scope?: string | undefined;
+  /**
+   * The activation an app user or app installation token is bound to. Not returned for any other token.
+   */
+  activationId?: number | undefined;
+  /**
+   * A single-use refresh token. Keep it as secret as a password; it is never a Bearer
+   *
+   * @remarks
+   * credential.
+   *
+   * - **Apps CLI** (`gsdr_…`): returned by the device grant and by every CLI refresh.
+   *   Each refresh spends it and returns a new one (see `OAuthCliRefreshTokenGrant`).
+   * - **Service account** (no prefix): returned by a service account's `refresh_token`
+   *   grant, replacing the token just spent. It expires after 30 days.
+   */
+  refreshToken?: string | undefined;
+  /**
+   * Apps CLI only: seconds until `refresh_token` expires if it is not used, normally
+   *
+   * @remarks
+   * 2592000 (30 days). A CLI login ends 90 days after the device authorization however
+   * often it is refreshed, so in its last 30 days this is capped at that end (for
+   * example 259200 on day 87).
+   */
+  refreshTokenExpiresIn?: number | undefined;
+};
+
+/** @internal */
+export const IssuedTokenType$inboundSchema: z.ZodType<
+  IssuedTokenType,
+  z.ZodTypeDef,
+  unknown
+> = openEnums.inboundSchema(IssuedTokenType);
+
+/** @internal */
+export const TokenResponse$inboundSchema: z.ZodType<
+  TokenResponse,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  access_token: types.string(),
+  issued_token_type: types.optional(IssuedTokenType$inboundSchema),
+  token_type: types.literal("Bearer"),
+  expires_in: types.number(),
+  scope: types.optional(types.string()),
+  activation_id: types.optional(types.number()),
+  refresh_token: types.optional(types.string()),
+  refresh_token_expires_in: types.optional(types.number()),
+}).transform((v) => {
+  return remap$(v, {
+    "access_token": "accessToken",
+    "issued_token_type": "issuedTokenType",
+    "token_type": "tokenType",
+    "expires_in": "expiresIn",
+    "activation_id": "activationId",
+    "refresh_token": "refreshToken",
+    "refresh_token_expires_in": "refreshTokenExpiresIn",
+  });
+});
+
+export function tokenResponseFromJSON(
+  jsonString: string,
+): SafeParseResult<TokenResponse, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => TokenResponse$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'TokenResponse' from JSON`,
+  );
+}

package/src/models/components/tokenrevocationrequest.ts

@@ -0,0 +1,60 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { remap as remap$ } from "../../lib/primitives.js";
+import {
+  OAuthTokenTypeHint,
+  OAuthTokenTypeHint$outboundSchema,
+} from "./oauthtokentypehint.js";
+
+export type TokenRevocationRequest = {
+  /**
+   * The token to revoke. Revoking any token of an apps CLI login (`gsd_` or `gsdr_`) revokes the whole login.
+   */
+  token: string;
+  /**
+   * Optional hint about the kind of token. Tokens are recognised by prefix, so this is informational.
+   */
+  tokenTypeHint?: OAuthTokenTypeHint | undefined;
+  /**
+   * The apps CLI's public client id (RFC 7009 section 2.1). With a `gsdr_` refresh token
+   *
+   * @remarks
+   * as `token`, no `Authorization` is needed: holding the refresh token entitles the
+   * caller to revoke its login. Ignored with any other token.
+   */
+  clientId?: "greensecurity-apps-cli" | undefined;
+};
+
+/** @internal */
+export type TokenRevocationRequest$Outbound = {
+  token: string;
+  token_type_hint?: string | undefined;
+  client_id?: "greensecurity-apps-cli" | undefined;
+};
+
+/** @internal */
+export const TokenRevocationRequest$outboundSchema: z.ZodType<
+  TokenRevocationRequest$Outbound,
+  z.ZodTypeDef,
+  TokenRevocationRequest
+> = z.object({
+  token: z.string(),
+  tokenTypeHint: OAuthTokenTypeHint$outboundSchema.optional(),
+  clientId: z.literal("greensecurity-apps-cli").optional(),
+}).transform((v) => {
+  return remap$(v, {
+    tokenTypeHint: "token_type_hint",
+    clientId: "client_id",
+  });
+});
+
+export function tokenRevocationRequestToJSON(
+  tokenRevocationRequest: TokenRevocationRequest,
+): string {
+  return JSON.stringify(
+    TokenRevocationRequest$outboundSchema.parse(tokenRevocationRequest),
+  );
+}

package/src/models/components/user.ts

@@ -50,6 +50,10 @@ export type InventoryManager = {};
  * The User object describes a person or service account.
  */
 export type User = {
+  /**
+   * Whether the user may manage zone devices (the `zone_devices.view` permission, which the Zone Device Managers role grants). Returned only when the caller requests their own record.
+   */
+  canManageZoneDevices?: boolean | undefined;
   /**
    * Whether the user is a `gatekeeper`, a special type of service user assigned to Kiosks and Apps to verify vendors using APIs that have some access to facility data.
    */
@@ -135,6 +139,7 @@ export function inventoryManagerFromJSON(
 /** @internal */
 export const User$inboundSchema: z.ZodType<User, z.ZodTypeDef, unknown> = z
   .object({
+    can_manage_zone_devices: types.optional(types.boolean()),
     is_gatekeeper: types.optional(types.boolean()),
     success: types.boolean(),
     user: UserDetails$inboundSchema,
@@ -147,6 +152,7 @@ export const User$inboundSchema: z.ZodType<User, z.ZodTypeDef, unknown> = z
     company: z.nullable(Company$inboundSchema).optional(),
   }).transform((v) => {
     return remap$(v, {
+      "can_manage_zone_devices": "canManageZoneDevices",
       "is_gatekeeper": "isGatekeeper",
       "user_token": "userToken",
       "inventory_manager": "inventoryManager",

package/src/models/components/zone.ts

@@ -15,6 +15,12 @@ import {
   Department$Outbound,
   Department$outboundSchema,
 } from "./department.js";
+import {
+  DeviceCounts,
+  DeviceCounts$inboundSchema,
+  DeviceCounts$Outbound,
+  DeviceCounts$outboundSchema,
+} from "./devicecounts.js";
 import {
   Facility,
   Facility$inboundSchema,
@@ -287,6 +293,10 @@ export type Zone = {
    * The department the zone belongs to. Contains the full department when you expand `zone.department`, otherwise the department ID.
    */
   department?: Department | number | null | undefined;
+  /**
+   * Gateway and iPad kiosk totals in the zone. Present only when `zone.device_counts` is in `expand` and the caller holds `zone_devices.view`, otherwise `null`.
+   */
+  deviceCounts?: DeviceCounts | null | undefined;
   /**
    * The name of the zone, or `null` if not set.
    */
@@ -936,6 +946,7 @@ export const Zone$inboundSchema: z.ZodType<Zone, z.ZodTypeDef, unknown> = z
     department: z.nullable(
       smartUnion([Department$inboundSchema, types.number()]),
     ).optional(),
+    device_counts: z.nullable(DeviceCounts$inboundSchema).optional(),
     name: z.nullable(types.string()).optional(),
     short_name: z.nullable(types.string()).optional(),
     description: z.nullable(types.string()).optional(),
@@ -960,6 +971,7 @@ export const Zone$inboundSchema: z.ZodType<Zone, z.ZodTypeDef, unknown> = z
     ),
   }).transform((v) => {
     return remap$(v, {
+      "device_counts": "deviceCounts",
       "short_name": "shortName",
       "kiosk_offline_notification": "kioskOfflineNotification",
       "vendor_policy": "vendorPolicy",
@@ -974,6 +986,7 @@ export type Zone$Outbound = {
   id?: number | undefined;
   facility?: Facility$Outbound | Facility2$Outbound | null | undefined;
   department?: Department$Outbound | number | null | undefined;
+  device_counts?: DeviceCounts$Outbound | null | undefined;
   name?: string | null | undefined;
   short_name?: string | null | undefined;
   description?: string | null | undefined;
@@ -1002,6 +1015,7 @@ export const Zone$outboundSchema: z.ZodType<Zone$Outbound, z.ZodTypeDef, Zone> =
     department: z.nullable(
       smartUnion([Department$outboundSchema, z.number().int()]),
     ).optional(),
+    deviceCounts: z.nullable(DeviceCounts$outboundSchema).optional(),
     name: z.nullable(z.string()).optional(),
     shortName: z.nullable(z.string()).optional(),
     description: z.nullable(z.string()).optional(),
@@ -1022,6 +1036,7 @@ export const Zone$outboundSchema: z.ZodType<Zone$Outbound, z.ZodTypeDef, Zone> =
     gpsCheckinPolicy: z.lazy(() => GpsCheckinPolicy$outboundSchema).optional(),
   }).transform((v) => {
     return remap$(v, {
+      deviceCounts: "device_counts",
       shortName: "short_name",
       kioskOfflineNotification: "kiosk_offline_notification",
       vendorPolicy: "vendor_policy",

package/src/models/errors/appsecretsunprocessable.ts

@@ -0,0 +1,50 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { smartUnion } from "../../types/smartUnion.js";
+import {
+  ApiErrorResponse,
+  ApiErrorResponse$inboundSchema,
+} from "./apierrorresponse.js";
+import {
+  ApiValidationErrorResponse,
+  ApiValidationErrorResponse$inboundSchema,
+} from "./apivalidationerrorresponse.js";
+import { SDKValidationError } from "./sdkvalidationerror.js";
+
+/**
+ * A parameter failed validation, `activation_id` is missing with the service account's
+ *
+ * @remarks
+ * token, a `user` scope has no `user_id` with the service account or an installation
+ * token from `client_credentials`, an `installation` scope names a `user_id`, or the scope
+ * already holds 25 secrets.
+ * Carries either the standard error envelope or the validation envelope.
+ */
+export type AppSecretsUnprocessable =
+  | ApiErrorResponse
+  | ApiValidationErrorResponse;
+
+/** @internal */
+export const AppSecretsUnprocessable$inboundSchema: z.ZodType<
+  AppSecretsUnprocessable,
+  z.ZodTypeDef,
+  unknown
+> = smartUnion([
+  ApiErrorResponse$inboundSchema,
+  ApiValidationErrorResponse$inboundSchema,
+]);
+
+export function appSecretsUnprocessableFromJSON(
+  jsonString: string,
+): SafeParseResult<AppSecretsUnprocessable, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => AppSecretsUnprocessable$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'AppSecretsUnprocessable' from JSON`,
+  );
+}

package/src/models/errors/createappdevsession.ts

@@ -0,0 +1,48 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { smartUnion } from "../../types/smartUnion.js";
+import {
+  ApiValidationErrorResponse,
+  ApiValidationErrorResponse$inboundSchema,
+} from "./apivalidationerrorresponse.js";
+import {
+  DevSessionErrorResponse,
+  DevSessionErrorResponse$inboundSchema,
+} from "./devsessionerrorresponse.js";
+import { SDKValidationError } from "./sdkvalidationerror.js";
+
+/**
+ * A field failed validation. A refused `manifest` also lists each problem in `errors`. A
+ *
+ * @remarks
+ * parameter that fails validation before the endpoint runs gets the validation envelope,
+ * whose `error` is an array.
+ */
+export type CreateAppDevSessionResponseBody =
+  | DevSessionErrorResponse
+  | ApiValidationErrorResponse;
+
+/** @internal */
+export const CreateAppDevSessionResponseBody$inboundSchema: z.ZodType<
+  CreateAppDevSessionResponseBody,
+  z.ZodTypeDef,
+  unknown
+> = smartUnion([
+  DevSessionErrorResponse$inboundSchema,
+  ApiValidationErrorResponse$inboundSchema,
+]);
+
+export function createAppDevSessionResponseBodyFromJSON(
+  jsonString: string,
+): SafeParseResult<CreateAppDevSessionResponseBody, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => CreateAppDevSessionResponseBody$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'CreateAppDevSessionResponseBody' from JSON`,
+  );
+}

package/src/models/errors/devsessionerrorresponse.ts

@@ -0,0 +1,107 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import * as types from "../../types/primitives.js";
+import { GreenSecurityError } from "./greensecurityerror.js";
+
+/**
+ * The standard error envelope. When `manifest` is refused, it also carries `errors`.
+ */
+export type DevSessionErrorResponseData = {
+  /**
+   * A short message that describes the error. For a refused `manifest`, it's
+   *
+   * @remarks
+   * `Invalid manifest: ` followed by the entries of `errors`, joined with `; `.
+   */
+  error: string;
+  /**
+   * Whether the request succeeded. Always false for an error response.
+   */
+  success?: boolean | undefined;
+  /**
+   * The HTTP status code of the error, or `null` if not available.
+   */
+  code?: number | null | undefined;
+  /**
+   * Only when `manifest` is refused: one message per problem, up to 20, in the order
+   *
+   * @remarks
+   * `error` lists them. A message can quote a key or value from your manifest, which may
+   * itself contain `; `, so read this list rather than splitting `error`.
+   */
+  errors?: Array<string> | undefined;
+};
+
+/**
+ * The standard error envelope. When `manifest` is refused, it also carries `errors`.
+ */
+export class DevSessionErrorResponse extends GreenSecurityError {
+  /**
+   * A short message that describes the error. For a refused `manifest`, it's
+   *
+   * @remarks
+   * `Invalid manifest: ` followed by the entries of `errors`, joined with `; `.
+   */
+  error: string;
+  /**
+   * Whether the request succeeded. Always false for an error response.
+   */
+  success?: boolean | undefined;
+  /**
+   * The HTTP status code of the error, or `null` if not available.
+   */
+  code?: number | null | undefined;
+  /**
+   * Only when `manifest` is refused: one message per problem, up to 20, in the order
+   *
+   * @remarks
+   * `error` lists them. A message can quote a key or value from your manifest, which may
+   * itself contain `; `, so read this list rather than splitting `error`.
+   */
+  errors?: Array<string> | undefined;
+
+  /** The original data that was passed to this error instance. */
+  data$: DevSessionErrorResponseData;
+
+  constructor(
+    err: DevSessionErrorResponseData,
+    httpMeta: { response: Response; request: Request; body: string },
+  ) {
+    const message = "message" in err && typeof err.message === "string"
+      ? err.message
+      : `API error occurred: ${JSON.stringify(err)}`;
+    super(message, httpMeta);
+    this.data$ = err;
+    this.error = err.error;
+    if (err.success != null) this.success = err.success;
+    if (err.code != null) this.code = err.code;
+    if (err.errors != null) this.errors = err.errors;
+
+    this.name = "DevSessionErrorResponse";
+  }
+}
+
+/** @internal */
+export const DevSessionErrorResponse$inboundSchema: z.ZodType<
+  DevSessionErrorResponse,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  error: types.string(),
+  success: types.optional(types.boolean()),
+  code: z.nullable(types.number()).optional(),
+  errors: types.optional(z.array(types.string())),
+  request$: z.instanceof(Request),
+  response$: z.instanceof(Response),
+  body$: z.string(),
+})
+  .transform((v) => {
+    return new DevSessionErrorResponse(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
+  });

package/src/models/errors/index.ts

@@ -5,8 +5,12 @@
 export * from "./apierror.js";
 export * from "./apierrorresponse.js";
 export * from "./apivalidationerrorresponse.js";
+export * from "./appsecretsunprocessable.js";
+export * from "./createappdevsession.js";
+export * from "./devsessionerrorresponse.js";
 export * from "./greensecurityerror.js";
 export * from "./httpclienterrors.js";
+export * from "./oautherror.js";
 export * from "./responsevalidationerror.js";
 export * from "./sdkvalidationerror.js";
 export * from "./unprocessableentityorvalidationerror.js";

package/src/models/errors/oautherror.ts

@@ -0,0 +1,127 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod/v3";
+import { remap as remap$ } from "../../lib/primitives.js";
+import * as types from "../../types/primitives.js";
+import * as components from "../components/index.js";
+import { GreenSecurityError } from "./greensecurityerror.js";
+
+/**
+ * The error body of the `/oauth/*` endpoints (RFC 6749 section 5.2, RFC 8628 section 3.5).
+ *
+ * @remarks
+ * These endpoints use this shape rather than `ApiErrorResponse`, including for a body that
+ * fails validation or cannot be parsed: that is a `400` `invalid_request`, never a `422`.
+ */
+export type OAuthErrorData = {
+  /**
+   * The RFC error code:
+   *
+   * @remarks
+   *
+   * | Code | Meaning |
+   * | --- | --- |
+   * | `invalid_request` | A parameter is missing or malformed (including `client_id` without `client_secret` or the reverse), an OAuth parameter was sent in the query string rather than the body, the body could not be parsed, or more than one activation covers the user and `activation_id` was left out. |
+   * | `invalid_client` | The client could not be authenticated. Returned with `401`. On the apps CLI's `refresh_token` (a `gsdr_` token): a `client_id` other than `greensecurity-apps-cli`. On `client_credentials`: wrong `client_id` or `client_secret`; an `Authorization` token that is missing, invalid, or not the service account's permanent token (a short-lived, narrowed or app token is refused); or a locked service account. On `refresh_token`: `client_id` or `client_secret` does not match the refresh token's service account, or that account is locked. On the device grant and `POST /oauth/device_authorization`: an unknown `client_id`. On `POST /oauth/introspect` and `POST /oauth/revoke`: see each endpoint. |
+   * | `invalid_grant` | `subject_token` is invalid or expired, is an app token or a narrowed (scoped) token, or belongs to a locked user or a service account; `refresh_token` is unknown, expired, already used or not a service account's; an apps CLI refresh token is unknown, expired, revoked or reused, its login is past 90 days, or its developer is locked or deleted (all answered "Re-authenticate with `gs-apps login`."); or `device_code` is unknown or already used, or the user who approved it can no longer sign in. |
+   * | `unauthorized_client` | The caller may not use this grant: `client_credentials` from a user who is not an API service account. |
+   * | `unsupported_grant_type` | `grant_type` is not one of the four supported grants. |
+   * | `invalid_target` | `audience` names no app, or an app the user is not covered by; or `activation_id` is not an activation of the caller's app, or does not match `audience`. |
+   * | `invalid_scope` | None of the requested scopes is available to the client: what it asked for and what it is allowed have nothing in common. On `POST /oauth/device_authorization`, any scope other than `apps:develop`. |
+   * | `authorization_pending` | Device flow: the user has not approved the request yet. Keep polling. |
+   * | `slow_down` | Device flow: polling too fast. Add 5 seconds to the interval and keep polling. `POST /oauth/device_authorization` also returns it, with `429`, when one address starts too many logins, and so does the apps CLI's `refresh_token` past 60 refreshes per address in ten minutes. Wait and retry; it is not a failed login. |
+   * | `access_denied` | Device flow: the user declined the request. Stop polling. |
+   * | `expired_token` | Device flow: `device_code` expired. Start again from `POST /oauth/device_authorization`. |
+   */
+  error: components.OAuthErrorCode;
+  /**
+   * A human-readable explanation, for logs rather than for end users. When a request
+   *
+   * @remarks
+   * parameter fails validation it names the parameter, as `<parameter>: <message>`.
+   */
+  errorDescription?: string | undefined;
+};
+
+/**
+ * The error body of the `/oauth/*` endpoints (RFC 6749 section 5.2, RFC 8628 section 3.5).
+ *
+ * @remarks
+ * These endpoints use this shape rather than `ApiErrorResponse`, including for a body that
+ * fails validation or cannot be parsed: that is a `400` `invalid_request`, never a `422`.
+ */
+export class OAuthError extends GreenSecurityError {
+  /**
+   * The RFC error code:
+   *
+   * @remarks
+   *
+   * | Code | Meaning |
+   * | --- | --- |
+   * | `invalid_request` | A parameter is missing or malformed (including `client_id` without `client_secret` or the reverse), an OAuth parameter was sent in the query string rather than the body, the body could not be parsed, or more than one activation covers the user and `activation_id` was left out. |
+   * | `invalid_client` | The client could not be authenticated. Returned with `401`. On the apps CLI's `refresh_token` (a `gsdr_` token): a `client_id` other than `greensecurity-apps-cli`. On `client_credentials`: wrong `client_id` or `client_secret`; an `Authorization` token that is missing, invalid, or not the service account's permanent token (a short-lived, narrowed or app token is refused); or a locked service account. On `refresh_token`: `client_id` or `client_secret` does not match the refresh token's service account, or that account is locked. On the device grant and `POST /oauth/device_authorization`: an unknown `client_id`. On `POST /oauth/introspect` and `POST /oauth/revoke`: see each endpoint. |
+   * | `invalid_grant` | `subject_token` is invalid or expired, is an app token or a narrowed (scoped) token, or belongs to a locked user or a service account; `refresh_token` is unknown, expired, already used or not a service account's; an apps CLI refresh token is unknown, expired, revoked or reused, its login is past 90 days, or its developer is locked or deleted (all answered "Re-authenticate with `gs-apps login`."); or `device_code` is unknown or already used, or the user who approved it can no longer sign in. |
+   * | `unauthorized_client` | The caller may not use this grant: `client_credentials` from a user who is not an API service account. |
+   * | `unsupported_grant_type` | `grant_type` is not one of the four supported grants. |
+   * | `invalid_target` | `audience` names no app, or an app the user is not covered by; or `activation_id` is not an activation of the caller's app, or does not match `audience`. |
+   * | `invalid_scope` | None of the requested scopes is available to the client: what it asked for and what it is allowed have nothing in common. On `POST /oauth/device_authorization`, any scope other than `apps:develop`. |
+   * | `authorization_pending` | Device flow: the user has not approved the request yet. Keep polling. |
+   * | `slow_down` | Device flow: polling too fast. Add 5 seconds to the interval and keep polling. `POST /oauth/device_authorization` also returns it, with `429`, when one address starts too many logins, and so does the apps CLI's `refresh_token` past 60 refreshes per address in ten minutes. Wait and retry; it is not a failed login. |
+   * | `access_denied` | Device flow: the user declined the request. Stop polling. |
+   * | `expired_token` | Device flow: `device_code` expired. Start again from `POST /oauth/device_authorization`. |
+   */
+  error: components.OAuthErrorCode;
+  /**
+   * A human-readable explanation, for logs rather than for end users. When a request
+   *
+   * @remarks
+   * parameter fails validation it names the parameter, as `<parameter>: <message>`.
+   */
+  errorDescription?: string | undefined;
+
+  /** The original data that was passed to this error instance. */
+  data$: OAuthErrorData;
+
+  constructor(
+    err: OAuthErrorData,
+    httpMeta: { response: Response; request: Request; body: string },
+  ) {
+    const message = "message" in err && typeof err.message === "string"
+      ? err.message
+      : `API error occurred: ${JSON.stringify(err)}`;
+    super(message, httpMeta);
+    this.data$ = err;
+    this.error = err.error;
+    if (err.errorDescription != null) {
+      this.errorDescription = err.errorDescription;
+    }
+
+    this.name = "OAuthError";
+  }
+}
+
+/** @internal */
+export const OAuthError$inboundSchema: z.ZodType<
+  OAuthError,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  error: components.OAuthErrorCode$inboundSchema,
+  error_description: types.optional(types.string()),
+  request$: z.instanceof(Request),
+  response$: z.instanceof(Response),
+  body$: z.string(),
+})
+  .transform((v) => {
+    const remapped = remap$(v, {
+      "error_description": "errorDescription",
+    });
+
+    return new OAuthError(remapped, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
+  });