@fastls/fastls 0.12.0 → 0.13.0

package/README.md

@@ -21,7 +21,7 @@ const h3 = new Session({ httpVersion: 'h3' });
 try { await h3.get('https://example.com'); } finally { await h3.closeAsync(); }
 ```
 
-Node.js 22+ 的 Fastls C ABI v1 绑定，提供 Promise API、TypeScript 声明、ESM 和 CommonJS 入口。本文对应 **0.12.0**。
+Node.js 22+ 的 Fastls C ABI v1 绑定，提供 Promise API、TypeScript 声明、ESM 和 CommonJS 入口。本文对应 **0.13.0**。
 
 支持 HTTP/1.1、HTTP/2、流式上传下载、双工、SSE、WebSocket、会话 Cookie 和 HTTP/HTTPS/SOCKS 代理。网络请求由 Go 执行，通过 Koffi 在当前 Node 进程中调用；使用者无需 Python 或 RPC 服务。
 
@@ -37,7 +37,7 @@ Node.js 22+ 的 Fastls C ABI v1 绑定，提供 Promise API、TypeScript 声明
 安装指定版本：
 
 ```sh
-npm install @fastls/fastls@0.12.0
+npm install @fastls/fastls@0.13.0
 ```
 
 主包通过同版本的可选依赖自动安装当前平台的 Fastls 原生库。保留 optional dependencies；支持 Windows x64、Linux glibc x64/arm64、macOS x64/arm64。Linux musl 和其它架构没有内置包。具体系统最低版本见原生包的 `native/manifest.json`。
@@ -404,3 +404,5 @@ JavaScript无法强行中断任意Promise：取消会立即释放原生请求，
 ## 动态库选择与安装排错
 
 加载优先级：显式 SessionOptions.library → FASTLS_LIBRARY → 包内 manifest → 同版本平台可选依赖；源码目录可回退仓库 dist，已安装 thin 包不回退仓库。普通 npm 用户应保留 optionalDependencies，不必设置外部库路径。外部旧库可能覆盖新包，ABI 号相同也不保证扩展能力相同。Linux glibc 与 macOS 最低版本、摘要及动态依赖以 native/manifest.json 为准。更多排错见 [在线帮助](https://fasttls.github.io/help/)。
+
+`ProfileSpec.fromFingerprints(base, { ja3, h2 })` 使用 Go 共用的离线转换器，返回经校验的完整 Spec；支持现有 Session/fetch 和 ProfileStore。详细[中文说明](https://github.com/FastTLS/fastls-ffi/blob/main/FINGERPRINTS.zh-CN.md) · [English contract](https://github.com/FastTLS/fastls-ffi/blob/main/FINGERPRINTS.md)。

package/dist/native.d.ts

@@ -38,6 +38,7 @@ export declare class Native {
     static load(library?: string): Native;
     private constructor();
     call<T = unknown>(name: string, ...args: unknown[]): T;
+    adaptProfile(input: unknown): Record<string, unknown>;
     start(input: unknown): bigint;
     requireCapabilities(required: readonly string[]): void;
     wsStart(input: unknown): bigint;

package/dist/native.js

@@ -104,6 +104,12 @@ class Native {
             this.functions.read = lib.func("int fastls_read(uint64_t handle, _Out_ void *buffer, size_t capacity, _Out_ size_t *length)");
             this.functions.write = lib.func("int fastls_write(uint64_t handle, const void *buffer, size_t length, int end)");
             const features = new Set(this.call("features"));
+            if (features.has("fingerprint_adapter_v1")) {
+                try {
+                    this.functions.profile_adapt = lib.func("void *fastls_profile_adapt(void *json, size_t length)");
+                }
+                catch { /* Reject use below; old HTTP operations remain available. */ }
+            }
             if (features.has("transport_options_v1")) {
                 try {
                     this.functions.transport_create_with_options = lib.func("void *fastls_transport_create_with_options(void *json, size_t length)");
@@ -169,6 +175,16 @@ class Native {
         }
         return envelope.result;
     }
+    adaptProfile(input) {
+        this.requireCapabilities(["fingerprint_adapter_v1", "profile_spec_v1"]);
+        if (!this.functions.profile_adapt) {
+            const error = new errors_js_1.FastlsError("native fingerprint adapter symbol is unavailable");
+            error.code = "unsupported_capability";
+            throw error;
+        }
+        const raw = encodeNativeJSON(input);
+        return this.call("profile_adapt", raw, raw.length);
+    }
     start(input) {
         const raw = encodeNativeJSON(input);
         return asHandle(this.call("start", raw, raw.length));

package/dist/profiles.d.ts

@@ -10,5 +10,10 @@ export interface AddressPolicy {
 export declare class ProfileSpec {
     private readonly snapshot;
     constructor(value: Readonly<Record<string, unknown>>);
+    static fromFingerprints(base: ProfileSpec, options: {
+        ja3?: string;
+        h2?: string;
+        library?: string;
+    }): ProfileSpec;
     toJSON(): Record<string, unknown>;
 }

package/dist/profiles.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProfileSpec = void 0;
+const native_js_1 = require("./native.js");
 /** Explicit snapshot of a complete schema-v1 profile, validated by the core. */
 class ProfileSpec {
     snapshot;
@@ -11,6 +12,16 @@ class ProfileSpec {
         if (Buffer.byteLength(this.snapshot) > 256 * 1024)
             throw new RangeError("profileSpec exceeds 256KiB");
     }
+    static fromFingerprints(base, options) {
+        if (!(base instanceof ProfileSpec))
+            throw new TypeError("base must be ProfileSpec");
+        const { ja3 = "", h2 = "", library } = options;
+        if (typeof ja3 !== "string" || typeof h2 !== "string")
+            throw new TypeError("ja3 and h2 must be strings");
+        if (Object.keys(options).some(key => !["ja3", "h2", "library"].includes(key)))
+            throw new TypeError("unknown fingerprint option");
+        return new ProfileSpec(native_js_1.Native.load(library).adaptProfile({ schema_version: 1, base: base.toJSON(), ja3, h2 }));
+    }
     toJSON() { return JSON.parse(this.snapshot); }
 }
 exports.ProfileSpec = ProfileSpec;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastls/fastls",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Node.js bindings for the Fastls C ABI",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,10 +35,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "optionalDependencies": {
-    "@fastls/fastls-win32-x64": "0.12.0",
-    "@fastls/fastls-linux-x64-glibc": "0.12.0",
-    "@fastls/fastls-linux-arm64-glibc": "0.12.0",
-    "@fastls/fastls-darwin-x64": "0.12.0",
-    "@fastls/fastls-darwin-arm64": "0.12.0"
+    "@fastls/fastls-win32-x64": "0.13.0",
+    "@fastls/fastls-linux-x64-glibc": "0.13.0",
+    "@fastls/fastls-linux-arm64-glibc": "0.13.0",
+    "@fastls/fastls-darwin-x64": "0.13.0",
+    "@fastls/fastls-darwin-arm64": "0.13.0"
   }
 }