@unkey/api 2.0.0-alpha.7 → 2.0.0

package/src/models/components/v2ratelimitdeleteoverrideresponsedata.ts

@@ -0,0 +1,66 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+/**
+ * Empty response object. A successful response indicates the override was successfully deleted. The operation is immediate - as soon as this response is received, the override no longer exists and affected identifiers have reverted to using the default rate limit for the namespace. No other data is returned as part of the deletion operation.
+ */
+export type V2RatelimitDeleteOverrideResponseData = {};
+
+/** @internal */
+export const V2RatelimitDeleteOverrideResponseData$inboundSchema: z.ZodType<
+  V2RatelimitDeleteOverrideResponseData,
+  z.ZodTypeDef,
+  unknown
+> = z.object({});
+
+/** @internal */
+export type V2RatelimitDeleteOverrideResponseData$Outbound = {};
+
+/** @internal */
+export const V2RatelimitDeleteOverrideResponseData$outboundSchema: z.ZodType<
+  V2RatelimitDeleteOverrideResponseData$Outbound,
+  z.ZodTypeDef,
+  V2RatelimitDeleteOverrideResponseData
+> = z.object({});
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace V2RatelimitDeleteOverrideResponseData$ {
+  /** @deprecated use `V2RatelimitDeleteOverrideResponseData$inboundSchema` instead. */
+  export const inboundSchema =
+    V2RatelimitDeleteOverrideResponseData$inboundSchema;
+  /** @deprecated use `V2RatelimitDeleteOverrideResponseData$outboundSchema` instead. */
+  export const outboundSchema =
+    V2RatelimitDeleteOverrideResponseData$outboundSchema;
+  /** @deprecated use `V2RatelimitDeleteOverrideResponseData$Outbound` instead. */
+  export type Outbound = V2RatelimitDeleteOverrideResponseData$Outbound;
+}
+
+export function v2RatelimitDeleteOverrideResponseDataToJSON(
+  v2RatelimitDeleteOverrideResponseData: V2RatelimitDeleteOverrideResponseData,
+): string {
+  return JSON.stringify(
+    V2RatelimitDeleteOverrideResponseData$outboundSchema.parse(
+      v2RatelimitDeleteOverrideResponseData,
+    ),
+  );
+}
+
+export function v2RatelimitDeleteOverrideResponseDataFromJSON(
+  jsonString: string,
+): SafeParseResult<V2RatelimitDeleteOverrideResponseData, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) =>
+      V2RatelimitDeleteOverrideResponseData$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'V2RatelimitDeleteOverrideResponseData' from JSON`,
+  );
+}

package/src/models/components/v2ratelimitgetoverriderequestbody.ts

@@ -8,19 +8,33 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Gets the configuration of an existing override.
+ * Gets the configuration of an existing rate limit override. Use this to retrieve details about custom rate limit rules that have been created for specific identifiers within a namespace.
+ *
+ * @remarks
+ *
+ * This endpoint is useful for:
+ * - Verifying override configurations
+ * - Checking current limits for specific entities
+ * - Auditing rate limit policies
+ * - Debugging rate limiting behavior
+ * - Retrieving override settings for modification
  */
 export type V2RatelimitGetOverrideRequestBody = {
   /**
-   * The id of the namespace. Either namespaceId or namespaceName must be provided
+   * The id or name of the namespace containing the override.
    */
-  namespaceId?: string | undefined;
+  namespace: string;
   /**
-   * The name of the namespace. Either namespaceId or namespaceName must be provided
-   */
-  namespaceName?: string | undefined;
-  /**
-   * Identifier of your user, this can be their userId, an email, an ip or anything else. Wildcards ( * ) can be used to match multiple identifiers, More info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
+   * The exact identifier pattern for the override you want to retrieve. This must match exactly as it was specified when creating the override.
+   *
+   * @remarks
+   *
+   * Important notes:
+   * - This is case-sensitive and must match exactly
+   * - Include any wildcards (*) that were part of the original pattern
+   * - For example, if the override was created for 'premium_*', you must use 'premium_*' here, not a specific ID like 'premium_user1'
+   *
+   * This field is used to look up the specific override configuration for this pattern.
    */
   identifier: string;
 };
@@ -31,15 +45,13 @@ export const V2RatelimitGetOverrideRequestBody$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  namespaceId: z.string().optional(),
-  namespaceName: z.string().optional(),
+  namespace: z.string(),
   identifier: z.string(),
 });
 
 /** @internal */
 export type V2RatelimitGetOverrideRequestBody$Outbound = {
-  namespaceId?: string | undefined;
-  namespaceName?: string | undefined;
+  namespace: string;
   identifier: string;
 };
 
@@ -49,8 +61,7 @@ export const V2RatelimitGetOverrideRequestBody$outboundSchema: z.ZodType<
   z.ZodTypeDef,
   V2RatelimitGetOverrideRequestBody
 > = z.object({
-  namespaceId: z.string().optional(),
-  namespaceName: z.string().optional(),
+  namespace: z.string(),
   identifier: z.string(),
 });
 

package/src/models/components/v2ratelimitgetoverrideresponsebody.ts

@@ -20,6 +20,9 @@ import {
 } from "./ratelimitoverride.js";
 
 export type V2RatelimitGetOverrideResponseBody = {
+  /**
+   * 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: Meta;
   data: RatelimitOverride;
 };

package/src/models/components/v2ratelimitlimitrequestbody.ts

@@ -9,23 +9,44 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 export type V2RatelimitLimitRequestBody = {
   /**
-   * The namespace name for the rate limit.
+   * The id or name of the namespace.
    */
   namespace: string;
   /**
-   * The cost of the request. Defaults to 1 if not provided.
+   * Sets how much of the rate limit quota this request consumes, enabling weighted rate limiting.
+   *
+   * @remarks
+   * Use higher values for resource-intensive operations and 0 for tracking without limiting.
+   * When accumulated cost exceeds the limit within the duration window, subsequent requests are rejected.
+   * Essential for implementing fair usage policies and preventing resource abuse through expensive operations.
    */
   cost?: number | undefined;
   /**
-   * The duration in milliseconds for the rate limit window.
+   * Sets the rate limit window duration in milliseconds after which the counter resets.
+   *
+   * @remarks
+   * Shorter durations enable faster recovery but may be less effective against sustained abuse.
+   * Common values include 60000 (1 minute), 3600000 (1 hour), and 86400000 (24 hours).
+   * Balance user experience with protection needs when choosing window sizes.
    */
   duration: number;
   /**
-   * The identifier for the rate limit.
+   * Defines the scope of rate limiting by identifying the entity being limited.
+   *
+   * @remarks
+   * Use user IDs for per-user limits, IP addresses for anonymous limiting, or API key IDs for per-key limits.
+   * Accepts letters, numbers, underscores, dots, colons, slashes, and hyphens for flexible identifier formats.
+   * The same identifier can be used across different namespaces to apply multiple rate limit types.
+   * Choose identifiers that provide appropriate granularity for your rate limiting strategy.
    */
   identifier: string;
   /**
-   * The maximum number of requests allowed.
+   * Sets the maximum operations allowed within the duration window before requests are rejected.
+   *
+   * @remarks
+   * When this limit is reached, subsequent requests fail with `RATE_LIMITED` until the window resets.
+   * Balance user experience with resource protection when setting limits for different user tiers.
+   * Consider system capacity, business requirements, and fair usage policies in limit determination.
    */
   limit: number;
 };

package/src/models/components/v2ratelimitlimitresponsebody.ts

@@ -13,15 +13,18 @@ import {
   Meta$outboundSchema,
 } from "./meta.js";
 import {
-  RatelimitLimitResponseData,
-  RatelimitLimitResponseData$inboundSchema,
-  RatelimitLimitResponseData$Outbound,
-  RatelimitLimitResponseData$outboundSchema,
-} from "./ratelimitlimitresponsedata.js";
+  V2RatelimitLimitResponseData,
+  V2RatelimitLimitResponseData$inboundSchema,
+  V2RatelimitLimitResponseData$Outbound,
+  V2RatelimitLimitResponseData$outboundSchema,
+} from "./v2ratelimitlimitresponsedata.js";
 
 export type V2RatelimitLimitResponseBody = {
+  /**
+   * 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: Meta;
-  data: RatelimitLimitResponseData;
+  data: V2RatelimitLimitResponseData;
 };
 
 /** @internal */
@@ -31,13 +34,13 @@ export const V2RatelimitLimitResponseBody$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   meta: Meta$inboundSchema,
-  data: RatelimitLimitResponseData$inboundSchema,
+  data: V2RatelimitLimitResponseData$inboundSchema,
 });
 
 /** @internal */
 export type V2RatelimitLimitResponseBody$Outbound = {
   meta: Meta$Outbound;
-  data: RatelimitLimitResponseData$Outbound;
+  data: V2RatelimitLimitResponseData$Outbound;
 };
 
 /** @internal */
@@ -47,7 +50,7 @@ export const V2RatelimitLimitResponseBody$outboundSchema: z.ZodType<
   V2RatelimitLimitResponseBody
 > = z.object({
   meta: Meta$outboundSchema,
-  data: RatelimitLimitResponseData$outboundSchema,
+  data: V2RatelimitLimitResponseData$outboundSchema,
 });
 
 /**

package/src/models/components/v2ratelimitlimitresponsedata.ts

@@ -0,0 +1,133 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+export type V2RatelimitLimitResponseData = {
+  /**
+   * The maximum number of operations allowed within the time window. This reflects either the default limit specified in the request or an override limit if one exists for this identifier.
+   *
+   * @remarks
+   *
+   * This value helps clients understand their total quota for the current window.
+   */
+  limit: number;
+  /**
+   * The number of operations remaining in the current window before the rate limit is exceeded. Applications should use this value to:
+   *
+   * @remarks
+   *
+   * - Implement client-side throttling before hitting limits
+   * - Display usage information to end users
+   * - Trigger alerts when approaching limits
+   * - Adjust request patterns based on available capacity
+   *
+   * When this reaches zero, requests will be rejected until the window resets.
+   */
+  remaining: number;
+  /**
+   * The Unix timestamp in milliseconds when the rate limit window will reset and 'remaining' will return to 'limit'.
+   *
+   * @remarks
+   *
+   * This timestamp enables clients to:
+   * - Calculate and display wait times to users
+   * - Implement intelligent retry mechanisms
+   * - Schedule requests to resume after the reset
+   * - Implement exponential backoff when needed
+   *
+   * The reset time is based on a sliding window from the first request in the current window.
+   */
+  reset: number;
+  /**
+   * Whether the request passed the rate limit check. If true, the request is allowed to proceed. If false, the request has exceeded the rate limit and should be blocked or rejected.
+   *
+   * @remarks
+   *
+   * You MUST check this field to determine if the request should proceed, as the endpoint always returns `HTTP 200` even when rate limited.
+   */
+  success: boolean;
+  /**
+   * If a rate limit override was applied for this identifier, this field contains the ID of the override that was used. Empty when no override is in effect.
+   *
+   * @remarks
+   *
+   * This can be useful for:
+   * - Debugging which override rule was matched
+   * - Tracking the effects of specific overrides
+   * - Understanding why limits differ from default values
+   */
+  overrideId?: string | undefined;
+};
+
+/** @internal */
+export const V2RatelimitLimitResponseData$inboundSchema: z.ZodType<
+  V2RatelimitLimitResponseData,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  limit: z.number().int(),
+  remaining: z.number().int(),
+  reset: z.number().int(),
+  success: z.boolean(),
+  overrideId: z.string().optional(),
+});
+
+/** @internal */
+export type V2RatelimitLimitResponseData$Outbound = {
+  limit: number;
+  remaining: number;
+  reset: number;
+  success: boolean;
+  overrideId?: string | undefined;
+};
+
+/** @internal */
+export const V2RatelimitLimitResponseData$outboundSchema: z.ZodType<
+  V2RatelimitLimitResponseData$Outbound,
+  z.ZodTypeDef,
+  V2RatelimitLimitResponseData
+> = z.object({
+  limit: z.number().int(),
+  remaining: z.number().int(),
+  reset: z.number().int(),
+  success: z.boolean(),
+  overrideId: z.string().optional(),
+});
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace V2RatelimitLimitResponseData$ {
+  /** @deprecated use `V2RatelimitLimitResponseData$inboundSchema` instead. */
+  export const inboundSchema = V2RatelimitLimitResponseData$inboundSchema;
+  /** @deprecated use `V2RatelimitLimitResponseData$outboundSchema` instead. */
+  export const outboundSchema = V2RatelimitLimitResponseData$outboundSchema;
+  /** @deprecated use `V2RatelimitLimitResponseData$Outbound` instead. */
+  export type Outbound = V2RatelimitLimitResponseData$Outbound;
+}
+
+export function v2RatelimitLimitResponseDataToJSON(
+  v2RatelimitLimitResponseData: V2RatelimitLimitResponseData,
+): string {
+  return JSON.stringify(
+    V2RatelimitLimitResponseData$outboundSchema.parse(
+      v2RatelimitLimitResponseData,
+    ),
+  );
+}
+
+export function v2RatelimitLimitResponseDataFromJSON(
+  jsonString: string,
+): SafeParseResult<V2RatelimitLimitResponseData, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => V2RatelimitLimitResponseData$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'V2RatelimitLimitResponseData' from JSON`,
+  );
+}

