@intelligo-dev/core 1.0.0-beta.1 → 1.0.0-beta.13

package/src/email/templates/workspace-invitation.tsx

@@ -0,0 +1,105 @@
+import { Button, Section, Text } from "@react-email/components";
+import * as React from "react";
+import { BaseLayout } from "./base-layout";
+
+export interface WorkspaceInvitationEmailProps {
+  inviterName: string;
+  workspaceName: string;
+  role: string;
+  acceptUrl: string;
+  declineUrl: string;
+}
+
+export function WorkspaceInvitationEmail({
+  inviterName,
+  workspaceName,
+  role,
+  acceptUrl,
+  declineUrl,
+}: WorkspaceInvitationEmailProps) {
+  const text = {
+    preview: `${inviterName} invited you to join ${workspaceName}`,
+    heading: "You're invited!",
+    body: "has invited you to join the workspace",
+    as: "as a",
+    invitedYou: "",
+    acceptButton: "Accept Invitation",
+    declineButton: "Decline",
+    note: "This invitation expires in 7 days.",
+  };
+
+  return (
+    <BaseLayout preview={text.preview}>
+      <Text style={headingStyle}>{text.heading}</Text>
+      <Text style={bodyTextStyle}>
+        <strong>{inviterName}</strong> {text.body}{" "}
+        <strong>&lsquo;{workspaceName}&rsquo;</strong> {text.as}{" "}
+        <strong>{role}</strong>
+        {text.invitedYou ? ` ${text.invitedYou}` : ""}.
+      </Text>
+      <Section style={buttonGroupStyle}>
+        <Button href={acceptUrl} style={acceptButtonStyle}>
+          {text.acceptButton}
+        </Button>
+        <Button href={declineUrl} style={declineButtonStyle}>
+          {text.declineButton}
+        </Button>
+      </Section>
+      <Text style={noteStyle}>{text.note}</Text>
+    </BaseLayout>
+  );
+}
+
+const headingStyle: React.CSSProperties = {
+  color: "#18181b",
+  fontSize: "22px",
+  fontWeight: 700,
+  lineHeight: "30px",
+  margin: "0 0 16px",
+};
+
+const bodyTextStyle: React.CSSProperties = {
+  color: "#18181b",
+  fontSize: "15px",
+  lineHeight: "24px",
+  margin: "0 0 12px",
+};
+
+const buttonGroupStyle: React.CSSProperties = {
+  marginTop: "8px",
+};
+
+const acceptButtonStyle: React.CSSProperties = {
+  backgroundColor: "#7c3aed",
+  borderRadius: "6px",
+  color: "#ffffff",
+  display: "inline-block",
+  fontSize: "15px",
+  fontWeight: 600,
+  lineHeight: "100%",
+  padding: "12px 24px",
+  textDecoration: "none",
+  textAlign: "center" as const,
+  marginRight: "12px",
+};
+
+const declineButtonStyle: React.CSSProperties = {
+  backgroundColor: "transparent",
+  border: "1px solid #d4d4d8",
+  borderRadius: "6px",
+  color: "#71717a",
+  display: "inline-block",
+  fontSize: "15px",
+  fontWeight: 600,
+  lineHeight: "100%",
+  padding: "12px 24px",
+  textDecoration: "none",
+  textAlign: "center" as const,
+};
+
+const noteStyle: React.CSSProperties = {
+  color: "#71717a",
+  fontSize: "13px",
+  lineHeight: "20px",
+  marginTop: "20px",
+};

package/src/env.ts

