@abloatai/ablo 0.26.0 → 0.27.0

package/dist/source/connector-protocol.js

@@ -1,161 +0,0 @@
-/**
- * Data Source reverse-channel wire protocol.
- *
- * The `commit`/`load`/`list` leg of Data Source mode is normally an INBOUND
- * webhook (Ablo Cloud → your HTTPS endpoint). That requires a public URL, so it
- * doesn't work on `localhost` or inside a locked-down VPC with no inbound path.
- *
- * The reverse channel inverts the direction: the customer's connector dials OUT
- * to Ablo Cloud over a WebSocket and serves those same requests over the open
- * socket — the Stripe-CLI `stripe listen` pattern. This module defines the
- * frames that travel over that socket.
- *
- * Trust model is unchanged. A `request` frame carries the SAME Standard Webhooks
- * signature headers (`webhook-id` / `webhook-timestamp` / `webhook-signature`)
- * and the SAME raw body Ablo would have POSTed, so the connector verifies it
- * through the unchanged `verifyAbloSourceRequest`. Only the transport differs.
- *
- * Frames are validated with zod at the boundary (matching `contract.ts`): a
- * malformed frame is rejected at the edge, and every wire type is inferred from
- * one schema so the two sides can never silently drift.
- */
-import { z } from 'zod';
-import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../auth/credentialSource.js';
-/**
- * Wire-protocol version. Bumped on any breaking frame-shape change so an old
- * connector talking to a new server (or vice-versa) fails fast at `register`
- * instead of misparsing a frame mid-stream.
- */
-export const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
-/** Path the connector dials. Appended to the connector's `baseURL`. */
-export const SOURCE_CONNECTOR_WS_PATH = '/v1/source/listen';
-/**
- * Negotiated WebSocket subprotocol that marks a reverse-channel source
- * connector (vs. the SDK sync client's `ablo.sync.v1`). The server selects and
- * echoes back ONLY this value, never the token-bearing subprotocol — keeping the
- * credential out of ALB / proxy logs exactly like the sync socket does.
- */
-export const WS_SOURCE_SUBPROTOCOL = 'ablo.source.v1';
-/**
- * Build the `Sec-WebSocket-Protocol` list a connector offers: the source
- * protocol plus the bearer credential (`ablo.bearer.<apiKey>`). Browsers can't
- * set an `Authorization` header on a WebSocket, so the API key rides as a
- * subprotocol — the same mechanism the SDK sync client uses, read server-side by
- * the shared `extractBearer`.
- */
-export function sourceConnectorSubprotocols(apiKey) {
-    return [WS_SOURCE_SUBPROTOCOL, `${WS_BEARER_SUBPROTOCOL_PREFIX}${apiKey}`];
-}
-const headerRecord = z.record(z.string(), z.string());
-/**
- * Connector → server, first frame after the socket opens and authenticates.
- * Auth and source resolution happen at the WS handshake from the API key; this
- * frame only carries protocol negotiation + advisory metadata.
- */
-export const registerFrameSchema = z.object({
-    type: z.literal('register'),
-    protocolVersion: z.number().int(),
-    /**
-     * Advisory client identifier (e.g. `@abloatai/ablo@0.12.0`) for server-side
-     * logging. Not trusted for any decision.
-     */
-    client: z.string().optional(),
-});
-/**
- * Server → connector, acknowledges a successful `register`. Echoes the resolved
- * source identity so the connector can log/verify which source it is serving.
- */
-export const readyFrameSchema = z.object({
-    type: z.literal('ready'),
-    protocolVersion: z.number().int(),
-    sourceId: z.string().optional(),
-    organizationId: z.string().optional(),
-    environment: z.enum(['production', 'sandbox']).optional(),
-});
-/**
- * Server → connector, one drained `commit`/`load`/`list` request. `headers` and
- * `body` are byte-identical to what the inbound webhook path would have sent —
- * the connector replays them into a synthesized `Request` so the unchanged
- * handler verifies the signature exactly as in production.
- */
-export const requestFrameSchema = z.object({
-    type: z.literal('request'),
-    /** Correlation id; the matching `response` frame carries the same value. */
-    id: z.string().min(1),
-    method: z.literal('POST'),
-    /** Synthetic absolute URL used only to construct the `Request` object. */
-    url: z.string().min(1),
-    /** Signed Standard Webhooks headers + `Content-Type`. */
-    headers: headerRecord,
-    /** Raw JSON request body — exactly the bytes that were signed. */
-    body: z.string(),
-});
-/**
- * Connector → server, the handler's `Response` for one `request`. The server
- * resolves the pending request keyed by `id` and feeds `status`/`body` back to
- * the `SourceClient` as if an HTTP response had returned.
- */
-export const responseFrameSchema = z.object({
-    type: z.literal('response'),
-    id: z.string().min(1),
-    status: z.number().int(),
-    headers: headerRecord.optional(),
-    /** Raw JSON response body. */
-    body: z.string(),
-});
-/**
- * Either direction, out-of-band failure not tied to a single request body
- * (auth rejected, unsupported protocol version, malformed frame). When `id` is
- * present the error pertains to that pending request and fails it; otherwise it
- * is a connection-level error.
- */
-export const errorFrameSchema = z.object({
-    type: z.literal('error'),
-    id: z.string().min(1).optional(),
-    code: z.string().min(1),
-    message: z.string(),
-});
-export const connectorFrameSchema = z.discriminatedUnion('type', [
-    registerFrameSchema,
-    readyFrameSchema,
-    requestFrameSchema,
-    responseFrameSchema,
-    errorFrameSchema,
-]);
-/** Thrown when an incoming frame fails to parse or validate. */
-export class ConnectorProtocolError extends Error {
-    code = 'source_connector_protocol_error';
-    constructor(message) {
-        super(message);
-        this.name = 'ConnectorProtocolError';
-    }
-}
-/** Serialize a frame for transmission. */
-export function encodeFrame(frame) {
-    return JSON.stringify(frame);
-}
-/**
- * Parse + validate an incoming frame. Accepts the string or binary payloads the
- * `ws` library / WebSocket `message` events deliver. Throws
- * `ConnectorProtocolError` on any malformed or unknown frame so callers can
- * reject the connection rather than act on garbage.
- */
-export function decodeFrame(raw) {
-    const text = typeof raw === 'string' ? raw : decodeBinary(raw);
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch {
-        throw new ConnectorProtocolError('Frame is not valid JSON');
-    }
-    const result = connectorFrameSchema.safeParse(parsed);
-    if (!result.success) {
-        throw new ConnectorProtocolError(`Invalid connector frame: ${result.error.message}`);
-    }
-    return result.data;
-}
-function decodeBinary(raw) {
-    const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
-    return new TextDecoder().decode(bytes);
-}