package/src/models/components/v2ratelimitlistoverridesrequestbody.ts

@@ -9,19 +9,23 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 export type V2RatelimitListOverridesRequestBody = {
   /**
-   * The id of the namespace to list overrides for.
+   * The id or name of the rate limit namespace to list overrides for.
    */
-  namespaceId?: string | undefined;
+  namespace: string;
   /**
-   * The name of the namespace to list overrides for.
-   */
-  namespaceName?: string | undefined;
-  /**
-   * Pagination cursor from a previous response
+   * Pagination cursor from a previous response. Include this when fetching subsequent pages of results. Each response containing more results than the requested limit will include a cursor value in the pagination object that can be used here.
    */
   cursor?: string | undefined;
   /**
-   * Maximum number of results to return
+   * Maximum number of override entries to return in a single response. Use this to control response size and loading performance.
+   *
+   * @remarks
+   *
+   * - Lower values (10-20): Better for UI displays and faster response times
+   * - Higher values (50-100): Better for data exports or bulk operations
+   * - Default (10): Suitable for most dashboard views
+   *
+   * Results exceeding this limit will be paginated, with a cursor provided for fetching subsequent pages.
    */
   limit?: number | undefined;
 };
@@ -32,16 +36,14 @@ export const V2RatelimitListOverridesRequestBody$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  namespaceId: z.string().optional(),
-  namespaceName: z.string().optional(),
+  namespace: z.string(),
   cursor: z.string().optional(),
   limit: z.number().int().default(10),
 });
 
 /** @internal */
 export type V2RatelimitListOverridesRequestBody$Outbound = {
-  namespaceId?: string | undefined;
-  namespaceName?: string | undefined;
+  namespace: string;
   cursor?: string | undefined;
   limit: number;
 };
