@terreno/api 0.1.0 → 0.2.0

package/dist/terrenoApp.test.js

@@ -0,0 +1,264 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var bun_test_1 = require("bun:test");
+var supertest_1 = __importDefault(require("supertest"));
+var api_1 = require("./api");
+var permissions_1 = require("./permissions");
+var terrenoApp_1 = require("./terrenoApp");
+var tests_1 = require("./tests");
+(0, bun_test_1.describe)("TerrenoApp", function () {
+    var originalEnv = process.env;
+    (0, bun_test_1.beforeEach)(function () {
+        process.env = __assign(__assign({}, originalEnv), { REFRESH_TOKEN_SECRET: "test-refresh-secret", SESSION_SECRET: "test-session-secret", TOKEN_EXPIRES_IN: "1h", TOKEN_ISSUER: "test-issuer", TOKEN_SECRET: "test-secret" });
+    });
+    (0, bun_test_1.afterEach)(function () {
+        process.env = originalEnv;
+    });
+    (0, bun_test_1.describe)("build", function () {
+        (0, bun_test_1.it)("returns an express application without listening", function () {
+            var app = new terrenoApp_1.TerrenoApp({
+                skipListen: true,
+                userModel: tests_1.UserModel,
+            }).build();
+            (0, bun_test_1.expect)(app).toBeDefined();
+        });
+        (0, bun_test_1.it)("creates server with custom corsOrigin", function () {
+            var app = new terrenoApp_1.TerrenoApp({
+                corsOrigin: "https://example.com",
+                skipListen: true,
+                userModel: tests_1.UserModel,
+            }).build();
+            (0, bun_test_1.expect)(app).toBeDefined();
+        });
+    });
+    (0, bun_test_1.describe)("start", function () {
+        (0, bun_test_1.it)("returns an express application with skipListen", function () {
+            var app = new terrenoApp_1.TerrenoApp({
+                skipListen: true,
+                userModel: tests_1.UserModel,
+            }).start();
+            (0, bun_test_1.expect)(app).toBeDefined();
+        });
+    });
+    (0, bun_test_1.describe)("register with modelRouter", function () {
+        var admin;
+        (0, bun_test_1.beforeEach)(function () { return __awaiter(void 0, void 0, void 0, function () {
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0: return [4 /*yield*/, (0, tests_1.setupDb)()];
+                    case 1:
+                        _a = __read.apply(void 0, [_b.sent(), 1]), admin = _a[0];
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("mounts model router at the specified path", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var foodRegistration, app, agent, res;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        foodRegistration = (0, api_1.modelRouter)("/food", tests_1.FoodModel, {
+                            allowAnonymous: true,
+                            permissions: {
+                                create: [permissions_1.Permissions.IsAny],
+                                delete: [permissions_1.Permissions.IsAny],
+                                list: [permissions_1.Permissions.IsAny],
+                                read: [permissions_1.Permissions.IsAny],
+                                update: [permissions_1.Permissions.IsAny],
+                            },
+                            sort: "-created",
+                        });
+                        (0, bun_test_1.expect)(foodRegistration.__type).toBe("modelRouter");
+                        (0, bun_test_1.expect)(foodRegistration.path).toBe("/food");
+                        app = new terrenoApp_1.TerrenoApp({
+                            skipListen: true,
+                            userModel: tests_1.UserModel,
+                        })
+                            .register(foodRegistration)
+                            .build();
+                        return [4 /*yield*/, tests_1.FoodModel.create({
+                                calories: 100,
+                                name: "Apple",
+                                ownerId: admin._id,
+                                source: { name: "Nature" },
+                            })];
+                    case 1:
+                        _a.sent();
+                        return [4 /*yield*/, (0, tests_1.authAsUser)(app, "admin")];
+                    case 2:
+                        agent = _a.sent();
+                        return [4 /*yield*/, agent.get("/food").expect(200)];
+                    case 3:
+                        res = _a.sent();
+                        (0, bun_test_1.expect)(res.body.data).toHaveLength(1);
+                        (0, bun_test_1.expect)(res.body.data[0].name).toBe("Apple");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("supports chaining multiple registrations", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var foodRegistration, app;
+            return __generator(this, function (_a) {
+                foodRegistration = (0, api_1.modelRouter)("/food", tests_1.FoodModel, {
+                    allowAnonymous: true,
+                    permissions: {
+                        create: [permissions_1.Permissions.IsAny],
+                        delete: [permissions_1.Permissions.IsAny],
+                        list: [permissions_1.Permissions.IsAny],
+                        read: [permissions_1.Permissions.IsAny],
+                        update: [permissions_1.Permissions.IsAny],
+                    },
+                });
+                app = new terrenoApp_1.TerrenoApp({
+                    skipListen: true,
+                    userModel: tests_1.UserModel,
+                })
+                    .register(foodRegistration)
+                    .build();
+                (0, bun_test_1.expect)(app).toBeDefined();
+                return [2 /*return*/];
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("register with plugin", function () {
+        (0, bun_test_1.it)("calls plugin.register with the express app", function () {
+            var registerFn = (0, bun_test_1.mock)(function () { });
+            var plugin = {
+                register: registerFn,
+            };
+            var app = new terrenoApp_1.TerrenoApp({
+                skipListen: true,
+                userModel: tests_1.UserModel,
+            })
+                .register(plugin)
+                .build();
+            (0, bun_test_1.expect)(registerFn).toHaveBeenCalledTimes(1);
+            // Verify the plugin received the express app
+            var calledWith = registerFn.mock.calls[0][0];
+            (0, bun_test_1.expect)(calledWith).toBe(app);
+        });
+    });
+    (0, bun_test_1.describe)("addMiddleware", function () {
+        (0, bun_test_1.it)("runs request handler middleware", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var middlewareCalled, middleware, app;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        middlewareCalled = false;
+                        middleware = function (_req, _res, next) {
+                            middlewareCalled = true;
+                            next();
+                        };
+                        app = new terrenoApp_1.TerrenoApp({
+                            skipListen: true,
+                            userModel: tests_1.UserModel,
+                        })
+                            .addMiddleware(middleware)
+                            .build();
+                        return [4 /*yield*/, (0, supertest_1.default)(app).get("/nonexistent").expect(404)];
+                    case 1:
+                        _a.sent();
+                        (0, bun_test_1.expect)(middlewareCalled).toBe(true);
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+    (0, bun_test_1.describe)("modelRouter overload", function () {
+        (0, bun_test_1.it)("returns ModelRouterRegistration when path is provided", function () {
+            var result = (0, api_1.modelRouter)("/food", tests_1.FoodModel, {
+                permissions: {
+                    create: [permissions_1.Permissions.IsAny],
+                    delete: [permissions_1.Permissions.IsAny],
+                    list: [permissions_1.Permissions.IsAny],
+                    read: [permissions_1.Permissions.IsAny],
+                    update: [permissions_1.Permissions.IsAny],
+                },
+            });
+            (0, bun_test_1.expect)(result.__type).toBe("modelRouter");
+            (0, bun_test_1.expect)(result.path).toBe("/food");
+            (0, bun_test_1.expect)(result.router).toBeDefined();
+        });
+        (0, bun_test_1.it)("returns express.Router when no path is provided", function () {
+            var result = (0, api_1.modelRouter)(tests_1.FoodModel, {
+                permissions: {
+                    create: [permissions_1.Permissions.IsAny],
+                    delete: [permissions_1.Permissions.IsAny],
+                    list: [permissions_1.Permissions.IsAny],
+                    read: [permissions_1.Permissions.IsAny],
+                    update: [permissions_1.Permissions.IsAny],
+                },
+            });
+            // Should be a regular router (function), not a ModelRouterRegistration
+            (0, bun_test_1.expect)(typeof result).toBe("function");
+            (0, bun_test_1.expect)(result.__type).toBeUndefined();
+        });
+    });
+});

package/dist/terrenoPlugin.d.ts

@@ -1,4 +1,38 @@
 import type express from "express";
+/**
+ * Interface for plugins that can be registered with TerrenoApp.
+ *
+ * Implement this interface to create reusable plugins that encapsulate
+ * routes, middleware, or other Express application setup. Plugins are
+ * registered via `TerrenoApp.register()` and are mounted after core
+ * authentication and OpenAPI middleware.
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin implements TerrenoPlugin {
+ *   register(app: express.Application): void {
+ *     app.get("/my-route", (req, res) => {
+ *       res.json({ status: "ok" });
+ *     });
+ *   }
+ * }
+ *
+ * const app = new TerrenoApp({ userModel: User })
+ *   .register(new MyPlugin())
+ *   .start();
+ * ```
+ *
+ * @see TerrenoApp for the application builder that consumes plugins
+ * @see HealthApp for a built-in plugin example
+ */
 export interface TerrenoPlugin {
+    /**
+     * Register routes and middleware with the Express application.
+     *
+     * Called during `TerrenoApp.build()` after core middleware has been
+     * configured but before error handling middleware is added.
+     *
+     * @param app - The Express application instance to register with
+     */
     register(app: express.Application): void;
 }

package/package.json

@@ -5,10 +5,11 @@
   },
   "dependencies": {
     "@sentry/bun": "^10.25.0",
+    "better-auth": "^1.2.8",
     "@sentry/profiling-node": "^10.25.0",
     "@types/qs": "^6.14.0",
     "@wesleytodd/openapi": "^1.1.0",
-    "ajv": "^8.17.1",
+    "ajv": "8.18.0",
     "ajv-formats": "^3.0.1",
     "axios": "^1.13.2",
     "cors": "^2.8.5",
@@ -17,7 +18,7 @@
     "express": "^4.21.2",
     "generaterr": "^1.5.0",
     "jsonwebtoken": "^9.0.2",
-    "lodash": "^4.17.21",
+    "lodash": "^4.17.23",
     "luxon": "^3.7.2",
     "mongoose": "8.18.1",
     "mongoose-to-swagger": "^1.4.0",
@@ -43,6 +44,7 @@
     "@types/express": "^4.17.21",
     "@types/jsonwebtoken": "^9.0.9",
     "@types/lodash": "^4.17.15",
+    "@types/mongodb": "^4.0.7",
     "@types/node": "^22.13.5",
     "@types/on-finished": "^2.3.4",
     "@types/passport": "^1.0.17",
@@ -52,6 +54,7 @@
     "@types/passport-local": "^1.0.38",
     "@types/sinon": "^17.0.4",
     "@types/supertest": "^6.0.2",
+    "mongodb-memory-server": "^11.0.1",
     "sinon": "^19.0.2",
     "supertest": "^7.0.0",
     "typedoc": "~0.27.9",
@@ -90,5 +93,5 @@
     "updateSnapshot": "bun test --update-snapshots"
   },
   "types": "dist/index.d.ts",
-  "version": "0.1.0"
+  "version": "0.2.0"
 }

package/src/api.ts

@@ -400,13 +400,71 @@ function getQueryValidationMiddleware<T>(
   return validateQueryParams(querySchema, validationOptions);
 }
 
+/**
+ * Registration object returned by modelRouter when called with a path.
+ *
+ * Used with `TerrenoApp.register()` to mount model routers at specific paths.
+ * Contains the Express router and the path it should be mounted at.
+ *
+ * @see modelRouter for creating registrations
+ * @see TerrenoApp for registering routers
+ */
+export interface ModelRouterRegistration {
+  /** Internal type discriminator for registration detection */
+  __type: "modelRouter";
+  /** The path where the router should be mounted (e.g., "/todos") */
+  path: string;
+  /** The Express router containing CRUD endpoints */
+  router: express.Router;
+}
+
 /**
  * Create a set of CRUD routes given a Mongoose model and configuration options.
  *
- * @param model A Mongoose Model
- * @param options Options for configuring the REST API, such as permissions, transformers, and hooks.
+ * When called with a path as the first argument, returns a `ModelRouterRegistration` that can be
+ * passed to `TerrenoApp.register()`.
+ *
+ * @example
+ * // Traditional usage (returns express.Router):
+ * router.use("/todos", modelRouter(Todo, options));
+ *
+ * // Registration usage (returns ModelRouterRegistration):
+ * const todoRouter = modelRouter("/todos", Todo, options);
+ * app.register(todoRouter);
  */
-export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router {
+export function modelRouter<T>(
+  path: string,
+  model: Model<T>,
+  options: ModelRouterOptions<T>
+): ModelRouterRegistration;
+export function modelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router;
+export function modelRouter<T>(
+  pathOrModel: string | Model<T>,
+  modelOrOptions: Model<T> | ModelRouterOptions<T>,
+  maybeOptions?: ModelRouterOptions<T>
+): express.Router | ModelRouterRegistration {
+  let model: Model<T>;
+  let options: ModelRouterOptions<T>;
+  let path: string | undefined;
+
+  if (typeof pathOrModel === "string") {
+    path = pathOrModel;
+    model = modelOrOptions as Model<T>;
+    options = maybeOptions as ModelRouterOptions<T>;
+  } else {
+    model = pathOrModel;
+    options = modelOrOptions as ModelRouterOptions<T>;
+  }
+
+  const router = _buildModelRouter(model, options);
+
+  if (path !== undefined) {
+    return {__type: "modelRouter", path, router};
+  }
+  return router;
+}
+
+function _buildModelRouter<T>(model: Model<T>, options: ModelRouterOptions<T>): express.Router {
   const router = express.Router();
 
   // Do before the other router options so endpoints take priority.

package/src/betterAuth.test.ts

@@ -0,0 +1,160 @@
+import {describe, expect, it} from "bun:test";
+
+import type {AuthProvider, BetterAuthConfig, BetterAuthOAuthProvider} from "./betterAuth";
+
+describe("Better Auth types", () => {
+  it("defines BetterAuthOAuthProvider interface correctly", () => {
+    const provider: BetterAuthOAuthProvider = {
+      clientId: "test-client-id",
+      clientSecret: "test-client-secret",
+    };
+
+    expect(provider.clientId).toBe("test-client-id");
+    expect(provider.clientSecret).toBe("test-client-secret");
+  });
+
+  it("defines BetterAuthConfig interface correctly", () => {
+    const config: BetterAuthConfig = {
+      basePath: "/api/auth",
+      baseURL: "http://localhost:3000",
+      enabled: true,
+      githubOAuth: {
+        clientId: "github-client-id",
+        clientSecret: "github-client-secret",
+      },
+      googleOAuth: {
+        clientId: "google-client-id",
+        clientSecret: "google-client-secret",
+      },
+      secret: "test-secret",
+      trustedOrigins: ["terreno://", "exp://"],
+    };
+
+    expect(config.enabled).toBe(true);
+    expect(config.googleOAuth?.clientId).toBe("google-client-id");
+    expect(config.githubOAuth?.clientId).toBe("github-client-id");
+    expect(config.trustedOrigins).toContain("terreno://");
+    expect(config.basePath).toBe("/api/auth");
+  });
+
+  it("allows minimal BetterAuthConfig", () => {
+    const minimalConfig: BetterAuthConfig = {
+      enabled: false,
+    };
+
+    expect(minimalConfig.enabled).toBe(false);
+    expect(minimalConfig.googleOAuth).toBeUndefined();
+    expect(minimalConfig.basePath).toBeUndefined();
+  });
+
+  it("defines AuthProvider type correctly", () => {
+    const jwtProvider: AuthProvider = "jwt";
+    const betterAuthProvider: AuthProvider = "better-auth";
+
+    expect(jwtProvider).toBe("jwt");
+    expect(betterAuthProvider).toBe("better-auth");
+  });
+});
+
+describe("Better Auth setup", () => {
+  it("syncBetterAuthUser creates a new user when not found", async () => {
+    // This test would require mocking MongoDB which is complex
+    // For now we test the interface structure
+    const betterAuthUser = {
+      createdAt: new Date(),
+      email: "test@example.com",
+      emailVerified: true,
+      id: "ba-user-123",
+      image: null,
+      name: "Test User",
+      updatedAt: new Date(),
+    };
+
+    expect(betterAuthUser.id).toBe("ba-user-123");
+    expect(betterAuthUser.email).toBe("test@example.com");
+    expect(betterAuthUser.name).toBe("Test User");
+  });
+
+  it("BetterAuthSession has correct structure", () => {
+    const session = {
+      createdAt: new Date(),
+      expiresAt: new Date(Date.now() + 3600000),
+      id: "session-123",
+      ipAddress: "127.0.0.1",
+      updatedAt: new Date(),
+      userAgent: "Mozilla/5.0",
+      userId: "user-456",
+    };
+
+    expect(session.id).toBe("session-123");
+    expect(session.userId).toBe("user-456");
+    expect(session.expiresAt.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  it("BetterAuthSessionData combines session and user", () => {
+    const sessionData = {
+      session: {
+        createdAt: new Date(),
+        expiresAt: new Date(),
+        id: "session-123",
+        ipAddress: null,
+        updatedAt: new Date(),
+        userAgent: null,
+        userId: "user-456",
+      },
+      user: {
+        createdAt: new Date(),
+        email: "test@example.com",
+        emailVerified: false,
+        id: "user-456",
+        image: null,
+        name: "Test",
+        updatedAt: new Date(),
+      },
+    };
+
+    expect(sessionData.session.userId).toBe(sessionData.user.id);
+  });
+});
+
+describe("Better Auth config validation", () => {
+  it("basePath defaults to /api/auth when not specified", () => {
+    const config: BetterAuthConfig = {
+      enabled: true,
+    };
+
+    const basePath = config.basePath ?? "/api/auth";
+    expect(basePath).toBe("/api/auth");
+  });
+
+  it("trustedOrigins defaults to empty array when not specified", () => {
+    const config: BetterAuthConfig = {
+      enabled: true,
+    };
+
+    const trustedOrigins = config.trustedOrigins ?? [];
+    expect(trustedOrigins).toEqual([]);
+  });
+
+  it("supports multiple OAuth providers simultaneously", () => {
+    const config: BetterAuthConfig = {
+      appleOAuth: {
+        clientId: "apple-id",
+        clientSecret: "apple-secret",
+      },
+      enabled: true,
+      githubOAuth: {
+        clientId: "github-id",
+        clientSecret: "github-secret",
+      },
+      googleOAuth: {
+        clientId: "google-id",
+        clientSecret: "google-secret",
+      },
+    };
+
+    expect(config.googleOAuth).toBeDefined();
+    expect(config.githubOAuth).toBeDefined();
+    expect(config.appleOAuth).toBeDefined();
+  });
+});

package/src/betterAuth.ts

@@ -0,0 +1,104 @@
+/**
+ * Better Auth types and configuration interfaces for @terreno/api.
+ *
+ * These types support optional Better Auth integration alongside the existing
+ * JWT/Passport authentication system.
+ */
+
+/**
+ * OAuth provider configuration for Better Auth.
+ */
+export interface BetterAuthOAuthProvider {
+  clientId: string;
+  clientSecret: string;
+}
+
+/**
+ * Configuration options for Better Auth integration.
+ */
+export interface BetterAuthConfig {
+  /**
+   * Whether Better Auth is enabled for this server.
+   */
+  enabled: boolean;
+
+  /**
+   * Google OAuth provider configuration.
+   */
+  googleOAuth?: BetterAuthOAuthProvider;
+
+  /**
+   * Apple OAuth provider configuration.
+   */
+  appleOAuth?: BetterAuthOAuthProvider;
+
+  /**
+   * GitHub OAuth provider configuration.
+   */
+  githubOAuth?: BetterAuthOAuthProvider;
+
+  /**
+   * Trusted origins for CORS and redirect validation.
+   * Include your app's deep link schemes (e.g., "terreno://", "exp://").
+   */
+  trustedOrigins?: string[];
+
+  /**
+   * Base path for Better Auth routes.
+   * @default "/api/auth"
+   */
+  basePath?: string;
+
+  /**
+   * Secret key for Better Auth session encryption.
+   * If not provided, falls back to BETTER_AUTH_SECRET environment variable.
+   */
+  secret?: string;
+
+  /**
+   * Base URL for the auth server.
+   * If not provided, falls back to BETTER_AUTH_URL environment variable.
+   */
+  baseURL?: string;
+}
+
+/**
+ * Auth provider selection for setupServer.
+ * - "jwt": Traditional JWT/Passport authentication (default)
+ * - "better-auth": Better Auth with OAuth support
+ */
+export type AuthProvider = "jwt" | "better-auth";
+
+/**
+ * User data from Better Auth session.
+ */
+export interface BetterAuthUser {
+  id: string;
+  email: string;
+  name: string | null;
+  image: string | null;
+  emailVerified: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Session data from Better Auth.
+ */
+export interface BetterAuthSession {
+  id: string;
+  userId: string;
+  expiresAt: Date;
+  ipAddress: string | null;
+  userAgent: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Combined session and user data from Better Auth.
+ */
+export interface BetterAuthSessionData {
+  session: BetterAuthSession;
+  user: BetterAuthUser;
+}