package/dist/transactions/OptimisticEchoTracker.d.ts

@@ -1,82 +0,0 @@
-/**
- * OptimisticEchoTracker — receive-layer reconciliation primitive.
- *
- * Tracks the set of transaction ids the client has applied locally
- * but the server has not yet confirmed. When a sync delta arrives
- * carrying a `transactionId` the tracker recognizes, the pool
- * mutation is suppressed (the optimistic write already reflects it).
- * Drained when the matching delta echo lands or when the originating
- * transaction is rolled back.
- *
- * Architectural framing: see
- * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`. This is the
- * "discriminator at the apply layer" the doc names — without it the
- * authoritative-layer apply path blindly re-applies confirmations on
- * top of whatever optimistic state has since diverged, producing the
- * chart-delete flicker.
- *
- * Bounded by `maxSize` to defend against runaway growth from a
- * pathological "transactions never confirmed and never rolled back"
- * loop. When the bound is hit, the OLDEST id is evicted (FIFO via
- * insertion-ordered Map). Eviction means a future echo of that
- * transaction will be applied as a foreign mutation — no correctness
- * risk for the originating tab (the pool already reflects the local
- * write); the worst case is a single redundant pool re-set.
- */
-export interface OptimisticEchoTrackerOptions {
-    /**
-     * Hard upper bound on tracked ids. FIFO eviction beyond this. The
-     * default of 10_000 covers a 200-tab user mid-bulk-edit (each tab
-     * tracking dozens of unconfirmed transactions) with two orders of
-     * magnitude of headroom.
-     */
-    maxSize?: number;
-}
-export interface OptimisticEchoMetrics {
-    /** Total ids currently tracked. */
-    size: number;
-    /** Cumulative ids ever added since construction. */
-    totalAdded: number;
-    /** Cumulative successful echo matches (delta arrived → drained). */
-    hits: number;
-    /** Cumulative explicit rollback drains (transaction never made it). */
-    rollbacks: number;
-    /** Cumulative ids evicted due to maxSize pressure. */
-    evictions: number;
-}
-export declare class OptimisticEchoTracker {
-    private readonly ids;
-    private readonly maxSize;
-    private _totalAdded;
-    private _hits;
-    private _rollbacks;
-    private _evictions;
-    constructor(options?: OptimisticEchoTrackerOptions);
-    /**
-     * Mark a transaction as locally-applied. The next sync delta with a
-     * matching `transactionId` will be recognized as the server's
-     * confirmation of this same write. Idempotent — repeated calls with
-     * the same id are no-ops.
-     */
-    markPending(transactionId: string): void;
-    /**
-     * If the id is currently tracked, drain it and return true (signal
-     * to the caller: this is an echo, skip the pool mutation).
-     * Otherwise return false (foreign mutation, apply normally).
-     *
-     * Combined check+drain into one method to make the receive-path
-     * idiom hard to misuse: a separate `has` then `drain` would race
-     * if multiple deltas with the same id arrived in the same batch.
-     */
-    consumeEcho(transactionId: string | null | undefined): boolean;
-    /**
-     * Drain on rollback. The transaction was cancelled before a server
-     * confirmation arrived — no echo will ever come, so the pending
-     * entry would otherwise leak. Counts as a separate metric category
-     * so a spike of `rollbacks` (vs `hits`) signals network or
-     * server-side health issues.
-     */
-    drainOnRollback(transactionId: string): void;
-    getMetrics(): Readonly<OptimisticEchoMetrics>;
-    clear(): void;
-}