@@ -52,8 +54,7 @@ export const V2RatelimitListOverridesRequestBody$outboundSchema: z.ZodType<
   z.ZodTypeDef,
   V2RatelimitListOverridesRequestBody
 > = z.object({
-  namespaceId: z.string().optional(),
-  namespaceName: z.string().optional(),
+  namespace: z.string(),
   cursor: z.string().optional(),
   limit: z.number().int().default(10),
 });

package/src/models/components/v2ratelimitlistoverridesresponsebody.ts

@@ -26,8 +26,14 @@ import {
 } from "./ratelimitoverride.js";
 
 export type V2RatelimitListOverridesResponseBody = {
+  /**
+   * 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: Meta;
   data: Array<RatelimitOverride>;
+  /**
+   * Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
+   */
   pagination?: Pagination | undefined;
 };
 

package/src/models/components/v2ratelimitsetoverriderequestbody.ts

@@ -8,27 +8,63 @@ import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 /**
- * Sets a new or overwrites an existing override.
+ * Sets a new or overwrites an existing rate limit override. Overrides allow you to apply special rate limit rules to specific identifiers, providing custom limits that differ from the default.
+ *
+ * @remarks
+ *
+ * Overrides are useful for:
+ * - Granting higher limits to premium users or trusted partners
+ * - Implementing stricter limits for suspicious or abusive users
+ * - Creating tiered access levels with different quotas
+ * - Implementing temporary rate limit adjustments
+ * - Prioritizing important clients with higher limits
  */
 export type V2RatelimitSetOverrideRequestBody = {
   /**
-   * The id of the namespace. Either namespaceId or namespaceName must be provided
+   * The ID or name of the rate limit namespace.
    */
-  namespaceId?: string | undefined;
+  namespace: string;
   /**
-   * The name of the namespace. Either namespaceId or namespaceName must be provided
-   */
-  namespaceName?: string | undefined;
-  /**
-   * The duration in milliseconds for the rate limit window.
+   * The duration in milliseconds for the rate limit window. This defines how long the rate limit counter accumulates before resetting to zero.
+   *
+   * @remarks
+   *
+   * Considerations:
+   * - This can differ from the default duration for the namespace
+   * - Longer durations create stricter limits that take longer to reset
+   * - Shorter durations allow more frequent bursts of activity
+   * - Common values: 60000 (1 minute), 3600000 (1 hour), 86400000 (1 day)
    */
   duration: number;
   /**
-   * Identifier of your user, this can be their userId, an email, an ip or anything else. Wildcards ( * ) can be used to match multiple identifiers, More info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
+   * Identifier of the entity receiving this custom rate limit. This can be:
+   *
+   * @remarks
+   *
+   * - A specific user ID for individual custom limits
+   * - An IP address for location-based rules
+   * - An email domain for organization-wide policies
+   * - Any other string that identifies the target entity
+   *
+   * Wildcards (*) can be used to create pattern-matching rules that apply to multiple identifiers. For example:
+   * - 'premium_*' would match all identifiers starting with 'premium_'
+   * - '*_admin' would match all identifiers ending with '_admin'
+   * - '*suspicious*' would match any identifier containing 'suspicious'
+   *
+   * More detailed information on wildcard pattern rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
    */
   identifier: string;
   /**
-   * The maximum number of requests allowed.
+   * The maximum number of requests allowed for this override. This defines the custom quota for the specified identifier(s).
+   *
+   * @remarks
+   *
+   * Special values:
+   * - Higher than default: For premium or trusted entities
+   * - Lower than default: For suspicious or abusive entities
+   * - 0: To completely block access (useful for ban implementation)
+   *
+   * This limit entirely replaces the default limit for matching identifiers.
    */
   limit: number;
 };
