@dyqr/sdk 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,40 @@
+import { type DeepLinkTarget } from './deep-link.js';
+import type { CreateLinkInput, CreateLinkResult, GetLinkResult, ListLinksParams, ListLinksResult, QrFormat, QrImage, UpdateLinkInput } from './types.js';
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export type DyqrClientOptions = {
+    baseUrl: string;
+    token: string;
+    fetch?: FetchLike;
+    userAgent?: string;
+    dashboardUrl?: string;
+};
+export declare class DyqrClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    private readonly dashboardUrl;
+    readonly links: LinksApi;
+    constructor(options: DyqrClientOptions);
+    deepLink(target: DeepLinkTarget): string;
+    requestJson<T>(method: string, path: string, body?: unknown): Promise<T>;
+    requestBinary(method: string, path: string): Promise<{
+        contentType: string;
+        bytes: Uint8Array;
+    }>;
+    private send;
+    private toError;
+}
+declare class LinksApi {
+    private readonly client;
+    constructor(client: DyqrClient);
+    create(input: CreateLinkInput): Promise<CreateLinkResult>;
+    list(params?: ListLinksParams): Promise<ListLinksResult>;
+    get(alias: string): Promise<GetLinkResult>;
+    update(alias: string, patch: UpdateLinkInput): Promise<GetLinkResult>;
+    remove(alias: string): Promise<void>;
+    qr(alias: string, options?: {
+        format?: QrFormat;
+    }): Promise<QrImage>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,106 @@
+import { buildDashboardDeepLink } from './deep-link.js';
+import { DyqrApiError } from './errors.js';
+export class DyqrClient {
+    baseUrl;
+    token;
+    fetchImpl;
+    userAgent;
+    dashboardUrl;
+    links;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.token = options.token;
+        this.fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.userAgent = options.userAgent;
+        this.dashboardUrl = (options.dashboardUrl ?? options.baseUrl).replace(/\/+$/, '');
+        this.links = new LinksApi(this);
+    }
+    // 生成后台 deep link（campaign / 数据分析 / 高级设置等交给用户在网页里完成）。
+    deepLink(target) {
+        return buildDashboardDeepLink(this.dashboardUrl, target);
+    }
+    // 发起请求并解析 JSON；非 2xx 或 { ok:false } 时抛 DyqrApiError。
+    async requestJson(method, path, body) {
+        const response = await this.send(method, path, body);
+        const data = (await response.json().catch(() => null));
+        if (!response.ok || (data && typeof data === 'object' && 'ok' in data && data.ok === false)) {
+            throw this.toError(response.status, data);
+        }
+        return data;
+    }
+    // 获取二进制响应（如二维码图片）。
+    async requestBinary(method, path) {
+        const response = await this.send(method, path);
+        if (!response.ok) {
+            const data = (await response.json().catch(() => null));
+            throw this.toError(response.status, data);
+        }
+        const buffer = await response.arrayBuffer();
+        return {
+            contentType: response.headers.get('content-type') ?? 'application/octet-stream',
+            bytes: new Uint8Array(buffer),
+        };
+    }
+    async send(method, path, body) {
+        const headers = { authorization: `Bearer ${this.token}` };
+        if (this.userAgent) {
+            headers['user-agent'] = this.userAgent;
+        }
+        if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+        }
+        return this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    toError(status, data) {
+        const message = data?.message || data?.error_description || data?.error || `Request failed with status ${status}`;
+        return new DyqrApiError(message, status);
+    }
+}
+class LinksApi {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    // 创建短链（动态二维码默认指向该短链）。
+    create(input) {
+        return this.client.requestJson('POST', '/api/links', input);
+    }
+    // 分页列出当前账号的短链。
+    list(params = {}) {
+        const query = new URLSearchParams();
+        if (params.page)
+            query.set('page', String(params.page));
+        if (params.pageSize)
+            query.set('pageSize', String(params.pageSize));
+        if (params.campaign)
+            query.set('campaign', params.campaign);
+        if (params.tag)
+            query.set('tag', params.tag);
+        if (params.sortBy)
+            query.set('sortBy', params.sortBy);
+        if (params.sortOrder)
+            query.set('sortOrder', params.sortOrder);
+        const qs = query.toString();
+        return this.client.requestJson('GET', `/api/links${qs ? `?${qs}` : ''}`);
+    }
+    get(alias) {
+        return this.client.requestJson('GET', `/api/links/${encodeURIComponent(alias)}`);
+    }
+    // 更新短链（改目标 URL、标题、启用/停用、二维码样式等）。
+    update(alias, patch) {
+        return this.client.requestJson('PATCH', `/api/links/${encodeURIComponent(alias)}`, patch);
+    }
+    async remove(alias) {
+        await this.client.requestJson('DELETE', `/api/links/${encodeURIComponent(alias)}`);
+    }
+    // 导出二维码图片（默认 SVG，PNG 为 best-effort）。
+    async qr(alias, options = {}) {
+        const format = options.format === 'png' ? 'png' : 'svg';
+        const { contentType, bytes } = await this.client.requestBinary('GET', `/api/links/${encodeURIComponent(alias)}/qr?format=${format}`);
+        return { format, contentType, bytes };
+    }
+}

package/dist/deep-link.d.ts