package/dist/transactions/OptimisticEchoTracker.js

@@ -1,104 +0,0 @@
-/**
- * OptimisticEchoTracker — receive-layer reconciliation primitive.
- *
- * Tracks the set of transaction ids the client has applied locally
- * but the server has not yet confirmed. When a sync delta arrives
- * carrying a `transactionId` the tracker recognizes, the pool
- * mutation is suppressed (the optimistic write already reflects it).
- * Drained when the matching delta echo lands or when the originating
- * transaction is rolled back.
- *
- * Architectural framing: see
- * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`. This is the
- * "discriminator at the apply layer" the doc names — without it the
- * authoritative-layer apply path blindly re-applies confirmations on
- * top of whatever optimistic state has since diverged, producing the
- * chart-delete flicker.
- *
- * Bounded by `maxSize` to defend against runaway growth from a
- * pathological "transactions never confirmed and never rolled back"
- * loop. When the bound is hit, the OLDEST id is evicted (FIFO via
- * insertion-ordered Map). Eviction means a future echo of that
- * transaction will be applied as a foreign mutation — no correctness
- * risk for the originating tab (the pool already reflects the local
- * write); the worst case is a single redundant pool re-set.
- */
-const DEFAULT_MAX_SIZE = 10_000;
-export class OptimisticEchoTracker {
-    // Map (not Set) for O(1) FIFO eviction via insertion order.
-    // Value is unused; Map.keys() iterates in insertion order so
-    // `keys().next()` yields the oldest id.
-    ids = new Map();
-    maxSize;
-    // Metrics — internal counters; exposed via `getMetrics()`. Kept
-    // numeric (not BigInt) since cumulative-since-page-load fits well
-    // under Number.MAX_SAFE_INTEGER for any realistic session.
-    _totalAdded = 0;
-    _hits = 0;
-    _rollbacks = 0;
-    _evictions = 0;
-    constructor(options = {}) {
-        this.maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
-    }
-    /**
-     * Mark a transaction as locally-applied. The next sync delta with a
-     * matching `transactionId` will be recognized as the server's
-     * confirmation of this same write. Idempotent — repeated calls with
-     * the same id are no-ops.
-     */
-    markPending(transactionId) {
-        if (this.ids.has(transactionId))
-            return;
-        if (this.ids.size >= this.maxSize) {
-            const oldest = this.ids.keys().next().value;
-            if (oldest !== undefined) {
-                this.ids.delete(oldest);
-                this._evictions += 1;
-            }
-        }
-        this.ids.set(transactionId, true);
-        this._totalAdded += 1;
-    }
-    /**
-     * If the id is currently tracked, drain it and return true (signal
-     * to the caller: this is an echo, skip the pool mutation).
-     * Otherwise return false (foreign mutation, apply normally).
-     *
-     * Combined check+drain into one method to make the receive-path
-     * idiom hard to misuse: a separate `has` then `drain` would race
-     * if multiple deltas with the same id arrived in the same batch.
-     */
-    consumeEcho(transactionId) {
-        if (!transactionId)
-            return false;
-        if (!this.ids.has(transactionId))
-            return false;
-        this.ids.delete(transactionId);
-        this._hits += 1;
-        return true;
-    }
-    /**
-     * Drain on rollback. The transaction was cancelled before a server
-     * confirmation arrived — no echo will ever come, so the pending
-     * entry would otherwise leak. Counts as a separate metric category
-     * so a spike of `rollbacks` (vs `hits`) signals network or
-     * server-side health issues.
-     */
-    drainOnRollback(transactionId) {
-        if (this.ids.delete(transactionId)) {
-            this._rollbacks += 1;
-        }
-    }
-    getMetrics() {
-        return {
-            size: this.ids.size,
-            totalAdded: this._totalAdded,
-            hits: this._hits,
-            rollbacks: this._rollbacks,
-            evictions: this._evictions,
-        };
-    }
-    clear() {
-        this.ids.clear();
-    }
-}

