@abloatai/ablo 0.26.0 → 0.28.0

package/dist/types/streams.js

@@ -1,11 +1,11 @@
 /**
- * Multiplayer stream types.
+ * The types for real-time multiplayer coordination.
  *
- * Ablo treats humans and agents as participants on live application
- * entities. Participants announce what they are reading or editing,
- * claim before writing, and capture context watermarks before
- * long-running AI work. The customer keeps their own schema, agent
- * stack, tools, prompts, and product policy; the sync engine provides
- * the shared coordination substrate.
+ * Ablo treats people and AI agents alike as participants working on live
+ * application entities. A participant announces what it is reading or editing,
+ * claims an entity before writing to it, and captures a context snapshot before
+ * starting long-running AI work. You keep your own schema, agent stack, tools,
+ * prompts, and product rules; this package provides the shared coordination
+ * layer underneath.
  */
 export {};

package/dist/utils/asyncIterator.d.ts

@@ -1,41 +1,34 @@
 /**
- * `asyncIteratorFrom` — adapt any callback-subscription primitive
- * into an async iterable.
+ * Turns a callback-based subscription into an async iterable that yields the
+ * latest snapshot each time the source changes. You supply two functions:
+ * `subscribe(listener)`, which registers your listener and returns a teardown
+ * function, and `getSnapshot()`, which reads the current value. On every change
+ * notification the iterator calls `getSnapshot()` and hands the result to the
+ * consumer's `for await` loop; when the loop ends, the iterator runs the
+ * teardown function.
  *
- * The inputs are two functions:
+ * Because each notification yields the current snapshot rather than a specific
+ * event, bursts coalesce harmlessly — a consumer that falls behind still ends up
+ * with the freshest value. The queue is unbounded, so a consumer that never
+ * advances lets memory grow without limit. When individual events matter and
+ * must not be dropped, use {@link asyncIteratorFromEvents} instead.
  *
- *   - `subscribe(onChange): unsubscribe` — the existing reactivity
- *     primitive on `PresenceStream` / `ClaimStream`. We register a
- *     listener that enqueues a value every time the source mutates;
- *     we tear it down in `return()`.
- *   - `getSnapshot()` — read the latest value to hand to the
- *     consumer. Called on every mutation notification.
- *
- * Back-pressure: an unlimited queue. If the consumer is slower than
- * the producer (rare for presence — mutations are <1/s per peer),
- * memory grows monotonically inside the iterator. For the current
- * presence workload this is fine; if we ever surface a high-frequency
- * stream (deltas at full firehose) we can bound the queue or drop
- * coalescable values.
- *
- * Multiple iterators: each call to the returned factory creates an
- * independent iterator with its own subscription. Iterators don't
- * steal values from each other — two `for await` loops on the same
- * stream both observe every mutation.
+ * Each call to the factory creates an independent iterator with its own
+ * subscription. Two `for await` loops over the same source each observe every
+ * change; they do not take values from one another.
  */
 /**
- * Variant of `asyncIteratorFrom` for event-per-iteration streams.
- *
- * Unlike the snapshot variant (where every notification yields the
- * *current value* — coalescing bursts is fine because state is the
- * consumer's concern), this variant yields the *specific value*
- * pushed by each event. Use when the underlying stream delivers
- * discrete events that must not be dropped — e.g. `DeltaEnvelope`
- * firehose.
+ * Turns a callback-based subscription into an async iterable that yields each
+ * discrete event, in order, with none dropped. You supply a single
+ * `subscribe(push)` function: it registers your producer and returns a teardown
+ * function, and your producer calls `push(value)` once per event. The consumer's
+ * `for await` loop receives every pushed value.
  *
- * The `subscribe(push): unsubscribe` signature takes a callback that
- * enqueues an event. The consumer's `for await` receives every
- * enqueued value in order.
+ * This is the counterpart to {@link asyncIteratorFrom}. Reach for that one when
+ * you only need the latest state and coalescing bursts is fine; reach for this
+ * one when every event is significant — for example a stream of change deltas
+ * where skipping one would lose data. The queue is unbounded, so a consumer that
+ * stops advancing lets memory grow without limit.
  */
 export declare function asyncIteratorFromEvents<T>(subscribe: (push: (value: T) => void) => () => void): AsyncIterableIterator<T>;
 export declare function asyncIteratorFrom<T>(subscribe: (listener: () => void) => () => void, getSnapshot: () => T): AsyncIterableIterator<T>;

