SDK TypeScript

@browlix/sdk không có phụ thuộc lúc chạy và dùng được trên Node 20 trở lên, Bun, Deno, Cloudflare Workers và trình duyệt được phép giữ khoá.

Cài đặt

Gói do Browlix phát hành, có SHA-256 ở trang tải về:

npm i https://browlix.com/api/public/sdk/v1/download/latest

Tạo client

import { Browlix, BrowlixError } from "@browlix/sdk";

const bx = new Browlix({ apiKey: process.env.BROWLIX_API_KEY! }); // SDK không tự đọc biến môi trường

Tuỳ chọn: baseUrl (mặc định https://browlix.com), attempts cho thử lại an toàn (mặc định 3), timeoutMs mỗi yêu cầu (mặc định 60 giây) và fetch tuỳ chỉnh.

Gọi mọi thao tác

const { data, page } = await bx.call("profiles.list", { query: { limit: 20, os: "windows" } });

for await (const profile of bx.paginate("profiles.list", { state: "active" })) {
  console.log(profile);
}

call(id, { path, query, body }) có kiểu theo tài liệu OpenAPI cho từng id thao tác: luôn có kiểu cho đầu vào, và từ SDK 0.9.0 có thêm kiểu cho data của mọi thao tác đã công bố trường phản hồi trong trang tham chiếu (profiles, sessions, bindings, devices, feedback, workspace). OPERATIONS liệt kê chúng. Trường phản hồi mới có thể xuất hiện không báo trước — xem Phiên bản và nhật ký thay đổi.

Thao tác ghi

Thao tác ghi tự có command_id khi bạn không truyền và trả lại ở reply.commandId. Thử lại tự động gửi lại cùng id, nên không có gì bị áp dụng hai lần. Sau OUTCOME_UNKNOWN, đọc kết quả bằng bx.receipt(commandId).

Phiên

const s = await bx.startSession({ profileId, deviceId, wait: { timeoutMs: 120_000 } });
const a = await bx.attach(s.data.id);
// … gắn Playwright trên máy này với a.endpoint và a.headers …
await bx.stopSession(s.data.id);

waitForSession và startSession({ wait }) chỉ chờ. Huỷ bằng signal (INTERRUPTED) hoặc hết thời gian (WAIT_TIMEOUT) vẫn để phiên chạy. stopSession là lệnh duy nhất kết thúc phiên.

Lỗi

Mọi lỗi là BrowlixError với code của API, retryable, và info (status, details, correlationId, commandId, retryAfterSeconds). Chuỗi trông giống khoá được che khỏi thông báo.

try {
  await bx.call("sessions.start", { body: { profile_id: profileId, device_id: deviceId } });
} catch (e) {
  if (e instanceof BrowlixError && e.code === "BUSY") console.log("BUSY", e.info.details);
  else throw e;
}

Webhook

verifyWebhook(secret, headers, rawBody) kiểm chữ ký Standard Webhooks và thời điểm (lệch tối đa 5 phút) rồi trả về sự kiện đã đọc — xem Webhook.