@unkey/api 0.16.0 → 0.18.0

package/dist/index.d.mts

@@ -1,3 +1,6 @@
+import { PermissionQuery } from '@unkey/rbac';
+export { Flatten, and, or } from '@unkey/rbac';
+
 /**
  * This file was auto-generated by openapi-typescript.
  * Do not make direct changes to the file.
@@ -248,6 +251,14 @@ interface paths {
             meta?: {
               [key: string]: unknown;
             };
+            /**
+             * @description A list of roles that this key should have. If the role does not exist, an error is thrown
+             * @example [
+             *   "admin",
+             *   "finance"
+             * ]
+             */
+            roles?: string[];
             /**
              * @description You can auto expire keys by providing a unix timestamp in milliseconds. Once Keys expire they will automatically be disabled and are no longer valid unless you enable them again.
              * @example 1623869797161
@@ -373,110 +384,14 @@ interface paths {
     post: {
       requestBody: {
         content: {
-          "application/json": {
-            /**
-             * @description The id of the api where the key belongs to. This is optional for now but will be required soon.
-             * The key will be verified against the api's configuration. If the key does not belong to the api, the verification will fail.
-             * @example api_1234
-             */
-            apiId?: string;
-            /**
-             * @description The key to verify
-             * @example sk_1234
-             */
-            key: string;
-          };
+          "application/json": components["schemas"]["V1KeysVerifyKeyRequest"];
         };
       };
       responses: {
         /** @description The verification result */
         200: {
           content: {
-            "application/json": {
-              /**
-               * @description The id of the key
-               * @example key_1234
-               */
-              keyId?: string;
-              /**
-               * @description Whether the key is valid or not.
-               * A key could be invalid for a number of reasons, for example if it has expired, has no more verifications left or if it has been deleted.
-               * @example true
-               */
-              valid: boolean;
-              /**
-               * @description The name of the key, give keys a name to easily identifiy their purpose
-               * @example Customer X
-               */
-              name?: string;
-              /**
-               * @description The id of the tenant associated with this key. Use whatever reference you have in your system to identify the tenant. When verifying the key, we will send this field back to you, so you know who is accessing your API.
-               * @example user_123
-               */
-              ownerId?: string;
-              /**
-               * @description Any additional metadata you want to store with the key
-               * @example {
-               *   "roles": [
-               *     "admin",
-               *     "user"
-               *   ],
-               *   "stripeCustomerId": "cus_1234"
-               * }
-               */
-              meta?: {
-                [key: string]: unknown;
-              };
-              /**
-               * @description The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring.
-               * @example 123
-               */
-              expires?: number;
-              /**
-               * @description The ratelimit configuration for this key. If this field is null or undefined, the key has no ratelimit.
-               * @example {
-               *   "limit": 10,
-               *   "remaining": 9,
-               *   "reset": 3600000
-               * }
-               */
-              ratelimit?: {
-                /**
-                 * @description Maximum number of requests that can be made inside a window
-                 * @example 10
-                 */
-                limit: number;
-                /**
-                 * @description Remaining requests after this verification
-                 * @example 9
-                 */
-                remaining: number;
-                /**
-                 * @description Unix timestamp in milliseconds when the ratelimit will reset
-                 * @example 3600000
-                 */
-                reset: number;
-              };
-              /**
-               * @description The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit.
-               * @example 1000
-               */
-              remaining?: number;
-              /**
-               * @description If the key is invalid this field will be set to the reason why it is invalid.
-               * Possible values are:
-               * - NOT_FOUND: the key does not exist or has expired
-               * - FORBIDDEN: the key is not allowed to access the api
-               * - USAGE_EXCEEDED: the key has exceeded its request limit
-               * - RATE_LIMITED: the key has been ratelimited
-               * - UNAUTHORIZED: the key is not authorized
-               * - DISABLED: the key is disabled
-               * @enum {string}
-               */
-              code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED";
-              /** @description Sets the key to be enabled or disabled. Disabled keys will not verify. */
-              enabled?: boolean;
-            };
+            "application/json": components["schemas"]["V1KeysVerifyKeyResponse"];
           };
         };
         /** @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). */
@@ -832,92 +747,6 @@ interface paths {
       };
     };
   };