package/dist/utils/asyncIterator.js

@@ -1,41 +1,34 @@
 /**
- * `asyncIteratorFrom` — adapt any callback-subscription primitive
- * into an async iterable.
+ * Turns a callback-based subscription into an async iterable that yields the
+ * latest snapshot each time the source changes. You supply two functions:
+ * `subscribe(listener)`, which registers your listener and returns a teardown
+ * function, and `getSnapshot()`, which reads the current value. On every change
+ * notification the iterator calls `getSnapshot()` and hands the result to the
+ * consumer's `for await` loop; when the loop ends, the iterator runs the
+ * teardown function.
  *
- * The inputs are two functions:
+ * Because each notification yields the current snapshot rather than a specific
+ * event, bursts coalesce harmlessly — a consumer that falls behind still ends up
+ * with the freshest value. The queue is unbounded, so a consumer that never
+ * advances lets memory grow without limit. When individual events matter and
+ * must not be dropped, use {@link asyncIteratorFromEvents} instead.
  *
- *   - `subscribe(onChange): unsubscribe` — the existing reactivity
- *     primitive on `PresenceStream` / `ClaimStream`. We register a
- *     listener that enqueues a value every time the source mutates;
- *     we tear it down in `return()`.
- *   - `getSnapshot()` — read the latest value to hand to the
- *     consumer. Called on every mutation notification.
- *
- * Back-pressure: an unlimited queue. If the consumer is slower than
- * the producer (rare for presence — mutations are <1/s per peer),
- * memory grows monotonically inside the iterator. For the current
- * presence workload this is fine; if we ever surface a high-frequency
- * stream (deltas at full firehose) we can bound the queue or drop
- * coalescable values.
- *
- * Multiple iterators: each call to the returned factory creates an
- * independent iterator with its own subscription. Iterators don't
- * steal values from each other — two `for await` loops on the same
- * stream both observe every mutation.
+ * Each call to the factory creates an independent iterator with its own
+ * subscription. Two `for await` loops over the same source each observe every
+ * change; they do not take values from one another.
  */
 /**
- * Variant of `asyncIteratorFrom` for event-per-iteration streams.
- *
- * Unlike the snapshot variant (where every notification yields the
- * *current value* — coalescing bursts is fine because state is the
- * consumer's concern), this variant yields the *specific value*
- * pushed by each event. Use when the underlying stream delivers
- * discrete events that must not be dropped — e.g. `DeltaEnvelope`
- * firehose.
+ * Turns a callback-based subscription into an async iterable that yields each
+ * discrete event, in order, with none dropped. You supply a single
+ * `subscribe(push)` function: it registers your producer and returns a teardown
+ * function, and your producer calls `push(value)` once per event. The consumer's
+ * `for await` loop receives every pushed value.
  *
- * The `subscribe(push): unsubscribe` signature takes a callback that
- * enqueues an event. The consumer's `for await` receives every
- * enqueued value in order.
+ * This is the counterpart to {@link asyncIteratorFrom}. Reach for that one when
+ * you only need the latest state and coalescing bursts is fine; reach for this
+ * one when every event is significant — for example a stream of change deltas
+ * where skipping one would lose data. The queue is unbounded, so a consumer that
+ * stops advancing lets memory grow without limit.
  */
 export function asyncIteratorFromEvents(subscribe) {
     const queue = [];

package/dist/utils/duration.d.ts

@@ -1,28 +1,25 @@
 /**
- * Duration parser — `'3m'`, `'24h'`, `500` (ms), `'15s'`, etc.
- *
- * The same TTL flavor every config-driven tool uses (Vercel's `ms`,
- * Zod's `.duration()`, a hundred CLIs). Zero deps, one regex, three
- * units that cover everything the SDK needs:
+ * Parses a duration into milliseconds. A duration is either a number of seconds
+ * or a string with a unit suffix — milliseconds, seconds, minutes, or hours:
  *
  *   - `'500ms'` → 500 ms
  *   - `'30s'`   → 30 000 ms
  *   - `'3m'`    → 180 000 ms
  *   - `'24h'`   → 86 400 000 ms
  *
- * Back-compat escape hatch: plain numbers are kept as-is and
- * interpreted in the caller's existing unit (seconds for TTL APIs).
- * This lets us retrofit the string form to every `ttlSeconds` field
- * without breaking numeric callers — the wrapper below branches on
- * the input type.
+ * A bare number is interpreted as seconds rather than milliseconds, matching the
+ * `ttlSeconds` fields used throughout the SDK, so a numeric caller and a string
+ * caller can pass the same field interchangeably. {@link toMs} returns
+ * milliseconds; {@link toSeconds} returns whole seconds.
  */
 export type Duration = number | `${number}ms` | `${number}s` | `${number}m` | `${number}h`;
 /**
- * Parse a duration expressed as a number-of-seconds OR a unit-suffixed
- * string. Returns milliseconds. A bare number is interpreted as
- * **seconds** (matches the existing `ttlSeconds` semantics — prevents
- * silent breakage when a caller migrates from numeric to string).
+ * Parses a duration and returns the equivalent number of milliseconds. Accepts
+ * either a bare number, interpreted as seconds, or a unit-suffixed string such
+ * as `'500ms'`, `'30s'`, `'3m'`, or `'24h'`. Throws an
+ * {@link AbloValidationError} with code `duration_invalid` when a string does
+ * not match a supported unit.
  */
 export declare function toMs(input: Duration): number;
-/** Convenience: same as `toMs` but divides out to seconds. */
+/** Parses a duration like {@link toMs} but returns whole seconds, rounding down. */
 export declare function toSeconds(input: Duration): number;

package/dist/utils/duration.js

@@ -1,20 +1,16 @@
 /**
- * Duration parser — `'3m'`, `'24h'`, `500` (ms), `'15s'`, etc.
- *
- * The same TTL flavor every config-driven tool uses (Vercel's `ms`,
- * Zod's `.duration()`, a hundred CLIs). Zero deps, one regex, three
- * units that cover everything the SDK needs:
+ * Parses a duration into milliseconds. A duration is either a number of seconds
+ * or a string with a unit suffix — milliseconds, seconds, minutes, or hours:
  *
  *   - `'500ms'` → 500 ms
  *   - `'30s'`   → 30 000 ms
  *   - `'3m'`    → 180 000 ms
  *   - `'24h'`   → 86 400 000 ms
  *
- * Back-compat escape hatch: plain numbers are kept as-is and
- * interpreted in the caller's existing unit (seconds for TTL APIs).
- * This lets us retrofit the string form to every `ttlSeconds` field
- * without breaking numeric callers — the wrapper below branches on
- * the input type.
+ * A bare number is interpreted as seconds rather than milliseconds, matching the
+ * `ttlSeconds` fields used throughout the SDK, so a numeric caller and a string
+ * caller can pass the same field interchangeably. {@link toMs} returns
+ * milliseconds; {@link toSeconds} returns whole seconds.
  */
 import { AbloValidationError } from '../errors.js';
 const PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/;
@@ -25,10 +21,11 @@ const UNIT_MS = {
     h: 3_600_000,
 };
 /**
- * Parse a duration expressed as a number-of-seconds OR a unit-suffixed
- * string. Returns milliseconds. A bare number is interpreted as
- * **seconds** (matches the existing `ttlSeconds` semantics — prevents
- * silent breakage when a caller migrates from numeric to string).
+ * Parses a duration and returns the equivalent number of milliseconds. Accepts
+ * either a bare number, interpreted as seconds, or a unit-suffixed string such
+ * as `'500ms'`, `'30s'`, `'3m'`, or `'24h'`. Throws an
+ * {@link AbloValidationError} with code `duration_invalid` when a string does
+ * not match a supported unit.
  */
 export function toMs(input) {
     if (typeof input === 'number')
@@ -42,7 +39,7 @@ export function toMs(input) {
     const unit = match[2];
     return value * UNIT_MS[unit];
 }
-/** Convenience: same as `toMs` but divides out to seconds. */
+/** Parses a duration like {@link toMs} but returns whole seconds, rounding down. */
 export function toSeconds(input) {
     return Math.floor(toMs(input) / 1_000);
 }

package/dist/utils/mobxSetup.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Wires a model instance into MobX so its schema-defined fields become
+ * observable and its mutations are tracked. This module reads the property
+ * metadata generated from a schema and applies the matching MobX annotation to
+ * each field, leaving any hand-written getter or setter in place.
+ */
+import { type AnnotationMapEntry } from 'mobx';
+import { type PropertyMetadata, type ReferenceMetadata } from '../types/index.js';
+/**
+ * The subset of a model instance that {@link M1} reads and writes. A model calls
+ * {@link M1} from its constructor, where these members exist on `this`;
+ * declaring them here lets {@link M1} reference them without loose casts. Every
+ * member is optional, so a partial model — such as a test fixture — still
+ * satisfies the type.
+ */
+interface M1Target {
+    _hasCustomObservability?: boolean;
+    _isConstructing?: boolean;
+    _extraMobxAnnotations?: Record<string, AnnotationMapEntry>;
+    setupObservability?(): void;
+    propertyChanged?(name: string, oldValue: unknown, newValue: unknown): void;
+}
+/**
+ * Makes a model instance's schema-defined properties observable with MobX. For
+ * each field it reads the {@link PropertyMetadata} and applies the matching MobX
+ * annotation — a plain observable for stored values, a computed for derived
+ * getters, and an action for mutating methods — while leaving any field that
+ * already declares its own getter and setter untouched. If the model provides
+ * its own `setupObservability` or sets `_hasCustomObservability`, this function
+ * defers to it and does nothing.
+ */
+export declare function M1<T extends M1Target>(target: T, propertyMetadata: Map<string, PropertyMetadata>, referenceMetadata?: Map<string, ReferenceMetadata>): void;
+/**
+ * Wraps a model class so every instance is made observable at construction time
+ * by calling {@link M1}. A class that manages its own observability — one whose
+ * prototype declares `setupObservability` or `_hasCustomObservability` — is
+ * returned unchanged. The wrapper preserves the original class name and its
+ * static members.
+ */
+export declare function makeModelObservable(modelClass: any, propertyMetadata: Map<string, PropertyMetadata>, referenceMetadata?: Map<string, any>): any;
+/**
+ * Reports whether a named property is one that {@link M1} makes observable —
+ * that is, a stored value, an ephemeral value, a reference collection, or a
+ * reference array. Returns `false` for an unknown property and for a computed
+ * reference.
+ */
+export declare function isObservableProperty(target: any, propName: string, propertyMetadata: Map<string, PropertyMetadata>): boolean;
+/**
+ * Returns the names of the properties that {@link M1} treats as computed: the
+ * referenced-model and back-reference fields derived from a foreign key.
+ */
+export declare function getComputedProperties(propertyMetadata: Map<string, PropertyMetadata>): string[];
+export {};

package/dist/utils/{mobx-setup.js → mobxSetup.js}

@@ -1,15 +1,20 @@
 /**
- * M1 Helper - Simplified MobX Setup
- *
- * Fixed version that doesn't conflict with existing getters/setters
+ * Wires a model instance into MobX so its schema-defined fields become
+ * observable and its mutations are tracked. This module reads the property
+ * metadata generated from a schema and applies the matching MobX annotation to
+ * each field, leaving any hand-written getter or setter in place.
  */
 import { observable, makeObservable, action, computed, observe, } from 'mobx';
 import { PropertyType } from '../types/index.js';
 import { getContext } from '../context.js';
 /**
- * M1 - Make properties observable with proper MobX setup
- *
- * Simplified version that respects existing getters/setters
+ * Makes a model instance's schema-defined properties observable with MobX. For
+ * each field it reads the {@link PropertyMetadata} and applies the matching MobX
+ * annotation — a plain observable for stored values, a computed for derived
+ * getters, and an action for mutating methods — while leaving any field that
+ * already declares its own getter and setter untouched. If the model provides
+ * its own `setupObservability` or sets `_hasCustomObservability`, this function
+ * defers to it and does nothing.
  */
 export function M1(target, propertyMetadata, referenceMetadata) {
     // MobX accepts an annotations map keyed by PropertyKey. We build it
@@ -168,27 +173,18 @@ export function M1(target, propertyMetadata, referenceMetadata) {
         // Only apply if we have annotations to apply
         if (Object.keys(annotations).length > 0) {
             makeObservable(target, annotations);
-            // Bridge MobX's observable setter to `propertyChanged()` so the
-            // dynamic-class mutation path sees direct assignments like
-            // `layer.position = newPos` — i.e., the transaction queue gets an
-            // update and the server eventually sees it.
+            // Bridge MobX's observable setter to `propertyChanged()` so a direct
+            // assignment like `layer.position = newPos` still records a change for the
+            // transaction queue, and the update reaches the server. Product code
+            // assigns model properties directly in many places (drag, resize,
+            // formatting, keyboard nudge, AI tools), so those writes must sync.
             //
-            // History: the old hand-coded models wired setters via
-            // `setupSimplePropertyTracking` which overrode MobX's accessors and
-            // broke reactivity — that function was correctly kept off the
-            // schema-driven dynamic-class path. The intended replacement was
-            // "use `store.mutate.slideLayers.update(...)` from callers," but a
-            // large amount of existing product code (drag, resize, formatting,
-            // keyboard nudge, AI tools, etc.) still assigns properties directly,
-            // and making that silently not sync was the regression that broke
-            // all slide-layer edits.
-            //
-            // `observe()` attaches a post-set listener WITHOUT replacing MobX's
-            // accessors — so the observable keeps its normal reactivity and we
-            // get a synchronous change event we can forward to
-            // `propertyChanged()`. We scope it to `PropertyType.property`
-            // (persisted fields) so ephemeral UI state and computed/reference
-            // virtual fields don't leak into `modifiedProperties`.
+            // `observe()` attaches a post-set listener without replacing MobX's
+            // accessors, so the observable keeps its normal reactivity and we get a
+            // synchronous change event to forward to `propertyChanged()`. Only
+            // persisted fields (`PropertyType.property`) are observed, so ephemeral UI
+            // state and computed or reference fields do not leak into
+            // `modifiedProperties`.
             //
             // Construction-time writes (the constructor's initial field
             // population from wire data) also fire `observe` — so we gate with
@@ -199,16 +195,15 @@ export function M1(target, propertyMetadata, referenceMetadata) {
                 for (const [propName, metadata] of propertyMetadata) {
                     if (metadata.type !== PropertyType.property)
                         continue;
-                    // Only `annotations[propName] === observable` entries are
-                    // safe to `observe()`. DON'T gate on
-                    // `Object.getOwnPropertyDescriptor(target, propName).get/set` —
-                    // `makeObservable(target, annotations)` has ALREADY installed
-                    // its own getter/setter by this point, so that descriptor
-                    // check flags every field as "custom" and silently skips
-                    // every observer. That was the root cause of `input: {}` on
-                    // the wire: `modifiedProperties` stayed empty for dynamic
-                    // models, the transaction queue couldn't find any changes to
-                    // send, and the server acked a no-op mutation.
+                    // Only entries annotated as `observable` are safe to `observe()`. Do
+                    // not gate on
+                    // `Object.getOwnPropertyDescriptor(target, propName).get/set`:
+                    // `makeObservable(target, annotations)` has already installed its own
+                    // getter/setter by this point, so that descriptor check flags every
+                    // field as custom and silently skips every observer. That mistake left
+                    // `modifiedProperties` empty for dynamic models, so the transaction
+                    // queue found no changes to send and the server acked a no-op
+                    // mutation.
                     if (!(propName in annotations))
                         continue;
                     // Accept any flavor of `observable` (deep, ref, shallow). `observe()`
@@ -272,66 +267,11 @@ export function M1(target, propertyMetadata, referenceMetadata) {
     }
 }
 /**
- * Setup simple property tracking for change detection
- * Only for properties without existing getters/setters
- */
-function setupSimplePropertyTracking(target, propertyMetadata) {
-    for (const [propName, metadata] of propertyMetadata) {
-        // Only track regular properties
-        if (metadata.type !== PropertyType.property &&
-            metadata.type !== PropertyType.ephemeralProperty) {
-            continue;
-        }
-        // Check if property already has custom getter/setter
-        const descriptor = Object.getOwnPropertyDescriptor(target, propName);
-        if (descriptor && (descriptor.get || descriptor.set)) {
-            // Property already managed, skip
-            continue;
-        }
-        // Check prototype chain
-        let proto = Object.getPrototypeOf(target);
-        let hasCustomAccessor = false;
-        while (proto && proto !== Object.prototype) {
-            const protoDescriptor = Object.getOwnPropertyDescriptor(proto, propName);
-            if (protoDescriptor && (protoDescriptor.get || protoDescriptor.set)) {
-                hasCustomAccessor = true;
-                break;
-            }
-            proto = Object.getPrototypeOf(proto);
-        }
-        if (hasCustomAccessor) {
-            continue;
-        }
-        // Only add tracking if property exists and isn't already tracked
-        if (propName in target) {
-            const currentValue = target[propName];
-            // Store value in a private field
-            const privateField = `_tracked_${propName}`;
-            target[privateField] = currentValue;
-            // Create simple getter/setter for tracking
-            Object.defineProperty(target, propName, {
-                get() {
-                    return this[privateField];
-                },
-                set(newValue) {
-                    const oldValue = this[privateField];
-                    if (oldValue !== newValue) {
-                        this[privateField] = newValue;
-                        // Only track changes for non-ephemeral properties
-                        if (metadata.type === PropertyType.property && this.propertyChanged) {
-                            this.propertyChanged(propName, oldValue, newValue);
-                        }
-                    }
-                },
-                enumerable: true,
-                configurable: true,
-            });
-        }
-    }
-}
-/**
- * Helper to make a class observable
- * For classes that don't have custom observability
+ * Wraps a model class so every instance is made observable at construction time
+ * by calling {@link M1}. A class that manages its own observability — one whose
+ * prototype declares `setupObservability` or `_hasCustomObservability` — is
+ * returned unchanged. The wrapper preserves the original class name and its
+ * static members.
  */
 export function makeModelObservable(modelClass, propertyMetadata, referenceMetadata) {
     // Check if class already handles observability
@@ -355,7 +295,10 @@ export function makeModelObservable(modelClass, propertyMetadata, referenceMetad
     return WrappedClass;
 }
 /**
- * Utility to check if a property is observable
+ * Reports whether a named property is one that {@link M1} makes observable —
+ * that is, a stored value, an ephemeral value, a reference collection, or a
+ * reference array. Returns `false` for an unknown property and for a computed
+ * reference.
  */
 export function isObservableProperty(target, propName, propertyMetadata) {
     const metadata = propertyMetadata.get(propName);
@@ -369,7 +312,8 @@ export function isObservableProperty(target, propName, propertyMetadata) {
     ].includes(metadata.type);
 }
 /**
- * Utility to get computed properties
+ * Returns the names of the properties that {@link M1} treats as computed: the
+ * referenced-model and back-reference fields derived from a foreign key.
  */
 export function getComputedProperties(propertyMetadata) {
     const computed = [];

package/dist/webhooks/events.d.ts

@@ -1,38 +1,43 @@
 /**
- * A Stripe-style webhook event delivered to the customer's endpoint. Verified
- * (via the Standard Webhooks library) before the customer reads it.
+ * A webhook event delivered to a customer's endpoint, representing a single
+ * committed change to a row. {@link deltaToWebhookEvent} produces it, and the
+ * recipient verifies the delivery signature before trusting its contents.
  */
 export interface AbloWebhookEvent {
-    /** Stable event id = `String(syncId)`. Dedupe by this (idempotency). */
+    /** A stable, unique event identifier equal to `String(syncId)`. Use it to
+     *  deduplicate deliveries. */
     readonly id: string;
-    /** `<model>.<verb>`, e.g. `"slide.updated"` — switch on this. */
+    /** The event type, formatted as `<model>.<verb>`, such as `"slide.updated"`.
+     *  Branch on this to route the event. */
     readonly type: string;
-    /** Wire model name, e.g. `"Slide"`. */
+    /** The name of the model whose row changed, such as `"Slide"`. */
     readonly model: string;
-    /** The changed row's id. */
+    /** The identifier of the row that changed. */
     readonly objectId: string;
-    /** Monotonic transaction-log position. ORDER by this (and dedupe). */
+    /** The change's position in the transaction log, increasing monotonically.
+     *  Order events by this value. */
     readonly syncId: number;
-    /** The post-change row (the object), or `null` on a delete. Like Stripe's
-     *  `event.data.object`. */
+    /** The row as it stands after the change, or `null` when the change was a
+     *  delete. */
     readonly data: Record<string, unknown> | null;
-    /** ISO timestamp the change was committed. */
+    /** The time the change was committed, as an ISO 8601 timestamp. */
     readonly createdAt: string;
 }
-/** The minimal delta shape the mapping reads (a `ServerSyncDelta` satisfies it). */
+/** The minimal delta shape {@link deltaToWebhookEvent} reads; a full server-side
+ *  delta record satisfies it. */
 export interface WebhookSourceDelta {
     readonly id: number;
     readonly actionType: string;
     readonly modelName: string;
     readonly modelId: string;
-    /** `jsonb` — parsed object, raw JSON string, or null. */
+    /** The row payload: an already-parsed object, a raw JSON string, or `null`. */
     readonly data: Record<string, unknown> | string | null;
     readonly createdAt: string;
 }
 /**
- * Map a committed delta to a customer-facing webhook event. Returns `null` for
- * internal sync deltas (permission/group changes) that aren't customer events —
- * the caller skips those (no webhook emitted). Pure: the `syncId` and timestamp
- * come from the delta, so the mapping is deterministic.
+ * Converts a committed delta into an {@link AbloWebhookEvent}. Returns `null`
+ * when the delta records an internal permission or group change rather than a
+ * row-level change, in which case the caller emits no webhook. The mapping is
+ * deterministic: the event id and timestamp come directly from the delta.
  */
 export declare function deltaToWebhookEvent(delta: WebhookSourceDelta): AbloWebhookEvent | null;

package/dist/webhooks/events.js

@@ -1,7 +1,9 @@
 /**
- * The customer-facing verb per delta action. Only the CRUD-ish actions become
- * webhook events; `C`overing / `G`roupAdded / `S`groupRemoved are internal sync
- * mechanics (permission/visibility), NOT customer events → no webhook.
+ * Maps each delta action code to the verb that appears in an event type. Only
+ * the row-level create, update, delete, archive, and unarchive actions produce a
+ * webhook. The remaining action codes describe internal permission and
+ * visibility changes and are deliberately absent, so {@link deltaToWebhookEvent}
+ * returns `null` for them.
  */
 const ACTION_VERB = {
     I: 'created',
@@ -19,15 +21,15 @@ function parseRow(data) {
     return data;
 }
 /**
- * Map a committed delta to a customer-facing webhook event. Returns `null` for
- * internal sync deltas (permission/group changes) that aren't customer events —
- * the caller skips those (no webhook emitted). Pure: the `syncId` and timestamp
- * come from the delta, so the mapping is deterministic.
+ * Converts a committed delta into an {@link AbloWebhookEvent}. Returns `null`
+ * when the delta records an internal permission or group change rather than a
+ * row-level change, in which case the caller emits no webhook. The mapping is
+ * deterministic: the event id and timestamp come directly from the delta.
  */
 export function deltaToWebhookEvent(delta) {
     const verb = ACTION_VERB[delta.actionType];
     if (!verb)
-        return null; // C / G / S — internal sync mechanics, not a customer event
+        return null; // an internal permission or group change, not a customer event
     return {
         id: String(delta.id),
         type: `${delta.modelName.toLowerCase()}.${verb}`,

package/dist/webhooks/index.d.ts

@@ -1,10 +1,8 @@
 /**
- * `@abloatai/ablo/webhooks` — the webhook event catalog + delta mapping.
- *
- * Customers import {@link AbloWebhookEvent} to type their handler; the server
- * uses {@link deltaToWebhookEvent} to turn transaction-log deltas into events
- * for Svix to deliver. Signature verification is NOT here — the customer uses
- * the open Standard Webhooks library (`svix` / `standardwebhooks`), so Ablo
- * ships no crypto.
+ * The public entry point for webhooks. Import {@link AbloWebhookEvent} to type
+ * your event handler, and use {@link deltaToWebhookEvent} to turn a committed
+ * change from the transaction log into an event to deliver. This module does not
+ * verify signatures and ships no cryptography; recipients verify deliveries with
+ * a standard webhooks library.
  */
 export { deltaToWebhookEvent, type AbloWebhookEvent, type WebhookSourceDelta, } from './events.js';