@supa-media/convex 1.5.0 → 1.7.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.7.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,7 +11,14 @@ export type {
   SupaAuthResendConfig,
   SupaAuthTestEmailConfig,
   SupaAuthTwilioConfig,
+  SupaAuthUserCreated,
 } from "./setup";
+export {
+  checkTwilioVerification,
+  sendTwilioVerification,
+  twilioVerifyKeys,
+} from "./twilioVerify";
+export type { TwilioCheckResult, TwilioSendResult, TwilioVerifyKeys } from "./twilioVerify";
 export {
   requireAuth,
   requireAuthId,

package/src/auth/setup.ts

@@ -22,14 +22,16 @@
  * ```
  */
 
+import { sendTwilioVerification } from "./twilioVerify";
 import { convexAuth } from "@convex-dev/auth/server";
 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 +126,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. */
@@ -378,39 +389,13 @@ function createPhoneOtp(config: SupaAuthConfig) {
         return;
       }
 
-      const response = await fetch(
-        `https://verify.twilio.com/v2/Services/${verifyServiceSid}/Verifications`,
-        {
-          method: "POST",
-          headers: {
-            Authorization: `Basic ${btoa(`${accountSid}:${authToken}`)}`,
-            "Content-Type": "application/x-www-form-urlencoded",
-          },
-          body: new URLSearchParams({
-            To: phone,
-            Channel: "sms",
-          }),
-        },
+      const sent = await sendTwilioVerification(
+        { accountSid, authToken, serviceSid: verifyServiceSid },
+        phone,
       );
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        let errorData: { code?: number; message?: string };
-        try {
-          errorData = JSON.parse(errorText);
-        } catch {
-          errorData = { message: errorText };
-        }
-
-        console.error("Twilio Verify send error:", {
-          status: response.status,
-          errorCode: errorData?.code,
-          errorMessage: errorData?.message,
-          phone,
-        });
-
+      if (!sent.ok) {
         throw new Error(
-          errorData?.message?.includes("Invalid phone number")
+          sent.reason === "invalid_phone"
             ? "Invalid phone number. Please check and try again."
             : "Failed to send verification code. Please try again.",
         );
@@ -440,6 +425,6 @@ export function createSupaAuth(config: SupaAuthConfig = {}) {
 
   return convexAuth({
     providers,
-    callbacks: { createOrUpdateUser: userCallback(config.admission) },
+    callbacks: { createOrUpdateUser: userCallback(config.admission, config.onUserCreated) },
   });
 }

package/src/auth/twilioVerify.ts

@@ -0,0 +1,98 @@
+/**
+ * Twilio Verify, on its own: send a code to a phone, then check one.
+ *
+ * `createSupaAuth`'s phone provider uses Twilio Verify to *sign in* with a
+ * phone. An app that signs in with email can still want to know a person holds
+ * a phone: proof of a real person, or one identity across several sign-in
+ * emails. These two calls are that, without a sign-in provider: Twilio keeps
+ * the code, so the app stores no secret and only records the result.
+ *
+ * The keys are the provider's: `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`,
+ * `TWILIO_VERIFY_SERVICE_SID`. With any missing, `twilioVerifyKeys` answers
+ * `null`, and the app decides what that means. It should never mean "verified".
+ */
+
+export interface TwilioVerifyKeys {
+  accountSid: string;
+  authToken: string;
+  serviceSid: string;
+}
+
+export type TwilioSendResult =
+  | { ok: true }
+  | { ok: false; reason: "invalid_phone" | "too_many" | "failed" };
+
+/** `wrong` covers an expired or unknown code too: Twilio answers both with 404. */
+export type TwilioCheckResult = "approved" | "wrong" | "too_many" | "failed";
+
+type Fetch = typeof fetch;
+
+/** The keys from the environment, or `null` when any is unset. */
+export function twilioVerifyKeys(
+  env: Record<string, string | undefined> = process.env,
+): TwilioVerifyKeys | null {
+  const accountSid = env.TWILIO_ACCOUNT_SID?.trim();
+  const authToken = env.TWILIO_AUTH_TOKEN?.trim();
+  const serviceSid = env.TWILIO_VERIFY_SERVICE_SID?.trim();
+  if (!accountSid || !authToken || !serviceSid) return null;
+  return { accountSid, authToken, serviceSid };
+}
+
+function request(keys: TwilioVerifyKeys, path: string, body: Record<string, string>, fetchImpl: Fetch) {
+  return fetchImpl(`https://verify.twilio.com/v2/Services/${keys.serviceSid}/${path}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${btoa(`${keys.accountSid}:${keys.authToken}`)}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams(body),
+  });
+}
+
+async function errorOf(response: Response): Promise<{ code?: number; message?: string }> {
+  const text = await response.text();
+  try {
+    return JSON.parse(text) as { code?: number; message?: string };
+  } catch {
+    return { message: text };
+  }
+}
+
+/** Twilio's "Max send attempts reached" and "Max check attempts reached". */
+const TOO_MANY = new Set([60203, 60202]);
+
+/** Text a code to `phone` (E.164). */
+export async function sendTwilioVerification(
+  keys: TwilioVerifyKeys,
+  phone: string,
+  fetchImpl: Fetch = fetch,
+): Promise<TwilioSendResult> {
+  const response = await request(keys, "Verifications", { To: phone, Channel: "sms" }, fetchImpl);
+  if (response.ok) return { ok: true };
+  const error = await errorOf(response);
+  // Logged without the number: a phone number is personal data.
+  console.error("Twilio Verify send failed", { status: response.status, code: error.code });
+  if (error.code !== undefined && TOO_MANY.has(error.code)) return { ok: false, reason: "too_many" };
+  if (error.code === 60200 || /invalid.*phone/i.test(error.message ?? "")) {
+    return { ok: false, reason: "invalid_phone" };
+  }
+  return { ok: false, reason: "failed" };
+}
+
+/** Check a code typed for `phone`. Only `approved` means the person holds it. */
+export async function checkTwilioVerification(
+  keys: TwilioVerifyKeys,
+  phone: string,
+  code: string,
+  fetchImpl: Fetch = fetch,
+): Promise<TwilioCheckResult> {
+  const response = await request(keys, "VerificationCheck", { To: phone, Code: code }, fetchImpl);
+  if (response.status === 404) return "wrong";
+  if (!response.ok) {
+    const error = await errorOf(response);
+    console.error("Twilio Verify check failed", { status: response.status, code: error.code });
+    return error.code !== undefined && TOO_MANY.has(error.code) ? "too_many" : "failed";
+  }
+  const body = (await response.json()) as { status?: string; valid?: boolean };
+  return body.status === "approved" && body.valid !== false ? "approved" : "wrong";
+}

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">;
   }