@spicyapi/proxy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpicyAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @spicyapi/proxy
+
+Let a browser, mobile or desktop app call SpicyAPI **without ever holding an API key**.
+
+A key compiled into a client is a public key. Anyone can decompile the app or watch one request, and
+then spend your balance until it runs out — while your dashboard just shows a busy day. The fix is
+not obfuscation. It is to never put the key there: the app calls **your** server, and your server
+adds the credential.
+
+This package is that server-side hop.
+
+## Install
+
+```bash
+npm install @spicyapi/proxy
+```
+
+Set `SPICY_API_KEY` in the server environment. It is never sent to the client.
+
+## Next.js (App Router)
+
+```ts
+// app/api/spicy/proxy/route.ts
+export { GET, POST, PUT, PATCH, DELETE } from "@spicyapi/proxy/nextjs";
+export const runtime = "nodejs";
+```
+
+`runtime = "nodejs"` is not optional. Edge runtimes do not see server-only environment variables, so
+the proxy would answer 500 in production while working perfectly on your machine.
+
+## Express
+
+```ts
+import { createExpressHandler } from "@spicyapi/proxy/express";
+
+app.all("/api/spicy/proxy", createExpressHandler());
+```
+
+Mount it **before** any body parser. `express.json()` consumes the request body, and the proxy would
+then forward an empty one — which surfaces upstream as a missing-parameter error that points nowhere
+near your middleware order.
+
+## Any fetch runtime
+
+```ts
+import { createProxyHandler } from "@spicyapi/proxy";
+
+const handle = createProxyHandler();
+// handle(request: Request) => Promise<Response>
+```
+
+## How a client uses it
+
+Point the client at your own route and put the real target in `x-spicy-target-url`:
+
+```ts
+await fetch("/api/spicy/proxy", {
+  method: "POST",
+  headers: {
+    "content-type": "application/json",
+    "x-spicy-target-url": "https://api.spicyapi.ai/api/v1/jobs/createTask",
+    "idempotency-key": crypto.randomUUID(),
+  },
+  body: JSON.stringify({ model, input }),
+});
+```
+
+## What it refuses
+
+| Situation                       | Answer |
+| ------------------------------- | ------ |
+| No `x-spicy-target-url`         | `400`  |
+| Target origin not allow-listed  | `403`  |
+| No key configured on the server | `500`  |
+| Upstream did not answer in time | `504`  |
+
+**The allow-list is the whole point.** Forwarding to whatever the header says would mean a stranger
+can make your server hand your key to a host they control — one request, and the traffic looks
+entirely normal because it came from you. The comparison is on the exact origin, never a prefix:
+`https://api.spicyapi.ai.attacker.example` starts with our domain too.
+
+Client-supplied `authorization`, `x-api-key` and `cookie` headers are dropped before forwarding, so
+the proxy cannot be turned into an open relay for someone else's credentials.
+
+## Limits
+
+This hop authenticates to SpicyAPI. It does **not** authenticate your users — anyone who can reach
+the route can spend your balance. Put your own session check, rate limit and per-user quota in front
+of it, exactly as you would for any endpoint that costs money.

package/SECURITY.md

@@ -0,0 +1,4 @@
+# Security
+
+Report suspected vulnerabilities privately at <https://spicyapi.ai/security>. Never include API
+keys, private media, signed URLs, recovery codes, or customer data in a public issue.