@@ -0,0 +1,180 @@
+/**
+ * Startup validation of environment variables: a missing required variable
+ * throws immediately instead of when its feature is first used. Some are
+ * optional in development (STRIPE_*, RESEND_API_KEY).
+ */
+
+type EnvVar = {
+  name: string;
+  required: boolean;
+  description: string;
+  /** Optional minimum length — used for secret strength checks */
+  minLength?: number;
+};
+
+// Only variables the framework itself reads. A model provider's key is
+// absent on purpose: which provider a deployment calls is the product's
+// choice, and its SDK reports a missing key on the first request.
+const ENV_VARS: EnvVar[] = [
+  {
+    name: "DATABASE_URL",
+    required: true,
+    description: "PostgreSQL connection string",
+  },
+  {
+    name: "BETTER_AUTH_SECRET",
+    required: true,
+    description:
+      "Better-Auth session encryption key (AUTH_SECRET is accepted as a legacy alias)",
+    minLength: 32,
+  },
+  {
+    name: "NEXT_PUBLIC_APP_URL",
+    required: true,
+    description: "Application base URL for auth and redirects",
+  },
+  {
+    name: "STRIPE_SECRET_KEY",
+    required: false,
+    description: "Stripe API key (billing features)",
+  },
+  {
+    name: "STRIPE_WEBHOOK_SECRET",
+    required: false,
+    description: "Stripe webhook signature secret",
+  },
+  {
+    name: "RESEND_API_KEY",
+    required: false,
+    description: "Resend API key (email features)",
+  },
+  {
+    name: "LOOPS_API_KEY",
+    required: false,
+    description:
+      "Loops API key (email features; templates mapped via LOOPS_TRANSACTIONAL_ID_*)",
+  },
+  {
+    name: "EMAIL_PROVIDER",
+    required: false,
+    description: "Explicit email provider selection (resend | loops | console)",
+  },
+  // Cron endpoints gate on a Bearer header equal to CRON_SECRET. Optional
+  // in development; production should set at least 32 characters.
+  {
+    name: "CRON_SECRET",
+    required: false,
+    description: "Shared secret for /api/cron/* Bearer auth",
+    minLength: 32,
+  },
+];
+
+export function validateEnv(): {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  for (const envVar of ENV_VARS) {
+    let value = process.env[envVar.name];
+    // Better-Auth reads BETTER_AUTH_SECRET then AUTH_SECRET; the CLI, the
+    // scaffold and this validator use the former.
+    if (
+      envVar.name === "BETTER_AUTH_SECRET" &&
+      !value &&
+      process.env.AUTH_SECRET
+    ) {
+      value = process.env.AUTH_SECRET;
+      warnings.push(
+        "AUTH_SECRET is set but BETTER_AUTH_SECRET is not — rename it; AUTH_SECRET is a legacy alias"
+      );
+    }
+    if (!value || value.trim() === "") {
+      if (envVar.required) {
+        errors.push(
+          `Missing required env var: ${envVar.name} — ${envVar.description}`
+        );
+      } else {
+        warnings.push(
+          `Missing optional env var: ${envVar.name} — ${envVar.description}`
+        );
+      }
+      continue;
+    }
+    if (envVar.minLength && value.length < envVar.minLength) {
+      const msg = `${envVar.name} is shorter than ${envVar.minLength} chars — too weak for ${envVar.description}`;
+      if (envVar.required) {
+        errors.push(msg);
+      } else {
+        warnings.push(msg);
+      }
+    }
+  }
+
+  // Resend rejects a send without a sender on a verified domain, and the
+  // framework has no domain of its own to fall back on. Loops takes the
+  // sender from each template, so only Resend is checked.
+  const emailProvider = process.env.EMAIL_PROVIDER?.toLowerCase();
+  const sendsThroughResend =
+    Boolean(process.env.RESEND_API_KEY?.trim()) &&
+    emailProvider !== "loops" &&
+    emailProvider !== "console";
+  if (sendsThroughResend && !process.env.EMAIL_FROM?.trim()) {
+    warnings.push(
+      'RESEND_API_KEY is set but EMAIL_FROM is not — every email fails until EMAIL_FROM names a sender on a domain verified with Resend, e.g. "Acme <noreply@acme.com>"'
+    );
+  }
+
+  // Production safety checks
+  if (process.env.NODE_ENV === "production") {
+    const appUrl = process.env.NEXT_PUBLIC_APP_URL?.trim();
+    if (appUrl && !appUrl.startsWith("https://")) {
+      warnings.push(
+        `NEXT_PUBLIC_APP_URL is ${appUrl}, not an https URL — auth callbacks, email links and secure cookies are built from it`
+      );
+    }
+    if (!process.env.RESEND_API_KEY && !process.env.LOOPS_API_KEY) {
+      warnings.push(
+        "No email provider (RESEND_API_KEY or LOOPS_API_KEY) — sign-ups are not email-verified and emails only reach the server console"
+      );
+    }
+    if (process.env.STRIPE_SECRET_KEY?.startsWith("sk_test_")) {
+      warnings.push(
+        "STRIPE_SECRET_KEY is a test key in production environment"
+      );
+    }
+    if (!process.env.CRON_SECRET || process.env.CRON_SECRET.length < 32) {
+      // A warning, not an error: the framework ships no cron route of its
+      // own, and the maintenance route refuses to serve without it.
+      warnings.push(
+        "CRON_SECRET unset or shorter than 32 chars — required by any /api/cron/* route you mount"
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Call during app initialization. Throws on missing required variables;
+ * logs warnings for optional ones.
+ */
+export function assertEnv(): void {
+  const { valid, errors, warnings } = validateEnv();
+
+  for (const warning of warnings) {
+    console.warn(`[Env] ${warning}`);
+  }
+
+  if (!valid) {
+    console.error("[Env] Missing required environment variables:");
+    for (const error of errors) {
+      console.error(`  - ${error}`);
+    }
+    throw new Error(
+      `Missing ${errors.length} required environment variable(s). See logs above.`
+    );
+  }
+}

package/src/identity/audit.ts

@@ -0,0 +1,65 @@
+/**
+ * Writes `user_memory_audit` rows. Core may not import
+ * `@intelligo-dev/audit` (only audit -> core is allowed), so the write lives
+ * here and audit exports only the event contract. Internal to identity; not
+ * re-exported.
+ */
+
+import { db } from "../db";
+import { userMemoryAudit } from "../db/schema";
+import type {
+  AuditTargetKind,
+  AuditAction,
+  AuditActorKind,
+  UserMemoryAuditRow,
+} from "../db/schema";
+import { IdentityServiceError } from "./errors";
+
+export type RecordMemoryAuditInput = {
+  userId: string;
+  workspaceId: string;
+  targetKind: AuditTargetKind;
+  targetId: string;
+  action: AuditAction;
+  actorKind: AuditActorKind;
+  actorId?: string;
+  beforeValue?: unknown;
+  afterValue?: unknown;
+  reason?: string;
+};
+
+/**
+ * `writer` is the transaction of the mutation being audited, so the
+ * change and its record commit or fail together.
+ */
+export async function recordMemoryAudit(
+  input: RecordMemoryAuditInput,
+  writer: Pick<typeof db, "insert"> = db
+): Promise<UserMemoryAuditRow> {
+  const [row] = await writer
+    .insert(userMemoryAudit)
+    .values({
+      id: crypto.randomUUID(),
+      userId: input.userId,
+      workspaceId: input.workspaceId,
+      targetKind: input.targetKind,
+      targetId: input.targetId,
+      action: input.action,
+      actorKind: input.actorKind,
+      actorId: input.actorId,
+      beforeValue: input.beforeValue,
+      afterValue: input.afterValue,
+      reason: input.reason,
+      createdAt: new Date(),
+    })
+    .returning();
+
+  if (!row) {
+    throw new IdentityServiceError(
+      "database_error",
+      "Failed to record memory audit event"
+    );
+  }
+
+  return row;
+}

package/src/identity/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Thrown by the identity service for every failure it recognizes. Shaping
+ * it into a transport envelope is the caller's job.
+ */
+
+/**
+ * - `not_found` — no fact exists at the given id within the actor's
+ *   workspace/user scope. Covers both "no such fact" and "a fact that
+ *   belongs to a different user in the same workspace" — deliberately
+ *   indistinguishable, so an id never reveals whose data exists behind it.
+ * - `invalid_input` — a caller-supplied argument failed a basic
+ *   invariant (e.g. an empty fact id).
+ * - `database_error` — the underlying insert did not return the row it
+ *   was expected to.
+ */
+export type IdentityServiceErrorCode =
+  "not_found" | "invalid_input" | "database_error";
+
+export class IdentityServiceError extends Error {
+  readonly code: IdentityServiceErrorCode;
+  // The ES2020 target predates `Error.cause`; declared so `err.cause`
+  // type-checks for callers.
+  readonly cause?: unknown;
+
+  constructor(
+    code: IdentityServiceErrorCode,
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(message);
+    this.name = "IdentityServiceError";
+    this.code = code;
+    if (options?.cause !== undefined) {
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+    Object.setPrototypeOf(this, IdentityServiceError.prototype);
+  }
+}
+
+export function isIdentityServiceError(
+  error: unknown
+): error is IdentityServiceError {
+  return error instanceof IdentityServiceError;
+}

package/src/identity/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Privacy-facing reads and mutations over the user identity graph: fact
+ * listing and deletion, full-identity export, and the memory-audit trail.
+ */
+
+export {
+  listFacts,
+  deleteFact,
+  exportIdentity,
+  getAuditTrail,
+} from "./service";
+
+export {
+  IdentityServiceError,
+  isIdentityServiceError,
+  type IdentityServiceErrorCode,
+} from "./errors";
+
+export type {
+  IdentityActor,
+  IdentityExport,
+  UserFact,
+  UserMemory,
+  UserProfileSnapshot,
+  UserMemoryAuditRow,
+} from "./types";

package/src/identity/service.ts

@@ -0,0 +1,202 @@
+/**
+ * Server-only reads and mutations over the user identity graph: fact
+ * listing and deletion, a full data export, and the memory-audit trail.
+ *
+ * `deleteFact` does not touch the cached profile snapshot; profile synthesis
+ * is the product's AI code, so a caller that owns it re-triggers it.
+ *
+ * Callers pass a resolved actor (workspaceId, userId); core cannot depend on
+ * `@intelligo-dev/auth`. Every query filters by both ids. Every mutation
+ * writes a `user_memory_audit` row. Failures throw `IdentityServiceError`.
+ */
+
+import { and, desc, eq } from "drizzle-orm";
+import { db } from "../db";
+import {
+  userFacts,
+  userMemories,
+  userProfileSnapshots,
+  userMemoryAudit,
+} from "../db/schema";
+import type { UserFact, UserMemoryAuditRow } from "../db/schema";
+import { recordMemoryAudit } from "./audit";
+import { IdentityServiceError } from "./errors";
+import type { IdentityActor, IdentityExport } from "./types";
+
+/**
+ * Returns the fact if the actor owns it. Throws
+ * IdentityServiceError("not_found") otherwise — another user's fact is
+ * indistinguishable from a missing one.
+ */
+async function verifyFact(
+  actor: IdentityActor,
+  factId: string
+): Promise<UserFact> {
+  const [fact] = await db
+    .select()
+    .from(userFacts)
+    .where(eq(userFacts.id, factId))
+    .limit(1);
+
+  if (
+    !fact ||
+    fact.userId !== actor.userId ||
+    fact.workspaceId !== actor.workspaceId
+  ) {
+    throw new IdentityServiceError("not_found", "Fact not found");
+  }
+
+  return fact;
+}
+
+/** List the actor's facts, most important and most confident first. */
+export async function listFacts(actor: IdentityActor): Promise<UserFact[]> {
+  return db
+    .select()
+    .from(userFacts)
+    .where(
+      and(
+        eq(userFacts.userId, actor.userId),
+        eq(userFacts.workspaceId, actor.workspaceId)
+      )
+    )
+    .orderBy(desc(userFacts.importance), desc(userFacts.confidence));
+}
+
+const MAX_AUDIT_LIMIT = 200;
+
+/**
+ * Read the actor's memory-audit trail, most recent first. Optionally
+ * scoped to a single target (e.g. one fact's history).
+ */
+export async function getAuditTrail(
+  actor: IdentityActor,
+  options?: { limit?: number; targetId?: string }
+): Promise<UserMemoryAuditRow[]> {
+  const limit = Math.min(
+    Math.max(1, options?.limit ?? MAX_AUDIT_LIMIT),
+    MAX_AUDIT_LIMIT
+  );
+
+  const baseClause = and(
+    eq(userMemoryAudit.userId, actor.userId),
+    eq(userMemoryAudit.workspaceId, actor.workspaceId)
+  );
+
+  return db
+    .select()
+    .from(userMemoryAudit)
+    .where(
+      options?.targetId
+        ? and(baseClause, eq(userMemoryAudit.targetId, options.targetId))
+        : baseClause
+    )
+    .orderBy(desc(userMemoryAudit.createdAt))
+    .limit(limit);
+}
+
+/**
+ * Delete a fact and record the deletion in the audit trail. Throws
+ * `invalid_input` for an empty id and `not_found` for anything outside
+ * the actor's scope. Does not re-trigger profile synthesis.
+ */
+export async function deleteFact(
+  actor: IdentityActor,
+  factId: string
+): Promise<void> {
+  if (!factId || factId.trim().length === 0) {
+    throw new IdentityServiceError("invalid_input", "factId is required");
+  }
+
+  const existing = await verifyFact(actor, factId);
+
+  await db.transaction(async (tx) => {
+    await tx.delete(userFacts).where(eq(userFacts.id, factId));
+    await recordMemoryAudit(
+      {
+        userId: actor.userId,
+        workspaceId: actor.workspaceId,
+        targetKind: "fact",
+        targetId: factId,
+        action: "delete",
+        actorKind: "user",
+        actorId: actor.userId,
+        beforeValue: existing,
+        reason: "user requested deletion",
+      },
+      tx
+    );
+  });
+}
+
+/**
+ * The actor's full identity graph — facts, memories, latest profile
+ * snapshot and audit trail — for a "download my data" flow. Records its own
+ * audit row (action "export").
+ */
+export async function exportIdentity(
+  actor: IdentityActor
+): Promise<IdentityExport> {
+  // Recorded before the reads so the export's own audit row is part of
+  // the export — the trail a user downloads should show that download.
+  await recordMemoryAudit({
+    userId: actor.userId,
+    workspaceId: actor.workspaceId,
+    targetKind: "snapshot",
+    targetId: actor.userId,
+    action: "export",
+    actorKind: "user",
+    actorId: actor.userId,
+    reason: "user requested data export",
+  });
+
+  const [facts, memories, snapshotRows, audit] = await Promise.all([
+    db
+      .select()
+      .from(userFacts)
+      .where(
+        and(
+          eq(userFacts.userId, actor.userId),
+          eq(userFacts.workspaceId, actor.workspaceId)
+        )
+      ),
+    db
+      .select()
+      .from(userMemories)
+      .where(
+        and(
+          eq(userMemories.userId, actor.userId),
+          eq(userMemories.workspaceId, actor.workspaceId)
+        )
+      ),
+    db
+      .select()
+      .from(userProfileSnapshots)
+      .where(
+        and(
+          eq(userProfileSnapshots.userId, actor.userId),
+          eq(userProfileSnapshots.workspaceId, actor.workspaceId)
+        )
+      )
+      .limit(1),
+    db
+      .select()
+      .from(userMemoryAudit)
+      .where(
+        and(
+          eq(userMemoryAudit.userId, actor.userId),
+          eq(userMemoryAudit.workspaceId, actor.workspaceId)
+        )
+      )
+      .orderBy(desc(userMemoryAudit.createdAt)),
+  ]);
+
+  return {
+    exportedAt: new Date().toISOString(),
+    user: { id: actor.userId, workspaceId: actor.workspaceId },
+    facts,
+    memories,
+    snapshot: snapshotRows[0] ?? null,
+    audit,
+  };
+}

package/src/identity/types.ts

@@ -0,0 +1,28 @@
+import type {
+  UserFact,
+  UserMemory,
+  UserProfileSnapshot,
+  UserMemoryAuditRow,
+} from "../db/schema";
+
+export type { UserFact, UserMemory, UserProfileSnapshot, UserMemoryAuditRow };
+
+/** Resolved actor identity — every query is scoped to this pair. */
+export type IdentityActor = {
+  workspaceId: string;
+  userId: string;
+};
+
+/**
+ * Full identity dump for a GDPR-style "download my data" flow: every
+ * fact and memory the actor owns, their latest synthesized profile
+ * snapshot (if one exists), and their complete memory-audit trail.
+ */
+export type IdentityExport = {
+  exportedAt: string;
+  user: { id: string; workspaceId: string };
+  facts: UserFact[];
+  memories: UserMemory[];
+  snapshot: UserProfileSnapshot | null;
+  audit: UserMemoryAuditRow[];
+};

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./db";
+
+// Everything else is a subpath import: @intelligo-dev/core/email,
+// /notifications, /conversations, /documents, /identity, /logger, /env.