@unkey/api 2.0.0-alpha.1 → 2.0.0-alpha.11

package/src/lib/matchers.ts

@@ -3,13 +3,13 @@
  */
 
 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"
   | "json"
   | "text"
   | "bytes"
@@ -19,6 +19,7 @@ export type Encoding =
   | "fail";
 
 const DEFAULT_CONTENT_TYPES: Record<Encoding, string> = {
+  jsonl: "application/jsonl",
   json: "application/json",
   text: "text/plain",
   bytes: "application/octet-stream",
@@ -72,6 +73,21 @@ export function json<T>(
   return { ...options, enc: "json", codes, schema };
 }
 
+export function jsonl<T>(
+  codes: StatusCodePredicate,
+  schema: Schema<T>,
+  options?: MatchOptions,
+): ValueMatcher<T> {
+  return { ...options, enc: "jsonl", codes, schema };
+}
+
+export function jsonlErr<E>(
+  codes: StatusCodePredicate,
+  schema: Schema<E>,
+  options?: MatchOptions,
+): ErrorMatcher<E> {
+  return { ...options, err: true, enc: "jsonl", codes, schema };
+}
 export function textErr<E>(
   codes: StatusCodePredicate,
   schema: Schema<E>,
@@ -159,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;
@@ -188,21 +206,25 @@ 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;
         break;
       case "bytes":
         raw = new Uint8Array(await response.arrayBuffer());
@@ -211,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;
@@ -230,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];
     }
 
@@ -246,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 = {
@@ -253,26 +277,31 @@ export function match<T, E>(
         ...(matcher.hdrs ? { Headers: unpackHeaders(response.headers) } : null),
         [resultKey]: raw,
       };
-    } else {
+    } else if (matcher.hdrs) {
       data = {
         ...options?.extraFields,
         ...(matcher.hdrs ? { Headers: unpackHeaders(response.headers) } : null),
+        ...(isPlainObject(raw) ? raw : null),
       };
+    } else {
+      data = raw;
     }
 
     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,
       ];
@@ -295,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" });
     }
 
@@ -302,7 +308,9 @@ export class ClientSDK {
   }
 }
 
