@unkey/api/src/sdk/ratelimit.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 { ratelimitDeleteOverride } from "../funcs/ratelimitDeleteOverride.js";
import { ratelimitGetOverride } from "../funcs/ratelimitGetOverride.js";
import { ratelimitLimit } from "../funcs/ratelimitLimit.js";
import { ratelimitListOverrides } from "../funcs/ratelimitListOverrides.js";
import { ratelimitMultiLimit } from "../funcs/ratelimitMultiLimit.js";
import { ratelimitSetOverride } from "../funcs/ratelimitSetOverride.js";
import { ClientSDK, RequestOptions } from "../lib/sdks.js";
import * as components from "../models/components/index.js";
import { unwrapAsync } from "../types/fp.js";

export class Ratelimit extends ClientSDK {
  /**
   * Delete ratelimit override
   *
   * @remarks
   * Permanently remove a rate limit override. Affected identifiers immediately revert to the namespace default.
   *
   * Use this to remove temporary overrides, reset identifiers to standard limits, or clean up outdated rules.
   *
   * **Important:** Deletion is immediate and permanent. The override cannot be recovered and must be recreated if needed again.
   *
   * **Permissions:** Requires `ratelimit.*.delete_override` or `ratelimit.<namespace_id>.delete_override`
   */
  async deleteOverride(
    request: components.V2RatelimitDeleteOverrideRequestBody,
    options?: RequestOptions,
  ): Promise<components.V2RatelimitDeleteOverrideResponseBody> {
    return unwrapAsync(ratelimitDeleteOverride(
      this,
      request,
      options,
    ));
  }

  /**
   * Get ratelimit override
   *
   * @remarks
   * Retrieve the configuration of a specific rate limit override by its identifier.
   *
   * Use this to inspect override configurations, audit rate limiting policies, or debug rate limiting behavior.
   *
   * **Important:** The identifier must match exactly as specified when creating the override, including wildcard patterns.
   *
   * **Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`
   */
  async getOverride(
    request: components.V2RatelimitGetOverrideRequestBody,
    options?: RequestOptions,
  ): Promise<components.V2RatelimitGetOverrideResponseBody> {
    return unwrapAsync(ratelimitGetOverride(
      this,
      request,
      options,
    ));
  }

  /**
   * Apply rate limiting
   *
   * @remarks
   * Check and enforce rate limits for any identifier (user ID, IP address, API client, etc.).
   *
   * Use this for rate limiting beyond API keys - limit users by ID, IPs by address, or any custom identifier. Supports namespace organization, variable costs, and custom overrides.
   *
   * **Response Codes**: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded — check the `success` field in the response to determine if the request should be allowed. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
   *
   * **Required Permissions**
   *
   * Your root key must have one of the following permissions:
   * - `ratelimit.*.limit` (to check limits in any namespace)
   * - `ratelimit.<namespace_id>.limit` (to check limits in a specific namespace)
   */
  async limit(
    request: components.V2RatelimitLimitRequestBody,
    options?: RequestOptions,
  ): Promise<components.V2RatelimitLimitResponseBody> {
    return unwrapAsync(ratelimitLimit(
      this,
      request,
      options,
    ));
  }

  /**
   * List ratelimit overrides
   *
   * @remarks
   * Retrieve a paginated list of all rate limit overrides in a namespace.
   *
   * Use this to audit rate limiting policies, build admin dashboards, or manage override configurations.
   *
   * **Important:** Results are paginated. Use the cursor parameter to retrieve additional pages when more results are available.
   *
   * **Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`
   */
  async listOverrides(
    request: components.V2RatelimitListOverridesRequestBody,
    options?: RequestOptions,
  ): Promise<components.V2RatelimitListOverridesResponseBody> {
    return unwrapAsync(ratelimitListOverrides(
      this,
      request,
      options,
    ));
  }

  /**
   * Apply multiple rate limit checks
   *
   * @remarks
   * Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses, API clients, etc.).
   *
   * Use this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own result with a top-level `passed` indicator showing if all checks succeeded.
   *
   * **Response Codes**: Rate limit checks return HTTP 200 regardless of whether limits are exceeded — check the `passed` field to see if all limits passed, or the `success` field in each individual result. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
   *
   * **Required Permissions**
   *
   * Your root key must have one of the following permissions:
   * - `ratelimit.*.limit` (to check limits in any namespace)
   * - `ratelimit.<namespace_id>.limit` (to check limits in all specific namespaces being checked)
   */
  async multiLimit(
    request: Array<components.V2RatelimitLimitRequestBody>,
    options?: RequestOptions,
  ): Promise<components.V2RatelimitMultiLimitResponseBody> {
    return unwrapAsync(ratelimitMultiLimit(
      this,
      request,
      options,
    ));
  }

  /**
   * Set ratelimit override
   *
   * @remarks
   * Create or update a custom rate limit for specific identifiers, bypassing the namespace default.
   *
   * Use this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency throttling.
   *
   * **Important:** Overrides take effect immediately and completely replace the default limit for matching identifiers. Use wildcard patterns (e.g., `premium_*`) to match multiple identifiers.
   *
   * **Permissions:** Requires `ratelimit.*.set_override` or `ratelimit.<namespace_id>.set_override`
   */
  async setOverride(
    request: components.V2RatelimitSetOverrideRequestBody,
    options?: RequestOptions,
  ): Promise<components.V2RatelimitSetOverrideResponseBody> {
    return unwrapAsync(ratelimitSetOverride(
      this,
      request,
      options,
    ));
  }
}