@frankie0736/dingtalk-notify 0.1.0 → 0.2.0

package/README.md

@@ -1,14 +1,17 @@
 # @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.
+[![npm version](https://img.shields.io/npm/v/@frankie0736/dingtalk-notify.svg)](https://www.npmjs.com/package/@frankie0736/dingtalk-notify)
+[![CI](https://github.com/frankie0736/dingtalk-notify-client/actions/workflows/ci.yml/badge.svg)](https://github.com/frankie0736/dingtalk-notify-client/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/npm/l/@frankie0736/dingtalk-notify.svg)](./LICENSE)
 
-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.
+Zero-dependency DingTalk custom robot client. It signs the robot webhook locally with HMAC-SHA256, builds DingTalk's `text` / `markdown` payloads, injects `@` mentions, and posts directly to DingTalk.
 
-- **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.
+- Pure ESM.
+- Runs on Node.js 18+, Bun, and Cloudflare Workers / Edge.
+- No runtime dependency on any notification server.
+- Throws one `DingTalkError` type for validation, network, HTTP, and DingTalk business rejection failures.
 
-> Not for browsers: the bearer token must never ship to a frontend.
+Do not use this package in browsers. The DingTalk webhook and secret are credentials.
 
 ## Install
 
@@ -18,60 +21,113 @@ npm install @frankie0736/dingtalk-notify
 bun add @frankie0736/dingtalk-notify
 ```
 
-## Quick start
+## Quick Start
 
 ```ts
 import { DingTalk } from '@frankie0736/dingtalk-notify';
 
-const dt = new DingTalk({ token: process.env.DINGTALK_TOKEN! }); // 'dnk_...'
+const dt = new DingTalk({
+  webhook: process.env.DINGTALK_WEBHOOK!,
+  secret: process.env.DINGTALK_SECRET, // optional for keyword/IP-whitelist robots
+});
 
-// Plain text — atMobiles here fires a real @-push + device notification.
-await dt.text('🔔 Build #123 failed', { atMobiles: ['13800138000'] });
+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)');
+await dt.markdown(
+  'Build #123',
+  '### main failed\n- env: prod\n- [logs](https://example.com)',
+);
 ```
 
-## `@`-mention behavior (a DingTalk platform quirk)
+## Mention Behavior
 
 | 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 |
+| `text` | No | Yes. Real blue-badge `@` and device notification. |
+| `markdown` | Yes | No. DingTalk can render the name in the card, but it does not push. |
 
-This asymmetry is a DingTalk limitation, not a choice of this library.
+This is a DingTalk platform behavior. The package preserves it instead of hiding it.
 
-### `combo()` — push + rich content in one call
+### `combo()`
 
-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:
+When you need both a real push and rich detail, send a short `text` first and a `markdown` card second:
 
 ```ts
 await dt.combo({
-  alert: '🔔 Build #123 failed — see detail',  // short text, carries the @
+  alert: 'Build #123 failed. See detail.',
   title: 'Build #123',
-  detail: '### main 失败\n- env: prod\n- [logs](https://example.com)',
+  detail: '### main failed\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`.
+If the markdown leg fails after the text leg succeeds, the thrown `DingTalkError` has `comboLeg: 'markdown'` and `comboPartial.text`.
+
+## API
+
+```ts
+new DingTalk({
+  webhook: 'https://oapi.dingtalk.com/robot/send?access_token=...',
+  secret: 'SEC...',       // optional
+  timeoutMs: 10_000,      // default
+  retries: 0,             // default; retries network failures and HTTP 5xx only
+  fetch: customFetch,     // optional
+  now: () => Date.now(),  // optional deterministic signing hook
+});
+```
+
+Methods:
+
+```ts
+await dt.text(content, { atMobiles, atAll });
+await dt.markdown(title, content, { atMobiles, atAll });
+await dt.notify({ type: 'text', content, atMobiles, atAll });
+await dt.notify({ type: 'markdown', title, content, atMobiles, atAll });
+await dt.combo({ alert, title, detail, atMobiles, atAll });
+```
+
+Validation runs before any request:
 
-## Error handling
+- `content`: 1-20000 chars.
+- markdown `title`: 1-200 chars.
+- `atMobiles`: max 50, each matching `/^\+?\d{6,20}$/`.
+- `atAll` and non-empty `atMobiles` are mutually exclusive.
 
-Every method throws [`DingTalkError`](./src/errors.ts) on failure. Branch on `kind`:
+## Result
+
+`text` / `markdown` / `notify` resolve to DingTalk's direct verdict:
 
 ```ts
-import { DingTalk, DingTalkError } from '@frankie0736/dingtalk-notify';
+{
+  httpStatus: 200,
+  errcode: 0,
+  errmsg: 'ok',
+  rawBody: '{"errcode":0,"errmsg":"ok"}',
+}
+```
+
+`combo()` resolves to `{ text: NotifyResult, markdown: NotifyResult }`.
+
+## Error Handling
+
+Every method throws `DingTalkError` on failure:
+
+```ts
+import { 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
+      case 'validation':
+        break; // bad local input; no request sent
+      case 'network':
+        break; // fetch failed or timed out
+      case 'http':
+        break; // non-2xx; err.status and err.rawBody are available
+      case 'rejected':
+        break; // HTTP 2xx, but DingTalk returned errcode !== 0
     }
   }
 }
@@ -79,51 +135,28 @@ try {
 
 | `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
+| `validation` | Local input rejected before sending | `message` |
+| `network` | `fetch` threw or timed out | `cause` |
+| `http` | DingTalk replied non-2xx | `status`, `errcode`, `errmsg`, `rawBody` |
+| `rejected` | DingTalk replied 2xx with `errcode !== 0` | `errcode`, `errmsg`, `rawBody` |
 
-```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
-});
-```
+`err.retryable` is true for `network` and HTTP 5xx failures only. DingTalk business rejections are not retried.
 
-## Result shape
+## DingTalk Limits
 
-`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.
+DingTalk custom robots are limited to 20 messages per minute per robot. This package does not add client-side throttling; keep rate control at your job queue, worker, or application boundary.
 
 ## Development
 
 ```bash
 bun install
-bun run check   # typecheck
-bun run test    # build + node:test
-bun run build   # emit dist/
+bun run check
+bun run test
+bun run build
 ```
 
+Tests import `../dist/index.js`, so use `bun run test` after changing `src/`; it builds first.
+
 ## License
 
-MIT © Frankie
+MIT (c) Frankie

package/dist/client.d.ts

@@ -1,43 +1,19 @@
-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`).
- */
+import type { AtOptions, ComboInput, ComboResult, DingTalkOptions, NotifyBody, NotifyResult } from './types.js';
 export declare class DingTalk {
     #private;
     constructor(options: DingTalkOptions);
-    /** Thin core: send a fully-formed message body. */
+    /** Send a fully-formed `text` or `markdown` message. */
     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>;
+    text(content: string, opts?: AtOptions): 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.
+     * Send a `markdown` card. Per DingTalk, `@` mentions render in the card but
+     * do not fire a device push; use {@link combo} when you need both.
      */
-    markdown(title: string, content: string, opts?: {
-        atMobiles?: string[];
-        atAll?: boolean;
-    }): Promise<NotifyResult>;
+    markdown(title: string, content: string, opts?: AtOptions): 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`.
+     * Send a short `text` push first, then a rich `markdown` card. If the second
+     * leg fails, the thrown error carries `comboPartial.text`.
      */
     combo(input: ComboInput): Promise<ComboResult>;
 }

package/dist/client.js

@@ -1,41 +1,24 @@
 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 enc = new TextEncoder();
 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;
+    #webhook;
+    #secret;
     #timeoutMs;
     #retries;
     #fetch;
-    #userAgent;
+    #now;
     constructor(options) {
-        if (!options || typeof options.token !== 'string' || options.token.length === 0) {
-            throw new DingTalkError({ kind: 'validation', message: 'token is required' });
+        if (!options || typeof options.webhook !== 'string' || options.webhook.length === 0) {
+            throw new DingTalkError({ kind: 'validation', message: 'webhook is required' });
+        }
+        if (options.secret !== undefined && (typeof options.secret !== 'string' || options.secret.length === 0)) {
+            throw new DingTalkError({ kind: 'validation', message: 'secret must be a non-empty string when provided' });
         }
-        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({
@@ -43,12 +26,16 @@ export class DingTalk {
                 message: 'global fetch is unavailable; pass options.fetch',
             });
         }
-        // Preserve `this` binding for environments where fetch is a bound global.
+        this.#webhook = options.webhook;
+        this.#secret = options.secret;
+        this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.#retries = Math.max(0, options.retries ?? 0);
         this.#fetch = f.bind(globalThis);
+        this.#now = options.now ?? Date.now;
     }
-    /** Thin core: send a fully-formed message body. */
+    /** Send a fully-formed `text` or `markdown` message. */
     async notify(body) {
-        const wire = buildWire(body);
+        const wire = buildDingTalkBody(validateBody(body));
         return this.#sendWithRetry(wire);
     }
     /** Send a plain `text` message. `atMobiles` here triggers a real @-push. */
@@ -61,9 +48,8 @@ export class DingTalk {
         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.
+     * Send a `markdown` card. Per DingTalk, `@` mentions render in the card but
+     * do not fire a device push; use {@link combo} when you need both.
      */
     async markdown(title, content, opts = {}) {
         const body = { type: 'markdown', title, content };
@@ -74,13 +60,8 @@ export class DingTalk {
         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`.
+     * Send a short `text` push first, then a rich `markdown` card. If the second
+     * leg fails, the thrown error carries `comboPartial.text`.
      */
     async combo(input) {
         const at = {};
@@ -103,11 +84,11 @@ export class DingTalk {
             throw tagComboLeg(err, 'markdown', { text: textResult });
         }
     }
-    async #sendWithRetry(wire) {
+    async #sendWithRetry(body) {
         let attempt = 0;
         for (;;) {
             try {
-                return await this.#sendOnce(wire);
+                return await this.#sendOnce(body);
             }
             catch (err) {
                 const isRetryable = err instanceof DingTalkError && err.retryable;
@@ -118,7 +99,7 @@ export class DingTalk {
             }
         }
     }
-    async #sendOnce(wire) {
+    async #sendOnce(body) {
         const controller = new AbortController();
         let timedOut = false;
         const timer = setTimeout(() => {
@@ -127,15 +108,10 @@ export class DingTalk {
         }, this.#timeoutMs);
         let res;
         try {
-            res = await this.#fetch(this.#url, {
+            res = await this.#fetch(await this.#requestUrl(), {
                 method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    Accept: 'application/json',
-                    Authorization: `Bearer ${this.#token}`,
-                    'User-Agent': this.#userAgent,
-                },
-                body: JSON.stringify(wire),
+                headers: { 'Content-Type': 'application/json; charset=utf-8' },
+                body: JSON.stringify(body),
                 signal: controller.signal,
             });
         }
@@ -149,82 +125,58 @@ export class DingTalk {
         finally {
             clearTimeout(timer);
         }
-        const rawText = await res.text().catch(() => '');
-        let parsed;
-        if (rawText.length > 0) {
-            try {
-                parsed = JSON.parse(rawText);
-            }
-            catch {
-                parsed = undefined;
-            }
-        }
+        const rawBody = await res.text().catch(() => '');
+        const parsed = parseDingTalkResponse(rawBody);
         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`,
+                message: `DingTalk returned HTTP ${res.status}`,
+                errcode: parsed.errcode,
+                errmsg: parsed.errmsg,
+                rawBody,
             });
         }
-        const dt = parsed.dingtalk ?? {};
-        if (parsed.ok === true) {
+        if (parsed.errcode === 0) {
             return {
-                logId: parsed.log_id ?? '',
-                requestId: parsed.request_id ?? '',
-                dingtalk: {
-                    httpStatus: dt.http_status ?? null,
-                    errcode: dt.errcode ?? null,
-                    errmsg: dt.errmsg ?? null,
-                },
+                httpStatus: res.status,
+                errcode: parsed.errcode,
+                errmsg: parsed.errmsg,
+                rawBody,
             };
         }
-        // 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 } : {}),
+            message: `DingTalk rejected the message: ${parsed.errmsg ?? 'unknown'} (errcode ${parsed.errcode ?? 'unknown'})`,
+            errcode: parsed.errcode,
+            errmsg: parsed.errmsg,
+            rawBody,
         });
     }
+    async #requestUrl() {
+        if (this.#secret === undefined)
+            return this.#webhook;
+        return buildSignedUrl(this.#webhook, this.#secret, this.#now().toString());
+    }
 }
-/**
- * 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,
-    });
+function b64encode(bytes) {
+    let s = '';
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s);
+}
+async function sign(secret, timestamp) {
+    const stringToSign = `${timestamp}\n${secret}`;
+    const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sig = new Uint8Array(await crypto.subtle.sign('HMAC', key, enc.encode(stringToSign)));
+    return encodeURIComponent(b64encode(sig));
 }
-/** Validate input at the boundary and convert to the snake_case wire shape. */
-function buildWire(body) {
+async function buildSignedUrl(webhook, secret, timestamp) {
+    const s = await sign(secret, timestamp);
+    const sep = webhook.includes('?') ? '&' : '?';
+    return `${webhook}${sep}timestamp=${timestamp}&sign=${s}`;
+}
+function validateBody(body) {
     if (!body || (body.type !== 'text' && body.type !== 'markdown')) {
         throw new DingTalkError({
             kind: 'validation',
@@ -234,28 +186,27 @@ function buildWire(body) {
     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',
+            message: 'content must be a string of 1-20000 chars',
         });
     }
-    const wire = { type: body.type, content: body.content };
+    const normalized = { 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',
+                message: 'markdown title must be a string of 1-200 chars',
             });
         }
-        wire.title = body.title;
+        normalized.title = body.title;
     }
-    const atMobiles = body.atMobiles;
-    if (atMobiles !== undefined) {
-        if (!Array.isArray(atMobiles) || atMobiles.length > 50) {
+    if (body.atMobiles !== undefined) {
+        if (!Array.isArray(body.atMobiles) || body.atMobiles.length > 50) {
             throw new DingTalkError({
                 kind: 'validation',
                 message: 'atMobiles must be an array of at most 50 numbers',
             });
         }
-        for (const m of atMobiles) {
+        for (const m of body.atMobiles) {
             if (typeof m !== 'string' || !MOBILE_RE.test(m)) {
                 throw new DingTalkError({
                     kind: 'validation',
@@ -263,17 +214,68 @@ function buildWire(body) {
                 });
             }
         }
-        if (atMobiles.length > 0)
-            wire.at_mobiles = atMobiles;
+        if (body.atMobiles.length > 0)
+            normalized.atMobiles = body.atMobiles;
     }
     if (body.atAll === true) {
-        if (wire.at_mobiles && wire.at_mobiles.length > 0) {
+        if (normalized.atMobiles && normalized.atMobiles.length > 0) {
             throw new DingTalkError({
                 kind: 'validation',
                 message: 'atAll and atMobiles are mutually exclusive',
             });
         }
-        wire.at_all = true;
+        normalized.atAll = true;
+    }
+    return normalized;
+}
+function buildDingTalkBody(input) {
+    const at = {
+        atMobiles: input.atMobiles ?? [],
+        isAtAll: input.atAll === true,
+    };
+    if (input.type === 'text') {
+        return {
+            msgtype: 'text',
+            text: { content: input.content },
+            at,
+        };
     }
-    return wire;
+    const trailingMentions = input.atMobiles && input.atMobiles.length > 0
+        ? '\n\n' + input.atMobiles.map((m) => `@${m} `).join('')
+        : '';
+    return {
+        msgtype: 'markdown',
+        markdown: {
+            title: input.title ?? 'Notification',
+            text: input.content + trailingMentions,
+        },
+        at,
+    };
+}
+function parseDingTalkResponse(rawBody) {
+    try {
+        const parsed = JSON.parse(rawBody);
+        return {
+            errcode: typeof parsed.errcode === 'number' ? parsed.errcode : null,
+            errmsg: typeof parsed.errmsg === 'string' ? parsed.errmsg : null,
+        };
+    }
+    catch {
+        return { errcode: null, errmsg: null };
+    }
+}
+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.errcode !== undefined ? { errcode: err.errcode } : {}),
+        ...(err.errmsg !== undefined ? { errmsg: err.errmsg } : {}),
+        ...(err.rawBody !== undefined ? { rawBody: err.rawBody } : {}),
+        comboLeg: leg,
+        ...(partial !== undefined ? { comboPartial: partial } : {}),
+        cause: err,
+    });
 }

package/dist/errors.d.ts

@@ -2,13 +2,10 @@ 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.
+ * - `validation` - input rejected client-side; no request was sent.
+ * - `network` - fetch threw, or the request timed out.
+ * - `http` - DingTalk replied with a non-2xx status.
+ * - `rejected` - HTTP 2xx but DingTalk returned `errcode !== 0`.
  */
 export type DingTalkErrorKind = 'validation' | 'network' | 'http' | 'rejected';
 export interface DingTalkErrorInit {
@@ -16,20 +13,12 @@ export interface DingTalkErrorInit {
     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`). */
+    /** DingTalk `errcode`, when DingTalk returned one. */
     errcode?: number | null;
-    /** DingTalk `errmsg` (for `rejected`). */
+    /** DingTalk `errmsg`, when DingTalk returned one. */
     errmsg?: string | null;
-    /** DingTalk's raw response body (for `rejected`), useful for debugging. */
+    /** DingTalk's raw response body, 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. */
@@ -43,13 +32,9 @@ export interface DingTalkErrorInit {
 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;

package/dist/errors.js

@@ -2,13 +2,9 @@
 export class DingTalkError extends Error {
     kind;
     status;
-    serverError;
-    details;
     errcode;
     errmsg;
     rawBody;
-    logId;
-    requestId;
     comboLeg;
     comboPartial;
     constructor(init) {
@@ -16,13 +12,9 @@ export class DingTalkError extends Error {
         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;
     }

package/dist/index.d.ts

@@ -1,4 +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';
+export type { AtMobiles, AtOptions, TextBody, MarkdownBody, NotifyBody, NotifyResult, DingTalkOptions, ComboInput, ComboResult, } from './types.js';

package/dist/types.d.ts

@@ -1,57 +1,41 @@
-/**
- * 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. */
+/** Mobile numbers to @-mention. 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). */
+    /** Real blue-badge @ + device push only 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 {
+/** A DingTalk `text` message: no rich formatting, but `atMobiles` triggers a real push. */
+export interface TextBody extends AtOptions {
     type: 'text';
-    /** 1–20000 chars. */
+    /** 1-20000 chars. */
     content: string;
-    atMobiles?: AtMobiles;
-    atAll?: boolean;
 }
-/** A `markdown` message: rich formatting, but `@` renders without a push. */
-export interface MarkdownBody {
+/** A DingTalk `markdown` message: rich formatting; `@` renders without a push. */
+export interface MarkdownBody extends AtOptions {
     type: 'markdown';
-    /** 1–200 chars. Shown as the card title / notification preview. */
+    /** 1-200 chars. Shown as the card title / notification preview. */
     title: string;
-    /** 1–20000 chars of DingTalk-flavored markdown. */
+    /** 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;
+/** DingTalk's direct response, normalized to camelCase and preserving raw text. */
+export interface NotifyResult {
+    httpStatus: number;
     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;
+    rawBody: string;
 }
 /** 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;
+    /** DingTalk custom robot webhook URL, including `access_token`. */
+    webhook: string;
+    /** DingTalk custom robot signing secret. Omit for keyword/IP-whitelist robots. */
+    secret?: string;
     /** Per-request timeout in ms (via AbortController). Defaults to 10000. */
     timeoutMs?: number;
     /**
@@ -61,19 +45,17 @@ export interface DingTalkOptions {
     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;
+    /** Timestamp provider for deterministic signing tests. Defaults to `Date.now`. */
+    now?: () => number;
 }
 /** Argument for {@link DingTalk.combo}. */
-export interface ComboInput {
+export interface ComboInput extends AtOptions {
     /** 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 {

package/dist/types.js

@@ -1,6 +1 @@
-/**
- * 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

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.2.0",
+  "description": "Zero-dependency DingTalk custom robot client with local HMAC signing.",
   "type": "module",
   "license": "MIT",
   "author": "Frankie",