@hizexai/herald-sdk

Client for the HiZex Herald API — the LINE-first notification and conversation platform for organisations with many units and one official account. Zero dependencies; Node 22+ (global fetch), Bun and Deno.

給校務系統、CRM、校友系統、學習系統與 BI 用的 Herald 客戶端：代發通知、主題、綁定與同意、CRM 同步（階段、歸因、標籤）、簽章事件、戰情室數字。

• Guide / 界接指南: docs/integration.md · online: https://hizexai.com/manual/sdk.html
• API reference: openapi.json · Swagger UI at your API host /docs
• Issues: https://github.com/hizexai/herald-sdk/issues · Contact: [email protected]

npm install @hizexai/herald-sdk

import { HeraldClient, HeraldError } from '@hizexai/herald-sdk';

const herald = new HeraldClient({ baseUrl: 'https://api.example.edu', producerKey: process.env.HERALD_PRODUCER_KEY! });

// Send a notice on behalf of a system (create → submit → auto-approval check)
const sent = await herald.messages.send(
  {
    categoryId: 'course_change',
    templateId: 'tpl-course-change-1',
    variables: { course: '資料結構', change: '教室改為 E302', when: '2026-11-02 09:10' },
    audience: { kind: 'individual', uids: ['s1120001'] },
    remindAt: '2026-11-01T09:00:00+08:00', // optional reminder; recipients can answer 不用提醒
  },
  'cls-chg-20261101-0042', // Idempotency-Key: a retry never sends twice
);

// Tell Herald what happened; the event binding decides what to send
await herald.sendEvent('academic', { keyId: 'academic-2026', secret: process.env.ACADEMIC_EVENT_SECRET! }, {
  eventId: 'cls-chg-20261101-0042',
  type: 'course.changed',
  subjectUids: ['s1120001'],
  data: { course: '演算法', change: '停課一次', when: '2026-11-03' },
});

// CRM / alumni sync (administrative-unit credential)
await herald.subjects.update('s1120001', { stage: 'alumni', tags: { add: ['cohort:2026', 'interest:ai'] } });

// Executive metrics for BI (counts only)
const metrics = await herald.metrics.executive({ days: 30 });

try {
  await herald.messages.create({ categoryId: 'x', audience: { kind: 'all' } }, 'k');
} catch (e) {
  if (e instanceof HeraldError) console.error(e.status, e.code, e.details);
}

What is in the client

| Namespace | Methods | Credential | | --- | --- | --- | | messages | create, dryRun, submit, approve, reject, cancel, get, list, send | producer key or console session | | topics | list, create, get, update | producer key or console session | | subjects | bind, unbind, grantConsent, revokeConsent, get, update | administrative-unit producer key | | metrics | executive, trend | producer key (own unit) or approver session | | sendEvent(source, key, event) | HMAC-signed 校務 event | signing key (EVENT_SIGNING_KEYS) | | health() | readiness | none | | request(method, path, opts) | any other endpoint | as above |

Every error is a HeraldError with status, code and details copied from the server's { error } body; codes are listed in the guide.

Other languages

Everything is plain HTTPS + JSON. Generate a client from openapi.json, or call the endpoints directly; the guide has Python and curl examples, including the three-line HMAC signature for events.

License

MIT