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

package/src/logger.ts

@@ -0,0 +1,198 @@
+/**
+ * Structured pino logger. Emails and ids are redacted in production and
+ * passed through in development; credential fields are always redacted.
+ *
+ * ```typescript
+ * import { createLogger } from "@intelligo-dev/core/logger";
+ * const log = createLogger("MyModule");
+ * log.info("User created", { email: "user@example.com" });
+ * // Production: {"level":30,"module":"MyModule","msg":"User created","email":"u***@example.com"}
+ * // Development: {"level":30,"module":"MyModule","msg":"User created","email":"user@example.com"}
+ * ```
+ */
+
+import pino from "pino";
+
+const isProduction = process.env.NODE_ENV === "production";
+
+/**
+ * Redact email addresses in production.
+ * user@example.com -> u***@example.com
+ */
+function redactEmail(email: string): string {
+  if (!isProduction) return email;
+  const [local, domain] = email.split("@");
+  if (!local || !domain) return "***@***";
+  return `${local[0]}***@${domain}`;
+}
+
+/**
+ * Redact IDs in production (workspace IDs, UUIDs).
+ * ws_abc123def456 -> ws_a...f456
+ * 550e8400-e29b-41d4-a716-446655440000 -> 550e...0000
+ */
+function redactId(id: string): string {
+  if (!isProduction) return id;
+  if (id.length <= 8) return id;
+  return `${id.slice(0, 4)}...${id.slice(-4)}`;
+}
+
+/**
+ * Field name fragments whose values are always replaced with [REDACTED], in
+ * every environment. Exported so an error reporter's scrubber can share the
+ * list.
+ */
+export const CREDENTIAL_KEY_FRAGMENTS = [
+  "password",
+  "passwd",
+  "secret",
+  "token",
+  "apikey",
+  "api_key",
+  "authorization",
+  "auth_header",
+  "cookie",
+  "session_token",
+  "session_secret",
+  "credit_card",
+  "creditcard",
+  "card_number",
+  "cvv",
+] as const;
+
+/** True when `key` contains any credential fragment (case-insensitive substring). */
+export function isCredentialKey(key: string): boolean {
+  const lower = key.toLowerCase();
+  return CREDENTIAL_KEY_FRAGMENTS.some((needle) => lower.includes(needle));
+}
+
+/**
+ * An identifier's key: `id`, `userId`, `workspace_id`. Matched as a
+ * suffix, not a substring, so `provider` or `paid` keep their values.
+ */
+function isIdKey(key: string): boolean {
+  return /^id$|[a-z0-9]Id$|[_-]id$/.test(key) || /workspace/i.test(key);
+}
+
+/** Nested objects and arrays are walked, to this depth, so a credential inside one is still found. */
+const MAX_REDACT_DEPTH = 6;
+
+function redactValue(key: string, value: unknown, depth: number): unknown {
+  if (isCredentialKey(key)) return "[REDACTED]";
+
+  if (value !== null && typeof value === "object") {
+    if (depth >= MAX_REDACT_DEPTH) return "[TRUNCATED]";
+    if (Array.isArray(value)) {
+      return value.map((item) => redactValue(key, item, depth + 1));
+    }
+    if (Object.getPrototypeOf(value) === Object.prototype) {
+      return redactObject(value as Record<string, unknown>, depth + 1);
+    }
+    return value;
+  }
+
+  // Email and id redaction is production-only, so development logs show
+  // real values.
+  if (!isProduction || typeof value !== "string") return value;
+  if (key.toLowerCase().includes("email")) return redactEmail(value);
+  if (isIdKey(key)) return redactId(value);
+  return value;
+}
+
+function redactObject(
+  data: Record<string, unknown>,
+  depth: number
+): Record<string, unknown> {
+  const redacted: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    redacted[key] = redactValue(key, value, depth);
+  }
+  return redacted;
+}
+
+function redactData(data: Record<string, unknown>): Record<string, unknown> {
+  return redactObject(data, 0);
+}
+
+const baseLogger = pino({
+  level: isProduction ? "info" : "debug",
+  formatters: {
+    level(label) {
+      return { level: label };
+    },
+  },
+  timestamp: isProduction ? pino.stdTimeFunctions.isoTime : false,
+});
+
+class Logger {
+  private pino: pino.Logger;
+
+  constructor(context: string) {
+    this.pino = baseLogger.child({ module: context });
+  }
+
+  info(message: string, data?: Record<string, unknown>) {
+    if (data) {
+      this.pino.info(redactData(data), message);
+    } else {
+      this.pino.info(message);
+    }
+  }
+
+  warn(message: string, data?: Record<string, unknown>) {
+    if (data) {
+      this.pino.warn(redactData(data), message);
+    } else {
+      this.pino.warn(message);
+    }
+  }
+
+  error(message: string, data?: Record<string, unknown>) {
+    if (data) {
+      this.pino.error(redactData(data), message);
+    } else {
+      this.pino.error(message);
+    }
+  }
+
+  debug(message: string, data?: Record<string, unknown>) {
+    if (data) {
+      this.pino.debug(redactData(data), message);
+    } else {
+      this.pino.debug(message);
+    }
+  }
+}
+
+export function createLogger(context: string): Logger {
+  return new Logger(context);
+}
+
+/**
+ * A logger writing to a custom pino destination, for capturing output in
+ * tests.
+ * @internal
+ */
+export function _createLoggerWithStream(
+  context: string,
+  stream: pino.DestinationStream
+): Logger {
+  const customBase = pino(
+    {
+      level: isProduction ? "info" : "debug",
+      formatters: {
+        level(label) {
+          return { level: label };
+        },
+      },
+      timestamp: false,
+    },
+    stream
+  );
+  const instance = new Logger(context);
+  (instance as any).pino = customBase.child({ module: context });
+  return instance;
+}
+
+export { Logger };
+export const logger = createLogger("app");

