@unkey/api 2.0.0-alpha.6 → 2.0.0

package/src/models/errors/badrequesterrorresponse.ts

@@ -4,26 +4,47 @@
 
 import * as z from "zod";
 import * as components from "../components/index.js";
+import { UnkeyError } from "./unkeyerror.js";
 
+/**
+ * Error response for invalid requests that cannot be processed due to client-side errors. This typically occurs when request parameters are missing, malformed, or fail validation rules. The response includes detailed information about the specific errors in the request, including the location of each error and suggestions for fixing it. When receiving this error, check the 'errors' array in the response for specific validation issues that need to be addressed before retrying.
+ */
 export type BadRequestErrorResponseData = {
+  /**
+   * 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;
+  /**
+   * Extended error details specifically for bad request (400) errors. This builds on the BaseError structure by adding an array of individual validation errors, making it easy to identify and fix multiple issues at once.
+   */
   error: components.BadRequestErrorDetails;
 };
 
-export class BadRequestErrorResponse extends Error {
+/**
+ * Error response for invalid requests that cannot be processed due to client-side errors. This typically occurs when request parameters are missing, malformed, or fail validation rules. The response includes detailed information about the specific errors in the request, including the location of each error and suggestions for fixing it. When receiving this error, check the 'errors' array in the response for specific validation issues that need to be addressed before retrying.
+ */
+export class BadRequestErrorResponse 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;
+  /**
+   * Extended error details specifically for bad request (400) errors. This builds on the BaseError structure by adding an array of individual validation errors, making it easy to identify and fix multiple issues at once.
+   */
   error: components.BadRequestErrorDetails;
 
   /** The original data that was passed to this error instance. */
   data$: BadRequestErrorResponseData;
 
-  constructor(err: BadRequestErrorResponseData) {
+  constructor(
+    err: BadRequestErrorResponseData,
+    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 +60,16 @@ export const BadRequestErrorResponse$inboundSchema: z.ZodType<
 > = z.object({
   meta: components.Meta$inboundSchema,
   error: components.BadRequestErrorDetails$inboundSchema,
+  request$: z.instanceof(Request),
+  response$: z.instanceof(Response),
+  body$: z.string(),
 })
   .transform((v) => {
-    return new BadRequestErrorResponse(v);
+    return new BadRequestErrorResponse(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
   });
 
 /** @internal */

package/src/models/errors/conflicterrorresponse.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 request conflicts with the current state of the resource. This occurs when:
+ *
+ * @remarks
+ * - Attempting to create a resource that already exists
+ * - Modifying a resource that has been changed by another operation
+ * - Violating unique constraints or business rules
+ *
+ * To resolve this error, check the current state of the resource and adjust your request accordingly.
+ */
 export type ConflictErrorResponseData = {
+  /**
+   * 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 ConflictErrorResponse extends Error {
+/**
+ * Error response when the request conflicts with the current state of the resource. This occurs when:
+ *
+ * @remarks
+ * - Attempting to create a resource that already exists
+ * - Modifying a resource that has been changed by another operation
+ * - Violating unique constraints or business rules
+ *
+ * To resolve this error, check the current state of the resource and adjust your request accordingly.
+ */
+export class ConflictErrorResponse 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$: ConflictErrorResponseData;
 
-  constructor(err: ConflictErrorResponseData) {
+  constructor(
+    err: ConflictErrorResponseData,
+    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 ConflictErrorResponse$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 ConflictErrorResponse(v);
+    return new ConflictErrorResponse(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
   });
 
 /** @internal */

package/src/models/errors/forbiddenerrorresponse.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 provided credentials are valid but lack sufficient permissions for the requested operation. This occurs when:
+ *
+ * @remarks
+ * - The root key doesn't have the required permissions for this endpoint
+ * - The operation requires elevated privileges that the current key lacks
+ * - Access to the requested resource is restricted based on workspace settings
+ *
+ * To resolve this error, ensure your root key has the necessary permissions or contact your workspace administrator.
+ */
 export type ForbiddenErrorResponseData = {
+  /**
+   * 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 ForbiddenErrorResponse extends Error {
+/**
+ * Error response when the provided credentials are valid but lack sufficient permissions for the requested operation. This occurs when:
+ *
+ * @remarks
+ * - The root key doesn't have the required permissions for this endpoint
+ * - The operation requires elevated privileges that the current key lacks
+ * - Access to the requested resource is restricted based on workspace settings
+ *
+ * To resolve this error, ensure your root key has the necessary permissions or contact your workspace administrator.
+ */
+export class ForbiddenErrorResponse 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$: ForbiddenErrorResponseData;
 
-  constructor(err: ForbiddenErrorResponseData) {
+  constructor(
+    err: ForbiddenErrorResponseData,
+    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 ForbiddenErrorResponse$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 ForbiddenErrorResponse(v);
+    return new ForbiddenErrorResponse(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
   });
 
 /** @internal */

package/src/models/errors/index.ts

@@ -10,5 +10,6 @@ export * from "./httpclienterrors.js";
 export * from "./internalservererrorresponse.js";
 export * from "./notfounderrorresponse.js";
 export * from "./preconditionfailederrorresponse.js";
+export * from "./responsevalidationerror.js";
 export * from "./sdkvalidationerror.js";
 export * from "./unauthorizederrorresponse.js";

package/src/models/errors/internalservererrorresponse.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 an unexpected error occurs on the server. This indicates a problem with Unkey's systems rather than your request.
+ *
+ * @remarks
+ *
+ * When you encounter this error:
+ * - The request ID in the response can help Unkey support investigate the issue
+ * - The error is likely temporary and retrying may succeed
+ * - If the error persists, contact Unkey support with the request ID
+ */
 export type InternalServerErrorResponseData = {
+  /**
+   * 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 InternalServerErrorResponse extends Error {
+/**
+ * Error response when an unexpected error occurs on the server. This indicates a problem with Unkey's systems rather than your request.
+ *
+ * @remarks
+ *
+ * When you encounter this error:
+ * - The request ID in the response can help Unkey support investigate the issue
+ * - The error is likely temporary and retrying may succeed
+ * - If the error persists, contact Unkey support with the request ID
+ */
+export class InternalServerErrorResponse 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$: InternalServerErrorResponseData;
 
-  constructor(err: InternalServerErrorResponseData) {
+  constructor(
+    err: InternalServerErrorResponseData,
+    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 InternalServerErrorResponse$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 InternalServerErrorResponse(v);
+    return new InternalServerErrorResponse(v, {
+      request: v.request$,
+      response: v.response$,
+      body: v.body$,
+    });
   });
 
 /** @internal */

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 */