-  "/vx/keys.getVerifications": {
-    get: {
-      parameters: {
-        query?: {
-          keyId?: string;
-          ownerId?: string;
-          start?: number | null;
-          end?: number | null;
-          granularity?: "day";
-        };
-      };
-      responses: {
-        /** @description The configuration for a single key */
-        200: {
-          content: {
-            "application/json": {
-              verifications: {
-                  /**
-                   * @description The timestamp of the usage data
-                   * @example 1620000000000
-                   */
-                  time: number;
-                  /**
-                   * @description The number of successful requests
-                   * @example 100
-                   */
-                  success: number;
-                  /**
-                   * @description The number of requests that were rate limited
-                   * @example 10
-                   */
-                  rateLimited: number;
-                  /**
-                   * @description The number of requests that exceeded the usage limit
-                   * @example 0
-                   */
-                  usageExceeded: 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"];
-          };
-        };
-      };
-    };
-  };
   "/v1/apis.getApi": {
     get: {
       parameters: {
@@ -1203,9 +1032,6 @@ interface paths {
   "/v1/keys/{keyId}": {
     put: {
       parameters: {
-        header: {
-          authorization: string;
-        };
         path: {
           keyId: string;
         };
@@ -1323,129 +1149,8 @@ interface paths {
       };
     };
   };
-  "/v1/keys/:keyId": {
-    get: {
-      parameters: {
-        header: {
-          authorization: string;
-        };
-      };
-      responses: {
-        /** @description The configuration for a single key */
-        200: {
-          content: {
-            "application/json": components["schemas"]["Key"];
-          };
-        };
-        /** @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"];
-          };
-        };
-      };
-    };
-    delete: {
-      parameters: {
-        header: {
-          authorization: string;
-        };
-      };
-      responses: {
-        /** @description The key was successfully revoked, it may take up to 30s for this to take effect in all regions */
-        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"];
-          };
-        };
-      };
-    };
-  };
   "/v1/keys": {
     post: {
-      parameters: {
-        header: {
-          authorization: string;
-        };
-      };
       requestBody: {
         content: {
           "application/json": {
@@ -1697,11 +1402,12 @@ interface paths {
                * - FORBIDDEN: the key is not allowed to access the api
                * - USAGE_EXCEEDED: the key has exceeded its request limit
                * - RATE_LIMITED: the key has been ratelimited,
+               * - INSUFFICIENT_PERMISSIONS: you do not have the required permissions to perform this action
                *
                * @example NOT_FOUND
                * @enum {string}
                */
-              code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED";
+              code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | "INSUFFICIENT_PERMISSIONS";
             };
           };
         };
@@ -1750,6 +1456,60 @@ interface paths {
       };
     };
   };
+  "/v1/keys/:keyId": {
+    delete: {
+      responses: {
+        /** @description The key was successfully revoked, it may take up to 30s for this to take effect in all regions */
+        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"];
+          };
+        };
+      };
+    };
+  };
   "/v1/apis": {
     post: {
       requestBody: {
@@ -1897,9 +1657,6 @@ interface paths {
     };
     delete: {
       parameters: {
-        header: {
-          authorization: string;
-        };
         path: {
           apiId: string;
         };
@@ -2294,12 +2051,154 @@ interface components {
         /** @description Determines the speed at which tokens are refilled, in milliseconds. */
         refillInterval: number;
       };
+      /**
+       * @description All roles this key belongs to
+       * @example [
+       *   "admin",
+       *   "finance"
+       * ]
+       */
+      roles?: string[];
+      /**
+       * @description All permissions this key has
+       * @example [
+       *   "domain.dns.create_record",
+       *   "finance.read_receipt"
+       * ]
+       */
+      permissions?: string[];
       /**
        * @description Sets if key is enabled or disabled. Disabled keys are not valid.
        * @example true
        */
       enabled?: boolean;
     };
+    V1KeysVerifyKeyResponse: {
+      /**
+       * @description The id of the key
+       * @example key_1234
+       */
+      keyId?: string;
+      /**
+       * @description Whether the key is valid or not.
+       * A key could be invalid for a number of reasons, for example if it has expired, has no more verifications left or if it has been deleted.
+       * @example true
+       */
+      valid: boolean;
+      /**
+       * @description The name of the key, give keys a name to easily identifiy their purpose
+       * @example Customer X
+       */
+      name?: string;
+      /**
+       * @description The id of the tenant associated with this key. Use whatever reference you have in your system to identify the tenant. When verifying the key, we will send this field back to you, so you know who is accessing your API.
+       * @example user_123
+       */
+      ownerId?: string;
+      /**
+       * @description Any additional metadata you want to store with the key
+       * @example {
+       *   "roles": [
+       *     "admin",
+       *     "user"
+       *   ],
+       *   "stripeCustomerId": "cus_1234"
+       * }
+       */
+      meta?: {
+        [key: string]: unknown;
+      };
+      /**
+       * @description The unix timestamp in milliseconds when the key will expire. If this field is null or undefined, the key is not expiring.
+       * @example 123
+       */
+      expires?: number;
+      /**
+       * @description The ratelimit configuration for this key. If this field is null or undefined, the key has no ratelimit.
+       * @example {
+       *   "limit": 10,
+       *   "remaining": 9,
+       *   "reset": 3600000
+       * }
+       */
+      ratelimit?: {
+        /**
+         * @description Maximum number of requests that can be made inside a window
+         * @example 10
+         */
+        limit: number;
+        /**
+         * @description Remaining requests after this verification
+         * @example 9
+         */
+        remaining: number;
+        /**
+         * @description Unix timestamp in milliseconds when the ratelimit will reset
+         * @example 3600000
+         */
+        reset: number;
+      };
+      /**
+       * @description The number of requests that can be made with this key before it becomes invalid. If this field is null or undefined, the key has no request limit.
+       * @example 1000
+       */
+      remaining?: number;
+      /**
+       * @description If the key is invalid this field will be set to the reason why it is invalid.
+       * Possible values are:
+       * - NOT_FOUND: the key does not exist or has expired
+       * - FORBIDDEN: the key is not allowed to access the api
+       * - USAGE_EXCEEDED: the key has exceeded its request limit
+       * - RATE_LIMITED: the key has been ratelimited
+       * - UNAUTHORIZED: the key is not authorized
+       * - DISABLED: the key is disabled
+       * - INSUFFICIENT_PERMISSIONS: you do not have the required permissions to perform this action
+       *
+       * @enum {string}
+       */
+      code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | "INSUFFICIENT_PERMISSIONS";
+      /** @description Sets the key to be enabled or disabled. Disabled keys will not verify. */
+      enabled?: boolean;
+      /**
+       * @description A list of all the permissions this key is connected to.
+       * @example [
+       *   "dns.record.update",
+       *   "dns.record.delete"
+       * ]
+       */
+      permissions?: string[];
+    };
+    V1KeysVerifyKeyRequest: {
+      /**
+       * @description The id of the api where the key belongs to. This is optional for now but will be required soon.
+       * The key will be verified against the api's configuration. If the key does not belong to the api, the verification will fail.
+       * @example api_1234
+       */
+      apiId?: string;
+      /**
+       * @description The key to verify
+       * @example sk_1234
+       */
+      key: string;
+      /** @description Perform RBAC checks */
+      authorization?: {
+        /**
+         * @description A query for which permissions you require
+         * @example {
+         *   "or": [
+         *     {
+         *       "and": [
+         *         "dns.record.read",
+         *         "dns.record.update"
+         *       ]
+         *     },
+         *     "admin"
+         *   ]
+         * }
+         */
+        permissions: Record<string, never>;
+      };
+    };
   };
   responses: never;
   parameters: {
@@ -2333,6 +2232,14 @@ type UnkeyOptions = ({
      * @default https://api.unkey.dev
      */
     baseUrl?: string;
+    /**
+     *
+     * By default telemetry data is enabled, and sends:
+     * runtime (Node.js / Edge)
+     * platform (Node.js / Vercel / AWS)
+     * SDK version
+     */
+    disableTelemetry?: boolean;
     /**
      * Retry on network errors
      */
@@ -2363,7 +2270,7 @@ type UnkeyOptions = ({
      *
      * You can leave this blank unless you are building a wrapper around this SDK.
      */
-    wrapperSdkVersion?: `v${string}`;
+    wrapperSdkVersion?: string;
 };
 type Result<R> = {
     result: R;
@@ -2376,17 +2283,28 @@ declare class Unkey {
     readonly baseUrl: string;
     private readonly rootKey;
     private readonly cache?;
-    private readonly sdkVersions;
+    private readonly telemetry?;
     readonly retry: {
         attempts: number;
         backoff: (retryCount: number) => number;
     };
     constructor(opts: UnkeyOptions);
+    private getHeaders;
     private fetch;
     get keys(): {
         create: (req: paths["/v1/keys.createKey"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.createKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
         update: (req: paths["/v1/keys.updateKey"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.updateKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
-        verify: (req: paths["/v1/keys.verifyKey"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.verifyKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
+        verify: <TPermission extends string = string>(req: Omit<{
+            apiId?: string | undefined;
+            key: string;
+            authorization?: {
+                permissions: Record<string, never>;
+            } | undefined;
+        }, "authorization"> & {
+            authorization?: {
+                permissions: PermissionQuery<TPermission>;
+            } | undefined;
+        }) => Promise<Result<paths["/v1/keys.verifyKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
         delete: (req: paths["/v1/keys.deleteKey"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.deleteKey"]["post"]["responses"]["200"]["content"]["application/json"]>>;
         updateRemaining: (req: paths["/v1/keys.updateRemaining"]["post"]["requestBody"]["content"]["application/json"]) => Promise<Result<paths["/v1/keys.updateRemaining"]["post"]["responses"]["200"]["content"]["application/json"]>>;
         get: (req: paths["/v1/keys.getKey"]["get"]["parameters"]["query"]) => Promise<Result<paths["/v1/keys.getKey"]["get"]["responses"]["200"]["content"]["application/json"]>>;
@@ -2448,8 +2366,9 @@ declare function verifyKey(req: string | {
             reset: number;
         } | undefined;
         remaining?: number | undefined;
-        code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | undefined;
+        code?: "NOT_FOUND" | "FORBIDDEN" | "USAGE_EXCEEDED" | "RATE_LIMITED" | "UNAUTHORIZED" | "DISABLED" | "INSUFFICIENT_PERMISSIONS" | undefined;
         enabled?: boolean | undefined;
+        permissions?: string[] | undefined;
     };
     error?: undefined;
 }>;