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

package/src/db/schema/notifications.ts

@@ -0,0 +1,31 @@
+import { pgTable, text, timestamp, boolean, index } from "drizzle-orm/pg-core";
+
+/**
+ * User-scoped, not workspace-scoped, so a user sees their notifications from
+ * every workspace in one place. `userId` references the users table by
+ * convention (no FK); `workspaceId` is null for user-level notifications.
+ */
+export const notifications = pgTable(
+  "notifications",
+  {
+    id: text("id")
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    userId: text("user_id").notNull(),
+    workspaceId: text("workspace_id"),
+    type: text("type").notNull(),
+    title: text("title").notNull(),
+    message: text("message").notNull(),
+    isRead: boolean("is_read").notNull().default(false),
+    metadata: text("metadata"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("notifications_user_id_idx").on(table.userId),
+    index("notifications_user_id_is_read_idx").on(table.userId, table.isRead),
+    index("notifications_created_at_idx").on(table.createdAt),
+  ]
+);
+
+export type Notification = typeof notifications.$inferSelect;
+export type InsertNotification = typeof notifications.$inferInsert;

package/src/db/schema/usage.ts

@@ -0,0 +1,269 @@
+/**
+ * Token consumption per request and aggregated per period, which the quota
+ * engine checks before AI requests and records into after them.
+ */
+
+import {
+  pgTable,
+  text,
+  timestamp,
+  integer,
+  bigint,
+  real,
+  index,
+  unique,
+  jsonb,
+} from "drizzle-orm/pg-core";
+import { organization, users } from "./auth";
+
+/**
+ * One row per AI request: tokens, model and agent, for per-model and
+ * per-agent reporting.
+ */
+export const usageRecords = pgTable(
+  "usage_records",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    type: text("type").notNull(), // "ai_tokens", "api_call"
+    model: text("model"), // "gpt-4o", "gpt-4o-mini"
+    agent: text("agent"), // the product's agent slug
+    inputTokens: integer("input_tokens").notNull().default(0),
+    outputTokens: integer("output_tokens").notNull().default(0),
+    totalTokens: integer("total_tokens").notNull().default(0),
+    /**
+     * What the provider charged, in USD micros. Integer on purpose: float
+     * arithmetic accumulates sub-cent error over many records.
+     */
+    providerCostMicros: bigint("provider_cost_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    /** Snapshots of the rate and margin this charge was computed with. */
+    marginBp: integer("margin_bp").notNull().default(0),
+    usdRateMicros: bigint("usd_rate_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    /** Authoritative charge, in micros of `currency`. */
+    chargedMicros: bigint("charged_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    currency: text("currency").notNull().default("USD"),
+    /** Request correlation id for log tracing */
+    requestId: text("request_id"),
+    /**
+     * Owning execution (@intelligo-dev/executions). No FK: the executions
+     * table is owned by another package and this column is written by
+     * the settlement path, which may run before or after the execution
+     * row's terminal update.
+     */
+    executionId: text("execution_id"),
+    /** Conversation/chat id for grouping in usage dashboards */
+    conversationId: text("conversation_id"),
+    metadata: text("metadata"), // JSON string for additional data
+    recordedAt: timestamp("recorded_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("usage_records_workspace_id_idx").on(table.workspaceId),
+    index("usage_records_workspace_recorded_at_idx").on(
+      table.workspaceId,
+      table.recordedAt
+    ),
+    index("usage_records_workspace_type_idx").on(table.workspaceId, table.type),
+    index("usage_records_conversation_id_idx").on(table.conversationId),
+    index("usage_records_execution_id_idx").on(table.executionId),
+  ]
+);
+
+/**
+ * One row per workspace per billing period, incremented atomically, so a
+ * quota check is O(1) instead of a SUM over usage_records.
+ */
+export const monthlyUsage = pgTable(
+  "monthly_usage",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    periodStart: timestamp("period_start").notNull(),
+    periodEnd: timestamp("period_end").notNull(),
+    tokensUsed: integer("tokens_used").notNull().default(0),
+    /** The plan allowance spent this period, in micros of `currency`. */
+    allowanceUsedMicros: bigint("allowance_used_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    currency: text("currency").notNull().default("USD"),
+    requestCount: integer("request_count").notNull().default(0),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (table) => [
+    unique("monthly_usage_workspace_period_unique").on(
+      table.workspaceId,
+      table.periodStart
+    ),
+    index("monthly_usage_workspace_id_idx").on(table.workspaceId),
+  ]
+);
+
+/**
+ * One-time trial grant, one per workspace (unique constraint). Separate from
+ * purchased credits; used when the plan quota is exceeded or the credit
+ * balance is zero. Status: active → depleted, converted or expired.
+ */
+export const trialCredits = pgTable(
+  "trial_credits",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .unique()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    initialCredits: integer("initial_credits").notNull().default(100000),
+    creditsUsed: integer("credits_used").notNull().default(0),
+    creditsRemaining: integer("credits_remaining").notNull().default(100000),
+    /** The grant, in micros of `currency`. */
+    initialMicros: bigint("initial_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    usedMicros: bigint("used_micros", { mode: "number" }).notNull().default(0),
+    remainingMicros: bigint("remaining_micros", { mode: "number" })
+      .notNull()
+      .default(0),
+    currency: text("currency").notNull().default("USD"),
+    status: text("status").notNull().default("active"), // active|depleted|converted|expired
+    provisionedAt: timestamp("provisioned_at").notNull().defaultNow(),
+    trialEndDate: timestamp("trial_end_date"), // 14 days from provisioning
+    depletedAt: timestamp("depleted_at"),
+    convertedAt: timestamp("converted_at"),
+    createdByIp: text("created_by_ip"),
+    createdByEmail: text("created_by_email"),
+    /**
+     * Canonical form of createdByEmail for the per-email abuse check,
+     * stored so the count can use an index instead of a full-table scan.
+     */
+    normalizedEmail: text("normalized_email"),
+  },
+  (table) => [
+    index("trial_credits_expiry_idx").on(table.status, table.trialEndDate),
+    index("trial_credits_normalized_email_idx").on(table.normalizedEmail),
+  ]
+);
+
+/**
+ * One row per (workspace, endpoint, minute bucket). Each request upserts the
+ * row and atomically increments `count`, so N concurrent requests observe
+ * 1..N and exactly `limit` are admitted. Old buckets are deleted by the
+ * billing-maintenance job.
+ */
+export const rateLimitEntries = pgTable(
+  "rate_limit_entries",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    endpoint: text("endpoint").notNull().default("chat"),
+    requestedAt: timestamp("requested_at").notNull().defaultNow(),
+    /** Floored minute bucket for unique constraint enforcement */
+    minuteBucket: timestamp("minute_bucket").notNull(),
+    /** Requests observed in this bucket — incremented via upsert */
+    count: integer("count").notNull().default(1),
+  },
+  (table) => [
+    index("rate_limit_entries_window_idx").on(
+      table.workspaceId,
+      table.endpoint,
+      table.requestedAt
+    ),
+    unique("rate_limit_entries_unique_bucket_idx").on(
+      table.workspaceId,
+      table.endpoint,
+      table.minuteBucket
+    ),
+  ]
+);
+
+/**
+ * Sent quota and trial notifications. The unique constraint on
+ * (workspaceId, type, periodKey) keeps one notification from being sent
+ * twice in a billing period.
+ */
+export const notificationHistory = pgTable(
+  "notification_history",
+  {
+    id: text("id").primaryKey(),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    type: text("type").notNull(), // "quota_warning_80", "quota_warning_100", "trial_warning_20", "trial_depleted"
+    periodKey: text("period_key").notNull(), // "2026-02" for monthly, "trial" for one-time
+    sentAt: timestamp("sent_at").notNull().defaultNow(),
+    channel: text("channel").notNull().default("console"), // "console" | "email"
+    metadata: text("metadata"), // JSON string for additional context
+  },
+  (table) => [
+    unique("notification_history_dedup_unique").on(
+      table.workspaceId,
+      table.type,
+      table.periodKey
+    ),
+    index("notification_history_workspace_id_idx").on(table.workspaceId),
+  ]
+);
+
+/**
+ * Per-user, per-action usage counters, one row per user and workspace (not
+ * per period). Counters live in the `usage` JSONB map and increment
+ * atomically in SQL, so a quota check is O(1).
+ */
+export const userQuotas = pgTable(
+  "user_quotas",
+  {
+    id: text("id").primaryKey(),
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    workspaceId: text("workspace_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    plan: text("plan").notNull().default("free"), // free | standard | pro
+    /**
+     * Per-action counters keyed by the product's own action slugs
+     * (`usage["chat"] = 42`), so a product adds a counter without a
+     * migration.
+     */
+    usage: jsonb("usage").notNull().default({}),
+    totalCostUsd: real("total_cost_usd").notNull().default(0),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("user_quotas_user_id_idx").on(table.userId),
+    index("user_quotas_workspace_id_idx").on(table.workspaceId),
+    // Unique per (user, workspace), not per user: a user in a paid and a
+    // free workspace must not share one plan and one set of counters.
+    unique("user_quotas_user_workspace_unique").on(
+      table.userId,
+      table.workspaceId
+    ),
+  ]
+);
+
+export type UserQuota = typeof userQuotas.$inferSelect;
+export type InsertUserQuota = typeof userQuotas.$inferInsert;
+export type UsageRecord = typeof usageRecords.$inferSelect;
+export type InsertUsageRecord = typeof usageRecords.$inferInsert;
+export type MonthlyUsage = typeof monthlyUsage.$inferSelect;
+export type InsertMonthlyUsage = typeof monthlyUsage.$inferInsert;
+export type TrialCredit = typeof trialCredits.$inferSelect;
+export type InsertTrialCredit = typeof trialCredits.$inferInsert;
+export type RateLimitEntry = typeof rateLimitEntries.$inferSelect;
+export type InsertRateLimitEntry = typeof rateLimitEntries.$inferInsert;
+export type NotificationHistoryRecord = typeof notificationHistory.$inferSelect;
+export type InsertNotificationHistoryRecord =
+  typeof notificationHistory.$inferInsert;

package/src/db/validate.ts

@@ -0,0 +1,63 @@
+import { db } from "./client";
+import { sql } from "drizzle-orm";
+
+export interface DatabaseValidationResult {
+  isConnected: boolean;
+  tablesExist: boolean;
+  error?: string;
+}
+
+/** Checks that the database answers and the four auth tables exist. */
+export async function validateDatabaseConnection(): Promise<DatabaseValidationResult> {
+  try {
+    await db.execute(sql`SELECT 1`);
+
+    const result = await db.execute(sql`
+      SELECT COUNT(*) as table_count
+      FROM information_schema.tables
+      WHERE table_schema = 'public'
+      AND table_name IN ('users', 'sessions', 'accounts', 'verifications')
+    `);
+
+    const tableCount = Number(result.rows[0]?.table_count ?? 0);
+    const tablesExist = tableCount === 4;
+
+    return {
+      isConnected: true,
+      tablesExist,
+      error: tablesExist
+        ? undefined
+        : "Auth tables do not exist. Run 'intelligo migrate' to apply the framework's migration chain.",
+    };
+  } catch (error) {
+    return {
+      isConnected: false,
+      tablesExist: false,
+      error: error instanceof Error ? error.message : "Unknown database error",
+    };
+  }
+}
+
+/** Startup check: throws with setup instructions when validation fails. */
+export async function requireDatabaseConnection(): Promise<void> {
+  const result = await validateDatabaseConnection();
+
+  if (!result.isConnected) {
+    throw new Error(
+      `❌ Database connection failed: ${result.error}\n\n` +
+        `Make sure DATABASE_URL is configured in .env.local\n` +
+        `Example: DATABASE_URL=postgres://user:pass@host/db`
+    );
+  }
+
+  if (!result.tablesExist) {
+    throw new Error(
+      `❌ Database tables do not exist.\n\n` +
+        `Run the following commands to set up the database:\n` +
+        `  1. intelligo migrate   (applies the framework's migration chain)\n` +
+        `  2. drizzle-kit migrate (your own tables, if any)`
+    );
+  }
+
+  console.log("✓ Database connection validated");
+}

package/src/db/workspace-queries.ts

@@ -0,0 +1,64 @@
+/**
+ * Workspace scoping for tables with a `workspaceId` column. Every query on
+ * such a table filters by the workspace resolved from `requireWorkspace()`.
+ * Organization, member and invitation rows go through the Better-Auth API,
+ * which scopes them to the caller's session.
+ */
+
+import { eq, and, type SQL } from "drizzle-orm";
+import type { PgColumn } from "drizzle-orm/pg-core";
+
+/**
+ * Creates a workspace-scoped WHERE condition for any table with a workspaceId column.
+ * Use it in every custom Drizzle query to enforce workspace isolation.
+ *
+ * @param workspaceIdColumn - The workspaceId column from the table schema
+ * @param workspaceId - The active workspace ID from requireWorkspace()
+ * @returns SQL condition: workspaceId = ?
+ *
+ * @example
+ * ```typescript
+ * const { workspace } = await requireWorkspace();
+ * const conversations = await db
+ *   .select()
+ *   .from(conversationsTable)
+ *   .where(workspaceEq(conversationsTable.workspaceId, workspace.id));
+ * ```
+ */
+export function workspaceEq(
+  workspaceIdColumn: PgColumn,
+  workspaceId: string
+): SQL {
+  return eq(workspaceIdColumn, workspaceId);
+}
+
+/**
+ * Combines a workspace scope condition with additional WHERE conditions.
+ *
+ * @param workspaceIdColumn - The workspaceId column from the table schema
+ * @param workspaceId - The active workspace ID from requireWorkspace()
+ * @param additionalConditions - Extra WHERE conditions to AND together
+ * @returns Combined SQL condition: workspaceId = ? AND ...
+ *
+ * @example
+ * ```typescript
+ * const { workspace } = await requireWorkspace();
+ * const activeConversations = await db
+ *   .select()
+ *   .from(conversationsTable)
+ *   .where(
+ *     withWorkspaceFilter(
+ *       conversationsTable.workspaceId,
+ *       workspace.id,
+ *       eq(conversationsTable.status, "active")
+ *     )
+ *   );
+ * ```
+ */
+export function withWorkspaceFilter(
+  workspaceIdColumn: PgColumn,
+  workspaceId: string,
+  ...additionalConditions: SQL[]
+): SQL {
+  return and(eq(workspaceIdColumn, workspaceId), ...additionalConditions)!;
+}

package/src/documents/classifier.ts

@@ -0,0 +1,61 @@
+/**
+ * Document title classifier. Products register their title patterns here;
+ * the documents service uses them to derive agent labels and the "report"
+ * filter. Kept free of the db import so client code and tests can load it.
+ */
+
+import { createRegistry } from "../registry";
+
+export type DocumentPatternEntry = {
+  /** Stable product slug — same one used across product configs. */
+  productSlug: string;
+  /** Human-readable agent label rendered in the documents UI. */
+  agentLabel: string;
+  /** Case-insensitive substring patterns; a document matches when its
+   *  title contains ANY of these, whatever the case of either. */
+  patterns: string[];
+};
+
+/**
+ * Keyed by product slug rather than appended, so a composition root that
+ * runs twice (or two copies of it) replaces the entry instead of matching
+ * the same patterns twice. Insertion order decides first-match
+ * classification.
+ */
+const registry = createRegistry<DocumentPatternEntry>("core/document-patterns");
+
+export function registerDocumentPatterns(entry: DocumentPatternEntry): void {
+  registry.set(entry.productSlug, entry);
+}
+
+export function classifyDocumentTitle(title: string): {
+  productSlug: string | null;
+  agentLabel: string;
+} {
+  const lower = title.toLowerCase();
+  for (const entry of registry.values()) {
+    if (entry.patterns.some((p) => lower.includes(p.toLowerCase()))) {
+      return { productSlug: entry.productSlug, agentLabel: entry.agentLabel };
+    }
+  }
+  return { productSlug: null, agentLabel: "AI Assistant" };
+}
+
+/** Returns true when the document looks like it belongs to any registered product. */
+export function isProductDocument(
+  title: string,
+  productSlug?: string
+): boolean {
+  const { productSlug: matched } = classifyDocumentTitle(title);
+  if (!matched) return false;
+  if (productSlug) return matched === productSlug;
+  return true;
+}
+
+export function listRegisteredDocumentPatterns(): readonly DocumentPatternEntry[] {
+  return [...registry.values()];
+}
+
+export function clearDocumentPatternRegistry(): void {
+  registry.clear();
+}

package/src/documents/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Thrown by the documents service for every failure it recognizes. Shaping
+ * it into a transport envelope is the caller's job.
+ */
+
+/**
+ * - `not_found` — no document (or no version of it) exists at the
+ *   given id within the actor's workspace/user scope.
+ * - `forbidden` — a document with this id exists but is owned by a
+ *   different user within the same workspace.
+ * - `invalid_input` — a caller-supplied argument failed a basic
+ *   invariant (e.g. an unparsable or out-of-window delete timestamp).
+ * - `database_error` — the underlying insert/update did not return the
+ *   row it was expected to.
+ */
+export type DocumentServiceErrorCode =
+  "not_found" | "forbidden" | "invalid_input" | "database_error";
+
+export class DocumentServiceError extends Error {
+  readonly code: DocumentServiceErrorCode;
+  // The ES2020 target predates `Error.cause`; declared so `err.cause`
+  // type-checks for callers.
+  readonly cause?: unknown;
+
+  constructor(
+    code: DocumentServiceErrorCode,
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(message);
+    this.name = "DocumentServiceError";
+    this.code = code;
+    if (options?.cause !== undefined) {
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+    Object.setPrototypeOf(this, DocumentServiceError.prototype);
+  }
+}
+
+export function isDocumentServiceError(
+  error: unknown
+): error is DocumentServiceError {
+  return error instanceof DocumentServiceError;
+}

package/src/documents/index.ts

@@ -0,0 +1,24 @@
+export {
+  getUserDocuments,
+  getDocument,
+  getDocumentVersions,
+  saveDocument,
+  deleteDocumentVersions,
+} from "./service";
+
+export {
+  DocumentServiceError,
+  isDocumentServiceError,
+  type DocumentServiceErrorCode,
+} from "./errors";
+
+export type { DocumentActor, DocumentFilter, DocumentListItem } from "./types";
+
+export {
+  registerDocumentPatterns,
+  classifyDocumentTitle,
+  isProductDocument,
+  listRegisteredDocumentPatterns,
+  clearDocumentPatternRegistry,
+  type DocumentPatternEntry,
+} from "./classifier";