package/dist/src/core.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 服务端代理：让客户端应用在**不持有 API 密钥**的前提下调用 SpicyAPI。
+ *
+ * 浏览器里的 JS、iOS / Android 应用、桌面应用——这些地方都放不住密钥。打进包里的
+ * 密钥等于公开的密钥：攻击者反编译或抓一次包就能拿到，然后一直花到余额见底，而
+ * 我们这边看到的只是「这个账号今天用得有点多」。
+ *
+ * 正确的形状是：客户端把请求打到**调用方自己的服务器**，由那一层补上密钥再转发。
+ * 这个模块就是那一层，装在调用方的 Next.js / Express / 任意 fetch 运行时里。
+ *
+ * ── 协议 ───────────────────────────────────────────────────────────
+ *
+ * 客户端把目标地址放进 `x-spicy-target-url` 头，打到自己后端约定的那条路由
+ * （惯例是 `/api/spicy/proxy`）。代理校验目标、补上 `Authorization`、转发，
+ * 再把响应原样回给客户端。
+ *
+ * ── 为什么目标地址必须白名单，而不是「转发到头里写的任何地址」 ──────
+ *
+ * 这是整个设计里唯一会造成灾难的地方。不校验的话，任何人往那个头里填
+ * `https://attacker.example` 就能让**你的服务器把你的密钥发给他**——一个
+ * 请求就泄露，而且流量看起来完全正常：是你自己的服务器发出去的。
+ *
+ * 所以 `allowedOrigins` 默认只有 `https://api.spicyapi.ai`，而且是**精确的
+ * origin 比较**，不是前缀匹配：`https://api.spicyapi.ai.attacker.example`
+ * 的前缀也是我们的域名。
+ */
+/** 承载目标地址的请求头。全小写，HTTP/2 只接受小写头名。 */
+export declare const TARGET_URL_HEADER = "x-spicy-target-url";
+/** 惯例路由。不是强制的，但保持一致能让前端的配置可以照抄。 */
+export declare const DEFAULT_PROXY_ROUTE = "/api/spicy/proxy";
+export interface ProxyOptions {
+    /**
+     * 密钥。缺省从 `SPICY_API_KEY` 读。
+     *
+     * 传函数可以支持轮换：每次请求现取，不必重启进程。
+     */
+    apiKey?: string | (() => string | undefined);
+    /** 允许转发到的 origin。默认只有生产入口；本地联调时才需要放宽。 */
+    allowedOrigins?: string[];
+    /** 转发超时。默认 120 秒——媒体任务的提交是快的，慢的是之后的轮询。 */
+    timeoutMs?: number;
+    /** 注入 fetch，用于测试。 */
+    fetch?: typeof fetch;
+}
+export declare class ProxyConfigurationError extends Error {
+    constructor(message: string);
+}
+/** 代理判定的结果：要么放行并给出该发的请求，要么拒绝并给出该回的状态。 */
+export type ProxyDecision = {
+    ok: true;
+    request: Request;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+};
+/**
+ * 把一条进来的请求判定成「转发什么」或「拒绝」。
+ *
+ * 这个函数不碰网络，所以各框架适配器共用它，测试也能直接断言判定结果，
+ * 不必起一个真的 HTTP 服务。
+ */
+export declare function decide(incoming: Request, options?: ProxyOptions): ProxyDecision;
+/**
+ * 通用处理器：吃一条 `Request`，回一条 `Response`。
+ *
+ * 各框架适配器只负责把自己的请求对象转成 `Request`，判定与转发都在这里。
+ */
+export declare function createProxyHandler(options?: ProxyOptions): (incoming: Request) => Promise<Response>;
+//# sourceMappingURL=core.d.ts.map

package/dist/src/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,qCAAqC;AACrC,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD,mCAAmC;AACnC,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AA8BtD,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qBAAqB;IACrB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED,yCAAyC;AACzC,MAAM,MAAM,aAAa,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAkBlF;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAE,YAAiB,GAAG,aAAa,CAgDnF;AAUD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,YAAiB,IAI9B,UAAU,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAmBnE"}

package/dist/src/core.js

