feat: Add override methods and docs (#2728)

* added overide methods to ratelimit sdk * [autofix.ci] apply automated fixes * new docs * Override sdk docs * fmt * changed to getters fixed docs * PR change * pr changes * Update list-overrides.mdx * Update set-override.mdx * pr changes --------- Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
unkeyed · Dec 12, 2024 · dce9d97 · dce9d97
1 parent 19548f8
commit dce9d97
Show file tree

Hide file tree

Showing 8 changed files with 366 additions and 3 deletions.
diff --git a/apps/docs/libraries/ts/sdk/overview.mdx b/apps/docs/libraries/ts/sdk/overview.mdx
@@ -112,14 +112,14 @@ The constructor accepts some options to customize the behavior:
 Run all requests against your own instance of unkey hosted on your own infrastructure.
 
 <ParamField body="baseUrl" type="string" default="https://api.unkey.dev">
-
-</ParamField>
 ```ts
 const unkey = new Unkey({
   //...
   baseUrl: "https://my.domain"
 })
 ```
+</ParamField>
+
 
 ### Retries
 

diff --git a/apps/docs/libraries/ts/sdk/ratelimits/overrides/delete-override.mdx b/apps/docs/libraries/ts/sdk/ratelimits/overrides/delete-override.mdx
@@ -0,0 +1,46 @@
+---
+title: "Delete Override"
+description: "Deletes an override"
+---
+
+## Request
+<ParamField body="identifier" type="string" required>
+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
+</ParamField>
+
+<Warning>
+Either `namespaceId` or `namespaceName` is required. Not both.
+</Warning>
+
+<ParamField body="namespaceId" type="string">
+The id of the namespace. Either namespaceId or namespaceName must be provided
+</ParamField>
+
+<ParamField body="namespaceName" type="string">
+Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes. Wildcards can also be used, more info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
+</ParamField>
+
+
+## Response
+
+No response, but if no error is returned the override has been deleted successfully.
+
+
+<RequestExample>
+
+```ts
+await unkey.ratelimit.deleteOverride({
+    identifier: "user_123",
+    namespaceName: "email.outbound",
+})
+```
+```ts
+await unkey.ratelimit.deleteOverride({
+    identifier: "user_123",
+    namespaceId: "rlns_1234",
+})
+```
+
+</RequestExample>
+
+
diff --git a/apps/docs/libraries/ts/sdk/ratelimits/overrides/get-override.mdx b/apps/docs/libraries/ts/sdk/ratelimits/overrides/get-override.mdx
@@ -0,0 +1,79 @@
+---
+title: "Get Override"
+description: "Gets a ratelimit override"
+---
+
+## Request
+<ParamField body="identifier" type="string" required>
+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
+</ParamField>
+
+<Warning>
+Either `namespaceId` or `namespaceName` is required. Not both.
+</Warning>
+
+<ParamField body="namespaceId" type="string">
+The id of the namespace. Either namespaceId or namespaceName must be provided
+</ParamField>
+
+<ParamField body="namespaceName" type="string">
+Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes. Wildcards can also be used, more info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
+</ParamField>
+
+
+## Response
+
+<ResponseField name="result">
+<Expandable title="properties" defaultOpen>
+
+<ParamField body="id" type="string" required>
+Identifier of the override requested
+</ParamField>
+
+<ParamField body="identifier" type="string" required>
+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
+</ParamField>
+
+<ParamField body="limit" type="number" required>
+How many requests may pass in a given window.
+</ParamField>
+
+<ParamField body="duration" type="number" required>
+The window duration in milliseconds.
+</ParamField>
+
+<ParamField body="async" type="boolean">
+Async will return a response immediately, lowering latency at the cost of accuracy.
+</ParamField>
+</Expandable>
+</ResponseField >
+
+
+<RequestExample>
+```ts
+const override = await unkey.ratelimit.getOverride({
+  identifier:"user.example", 
+  nameSpaceId:"rlns_12345",
+});
+```
+```ts
+const override = await unkey.ratelimit.getOverride({
+  identifier:"user.example", 
+  namespaceName: "email.outbound"
+});
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+{
+  result: {
+    id: "rlor_4567",
+    identifier: "user.example",
+    limit: 10,
+    duration: 60000,
+    async: false
+  }
+}
+```
+</ResponseExample>
diff --git a/apps/docs/libraries/ts/sdk/ratelimits/overrides/list-overrides.mdx b/apps/docs/libraries/ts/sdk/ratelimits/overrides/list-overrides.mdx
@@ -0,0 +1,95 @@
+---
+title: "List Overrides"
+description: "Lists all overrides"
+---
+
+## Request
+
+<Warning>
+Either `namespaceId` or `namespaceName` is required. Not both.
+</Warning>
+
+<ParamField body="namespaceId" type="string">
+The id of the namespace. Either namespaceId or namespaceName must be provided
+</ParamField>
+
+<ParamField body="namespaceName" type="string">
+Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes. Wildcards can also be used, more info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
+</ParamField>
+
+## Response
+
+<ResponseField name="result">
+<Expandable title="properties" defaultOpen>
+
+<ResponseField name="overrides" type="Array" required>
+
+ <Expandable>
+  <ParamField body="id" type="string" required>
+Identifier of the override requested
+</ParamField>
+
+<ParamField body="identifier" type="string" required>
+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
+</ParamField>
+
+<ParamField body="limit" type="number" required>
+How many requests may pass in a given window.
+</ParamField>
+
+<ParamField body="duration" type="number" required>
+The window duration in milliseconds.
+</ParamField>
+
+<ParamField body="async" type="boolean">
+Async will return a response immediately, lowering latency at the cost of accuracy.
+</ParamField>
+
+ </Expandable>
+</ResponseField>
+
+<ResponseField name="total" type="number" required>
+The total number of overrides
+</ResponseField>
+<ResponseField name="cursor" type="string">
+The cursor to use for pagination
+</ResponseField>
+ </Expandable>
+
+</ResponseField>
+
+
+<RequestExample>
+
+```ts
+const overrides = await unkey.ratelimit.listOverrides({
+    nameSpaceId:"rlns_12345", 
+});
+```
+```ts
+const overrides = await unkey.ratelimit.listOverrides({
+    namespaceName: "email.outbound"
+});
+```
+</RequestExample>
+
+<ResponseExample>
+```ts
+{
+  result: {
+    overrides: [
+       {
+        id: 'rlor_1234',
+        identifier: 'customer_123',
+        limit: 10,
+        duration: 50000,
+        async: false
+      }
+    ],
+    total: 1,
+    cursor: 'rlor_1234'
+  }
+}
+```
+
+</ResponseExample>
diff --git a/apps/docs/libraries/ts/sdk/ratelimits/overrides/set-override.mdx b/apps/docs/libraries/ts/sdk/ratelimits/overrides/set-override.mdx
@@ -0,0 +1,80 @@
+---
+title: "Set Override"
+description: "Sets an override for a ratelimit"
+---
+
+## Request
+
+
+ <ParamField body="identifier" type="string" required>
+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
+</ParamField>
+
+<ParamField body="limit" type="number" required>
+How many requests may pass in a given window.
+</ParamField>
+
+<ParamField body="duration" type="number" required>
+The window duration in milliseconds.
+</ParamField>
+
+ <Warning>
+Either `namespaceId` or `namespaceName` is required. Not both.
+</Warning>
+
+<ParamField body="namespaceId" type="string">
+The id of the namespace. Either namespaceId or namespaceName must be provided
+</ParamField>
+
+<ParamField body="namespaceName" type="string">
+Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes. Wildcards can also be used, more info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
+</ParamField>
+
+<ParamField body="async" type="boolean" default="false">
+Async will return a response immediately, lowering latency at the cost of accuracy.
+</ParamField>
+
+
+## Response
+
+<ResponseField name="result">
+  <Expandable title="properties" defaultOpen>
+    <ResponseField name="overrideId" type="string" required>
+    The id of the override that was set.
+    </ResponseField>
+  </Expandable>
+  </ResponseField>
+<RequestExample>
+
+```ts
+const override = await unkey.ratelimit.setOverride({
+    identifier: "user_123",
+    limit: 10,
+    duration: 60000,
+    namespaceId: "rlns_1234",
+    async: true
+})
+```
+```ts
+const override = await unkey.ratelimit.setOverride({
+    identifier: "user_123",
+    limit: 10,
+    duration: 60000,
+    namespaceName: "email.outbound",
+    async: true
+})
+```
+
+</RequestExample>
+
+<ResponseExample>
+```ts
+{ 
+  result: {
+     overrideId: 'rlor_12345' 
+  }
+}
+```
+
+</ResponseExample>
+
diff --git a/apps/docs/mint.json b/apps/docs/mint.json
@@ -311,7 +311,18 @@
             },
             {
               "group": "Ratelimits",
-              "pages": ["libraries/ts/sdk/ratelimits/limit"]
+              "pages": [
+                "libraries/ts/sdk/ratelimits/limit",
+                {
+                  "group": "Overrides",
+                  "pages": [
+                    "libraries/ts/sdk/ratelimits/overrides/set-override",
+                    "libraries/ts/sdk/ratelimits/overrides/get-override",
+                    "libraries/ts/sdk/ratelimits/overrides/list-overrides",
+                    "libraries/ts/sdk/ratelimits/overrides/delete-override"
+                  ]
+                }
+              ]
             }
           ]
         },

