@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/libraries/weaviate/utils/TenantContextManager.ts

@@ -0,0 +1,94 @@
+import type { TenantContext } from "../types/MultiTenancy.js";
+
+/**
+ * Utility class for managing tenant context in multi-tenant operations
+ */
+export default class TenantContextManager {
+  private static currentContext: TenantContext | null = null;
+
+  /**
+   * Set the current tenant context
+   */
+  static setContext(tenant: string, activityStatus?: "HOT" | "COLD" | "FROZEN"): void {
+    TenantContextManager.currentContext = {
+      tenant,
+      activityStatus: activityStatus || "HOT",
+    };
+  }
+
+  /**
+   * Get the current tenant context
+   */
+  static getContext(): TenantContext | null {
+    return TenantContextManager.currentContext;
+  }
+
+  /**
+   * Clear the current tenant context
+   */
+  static clearContext(): void {
+    TenantContextManager.currentContext = null;
+  }
+
+  /**
+   * Check if a tenant context is set
+   */
+  static hasContext(): boolean {
+    return TenantContextManager.currentContext !== null;
+  }
+
+  /**
+   * Get the current tenant name
+   */
+  static getCurrentTenant(): string | null {
+    return TenantContextManager.currentContext?.tenant || null;
+  }
+
+  /**
+   * Execute a function with a specific tenant context
+   */
+  static async withContext<T>(
+    tenant: string,
+    activityStatus: "HOT" | "COLD" | "FROZEN" | undefined,
+    fn: () => Promise<T>,
+  ): Promise<T> {
+    const previousContext = TenantContextManager.currentContext;
+
+    try {
+      TenantContextManager.setContext(tenant, activityStatus);
+      return await fn();
+    } finally {
+      TenantContextManager.currentContext = previousContext;
+    }
+  }
+
+  /**
+   * Create a tenant context object
+   */
+  static createContext(tenant: string, activityStatus?: "HOT" | "COLD" | "FROZEN"): TenantContext {
+    return {
+      tenant,
+      activityStatus: activityStatus || "HOT",
+    };
+  }
+
+  /**
+   * Validate tenant name format
+   */
+  static validateTenantName(tenant: string): boolean {
+    // Weaviate tenant names must be lowercase and contain only alphanumeric characters and hyphens
+    return /^[a-z0-9-]+$/.test(tenant) && tenant.length > 0 && tenant.length <= 63;
+  }
+
+  /**
+   * Sanitize tenant name to meet Weaviate requirements
+   */
+  static sanitizeTenantName(tenant: string): string {
+    return tenant
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, "-")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "")
+      .substring(0, 63);
+  }
+}

package/lib/modules/accounts/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Accounts module — public barrel.
+ *
+ * Default account / role / permission CRUD over the module's own identity
+ * tables. Consumers wire it via `defineAccountsRoutes(app, { service, provider })`.
+ */
+
+export {
+  ACCOUNTS_PERMISSION_DEFINITIONS,
+  ACCOUNTS_PERMISSIONS,
+  type AccountsPermission,
+} from "./permissions.js";
+export { type AccountsRoutesDeps, buildAccountsApp, defineAccountsRoutes } from "./routes.js";
+export {
+  type Account,
+  accounts,
+  accountsRelations,
+  accountsSchema,
+  type NewAccount,
+  type NewPermission,
+  type NewRole,
+  type NewRolePermission,
+  type NewTenant,
+  type Permission,
+  permissions,
+  permissionsRelations,
+  type Role,
+  type RolePermission,
+  rolePermissions,
+  rolePermissionsRelations,
+  roles,
+  rolesRelations,
+  type Tenant,
+  tenants,
+  tenantsSchema,
+} from "./schema.js";
+export { AccountService } from "./services/AccountService.js";
+export {
+  type AccountIdParam,
+  accountIdParamSchema,
+  type CreateAccountInput,
+  createAccountSchema,
+  type ListAccountsQuery,
+  listAccountsQuerySchema,
+  type UpdateAccountInput,
+  updateAccountSchema,
+} from "./validation/schemas.js";

package/lib/modules/accounts/module.json