package/dist/transactions/mutation-error-handler.d.ts

@@ -1,5 +0,0 @@
-/**
- * Shared error handler for mutation execution.
- * Logs to SyncObservability (unless offline + network error), then re-throws.
- */
-export declare function handleMutationError(error: unknown, context: string, schemaName: string, modelId: string): never;

package/dist/transactions/mutation-error-handler.js

@@ -1,39 +0,0 @@
-import { getContext } from "../context.js";
-/**
- * Shared error handler for mutation execution.
- * Logs to SyncObservability (unless offline + network error), then re-throws.
- */
-export function handleMutationError(error, context, schemaName, modelId) {
-    const errorInfo = { schemaName, modelId, rawError: error };
-    if (error instanceof Error) {
-        errorInfo.message = error.message;
-        errorInfo.name = error.name;
-        errorInfo.stack =
-            typeof error.stack === 'string' ? error.stack.split('\n').slice(0, 5) : undefined;
-    }
-    else if (error && typeof error === 'object') {
-        errorInfo.message =
-            error.message ??
-                error.error ??
-                'Unknown error';
-        errorInfo.code = error.code;
-        errorInfo.extensions = error.extensions;
-    }
-    else {
-        errorInfo.message = String(error);
-    }
-    const isOffline = !getContext().onlineStatus.isOnline();
-    const msg = errorInfo.message;
-    const isNetworkError = msg?.includes('Failed to fetch') ||
-        msg?.includes('Network request failed') ||
-        msg?.includes('NetworkError');
-    if (!isOffline || !isNetworkError) {
-        getContext().observability.captureTransactionFailure({
-            context,
-            error: error instanceof Error ? error : String(errorInfo.message ?? error),
-            modelName: schemaName,
-            modelId,
-        });
-    }
-    throw error;
-}

package/dist/transactions/optimistic.d.ts

@@ -1,24 +0,0 @@
-/**
- * Optimistic apply/rollback — the queue's local-first bookkeeping, lifted out
- * of `TransactionQueue.ts` as a pure leaf. The queue never mutates the pool
- * itself: applying/rolling back records an entry in the host-owned ledger and
- * emits `optimistic:*` events that the pool-side listeners act on. These
- * functions take that ledger plus a minimal emitter interface (never the host
- * class type), so the rules stay cycle-free and testable in isolation.
- */
-import type { Model } from '../Model.js';
-import type { MutationInput, Transaction } from './commitPayload.js';
-/** One tracked optimistic mutation: the live model + its pre-image. */
-export interface OptimisticUpdateEntry {
-    model: Model;
-    previousState: MutationInput | null | undefined;
-    transaction: Transaction;
-}
-/** The host's event surface — the only queue capability these rules need. */
-export interface OptimisticEmitter {
-    emit(event: string, payload: unknown): void;
-}
-export declare function applyOptimisticCreate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
-export declare function applyOptimisticUpdate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
-export declare function applyOptimisticDelete(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: Transaction): void;
-export declare function rollbackOptimistic(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, transaction: Transaction, reason?: string, error?: Error): Promise<void>;

