npm - @unkey/api - Versions diffs - 2.0.5 → 2.1.0 - Mend

@unkey/api 2.0.5 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1421) hide show

package/docs/sdks/ratelimit/README.md DELETED Viewed

@@ -1,468 +0,0 @@
-# Ratelimit
-(*ratelimit*)
-## Overview
-Rate limiting operations
-### Available Operations
-* [deleteOverride](#deleteoverride) - Delete ratelimit override
-* [getOverride](#getoverride) - Get ratelimit override
-* [limit](#limit) - Apply rate limiting
-* [listOverrides](#listoverrides) - List ratelimit overrides
-* [setOverride](#setoverride) - Set ratelimit override
-## deleteOverride
-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`
-### Example Usage
-<!-- UsageSnippet language="typescript" operationID="ratelimit.deleteOverride" method="post" path="/v2/ratelimit.deleteOverride" -->
-```typescript
-import { Unkey } from "@unkey/api";
-const unkey = new Unkey({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const result = await unkey.ratelimit.deleteOverride({
-    namespace: "<value>",
-    identifier: "premium_user_123",
-  });
-  console.log(result);
-}
-run();
-```
-### Standalone function
-The standalone function version of this method:
-```typescript
-import { UnkeyCore } from "@unkey/api/core.js";
-import { ratelimitDeleteOverride } from "@unkey/api/funcs/ratelimitDeleteOverride.js";
-// Use `UnkeyCore` for best tree-shaking performance.
-// You can create one instance of it to use across an application.
-const unkey = new UnkeyCore({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const res = await ratelimitDeleteOverride(unkey, {
-    namespace: "<value>",
-    identifier: "premium_user_123",
-  });
-  if (res.ok) {
-    const { value: result } = res;
-    console.log(result);
-  } else {
-    console.log("ratelimitDeleteOverride failed:", res.error);
-  }
-}
-run();
-```
-### Parameters
-| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `request`                                                                                                                                                                      | [components.V2RatelimitDeleteOverrideRequestBody](../../models/components/v2ratelimitdeleteoverriderequestbody.md)                                                             | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
-| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
-| `options.fetchOptions`                                                                                                                                                         | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options)                                                                                        | :heavy_minus_sign:                                                                                                                                                             | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
-| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
-### Response
-**Promise\<[components.V2RatelimitDeleteOverrideResponseBody](../../models/components/v2ratelimitdeleteoverrideresponsebody.md)\>**
-### Errors
-| Error Type                         | Status Code                        | Content Type                       |
-| ---------------------------------- | ---------------------------------- | ---------------------------------- |
-| errors.BadRequestErrorResponse     | 400                                | application/json                   |
-| errors.UnauthorizedErrorResponse   | 401                                | application/json                   |
-| errors.ForbiddenErrorResponse      | 403                                | application/json                   |
-| errors.NotFoundErrorResponse       | 404                                | application/json                   |
-| errors.InternalServerErrorResponse | 500                                | application/json                   |
-| errors.APIError                    | 4XX, 5XX                           | \*/\*                              |
-## getOverride
-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`
-### Example Usage
-<!-- UsageSnippet language="typescript" operationID="ratelimit.getOverride" method="post" path="/v2/ratelimit.getOverride" -->
-```typescript
-import { Unkey } from "@unkey/api";
-const unkey = new Unkey({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const result = await unkey.ratelimit.getOverride({
-    namespace: "<value>",
-    identifier: "premium_user_123",
-  });
-  console.log(result);
-}
-run();
-```
-### Standalone function
-The standalone function version of this method:
-```typescript
-import { UnkeyCore } from "@unkey/api/core.js";
-import { ratelimitGetOverride } from "@unkey/api/funcs/ratelimitGetOverride.js";
-// Use `UnkeyCore` for best tree-shaking performance.
-// You can create one instance of it to use across an application.
-const unkey = new UnkeyCore({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const res = await ratelimitGetOverride(unkey, {
-    namespace: "<value>",
-    identifier: "premium_user_123",
-  });
-  if (res.ok) {
-    const { value: result } = res;
-    console.log(result);
-  } else {
-    console.log("ratelimitGetOverride failed:", res.error);
-  }
-}
-run();
-```
-### Parameters
-| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `request`                                                                                                                                                                      | [components.V2RatelimitGetOverrideRequestBody](../../models/components/v2ratelimitgetoverriderequestbody.md)                                                                   | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
-| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
-| `options.fetchOptions`                                                                                                                                                         | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options)                                                                                        | :heavy_minus_sign:                                                                                                                                                             | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
-| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
-### Response
-**Promise\<[components.V2RatelimitGetOverrideResponseBody](../../models/components/v2ratelimitgetoverrideresponsebody.md)\>**
-### Errors
-| Error Type                         | Status Code                        | Content Type                       |
-| ---------------------------------- | ---------------------------------- | ---------------------------------- |
-| errors.BadRequestErrorResponse     | 400                                | application/json                   |
-| errors.UnauthorizedErrorResponse   | 401                                | application/json                   |
-| errors.ForbiddenErrorResponse      | 403                                | application/json                   |
-| errors.NotFoundErrorResponse       | 404                                | application/json                   |
-| errors.InternalServerErrorResponse | 500                                | application/json                   |
-| errors.APIError                    | 4XX, 5XX                           | \*/\*                              |
-## limit
-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. 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)
-**Side Effects**
-Records rate limit metrics for analytics and monitoring, updates rate limit counters with sliding window algorithm, and optionally triggers override matching for custom limits.
-### Example Usage
-<!-- UsageSnippet language="typescript" operationID="ratelimit.limit" method="post" path="/v2/ratelimit.limit" -->
-```typescript
-import { Unkey } from "@unkey/api";
-const unkey = new Unkey({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const result = await unkey.ratelimit.limit({
-    namespace: "api.requests",
-    cost: 5,
-    duration: 60000,
-    identifier: "user_abc123",
-    limit: 100,
-  });
-  console.log(result);
-}
-run();
-```
-### Standalone function
-The standalone function version of this method:
-```typescript
-import { UnkeyCore } from "@unkey/api/core.js";
-import { ratelimitLimit } from "@unkey/api/funcs/ratelimitLimit.js";
-// Use `UnkeyCore` for best tree-shaking performance.
-// You can create one instance of it to use across an application.
-const unkey = new UnkeyCore({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const res = await ratelimitLimit(unkey, {
-    namespace: "api.requests",
-    cost: 5,
-    duration: 60000,
-    identifier: "user_abc123",
-    limit: 100,
-  });
-  if (res.ok) {
-    const { value: result } = res;
-    console.log(result);
-  } else {
-    console.log("ratelimitLimit failed:", res.error);
-  }
-}
-run();
-```
-### Parameters
-| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `request`                                                                                                                                                                      | [components.V2RatelimitLimitRequestBody](../../models/components/v2ratelimitlimitrequestbody.md)                                                                               | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
-| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
-| `options.fetchOptions`                                                                                                                                                         | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options)                                                                                        | :heavy_minus_sign:                                                                                                                                                             | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
-| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
-### Response
-**Promise\<[components.V2RatelimitLimitResponseBody](../../models/components/v2ratelimitlimitresponsebody.md)\>**
-### Errors
-| Error Type                         | Status Code                        | Content Type                       |
-| ---------------------------------- | ---------------------------------- | ---------------------------------- |
-| errors.BadRequestErrorResponse     | 400                                | application/json                   |
-| errors.UnauthorizedErrorResponse   | 401                                | application/json                   |
-| errors.ForbiddenErrorResponse      | 403                                | application/json                   |
-| errors.NotFoundErrorResponse       | 404                                | application/json                   |
-| errors.GoneErrorResponse           | 410                                | application/json                   |
-| errors.InternalServerErrorResponse | 500                                | application/json                   |
-| errors.APIError                    | 4XX, 5XX                           | \*/\*                              |
-## listOverrides
-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`
-### Example Usage
-<!-- UsageSnippet language="typescript" operationID="ratelimit.listOverrides" method="post" path="/v2/ratelimit.listOverrides" -->
-```typescript
-import { Unkey } from "@unkey/api";
-const unkey = new Unkey({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const result = await unkey.ratelimit.listOverrides({
-    namespace: "<value>",
-    limit: 20,
-  });
-  console.log(result);
-}
-run();
-```
-### Standalone function
-The standalone function version of this method:
-```typescript
-import { UnkeyCore } from "@unkey/api/core.js";
-import { ratelimitListOverrides } from "@unkey/api/funcs/ratelimitListOverrides.js";
-// Use `UnkeyCore` for best tree-shaking performance.
-// You can create one instance of it to use across an application.
-const unkey = new UnkeyCore({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const res = await ratelimitListOverrides(unkey, {
-    namespace: "<value>",
-    limit: 20,
-  });
-  if (res.ok) {
-    const { value: result } = res;
-    console.log(result);
-  } else {
-    console.log("ratelimitListOverrides failed:", res.error);
-  }
-}
-run();
-```
-### Parameters
-| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `request`                                                                                                                                                                      | [components.V2RatelimitListOverridesRequestBody](../../models/components/v2ratelimitlistoverridesrequestbody.md)                                                               | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
-| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
-| `options.fetchOptions`                                                                                                                                                         | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options)                                                                                        | :heavy_minus_sign:                                                                                                                                                             | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
-| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
-### Response
-**Promise\<[components.V2RatelimitListOverridesResponseBody](../../models/components/v2ratelimitlistoverridesresponsebody.md)\>**
-### Errors
-| Error Type                         | Status Code                        | Content Type                       |
-| ---------------------------------- | ---------------------------------- | ---------------------------------- |
-| errors.BadRequestErrorResponse     | 400                                | application/json                   |
-| errors.UnauthorizedErrorResponse   | 401                                | application/json                   |
-| errors.ForbiddenErrorResponse      | 403                                | application/json                   |
-| errors.NotFoundErrorResponse       | 404                                | application/json                   |
-| errors.InternalServerErrorResponse | 500                                | application/json                   |
-| errors.APIError                    | 4XX, 5XX                           | \*/\*                              |
-## setOverride
-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`
-### Example Usage
-<!-- UsageSnippet language="typescript" operationID="ratelimit.setOverride" method="post" path="/v2/ratelimit.setOverride" -->
-```typescript
-import { Unkey } from "@unkey/api";
-const unkey = new Unkey({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const result = await unkey.ratelimit.setOverride({
-    namespace: "<value>",
-    duration: 60000,
-    identifier: "premium_user_123",
-    limit: 1000,
-  });
-  console.log(result);
-}
-run();
-```
-### Standalone function
-The standalone function version of this method:
-```typescript
-import { UnkeyCore } from "@unkey/api/core.js";
-import { ratelimitSetOverride } from "@unkey/api/funcs/ratelimitSetOverride.js";
-// Use `UnkeyCore` for best tree-shaking performance.
-// You can create one instance of it to use across an application.
-const unkey = new UnkeyCore({
-  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
-});
-async function run() {
-  const res = await ratelimitSetOverride(unkey, {
-    namespace: "<value>",
-    duration: 60000,
-    identifier: "premium_user_123",
-    limit: 1000,
-  });
-  if (res.ok) {
-    const { value: result } = res;
-    console.log(result);
-  } else {
-    console.log("ratelimitSetOverride failed:", res.error);
-  }
-}
-run();
-```
-### Parameters
-| Parameter                                                                                                                                                                      | Type                                                                                                                                                                           | Required                                                                                                                                                                       | Description                                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `request`                                                                                                                                                                      | [components.V2RatelimitSetOverrideRequestBody](../../models/components/v2ratelimitsetoverriderequestbody.md)                                                                   | :heavy_check_mark:                                                                                                                                                             | The request object to use for the request.                                                                                                                                     |
-| `options`                                                                                                                                                                      | RequestOptions                                                                                                                                                                 | :heavy_minus_sign:                                                                                                                                                             | Used to set various options for making HTTP requests.                                                                                                                          |
-| `options.fetchOptions`                                                                                                                                                         | [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options)                                                                                        | :heavy_minus_sign:                                                                                                                                                             | Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed. |
-| `options.retries`                                                                                                                                                              | [RetryConfig](../../lib/utils/retryconfig.md)                                                                                                                                  | :heavy_minus_sign:                                                                                                                                                             | Enables retrying HTTP requests under certain failure conditions.                                                                                                               |
-### Response
-**Promise\<[components.V2RatelimitSetOverrideResponseBody](../../models/components/v2ratelimitsetoverrideresponsebody.md)\>**
-### Errors
-| Error Type                         | Status Code                        | Content Type                       |
-| ---------------------------------- | ---------------------------------- | ---------------------------------- |
-| errors.BadRequestErrorResponse     | 400                                | application/json                   |
-| errors.UnauthorizedErrorResponse   | 401                                | application/json                   |
-| errors.ForbiddenErrorResponse      | 403                                | application/json                   |
-| errors.NotFoundErrorResponse       | 404                                | application/json                   |
-| errors.InternalServerErrorResponse | 500                                | application/json                   |
-| errors.APIError                    | 4XX, 5XX                           | \*/\*                              |

package/docs/sdks/unkey/README.md DELETED Viewed

@@ -1,82 +0,0 @@
-# Unkey SDK
-## Overview
-Unkey API: Unkey's API provides programmatic access for all resources within our platform.
-### Authentication
-#
-This API uses HTTP Bearer authentication with root keys. Most endpoints require specific permissions associated with your root key. When making requests, include your root key in the `Authorization` header:
-```
-Authorization: Bearer unkey_xxxxxxxxxxx
-```
-All responses follow a consistent envelope structure that separates operational metadata from actual data. This design provides several benefits:
-- Debugging: Every response includes a unique requestId for tracing issues
-- Consistency: Predictable response format across all endpoints
-- Extensibility: Easy to add new metadata without breaking existing integrations
-- Error Handling: Unified error format with actionable information
-### Success Response Format:
-```json
-{
-  "meta": {
-    "requestId": "req_123456"
-  },
-  "data": {
-    // Actual response data here
-  }
-}
-```
-The meta object contains operational information:
-- `requestId`: Unique identifier for this request (essential for support)
-The data object contains the actual response data specific to each endpoint.
-### Paginated Response Format:
-```json
-{
-  "meta": {
-    "requestId": "req_123456"
-  },
-  "data": [
-    // Array of results
-  ],
-  "pagination": {
-    "cursor": "next_page_token",
-    "hasMore": true
-  }
-}
-```
-The pagination object appears on list endpoints and contains:
-- `cursor`: Token for requesting the next page
-- `hasMore`: Whether more results are available
-### Error Response Format:
-```json
-{
-  "meta": {
-    "requestId": "req_2c9a0jf23l4k567"
-  },
-  "error": {
-    "detail": "The resource you are attempting to modify is protected and cannot be changed",
-    "status": 403,
-    "title": "Forbidden",
-    "type": "https://unkey.com/docs/errors/unkey/application/protected_resource"
-  }
-}
-```
-Error responses include comprehensive diagnostic information:
-- `title`: Human-readable error summary
-- `detail`: Specific description of what went wrong
-- `status`: HTTP status code
-- `type`: Link to error documentation
-- `errors`: Array of validation errors (for 400 responses)
-This structure ensures you always have the context needed to debug issues and take corrective action.
-### Available Operations

package/examples/README.md DELETED Viewed

@@ -1,31 +0,0 @@
-# @unkey/api Examples
-This directory contains example scripts demonstrating how to use the @unkey/api SDK.
-## Prerequisites
-- Node.js (v18 or higher)
-- npm
-## Setup
-1. Copy `.env.template` to `.env`:
-   ```bash
-   cp .env.template .env
-   ```
-2. Edit `.env` and add your actual credentials (API keys, tokens, etc.)
-## Running the Examples
-To run an example file from the examples directory:
-```bash
-npm run build && npx tsx example.ts
-```
-## Creating new examples
-Duplicate an existing example file, they won't be overwritten by the generation process.