@fatagnus/dink-convex 1.0.0

package/dist/schema.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Schema helpers for defining synced tables.
+ *
+ * Provides:
+ * - `syncedTable` helper that wraps table definitions to enable automatic sync
+ * - `internalSyncSchema` that users spread into their schema for internal sync tables
+ *
+ * @module schema
+ */
+import { defineTable } from "convex/server";
+/**
+ * Internal sync tables schema.
+ *
+ * These tables are required by the @fatagnus/dink-convex sync system.
+ * Spread this into your app's schema to include all internal tables:
+ *
+ * @example
+ * ```typescript
+ * // convex/schema.ts
+ * import { defineSchema } from "convex/server";
+ * import { syncedTable, internalSyncSchema } from "@fatagnus/dink-convex";
+ *
+ * export default defineSchema({
+ *   // Your synced tables
+ *   tasks: syncedTable({ title: v.string(), completed: v.boolean() }),
+ *
+ *   // Spread internal sync tables (required)
+ *   ...internalSyncSchema,
+ * });
+ * ```
+ *
+ * ## Why These Tables Are in Your Schema (Not Hidden in the Component)
+ *
+ * You might wonder why `@fatagnus/dink-convex` requires spreading these tables into your
+ * schema rather than hiding them entirely inside the component. This is due to
+ * a fundamental Convex constraint:
+ *
+ * **Convex mutations cannot call `ctx.runMutation()` to invoke other mutations.**
+ *
+ * This matters because:
+ * 1. Sync triggers run inside your mutation context (via convex-helpers Triggers)
+ * 2. Triggers must write delta/outbox records atomically in the same transaction
+ * 3. Component-internal tables can only be written via component mutations
+ * 4. Since triggers can't call component mutations, tables must be in app schema
+ *
+ * This ensures atomicity: your data changes and sync metadata are written together.
+ * If we used actions instead, a failure after your mutation but before recording
+ * the delta would leave data that never syncs.
+ *
+ * The practical impact is minimal - just one spread line in your schema. You never
+ * interact with these tables directly; they're managed entirely by the sync system.
+ */
+export declare const internalSyncSchema: {
+    /**
+     * sync_deltas - Stores CRDT delta updates for sync operations.
+     * Each delta represents a change that needs to be synchronized.
+     */
+    readonly sync_deltas: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        edgeId?: string | undefined;
+        bytes: ArrayBuffer;
+        collection: string;
+        docId: string;
+        seq: number;
+        timestamp: number;
+    }, {
+        /** Collection name (user table) */
+        collection: import("convex/values").VString<string, "required">;
+        /** Document sync ID (syncId from user table) */
+        docId: import("convex/values").VString<string, "required">;
+        /** CRDT delta bytes (Yjs update) */
+        bytes: import("convex/values").VBytes<ArrayBuffer, "required">;
+        /** Sequence number for ordering */
+        seq: import("convex/values").VFloat64<number, "required">;
+        /** Timestamp when delta was created */
+        timestamp: import("convex/values").VFloat64<number, "required">;
+        /** Edge ID that originated this delta (optional) */
+        edgeId: import("convex/values").VString<string | undefined, "optional">;
+    }, "required", "bytes" | "collection" | "docId" | "seq" | "timestamp" | "edgeId">, {
+        by_collection: ["collection", "_creationTime"];
+        by_docId: ["collection", "docId", "_creationTime"];
+        by_seq: ["collection", "seq", "_creationTime"];
+    }, {}, {}>;
+    /**
+     * sync_outbox - Queue of deltas pending push to dinkd.
+     * Deltas are queued here when triggers fire, then processed by
+     * the scheduled outbox processor which pushes them to dinkd.
+     */
+    readonly sync_outbox: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        lastAttempt?: number | undefined;
+        collection: string;
+        docId: string;
+        seq: number;
+        delta: ArrayBuffer;
+        status: string;
+        retries: number;
+        createdAt: number;
+    }, {
+        /** Collection name (user table) */
+        collection: import("convex/values").VString<string, "required">;
+        /** Document sync ID (syncId from user table) */
+        docId: import("convex/values").VString<string, "required">;
+        /** CRDT delta bytes to send */
+        delta: import("convex/values").VBytes<ArrayBuffer, "required">;
+        /** Sequence number for deduplication */
+        seq: import("convex/values").VFloat64<number, "required">;
+        /** Status: "pending" | "sent" | "failed" */
+        status: import("convex/values").VString<string, "required">;
+        /** Number of retry attempts */
+        retries: import("convex/values").VFloat64<number, "required">;
+        /** Timestamp when item was created */
+        createdAt: import("convex/values").VFloat64<number, "required">;
+        /** Timestamp of last send attempt (optional) */
+        lastAttempt: import("convex/values").VFloat64<number | undefined, "optional">;
+    }, "required", "collection" | "docId" | "seq" | "delta" | "status" | "retries" | "createdAt" | "lastAttempt">, {
+        by_status: ["status", "_creationTime"];
+        by_collection: ["collection", "_creationTime"];
+        by_docId_seq: ["docId", "seq", "_creationTime"];
+    }, {}, {}>;
+    /**
+     * sync_sessions - Tracks connected sessions and their sync state.
+     */
+    readonly sync_sessions: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        collection: string;
+        sessionId: string;
+        lastSeq: number;
+        lastSeen: number;
+    }, {
+        /** Unique session identifier */
+        sessionId: import("convex/values").VString<string, "required">;
+        /** Collection being synced */
+        collection: import("convex/values").VString<string, "required">;
+        /** Last sequence number acknowledged by this session */
+        lastSeq: import("convex/values").VFloat64<number, "required">;
+        /** Timestamp when session was last active */
+        lastSeen: import("convex/values").VFloat64<number, "required">;
+    }, "required", "collection" | "sessionId" | "lastSeq" | "lastSeen">, {
+        by_sessionId: ["sessionId", "_creationTime"];
+        by_collection: ["collection", "_creationTime"];
+    }, {}, {}>;
+    /**
+     * sync_config - Configuration for which tables have sync enabled.
+     */
+    readonly sync_config: import("convex/server").TableDefinition<import("convex/values").VObject<{
+        collection: string;
+        enabled: boolean;
+    }, {
+        /** Collection name (user table) */
+        collection: import("convex/values").VString<string, "required">;
+        /** Whether sync is enabled for this collection */
+        enabled: import("convex/values").VBoolean<boolean, "required">;
+    }, "required", "collection" | "enabled">, {
+        by_collection: ["collection", "_creationTime"];
+    }, {}, {}>;
+};
+/**
+ * Configuration options for syncedTable.
+ */
+export interface SyncedTableConfig {
+    /** Optional custom sync ID field name (defaults to syncId) */
+    syncIdField?: string;
+}
+/**
+ * Register a table name as a synced table.
+ * Called internally or by developers to track which tables need sync enabled.
+ *
+ * @param tableName - The name of the table to register
+ */
+export declare function registerSyncedTableName(tableName: string): void;
+/**
+ * Get all registered synced table names.
+ * Used during installation to auto-enable sync for all registered tables.
+ *
+ * @returns Array of registered table names
+ */
+export declare function getRegisteredSyncedTables(): string[];
+/**
+ * Clear all registered synced tables.
+ * Useful for testing.
+ */
+export declare function clearRegisteredSyncedTables(): void;
+/**
+ * The return type of defineTable - a table definition that can have indexes added.
+ */
+type TableDefinition = ReturnType<typeof defineTable>;
+/**
+ * Field validators type - the object passed to defineTable
+ * Using a simple record type since Convex validators are complex
+ */
+type ValidatorFields = Record<string, any>;
+/**
+ * Creates a synced Convex table definition with sync-related fields and indexes.
+ *
+ * This helper automatically adds:
+ * - A sync ID field (default: syncId) for tracking document sync state
+ * - An index on the sync ID field for efficient sync queries
+ *
+ * @param fields - The field validators for the table (same as what you'd pass to defineTable)
+ * @param config - Optional configuration for sync behavior
+ * @returns A table definition with sync fields and indexes included
+ *
+ * @example
+ * ```typescript
+ * import { defineSchema } from "convex/server";
+ * import { v } from "convex/values";
+ * import { syncedTable } from "@fatagnus/dink-convex";
+ *
+ * export default defineSchema({
+ *   tasks: syncedTable({
+ *     text: v.string(),
+ *     isCompleted: v.boolean(),
+ *   }),
+ * });
+ * ```
+ */
+export declare function syncedTable<T extends ValidatorFields>(fields: T, config?: SyncedTableConfig): TableDefinition;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,kBAAkB;IAC7B;;;OAGG;;;;;;;;;QAED,mCAAmC;;QAEnC,gDAAgD;;QAEhD,oCAAoC;;QAEpC,mCAAmC;;QAEnC,uCAAuC;;QAEvC,oDAAoD;;;;;;;IAOtD;;;;OAIG;;;;;;;;;;;QAED,mCAAmC;;QAEnC,gDAAgD;;QAEhD,+BAA+B;;QAE/B,wCAAwC;;QAExC,4CAA4C;;QAE5C,+BAA+B;;QAE/B,sCAAsC;;QAEtC,gDAAgD;;;;;;;IAOlD;;OAEG;;;;;;;QAED,gCAAgC;;QAEhC,8BAA8B;;QAE9B,wDAAwD;;QAExD,6CAA6C;;;;;;IAM/C;;OAEG;;;;;QAED,mCAAmC;;QAEnC,kDAAkD;;;;;CAG5C,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAQD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAEpD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAED;;GAEG;AACH,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;GAGG;AAEH,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,eAAe,EACnD,MAAM,EAAE,CAAC,EACT,MAAM,CAAC,EAAE,iBAAiB,GACzB,eAAe,CAcjB"}