package/dist/transactions/optimistic.js

@@ -1,45 +0,0 @@
-/**
- * Optimistic apply/rollback — the queue's local-first bookkeeping, lifted out
- * of `TransactionQueue.ts` as a pure leaf. The queue never mutates the pool
- * itself: applying/rolling back records an entry in the host-owned ledger and
- * emits `optimistic:*` events that the pool-side listeners act on. These
- * functions take that ledger plus a minimal emitter interface (never the host
- * class type), so the rules stay cycle-free and testable in isolation.
- */
-export function applyOptimisticCreate(optimisticUpdates, emitter, model, transaction) {
-    optimisticUpdates.set(transaction.id, {
-        model,
-        previousState: null,
-        transaction,
-    });
-    emitter.emit('optimistic:create', { model, transaction });
-}
-export function applyOptimisticUpdate(optimisticUpdates, emitter, model, transaction) {
-    optimisticUpdates.set(transaction.id, {
-        model,
-        previousState: transaction.previousData,
-        transaction,
-    });
-    emitter.emit('optimistic:update', { model, transaction });
-}
-export function applyOptimisticDelete(optimisticUpdates, emitter, model, transaction) {
-    optimisticUpdates.set(transaction.id, {
-        model,
-        previousState: transaction.previousData,
-        transaction,
-    });
-    emitter.emit('optimistic:delete', { model, transaction });
-}
-export async function rollbackOptimistic(optimisticUpdates, emitter, transaction, reason, error) {
-    const optimistic = optimisticUpdates.get(transaction.id);
-    if (!optimistic)
-        return;
-    emitter.emit('optimistic:rollback', {
-        model: optimistic.model,
-        previousState: optimistic.previousState,
-        transaction,
-        reason: reason ?? 'unknown',
-        error,
-    });
-    optimisticUpdates.delete(transaction.id);
-}

package/dist/utils/mobx-setup.d.ts

@@ -1,42 +0,0 @@
-/**
- * M1 Helper - Simplified MobX Setup
- *
- * Fixed version that doesn't conflict with existing getters/setters
- */
-import { type AnnotationMapEntry } from 'mobx';
-import { type PropertyMetadata, type ReferenceMetadata } from '../types/index.js';
-/**
- * The internal contract M1 relies on. Models invoke M1 from inside
- * their constructor, where these fields are guaranteed to exist on
- * `this`. Declared here as the bound on M1's generic so the body can
- * reference them without `as any` casts. Each field is optional so a
- * partial Model implementation (e.g., a test fixture) still satisfies
- * the bound.
- */
-interface M1Target {
-    _hasCustomObservability?: boolean;
-    _isConstructing?: boolean;
-    _extraMobxAnnotations?: Record<string, AnnotationMapEntry>;
-    setupObservability?(): void;
-    propertyChanged?(name: string, oldValue: unknown, newValue: unknown): void;
-}
-/**
- * M1 - Make properties observable with proper MobX setup
- *
- * Simplified version that respects existing getters/setters
- */
-export declare function M1<T extends M1Target>(target: T, propertyMetadata: Map<string, PropertyMetadata>, referenceMetadata?: Map<string, ReferenceMetadata>): void;
-/**
- * Helper to make a class observable
- * For classes that don't have custom observability
- */
-export declare function makeModelObservable(modelClass: any, propertyMetadata: Map<string, PropertyMetadata>, referenceMetadata?: Map<string, any>): any;
-/**
- * Utility to check if a property is observable
- */
-export declare function isObservableProperty(target: any, propName: string, propertyMetadata: Map<string, PropertyMetadata>): boolean;
-/**
- * Utility to get computed properties
- */
-export declare function getComputedProperties(propertyMetadata: Map<string, PropertyMetadata>): string[];
-export {};