@convex-dev/workos-authkit 0.2.9 → 0.3.0

package/src/component/lib.ts

@@ -1,23 +1,12 @@
+import { type Event as WorkOSEvent } from "@workos-inc/node";
+import { withoutSystemFields } from "convex-helpers";
+import { parse } from "convex-helpers/validators";
+import type { FunctionHandle } from "convex/server";
 import { type Infer, v } from "convex/values";
-import {
-  internalAction,
-  internalMutation,
-  internalQuery,
-  mutation,
-  query,
-} from "./_generated/server.js";
+import { vUser } from "../validators.js";
+import type { Doc } from "./_generated/dataModel.js";
 import type { MutationCtx } from "./_generated/server.js";
-import { components, internal } from "./_generated/api.js";
-import { omit, withoutSystemFields } from "convex-helpers";
-import { WorkOS, type Event as WorkOSEvent } from "@workos-inc/node";
-import type { FunctionHandle } from "convex/server";
-import { Workpool } from "@convex-dev/workpool";
-import schema from "./schema.js";
-import { parse } from "convex-helpers/validators";
-
-const eventWorkpool = new Workpool(components.eventWorkpool, {
-  maxParallelism: 1,
-});
+import { mutation, query } from "./_generated/server.js";
 
 export const vEvent = v.object({
   id: v.string(),
@@ -27,6 +16,25 @@ export const vEvent = v.object({
   context: v.optional(v.record(v.string(), v.any())),
 });
 
+/**
+ * Returns the WorkOS user id an event is about, or undefined when the
+ * event is about something other than a user.
+ */
+function eventUserId(event: Infer<typeof vEvent>): string | undefined {
+  const data = event.data as { id?: unknown; userId?: unknown };
+  if (typeof data.userId === "string") {
+    return data.userId;
+  }
+  const isUserEvent =
+    event.event === "user.created" ||
+    event.event === "user.updated" ||
+    event.event === "user.deleted";
+  if (isUserEvent && typeof data.id === "string") {
+    return data.id;
+  }
+  return undefined;
+}
+
 async function processEventHandler(
   ctx: MutationCtx,
   args: {
@@ -38,6 +46,8 @@ async function processEventHandler(
   if (args.logLevel === "DEBUG") {
     console.log("processing event", args.event);
   }
+  const event = args.event as WorkOSEvent;
+  const userId = eventUserId(args.event);
   const dbEvent = await ctx.db
     .query("events")
     .withIndex("eventId", (q) => q.eq("eventId", args.event.id))
@@ -47,74 +57,94 @@ async function processEventHandler(
     return;
   }
   await ctx.db.insert("events", {
+    userId,
     eventId: args.event.id,
     event: args.event.event,
     updatedAt: args.event.data.updatedAt as string | undefined,
   });
-  const event = args.event as WorkOSEvent;
+  let eventForCallback = event.event;
+  let dataForCallback = args.event.data;
   switch (event.event) {
-    case "user.created": {
-      const data = omit(event.data, ["object"]);
-      const existingUser = await ctx.db
-        .query("users")
-        .withIndex("id", (q) => q.eq("id", data.id))
-        .unique();
-      if (existingUser) {
-        console.warn("user already exists", data.id);
-        return;
-      }
-      await ctx.db.insert("users", data);
-      break;
-    }
+    case "user.created":
     case "user.updated": {
-      const data = omit(event.data, ["object"]);
-      const user = await ctx.db
+      const data = parse(vUser, event.data);
+      const existingUser = await ctx.db
         .query("users")
         .withIndex("id", (q) => q.eq("id", data.id))
         .unique();
-      if (!user) {
-        // The update may have been delivered before the create; the
-        // payload is the full user object, so insert it. The create
-        // no-ops on arrival via the existing-user guard above.
-        console.warn("user not found for update, inserting", data.id);
+      if (!existingUser) {
+        const deletedUser = await ctx.db
+          .query("deletedUsers")
+          .withIndex("id", (q) => q.eq("id", data.id))
+          .unique();
+        if (deletedUser) {
+          console.warn("user already deleted, skipping", event.event, data.id);
+          return;
+        }
         await ctx.db.insert("users", data);
-        break;
-      }
-      if (user.updatedAt >= data.updatedAt) {
-        console.warn(`user already updated for event ${event.id}, skipping`);
-        return;
+        if (event.event === "user.updated") {
+          // WorkOS can deliver the update before the create. The update
+          // payload holds the whole user, so it is safe to insert.
+          console.warn("user not found for update, inserting", data.id);
+          eventForCallback = "user.created";
+        }
+      } else {
+        if (event.event === "user.created") {
+          console.warn("user already exists", data.id);
+          // The callback already fired as user.created when this user was
+          // first inserted, so skip it here.
+          return;
+        } else if (existingUser.updatedAt >= data.updatedAt) {
+          console.warn(`user already updated for event ${event.id}, skipping`);
+          return;
+        }
+        await ctx.db.patch("users", existingUser._id, data);
       }
-      await ctx.db.patch("users", user._id, data);
       break;
     }
     case "user.deleted": {
-      const data = omit(event.data, ["object"]);
+      // Only the id is needed, so a trimmed payload should not fail the webhook.
+      const { id } = parse(v.object({ id: v.string() }), event.data);
+      // Record the deletion even if the user was never inserted locally, so a
+      // late user.created or user.updated for this user is skipped.
+      const deletedUser = await ctx.db
+        .query("deletedUsers")
+        .withIndex("id", (q) => q.eq("id", id))
+        .unique();
+      if (!deletedUser) {
+        await ctx.db.insert("deletedUsers", { id });
+      }
       const user = await ctx.db
         .query("users")
-        .withIndex("id", (q) => q.eq("id", data.id))
+        .withIndex("id", (q) => q.eq("id", id))
         .unique();
       if (!user) {
-        console.warn("user not found", data.id);
-        return;
+        console.warn("user not found, forwarding deletion", id);
+        break;
       }
       await ctx.db.delete("users", user._id);
+      // The callback data is typed as a whole user, so fill anything the
+      // payload left out from the stored user.
+      dataForCallback = {
+        ...withoutSystemFields(user),
+        object: "user",
+        ...args.event.data,
+      };
       break;
     }
   }
   if (args.onEventHandle) {
     await ctx.runMutation(args.onEventHandle as FunctionHandle<"mutation">, {
-      event: args.event.event,
-      data: args.event.data,
+      event: eventForCallback,
+      data: dataForCallback,
     });
   }
 }
 
 export const onWebhookEvent = mutation({
   args: {
-    apiKey: v.string(),
     event: vEvent,
     onEventHandle: v.optional(v.string()),
-    eventTypes: v.optional(v.array(v.string())),
     logLevel: v.optional(v.literal("DEBUG")),
   },
   returns: v.null(),
@@ -126,84 +156,17 @@ export const onWebhookEvent = mutation({
   },
 });
 
-export const getCursor = internalQuery({
-  args: {},
-  returns: v.union(v.string(), v.null()),
-  handler: async (ctx) => {
-    const lastProcessedEvent = await ctx.db
-      .query("events")
-      .order("desc")
-      .first();
-    return lastProcessedEvent?.eventId;
-  },
-});
-
-export const updateEvents = internalAction({
-  args: {
-    apiKey: v.string(),
-    onEventHandle: v.optional(v.string()),
-    eventTypes: v.optional(v.array(v.string())),
-    logLevel: v.optional(v.literal("DEBUG")),
-  },
-  handler: async (ctx, args) => {
-    // Cancel other pending workpool jobs since this run will
-    // process all available events from the WorkOS API.
-    await eventWorkpool.cancelAll(ctx);
-    const workos = new WorkOS(args.apiKey);
-    const cursor = await ctx.runQuery(internal.lib.getCursor);
-    let nextCursor = cursor ?? undefined;
-    const eventTypes = [
-      "user.created" as const,
-      "user.updated" as const,
-      "user.deleted" as const,
-      ...((args.eventTypes as WorkOSEvent["event"][]) ?? []),
-    ];
-    // No cursor should mean we haven't handled any events - set
-    // a start time of 5 minutes ago
-    let rangeStart = nextCursor
-      ? undefined
-      : new Date(Date.now() - 1000 * 60 * 5).toISOString();
-    do {
-      const { data, listMetadata } = await workos.events.listEvents({
-        events: eventTypes,
-        after: nextCursor,
-        rangeStart,
-      });
-      for (const event of data) {
-        await ctx.runMutation(internal.lib.processEvent, {
-          event: parse(vEvent, event),
-          logLevel: args.logLevel,
-          onEventHandle: args.onEventHandle,
-        });
-      }
-      nextCursor = listMetadata.after ?? undefined;
-      rangeStart = undefined;
-    } while (nextCursor);
-  },
-});
-
-export const processEvent = internalMutation({
-  args: {
-    event: vEvent,
-    logLevel: v.optional(v.literal("DEBUG")),
-    onEventHandle: v.optional(v.string()),
-  },
-  handler: async (ctx, args) => {
-    await processEventHandler(ctx, args);
-  },
-});
-
 export const getAuthUser = query({
   args: {
     id: v.string(),
   },
-  returns: v.union(schema.tables.users.validator, v.null()),
+  returns: v.union(vUser, v.null()),
   handler: async (ctx, args) => {
     const user = await ctx.db
       .query("users")
       .withIndex("id", (q) => q.eq("id", args.id))
       .unique();
-    return user ? withoutSystemFields(user) : null;
+    return publicUser(user);
   },
 });
 
@@ -211,12 +174,20 @@ export const getAuthUserByExternalId = query({
   args: {
     externalId: v.string(),
   },
-  returns: v.union(schema.tables.users.validator, v.null()),
+  returns: v.union(vUser, v.null()),
   handler: async (ctx, args) => {
     const user = await ctx.db
       .query("users")
       .withIndex("externalId", (q) => q.eq("externalId", args.externalId))
       .unique();
-    return user ? withoutSystemFields(user) : null;
+    return publicUser(user);
   },
 });
+
+/** Drops the Convex system fields so the user matches the public vUser shape. */
+function publicUser(user: Doc<"users"> | null): Infer<typeof vUser> | null {
+  if (!user) {
+    return null;
+  }
+  return withoutSystemFields(user);
+}

package/src/component/schema.ts

@@ -1,28 +1,21 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values";
+import { vUser } from "../validators.js";
 
 export default defineSchema({
   events: defineTable({
     eventId: v.string(),
     event: v.string(),
     updatedAt: v.optional(v.string()),
+    userId: v.optional(v.string()),
   }).index("eventId", ["eventId"]),
   backfillState: defineTable({
     apiKey: v.string(),
   }),
-  users: defineTable({
+  users: defineTable(vUser)
+    .index("id", ["id"])
+    .index("externalId", ["externalId"]),
+  deletedUsers: defineTable({
     id: v.string(),
-    email: v.string(),
-    name: v.optional(v.union(v.null(), v.string())),
-    firstName: v.optional(v.union(v.null(), v.string())),
-    lastName: v.optional(v.union(v.null(), v.string())),
-    emailVerified: v.boolean(),
-    profilePictureUrl: v.optional(v.union(v.null(), v.string())),
-    lastSignInAt: v.optional(v.union(v.null(), v.string())),
-    externalId: v.optional(v.union(v.null(), v.string())),
-    metadata: v.record(v.string(), v.any()),
-    locale: v.optional(v.union(v.null(), v.string())),
-    createdAt: v.string(),
-    updatedAt: v.string(),
-  }).index("id", ["id"]).index("externalId", ["externalId"]),
+  }).index("id", ["id"]),
 });

package/src/test.ts

@@ -1,7 +1,7 @@
 import type { TestConvex } from "convex-test";
 import type { GenericSchema, SchemaDefinition } from "convex/server";
-import workpool from "@convex-dev/workpool/test";
 import workflow from "@convex-dev/workflow/test";
+import type { ComponentApi } from "./component/_generated/component.js";
 import schema from "./component/schema.js";
 const modules = import.meta.glob("./component/**/*.ts");
 
@@ -9,13 +9,14 @@ const modules = import.meta.glob("./component/**/*.ts");
  * Register the component with the test convex instance.
  * @param t - The test convex instance, e.g. from calling `convexTest`.
  * @param name - The name of the component, as registered in convex.config.ts.
+ * @returns a component api to test via ctx.runMutation or for thick client
+ *   usage. Also provides types for convex-test's defineTestApp.
  */
 function register(
   t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
   name: string = "workOSAuthKit"
 ) {
-  t.registerComponent(name, schema, modules);
-  workpool.register(t, `${name}/eventWorkpool`);
   workflow.register(t, `${name}/backfillWorkflow`);
+  return t.registerComponent(name, schema, modules) as unknown as ComponentApi;
 }
 export default { register, schema, modules };

package/src/validators.ts

@@ -0,0 +1,17 @@
+import { v } from "convex/values";
+
+export const vUser = v.object({
+  id: v.string(),
+  email: v.string(),
+  name: v.optional(v.union(v.null(), v.string())),
+  firstName: v.optional(v.union(v.null(), v.string())),
+  lastName: v.optional(v.union(v.null(), v.string())),
+  emailVerified: v.boolean(),
+  profilePictureUrl: v.optional(v.union(v.null(), v.string())),
+  lastSignInAt: v.optional(v.union(v.null(), v.string())),
+  externalId: v.optional(v.union(v.null(), v.string())),
+  metadata: v.record(v.string(), v.any()),
+  locale: v.optional(v.union(v.null(), v.string())),
+  createdAt: v.string(),
+  updatedAt: v.string(),
+});