slotlock 0.6.2 → 0.7.0

package/webhooks.d.ts

@@ -17,13 +17,13 @@ export interface SlotlockCloudEvent {
 }
 /**
  * A change as CloudEvents 1.0 (structured mode): `type` is `io.pylota.slotlock.<change type>`, with
- * the extension attributes `slotlockorigin` and `slotlockkeyid` when the change records them. A
- * `coverage.*` change is redacted as the feed serves it (slotlockServedChange), whoever built it.
+ * `slotlockorigin` and `slotlockkeyid` when recorded. A `coverage.*` change is redacted as the feed
+ * serves it (slotlockServedChange).
  */
 export declare function slotlockCloudEvent(change: SlotlockChange): SlotlockCloudEvent;
 /**
- * The Standard Webhooks signature of one attempt: `v1,` and the base64 HMAC-SHA256, keyed by the
- * secret's bytes, of `id.timestamp.body`.
+ * The Standard Webhooks signature: `v1,` and the base64 HMAC-SHA256 of `id.timestamp.body`, keyed
+ * by the secret's bytes.
  */
 export declare function signSlotlockWebhook(params: {
     secret: string;
@@ -32,9 +32,8 @@ export declare function signSlotlockWebhook(params: {
     body: string;
 }): string;
 /**
- * When to try a failed endpoint again, by how many attempts have failed in a row: the Standard
- * Webhooks example schedule (5 s, 5 min, 30 min, 2 h, 5 h, then 10 h), with ±10% jitter, and never
- * sooner than the endpoint's Retry-After (capped at a day).
+ * Retry delay by consecutive failures: the Standard Webhooks example schedule (5 s, 5 min, 30 min,
+ * 2 h, 5 h, then 10 h) with ±10% jitter, never sooner than Retry-After (capped at a day).
  */
 export declare function slotlockWebhookRetryDelayMs(attempts: number, retryAfterMs?: number, random?: () => number): number;
 /** Whether `address` is one a webhook may not reach: loopback, private, link-local, and the like. */
@@ -50,19 +49,18 @@ export type SlotlockWebhookSender = (request: {
     body: string;
 }) => Promise<SlotlockWebhookResponse>;
 /**
- * POST with Node's http client: no redirect is followed, the answer's body is never read beyond
- * 64 KiB, and every address the host resolves to is checked when the socket connects, so a name
- * that resolves to a private network (or is rebound to one) is refused unless `allowPrivateNetworks`.
+ * POST with Node's http client: no redirect is followed, at most 64 KiB of body is read, and every
+ * resolved address is checked at connect time, so a name resolving (or rebound) to a private
+ * network is refused unless `allowPrivateNetworks`.
  */
 export declare function createSlotlockWebhookSender(options?: {
     timeoutMs?: number;
     allowPrivateNetworks?: boolean;
 }): SlotlockWebhookSender;
 /**
- * A `dns.lookup` that answers every address a name resolves to, and refuses (an error with `code`)
- * a name with any private one unless `allowPrivateNetworks`. Given to a socket's connect, it checks
- * the addresses the connection will use, so a name rebound to a private address after an earlier
- * check is still refused. `resolve` stands in for `dns.lookup` (tests).
+ * A `dns.lookup` that returns every address and refuses (with `code`) a name with any private one
+ * unless `allowPrivateNetworks`. Used at socket connect, so a rebound name is still refused.
+ * `resolve` stands in for `dns.lookup` in tests.
  */
 export declare function slotlockPrivateAddressLookup(options: {
     allowPrivateNetworks: boolean;
@@ -71,11 +69,10 @@ export declare function slotlockPrivateAddressLookup(options: {
     resolve?: typeof dnsLookup;
 }): typeof dnsLookup;
 /**
- * A `fetch` for a server reaching a URL a tenant chose (the dashboard assistant's model): Node's
- * http client with the webhooks' address check. A URL naming a private address, or a host that
- * resolves to one when the socket connects, is refused with an error whose `code` is
- * `private_address`, unless `allowPrivateNetworks`. No redirect is followed (the answer is
- * returned as is) and no proxy from the environment is used. Takes a string body only.
+ * A `fetch` for URLs a tenant chose (the assistant's model), with the webhooks' address check: a
+ * private address or a host resolving to one at connect time is refused with `code`
+ * `private_address` unless `allowPrivateNetworks`. No redirects, no environment proxy, string
+ * bodies only.
  */
 export declare function createSlotlockGuardedFetch(options?: {
     allowPrivateNetworks?: boolean;
@@ -88,9 +85,9 @@ export interface SlotlockWebhookPassResult {
     failed: number;
 }
 /**
- * One delivery pass for a tenant: claim each endpoint with changes due, send them in order until
- * one fails, and record how far each got. A 2xx is delivered; 410 disables the endpoint; anything
- * else, or no answer, is retried on the schedule. The send happens outside any transaction.
+ * One delivery pass for a tenant: claim each endpoint with changes due, send in order until one
+ * fails, and record progress. 2xx is delivered; 410 disables the endpoint; anything else is retried
+ * on the schedule. Sending happens outside any transaction.
  */
 export declare function deliverSlotlockWebhooks(params: {
     feed: Pick<SlotlockEventFeed, 'claimWebhookDeliveries' | 'settleWebhookDelivery'>;
@@ -108,9 +105,9 @@ export interface SlotlockWebhookScheduler {
     close(): Promise<void>;
 }
 /**
- * Delivery passes every `intervalMs` (250-60,000, default 2,000) for the tenants `tenants()` lists
- * (the store's webhook_tenants(), say) and those touched, one tenant at a time. A pass that fails
- * is reported and the next one runs as usual.
+ * Delivery passes every `intervalMs` (250-60,000, default 2,000) for `tenants()` (the store's
+ * webhook_tenants(), say) and touched tenants. A failed pass is reported and the next runs as
+ * usual.
  */
 export declare function startSlotlockWebhookDelivery(options: {
     tenants: () => Promise<readonly string[]>;

package/webhooks.js

@@ -1,8 +1,7 @@
-// Webhook delivery of the event feed (RFC 0002 P1-5): each change is a CloudEvents 1.0 envelope,
-// signed and headed as Standard Webhooks asks (webhook-id, webhook-timestamp, webhook-signature),
-// sent to each endpoint in feed order, one at a time, and retried on a growing schedule until the
-// endpoint has failed for a day. The store keeps the position and the schedule (event-feed.ts), so
-// a worker that stops mid-batch loses nothing: the next one sends the rest, with the same ids.
+// Webhook delivery of the event feed: each change is a CloudEvents 1.0 envelope, signed with
+// Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature), sent per endpoint
+// in feed order, and retried on a growing schedule until the endpoint has failed for a day. The
+// store keeps position and schedule (event-feed.ts), so a stopped worker loses nothing.
 import { createHmac } from 'node:crypto';
 import { lookup as dnsLookup } from 'node:dns';
 import { Agent as HttpAgent, request as httpRequest } from 'node:http';
@@ -13,8 +12,8 @@ import { slotlockServedChange, } from './event-feed.js';
 import { ignoreRejection } from './hooks.js';
 /**
  * A change as CloudEvents 1.0 (structured mode): `type` is `io.pylota.slotlock.<change type>`, with
- * the extension attributes `slotlockorigin` and `slotlockkeyid` when the change records them. A
- * `coverage.*` change is redacted as the feed serves it (slotlockServedChange), whoever built it.
+ * `slotlockorigin` and `slotlockkeyid` when recorded. A `coverage.*` change is redacted as the feed
+ * serves it (slotlockServedChange).
  */
 export function slotlockCloudEvent(change) {
     const served = slotlockServedChange(change.type, change.subject, change.data);
@@ -32,8 +31,8 @@ export function slotlockCloudEvent(change) {
     };
 }
 /**
- * The Standard Webhooks signature of one attempt: `v1,` and the base64 HMAC-SHA256, keyed by the
- * secret's bytes, of `id.timestamp.body`.
+ * The Standard Webhooks signature: `v1,` and the base64 HMAC-SHA256 of `id.timestamp.body`, keyed
+ * by the secret's bytes.
  */
 export function signSlotlockWebhook(params) {
     if (!params.secret.startsWith('whsec_'))
@@ -45,9 +44,8 @@ export function signSlotlockWebhook(params) {
     return `v1,${signature}`;
 }
 /**
- * When to try a failed endpoint again, by how many attempts have failed in a row: the Standard
- * Webhooks example schedule (5 s, 5 min, 30 min, 2 h, 5 h, then 10 h), with ±10% jitter, and never
- * sooner than the endpoint's Retry-After (capped at a day).
+ * Retry delay by consecutive failures: the Standard Webhooks example schedule (5 s, 5 min, 30 min,
+ * 2 h, 5 h, then 10 h) with ±10% jitter, never sooner than Retry-After (capped at a day).
  */
 export function slotlockWebhookRetryDelayMs(attempts, retryAfterMs, random = Math.random) {
     const schedule = [5_000, 300_000, 1_800_000, 7_200_000, 18_000_000, 36_000_000];
@@ -55,8 +53,8 @@ export function slotlockWebhookRetryDelayMs(attempts, retryAfterMs, random = Mat
     const jittered = Math.round(base * (0.9 + random() * 0.2));
     return Math.max(jittered, Math.min(retryAfterMs ?? 0, 86_400_000));
 }
-// One list per family: a BlockList also checks an IPv4 address against IPv6 rules through its
-// mapped form, so ::ffff:0:0/96 in the same list would match every IPv4 address.
+// One list per family: a BlockList checks IPv4 against IPv6 rules via the mapped form, so
+// ::ffff:0:0/96 in the same list would match every IPv4 address.
 const PRIVATE_IPV4 = new BlockList();
 for (const [address, prefix] of [
     ['0.0.0.0', 8],
@@ -95,7 +93,6 @@ export function isPrivateAddress(address) {
         return PRIVATE_IPV4.check(address, 'ipv4');
     if (family !== 6)
         return true;
-    // An IPv4-mapped address (::ffff:a.b.c.d, or its hex form) is the IPv4 address it carries.
     const mapped = /^::ffff:(?:(\d+\.\d+\.\d+\.\d+)|([0-9a-f]{1,4}):([0-9a-f]{1,4}))$/i.exec(address);
     if (mapped) {
         if (mapped[1])
@@ -107,9 +104,9 @@ export function isPrivateAddress(address) {
     return PRIVATE_IPV6.check(address, 'ipv6');
 }
 /**
- * POST with Node's http client: no redirect is followed, the answer's body is never read beyond
- * 64 KiB, and every address the host resolves to is checked when the socket connects, so a name
- * that resolves to a private network (or is rebound to one) is refused unless `allowPrivateNetworks`.
+ * POST with Node's http client: no redirect is followed, at most 64 KiB of body is read, and every
+ * resolved address is checked at connect time, so a name resolving (or rebound) to a private
+ * network is refused unless `allowPrivateNetworks`.
  */
 export function createSlotlockWebhookSender(options = {}) {
     const timeoutMs = options.timeoutMs ?? 15_000;
@@ -128,8 +125,8 @@ export function createSlotlockWebhookSender(options = {}) {
         const outgoing = send(url, {
             method: 'POST',
             headers: { ...request.headers, 'Content-Length': String(Buffer.byteLength(request.body)) },
-            // An agent of its own, never the global one: with NODE_USE_ENV_PROXY a proxy from the
-            // environment would connect for us, and the address check below would never run.
+            // Our own agent, never the global one: with NODE_USE_ENV_PROXY a proxy would connect
+            // instead and the address check would never run.
             agent: url.protocol === 'https:' ? new HttpsAgent({ lookup }) : new HttpAgent({ lookup }),
             lookup,
             timeout: timeoutMs,
@@ -152,8 +149,8 @@ export function createSlotlockWebhookSender(options = {}) {
         });
         const timedOut = () => outgoing.destroy(Object.assign(new Error('webhook request timed out'), { code: 'webhook_timeout' }));
         outgoing.on('timeout', timedOut);
-        // `timeout` is idleness only: an answer dripped a byte at a time would hold the request
-        // open for hours. The whole exchange has this long.
+        // `timeout` is idleness only, so a dripped answer could hold the request for hours: the whole
+        // exchange gets this long.
         const deadline = setTimeout(timedOut, timeoutMs);
         deadline.unref?.();
         outgoing.on('close', () => clearTimeout(deadline));
@@ -167,10 +164,9 @@ function namesPrivateAddress(url) {
     return isIP(host) !== 0 && isPrivateAddress(host);
 }
 /**
- * A `dns.lookup` that answers every address a name resolves to, and refuses (an error with `code`)
- * a name with any private one unless `allowPrivateNetworks`. Given to a socket's connect, it checks
- * the addresses the connection will use, so a name rebound to a private address after an earlier
- * check is still refused. `resolve` stands in for `dns.lookup` (tests).
+ * A `dns.lookup` that returns every address and refuses (with `code`) a name with any private one
+ * unless `allowPrivateNetworks`. Used at socket connect, so a rebound name is still refused.
+ * `resolve` stands in for `dns.lookup` in tests.
  */
 export function slotlockPrivateAddressLookup(options) {
     const resolve = options.resolve ?? dnsLookup;
@@ -191,11 +187,10 @@ export function slotlockPrivateAddressLookup(options) {
     });
 }
 /**
- * A `fetch` for a server reaching a URL a tenant chose (the dashboard assistant's model): Node's
- * http client with the webhooks' address check. A URL naming a private address, or a host that
- * resolves to one when the socket connects, is refused with an error whose `code` is
- * `private_address`, unless `allowPrivateNetworks`. No redirect is followed (the answer is
- * returned as is) and no proxy from the environment is used. Takes a string body only.
+ * A `fetch` for URLs a tenant chose (the assistant's model), with the webhooks' address check: a
+ * private address or a host resolving to one at connect time is refused with `code`
+ * `private_address` unless `allowPrivateNetworks`. No redirects, no environment proxy, string
+ * bodies only.
  */
 export function createSlotlockGuardedFetch(options = {}) {
     const allow = options.allowPrivateNetworks === true;
@@ -224,7 +219,7 @@ export function createSlotlockGuardedFetch(options = {}) {
             const outgoing = send(url, {
                 method: init.method ?? 'GET',
                 headers,
-                // An agent of its own: a proxy from the environment would skip the address check.
+                // Our own agent: an environment proxy would skip the address check.
                 agent: url.protocol === 'https:' ? new HttpsAgent({ lookup }) : new HttpAgent({ lookup }),
                 lookup,
                 ...(init.signal ? { signal: init.signal } : {}),
@@ -250,9 +245,9 @@ export function createSlotlockGuardedFetch(options = {}) {
     });
 }
 /**
- * One delivery pass for a tenant: claim each endpoint with changes due, send them in order until
- * one fails, and record how far each got. A 2xx is delivered; 410 disables the endpoint; anything
- * else, or no answer, is retried on the schedule. The send happens outside any transaction.
+ * One delivery pass for a tenant: claim each endpoint with changes due, send in order until one
+ * fails, and record progress. 2xx is delivered; 410 disables the endpoint; anything else is retried
+ * on the schedule. Sending happens outside any transaction.
  */
 export async function deliverSlotlockWebhooks(params) {
     const now = params.now ?? Date.now;
@@ -267,7 +262,7 @@ export async function deliverSlotlockWebhooks(params) {
     await Promise.all(claims.map(async (claim) => {
         let last;
         let failure;
-        // The failures before this pass set the delay: the schedule grows across passes.
+        // Failures before this pass set the delay, so the schedule grows across passes.
         let attempts = claim.endpoint.attempts;
         for (const change of claim.changes) {
             if (now() >= stopAt)
@@ -328,9 +323,9 @@ export async function deliverSlotlockWebhooks(params) {
     return { delivered, failed };
 }
 /**
- * Delivery passes every `intervalMs` (250-60,000, default 2,000) for the tenants `tenants()` lists
- * (the store's webhook_tenants(), say) and those touched, one tenant at a time. A pass that fails
- * is reported and the next one runs as usual.
+ * Delivery passes every `intervalMs` (250-60,000, default 2,000) for `tenants()` (the store's
+ * webhook_tenants(), say) and touched tenants. A failed pass is reported and the next runs as
+ * usual.
  */
 export function startSlotlockWebhookDelivery(options) {
     const intervalMs = options.intervalMs ?? 2_000;
@@ -361,7 +356,7 @@ export function startSlotlockWebhookDelivery(options) {
         await Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, worker));
     };
     const timer = setInterval(() => {
-        // A pass still running skips this tick rather than queue another behind it.
+        // A pass still running skips this tick.
         if (running || closed)
             return;
         running = pass()

package/weekly-hours.d.ts

@@ -13,6 +13,9 @@ export interface HoursWindow {
     to: number;
 }
 export type WeeklyHours = Record<Weekday, HoursWindow[]>;
+export declare function invalidAvailability(message: string): Error & {
+    code: 'invalid_availability';
+};
 /**
  * Why `candidate` cannot be an availability rule: `'shape'` (not exactly rrule, startMinutes 0-1439
  * and durationMinutes 1-10080), `'unsupported'` (a rule `expandRules` would skip: anything but

package/weekly-hours.js

@@ -23,7 +23,7 @@ const MAX_WINDOWS_A_DAY = 2;
 const CANONICAL_RRULE = /^FREQ=WEEKLY;BYDAY=((?:MO|TU|WE|TH|FR|SA|SU)(?:,(?:MO|TU|WE|TH|FR|SA|SU))*)$/;
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const isMinuteOfDay = (value) => Number.isInteger(value) && value >= 0 && value < DAY_MINUTES;
-function invalidAvailability(message) {
+export function invalidAvailability(message) {
     return Object.assign(new Error(message), { code: 'invalid_availability' });
 }
 /**