@larksuiteoapi/node-sdk 1.60.0 → 1.61.0

package/README.md

@@ -627,6 +627,68 @@ server.listen(3000);
 | logger | - | Logger | No | - |
 | cache | Cache | Cache | No | - |
 
+### App Registration
+The SDK provides a `registerApp` method for one-click app creation based on the OAuth 2.0 Device Authorization Grant (RFC 8628) protocol. It returns a verification URL that users can open in Feishu/Lark to authorize and automatically register an app, obtaining credentials without manually creating one on the developer console.
+
+```typescript
+import * as lark from '@larksuiteoapi/node-sdk';
+
+try {
+    const result = await lark.registerApp({
+        onQRCodeReady(info) {
+            console.log(`Scan the QR code: ${info.url}`);
+            console.log(`Link expires in ${info.expireIn} seconds`);
+        },
+        onStatusChange(info) {
+            // Handle status changes: 'polling' | 'slow_down' | 'domain_switched'
+        },
+    });
+
+    console.log('App ID:', result.client_id);
+    console.log('App Secret:', result.client_secret);
+
+    // Use the credentials to initialize a Client
+    const client = new lark.Client({
+        appId: result.client_id,
+        appSecret: result.client_secret,
+    });
+} catch (e) {
+    // e.code: 'access_denied' | 'expired_token' | 'abort' | ...
+    // e.description: error description
+    console.error(e.code, e.description);
+}
+```
+
+#### `registerApp` parameters
+
+| Parameter | Description | Type | Required | Default |
+| ---- | ---- | ---- | ---- | ---- |
+| domain | Custom accounts domain (host only) | string | No | `accounts.feishu.cn` |
+| larkDomain | Custom Lark accounts domain (host only), used when tenant brand is detected as Lark | string | No | `accounts.larksuite.com` |
+| source | Source identifier, appended to the QR code URL `from` parameter as `node-sdk/{source}` | string | No | - |
+| signal | `AbortSignal` to cancel the polling | AbortSignal | No | - |
+| onQRCodeReady | Callback when the verification URL is ready. Receives `{ url, expireIn }`. You can render the URL as a QR code for users to scan, or display it as a link | function | Yes | - |
+| onStatusChange | Callback on polling status changes. Receives `{ status, interval? }`. Status values: `polling`, `slow_down`, `domain_switched` | function | No | - |
+
+#### Return value
+
+| Field | Type | Description |
+| ---- | ---- | ---- |
+| client_id | string | App ID |
+| client_secret | string | App Secret |
+| user_info | object (optional) | Scanning user info |
+| user_info.open_id | string (optional) | User's open_id |
+| user_info.tenant_brand | string (optional) | `"feishu"` or `"lark"` |
+
+#### Error handling
+The thrown error object contains `code` and `description` fields:
+
+| code | Description |
+| ---- | ---- |
+| `access_denied` | User denied the authorization |
+| `expired_token` | QR code expired or polling timed out |
+| `abort` | Cancelled via AbortSignal |
+
 ### Tool method
 #### AESCipher
 Decrypt. If [Encrypted Push](https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/encrypt-key-encryption-configuration-case) is configured, the open platform will push encrypted data, At this time, the data needs to be decrypted, and this method can be called for convenient decryption. (In general, the decryption logic is built into the SDK, and no manual processing is required).

package/README.zh.md

@@ -627,6 +627,68 @@ server.listen(3000);
 | logger  | - | Logger | 否 | - |
 | cache  | 缓存器 | Cache | 否 | - |
 
