@abloatai/ablo 0.3.0

package/dist/transactions/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Transaction types and exports (MVP)
+ *
+ * Simplified for MVP: only TransactionQueue exports
+ * Individual transaction classes removed in favor of simple transaction objects
+ */
+export { TransactionQueue } from './TransactionQueue.js';
+export type TransactionType = 'create' | 'update' | 'delete';
+export interface Transaction {
+    id: string;
+    type: TransactionType;
+    modelName: string;
+    modelId: string;
+    data?: any;
+    createdAt: number;
+}

package/dist/transactions/index.js

@@ -0,0 +1,7 @@
+/**
+ * Transaction types and exports (MVP)
+ *
+ * Simplified for MVP: only TransactionQueue exports
+ * Individual transaction classes removed in favor of simple transaction objects
+ */
+export { TransactionQueue } from './TransactionQueue.js';

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

@@ -0,0 +1,5 @@
+/**
+ * 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

@@ -0,0 +1,39 @@
+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/types/global.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Typed-global augmentation point for SDK consumers.
+ *
+ * Consumers declare their Schema, Presence, Intents, and UserMeta ONCE in a
+ * `.d.ts` file and every SDK hook — `useQuery`, `useOne`, `useMutate`,
+ * `usePresence`, `useIntent` — reads its types from the resolved global.
+ * No generics at call sites. No `schema` runtime arg passed per hook call.
+ *
+ * This is the same canonical TypeScript declaration-merging pattern that
+ * Next.js uses for `process.env` / `NodeJS.ProcessEnv`, that CSS Modules
+ * use for `declare module '*.module.css'`, and that Liveblocks uses for
+ * `interface Liveblocks`. It's a language feature, not a library trick —
+ * any file in the compilation can augment the global `AbloSync` interface
+ * and every consumer of the resolved types below picks up the augmentation
+ * automatically.
+ *
+ * Consumer example:
+ *
+ * ```ts
+ * // apps/your-app/src/ablo-sync.d.ts
+ * import type { schema } from './your-schema';
+ *
+ * declare global {
+ *   interface AbloSync {
+ *     Schema: typeof schema;
+ *     Presence: { cursor: { x: number; y: number } | null };
+ *     Intents: { editLayer: { layerId: string } };
+ *     UserMeta: { id: string; email: string };
+ *   }
+ * }
+ * export {};
+ * ```
+ *
+ * If `AbloSync` is never declared, every resolver falls back to the
+ * `DefaultSyncShape` — a loose `Record<string, unknown>` shape that keeps
+ * SDK consumers compiling without typed benefits until they opt in.
+ */
+/**
+ * Default fallback shapes used when the consumer hasn't declared
+ * `interface AbloSync`. `DefaultSyncShape.Schema` is intentionally
+ * structural — it carries `{ models: Record<string, unknown> }` so hooks
+ * can still validate the model key argument against *something*, just
+ * without producing a typed entity shape. Once the consumer augments the
+ * global, every resolver below picks up the augmented types automatically.
+ */
+export interface DefaultSyncShape {
+    readonly Schema: {
+        readonly models: Record<string, unknown>;
+    };
+    readonly Presence: Record<string, unknown>;
+    readonly Intents: Record<string, unknown>;
+    readonly UserMeta: {
+        readonly id: string;
+    };
+}
+declare global {
+    /**
+     * Global augmentation target. Consumers augment this via
+     * `declare global { interface AbloSync { Schema: ...; Presence: ...; ... } }`.
+     * Empty by default — every SDK resolver falls back to {@link DefaultSyncShape}
+     * when an expected key is absent.
+     */
+    interface AbloSync {
+    }
+}
+/**
+ * The consumer's schema, or the default shape if undeclared. Hooks use
+ * this to type their model-key argument and to infer the entity type
+ * returned from queries/mutations.
+ */
+export type ResolveSchema = AbloSync extends {
+    Schema: infer S;
+} ? S extends {
+    models: Record<string, unknown>;
+} ? S : DefaultSyncShape['Schema'] : DefaultSyncShape['Schema'];
+/**
+ * The consumer's presence shape, or the default shape if undeclared.
+ * Used by `usePresence`. The shape is free-form — any serializable JSON
+ * the consumer wants to broadcast per session.
+ */
+export type ResolvePresence = AbloSync extends {
+    Presence: infer P;
+} ? P : DefaultSyncShape['Presence'];
+/**
+ * The consumer's intent vocabulary, or the default if undeclared. Keys
+ * are intent names; values are the claim payload for each intent. Used
+ * by `useIntent(intentName)`.
+ */
+export type ResolveIntents = AbloSync extends {
+    Intents: infer I;
+} ? I : DefaultSyncShape['Intents'];
+/**
+ * The consumer's user-metadata shape, or the default if undeclared.
+ * Carries identity info the consumer trusts from their auth layer —
+ * the SDK doesn't validate this.
+ */
+export type ResolveUserMeta = AbloSync extends {
+    UserMeta: infer U;
+} ? U : DefaultSyncShape['UserMeta'];
+/**
+ * The keys of the consumer's schema models. `useQuery(modelKey)` narrows
+ * its first argument to this union, so unknown key literals fail at
+ * compile time.
+ */
+export type ResolveModelKey = ResolveSchema extends {
+    models: infer M;
+} ? keyof M & string : string;

