@frankie0736/dingtalk-notify 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frankie
+
+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,129 @@
+# @frankie0736/dingtalk-notify
+
+Thin, zero-dependency client for the [DingTalk Notification Server](https://github.com/frankie0736/dingtalk-notify-client). Send DingTalk group-chat notifications over a single authenticated endpoint — no HMAC signing, no `@mobile` injection, no per-service boilerplate.
+
+The server handles signing, encryption, and auditing. This package handles the one thing every caller would otherwise re-implement: a correct `fetch` with the right headers, body shape, and — crucially — the "HTTP 200 but DingTalk rejected it" failure that a naive wrapper silently treats as success.
+
+- **Pure ESM**, zero runtime dependencies.
+- Runs on **Node.js 18+, Bun, and Cloudflare Workers / Edge** (anything with global `fetch`).
+- **Throws on failure**, with a single `DingTalkError` whose `kind` tells you exactly what went wrong.
+
+> Not for browsers: the bearer token must never ship to a frontend.
+
+## Install
+
+```bash
+npm install @frankie0736/dingtalk-notify
+# or
+bun add @frankie0736/dingtalk-notify
+```
+
+## Quick start
+
+```ts
+import { DingTalk } from '@frankie0736/dingtalk-notify';
+
+const dt = new DingTalk({ token: process.env.DINGTALK_TOKEN! }); // 'dnk_...'
+
+// Plain text — atMobiles here fires a real @-push + device notification.
+await dt.text('🔔 Build #123 failed', { atMobiles: ['13800138000'] });
+
+// Markdown card — rich formatting (no push; see below).
+await dt.markdown('Build #123', '### main 失败\n- env: prod\n- [logs](https://example.com)');
+```
+
+## `@`-mention behavior (a DingTalk platform quirk)
+
+| Mode | Rich formatting | `atMobiles` triggers push? |
+| --- | --- | --- |
+| `text` | No | **Yes** — real blue-badge @ + device notification |
+| `markdown` | Yes (lists, links, bold, code) | **No** — name renders in the card, but no push fires |
+
+This asymmetry is a DingTalk limitation, not a choice of this library.
+
+### `combo()` — push + rich content in one call
+
+When you need both a reliable @-push **and** a rich card, send a short `text` (the actual notification) followed by a `markdown` card with the detail:
+
+```ts
+await dt.combo({
+  alert: '🔔 Build #123 failed — see detail',  // short text, carries the @
+  title: 'Build #123',
+  detail: '### main 失败\n- env: prod\n- [logs](https://example.com)',
+  atMobiles: ['13800138000'],
+});
+```
+
+The `text` leg is sent first (it's the real push). If the `markdown` leg then fails, the thrown error carries `comboLeg: 'markdown'` and the already-sent text result on `comboPartial.text`.
+
+## Error handling
+
+Every method throws [`DingTalkError`](./src/errors.ts) on failure. Branch on `kind`:
+
+```ts
+import { DingTalk, DingTalkError } from '@frankie0736/dingtalk-notify';
+
+try {
+  await dt.text('hi', { atMobiles: ['13800138000'] });
+} catch (err) {
+  if (err instanceof DingTalkError) {
+    switch (err.kind) {
+      case 'validation': break; // bad input — no request was sent
+      case 'network':    break; // fetch failed or timed out
+      case 'http':       break; // non-2xx; err.status, err.serverError
+      case 'rejected':   break; // HTTP 200 but DingTalk said no; err.errcode, err.errmsg, err.logId
+    }
+  }
+}
+```
+
+| `kind` | Meaning | Useful fields |
+| --- | --- | --- |
+| `validation` | Input rejected client-side; **no request sent** | `message` |
+| `network` | `fetch` threw or the request timed out | `cause` |
+| `http` | Server replied non-2xx | `status`, `serverError`, `details`, `requestId` |
+| `rejected` | HTTP 200 but `ok:false` (DingTalk rejected) | `errcode`, `errmsg`, `rawBody`, `logId`, `requestId` |
+
+`err.retryable` is `true` for `network` failures and HTTP 5xx.
+
+## Options
+
+```ts
+new DingTalk({
+  token: 'dnk_...',                          // required, per-robot bearer token
+  baseUrl: 'https://dingtalk-notify.210k.cc', // default
+  timeoutMs: 10_000,                          // per-request, via AbortController
+  retries: 0,                                 // retries network/timeout/5xx only; never 4xx or rejected
+  fetch: customFetch,                         // optional; defaults to global fetch
+  userAgent: '@frankie0736/dingtalk-notify',  // optional override
+});
+```
+
+## Result shape
+
+`text` / `markdown` / `notify` resolve to:
+
+```ts
+{
+  logId: string;      // server audit-log id (lg_...); cross-reference in /admin/logs
+  requestId: string;  // trace id (rq_...); also in server logs
+  dingtalk: { httpStatus: number | null; errcode: number | null; errmsg: string | null };
+}
+```
+
+`combo` resolves to `{ text: NotifyResult, markdown: NotifyResult }`.
+
+> Field names are camelCase here; the server's wire format uses snake_case (`log_id`, `request_id`, `at_mobiles`). The SDK converts both ways for you.
+
+## Development
+
+```bash
+bun install
+bun run check   # typecheck
+bun run test    # build + node:test
+bun run build   # emit dist/
+```
+
+## License
+
+MIT © Frankie

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+import type { ComboInput, ComboResult, DingTalkOptions, NotifyBody, NotifyResult } from './types.js';
+/**
+ * Client for the DingTalk Notification Server.
+ *
+ * ```ts
+ * const dt = new DingTalk({ token: process.env.DINGTALK_TOKEN! });
+ * await dt.text('🔔 Build #123 failed', { atMobiles: ['13800138000'] });
+ * ```
+ *
+ * Every method throws {@link DingTalkError} on failure — including the
+ * easy-to-miss case where the transport succeeds but DingTalk rejects the
+ * message (HTTP 200, `ok:false`).
+ */
+export declare class DingTalk {
+    #private;
+    constructor(options: DingTalkOptions);
+    /** Thin core: send a fully-formed message body. */
+    notify(body: NotifyBody): Promise<NotifyResult>;
+    /** Send a plain `text` message. `atMobiles` here triggers a real @-push. */
+    text(content: string, opts?: {
+        atMobiles?: string[];
+        atAll?: boolean;
+    }): Promise<NotifyResult>;
+    /**
+     * Send a `markdown` card. Note: per the DingTalk platform, `@` mentions
+     * render in the card but do **not** fire a device push — use {@link combo}
+     * (or a separate {@link text} call) when you need the push.
+     */
+    markdown(title: string, content: string, opts?: {
+        atMobiles?: string[];
+        atAll?: boolean;
+    }): Promise<NotifyResult>;
+    /**
+     * Recommended pattern when you want both a reliable @-push and rich content:
+     * send a short `text` (the actual notification, carrying the @) followed by a
+     * `markdown` card with the full detail.
+     *
+     * The `text` leg is sent first because it is the real push. If the `markdown`
+     * leg then fails, the thrown {@link DingTalkError} carries `comboLeg:'markdown'`
+     * and the already-succeeded `text` result on `comboPartial.text`.
+     */
+    combo(input: ComboInput): Promise<ComboResult>;
+}

package/dist/client.js

@@ -0,0 +1,279 @@
+import { DingTalkError } from './errors.js';
+const DEFAULT_BASE_URL = 'https://dingtalk-notify.210k.cc';
+const NOTIFY_PATH = '/api/v1/notify';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_USER_AGENT = '@frankie0736/dingtalk-notify';
+const MOBILE_RE = /^\+?\d{6,20}$/;
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Client for the DingTalk Notification Server.
+ *
+ * ```ts
+ * const dt = new DingTalk({ token: process.env.DINGTALK_TOKEN! });
+ * await dt.text('🔔 Build #123 failed', { atMobiles: ['13800138000'] });
+ * ```
+ *
+ * Every method throws {@link DingTalkError} on failure — including the
+ * easy-to-miss case where the transport succeeds but DingTalk rejects the
+ * message (HTTP 200, `ok:false`).
+ */
+export class DingTalk {
+    #token;
+    #url;
+    #timeoutMs;
+    #retries;
+    #fetch;
+    #userAgent;
+    constructor(options) {
+        if (!options || typeof options.token !== 'string' || options.token.length === 0) {
+            throw new DingTalkError({ kind: 'validation', message: 'token is required' });
+        }
+        const base = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.#token = options.token;
+        this.#url = base + NOTIFY_PATH;
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#retries = Math.max(0, options.retries ?? 0);
+        this.#userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+        const f = options.fetch ?? globalThis.fetch;
+        if (typeof f !== 'function') {
+            throw new DingTalkError({
+                kind: 'validation',
+                message: 'global fetch is unavailable; pass options.fetch',
+            });
+        }
+        // Preserve `this` binding for environments where fetch is a bound global.
+        this.#fetch = f.bind(globalThis);
+    }
+    /** Thin core: send a fully-formed message body. */
+    async notify(body) {
+        const wire = buildWire(body);
+        return this.#sendWithRetry(wire);
+    }
+    /** Send a plain `text` message. `atMobiles` here triggers a real @-push. */
+    async text(content, opts = {}) {
+        const body = { type: 'text', content };
+        if (opts.atMobiles !== undefined)
+            body.atMobiles = opts.atMobiles;
+        if (opts.atAll !== undefined)
+            body.atAll = opts.atAll;
+        return this.notify(body);
+    }
+    /**
+     * Send a `markdown` card. Note: per the DingTalk platform, `@` mentions
+     * render in the card but do **not** fire a device push — use {@link combo}
+     * (or a separate {@link text} call) when you need the push.
+     */
+    async markdown(title, content, opts = {}) {
+        const body = { type: 'markdown', title, content };
+        if (opts.atMobiles !== undefined)
+            body.atMobiles = opts.atMobiles;
+        if (opts.atAll !== undefined)
+            body.atAll = opts.atAll;
+        return this.notify(body);
+    }
+    /**
+     * Recommended pattern when you want both a reliable @-push and rich content:
+     * send a short `text` (the actual notification, carrying the @) followed by a
+     * `markdown` card with the full detail.
+     *
+     * The `text` leg is sent first because it is the real push. If the `markdown`
+     * leg then fails, the thrown {@link DingTalkError} carries `comboLeg:'markdown'`
+     * and the already-succeeded `text` result on `comboPartial.text`.
+     */
+    async combo(input) {
+        const at = {};
+        if (input.atMobiles !== undefined)
+            at.atMobiles = input.atMobiles;
+        if (input.atAll !== undefined)
+            at.atAll = input.atAll;
+        let textResult;
+        try {
+            textResult = await this.text(input.alert, at);
+        }
+        catch (err) {
+            throw tagComboLeg(err, 'text');
+        }
+        try {
+            const markdownResult = await this.markdown(input.title, input.detail);
+            return { text: textResult, markdown: markdownResult };
+        }
+        catch (err) {
+            throw tagComboLeg(err, 'markdown', { text: textResult });
+        }
+    }
+    async #sendWithRetry(wire) {
+        let attempt = 0;
+        for (;;) {
+            try {
+                return await this.#sendOnce(wire);
+            }
+            catch (err) {
+                const isRetryable = err instanceof DingTalkError && err.retryable;
+                if (!isRetryable || attempt >= this.#retries)
+                    throw err;
+                await sleep(250 * 2 ** attempt);
+                attempt += 1;
+            }
+        }
+    }
+    async #sendOnce(wire) {
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, this.#timeoutMs);
+        let res;
+        try {
+            res = await this.#fetch(this.#url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    Authorization: `Bearer ${this.#token}`,
+                    'User-Agent': this.#userAgent,
+                },
+                body: JSON.stringify(wire),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            throw new DingTalkError({
+                kind: 'network',
+                message: timedOut ? `request timed out after ${this.#timeoutMs}ms` : 'network request failed',
+                cause: err,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const rawText = await res.text().catch(() => '');
+        let parsed;
+        if (rawText.length > 0) {
+            try {
+                parsed = JSON.parse(rawText);
+            }
+            catch {
+                parsed = undefined;
+            }
+        }
+        if (!res.ok) {
+            throw new DingTalkError({
+                kind: 'http',
+                status: res.status,
+                message: `server returned HTTP ${res.status}${parsed?.error ? ` (${parsed.error})` : ''}`,
+                ...(parsed?.error !== undefined ? { serverError: parsed.error } : {}),
+                ...(parsed?.details !== undefined ? { details: parsed.details } : {}),
+                ...(parsed?.request_id !== undefined ? { requestId: parsed.request_id } : {}),
+            });
+        }
+        if (!parsed) {
+            throw new DingTalkError({
+                kind: 'http',
+                status: res.status,
+                message: `server returned HTTP ${res.status} with an unparseable body`,
+            });
+        }
+        const dt = parsed.dingtalk ?? {};
+        if (parsed.ok === true) {
+            return {
+                logId: parsed.log_id ?? '',
+                requestId: parsed.request_id ?? '',
+                dingtalk: {
+                    httpStatus: dt.http_status ?? null,
+                    errcode: dt.errcode ?? null,
+                    errmsg: dt.errmsg ?? null,
+                },
+            };
+        }
+        // HTTP 200 but DingTalk rejected the message.
+        throw new DingTalkError({
+            kind: 'rejected',
+            message: `DingTalk rejected the message: ${dt.errmsg ?? 'unknown'} (errcode ${dt.errcode ?? 'unknown'})`,
+            errcode: dt.errcode ?? null,
+            errmsg: dt.errmsg ?? null,
+            ...(dt.raw_body !== undefined ? { rawBody: dt.raw_body } : {}),
+            ...(parsed.log_id !== undefined ? { logId: parsed.log_id } : {}),
+            ...(parsed.request_id !== undefined ? { requestId: parsed.request_id } : {}),
+        });
+    }
+}
+/**
+ * Re-wrap a leg failure with combo context, preserving every field. Non-SDK
+ * errors (which shouldn't normally occur) are returned untouched.
+ */
+function tagComboLeg(err, leg, partial) {
+    if (!(err instanceof DingTalkError))
+        return err;
+    return new DingTalkError({
+        kind: err.kind,
+        message: `combo ${leg} leg failed: ${err.message}`,
+        ...(err.status !== undefined ? { status: err.status } : {}),
+        ...(err.serverError !== undefined ? { serverError: err.serverError } : {}),
+        ...(err.details !== undefined ? { details: err.details } : {}),
+        ...(err.errcode !== undefined ? { errcode: err.errcode } : {}),
+        ...(err.errmsg !== undefined ? { errmsg: err.errmsg } : {}),
+        ...(err.rawBody !== undefined ? { rawBody: err.rawBody } : {}),
+        ...(err.logId !== undefined ? { logId: err.logId } : {}),
+        ...(err.requestId !== undefined ? { requestId: err.requestId } : {}),
+        comboLeg: leg,
+        ...(partial !== undefined ? { comboPartial: partial } : {}),
+        cause: err,
+    });
+}
+/** Validate input at the boundary and convert to the snake_case wire shape. */
+function buildWire(body) {
+    if (!body || (body.type !== 'text' && body.type !== 'markdown')) {
+        throw new DingTalkError({
+            kind: 'validation',
+            message: "type must be 'text' or 'markdown'",
+        });
+    }
+    if (typeof body.content !== 'string' || body.content.length < 1 || body.content.length > 20_000) {
+        throw new DingTalkError({
+            kind: 'validation',
+            message: 'content must be a string of 1–20000 chars',
+        });
+    }
+    const wire = { type: body.type, content: body.content };
+    if (body.type === 'markdown') {
+        if (typeof body.title !== 'string' || body.title.length < 1 || body.title.length > 200) {
+            throw new DingTalkError({
+                kind: 'validation',
+                message: 'markdown title must be a string of 1–200 chars',
+            });
+        }
+        wire.title = body.title;
+    }
+    const atMobiles = body.atMobiles;
+    if (atMobiles !== undefined) {
+        if (!Array.isArray(atMobiles) || atMobiles.length > 50) {
+            throw new DingTalkError({
+                kind: 'validation',
+                message: 'atMobiles must be an array of at most 50 numbers',
+            });
+        }
+        for (const m of atMobiles) {
+            if (typeof m !== 'string' || !MOBILE_RE.test(m)) {
+                throw new DingTalkError({
+                    kind: 'validation',
+                    message: `invalid mobile number: ${String(m)} (expected /^\\+?\\d{6,20}$/)`,
+                });
+            }
+        }
+        if (atMobiles.length > 0)
+            wire.at_mobiles = atMobiles;
+    }
+    if (body.atAll === true) {
+        if (wire.at_mobiles && wire.at_mobiles.length > 0) {
+            throw new DingTalkError({
+                kind: 'validation',
+                message: 'atAll and atMobiles are mutually exclusive',
+            });
+        }
+        wire.at_all = true;
+    }
+    return wire;
+}

package/dist/errors.d.ts

@@ -0,0 +1,60 @@
+import type { NotifyResult } from './types.js';
+/**
+ * How a {@link DingTalkError} arose. Branch on this in a `catch`:
+ *
+ * - `validation` — input rejected client-side; **no request was sent**.
+ * - `network`    — fetch threw, or the request timed out.
+ * - `http`       — server replied with a non-2xx status.
+ * - `rejected`   — HTTP 200 but DingTalk rejected it (`ok:false`, `errcode !== 0`).
+ *
+ * The `rejected` case is the easy-to-miss one: the transport succeeded, so a
+ * bare fetch wrapper would treat it as success. The SDK surfaces it as an error.
+ */
+export type DingTalkErrorKind = 'validation' | 'network' | 'http' | 'rejected';
+export interface DingTalkErrorInit {
+    kind: DingTalkErrorKind;
+    message: string;
+    /** HTTP status, when one was received. */
+    status?: number;
+    /** Server error code string, e.g. `invalid_token` / `validation_failed`. */
+    serverError?: string;
+    /** Server-provided validation details (zod issues or a message string). */
+    details?: unknown;
+    /** DingTalk `errcode` (for `rejected`). */
+    errcode?: number | null;
+    /** DingTalk `errmsg` (for `rejected`). */
+    errmsg?: string | null;
+    /** DingTalk's raw response body (for `rejected`), useful for debugging. */
+    rawBody?: string;
+    /** Server audit-log id, when known. */
+    logId?: string;
+    /** Trace id, when known. */
+    requestId?: string;
+    /** Which `combo` leg failed, when thrown from {@link DingTalk.combo}. */
+    comboLeg?: 'text' | 'markdown';
+    /** A `combo` leg that already succeeded before the failure. */
+    comboPartial?: {
+        text?: NotifyResult;
+    };
+    /** Underlying cause (e.g. the original fetch error). */
+    cause?: unknown;
+}
+/** The single error type thrown by every {@link DingTalk} method on failure. */
+export declare class DingTalkError extends Error {
+    readonly kind: DingTalkErrorKind;
+    readonly status?: number;
+    readonly serverError?: string;
+    readonly details?: unknown;
+    readonly errcode?: number | null;
+    readonly errmsg?: string | null;
+    readonly rawBody?: string;
+    readonly logId?: string;
+    readonly requestId?: string;
+    readonly comboLeg?: 'text' | 'markdown';
+    readonly comboPartial?: {
+        text?: NotifyResult;
+    };
+    constructor(init: DingTalkErrorInit);
+    /** True for transient failures worth retrying (network/timeout, HTTP 5xx). */
+    get retryable(): boolean;
+}

package/dist/errors.js

@@ -0,0 +1,37 @@
+/** The single error type thrown by every {@link DingTalk} method on failure. */
+export class DingTalkError extends Error {
+    kind;
+    status;
+    serverError;
+    details;
+    errcode;
+    errmsg;
+    rawBody;
+    logId;
+    requestId;
+    comboLeg;
+    comboPartial;
+    constructor(init) {
+        super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = 'DingTalkError';
+        this.kind = init.kind;
+        this.status = init.status;
+        this.serverError = init.serverError;
+        this.details = init.details;
+        this.errcode = init.errcode;
+        this.errmsg = init.errmsg;
+        this.rawBody = init.rawBody;
+        this.logId = init.logId;
+        this.requestId = init.requestId;
+        this.comboLeg = init.comboLeg;
+        this.comboPartial = init.comboPartial;
+    }
+    /** True for transient failures worth retrying (network/timeout, HTTP 5xx). */
+    get retryable() {
+        if (this.kind === 'network')
+            return true;
+        if (this.kind === 'http' && this.status !== undefined)
+            return this.status >= 500;
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { DingTalk } from './client.js';
+export { DingTalkError } from './errors.js';
+export type { DingTalkErrorKind, DingTalkErrorInit } from './errors.js';
+export type { AtMobiles, AtOptions, TextBody, MarkdownBody, NotifyBody, DingTalkVerdict, NotifyResult, DingTalkOptions, ComboInput, ComboResult, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { DingTalk } from './client.js';
+export { DingTalkError } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Wire types — a faithful replica of the server contract in
+ * `dingtalk_notification_server/src/routes/notify.ts`. Keep these in sync
+ * with that file when the server's request/response shape changes.
+ */
+/** Mobile numbers to @-mention. Server rule: `/^\+?\d{6,20}$/`, max 50. */
+export type AtMobiles = string[];
+/** Common `@` options shared by both message types. */
+export interface AtOptions {
+    /** Real blue-badge @ + device push (only effective for `text` messages). */
+    atMobiles?: AtMobiles;
+    /** @-everyone. Mutually exclusive with a non-empty `atMobiles`. */
+    atAll?: boolean;
+}
+/** A `text` message: no rich formatting, but `atMobiles` triggers a real push. */
+export interface TextBody {
+    type: 'text';
+    /** 1–20000 chars. */
+    content: string;
+    atMobiles?: AtMobiles;
+    atAll?: boolean;
+}
+/** A `markdown` message: rich formatting, but `@` renders without a push. */
+export interface MarkdownBody {
+    type: 'markdown';
+    /** 1–200 chars. Shown as the card title / notification preview. */
+    title: string;
+    /** 1–20000 chars of DingTalk-flavored markdown. */
+    content: string;
+    atMobiles?: AtMobiles;
+    atAll?: boolean;
+}
+/** Discriminated union accepted by {@link DingTalk.notify}. */
+export type NotifyBody = TextBody | MarkdownBody;
+/** DingTalk's verbatim verdict, normalized to camelCase. */
+export interface DingTalkVerdict {
+    httpStatus: number | null;
+    errcode: number | null;
+    errmsg: string | null;
+}
+/** Successful result of a notify call (`errcode === 0`). */
+export interface NotifyResult {
+    /** Server audit-log id (`lg_...`). */
+    logId: string;
+    /** End-to-end trace id (`rq_...`); also surfaced in server logs. */
+    requestId: string;
+    dingtalk: DingTalkVerdict;
+}
+/** Options for {@link DingTalk}. */
+export interface DingTalkOptions {
+    /** Per-robot bearer token (`dnk_...`). Required. */
+    token: string;
+    /** Server origin. Defaults to `https://dingtalk-notify.210k.cc`. */
+    baseUrl?: string;
+    /** Per-request timeout in ms (via AbortController). Defaults to 10000. */
+    timeoutMs?: number;
+    /**
+     * Retry attempts for transient failures (network error, timeout, HTTP 5xx).
+     * Defaults to 0. DingTalk business rejections and HTTP 4xx are never retried.
+     */
+    retries?: number;
+    /** Custom fetch (for tests or non-standard runtimes). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /** Overrides the default `User-Agent` header. */
+    userAgent?: string;
+}
+/** Argument for {@link DingTalk.combo}. */
+export interface ComboInput {
+    /** Short `text` line carrying the actual @-push. */
+    alert: string;
+    /** Markdown card title. */
+    title: string;
+    /** Markdown card body. */
+    detail: string;
+    atMobiles?: AtMobiles;
+    atAll?: boolean;
+}
+/** Result of {@link DingTalk.combo}: both legs that were sent. */
+export interface ComboResult {
+    text: NotifyResult;
+    markdown: NotifyResult;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Wire types — a faithful replica of the server contract in
+ * `dingtalk_notification_server/src/routes/notify.ts`. Keep these in sync
+ * with that file when the server's request/response shape changes.
+ */
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@frankie0736/dingtalk-notify",
+  "version": "0.1.0",
+  "description": "Thin client for the DingTalk Notification Server — send DingTalk group notifications over a single authenticated endpoint.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Frankie",
+  "homepage": "https://github.com/frankie0736/dingtalk-notify-client#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frankie0736/dingtalk-notify-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/frankie0736/dingtalk-notify-client/issues"
+  },
+  "keywords": [
+    "dingtalk",
+    "钉钉",
+    "webhook",
+    "notification",
+    "robot",
+    "cloudflare-workers"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "test": "tsc -p tsconfig.build.json && node --test --experimental-strip-types",
+    "prepublishOnly": "tsc --noEmit && tsc -p tsconfig.build.json && node --test --experimental-strip-types"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "typescript": "^5.9.2"
+  }
+}