@@ -0,0 +1,15 @@
+{
+  "name": "accounts",
+  "description": "Identity + RBAC on the v4 substrate — owns the `accounts`/`roles`/`permissions`/`refresh_tokens` schema (relocated out of core), DrizzleEntityService, Hono routes, pluggable AuthProvider. Compose its `accountsSchema` fragment into `createApp({ schema })` and customize as needed.",
+  "version": "2.0.0-alpha.1",
+  "dependencies": [],
+  "npmDependencies": {},
+  "requiredEnvVars": [],
+  "optionalEnvVars": [],
+  "postInstall": [
+    "Add the schema to your composed schema: `createApp({ schema: { ...accountsSchema } })`",
+    "Wire the routes in src/index.ts, capturing the chained return so hc() types survive: `const app = defineAccountsRoutes(createApp({ schema }), { service, provider })`",
+    "Provide a service constructed against your composed schema: `new AccountService(app.db)`",
+    "Provide an AuthProvider (Firebase by default; Better-Auth/Clerk/WorkOS in v4.x)"
+  ]
+}

package/lib/modules/accounts/permissions.ts

@@ -0,0 +1,33 @@
+/**
+ * Permission slugs for the accounts module.
+ *
+ * v3 exported `Permission` entity instances; v4 exports plain string
+ * constants because authorization is enforced by `requirePermission(slug)`
+ * middleware at the route, not by `@HasPermission` decorators on a
+ * controller method. The Permission DB rows themselves are seeded by
+ * the consuming app (typically in a custom bootstrapper) — the module
+ * declares the *names* it expects to exist.
+ */
+
+import type { PermissionDefinition } from "@sixthsummit/ship-api";
+
+export const ACCOUNTS_PERMISSIONS = {
+  read: "accounts:read",
+  create: "accounts:create",
+  update: "accounts:update",
+  delete: "accounts:delete",
+} as const;
+
+export type AccountsPermission = (typeof ACCOUNTS_PERMISSIONS)[keyof typeof ACCOUNTS_PERMISSIONS];
+
+/**
+ * The list form is what a seed script feeds to the Permission table.
+ * Each entry pairs the slug with a human-readable label that surfaces
+ * in admin UIs when assigning permissions to roles.
+ */
+export const ACCOUNTS_PERMISSION_DEFINITIONS = [
+  { slug: ACCOUNTS_PERMISSIONS.read, label: "View Accounts" },
+  { slug: ACCOUNTS_PERMISSIONS.create, label: "Create Accounts" },
+  { slug: ACCOUNTS_PERMISSIONS.update, label: "Update Accounts" },
+  { slug: ACCOUNTS_PERMISSIONS.delete, label: "Delete Accounts" },
+] as const satisfies readonly PermissionDefinition[];

package/lib/modules/accounts/routes.ts

