@unkey/api 0.26.2 → 0.28.0

package/dist/index.d.mts

@@ -19,6 +19,9 @@ interface paths {
   "/v1/keys.getKey": {
     get: operations["getKey"];
   };
+  "/v1/keys.whoami": {
+    post: operations["whoami"];
+  };
   "/v1/keys.deleteKey": {
     post: operations["deleteKey"];
   };
@@ -73,6 +76,18 @@ interface paths {
   "/v1/ratelimits.limit": {
     post: operations["limit"];
   };
+  "/v1/ratelimits.setOverride": {
+    post: operations["ratelimit.setOverride"];
+  };
+  "/v1/ratelimits.listOverrides": {
+    get: operations["listOverrides"];
+  };
+  "/v1/ratelimits.deleteOverride": {
+    post: operations["deleteOverride"];
+  };
+  "/v1/ratelimits.getOverride": {
+    get: operations["getOverride"];
+  };
   "/v1/migrations.createKeys": {
     post: operations["v1.migrations.createKeys"];
   };
@@ -353,13 +368,14 @@ interface components {
       /**
        * @description Unkey allows you to refill remaining verifications on a key on a regular interval.
        * @example {
-       *   "interval": "daily",
-       *   "amount": 10
+       *   "interval": "monthly",
+       *   "amount": 10,
+       *   "refillDay": 10
        * }
        */
       refill?: {
         /**
-         * @description Determines the rate at which verifications will be refilled.
+         * @description Determines the rate at which verifications will be refilled. When 'daily' is set for 'interval' 'refillDay' will be set to null.
          * @example daily
          * @enum {string}
          */
@@ -369,6 +385,12 @@ interface components {
          * @example 100
          */
         amount: number;
+        /**
+         * @description The day verifications will refill each month, when interval is set to 'monthly'. Value is not zero-indexed making 1 the first day of the month. If left blank it will default to the first day of the month. When 'daily' is set for 'interval' 'refillDay' will be set to null.
+         * @default 1
+         * @example 15
+         */
+        refillDay?: number | null;
         /**
          * @description The unix timestamp in miliseconds when the key was last refilled.
          * @example 100
@@ -517,6 +539,8 @@ interface components {
        * - INSUFFICIENT_PERMISSIONS: you do not have the required permissions to perform this action
        * - EXPIRED: The key was only valid for a certain time and has expired.
        *
+       * These are validation codes, the HTTP status will be 200.
+       *
        * @enum {string}
        */
       code: "VALID" | "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | "INSUFFICIENT_PERMISSIONS" | "EXPIRED";
@@ -562,6 +586,21 @@ interface components {
        * @example sk_1234
        */
       key: string;
+      /**
+       * @description Tags do not influence the outcome of a verification.
+       *                 They can be added to filter or aggregate historical verification data for your analytics needs.
+       *
+       *                 To unkey, a tag is simply a string, we don't enforce any schema but leave that up to you.
+       *                 The only exception is that each tag must be between 1 and 128 characters long.
+       *
+       *                 A typical setup would be to add key-value pairs of resources or locations, that you need later when querying.
+       *
+       * @example [
+       *   "path=/v1/users/123",
+       *   "region=us-east-1"
+       * ]
+       */
+      tags?: string[];
       /** @description Perform RBAC checks */
       authorization?: {
         permissions?: components["schemas"]["PermissionQuery"];
@@ -666,8 +705,6 @@ interface operations {
               ratelimit: string;
               /** @description The name of the connected usagelimit service */
               usagelimit: string;
-              /** @description The name of the connected analytics service */
-              analytics: string;
             };
           };
         };
@@ -774,6 +811,123 @@ interface operations {
       };
     };
   };
+  whoami: {
+    requestBody: {
+      content: {
+        "application/json": {
+          /**
+           * @description The actual key to fetch
+           * @example sk_123
+           */
+          key: string;
+        };
+      };
+    };
+    responses: {
+      /** @description The configuration for a single key */
+      200: {
+        content: {
+          "application/json": {
+            /**
+             * @description The ID of the key
+             * @example key_123
+             */
+            id: string;
+            /**
+             * @description The name of the key
+             * @example API Key 1
+             */
+            name?: string;
+            /**
+             * @description The remaining number of requests for the key
+             * @example 1000
+             */
+            remaining?: number;
+            /** @description The identity object associated with the key */
+            identity?: {
+              /**
+               * @description The identity ID associated with the key
+               * @example id_123
+               */
+              id: string;
+              /**
+               * @description The external identity ID associated with the key
+               * @example ext123
+               */
+              externalId: string;
+            };
+            /**
+             * @description Metadata associated with the key
+             * @example {
+             *   "role": "admin",
+             *   "plan": "premium"
+             * }
+             */
+            meta?: {
+              [key: string]: unknown;
+            };
+            /**
+             * @description The timestamp in milliseconds when the key was created
+             * @example 1620000000000
+             */
+            createdAt: number;
+            /**
+             * @description Whether the key is enabled
+             * @example true
+             */
+            enabled: boolean;
+            /**
+             * @description The environment the key is associated with
+             * @example production
+             */
+            environment?: string;
+          };
+        };
+      };
+      /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
+      400: {
+        content: {
+          "application/json": components["schemas"]["ErrBadRequest"];
+        };
+      };
+      /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
+      401: {
+        content: {
+          "application/json": components["schemas"]["ErrUnauthorized"];
+        };
+      };
+      /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
+      403: {
+        content: {
+          "application/json": components["schemas"]["ErrForbidden"];
+        };
+      };
+      /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
+      404: {
+        content: {
+          "application/json": components["schemas"]["ErrNotFound"];
+        };
+      };
+      /** @description This response is sent when a request conflicts with the current state of the server. */
+      409: {
+        content: {
+          "application/json": components["schemas"]["ErrConflict"];
+        };
+      };
+      /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
+      429: {
+        content: {
+          "application/json": components["schemas"]["ErrTooManyRequests"];
+        };
+      };
+      /** @description The server has encountered a situation it does not know how to handle. */
+      500: {
+        content: {
+          "application/json": components["schemas"]["ErrInternalServerError"];
+        };
+      };
+    };
+  };
   deleteKey: {
     requestBody: {
       content: {
@@ -915,8 +1069,9 @@ interface operations {
           /**
            * @description Unkey enables you to refill verifications for each key at regular intervals.
            * @example {
-           *   "interval": "daily",
-           *   "amount": 100
+           *   "interval": "monthly",
+           *   "amount": 100,
+           *   "refillDay": 15
            * }
            */
           refill?: {
@@ -927,6 +1082,11 @@ interface operations {
             interval: "daily" | "monthly";
             /** @description The number of verifications to refill for each occurrence is determined individually for each key. */
             amount: number;
+            /**
+             * @description The day of the month, when we will refill the remaining verifications. To refill on the 15th of each month, set 'refillDay': 15.
+             *                     If the day does not exist, for example you specified the 30th and it's february, we will refill them on the last day of the month instead.
+             */
+            refillDay?: number;
           };
           /**
            * @description Unkey comes with per-key fixed-window ratelimiting out of the box.
@@ -978,7 +1138,7 @@ interface operations {
            *
            * In addition to storing the key's hash, recoverable keys are stored in an encrypted vault, allowing you to retrieve and display the plaintext later.
            *
-           * https://www.unkey.com/docs/security/recovering-keys for more information.
+           * [https://www.unkey.com/docs/security/recovering-keys](https://www.unkey.com/docs/security/recovering-keys) for more information.
            * @default false
            */
           recoverable?: boolean;
@@ -1223,6 +1383,8 @@ interface operations {
             interval: "daily" | "monthly";
             /** @description The amount of verifications to refill for each occurrence is determined individually for each key. */
             amount: number;
+            /** @description The day verifications will refill each month, when interval is set to 'monthly' */
+            refillDay?: number;
           }) | null;
           /**
            * @description Set if key is enabled or disabled. If disabled, the key cannot be used to verify.
@@ -2196,7 +2358,7 @@ interface operations {
              * @example eyJrZXkiOiJrZXlfMTIzNCJ9
              */
             cursor?: string;
-            /** @description The total number of keys for this api */
+            /** @description The total number of keys for this api. This is an approximation and may lag behind up to 5 minutes. */
             total: number;
           };
         };
@@ -2527,6 +2689,313 @@ interface operations {
       };
     };
   };
+  "ratelimit.setOverride": {
+    requestBody: {
+      content: {
+        "application/json": {
+          /**
+           * @description The id of the namespace. Either namespaceId or namespaceName must be provided
+           * @example rlns_1234
+           */
+          namespaceId?: string;
+          /**
+           * @description 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
+           * @example email.outbound
+           */
+          namespaceName?: string;
+          /**
+           * @description 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
+           * @example user_123
+           */
+          identifier: string;
+          /**
+           * @description How many requests may pass in a given window.
+           * @example 10
+           */
+          limit: number;
+          /**
+           * @description The window duration in milliseconds
+           * @example 60000
+           */
+          duration: number;
+          /**
+           * @description Async will return a response immediately, lowering latency at the cost of accuracy.
+           * @default false
+           */
+          async?: boolean;
+        };
+      };
+    };
+    responses: {
+      /** @description Sucessfully created a ratelimit override */
+      200: {
+        content: {
+          "application/json": {
+            /**
+             * @description The id of the override. This is used internally
+             * @example over_123
+             */
+            overrideId: string;
+          };
+        };
+      };
+      /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
+      400: {
+        content: {
+          "application/json": components["schemas"]["ErrBadRequest"];
+        };
+      };
+      /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
+      401: {
+        content: {
+          "application/json": components["schemas"]["ErrUnauthorized"];
+        };
+      };
+      /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
+      403: {
+        content: {
+          "application/json": components["schemas"]["ErrForbidden"];
+        };
+      };
+      /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
+      404: {
+        content: {
+          "application/json": components["schemas"]["ErrNotFound"];
+        };
+      };
+      /** @description This response is sent when a request conflicts with the current state of the server. */
+      409: {
+        content: {
+          "application/json": components["schemas"]["ErrConflict"];
+        };
+      };
+      /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
+      429: {
+        content: {
+          "application/json": components["schemas"]["ErrTooManyRequests"];
+        };
+      };
+      /** @description The server has encountered a situation it does not know how to handle. */
+      500: {
+        content: {
+          "application/json": components["schemas"]["ErrInternalServerError"];
+        };
+      };
+    };
+  };
+  listOverrides: {
+    parameters: {
+      query?: {
+        namespaceId?: string;
+        namespaceName?: string;
+        limit?: number;
+        cursor?: string;
+      };
+    };
+    responses: {
+      /** @description List of overrides for the given namespace. */
+      200: {
+        content: {
+          "application/json": {
+            overrides: ({
+                id: string;
+                identifier: string;
+                limit: number;
+                duration: number;
+                async?: boolean | null;
+              })[];
+            /**
+             * @description The cursor to use for the next page of results, if no cursor is returned, there are no more results
+             * @example eyJrZXkiOiJrZXlfMTIzNCJ9
+             */
+            cursor?: string;
+            /** @description The total number of overrides for the namespace */
+            total: number;
+          };
+        };
+      };
+      /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
+      400: {
+        content: {
+          "application/json": components["schemas"]["ErrBadRequest"];
+        };
+      };
+      /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
+      401: {
+        content: {
+          "application/json": components["schemas"]["ErrUnauthorized"];
+        };
+      };
+      /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
+      403: {
+        content: {
+          "application/json": components["schemas"]["ErrForbidden"];
+        };
+      };
+      /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
+      404: {
+        content: {
+          "application/json": components["schemas"]["ErrNotFound"];
+        };
+      };
+      /** @description This response is sent when a request conflicts with the current state of the server. */
+      409: {
+        content: {
+          "application/json": components["schemas"]["ErrConflict"];
+        };
+      };
+      /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
+      429: {
+        content: {
+          "application/json": components["schemas"]["ErrTooManyRequests"];
+        };
+      };
+      /** @description The server has encountered a situation it does not know how to handle. */
+      500: {
+        content: {
+          "application/json": components["schemas"]["ErrInternalServerError"];
+        };
+      };
+    };
+  };
+  deleteOverride: {
+    requestBody: {
+      content: {
+        "application/json": {
+          /**
+           * @description The id of the namespace. Either namespaceId or namespaceName must be provided
+           * @example rlns_1234
+           */
+          namespaceId?: string;
+          /**
+           * @description The name of the namespace. Namespaces group different limits together for better analytics. You might have a namespace for your public API and one for internal tRPC routes.
+           * @example email.outbound
+           */
+          namespaceName?: string;
+          /**
+           * @description 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
+           * @example user_123
+           */
+          identifier: string;
+        };
+      };
+    };
+    responses: {
+      /** @description Successfully deleted a ratelimit override */
+      200: {
+        content: {
+          "application/json": Record<string, never>;
+        };
+      };
+      /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
+      400: {
+        content: {
+          "application/json": components["schemas"]["ErrBadRequest"];
+        };
+      };
+      /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
+      401: {
+        content: {
+          "application/json": components["schemas"]["ErrUnauthorized"];
+        };
+      };
+      /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
+      403: {
+        content: {
+          "application/json": components["schemas"]["ErrForbidden"];
+        };
+      };
+      /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
+      404: {
+        content: {
+          "application/json": components["schemas"]["ErrNotFound"];
+        };
+      };
+      /** @description This response is sent when a request conflicts with the current state of the server. */
+      409: {
+        content: {
+          "application/json": components["schemas"]["ErrConflict"];
+        };
+      };
+      /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
+      429: {
+        content: {
+          "application/json": components["schemas"]["ErrTooManyRequests"];
+        };
+      };
+      /** @description The server has encountered a situation it does not know how to handle. */
+      500: {
+        content: {
+          "application/json": components["schemas"]["ErrInternalServerError"];
+        };
+      };
+    };
+  };
+  getOverride: {
+    parameters: {
+      query: {
+        namespaceId?: string;
+        namespaceName?: string;
+        identifier: string;
+      };
+    };
+    responses: {
+      /** @description Details of the override for the given identifier */
+      200: {
+        content: {
+          "application/json": {
+            id: string;
+            identifier: string;
+            limit: number;
+            duration: number;
+            async?: boolean | null;
+          };
+        };
+      };
+      /** @description The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). */
+      400: {
+        content: {
+          "application/json": components["schemas"]["ErrBadRequest"];
+        };
+      };
+      /** @description Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response. */
+      401: {
+        content: {
+          "application/json": components["schemas"]["ErrUnauthorized"];
+        };
+      };
+      /** @description The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server. */
+      403: {
+        content: {
+          "application/json": components["schemas"]["ErrForbidden"];
+        };
+      };
+      /** @description The server cannot find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. */
+      404: {
+        content: {
+          "application/json": components["schemas"]["ErrNotFound"];
+        };
+      };
+      /** @description This response is sent when a request conflicts with the current state of the server. */
+      409: {
+        content: {
+          "application/json": components["schemas"]["ErrConflict"];
+        };
+      };
+      /** @description The user has sent too many requests in a given amount of time ("rate limiting") */
+      429: {
+        content: {
+          "application/json": components["schemas"]["ErrTooManyRequests"];
+        };
+      };
+      /** @description The server has encountered a situation it does not know how to handle. */
+      500: {
+        content: {
+          "application/json": components["schemas"]["ErrInternalServerError"];
+        };
+      };
+    };
+  };
   "v1.migrations.createKeys": {
     requestBody: {
       content: {
@@ -2623,6 +3092,8 @@ interface operations {
               interval: "daily" | "monthly";
               /** @description The number of verifications to refill for each occurrence is determined individually for each key. */
               amount: number;
+              /** @description The day verifications will refill each month, when interval is set to 'monthly' */
+              refillDay?: number;
             };
             /**
              * @description Unkey comes with per-key ratelimiting out of the box.
@@ -2835,6 +3306,8 @@ interface operations {
                 interval: "daily" | "monthly";
                 /** @description The number of verifications to refill for each occurrence is determined individually for each key. */
                 amount: number;
+                /** @description The day verifications will refill each month, when interval is set to 'monthly' */
+                refillDay?: number;
               };
               /**
                * @description Unkey comes with per-key fixed-window ratelimiting out of the box.
@@ -3513,6 +3986,8 @@ interface operations {
            * This usually comes from your authentication provider and could be a userId, organisationId or even an email.
            * It does not matter what you use, as long as it uniquely identifies something in your application.
            *
+           * `externalId`s are unique across your workspace and therefore a `PRECONDITION_FAILED` error is returned when you try to create duplicates.
+           *
            * @example user_123
            */
           externalId: string;
@@ -4168,7 +4643,7 @@ interface operations {
              */
             valid: boolean;
             /**
-             * @description The name of the key, give keys a name to easily identifiy their purpose
+             * @description The name of the key, give keys a name to easily identify their purpose
              * @example Customer X
              */
             name?: string;
@@ -4427,7 +4902,12 @@ type Result<R> = {
     error?: never;
 } | {
     result?: never;
-    error: ErrorResponse["error"];
+    error: {
+        code: ErrorResponse["error"]["code"];
+        message: ErrorResponse["error"]["message"];
+        docs: ErrorResponse["error"]["docs"];
+        requestId: string;
+    };
 };
 declare class Unkey {
     readonly baseUrl: string;
@@ -4462,6 +4942,10 @@ declare class Unkey {
     };
     get ratelimits(): {
         limit: (req: paths["/v1/ratelimits.limit"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/ratelimits.limit"]["post"]["responses"]["200"]["content"]["application/json"]>>;
+        getOverride: (req: paths["/v1/ratelimits.getOverride"]["get"]["parameters"]["query"]) => Promise<Result<paths["/v1/ratelimits.getOverride"]["get"]["responses"]["200"]["content"]["application/json"]>>;
+        listOverrides: (req: paths["/v1/ratelimits.listOverrides"]["get"]["parameters"]["query"]) => Promise<Result<paths["/v1/ratelimits.listOverrides"]["get"]["responses"]["200"]["content"]["application/json"]>>;
+        setOverride: (req: paths["/v1/ratelimits.setOverride"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/ratelimits.setOverride"]["post"]["responses"]["200"]["content"]["application/json"]>>;
+        deleteOverride: (req: paths["/v1/ratelimits.deleteOverride"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/ratelimits.deleteOverride"]["post"]["responses"]["200"]["content"]["application/json"]>>;
     };
     get identities(): {
         create: (req: paths["/v1/identities.createIdentity"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/identities.createIdentity"]["post"]["responses"]["200"]["content"]["application/json"]>>;
@@ -4502,7 +4986,12 @@ declare function verifyKey(req: string | {
     apiId: string;
 }): Promise<{
     result?: never;
-    error: ErrorResponse["error"];
+    error: {
+        code: ErrorResponse["error"]["code"];
+        message: ErrorResponse["error"]["message"];
+        docs: ErrorResponse["error"]["docs"];
+        requestId: string;
+    };
 } | {
     result: {
         keyId?: string;