@useatlas/create 0.0.6 → 0.0.7

package/templates/nextjs-standalone/src/lib/email/store.ts

@@ -0,0 +1,163 @@
+/**
+ * Email integration storage.
+ *
+ * Stores per-workspace email delivery configuration in the internal database.
+ * Supports multiple providers: SMTP, SendGrid, Postmark, SES.
+ * Each workspace admin configures their own email delivery settings (BYOT).
+ */
+
+import { hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
+import { createLogger } from "@atlas/api/lib/logger";
+import type { EmailInstallationWithSecret, EmailProvider, ProviderConfig } from "@atlas/api/lib/integrations/types";
+
+export type {
+  EmailInstallation,
+  EmailInstallationWithSecret,
+  EmailProvider,
+  ProviderConfig,
+  SmtpConfig,
+  SendGridConfig,
+  PostmarkConfig,
+  SesConfig,
+} from "@atlas/api/lib/integrations/types";
+
+const log = createLogger("email-store");
+
+// ---------------------------------------------------------------------------
+// Shared row parser
+// ---------------------------------------------------------------------------
+
+function parseInstallationRow(
+  row: Record<string, unknown>,
+  context: Record<string, unknown>,
+): EmailInstallationWithSecret | null {
+  const configId = row.config_id;
+  const provider = row.provider;
+  const senderAddress = row.sender_address;
+  const config = row.config;
+  if (
+    typeof configId !== "string" || !configId ||
+    typeof provider !== "string" || !provider ||
+    typeof senderAddress !== "string" || !senderAddress ||
+    !config || typeof config !== "object"
+  ) {
+    log.warn(context, "Invalid email installation record in database");
+    return null;
+  }
+  return {
+    config_id: configId,
+    provider: provider as EmailProvider,
+    sender_address: senderAddress,
+    config: config as ProviderConfig,
+    org_id: typeof row.org_id === "string" ? row.org_id : null,
+    installed_at: typeof row.installed_at === "string" ? row.installed_at : new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Read operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the email installation for an org. Returns null if not found or
+ * if no internal database is configured.
+ *
+ * Returns the full WithSecret type because email delivery (delivery.ts)
+ * needs the provider credentials to send. The status endpoint only uses
+ * public fields from the result.
+ */
+export async function getEmailInstallationByOrg(
+  orgId: string,
+): Promise<EmailInstallationWithSecret | null> {
+  if (!hasInternalDB()) {
+    return null;
+  }
+
+  try {
+    const rows = await internalQuery<Record<string, unknown>>(
+      "SELECT config_id, provider, sender_address, config, org_id, installed_at::text FROM email_installations WHERE org_id = $1",
+      [orgId],
+    );
+    if (rows.length > 0) {
+      return parseInstallationRow(rows[0], { orgId });
+    }
+    return null;
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err), orgId },
+      "Failed to query email_installations by org",
+    );
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Write operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Save or update an email installation for an org.
+ * Atomic upsert on org_id (UNIQUE index) — each org gets exactly one email config.
+ * Throws if the database write fails.
+ */
+export async function saveEmailInstallation(
+  orgId: string,
+  opts: {
+    provider: EmailProvider;
+    senderAddress: string;
+    config: ProviderConfig;
+  },
+): Promise<void> {
+  if (!hasInternalDB()) {
+    throw new Error("Cannot save email installation — no internal database configured");
+  }
+
+  try {
+    // Atomic upsert — the UNIQUE index on org_id ensures one config per org.
+    await internalQuery(
+      `INSERT INTO email_installations (provider, sender_address, config, org_id)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (org_id) DO UPDATE SET
+         provider = $1,
+         sender_address = $2,
+         config = $3,
+         installed_at = now()`,
+      [opts.provider, opts.senderAddress, JSON.stringify(opts.config), orgId],
+    );
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err), orgId },
+      "Failed to save email_installations",
+    );
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Delete operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove the email installation for an org.
+ * Returns true if a row was deleted, false if no matching row found.
+ * Throws if no internal DB or if the query fails.
+ */
+export async function deleteEmailInstallationByOrg(orgId: string): Promise<boolean> {
+  if (!hasInternalDB()) {
+    throw new Error("Cannot delete email installation — no internal database configured");
+  }
+
+  try {
+    const rows = await internalQuery<{ config_id: string }>(
+      "DELETE FROM email_installations WHERE org_id = $1 RETURNING config_id",
+      [orgId],
+    );
+    return rows.length > 0;
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err.message : String(err), orgId },
+      "Failed to delete email_installations by org",
+    );
+    throw err;
+  }
+}