@@ -39,8 +75,7 @@ export const V2RatelimitSetOverrideRequestBody$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  namespaceId: z.string().optional(),
-  namespaceName: z.string().optional(),
+  namespace: z.string(),
   duration: z.number().int(),
   identifier: z.string(),
   limit: z.number().int(),
@@ -48,8 +83,7 @@ export const V2RatelimitSetOverrideRequestBody$inboundSchema: z.ZodType<
 
 /** @internal */
 export type V2RatelimitSetOverrideRequestBody$Outbound = {
-  namespaceId?: string | undefined;
-  namespaceName?: string | undefined;
+  namespace: string;
   duration: number;
   identifier: string;
   limit: number;
@@ -61,8 +95,7 @@ export const V2RatelimitSetOverrideRequestBody$outboundSchema: z.ZodType<
   z.ZodTypeDef,
   V2RatelimitSetOverrideRequestBody
 > = z.object({
-  namespaceId: z.string().optional(),
-  namespaceName: z.string().optional(),
+  namespace: z.string(),
   duration: z.number().int(),
   identifier: z.string(),
   limit: z.number().int(),

package/src/models/components/v2ratelimitsetoverrideresponsebody.ts

@@ -13,15 +13,18 @@ import {
   Meta$outboundSchema,
 } from "./meta.js";
 import {
-  RatelimitSetOverrideResponseData,
-  RatelimitSetOverrideResponseData$inboundSchema,
-  RatelimitSetOverrideResponseData$Outbound,
-  RatelimitSetOverrideResponseData$outboundSchema,
-} from "./ratelimitsetoverrideresponsedata.js";
+  V2RatelimitSetOverrideResponseData,
+  V2RatelimitSetOverrideResponseData$inboundSchema,
+  V2RatelimitSetOverrideResponseData$Outbound,
+  V2RatelimitSetOverrideResponseData$outboundSchema,
+} from "./v2ratelimitsetoverrideresponsedata.js";
 
 export type V2RatelimitSetOverrideResponseBody = {
+  /**
+   * 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: Meta;
-  data: RatelimitSetOverrideResponseData;
+  data: V2RatelimitSetOverrideResponseData;
 };
 
 /** @internal */
@@ -31,13 +34,13 @@ export const V2RatelimitSetOverrideResponseBody$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   meta: Meta$inboundSchema,
-  data: RatelimitSetOverrideResponseData$inboundSchema,
+  data: V2RatelimitSetOverrideResponseData$inboundSchema,
 });
 
 /** @internal */
 export type V2RatelimitSetOverrideResponseBody$Outbound = {
   meta: Meta$Outbound;
-  data: RatelimitSetOverrideResponseData$Outbound;
+  data: V2RatelimitSetOverrideResponseData$Outbound;
 };
 
 /** @internal */
@@ -47,7 +50,7 @@ export const V2RatelimitSetOverrideResponseBody$outboundSchema: z.ZodType<
   V2RatelimitSetOverrideResponseBody
 > = z.object({
   meta: Meta$outboundSchema,
-  data: RatelimitSetOverrideResponseData$outboundSchema,
+  data: V2RatelimitSetOverrideResponseData$outboundSchema,
 });
 
 /**