@fatagnus/dink-convex 1.0.0

package/convex/http.ts

@@ -0,0 +1,421 @@
+/**
+ * HTTP endpoints for dinkd communication.
+ *
+ * Provides the /api/dink/applyDelta and /api/dink/getSnapshot endpoints
+ * for bidirectional sync with edge devices via dinkd.
+ *
+ * @module convex/http
+ */
+
+import { httpRouter } from "convex/server";
+import { httpAction } from "./_generated/server";
+import { api } from "./_generated/api";
+
+const http = httpRouter();
+
+/**
+ * POST /api/dink/applyDelta
+ *
+ * Receives CRDT deltas from edge devices and merges them into
+ * the target user table. Skips outbox queueing to prevent sync loops.
+ *
+ * Request:
+ * - Authorization: Bearer <appSyncKey>
+ * - Body: { collection: string, docId: string, bytes: number[] }
+ *
+ * Response:
+ * - 200: { success: true, seq: number }
+ * - 400: { success: false, error: string } - Invalid payload
+ * - 401: { success: false, error: string } - Unauthorized
+ * - 500: { success: false, error: string } - Server error
+ */
+http.route({
+  path: "/api/dink/applyDelta",
+  method: "POST",
+  handler: httpAction(async (ctx, request) => {
+    // Validate Authorization header
+    const authHeader = request.headers.get("Authorization");
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing or invalid Authorization header",
+        }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    const token = authHeader.slice(7).trim();
+    if (!token) {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing authorization token",
+        }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // Parse request body
+    let payload: { collection?: string; docId?: string; bytes?: number[]; edgeId?: string };
+    try {
+      payload = await request.json();
+    } catch {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Invalid JSON payload",
+        }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // Validate payload
+    if (!payload.collection || typeof payload.collection !== "string") {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing or invalid collection field",
+        }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    if (!payload.docId || typeof payload.docId !== "string") {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing or invalid docId field",
+        }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    if (!Array.isArray(payload.bytes)) {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing or invalid bytes field",
+        }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // Convert bytes array to ArrayBuffer for Convex
+    const bytes = new Uint8Array(payload.bytes).buffer;
+
+    try {
+      // Call the internal mutation that skips outbox
+      // The mutation uses ctx.db directly (not wrapped with triggers)
+      // to prevent sync loops back to edge
+      const result = await ctx.runMutation(api.sync.applyDeltaFromEdge, {
+        collection: payload.collection,
+        docId: payload.docId,
+        bytes,
+        authToken: token,
+        edgeId: payload.edgeId,
+      });
+
+      return new Response(
+        JSON.stringify({
+          success: true,
+          seq: result.seq,
+        }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: message,
+        }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+  }),
+});
+
+/**
+ * GET /api/dink/getSnapshot
+ *
+ * Returns the current document state as a Yjs snapshot for edge clients
+ * to bootstrap their local state or reconnect after disconnection.
+ *
+ * Query Parameters:
+ * - collection: string - The collection/table name
+ * - docId: string - The document sync ID
+ *
+ * Headers:
+ * - Authorization: Bearer <appSyncKey>
+ *
+ * Response:
+ * - 200: { success: true, bytes: number[], seq: number }
+ * - 400: { success: false, error: string } - Invalid parameters
+ * - 401: { success: false, error: string } - Unauthorized
+ * - 404: { success: false, error: string } - Document not found
+ * - 500: { success: false, error: string } - Server error
+ */
+http.route({
+  path: "/api/dink/getSnapshot",
+  method: "GET",
+  handler: httpAction(async (ctx, request) => {
+    // Validate Authorization header
+    const authHeader = request.headers.get("Authorization");
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing or invalid Authorization header",
+        }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    const token = authHeader.slice(7).trim();
+    if (!token) {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing authorization token",
+        }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // Parse query parameters
+    const url = new URL(request.url);
+    const collection = url.searchParams.get("collection");
+    const docId = url.searchParams.get("docId");
+
+    // Validate query parameters
+    if (!collection || typeof collection !== "string") {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing or invalid collection parameter",
+        }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    if (!docId || typeof docId !== "string") {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing or invalid docId parameter",
+        }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    try {
+      // Query the document state
+      const result = await ctx.runQuery(api.sync.getDocumentState, {
+        collection,
+        docId,
+      });
+
+      // Return 404 if document not found
+      if (!result) {
+        return new Response(
+          JSON.stringify({
+            success: false,
+            error: "Document not found",
+          }),
+          {
+            status: 404,
+            headers: { "Content-Type": "application/json" },
+          }
+        );
+      }
+
+      // Convert ArrayBuffer to number array for JSON serialization
+      const bytes = Array.from(new Uint8Array(result.bytes));
+
+      return new Response(
+        JSON.stringify({
+          success: true,
+          bytes,
+          seq: result.seq,
+        }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: message,
+        }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+  }),
+});
+
+/**
+ * GET /api/dink/listDocuments
+ *
+ * Returns a list of document IDs (syncId values) in a collection.
+ * Supports pagination via cursor parameter.
+ *
+ * Query Parameters:
+ * - collection: string - The collection/table name
+ * - cursor: string (optional) - Pagination cursor
+ * - limit: number (optional) - Max results per page (default: 100)
+ *
+ * Headers:
+ * - Authorization: Bearer <appSyncKey>
+ *
+ * Response:
+ * - 200: { success: true, docIds: string[], nextCursor?: string }
+ * - 400: { success: false, error: string } - Invalid parameters
+ * - 401: { success: false, error: string } - Unauthorized
+ * - 500: { success: false, error: string } - Server error
+ */
+http.route({
+  path: "/api/dink/listDocuments",
+  method: "GET",
+  handler: httpAction(async (ctx, request) => {
+    // Validate Authorization header
+    const authHeader = request.headers.get("Authorization");
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing or invalid Authorization header",
+        }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    const token = authHeader.slice(7).trim();
+    if (!token) {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing authorization token",
+        }),
+        {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // Parse query parameters
+    const url = new URL(request.url);
+    const collection = url.searchParams.get("collection");
+    const cursor = url.searchParams.get("cursor") || undefined;
+    const limitParam = url.searchParams.get("limit");
+    const limit = limitParam ? parseInt(limitParam, 10) : 100;
+
+    // Validate query parameters
+    if (!collection || typeof collection !== "string") {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Missing or invalid collection parameter",
+        }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    if (isNaN(limit) || limit < 1) {
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: "Invalid limit parameter",
+        }),
+        {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    try {
+      // Query the document list
+      const result = await ctx.runQuery(api.sync.listDocumentsPaginated, {
+        collection,
+        cursor,
+        limit,
+      });
+
+      return new Response(
+        JSON.stringify({
+          success: true,
+          docIds: result.docIds,
+          nextCursor: result.nextCursor,
+        }),
+        {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return new Response(
+        JSON.stringify({
+          success: false,
+          error: message,
+        }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+  }),
+});
+
+export default http;

package/convex/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @fatagnus/dink-convex - Internal Convex Functions
+ *
+ * This directory contains the component's internal Convex code including:
+ * - Internal sync tables schema
+ * - HTTP endpoints for dinkd communication
+ * - Scheduled functions for outbox processing
+ * - Trigger setup for intercepting writes
+ *
+ * @packageDocumentation
+ */
+
+// Placeholder exports - will be implemented in subsequent stories
+// US-003: Schema
+// US-004: Triggers
+// US-006-008: HTTP endpoints
+// US-009: Scheduled functions
+
+export const COMPONENT_NAME = "@fatagnus/dink-convex";
+export const COMPONENT_VERSION = "0.1.0";

package/convex/install.ts

@@ -0,0 +1,172 @@
+/**
+ * Installation and configuration mutations for @fatagnus/dink-convex component.
+ *
+ * Provides functions to enable/disable sync for specific collections
+ * by managing the _sync_config table.
+ *
+ * @module convex/install
+ */
+
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+
+/**
+ * Enable sync for a collection.
+ *
+ * Registers the collection in _sync_config with enabled=true.
+ * If the collection is already registered, updates it to enabled.
+ *
+ * @param collection - The name of the collection/table to enable sync for
+ * @returns Object with success status
+ */
+export const enableSync = mutation({
+  args: {
+    collection: v.string(),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    message: v.string(),
+  }),
+  handler: async (ctx, args) => {
+    // Check if collection already exists in _sync_config
+    const existing = await ctx.db
+      .query("sync_config")
+      .withIndex("by_collection", (q) => q.eq("collection", args.collection))
+      .first();
+
+    if (existing) {
+      // Update existing config to enabled
+      if (!existing.enabled) {
+        await ctx.db.patch(existing._id, { enabled: true });
+        return {
+          success: true,
+          message: `Sync enabled for collection: ${args.collection}`,
+        };
+      }
+      return {
+        success: true,
+        message: `Sync already enabled for collection: ${args.collection}`,
+      };
+    }
+
+    // Create new config entry
+    await ctx.db.insert("sync_config", {
+      collection: args.collection,
+      enabled: true,
+    });
+
+    return {
+      success: true,
+      message: `Sync enabled for collection: ${args.collection}`,
+    };
+  },
+});
+
+/**
+ * Disable sync for a collection.
+ *
+ * Updates the collection's _sync_config entry to enabled=false.
+ * Does not delete the config entry to preserve history.
+ *
+ * @param collection - The name of the collection/table to disable sync for
+ * @returns Object with success status
+ */
+export const disableSync = mutation({
+  args: {
+    collection: v.string(),
+  },
+  returns: v.object({
+    success: v.boolean(),
+    message: v.string(),
+  }),
+  handler: async (ctx, args) => {
+    // Check if collection exists in _sync_config
+    const existing = await ctx.db
+      .query("sync_config")
+      .withIndex("by_collection", (q) => q.eq("collection", args.collection))
+      .first();
+
+    if (!existing) {
+      return {
+        success: false,
+        message: `Collection not found in sync config: ${args.collection}`,
+      };
+    }
+
+    if (!existing.enabled) {
+      return {
+        success: true,
+        message: `Sync already disabled for collection: ${args.collection}`,
+      };
+    }
+
+    // Update to disabled
+    await ctx.db.patch(existing._id, { enabled: false });
+
+    return {
+      success: true,
+      message: `Sync disabled for collection: ${args.collection}`,
+    };
+  },
+});
+
+/**
+ * Get sync status for a collection.
+ *
+ * Queries _sync_config to determine if sync is enabled for the collection.
+ *
+ * @param collection - The name of the collection/table to check
+ * @returns Object with enabled status, or null if not configured
+ */
+export const getSyncStatus = query({
+  args: {
+    collection: v.string(),
+  },
+  returns: v.union(
+    v.object({
+      collection: v.string(),
+      enabled: v.boolean(),
+    }),
+    v.null()
+  ),
+  handler: async (ctx, args) => {
+    const config = await ctx.db
+      .query("sync_config")
+      .withIndex("by_collection", (q) => q.eq("collection", args.collection))
+      .first();
+
+    if (!config) {
+      return null;
+    }
+
+    return {
+      collection: config.collection,
+      enabled: config.enabled,
+    };
+  },
+});
+
+/**
+ * List all collections with sync configuration.
+ *
+ * Returns all collections in _sync_config with their enabled status.
+ *
+ * @returns Array of collection configs
+ */
+export const listSyncedCollections = query({
+  args: {},
+  returns: v.array(
+    v.object({
+      collection: v.string(),
+      enabled: v.boolean(),
+    })
+  ),
+  handler: async (ctx) => {
+    const configs = await ctx.db.query("sync_config").collect();
+
+    return configs.map((config) => ({
+      collection: config.collection,
+      enabled: config.enabled,
+    }));
+  },
+});