@@ -0,0 +1,164 @@
+/**
+ * 服务端代理：让客户端应用在**不持有 API 密钥**的前提下调用 SpicyAPI。
+ *
+ * 浏览器里的 JS、iOS / Android 应用、桌面应用——这些地方都放不住密钥。打进包里的
+ * 密钥等于公开的密钥：攻击者反编译或抓一次包就能拿到，然后一直花到余额见底，而
+ * 我们这边看到的只是「这个账号今天用得有点多」。
+ *
+ * 正确的形状是：客户端把请求打到**调用方自己的服务器**，由那一层补上密钥再转发。
+ * 这个模块就是那一层，装在调用方的 Next.js / Express / 任意 fetch 运行时里。
+ *
+ * ── 协议 ───────────────────────────────────────────────────────────
+ *
+ * 客户端把目标地址放进 `x-spicy-target-url` 头，打到自己后端约定的那条路由
+ * （惯例是 `/api/spicy/proxy`）。代理校验目标、补上 `Authorization`、转发，
+ * 再把响应原样回给客户端。
+ *
+ * ── 为什么目标地址必须白名单，而不是「转发到头里写的任何地址」 ──────
+ *
+ * 这是整个设计里唯一会造成灾难的地方。不校验的话，任何人往那个头里填
+ * `https://attacker.example` 就能让**你的服务器把你的密钥发给他**——一个
+ * 请求就泄露，而且流量看起来完全正常：是你自己的服务器发出去的。
+ *
+ * 所以 `allowedOrigins` 默认只有 `https://api.spicyapi.ai`，而且是**精确的
+ * origin 比较**，不是前缀匹配：`https://api.spicyapi.ai.attacker.example`
+ * 的前缀也是我们的域名。
+ */
+/** 承载目标地址的请求头。全小写，HTTP/2 只接受小写头名。 */
+export const TARGET_URL_HEADER = "x-spicy-target-url";
+/** 惯例路由。不是强制的，但保持一致能让前端的配置可以照抄。 */
+export const DEFAULT_PROXY_ROUTE = "/api/spicy/proxy";
+/** 平台唯一的生产入口。 */
+const DEFAULT_ALLOWED_ORIGIN = "https://api.spicyapi.ai";
+/**
+ * 逐跳头：它们描述的是**这一段连接**，不是这条消息，转发出去没有意义且可能有害。
+ * 见 RFC 9110 §7.6.1。`host` 另算——它必须按目标重新计算，照抄会把源站打糊涂。
+ */
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "host",
+    "content-length",
+]);
+/**
+ * 客户端送来的这些头一律**丢弃**，不允许它影响我们替它做的鉴权决定。
+ *
+ * `authorization` 尤其要紧：不丢的话，客户端可以自带一个头覆盖掉我们补的那个，
+ * 把代理变成一个替任意密钥转发的开放中继。
+ */
+const CLIENT_CONTROLLED = new Set(["authorization", "cookie", "x-api-key"]);
+export class ProxyConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProxyConfigurationError";
+    }
+}
+function resolveKey(options) {
+    const raw = typeof options.apiKey === "function" ? options.apiKey() : options.apiKey;
+    const key = (raw ?? process.env.SPICY_API_KEY)?.trim();
+    return key || undefined;
+}
+function allowed(options) {
+    const list = options.allowedOrigins ?? [DEFAULT_ALLOWED_ORIGIN];
+    if (list.length === 0) {
+        throw new ProxyConfigurationError("allowedOrigins must not be empty; an empty list would forward your API key anywhere");
+    }
+    return list;
+}
+/**
+ * 把一条进来的请求判定成「转发什么」或「拒绝」。
+ *
+ * 这个函数不碰网络，所以各框架适配器共用它，测试也能直接断言判定结果，
+ * 不必起一个真的 HTTP 服务。
+ */
+export function decide(incoming, options = {}) {
+    const target = incoming.headers.get(TARGET_URL_HEADER);
+    if (!target) {
+        return { ok: false, status: 400, message: `missing ${TARGET_URL_HEADER} header` };
+    }
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        return { ok: false, status: 400, message: `${TARGET_URL_HEADER} is not a valid absolute URL` };
+    }
+    // 精确 origin 比较。前缀匹配会把 https://api.spicyapi.ai.attacker.example 放进来。
+    if (!allowed(options).includes(url.origin)) {
+        return { ok: false, status: 403, message: `target origin is not allowed: ${url.origin}` };
+    }
+    const key = resolveKey(options);
+    if (!key) {
+        // 这是部署问题，不是调用方的错，所以不要把它说成 4xx。
+        return { ok: false, status: 500, message: "the proxy has no SpicyAPI key configured" };
+    }
+    const headers = new Headers();
+    for (const [name, value] of incoming.headers) {
+        const lower = name.toLowerCase();
+        if (lower === TARGET_URL_HEADER)
+            continue;
+        if (HOP_BY_HOP.has(lower))
+            continue;
+        if (CLIENT_CONTROLLED.has(lower))
+            continue;
+        headers.set(name, value);
+    }
+    headers.set("authorization", `Bearer ${key}`);
+    return {
+        ok: true,
+        request: new Request(url, {
+            method: incoming.method,
+            headers,
+            body: incoming.body,
+            // 转发的是一条新请求，不该继承调用方的重定向策略。
+            redirect: "manual",
+            // Node 的 undici 要求带流式 body 时显式声明 duplex。它不在标准的
+            // RequestInit 里，所以单独断言这一小块，而不是把整个字面量断言成
+            // RequestInit——那样会把上面每个字段的类型检查一起关掉。
+            ...(incoming.body ? { duplex: "half" } : {}),
+        }),
+    };
+}
+/** 回一条拒绝响应。形状与平台的错误信封一致，客户端不必为代理另写一套解析。 */
+function refuse(status, message) {
+    return new Response(JSON.stringify({ code: status, msg: message, request_id: null }), {
+        status,
+        headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
+    });
+}
+/**
+ * 通用处理器：吃一条 `Request`，回一条 `Response`。
+ *
+ * 各框架适配器只负责把自己的请求对象转成 `Request`，判定与转发都在这里。
+ */
+export function createProxyHandler(options = {}) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    return async function handle(incoming) {
+        const decision = decide(incoming, options);
+        if (!decision.ok)
+            return refuse(decision.status, decision.message);
+        let upstream;
+        try {
+            upstream = await doFetch(decision.request, { signal: AbortSignal.timeout(timeoutMs) });
+        }
+        catch {
+            // 不把上游的原始错误回给客户端：它可能带着内部主机名。
+            return refuse(504, "the upstream request did not complete in time");
+        }
+        const headers = new Headers();
+        for (const [name, value] of upstream.headers) {
+            if (HOP_BY_HOP.has(name.toLowerCase()))
+                continue;
+            headers.set(name, value);
+        }
+        return new Response(upstream.body, { status: upstream.status, headers });
+    };
+}
+//# sourceMappingURL=core.js.map

