@unkey/api 2.0.0-alpha.7 → 2.0.0

package/src/lib/matchers.ts

@@ -3,11 +3,10 @@
  */
 
 import { APIError } from "../models/errors/apierror.js";
-import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
-import { Result } from "../types/fp.js";
+import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
+import { ERR, OK, Result } from "../types/fp.js";
 import { matchResponse, matchStatusCode, StatusCodePredicate } from "./http.js";
 import { isPlainObject } from "./is-plain-object.js";
-import { safeParse } from "./schemas.js";
 
 export type Encoding =
   | "jsonl"
@@ -176,17 +175,19 @@ export type MatchedError<Matchers> = Matchers extends Matcher<any, infer E>[]
   : never;
 export type MatchFunc<T, E> = (
   response: Response,
+  request: Request,
   options?: { resultKey?: string; extraFields?: Record<string, unknown> },
 ) => Promise<[result: Result<T, E>, raw: unknown]>;
 
 export function match<T, E>(
   ...matchers: Array<Matcher<T, E>>
-): MatchFunc<T, E | APIError | SDKValidationError> {
+): MatchFunc<T, E | APIError | ResponseValidationError> {
   return async function matchFunc(
     response: Response,
+    request: Request,
     options?: { resultKey?: string; extraFields?: Record<string, unknown> },
   ): Promise<
-    [result: Result<T, E | APIError | SDKValidationError>, raw: unknown]
+    [result: Result<T, E | APIError | ResponseValidationError>, raw: unknown]
   > {
     let raw: unknown;
     let matcher: Matcher<T, E> | undefined;
@@ -205,21 +206,22 @@ export function match<T, E>(
     }
 
     if (!matcher) {
-      const responseBody = await response.text();
       return [{
         ok: false,
-        error: new APIError(
-          "Unexpected API response status or content-type",
+        error: new APIError("Unexpected Status or Content-Type", {
           response,
-          responseBody,
-        ),
-      }, responseBody];
+          request,
+          body: await response.text().catch(() => ""),
+        }),
+      }, raw];
     }
 
     const encoding = matcher.enc;