package/dist/types/global.js

@@ -0,0 +1,38 @@
+/**
+ * Typed-global augmentation point for SDK consumers.
+ *
+ * Consumers declare their Schema, Presence, Intents, and UserMeta ONCE in a
+ * `.d.ts` file and every SDK hook — `useQuery`, `useOne`, `useMutate`,
+ * `usePresence`, `useIntent` — reads its types from the resolved global.
+ * No generics at call sites. No `schema` runtime arg passed per hook call.
+ *
+ * This is the same canonical TypeScript declaration-merging pattern that
+ * Next.js uses for `process.env` / `NodeJS.ProcessEnv`, that CSS Modules
+ * use for `declare module '*.module.css'`, and that Liveblocks uses for
+ * `interface Liveblocks`. It's a language feature, not a library trick —
+ * any file in the compilation can augment the global `AbloSync` interface
+ * and every consumer of the resolved types below picks up the augmentation
+ * automatically.
+ *
+ * Consumer example:
+ *
+ * ```ts
+ * // apps/your-app/src/ablo-sync.d.ts
+ * import type { schema } from './your-schema';
+ *
+ * declare global {
+ *   interface AbloSync {
+ *     Schema: typeof schema;
+ *     Presence: { cursor: { x: number; y: number } | null };
+ *     Intents: { editLayer: { layerId: string } };
+ *     UserMeta: { id: string; email: string };
+ *   }
+ * }
+ * export {};
+ * ```
+ *
+ * If `AbloSync` is never declared, every resolver falls back to the
+ * `DefaultSyncShape` — a loose `Record<string, unknown>` shape that keeps
+ * SDK consumers compiling without typed benefits until they opt in.
+ */
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Linear Sync Engine - Core Types
+ *
+ * Foundational type definitions for the model-driven sync architecture.
+ * These types define how properties are tracked, loaded, and synchronized.
+ */
+/**
+ * Model Scope - lifecycle filter for queries.
+ * Controls whether live, archived, or all entities are returned.
+ */
+export declare enum ModelScope {
+    live = "live",
+    archived = "archived",
+    all = "all"
+}
+/**
+ * Property Types - EXACTLY 7 types as per Linear Sync Engine
+ * These define how model properties behave in the sync system
+ */
+export declare enum PropertyType {
+    /** Standard observable property - owned by model, persisted and synced */
+    property = "property",
+    /** Property that doesn't persist or sync - runtime only */
+    ephemeralProperty = "ephemeralProperty",
+    /** Foreign key reference - stores ID only */
+    reference = "reference",
+    /** Lazy-loaded model reference - getter/setter for model based on ID */
+    referenceModel = "referenceModel",
+    /** Collection of related models - one-to-many relationship */
+    referenceCollection = "referenceCollection",
+    /** Back-reference computed property - inverse relationship */
+    backReference = "backReference",
+    /** Array of foreign key references - many-to-many relationship */
+    referenceArray = "referenceArray"
+}
+/**
+ * Load Strategies - EXACTLY 5 strategies as per Linear Sync Engine
+ * Controls when and how model data is loaded from the server
+ */
+export declare enum LoadStrategy {
+    /** Load immediately into ObjectPool during bootstrap - for critical models */
+    instant = "instant",
+    /** Load all at once when first needed - for secondary models */
+    lazy = "lazy",
+    /** Load on demand in subsets - for large collections */
+    partial = "partial",
+    /** Only load when explicitly requested - for optional data */
+    explicitlyRequested = "explicitlyRequested",
+    /** Never sync with server, local only - for client-side state */
+    local = "local"
+}
+/**
+ * Property Metadata - Configuration for decorated properties
+ */
+export interface PropertyMetadata {
+    type: PropertyType;
+    indexed?: boolean;
+    optional?: boolean;
+    nullable?: boolean;
+    defaultValue?: unknown;
+    loadStrategy?: LoadStrategy;
+    /**
+     * MobX observability annotation for this property. Controls how deeply
+     * MobX wraps the value when `M1` registers the model.
+     *
+     * - `'deep'` (default): full recursive observability. Every nested
+     *   object/array becomes its own atom. Correct for scalar fields and
+     *   small structured values where consumers subscribe to inner
+     *   properties.
+     * - `'shallow'`: track the reference and array/map/set operations, but
+     *   do NOT recurse into element internals. Right for collections whose
+     *   elements are replaced wholesale.
+     * - `'ref'`: track ONLY reassignment. Right for opaque JSON blobs
+     *   (chart specs, ProseMirror docs, style maps) that are treated as
+     *   immutable values — consumers always read the whole blob and pass
+     *   it to a renderer. Deep enhancement on these produces a microtask
+     *   storm with no benefit.
+     *
+     * Schema-driven registration auto-sets this to `'ref'` for fields with
+     * wire type `'json'`, which is the right default for the blob pattern.
+     */
+    observability?: 'deep' | 'shallow' | 'ref';
+}
+/** Model constructor type for reference metadata */
+type ModelConstructor = abstract new (...args: never[]) => unknown;
+/**
+ * Reference Metadata - Configuration for reference properties
+ */
+export interface ReferenceMetadata {
+    referencedModel: () => ModelConstructor;
+    backReference?: string;
+    indexed?: boolean;
+    nullable?: boolean;
+}
+/**
+ * Model Metadata - Configuration for model classes
+ */
+export interface ModelMetadata {
+    loadStrategy: LoadStrategy;
+    syncGroup?: string;
+    tableName?: string;
+    partialLoadMode?: 'full' | 'regular' | 'lowPriority';
+    usedForPartialIndexes?: boolean;
+    schemaVersion?: number;
+    /**
+     * Schema-declared fields for this model, keyed by field name. Drives
+     * commit payload projection (filter to declared fields + stringify
+     * JSON-typed values) inside the transaction queue.
+     *
+     * Populated by `registerModelsFromSchema`. Each entry carries the
+     * sync-engine type tag (`'string' | 'number' | 'boolean' | 'date' |
+     * 'enum' | 'json'`), which tells the wire serializer how to handle
+     * the value. Missing → projection becomes identity pass-through
+     * (back-compat for models registered outside the schema path).
+     */
+    fields?: Readonly<Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'json';
+    }>>;
+    /**
+     * Fields to back-fill from the sync client identity when missing
+     * during IndexedDB self-healing. Populated from
+     * `ModelOptions.autoFill` in the schema. Each entry maps a field on
+     * this model to one of the identity values held by `SyncClient`
+     * (`organizationId` or `userId`).
+     *
+     * Used by `SyncClient.healModelRecord` to keep the engine
+     * product-neutral: the engine no longer hardcodes which models carry
+     * `organizationId` / `createdBy` — the consumer's schema declares it.
+     */
+    autoFill?: ReadonlyArray<{
+        field: string;
+        from: 'organizationId' | 'userId';
+    }>;
+    /**
+     * Fields whose absence makes a stored row orphaned. When healing
+     * encounters a record missing any of these fields, it returns `null`
+     * to signal the caller to skip the row. Populated from
+     * `ModelOptions.requiredFields` in the schema.
+     */
+    requiredFields?: readonly string[];
+}
+/**
+ * Model Options - Options for @ClientModel decorator
+ */
+export interface ModelOptions {
+    loadStrategy: LoadStrategy;
+    syncGroup?: string;
+    tableName?: string;
+}
+/**
+ * Property Options - Options for @Property decorator
+ */
+export interface PropertyOptions {
+    indexed?: boolean;
+    optional?: boolean;
+    defaultValue?: unknown;
+    ephemeral?: boolean;
+}
+/**
+ * Reference Options - Options for @Reference decorator
+ */
+export interface ReferenceOptions {
+    indexed?: boolean;
+    nullable?: boolean;
+}
+/**
+ * GraphQL Mutation Interface
+ */
+export interface GraphQLMutation {
+    mutationText: string;
+    variables: Record<string, unknown>;
+}
+/**
+ * Load Request Interface
+ */
+export interface LoadRequest {
+    modelName: string;
+    indexedKey: string;
+    keyValue: string;
+    resolve?: (value: unknown[]) => void;
+}
+/**
+ * Sync Action Types - Complete Linear specification
+ */
+export type SyncActionType = 'I' | 'U' | 'A' | 'D' | 'C' | 'G' | 'S' | 'V';
+/**
+ * Sync Action Interface - Linear format
+ */
+export interface SyncAction {
+    id: number;
+    modelName: string;
+    modelId: string;
+    action: SyncActionType;
+    data: unknown;
+    __class: 'SyncAction';
+}
+/**
+ * Delta Packet - Array of sync actions
+ */
+export type DeltaPacket = SyncAction[];
+/**
+ * Bootstrap Types
+ */
+export type BootstrapType = 'full' | 'partial' | 'local';
+/**
+ * Bootstrap Metadata
+ */
+export interface BootstrapMetadata {
+    lastSyncId: number;
+    subscribedSyncGroups: string[];
+}
+/**
+ * Database Metadata - Sync engine state tracking
+ */
+export interface DatabaseMetadata {
+    lastSyncId: number;
+    firstSyncId: number;
+    backendDatabaseVersion: number;
+    subscribedSyncGroups: string[];
+    updatedAt: Date;
+}
+/**
+ * Mutation operation types for batch mutations.
+ */
+export declare enum MutationOperationType {
+    ARCHIVE = "ARCHIVE",
+    CREATE = "CREATE",
+    DELETE = "DELETE",
+    UNARCHIVE = "UNARCHIVE",
+    UPDATE = "UPDATE"
+}
+/**
+ * Partial Index Information - For complex querying
+ */
+export interface PartialIndexInfo {
+    modelName: string;
+    indexKey: string;
+    depth: number;
+    path: string[];
+}
+export * from "./streams.js";