package/templates/nextjs-standalone/src/lib/email/templates.ts

@@ -0,0 +1,215 @@
+/**
+ * Onboarding email HTML templates.
+ *
+ * Inline-styled HTML suitable for email clients (no external CSS).
+ * Templates respect workspace branding (logo, colors) when available.
+ */
+
+import type { OnboardingEmailStep } from "@useatlas/types";
+import type { WorkspaceBrandingPublic } from "@useatlas/types";
+import { ONBOARDING_SEQUENCE } from "./sequence";
+
+// ── Branding defaults ───────────────────────────────────────────────
+
+const DEFAULT_APP_NAME = "Atlas";
+const DEFAULT_PRIMARY_COLOR = "#171717"; // neutral-900
+const DEFAULT_ACCENT_COLOR = "#2563eb"; // blue-600
+
+interface BrandingContext {
+  appName: string;
+  primaryColor: string;
+  accentColor: string;
+  logoUrl: string | null;
+  logoText: string | null;
+}
+
+function buildBrandingContext(branding?: WorkspaceBrandingPublic | null): BrandingContext {
+  return {
+    appName: branding?.logoText || DEFAULT_APP_NAME,
+    primaryColor: branding?.primaryColor || DEFAULT_PRIMARY_COLOR,
+    accentColor: branding?.primaryColor || DEFAULT_ACCENT_COLOR,
+    logoUrl: branding?.logoUrl ?? null,
+    logoText: branding?.logoText ?? null,
+  };
+}
+
+// ── Shared helpers ──────────────────────────────────────────────────
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function header(ctx: BrandingContext): string {
+  const logo = ctx.logoUrl
+    ? `<img src="${escapeHtml(ctx.logoUrl)}" alt="${escapeHtml(ctx.appName)}" style="height:32px;max-width:160px;object-fit:contain;" />`
+    : `<span style="font-size:20px;font-weight:700;color:${ctx.primaryColor};">${escapeHtml(ctx.appName)}</span>`;
+
+  return `
+    <div style="padding:24px 32px;border-bottom:2px solid ${ctx.accentColor};">
+      ${logo}
+    </div>`;
+}
+
+function footer(ctx: BrandingContext, unsubscribeUrl: string): string {
+  return `
+    <div style="padding:20px 32px;border-top:1px solid #e5e5e5;color:#737373;font-size:12px;line-height:1.5;">
+      <p style="margin:0;">You're receiving this because you signed up for ${escapeHtml(ctx.appName)}.</p>
+      <p style="margin:4px 0 0;">
+        <a href="${escapeHtml(unsubscribeUrl)}" style="color:#737373;text-decoration:underline;">Unsubscribe</a>
+        from onboarding emails.
+      </p>
+    </div>`;
+}
+
+function button(text: string, url: string, color: string): string {
+  return `
+    <a href="${escapeHtml(url)}" style="display:inline-block;padding:12px 28px;background:${color};color:#ffffff;text-decoration:none;border-radius:6px;font-weight:600;font-size:14px;">
+      ${escapeHtml(text)}
+    </a>`;
+}
+
+function wrap(ctx: BrandingContext, content: string, unsubscribeUrl: string): string {
+  return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8" /><meta name="viewport" content="width=device-width,initial-scale=1" /></head>
+<body style="margin:0;padding:0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#f5f5f5;">
+  <div style="max-width:600px;margin:32px auto;background:#ffffff;border-radius:8px;overflow:hidden;border:1px solid #e5e5e5;">
+    ${header(ctx)}
+    <div style="padding:32px;">
+      ${content}
+    </div>
+    ${footer(ctx, unsubscribeUrl)}
+  </div>
+</body>
+</html>`;
+}
+
+// ── Step content ────────────────────────────────────────────────────
+
+function welcomeContent(ctx: BrandingContext, baseUrl: string): string {
+  return `
+    <h1 style="margin:0 0 16px;font-size:24px;color:${ctx.primaryColor};">Welcome to ${escapeHtml(ctx.appName)}!</h1>
+    <p style="margin:0 0 16px;font-size:15px;color:#404040;line-height:1.6;">
+      You're all set. ${escapeHtml(ctx.appName)} turns natural language into SQL — ask questions about your data and get instant answers.
+    </p>
+    <p style="margin:0 0 8px;font-size:15px;font-weight:600;color:${ctx.primaryColor};">Quick-start guide:</p>
+    <ol style="margin:0 0 24px;padding-left:20px;font-size:14px;color:#404040;line-height:1.8;">
+      <li>Connect your database (PostgreSQL or MySQL)</li>
+      <li>Atlas profiles your schema and builds a semantic layer</li>
+      <li>Ask questions in natural language — Atlas writes the SQL</li>
+      <li>Invite your team to collaborate</li>
+    </ol>
+    <div style="text-align:center;margin:24px 0;">
+      ${button("Get Started", `${baseUrl}/admin/connections`, ctx.accentColor)}
+    </div>`;
+}
+
+function connectDatabaseContent(ctx: BrandingContext, baseUrl: string): string {
+  return `
+    <h1 style="margin:0 0 16px;font-size:24px;color:${ctx.primaryColor};">Connect your database</h1>
+    <p style="margin:0 0 16px;font-size:15px;color:#404040;line-height:1.6;">
+      ${escapeHtml(ctx.appName)} needs a database connection to answer your questions. We support PostgreSQL and MySQL — read-only access is all that's needed.
+    </p>
+    <p style="margin:0 0 16px;font-size:14px;color:#404040;line-height:1.6;">
+      Your connection is encrypted at rest and all queries are validated as read-only SELECT statements before execution.
+    </p>
+    <div style="text-align:center;margin:24px 0;">
+      ${button("Connect Database", `${baseUrl}/admin/connections`, ctx.accentColor)}
+    </div>`;
+}
+
+function firstQueryContent(ctx: BrandingContext, baseUrl: string): string {
+  return `
+    <h1 style="margin:0 0 16px;font-size:24px;color:${ctx.primaryColor};">Ask your first question</h1>
+    <p style="margin:0 0 16px;font-size:15px;color:#404040;line-height:1.6;">
+      Your database is connected — now try asking a question in plain English. ${escapeHtml(ctx.appName)} will translate it to SQL and return the results.
+    </p>
+    <p style="margin:0 0 8px;font-size:14px;font-weight:600;color:${ctx.primaryColor};">Try something like:</p>
+    <ul style="margin:0 0 24px;padding-left:20px;font-size:14px;color:#404040;line-height:1.8;">
+      <li>"How many active users do we have this month?"</li>
+      <li>"Show me revenue by product category"</li>
+      <li>"What are the top 10 customers by order count?"</li>
+    </ul>
+    <div style="text-align:center;margin:24px 0;">
+      ${button("Ask a Question", baseUrl, ctx.accentColor)}
+    </div>`;
+}
+
+function inviteTeamContent(ctx: BrandingContext, baseUrl: string): string {
+  return `
+    <h1 style="margin:0 0 16px;font-size:24px;color:${ctx.primaryColor};">Invite your team</h1>
+    <p style="margin:0 0 16px;font-size:15px;color:#404040;line-height:1.6;">
+      ${escapeHtml(ctx.appName)} is better with your whole team. Invite colleagues so they can ask questions about your data too — no SQL knowledge required.
+    </p>
+    <p style="margin:0 0 16px;font-size:14px;color:#404040;line-height:1.6;">
+      Team members get their own chat history and can share interesting queries with each other.
+    </p>
+    <div style="text-align:center;margin:24px 0;">
+      ${button("Invite Team", `${baseUrl}/admin/users`, ctx.accentColor)}
+    </div>`;
+}
+
+function exploreFeaturesContent(ctx: BrandingContext, baseUrl: string): string {
+  return `
+    <h1 style="margin:0 0 16px;font-size:24px;color:${ctx.primaryColor};">Explore more features</h1>
+    <p style="margin:0 0 16px;font-size:15px;color:#404040;line-height:1.6;">
+      You've got the basics down. Here's what else ${escapeHtml(ctx.appName)} can do:
+    </p>
+    <ul style="margin:0 0 24px;padding-left:20px;font-size:14px;color:#404040;line-height:1.8;">
+      <li><strong>Notebooks</strong> — Save and organize multi-step analyses</li>
+      <li><strong>Scheduled Reports</strong> — Get automatic email/Slack updates on metrics</li>
+      <li><strong>Semantic Layer</strong> — Customize how your data is interpreted</li>
+      <li><strong>Admin Console</strong> — Manage users, connections, and settings</li>
+    </ul>
+    <div style="text-align:center;margin:24px 0;">
+      ${button("Explore Features", baseUrl, ctx.accentColor)}
+    </div>`;
+}
+
+const STEP_CONTENT: Record<OnboardingEmailStep, (ctx: BrandingContext, baseUrl: string) => string> = {
+  welcome: welcomeContent,
+  connect_database: connectDatabaseContent,
+  first_query: firstQueryContent,
+  invite_team: inviteTeamContent,
+  explore_features: exploreFeaturesContent,
+};
+
+// ── Public API ──────────────────────────────────────────────────────
+
+export interface RenderedEmail {
+  subject: string;
+  html: string;
+}
+
+/**
+ * Render an onboarding email for the given step.
+ *
+ * @param step - Which email in the sequence
+ * @param baseUrl - The app base URL (e.g. https://app.useatlas.dev)
+ * @param unsubscribeUrl - Full URL to unsubscribe endpoint
+ * @param branding - Optional workspace branding to apply
+ */
+export function renderOnboardingEmail(
+  step: OnboardingEmailStep,
+  baseUrl: string,
+  unsubscribeUrl: string,
+  branding?: WorkspaceBrandingPublic | null,
+): RenderedEmail {
+  const ctx = buildBrandingContext(branding);
+  const contentFn = STEP_CONTENT[step];
+  const content = contentFn(ctx, baseUrl);
+  const html = wrap(ctx, content, unsubscribeUrl);
+
+  // Resolve subject template
+  const stepDef = ONBOARDING_SEQUENCE.find((s) => s.step === step);
+  const subject = (stepDef?.subject ?? `${ctx.appName} — ${step}`).replace(
+    /\{\{appName\}\}/g,
+    ctx.appName,
+  );
+
+  return { subject, html };
+}

package/templates/nextjs-standalone/src/lib/format.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import {
+  formatDate,
+  formatLongDate,
+  formatDateTime,
+  formatShortDateTime,
+  formatNumber,
+} from "./format";
+
+const EM_DASH = "\u2014";
+
+// Use a fixed UTC date to avoid timezone flakiness in CI.
+// We test that the formatters produce *some* reasonable output rather than
+// asserting exact locale strings, since locale rendering varies by OS/ICU.
+const ISO = "2026-03-27T14:30:00Z";
+const DATE_OBJ = new Date(ISO);
+const EPOCH_MS = DATE_OBJ.getTime();
+
+describe("formatDate", () => {
+  test("returns em-dash for null", () => {
+    expect(formatDate(null)).toBe(EM_DASH);
+  });
+
+  test("returns em-dash for undefined", () => {
+    expect(formatDate(undefined)).toBe(EM_DASH);
+  });
+
+  test("returns em-dash for invalid date string", () => {
+    expect(formatDate("not-a-date")).toBe(EM_DASH);
+  });
+
+  test("formats valid ISO string", () => {
+    const result = formatDate(ISO);
+    expect(result).toContain("2026");
+    expect(result).not.toBe(EM_DASH);
+  });
+
+  test("formats Date object", () => {
+    const result = formatDate(DATE_OBJ);
+    expect(result).toContain("2026");
+  });
+
+  test("formats numeric timestamp", () => {
+    const result = formatDate(EPOCH_MS);
+    expect(result).toContain("2026");
+  });
+
+  test("handles epoch zero as valid date", () => {
+    const result = formatDate(0);
+    expect(result).toContain("1970");
+    expect(result).not.toBe(EM_DASH);
+  });
+});
+
+describe("formatLongDate", () => {
+  test("returns em-dash for null", () => {
+    expect(formatLongDate(null)).toBe(EM_DASH);
+  });
+
+  test("uses long month name (en-US)", () => {
+    const result = formatLongDate(ISO);
+    expect(result).toContain("March");
+    expect(result).toContain("2026");
+  });
+});
+
+describe("formatDateTime", () => {
+  test("returns em-dash for null", () => {
+    expect(formatDateTime(null)).toBe(EM_DASH);
+  });
+
+  test("returns em-dash for invalid string", () => {
+    expect(formatDateTime("nope")).toBe(EM_DASH);
+  });
+
+  test("includes year and time components", () => {
+    const result = formatDateTime(ISO);
+    expect(result).toContain("2026");
+    // Should contain time separator (colon between hour:minute)
+    expect(result).toMatch(/\d{1,2}:\d{2}/);
+  });
+});
+
+describe("formatShortDateTime", () => {
+  test("returns em-dash for null", () => {
+    expect(formatShortDateTime(null)).toBe(EM_DASH);
+  });
+
+  test("includes time but not year", () => {
+    const result = formatShortDateTime(ISO);
+    expect(result).toMatch(/\d{1,2}:\d{2}/);
+    expect(result).not.toContain("2026");
+  });
+});
+
+describe("formatNumber", () => {
+  test("formats millions with M suffix", () => {
+    expect(formatNumber(1_500_000)).toBe("1.5M");
+  });
+
+  test("formats thousands with K suffix", () => {
+    expect(formatNumber(2_500)).toBe("2.5K");
+  });
+
+  test("formats small numbers with locale separators", () => {
+    const result = formatNumber(999);
+    expect(result).toContain("999");
+  });
+
+  test("formats exact million boundary", () => {
+    expect(formatNumber(1_000_000)).toBe("1.0M");
+  });
+
+  test("formats exact thousand boundary", () => {
+    expect(formatNumber(1_000)).toBe("1.0K");
+  });
+});

package/templates/nextjs-standalone/src/lib/format.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared date/time formatting helpers for admin pages and UI components.
+ *
+ * All helpers accept nullable input and return "—" for missing or invalid dates.
+ */
+
+type DateInput = Date | string | number | null | undefined;
+
+function toSafeDate(date: DateInput): Date | null {
+  if (date == null) return null;
+  const d = date instanceof Date ? date : new Date(date);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** "Mar 27, 2026" — date only, short month. */
+export function formatDate(date: DateInput): string {
+  const d = toSafeDate(date);
+  if (!d) return "\u2014";
+  return d.toLocaleDateString(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+}
+
+/** "March 27, 2026" — date only, long month. Used by date-filter UI. */
+export function formatLongDate(date: DateInput): string {
+  const d = toSafeDate(date);
+  if (!d) return "\u2014";
+  return d.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "long",
+    day: "numeric",
+  });
+}
+
+/** "Mar 27, 2026, 2:30 PM" — date + time, short month. */
+export function formatDateTime(date: DateInput): string {
+  const d = toSafeDate(date);
+  if (!d) return "\u2014";
+  return d.toLocaleString(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/** Format a number with K/M suffixes for compact display. */
+export function formatNumber(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+  return n.toLocaleString();
+}
+
+/** "Mar 27, 2:30 PM" — date + time without year, short month. */
+export function formatShortDateTime(date: DateInput): string {
+  const d = toSafeDate(date);
+  if (!d) return "\u2014";
+  return d.toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}