@supa-media/convex 1.5.0 → 1.6.0

package/README.md

@@ -194,6 +194,7 @@ function createSupaAuth(config?: {
   methods?: Array<"email" | "phone">;      // default ["email", "phone"]
   magicLink?: SupaAuthMagicLinkConfig;     // off unless present
   admission?: SupaAuthAdmission;           // invite-only; open sign-up unless present
+  onUserCreated?: SupaAuthUserCreated;     // once per brand-new user, same transaction
   resend?: { fromAddress: string; emailSubject?: (code) => string;
              renderHtml?: (p: { code, email }) => string };
   twilio?: { tokenBridgePath?: string };   // default "/api/internal/phone-token"
@@ -265,6 +266,22 @@ that throws refuses. Ask your own "is this address let in?" before calling
 `signIn` and draw the answer yourself; the error message is redacted in
 production.
 
+### New accounts (`onUserCreated`)
+
+```ts
+createSupaAuth({
+  onUserCreated: async (ctx, { userId, email }) => {
+    await ctx.scheduler.runAfter(0, internal.alerts.newAccount, { userId });
+  },
+});
+```
+
+Runs once for each brand-new user row, after the insert and inside the same
+mutation, so whatever it writes or schedules commits only with the account. A
+returning account, or a new sign-in method linked to an existing user, never
+calls it. A hook that throws fails the sign-in, so keep it to quick writes and
+`ctx.scheduler`.
+
 ### Magic link (opt-in)
 
 Set `magicLink: {}` and a **second** email provider is registered under

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supa-media/convex",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Backend package for the Supa framework — OTP auth, schema helpers, and backend utilities for Convex",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/auth/index.ts

@@ -11,6 +11,7 @@ export type {
   SupaAuthResendConfig,
   SupaAuthTestEmailConfig,
   SupaAuthTwilioConfig,
+  SupaAuthUserCreated,
 } from "./setup";
 export {
   requireAuth,

package/src/auth/setup.ts

@@ -27,9 +27,10 @@ import { Email } from "@convex-dev/auth/providers/Email";
 import { Phone } from "@convex-dev/auth/providers/Phone";
 import { assertMayReceiveEmailCode, type SupaAuthAdmission } from "./admission";
 import { createTestEmailOtps, type SupaAuthTestEmailConfig } from "./testEmail";
-import { userCallback } from "./users";
+import { userCallback, type SupaAuthUserCreated } from "./users";
 
 export { NOT_ADMITTED_MESSAGE, type SupaAuthAdmission } from "./admission";
+export type { SupaAuthUserCreated } from "./users";
 
 export {
   createTestEmailOtp,
@@ -124,6 +125,15 @@ export interface SupaAuthConfig {
    * get a brand-new account. Omitted, anybody may sign up. See `admission.ts`.
    */
   admission?: SupaAuthAdmission;
+  /**
+   * Called once for each brand-new user row, never for a returning account or
+   * a new sign-in method linked to an existing one. Runs inside the sign-in
+   * mutation, after the insert: what it writes or schedules commits only with
+   * the account, and a hook that throws fails the sign-in. Keep it to quick
+   * writes and `ctx.scheduler` — a welcome email or a staff alert belongs in a
+   * scheduled action, not here.
+   */
+  onUserCreated?: SupaAuthUserCreated;
   /** Resend email OTP configuration. */
   resend?: SupaAuthResendConfig;
   /** Twilio phone OTP configuration. */
@@ -440,6 +450,6 @@ export function createSupaAuth(config: SupaAuthConfig = {}) {
 
   return convexAuth({
     providers,
-    callbacks: { createOrUpdateUser: userCallback(config.admission) },
+    callbacks: { createOrUpdateUser: userCallback(config.admission, config.onUserCreated) },
   });
 }

package/src/auth/users.ts

@@ -6,18 +6,29 @@
  * who signs in two ways is one user. Only when nobody matches is a user row
  * created — and that is the one place `admission.canCreateUser` is asked, so
  * an invite-only app can refuse a stranger without ever locking out somebody
- * who already has an account.
+ * who already has an account. It is also the one place `onUserCreated` runs,
+ * so an app hears about each brand-new account exactly once.
  */
+import type { AnyDataModel, GenericMutationCtx } from "convex/server";
 import type { GenericId } from "convex/values";
 import type { convexAuth } from "@convex-dev/auth/server";
 
 import { assertMayCreateUser, type SupaAuthAdmission } from "./admission";
 
+/** See `SupaAuthConfig.onUserCreated`. */
+export type SupaAuthUserCreated = (
+  ctx: GenericMutationCtx<AnyDataModel>,
+  created: { userId: GenericId<"users">; provider: string; email?: string; phone?: string },
+) => Promise<void>;
+
 type Handler = NonNullable<
   NonNullable<Parameters<typeof convexAuth>[0]["callbacks"]>["createOrUpdateUser"]
 >;
 
-export function userCallback(admission: SupaAuthAdmission | undefined): Handler {
+export function userCallback(
+  admission: SupaAuthAdmission | undefined,
+  onUserCreated?: SupaAuthUserCreated,
+): Handler {
   async function createOrUpdateUser(
     ctx: Parameters<Handler>[0],
     { existingUserId, type, provider, profile }: Parameters<Handler>[1],
@@ -106,6 +117,16 @@ export function userCallback(admission: SupaAuthAdmission | undefined): Handler
         phone?: string;
       },
     );
+    // Same transaction as the insert: a hook that throws undoes the account,
+    // and anything it writes or schedules lands only if the account does.
+    if (onUserCreated !== undefined) {
+      await onUserCreated(ctx, {
+        userId: userId as GenericId<"users">,
+        provider: provider.id,
+        ...(typeof profile.email === "string" ? { email: profile.email } : {}),
+        ...(typeof profile.phone === "string" ? { phone: profile.phone } : {}),
+      });
+    }
     return userId as GenericId<"users">;
   }