@@ -0,0 +1,200 @@
+import type {
+  AuthenticatedAccount,
+  AuthProvider,
+} from "@sixthsummit/ship-api/app/auth/AuthProvider";
+import type { AppEnv } from "@sixthsummit/ship-api/http/app/createApp";
+import { createModuleApp } from "@sixthsummit/ship-api/http/app/createApp";
+import { NotFoundError } from "@sixthsummit/ship-api/http/errors/NotFoundError";
+import { requireAuth } from "@sixthsummit/ship-api/http/middleware/requireAuth";
+import { requirePermission } from "@sixthsummit/ship-api/http/middleware/requirePermission";
+import { validate } from "@sixthsummit/ship-api/http/utils/validate";
+import type { Hono, Schema } from "hono";
+import type { BlankSchema } from "hono/types";
+
+import { ACCOUNTS_PERMISSIONS } from "./permissions.js";
+import type { AccountService } from "./services/AccountService.js";
+import {
+  accountIdParamSchema,
+  createAccountSchema,
+  listAccountsQuerySchema,
+  updateAccountSchema,
+} from "./validation/schemas.js";
+
+/**
+ * v4 routes — `defineAccountsRoutes(app, deps)`.
+ *
+ * Replaces v3's `Router`-based `routes.ts` + `initializeRoutes(em)`
+ * pattern. Differences:
+ *   - Returns the chained Hono app so consumer composition keeps RPC
+ *     types end-to-end (`hc<typeof app>()` sees every account route).
+ *   - Authorization runs at the route via `requirePermission(slug)`
+ *     middleware, not the v3 `@HasPermission` decorator on a controller
+ *     method.
+ *   - Validation runs via `validate('json' | 'query' | 'param', schema)`
+ *     wrapping `zValidator`; handlers read parsed input via
+ *     `c.req.valid('json' | ...)`.
+ *   - 404s throw `NotFoundError` so `app.onError` (registered via
+ *     `registerErrorHandlers`) produces the consistent JSON error
+ *     shape — handlers don't shape error responses themselves.
+ *   - The service is injected (not constructed inside the route file
+ *     from an EntityManager) so consumers swap it for tests / custom
+ *     subclasses.
+ */
+
+export interface AccountsRoutesDeps<TAccount extends AuthenticatedAccount = AuthenticatedAccount> {
+  service: AccountService;
+  provider: AuthProvider<TAccount>;
+}
+
+/**
+ * ⚠️ FOOT-GUN: do NOT thread one shared `app` through several modules'
+ * `defineXxxRoutes` calls. Chaining every module's routes onto a single app
+ * accumulates one giant Hono route-type and detonates `tsc` (TS2589 /
+ * "instantiation excessively deep") once you have enough modules. Prefer
+ * {@link buildAccountsApp} and mount it on the root with
+ * `root.route("/", buildAccountsApp(deps))` — each module then gets its own
+ * bounded sub-app. This raw `(app, deps)` form is kept for advanced
+ * composition (deliberately registering accounts routes onto an existing
+ * already-typed app).
+ */
+// Generic over Hono's schema param `S`: `.get()`/`.post()` resolve on the
+// parameter's declared type, so taking `Hono<AppEnv>` (or `<T extends
+// Hono<AppEnv>>`) widens an already-chained app and erases every previously
+// registered route from the RPC type. `Hono<AppEnv, S>` accumulates instead —
+// the return type is `Hono<AppEnv, S & <these routes>>`.
+export function defineAccountsRoutes<
+  TAccount extends AuthenticatedAccount = AuthenticatedAccount,
+  S extends Schema = BlankSchema,
+>(app: Hono<AppEnv, S>, deps: AccountsRoutesDeps<TAccount>) {
+  const auth = requireAuth({ provider: deps.provider });
+
+  return app
+    .post(
+      "/accounts",
+      auth,
+      requirePermission(ACCOUNTS_PERMISSIONS.create),
+      validate("json", createAccountSchema),
+      async (c) => {
+        const body = c.req.valid("json");
+        const account = await deps.service.create(body);
+        return c.json(account, 201);
+      },
+    )
+    .get(
+      "/accounts",
+      auth,
+      requirePermission(ACCOUNTS_PERMISSIONS.read),
+      validate("query", listAccountsQuerySchema),
+      async (c) => {
+        const q = c.req.valid("query");
+        const rows = await deps.service.getAll({
+          search: q.search,
+          where: filterFromQuery(q),
+        });
+        return c.json(rows, 200);
+      },
+    )
+    .get(
+      "/accounts/list",
+      auth,
+      requirePermission(ACCOUNTS_PERMISSIONS.read),
+      validate("query", listAccountsQuerySchema),
+      async (c) => {
+        const q = c.req.valid("query");
+        const offset = (q.page - 1) * q.perPage;
+        const result = await deps.service.list({
+          search: q.search,
+          where: filterFromQuery(q),
+          limit: q.perPage,
+          offset,
+        });
+        return c.json({ ...result, page: q.page, perPage: q.perPage }, 200);
+      },
+    )
+    .get(
+      "/accounts/count",
+      auth,
+      requirePermission(ACCOUNTS_PERMISSIONS.read),
+      validate("query", listAccountsQuerySchema),
+      async (c) => {
+        const q = c.req.valid("query");
+        const count = await deps.service.count({
+          search: q.search,
+          where: filterFromQuery(q),
+        });
+        return c.json({ count }, 200);
+      },
+    )
+    .get(
+      "/accounts/:id",
+      auth,
+      requirePermission(ACCOUNTS_PERMISSIONS.read),
+      validate("param", accountIdParamSchema),
+      async (c) => {
+        const { id } = c.req.valid("param");
+        const account = await deps.service.get(id);
+        if (account === null) throw new NotFoundError("Account not found");
+        return c.json(account, 200);
+      },
+    )
+    .put(
+      "/accounts/:id",
+      auth,
+      requirePermission(ACCOUNTS_PERMISSIONS.update),
+      validate("param", accountIdParamSchema),
+      validate("json", updateAccountSchema),
+      async (c) => {
+        const { id } = c.req.valid("param");
+        const body = c.req.valid("json");
+        const account = await deps.service.update(id, body);
+        if (account === null) throw new NotFoundError("Account not found");
+        return c.json(account, 200);
+      },
+    )
+    .delete(
+      "/accounts/:id",
+      auth,
+      requirePermission(ACCOUNTS_PERMISSIONS.delete),
+      validate("param", accountIdParamSchema),
+      async (c) => {
+        const { id } = c.req.valid("param");
+        const existing = await deps.service.get(id);
+        if (existing === null) throw new NotFoundError("Account not found");
+        await deps.service.delete(id);
+        return c.body(null, 204);
+      },
+    );
+}
+
+/**
+ * Build the accounts module as its own sub-app, ready to mount on the root:
+ *
+ * ```ts
+ * const app = createApp({ cors }).route("/", buildAccountsApp({ service, provider }));
+ * ```
+ *
+ * This is the canonical wiring — each module is an independent, bounded
+ * sub-app, so the composed `hc()` client type scales without `tsc` overflow.
+ * The module owns its registry tag (`createModuleApp("accounts")`), so its
+ * routes show up under the `accounts` module in `/dev/routes` and `list_routes`.
+ */
+export function buildAccountsApp<TAccount extends AuthenticatedAccount = AuthenticatedAccount>(
+  deps: AccountsRoutesDeps<TAccount>,
+) {
+  return defineAccountsRoutes(createModuleApp("accounts"), deps);
+}
+
+/**
+ * Translates the strict-typed query options into the
+ * `DrizzleEntityService.QueryOptions['where']` shape — booleans coerced
+ * from "true" / "false", optional fields stripped when absent.
+ */
+function filterFromQuery(q: {
+  isActive?: "true" | "false";
+  roleId?: string;
+}): Record<string, unknown> | undefined {
+  const where: Record<string, unknown> = {};
+  if (q.isActive !== undefined) where.isActive = q.isActive === "true";
+  if (q.roleId !== undefined) where.roleId = q.roleId;
+  return Object.keys(where).length > 0 ? where : undefined;
+}