@@ -0,0 +1,10 @@
+export type DeepLinkTarget = {
+    page: 'links' | 'campaigns' | 'account' | 'connections';
+} | {
+    page: 'link' | 'linkStats';
+    alias: string;
+} | {
+    page: 'campaign' | 'campaignStats';
+    campaignId: string;
+};
+export declare function buildDashboardDeepLink(dashboardUrl: string, target: DeepLinkTarget): string;

package/dist/deep-link.js

@@ -0,0 +1,21 @@
+export function buildDashboardDeepLink(dashboardUrl, target) {
+    const base = dashboardUrl.replace(/\/+$/, '');
+    switch (target.page) {
+        case 'links':
+            return `${base}/links`;
+        case 'link':
+            return `${base}/links/${encodeURIComponent(target.alias)}`;
+        case 'linkStats':
+            return `${base}/links/${encodeURIComponent(target.alias)}/stats`;
+        case 'campaigns':
+            return `${base}/campaigns`;
+        case 'campaign':
+            return `${base}/campaigns/${encodeURIComponent(target.campaignId)}`;
+        case 'campaignStats':
+            return `${base}/campaigns/${encodeURIComponent(target.campaignId)}/stats`;
+        case 'account':
+            return `${base}/account`;
+        case 'connections':
+            return `${base}/account/connections`;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class DyqrApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}

package/dist/errors.js

@@ -0,0 +1,9 @@
+// API 调用失败时抛出的统一错误，携带 HTTP 状态码与服务端返回的信息。
+export class DyqrApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'DyqrApiError';
+        this.status = status;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { DyqrClientOptions, FetchLike } from './client.js';
+export { DyqrClient } from './client.js';
+export type { DeepLinkTarget } from './deep-link.js';
+export { buildDashboardDeepLink } from './deep-link.js';
+export { DyqrApiError } from './errors.js';
+export type { CreateLinkInput, CreateLinkResult, DyqrLink, DyqrLinkListItem, GetLinkResult, LinkRedirectMode, ListLinksParams, ListLinksResult, QrFormat, QrImage, QrStyleInput, UpdateLinkInput, } from './types.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { DyqrClient } from './client.js';
+export { buildDashboardDeepLink } from './deep-link.js';
+export { DyqrApiError } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,90 @@
+export type DyqrLink = {
+    alias: string;
+    title: string;
+    targetUrl: string;
+    baseTargetUrl: string | null;
+    campaignId: string | null;
+    createdAt: string;
+    updatedAt: string;
+    isDisabled: boolean;
+    aliasKind: 'auto' | 'custom';
+    redirectMode: 'auto' | 'direct' | 'interstitial';
+    qrStyleSource: 'own' | 'campaign';
+    expiresAt: string | null;
+    maxClicks: number | null;
+    hasPassword: boolean;
+};
+export type DyqrLinkListItem = DyqrLink & {
+    shortUrl: string;
+    tags: string[];
+    last7DaysClicks: number;
+    last7DaysSeries: number[];
+};
+export type QrStyleInput = {
+    size?: number;
+    foreground?: string;
+    background?: string;
+    isTransparent?: boolean;
+    errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+    moduleShape?: 'square' | 'dot';
+    dotScale?: number;
+    logoDataUrl?: string | null;
+    logoScale?: number;
+    watermarkEnabled?: boolean;
+    eyes?: Record<string, unknown>;
+    frame?: Record<string, unknown>;
+};
+export type LinkRedirectMode = 'auto' | 'direct' | 'interstitial';
+export type CreateLinkInput = {
+    targetUrl: string;
+    alias?: string;
+    title?: string;
+    tags?: string[];
+    redirectMode?: LinkRedirectMode;
+    expiresAt?: string | null;
+    maxClicks?: number | null;
+    password?: string;
+    campaignId?: string | null;
+    qrStyle?: QrStyleInput;
+    qrStyleSource?: 'own' | 'campaign';
+};
+export type UpdateLinkInput = {
+    title?: string;
+    targetUrl?: string;
+    tags?: string[];
+    redirectMode?: LinkRedirectMode;
+    expiresAt?: string | null;
+    maxClicks?: number | null;
+    campaignId?: string | null;
+    qrStyle?: QrStyleInput;
+    qrStyleSource?: 'own' | 'campaign';
+    isDisabled?: boolean;
+};
+export type ListLinksParams = {
+    page?: number;
+    pageSize?: number;
+    campaign?: string;
+    tag?: string;
+    sortBy?: 'createdAt' | 'alias' | 'title';
+    sortOrder?: 'asc' | 'desc';
+};
+export type ListLinksResult = {
+    links: DyqrLinkListItem[];
+    page: number;
+    pageSize: number;
+    totalCount: number;
+};
+export type CreateLinkResult = {
+    link: DyqrLink;
+    shortUrl: string;
+};
+export type GetLinkResult = {
+    link: DyqrLink;
+    shortUrl: string;
+};
+export type QrFormat = 'svg' | 'png';
+export type QrImage = {
+    format: QrFormat;
+    contentType: string;
+    bytes: Uint8Array;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@dyqr/sdk",
+  "version": "0.1.0",
+  "description": "Typed client for the DYQR.me short-link & dynamic QR code API.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}