@abloatai/ablo 0.7.0 → 0.9.0

package/dist/sync/SyncWebSocket.js

@@ -10,7 +10,8 @@
 import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
 import { flushOfflineQueueOnce } from './OfflineFlush.js';
-import { AbloClaimedError, CapabilityError, SyncSessionError, } from '../errors.js';
+import { AbloConnectionError, AbloError, CapabilityError, SyncSessionError, errorFromWire, toAbloError, } from '../errors.js';
+import { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from '../auth/credentialSource.js';
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
 // Consumers pass their own event types as TCollaboration generic parameter.
@@ -170,16 +171,10 @@ export class SyncWebSocket extends EventEmitter {
         }
         this.isConnecting = true;
         this.isManualClose = false;
-        // Pattern: one credential, server-resolved identity. The WS URL
-        // carries the credential (cap-token bearer in `?authorization=`
-        // for the cap path; session cookie in headers for the cookie
-        // path). The server's AuthProvider chain (`apiKeyProvider →
-        // agentTokenProvider → betterAuthProvider`) resolves identity
-        // from the verified credential — userId/organizationId are
-        // NEVER read from URL params in production. See
-        // `apps/sync-server/src/auth/provider.ts:148` (betterAuthProvider
-        // calls `auth.api.getSession({headers})`) and `agentTokenProvider`
-        // for the cap-token path.
+        // Pattern: one credential, server-resolved identity. The bearer travels
+        // in a `Sec-WebSocket-Protocol` value (built below), NOT the URL. The
+        // server is bearer-only (`apiKeyProvider`) and resolves identity from the
+        // verified token — userId/organizationId are NEVER read from URL params.
         const params = new URLSearchParams({
             // Intentionally omit lastSyncId, versions, capabilities from URL; these are sent in sync_request
             // and ack messages to avoid stale baselines on reconnect.
@@ -191,22 +186,28 @@ export class SyncWebSocket extends EventEmitter {
         if (this.options.kind && this.options.kind !== 'user') {
             params.set('kind', this.options.kind);
         }
-        // Capability bearer (query-param form so it works in both Node's
-        // global WebSocket — which can't set headers — and browsers).
-        if (this.options.capabilityToken) {
-            params.set('authorization', `Bearer ${this.options.capabilityToken}`);
-        }
         // Add sync groups if provided
         this.options.syncGroups.forEach((group) => {
             params.append('syncGroups', group);
         });
         const wsUrl = `${this.options.url}?${params.toString()}`;
+        // Carry the bearer in a `Sec-WebSocket-Protocol` value, NOT the URL. A
+        // browser can't set an Authorization header on a WS, but it CAN offer
+        // subprotocols — and unlike the query string, those don't land in ALB
+        // access logs, proxies, or browser history. The server reads
+        // `ablo.bearer.<token>` and selects the real `ablo.sync.v1` protocol,
+        // never echoing the token-bearing value back. (Token is the raw ek_/rk_,
+        // which is subprotocol-token-safe — alphanumerics + `_`.)
+        const authToken = this.resolveAuthToken();
+        const protocols = authToken
+            ? [`${WS_BEARER_SUBPROTOCOL_PREFIX}${authToken}`, WS_SYNC_SUBPROTOCOL]
+            : [WS_SYNC_SUBPROTOCOL];
         try {
             // Reset the handshake flag before wiring the new socket. Each connect()
             // gets its own lifecycle — a prior successful open on a previous socket
             // must not mask a handshake failure on the new one.
             this._everOpened = false;
-            this.ws = new WebSocket(wsUrl);
+            this.ws = new WebSocket(wsUrl, protocols);
             this.setupEventHandlers();
         }
         catch (error) {
@@ -214,7 +215,7 @@ export class SyncWebSocket extends EventEmitter {
             const errorMessage = error instanceof Error ? error.message : 'Failed to create WebSocket';
             getContext().observability.captureWebSocketError({ context: 'create-websocket', error: errorMessage });
             this.isConnecting = false;
-            this.emit('error', new Error(errorMessage));
+            this.emit('error', new AbloConnectionError(errorMessage, { cause: error }));
             this.scheduleReconnect();
         }
     }
@@ -303,11 +304,10 @@ export class SyncWebSocket extends EventEmitter {
                         this.handlePresenceUpdate(message);
                         break;
                     case 'mutation_result': {
-                        // Ack for a prior `commit` we sent. Wire format (mirrors
-                        // apps/sync-server/src/hub/types.ts MutationResultMessage):
-                        //   { type: 'mutation_result',
-                        //     payload: { clientTxId, serverTxId, success,
-                        //                lastSyncId?, error? } }
+                        // Ack for a prior `commit` we sent. Canonical shape is
+                        // `MutationResultMessage` in `@abloatai/ablo/wire`. This stays a
+                        // DEFENSIVE parse (not a typed cast) because the payload is
+                        // untrusted wire data that may be malformed or from an older server.
                         const p = message.payload ?? message;
                         const { clientTxId, success, lastSyncId, error } = p ?? {};
                         const pending = typeof clientTxId === 'string'
@@ -360,38 +360,19 @@ export class SyncWebSocket extends EventEmitter {
                             else {
                                 errorMessage = 'mutation failed on server';
                             }
-                            // Capability denials route through the typed CapabilityError
-                            // so callers can `instanceof CapabilityError` and read
-                            // `.requiredCapability` to attenuate-and-retry without
-                            // string-matching the error code.
-                            if (errorCode === 'capability_scope_denied' ||
-                                errorCode === 'capability_invalid') {
-                                pending.reject(new CapabilityError(errorCode, errorMessage, requiredCapability));
-                            }
-                            else if (errorCode === 'intent_conflict' ||
-                                errorCode === 'claim_conflict' ||
-                                errorCode === 'entity_claimed') {
-                                // Claim enforcement: another participant holds a live claim on
-                                // a targeted entity. Two server layers reject this — the Hub's
-                                // pre-commit lease check (`intent_conflict`, the code that
-                                // reaches clients in practice) and `executeCommit`'s deeper
-                                // guard (`entity_claimed`). Both mean "claimed", so both route
-                                // through the typed AbloClaimedError, letting callers
-                                // `instanceof AbloClaimedError` (or read `e.type` across worker
-                                // boundaries) and wait/bypass — symmetric with the
-                                // CapabilityError branch above, and with the HTTP commit path
-                                // (`translateHttpError`).
-                                pending.reject(new AbloClaimedError(errorMessage, {
-                                    code: errorCode === 'intent_conflict' ? 'claim_conflict' : errorCode,
-                                    httpStatus: 409,
-                                }));
-                            }
-                            else {
-                                const rejection = new Error(errorMessage);
-                                if (errorCode)
-                                    rejection.code = errorCode;
-                                pending.reject(rejection);
-                            }
+                            // Build the proper typed AbloError from the wire code via the
+                            // shared factory — the same code→class mapping the HTTP commit
+                            // path uses (`translateHttpError`). This keeps rejected commits
+                            // inside the typed hierarchy (capability denials →
+                            // CapabilityError with `.requiredCapability`; foreign-claim
+                            // conflicts → AbloClaimedError; everything else → the subclass
+                            // its registry `httpStatus` implies) instead of a hand-rolled
+                            // `new Error`, so callers can `instanceof`/`e.type` it and
+                            // downstream retry logic can read the contract's retryability.
+                            pending.reject(errorFromWire(errorMessage, {
+                                code: errorCode,
+                                requiredCapability,
+                            }));
                         }
                         break;
                     }
@@ -438,11 +419,10 @@ export class SyncWebSocket extends EventEmitter {
                                 pending.reject(new CapabilityError(code, msg, requiredCapability));
                             }
                             else {
-                                // Attach `code` as a property on the rejection so callers
-                                // can discriminate (`scope_conflict`, `malformed_claim`,
-                                // ...) without parsing the message.
-                                const rejection = Object.assign(new Error(`${code}: ${msg}`), { code });
-                                pending.reject(rejection);
+                                // Route through the shared factory so a failed claim_ack is a
+                                // typed AbloError (registry code → right subclass), symmetric
+                                // with the commit `mutation_result` path — never a bare Error.
+                                pending.reject(errorFromWire(msg, { code }));
                             }
                         }
                         break;
@@ -539,12 +519,12 @@ export class SyncWebSocket extends EventEmitter {
             // Check if we're offline first
             if (!getContext().onlineStatus.isOnline()) {
                 getContext().observability.breadcrumb('WebSocket error: Network is offline', 'sync.websocket', 'warning');
-                this.emit('error', new Error('Network is offline'));
+                this.emit('error', new AbloConnectionError('Network is offline', { code: 'bootstrap_offline' }));
                 return;
             }
             // After session error, suppress Sentry capture — the root cause is already reported.
             // Still emit so SyncedStore can update UI state.
-            const error = new Error(`WebSocket connection failed`);
+            const error = new AbloConnectionError(`WebSocket connection failed`);
             if (!this._sessionErrorDetected) {
                 getContext().observability.captureWebSocketError({
                     context: 'connection-error',
@@ -578,12 +558,16 @@ export class SyncWebSocket extends EventEmitter {
             if (this.pendingMutations.size > 0) {
                 for (const pending of this.pendingMutations.values()) {
                     clearTimeout(pending.timeout);
-                    pending.reject(Object.assign(new Error(`WebSocket closed while commit was in flight (code=${event.code}` +
+                    // AbloConnectionError → `isPermanentError` treats it as transient,
+                    // so TransactionQueue retries the commit on reconnect rather than
+                    // rolling it back. `diagnostics` is preserved as a property (the
+                    // queue's failure log walks the cause chain for it).
+                    pending.reject(Object.assign(new AbloConnectionError(`WebSocket closed while commit was in flight (code=${event.code}` +
                         (event.reason ? ` reason=${event.reason}` : '') +
                         (this.lastForceCloseReason
                             ? ` forceCloseReason=${this.lastForceCloseReason}`
                             : '') +
-                        ')'), { diagnostics: this.getConnectionDiagnostics() }));
+                        ')', { code: 'commit_no_result' }), { diagnostics: this.getConnectionDiagnostics() }));
                 }
                 this.pendingMutations.clear();
             }
@@ -594,7 +578,7 @@ export class SyncWebSocket extends EventEmitter {
             if (this.pendingClaims.size > 0) {
                 for (const pending of this.pendingClaims.values()) {
                     clearTimeout(pending.timeout);
-                    pending.reject(new Error(`WebSocket closed while claim was in flight (code=${event.code})`));
+                    pending.reject(new AbloConnectionError(`WebSocket closed while claim was in flight (code=${event.code})`));
                 }
                 this.pendingClaims.clear();
             }
@@ -736,6 +720,32 @@ export class SyncWebSocket extends EventEmitter {
             }
         }
     }
+    /**
+     * Project the SDK's `MutationOperation[]` onto the canonical wire
+     * `CommitMessage`. This is the single serialize boundary between the SDK op
+     * type (loose `type: string`, plus an SDK-internal `options` the server never
+     * reads) and the strict wire contract. The per-field map gives compile-time
+     * drift detection (a `CommitOperation` shape change breaks here) and the lone
+     * `as` narrows the validated op `type` to the wire union — the only
+     * loosening, localized to this boundary.
+     */
+    buildCommitFrame(operations, clientTxId, causedByTaskId) {
+        const payload = {
+            operations: operations.map((op) => ({
+                type: op.type,
+                model: op.model,
+                id: op.id,
+                input: op.input,
+                transactionId: op.transactionId,
+                readAt: op.readAt,
+                onStale: op.onStale,
+            })),
+            clientTxId,
+        };
+        if (causedByTaskId)
+            payload.causedByTaskId = causedByTaskId;
+        return { type: 'commit', payload };
+    }
     /**
      * Send a `commit` mutation request over the existing WebSocket and
      * resolve when the server's `mutation_result` frame comes back with
@@ -762,7 +772,7 @@ export class SyncWebSocket extends EventEmitter {
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
                 this.pendingMutations.delete(clientTxId);
-                reject(new Error(`commit timed out after ${timeoutMs}ms (clientTxId=${clientTxId})`));
+                reject(new AbloConnectionError(`commit timed out after ${timeoutMs}ms (clientTxId=${clientTxId})`, { code: 'commit_no_result' }));
             }, timeoutMs);
             this.pendingMutations.set(clientTxId, { resolve, reject, timeout });
             try {
@@ -770,17 +780,13 @@ export class SyncWebSocket extends EventEmitter {
                 // an open turn — keeps the wire shape stable for sessions
                 // that don't use turns. Servers that don't know the field
                 // ignore it; newer servers stamp it onto every delta.
-                const payload = { operations, clientTxId };
-                if (causedByTaskId)
-                    payload.causedByTaskId = causedByTaskId;
-                this.ws.send(JSON.stringify({ type: 'commit', payload }));
+                const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId);
+                this.ws.send(JSON.stringify(frame));
             }
             catch (error) {
                 clearTimeout(timeout);
                 this.pendingMutations.delete(clientTxId);
-                reject(error instanceof Error
-                    ? error
-                    : new Error(String(error)));
+                reject(toAbloError(error));
             }
         });
     }
@@ -796,10 +802,8 @@ export class SyncWebSocket extends EventEmitter {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             throw this.notConnectedError('commit');
         }
-        const payload = { operations, clientTxId };
-        if (causedByTaskId)
-            payload.causedByTaskId = causedByTaskId;
-        this.ws.send(JSON.stringify({ type: 'commit', payload }));
+        const frame = this.buildCommitFrame(operations, clientTxId, causedByTaskId);
+        this.ws.send(JSON.stringify(frame));
     }
     /**
      * Activate a participant claim on this connection. Multiplexed
@@ -826,7 +830,9 @@ export class SyncWebSocket extends EventEmitter {
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
                 this.pendingClaims.delete(claimId);
-                reject(new Error(`claim timed out after ${timeoutMs}ms (claimId=${claimId})`));
+                reject(new AbloConnectionError(`claim timed out after ${timeoutMs}ms (claimId=${claimId})`, {
+                    code: 'wait_for_timeout',
+                }));
             }, timeoutMs);
             this.pendingClaims.set(claimId, { resolve, reject, timeout });
             try {
@@ -843,7 +849,7 @@ export class SyncWebSocket extends EventEmitter {
             catch (error) {
                 clearTimeout(timeout);
                 this.pendingClaims.delete(claimId);
-                reject(error instanceof Error ? error : new Error(String(error)));
+                reject(toAbloError(error));
             }
         });
     }
@@ -864,7 +870,10 @@ export class SyncWebSocket extends EventEmitter {
         if (pending) {
             clearTimeout(pending.timeout);
             this.pendingClaims.delete(claimId);
-            pending.reject(new Error(`claim ${claimId} released before ack`));
+            pending.reject(new AbloError(`claim ${claimId} released before ack`, {
+                code: 'intent_wait_aborted',
+                httpStatus: 409,
+            }));
         }
         if (this.ws?.readyState !== WebSocket.OPEN)
             return;
@@ -876,17 +885,29 @@ export class SyncWebSocket extends EventEmitter {
         }
     }
     /**
-     * Replace the capability token used for authentication. The new
-     * value is read by the next URL-build (i.e., next connect / reconnect
-     * cycle). The currently-open WS is NOT torn down — servers keep
-     * connections alive past cap expiry until they decide to close, and
-     * a forced reconnect would interrupt in-flight deltas. The cap-mint
-     * scheduler in `Ablo.ts` calls this on each successful refresh so
-     * reconnects after server-initiated close pick up the fresh token.
+     * Compatibility setter for direct SyncWebSocket users. The SDK-owned
+     * `Ablo()` path passes `getAuthToken`, so reconnect URL auth reads the
+     * shared credential source instead of this copied value.
      */
     setCapabilityToken(token) {
         this.options.capabilityToken = token;
     }
+    getAuthToken() {
+        return this.resolveAuthToken();
+    }
+    /**
+     * Return the credential that will be used by the next WebSocket upgrade.
+     * ConnectionManager reads this for HTTP auth probes so visibility/network
+     * checks authenticate the same way reconnects do.
+     */
+    getCapabilityToken() {
+        return this.resolveAuthToken();
+    }
+    resolveAuthToken = () => {
+        return this.options.getAuthToken?.()
+            ?? this.options.getCapabilityToken?.()
+            ?? this.options.capabilityToken;
+    };
     /**
      * Send spreadsheet selection presence
      */
@@ -1172,8 +1193,11 @@ export class SyncWebSocket extends EventEmitter {
         else {
             detail = 'never_connected';
         }
-        const err = new Error(`SyncWebSocket not connected — cannot send ${action} (${detail})`);
-        err.diagnostics = d;
+        // Typed so it lands in the AbloError hierarchy AND `isPermanentError`
+        // sees a transient transport failure (retry on reconnect, don't roll
+        // back). `diagnostics` stays a property — the queue's failure log walks
+        // the cause chain for it.
+        const err = Object.assign(new AbloConnectionError(`SyncWebSocket not connected — cannot send ${action} (${detail})`, { code: 'ws_not_ready' }), { diagnostics: d });
         return err;
     }
     /** Returns the sync groups this connection is subscribed to. */

package/dist/sync/createIntentStream.js

@@ -93,6 +93,9 @@ export function createIntentStream(config, transport = null) {
                 // `settled()`. Absent status means active (wire back-compat).
                 if (claim.status && claim.status !== 'active')
                     continue;
+                const description = typeof claim.meta?.description === 'string'
+                    ? claim.meta.description
+                    : undefined;
                 activeByIntentId.set(claim.intentId, {
                     id: claim.intentId,
                     heldBy: event.userId,
@@ -106,6 +109,7 @@ export function createIntentStream(config, transport = null) {
                         meta: claim.meta,
                     },
                     reason: claim.action,
+                    ...(description ? { description } : {}),
                     ttlSeconds: Math.max(0, Math.floor((claim.expiresAt - Date.now()) / 1000)),
                     announcedAt: new Date(claim.declaredAt).toISOString(),
                     expiresAt: new Date(claim.expiresAt).toISOString(),
@@ -227,6 +231,11 @@ export function createIntentStream(config, transport = null) {
             },
         });
     }
+    function withDescription(meta, description) {
+        if (!description)
+            return meta;
+        return { ...(meta ?? {}), description };
+    }
     function mintHandle(args) {
         const intentId = crypto.randomUUID();
         const estimatedMs = args.ttl !== undefined ? toMs(args.ttl) : undefined;
@@ -273,7 +282,7 @@ export function createIntentStream(config, transport = null) {
                 path: resolved.path,
                 range: resolved.range,
                 field: resolved.field,
-                meta: resolved.meta,
+                meta: withDescription(resolved.meta, opts?.description),
                 action: opts?.reason ?? 'editing',
                 ttl: opts?.ttl,
                 queue: opts?.queue,

package/dist/sync/participants.js

@@ -1,4 +1,5 @@
 import { scopeKindOf } from '../schema/model.js';
+import { AbloConnectionError, AbloValidationError } from '../errors.js';
 export function createParticipantManager(config) {
     return {
         async join(input, overrides) {
@@ -10,7 +11,7 @@ export function createParticipantManager(config) {
             await config.ready();
             const transport = config.getTransport();
             if (!transport) {
-                throw new Error('Ablo participant join failed: WebSocket is not connected');
+                throw new AbloConnectionError('Ablo participant join failed: WebSocket is not connected', { code: 'ws_not_ready' });
             }
             const claimId = createParticipantClaimId();
             if (syncGroups.length > 0) {
@@ -154,7 +155,9 @@ function createJoinedParticipant(args) {
     const requireTarget = (target) => {
         const resolved = target ? targetToEntityRef(target) : currentTarget;
         if (!resolved) {
-            throw new Error('Participant action requires a structured target');
+            throw new AbloValidationError('Participant action requires a structured target', {
+                code: 'invalid_request',
+            });
         }
         return resolved;
     };

package/dist/transactions/TransactionQueue.js

@@ -12,7 +12,7 @@ import { getContext } from '../context.js';
 import { getActiveRegistry } from '../ModelRegistry.js';
 import { MutationOperationType } from '../types/index.js';
 import { handleMutationError } from './mutation-error-handler.js';
-import { AbloError, AbloConnectionError } from '../errors.js';
+import { AbloError, AbloConnectionError, errorCodeSpec } from '../errors.js';
 /**
  * Framework-internal keys added by `Model.toJSON()` that must never
  * reach the wire. The server treats each top-level key as a target
@@ -1482,6 +1482,18 @@ export class TransactionQueue extends EventEmitter {
         if (error instanceof AbloConnectionError) {
             return false;
         }
+        // Registry-driven retryability is authoritative when the error carries a
+        // known wire code: the error contract (errorCodes.ts) decides whether the
+        // same request can succeed on retry, not message string-matching. This is
+        // why rejected commits must arrive as typed AbloErrors (see
+        // `errorFromWire`) — a bare `Error` has no code and falls through to the
+        // heuristics below. Unknown / forward-compat codes (`errorCodeSpec`
+        // returns undefined) also fall through, preserving the safe default.
+        if (error instanceof AbloError && error.code) {
+            const spec = errorCodeSpec(error.code);
+            if (spec)
+                return !spec.retryable;
+        }
         const message = error?.message?.toLowerCase() || '';
         // Network/connection errors are transient - retry these
         const isNetworkError = message.includes('failed to fetch') ||

package/dist/types/streams.d.ts

@@ -340,6 +340,12 @@ export interface ClaimOptions extends IntentOptions {
      * app-specific phases.
      */
     readonly reason?: string;
+    /**
+     * Peer-visible explanation of the exact work being performed. This is more
+     * specific than `reason`: `reason` is the phase (`'renaming'`), while
+     * `description` is the instruction other agents should see.
+     */
+    readonly description?: string;
     /**
      * Join the server's fair FIFO queue on contention instead of being
      * rejected. The grant arrives asynchronously (`intent_acquired` if the
@@ -528,6 +534,7 @@ export interface ActiveIntent extends IntentDeclaration {
      * from "user editing X" without string-parsing `heldBy`.
      */
     readonly participantKind: 'human' | 'agent';
+    readonly description?: string;
     readonly announcedAt: string;
     readonly expiresAt: string;
 }
@@ -565,6 +572,8 @@ export interface Intent {
     readonly target: EntityRef;
     /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. */
     readonly action: string;
+    /** Peer-visible explanation of the work being performed. */
+    readonly description?: string;
     /** Participant holding it. */
     readonly heldBy: string;
     readonly participantKind: 'human' | 'agent';

package/dist/utils/mobx-setup.js

@@ -146,6 +146,7 @@ export function M1(target, propertyMetadata, referenceMetadata) {
         'markAsPersisted',
         'clearChanges',
         'updateFromData',
+        'applyChanges',
     ];
     for (const methodName of actionMethods) {
         if (typeof Reflect.get(target, methodName) === 'function') {

package/dist/webhooks/events.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A Stripe-style webhook event delivered to the customer's endpoint. Verified
+ * (via the Standard Webhooks library) before the customer reads it.
+ */
+export interface AbloWebhookEvent {
+    /** Stable event id = `String(syncId)`. Dedupe by this (idempotency). */
+    readonly id: string;
+    /** `<model>.<verb>`, e.g. `"slide.updated"` — switch on this. */
+    readonly type: string;
+    /** Wire model name, e.g. `"Slide"`. */
+    readonly model: string;
+    /** The changed row's id. */
+    readonly objectId: string;
+    /** Monotonic transaction-log position. ORDER by this (and dedupe). */
+    readonly syncId: number;
+    /** The post-change row (the object), or `null` on a delete. Like Stripe's
+     *  `event.data.object`. */
+    readonly data: Record<string, unknown> | null;
+    /** ISO timestamp the change was committed. */
+    readonly createdAt: string;
+}
+/** The minimal delta shape the mapping reads (a `ServerSyncDelta` 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. */
+    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.
+ */
+export declare function deltaToWebhookEvent(delta: WebhookSourceDelta): AbloWebhookEvent | null;

package/dist/webhooks/events.js

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+const ACTION_VERB = {
+    I: 'created',
+    U: 'updated',
+    D: 'deleted',
+    A: 'archived',
+    V: 'unarchived',
+};
+function parseRow(data) {
+    if (data == null)
+        return null;
+    if (typeof data === 'string') {
+        return data === '' ? null : JSON.parse(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.
+ */
+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 {
+        id: String(delta.id),
+        type: `${delta.modelName.toLowerCase()}.${verb}`,
+        model: delta.modelName,
+        objectId: delta.modelId,
+        syncId: delta.id,
+        data: parseRow(delta.data),
+        createdAt: delta.createdAt,
+    };
+}

package/dist/webhooks/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@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.
+ */
+export { deltaToWebhookEvent, type AbloWebhookEvent, type WebhookSourceDelta, } from './events.js';

package/dist/webhooks/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@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.
+ */
+export { deltaToWebhookEvent, } from './events.js';

package/dist/wire/errorEnvelope.d.ts

@@ -0,0 +1,34 @@
+/** The canonical wire envelope — Stripe's error-object shape. Every HTTP error
+ *  response and every structured frame error carries this exact set of keys,
+ *  regardless of which route or transport produced it. */
+export interface ErrorEnvelope {
+    readonly type: string;
+    readonly code?: string;
+    readonly param?: string;
+    readonly message: string;
+    readonly doc_url?: string;
+    readonly request_id?: string;
+}
+/** {@link AbloError} subclass → default HTTP status. The subclass is chosen to
+ *  match status semantics (a validation error is a 400, a permission error a
+ *  403), so a throw site only picks the right class + code and the status
+ *  follows — an explicit `httpStatus` is passed only when it diverges (e.g. a
+ *  404 on the base class, a 503 on AbloServerError). Mirrors the same table in
+ *  apps/sync-server's self-contained `errors.ts`. */
+export declare function statusForType(type: string): number;
+/**
+ * Convert ANY thrown value into the canonical {@link ErrorEnvelope} plus an
+ * HTTP status. A typed {@link AbloError} is serialized via its own `toJSON`
+ * (so `code`/`param`/`doc_url`/structured `details` survive) and gets its
+ * status from an explicit `httpStatus` or, failing that, {@link statusForType}.
+ * Anything else degrades to a 500 `internal_error` envelope — never a bare
+ * framework "Internal Server Error" text body, and never a raw error string
+ * leaked onto the wire as an unregistered code.
+ *
+ * `requestId` is stamped into the body when the error didn't already carry one,
+ * so the response and the `x-request-id` header agree for support correlation.
+ */
+export declare function errorEnvelope(err: unknown, requestId?: string): {
+    body: ErrorEnvelope;
+    status: number;
+};