package/lib/modules/accounts/schema.ts

@@ -0,0 +1,219 @@
+import { baseFields } from "@sixthsummit/ship-api/app/db/baseFields";
+import { relations } from "drizzle-orm";
+import {
+  boolean,
+  index,
+  pgTable,
+  timestamp,
+  uniqueIndex,
+  uuid,
+  varchar,
+} from "drizzle-orm/pg-core";
+
+/**
+ * Identity + RBAC schema for the accounts module.
+ *
+ * Relocated out of framework core (`@sixthsummit/ship-api/app/schema/*`) so the
+ * framework stays incrementally adoptable and each product owns / tailors its
+ * identity model (multi-tenant or not). Core ships the primitives — `baseFields`,
+ * the `AuthProvider` interface, `DrizzleEntityService`; this module owns the
+ * concrete tables.
+ *
+ * Spread `accountsSchema` into `createApp({ schema })` (and the test-DB harness)
+ * the way the old core `defaultSchema` was.
+ */
+
+/**
+ * `tenants` — opt-in multi-tenancy root table (A2-1).
+ *
+ * Tenancy is a per-product choice. This table + the `tenantsSchema` fragment
+ * ship with the accounts module but are NOT part of the default `accountsSchema`
+ * — a single-tenant product never composes them and never sees a `tenants`
+ * table. A multi-tenant product:
+ *   1. composes `tenantsSchema` into `createApp({ schema })`,
+ *   2. applies `...tenantScoped(tenants)` to the domain tables it wants scoped
+ *      (and, for the one-tenant-per-account default, to `accounts` — see the
+ *      commented field below),
+ *   3. wires `resolveTenant()` after `requireAuth`.
+ *
+ * Domain tables FK `tenants`, not `accounts`, so a future move to a membership
+ * model (Model A → B) is an identity-tables-only migration. See
+ * `docs/v4/concepts/tenancy.md`.
+ */
+export const tenants = pgTable("tenants", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  slug: varchar("slug", { length: 100 }).notNull().unique(),
+  name: varchar("name", { length: 200 }).notNull(),
+  ...baseFields,
+});
+
+export type Tenant = typeof tenants.$inferSelect;
+export type NewTenant = typeof tenants.$inferInsert;
+
+/**
+ * Opt-in tenancy schema fragment — compose alongside `accountsSchema` when a
+ * product enables multi-tenancy:
+ * `createApp({ schema: { ...accountsSchema, ...tenantsSchema, ...domainTables } })`.
+ * Kept separate from `accountsSchema` so single-tenant products never get a
+ * `tenants` table.
+ */
+export const tenantsSchema = {
+  tenants,
+} as const;
+
+export const roles = pgTable("roles", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  slug: varchar("slug", { length: 100 }).notNull().unique(),
+  name: varchar("name", { length: 100 }).notNull(),
+  description: varchar("description", { length: 500 }),
+  ...baseFields,
+});
+
+export const permissions = pgTable("permissions", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  slug: varchar("slug", { length: 200 }).notNull().unique(),
+  name: varchar("name", { length: 200 }).notNull(),
+  ...baseFields,
+});
+
+export const rolePermissions = pgTable("role_permissions", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  roleId: uuid("role_id")
+    .notNull()
+    .references(() => roles.id, { onDelete: "cascade" }),
+  permissionId: uuid("permission_id")
+    .notNull()
+    .references(() => permissions.id, { onDelete: "cascade" }),
+  ...baseFields,
+});
+
+export const accounts = pgTable(
+  "accounts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+
+    /**
+     * Stable subject identifier from the auth provider (Firebase UID by default;
+     * `sub` claim under any other `AuthProvider` adapter).
+     */
+    firebaseUid: varchar("firebase_uid", { length: 128 }),
+
+    email: varchar("email", { length: 320 }).notNull(),
+    emailVerified: boolean("email_verified").notNull().default(false),
+
+    displayName: varchar("display_name", { length: 200 }),
+
+    /** Soft-disable without deleting (distinct from `deletedAt`). */
+    isActive: boolean("is_active").notNull().default(true),
+
+    /** Optional FK to a single primary role. Multi-role assignments are
+     *  modeled in a join table by consumers who need them. */
+    roleId: uuid("role_id").references(() => roles.id, { onDelete: "set null" }),
+
+    // ─── Multi-tenancy (opt-in, A2-1) ────────────────────────────────
+    // Uncomment for the one-tenant-per-account model: adds a non-null
+    // `tenant_id` uuid FK → tenants.id. Then compose `tenantsSchema` into your
+    // app schema and wire `resolveTenant()` after `requireAuth`. Import the
+    // mixin from the barrel: `import { tenantScoped } from "@sixthsummit/ship-api"`.
+    // ...tenantScoped(tenants),
+
+    ...baseFields,
+  },
+  (table) => [
+    uniqueIndex("accounts_email_unique").on(table.email),
+    uniqueIndex("accounts_firebase_uid_unique").on(table.firebaseUid),
+  ],
+);
+
+export const rolesRelations = relations(roles, ({ many }) => ({
+  rolePermissions: many(rolePermissions),
+}));
+
+export const permissionsRelations = relations(permissions, ({ many }) => ({
+  rolePermissions: many(rolePermissions),
+}));
+
+export const rolePermissionsRelations = relations(rolePermissions, ({ one }) => ({
+  role: one(roles, {
+    fields: [rolePermissions.roleId],
+    references: [roles.id],
+  }),
+  permission: one(permissions, {
+    fields: [rolePermissions.permissionId],
+    references: [permissions.id],
+  }),
+}));
+
+export const accountsRelations = relations(accounts, ({ one }) => ({
+  role: one(roles, {
+    fields: [accounts.roleId],
+    references: [roles.id],
+  }),
+}));
+
+export type Account = typeof accounts.$inferSelect;
+export type NewAccount = typeof accounts.$inferInsert;
+export type Role = typeof roles.$inferSelect;
+export type NewRole = typeof roles.$inferInsert;
+export type Permission = typeof permissions.$inferSelect;
+export type NewPermission = typeof permissions.$inferInsert;
+export type RolePermission = typeof rolePermissions.$inferSelect;
+export type NewRolePermission = typeof rolePermissions.$inferInsert;
+
+/**
+ * `refresh_tokens` — server-side store for the JWT-cookie auth refresh-token
+ * rotation flow. `tokenHash` is a SHA-256 of the token (never the raw value);
+ * `revokedAt` supports immediate server-side revocation; `replacedById` tracks
+ * rotation history so refresh-token reuse (a theft signal) can revoke the whole
+ * chain. Consumed by the framework's generic `DrizzleRefreshTokenStore`, which
+ * takes this table via its constructor.
+ */
+export const refreshTokens = pgTable(
+  "refresh_tokens",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id")
+      .notNull()
+      .references(() => accounts.id, { onDelete: "cascade" }),
+    tokenHash: varchar("token_hash", { length: 128 }).notNull().unique(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    revokedAt: timestamp("revoked_at", { withTimezone: true }),
+    replacedById: uuid("replaced_by_id"),
+    /** User-agent / IP on issue, for audit + risk signals. */
+    userAgent: varchar("user_agent", { length: 500 }),
+    issuedFromIp: varchar("issued_from_ip", { length: 64 }),
+    ...baseFields,
+  },
+  (table) => [
+    index("refresh_tokens_account_id_idx").on(table.accountId),
+    index("refresh_tokens_expires_at_idx").on(table.expiresAt),
+  ],
+);
+
+export const refreshTokensRelations = relations(refreshTokens, ({ one }) => ({
+  account: one(accounts, {
+    fields: [refreshTokens.accountId],
+    references: [accounts.id],
+  }),
+}));
+
+export type RefreshToken = typeof refreshTokens.$inferSelect;
+export type NewRefreshToken = typeof refreshTokens.$inferInsert;
+
+/**
+ * Composable schema fragment — spread into `createApp({ schema })` and the
+ * integration-test DB harness. Replaces this module's slice of the old core
+ * `defaultSchema`.
+ */
+export const accountsSchema = {
+  accounts,
+  accountsRelations,
+  roles,
+  rolesRelations,
+  permissions,
+  permissionsRelations,
+  rolePermissions,
+  rolePermissionsRelations,
+  refreshTokens,
+  refreshTokensRelations,
+} as const;

