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

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,29 @@
+/**
+ * Privacy-facing reads and mutations over the user identity graph: fact
+ * listing and deletion, the profile snapshot's write, full-identity
+ * export, and the memory-audit trail.
+ */
+
+export {
+  listFacts,
+  deleteFact,
+  saveProfileSnapshot,
+  exportIdentity,
+  getAuditTrail,
+} from "./service";
+
+export {
+  IdentityServiceError,
+  isIdentityServiceError,
+  type IdentityServiceErrorCode,
+} from "./errors";
+
+export type {
+  IdentityActor,
+  IdentityExport,
+  SaveProfileSnapshotInput,
+  UserFact,
+  UserMemory,
+  UserProfileSnapshot,
+  UserMemoryAuditRow,
+} from "./types";

package/src/identity/service.ts

@@ -0,0 +1,303 @@
+/**
+ * Server-only reads and mutations over the user identity graph: fact
+ * listing and deletion, the profile snapshot's write, 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 and
+ * stores the result with `saveProfileSnapshot`.
+ *
+ * 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, sql } from "drizzle-orm";
+import { db } from "../db";
+import {
+  userFacts,
+  userMemories,
+  userProfileSnapshots,
+  userMemoryAudit,
+} from "../db/schema";
+import type {
+  UserFact,
+  UserMemoryAuditRow,
+  UserProfileSnapshot,
+} from "../db/schema";
+import { recordMemoryAudit } from "./audit";
+import { IdentityServiceError } from "./errors";
+import type {
+  IdentityActor,
+  IdentityExport,
+  SaveProfileSnapshotInput,
+} 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,
+  };
+}
+
+/**
+ * Store the actor's synthesized profile — one row per user per workspace,
+ * inserted on the first synthesis and replaced on every later one. The
+ * version is bumped in the same statement (`ON CONFLICT … version + 1`),
+ * so two syntheses racing each other get two versions rather than one
+ * overwriting the other's number; it starts at 1.
+ *
+ * A field left `undefined` keeps what the row holds (null on insert); an
+ * explicit `null` clears it. `synthesizedAt` defaults to now. Records an
+ * audit row (`snapshot`, `create` or `update`) in the same transaction,
+ * attributed to `input.actorKind` — `system_job` unless the caller says
+ * otherwise. Throws `invalid_input` for an empty summary.
+ */
+export async function saveProfileSnapshot(
+  actor: IdentityActor,
+  input: SaveProfileSnapshotInput
+): Promise<UserProfileSnapshot> {
+  if (!input.summary || input.summary.trim().length === 0) {
+    throw new IdentityServiceError("invalid_input", "summary is required");
+  }
+  if (input.factsDigest === undefined || input.factsDigest === null) {
+    throw new IdentityServiceError("invalid_input", "factsDigest is required");
+  }
+
+  const replaced = {
+    summary: input.summary,
+    factsDigest: input.factsDigest,
+    synthesizedAt: input.synthesizedAt ?? new Date(),
+    ...definedOnly({
+      summaryEn: input.summaryEn,
+      summaryMn: input.summaryMn,
+      activeGoals: input.activeGoals,
+      personalitySignals: input.personalitySignals,
+      relationshipNotes: input.relationshipNotes,
+      synthesizedByModel: input.synthesizedByModel,
+      nextSynthesisAt: input.nextSynthesisAt,
+      triggerReason: input.triggerReason,
+    }),
+  };
+
+  return db.transaction(async (tx) => {
+    const [row] = await tx
+      .insert(userProfileSnapshots)
+      .values({
+        userId: actor.userId,
+        workspaceId: actor.workspaceId,
+        version: 1,
+        ...replaced,
+      })
+      .onConflictDoUpdate({
+        target: [userProfileSnapshots.userId, userProfileSnapshots.workspaceId],
+        set: {
+          ...replaced,
+          version: sql`${userProfileSnapshots.version} + 1`,
+        },
+      })
+      .returning();
+
+    if (!row) {
+      throw new IdentityServiceError(
+        "database_error",
+        "Failed to save profile snapshot"
+      );
+    }
+
+    await recordMemoryAudit(
+      {
+        userId: actor.userId,
+        workspaceId: actor.workspaceId,
+        targetKind: "snapshot",
+        targetId: actor.userId,
+        action: row.version === 1 ? "create" : "update",
+        actorKind: input.actorKind ?? "system_job",
+        actorId: input.actorId,
+        afterValue: { version: row.version, triggerReason: row.triggerReason },
+        reason: input.reason,
+      },
+      tx
+    );
+
+    return row;
+  });
+}
+
+/** The entries whose value is not `undefined` — `null` is kept, to clear. */
+function definedOnly<T extends Record<string, unknown>>(fields: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(fields).filter(([, value]) => value !== undefined)
+  ) as Partial<T>;
+}

package/src/identity/types.ts

@@ -0,0 +1,58 @@
+import type {
+  AuditActorKind,
+  SynthesisTriggerReason,
+  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[];
+};
+
+/**
+ * A synthesized profile, as `saveProfileSnapshot` stores it. The actor
+ * supplies the tenancy; the version is the store's.
+ */
+export type SaveProfileSnapshotInput = {
+  /** The summary a prompt hydrates from, in the product's primary language. */
+  summary: string;
+  summaryEn?: string | null;
+  summaryMn?: string | null;
+  /** The structured digest the summary was written from. */
+  factsDigest: unknown;
+  activeGoals?: unknown;
+  personalitySignals?: unknown;
+  relationshipNotes?: unknown;
+  /** The model that wrote it, or a label for a deterministic synthesis. */
+  synthesizedByModel?: string | null;
+  /** Default: now. */
+  synthesizedAt?: Date;
+  /** When a scheduled re-synthesis may next pick this user up. */
+  nextSynthesisAt?: Date | null;
+  triggerReason?: SynthesisTriggerReason | null;
+  /** Who the audit row names. Default `"system_job"`. */
+  actorKind?: AuditActorKind;
+  actorId?: string;
+  /** Recorded on the audit row. */
+  reason?: string;
+};

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.