+    let body = "";
     switch (encoding) {
       case "json":
-        raw = await response.json();
+        body = await response.text();
+        raw = JSON.parse(body);
         break;
       case "jsonl":
         raw = response.body;
@@ -231,16 +233,19 @@ export function match<T, E>(
         raw = response.body;
         break;
       case "text":
-        raw = await response.text();
+        body = await response.text();
+        raw = body;
         break;
       case "sse":
         raw = response.body;
         break;
       case "nil":
-        raw = await discardResponseBody(response);
+        body = await response.text();
+        raw = undefined;
         break;
       case "fail":
-        raw = await response.text();
+        body = await response.text();
+        raw = body;
         break;
       default:
         encoding satisfies never;
@@ -250,11 +255,7 @@ export function match<T, E>(
     if (matcher.enc === "fail") {
       return [{
         ok: false,
-        error: new APIError(
-          "API error occurred",
-          response,
-          typeof raw === "string" ? raw : "",
-        ),
+        error: new APIError("API error occurred", { request, response, body }),
       }, raw];
     }
 
@@ -266,6 +267,9 @@ export function match<T, E>(
         ...options?.extraFields,
         ...(matcher.hdrs ? { Headers: unpackHeaders(response.headers) } : null),
         ...(isPlainObject(raw) ? raw : null),
+        request$: request,
+        response$: response,
+        body$: body,
       };
     } else if (resultKey) {
       data = {
@@ -284,18 +288,20 @@ export function match<T, E>(
     }
 
     if ("err" in matcher) {
-      const result = safeParse(
+      const result = safeParseResponse(
         data,
         (v: unknown) => matcher.schema.parse(v),
         "Response validation failed",
+        { request, response, body },
       );
       return [result.ok ? { ok: false, error: result.value } : result, raw];
     } else {
       return [
-        safeParse(
+        safeParseResponse(
           data,
           (v: unknown) => matcher.schema.parse(v),
           "Response validation failed",
+          { request, response, body },
         ),
         raw,
       ];
@@ -318,25 +324,22 @@ export function unpackHeaders(headers: Headers): Record<string, string[]> {
   return out;
 }
 
-/**
- * Discards the response body to free up resources.
- *
- * To learn why this is need, see the undici docs:
- * https://undici.nodejs.org/#/?id=garbage-collection
- */
-export async function discardResponseBody(res: Response) {
-  const reader = res.body?.getReader();
-  if (reader == null) {
-    return;
-  }
-
+function safeParseResponse<Inp, Out>(
+  rawValue: Inp,
+  fn: (value: Inp) => Out,
+  errorMessage: string,
+  httpMeta: { response: Response; request: Request; body: string },
+): Result<Out, ResponseValidationError> {
   try {
-    let done = false;
-    while (!done) {
-      const res = await reader.read();
-      done = res.done;
-    }
-  } finally {
-    reader.releaseLock();
+    return OK(fn(rawValue));
+  } catch (err) {
+    return ERR(
+      new ResponseValidationError(errorMessage, {
+        cause: err,
+        rawValue,
+        rawMessage: errorMessage,
+        ...httpMeta,
+      }),
+    );
   }
 }

package/src/lib/sdks.ts

@@ -47,12 +47,14 @@ export type RequestOptions = {
    */
   serverURL?: string | URL;
   /**
+   * @deprecated `fetchOptions` has been flattened into `RequestOptions`.
+   *
    * Sets various request options on the `fetch` call made by an SDK method.
    *
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options|Request}
    */
   fetchOptions?: Omit<RequestInit, "method" | "body">;
-};
+} & Omit<RequestInit, "method" | "body">;
 
 type RequestConfig = {
   method: string;
@@ -63,6 +65,7 @@ type RequestConfig = {
   headers?: HeadersInit;
   security?: SecurityState | null;
   uaHeader?: string;
+  userAgent?: string | undefined;
   timeoutMs?: number;
 };
 
@@ -94,19 +97,21 @@ export class ClientSDK {
     } else {
       this.#hooks = new SDKHooks();
     }
-    this._options = { ...options, hooks: this.#hooks };
-
     const url = serverURLFromOptions(options);
     if (url) {
       url.pathname = url.pathname.replace(/\/+$/, "") + "/";
     }
+
     const { baseURL, client } = this.#hooks.sdkInit({
       baseURL: url,
       client: options.httpClient || new HTTPClient(),
     });
     this._baseURL = baseURL;
     this.#httpClient = client;
-    this.#logger = options.debugLogger;
+
+    this._options = { ...options, hooks: this.#hooks };
+
+    this.#logger = this._options.debugLogger;
     if (!this.#logger && env().UNKEY_DEBUG) {
       this.#logger = console;
     }
@@ -172,7 +177,9 @@ export class ClientSDK {
     cookie = cookie.startsWith("; ") ? cookie.slice(2) : cookie;
     headers.set("cookie", cookie);
 
-    const userHeaders = new Headers(options?.fetchOptions?.headers);
+    const userHeaders = new Headers(
+      options?.headers ?? options?.fetchOptions?.headers,
+    );
     for (const [k, v] of userHeaders) {
       headers.set(k, v);
     }
@@ -180,23 +187,22 @@ export class ClientSDK {
     // Only set user agent header in non-browser-like environments since CORS
     // policy disallows setting it in browsers e.g. Chrome throws an error.
     if (!isBrowserLike) {
-      headers.set(conf.uaHeader ?? "user-agent", SDK_METADATA.userAgent);
+      headers.set(
+        conf.uaHeader ?? "user-agent",
+        conf.userAgent ?? SDK_METADATA.userAgent,
+      );
     }
 
-    let fetchOptions = options?.fetchOptions;
+    const fetchOptions: Omit<RequestInit, "method" | "body"> = {
+      ...options?.fetchOptions,
+      ...options,
+    };
     if (!fetchOptions?.signal && conf.timeoutMs && conf.timeoutMs > 0) {
       const timeoutSignal = AbortSignal.timeout(conf.timeoutMs);
-      if (!fetchOptions) {
-        fetchOptions = { signal: timeoutSignal };
-      } else {
-        fetchOptions.signal = timeoutSignal;
-      }
+      fetchOptions.signal = timeoutSignal;
     }
 
     if (conf.body instanceof ReadableStream) {
-      if (!fetchOptions) {
-        fetchOptions = {};
-      }
       Object.assign(fetchOptions, { duplex: "half" });
     }
 

package/src/lib/security.ts

@@ -7,8 +7,8 @@ import { env } from "./env.js";
 
 type OAuth2PasswordFlow = {
   username: string;
-  password?: string | undefined;
-  clientID: string;
+  password: string;
+  clientID?: string | undefined;
   clientSecret?: string | undefined;
   tokenURL: string;
 };

package/src/mcp-server/cli/start/command.ts

@@ -6,7 +6,6 @@ import { buildCommand } from "@stricli/core";
 import { numberParser } from "@stricli/core";
 import * as z from "zod";
 import { consoleLoggerLevels } from "../../console-logger.js";
-import { mcpScopes } from "../../scopes.js";
 
 export const startCommand = buildCommand({
   loader: async () => {
@@ -37,18 +36,6 @@ export const startCommand = buildCommand({
           return z.string().parse(value);
         },
       },
-      ...(mcpScopes.length
-        ? {
-          scope: {
-            kind: "enum",
-            brief:
-              "Mount tools/resources that match given scope (repeatable flag)",
-            values: mcpScopes,
-            variadic: true,
-            optional: true,
-          },
-        }
-        : {}),
       "root-key": {
         kind: "parsed",
         brief: "Sets the rootKey auth field for the API",

package/src/mcp-server/cli/start/impl.ts

@@ -11,14 +11,12 @@ import {
   ConsoleLoggerLevel,
   createConsoleLogger,
 } from "../../console-logger.js";
-import { MCPScope } from "../../scopes.js";
 import { createMCPServer } from "../../server.js";
 
 interface StartCommandFlags {
   readonly transport: "stdio" | "sse";
   readonly port: number;
   readonly tool?: string[];
-  readonly scope?: MCPScope[];
   readonly "root-key"?: string | undefined;
   readonly "server-url"?: string;
   readonly "server-index"?: SDKOptions["serverIdx"];
@@ -49,8 +47,7 @@ async function startStdio(flags: StartCommandFlags) {
   const server = createMCPServer({
     logger,
     allowedTools: flags.tool,
-    scopes: flags.scope,
-    ...{ rootKey: flags["root-key"] },
+    ...{ rootKey: flags["root-key"] ?? "" },
     serverURL: flags["server-url"],
     serverIdx: flags["server-index"],
   });
@@ -70,8 +67,7 @@ async function startSSE(flags: StartCommandFlags) {
   const mcpServer = createMCPServer({
     logger,
     allowedTools: flags.tool,
-    scopes: flags.scope,
-    ...{ rootKey: flags["root-key"] },
+    ...{ rootKey: flags["root-key"] ?? "" },
     serverURL: flags["server-url"],
     serverIdx: flags["server-index"],
   });

package/src/mcp-server/mcp-server.ts

@@ -19,7 +19,7 @@ const routes = buildRouteMap({
 export const app = buildApplication(routes, {
   name: "mcp",
   versionInfo: {
-    currentVersion: "2.0.0-alpha.7",
+    currentVersion: "2.0.0",
   },
 });
 

package/src/mcp-server/server.ts

@@ -14,8 +14,35 @@ import {
 import { MCPScope } from "./scopes.js";
 import { createRegisterTool } from "./tools.js";
 import { tool$apisCreateApi } from "./tools/apisCreateApi.js";
+import { tool$apisDeleteApi } from "./tools/apisDeleteApi.js";
+import { tool$apisGetApi } from "./tools/apisGetApi.js";
+import { tool$apisListKeys } from "./tools/apisListKeys.js";
 import { tool$identitiesCreateIdentity } from "./tools/identitiesCreateIdentity.js";
-import { tool$livenessLiveness } from "./tools/livenessLiveness.js";
+import { tool$identitiesDeleteIdentity } from "./tools/identitiesDeleteIdentity.js";
+import { tool$identitiesGetIdentity } from "./tools/identitiesGetIdentity.js";
+import { tool$identitiesListIdentities } from "./tools/identitiesListIdentities.js";
+import { tool$identitiesUpdateIdentity } from "./tools/identitiesUpdateIdentity.js";
+import { tool$keysAddPermissions } from "./tools/keysAddPermissions.js";
+import { tool$keysAddRoles } from "./tools/keysAddRoles.js";
+import { tool$keysCreateKey } from "./tools/keysCreateKey.js";
+import { tool$keysDeleteKey } from "./tools/keysDeleteKey.js";
+import { tool$keysGetKey } from "./tools/keysGetKey.js";
+import { tool$keysRemovePermissions } from "./tools/keysRemovePermissions.js";
+import { tool$keysRemoveRoles } from "./tools/keysRemoveRoles.js";
+import { tool$keysSetPermissions } from "./tools/keysSetPermissions.js";
+import { tool$keysSetRoles } from "./tools/keysSetRoles.js";
+import { tool$keysUpdateCredits } from "./tools/keysUpdateCredits.js";
+import { tool$keysUpdateKey } from "./tools/keysUpdateKey.js";
+import { tool$keysVerifyKey } from "./tools/keysVerifyKey.js";
+import { tool$keysWhoami } from "./tools/keysWhoami.js";
+import { tool$permissionsCreatePermission } from "./tools/permissionsCreatePermission.js";
+import { tool$permissionsCreateRole } from "./tools/permissionsCreateRole.js";
+import { tool$permissionsDeletePermission } from "./tools/permissionsDeletePermission.js";
+import { tool$permissionsDeleteRole } from "./tools/permissionsDeleteRole.js";
+import { tool$permissionsGetPermission } from "./tools/permissionsGetPermission.js";
+import { tool$permissionsGetRole } from "./tools/permissionsGetRole.js";
+import { tool$permissionsListPermissions } from "./tools/permissionsListPermissions.js";
+import { tool$permissionsListRoles } from "./tools/permissionsListRoles.js";
 import { tool$ratelimitDeleteOverride } from "./tools/ratelimitDeleteOverride.js";
 import { tool$ratelimitGetOverride } from "./tools/ratelimitGetOverride.js";
 import { tool$ratelimitLimit } from "./tools/ratelimitLimit.js";
@@ -32,7 +59,7 @@ export function createMCPServer(deps: {
 }) {
   const server = new McpServer({
     name: "Unkey",
-    version: "2.0.0-alpha.7",
+    version: "2.0.0",
   });
 
   const client = new UnkeyCore({
@@ -62,14 +89,41 @@ export function createMCPServer(deps: {
   const register = { tool, resource, resourceTemplate, prompt };
   void register; // suppress unused warnings
 
-  tool(tool$ratelimitLimit);
-  tool(tool$ratelimitSetOverride);
+  tool(tool$apisCreateApi);
+  tool(tool$apisDeleteApi);
+  tool(tool$apisGetApi);
+  tool(tool$apisListKeys);
+  tool(tool$identitiesCreateIdentity);
+  tool(tool$identitiesDeleteIdentity);
+  tool(tool$identitiesGetIdentity);
+  tool(tool$identitiesListIdentities);
+  tool(tool$identitiesUpdateIdentity);
+  tool(tool$keysAddPermissions);
+  tool(tool$keysAddRoles);
+  tool(tool$keysCreateKey);
+  tool(tool$keysDeleteKey);
+  tool(tool$keysGetKey);
+  tool(tool$keysRemovePermissions);
+  tool(tool$keysRemoveRoles);
+  tool(tool$keysSetPermissions);
+  tool(tool$keysSetRoles);
+  tool(tool$keysUpdateCredits);
+  tool(tool$keysUpdateKey);
+  tool(tool$keysVerifyKey);
+  tool(tool$keysWhoami);
+  tool(tool$permissionsCreatePermission);
+  tool(tool$permissionsCreateRole);
+  tool(tool$permissionsDeletePermission);
+  tool(tool$permissionsDeleteRole);
+  tool(tool$permissionsGetPermission);
+  tool(tool$permissionsGetRole);
+  tool(tool$permissionsListPermissions);
+  tool(tool$permissionsListRoles);
+  tool(tool$ratelimitDeleteOverride);
   tool(tool$ratelimitGetOverride);
+  tool(tool$ratelimitLimit);
   tool(tool$ratelimitListOverrides);
-  tool(tool$ratelimitDeleteOverride);
-  tool(tool$identitiesCreateIdentity);
-  tool(tool$apisCreateApi);
-  tool(tool$livenessLiveness);
+  tool(tool$ratelimitSetOverride);
 
   return server;
 }

package/src/mcp-server/tools/apisCreateApi.ts

@@ -12,7 +12,19 @@ const args = {
 
 export const tool$apisCreateApi: ToolDefinition<typeof args> = {
   name: "apis-create-api",
-  description: ``,
+  description: `Create API namespace
+
+Create an API namespace for organizing keys by environment, service, or product.
+
+Use this to separate production from development keys, isolate different services, or manage multiple products. Each API gets a unique identifier and dedicated infrastructure for secure key operations.
+
+**Important**: API names must be unique within your workspace and cannot be changed after creation.
+
+**Required Permissions**
+
+Your root key must have one of the following permissions:
+- \`api.*.create_api\` (to create APIs in any workspace)
+`,
   args,
   tool: async (client, args, ctx) => {
     const [result, apiCall] = await apisCreateApi(

package/src/mcp-server/tools/apisDeleteApi.ts

@@ -0,0 +1,48 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { apisDeleteApi } from "../../funcs/apisDeleteApi.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2ApisDeleteApiRequestBody$inboundSchema,
+};
+
+export const tool$apisDeleteApi: ToolDefinition<typeof args> = {
+  name: "apis-delete-api",
+  description: `Delete API namespace
+
+Permanently delete an API namespace and immediately invalidate all associated keys.
+
+Use this for cleaning up development environments, retiring deprecated services, or removing unused resources. All keys in the namespace are immediately marked as deleted and will fail verification with \`code=NOT_FOUND\`.
+
+**Important**: This operation is immediate and permanent. Verify you have the correct API ID before deletion. If delete protection is enabled, disable it first through the dashboard or API configuration.
+
+**Required Permissions**
+
+Your root key must have one of the following permissions:
+- \`api.*.delete_api\` (to delete any API)
+- \`api.<api_id>.delete_api\` (to delete a specific API)
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await apisDeleteApi(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/apisGetApi.ts

@@ -0,0 +1,46 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { apisGetApi } from "../../funcs/apisGetApi.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2ApisGetApiRequestBody$inboundSchema,
+};
+
+export const tool$apisGetApi: ToolDefinition<typeof args> = {
+  name: "apis-get-api",
+  description: `Get API namespace
+
+Retrieve basic information about an API namespace including its ID and name.
+
+Use this to verify an API exists before performing operations, get the human-readable name when you only have the API ID, or confirm access to a specific namespace. For detailed key information, use the \`listKeys\` endpoint instead.
+
+**Required Permissions**
+
+Your root key must have one of the following permissions:
+- \`api.*.read_api\` (to read any API)
+- \`api.<api_id>.read_api\` (to read a specific API)
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await apisGetApi(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/apisListKeys.ts

@@ -0,0 +1,54 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { apisListKeys } from "../../funcs/apisListKeys.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2ApisListKeysRequestBody$inboundSchema,
+};
+
+export const tool$apisListKeys: ToolDefinition<typeof args> = {
+  name: "apis-list-keys",
+  description: `List API keys
+
+Retrieve a paginated list of API keys for dashboard and administrative interfaces.
+
+Use this to build key management dashboards, filter keys by user with \`externalId\`, or retrieve key details for administrative purposes. Each key includes status, metadata, permissions, and usage limits.
+
+**Important**: Set \`decrypt: true\` only in secure contexts to retrieve plaintext key values from recoverable keys.
+
+**Required Permissions**
+
+Your root key must have one of the following permissions for basic key listing:
+- \`api.*.read_key\` (to read keys from any API)
+- \`api.<api_id>.read_key\` (to read keys from a specific API)
+
+Additionally, you need read access to the API itself:
+- \`api.*.read_api\` or \`api.<api_id>.read_api\`
+
+Additional permission required for decrypt functionality:
+- \`api.*.decrypt_key\` or \`api.<api_id>.decrypt_key\`
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await apisListKeys(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};

package/src/mcp-server/tools/identitiesCreateIdentity.ts

@@ -12,7 +12,15 @@ const args = {
 
 export const tool$identitiesCreateIdentity: ToolDefinition<typeof args> = {
   name: "identities-create-identity",
-  description: ``,
+  description: `Create Identity
+
+Create an identity to group multiple API keys under a single entity. Identities enable shared rate limits and metadata across all associated keys.
+
+Perfect for users with multiple devices, organizations with multiple API keys, or when you need unified rate limiting across different services.
+
+> **Important**  
+> Requires \`identity.*.create_identity\` permission
+`,
   args,
   tool: async (client, args, ctx) => {
     const [result, apiCall] = await identitiesCreateIdentity(

package/src/mcp-server/tools/identitiesDeleteIdentity.ts

@@ -0,0 +1,45 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { identitiesDeleteIdentity } from "../../funcs/identitiesDeleteIdentity.js";
+import * as components from "../../models/components/index.js";
+import { formatResult, ToolDefinition } from "../tools.js";
+
+const args = {
+  request: components.V2IdentitiesDeleteIdentityRequestBody$inboundSchema,
+};
+
+export const tool$identitiesDeleteIdentity: ToolDefinition<typeof args> = {
+  name: "identities-delete-identity",
+  description: `Delete Identity
+
+Permanently delete an identity. This operation cannot be undone.
+
+Use this for data cleanup, compliance requirements, or when removing entities from your system.
+
+> **Important**  
+> Requires \`identity.*.delete_identity\` permission  
+> Associated API keys remain functional but lose shared resources  
+> External ID becomes available for reuse immediately
+`,
+  args,
+  tool: async (client, args, ctx) => {
+    const [result, apiCall] = await identitiesDeleteIdentity(
+      client,
+      args.request,
+      { fetchOptions: { signal: ctx.signal } },
+    ).$inspect();
+
+    if (!result.ok) {
+      return {
+        content: [{ type: "text", text: result.error.message }],
+        isError: true,
+      };
+    }
+
+    const value = result.value;
+
+    return formatResult(value, apiCall);
+  },
+};