Latest changes

Author: Rajat

ARCHITECTURE.md

@@ -228,7 +228,12 @@ Phase 5 — **done**:
       Idempotent, keyed by a consumer-supplied `externalId` (e.g.
       `courselit:<domainId>`) rather than the owner's email, since two of a
       consumer's own tenants may share an owner email (which would otherwise
-      incorrectly merge them into one team).
+      incorrectly merge them into one team). Ownership is still assigned: the
+      request body includes `ownerEmail`, which is resolved via
+      `findOrCreateBareAccount` (email lowercased; account created if missing);
+      that account becomes the team's `ownerAccountId` and its sole
+      `team_members` row with role `owner`. There is no fixed platform/system
+      owner account — whichever email the consumer sends is the owner.
     - `src/bootstrap.ts`: a _separate_, boot-time-only convenience directly
       ported from MediaLit's `createAdminUser()` — if `SUPER_ADMIN_EMAIL` is
       set and no account exists for it yet, creates one (with its default team

apps/api/.env.example

@@ -48,6 +48,8 @@ SUPPRESSION_HASH_KEY=
 # Platform mail transport for system email such as login OTPs. Campaign,
 # broadcast, sequence and ESP test mail require each team to configure its own
 # ESP in settings.
+# EMAIL_HOST is required in production. EMAIL_USER/EMAIL_PASS are optional
+# (leave empty for auth-less sinks like Mailpit).
 EMAIL_HOST=
 EMAIL_PORT=587
 EMAIL_USER=

apps/api/src/auth/better-auth.ts

@@ -64,7 +64,9 @@ async function sendOtpEmail(email: string, otp: string) {
         return;
     }
 
-    if (!process.env.EMAIL_HOST || !process.env.EMAIL_USER) {
+    // Platform SMTP for login OTPs. Host is required; user/pass are optional so
+    // auth-less sinks (Mailpit, local smtp4dev) work without dummy credentials.
+    if (!process.env.EMAIL_HOST) {
         logger.error(
             { email },
             "Cannot send OTP email: SMTP is not configured",
@@ -75,10 +77,12 @@ async function sendOtpEmail(email: string, otp: string) {
     const transporter = createTransport({
         host: process.env.EMAIL_HOST,
         port: Number(process.env.EMAIL_PORT) || 587,
-        auth: {
-            user: process.env.EMAIL_USER,
-            pass: process.env.EMAIL_PASS,
-        },
+        auth: process.env.EMAIL_USER
+            ? {
+                  user: process.env.EMAIL_USER,
+                  pass: process.env.EMAIL_PASS || "",
+              }
+            : undefined,
     });
 
     await transporter.sendMail({

apps/api/src/automation/process-ongoing-sequence.ts

@@ -169,6 +169,8 @@ async function cleanUpResources(
     // once every recipient has been delivered to. Multi-step "sequence" type
     // automations stay "active" indefinitely so future contacts can still be
     // enrolled by their trigger (see `automation/fire-event.ts`).
+    // Zero-recipient broadcasts never create ongoing rows; they complete in
+    // `processRule` instead (see automation/process-rules.ts).
     if (completed && sequenceType === "broadcast" && publicSequenceId) {
         const remaining = await countOngoingSequencesForSequence(
             ongoingSequence.sequenceId,

apps/api/src/automation/process-rules.test.ts

@@ -8,6 +8,7 @@ const mocks = vi.hoisted(() => ({
     getPublicIds: vi.fn(),
     getSequence: vi.fn(),
     lockBroadcast: vi.fn(),
+    markBroadcastSent: vi.fn(),
     captureError: vi.fn(),
     captureEvent: vi.fn(),
 }));
@@ -20,6 +21,7 @@ vi.mock("./queries", () => ({
     getMatchingPublicContactIds: mocks.getPublicIds,
     getSequenceRowById: mocks.getSequence,
     lockBroadcast: mocks.lockBroadcast,
+    markBroadcastSent: mocks.markBroadcastSent,
 }));
 vi.mock("../observability/posthog", () => ({
     captureError: mocks.captureError,
@@ -44,9 +46,11 @@ beforeEach(() => {
     mocks.getInternalIds.mockResolvedValue(["contact-internal"]);
     mocks.getPublicIds.mockResolvedValue(["cnt_public"]);
     mocks.lockBroadcast.mockResolvedValue(undefined);
+    mocks.markBroadcastSent.mockResolvedValue(undefined);
     mocks.getSequence.mockResolvedValue({
         id: "sequence-internal",
         sequenceId: "seq_public",
+        type: "broadcast",
         filter: { aggregator: "and", filters: [] },
     });
 });
@@ -84,12 +88,23 @@ describe("scheduled broadcast rule processing", () => {
         expect(mocks.lockBroadcast).toHaveBeenCalledWith("sequence-internal", [
             "cnt_public",
         ]);
+        expect(mocks.markBroadcastSent).not.toHaveBeenCalled();
         expect(order).toEqual(["enroll", "lock", "delete"]);
     });
 
-    it("handles an empty audience and still consumes the due rule", async () => {
+    it("completes an empty-audience broadcast after lock and still consumes the rule", async () => {
         mocks.getInternalIds.mockResolvedValue([]);
         mocks.getPublicIds.mockResolvedValue([]);
+        const order: string[] = [];
+        mocks.lockBroadcast.mockImplementation(async () => {
+            order.push("lock");
+        });
+        mocks.markBroadcastSent.mockImplementation(async () => {
+            order.push("complete");
+        });
+        mocks.deleteRule.mockImplementation(async () => {
+            order.push("delete");
+        });
 
         await processRule(rule);
 
@@ -100,6 +115,34 @@ describe("scheduled broadcast rule processing", () => {
             "sequence-internal",
             [],
         );
+        expect(mocks.markBroadcastSent).toHaveBeenCalledWith("seq_public");
+        expect(mocks.captureEvent).toHaveBeenCalledWith(
+            expect.objectContaining({
+                event: "broadcast_sent",
+                source: "automation.process_rules",
+                properties: expect.objectContaining({
+                    sequence_id: "seq_public",
+                    recipients_count: 0,
+                }),
+            }),
+        );
+        expect(mocks.deleteRule).toHaveBeenCalledWith("rule_1");
+        expect(order).toEqual(["lock", "complete", "delete"]);
+    });
+
+    it("does not mark non-broadcast sequences completed on empty match", async () => {
+        mocks.getInternalIds.mockResolvedValue([]);
+        mocks.getPublicIds.mockResolvedValue([]);
+        mocks.getSequence.mockResolvedValue({
+            id: "sequence-internal",
+            sequenceId: "seq_public",
+            type: "sequence",
+            filter: { aggregator: "and", filters: [] },
+        });
+
+        await processRule(rule);
+
+        expect(mocks.markBroadcastSent).not.toHaveBeenCalled();
         expect(mocks.deleteRule).toHaveBeenCalledWith("rule_1");
     });
 

apps/api/src/automation/process-rules.ts

@@ -8,6 +8,7 @@ import {
     getMatchingPublicContactIds,
     getSequenceRowById,
     lockBroadcast,
+    markBroadcastSent,
 } from "./queries";
 import type { ContactFilterWithAggregator } from "../contacts/segment";
 
@@ -16,6 +17,11 @@ import type { ContactFilterWithAggregator } from "../contacts/segment";
  * `DATE_OCCURRED` rules (used to schedule broadcasts). Tag/subscriber based
  * triggers are handled immediately by `automation/fire-event.ts` instead of
  * being polled here.
+ *
+ * Empty-audience broadcasts: after lock, mark completed here via
+ * `markBroadcastSent`. The sequence/mail workers only complete broadcasts when
+ * the last `ongoing_sequences` row finishes, so a zero-recipient fire would
+ * otherwise stay `active` forever.
  */
 export async function processRules() {
     // eslint-disable-next-line no-constant-condition
@@ -99,6 +105,22 @@ export async function processRule(rule: {
         rule.teamId,
         sequenceRow.filter as ContactFilterWithAggregator | null,
     );
+    // lockBroadcast must run before markBroadcastSent: the latter jsonb_set's
+    // `{broadcast,sentAt}` and needs `report.broadcast` to already exist.
     await lockBroadcast(sequenceRow.id, publicContactIds);
+
+    if (sequenceRow.type === "broadcast" && contactIds.length === 0) {
+        await markBroadcastSent(sequenceRow.sequenceId);
+        captureEvent({
+            event: "broadcast_sent",
+            source: "automation.process_rules",
+            teamId: rule.teamId,
+            properties: {
+                sequence_id: sequenceRow.sequenceId,
+                recipients_count: 0,
+            },
+        });
+    }
+
     await deleteRule(rule.ruleId);
 }

apps/api/src/config/strings.ts

@@ -6,6 +6,9 @@ export const responses = {
     no_published_emails: "This sequence has no published emails",
     sequence_details_missing: "Sequence details are missing",
     sequence_not_active: "This sequence is not active",
+    /** Broadcast start rejected when the current filter matches nobody. */
+    broadcast_no_recipients:
+        "This broadcast has no matching recipients. Add contacts or widen the audience filter before sending.",
     mail_already_sent: "This broadcast has already been sent",
     cannot_delete_last_email: "Cannot delete the last email in a sequence",
     mandatory_tags_missing:

apps/api/src/sequences/queries.test.ts

@@ -244,6 +244,37 @@ describe("sequence queries", () => {
         ).resolves.toMatchObject({ status: "active" });
     });
 
+    it("rejects starting a broadcast with no matching recipients", async () => {
+        const { team } = await seedTeamAndContact(tdb);
+        await tdb.delete(contacts).where(eq(contacts.teamId, team.id));
+        const template = await makeTemplate(team.id);
+        const broadcast = await createSequence({
+            teamId: team.id,
+            type: "broadcast",
+            templateId: template.templateId,
+        });
+        await tdb
+            .update(sequenceEmails)
+            .set({ published: true })
+            .where(eq(sequenceEmails.id, broadcast.emails[0].id));
+
+        await expect(
+            startSequence({
+                teamId: team.id,
+                sequenceId: broadcast.sequenceId,
+            }),
+        ).rejects.toThrow(responses.broadcast_no_recipients);
+
+        await expect(
+            getSequenceBySequenceId(team.id, broadcast.sequenceId),
+        ).resolves.toMatchObject({ status: "draft" });
+        const createdRules = await tdb
+            .select()
+            .from(rules)
+            .where(eq(rules.sequenceId, broadcast.id));
+        expect(createdRules).toHaveLength(0);
+    });
+
     it("does not start or create a rule when no ESP is configured", async () => {
         const { team } = await seedTeamAndContact(tdb);
         const template = await makeTemplate(team.id);

apps/api/src/sequences/queries.ts

@@ -30,6 +30,7 @@ import { syncEmailContentMediaReferences } from "../media/email-content";
 import { deleteMediaReferencesForResource } from "../media/queries";
 import { getEspConfigById, resolveEspConfig } from "../settings/esp/queries";
 import { assertMailingAddressConfigured } from "../settings/general/queries";
+import { getMatchingContactIds } from "../automation/queries";
 
 export type Sequence = typeof sequences.$inferSelect;
 export type SequenceEmail = typeof sequenceEmails.$inferSelect;
@@ -613,6 +614,19 @@ export async function startSequence({
 
     // Broadcasts don't require a filter: an empty/null filter means the
     // whole audience (buildContactFilterCondition returns no condition).
+    // Refuse to start a broadcast that currently matches nobody — otherwise
+    // the schedule would fire, lock an empty snapshot, and (without the
+    // empty-audience completion path) look stuck in "sending". Multi-step
+    // sequences are allowed with an empty list; they enroll later via triggers.
+    if (sequence.type === "broadcast") {
+        const recipientIds = await getMatchingContactIds(
+            teamId,
+            sequence.filter as ContactFilterWithAggregator | null,
+        );
+        if (recipientIds.length === 0) {
+            throw new Error(responses.broadcast_no_recipients);
+        }
+    }
 
     await addRule({
         teamId,

apps/web/app/(dashboard)/account/page.tsx

@@ -3,6 +3,8 @@
 import { useEffect, useState } from "react";
 import { useRouter, useSearchParams } from "next/navigation";
 import { CreditCard, Sparkles, UserRound } from "lucide-react";
+import { Loader } from "@codelitdev/design-system";
+import { Loading } from "@/components/dashboard/loading";
 import { PageHeader } from "@/components/dashboard/page-header";
 import { ScrollablePage } from "@/components/dashboard/scrollable-page";
 import { useSetBreadcrumb } from "@/components/dashboard/breadcrumb-context";
@@ -186,6 +188,9 @@ export default function AccountPage() {
                                                 type="submit"
                                                 disabled={isSavingProfile}
                                             >
+                                                {isSavingProfile ? (
+                                                    <Loader size={16} />
+                                                ) : null}
                                                 {isSavingProfile
                                                     ? "Saving…"
                                                     : "Save changes"}
@@ -234,9 +239,13 @@ export default function AccountPage() {
                                     <p className="text-muted-foreground">
                                         Email
                                     </p>
-                                    <p className="font-medium">
-                                        {account?.email || "Loading…"}
-                                    </p>
+                                    {account ? (
+                                        <p className="font-medium">
+                                            {account.email}
+                                        </p>
+                                    ) : (
+                                        <Loading />
+                                    )}
                                 </div>
                             </CardContent>
                         </Card>