@unkey/api 2.0.0-alpha.7 → 2.0.0

package/src/models/errors/notfounderrorresponse.ts

@@ -4,26 +4,61 @@
 
 import * as z from "zod";
 import * as components from "../components/index.js";
+import { UnkeyError } from "./unkeyerror.js";
 
+/**
+ * Error response when the requested resource cannot be found. This occurs when:
+ *
+ * @remarks
+ * - The specified resource ID doesn't exist in your workspace
+ * - The resource has been deleted or moved
+ * - The resource exists but is not accessible with current permissions
+ *
+ * To resolve this error, verify the resource ID is correct and that you have access to it.
+ */
 export type NotFoundErrorResponseData = {
+  /**
+   * Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
+   */
   meta: components.Meta;
+  /**
+   * Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.
+   */
   error: components.BaseError;
 };
 
-export class NotFoundErrorResponse extends Error {
+/**
+ * Error response when the requested resource cannot be found. This occurs when:
+ *
+ * @remarks
+ * - The specified resource ID doesn't exist in your workspace
+ * - The resource has been deleted or moved
+ * - The resource exists but is not accessible with current permissions
+ *
+ * To resolve this error, verify the resource ID is correct and that you have access to it.
+ */
+export class NotFoundErrorResponse extends UnkeyError {
+  /**
+   * Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
+   */
   meta: components.Meta;
+  /**
+   * Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.
+   */
   error: components.BaseError;
 
   /** The original data that was passed to this error instance. */
   data$: NotFoundErrorResponseData;
 
-  constructor(err: NotFoundErrorResponseData) {
+  constructor(
+    err: NotFoundErrorResponseData,
+    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);
+    super(message, httpMeta);
     this.data$ = err;
-
     this.meta = err.meta;
     this.error = err.error;
 
@@ -39,9 +74,16 @@ export const NotFoundErrorResponse$inboundSchema: z.ZodType<
 > = z.object({
   meta: components.Meta$inboundSchema,
   error: components.BaseError$inboundSchema,
+  request$: z.instanceof(Request),
+  response$: z.instanceof(Response),
+  body$: z.string(),
 })
   .transform((v) => {
-    return new NotFoundErrorResponse(v);
+    return new NotFoundErrorResponse(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
   });
 
 /** @internal */

package/src/models/errors/preconditionfailederrorresponse.ts

@@ -4,26 +4,61 @@
 
 import * as z from "zod";
 import * as components from "../components/index.js";
+import { UnkeyError } from "./unkeyerror.js";
 
+/**
+ * Error response when one or more conditions specified in the request headers are not met. This typically occurs when:
+ *
+ * @remarks
+ * - Using conditional requests with If-Match or If-None-Match headers
+ * - The resource version doesn't match the expected value
+ * - Optimistic concurrency control detects a conflict
+ *
+ * To resolve this error, fetch the latest version of the resource and retry with updated conditions.
+ */
 export type PreconditionFailedErrorResponseData = {
+  /**
+   * Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
+   */
   meta: components.Meta;
+  /**
+   * Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.
+   */
   error: components.BaseError;
 };
 
-export class PreconditionFailedErrorResponse extends Error {
+/**
+ * Error response when one or more conditions specified in the request headers are not met. This typically occurs when:
+ *
+ * @remarks
+ * - Using conditional requests with If-Match or If-None-Match headers
+ * - The resource version doesn't match the expected value
+ * - Optimistic concurrency control detects a conflict
+ *
+ * To resolve this error, fetch the latest version of the resource and retry with updated conditions.
+ */
+export class PreconditionFailedErrorResponse extends UnkeyError {
+  /**
+   * Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
+   */
   meta: components.Meta;
+  /**
+   * Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.
+   */
   error: components.BaseError;
 
   /** The original data that was passed to this error instance. */
   data$: PreconditionFailedErrorResponseData;
 
-  constructor(err: PreconditionFailedErrorResponseData) {
+  constructor(
+    err: PreconditionFailedErrorResponseData,
+    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);
+    super(message, httpMeta);
     this.data$ = err;
-
     this.meta = err.meta;
     this.error = err.error;
 
@@ -39,9 +74,16 @@ export const PreconditionFailedErrorResponse$inboundSchema: z.ZodType<
 > = z.object({
   meta: components.Meta$inboundSchema,
   error: components.BaseError$inboundSchema,
+  request$: z.instanceof(Request),
+  response$: z.instanceof(Response),
+  body$: z.string(),
 })
   .transform((v) => {
-    return new PreconditionFailedErrorResponse(v);
+    return new PreconditionFailedErrorResponse(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
   });
 
 /** @internal */

package/src/models/errors/responsevalidationerror.ts

@@ -0,0 +1,50 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { formatZodError } from "./sdkvalidationerror.js";
+import { UnkeyError } from "./unkeyerror.js";
+
+export class ResponseValidationError extends UnkeyError {
+  /**
+   * The raw value that failed validation.
+   */
+  public readonly rawValue: unknown;
+
+  /**
+   * The raw message that failed validation.
+   */
+  public readonly rawMessage: unknown;
+
+  constructor(
+    message: string,
+    extra: {
+      response: Response;
+      request: Request;
+      body: string;
+      cause: unknown;
+      rawValue: unknown;
+      rawMessage: unknown;
+    },
+  ) {
+    super(message, extra);
+    this.name = "ResponseValidationError";
+    this.cause = extra.cause;
+    this.rawValue = extra.rawValue;
+    this.rawMessage = extra.rawMessage;
+  }
+
+  /**
+   * Return a pretty-formatted error message if the underlying validation error
+   * is a ZodError or some other recognized error type, otherwise return the
+   * default error message.
+   */
+  public pretty(): string {
+    if (this.cause instanceof z.ZodError) {
+      return `${this.rawMessage}\n${formatZodError(this.cause)}`;
+    } else {
+      return this.toString();
+    }
+  }
+}

package/src/models/errors/sdkvalidationerror.ts

@@ -15,6 +15,18 @@ export class SDKValidationError extends Error {
    */
   public readonly rawMessage: unknown;
 
+  // Allows for backwards compatibility for `instanceof` checks of `ResponseValidationError`
+  static override [Symbol.hasInstance](
+    instance: unknown,
+  ): instance is SDKValidationError {
+    if (!(instance instanceof Error)) return false;
+    if (!("rawValue" in instance)) return false;
+    if (!("rawMessage" in instance)) return false;
+    if (!("pretty" in instance)) return false;
+    if (typeof instance.pretty !== "function") return false;
+    return true;
+  }
+
   constructor(message: string, cause: unknown, rawValue: unknown) {
     super(`${message}: ${cause}`);
     this.name = "SDKValidationError";

package/src/models/errors/unauthorizederrorresponse.ts

@@ -4,26 +4,61 @@
 
 import * as z from "zod";
 import * as components from "../components/index.js";
+import { UnkeyError } from "./unkeyerror.js";
 
+/**
+ * Error response when authentication has failed or credentials are missing. This occurs when:
+ *
+ * @remarks
+ * - No authentication token is provided in the request
+ * - The provided token is invalid, expired, or malformed
+ * - The token format doesn't match expected patterns
+ *
+ * To resolve this error, ensure you're including a valid root key in the Authorization header.
+ */
 export type UnauthorizedErrorResponseData = {
+  /**
+   * Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
+   */
   meta: components.Meta;
+  /**
+   * Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.
+   */
   error: components.BaseError;
 };
 
-export class UnauthorizedErrorResponse extends Error {
+/**
+ * Error response when authentication has failed or credentials are missing. This occurs when:
+ *
+ * @remarks
+ * - No authentication token is provided in the request
+ * - The provided token is invalid, expired, or malformed
+ * - The token format doesn't match expected patterns
+ *
+ * To resolve this error, ensure you're including a valid root key in the Authorization header.
+ */
+export class UnauthorizedErrorResponse extends UnkeyError {
+  /**
+   * Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
+   */
   meta: components.Meta;
+  /**
+   * Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.
+   */
   error: components.BaseError;
 
   /** The original data that was passed to this error instance. */
   data$: UnauthorizedErrorResponseData;
 
-  constructor(err: UnauthorizedErrorResponseData) {
+  constructor(
+    err: UnauthorizedErrorResponseData,
+    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);
+    super(message, httpMeta);
     this.data$ = err;
-
     this.meta = err.meta;
     this.error = err.error;
 
@@ -39,9 +74,16 @@ export const UnauthorizedErrorResponse$inboundSchema: z.ZodType<
 > = z.object({
   meta: components.Meta$inboundSchema,
   error: components.BaseError$inboundSchema,
+  request$: z.instanceof(Request),
+  response$: z.instanceof(Response),
+  body$: z.string(),
 })
   .transform((v) => {
-    return new UnauthorizedErrorResponse(v);
+    return new UnauthorizedErrorResponse(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
   });
 
 /** @internal */

package/src/models/errors/unkeyerror.ts

@@ -0,0 +1,35 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+/** The base class for all HTTP error responses */
+export class UnkeyError extends Error {
+  /** HTTP status code */
+  public readonly statusCode: number;
+  /** HTTP body */
+  public readonly body: string;
+  /** HTTP headers */
+  public readonly headers: Headers;
+  /** HTTP content type */
+  public readonly contentType: string;
+  /** Raw response */
+  public readonly rawResponse: Response;
+
+  constructor(
+    message: string,
+    httpMeta: {
+      response: Response;
+      request: Request;
+      body: string;
+    },
+  ) {
+    super(message);
+    this.statusCode = httpMeta.response.status;
+    this.body = httpMeta.body;
+    this.headers = httpMeta.response.headers;
+    this.contentType = httpMeta.response.headers.get("content-type") || "";
+    this.rawResponse = httpMeta.response;
+
+    this.name = "UnkeyError";
+  }
+}

package/src/models/operations/identitieslistidentities.ts

@@ -0,0 +1,78 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { remap as remap$ } from "../../lib/primitives.js";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import * as components from "../components/index.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+export type IdentitiesListIdentitiesResponse = {
+  result: components.V2IdentitiesListIdentitiesResponseBody;
+};
+
+/** @internal */
+export const IdentitiesListIdentitiesResponse$inboundSchema: z.ZodType<
+  IdentitiesListIdentitiesResponse,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  Result: components.V2IdentitiesListIdentitiesResponseBody$inboundSchema,
+}).transform((v) => {
+  return remap$(v, {
+    "Result": "result",
+  });
+});
+
+/** @internal */
+export type IdentitiesListIdentitiesResponse$Outbound = {
+  Result: components.V2IdentitiesListIdentitiesResponseBody$Outbound;
+};
+
+/** @internal */
+export const IdentitiesListIdentitiesResponse$outboundSchema: z.ZodType<
+  IdentitiesListIdentitiesResponse$Outbound,
+  z.ZodTypeDef,
+  IdentitiesListIdentitiesResponse
+> = z.object({
+  result: components.V2IdentitiesListIdentitiesResponseBody$outboundSchema,
+}).transform((v) => {
+  return remap$(v, {
+    result: "Result",
+  });
+});
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace IdentitiesListIdentitiesResponse$ {
+  /** @deprecated use `IdentitiesListIdentitiesResponse$inboundSchema` instead. */
+  export const inboundSchema = IdentitiesListIdentitiesResponse$inboundSchema;
+  /** @deprecated use `IdentitiesListIdentitiesResponse$outboundSchema` instead. */
+  export const outboundSchema = IdentitiesListIdentitiesResponse$outboundSchema;
+  /** @deprecated use `IdentitiesListIdentitiesResponse$Outbound` instead. */
+  export type Outbound = IdentitiesListIdentitiesResponse$Outbound;
+}
+
+export function identitiesListIdentitiesResponseToJSON(
+  identitiesListIdentitiesResponse: IdentitiesListIdentitiesResponse,
+): string {
+  return JSON.stringify(
+    IdentitiesListIdentitiesResponse$outboundSchema.parse(
+      identitiesListIdentitiesResponse,
+    ),
+  );
+}
+
+export function identitiesListIdentitiesResponseFromJSON(
+  jsonString: string,
+): SafeParseResult<IdentitiesListIdentitiesResponse, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => IdentitiesListIdentitiesResponse$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'IdentitiesListIdentitiesResponse' from JSON`,
+  );
+}

package/src/models/operations/index.ts

@@ -0,0 +1,5 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export * from "./identitieslistidentities.js";

package/src/sdk/apis.ts

@@ -3,11 +3,29 @@
  */
 
 import { apisCreateApi } from "../funcs/apisCreateApi.js";
+import { apisDeleteApi } from "../funcs/apisDeleteApi.js";
+import { apisGetApi } from "../funcs/apisGetApi.js";
+import { apisListKeys } from "../funcs/apisListKeys.js";
 import { ClientSDK, RequestOptions } from "../lib/sdks.js";
 import * as components from "../models/components/index.js";
 import { unwrapAsync } from "../types/fp.js";
 
 export class Apis extends ClientSDK {
+  /**
+   * Create API namespace
+   *
+   * @remarks
+   * Create an API namespace for organizing keys by environment, service, or product.
+   *
+   * Use this to separate production from development keys, isolate different services, or manage multiple products. Each API gets a unique identifier and dedicated infrastructure for secure key operations.
+   *
+   * **Important**: API names must be unique within your workspace and cannot be changed after creation.
+   *
+   * **Required Permissions**
+   *
+   * Your root key must have one of the following permissions:
+   * - `api.*.create_api` (to create APIs in any workspace)
+   */
   async createApi(
     request: components.V2ApisCreateApiRequestBody,
     options?: RequestOptions,
@@ -18,4 +36,89 @@ export class Apis extends ClientSDK {
       options,
     ));
   }
+
+  /**
+   * Delete API namespace
+   *
+   * @remarks
+   * Permanently delete an API namespace and immediately invalidate all associated keys.
+   *
+   * Use this for cleaning up development environments, retiring deprecated services, or removing unused resources. All keys in the namespace are immediately marked as deleted and will fail verification with `code=NOT_FOUND`.
+   *
+   * **Important**: This operation is immediate and permanent. Verify you have the correct API ID before deletion. If delete protection is enabled, disable it first through the dashboard or API configuration.
+   *
+   * **Required Permissions**
+   *
+   * Your root key must have one of the following permissions:
+   * - `api.*.delete_api` (to delete any API)
+   * - `api.<api_id>.delete_api` (to delete a specific API)
+   */
+  async deleteApi(
+    request: components.V2ApisDeleteApiRequestBody,
+    options?: RequestOptions,
+  ): Promise<components.V2ApisDeleteApiResponseBody> {
+    return unwrapAsync(apisDeleteApi(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get API namespace
+   *
+   * @remarks
+   * Retrieve basic information about an API namespace including its ID and name.
+   *
+   * Use this to verify an API exists before performing operations, get the human-readable name when you only have the API ID, or confirm access to a specific namespace. For detailed key information, use the `listKeys` endpoint instead.
+   *
+   * **Required Permissions**
+   *
+   * Your root key must have one of the following permissions:
+   * - `api.*.read_api` (to read any API)
+   * - `api.<api_id>.read_api` (to read a specific API)
+   */
+  async getApi(
+    request: components.V2ApisGetApiRequestBody,
+    options?: RequestOptions,
+  ): Promise<components.V2ApisGetApiResponseBody> {
+    return unwrapAsync(apisGetApi(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * List API keys
+   *
+   * @remarks
+   * Retrieve a paginated list of API keys for dashboard and administrative interfaces.
+   *
+   * Use this to build key management dashboards, filter keys by user with `externalId`, or retrieve key details for administrative purposes. Each key includes status, metadata, permissions, and usage limits.
+   *
+   * **Important**: Set `decrypt: true` only in secure contexts to retrieve plaintext key values from recoverable keys.
+   *
+   * **Required Permissions**
+   *
+   * Your root key must have one of the following permissions for basic key listing:
+   * - `api.*.read_key` (to read keys from any API)
+   * - `api.<api_id>.read_key` (to read keys from a specific API)
+   *
+   * Additionally, you need read access to the API itself:
+   * - `api.*.read_api` or `api.<api_id>.read_api`
+   *
+   * Additional permission required for decrypt functionality:
+   * - `api.*.decrypt_key` or `api.<api_id>.decrypt_key`
+   */
+  async listKeys(
+    request: components.V2ApisListKeysRequestBody,
+    options?: RequestOptions,
+  ): Promise<components.V2ApisListKeysResponseBody> {
+    return unwrapAsync(apisListKeys(
+      this,
+      request,
+      options,
+    ));
+  }
 }

package/src/sdk/identities.ts

@@ -3,11 +3,28 @@
  */
 
 import { identitiesCreateIdentity } from "../funcs/identitiesCreateIdentity.js";
+import { identitiesDeleteIdentity } from "../funcs/identitiesDeleteIdentity.js";
+import { identitiesGetIdentity } from "../funcs/identitiesGetIdentity.js";
+import { identitiesListIdentities } from "../funcs/identitiesListIdentities.js";
+import { identitiesUpdateIdentity } from "../funcs/identitiesUpdateIdentity.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 Identities extends ClientSDK {
+  /**
+   * Create Identity
+   *
+   * @remarks
+   * Create an identity to group multiple API keys under a single entity. Identities enable shared rate limits and metadata across all associated keys.
+   *
+   * Perfect for users with multiple devices, organizations with multiple API keys, or when you need unified rate limiting across different services.
+   *
+   * > **Important**
+   * > Requires `identity.*.create_identity` permission
+   */
   async createIdentity(
     request: components.V2IdentitiesCreateIdentityRequestBody,
     options?: RequestOptions,
@@ -18,4 +35,100 @@ export class Identities extends ClientSDK {
       options,
     ));
   }
+
+  /**
+   * Delete Identity
+   *
+   * @remarks
+   * Permanently delete an identity. This operation cannot be undone.
+   *
+   * Use this for data cleanup, compliance requirements, or when removing entities from your system.
+   *
+   * > **Important**
+   * > Requires `identity.*.delete_identity` permission
+   * > Associated API keys remain functional but lose shared resources
+   * > External ID becomes available for reuse immediately
+   */
+  async deleteIdentity(
+    request: components.V2IdentitiesDeleteIdentityRequestBody,
+    options?: RequestOptions,
+  ): Promise<components.V2IdentitiesDeleteIdentityResponseBody> {
+    return unwrapAsync(identitiesDeleteIdentity(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get Identity
+   *
+   * @remarks
+   * Retrieve an identity by external ID. Returns metadata, rate limits, and other associated data.
+   *
+   * Use this to check if an identity exists, view configurations, or build management dashboards.
+   *
+   * > **Important**
+   * > Requires `identity.*.read_identity` permission
+   */
+  async getIdentity(
+    request: components.V2IdentitiesGetIdentityRequestBody,
+    options?: RequestOptions,
+  ): Promise<components.V2IdentitiesGetIdentityResponseBody> {
+    return unwrapAsync(identitiesGetIdentity(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * List Identities
+   *
+   * @remarks
+   * Get a paginated list of all identities in your workspace. Returns metadata and rate limit configurations.
+   *
+   * Perfect for building management dashboards, auditing configurations, or browsing your identities.
+   *
+   * > **Important**
+   * > Requires `identity.*.read_identity` permission
+   */
+  async listIdentities(
+    request: components.V2IdentitiesListIdentitiesRequestBody,
+    options?: RequestOptions,
+  ): Promise<
+    PageIterator<
+      operations.IdentitiesListIdentitiesResponse,
+      { cursor: string }
+    >
+  > {
+    return unwrapResultIterator(identitiesListIdentities(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Update Identity
+   *
+   * @remarks
+   * Update an identity's metadata and rate limits. Only specified fields are modified - others remain unchanged.
+   *
+   * Perfect for subscription changes, plan upgrades, or updating user information. Changes take effect immediately.
+   *
+   * > **Important**
+   * > Requires `identity.*.update_identity` permission
+   * > Rate limit changes propagate within 30 seconds
+   */
+  async updateIdentity(
+    request: components.V2IdentitiesUpdateIdentityRequestBody,
+    options?: RequestOptions,
+  ): Promise<components.V2IdentitiesUpdateIdentityResponseBody> {
+    return unwrapAsync(identitiesUpdateIdentity(
+      this,
+      request,
+      options,
+    ));
+  }
 }