package/dist/src/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"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"}

package/dist/src/express.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Express 适配器。
+ *
+ * ```ts
+ * app.all("/api/spicy/proxy", createExpressHandler());
+ * ```
+ *
+ * Express 的 req/res 是 Node 的流，不是 fetch 的 `Request`/`Response`，
+ * 所以这一层做的全部事情就是两边互转，判定与转发仍在 core 里。
+ *
+ * **不要在这条路由前面挂 body 解析中间件**（`express.json()` 之类）：那会把
+ * 请求体读干净，转发出去的就是一条空 body 的请求，而错误发生在上游——表现是
+ * 「参数缺失」，指不到中间件顺序上。要么把代理挂在解析器之前，要么对这条路径跳过。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type ProxyOptions } from "./core.js";
+type ExpressLike = IncomingMessage & {
+    originalUrl?: string;
+    body?: unknown;
+};
+export declare function createExpressHandler(options?: ProxyOptions): (req: ExpressLike, res: ServerResponse, next?: (error?: unknown) => void) => Promise<void>;
+export {};
+//# sourceMappingURL=express.d.ts.map

package/dist/src/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/express.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGjE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAElE,KAAK,WAAW,GAAG,eAAe,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE9E,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,YAAiB,IAI3D,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,KAC/B,OAAO,CAAC,IAAI,CAAC,CAmCjB"}

package/dist/src/express.js