package/dist/types/index.js

@@ -0,0 +1,70 @@
+/**
+ * Linear Sync Engine - Core Types
+ *
+ * Foundational type definitions for the model-driven sync architecture.
+ * These types define how properties are tracked, loaded, and synchronized.
+ */
+/**
+ * Model Scope - lifecycle filter for queries.
+ * Controls whether live, archived, or all entities are returned.
+ */
+export var ModelScope;
+(function (ModelScope) {
+    ModelScope["live"] = "live";
+    ModelScope["archived"] = "archived";
+    ModelScope["all"] = "all";
+})(ModelScope || (ModelScope = {}));
+/**
+ * Property Types - EXACTLY 7 types as per Linear Sync Engine
+ * These define how model properties behave in the sync system
+ */
+export var PropertyType;
+(function (PropertyType) {
+    /** Standard observable property - owned by model, persisted and synced */
+    PropertyType["property"] = "property";
+    /** Property that doesn't persist or sync - runtime only */
+    PropertyType["ephemeralProperty"] = "ephemeralProperty";
+    /** Foreign key reference - stores ID only */
+    PropertyType["reference"] = "reference";
+    /** Lazy-loaded model reference - getter/setter for model based on ID */
+    PropertyType["referenceModel"] = "referenceModel";
+    /** Collection of related models - one-to-many relationship */
+    PropertyType["referenceCollection"] = "referenceCollection";
+    /** Back-reference computed property - inverse relationship */
+    PropertyType["backReference"] = "backReference";
+    /** Array of foreign key references - many-to-many relationship */
+    PropertyType["referenceArray"] = "referenceArray";
+})(PropertyType || (PropertyType = {}));
+/**
+ * Load Strategies - EXACTLY 5 strategies as per Linear Sync Engine
+ * Controls when and how model data is loaded from the server
+ */
+export var LoadStrategy;
+(function (LoadStrategy) {
+    /** Load immediately into ObjectPool during bootstrap - for critical models */
+    LoadStrategy["instant"] = "instant";
+    /** Load all at once when first needed - for secondary models */
+    LoadStrategy["lazy"] = "lazy";
+    /** Load on demand in subsets - for large collections */
+    LoadStrategy["partial"] = "partial";
+    /** Only load when explicitly requested - for optional data */
+    LoadStrategy["explicitlyRequested"] = "explicitlyRequested";
+    /** Never sync with server, local only - for client-side state */
+    LoadStrategy["local"] = "local";
+})(LoadStrategy || (LoadStrategy = {}));
+/**
+ * Mutation operation types for batch mutations.
+ */
+export var MutationOperationType;
+(function (MutationOperationType) {
+    MutationOperationType["ARCHIVE"] = "ARCHIVE";
+    MutationOperationType["CREATE"] = "CREATE";
+    MutationOperationType["DELETE"] = "DELETE";
+    MutationOperationType["UNARCHIVE"] = "UNARCHIVE";
+    MutationOperationType["UPDATE"] = "UPDATE";
+})(MutationOperationType || (MutationOperationType = {}));
+// Re-export stream + snapshot + principal types for the engine surface
+// (PresenceStream,
+// IntentStream, Snapshot, etc.) consumed by `Ablo({...}).presence`,
+// `.intents`, `.snapshot()`.
+export * from "./streams.js";