package/dist/schema.js

@@ -0,0 +1,195 @@
+/**
+ * Schema helpers for defining synced tables.
+ *
+ * Provides:
+ * - `syncedTable` helper that wraps table definitions to enable automatic sync
+ * - `internalSyncSchema` that users spread into their schema for internal sync tables
+ *
+ * @module schema
+ */
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+/**
+ * Internal sync tables schema.
+ *
+ * These tables are required by the @fatagnus/dink-convex sync system.
+ * Spread this into your app's schema to include all internal tables:
+ *
+ * @example
+ * ```typescript
+ * // convex/schema.ts
+ * import { defineSchema } from "convex/server";
+ * import { syncedTable, internalSyncSchema } from "@fatagnus/dink-convex";
+ *
+ * export default defineSchema({
+ *   // Your synced tables
+ *   tasks: syncedTable({ title: v.string(), completed: v.boolean() }),
+ *
+ *   // Spread internal sync tables (required)
+ *   ...internalSyncSchema,
+ * });
+ * ```
+ *
+ * ## Why These Tables Are in Your Schema (Not Hidden in the Component)
+ *
+ * You might wonder why `@fatagnus/dink-convex` requires spreading these tables into your
+ * schema rather than hiding them entirely inside the component. This is due to
+ * a fundamental Convex constraint:
+ *
+ * **Convex mutations cannot call `ctx.runMutation()` to invoke other mutations.**
+ *
+ * This matters because:
+ * 1. Sync triggers run inside your mutation context (via convex-helpers Triggers)
+ * 2. Triggers must write delta/outbox records atomically in the same transaction
+ * 3. Component-internal tables can only be written via component mutations
+ * 4. Since triggers can't call component mutations, tables must be in app schema
+ *
+ * This ensures atomicity: your data changes and sync metadata are written together.
+ * If we used actions instead, a failure after your mutation but before recording
+ * the delta would leave data that never syncs.
+ *
+ * The practical impact is minimal - just one spread line in your schema. You never
+ * interact with these tables directly; they're managed entirely by the sync system.
+ */
+export const internalSyncSchema = {
+    /**
+     * sync_deltas - Stores CRDT delta updates for sync operations.
+     * Each delta represents a change that needs to be synchronized.
+     */
+    sync_deltas: defineTable({
+        /** Collection name (user table) */
+        collection: v.string(),
+        /** Document sync ID (syncId from user table) */
+        docId: v.string(),
+        /** CRDT delta bytes (Yjs update) */
+        bytes: v.bytes(),
+        /** Sequence number for ordering */
+        seq: v.number(),
+        /** Timestamp when delta was created */
+        timestamp: v.number(),
+        /** Edge ID that originated this delta (optional) */
+        edgeId: v.optional(v.string()),
+    })
+        .index("by_collection", ["collection"])
+        .index("by_docId", ["collection", "docId"])
+        .index("by_seq", ["collection", "seq"]),
+    /**
+     * sync_outbox - Queue of deltas pending push to dinkd.
+     * Deltas are queued here when triggers fire, then processed by
+     * the scheduled outbox processor which pushes them to dinkd.
+     */
+    sync_outbox: defineTable({
+        /** Collection name (user table) */
+        collection: v.string(),
+        /** Document sync ID (syncId from user table) */
+        docId: v.string(),
+        /** CRDT delta bytes to send */
+        delta: v.bytes(),
+        /** Sequence number for deduplication */
+        seq: v.number(),
+        /** Status: "pending" | "sent" | "failed" */
+        status: v.string(),
+        /** Number of retry attempts */
+        retries: v.number(),
+        /** Timestamp when item was created */
+        createdAt: v.number(),
+        /** Timestamp of last send attempt (optional) */
+        lastAttempt: v.optional(v.number()),
+    })
+        .index("by_status", ["status"])
+        .index("by_collection", ["collection"])
+        .index("by_docId_seq", ["docId", "seq"]),
+    /**
+     * sync_sessions - Tracks connected sessions and their sync state.
+     */
+    sync_sessions: defineTable({
+        /** Unique session identifier */
+        sessionId: v.string(),
+        /** Collection being synced */
+        collection: v.string(),
+        /** Last sequence number acknowledged by this session */
+        lastSeq: v.number(),
+        /** Timestamp when session was last active */
+        lastSeen: v.number(),
+    })
+        .index("by_sessionId", ["sessionId"])
+        .index("by_collection", ["collection"]),
+    /**
+     * sync_config - Configuration for which tables have sync enabled.
+     */
+    sync_config: defineTable({
+        /** Collection name (user table) */
+        collection: v.string(),
+        /** Whether sync is enabled for this collection */
+        enabled: v.boolean(),
+    }).index("by_collection", ["collection"]),
+};
+/**
+ * Registry of table names that use syncedTable().
+ * Used during installation to auto-register collections in _sync_config.
+ */
+const registeredSyncedTables = new Set();
+/**
+ * Register a table name as a synced table.
+ * Called internally or by developers to track which tables need sync enabled.
+ *
+ * @param tableName - The name of the table to register
+ */
+export function registerSyncedTableName(tableName) {
+    registeredSyncedTables.add(tableName);
+}
+/**
+ * Get all registered synced table names.
+ * Used during installation to auto-enable sync for all registered tables.
+ *
+ * @returns Array of registered table names
+ */
+export function getRegisteredSyncedTables() {
+    return Array.from(registeredSyncedTables);
+}
+/**
+ * Clear all registered synced tables.
+ * Useful for testing.
+ */
+export function clearRegisteredSyncedTables() {
+    registeredSyncedTables.clear();
+}
+/**
+ * Creates a synced Convex table definition with sync-related fields and indexes.
+ *
+ * This helper automatically adds:
+ * - A sync ID field (default: syncId) for tracking document sync state
+ * - An index on the sync ID field for efficient sync queries
+ *
+ * @param fields - The field validators for the table (same as what you'd pass to defineTable)
+ * @param config - Optional configuration for sync behavior
+ * @returns A table definition with sync fields and indexes included
+ *
+ * @example
+ * ```typescript
+ * import { defineSchema } from "convex/server";
+ * import { v } from "convex/values";
+ * import { syncedTable } from "@fatagnus/dink-convex";
+ *
+ * export default defineSchema({
+ *   tasks: syncedTable({
+ *     text: v.string(),
+ *     isCompleted: v.boolean(),
+ *   }),
+ * });
+ * ```
+ */
+export function syncedTable(fields, config) {
+    // Use "syncId" without underscore prefix since Convex doesn't allow reserved fields in indexes
+    const syncIdField = config?.syncIdField ?? "syncId";
+    const indexName = `by_${syncIdField}`;
+    // Create table with original fields plus sync ID field
+    const extendedFields = {
+        ...fields,
+        [syncIdField]: v.optional(v.string()),
+    };
+    // Create table definition using Convex's defineTable and add the sync index
+    // Cast to any to work around strict typing on index fields
+    return defineTable(extendedFields).index(indexName, [syncIdField]);
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/syncFactories.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Sync factories for @fatagnus/dink-convex component.
+ *
+ * These factories create Convex function definitions using the user's
+ * _generated imports, keeping all complex logic in the package while
+ * reducing user boilerplate to ~5 lines per file.
+ *
+ * @module syncFactories
+ */
+import { httpRouter, cronJobs } from "convex/server";
+/**
+ * Convex mutation builder type from _generated/server.
+ */
+type MutationBuilder = <Args extends Record<string, unknown>, Returns>(def: {
+    args: Record<string, unknown>;
+    returns: unknown;
+    handler: (ctx: MutationCtx, args: Args) => Promise<Returns>;
+}) => unknown;
+/**
+ * Convex query builder type from _generated/server.
+ */
+type QueryBuilder = <Args extends Record<string, unknown>, Returns>(def: {
+    args: Record<string, unknown>;
+    returns: unknown;
+    handler: (ctx: QueryCtx, args: Args) => Promise<Returns>;
+}) => unknown;
+/**
+ * Convex internalAction builder type from _generated/server.
+ */
+type InternalActionBuilder = <Args extends Record<string, unknown>, Returns>(def: {
+    args: Record<string, unknown>;
+    returns: unknown;
+    handler: (ctx: ActionCtx, args: Args) => Promise<Returns>;
+}) => unknown;
+/**
+ * Convex internalMutation builder type from _generated/server.
+ */
+type InternalMutationBuilder = <Args extends Record<string, unknown>, Returns>(def: {
+    args: Record<string, unknown>;
+    returns: unknown;
+    handler: (ctx: MutationCtx, args: Args) => Promise<Returns>;
+}) => unknown;
+/**
+ * Convex internalQuery builder type from _generated/server.
+ */
+type InternalQueryBuilder = <Args extends Record<string, unknown>, Returns>(def: {
+    args: Record<string, unknown>;
+    returns: unknown;
+    handler: (ctx: QueryCtx, args: Args) => Promise<Returns>;
+}) => unknown;
+/**
+ * Convex httpAction builder type from _generated/server.
+ */
+type HttpActionBuilder = (handler: (ctx: ActionCtx, request: Request) => Promise<Response>) => unknown;
+/**
+ * Mutation context type.
+ */
+interface MutationCtx {
+    db: {
+        insert: (table: string, doc: Record<string, unknown>) => Promise<string>;
+        patch: (id: string, fields: Record<string, unknown>) => Promise<void>;
+        delete: (id: string) => Promise<void>;
+        query: (table: string) => {
+            order: (dir: "asc" | "desc") => {
+                first: () => Promise<Record<string, unknown> | null>;
+            };
+            withIndex: (indexName: string, queryFn: (q: {
+                eq: (field: string, value: unknown) => unknown;
+            }) => unknown) => {
+                first: () => Promise<Record<string, unknown> | null>;
+                collect: () => Promise<Array<Record<string, unknown>>>;
+            };
+            collect: () => Promise<Array<Record<string, unknown>>>;
+        };
+    };
+    scheduler: {
+        runAfter: (delay: number, fn: unknown, args: unknown) => Promise<unknown>;
+    };
+}
+/**
+ * Query context type.
+ */
+interface QueryCtx {
+    db: MutationCtx["db"];
+}
+/**
+ * Action context type.
+ */
+interface ActionCtx {
+    runQuery: (fn: unknown, args: unknown) => Promise<unknown>;
+    runMutation: (fn: unknown, args: unknown) => Promise<unknown>;
+}
+/**
+ * Input for createSyncMutations factory.
+ */
+export interface SyncMutationsInput {
+    /** mutation builder from _generated/server */
+    mutation: MutationBuilder;
+    /** query builder from _generated/server */
+    query: QueryBuilder;
+}
+/**
+ * Output from createSyncMutations factory.
+ */
+export interface SyncMutationsOutput {
+    applyDeltaFromEdge: unknown;
+    getDocumentState: unknown;
+    listDocuments: unknown;
+    listDocumentsPaginated: unknown;
+}
+/**
+ * Create sync mutations and queries.
+ *
+ * Returns the Convex function definitions for handling CRDT delta operations.
+ * The applyDeltaFromEdge mutation skips outbox queueing to prevent sync loops.
+ *
+ * @param input - Object containing mutation and query builders from _generated/server
+ * @returns Object with applyDeltaFromEdge, getDocumentState, listDocuments, listDocumentsPaginated
+ *
+ * @example
+ * ```typescript
+ * // convex/sync.ts (~5 lines!)
+ * import { createSyncMutations } from "@fatagnus/dink-convex";
+ * import { mutation, query } from "./_generated/server";
+ *
+ * export const { applyDeltaFromEdge, getDocumentState, listDocuments, listDocumentsPaginated } =
+ *   createSyncMutations({ mutation, query });
+ * ```
+ */
+export declare function createSyncMutations(input: SyncMutationsInput): SyncMutationsOutput;
+/**
+ * Input for createOutboxProcessor factory.
+ */
+export interface OutboxProcessorInput {
+    /** internalAction builder from _generated/server */
+    internalAction: InternalActionBuilder;
+    /** internalMutation builder from _generated/server */
+    internalMutation: InternalMutationBuilder;
+    /** internalQuery builder from _generated/server */
+    internalQuery: InternalQueryBuilder;
+    /** internal API from _generated/api */
+    internal: {
+        outboxProcessor: {
+            queryPendingItems: unknown;
+            updateItemStatus: unknown;
+            processOutboxBatch: unknown;
+        };
+    };
+}
+/**
+ * Output from createOutboxProcessor factory.
+ */
+export interface OutboxProcessorOutput {
+    processOutboxBatch: unknown;
+    queryPendingItems: unknown;
+    updateItemStatus: unknown;
+    scheduleOutboxProcessing: unknown;
+}
+/**
+ * Create outbox processor functions.
+ *
+ * Returns Convex function definitions for processing the sync_outbox table
+ * and pushing deltas to dinkd.
+ *
+ * @param input - Object containing internalAction, internalMutation, internalQuery, and internal API
+ * @returns Object with processOutboxBatch, queryPendingItems, updateItemStatus, scheduleOutboxProcessing
+ *
+ * @example
+ * ```typescript
+ * // convex/outboxProcessor.ts (~5 lines!)
+ * import { createOutboxProcessor } from "@fatagnus/dink-convex";
+ * import { internalAction, internalMutation, internalQuery } from "./_generated/server";
+ * import { internal } from "./_generated/api";
+ *
+ * export const { processOutboxBatch, queryPendingItems, updateItemStatus, scheduleOutboxProcessing } =
+ *   createOutboxProcessor({ internalAction, internalMutation, internalQuery, internal });
+ * ```
+ */
+export declare function createOutboxProcessor(input: OutboxProcessorInput): OutboxProcessorOutput;
+/**
+ * Input for createSyncHttpRouter factory.
+ */
+export interface SyncHttpRouterInput {
+    /** httpAction builder from _generated/server */
+    httpAction: HttpActionBuilder;
+    /** api from _generated/api */
+    api: {
+        sync: {
+            applyDeltaFromEdge: unknown;
+        };
+    };
+}
+/**
+ * Create sync HTTP router with /dink/applyDelta endpoint.
+ *
+ * @param input - Object containing httpAction builder and api
+ * @returns HTTP router to export as default
+ *
+ * @example
+ * ```typescript
+ * // convex/http.ts (~5 lines!)
+ * import { createSyncHttpRouter } from "@fatagnus/dink-convex";
+ * import { httpAction } from "./_generated/server";
+ * import { api } from "./_generated/api";
+ *
+ * export default createSyncHttpRouter({ httpAction, api });
+ * ```
+ */
+export declare function createSyncHttpRouter(input: SyncHttpRouterInput): ReturnType<typeof httpRouter>;
+/**
+ * Input for createSyncCrons factory.
+ */
+export interface SyncCronsInput {
+    /** internal API from _generated/api */
+    internal: {
+        outboxProcessor: {
+            processOutboxBatch: unknown;
+        };
+    };
+    /** Cron interval in minutes (default: 1) */
+    intervalMinutes?: number;
+}
+/**
+ * Create sync cron jobs for outbox processing.
+ *
+ * @param input - Object containing internal API
+ * @returns Cron jobs to export as default
+ *
+ * @example
+ * ```typescript
+ * // convex/crons.ts (~4 lines!)
+ * import { createSyncCrons } from "@fatagnus/dink-convex";
+ * import { internal } from "./_generated/api";
+ *
+ * export default createSyncCrons({ internal });
+ * ```
+ */
+export declare function createSyncCrons(input: SyncCronsInput): ReturnType<typeof cronJobs>;
+export {};
+//# sourceMappingURL=syncFactories.d.ts.map

package/dist/syncFactories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncFactories.d.ts","sourceRoot":"","sources":["../src/syncFactories.ts"],"names":[],"mappings":"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"}