lexmount 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lexmount
+
+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,493 @@
+# Lexmount Node.js SDK
+
+[English](#english) | [中文](#中文)
+
+---
+
+## English
+
+Node.js SDK for the Lexmount browser automation service.
+
+### Features
+
+- Node.js 18+ only
+- Typed public API with ESM and CommonJS support
+- Session management with pagination support
+- Persistent context management
+- Structured SDK errors
+- Configurable SDK logging
+- TSDoc + TypeDoc based API documentation generation
+
+### Requirements
+
+- Node.js 18 LTS or later
+- npm 9+ recommended
+- Playwright is optional and only needed when you connect to browser sessions
+
+### Installation
+
+#### Internal package / tgz
+
+```bash
+npm install <lexmount-package-or-tgz>
+```
+
+#### From source
+
+```bash
+git clone <repository-url>
+cd lexmount-js-sdk
+npm install
+npm run build
+```
+
+### Configuration
+
+The SDK reads credentials from constructor options or environment variables.
+
+```bash
+LEXMOUNT_API_KEY=your-api-key
+LEXMOUNT_PROJECT_ID=your-project-id
+LEXMOUNT_BASE_URL=https://api.lexmount.cn
+```
+
+`LEXMOUNT_BASE_URL` is optional. The default is `https://api.lexmount.cn`.
+
+### Quick Start
+
+```ts
+import { Lexmount } from 'lexmount';
+
+const client = new Lexmount({
+  apiKey: process.env.LEXMOUNT_API_KEY,
+  projectId: process.env.LEXMOUNT_PROJECT_ID,
+});
+
+const session = await client.sessions.create();
+console.log(session.id);
+console.log(session.connectUrl);
+
+await session.close();
+client.close();
+```
+
+### Sessions
+
+Create a session:
+
+```ts
+const session = await client.sessions.create({
+  browserMode: 'normal',
+});
+```
+
+Create a session with a persistent context:
+
+```ts
+const context = await client.contexts.create({
+  metadata: { userId: '1001' },
+});
+
+const session = await client.sessions.create({
+  context: { id: context.id, mode: 'readWrite' },
+});
+```
+
+List sessions with pagination metadata:
+
+```ts
+const result = await client.sessions.list({ status: 'active' });
+
+console.log(result.pagination.totalCount);
+for (const session of result) {
+  console.log(session.id, session.status);
+}
+```
+
+Delete a session:
+
+```ts
+await client.sessions.delete({ sessionId: 'session-id' });
+```
+
+### Contexts
+
+Create and inspect contexts:
+
+```ts
+const context = await client.contexts.create({
+  metadata: { owner: 'demo' },
+});
+
+const details = await client.contexts.get(context.id);
+console.log(details.status);
+```
+
+List contexts:
+
+```ts
+const contexts = await client.contexts.list({
+  status: 'available',
+  limit: 20,
+});
+```
+
+Force release a stuck lock:
+
+```ts
+await client.contexts.forceRelease('context-id');
+```
+
+### Playwright Example
+
+```ts
+import { chromium } from 'playwright';
+import { Lexmount } from 'lexmount';
+
+const client = new Lexmount();
+const session = await client.sessions.create();
+
+const browser = await chromium.connectOverCDP(session.connectUrl);
+const context = browser.contexts()[0];
+const page = context.pages()[0] ?? (await context.newPage());
+
+await page.goto('https://example.com');
+console.log(await page.title());
+
+await browser.close();
+await session.close();
+client.close();
+```
+
+### Error Handling
+
+```ts
+import {
+  AuthenticationError,
+  ContextLockedError,
+  NetworkError,
+  TimeoutError,
+} from 'lexmount';
+
+try {
+  await client.sessions.create({
+    context: { id: 'ctx_123', mode: 'readWrite' },
+  });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Authentication failed');
+  } else if (error instanceof ContextLockedError) {
+    console.error(error.activeSessionId, error.retryAfter);
+  } else if (error instanceof TimeoutError || error instanceof NetworkError) {
+    console.error('Temporary connectivity issue');
+  } else {
+    throw error;
+  }
+}
+```
+
+### Logging
+
+```ts
+import { setLogLevel } from 'lexmount';
+
+setLogLevel('DEBUG');
+```
+
+Available levels:
+
+- `DEBUG`
+- `INFO`
+- `WARNING`
+- `ERROR`
+- `CRITICAL`
+- `SILENT`
+
+### Documentation Generation
+
+Public API docs are generated from TSDoc comments.
+
+```bash
+npm run docs:api
+npm run docs:html
+```
+
+Generated files are written to `generated-docs/` and are not meant to be committed.
+
+### Examples
+
+Example scripts live in [examples](./examples):
+
+- `playwright-basic.ts`
+- `session-management.ts`
+- `context-basic.ts`
+- `context-list-get.ts`
+- `context-modes.ts`
+- `context-lock-handling.ts`
+
+Run them with:
+
+```bash
+cd examples
+npm install
+npm run playwright-basic
+npm run session-management
+```
+
+### Development
+
+```bash
+npm run build
+npm run typecheck
+npm test
+npm run docs:api
+```
+
+### License
+
+MIT License
+
+---
+
+## 中文
+
+Lexmount 浏览器自动化服务的 Node.js SDK。
+
+### 特性
+
+- 仅支持 Node.js 18+
+- 提供完整类型定义，同时支持 ESM 和 CommonJS
+- 会话管理，支持分页信息
+- 持久化 context 管理
+- 结构化 SDK 异常
+- 可配置 SDK 日志
+- 基于 TSDoc + TypeDoc 的自动文档生成能力
+
+### 运行要求
+
+- Node.js 18 LTS 或更高版本
+- 建议使用 npm 9+
+- 如果需要连接浏览器会话，才需要额外安装 Playwright
+
+### 安装
+
+#### 内部包 / tgz
+
+```bash
+npm install <lexmount-package-or-tgz>
+```
+
+#### 从源码安装
+
+```bash
+git clone <repository-url>
+cd lexmount-js-sdk
+npm install
+npm run build
+```
+
+### 配置
+
+SDK 会优先读取构造参数，其次读取环境变量：
+
+```bash
+LEXMOUNT_API_KEY=your-api-key
+LEXMOUNT_PROJECT_ID=your-project-id
+LEXMOUNT_BASE_URL=https://api.lexmount.cn
+```
+
+`LEXMOUNT_BASE_URL` 可选，默认值是 `https://api.lexmount.cn`。
+
+### 快速开始
+
+```ts
+import { Lexmount } from 'lexmount';
+
+const client = new Lexmount({
+  apiKey: process.env.LEXMOUNT_API_KEY,
+  projectId: process.env.LEXMOUNT_PROJECT_ID,
+});
+
+const session = await client.sessions.create();
+console.log(session.id);
+console.log(session.connectUrl);
+
+await session.close();
+client.close();
+```
+
+### Sessions
+
+创建会话：
+
+```ts
+const session = await client.sessions.create({
+  browserMode: 'normal',
+});
+```
+
+结合持久化 context 创建会话：
+
+```ts
+const context = await client.contexts.create({
+  metadata: { userId: '1001' },
+});
+
+const session = await client.sessions.create({
+  context: { id: context.id, mode: 'readWrite' },
+});
+```
+
+分页列出会话：
+
+```ts
+const result = await client.sessions.list({ status: 'active' });
+
+console.log(result.pagination.totalCount);
+for (const session of result) {
+  console.log(session.id, session.status);
+}
+```
+
+删除会话：
+
+```ts
+await client.sessions.delete({ sessionId: 'session-id' });
+```
+
+### Contexts
+
+创建并查看 context：
+
+```ts
+const context = await client.contexts.create({
+  metadata: { owner: 'demo' },
+});
+
+const details = await client.contexts.get(context.id);
+console.log(details.status);
+```
+
+列出 context：
+
+```ts
+const contexts = await client.contexts.list({
+  status: 'available',
+  limit: 20,
+});
+```
+
+强制释放卡住的锁：
+
+```ts
+await client.contexts.forceRelease('context-id');
+```
+
+### Playwright 示例
+
+```ts
+import { chromium } from 'playwright';
+import { Lexmount } from 'lexmount';
+
+const client = new Lexmount();
+const session = await client.sessions.create();
+
+const browser = await chromium.connectOverCDP(session.connectUrl);
+const context = browser.contexts()[0];
+const page = context.pages()[0] ?? (await context.newPage());
+
+await page.goto('https://example.com');
+console.log(await page.title());
+
+await browser.close();
+await session.close();
+client.close();
+```
+
+### 错误处理
+
+```ts
+import {
+  AuthenticationError,
+  ContextLockedError,
+  NetworkError,
+  TimeoutError,
+} from 'lexmount';
+
+try {
+  await client.sessions.create({
+    context: { id: 'ctx_123', mode: 'readWrite' },
+  });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('鉴权失败');
+  } else if (error instanceof ContextLockedError) {
+    console.error(error.activeSessionId, error.retryAfter);
+  } else if (error instanceof TimeoutError || error instanceof NetworkError) {
+    console.error('网络或超时问题');
+  } else {
+    throw error;
+  }
+}
+```
+
+### 日志
+
+```ts
+import { setLogLevel } from 'lexmount';
+
+setLogLevel('DEBUG');
+```
+
+可用级别：
+
+- `DEBUG`
+- `INFO`
+- `WARNING`
+- `ERROR`
+- `CRITICAL`
+- `SILENT`
+
+### 自动文档生成
+
+公开 API 文档基于源码里的 TSDoc 注释生成。
+
+```bash
+npm run docs:api
+npm run docs:html
+```
+
+生成文件会输出到 `generated-docs/`，默认不提交到仓库。
+
+### 示例
+
+示例脚本位于 [examples](./examples)：
+
+- `playwright-basic.ts`
+- `session-management.ts`
+- `context-basic.ts`
+- `context-list-get.ts`
+- `context-modes.ts`
+- `context-lock-handling.ts`
+
+运行方式：
+
+```bash
+cd examples
+npm install
+npm run playwright-basic
+npm run session-management
+```
+
+### 开发
+
+```bash
+npm run build
+npm run typecheck
+npm test
+npm run docs:api
+```
+
+### 许可证
+
+MIT License