-const jsonLikeContentTypeRE = /^application\/(?:.{0,100}\+)?json/;
+const jsonLikeContentTypeRE = /(application|text)\/.*?\+*json.*/;
+const jsonlLikeContentTypeRE =
+  /(application|text)\/(.*?\+*\bjsonl\b.*|.*?\+*\bx-ndjson\b.*)/;
 async function logRequest(logger: Logger | undefined, req: Request) {
   if (!logger) {
     return;
@@ -368,9 +376,13 @@ async function logResponse(
   logger.group("Body:");
   switch (true) {
     case matchContentType(res, "application/json")
-      || jsonLikeContentTypeRE.test(ct):
+      || jsonLikeContentTypeRE.test(ct) && !jsonlLikeContentTypeRE.test(ct):
       logger.log(await res.clone().json());
       break;
+    case matchContentType(res, "application/jsonl")
+      || jsonlLikeContentTypeRE.test(ct):
+      logger.log(await res.clone().text());
+      break;
     case matchContentType(res, "text/event-stream"):
       logger.log(`<${contentType}>`);
       break;

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

@@ -0,0 +1,94 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { buildCommand } from "@stricli/core";
+import { numberParser } from "@stricli/core";
+import * as z from "zod";
+import { consoleLoggerLevels } from "../../console-logger.js";
+
+export const startCommand = buildCommand({
+  loader: async () => {
+    const { main } = await import("./impl.js");
+    return main;
+  },
+  parameters: {
+    flags: {
+      transport: {
+        kind: "enum",
+        brief: "The transport to use for communicating with the server",
+        default: "stdio",
+        values: ["stdio", "sse"],
+      },
+      port: {
+        kind: "parsed",
+        brief: "The port to use when the SSE transport is enabled",
+        default: "2718",
+        parse: (val: string) =>
+          z.coerce.number().int().gte(0).lt(65536).parse(val),
+      },
+      tool: {
+        kind: "parsed",
+        brief: "Specify tools to mount on the server",
+        optional: true,
+        variadic: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      "root-key": {
+        kind: "parsed",
+        brief: "Sets the rootKey auth field for the API",
+        optional: true,
+        parse: (value) => {
+          return z.string().parse(value);
+        },
+      },
+      "server-url": {
+        kind: "parsed",
+        brief: "Overrides the default server URL used by the SDK",
+        optional: true,
+        parse: (value) => new URL(value).toString(),
+      },
+      "server-index": {
+        kind: "parsed",
+        brief: "Selects a predefined server used by the SDK",
+        optional: true,
+        parse: numberParser,
+      },
+      "log-level": {
+        kind: "enum",
+        brief: "The log level to use for the server",
+        default: "info",
+        values: consoleLoggerLevels,
+      },
+      env: {
+        kind: "parsed",
+        brief: "Environment variables made available to the server",
+        optional: true,
+        variadic: true,
+        parse: (val: string) => {
+          const sepIdx = val.indexOf("=");
+          if (sepIdx === -1) {
+            throw new Error("Invalid environment variable format");
+          }
+
+          const key = val.slice(0, sepIdx);
+          const value = val.slice(sepIdx + 1);
+
+          return [
+            z.string().nonempty({
+              message: "Environment variable key must be a non-empty string",
+            }).parse(key),
+            z.string().nonempty({
+              message: "Environment variable value must be a non-empty string",
+            }).parse(value),
+          ] satisfies [string, string];
+        },
+      },
+    },
+  },
+  docs: {
+    brief: "Run the Model Context Protocol server",
+  },
+});

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

@@ -0,0 +1,130 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import express from "express";
+import { SDKOptions } from "../../../lib/config.js";
+import { LocalContext } from "../../cli.js";
+import {
+  ConsoleLoggerLevel,
+  createConsoleLogger,
+} from "../../console-logger.js";
+import { createMCPServer } from "../../server.js";
+
+interface StartCommandFlags {
+  readonly transport: "stdio" | "sse";
+  readonly port: number;
+  readonly tool?: string[];
+  readonly "root-key"?: string | undefined;
+  readonly "server-url"?: string;
+  readonly "server-index"?: SDKOptions["serverIdx"];
+  readonly "log-level": ConsoleLoggerLevel;
+  readonly env?: [string, string][];
+}
+
+export async function main(this: LocalContext, flags: StartCommandFlags) {
+  flags.env?.forEach(([key, value]) => {
+    process.env[key] = value;
+  });
+
+  switch (flags.transport) {
+    case "stdio":
+      await startStdio(flags);
+      break;
+    case "sse":
+      await startSSE(flags);
+      break;
+    default:
+      throw new Error(`Invalid transport: ${flags.transport}`);
+  }
+}
+
+async function startStdio(flags: StartCommandFlags) {
+  const logger = createConsoleLogger(flags["log-level"]);
+  const transport = new StdioServerTransport();
+  const server = createMCPServer({
+    logger,
+    allowedTools: flags.tool,
+    ...{ rootKey: flags["root-key"] ?? "" },
+    serverURL: flags["server-url"],
+    serverIdx: flags["server-index"],
+  });
+  await server.connect(transport);
+
+  const abort = async () => {
+    await server.close();
+    process.exit(0);
+  };
+  process.on("SIGTERM", abort);
+  process.on("SIGINT", abort);
+}
+
+async function startSSE(flags: StartCommandFlags) {
+  const logger = createConsoleLogger(flags["log-level"]);
+  const app = express();
+  const mcpServer = createMCPServer({
+    logger,
+    allowedTools: flags.tool,
+    ...{ rootKey: flags["root-key"] ?? "" },
+    serverURL: flags["server-url"],
+    serverIdx: flags["server-index"],
+  });
+  let transport: SSEServerTransport | undefined;
+  const controller = new AbortController();
+
+  app.get("/sse", async (_req, res) => {
+    transport = new SSEServerTransport("/message", res);
+
+    await mcpServer.connect(transport);
+
+    mcpServer.server.onclose = async () => {
+      res.end();
+    };
+  });
+
+  app.post("/message", async (req, res) => {
+    if (!transport) {
+      throw new Error("Server transport not initialized");
+    }
+
+    await transport.handlePostMessage(req, res);
+  });
+
+  const httpServer = app.listen(flags.port, "0.0.0.0", () => {
+    const ha = httpServer.address();
+    const host = typeof ha === "string" ? ha : `${ha?.address}:${ha?.port}`;
+    logger.info("MCP HTTP server started", { host });
+  });
+
+  let closing = false;
+  controller.signal.addEventListener("abort", async () => {
+    if (closing) {
+      logger.info("Received second signal. Forcing shutdown.");
+      process.exit(1);
+    }
+    closing = true;
+
+    logger.info("Shutting down MCP server");
+
+    await mcpServer.close();
+
+    logger.info("Shutting down HTTP server");
+
+    const timer = setTimeout(() => {
+      logger.info("Forcing shutdown");
+      process.exit(1);
+    }, 5000);
+
+    httpServer.close(() => {
+      clearTimeout(timer);
+      logger.info("Graceful shutdown complete");
+      process.exit(0);
+    });
+  });
+
+  const abort = () => controller.abort();
+  process.on("SIGTERM", abort);
+  process.on("SIGINT", abort);
+}

package/src/mcp-server/cli.ts

@@ -0,0 +1,13 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { CommandContext, StricliProcess } from "@stricli/core";
+
+export interface LocalContext extends CommandContext {
+  readonly process: StricliProcess;
+}
+
+export function buildContext(process: NodeJS.Process): LocalContext {
+  return { process: process as StricliProcess };
+}

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

@@ -0,0 +1,71 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export const consoleLoggerLevels = [
+  "debug",
+  "warning",
+  "info",
+  "error",
+] as const;
+
+export type ConsoleLoggerLevel = (typeof consoleLoggerLevels)[number];
+
+export type ConsoleLogger = {
+  [key in ConsoleLoggerLevel]: (
+    message: string,
+    data?: Record<string, unknown>,
+  ) => void;
+};
+
+export function createConsoleLogger(level: ConsoleLoggerLevel): ConsoleLogger {
+  const min = consoleLoggerLevels.indexOf(level);
+  const noop = () => {};
+
+  const logger: ConsoleLogger = {
+    debug: noop,
+    warning: noop,
+    info: noop,
+    error: noop,
+  };
+
+  return consoleLoggerLevels.reduce((logger, level, i) => {
+    if (i < min) {
+      return logger;
+    }
+
+    logger[level] = log.bind(null, level);
+
+    return logger;
+  }, logger);
+}
+
+function log(
+  level: ConsoleLoggerLevel,
+  message: string,
+  data?: Record<string, unknown>,
+) {
+  let line = "";
+  const allData = [{ msg: message, l: level }, data];
+
+  for (const ctx of allData) {
+    for (const [key, value] of Object.entries(ctx || {})) {
+      if (value == null) {
+        line += ` ${key}=<${value}>`;
+      } else if (typeof value === "function") {
+        line += ` ${key}=<function>`;
+      } else if (typeof value === "symbol") {
+        line += ` ${key}=${value.toString()}`;
+      } else if (typeof value === "string") {
+        const v = value.search(/\s/g) >= 0 ? JSON.stringify(value) : value;
+        line += ` ${key}=${v}`;
+      } else if (typeof value !== "object") {
+        line += ` ${key}=${value}`;
+      } else {
+        line += ` ${key}="${JSON.stringify(value)}"`;
+      }
+    }
+  }
+
+  console.error(line);
+}

package/src/mcp-server/extensions.ts

@@ -0,0 +1,17 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ZodRawShape } from "zod";
+import { PromptArgsRawShape, PromptDefinition } from "./prompts.js";
+import { ResourceDefinition, ResourceTemplateDefinition } from "./resources.js";
+import { ToolDefinition } from "./tools.js";
+
+export type Register = {
+  tool: <A extends ZodRawShape | undefined>(def: ToolDefinition<A>) => void;
+  resource: (def: ResourceDefinition) => void;
+  resourceTemplate: (def: ResourceTemplateDefinition) => void;
+  prompt: <A extends PromptArgsRawShape | undefined>(
+    prompt: PromptDefinition<A>,
+  ) => void;
+};