@l4yercak3/cli 1.2.16 → 1.2.19

package/src/generators/quickstart/database/convex.js

@@ -0,0 +1,1257 @@
+/**
+ * Convex Database Generator
+ * Generates Convex schema, queries, and mutations for L4YERCAK3 integration
+ */
+
+const path = require('path');
+const { ensureDir, writeFileWithBackup, checkFileOverwrite } = require('../../../utils/file-utils');
+
+class ConvexGenerator {
+  /**
+   * Generate Convex database files
+   * @param {Object} options - Generation options
+   * @returns {Promise<Object>} - Generated file paths
+   */
+  async generate(options) {
+    const { projectPath, features = [] } = options;
+
+    const results = {
+      schema: null,
+      objects: null,
+      frontendUsers: null,
+      sync: null,
+      http: null,
+    };
+
+    const convexDir = path.join(projectPath, 'convex');
+    ensureDir(convexDir);
+
+    // Generate schema.ts
+    results.schema = await this.generateSchema(convexDir, features);
+
+    // Generate objects.ts (queries/mutations for universal objects)
+    results.objects = await this.generateObjects(convexDir);
+
+    // Generate frontendUsers.ts (auth-related queries/mutations)
+    if (features.includes('oauth')) {
+      results.frontendUsers = await this.generateFrontendUsers(convexDir);
+    }
+
+    // Generate sync.ts (L4YERCAK3 sync logic)
+    results.sync = await this.generateSync(convexDir);
+
+    // Generate http.ts (webhook endpoints)
+    results.http = await this.generateHttp(convexDir);
+
+    return results;
+  }
+
+  async generateSchema(convexDir, _features) {
+    const outputPath = path.join(convexDir, 'schema.ts');
+
+    const action = await checkFileOverwrite(outputPath);
+    if (action === 'skip') {
+      return null;
+    }
+
+    const content = `/**
+ * Convex Schema for L4YERCAK3 Integration
+ * Auto-generated by @l4yercak3/cli
+ *
+ * This schema follows the ontology-first pattern, mirroring
+ * L4YERCAK3's universal object structure for seamless sync.
+ */
+
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  // ============================================
+  // ONTOLOGY: Universal object storage
+  // ============================================
+
+  objects: defineTable({
+    // L4YERCAK3 sync
+    l4yercak3Id: v.optional(v.string()),
+    organizationId: v.string(),
+
+    // Core fields (all objects have these)
+    type: v.string(), // "contact", "event", "form", "product", "order", etc.
+    subtype: v.optional(v.string()), // Type-specific classification
+    name: v.string(),
+    status: v.string(),
+
+    // Type-specific data stored as JSON
+    customProperties: v.any(),
+
+    // Sync tracking
+    syncStatus: v.union(
+      v.literal("synced"),
+      v.literal("pending_push"),
+      v.literal("pending_pull"),
+      v.literal("conflict"),
+      v.literal("local_only")
+    ),
+    syncedAt: v.optional(v.number()),
+    localVersion: v.number(),
+    remoteVersion: v.optional(v.number()),
+
+    // Timestamps
+    createdAt: v.number(),
+    updatedAt: v.number(),
+    deletedAt: v.optional(v.number()), // Soft delete
+  })
+    .index("by_l4yercak3_id", ["l4yercak3Id"])
+    .index("by_type", ["type"])
+    .index("by_type_status", ["type", "status"])
+    .index("by_type_subtype", ["type", "subtype"])
+    .index("by_sync_status", ["syncStatus"])
+    .index("by_organization", ["organizationId"])
+    .index("by_updated", ["updatedAt"]),
+
+  // Relationships between objects
+  objectLinks: defineTable({
+    l4yercak3Id: v.optional(v.string()),
+    fromObjectId: v.id("objects"),
+    toObjectId: v.id("objects"),
+    linkType: v.string(), // "attendee", "sponsor", "submission", etc.
+    metadata: v.optional(v.any()),
+    syncStatus: v.string(),
+    createdAt: v.number(),
+  })
+    .index("by_from", ["fromObjectId"])
+    .index("by_to", ["toObjectId"])
+    .index("by_from_type", ["fromObjectId", "linkType"])
+    .index("by_to_type", ["toObjectId", "linkType"]),
+
+  // ============================================
+  // AUTHENTICATION: Local user management
+  // ============================================
+
+  frontendUsers: defineTable({
+    // L4YERCAK3 sync - users become CRM contacts
+    l4yercak3ContactId: v.optional(v.string()),
+    l4yercak3FrontendUserId: v.optional(v.string()),
+    organizationId: v.string(),
+
+    // Core identity
+    email: v.string(),
+    emailVerified: v.boolean(),
+    name: v.optional(v.string()),
+    firstName: v.optional(v.string()),
+    lastName: v.optional(v.string()),
+    image: v.optional(v.string()),
+    phone: v.optional(v.string()),
+
+    // Local auth (stored securely, never synced)
+    passwordHash: v.optional(v.string()),
+
+    // OAuth accounts (stored locally)
+    oauthAccounts: v.array(
+      v.object({
+        provider: v.string(),
+        providerAccountId: v.string(),
+        accessToken: v.optional(v.string()),
+        refreshToken: v.optional(v.string()),
+        expiresAt: v.optional(v.number()),
+        scope: v.optional(v.string()),
+      })
+    ),
+
+    // App-specific
+    role: v.string(), // "user", "admin", "moderator"
+    preferences: v.optional(
+      v.object({
+        language: v.optional(v.string()),
+        timezone: v.optional(v.string()),
+        theme: v.optional(v.string()),
+        emailNotifications: v.optional(v.boolean()),
+      })
+    ),
+
+    // Sync
+    syncStatus: v.string(),
+    syncedAt: v.optional(v.number()),
+
+    // Timestamps
+    createdAt: v.number(),
+    updatedAt: v.number(),
+    lastLoginAt: v.optional(v.number()),
+  })
+    .index("by_email", ["email"])
+    .index("by_l4yercak3_contact", ["l4yercak3ContactId"])
+    .index("by_organization", ["organizationId"]),
+
+  // Sessions for auth
+  sessions: defineTable({
+    userId: v.id("frontendUsers"),
+    sessionToken: v.string(),
+    expiresAt: v.number(),
+    userAgent: v.optional(v.string()),
+    ipAddress: v.optional(v.string()),
+    createdAt: v.number(),
+  })
+    .index("by_token", ["sessionToken"])
+    .index("by_user", ["userId"]),
+
+  // ============================================
+  // STRIPE: Local payment handling
+  // ============================================
+
+  stripeCustomers: defineTable({
+    frontendUserId: v.id("frontendUsers"),
+    stripeCustomerId: v.string(),
+    l4yercak3ContactId: v.optional(v.string()),
+    email: v.string(),
+    name: v.optional(v.string()),
+    defaultPaymentMethodId: v.optional(v.string()),
+    syncStatus: v.string(),
+    createdAt: v.number(),
+  })
+    .index("by_stripe_id", ["stripeCustomerId"])
+    .index("by_user", ["frontendUserId"]),
+
+  stripePayments: defineTable({
+    stripePaymentIntentId: v.string(),
+    stripeCustomerId: v.optional(v.string()),
+    frontendUserId: v.optional(v.id("frontendUsers")),
+
+    // Payment details
+    amount: v.number(),
+    currency: v.string(),
+    status: v.string(),
+    paymentMethod: v.optional(v.string()),
+
+    // What was purchased
+    metadata: v.object({
+      type: v.string(), // "event_ticket", "product", "subscription"
+      items: v.array(
+        v.object({
+          objectId: v.optional(v.id("objects")),
+          l4yercak3ProductId: v.optional(v.string()),
+          name: v.string(),
+          quantity: v.number(),
+          priceInCents: v.number(),
+        })
+      ),
+      eventId: v.optional(v.string()),
+    }),
+
+    // L4YERCAK3 sync
+    l4yercak3OrderId: v.optional(v.string()),
+    l4yercak3InvoiceId: v.optional(v.string()),
+    syncStatus: v.string(),
+    syncedAt: v.optional(v.number()),
+
+    // Timestamps
+    createdAt: v.number(),
+    completedAt: v.optional(v.number()),
+  })
+    .index("by_stripe_id", ["stripePaymentIntentId"])
+    .index("by_customer", ["stripeCustomerId"])
+    .index("by_user", ["frontendUserId"])
+    .index("by_sync_status", ["syncStatus"]),
+
+  // ============================================
+  // SYNC: Job tracking
+  // ============================================
+
+  syncJobs: defineTable({
+    entityType: v.string(),
+    direction: v.union(
+      v.literal("push"),
+      v.literal("pull"),
+      v.literal("bidirectional")
+    ),
+    status: v.union(
+      v.literal("pending"),
+      v.literal("running"),
+      v.literal("completed"),
+      v.literal("failed")
+    ),
+
+    cursor: v.optional(v.string()),
+    processedCount: v.number(),
+    totalCount: v.optional(v.number()),
+
+    errorMessage: v.optional(v.string()),
+    errorDetails: v.optional(v.any()),
+
+    startedAt: v.number(),
+    completedAt: v.optional(v.number()),
+  })
+    .index("by_status", ["status"])
+    .index("by_entity", ["entityType"]),
+
+  syncConflicts: defineTable({
+    objectId: v.id("objects"),
+    localVersion: v.any(),
+    remoteVersion: v.any(),
+    conflictType: v.string(), // "update_conflict", "delete_conflict"
+    resolvedAt: v.optional(v.number()),
+    resolution: v.optional(v.string()), // "local_wins", "remote_wins", "merged"
+    createdAt: v.number(),
+  })
+    .index("by_object", ["objectId"])
+    .index("by_unresolved", ["resolvedAt"]),
+});
+`;
+
+    return writeFileWithBackup(outputPath, content, action);
+  }
+
+  async generateObjects(convexDir) {
+    const outputPath = path.join(convexDir, 'objects.ts');
+
+    const action = await checkFileOverwrite(outputPath);
+    if (action === 'skip') {
+      return null;
+    }
+
+    const content = `/**
+ * Convex Objects Queries and Mutations
+ * Auto-generated by @l4yercak3/cli
+ *
+ * Universal object operations for the ontology-first pattern.
+ */
+
+import { v } from "convex/values";
+import { query, mutation } from "./_generated/server";
+
+// ============ Queries ============
+
+export const list = query({
+  args: {
+    type: v.string(),
+    status: v.optional(v.string()),
+    subtype: v.optional(v.string()),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    let q = ctx.db
+      .query("objects")
+      .withIndex("by_type", (q) => q.eq("type", args.type));
+
+    const objects = await q.collect();
+
+    // Filter by status/subtype if provided
+    let filtered = objects.filter((o) => !o.deletedAt);
+    if (args.status) {
+      filtered = filtered.filter((o) => o.status === args.status);
+    }
+    if (args.subtype) {
+      filtered = filtered.filter((o) => o.subtype === args.subtype);
+    }
+
+    // Sort by updatedAt descending
+    filtered.sort((a, b) => b.updatedAt - a.updatedAt);
+
+    // Apply limit
+    if (args.limit) {
+      filtered = filtered.slice(0, args.limit);
+    }
+
+    return filtered;
+  },
+});
+
+export const get = query({
+  args: { id: v.id("objects") },
+  handler: async (ctx, args) => {
+    return ctx.db.get(args.id);
+  },
+});
+
+export const getByL4yercak3Id = query({
+  args: { l4yercak3Id: v.string() },
+  handler: async (ctx, args) => {
+    return ctx.db
+      .query("objects")
+      .withIndex("by_l4yercak3_id", (q) => q.eq("l4yercak3Id", args.l4yercak3Id))
+      .first();
+  },
+});
+
+export const search = query({
+  args: {
+    type: v.string(),
+    searchTerm: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const objects = await ctx.db
+      .query("objects")
+      .withIndex("by_type", (q) => q.eq("type", args.type))
+      .collect();
+
+    const term = args.searchTerm.toLowerCase();
+    return objects.filter(
+      (o) =>
+        !o.deletedAt &&
+        (o.name.toLowerCase().includes(term) ||
+          JSON.stringify(o.customProperties).toLowerCase().includes(term))
+    );
+  },
+});
+
+// ============ Mutations ============
+
+export const create = mutation({
+  args: {
+    type: v.string(),
+    subtype: v.optional(v.string()),
+    name: v.string(),
+    status: v.string(),
+    customProperties: v.any(),
+    organizationId: v.string(),
+    l4yercak3Id: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    const id = await ctx.db.insert("objects", {
+      type: args.type,
+      subtype: args.subtype,
+      name: args.name,
+      status: args.status,
+      customProperties: args.customProperties,
+      organizationId: args.organizationId,
+      l4yercak3Id: args.l4yercak3Id,
+      syncStatus: args.l4yercak3Id ? "synced" : "local_only",
+      syncedAt: args.l4yercak3Id ? now : undefined,
+      localVersion: 1,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    return id;
+  },
+});
+
+export const update = mutation({
+  args: {
+    id: v.id("objects"),
+    name: v.optional(v.string()),
+    status: v.optional(v.string()),
+    subtype: v.optional(v.string()),
+    customProperties: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db.get(args.id);
+    if (!existing) {
+      throw new Error("Object not found");
+    }
+
+    const updates: Record<string, unknown> = {
+      updatedAt: Date.now(),
+      localVersion: existing.localVersion + 1,
+    };
+
+    if (args.name !== undefined) updates.name = args.name;
+    if (args.status !== undefined) updates.status = args.status;
+    if (args.subtype !== undefined) updates.subtype = args.subtype;
+    if (args.customProperties !== undefined) {
+      updates.customProperties = {
+        ...existing.customProperties,
+        ...args.customProperties,
+      };
+    }
+
+    // Mark as pending push if it was previously synced
+    if (existing.syncStatus === "synced") {
+      updates.syncStatus = "pending_push";
+    }
+
+    await ctx.db.patch(args.id, updates);
+    return args.id;
+  },
+});
+
+export const remove = mutation({
+  args: { id: v.id("objects") },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db.get(args.id);
+    if (!existing) {
+      throw new Error("Object not found");
+    }
+
+    // Soft delete
+    await ctx.db.patch(args.id, {
+      deletedAt: Date.now(),
+      updatedAt: Date.now(),
+      syncStatus: existing.l4yercak3Id ? "pending_push" : "local_only",
+    });
+
+    return args.id;
+  },
+});
+
+// ============ Links ============
+
+export const createLink = mutation({
+  args: {
+    fromObjectId: v.id("objects"),
+    toObjectId: v.id("objects"),
+    linkType: v.string(),
+    metadata: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    const id = await ctx.db.insert("objectLinks", {
+      fromObjectId: args.fromObjectId,
+      toObjectId: args.toObjectId,
+      linkType: args.linkType,
+      metadata: args.metadata,
+      syncStatus: "local_only",
+      createdAt: Date.now(),
+    });
+
+    return id;
+  },
+});
+
+export const getLinks = query({
+  args: {
+    objectId: v.id("objects"),
+    linkType: v.optional(v.string()),
+    direction: v.optional(v.union(v.literal("from"), v.literal("to"))),
+  },
+  handler: async (ctx, args) => {
+    const direction = args.direction || "from";
+
+    let links;
+    if (direction === "from") {
+      links = await ctx.db
+        .query("objectLinks")
+        .withIndex("by_from", (q) => q.eq("fromObjectId", args.objectId))
+        .collect();
+    } else {
+      links = await ctx.db
+        .query("objectLinks")
+        .withIndex("by_to", (q) => q.eq("toObjectId", args.objectId))
+        .collect();
+    }
+
+    if (args.linkType) {
+      links = links.filter((l) => l.linkType === args.linkType);
+    }
+
+    return links;
+  },
+});
+
+// ============ Sync Helpers ============
+
+export const getPendingSync = query({
+  args: { direction: v.union(v.literal("push"), v.literal("pull")) },
+  handler: async (ctx, args) => {
+    const status = args.direction === "push" ? "pending_push" : "pending_pull";
+
+    return ctx.db
+      .query("objects")
+      .withIndex("by_sync_status", (q) => q.eq("syncStatus", status))
+      .collect();
+  },
+});
+
+export const markSynced = mutation({
+  args: {
+    id: v.id("objects"),
+    l4yercak3Id: v.string(),
+    remoteVersion: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.id, {
+      l4yercak3Id: args.l4yercak3Id,
+      syncStatus: "synced",
+      syncedAt: Date.now(),
+      remoteVersion: args.remoteVersion,
+    });
+  },
+});
+`;
+
+    return writeFileWithBackup(outputPath, content, action);
+  }
+
+  async generateFrontendUsers(convexDir) {
+    const outputPath = path.join(convexDir, 'frontendUsers.ts');
+
+    const action = await checkFileOverwrite(outputPath);
+    if (action === 'skip') {
+      return null;
+    }
+
+    const content = `/**
+ * Convex Frontend Users Queries and Mutations
+ * Auto-generated by @l4yercak3/cli
+ *
+ * Handles local user authentication and syncs users as CRM contacts.
+ */
+
+import { v } from "convex/values";
+import { query, mutation } from "./_generated/server";
+
+// ============ Queries ============
+
+export const getByEmail = query({
+  args: { email: v.string() },
+  handler: async (ctx, args) => {
+    return ctx.db
+      .query("frontendUsers")
+      .withIndex("by_email", (q) => q.eq("email", args.email))
+      .first();
+  },
+});
+
+export const get = query({
+  args: { id: v.id("frontendUsers") },
+  handler: async (ctx, args) => {
+    return ctx.db.get(args.id);
+  },
+});
+
+export const getBySession = query({
+  args: { sessionToken: v.string() },
+  handler: async (ctx, args) => {
+    const session = await ctx.db
+      .query("sessions")
+      .withIndex("by_token", (q) => q.eq("sessionToken", args.sessionToken))
+      .first();
+
+    if (!session || session.expiresAt < Date.now()) {
+      return null;
+    }
+
+    return ctx.db.get(session.userId);
+  },
+});
+
+// ============ Mutations ============
+
+export const create = mutation({
+  args: {
+    email: v.string(),
+    name: v.optional(v.string()),
+    firstName: v.optional(v.string()),
+    lastName: v.optional(v.string()),
+    image: v.optional(v.string()),
+    organizationId: v.string(),
+    role: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    // Check if user already exists
+    const existing = await ctx.db
+      .query("frontendUsers")
+      .withIndex("by_email", (q) => q.eq("email", args.email))
+      .first();
+
+    if (existing) {
+      throw new Error("User with this email already exists");
+    }
+
+    const now = Date.now();
+
+    const id = await ctx.db.insert("frontendUsers", {
+      email: args.email,
+      emailVerified: false,
+      name: args.name,
+      firstName: args.firstName,
+      lastName: args.lastName,
+      image: args.image,
+      organizationId: args.organizationId,
+      role: args.role || "user",
+      oauthAccounts: [],
+      syncStatus: "pending_push", // Will sync to L4YERCAK3 as CRM contact
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    return id;
+  },
+});
+
+export const update = mutation({
+  args: {
+    id: v.id("frontendUsers"),
+    name: v.optional(v.string()),
+    firstName: v.optional(v.string()),
+    lastName: v.optional(v.string()),
+    image: v.optional(v.string()),
+    phone: v.optional(v.string()),
+    preferences: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    const { id, ...updates } = args;
+
+    const existing = await ctx.db.get(id);
+    if (!existing) {
+      throw new Error("User not found");
+    }
+
+    await ctx.db.patch(id, {
+      ...updates,
+      updatedAt: Date.now(),
+      syncStatus: existing.l4yercak3ContactId ? "pending_push" : "pending_push",
+    });
+
+    return id;
+  },
+});
+
+export const linkOAuthAccount = mutation({
+  args: {
+    userId: v.id("frontendUsers"),
+    provider: v.string(),
+    providerAccountId: v.string(),
+    accessToken: v.optional(v.string()),
+    refreshToken: v.optional(v.string()),
+    expiresAt: v.optional(v.number()),
+    scope: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const user = await ctx.db.get(args.userId);
+    if (!user) {
+      throw new Error("User not found");
+    }
+
+    // Check if this OAuth account is already linked
+    const existingAccount = user.oauthAccounts.find(
+      (a) =>
+        a.provider === args.provider &&
+        a.providerAccountId === args.providerAccountId
+    );
+
+    let oauthAccounts;
+    if (existingAccount) {
+      // Update existing account
+      oauthAccounts = user.oauthAccounts.map((a) =>
+        a.provider === args.provider &&
+        a.providerAccountId === args.providerAccountId
+          ? {
+              provider: args.provider,
+              providerAccountId: args.providerAccountId,
+              accessToken: args.accessToken,
+              refreshToken: args.refreshToken,
+              expiresAt: args.expiresAt,
+              scope: args.scope,
+            }
+          : a
+      );
+    } else {
+      // Add new account
+      oauthAccounts = [
+        ...user.oauthAccounts,
+        {
+          provider: args.provider,
+          providerAccountId: args.providerAccountId,
+          accessToken: args.accessToken,
+          refreshToken: args.refreshToken,
+          expiresAt: args.expiresAt,
+          scope: args.scope,
+        },
+      ];
+    }
+
+    await ctx.db.patch(args.userId, {
+      oauthAccounts,
+      emailVerified: true, // OAuth email is verified
+      updatedAt: Date.now(),
+    });
+
+    return args.userId;
+  },
+});
+
+export const createSession = mutation({
+  args: {
+    userId: v.id("frontendUsers"),
+    sessionToken: v.string(),
+    expiresAt: v.number(),
+    userAgent: v.optional(v.string()),
+    ipAddress: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    // Update last login
+    await ctx.db.patch(args.userId, {
+      lastLoginAt: now,
+    });
+
+    const id = await ctx.db.insert("sessions", {
+      userId: args.userId,
+      sessionToken: args.sessionToken,
+      expiresAt: args.expiresAt,
+      userAgent: args.userAgent,
+      ipAddress: args.ipAddress,
+      createdAt: now,
+    });
+
+    return id;
+  },
+});
+
+export const deleteSession = mutation({
+  args: { sessionToken: v.string() },
+  handler: async (ctx, args) => {
+    const session = await ctx.db
+      .query("sessions")
+      .withIndex("by_token", (q) => q.eq("sessionToken", args.sessionToken))
+      .first();
+
+    if (session) {
+      await ctx.db.delete(session._id);
+    }
+  },
+});
+
+// ============ Sync Helpers ============
+
+export const markSyncedAsContact = mutation({
+  args: {
+    id: v.id("frontendUsers"),
+    l4yercak3ContactId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.id, {
+      l4yercak3ContactId: args.l4yercak3ContactId,
+      syncStatus: "synced",
+      syncedAt: Date.now(),
+    });
+  },
+});
+
+export const getPendingSync = query({
+  args: {},
+  handler: async (ctx) => {
+    const users = await ctx.db.query("frontendUsers").collect();
+    return users.filter((u) => u.syncStatus === "pending_push");
+  },
+});
+`;
+
+    return writeFileWithBackup(outputPath, content, action);
+  }
+
+  async generateSync(convexDir) {
+    const outputPath = path.join(convexDir, 'sync.ts');
+
+    const action = await checkFileOverwrite(outputPath);
+    if (action === 'skip') {
+      return null;
+    }
+
+    const content = `/**
+ * Convex L4YERCAK3 Sync Logic
+ * Auto-generated by @l4yercak3/cli
+ *
+ * Handles bidirectional sync between local Convex and L4YERCAK3 backend.
+ */
+
+import { v } from "convex/values";
+import { internalMutation, internalQuery, action } from "./_generated/server";
+import { internal } from "./_generated/api";
+
+// ============ Sync Job Management ============
+
+export const createSyncJob = internalMutation({
+  args: {
+    entityType: v.string(),
+    direction: v.union(
+      v.literal("push"),
+      v.literal("pull"),
+      v.literal("bidirectional")
+    ),
+  },
+  handler: async (ctx, args) => {
+    const id = await ctx.db.insert("syncJobs", {
+      entityType: args.entityType,
+      direction: args.direction,
+      status: "pending",
+      processedCount: 0,
+      startedAt: Date.now(),
+    });
+
+    return id;
+  },
+});
+
+export const updateSyncJob = internalMutation({
+  args: {
+    id: v.id("syncJobs"),
+    status: v.optional(
+      v.union(
+        v.literal("pending"),
+        v.literal("running"),
+        v.literal("completed"),
+        v.literal("failed")
+      )
+    ),
+    processedCount: v.optional(v.number()),
+    totalCount: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+    errorMessage: v.optional(v.string()),
+    errorDetails: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    const { id, ...updates } = args;
+
+    const finalUpdates: Record<string, unknown> = { ...updates };
+
+    if (updates.status === "completed" || updates.status === "failed") {
+      finalUpdates.completedAt = Date.now();
+    }
+
+    await ctx.db.patch(id, finalUpdates);
+  },
+});
+
+// ============ Conflict Resolution ============
+
+export const recordConflict = internalMutation({
+  args: {
+    objectId: v.id("objects"),
+    localVersion: v.any(),
+    remoteVersion: v.any(),
+    conflictType: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const id = await ctx.db.insert("syncConflicts", {
+      objectId: args.objectId,
+      localVersion: args.localVersion,
+      remoteVersion: args.remoteVersion,
+      conflictType: args.conflictType,
+      createdAt: Date.now(),
+    });
+
+    // Mark object as conflicted
+    await ctx.db.patch(args.objectId, {
+      syncStatus: "conflict",
+    });
+
+    return id;
+  },
+});
+
+export const resolveConflict = internalMutation({
+  args: {
+    conflictId: v.id("syncConflicts"),
+    resolution: v.union(
+      v.literal("local_wins"),
+      v.literal("remote_wins"),
+      v.literal("merged")
+    ),
+    mergedData: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    const conflict = await ctx.db.get(args.conflictId);
+    if (!conflict) {
+      throw new Error("Conflict not found");
+    }
+
+    // Apply resolution
+    if (args.resolution === "local_wins") {
+      await ctx.db.patch(conflict.objectId, {
+        syncStatus: "pending_push",
+      });
+    } else if (args.resolution === "remote_wins") {
+      await ctx.db.patch(conflict.objectId, {
+        customProperties: conflict.remoteVersion,
+        syncStatus: "synced",
+        syncedAt: Date.now(),
+      });
+    } else if (args.resolution === "merged" && args.mergedData) {
+      await ctx.db.patch(conflict.objectId, {
+        customProperties: args.mergedData,
+        syncStatus: "pending_push",
+      });
+    }
+
+    // Mark conflict as resolved
+    await ctx.db.patch(args.conflictId, {
+      resolvedAt: Date.now(),
+      resolution: args.resolution,
+    });
+  },
+});
+
+// ============ Sync Actions ============
+
+/**
+ * Push local changes to L4YERCAK3
+ * Call this action to sync pending local changes to the backend.
+ */
+export const pushToL4yercak3 = action({
+  args: {
+    entityType: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    // This is a placeholder - actual implementation requires:
+    // 1. L4YERCAK3 API key from environment
+    // 2. Fetching pending items from Convex
+    // 3. Making API calls to L4YERCAK3
+    // 4. Updating sync status
+
+    const apiKey = process.env.L4YERCAK3_API_KEY;
+    if (!apiKey) {
+      throw new Error("L4YERCAK3_API_KEY environment variable required");
+    }
+
+    // Create sync job
+    const jobId = await ctx.runMutation(internal.sync.createSyncJob, {
+      entityType: args.entityType || "all",
+      direction: "push",
+    });
+
+    await ctx.runMutation(internal.sync.updateSyncJob, {
+      id: jobId,
+      status: "running",
+    });
+
+    try {
+      // TODO: Implement actual sync logic
+      // 1. Query pending_push objects
+      // 2. For each object, call L4YERCAK3 API
+      // 3. Update local records with l4yercak3Id
+      // 4. Mark as synced
+
+      await ctx.runMutation(internal.sync.updateSyncJob, {
+        id: jobId,
+        status: "completed",
+        processedCount: 0,
+      });
+
+      return { success: true, jobId };
+    } catch (error) {
+      await ctx.runMutation(internal.sync.updateSyncJob, {
+        id: jobId,
+        status: "failed",
+        errorMessage: error instanceof Error ? error.message : "Unknown error",
+      });
+
+      throw error;
+    }
+  },
+});
+
+/**
+ * Pull changes from L4YERCAK3
+ * Call this action to fetch updates from the backend.
+ */
+export const pullFromL4yercak3 = action({
+  args: {
+    entityType: v.optional(v.string()),
+    since: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const apiKey = process.env.L4YERCAK3_API_KEY;
+    if (!apiKey) {
+      throw new Error("L4YERCAK3_API_KEY environment variable required");
+    }
+
+    // Create sync job
+    const jobId = await ctx.runMutation(internal.sync.createSyncJob, {
+      entityType: args.entityType || "all",
+      direction: "pull",
+    });
+
+    await ctx.runMutation(internal.sync.updateSyncJob, {
+      id: jobId,
+      status: "running",
+    });
+
+    try {
+      // TODO: Implement actual sync logic
+      // 1. Call L4YERCAK3 API to get updated records
+      // 2. For each record, check if local version exists
+      // 3. If exists and different, create conflict or update
+      // 4. If doesn't exist, create new record
+
+      await ctx.runMutation(internal.sync.updateSyncJob, {
+        id: jobId,
+        status: "completed",
+        processedCount: 0,
+      });
+
+      return { success: true, jobId };
+    } catch (error) {
+      await ctx.runMutation(internal.sync.updateSyncJob, {
+        id: jobId,
+        status: "failed",
+        errorMessage: error instanceof Error ? error.message : "Unknown error",
+      });
+
+      throw error;
+    }
+  },
+});
+
+// ============ Queries ============
+
+export const getUnresolvedConflicts = internalQuery({
+  args: {},
+  handler: async (ctx) => {
+    return ctx.db
+      .query("syncConflicts")
+      .withIndex("by_unresolved", (q) => q.eq("resolvedAt", undefined))
+      .collect();
+  },
+});
+
+export const getRecentSyncJobs = internalQuery({
+  args: { limit: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    const jobs = await ctx.db.query("syncJobs").order("desc").collect();
+    return jobs.slice(0, args.limit || 10);
+  },
+});
+`;
+
+    return writeFileWithBackup(outputPath, content, action);
+  }
+
+  async generateHttp(convexDir) {
+    const outputPath = path.join(convexDir, 'http.ts');
+
+    const action = await checkFileOverwrite(outputPath);
+    if (action === 'skip') {
+      return null;
+    }
+
+    const content = `/**
+ * Convex HTTP Endpoints
+ * Auto-generated by @l4yercak3/cli
+ *
+ * Webhook endpoints for L4YERCAK3 and Stripe.
+ */
+
+import { httpRouter } from "convex/server";
+import { httpAction } from "./_generated/server";
+
+const http = httpRouter();
+
+/**
+ * L4YERCAK3 Webhook Handler
+ * Receives events from L4YERCAK3 backend
+ */
+http.route({
+  path: "/webhooks/l4yercak3",
+  method: "POST",
+  handler: httpAction(async (ctx, request) => {
+    const signature = request.headers.get("x-l4yercak3-signature");
+    const webhookSecret = process.env.L4YERCAK3_WEBHOOK_SECRET;
+
+    if (!webhookSecret) {
+      return new Response("Webhook secret not configured", { status: 500 });
+    }
+
+    // Get raw body for signature verification
+    const body = await request.text();
+
+    // TODO: Verify signature using the same logic as webhooks.ts
+    // For now, basic validation
+    if (!signature) {
+      return new Response("Missing signature", { status: 401 });
+    }
+
+    try {
+      const event = JSON.parse(body);
+
+      // Handle different event types
+      switch (event.type) {
+        case "contact.created":
+        case "contact.updated":
+          // Sync contact to local objects
+          console.log("Contact event:", event.type, event.data);
+          break;
+
+        case "event.created":
+        case "event.updated":
+          // Sync event to local objects
+          console.log("Event event:", event.type, event.data);
+          break;
+
+        case "order.created":
+        case "order.paid":
+          // Sync order to local objects
+          console.log("Order event:", event.type, event.data);
+          break;
+
+        default:
+          console.log("Unhandled event type:", event.type);
+      }
+
+      return new Response("OK", { status: 200 });
+    } catch (error) {
+      console.error("Webhook error:", error);
+      return new Response("Invalid payload", { status: 400 });
+    }
+  }),
+});
+
+/**
+ * Stripe Webhook Handler
+ * Receives events from Stripe
+ */
+http.route({
+  path: "/webhooks/stripe",
+  method: "POST",
+  handler: httpAction(async (ctx, request) => {
+    const signature = request.headers.get("stripe-signature");
+    const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
+
+    if (!webhookSecret) {
+      return new Response("Stripe webhook secret not configured", {
+        status: 500,
+      });
+    }
+
+    if (!signature) {
+      return new Response("Missing Stripe signature", { status: 401 });
+    }
+
+    const body = await request.text();
+
+    try {
+      // TODO: Verify Stripe signature
+      // const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
+      // const event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
+
+      const event = JSON.parse(body);
+
+      // Handle Stripe events
+      switch (event.type) {
+        case "payment_intent.succeeded":
+          console.log("Payment succeeded:", event.data.object.id);
+          // Store payment locally and sync to L4YERCAK3
+          break;
+
+        case "payment_intent.payment_failed":
+          console.log("Payment failed:", event.data.object.id);
+          break;
+
+        case "customer.subscription.created":
+        case "customer.subscription.updated":
+        case "customer.subscription.deleted":
+          console.log("Subscription event:", event.type);
+          break;
+
+        default:
+          console.log("Unhandled Stripe event:", event.type);
+      }
+
+      return new Response("OK", { status: 200 });
+    } catch (error) {
+      console.error("Stripe webhook error:", error);
+      return new Response("Invalid payload", { status: 400 });
+    }
+  }),
+});
+
+export default http;
+`;
+
+    return writeFileWithBackup(outputPath, content, action);
+  }
+}
+
+module.exports = new ConvexGenerator();