@unkey/api/src/models/components/v2keysverifykeyresponsedata.ts

Developer-friendly & type-safe Typescript SDK specifically catered to leverage *@unkey/api* API.

/*
 * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
 */

import * as z from "zod/v3";
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 { SDKValidationError } from "../errors/sdkvalidationerror.js";
import { Identity, Identity$inboundSchema } from "./identity.js";
import {
  VerifyKeyRatelimitData,
  VerifyKeyRatelimitData$inboundSchema,
} from "./verifykeyratelimitdata.js";

/**
 * A machine-readable code indicating the verification status
 *
 * @remarks
 * or failure reason. Values: `VALID` (key is valid and passed all checks), `NOT_FOUND` (key doesn't
 * exist or belongs to wrong API), `FORBIDDEN` (key lacks required permissions), `INSUFFICIENT_PERMISSIONS`
 * (key lacks specific required permissions for this request), `USAGE_EXCEEDED` (key has no remaining credits), `RATE_LIMITED` (key exceeded rate limits), `DISABLED` (key was explicitly disabled),
 * `EXPIRED` (key has passed its expiration date).
 */
export const Code = {
  Valid: "VALID",
  NotFound: "NOT_FOUND",
  Forbidden: "FORBIDDEN",
  InsufficientPermissions: "INSUFFICIENT_PERMISSIONS",
  UsageExceeded: "USAGE_EXCEEDED",
  RateLimited: "RATE_LIMITED",
  Disabled: "DISABLED",
  Expired: "EXPIRED",
} as const;
/**
 * A machine-readable code indicating the verification status
 *
 * @remarks
 * or failure reason. Values: `VALID` (key is valid and passed all checks), `NOT_FOUND` (key doesn't
 * exist or belongs to wrong API), `FORBIDDEN` (key lacks required permissions), `INSUFFICIENT_PERMISSIONS`
 * (key lacks specific required permissions for this request), `USAGE_EXCEEDED` (key has no remaining credits), `RATE_LIMITED` (key exceeded rate limits), `DISABLED` (key was explicitly disabled),
 * `EXPIRED` (key has passed its expiration date).
 */
export type Code = OpenEnum<typeof Code>;

export type V2KeysVerifyKeyResponseData = {
  /**
   * The primary verification result. If true, the key is valid
   *
   * @remarks
   * and can be used. If false, check the 'code' field to understand why verification
   * failed. Your application should always check this field first before proceeding.
   */
  valid: boolean;
  /**
   * A machine-readable code indicating the verification status
   *
   * @remarks
   * or failure reason. Values: `VALID` (key is valid and passed all checks), `NOT_FOUND` (key doesn't
   * exist or belongs to wrong API), `FORBIDDEN` (key lacks required permissions), `INSUFFICIENT_PERMISSIONS`
   * (key lacks specific required permissions for this request), `USAGE_EXCEEDED` (key has no remaining credits), `RATE_LIMITED` (key exceeded rate limits), `DISABLED` (key was explicitly disabled),
   * `EXPIRED` (key has passed its expiration date).
   */
  code: Code;
  /**
   * The unique identifier of the verified key in Unkey's system.
   *
   * @remarks
   * Use this ID for operations like updating or revoking the key. This field
   * is returned for both valid and invalid keys (except when `code=NOT_FOUND`).
   */
  keyId?: string | undefined;
  /**
   * The human-readable name assigned to this key during creation.
   *
   * @remarks
   * This is useful for displaying in logs or admin interfaces to identify
   * the key's purpose.
   */
  name?: string | undefined;
  /**
   * Custom metadata associated with the key. This can include any
   *
   * @remarks
   * JSON-serializable data you stored with the key during creation or updates,
   * such as plan information, feature flags, or user details. Use this to
   * avoid additional database lookups for contextual information needed during
   * API calls.
   */
  meta?: { [k: string]: any } | undefined;
  /**
   * Unix timestamp (in milliseconds) when the key will expire.
   *
   * @remarks
   * If omitted, the key has no expiration. You can use this to
   * warn users about upcoming expirations or to understand the validity period.
   */
  expires?: number | undefined;
  /**
   * The number of requests/credits remaining for this key. If omitted,
   *
   * @remarks
   * the key has unlimited usage. This value decreases with
   * each verification (based on the 'cost' parameter) unless explicit credit
   * refills are configured.
   */
  credits?: number | undefined;
  /**
   * Indicates if the key is currently enabled. Disabled keys will
   *
   * @remarks
   * always fail verification with `code=DISABLED`. This is useful for implementing
   * temporary suspensions without deleting the key.
   */
  enabled?: boolean | undefined;
  /**
   * A list of all permission names assigned to this key, either
   *
   * @remarks
   * directly or through roles. These permissions determine what actions the
   * key can perform. Only returned when permissions were checked during verification
   * or when the key fails with `code=FORBIDDEN`.
   */
  permissions?: Array<string> | undefined;
  /**
   * A list of all role names assigned to this key. Roles are collections
   *
   * @remarks
   * of permissions that grant access to specific functionality. Only returned
   * when permissions were checked during verification.
   */
  roles?: Array<string> | undefined;
  identity?: Identity | undefined;
  ratelimits?: Array<VerifyKeyRatelimitData> | undefined;
};

/** @internal */
export const Code$inboundSchema: z.ZodType<Code, z.ZodTypeDef, unknown> =
  openEnums.inboundSchema(Code);

/** @internal */
export const V2KeysVerifyKeyResponseData$inboundSchema: z.ZodType<
  V2KeysVerifyKeyResponseData,
  z.ZodTypeDef,
  unknown
> = z.object({
  valid: z.boolean(),
  code: Code$inboundSchema,
  keyId: z.string().optional(),
  name: z.string().optional(),
  meta: z.record(z.any()).optional(),
  expires: z.number().int().optional(),
  credits: z.number().int().optional(),
  enabled: z.boolean().optional(),
  permissions: z.array(z.string()).optional(),
  roles: z.array(z.string()).optional(),
  identity: Identity$inboundSchema.optional(),
  ratelimits: z.array(VerifyKeyRatelimitData$inboundSchema).optional(),
});

export function v2KeysVerifyKeyResponseDataFromJSON(
  jsonString: string,
): SafeParseResult<V2KeysVerifyKeyResponseData, SDKValidationError> {
  return safeParse(
    jsonString,
    (x) => V2KeysVerifyKeyResponseData$inboundSchema.parse(JSON.parse(x)),
    `Failed to parse 'V2KeysVerifyKeyResponseData' from JSON`,
  );
}