@iflow-ai/search-openapi 0.1.0-pre.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iFlow AI
+
+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,248 @@
+# @iflow-ai/search-openapi
+
+> HTTP / OpenAPI tool server for [iFlow Search](https://platform.iflow.cn) — exposes web search, image search, and web fetch as JSON-over-HTTP endpoints for **Open WebUI**, **Coze**, and other agent platforms that consume an OpenAPI 3.x document.
+
+Built on [`@iflow-ai/search-core`](../search-core). Same three tools as
+[`@iflow-ai/search-langchain`](../search-langchain) and
+[`@iflow-ai/search-mcp`](../search-mcp) — same names, same shapes, same
+attribution — so prompts that drive an iFlow-search-tool agent under one
+runtime keep working verbatim under another.
+
+## Status — MVP (`0.1.0-pre.0`)
+
+- **Transport:** HTTP only. Plain JSON request / response. No SSE, no
+  WebSocket. The MVP uses Node's built-in `http` module — no Express,
+  Fastify, or Koa dependency.
+- **Endpoints:**
+  - `GET /health` — liveness probe. Never gated by the bearer guard.
+  - `GET /openapi.json` — OpenAPI 3.1 document for tool catalogs.
+  - `POST /tools/iflow_web_search`
+  - `POST /tools/iflow_image_search`
+  - `POST /tools/iflow_web_fetch`
+- **Configuration:** environment variables only, supplied by your
+  deployment (Docker `-e`, systemd `Environment=`, your platform's
+  secret manager). The process never reads from disk.
+
+## Install & run
+
+```bash
+# One-shot, no install — pulls the published @next tag:
+IFLOW_API_KEY=YOUR_IFLOW_API_KEY \
+  npx -y @iflow-ai/search-openapi@next
+```
+
+Or pin it as a dependency:
+
+```bash
+pnpm add @iflow-ai/search-openapi
+# or
+npm install @iflow-ai/search-openapi
+
+iflow-search-openapi
+```
+
+Node ≥ 18. The server binds to `0.0.0.0:8787` by default; override with
+`PORT`.
+
+> **Do not commit a real key.** Use `YOUR_IFLOW_API_KEY` everywhere you'd
+> normally write the value and inject the real one at runtime via your
+> platform's secret store. `@iflow-ai/search-openapi` never reads from
+> disk and will not pick up a `.env` automatically.
+
+## Configuration
+
+All configuration is read from `process.env`.
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `IFLOW_API_KEY` | yes | — | Bearer token sent to iFlow as `Authorization: Bearer ...`. |
+| `IFLOW_BASE_URL` | no | `https://platform.iflow.cn` | Override for testing / private deployments. |
+| `IFLOW_TIMEOUT_MS` | no | `30000` | Per-request timeout in ms. Must be a positive integer if set. |
+| `PORT` | no | `8787` | TCP port to listen on. Must be an integer in `[0, 65535]`. |
+| `IFLOW_OPENAPI_AUTH_TOKEN` | no | — | When set, every endpoint **except** `/health` requires `Authorization: Bearer <token>`. Constant-time compared. Absent = open mode (no auth gate). |
+| `IFLOW_OPENAPI_CLIENT` | no | — | Identifies the host platform (`open-webui`, `coze`, …). Allowed: `[a-z0-9._-]{1,64}`. Captured into the startup banner; not forwarded to iFlow today. |
+
+A missing or invalid configuration is a fatal init error: the process
+writes a one-line diagnostic to **stderr** and exits with code `1`.
+
+## Curl smoke test
+
+With the server running locally (open mode):
+
+```bash
+# Liveness
+curl -s http://127.0.0.1:8787/health
+
+# Tool catalog
+curl -s http://127.0.0.1:8787/openapi.json | jq '.paths | keys'
+
+# Web search
+curl -s -X POST http://127.0.0.1:8787/tools/iflow_web_search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"site:nytimes.com OpenAI","count":3}' | jq .
+
+# Image search
+curl -s -X POST http://127.0.0.1:8787/tools/iflow_image_search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"snow leopard","count":3}' | jq .
+
+# Web fetch
+curl -s -X POST http://127.0.0.1:8787/tools/iflow_web_fetch \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://zh.wikipedia.org/wiki/%E8%A5%BF%E6%B9%96"}' | jq .
+```
+
+With `IFLOW_OPENAPI_AUTH_TOKEN` set, add the bearer header to every call
+except `/health`:
+
+```bash
+curl -s -X POST http://127.0.0.1:8787/tools/iflow_web_search \
+  -H 'Authorization: Bearer YOUR_OPENAPI_AUTH_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"hello"}'
+```
+
+## Response shapes
+
+Success:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "query": "...",
+    "count": 3,
+    "tookMs": 412,
+    "results": [
+      { "title": "...", "url": "...", "snippet": "...", "position": 1, "date": null }
+    ]
+  }
+}
+```
+
+Error (uniform across all routes):
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "invalid_param",
+    "message": "Parameter \"query\" is required.",
+    "status": 400
+  }
+}
+```
+
+Error codes come straight from `@iflow-ai/search-core`: `missing_api_key`,
+`missing_param`, `invalid_param`, `network_timeout`, `network_error`,
+`api_error`, `api_business_error`. The server adds three HTTP-level codes
+for problems before a tool ever runs: `unauthorized`,
+`method_not_allowed`, `not_found`, `invalid_input`, `payload_too_large`.
+
+For `api_error`, iFlow's upstream HTTP status (401 / 403 / 429 / 5xx) is
+preserved on the response so platforms can react to rate limits or auth
+failures correctly.
+
+## Open WebUI
+
+Open WebUI consumes OpenAPI tool servers directly. After starting
+`iflow-search-openapi` somewhere it can reach (Docker compose, k8s, a
+sidecar, or `npx` on the same host):
+
+1. **Settings → Tools → Add → OpenAPI URL.**
+2. URL: `http://<host>:8787/openapi.json`.
+3. If you launched the server with `IFLOW_OPENAPI_AUTH_TOKEN` set, paste
+   the same token into Open WebUI's *Bearer Token* field for the tool.
+   Leave blank for open mode.
+4. Save. The three `iflow_*` tools appear in the chat tool picker.
+
+A typical Docker Compose service:
+
+```yaml
+services:
+  iflow-search-openapi:
+    image: node:20-alpine
+    command: npx -y @iflow-ai/search-openapi@next
+    environment:
+      IFLOW_API_KEY: YOUR_IFLOW_API_KEY
+      IFLOW_OPENAPI_AUTH_TOKEN: YOUR_OPENAPI_AUTH_TOKEN
+      IFLOW_OPENAPI_CLIENT: open-webui
+    ports:
+      - "8787:8787"
+```
+
+Then in Open WebUI:
+
+- URL: `http://iflow-search-openapi:8787/openapi.json` (or
+  `http://localhost:8787/openapi.json` if you're running Open WebUI on
+  the host)
+- Bearer Token: the value of `IFLOW_OPENAPI_AUTH_TOKEN`
+
+## Coze (custom tool / plugin)
+
+Coze can register an external tool from an OpenAPI 3.x document:
+
+1. **Plugins → Create plugin → Import from OpenAPI.**
+2. URL: `https://<your-host>/openapi.json`.
+3. Authentication: *Bearer Token*. Paste the value of
+   `IFLOW_OPENAPI_AUTH_TOKEN` if set; leave blank for open mode.
+4. Select all three tools to expose to the agent.
+
+For Coze you generally need a publicly reachable URL — terminate TLS in
+front of the server (Caddy, Nginx, your platform's load balancer) and
+keep `IFLOW_OPENAPI_AUTH_TOKEN` non-empty so the endpoint is not open
+to the internet.
+
+## Programmatic API
+
+The package also exports the building blocks so you can embed the
+listener in a larger HTTP app or drive it from integration tests:
+
+```ts
+import { createIFlowSearchClient } from "@iflow-ai/search-core";
+import { createApp } from "@iflow-ai/search-openapi";
+import { createServer } from "node:http";
+
+const client = createIFlowSearchClient({
+  apiKey: process.env.IFLOW_API_KEY!,
+  source: "openapi",
+  integrationName: "@iflow-ai/search-openapi",
+  integrationVersion: "0.1.0-pre.0",
+});
+
+const app = createApp({ client, authToken: process.env.IFLOW_OPENAPI_AUTH_TOKEN });
+createServer(app).listen(8787);
+```
+
+## What this package does NOT do
+
+The MVP is deliberately small. The following are explicit non-goals for
+this release:
+
+- No TLS termination. Put a reverse proxy in front for production.
+- No per-platform packages (`@iflow-ai/search-open-webui`,
+  `@iflow-ai/search-coze`, …). One generic OpenAPI server covers them
+  all by design.
+- No streaming responses, no SSE, no WebSocket.
+- No multi-tenant hosting, no per-call API-key override.
+- No bundled prompts or resources — only the three search tools.
+
+## Attribution
+
+Every outbound request to iFlow carries:
+
+```
+IFlow-Source: openapi
+IFlow-Integration: @iflow-ai/search-openapi
+IFlow-Integration-Version: <pkg version>
+User-Agent: @iflow-ai/search-openapi/<pkg version>
+```
+
+`IFLOW_OPENAPI_CLIENT` is **not** forwarded as `IFlow-MCP-Client` — that
+header is reserved for MCP transports. It is kept in the startup banner
+so operators can confirm which platform a given deployment is intended
+to serve.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bearer-token auth for the HTTP server.
+ *
+ * Behavior:
+ *   - If no `expectedToken` is configured, every request is allowed (open mode).
+ *   - If `expectedToken` is set, the request must carry
+ *     `Authorization: Bearer <expectedToken>`. Tokens are compared
+ *     with timing-safe equality to remove the obvious side-channel.
+ *
+ * The /health route is checked separately by server.ts; this module
+ * does not know about route semantics.
+ */
+export type AuthCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: 401;
+    code: "unauthorized";
+    message: string;
+};
+export declare function checkBearer(authorizationHeader: string | undefined, expectedToken: string | undefined): AuthCheckResult;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE,wBAAgB,WAAW,CACzB,mBAAmB,EAAE,MAAM,GAAG,SAAS,EACvC,aAAa,EAAE,MAAM,GAAG,SAAS,GAChC,eAAe,CA+CjB"}

