@maiyunnet/kebab 2.0.6 → 2.0.8

package/lib/net.js

@@ -47,16 +47,27 @@ exports.filterProxyHeaders = filterProxyHeaders;
 exports.mproxy = mproxy;
 exports.mproxyData = mproxyData;
 exports.rproxy = rproxy;
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-5-15 22:47
+ * CA: https://curl.haxx.se/ca/cacert.pem
+ * Last: 2020-4-9 20:11:02, 2022-09-22 14:30:13, 2024-1-1 21:32:26, 2024-1-12 13:01:54, 2025-6-13 13:20:52
+ */
 const stream = __importStar(require("stream"));
+// --- 第三方 ---
 const hc = __importStar(require("@litert/http-client"));
+// --- 库和定义 ---
 const fs = __importStar(require("../lib/fs"));
 const text = __importStar(require("../lib/text"));
 const time = __importStar(require("../lib/time"));
 const kebab = __importStar(require("../index"));
+// --- 自己 ---
 const fd = __importStar(require("./net/formdata"));
 const lRequest = __importStar(require("./net/request"));
 const response = __importStar(require("./net/response"));
+/** --- ca 根证书内容 --- */
 let ca = '';
+/** --- 获取 CA 证书 --- */
 async function getCa() {
     if (ca) {
         return ca;
@@ -64,26 +75,53 @@ async function getCa() {
     ca = (await fs.getContent(kebab.LIB_PATH + 'net/cacert.pem', 'utf8')) ?? '';
     return ca;
 }
+/** --- 复用的 hc 对象列表 --- */
 const reuses = {
     'default': hc.createHttpClient()
 };
+/**
+ * --- 创建一个请求对象 ---
+ * @param u
+ */
 function open(u) {
     return new lRequest.Request(u);
 }
+/**
+ * --- 发起一个 get 请求 ---
+ * @param u 请求的 URL
+ * @param opt 参数
+ */
 async function get(u, opt = {}) {
     return request(u, undefined, opt);
 }
+/**
+ * --- 发起一个 post 请求 ---
+ * @param u 请求的 URL
+ * @param data 要发送的数据
+ * @param opt 参数
+ */
 async function post(u, data, opt = {}) {
     opt.method = 'POST';
     return request(u, data, opt);
 }
+/**
+ * --- 发起 JSON 请求 ---
+ * @param u
+ * @param data
+ * @param opt
+ */
 async function postJson(u, data, opt = {}) {
     opt.method = 'POST';
     opt.type = 'json';
     return request(u, data, opt);
 }
+/**
+ * --- 发起一个请求 ---
+ * @param opt 配置项
+ */
 async function request(u, data, opt = {}) {
     const uri = text.parseUrl(u);
+    /** --- 正向代理的地址 --- */
     const puri = opt.mproxy ? text.parseUrl(opt.mproxy.url) : null;
     const method = opt.method ?? 'GET';
     const type = opt.type ?? 'form';
@@ -100,6 +138,7 @@ async function request(u, data, opt = {}) {
         }
     }
     headers['user-agent'] ??= 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.86 Safari/537.36';
+    // --- DATA ---
     if (method === 'GET') {
         if (data && !(data instanceof stream.Readable) && !Buffer.isBuffer(data)) {
             u += (u.includes('?') ? '&' : '?') +
@@ -108,6 +147,7 @@ async function request(u, data, opt = {}) {
         }
     }
     else {
+        // --- POST ---
         if (data && !(data instanceof stream.Readable) && !Buffer.isBuffer(data) && typeof data !== 'string') {
             if (type === 'form') {
                 data = text.queryStringify(data);
@@ -124,14 +164,18 @@ async function request(u, data, opt = {}) {
         }
     }
     headers['accept-encoding'] = 'gzip, deflate';
+    // --- ssl ---
     if (uri.protocol === 'https:') {
         await getCa();
     }
+    // --- cookie 托管 ---
     if (opt.cookie) {
         headers['cookie'] = buildCookieQuery(opt.cookie, uri);
     }
+    // --- 发起请求 ---
     let req;
     try {
+        // --- 重定义 IP ---
         const host = (puri ? puri.hostname : uri.hostname) ?? '';
         if (!host) {
             const res = new response.Response(null);
@@ -174,9 +218,14 @@ async function request(u, data, opt = {}) {
         res.error = err;
         return res;
     }
+    // --- 处理返回值 ---
+    // --- 是否追踪 cookie ---
     if (opt.cookie) {
+        // --- 提取 cookie ---
         await buildCookieObject(opt.cookie, (req.headers['set-cookie'] ?? []), uri);
     }
+    // --- 直接下载到文件 ---
+    /** --- 已下载文件的 size --- */
     let total = 0;
     if (save && (!req.headers['location'] || follow === 0)) {
         await new Promise(function (resolve) {
@@ -192,6 +241,7 @@ async function request(u, data, opt = {}) {
             }).pipe(fs.createWriteStream(save));
         });
     }
+    // --- 创建 Response 对象 ---
     const res = new response.Response(req);
     if (total) {
         res.setContent(total.toString());
@@ -209,12 +259,14 @@ async function request(u, data, opt = {}) {
     }
     res.headers['http-code'] = req.statusCode;
     res.headers['http-url'] = u;
+    // --- 判断 follow 追踪 ---
     if (follow === 0) {
         return res;
     }
     if (!res.headers['location']) {
         return res;
     }
+    // --- 哦，要追踪 ---
     headers['referer'] = u;
     return request(text.urlResolve(u, req.headers['location']), data, {
         'method': method,
@@ -229,6 +281,14 @@ async function request(u, data, opt = {}) {
         'reuse': reuse
     });
 }
+/**
+ * --- 对 cookie 对象进行操作 ---
+ * @param cookie 要操作的对象
+ * @param name 名
+ * @param value 值
+ * @param domain 应用网址，如 .xxx.com
+ * @param opt 选项 ttl, path, ssl, httponly
+ */
 function setCookie(cookie, name, value, domain, opt = {}) {
     const tim = time.stamp();
     const ttl = opt.ttl ?? 0;
@@ -248,25 +308,35 @@ function setCookie(cookie, name, value, domain, opt = {}) {
         'httponly': opt['httponly'] ? true : false
     };
 }
+/**
+ * --- 根据 Set-Cookie 头部转换到 cookie 对象 ---
+ * @param cookie cookie 对象
+ * @param setCookies 头部的 set-cookie 数组
+ * @param uri 请求的 URI 对象
+ */
 async function buildCookieObject(cookie, setCookies, uri) {
     const tim = time.stamp();
     uri.path ??= '/';
     for (const setCookie of setCookies) {
         const cookieTmp = {};
         const list = setCookie.split(';');
+        // --- 提取 set-cookie 中的定义信息 ---
         for (let index = 0; index < list.length; ++index) {
             const item = list[index];
             const arr = item.split('=');
             const key = arr[0].trim();
             const val = arr[1] ?? '';
             if (index === 0) {
+                // --- 用户定义的信息 ---
                 cookieTmp['name'] = key;
                 cookieTmp['value'] = decodeURIComponent(val);
             }
             else {
+                // --- cookie 配置信息，可转小写方便读取 ---
                 cookieTmp[key.toLowerCase()] = val;
             }
         }
+        // --- 获取定义的 domain ---
         let domain = '', domainN = '';
         if (cookieTmp['domain']) {
             cookieTmp['domain'] = cookieTmp['domain'].split(':')[0];
@@ -283,15 +353,28 @@ async function buildCookieObject(cookie, setCookies, uri) {
             domain = '.' + (uri.hostname ?? '');
             domainN = uri.hostname ?? '';
         }
+        // --- 判断有没有设置 domain 的权限 ---
+        // --- uri.hostname vs  domain(domainN) ---
+        // --- ok.xxx.com   vs  .ok.xxx.com: true ---
+        // --- ok.xxx.com   vs  .xxx.com: true ---
+        // --- z.ok.xxx.com vs  .xxx.com: true ---
+        // --- ok.xxx.com   vs  .zz.ok.xxx.com: false ---
         if (uri.hostname !== domainN) {
+            // --- 设置的域名和当前 host 不相等，如果是 IP、无 . 域名，则直接失败 ---
             if (!text.isDomain(uri.hostname ?? '')) {
                 continue;
             }
             const parseDomain = await text.parseDomain(domainN);
             if (parseDomain.tld === domainN.toLowerCase()) {
+                // --- 不能给 tld 设置 cookie ---
                 continue;
             }
+            // --- 判断访问路径 (uri['host']) 是不是设置域名 (domain) 的孩子，domain 必须是 uriHost 的同级或者父辈 ---
             if (!((uri.hostname ?? '').endsWith(domain))) {
+                // --- false 代表进入了，代表失败 ---
+                // --- ok.xxx.com, .xxx.com: true ---
+                // --- ok.xxx.com, .ppp.com: false ---
+                // --- ok.xxx.com, .p.ok.xxx.com: false ---
                 continue;
             }
         }
@@ -306,6 +389,7 @@ async function buildCookieObject(cookie, setCookies, uri) {
         if (cookieTmp['max-age']) {
             exp = tim + Number(cookieTmp['max-age']);
         }
+        // --- path ---
         let path = cookieTmp['path'] ?? '';
         if (path === '') {
             const srp = (uri.pathname ?? '').lastIndexOf('/');
@@ -325,6 +409,11 @@ async function buildCookieObject(cookie, setCookies, uri) {
         };
     }
 }
+/**
+ * --- 对象转换为 Cookie 拼接字符串（会自动筛掉不能发送的 cookie） ---
+ * @param cookie cookie 对象
+ * @param uri 请求的 URI 对象
+ */
 function buildCookieQuery(cookie, uri) {
     const tim = time.stamp();
     let cookieStr = '';
@@ -338,12 +427,26 @@ function buildCookieQuery(cookie, uri) {
         if (item.secure && (uri.protocol === 'https')) {
             continue;
         }
+        // --- 判断 path 是否匹配 ---
         if (!uri.path.startsWith(item.path)) {
             continue;
         }
         const domain = '.' + item.domain;
+        // --- 判断 $uri['host'] 必须是 $domain 的同级或子级 ---
+        // --- $uri['host']     vs      $domain ---
+        // --- ok.xxx.com       vs      .ok.xxx.com: true ---
+        // --- ok.xxx.com       vs      .xxx.com: true ---
+        // --- z.ok.xxx.com     vs      .xxx.com: true ---
+        // --- ok.xxx.com       vs      .zz.ok.xxx.com: false ---
         if ('.' + (uri.hostname ?? '') !== domain) {
+            // --- 域名不相等，那么判断当前域名 host 是不是 domain 的孩子 ---
             if (!(uri.hostname.endsWith(domain))) {
+                // --- false 代表进入，被排除了，因为 cookie 的 domain 和当前 host 后半部分，代表不是 domain 的孩子 ---
+                // --- ok.xxx.com, .zz.ok.xxx.com: false ---
+                // --- pp.ok.xxx.com, .zz.ok.xxx.com: false ---
+                // --- q.b.ok.xx.com, .zz.ok.xxx.com: false ---
+                // --- z.ok.xxx.com, .xxx.com: true ---
+                // --- xx.xxx.com, .ok.xxx.com: false ---
                 continue;
             }
         }
@@ -356,6 +459,10 @@ function buildCookieQuery(cookie, uri) {
         return '';
     }
 }
+/**
+ * --- 模拟重启浏览器后的状态 ---
+ * @param cookie cookie 对象
+ */
 function resetCookieSession(cookie) {
     for (const key in cookie) {
         const item = cookie[key];
@@ -364,10 +471,19 @@ function resetCookieSession(cookie) {
         }
     }
 }
+/**
+ * --- 创建 FormData 对象, Mutton: false, Kebab: true ---
+ */
 function getFormData() {
     return new fd.FormData();
 }
+/** --- proxy 要剔除的基础头部 --- */
 const proxyContinueHeaders = ['host', 'connection', 'http-version', 'http-code', 'http-url'];
+/**
+ * --- 剔除不代理的 header ---
+ * @param headers 剔除前的 header
+ * @param res 直接设置头部而不返回，可置空
+ */
 function filterProxyHeaders(headers, res) {
     const heads = {};
     for (const h in headers) {
@@ -389,10 +505,18 @@ function filterProxyHeaders(headers, res) {
     }
     return heads;
 }
+/**
+ * --- 正向 mproxy 代理，读取 get 的 url 为实际请求地址 ---
+ * --- get: url, auth ---
+ * @param ctr 当前控制器
+ * @param auth 校验字符串，读取 get 的 auth 和本参数做比对
+ * @param opt 参数
+ */
 async function mproxy(ctr, auth, opt = {}) {
     const req = ctr.getPrototype('_req');
     const res = ctr.getPrototype('_res');
     const input = ctr.getPrototype('_input');
+    /** --- 客户端请求中的 get 的数据 --- */
     const get = ctr.getPrototype('_get');
     if (get['auth'] !== auth) {
         return 0;
@@ -403,6 +527,7 @@ async function mproxy(ctr, auth, opt = {}) {
     opt.method = req.method ?? 'GET';
     opt.headers ??= {};
     Object.assign(opt.headers, filterProxyHeaders(req.headers));
+    // --- 发起请求 ---
     const rres = await request(get['url'], req.headers['content-type']?.includes('form-data') ? req : input, opt);
     if (rres.error) {
         return -2;
@@ -418,6 +543,10 @@ async function mproxy(ctr, auth, opt = {}) {
     });
     return 1;
 }
+/**
+ * --- 获取 mproxy 的附加数据 ---
+ * @param ctr 当前控制器
+ */
 function mproxyData(ctr) {
     const get = ctr.getPrototype('_get');
     if (!get['data']) {
@@ -429,6 +558,12 @@ function mproxyData(ctr) {
     }
     return data;
 }
+/**
+ * --- 反向代理，将本服务器的某个路由反代到其他网址 ---
+ * @param ctr 当前控制器
+ * @param route 要反代的路由
+ * @param opt 参数
+ */
 async function rproxy(ctr, route, opt = {}) {
     const req = ctr.getPrototype('_req');
     const res = ctr.getPrototype('_res');
@@ -439,10 +574,15 @@ async function rproxy(ctr, route, opt = {}) {
         if (!path.startsWith(key)) {
             continue;
         }
+        // --- 找到了，做转发 ---
+        // --- key 类似：test/net-rproxy/ ---
+        // --- 值类似：https://cdn.jsdelivr.net/npm/deskrt@2.0.10/ ---
+        /** --- 要拼接的地址 --- */
         const lpath = path.slice(key.length);
         opt.method = req.method ?? 'GET';
         opt.headers ??= {};
         Object.assign(opt.headers, filterProxyHeaders(req.headers));
+        // --- 发起请求 ---
         const rres = await request(route[key] + lpath, req.headers['content-type']?.includes('form-data') ? req : input, opt);
         if (rres.error) {
             return false;

package/lib/s3.d.ts

@@ -1,35 +1,87 @@
+/**
+ * Project: Kebab, User: Tang Rukun, JianSuoQiYue
+ * Date: 2024-2-18 18:32:45
+ * Last: 2024-2-18 18:32:47, 2024-3-16 16:42:27, 2024-5-31 21:36:26, 2024-7-8 00:28:42, 2024-7-19 11:32:43, 2025-6-10 21:45:34
+ */
 import * as s3 from '@aws-sdk/client-s3';
 import * as stream from 'stream';
 import * as sCtr from '../sys/ctr';
+/**
+ * s3 文档：https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/
+ */
+/** --- 服务商定义 --- */
 export declare enum ESERVICE {
     'AMAZON' = 0,
     'TENCENT' = 1,
     'ALIBABA' = 2,
     'CF' = 3
 }
+/** --- 选项 --- */
 export interface IOptions {
+    /** --- 服务商 ---- */
     'service': ESERVICE;
+    /** --- cf r2 使用 --- */
     'account'?: string;
+    /** --- 密钥键 --- */
     'secretId'?: string;
+    /** --- 密钥值 --- */
     'secretKey'?: string;
+    /** --- 区域 --- */
     'region'?: string;
+    /** --- 预定义 bucket --- */
     'bucket'?: string;
 }
 export declare class S3 {
     private readonly _link;
+    /** --- bucket 名 --- */
     private _bucket;
     private readonly _ctr;
     constructor(ctr: sCtr.Ctr, opt: IOptions);
+    /**
+     * --- 修改预定义 bucket ---
+     * @param bucket bucket 名
+     */
     setBucket(bucket: string): void;
+    /**
+     * --- 上传对象（可传流且也可无需设置 length） --
+     * @param key 对象路径
+     * @param content 内容
+     * @param length 设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+     * @param bucket bucket 名
+     */
     putObject(key: string, content: string | Buffer | stream.Readable, length?: number | {
         'length'?: number;
         'type'?: string;
         'disposition'?: string;
         'bucket'?: string;
     }, bucket?: string): Promise<s3.CompleteMultipartUploadCommandOutput | false>;
+    /**
+     * --- 获取对象流，可通过流获取 buffer 或 text ---
+     * @param key 对象路径
+     * @param bucket bucket 名
+     */
     getObject(key: string, bucket?: string): Promise<false | (stream.Readable & import("@smithy/types").SdkStreamMixin) | (Blob & import("@smithy/types").SdkStreamMixin) | (ReadableStream<any> & import("@smithy/types").SdkStreamMixin) | undefined>;
+    /**
+     * --- 删除对象 ---
+     * @param key 对象路径
+     * @param bucket bucket 名
+     */
     deleteObject(key: string, bucket?: string): Promise<boolean>;
+    /**
+     * --- 批量删除对象 ---
+     * @param keys 批量对象路径
+     * @param bucket bucket 名
+     */
     deleteObjects(keys: string[], bucket?: string): Promise<boolean>;
+    /**
+     * --- 检测对象是否存在 ---
+     * @param key 对象路径
+     * @param bucket bucket 名
+     */
     headObject(key: string, bucket?: string): Promise<s3.HeadObjectCommandOutput | false>;
 }
+/**
+ * --- 创建一个对象存储对象 ---
+ * @param opt 选项
+ */
 export declare function get(ctr: sCtr.Ctr, opt: IOptions): S3;

package/lib/s3.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Project: Kebab, User: Tang Rukun, JianSuoQiYue
+ * Date: 2024-2-18 18:32:45
+ * Last: 2024-2-18 18:32:47, 2024-3-16 16:42:27, 2024-5-31 21:36:26, 2024-7-8 00:28:42, 2024-7-19 11:32:43, 2025-6-10 21:45:34
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -35,10 +40,15 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.S3 = exports.ESERVICE = void 0;
 exports.get = get;
+// --- 库和定义 ---
 const s3 = __importStar(require("@aws-sdk/client-s3"));
 const ls = __importStar(require("@aws-sdk/lib-storage"));
 const lCore = __importStar(require("../lib/core"));
 const lText = __importStar(require("../lib/text"));
+/**
+ * s3 文档：https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/
+ */
+/** --- 服务商定义 --- */
 var ESERVICE;
 (function (ESERVICE) {
     ESERVICE[ESERVICE["AMAZON"] = 0] = "AMAZON";
@@ -48,6 +58,7 @@ var ESERVICE;
 })(ESERVICE || (exports.ESERVICE = ESERVICE = {}));
 class S3 {
     constructor(ctr, opt) {
+        /** --- bucket 名 --- */
         this._bucket = '';
         this._ctr = ctr;
         const config = ctr.getPrototype('_config');
@@ -84,12 +95,25 @@ class S3 {
             'endpoint': endpoint
         });
     }
+    /**
+     * --- 修改预定义 bucket ---
+     * @param bucket bucket 名
+     */
     setBucket(bucket) {
         this._bucket = bucket;
     }
+    /**
+     * --- 上传对象（可传流且也可无需设置 length） --
+     * @param key 对象路径
+     * @param content 内容
+     * @param length 设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+     * @param bucket bucket 名
+     */
     async putObject(key, content, length, bucket) {
         try {
+            /** --- content type --- */
             let type = undefined;
+            /** --- content disposition --- */
             let disposition = undefined;
             if (typeof length !== 'number') {
                 type = length?.type;
@@ -116,6 +140,12 @@ class S3 {
             return false;
         }
     }
+    /**
+     * --- 获取对象流，可通过流获取 buffer 或 text ---
+     * @param key 对象路径
+     * @param bucket bucket 名
+     */
+    // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
     async getObject(key, bucket) {
         try {
             const go = new s3.GetObjectCommand({
@@ -126,9 +156,15 @@ class S3 {
             return r.Body;
         }
         catch {
+            // await lCore.log(this._ctr, '[getObject, s3] ' + lText.stringifyJson(e.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
             return false;
         }
     }
+    /**
+     * --- 删除对象 ---
+     * @param key 对象路径
+     * @param bucket bucket 名
+     */
     async deleteObject(key, bucket) {
         try {
             const doc = new s3.DeleteObjectCommand({
@@ -139,9 +175,15 @@ class S3 {
             return true;
         }
         catch {
+            // await lCore.log(this._ctr, '[deleteObject, s3] ' + lText.stringifyJson(e.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
             return false;
         }
     }
+    /**
+     * --- 批量删除对象 ---
+     * @param keys 批量对象路径
+     * @param bucket bucket 名
+     */
     async deleteObjects(keys, bucket) {
         try {
             const doc = new s3.DeleteObjectsCommand({
@@ -158,6 +200,11 @@ class S3 {
             return false;
         }
     }
+    /**
+     * --- 检测对象是否存在 ---
+     * @param key 对象路径
+     * @param bucket bucket 名
+     */
     async headObject(key, bucket) {
         try {
             const ho = new s3.HeadObjectCommand({
@@ -175,6 +222,10 @@ class S3 {
     }
 }
 exports.S3 = S3;
+/**
+ * --- 创建一个对象存储对象 ---
+ * @param opt 选项
+ */
 function get(ctr, opt) {
     return new S3(ctr, opt);
 }

package/lib/scan.d.ts

@@ -1,11 +1,18 @@
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2022-09-24 15:23:25
+ * Last: 2022-09-24 15:23:25, 2022-9-26 12:37:01, 2022-12-29 00:11:16
+ */
 import * as lDb from '../lib/db';
 import * as lKv from '../lib/kv';
 import * as sCtr from '../sys/ctr';
+/** --- Scan 设置的选项 --- */
 export interface IOptions {
     'ttl'?: number;
     'sqlPre'?: sCtr.Ctr | string;
     'name'?: string;
 }
+/** --- scanned 函数的选项 --- */
 export interface IStaticOptions {
     'sqlPre'?: sCtr.Ctr | string;
     'name'?: string;
@@ -13,19 +20,64 @@ export interface IStaticOptions {
 export declare class Scan {
     private readonly _link;
     private readonly _sql;
+    /** --- 表名或者 kv 里 key 的前缀 --- */
     private readonly _name;
     private _token;
+    /** --- 有效期，默认 5 分钟 --- */
     private _ttl;
     constructor(link: lDb.Pool | lKv.Pool, token?: string, opt?: IOptions);
+    /** --- 二维码剩余有效时间 --- */
     private _timeLeft;
+    /**
+     * --- 生成二维码处的轮询，检查是否被扫码、被录入数据 ---
+     * @returns -3 系统错误 -2 token 不存在或已过期 -1 无操作, 0 已扫码, 其他返回为存的数据并结束轮询
+     */
     poll(): Promise<any>;
+    /**
+     * --- 创建 token，直接应用到本类 ---
+     */
     createToken(): Promise<boolean>;
+    /**
+     * --- 获取当前 token ---
+     */
     getToken(): string | null;
+    /**
+     * --- 设置有效期，设置后的新 token 被创建有效 ---
+     * @param ttl
+     */
     setTTL(ttl: number): void;
+    /**
+     * --- 获取设置的有效期 ---
+     */
     getTTL(): number;
+    /**
+     * --- 获取当前 token 可扫剩余有效期 ---
+     */
     getTimeLeft(): number | null;
+    /**
+     * --- 根据情况清空 Db 状态下的 scan 表垃圾数据 ---
+     */
     private _gc;
 }
+/**
+ * -- 创建 Scan 对象 ---
+ * @param link
+ * @param token Token
+ * @param opt
+ */
 export declare function get(link: lDb.Pool | lKv.Pool, token?: string, opt?: IOptions): Promise<Scan>;
+/**
+ * --- 对 token 执行访问操作，通常用户扫码后展示的网页所调用，代表已扫码 ---
+ * @param link
+ * @patam token 必填
+ * @param opt
+ */
 export declare function scanned(link: lDb.Pool | lKv.Pool, token: string, opt?: IStaticOptions): Promise<boolean>;
+/**
+ * --- 将数据写入 token，通常在客户的逻辑下去写，服务器会 poll 到 ---
+ * @param link
+ * @param token
+ * @param data
+ * @param opt
+ */
 export declare function setData(link: lDb.Pool | lKv.Pool, token: string, data: Record<string, any> | string | number, opt?: IStaticOptions): Promise<boolean>;