package/src/money.ts

@@ -0,0 +1,270 @@
+/**
+ * Money, in one unit, with the currency attached. Imports nothing:
+ * `@intelligo-dev/executions/pricing` is a zero-import leaf that client
+ * bundles reach, and it needs these types.
+ *
+ * **Micros, not minor units.** A chat turn on a cheap model costs a
+ * fraction of a cent; rounding it to whole cents overcharges by more than a
+ * third on every request.
+ *
+ * **Currency on the amount, not in a global.** A bare `number` lets one
+ * unit be sold as another; here the currency travels with the amount and
+ * `add` refuses to mix two.
+ */
+
+declare const isoTag: unique symbol;
+declare const microsTag: unique symbol;
+
+/** An ISO-4217 alphabetic code, upper-cased and validated. */
+export type CurrencyCode = string & { readonly [isoTag]: true };
+
+/** An integer number of millionths of one major currency unit. */
+export type Micros = number & { readonly [microsTag]: true };
+
+/** An amount and the currency it is denominated in. */
+export type Money = {
+  readonly amount: Micros;
+  readonly currency: CurrencyCode;
+};
+
+/** Thrown for every misuse in this module, so callers can catch one type. */
+export class MoneyError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+    this.name = "MoneyError";
+  }
+}
+
+const MICROS_PER_UNIT = 1_000_000;
+
+/**
+ * Currencies whose minor unit is not the usual hundredth; everything else
+ * is 2. Getting this wrong charges ¥100,000 instead of ¥1,000, because
+ * Stripe takes zero-decimal currencies in whole units.
+ */
+const MINOR_EXPONENT: Readonly<Record<string, 0 | 2 | 3>> = {
+  BIF: 0,
+  CLP: 0,
+  DJF: 0,
+  GNF: 0,
+  ISK: 0,
+  JPY: 0,
+  KMF: 0,
+  KRW: 0,
+  MGA: 0,
+  MNT: 0,
+  PYG: 0,
+  RWF: 0,
+  UGX: 0,
+  UYI: 0,
+  VND: 0,
+  VUV: 0,
+  XAF: 0,
+  XOF: 0,
+  XPF: 0,
+  BHD: 3,
+  IQD: 3,
+  JOD: 3,
+  KWD: 3,
+  LYD: 3,
+  OMR: 3,
+  TND: 3,
+};
+
+/**
+ * Validates and normalises an ISO-4217 code. Shape only: a list would go
+ * stale and block a deployment selling in a code it does not know.
+ * `minorExponent` gives an unknown code its default.
+ */
+export function currency(code: string): CurrencyCode {
+  const upper = code.toUpperCase();
+  if (!/^[A-Z]{3}$/.test(upper)) {
+    throw new MoneyError(
+      "invalid_currency",
+      `"${code}" is not an ISO-4217 alphabetic code (three letters).`
+    );
+  }
+  return upper as CurrencyCode;
+}
+
+/**
+ * An integer count of micros, up to `Number.MAX_SAFE_INTEGER` (about 9
+ * billion major units) — low enough to catch a value in the wrong unit.
+ */
+export function micros(value: number): Micros {
+  if (!Number.isInteger(value)) {
+    throw new MoneyError(
+      "not_an_integer",
+      `Micros must be a whole number; received ${value}. Convert with fromMajor/fromMinor rather than multiplying by hand.`
+    );
+  }
+  if (!Number.isSafeInteger(value)) {
+    throw new MoneyError(
+      "out_of_range",
+      `${value} micros exceeds the safe integer range.`
+    );
+  }
+  return value as Micros;
+}
+
+export function money(amount: number, code: string | CurrencyCode): Money {
+  return { amount: micros(amount), currency: currency(code) };
+}
+
+/** How many decimal places this currency's minor unit has. */
+export function minorExponent(code: CurrencyCode): 0 | 2 | 3 {
+  return MINOR_EXPONENT[code] ?? 2;
+}
+
+/** `12.34` USD → `12_340_000` micros. */
+export function fromMajor(value: number, code: string | CurrencyCode): Money {
+  return {
+    amount: micros(Math.round(value * MICROS_PER_UNIT)),
+    currency: currency(code),
+  };
+}
+
+/** `1234` cents → `12_340_000` micros. */
+export function fromMinor(value: number, code: string | CurrencyCode): Money {
+  const c = currency(code);
+  const scale = MICROS_PER_UNIT / 10 ** minorExponent(c);
+  return { amount: micros(Math.round(value * scale)), currency: c };
+}
+
+/**
+ * The integer a payment provider wants: whole units for a zero-decimal
+ * currency, hundredths for most, thousandths for a few.
+ *
+ * Rounds up. A fraction of a minor unit is money the deployment has
+ * already spent, and rounding it away means eating the difference on
+ * every transaction.
+ */
+export function toMinor(value: Money): number {
+  const scale = MICROS_PER_UNIT / 10 ** minorExponent(value.currency);
+  return Math.ceil(value.amount / scale);
+}
+
+/** The amount as a plain decimal number, for display and for charts. */
+export function toMajor(value: Money): number {
+  return value.amount / MICROS_PER_UNIT;
+}
+
+export const zero = (code: string | CurrencyCode): Money => ({
+  amount: 0 as Micros,
+  currency: currency(code),
+});
+
+function sameCurrency(a: Money, b: Money, op: string): void {
+  if (a.currency !== b.currency) {
+    throw new MoneyError(
+      "currency_mismatch",
+      `Cannot ${op} ${a.currency} and ${b.currency}. Convert one first — an exchange rate is a decision, not a coercion.`
+    );
+  }
+}
+
+export function add(a: Money, b: Money): Money {
+  sameCurrency(a, b, "add");
+  return { amount: micros(a.amount + b.amount), currency: a.currency };
+}
+
+export function subtract(a: Money, b: Money): Money {
+  sameCurrency(a, b, "subtract");
+  return { amount: micros(a.amount - b.amount), currency: a.currency };
+}
+
+/** Scale by a plain factor — a margin multiplier, a percentage, a count. */
+export function multiply(value: Money, factor: number): Money {
+  if (!Number.isFinite(factor)) {
+    throw new MoneyError("invalid_factor", `Factor must be finite.`);
+  }
+  return {
+    amount: micros(Math.ceil(value.amount * factor)),
+    currency: value.currency,
+  };
+}
+
+export function compare(a: Money, b: Money): number {
+  sameCurrency(a, b, "compare");
+  return a.amount === b.amount ? 0 : a.amount < b.amount ? -1 : 1;
+}
+
+export const isZero = (value: Money): boolean => value.amount === 0;
+export const isNegative = (value: Money): boolean => value.amount < 0;
+
+/**
+ * Convert at an explicit rate, expressed in micros so the rate itself
+ * carries no float error: `3_450_000_000` is 3450.0.
+ *
+ * There is no ambient rate and no default. A framework that guesses an
+ * exchange rate is inventing money.
+ */
+export function convert(
+  value: Money,
+  to: string | CurrencyCode,
+  rateMicros: number
+): Money {
+  const target = currency(to);
+  if (!Number.isInteger(rateMicros) || rateMicros <= 0) {
+    throw new MoneyError(
+      "invalid_rate",
+      `Rate must be a positive integer number of micros; received ${rateMicros}.`
+    );
+  }
+  if (target === value.currency) {
+    if (rateMicros !== MICROS_PER_UNIT) {
+      throw new MoneyError(
+        "invalid_rate",
+        `Converting ${value.currency} to itself at ${rateMicros / MICROS_PER_UNIT} is not a conversion.`
+      );
+    }
+    return value;
+  }
+  return {
+    amount: micros(Math.ceil((value.amount * rateMicros) / MICROS_PER_UNIT)),
+    currency: target,
+  };
+}
+
+/** Two significant digits is enough to read a sub-cent amount by. */
+const SIGNIFICANT_DIGITS = 2;
+
+/**
+ * How many decimals an amount needs to be legible.
+ *
+ * The currency's own minor unit, except when that would render a real
+ * charge as nothing: one chat turn costs a fraction of a cent, and a
+ * usage page that says every request cost `$0.00` is worse than one
+ * that says `$0.0048`. Below the minor unit the amount is shown to two
+ * significant digits, capped at the six decimals micros can hold.
+ */
+export function displayFractionDigits(value: Money): number {
+  const digits = minorExponent(value.currency);
+  const major = Math.abs(toMajor(value));
+  // Zero, and anything that still rounds to a visible minor unit, reads
+  // the way the currency is normally written.
+  if (major === 0 || major >= 10 ** -digits / 2) return digits;
+  const leadingZeros = Math.floor(-Math.log10(major));
+  return Math.min(6, leadingZeros + SIGNIFICANT_DIGITS);
+}
+
+/**
+ * Formats for a human, in their locale. `Intl` owns the symbol, its
+ * position and the separators.
+ */
+export function formatMoney(
+  value: Money,
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+): string {
+  const digits = displayFractionDigits(value);
+  return new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: value.currency,
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+    ...options,
+  }).format(toMajor(value));
+}