+### 一键创建应用
+SDK提供了`registerApp`方法，基于 OAuth 2.0 Device Authorization Grant（RFC 8628）协议实现一键创建应用。该方法会返回一个验证链接，用户在飞书/Lark中打开该链接完成授权后，即可自动注册应用并获取凭据，无需手动到开发者后台创建。
+
+```typescript
+import * as lark from '@larksuiteoapi/node-sdk';
+
+try {
+    const result = await lark.registerApp({
+        onQRCodeReady(info) {
+            console.log(`请扫码: ${info.url}`);
+            console.log(`链接将在 ${info.expireIn} 秒后过期`);
+        },
+        onStatusChange(info) {
+            // 处理状态变化：'polling' | 'slow_down' | 'domain_switched'
+        },
+    });
+
+    console.log('App ID:', result.client_id);
+    console.log('App Secret:', result.client_secret);
+
+    // 用获取到的凭据初始化 Client
+    const client = new lark.Client({
+        appId: result.client_id,
+        appSecret: result.client_secret,
+    });
+} catch (e) {
+    // e.code: 'access_denied' | 'expired_token' | 'abort' | ...
+    // e.description: 错误描述
+    console.error(e.code, e.description);
+}
+```
+
+#### `registerApp`参数
+
+| 参数 | 描述 | 类型 | 必须 | 默认 |
+| ---- | ---- | ---- | ---- | ---- |
+| domain | 自定义认证域名（仅 host 部分） | string | 否 | `accounts.feishu.cn` |
+| larkDomain | 自定义 Lark 认证域名（仅 host 部分），检测到 Lark 租户时自动切换 | string | 否 | `accounts.larksuite.com` |
+| source | 来源标识，拼入二维码 URL 的 `from` 参数，格式为 `node-sdk/{source}` | string | 否 | - |
+| signal | 用于取消轮询的 `AbortSignal` | AbortSignal | 否 | - |
+| onQRCodeReady | 验证链接就绪时的回调，参数为 `{ url, expireIn }`。可将 URL 渲染为二维码供用户扫码，或直接作为链接展示 | function | 是 | - |
+| onStatusChange | 轮询状态变化时的回调，参数为 `{ status, interval? }`。status 取值：`polling`、`slow_down`、`domain_switched` | function | 否 | - |
+
+#### 返回值
+
+| 字段 | 类型 | 描述 |
+| ---- | ---- | ---- |
+| client_id | string | App ID |
+| client_secret | string | App Secret |
+| user_info | object（可选） | 扫码用户信息 |
+| user_info.open_id | string（可选） | 扫码用户的 open_id |
+| user_info.tenant_brand | string（可选） | `"feishu"` 或 `"lark"` |
+
+#### 错误处理
+抛出的错误对象包含 `code` 和 `description` 字段：
+
+| code | 描述 |
+| ---- | ---- |
+| `access_denied` | 用户拒绝了授权 |
+| `expired_token` | 二维码过期或轮询超时 |
+| `abort` | 通过 AbortSignal 取消 |
+
 ### 工具方法
 #### AESCipher
 解密。如果配置了[加密推送](https://open.feishu.cn/document/ukTMukTMukTM/uYDNxYjL2QTM24iN0EjN/event-subscription-configure-/encrypt-key-encryption-configuration-case)，开放平台会推送加密的数据，这时候需要对数据进行解密处理，调用此方法可以便捷的进行解密。（一般情况下，SDK中内置了解密逻辑，不需要手动进行处理）。

package/es/index.js

@@ -85895,4 +85895,152 @@ class Aily {
     }
 }
 
