notte-sdk 0.0.1

package/dist/proxy/next.mjs

@@ -0,0 +1,323 @@
+// src/proxy/patterns.ts
+var DEFAULT_ALLOWED_PATTERNS = [
+  // Agents endpoints
+  /^agents$/,
+  // /agents
+  /^agents\/[^\/]+$/,
+  // /agents/{agent_id}
+  /^agents\/[^\/]+\/stop$/,
+  // /agents/{agent_id}/stop
+  /^agents\/[^\/]+\/workflow\/code$/,
+  // /agents/{agent_id}/workflow/code
+  /^agents\/start$/,
+  // /agents/start
+  // Anything endpoints
+  /^anything\/start$/,
+  // /anything/start
+  // Functions endpoints
+  /^functions$/,
+  // /functions
+  /^functions\/[^\/]+$/,
+  // /functions/{function_id}
+  /^functions\/[^\/]+\/fork$/,
+  // /functions/{function_id}/fork
+  /^functions\/[^\/]+\/runs$/,
+  // /functions/{function_id}/runs
+  /^functions\/[^\/]+\/runs\/[^\/]+$/,
+  // /functions/{function_id}/runs/{run_id}
+  /^functions\/[^\/]+\/runs\/start$/,
+  // /functions/{function_id}/runs/start
+  /^functions\/[^\/]+\/schedule$/,
+  // /functions/{function_id}/schedule
+  // Personas endpoints
+  /^personas$/,
+  // /personas
+  /^personas\/[^\/]+$/,
+  // /personas/{persona_id}
+  /^personas\/[^\/]+\/emails$/,
+  // /personas/{persona_id}/emails
+  /^personas\/[^\/]+\/sms$/,
+  // /personas/{persona_id}/sms
+  /^personas\/create$/,
+  // /personas/create
+  // Profiles endpoints
+  /^profiles$/,
+  // /profiles
+  /^profiles\/[^\/]+$/,
+  // /profiles/{profile_id}
+  /^profiles\/create$/,
+  // /profiles/create
+  // Prompts endpoints
+  /^prompts\/improve$/,
+  // /prompts/improve
+  /^prompts\/nudge$/,
+  // /prompts/nudge
+  // Root endpoints
+  /^health$/,
+  // /health
+  /^scrape$/,
+  // /scrape
+  /^scrape_from_html$/,
+  // /scrape_from_html
+  // Sessions endpoints
+  /^sessions$/,
+  // /sessions
+  /^sessions\/[^\/]+$/,
+  // /sessions/{session_id}
+  /^sessions\/[^\/]+\/cookies$/,
+  // /sessions/{session_id}/cookies
+  /^sessions\/[^\/]+\/debug$/,
+  // /sessions/{session_id}/debug
+  /^sessions\/[^\/]+\/network\/logs$/,
+  // /sessions/{session_id}/network/logs
+  /^sessions\/[^\/]+\/offset$/,
+  // /sessions/{session_id}/offset
+  /^sessions\/[^\/]+\/page\/execute$/,
+  // /sessions/{session_id}/page/execute
+  /^sessions\/[^\/]+\/page\/observe$/,
+  // /sessions/{session_id}/page/observe
+  /^sessions\/[^\/]+\/page\/scrape$/,
+  // /sessions/{session_id}/page/scrape
+  /^sessions\/[^\/]+\/page\/screenshot$/,
+  // /sessions/{session_id}/page/screenshot
+  /^sessions\/[^\/]+\/replay$/,
+  // /sessions/{session_id}/replay
+  /^sessions\/[^\/]+\/stop$/,
+  // /sessions/{session_id}/stop
+  /^sessions\/[^\/]+\/workflow\/code$/,
+  // /sessions/{session_id}/workflow/code
+  /^sessions\/start$/,
+  // /sessions/start
+  // Storage endpoints
+  /^storage\/[^\/]+\/downloads$/,
+  // /storage/{session_id}/downloads
+  /^storage\/[^\/]+\/downloads\/[^\/]+$/,
+  // /storage/{session_id}/downloads/{filename}
+  /^storage\/uploads$/,
+  // /storage/uploads
+  /^storage\/uploads\/[^\/]+$/,
+  // /storage/uploads/{filename}
+  // Usage endpoints
+  /^usage$/,
+  // /usage
+  /^usage\/logs$/,
+  // /usage/logs
+  // Vaults endpoints
+  /^vaults$/,
+  // /vaults
+  /^vaults\/[^\/]+$/,
+  // /vaults/{vault_id}
+  /^vaults\/[^\/]+\/card$/,
+  // /vaults/{vault_id}/card
+  /^vaults\/[^\/]+\/credentials$/,
+  // /vaults/{vault_id}/credentials
+  /^vaults\/create$/
+  // /vaults/create
+];
+function validatePath(pathSegments, allowedPatterns) {
+  const path = pathSegments.join("/");
+  if (path.includes("..") || path.includes("//") || path.startsWith("/")) {
+    return {
+      isValid: false,
+      error: "Invalid path: directory traversal detected"
+    };
+  }
+  const isValidPattern = allowedPatterns.some((pattern) => pattern.test(path));
+  if (!isValidPattern) {
+    return {
+      isValid: false,
+      error: `Invalid path: ${path} does not match any allowed endpoint pattern`
+    };
+  }
+  return { isValid: true };
+}
+
+// src/proxy/types.ts
+var NotteProxyAuthError = class extends Error {
+  constructor(message = "Unauthorized") {
+    super(message);
+    this.name = "NotteProxyAuthError";
+  }
+};
+
+// src/proxy/core.ts
+var DEFAULT_API_URL = "https://api.notte.cc";
+var DEFAULT_FORWARD_HEADERS = ["content-type", "accept"];
+var METHODS_WITH_BODY = ["POST", "PUT", "PATCH"];
+async function handleProxyRequest(request, pathSegments, config) {
+  try {
+    if (config.allowedPatterns !== false) {
+      const patterns = config.allowedPatterns || DEFAULT_ALLOWED_PATTERNS;
+      const pathValidation = validatePath(pathSegments, patterns);
+      if (!pathValidation.isValid) {
+        return new Response(
+          JSON.stringify({
+            error: "Invalid API endpoint",
+            details: pathValidation.error
+          }),
+          {
+            status: 400,
+            headers: { "Content-Type": "application/json" }
+          }
+        );
+      }
+    }
+    let apiKey = config.apiKey || process.env.NOTTE_API_KEY;
+    if (config.authenticate) {
+      const result = await config.authenticate(request);
+      if (typeof result === "string") {
+        apiKey = result;
+      }
+    }
+    if (!apiKey) {
+      return new Response(
+        JSON.stringify({ error: "No API key configured" }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+    const apiUrl = (config.apiUrl || DEFAULT_API_URL).replace(/\/$/, "");
+    const path = pathSegments.join("/");
+    const incomingUrl = new URL(request.url);
+    const searchParams = incomingUrl.searchParams.toString();
+    const targetUrl = `${apiUrl}/${path}${searchParams ? `?${searchParams}` : ""}`;
+    const forwardHeaders = new Headers();
+    forwardHeaders.set("Authorization", `Bearer ${apiKey}`);
+    forwardHeaders.set(
+      "x-notte-request-origin",
+      config.requestOrigin || "sdk-proxy"
+    );
+    const headersToForward = config.forwardHeaders || DEFAULT_FORWARD_HEADERS;
+    for (const header of headersToForward) {
+      const value = request.headers.get(header);
+      if (value) {
+        forwardHeaders.set(header, value);
+      }
+    }
+    if (config.onBeforeRequest) {
+      await config.onBeforeRequest({
+        path,
+        method: request.method,
+        headers: forwardHeaders,
+        url: targetUrl,
+        incomingRequest: request
+      });
+    }
+    const requestOptions = {
+      method: request.method,
+      headers: forwardHeaders
+    };
+    if (METHODS_WITH_BODY.includes(request.method) && request.body) {
+      requestOptions.body = request.body;
+      requestOptions.duplex = "half";
+    }
+    let response;
+    try {
+      response = await fetch(targetUrl, requestOptions);
+    } catch (fetchError) {
+      const errorMessage = fetchError instanceof Error ? fetchError.message : "Unknown fetch error";
+      return new Response(
+        JSON.stringify({
+          error: "Failed to forward request to Notte API",
+          details: errorMessage
+        }),
+        {
+          status: 502,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+    const contentType = response.headers.get("content-type") || "";
+    const isBinaryResponse = contentType.startsWith("image/") || contentType.startsWith("video/") || contentType.startsWith("audio/") || contentType.includes("octet-stream");
+    const isStreamingResponse = contentType.includes("text/event-stream");
+    if (isStreamingResponse && response.body) {
+      return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: {
+          "Content-Type": contentType,
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive"
+        }
+      });
+    }
+    if (response.body) {
+      return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: {
+          "Content-Type": contentType
+        }
+      });
+    }
+    if (isBinaryResponse) {
+      const data2 = await response.arrayBuffer();
+      return new Response(data2, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: { "Content-Type": contentType }
+      });
+    }
+    const data = await response.text();
+    return new Response(data, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: { "Content-Type": contentType }
+    });
+  } catch (error) {
+    if (error instanceof NotteProxyAuthError) {
+      return new Response(
+        JSON.stringify({ error: error.message }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+    throw error;
+  }
+}
+
+// src/proxy/next.ts
+function createNotteProxy(config) {
+  const resolvedConfig = { ...config };
+  const makeHandler = () => {
+    return async (request, context) => {
+      try {
+        const { path } = await context.params;
+        return await handleProxyRequest(request, path, resolvedConfig);
+      } catch (error) {
+        if (error instanceof Error) {
+          return new Response(JSON.stringify({ error: error.message }), {
+            status: 500,
+            headers: { "Content-Type": "application/json" }
+          });
+        }
+        return new Response(
+          JSON.stringify({ error: "Internal server error" }),
+          {
+            status: 500,
+            headers: { "Content-Type": "application/json" }
+          }
+        );
+      }
+    };
+  };
+  return {
+    GET: makeHandler(),
+    POST: makeHandler(),
+    PUT: makeHandler(),
+    DELETE: makeHandler(),
+    PATCH: makeHandler()
+  };
+}
+export {
+  DEFAULT_ALLOWED_PATTERNS,
+  NotteProxyAuthError,
+  createNotteProxy,
+  handleProxyRequest,
+  validatePath
+};
+//# sourceMappingURL=next.mjs.map

package/dist/proxy/next.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/proxy/patterns.ts","../../src/proxy/types.ts","../../src/proxy/core.ts","../../src/proxy/next.ts"],"sourcesContent":["/**\n * Auto-generated from sdk.gen.ts by scripts/generate-proxy-patterns.js\n * DO NOT EDIT MANUALLY — re-run `npm run generate` to update.\n *\n * Allowed API endpoint patterns to prevent SSRF attacks.\n * Every pattern corresponds to an endpoint in the Notte API OpenAPI spec.\n */\nexport const DEFAULT_ALLOWED_PATTERNS: RegExp[] = [\n  // Agents endpoints\n  /^agents$/, // /agents\n  /^agents\\/[^\\/]+$/, // /agents/{agent_id}\n  /^agents\\/[^\\/]+\\/stop$/, // /agents/{agent_id}/stop\n  /^agents\\/[^\\/]+\\/workflow\\/code$/, // /agents/{agent_id}/workflow/code\n  /^agents\\/start$/, // /agents/start\n\n  // Anything endpoints\n  /^anything\\/start$/, // /anything/start\n\n  // Functions endpoints\n  /^functions$/, // /functions\n  /^functions\\/[^\\/]+$/, // /functions/{function_id}\n  /^functions\\/[^\\/]+\\/fork$/, // /functions/{function_id}/fork\n  /^functions\\/[^\\/]+\\/runs$/, // /functions/{function_id}/runs\n  /^functions\\/[^\\/]+\\/runs\\/[^\\/]+$/, // /functions/{function_id}/runs/{run_id}\n  /^functions\\/[^\\/]+\\/runs\\/start$/, // /functions/{function_id}/runs/start\n  /^functions\\/[^\\/]+\\/schedule$/, // /functions/{function_id}/schedule\n\n  // Personas endpoints\n  /^personas$/, // /personas\n  /^personas\\/[^\\/]+$/, // /personas/{persona_id}\n  /^personas\\/[^\\/]+\\/emails$/, // /personas/{persona_id}/emails\n  /^personas\\/[^\\/]+\\/sms$/, // /personas/{persona_id}/sms\n  /^personas\\/create$/, // /personas/create\n\n  // Profiles endpoints\n  /^profiles$/, // /profiles\n  /^profiles\\/[^\\/]+$/, // /profiles/{profile_id}\n  /^profiles\\/create$/, // /profiles/create\n\n  // Prompts endpoints\n  /^prompts\\/improve$/, // /prompts/improve\n  /^prompts\\/nudge$/, // /prompts/nudge\n\n  // Root endpoints\n  /^health$/, // /health\n  /^scrape$/, // /scrape\n  /^scrape_from_html$/, // /scrape_from_html\n\n  // Sessions endpoints\n  /^sessions$/, // /sessions\n  /^sessions\\/[^\\/]+$/, // /sessions/{session_id}\n  /^sessions\\/[^\\/]+\\/cookies$/, // /sessions/{session_id}/cookies\n  /^sessions\\/[^\\/]+\\/debug$/, // /sessions/{session_id}/debug\n  /^sessions\\/[^\\/]+\\/network\\/logs$/, // /sessions/{session_id}/network/logs\n  /^sessions\\/[^\\/]+\\/offset$/, // /sessions/{session_id}/offset\n  /^sessions\\/[^\\/]+\\/page\\/execute$/, // /sessions/{session_id}/page/execute\n  /^sessions\\/[^\\/]+\\/page\\/observe$/, // /sessions/{session_id}/page/observe\n  /^sessions\\/[^\\/]+\\/page\\/scrape$/, // /sessions/{session_id}/page/scrape\n  /^sessions\\/[^\\/]+\\/page\\/screenshot$/, // /sessions/{session_id}/page/screenshot\n  /^sessions\\/[^\\/]+\\/replay$/, // /sessions/{session_id}/replay\n  /^sessions\\/[^\\/]+\\/stop$/, // /sessions/{session_id}/stop\n  /^sessions\\/[^\\/]+\\/workflow\\/code$/, // /sessions/{session_id}/workflow/code\n  /^sessions\\/start$/, // /sessions/start\n\n  // Storage endpoints\n  /^storage\\/[^\\/]+\\/downloads$/, // /storage/{session_id}/downloads\n  /^storage\\/[^\\/]+\\/downloads\\/[^\\/]+$/, // /storage/{session_id}/downloads/{filename}\n  /^storage\\/uploads$/, // /storage/uploads\n  /^storage\\/uploads\\/[^\\/]+$/, // /storage/uploads/{filename}\n\n  // Usage endpoints\n  /^usage$/, // /usage\n  /^usage\\/logs$/, // /usage/logs\n\n  // Vaults endpoints\n  /^vaults$/, // /vaults\n  /^vaults\\/[^\\/]+$/, // /vaults/{vault_id}\n  /^vaults\\/[^\\/]+\\/card$/, // /vaults/{vault_id}/card\n  /^vaults\\/[^\\/]+\\/credentials$/, // /vaults/{vault_id}/credentials\n  /^vaults\\/create$/, // /vaults/create\n];\n\nexport interface PathValidationResult {\n  isValid: boolean;\n  error?: string;\n}\n\n/**\n * Validates a request path against a list of allowed patterns.\n * Prevents directory traversal and SSRF attacks.\n */\nexport function validatePath(\n  pathSegments: string[],\n  allowedPatterns: RegExp[],\n): PathValidationResult {\n  const path = pathSegments.join('/');\n\n  // Check for directory traversal attempts\n  if (path.includes('..') || path.includes('//') || path.startsWith('/')) {\n    return {\n      isValid: false,\n      error: 'Invalid path: directory traversal detected',\n    };\n  }\n\n  // Check against allowed patterns\n  const isValidPattern = allowedPatterns.some((pattern) => pattern.test(path));\n  if (!isValidPattern) {\n    return {\n      isValid: false,\n      error: `Invalid path: ${path} does not match any allowed endpoint pattern`,\n    };\n  }\n\n  return { isValid: true };\n}\n","/**\n * Error class for authentication/authorization failures in the proxy.\n * Throw this from `authenticate()` to return a 401 response.\n *\n * @example\n * ```typescript\n * authenticate: async (request) => {\n *   const session = await getSession(request);\n *   if (!session) throw new NotteProxyAuthError('Not logged in');\n * }\n * ```\n */\nexport class NotteProxyAuthError extends Error {\n  constructor(message = 'Unauthorized') {\n    super(message);\n    this.name = 'NotteProxyAuthError';\n  }\n}\n\n/**\n * Configuration for the Notte API proxy.\n *\n * The proxy forwards incoming HTTP requests to the Notte API,\n * injecting authentication headers server-side so the API key\n * is never exposed to the client.\n */\nexport interface NotteProxyConfig {\n  /**\n   * The Notte API key to use for all forwarded requests.\n   * Falls back to the NOTTE_API_KEY environment variable when omitted.\n   * Can be overridden per-request by returning a string from `authenticate`.\n   */\n  apiKey?: string;\n\n  /**\n   * Base URL of the Notte API.\n   * @default 'https://api.notte.cc'\n   */\n  apiUrl?: string;\n\n  /**\n   * Optional async function to authenticate/authorize incoming requests.\n   *\n   * - Throw a `NotteProxyAuthError` to reject the request (returns 401).\n   * - Return `void` to allow the request through using the default `apiKey`.\n   * - Return a `string` to override the API key for this specific request\n   *   (useful for per-user API keys).\n   */\n  authenticate?: (request: Request) => Promise<void | string>;\n\n  /**\n   * Allowed API endpoint patterns for path validation (SSRF prevention).\n   *\n   * - `undefined` (default): uses the built-in allowlist derived from the OpenAPI spec.\n   * - `RegExp[]`: custom list of allowed patterns.\n   * - `false`: disables path validation entirely (not recommended for public-facing proxies).\n   */\n  allowedPatterns?: RegExp[] | false;\n\n  /**\n   * Value for the `x-notte-request-origin` header sent to the Notte API.\n   * @default 'sdk-proxy'\n   */\n  requestOrigin?: string;\n\n  /**\n   * List of header names to forward from the incoming request to the Notte API.\n   * @default ['content-type', 'accept']\n   */\n  forwardHeaders?: string[];\n\n  /**\n   * Optional hook called just before the request is forwarded to the Notte API.\n   * Use this to modify outgoing headers, log requests, etc.\n   */\n  onBeforeRequest?: (ctx: {\n    path: string;\n    method: string;\n    headers: Headers;\n    url: string;\n    incomingRequest: Request;\n  }) => Promise<void> | void;\n}\n","import { validatePath, DEFAULT_ALLOWED_PATTERNS } from './patterns';\nimport type { NotteProxyConfig } from './types';\nimport { NotteProxyAuthError } from './types';\n\nconst DEFAULT_API_URL = 'https://api.notte.cc';\nconst DEFAULT_FORWARD_HEADERS = ['content-type', 'accept'];\nconst METHODS_WITH_BODY = ['POST', 'PUT', 'PATCH'];\n\n/**\n * Framework-agnostic proxy handler that forwards requests to the Notte API.\n *\n * Takes a standard Web API `Request`, injects authentication, and returns\n * a standard Web API `Response`. Works with any runtime that supports\n * the Web API standards (Node 18+, Deno, Bun, Cloudflare Workers).\n *\n * @param request - The incoming HTTP request (standard Web API Request)\n * @param pathSegments - The path segments after the proxy base path (e.g., ['sessions', 'start'])\n * @param config - Proxy configuration including API key, auth hooks, etc.\n * @returns A standard Web API Response\n */\nexport async function handleProxyRequest(\n  request: Request,\n  pathSegments: string[],\n  config: NotteProxyConfig,\n): Promise<Response> {\n  try {\n    // Step 1: Path validation\n    if (config.allowedPatterns !== false) {\n      const patterns = config.allowedPatterns || DEFAULT_ALLOWED_PATTERNS;\n      const pathValidation = validatePath(pathSegments, patterns);\n\n      if (!pathValidation.isValid) {\n        return new Response(\n          JSON.stringify({\n            error: 'Invalid API endpoint',\n            details: pathValidation.error,\n          }),\n          {\n            status: 400,\n            headers: { 'Content-Type': 'application/json' },\n          },\n        );\n      }\n    }\n\n    // Step 2: Authentication\n    let apiKey = config.apiKey || process.env.NOTTE_API_KEY;\n\n    if (config.authenticate) {\n      const result = await config.authenticate(request);\n      if (typeof result === 'string') {\n        apiKey = result;\n      }\n    }\n\n    if (!apiKey) {\n      return new Response(\n        JSON.stringify({ error: 'No API key configured' }),\n        {\n          status: 401,\n          headers: { 'Content-Type': 'application/json' },\n        },\n      );\n    }\n\n    // Step 3: Build target URL\n    const apiUrl = (config.apiUrl || DEFAULT_API_URL).replace(/\\/$/, '');\n    const path = pathSegments.join('/');\n    const incomingUrl = new URL(request.url);\n    const searchParams = incomingUrl.searchParams.toString();\n    const targetUrl = `${apiUrl}/${path}${searchParams ? `?${searchParams}` : ''}`;\n\n    // Step 4: Build headers\n    const forwardHeaders = new Headers();\n    forwardHeaders.set('Authorization', `Bearer ${apiKey}`);\n    forwardHeaders.set(\n      'x-notte-request-origin',\n      config.requestOrigin || 'sdk-proxy',\n    );\n\n    const headersToForward =\n      config.forwardHeaders || DEFAULT_FORWARD_HEADERS;\n    for (const header of headersToForward) {\n      const value = request.headers.get(header);\n      if (value) {\n        forwardHeaders.set(header, value);\n      }\n    }\n\n    // Step 5: onBeforeRequest hook\n    if (config.onBeforeRequest) {\n      await config.onBeforeRequest({\n        path,\n        method: request.method,\n        headers: forwardHeaders,\n        url: targetUrl,\n        incomingRequest: request,\n      });\n    }\n\n    // Step 6: Forward the request\n    const requestOptions: RequestInit = {\n      method: request.method,\n      headers: forwardHeaders,\n    };\n\n    if (METHODS_WITH_BODY.includes(request.method) && request.body) {\n      requestOptions.body = request.body;\n      (requestOptions as any).duplex = 'half';\n    }\n\n    let response: globalThis.Response;\n    try {\n      response = await fetch(targetUrl, requestOptions);\n    } catch (fetchError) {\n      const errorMessage =\n        fetchError instanceof Error\n          ? fetchError.message\n          : 'Unknown fetch error';\n      return new Response(\n        JSON.stringify({\n          error: 'Failed to forward request to Notte API',\n          details: errorMessage,\n        }),\n        {\n          status: 502,\n          headers: { 'Content-Type': 'application/json' },\n        },\n      );\n    }\n\n    // Step 7: Handle response\n    const contentType = response.headers.get('content-type') || '';\n\n    const isBinaryResponse =\n      contentType.startsWith('image/') ||\n      contentType.startsWith('video/') ||\n      contentType.startsWith('audio/') ||\n      contentType.includes('octet-stream');\n\n    const isStreamingResponse = contentType.includes('text/event-stream');\n\n    // For streaming responses, pass through the body with appropriate headers\n    if (isStreamingResponse && response.body) {\n      return new Response(response.body, {\n        status: response.status,\n        statusText: response.statusText,\n        headers: {\n          'Content-Type': contentType,\n          'Cache-Control': 'no-cache',\n          Connection: 'keep-alive',\n        },\n      });\n    }\n\n    // For all other responses with a body stream, pass it through directly\n    if (response.body) {\n      return new Response(response.body, {\n        status: response.status,\n        statusText: response.statusText,\n        headers: {\n          'Content-Type': contentType,\n        },\n      });\n    }\n\n    // Fallback for responses without a body stream: buffer appropriately\n    if (isBinaryResponse) {\n      const data = await response.arrayBuffer();\n      return new Response(data, {\n        status: response.status,\n        statusText: response.statusText,\n        headers: { 'Content-Type': contentType },\n      });\n    }\n\n    // Fallback: buffer as text\n    const data = await response.text();\n    return new Response(data, {\n      status: response.status,\n      statusText: response.statusText,\n      headers: { 'Content-Type': contentType },\n    });\n  } catch (error) {\n    // NotteProxyAuthError from authenticate() → 401\n    if (error instanceof NotteProxyAuthError) {\n      return new Response(\n        JSON.stringify({ error: error.message }),\n        {\n          status: 401,\n          headers: { 'Content-Type': 'application/json' },\n        },\n      );\n    }\n\n    // Re-throw unexpected errors so the adapter layer can handle them\n    throw error;\n  }\n}\n","import type { NotteProxyConfig } from './types';\nimport { handleProxyRequest } from './core';\n\n/**\n * Type for a Next.js App Router route handler.\n * Uses standard Web API Request/Response (Next.js accepts these natively),\n * so `next` is NOT a dependency.\n */\ntype NextRouteHandler = (\n  request: Request,\n  context: { params: Promise<{ path: string[] }> },\n) => Promise<Response>;\n\n/**\n * Creates Next.js App Router route handlers that proxy requests to the Notte API.\n *\n * This allows you to hide your Notte API key from client-side code by routing\n * requests through your own server.\n *\n * @example\n * ```typescript\n * // app/api/notte/[...path]/route.ts\n * import { createNotteProxy } from '@notte/sdk/next';\n *\n * export const { GET, POST, PUT, DELETE, PATCH } = createNotteProxy({\n *   apiKey: process.env.NOTTE_API_KEY!,\n * });\n * ```\n *\n * @example With authentication\n * ```typescript\n * import { createNotteProxy, NotteProxyAuthError } from '@notte/sdk/next';\n *\n * export const { GET, POST, PUT, DELETE, PATCH } = createNotteProxy({\n *   apiKey: process.env.NOTTE_API_KEY!,\n *   authenticate: async (request) => {\n *     const session = await getSession(request);\n *     if (!session) throw new NotteProxyAuthError('Not logged in');\n *   },\n * });\n * ```\n *\n * @example With per-user API keys\n * ```typescript\n * export const { GET, POST, PUT, DELETE, PATCH } = createNotteProxy({\n *   apiKey: 'fallback-key', // pragma: allowlist secret\n *   authenticate: async (request) => {\n *     const user = await getUser(request);\n *     if (!user) throw new NotteProxyAuthError();\n *     return user.notteApiKey; // returned string overrides apiKey\n *   },\n * });\n * ```\n */\nexport function createNotteProxy(config: NotteProxyConfig): {\n  GET: NextRouteHandler;\n  POST: NextRouteHandler;\n  PUT: NextRouteHandler;\n  DELETE: NextRouteHandler;\n  PATCH: NextRouteHandler;\n} {\n  const resolvedConfig = { ...config };\n\n  const makeHandler = (): NextRouteHandler => {\n    return async (request, context) => {\n      try {\n        const { path } = await context.params;\n        return await handleProxyRequest(request, path, resolvedConfig);\n      } catch (error) {\n        if (error instanceof Error) {\n          return new Response(JSON.stringify({ error: error.message }), {\n            status: 500,\n            headers: { 'Content-Type': 'application/json' },\n          });\n        }\n        return new Response(\n          JSON.stringify({ error: 'Internal server error' }),\n          {\n            status: 500,\n            headers: { 'Content-Type': 'application/json' },\n          },\n        );\n      }\n    };\n  };\n\n  return {\n    GET: makeHandler(),\n    POST: makeHandler(),\n    PUT: makeHandler(),\n    DELETE: makeHandler(),\n    PATCH: makeHandler(),\n  };\n}\n\n// Re-export types and utilities for convenience\nexport type { NotteProxyConfig } from './types';\nexport { NotteProxyAuthError } from './types';\nexport { DEFAULT_ALLOWED_PATTERNS, validatePath } from './patterns';\nexport { handleProxyRequest } from './core';\n"],"mappings":";AAOO,IAAM,2BAAqC;AAAA;AAAA,EAEhD;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA,EACA;AAAA;AAAA;AAAA,EAGA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAWO,SAAS,aACd,cACA,iBACsB;AACtB,QAAM,OAAO,aAAa,KAAK,GAAG;AAGlC,MAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,WAAW,GAAG,GAAG;AACtE,WAAO;AAAA,MACL,SAAS;AAAA,MACT,OAAO;AAAA,IACT;AAAA,EACF;AAGA,QAAM,iBAAiB,gBAAgB,KAAK,CAAC,YAAY,QAAQ,KAAK,IAAI,CAAC;AAC3E,MAAI,CAAC,gBAAgB;AACnB,WAAO;AAAA,MACL,SAAS;AAAA,MACT,OAAO,iBAAiB,IAAI;AAAA,IAC9B;AAAA,EACF;AAEA,SAAO,EAAE,SAAS,KAAK;AACzB;;;ACvGO,IAAM,sBAAN,cAAkC,MAAM;AAAA,EAC7C,YAAY,UAAU,gBAAgB;AACpC,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;;;ACbA,IAAM,kBAAkB;AACxB,IAAM,0BAA0B,CAAC,gBAAgB,QAAQ;AACzD,IAAM,oBAAoB,CAAC,QAAQ,OAAO,OAAO;AAcjD,eAAsB,mBACpB,SACA,cACA,QACmB;AACnB,MAAI;AAEF,QAAI,OAAO,oBAAoB,OAAO;AACpC,YAAM,WAAW,OAAO,mBAAmB;AAC3C,YAAM,iBAAiB,aAAa,cAAc,QAAQ;AAE1D,UAAI,CAAC,eAAe,SAAS;AAC3B,eAAO,IAAI;AAAA,UACT,KAAK,UAAU;AAAA,YACb,OAAO;AAAA,YACP,SAAS,eAAe;AAAA,UAC1B,CAAC;AAAA,UACD;AAAA,YACE,QAAQ;AAAA,YACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,UAChD;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAGA,QAAI,SAAS,OAAO,UAAU,QAAQ,IAAI;AAE1C,QAAI,OAAO,cAAc;AACvB,YAAM,SAAS,MAAM,OAAO,aAAa,OAAO;AAChD,UAAI,OAAO,WAAW,UAAU;AAC9B,iBAAS;AAAA,MACX;AAAA,IACF;AAEA,QAAI,CAAC,QAAQ;AACX,aAAO,IAAI;AAAA,QACT,KAAK,UAAU,EAAE,OAAO,wBAAwB,CAAC;AAAA,QACjD;AAAA,UACE,QAAQ;AAAA,UACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,QAChD;AAAA,MACF;AAAA,IACF;AAGA,UAAM,UAAU,OAAO,UAAU,iBAAiB,QAAQ,OAAO,EAAE;AACnE,UAAM,OAAO,aAAa,KAAK,GAAG;AAClC,UAAM,cAAc,IAAI,IAAI,QAAQ,GAAG;AACvC,UAAM,eAAe,YAAY,aAAa,SAAS;AACvD,UAAM,YAAY,GAAG,MAAM,IAAI,IAAI,GAAG,eAAe,IAAI,YAAY,KAAK,EAAE;AAG5E,UAAM,iBAAiB,IAAI,QAAQ;AACnC,mBAAe,IAAI,iBAAiB,UAAU,MAAM,EAAE;AACtD,mBAAe;AAAA,MACb;AAAA,MACA,OAAO,iBAAiB;AAAA,IAC1B;AAEA,UAAM,mBACJ,OAAO,kBAAkB;AAC3B,eAAW,UAAU,kBAAkB;AACrC,YAAM,QAAQ,QAAQ,QAAQ,IAAI,MAAM;AACxC,UAAI,OAAO;AACT,uBAAe,IAAI,QAAQ,KAAK;AAAA,MAClC;AAAA,IACF;AAGA,QAAI,OAAO,iBAAiB;AAC1B,YAAM,OAAO,gBAAgB;AAAA,QAC3B;AAAA,QACA,QAAQ,QAAQ;AAAA,QAChB,SAAS;AAAA,QACT,KAAK;AAAA,QACL,iBAAiB;AAAA,MACnB,CAAC;AAAA,IACH;AAGA,UAAM,iBAA8B;AAAA,MAClC,QAAQ,QAAQ;AAAA,MAChB,SAAS;AAAA,IACX;AAEA,QAAI,kBAAkB,SAAS,QAAQ,MAAM,KAAK,QAAQ,MAAM;AAC9D,qBAAe,OAAO,QAAQ;AAC9B,MAAC,eAAuB,SAAS;AAAA,IACnC;AAEA,QAAI;AACJ,QAAI;AACF,iBAAW,MAAM,MAAM,WAAW,cAAc;AAAA,IAClD,SAAS,YAAY;AACnB,YAAM,eACJ,sBAAsB,QAClB,WAAW,UACX;AACN,aAAO,IAAI;AAAA,QACT,KAAK,UAAU;AAAA,UACb,OAAO;AAAA,UACP,SAAS;AAAA,QACX,CAAC;AAAA,QACD;AAAA,UACE,QAAQ;AAAA,UACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,QAChD;AAAA,MACF;AAAA,IACF;AAGA,UAAM,cAAc,SAAS,QAAQ,IAAI,cAAc,KAAK;AAE5D,UAAM,mBACJ,YAAY,WAAW,QAAQ,KAC/B,YAAY,WAAW,QAAQ,KAC/B,YAAY,WAAW,QAAQ,KAC/B,YAAY,SAAS,cAAc;AAErC,UAAM,sBAAsB,YAAY,SAAS,mBAAmB;AAGpE,QAAI,uBAAuB,SAAS,MAAM;AACxC,aAAO,IAAI,SAAS,SAAS,MAAM;AAAA,QACjC,QAAQ,SAAS;AAAA,QACjB,YAAY,SAAS;AAAA,QACrB,SAAS;AAAA,UACP,gBAAgB;AAAA,UAChB,iBAAiB;AAAA,UACjB,YAAY;AAAA,QACd;AAAA,MACF,CAAC;AAAA,IACH;AAGA,QAAI,SAAS,MAAM;AACjB,aAAO,IAAI,SAAS,SAAS,MAAM;AAAA,QACjC,QAAQ,SAAS;AAAA,QACjB,YAAY,SAAS;AAAA,QACrB,SAAS;AAAA,UACP,gBAAgB;AAAA,QAClB;AAAA,MACF,CAAC;AAAA,IACH;AAGA,QAAI,kBAAkB;AACpB,YAAMA,QAAO,MAAM,SAAS,YAAY;AACxC,aAAO,IAAI,SAASA,OAAM;AAAA,QACxB,QAAQ,SAAS;AAAA,QACjB,YAAY,SAAS;AAAA,QACrB,SAAS,EAAE,gBAAgB,YAAY;AAAA,MACzC,CAAC;AAAA,IACH;AAGA,UAAM,OAAO,MAAM,SAAS,KAAK;AACjC,WAAO,IAAI,SAAS,MAAM;AAAA,MACxB,QAAQ,SAAS;AAAA,MACjB,YAAY,SAAS;AAAA,MACrB,SAAS,EAAE,gBAAgB,YAAY;AAAA,IACzC,CAAC;AAAA,EACH,SAAS,OAAO;AAEd,QAAI,iBAAiB,qBAAqB;AACxC,aAAO,IAAI;AAAA,QACT,KAAK,UAAU,EAAE,OAAO,MAAM,QAAQ,CAAC;AAAA,QACvC;AAAA,UACE,QAAQ;AAAA,UACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,QAChD;AAAA,MACF;AAAA,IACF;AAGA,UAAM;AAAA,EACR;AACF;;;AChJO,SAAS,iBAAiB,QAM/B;AACA,QAAM,iBAAiB,EAAE,GAAG,OAAO;AAEnC,QAAM,cAAc,MAAwB;AAC1C,WAAO,OAAO,SAAS,YAAY;AACjC,UAAI;AACF,cAAM,EAAE,KAAK,IAAI,MAAM,QAAQ;AAC/B,eAAO,MAAM,mBAAmB,SAAS,MAAM,cAAc;AAAA,MAC/D,SAAS,OAAO;AACd,YAAI,iBAAiB,OAAO;AAC1B,iBAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,MAAM,QAAQ,CAAC,GAAG;AAAA,YAC5D,QAAQ;AAAA,YACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,UAChD,CAAC;AAAA,QACH;AACA,eAAO,IAAI;AAAA,UACT,KAAK,UAAU,EAAE,OAAO,wBAAwB,CAAC;AAAA,UACjD;AAAA,YACE,QAAQ;AAAA,YACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,UAChD;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AAAA,IACL,KAAK,YAAY;AAAA,IACjB,MAAM,YAAY;AAAA,IAClB,KAAK,YAAY;AAAA,IACjB,QAAQ,YAAY;AAAA,IACpB,OAAO,YAAY;AAAA,EACrB;AACF;","names":["data"]}

package/dist/types-DmqqdEMP.d.mts

@@ -0,0 +1,75 @@
+/**
+ * Error class for authentication/authorization failures in the proxy.
+ * Throw this from `authenticate()` to return a 401 response.
+ *
+ * @example
+ * ```typescript
+ * authenticate: async (request) => {
+ *   const session = await getSession(request);
+ *   if (!session) throw new NotteProxyAuthError('Not logged in');
+ * }
+ * ```
+ */
+declare class NotteProxyAuthError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Configuration for the Notte API proxy.
+ *
+ * The proxy forwards incoming HTTP requests to the Notte API,
+ * injecting authentication headers server-side so the API key
+ * is never exposed to the client.
+ */
+interface NotteProxyConfig {
+    /**
+     * The Notte API key to use for all forwarded requests.
+     * Falls back to the NOTTE_API_KEY environment variable when omitted.
+     * Can be overridden per-request by returning a string from `authenticate`.
+     */
+    apiKey?: string;
+    /**
+     * Base URL of the Notte API.
+     * @default 'https://api.notte.cc'
+     */
+    apiUrl?: string;
+    /**
+     * Optional async function to authenticate/authorize incoming requests.
+     *
+     * - Throw a `NotteProxyAuthError` to reject the request (returns 401).
+     * - Return `void` to allow the request through using the default `apiKey`.
+     * - Return a `string` to override the API key for this specific request
+     *   (useful for per-user API keys).
+     */
+    authenticate?: (request: Request) => Promise<void | string>;
+    /**
+     * Allowed API endpoint patterns for path validation (SSRF prevention).
+     *
+     * - `undefined` (default): uses the built-in allowlist derived from the OpenAPI spec.
+     * - `RegExp[]`: custom list of allowed patterns.
+     * - `false`: disables path validation entirely (not recommended for public-facing proxies).
+     */
+    allowedPatterns?: RegExp[] | false;
+    /**
+     * Value for the `x-notte-request-origin` header sent to the Notte API.
+     * @default 'sdk-proxy'
+     */
+    requestOrigin?: string;
+    /**
+     * List of header names to forward from the incoming request to the Notte API.
+     * @default ['content-type', 'accept']
+     */
+    forwardHeaders?: string[];
+    /**
+     * Optional hook called just before the request is forwarded to the Notte API.
+     * Use this to modify outgoing headers, log requests, etc.
+     */
+    onBeforeRequest?: (ctx: {
+        path: string;
+        method: string;
+        headers: Headers;
+        url: string;
+        incomingRequest: Request;
+    }) => Promise<void> | void;
+}
+
+export { NotteProxyAuthError as N, type NotteProxyConfig as a };

package/dist/types-DmqqdEMP.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Error class for authentication/authorization failures in the proxy.
+ * Throw this from `authenticate()` to return a 401 response.
+ *
+ * @example
+ * ```typescript
+ * authenticate: async (request) => {
+ *   const session = await getSession(request);
+ *   if (!session) throw new NotteProxyAuthError('Not logged in');
+ * }
+ * ```
+ */
+declare class NotteProxyAuthError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Configuration for the Notte API proxy.
+ *
+ * The proxy forwards incoming HTTP requests to the Notte API,
+ * injecting authentication headers server-side so the API key
+ * is never exposed to the client.
+ */
+interface NotteProxyConfig {
+    /**
+     * The Notte API key to use for all forwarded requests.
+     * Falls back to the NOTTE_API_KEY environment variable when omitted.
+     * Can be overridden per-request by returning a string from `authenticate`.
+     */
+    apiKey?: string;
+    /**
+     * Base URL of the Notte API.
+     * @default 'https://api.notte.cc'
+     */
+    apiUrl?: string;
+    /**
+     * Optional async function to authenticate/authorize incoming requests.
+     *
+     * - Throw a `NotteProxyAuthError` to reject the request (returns 401).
+     * - Return `void` to allow the request through using the default `apiKey`.
+     * - Return a `string` to override the API key for this specific request
+     *   (useful for per-user API keys).
+     */
+    authenticate?: (request: Request) => Promise<void | string>;
+    /**
+     * Allowed API endpoint patterns for path validation (SSRF prevention).
+     *
+     * - `undefined` (default): uses the built-in allowlist derived from the OpenAPI spec.
+     * - `RegExp[]`: custom list of allowed patterns.
+     * - `false`: disables path validation entirely (not recommended for public-facing proxies).
+     */
+    allowedPatterns?: RegExp[] | false;
+    /**
+     * Value for the `x-notte-request-origin` header sent to the Notte API.
+     * @default 'sdk-proxy'
+     */
+    requestOrigin?: string;
+    /**
+     * List of header names to forward from the incoming request to the Notte API.
+     * @default ['content-type', 'accept']
+     */
+    forwardHeaders?: string[];
+    /**
+     * Optional hook called just before the request is forwarded to the Notte API.
+     * Use this to modify outgoing headers, log requests, etc.
+     */
+    onBeforeRequest?: (ctx: {
+        path: string;
+        method: string;
+        headers: Headers;
+        url: string;
+        incomingRequest: Request;
+    }) => Promise<void> | void;
+}
+
+export { NotteProxyAuthError as N, type NotteProxyConfig as a };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "notte-sdk",
+  "version": "0.0.1",
+  "description": "TypeScript SDK for Notte - Cloud-hosted browser sessions with LLM-powered web agents",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./next": {
+      "types": "./dist/proxy/next.d.ts",
+      "import": "./dist/proxy/next.mjs",
+      "require": "./dist/proxy/next.js"
+    },
+    "./proxy": {
+      "types": "./dist/proxy/core.d.ts",
+      "import": "./dist/proxy/core.mjs",
+      "require": "./dist/proxy/core.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "generate": "openapi-ts && node scripts/normalize-generated.js && node scripts/generate-proxy-patterns.js",
+    "build": "npm run generate && tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build",
+    "test": "vitest",
+    "test:unit": "vitest --exclude='**/*.integration.test.ts'",
+    "test:integration": "VITEST_INTEGRATION=1 vitest --run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "notte",
+    "api",
+    "sdk",
+    "typescript"
+  ],
+  "author": "Notte",
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.18.0",
+    "zod": "^4.1.9"
+  },
+  "devDependencies": {
+    "@hey-api/openapi-ts": "^0.95.0",
+    "@types/node": "^20.14.0",
+    "@types/ws": "^8.5.10",
+    "dotenv": "^16.4.5",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.4",
+    "vitest": "^4.0.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "glob": "^11.1.0",
+    "tar": "^7.5.8"
+  }
+}