package/lib/modules/accounts/services/AccountService.ts

@@ -0,0 +1,44 @@
+import { DrizzleEntityService } from "@sixthsummit/ship-api/app/services/DrizzleEntityService";
+import { accounts } from "../schema.js";
+
+/**
+ * v4 `AccountService` — thin extension of `DrizzleEntityService` against
+ * the framework's default `accounts` table.
+ *
+ * Replaces v3's `EntityService<Account>` subclass. Same surface
+ * (`get`/`getAll`/`list`/`count`/`create`/`update`/`delete`) inherited
+ * from the base; only the entity-specific overrides live here:
+ *
+ *   - `getTable()` returns the framework's default `accounts` pgTable
+ *   - `getDefaultSearchFields()` lists the columns the free-text
+ *     `?search=` filter scans (email + displayName, the human-readable
+ *     identifiers operators reach for in admin UIs)
+ *   - `getDefaultRelations()` declares `role` so `?relations=role`
+ *     loads a populated role
+ *
+ * Soft-delete + audit-column auto-stamping (createdAt / createdBy on
+ * insert; updatedAt / updatedBy on update) are inherited from the
+ * base — no per-service wiring required.
+ *
+ * Schema customization: consumers who extend the `accounts` table via
+ * `createApp({ schema })` should subclass this service (or replace it
+ * entirely) so `getDefaultSearchFields()` reflects any new searchable
+ * columns. The `TSchema` generic carries the full composed schema so
+ * Drizzle relational queries stay typed end-to-end.
+ */
+export class AccountService extends DrizzleEntityService<
+  typeof accounts,
+  { accounts: typeof accounts }
+> {
+  protected getTable() {
+    return accounts;
+  }
+
+  protected override getDefaultSearchFields(): readonly string[] {
+    return ["email", "displayName"];
+  }
+
+  protected override getDefaultRelations(): readonly string[] {
+    return ["role"];
+  }
+}