package/src/notifications/index.ts

@@ -0,0 +1,108 @@
+/**
+ * User notifications. User-scoped, not workspace-scoped, so a user sees
+ * their notifications from every workspace.
+ */
+
+import { db } from "../db";
+import { notifications } from "../db/schema";
+import { eq, and, desc, count } from "drizzle-orm";
+import type { CreateNotificationParams } from "./types";
+
+export type { NotificationType, CreateNotificationParams } from "./types";
+
+export {
+  triggerQuotaNotification,
+  triggerTrialNotification,
+  triggerPaymentFailedNotification,
+  triggerTeamMemberJoinedNotification,
+} from "./triggers";
+
+/** Creates a notification; `metadata` is stored as a JSON string. */
+export async function createNotification(params: CreateNotificationParams) {
+  const [notification] = await db
+    .insert(notifications)
+    .values({
+      userId: params.userId,
+      workspaceId: params.workspaceId,
+      type: params.type,
+      title: params.title,
+      message: params.message,
+      metadata: params.metadata ? JSON.stringify(params.metadata) : null,
+    })
+    .returning();
+
+  return notification;
+}
+
+/** The user's unread notifications, newest first. */
+export async function getUnreadNotifications(
+  userId: string,
+  limit: number = 20
+) {
+  const rows = await db
+    .select()
+    .from(notifications)
+    .where(
+      and(eq(notifications.userId, userId), eq(notifications.isRead, false))
+    )
+    .orderBy(desc(notifications.createdAt))
+    .limit(limit);
+
+  return rows.map(parseMetadata);
+}
+
+/** All of the user's notifications, newest first. */
+export async function getNotifications(userId: string, limit: number = 50) {
+  const rows = await db
+    .select()
+    .from(notifications)
+    .where(eq(notifications.userId, userId))
+    .orderBy(desc(notifications.createdAt))
+    .limit(limit);
+
+  return rows.map(parseMetadata);
+}
+
+export async function getNotificationCount(userId: string): Promise<number> {
+  const [result] = await db
+    .select({ count: count() })
+    .from(notifications)
+    .where(
+      and(eq(notifications.userId, userId), eq(notifications.isRead, false))
+    );
+
+  return result?.count ?? 0;
+}
+
+/** Filters on userId as well, so users can only mark their own. */
+export async function markAsRead(notificationId: string, userId: string) {
+  await db
+    .update(notifications)
+    .set({ isRead: true })
+    .where(
+      and(
+        eq(notifications.id, notificationId),
+        eq(notifications.userId, userId)
+      )
+    );
+}
+
+export async function markAllAsRead(userId: string) {
+  await db
+    .update(notifications)
+    .set({ isRead: true })
+    .where(
+      and(eq(notifications.userId, userId), eq(notifications.isRead, false))
+    );
+}
+
+function parseMetadata<T extends { metadata: string | null }>(
+  notification: T
+): T & { metadata: Record<string, unknown> | null } {
+  return {
+    ...notification,
+    metadata: notification.metadata
+      ? (JSON.parse(notification.metadata) as Record<string, unknown>)
+      : null,
+  };
+}