honk-me 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `honk-me` (npm) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] - 2026-10-07
+
+### Added
+- `actions`: up to 3 buttons on a message, `{ title, url }` with an `https://`, `mailto:`,
+  `tel:` or `sms:` URL (the `Action` type). Validated locally like the server does, with
+  errors named `actions[1].url`; empty `actions` are omitted, so messages without buttons are
+  sent exactly as before.
+
+## [0.1.1] - 2026-10-06
+
+### Fixed
+- Near the deadline, a retry no longer starts with only a few milliseconds left. Such an
+  attempt could only time out, and its `HonkTimeoutError` hid the server's real answer (for
+  example `503`). A retry now needs at least 250 ms (or `timeoutMs`, when shorter) before
+  `deadlineMs`; otherwise the last error is thrown at once.
+
+### Changed
+- Package author: Honk <accounts@honk-me.app>. The README links the Rust SDK, the n8n node
+  and the WordPress plugin.
+
 ## [0.1.0] - 2026-10-04
 
 ### Added

package/README.md

@@ -114,12 +114,13 @@ honk.send(message, { idempotencyKey?, signal? }) // → Promise<{ id, duplicate,
 | `occurredAt` | `Date` or RFC 3339 string | informational |
 | `url` | string | `https://` only, no credentials |
 | `imageUrl` | string | `https://` only, no credentials or `#fragment`; fetched by the server afterwards |
+| `actions` | `{ title, url }[]` | up to 3 buttons, the first is the primary; see below |
 | `metadata` | `Record<string, string \| number \| boolean>` | ≤ 16 keys `[A-Za-z0-9_.-]{1,64}`, strings ≤ 512 chars |
 | `ttlSeconds` | integer | push lifetime 60–86400, default 3600 |
 | `sourceSequence` | integer | 0 … 2^53-1, needs `groupKey`; a delayed recovery never closes a newer problem |
 
-Fields are camelCase in this SDK and sent with the API's snake_case names. `null`, `undefined`
-and empty optional strings are omitted. A resolved promise means Honk **durably stored** the
+Fields are camelCase in this SDK and sent with the API's snake_case names. `null`, `undefined`,
+empty optional strings and an empty `actions` array are omitted. A resolved promise means Honk **durably stored** the
 message (`202`); it does not mean a push was delivered or read.
 
 Helpers (the last argument takes any message field plus `idempotencyKey` and `signal`):
