@abloatai/ablo 0.26.0 → 0.27.0

package/dist/source/pushQueue.js

@@ -1,32 +1,35 @@
 /**
- * Customer-side push retry queue.
+ * A durable retry queue for delivering source events to the server.
  *
- * The push path (`POST /api/source/events` on Ablo Cloud) acks
- * synchronously. If the customer's app crashes mid-call, the network
- * drops, or Ablo returns 5xx, those events would otherwise be lost
- * — the poll path is the durability backstop, but it's higher
- * latency.
+ * When your application changes a row, it can push the resulting event to
+ * the server, which acknowledges delivery synchronously. If your process
+ * crashes mid-call, the network drops, or the server returns a 5xx, that
+ * event would be lost without a safety net. This queue is the safety net:
+ * it persists each event first, then delivers it from a background worker
+ * with automatic retries. (Polling the change feed is the slower fallback
+ * for anything the queue never manages to deliver.)
  *
- * `PushQueue` lives in the customer's process and gives them a
- * queue+worker pattern matching Stripe / Svix semantics:
+ * The queue follows a familiar enqueue-and-worker shape:
  *
- *   - `enqueue(events)` returns immediately after persisting
- *   - background worker delivers and retries per the Standard
- *     Webhooks schedule (0, 5s, 5m, 30m, 2h, 5h, 10h, 14h, 20h, 24h
- *     — ~3 days total)
- *   - exhausted items move to DLQ for customer-owned monitoring
+ *   - `enqueue(events)` returns as soon as the events are persisted.
+ *   - A background worker delivers them and retries on failure, following
+ *     the Standard Webhooks schedule (0, 5s, 5m, 30m, 2h, 5h, 10h, 14h,
+ *     20h, 24h — roughly three days in total).
+ *   - Items that exhaust every retry move to a dead-letter queue you can
+ *     monitor.
  *
- * Persistence is pluggable — `InMemoryPushQueueStorage` for single-
- * process customers, a SQL implementation against the customer's own
- * outbox table for production.
+ * Persistence is pluggable through {@link PushQueueStorage}. Use
+ * {@link InMemoryPushQueueStorage} for a single process, or implement that
+ * interface against your own outbox table for production durability.
  */
 import { ABLO_SOURCE_HEADERS, signAbloSourceRequest } from './signing.js';
 /**
- * Standard Webhooks retry schedule. Index = attempt number; value =
- * delay-ms after the previous attempt. After the last entry, items
- * move to DLQ.
+ * The default retry schedule, taken from the Standard Webhooks
+ * specification. The index is the attempt number and the value is the delay
+ * in milliseconds after the previous attempt failed. Once an item runs off
+ * the end of this array, it moves to the dead-letter queue.
  *
- * Source: https://www.standardwebhooks.com/
+ * See https://www.standardwebhooks.com/.
  */
 export const STANDARD_WEBHOOKS_RETRY_SCHEDULE = [
     0, // immediate
@@ -40,6 +43,7 @@ export const STANDARD_WEBHOOKS_RETRY_SCHEDULE = [
     20 * 60 * 60_000, // 20h
     24 * 60 * 60_000, // 24h
 ];
+/** Create a {@link PushQueue} from the given {@link PushQueueOptions}. */
 export function createPushQueue(options) {
     const tickIntervalMs = options.tickIntervalMs ?? 1000;
     const batchSize = options.batchSize ?? 50;
@@ -133,8 +137,8 @@ export function createPushQueue(options) {
     }
     async function reschedule(item, error) {
         const nextAttempt = item.attempts + 1;
-        // Off the end of the backoff schedule (same check as the old
-        // `nextAttempt >= schedule.length`) — dead-letter the item.
+        // Past the end of the backoff schedule: no attempts left, so dead-letter
+        // the item.
         const backoff = schedule[nextAttempt];
         if (backoff === undefined) {
             await options.storage.markDlq(item.id, error);
@@ -145,13 +149,13 @@ export function createPushQueue(options) {
         await options.storage.reschedule(item.id, now() + delay, error);
     }
 }
+/**
+ * A {@link PushQueueStorage} that keeps items in memory. It is not durable —
+ * items are lost when the process restarts — so it suits development and
+ * low-volume use. For production, implement {@link PushQueueStorage} against
+ * your own table.
+ */
 export class InMemoryPushQueueStorage {
-    /**
-     * Real implementation, not a mock. Suitable for low-volume single-
-     * process customers; not durable across restarts (in-flight items
-     * are lost). Production customers should swap in a SQL-backed
-     * storage that writes to their existing outbox table.
-     */
     items = new Map();
     nextId = 0;
     now;

package/dist/source/signing.d.ts

@@ -1,42 +1,54 @@
 /**
- * Standard Webhooks request signing/verification for Data Source calls.
+ * Signs and verifies source requests using the Standard Webhooks scheme.
  *
- * Ablo signs every outbound source request with the customer's project API
- * key; the customer's endpoint verifies before any handler runs. Both halves
- * live in this leaf so `pushQueue.ts` (customer-side sender) and `factory.ts`
- * (customer-side receiver) can import them directly without a runtime cycle
- * through the `index.ts` barrel.
+ * Every request Ablo sends to a data source is signed with that source's API
+ * key, and the receiving endpoint verifies the signature before any handler
+ * runs. This module provides both halves: {@link signAbloSourceRequest} for
+ * the sender and {@link verifyAbloSourceRequest} for the receiver. Because the
+ * signature format follows the Standard Webhooks specification, you can verify
+ * it with any compatible library instead of these functions if you prefer.
  */
+/** Inputs to {@link signAbloSourceRequest}. */
 export interface SourceSignatureOptions {
+    /** The API key to sign with; the receiver verifies against the same key. */
     readonly apiKey: string;
+    /** The exact request body being signed. */
     readonly body: string;
     /**
-     * Unique message id (`webhook-id` per the Standard Webhooks spec).
-     * Required: it goes into the HMAC input for replay defense, and
-     * receivers may dedupe by it.
+     * The unique message id, sent as the `webhook-id` header. It is folded into
+     * the signature to defend against replay, and receivers may deduplicate on
+     * it. Retries of the same request must reuse the same id.
      */
     readonly messageId: string;
-    /**
-     * Unix timestamp in seconds. Defaults to the current time.
-     */
+    /** The signing time as a Unix timestamp in seconds. Defaults to the current time. */
     readonly timestamp?: number;
 }
+/** Inputs to {@link verifyAbloSourceRequest}. */
 export interface SourceSignatureVerificationOptions {
+    /** The incoming request, whose headers carry the signature to check. */
     readonly request: Request;
+    /** The request body, which must match what was signed. */
     readonly body: string;
+    /** The API key to verify against. */
     readonly apiKey: string;
+    /**
+     * How far the request's timestamp may differ from the current clock, in
+     * milliseconds, before it is rejected as expired. Defaults to five minutes.
+     */
     readonly toleranceMs?: number;
 }
+/** What {@link verifyAbloSourceRequest} returns once a signature checks out. */
 export interface SourceSignatureVerificationResult {
+    /** The verified `webhook-id` of the request. */
     readonly messageId: string;
+    /** The time the request was signed, as a Unix timestamp in seconds. */
     readonly signedAt: number;
 }
 /**
- * HTTP headers used on signed source requests. Conforms to the
- * Standard Webhooks specification (https://www.standardwebhooks.com/)
- * so customer code can verify our signatures with any of the official
- * libraries (svix, standardwebhooks, hookdeck, etc.) — no Ablo-
- * specific verifier required.
+ * The HTTP header names carried on a signed source request. They follow the
+ * Standard Webhooks specification (https://www.standardwebhooks.com/), so you
+ * can verify the signature with any compatible library rather than
+ * {@link verifyAbloSourceRequest} if you prefer.
  */
 export declare const ABLO_SOURCE_HEADERS: {
     readonly signature: "webhook-signature";
@@ -44,15 +56,32 @@ export declare const ABLO_SOURCE_HEADERS: {
     readonly id: "webhook-id";
     readonly idempotencyKey: "Idempotency-Key";
 };
+/**
+ * Thrown when a source request fails signature verification. The
+ * {@link SourceSignatureError.code} names the specific reason — a missing
+ * header, a malformed or expired timestamp, or a signature that does not
+ * match.
+ */
 export declare class SourceSignatureError extends Error {
     readonly code: 'source_signature_missing' | 'source_id_missing' | 'source_timestamp_missing' | 'source_timestamp_invalid' | 'source_timestamp_expired' | 'source_signature_invalid' | 'source_forbidden';
     constructor(code: SourceSignatureError['code'], message: string);
 }
+/**
+ * Sign a source request and return the headers to send with it. The signature
+ * covers the message id, the timestamp, and the body, so any change to those
+ * invalidates it. The receiver checks it with {@link verifyAbloSourceRequest}.
+ */
 export declare function signAbloSourceRequest(options: SourceSignatureOptions): Promise<{
     readonly headers: Record<string, string>;
     readonly signedAt: number;
     readonly signature: string;
 }>;
+/**
+ * Verify a signed source request, throwing {@link SourceSignatureError} when
+ * the message id, timestamp, or signature is missing, malformed, or outside
+ * the allowed clock-skew window. On success it returns the request's message
+ * id and signing time. This is the counterpart to {@link signAbloSourceRequest}.
+ */
 export declare function verifyAbloSourceRequest(options: SourceSignatureVerificationOptions): Promise<SourceSignatureVerificationResult>;
 export type DataSourceSignatureOptions = SourceSignatureOptions;
 export type DataSourceSignatureVerificationOptions = SourceSignatureVerificationOptions;

package/dist/source/signing.js

@@ -1,18 +1,18 @@
 /**
- * Standard Webhooks request signing/verification for Data Source calls.
+ * Signs and verifies source requests using the Standard Webhooks scheme.
  *
- * Ablo signs every outbound source request with the customer's project API
- * key; the customer's endpoint verifies before any handler runs. Both halves
- * live in this leaf so `pushQueue.ts` (customer-side sender) and `factory.ts`
- * (customer-side receiver) can import them directly without a runtime cycle
- * through the `index.ts` barrel.
+ * Every request Ablo sends to a data source is signed with that source's API
+ * key, and the receiving endpoint verifies the signature before any handler
+ * runs. This module provides both halves: {@link signAbloSourceRequest} for
+ * the sender and {@link verifyAbloSourceRequest} for the receiver. Because the
+ * signature format follows the Standard Webhooks specification, you can verify
+ * it with any compatible library instead of these functions if you prefer.
  */
 /**
- * HTTP headers used on signed source requests. Conforms to the
- * Standard Webhooks specification (https://www.standardwebhooks.com/)
- * so customer code can verify our signatures with any of the official
- * libraries (svix, standardwebhooks, hookdeck, etc.) — no Ablo-
- * specific verifier required.
+ * The HTTP header names carried on a signed source request. They follow the
+ * Standard Webhooks specification (https://www.standardwebhooks.com/), so you
+ * can verify the signature with any compatible library rather than
+ * {@link verifyAbloSourceRequest} if you prefer.
  */
 export const ABLO_SOURCE_HEADERS = {
     signature: 'webhook-signature',
@@ -20,6 +20,12 @@ export const ABLO_SOURCE_HEADERS = {
     id: 'webhook-id',
     idempotencyKey: 'Idempotency-Key',
 };
+/**
+ * Thrown when a source request fails signature verification. The
+ * {@link SourceSignatureError.code} names the specific reason — a missing
+ * header, a malformed or expired timestamp, or a signature that does not
+ * match.
+ */
 export class SourceSignatureError extends Error {
     code;
     constructor(code, message) {
@@ -94,6 +100,11 @@ function timingSafeEqual(expected, actual) {
     }
     return diff === 0;
 }
+/**
+ * Sign a source request and return the headers to send with it. The signature
+ * covers the message id, the timestamp, and the body, so any change to those
+ * invalidates it. The receiver checks it with {@link verifyAbloSourceRequest}.
+ */
 export async function signAbloSourceRequest(options) {
     const signedAt = options.timestamp ?? Math.floor(Date.now() / 1000);
     // Standard Webhooks signing input: `${msg_id}.${timestamp}.${payload}`
@@ -108,6 +119,12 @@ export async function signAbloSourceRequest(options) {
         },
     };
 }
+/**
+ * Verify a signed source request, throwing {@link SourceSignatureError} when
+ * the message id, timestamp, or signature is missing, malformed, or outside
+ * the allowed clock-skew window. On success it returns the request's message
+ * id and signing time. This is the counterpart to {@link signAbloSourceRequest}.
+ */
 export async function verifyAbloSourceRequest(options) {
     const messageId = getHeader(options.request, ABLO_SOURCE_HEADERS.id);
     if (!messageId) {