-export { AESCipher, Aily, AppType, CAppTicket, CTenantAccessToken, CardActionHandler, Client, Domain, EventDispatcher, LoggerLevel, WSClient, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, messageCard, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };
+function createError(code, description) {
+    return { code, description };
+}
+
+const SDK_NAME = 'node-sdk';
+const DEFAULT_FEISHU_DOMAIN = 'accounts.feishu.cn';
+const DEFAULT_LARK_DOMAIN = 'accounts.larksuite.com';
+const ENDPOINT = '/oauth/v1/app/registration';
+function requestRegistration(baseUrl, params) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const resp = yield defaultHttpInstance.post(`${baseUrl}${ENDPOINT}`, new URLSearchParams(params).toString(), {
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            });
+            return resp;
+        }
+        catch (e) {
+            // RFC 8628: authorization_pending, slow_down etc. are returned with HTTP 400
+            if (e instanceof AxiosError && ((_a = e.response) === null || _a === void 0 ? void 0 : _a.data)) {
+                return e.response.data;
+            }
+            throw e;
+        }
+    });
+}
+function begin(baseUrl) {
+    return requestRegistration(baseUrl, {
+        action: 'begin',
+        archetype: 'PersonalAgent',
+        auth_method: 'client_secret',
+        request_user_info: 'open_id',
+    });
+}
+function startPolling(ctx) {
+    return new Promise((resolve, reject) => {
+        var _a, _b;
+        let { baseUrl, interval } = ctx;
+        let domainSwitched = false;
+        let pollTimer = null;
+        let expireTimer = null;
+        const cleanup = () => {
+            var _a;
+            if (pollTimer !== null) {
+                clearTimeout(pollTimer);
+                pollTimer = null;
+            }
+            if (expireTimer !== null) {
+                clearTimeout(expireTimer);
+                expireTimer = null;
+            }
+            (_a = ctx.signal) === null || _a === void 0 ? void 0 : _a.removeEventListener('abort', onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(createError('abort', 'Registration was aborted'));
+        };
+        if ((_a = ctx.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+            return reject(createError('abort', 'Registration was aborted'));
+        }
+        (_b = ctx.signal) === null || _b === void 0 ? void 0 : _b.addEventListener('abort', onAbort, { once: true });
+        expireTimer = setTimeout(() => {
+            cleanup();
+            reject(createError('expired_token', 'Polling timed out'));
+        }, ctx.expireIn);
+        const poll = () => __awaiter(this, void 0, void 0, function* () {
+            var _c, _d, _e, _f, _g, _h;
+            try {
+                const pollRes = yield requestRegistration(baseUrl, {
+                    action: 'poll',
+                    device_code: ctx.deviceCode,
+                });
+                // Lark domain switch (once only)
+                if (((_c = pollRes.user_info) === null || _c === void 0 ? void 0 : _c.tenant_brand) === 'lark' && !domainSwitched) {
+                    baseUrl = ctx.larkBaseUrl;
+                    domainSwitched = true;
+                    (_d = ctx.onStatusChange) === null || _d === void 0 ? void 0 : _d.call(ctx, { status: 'domain_switched' });
+                    poll();
+                    return;
+                }
+                // Success
+                if (pollRes.client_id && pollRes.client_secret) {
+                    cleanup();
+                    resolve({
+                        client_id: pollRes.client_id,
+                        client_secret: pollRes.client_secret,
+                        user_info: pollRes.user_info,
+                    });
+                    return;
+                }
+                // Handle errors
+                switch (pollRes.error) {
+                    case 'authorization_pending':
+                        (_e = ctx.onStatusChange) === null || _e === void 0 ? void 0 : _e.call(ctx, { status: 'polling' });
+                        break;
+                    case 'slow_down':
+                        interval += 5000;
+                        (_f = ctx.onStatusChange) === null || _f === void 0 ? void 0 : _f.call(ctx, { status: 'slow_down', interval: interval / 1000 });
+                        break;
+                    case 'access_denied':
+                    case 'expired_token':
+                        cleanup();
+                        reject(createError(pollRes.error, (_g = pollRes.error_description) !== null && _g !== void 0 ? _g : 'Unknown error'));
+                        return;
+                    default:
+                        if (pollRes.error) {
+                            cleanup();
+                            reject(createError(pollRes.error, (_h = pollRes.error_description) !== null && _h !== void 0 ? _h : 'Unknown error'));
+                            return;
+                        }
+                        break;
+                }
+                pollTimer = setTimeout(poll, interval);
+            }
+            catch (e) {
+                cleanup();
+                reject(e);
+            }
+        });
+        poll();
+    });
+}
+function registerApp(options) {
+    var _a, _b, _c, _d;
+    return __awaiter(this, void 0, void 0, function* () {
+        const { domain, source, signal, onQRCodeReady, onStatusChange } = options;
+        const baseUrl = `https://${domain !== null && domain !== void 0 ? domain : DEFAULT_FEISHU_DOMAIN}`;
+        const beginRes = yield begin(baseUrl);
+        const qrCodeUrl = new URL(beginRes.verification_uri_complete);
+        qrCodeUrl.searchParams.set('from', 'sdk');
+        qrCodeUrl.searchParams.set('source', source ? `${SDK_NAME}/${source}` : SDK_NAME);
+        qrCodeUrl.searchParams.set('tp', 'sdk');
+        onQRCodeReady({
+            url: qrCodeUrl.toString(),
+            expireIn: (_a = beginRes.expire_in) !== null && _a !== void 0 ? _a : 600,
+        });
+        return startPolling({
+            baseUrl,
+            deviceCode: beginRes.device_code,
+            interval: ((_b = beginRes.interval) !== null && _b !== void 0 ? _b : 5) * 1000,
+            expireIn: ((_c = beginRes.expire_in) !== null && _c !== void 0 ? _c : 600) * 1000,
+            larkBaseUrl: `https://${(_d = options.larkDomain) !== null && _d !== void 0 ? _d : DEFAULT_LARK_DOMAIN}`,
+            signal,
+            onStatusChange,
+        });
+    });
+}
+
+export { AESCipher, Aily, AppType, CAppTicket, CTenantAccessToken, CardActionHandler, Client, Domain, EventDispatcher, LoggerLevel, WSClient, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, messageCard, registerApp, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };

package/lib/index.js

@@ -85910,6 +85910,154 @@ class Aily {
     }
 }
 
+function createError(code, description) {
+    return { code, description };
+}
+
+const SDK_NAME = 'node-sdk';
+const DEFAULT_FEISHU_DOMAIN = 'accounts.feishu.cn';
+const DEFAULT_LARK_DOMAIN = 'accounts.larksuite.com';
+const ENDPOINT = '/oauth/v1/app/registration';
+function requestRegistration(baseUrl, params) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const resp = yield defaultHttpInstance.post(`${baseUrl}${ENDPOINT}`, new URLSearchParams(params).toString(), {
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            });
+            return resp;
+        }
+        catch (e) {
+            // RFC 8628: authorization_pending, slow_down etc. are returned with HTTP 400
+            if (e instanceof axios.AxiosError && ((_a = e.response) === null || _a === void 0 ? void 0 : _a.data)) {
+                return e.response.data;
+            }
+            throw e;
+        }
+    });
+}
+function begin(baseUrl) {
+    return requestRegistration(baseUrl, {
+        action: 'begin',
+        archetype: 'PersonalAgent',
+        auth_method: 'client_secret',
+        request_user_info: 'open_id',
+    });
+}
+function startPolling(ctx) {
+    return new Promise((resolve, reject) => {
+        var _a, _b;
+        let { baseUrl, interval } = ctx;
+        let domainSwitched = false;
+        let pollTimer = null;
+        let expireTimer = null;
+        const cleanup = () => {
+            var _a;
+            if (pollTimer !== null) {
+                clearTimeout(pollTimer);
+                pollTimer = null;
+            }
+            if (expireTimer !== null) {
+                clearTimeout(expireTimer);
+                expireTimer = null;
+            }
+            (_a = ctx.signal) === null || _a === void 0 ? void 0 : _a.removeEventListener('abort', onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(createError('abort', 'Registration was aborted'));
+        };
+        if ((_a = ctx.signal) === null || _a === void 0 ? void 0 : _a.aborted) {
+            return reject(createError('abort', 'Registration was aborted'));
+        }
+        (_b = ctx.signal) === null || _b === void 0 ? void 0 : _b.addEventListener('abort', onAbort, { once: true });
+        expireTimer = setTimeout(() => {
+            cleanup();
+            reject(createError('expired_token', 'Polling timed out'));
+        }, ctx.expireIn);
+        const poll = () => __awaiter(this, void 0, void 0, function* () {
+            var _c, _d, _e, _f, _g, _h;
+            try {
+                const pollRes = yield requestRegistration(baseUrl, {
+                    action: 'poll',
+                    device_code: ctx.deviceCode,
+                });
+                // Lark domain switch (once only)
+                if (((_c = pollRes.user_info) === null || _c === void 0 ? void 0 : _c.tenant_brand) === 'lark' && !domainSwitched) {
+                    baseUrl = ctx.larkBaseUrl;
+                    domainSwitched = true;
+                    (_d = ctx.onStatusChange) === null || _d === void 0 ? void 0 : _d.call(ctx, { status: 'domain_switched' });
+                    poll();
+                    return;
+                }
+                // Success
+                if (pollRes.client_id && pollRes.client_secret) {
+                    cleanup();
+                    resolve({
+                        client_id: pollRes.client_id,
+                        client_secret: pollRes.client_secret,
+                        user_info: pollRes.user_info,
+                    });
+                    return;
+                }
+                // Handle errors
+                switch (pollRes.error) {
+                    case 'authorization_pending':
+                        (_e = ctx.onStatusChange) === null || _e === void 0 ? void 0 : _e.call(ctx, { status: 'polling' });
+                        break;
+                    case 'slow_down':
+                        interval += 5000;
+                        (_f = ctx.onStatusChange) === null || _f === void 0 ? void 0 : _f.call(ctx, { status: 'slow_down', interval: interval / 1000 });
+                        break;
+                    case 'access_denied':
+                    case 'expired_token':
+                        cleanup();
+                        reject(createError(pollRes.error, (_g = pollRes.error_description) !== null && _g !== void 0 ? _g : 'Unknown error'));
+                        return;
+                    default:
+                        if (pollRes.error) {
+                            cleanup();
+                            reject(createError(pollRes.error, (_h = pollRes.error_description) !== null && _h !== void 0 ? _h : 'Unknown error'));
+                            return;
+                        }
+                        break;
+                }
+                pollTimer = setTimeout(poll, interval);
+            }
+            catch (e) {
+                cleanup();
+                reject(e);
+            }
+        });
+        poll();
+    });
+}
+function registerApp(options) {
+    var _a, _b, _c, _d;
+    return __awaiter(this, void 0, void 0, function* () {
+        const { domain, source, signal, onQRCodeReady, onStatusChange } = options;
+        const baseUrl = `https://${domain !== null && domain !== void 0 ? domain : DEFAULT_FEISHU_DOMAIN}`;
+        const beginRes = yield begin(baseUrl);
+        const qrCodeUrl = new URL(beginRes.verification_uri_complete);
+        qrCodeUrl.searchParams.set('from', 'sdk');
+        qrCodeUrl.searchParams.set('source', source ? `${SDK_NAME}/${source}` : SDK_NAME);
+        qrCodeUrl.searchParams.set('tp', 'sdk');
+        onQRCodeReady({
+            url: qrCodeUrl.toString(),
+            expireIn: (_a = beginRes.expire_in) !== null && _a !== void 0 ? _a : 600,
+        });
+        return startPolling({
+            baseUrl,
+            deviceCode: beginRes.device_code,
+            interval: ((_b = beginRes.interval) !== null && _b !== void 0 ? _b : 5) * 1000,
+            expireIn: ((_c = beginRes.expire_in) !== null && _c !== void 0 ? _c : 600) * 1000,
+            larkBaseUrl: `https://${(_d = options.larkDomain) !== null && _d !== void 0 ? _d : DEFAULT_LARK_DOMAIN}`,
+            signal,
+            onStatusChange,
+        });
+    });
+}
+
 exports.AESCipher = AESCipher;
 exports.Aily = Aily;
 exports.CAppTicket = CAppTicket;
@@ -85925,6 +86073,7 @@ exports.adaptKoaRouter = adaptKoaRouter;
 exports.defaultHttpInstance = defaultHttpInstance;
 exports.generateChallenge = generateChallenge;
 exports.messageCard = messageCard;
+exports.registerApp = registerApp;
 exports.withAll = withAll;
 exports.withHelpDeskCredential = withHelpDeskCredential;
 exports.withTenantKey = withTenantKey;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuiteoapi/node-sdk",
-  "version": "1.60.0",
+  "version": "1.61.0",
   "description": "larksuite open sdk for nodejs",
   "keywords": [
     "feishu",

package/types/index.d.ts

@@ -293196,4 +293196,32 @@ declare class Aily {
     };
 }
 
-export { AESCipher, Aily, AppType, CAppTicket, CTenantAccessToken, Cache, CardActionHandler, Client, Domain, EventDispatcher, IHandles as EventHandles, HttpInstance, HttpRequestOptions, InteractiveCard, InteractiveCardActionEvent, InteractiveCardActionItem, InteractiveCardButtonActionItem, InteractiveCardDatePickerActionItem, InteractiveCardDivElement, InteractiveCardDividerElement, InteractiveCardElement, InteractiveCardField, InteractiveCardImageElement, InteractiveCardImageItem, InteractiveCardLarkMdItem, InteractiveCardMarkdownElement, InteractiveCardNoteElement, InteractiveCardOverflowActionItem, InteractiveCardPlainTextItem, InteractiveCardSelectMenuActionItem, InteractiveCardTextItem, InteractiveCardTitle, InteractiveCardUrlItem, InterfaceCardActionElement, LoggerLevel, WSClient, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, messageCard, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };
+interface QRCodeInfo {
+    url: string;
+    expireIn: number;
+}
+interface StatusChangeInfo {
+    status: 'polling' | 'slow_down' | 'domain_switched';
+    interval?: number;
+}
+interface RegisterAppOptions {
+    domain?: string;
+    larkDomain?: string;
+    source?: string;
+    signal?: AbortSignal;
+    onQRCodeReady: (info: QRCodeInfo) => void;
+    onStatusChange?: (info: StatusChangeInfo) => void;
+}
+interface UserInfo {
+    open_id?: string;
+    tenant_brand?: 'feishu' | 'lark';
+}
+interface RegisterAppResult {
+    client_id: string;
+    client_secret: string;
+    user_info?: UserInfo;
+}
+
+declare function registerApp(options: RegisterAppOptions): Promise<RegisterAppResult>;
+
+export { AESCipher, Aily, AppType, CAppTicket, CTenantAccessToken, Cache, CardActionHandler, Client, Domain, EventDispatcher, IHandles as EventHandles, HttpInstance, HttpRequestOptions, InteractiveCard, InteractiveCardActionEvent, InteractiveCardActionItem, InteractiveCardButtonActionItem, InteractiveCardDatePickerActionItem, InteractiveCardDivElement, InteractiveCardDividerElement, InteractiveCardElement, InteractiveCardField, InteractiveCardImageElement, InteractiveCardImageItem, InteractiveCardLarkMdItem, InteractiveCardMarkdownElement, InteractiveCardNoteElement, InteractiveCardOverflowActionItem, InteractiveCardPlainTextItem, InteractiveCardSelectMenuActionItem, InteractiveCardTextItem, InteractiveCardTitle, InteractiveCardUrlItem, InterfaceCardActionElement, LoggerLevel, WSClient, adaptDefault, adaptExpress, adaptKoa, adaptKoaRouter, defaultHttpInstance, generateChallenge, messageCard, registerApp, withAll, withHelpDeskCredential, withTenantKey, withTenantToken, withUserAccessToken };