@flash-tunnel/sdk 0.0.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flash-tunnel
+
+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,17 @@
+# @flash-tunnel/sdk
+
+面向程序化集成的 Tunnel SDK。它接收一个已经运行的本地 origin，负责启动 Cloudflare Tunnel、等待公网地址，并在停止时清理本次会话创建的资源。
+
+```ts
+import { startTunnel } from '@flash-tunnel/sdk'
+
+const session = await startTunnel({
+  localUrl: 'http://127.0.0.1:4317',
+  mode: 'quick'
+})
+
+console.log(session.publicUrl)
+await session.stop()
+```
+
+宿主程序负责本地服务、进程信号和业务协议；SDK 不安装全局信号处理器，也不依赖 CLI UI。运行仍然需要开发机安装 `cloudflared`。

package/dist/index.d.mts

@@ -0,0 +1,54 @@
+import { Emitter } from '@flash-tunnel/core';
+export { Emitter, PreviewSession } from '@flash-tunnel/core';
+import { TunnelMode, FlashTunnelEvents } from '@flash-tunnel/types';
+export { FlashTunnelEvents, TunnelMode } from '@flash-tunnel/types';
+
+interface EmbeddedTunnelOptions {
+    /** Origin URL already serving the local application. */
+    localUrl: string;
+    /** Working directory used for session state and diagnostics. */
+    cwd?: string;
+    mode?: Extract<TunnelMode, 'quick' | 'named'>;
+    /** Required for named tunnels. */
+    hostname?: string;
+    /** Required for named tunnels. */
+    zone?: string;
+    name?: string;
+    accountId?: string;
+    zoneId?: string;
+    apiToken?: string;
+    apiBase?: string;
+    cloudflaredPath?: string;
+    originRequest?: {
+        httpHostHeader?: string;
+        noTLSVerify?: boolean;
+    };
+    persist?: boolean;
+    keep?: boolean;
+    overwrite?: boolean;
+    autoStopAfterMs?: number;
+    verifyTimeoutMs?: number;
+    signal?: AbortSignal;
+    onLog?: (line: string, stream: 'stdout' | 'stderr') => void;
+}
+interface EmbeddedTunnelSession {
+    sessionId: string;
+    localUrl: string;
+    publicUrl: string;
+    hostname?: string;
+    expiresAt?: string;
+    events: Emitter<FlashTunnelEvents>;
+    exited: Promise<void>;
+    /** Stop cloudflared and remove resources owned by this session. */
+    stop: () => Promise<void>;
+}
+/**
+ * Start a tunnel for an already-running local origin.
+ *
+ * The caller owns the local server lifecycle. This API only owns cloudflared
+ * and any named-tunnel/DNS resources created for the session.
+ */
+declare function startTunnel(options: EmbeddedTunnelOptions): Promise<EmbeddedTunnelSession>;
+
+export { startTunnel };
+export type { EmbeddedTunnelOptions, EmbeddedTunnelSession };

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { Emitter } from '@flash-tunnel/core';
+export { Emitter, PreviewSession } from '@flash-tunnel/core';
+import { TunnelMode, FlashTunnelEvents } from '@flash-tunnel/types';
+export { FlashTunnelEvents, TunnelMode } from '@flash-tunnel/types';
+
+interface EmbeddedTunnelOptions {
+    /** Origin URL already serving the local application. */
+    localUrl: string;
+    /** Working directory used for session state and diagnostics. */
+    cwd?: string;
+    mode?: Extract<TunnelMode, 'quick' | 'named'>;
+    /** Required for named tunnels. */
+    hostname?: string;
+    /** Required for named tunnels. */
+    zone?: string;
+    name?: string;
+    accountId?: string;
+    zoneId?: string;
+    apiToken?: string;
+    apiBase?: string;
+    cloudflaredPath?: string;
+    originRequest?: {
+        httpHostHeader?: string;
+        noTLSVerify?: boolean;
+    };
+    persist?: boolean;
+    keep?: boolean;
+    overwrite?: boolean;
+    autoStopAfterMs?: number;
+    verifyTimeoutMs?: number;
+    signal?: AbortSignal;
+    onLog?: (line: string, stream: 'stdout' | 'stderr') => void;
+}
+interface EmbeddedTunnelSession {
+    sessionId: string;
+    localUrl: string;
+    publicUrl: string;
+    hostname?: string;
+    expiresAt?: string;
+    events: Emitter<FlashTunnelEvents>;
+    exited: Promise<void>;
+    /** Stop cloudflared and remove resources owned by this session. */
+    stop: () => Promise<void>;
+}
+/**
+ * Start a tunnel for an already-running local origin.
+ *
+ * The caller owns the local server lifecycle. This API only owns cloudflared
+ * and any named-tunnel/DNS resources created for the session.
+ */
+declare function startTunnel(options: EmbeddedTunnelOptions): Promise<EmbeddedTunnelSession>;
+
+export { startTunnel };
+export type { EmbeddedTunnelOptions, EmbeddedTunnelSession };