@@ -0,0 +1,39 @@
+import { Readable } from "node:stream";
+import { createProxyHandler } from "./core.js";
+export function createExpressHandler(options = {}) {
+    const handle = createProxyHandler(options);
+    return async function middleware(req, res, next) {
+        try {
+            const headers = new Headers();
+            for (const [name, value] of Object.entries(req.headers)) {
+                if (value === undefined)
+                    continue;
+                headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+            }
+            const hasBody = req.method !== "GET" && req.method !== "HEAD";
+            const response = await handle(new Request(`http://proxy.invalid${req.originalUrl ?? req.url ?? "/"}`, {
+                method: req.method,
+                headers,
+                ...(hasBody ? { body: Readable.toWeb(req), duplex: "half" } : {}),
+            }));
+            res.statusCode = response.status;
+            response.headers.forEach((value, name) => res.setHeader(name, value));
+            if (response.body) {
+                const nodeStream = Readable.fromWeb(response.body);
+                nodeStream.pipe(res);
+            }
+            else {
+                res.end();
+            }
+        }
+        catch (error) {
+            if (next)
+                next(error);
+            else {
+                res.statusCode = 500;
+                res.end();
+            }
+        }
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/src/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/express.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,kBAAkB,EAAqB,MAAM,WAAW,CAAC;AAIlE,MAAM,UAAU,oBAAoB,CAAC,UAAwB,EAAE;IAC7D,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAE3C,OAAO,KAAK,UAAU,UAAU,CAC9B,GAAgB,EAChB,GAAmB,EACnB,IAAgC;QAEhC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;YAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxD,IAAI,KAAK,KAAK,SAAS;oBAAE,SAAS;gBAClC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YACrE,CAAC;YAED,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC;YAC9D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAC3B,IAAI,OAAO,CAAC,uBAAuB,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,EAAE;gBACtE,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,OAAO;gBACP,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAmB,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACrE,CAAC,CAClB,CAAC;YAEF,GAAG,CAAC,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;YACjC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;YACtE,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;gBAClB,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CACjC,QAAQ,CAAC,IAA8C,CACxD,CAAC;gBACF,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,GAAG,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,IAAI;gBAAE,IAAI,CAAC,KAAK,CAAC,CAAC;iBACjB,CAAC;gBACJ,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC;gBACrB,GAAG,CAAC,GAAG,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { createProxyHandler, decide, ProxyConfigurationError, DEFAULT_PROXY_ROUTE, TARGET_URL_HEADER, type ProxyDecision, type ProxyOptions, } from "./core.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,MAAM,EACN,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,WAAW,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { createProxyHandler, decide, ProxyConfigurationError, DEFAULT_PROXY_ROUTE, TARGET_URL_HEADER, } from "./core.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,MAAM,EACN,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,GAGlB,MAAM,WAAW,CAAC"}

package/dist/src/nextjs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Next.js 适配器。
+ *
+ * App Router：把 `route` 原样导出成路由的方法处理器即可。
+ *
+ * ```ts
+ * // app/api/spicy/proxy/route.ts
+ * export const { GET, POST, PUT, DELETE } = route;
+ * export const runtime = "nodejs"; // 见下
+ * ```
+ *
+ * **`runtime` 要显式写 `nodejs`**：边缘运行时读不到 `process.env` 里那些只在
+ * 服务端配置的值，而密钥恰恰住在那里。默认跑在边缘的项目会在部署之后才发现
+ * 这一点——那时表现是代理回 500「没有配置密钥」，而本地一切正常。
+ */
+import { type ProxyOptions } from "./core.js";
+/** App Router：`export const { POST } = route` 就能用。 */
+export declare function createRoute(options?: ProxyOptions): {
+    GET: (incoming: Request) => Promise<Response>;
+    POST: (incoming: Request) => Promise<Response>;
+    PUT: (incoming: Request) => Promise<Response>;
+    PATCH: (incoming: Request) => Promise<Response>;
+    DELETE: (incoming: Request) => Promise<Response>;
+};
+/** 默认配置的 App Router 路由，密钥取自 `SPICY_API_KEY`。 */
+export declare const route: {
+    GET: (incoming: Request) => Promise<Response>;
+    POST: (incoming: Request) => Promise<Response>;
+    PUT: (incoming: Request) => Promise<Response>;
+    PATCH: (incoming: Request) => Promise<Response>;
+    DELETE: (incoming: Request) => Promise<Response>;
+};
+//# sourceMappingURL=nextjs.d.ts.map

package/dist/src/nextjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.d.ts","sourceRoot":"","sources":["../../src/nextjs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAElE,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,OAAO,GAAE,YAAiB;;;;;;EAGrD;AAED,gDAAgD;AAChD,eAAO,MAAM,KAAK;;;;;;CAAgB,CAAC"}

package/dist/src/nextjs.js

@@ -0,0 +1,24 @@
+/**
+ * Next.js 适配器。
+ *
+ * App Router：把 `route` 原样导出成路由的方法处理器即可。
+ *
+ * ```ts
+ * // app/api/spicy/proxy/route.ts
+ * export const { GET, POST, PUT, DELETE } = route;
+ * export const runtime = "nodejs"; // 见下
+ * ```
+ *
+ * **`runtime` 要显式写 `nodejs`**：边缘运行时读不到 `process.env` 里那些只在
+ * 服务端配置的值，而密钥恰恰住在那里。默认跑在边缘的项目会在部署之后才发现
+ * 这一点——那时表现是代理回 500「没有配置密钥」，而本地一切正常。
+ */
+import { createProxyHandler } from "./core.js";
+/** App Router：`export const { POST } = route` 就能用。 */
+export function createRoute(options = {}) {
+    const handle = createProxyHandler(options);
+    return { GET: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle };
+}
+/** 默认配置的 App Router 路由，密钥取自 `SPICY_API_KEY`。 */
+export const route = createRoute();
+//# sourceMappingURL=nextjs.js.map

package/dist/src/nextjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.js","sourceRoot":"","sources":["../../src/nextjs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,kBAAkB,EAAqB,MAAM,WAAW,CAAC;AAElE,sDAAsD;AACtD,MAAM,UAAU,WAAW,CAAC,UAAwB,EAAE;IACpD,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACnF,CAAC;AAED,gDAAgD;AAChD,MAAM,CAAC,MAAM,KAAK,GAAG,WAAW,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@spicyapi/proxy",
+  "version": "0.1.0",
+  "description": "Server-side proxy for SpicyAPI: let browser, mobile and desktop apps call the API without ever holding an API key.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SpicyAPI/spicy-devkit.git",
+    "directory": "packages/proxy"
+  },
+  "homepage": "https://spicyapi.ai",
+  "bugs": {
+    "url": "https://spicyapi.ai/contact"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./nextjs": {
+      "types": "./dist/src/nextjs.d.ts",
+      "import": "./dist/src/nextjs.js"
+    },
+    "./express": {
+      "types": "./dist/src/express.d.ts",
+      "import": "./dist/src/express.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}