@@ -132,6 +133,33 @@ await honk.problem('db/backup', 'Backup failed', 'pg_dump exited with 1');
 await honk.recovery('db/backup', 'Backup OK', 'pg_dump finished in 41 s');      // a beep by default
 ```
 
+### Buttons (actions)
+
+Up to three buttons on the message, in display order: reply to the customer, call them, open
+the order.
+
+```js
+await honk.send({
+  title: 'New request: online shop quote',
+  message: 'Emily Carter (Acme) asked for a quote: online shop, 40 products',
+  category: 'customers',
+  groupKey: 'requests/4812',
+  actions: [
+    { title: 'Reply', url: 'mailto:emily@example.com?subject=Your%20quote' },
+    { title: 'Call Emily', url: 'tel:+15550134' },
+  ],
+});
+```
+
+- `title`: 1–40 characters, one line, shown as sent.
+- `url`, at most 2048 bytes without spaces: `https://` (no credentials); `mailto:` with one
+  address and optionally `?subject=…&body=…` (percent-encoded with `encodeURIComponent`, no
+  other keys); `tel:` with a number (digits, `-` `.` `(` `)`, `+` only first); `sms:` with a
+  number and optionally `?body=…`. Other schemes are refused.
+- Honk never opens or fetches them; the app does when you tap one. They appear on the
+  message in the app and the web inbox, and on iPhone notifications that show the message
+  text. Errors name the button: `actions[1].url`.
+
 ### Options
 
 ```js
@@ -155,8 +183,9 @@ new Honk({
   `duplicate: true`, so a lost response never creates a second message.
 - Only network errors, timeouts, `429` and `5xx` are retried, with exponential backoff and
   full jitter (`random(0, min(8 s, 0.5 s·2ⁿ))`), never sooner than the server's `Retry-After`.
-- Everything stops at `deadlineMs`: if the next wait would cross it (for example a daily quota
-  that resets at midnight), the error is thrown at once with `retryAfter`.
+- Everything stops at `deadlineMs`: if the next wait, plus time for one more attempt, would
+  cross it (for example a daily quota that resets at midnight), the error is thrown at once
+  with `retryAfter`.
 - `4xx` other than `429` are never retried: fix the request instead.
 - Short per-attempt timeouts; Node's `fetch` keeps connections alive, so create one `Honk`
   per process and reuse it.
@@ -216,9 +245,11 @@ workflow publishes to npm with provenance (see `CHANGELOG.md`).
 
 ## Links
 
-- [honk-me.app](https://honk-me.app): the Honk inbox (web, iPhone).
+- [honk-me.app](https://honk-me.app): the Honk inbox (web, iPhone, Apple Watch).
 - Other SDKs: [PHP / Laravel](https://github.com/honk-me/honk-php),
   [Go + CLI](https://github.com/honk-me/honk-go), [Swift](https://github.com/honk-me/honk-swift),
-  [Kotlin / Java](https://github.com/honk-me/honk-kotlin).
+  [Kotlin / Java](https://github.com/honk-me/honk-kotlin), [Rust](https://github.com/honk-me/honk-rust).
+- No code: [n8n node](https://github.com/honk-me/honk-n8n) (`n8n-nodes-honk`) and the
+  [WordPress plugin](https://github.com/honk-me/honk-wordpress).
 
 MIT License.

package/dist/cjs/client.js

@@ -12,6 +12,9 @@ const DEFAULT_RETRIES = 4;
 const DEFAULT_DEADLINE_MS = 30_000;
 const DEFAULT_BACKOFF_BASE_MS = 500;
 const DEFAULT_BACKOFF_MAX_MS = 8_000;
+// A retry starts only with at least this long left before the deadline (or timeoutMs, when
+// shorter): with less it could only time out, and its timeout would hide the real error.
+const MIN_ATTEMPT_MS = 250;
 /** Seconds from a Retry-After header (delta-seconds or HTTP date), or undefined. */
 function parseRetryAfter(value, now = Date.now()) {
     if (value === null)
@@ -120,7 +123,7 @@ class Honk {
                 throw failure;
             const jitter = Math.random() * Math.min(this.#backoffMax, this.#backoffBase * 2 ** (attempt - 1));
             const wait = Math.max(jitter, (failure.retryAfter ?? 0) * 1000);
-            if (Date.now() + wait >= deadline)
+            if (Date.now() + wait + Math.min(this.timeoutMs, MIN_ATTEMPT_MS) > deadline)
                 throw failure;
             await sleep(wait, signal);
         }

package/dist/cjs/index.d.ts

@@ -2,4 +2,4 @@ export { Honk, VERSION, parseRetryAfter } from './client.js';
 export { HonkError, HonkValidationError, HonkAuthError, HonkQuotaError, HonkConflictError, HonkNetworkError, HonkTimeoutError, HonkServerError, type ErrorKind, type FieldError, } from './errors.js';
 export { buildBody, LIMITS } from './validate.js';
 export { uuidv7 } from './uuid.js';
-export { Severity, SEVERITY_ALIASES, normalizeSeverity, SEVERITIES, PRIORITIES, EVENT_TYPES, CATEGORIES, type SeverityAlias, type SeverityInput, type Priority, type EventType, type Category, type MetadataValue, type Message, type Defaults, type HonkOptions, type SendOptions, type HelperOptions, type SendResult, } from './types.js';
+export { Severity, SEVERITY_ALIASES, normalizeSeverity, SEVERITIES, PRIORITIES, EVENT_TYPES, CATEGORIES, type SeverityAlias, type SeverityInput, type Priority, type EventType, type Category, type MetadataValue, type Action, type Message, type Defaults, type HonkOptions, type SendOptions, type HelperOptions, type SendResult, } from './types.js';

package/dist/cjs/types.d.ts

@@ -41,6 +41,20 @@ export declare const PRIORITIES: readonly Priority[];
 export declare const EVENT_TYPES: readonly EventType[];
 export declare const CATEGORIES: readonly Category[];
 export type MetadataValue = string | number | boolean;
+/**
+ * A button on the message. Honk never opens or fetches the URL; the app opens it when the user
+ * taps the button.
+ */
+export interface Action {
+    /** 1–40 characters (trimmed), one line, shown as sent: `Reply`, `Call Emily`. */
+    title: string;
+    /**
+     * ≤ 2048 bytes, no spaces: `https://` (no credentials), `mailto:` with one address
+     * (`?subject=…&body=…` percent-encoded, no other keys), `tel:` or `sms:` with a number
+     * (`sms:` also `?body=…`). Other schemes are refused.
+     */
+    url: string;
+}
 /**
  * One event for `POST /v1/messages`. Only `message` is required. Fields are camelCase here and
  * sent as the snake_case names of the API (`groupKey` → `group_key`). Empty optional strings
@@ -79,6 +93,8 @@ export interface Message {
     url?: string | null;
     /** HTTPS image fetched by the server after ingestion. No credentials or fragment. ≤ 2048 bytes. */
     imageUrl?: string | null;