package/dist/auth.js

@@ -0,0 +1,68 @@
+/**
+ * Bearer-token auth for the HTTP server.
+ *
+ * Behavior:
+ *   - If no `expectedToken` is configured, every request is allowed (open mode).
+ *   - If `expectedToken` is set, the request must carry
+ *     `Authorization: Bearer <expectedToken>`. Tokens are compared
+ *     with timing-safe equality to remove the obvious side-channel.
+ *
+ * The /health route is checked separately by server.ts; this module
+ * does not know about route semantics.
+ */
+import { timingSafeEqual } from "node:crypto";
+export function checkBearer(authorizationHeader, expectedToken) {
+    if (!expectedToken) {
+        return { ok: true };
+    }
+    const raw = (authorizationHeader ?? "").trim();
+    if (!raw) {
+        return {
+            ok: false,
+            status: 401,
+            code: "unauthorized",
+            message: 'Missing Authorization header. Send "Authorization: Bearer <token>".',
+        };
+    }
+    const match = /^Bearer\s+(.+)$/i.exec(raw);
+    if (!match) {
+        return {
+            ok: false,
+            status: 401,
+            code: "unauthorized",
+            message: "Authorization header must be of form `Bearer <token>`.",
+        };
+    }
+    const provided = (match[1] ?? "").trim();
+    if (!provided) {
+        return {
+            ok: false,
+            status: 401,
+            code: "unauthorized",
+            message: "Bearer token is empty.",
+        };
+    }
+    if (!safeEqual(provided, expectedToken)) {
+        return {
+            ok: false,
+            status: 401,
+            code: "unauthorized",
+            message: "Invalid bearer token.",
+        };
+    }
+    return { ok: true };
+}
+function safeEqual(a, b) {
+    const aBuf = Buffer.from(a, "utf8");
+    const bBuf = Buffer.from(b, "utf8");
+    if (aBuf.length !== bBuf.length) {
+        // Still do a constant-time compare on equal-length buffers to avoid
+        // leaking length differences via timing — compare two identical
+        // throwaway buffers so we always do the same amount of work.
+        const dummy = Buffer.alloc(aBuf.length);
+        timingSafeEqual(aBuf, dummy);
+        return false;
+    }
+    return timingSafeEqual(aBuf, bBuf);
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAM9C,MAAM,UAAU,WAAW,CACzB,mBAAuC,EACvC,aAAiC;IAEjC,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,MAAM,GAAG,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,cAAc;YACpB,OAAO,EACL,qEAAqE;SACxE,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,cAAc;YACpB,OAAO,EACL,wDAAwD;SAC3D,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,wBAAwB;SAClC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,CAAC;QACxC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,uBAAuB;SACjC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,SAAS,CAAC,CAAS,EAAE,CAAS;IACrC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,oEAAoE;QACpE,gEAAgE;QAChE,6DAA6D;QAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxC,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/bin.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * `iflow-search-openapi` — HTTP/OpenAPI tool server for the iFlow Search API.
+ *
+ * Spawned as a regular Node process; listens on PORT (default 8787) and
+ * answers HTTP. Intended for Open WebUI / Coze and other OpenAPI 3.x
+ * tool hosts.
+ *
+ * stderr is used for the startup banner and shutdown messages. The server
+ * itself does not log per-request lines — platforms typically want to do
+ * that in front via a reverse proxy.
+ *
+ * Exit codes:
+ *   0 — clean shutdown after SIGINT / SIGTERM
+ *   1 — configuration error or listener failure
+ *
+ * Attribution: source=`openapi`, integration=`@iflow-ai/search-openapi`.
+ * IFLOW_OPENAPI_CLIENT is captured into `clientName` for local visibility
+ * (printed in the banner) but is intentionally NOT forwarded to
+ * createIFlowSearchClient — the `IFlow-MCP-Client` header is reserved for
+ * MCP hosts and reusing it from a non-MCP transport would muddy analytics.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/bin.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * `iflow-search-openapi` — HTTP/OpenAPI tool server for the iFlow Search API.
+ *
+ * Spawned as a regular Node process; listens on PORT (default 8787) and
+ * answers HTTP. Intended for Open WebUI / Coze and other OpenAPI 3.x
+ * tool hosts.
+ *
+ * stderr is used for the startup banner and shutdown messages. The server
+ * itself does not log per-request lines — platforms typically want to do
+ * that in front via a reverse proxy.
+ *
+ * Exit codes:
+ *   0 — clean shutdown after SIGINT / SIGTERM
+ *   1 — configuration error or listener failure
+ *
+ * Attribution: source=`openapi`, integration=`@iflow-ai/search-openapi`.
+ * IFLOW_OPENAPI_CLIENT is captured into `clientName` for local visibility
+ * (printed in the banner) but is intentionally NOT forwarded to
+ * createIFlowSearchClient — the `IFlow-MCP-Client` header is reserved for
+ * MCP hosts and reusing it from a non-MCP transport would muddy analytics.
+ */
+import { createServer } from "node:http";
+import { createIFlowSearchClient } from "@iflow-ai/search-core";
+import { ConfigError, loadConfig } from "./config.js";
+import { createApp } from "./server.js";
+import { INTEGRATION_NAME, SOURCE, VERSION } from "./version.js";
+async function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            process.stderr.write(`[${INTEGRATION_NAME}] ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const client = createIFlowSearchClient({
+        apiKey: config.apiKey,
+        baseUrl: config.baseUrl,
+        timeoutMs: config.timeoutMs,
+        source: SOURCE,
+        integrationName: INTEGRATION_NAME,
+        integrationVersion: VERSION,
+    });
+    const app = createApp({
+        client,
+        authToken: config.authToken,
+    });
+    const httpServer = createServer(app);
+    const shutdown = (signal) => {
+        process.stderr.write(`[${INTEGRATION_NAME}] received ${signal}, closing.\n`);
+        httpServer.close((err) => {
+            if (err) {
+                process.stderr.write(`[${INTEGRATION_NAME}] error during shutdown: ${err.message}\n`);
+                process.exit(1);
+            }
+            process.exit(0);
+        });
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    httpServer.on("error", (err) => {
+        process.stderr.write(`[${INTEGRATION_NAME}] listen error: ${err.message}\n`);
+        process.exit(1);
+    });
+    httpServer.listen(config.port, () => {
+        const address = httpServer.address();
+        const boundPort = typeof address === "object" && address !== null ? address.port : config.port;
+        const authNote = config.authToken
+            ? "bearer auth ENABLED"
+            : "bearer auth DISABLED (open mode)";
+        const clientNote = config.clientName ? ` client=${config.clientName}` : "";
+        process.stderr.write(`[${INTEGRATION_NAME}] v${VERSION} listening on http://0.0.0.0:${boundPort} — ${authNote}${clientNote}\n`);
+    });
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[${INTEGRATION_NAME}] fatal: ${message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Env-only configuration for the iFlow Search OpenAPI server.
+ *
+ *   IFLOW_API_KEY              (required) — forwarded to search-core, sent as Authorization: Bearer ...
+ *   IFLOW_BASE_URL             (optional) — defaults to search-core's default
+ *   IFLOW_TIMEOUT_MS           (optional) — positive integer milliseconds
+ *   PORT                       (optional) — listen port, defaults to 8787
+ *   IFLOW_OPENAPI_AUTH_TOKEN   (optional) — if set, all routes except /health require
+ *                                            `Authorization: Bearer <token>`. Token is
+ *                                            checked with constant-time comparison.
+ *   IFLOW_OPENAPI_CLIENT       (optional) — identifies the host platform (open-webui,
+ *                                            coze, ...). Allowed: [a-z0-9._-]{1,64}.
+ *                                            Not currently wired into a wire header — kept
+ *                                            for future platform attribution. Stored on
+ *                                            ResolvedConfig.clientName so server.ts and
+ *                                            tests can observe it.
+ *
+ * Errors thrown here are init-time fatal: bin.ts prints them to stderr
+ * and exits non-zero BEFORE the HTTP listener is wired up.
+ */
+export declare const DEFAULT_PORT = 8787;
+export interface ResolvedConfig {
+    apiKey: string;
+    baseUrl: string | undefined;
+    timeoutMs: number | undefined;
+    port: number;
+    authToken: string | undefined;
+    clientName: string | undefined;
+}
+export interface EnvLike {
+    IFLOW_API_KEY?: string | undefined;
+    IFLOW_BASE_URL?: string | undefined;
+    IFLOW_TIMEOUT_MS?: string | undefined;
+    PORT?: string | undefined;
+    IFLOW_OPENAPI_AUTH_TOKEN?: string | undefined;
+    IFLOW_OPENAPI_CLIENT?: string | undefined;
+}
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function loadConfig(env?: EnvLike): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,OAAO;IACtB,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAID,wBAAgB,UAAU,CAAC,GAAG,GAAE,OAAqB,GAAG,cAAc,CAwDrE"}

package/dist/config.js

@@ -0,0 +1,70 @@
+/**
+ * Env-only configuration for the iFlow Search OpenAPI server.
+ *
+ *   IFLOW_API_KEY              (required) — forwarded to search-core, sent as Authorization: Bearer ...
+ *   IFLOW_BASE_URL             (optional) — defaults to search-core's default
+ *   IFLOW_TIMEOUT_MS           (optional) — positive integer milliseconds
+ *   PORT                       (optional) — listen port, defaults to 8787
+ *   IFLOW_OPENAPI_AUTH_TOKEN   (optional) — if set, all routes except /health require
+ *                                            `Authorization: Bearer <token>`. Token is
+ *                                            checked with constant-time comparison.
+ *   IFLOW_OPENAPI_CLIENT       (optional) — identifies the host platform (open-webui,
+ *                                            coze, ...). Allowed: [a-z0-9._-]{1,64}.
+ *                                            Not currently wired into a wire header — kept
+ *                                            for future platform attribution. Stored on
+ *                                            ResolvedConfig.clientName so server.ts and
+ *                                            tests can observe it.
+ *
+ * Errors thrown here are init-time fatal: bin.ts prints them to stderr
+ * and exits non-zero BEFORE the HTTP listener is wired up.
+ */
+export const DEFAULT_PORT = 8787;
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+const CLIENT_NAME_PATTERN = /^[a-z0-9._-]{1,64}$/u;
+export function loadConfig(env = process.env) {
+    const apiKey = (env.IFLOW_API_KEY ?? "").trim();
+    if (!apiKey) {
+        throw new ConfigError("IFLOW_API_KEY is required. Set it in your environment, e.g. " +
+            "IFLOW_API_KEY=YOUR_IFLOW_API_KEY. Never commit the real key.");
+    }
+    const rawBase = env.IFLOW_BASE_URL?.trim();
+    const baseUrl = rawBase && rawBase.length > 0 ? rawBase : undefined;
+    const rawTimeout = env.IFLOW_TIMEOUT_MS?.trim();
+    let timeoutMs;
+    if (rawTimeout && rawTimeout.length > 0) {
+        const parsed = Number(rawTimeout);
+        if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
+            throw new ConfigError(`IFLOW_TIMEOUT_MS must be a positive integer (milliseconds). Got: ${JSON.stringify(rawTimeout)}.`);
+        }
+        timeoutMs = parsed;
+    }
+    const rawPort = env.PORT?.trim();
+    let port = DEFAULT_PORT;
+    if (rawPort && rawPort.length > 0) {
+        const parsed = Number(rawPort);
+        if (!Number.isFinite(parsed) ||
+            !Number.isInteger(parsed) ||
+            parsed < 0 ||
+            parsed > 65535) {
+            throw new ConfigError(`PORT must be an integer in [0, 65535]. Got: ${JSON.stringify(rawPort)}.`);
+        }
+        port = parsed;
+    }
+    const rawToken = env.IFLOW_OPENAPI_AUTH_TOKEN?.trim();
+    const authToken = rawToken && rawToken.length > 0 ? rawToken : undefined;
+    const rawClient = env.IFLOW_OPENAPI_CLIENT?.trim();
+    let clientName;
+    if (rawClient && rawClient.length > 0) {
+        if (!CLIENT_NAME_PATTERN.test(rawClient)) {
+            throw new ConfigError(`IFLOW_OPENAPI_CLIENT must match [a-z0-9._-]{1,64}. Got: ${JSON.stringify(rawClient)}.`);
+        }
+        clientName = rawClient;
+    }
+    return { apiKey, baseUrl, timeoutMs, port, authToken, clientName };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HTTP error JSON shape used by every endpoint. The OpenAPI spec
+ * advertises the same shape so Open WebUI / Coze and other OpenAPI
+ * tool hosts can render errors uniformly.
+ *
+ * iFlow errors come pre-shaped from @iflow-ai/search-core (stable codes
+ * + messages). This module never re-derives codes — it just maps to
+ * HTTP status codes and JSON output.
+ *
+ * For api_error specifically, iFlow's own HTTP status (when present on
+ * `IFlowError.status`) wins over the default — that preserves the
+ * upstream 401 / 403 / 429 signal to clients who key off status codes.
+ */
+import type { IFlowError } from "@iflow-ai/search-core";
+export interface ErrorBody {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        status?: number;
+        detail?: unknown;
+    };
+}
+export declare function statusForIFlowError(error: IFlowError): number;
+export declare function iflowErrorToBody(error: IFlowError): ErrorBody;
+export declare function genericErrorBody(code: string, message: string): ErrorBody;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,uBAAuB,CAAC;AAExE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAYD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAU7D;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAW7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAEzE"}