diff --git a/packages/ratelimit/src/index.ts b/packages/ratelimit/src/index.ts
@@ -2,4 +2,5 @@ export * from "./types";
 export * from "./interface";
 export * from "./noop";
 export * from "./ratelimit";
+export * from "./overrides";
 export { type Duration } from "./duration";
diff --git a/packages/ratelimit/src/overrides.ts b/packages/ratelimit/src/overrides.ts
@@ -0,0 +1,51 @@
+import { Unkey } from "@unkey/api";
+import { version } from "../package.json";
+
+export type OverrideConfig = {
+  /**
+   * @default https://api.unkey.dev
+   */
+  baseUrl?: string;
+
+  /**
+   * The unkey root key. You can create one at https://unkey.dev/app/settings/root-keys
+   *
+   * Make sure the root key has permissions to use overrides.
+   */
+  rootKey: string;
+
+  /**
+   *
+   * By default telemetry data is enabled, and sends:
+   * runtime (Node.js / Edge)
+   * platform (Node.js / Vercel / AWS)
+   * SDK version
+   */
+  disableTelemetry?: boolean;
+};
+
+export class Overrides {
+  private readonly unkey: Unkey;
+
+  constructor(config: OverrideConfig) {
+    this.unkey = new Unkey({
+      baseUrl: config.baseUrl,
+      rootKey: config.rootKey,
+      disableTelemetry: config.disableTelemetry,
+      wrapperSdkVersion: `@unkey/ratelimit@${version}`,
+    });
+  }
+
+  public get getOverride() {
+    return this.unkey.ratelimits.getOverride;
+  }
+  public get setOverride() {
+    return this.unkey.ratelimits.setOverride;
+  }
+  public get deleteOverride() {
+    return this.unkey.ratelimits.deleteOverride;
+  }
+  public get listOverrides() {
+    return this.unkey.ratelimits.listOverrides;
+  }
+}