+    /** Up to 3 buttons, in display order (the first is the primary). Empty means none. */
+    actions?: readonly Action[] | null;
     /** ≤ 16 keys matching `[A-Za-z0-9_.-]{1,64}`; values are strings (≤ 512 chars), numbers or booleans. */
     metadata?: Record<string, MetadataValue> | null;
     /** Push lifetime, 60–86400 seconds. Default 3600. */

package/dist/cjs/validate.d.ts

@@ -9,6 +9,8 @@ export declare const LIMITS: {
     readonly channel: 64;
     readonly groupKey: 128;
     readonly urlBytes: 2048;
+    readonly actions: 3;
+    readonly actionTitle: 40;
     readonly metadataKeys: 16;
     readonly metadataValue: 512;
     readonly ttlMin: 60;
@@ -24,5 +26,11 @@ export declare function checkIdempotencyKey(key: unknown): string;
  * listing every invalid field.
  */
 export declare function buildBody(input: Message, defaults?: Defaults, validate?: boolean): Record<string, unknown>;
+/**
+ * The server's check of a (trimmed) action URL, scheme in any case: `https://` with a host and
+ * no credentials (as `url`), `mailto:` with one address and an optional `?subject=…&body=…`,
+ * `tel:` / `tel://` with a number, `sms:` with a number and an optional `?body=…`.
+ */
+export declare function validActionUrl(s: string): boolean;
 /** Syntactic check matching the server: https, a host, no credentials, no spaces/backslashes, ≤ 2048 bytes. */
 export declare function validUrl(raw: unknown, image: boolean): boolean;

package/dist/cjs/validate.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.byteLength = exports.LIMITS = void 0;
 exports.checkIdempotencyKey = checkIdempotencyKey;
 exports.buildBody = buildBody;
+exports.validActionUrl = validActionUrl;
 exports.validUrl = validUrl;
 const errors_js_1 = require("./errors.js");
 const types_js_1 = require("./types.js");
@@ -16,6 +17,8 @@ exports.LIMITS = {
     channel: 64,
     groupKey: 128,
     urlBytes: 2048,
+    actions: 3,
+    actionTitle: 40,
     metadataKeys: 16,
     metadataValue: 512,
     ttlMin: 60,
@@ -37,6 +40,7 @@ const FIELDS = {
     occurredAt: 'occurred_at',
     url: 'url',
     imageUrl: 'image_url',
+    actions: 'actions',
     metadata: 'metadata',
     ttlSeconds: 'ttl_seconds',
     sourceSequence: 'source_sequence',
@@ -48,6 +52,15 @@ const CONTROL_EXCEPT_BREAKS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u0
 const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
 const METADATA_KEY = /^[A-Za-z0-9_.-]{1,64}$/;
 const IDEMPOTENCY_KEY = /^[\x21-\x7e]{1,128}$/;
+// Unicode White_Space outside the control characters (Go's unicode.IsSpace, as on the server).
+const SPACE = /[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]/;
+// The number of a tel: or sms: action: an optional leading +, digits and - . ( ) separators.
+const PHONE_NUMBER = /^\+?[0-9().-]*[0-9][0-9().-]*$/;
+// A single plain mailto: address, once percent-decoded: dot-atom@dot-atom with a dotted domain
+// (or an IPv4 literal).
+const ATOM = "[A-Za-z0-9!#$%&'*+/=?^_`{|}~\\-\\u{80}-\\u{10ffff}]+";
+const MAIL_ADDRESS = new RegExp(`^${ATOM}(\\.${ATOM})*@(${ATOM}(\\.${ATOM})+|\\[[0-9.]*\\.[0-9.]*\\])$`, 'u');
+const BAD_ESCAPE = /%(?![0-9A-Fa-f]{2})/;
 const encoder = new TextEncoder();
 const byteLength = (s) => encoder.encode(s).length;
 exports.byteLength = byteLength;
@@ -100,7 +113,7 @@ function buildBody(input, defaults = {}, validate = true) {
     const body = {};
     for (const name of Object.keys(FIELDS)) {
         const v = value(name);
-        if (v === undefined)
+        if (v === undefined || (name === 'actions' && Array.isArray(v) && v.length === 0))
             continue;
         const wire = FIELDS[name];
         if (name === 'occurredAt') {
@@ -177,6 +190,7 @@ function checkMessage(b, add) {
     if (b.image_url !== undefined && !validUrl(b.image_url, true)) {
         add('image_url', 'invalid_format', 'must be an https URL without credentials or fragment, at most 2048 bytes');
     }
+    checkActions(b.actions, add);
     const md = b.metadata;
     if (md !== undefined) {
         if (typeof md !== 'object' || md === null || Array.isArray(md)) {
@@ -210,6 +224,100 @@ function checkMessage(b, add) {
         add('ttl_seconds', 'out_of_range', `must be an integer between ${exports.LIMITS.ttlMin} and ${exports.LIMITS.ttlMax}`);
     }
 }
+function checkActions(v, add) {
+    if (v === undefined)
+        return;
+    const format = 'must be an array of at most 3 { title, url } objects';
+    if (!Array.isArray(v))
+        return add('actions', 'invalid_format', format);
+    if (v.length > exports.LIMITS.actions)
+        return add('actions', 'too_long', `at most ${exports.LIMITS.actions} actions`);
+    if (v.some((a) => a === null || typeof a !== 'object' || Array.isArray(a)))
+        return add('actions', 'invalid_format', format);
+    v.forEach((a, i) => {
+        const field = `actions[${i}]`;
+        const title = typeof a.title === 'string' ? a.title.trim() : a.title;
+        if (title === undefined || title === null || title === '')
+            add(`${field}.title`, 'required', 'title is required');
+        else if (typeof title !== 'string')
+            add(`${field}.title`, 'invalid_format', 'must be a string');
+        else if (codePoints(title) > exports.LIMITS.actionTitle)
+            add(`${field}.title`, 'too_long', `must be at most ${exports.LIMITS.actionTitle} characters`);
+        else if (CONTROL.test(title))
+            add(`${field}.title`, 'invalid_format', 'must be one line without control characters');
+        const url = typeof a.url === 'string' ? a.url.trim() : a.url;
+        if (url === undefined || url === null || url === '')
+            add(`${field}.url`, 'required', 'url is required');
+        else if (typeof url !== 'string')
+            add(`${field}.url`, 'invalid_format', 'must be a string');
+        else if ((0, exports.byteLength)(url) > exports.LIMITS.urlBytes)
+            add(`${field}.url`, 'too_long', `must be at most ${exports.LIMITS.urlBytes} bytes`);
+        else if (!validActionUrl(url))
+            add(`${field}.url`, 'invalid_format', 'must be an https://, mailto:, tel: or sms: URL without spaces');
+        for (const key of Object.keys(a).sort()) {
+            if (key !== 'title' && key !== 'url')
+                add(`${field}.${key}`, 'not_allowed', 'unknown field (an action has title and url)');
+        }
+    });
+}
+/**
+ * The server's check of a (trimmed) action URL, scheme in any case: `https://` with a host and
+ * no credentials (as `url`), `mailto:` with one address and an optional `?subject=…&body=…`,
+ * `tel:` / `tel://` with a number, `sms:` with a number and an optional `?body=…`.
+ */
+function validActionUrl(s) {
+    if (CONTROL.test(s) || SPACE.test(s))
+        return false;
+    const colon = s.indexOf(':');
+    if (colon < 0)
+        return false;
+    const rest = s.slice(colon + 1);
+    const [head, query] = splitOnce(rest, '?');
+    switch (s.slice(0, colon).toLowerCase()) {
+        case 'https':
+            return validUrl(s, false);
+        case 'mailto':
+            return mailAddress(head) && actionQuery(query, ['subject', 'body']);
+        case 'tel':
+            return PHONE_NUMBER.test(rest.startsWith('//') ? rest.slice(2) : rest);
+        case 'sms':
+            return PHONE_NUMBER.test(head) && actionQuery(query, ['body']);
+        default:
+            return false;
+    }
+}
+function splitOnce(s, sep) {
+    const i = s.indexOf(sep);
+    return i < 0 ? [s, ''] : [s.slice(0, i), s.slice(i + 1)];
+}
+function mailAddress(s) {
+    if (BAD_ESCAPE.test(s))
+        return false;
+    try {
+        return MAIL_ADDRESS.test(decodeURIComponent(s));
+    }
+    catch {
+        return false;
+    }
+}
+// Valid percent-encoding, no ";" separators and only the allowed keys ("" is no query).
+function actionQuery(q, allowed) {
+    for (const pair of q.split('&')) {
+        if (pair.includes(';') || BAD_ESCAPE.test(pair))
+            return false;
+        if (pair === '')
+            continue;
+        const [key] = splitOnce(pair, '=');
+        try {
+            if (!allowed.includes(decodeURIComponent(key.replace(/\+/g, ' '))))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
 function shortText(b, field, max, add) {
     const v = b[field];
     if (v === undefined)

package/dist/cjs/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";

package/dist/cjs/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Generated from package.json by scripts/build.mjs on every build. Do not edit: change
 // "version" in package.json instead.
-exports.VERSION = '0.1.0';
+exports.VERSION = '0.2.0';

package/dist/esm/client.js

@@ -8,6 +8,9 @@ const DEFAULT_RETRIES = 4;
 const DEFAULT_DEADLINE_MS = 30_000;
 const DEFAULT_BACKOFF_BASE_MS = 500;
 const DEFAULT_BACKOFF_MAX_MS = 8_000;
+// A retry starts only with at least this long left before the deadline (or timeoutMs, when
+// shorter): with less it could only time out, and its timeout would hide the real error.
+const MIN_ATTEMPT_MS = 250;
 /** Seconds from a Retry-After header (delta-seconds or HTTP date), or undefined. */
 export function parseRetryAfter(value, now = Date.now()) {
     if (value === null)
@@ -116,7 +119,7 @@ export class Honk {
                 throw failure;
             const jitter = Math.random() * Math.min(this.#backoffMax, this.#backoffBase * 2 ** (attempt - 1));
             const wait = Math.max(jitter, (failure.retryAfter ?? 0) * 1000);
-            if (Date.now() + wait >= deadline)
+            if (Date.now() + wait + Math.min(this.timeoutMs, MIN_ATTEMPT_MS) > deadline)
                 throw failure;
             await sleep(wait, signal);
         }

package/dist/esm/index.d.ts

@@ -2,4 +2,4 @@ export { Honk, VERSION, parseRetryAfter } from './client.js';
 export { HonkError, HonkValidationError, HonkAuthError, HonkQuotaError, HonkConflictError, HonkNetworkError, HonkTimeoutError, HonkServerError, type ErrorKind, type FieldError, } from './errors.js';
 export { buildBody, LIMITS } from './validate.js';
 export { uuidv7 } from './uuid.js';
-export { Severity, SEVERITY_ALIASES, normalizeSeverity, SEVERITIES, PRIORITIES, EVENT_TYPES, CATEGORIES, type SeverityAlias, type SeverityInput, type Priority, type EventType, type Category, type MetadataValue, type Message, type Defaults, type HonkOptions, type SendOptions, type HelperOptions, type SendResult, } from './types.js';
+export { Severity, SEVERITY_ALIASES, normalizeSeverity, SEVERITIES, PRIORITIES, EVENT_TYPES, CATEGORIES, type SeverityAlias, type SeverityInput, type Priority, type EventType, type Category, type MetadataValue, type Action, type Message, type Defaults, type HonkOptions, type SendOptions, type HelperOptions, type SendResult, } from './types.js';

package/dist/esm/types.d.ts

@@ -41,6 +41,20 @@ export declare const PRIORITIES: readonly Priority[];
 export declare const EVENT_TYPES: readonly EventType[];
 export declare const CATEGORIES: readonly Category[];
 export type MetadataValue = string | number | boolean;
+/**
+ * A button on the message. Honk never opens or fetches the URL; the app opens it when the user
+ * taps the button.
+ */
+export interface Action {
+    /** 1–40 characters (trimmed), one line, shown as sent: `Reply`, `Call Emily`. */
+    title: string;
+    /**
+     * ≤ 2048 bytes, no spaces: `https://` (no credentials), `mailto:` with one address
+     * (`?subject=…&body=…` percent-encoded, no other keys), `tel:` or `sms:` with a number
+     * (`sms:` also `?body=…`). Other schemes are refused.
+     */
+    url: string;
+}
 /**
  * One event for `POST /v1/messages`. Only `message` is required. Fields are camelCase here and
  * sent as the snake_case names of the API (`groupKey` → `group_key`). Empty optional strings
@@ -79,6 +93,8 @@ export interface Message {
     url?: string | null;
     /** HTTPS image fetched by the server after ingestion. No credentials or fragment. ≤ 2048 bytes. */
     imageUrl?: string | null;
+    /** Up to 3 buttons, in display order (the first is the primary). Empty means none. */
+    actions?: readonly Action[] | null;
     /** ≤ 16 keys matching `[A-Za-z0-9_.-]{1,64}`; values are strings (≤ 512 chars), numbers or booleans. */
     metadata?: Record<string, MetadataValue> | null;
     /** Push lifetime, 60–86400 seconds. Default 3600. */

package/dist/esm/validate.d.ts

@@ -9,6 +9,8 @@ export declare const LIMITS: {
     readonly channel: 64;
     readonly groupKey: 128;
     readonly urlBytes: 2048;
+    readonly actions: 3;
+    readonly actionTitle: 40;
     readonly metadataKeys: 16;
     readonly metadataValue: 512;
     readonly ttlMin: 60;
@@ -24,5 +26,11 @@ export declare function checkIdempotencyKey(key: unknown): string;
  * listing every invalid field.
  */
 export declare function buildBody(input: Message, defaults?: Defaults, validate?: boolean): Record<string, unknown>;
+/**
+ * The server's check of a (trimmed) action URL, scheme in any case: `https://` with a host and
+ * no credentials (as `url`), `mailto:` with one address and an optional `?subject=…&body=…`,
+ * `tel:` / `tel://` with a number, `sms:` with a number and an optional `?body=…`.
+ */
+export declare function validActionUrl(s: string): boolean;
 /** Syntactic check matching the server: https, a host, no credentials, no spaces/backslashes, ≤ 2048 bytes. */
 export declare function validUrl(raw: unknown, image: boolean): boolean;

package/dist/esm/validate.js

@@ -10,6 +10,8 @@ export const LIMITS = {
     channel: 64,
     groupKey: 128,
     urlBytes: 2048,
+    actions: 3,
+    actionTitle: 40,
     metadataKeys: 16,
     metadataValue: 512,
     ttlMin: 60,
@@ -31,6 +33,7 @@ const FIELDS = {
     occurredAt: 'occurred_at',
     url: 'url',
     imageUrl: 'image_url',
+    actions: 'actions',
     metadata: 'metadata',
     ttlSeconds: 'ttl_seconds',
     sourceSequence: 'source_sequence',
@@ -42,6 +45,15 @@ const CONTROL_EXCEPT_BREAKS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u0
 const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
 const METADATA_KEY = /^[A-Za-z0-9_.-]{1,64}$/;
 const IDEMPOTENCY_KEY = /^[\x21-\x7e]{1,128}$/;
+// Unicode White_Space outside the control characters (Go's unicode.IsSpace, as on the server).
+const SPACE = /[ \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]/;
+// The number of a tel: or sms: action: an optional leading +, digits and - . ( ) separators.
+const PHONE_NUMBER = /^\+?[0-9().-]*[0-9][0-9().-]*$/;
+// A single plain mailto: address, once percent-decoded: dot-atom@dot-atom with a dotted domain
+// (or an IPv4 literal).
+const ATOM = "[A-Za-z0-9!#$%&'*+/=?^_`{|}~\\-\\u{80}-\\u{10ffff}]+";
+const MAIL_ADDRESS = new RegExp(`^${ATOM}(\\.${ATOM})*@(${ATOM}(\\.${ATOM})+|\\[[0-9.]*\\.[0-9.]*\\])$`, 'u');
+const BAD_ESCAPE = /%(?![0-9A-Fa-f]{2})/;
 const encoder = new TextEncoder();
 export const byteLength = (s) => encoder.encode(s).length;
 const codePoints = (s) => {
@@ -93,7 +105,7 @@ export function buildBody(input, defaults = {}, validate = true) {
     const body = {};
     for (const name of Object.keys(FIELDS)) {
         const v = value(name);
-        if (v === undefined)
+        if (v === undefined || (name === 'actions' && Array.isArray(v) && v.length === 0))
             continue;
         const wire = FIELDS[name];
         if (name === 'occurredAt') {
@@ -170,6 +182,7 @@ function checkMessage(b, add) {
     if (b.image_url !== undefined && !validUrl(b.image_url, true)) {
         add('image_url', 'invalid_format', 'must be an https URL without credentials or fragment, at most 2048 bytes');
     }
+    checkActions(b.actions, add);
     const md = b.metadata;
     if (md !== undefined) {
         if (typeof md !== 'object' || md === null || Array.isArray(md)) {
@@ -203,6 +216,100 @@ function checkMessage(b, add) {
         add('ttl_seconds', 'out_of_range', `must be an integer between ${LIMITS.ttlMin} and ${LIMITS.ttlMax}`);
     }
 }
+function checkActions(v, add) {
+    if (v === undefined)
+        return;
+    const format = 'must be an array of at most 3 { title, url } objects';
+    if (!Array.isArray(v))
+        return add('actions', 'invalid_format', format);
+    if (v.length > LIMITS.actions)
+        return add('actions', 'too_long', `at most ${LIMITS.actions} actions`);
+    if (v.some((a) => a === null || typeof a !== 'object' || Array.isArray(a)))
+        return add('actions', 'invalid_format', format);
+    v.forEach((a, i) => {
+        const field = `actions[${i}]`;
+        const title = typeof a.title === 'string' ? a.title.trim() : a.title;
+        if (title === undefined || title === null || title === '')
+            add(`${field}.title`, 'required', 'title is required');
+        else if (typeof title !== 'string')
+            add(`${field}.title`, 'invalid_format', 'must be a string');
+        else if (codePoints(title) > LIMITS.actionTitle)
+            add(`${field}.title`, 'too_long', `must be at most ${LIMITS.actionTitle} characters`);
+        else if (CONTROL.test(title))
+            add(`${field}.title`, 'invalid_format', 'must be one line without control characters');
+        const url = typeof a.url === 'string' ? a.url.trim() : a.url;
+        if (url === undefined || url === null || url === '')
+            add(`${field}.url`, 'required', 'url is required');
+        else if (typeof url !== 'string')
+            add(`${field}.url`, 'invalid_format', 'must be a string');
+        else if (byteLength(url) > LIMITS.urlBytes)
+            add(`${field}.url`, 'too_long', `must be at most ${LIMITS.urlBytes} bytes`);
+        else if (!validActionUrl(url))
+            add(`${field}.url`, 'invalid_format', 'must be an https://, mailto:, tel: or sms: URL without spaces');
+        for (const key of Object.keys(a).sort()) {
+            if (key !== 'title' && key !== 'url')
+                add(`${field}.${key}`, 'not_allowed', 'unknown field (an action has title and url)');
+        }
+    });
+}
+/**
+ * The server's check of a (trimmed) action URL, scheme in any case: `https://` with a host and
+ * no credentials (as `url`), `mailto:` with one address and an optional `?subject=…&body=…`,
+ * `tel:` / `tel://` with a number, `sms:` with a number and an optional `?body=…`.
+ */
+export function validActionUrl(s) {
+    if (CONTROL.test(s) || SPACE.test(s))
+        return false;
+    const colon = s.indexOf(':');
+    if (colon < 0)
+        return false;
+    const rest = s.slice(colon + 1);
+    const [head, query] = splitOnce(rest, '?');
+    switch (s.slice(0, colon).toLowerCase()) {
+        case 'https':
+            return validUrl(s, false);
+        case 'mailto':
+            return mailAddress(head) && actionQuery(query, ['subject', 'body']);
+        case 'tel':
+            return PHONE_NUMBER.test(rest.startsWith('//') ? rest.slice(2) : rest);
+        case 'sms':
+            return PHONE_NUMBER.test(head) && actionQuery(query, ['body']);
+        default:
+            return false;
+    }
+}
+function splitOnce(s, sep) {
+    const i = s.indexOf(sep);
+    return i < 0 ? [s, ''] : [s.slice(0, i), s.slice(i + 1)];
+}
+function mailAddress(s) {
+    if (BAD_ESCAPE.test(s))
+        return false;
+    try {
+        return MAIL_ADDRESS.test(decodeURIComponent(s));
+    }
+    catch {
+        return false;
+    }
+}
+// Valid percent-encoding, no ";" separators and only the allowed keys ("" is no query).
+function actionQuery(q, allowed) {
+    for (const pair of q.split('&')) {
+        if (pair.includes(';') || BAD_ESCAPE.test(pair))
+            return false;
+        if (pair === '')
+            continue;
+        const [key] = splitOnce(pair, '=');
+        try {
+            if (!allowed.includes(decodeURIComponent(key.replace(/\+/g, ' '))))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
 function shortText(b, field, max, add) {
     const v = b[field];
     if (v === undefined)

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/build.mjs on every build. Do not edit: change
 // "version" in package.json instead.
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "honk-me",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official Node.js/TypeScript client for Honk (honk-me.app): send events from apps, scripts and automations to your phone, with retries and idempotency built in.",
   "keywords": [
     "honk",
@@ -24,7 +24,11 @@
     "url": "git+https://github.com/honk-me/honk-node.git"
   },
   "license": "MIT",
-  "author": "Honk contributors",
+  "author": {
+    "name": "Honk",
+    "email": "accounts@honk-me.app",
+    "url": "https://honk-me.app"
+  },
   "sideEffects": false,
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",