Node.js 和浏览器

Lix.li JavaScript SDK

Lix.li URL 缩短 API 官方 JavaScript SDK。在 Node.js 和浏览器环境中运行。使用 async/await 和基于类的干净 DTO 创建短链接、管理分组并跟踪点击。

// npm install lix-url
const { Client } = require('lix-url');

const client = new Client('lix_live_xxx');

async function main() {
    const result = await client.links().create('https://example.com');
    console.log(result.link.shortUrl);
    // https://lix.li/a3b7k2
}

main();

功能

JavaScript URL 缩短 API 集成所需的一切

基于 async/await、基于类的干净 DTO 和可交换的 fetch 函数构建，适用于 Node.js 或浏览器。

链接管理

创建、获取、更新、删除和列出短链接。具有定型类响应的完整 CRUD。

分组管理

将链接组织成组。创建旋转分组进行网页 A/B 测试。

账户和使用量 API

检索帐户个人资料、计划详情和实时使用限制。

基于类的 DTO

每个 API 响应都是一个普通 JavaScript 类实例。没有原始对象 — 具有可预测结构和点记号访问。

定型异常

6 个专用异常类型用于验证、授权、速率限制、服务器错误和传输故障。

自定义 Fetch

注入任何与 fetch 兼容的函数。可与 Node.js fetch、undici 或浏览器 fetch 配合使用。

快速开始

30 秒就能上手

在任何支持 fetch 的 Node.js 或浏览器环境中运行。没有重型依赖 — 只有一个干净的 HTTP 客户端层。

Node.js 18+ MIT License Browser

通过 npm 安装

将 SDK 添加到您的 Node.js 或浏览器项目。

 npm install lix-url

实例化客户端

传入您的 API 密钥。可选注入自定义的 fetch 函数以进行测试或边缘运行时。

const { Client } = require('lix-url');
const client = new Client('lix_live_xxx');

// With custom fetch (e.g., for testing)
const client = new Client('lix_live_xxx', myFetchFn);

创建您的第一个链接

缩短 URL 并获取带有短链接和使用信息的定型 LinkShortenResult。

const result = await client.links().create('https://example.com');
console.log(result.link.shortUrl);
// https://lix.li/a3b7k2
// Links used: 42 / 100
console.log(result.usage.used, '/', result.usage.limit);

链接 API

JavaScript 中完整的链接生命周期

使用自定义别名、UTM 参数、跟踪像素、密码保护和过期日期创建短链接。每次操作都返回一个定型的类实例。

// Create a basic link
const result = await client.links().create('https://example.com');

// With custom alias and UTM
const result = await client.links().create(
    'https://example.com',
    'summer-sale',           // alias
    'My Summer Sale',        // title
    null,                    // groupId
    ['marketing', '2026'],   // tags
    [],                      // meta
    {                        // utm
        source: 'newsletter',
        medium: 'email',
        campaign: 'summer-sale',
    },
    [1, 2],                 // trackingPixelIds
    null,                    // activeBeforeDatetime
    null,                    // password
    true                     // isPublic
);

// Password protection + expiration
const result = await client.links().create(
    'https://example.com',
    null, null, null, [], [], [], [],
    '2026-12-31T23:59:59Z',  // activeBeforeDatetime
    'secret123'              // password
);

create() 使用别名、UTM 标签、跟踪像素、密码、过期日期和自定义设置创建短链接。
get() 检索带有元数据、标签、组、使用数据和当前状态的短链接。
update() 更新链接的任何字段：URL、标题、组、标签、UTM、密码、可见性。
delete() 按 ID 软删除链接。成功时返回 void。
list() 使用分页、过滤和定型集合响应浏览链接。使用 limit 和 fromId 进行分页。返回带有元数据的 Links DTO。

分页示例： $client->links()->list(limit: 100, fromId: 500) 返回从 ID 500 开始的下 100 个链接，其中 ResponseMeta 包含总数和下一个 URL。

分组 API

组织和旋转链接

分组有助于按营销活动、团队或项目对链接进行分类。旋转组通过在多个链接之间分配流量来实现 A/B 测试。

create() 使用名称、可选描述和旋转模式创建组。
get() 检索具有所有元数据的组。
update() 更名、更新描述或切换旋转模式。
delete() 删除组同时保持链接数据完整。
list() 使用分页和定型集合响应浏览组。

// Create a regular group
const group = await client.groups().create('Marketing');
console.log(group.name);

// Create a rotating group for A/B testing
const group = await client.groups().create(
    'Landing Pages',
    null,
    true   // isRotate
);

// Update group
const group = await client.groups().update(
    10,
    null,
    'Updated description'
);

// List with pagination
const response = await client.groups().list(10, 1000);
for (const group of response.groups) {
    console.log(group.name);
}

账户和使用量 API

账户和使用详情

检索您的个人资料、计划和实时使用限制 — 一切都返回为嵌套的类实例，具有完整的属性访问。

const profile = await client.profile().me();

// Account info
console.log(profile.client.name, profile.client.email);
console.log(profile.user.email);

// Plan details
console.log(profile.plan.name, profile.plan.endDatetime);

// Usage limits
console.log(profile.usages.links.remaining);
console.log(profile.usages.apiLinks.used);
console.log(profile.usages.massLinks.limit);

客户

组织和帐户元数据。

用户

经过身份验证的用户信息和帐户详情。

计划

当前订阅和计费周期。

使用量

API 限制、链接配额和剩余使用量。

错误处理

7 个定型异常用于精确控制

捕获您正好需要的内容。所有异常都扩展自 LixException。ValidationException 将完整的字段级验证错误数据包含在 err.data 中。

const {
    ValidationException,
    NotFoundException,
    UnauthorizedException,
    RateLimitException,
    ServerException
} = require('lix-url');

try {
    await client.links().create('invalid-url');
} catch (err) {
    if (err instanceof ValidationException) {
        // Field-level validation errors
        console.error('Validation:', err.data);
    } else if (err instanceof NotFoundException) {
        console.error('Not found:', err.message);
    } else if (err instanceof UnauthorizedException) {
        // Invalid API key
    } else if (err instanceof RateLimitException) {
        // Too many requests — retry after
    } else if (err instanceof ServerException) {
        // 5xx server error
    } else {
        // Generic Lix or network error
        console.error('Error:', err.message);
    }
}

ValidationException

400 — 无效输入。访问 err.data 以获取字段错误。

UnauthorizedException

401 — 缺少、无效或已过期的 API 凭据。

NotFoundException

404 — 未找到链接、组或资源。

RateLimitException

429 — 超出速率限制。

ServerException

500 — 意外的服务器错误。

HttpClientException

网络 / 传输故障。

所有异常都扩展自 LixException，其扩展了原生的 Error。捕获基类以处理任何 SDK 错误，或定位特定类以进行精细处理。

生态系统

流行技术栈的官方 SDK

从 PHP、JavaScript、Python 或 Go 使用相同的 Lix.li API，配备为每个生态系统量身定制的 SDK。

Python SDK

用于短链接、分组、分析和自动化的定型 Python 客户端。为现代 Python 应用和工作流构建。

GitHub 文档

Go SDK

具有定型结构、上下文支持和为 URL 缩短 API 集成的惯用错误处理的原生 Go SDK。

GitHub 文档

PHP SDK

具有定型 DTO、只读模型、专用异常和通过 Composer 优先安装的现代 PHP SDK。

GitHub 文档

准备好在 JavaScript 中缩短链接了吗？

安装 SDK，获取 API 密钥，并在一分钟内开始创建短链接。

GitHub Repository npm 创建 API 密钥