package/dist/index.mjs

@@ -0,0 +1,74 @@
+import process from 'node:process';
+import { createCloudflareTunnel, createCloudflareDns } from '@flash-tunnel/adapter-cloudflare';
+import { startPreviewSession } from '@flash-tunnel/core';
+
+function toConfig(options, mode) {
+  return {
+    server: { url: options.localUrl },
+    domain: {
+      zone: options.zone
+    },
+    tunnel: {
+      mode,
+      name: options.name
+    },
+    providers: {
+      cloudflare: {
+        accountId: options.accountId,
+        zoneId: options.zoneId,
+        cloudflaredPath: options.cloudflaredPath,
+        originRequest: options.originRequest
+      }
+    },
+    autoStopAfter: options.autoStopAfterMs
+  };
+}
+function publicSession(session) {
+  return {
+    sessionId: session.sessionId,
+    localUrl: session.localUrl,
+    publicUrl: session.publicUrl,
+    hostname: session.hostname,
+    expiresAt: session.expiresAt,
+    events: session.events,
+    exited: session.exited,
+    stop: session.stop
+  };
+}
+async function startTunnel(options) {
+  const mode = options.mode ?? "quick";
+  const apiToken = options.apiToken ?? process.env.CLOUDFLARE_API_TOKEN;
+  const tunnel = createCloudflareTunnel({
+    cloudflaredPath: options.cloudflaredPath,
+    accountId: options.accountId,
+    apiToken,
+    apiBase: options.apiBase,
+    originRequest: options.originRequest
+  });
+  const dns = mode === "named" ? createCloudflareDns({
+    apiToken: apiToken ?? "",
+    zoneId: options.zoneId,
+    apiBase: options.apiBase
+  }) : void 0;
+  if (mode === "named" && (!options.hostname || !options.zone)) {
+    throw new Error("Named tunnels require both hostname and zone");
+  }
+  const session = await startPreviewSession({
+    cwd: options.cwd ?? process.cwd(),
+    config: toConfig(options, mode),
+    adapters: { tunnel, dns },
+    mode,
+    hostname: options.hostname,
+    zone: options.zone,
+    signal: options.signal,
+    onLog: options.onLog,
+    persist: options.persist,
+    keep: options.keep,
+    overwrite: options.overwrite,
+    autoStopAfterMs: options.autoStopAfterMs,
+    verifyTimeoutMs: options.verifyTimeoutMs
+  });
+  return publicSession(session);
+}
+
+export { startTunnel };

package/package.json

@@ -1,14 +1,43 @@
 {
   "name": "@flash-tunnel/sdk",
-  "version": "0.0.0",
-  "description": "Placeholder for @flash-tunnel/sdk",
-  "main": "index.js",
-  "scripts": {},
-  "keywords": [],
-  "author": "imba97 (https://www.npmjs.com/~imba97)",
-  "license": "UNLICENSED",
-  "private": false,
+  "type": "module",
+  "version": "0.3.0",
+  "license": "MIT",
+  "homepage": "https://github.com/flash-tunnel/flash-tunnel#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flash-tunnel/flash-tunnel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/flash-tunnel/flash-tunnel/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@flash-tunnel/adapter-cloudflare": "0.3.0",
+    "@flash-tunnel/config": "0.3.0",
+    "@flash-tunnel/core": "0.3.0",
+    "@flash-tunnel/types": "0.3.0"
+  },
+  "scripts": {
+    "stub": "unbuild --stub",
+    "build": "unbuild",
+    "typecheck": "tsc --noEmit"
   }
 }

package/index.js

@@ -1 +0,0 @@
-// Placeholder