@terreno/api 0.1.0 → 0.2.0

package/dist/expressServer.js

@@ -285,7 +285,7 @@ function initializeRoutes(UserModel, addRoutes, options) {
         app.use("/swagger", oapi.swaggerui());
     }
     (0, auth_1.addMeRoutes)(app, UserModel, options === null || options === void 0 ? void 0 : options.authOptions);
-    // Set up GitHub OAuth if configured
+    // Set up GitHub OAuth if configured (works with JWT auth)
     if (options.githubAuth) {
         (0, githubAuth_1.setupGitHubAuth)(app, UserModel, options.githubAuth);
         (0, githubAuth_1.addGitHubAuthRoutes)(app, UserModel, options.githubAuth, options.authOptions);
@@ -303,7 +303,7 @@ function initializeRoutes(UserModel, addRoutes, options) {
     });
     return app;
 }
-// Sets up the routes and returns a function to launch the API.
+// Sets up the routes and returns the app.
 function setupServer(options) {
     var UserModel = options.userModel;
     var addRoutes = options.addRoutes;

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export * from "./api";
 export * from "./auth";
+export * from "./betterAuth";
+export * from "./betterAuthApp";
+export * from "./betterAuthSetup";
 export * from "./errors";
 export * from "./expressServer";
 export * from "./githubAuth";
@@ -12,6 +15,7 @@ export * from "./openApiValidator";
 export * from "./permissions";
 export * from "./plugins";
 export * from "./populate";
+export * from "./terrenoApp";
 export * from "./terrenoPlugin";
 export * from "./transformers";
 export * from "./utils";

package/dist/index.js

@@ -16,6 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./api"), exports);
 __exportStar(require("./auth"), exports);
+__exportStar(require("./betterAuth"), exports);
+__exportStar(require("./betterAuthApp"), exports);
+__exportStar(require("./betterAuthSetup"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./expressServer"), exports);
 __exportStar(require("./githubAuth"), exports);
@@ -28,6 +31,7 @@ __exportStar(require("./openApiValidator"), exports);
 __exportStar(require("./permissions"), exports);
 __exportStar(require("./plugins"), exports);
 __exportStar(require("./populate"), exports);
+__exportStar(require("./terrenoApp"), exports);
 __exportStar(require("./terrenoPlugin"), exports);
 __exportStar(require("./transformers"), exports);
 __exportStar(require("./utils"), exports);

package/dist/terrenoApp.d.ts

@@ -0,0 +1,189 @@
+import * as Sentry from "@sentry/bun";
+import express from "express";
+import type { ModelRouterRegistration } from "./api";
+import { type UserModel as UserMongooseModel } from "./auth";
+import { type AuthOptions } from "./expressServer";
+import { type GitHubAuthOptions } from "./githubAuth";
+import { type LoggingOptions } from "./logger";
+import type { TerrenoPlugin } from "./terrenoPlugin";
+type CorsOrigin = string | boolean | RegExp | Array<boolean | string | RegExp> | ((requestOrigin: string | undefined, callback: (err: Error | null, origin?: boolean | string | RegExp | Array<boolean | string | RegExp>) => void) => void);
+/**
+ * Configuration options for TerrenoApp.
+ */
+export interface TerrenoAppOptions {
+    /** Mongoose User model with passport-local-mongoose plugin */
+    userModel: UserMongooseModel;
+    /** CORS origin configuration (default: "*") */
+    corsOrigin?: CorsOrigin;
+    /** Logging configuration options */
+    loggingOptions?: LoggingOptions;
+    /** Authentication configuration options */
+    authOptions?: AuthOptions;
+    /** GitHub OAuth configuration (enables GitHub authentication if provided) */
+    githubAuth?: GitHubAuthOptions;
+    /** Skip calling app.listen() in start() method (useful for testing) */
+    skipListen?: boolean;
+    /** Sentry configuration options */
+    sentryOptions?: Sentry.BunOptions;
+    /** Maximum number of array items in query parameters (default: 200) */
+    arrayLimit?: number;
+    /** Whether to log all incoming requests (default: true) */
+    logRequests?: boolean;
+}
+/**
+ * Fluent API for building Express applications with Terreno framework.
+ *
+ * TerrenoApp provides an alternative to `setupServer` using a registration
+ * pattern instead of callbacks. Build applications by registering model
+ * routers and plugins, then calling `start()` to begin listening.
+ *
+ * The middleware stack is configured in this order:
+ * 1. CORS
+ * 2. Custom middleware (via addMiddleware)
+ * 3. JSON body parser
+ * 4. Auth routes (/auth/login, /auth/signup, etc.)
+ * 5. JWT authentication setup
+ * 6. Request logging
+ * 7. Sentry scopes
+ * 8. OpenAPI middleware
+ * 9. /auth/me routes
+ * 10. GitHub OAuth routes (if enabled)
+ * 11. Registered model routers and plugins
+ * 12. Error handling middleware
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with model routers
+ * const todoRouter = modelRouter("/todos", Todo, {
+ *   permissions: { list: [Permissions.IsAuthenticated], ... },
+ * });
+ *
+ * const app = new TerrenoApp({ userModel: User })
+ *   .register(todoRouter)
+ *   .register(new HealthApp())
+ *   .start();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom middleware
+ * const app = new TerrenoApp({
+ *   userModel: User,
+ *   corsOrigin: ["https://app.example.com"],
+ *   loggingOptions: { logRequests: true },
+ *   githubAuth: {
+ *     clientId: process.env.GITHUB_CLIENT_ID!,
+ *     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *     callbackURL: process.env.GITHUB_CALLBACK_URL!,
+ *   },
+ * })
+ *   .addMiddleware((req, res, next) => {
+ *     res.setHeader("X-Custom-Header", "value");
+ *     next();
+ *   })
+ *   .register(todoRouter)
+ *   .register(userRouter)
+ *   .start();
+ * ```
+ *
+ * @see setupServer for the callback-based alternative
+ * @see TerrenoPlugin for creating reusable plugins
+ * @see modelRouter for creating CRUD route registrations
+ */
+export declare class TerrenoApp {
+    private options;
+    private registrations;
+    private middlewareFns;
+    /**
+     * Create a new TerrenoApp builder.
+     *
+     * @param options - Application configuration options including user model and auth settings
+     */
+    constructor(options: TerrenoAppOptions);
+    /**
+     * Register a model router or plugin with the application.
+     *
+     * Model routers are created with `modelRouter("/path", Model, options)` and
+     * provide CRUD endpoints. Plugins implement `TerrenoPlugin` interface and
+     * can register custom routes and middleware.
+     *
+     * Registrations are mounted in the order they are added.
+     *
+     * @param registration - A ModelRouterRegistration from modelRouter() or a TerrenoPlugin instance
+     * @returns This TerrenoApp instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const todoRouter = modelRouter("/todos", Todo, options);
+     * const healthPlugin = new HealthApp({ path: "/health" });
+     *
+     * app.register(todoRouter).register(healthPlugin);
+     * ```
+     */
+    register(registration: ModelRouterRegistration | TerrenoPlugin): this;
+    /**
+     * Add custom Express middleware to the application.
+     *
+     * Middleware is added BEFORE JSON body parsing and authentication setup,
+     * allowing you to modify incoming requests early in the middleware stack.
+     *
+     * @param fn - Express middleware function or a function that configures the app
+     * @returns This TerrenoApp instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * app.addMiddleware((req, res, next) => {
+     *   res.setHeader("X-Request-ID", req.id);
+     *   next();
+     * });
+     * ```
+     */
+    addMiddleware(fn: express.RequestHandler | ((app: express.Application) => void)): this;
+    /**
+     * Build the Express application without starting the server.
+     *
+     * Configures the complete middleware stack including:
+     * - CORS, JSON parsing, authentication, logging, Sentry, OpenAPI
+     * - All registered model routers and plugins
+     * - Error handling middleware
+     *
+     * Use this method when you need the Express app instance for testing
+     * or custom server setup. For normal use, call `start()` instead.
+     *
+     * @returns Configured Express application instance
+     *
+     * @example
+     * ```typescript
+     * const app = new TerrenoApp({ userModel: User })
+     *   .register(todoRouter)
+     *   .build();
+     *
+     * // Use app for testing with supertest
+     * await request(app).get("/todos").expect(200);
+     * ```
+     */
+    build(): express.Application;
+    /**
+     * Build the Express application and start listening on the configured port.
+     *
+     * Calls `build()` to configure the application, then starts an HTTP server
+     * listening on the port specified by the `PORT` environment variable (default: 9000).
+     * If `skipListen` option is true, the app is built but the server is not started.
+     *
+     * @returns Configured Express application instance
+     *
+     * @throws Process exits with code 1 if the server fails to start
+     *
+     * @example
+     * ```typescript
+     * // Start server on port 3000
+     * process.env.PORT = "3000";
+     * const app = new TerrenoApp({ userModel: User })
+     *   .register(todoRouter)
+     *   .start();
+     * ```
+     */
+    start(): express.Application;
+    private isModelRouterRegistration;
+}
+export {};

package/dist/terrenoApp.js

@@ -0,0 +1,352 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TerrenoApp = void 0;
+var Sentry = __importStar(require("@sentry/bun"));
+var openapi_1 = __importDefault(require("@wesleytodd/openapi"));
+var cors_1 = __importDefault(require("cors"));
+var express_1 = __importDefault(require("express"));
+var qs_1 = __importDefault(require("qs"));
+var auth_1 = require("./auth");
+var errors_1 = require("./errors");
+var expressServer_1 = require("./expressServer");
+var githubAuth_1 = require("./githubAuth");
+var logger_1 = require("./logger");
+var openApiEtag_1 = require("./openApiEtag");
+/**
+ * Fluent API for building Express applications with Terreno framework.
+ *
+ * TerrenoApp provides an alternative to `setupServer` using a registration
+ * pattern instead of callbacks. Build applications by registering model
+ * routers and plugins, then calling `start()` to begin listening.
+ *
+ * The middleware stack is configured in this order:
+ * 1. CORS
+ * 2. Custom middleware (via addMiddleware)
+ * 3. JSON body parser
+ * 4. Auth routes (/auth/login, /auth/signup, etc.)
+ * 5. JWT authentication setup
+ * 6. Request logging
+ * 7. Sentry scopes
+ * 8. OpenAPI middleware
+ * 9. /auth/me routes
+ * 10. GitHub OAuth routes (if enabled)
+ * 11. Registered model routers and plugins
+ * 12. Error handling middleware
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with model routers
+ * const todoRouter = modelRouter("/todos", Todo, {
+ *   permissions: { list: [Permissions.IsAuthenticated], ... },
+ * });
+ *
+ * const app = new TerrenoApp({ userModel: User })
+ *   .register(todoRouter)
+ *   .register(new HealthApp())
+ *   .start();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom middleware
+ * const app = new TerrenoApp({
+ *   userModel: User,
+ *   corsOrigin: ["https://app.example.com"],
+ *   loggingOptions: { logRequests: true },
+ *   githubAuth: {
+ *     clientId: process.env.GITHUB_CLIENT_ID!,
+ *     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *     callbackURL: process.env.GITHUB_CALLBACK_URL!,
+ *   },
+ * })
+ *   .addMiddleware((req, res, next) => {
+ *     res.setHeader("X-Custom-Header", "value");
+ *     next();
+ *   })
+ *   .register(todoRouter)
+ *   .register(userRouter)
+ *   .start();
+ * ```
+ *
+ * @see setupServer for the callback-based alternative
+ * @see TerrenoPlugin for creating reusable plugins
+ * @see modelRouter for creating CRUD route registrations
+ */
+var TerrenoApp = /** @class */ (function () {
+    /**
+     * Create a new TerrenoApp builder.
+     *
+     * @param options - Application configuration options including user model and auth settings
+     */
+    function TerrenoApp(options) {
+        this.registrations = [];
+        this.middlewareFns = [];
+        this.options = options;
+    }
+    /**
+     * Register a model router or plugin with the application.
+     *
+     * Model routers are created with `modelRouter("/path", Model, options)` and
+     * provide CRUD endpoints. Plugins implement `TerrenoPlugin` interface and
+     * can register custom routes and middleware.
+     *
+     * Registrations are mounted in the order they are added.
+     *
+     * @param registration - A ModelRouterRegistration from modelRouter() or a TerrenoPlugin instance
+     * @returns This TerrenoApp instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const todoRouter = modelRouter("/todos", Todo, options);
+     * const healthPlugin = new HealthApp({ path: "/health" });
+     *
+     * app.register(todoRouter).register(healthPlugin);
+     * ```
+     */
+    TerrenoApp.prototype.register = function (registration) {
+        this.registrations.push(registration);
+        return this;
+    };
+    /**
+     * Add custom Express middleware to the application.
+     *
+     * Middleware is added BEFORE JSON body parsing and authentication setup,
+     * allowing you to modify incoming requests early in the middleware stack.
+     *
+     * @param fn - Express middleware function or a function that configures the app
+     * @returns This TerrenoApp instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * app.addMiddleware((req, res, next) => {
+     *   res.setHeader("X-Request-ID", req.id);
+     *   next();
+     * });
+     * ```
+     */
+    TerrenoApp.prototype.addMiddleware = function (fn) {
+        this.middlewareFns.push(fn);
+        return this;
+    };
+    /**
+     * Build the Express application without starting the server.
+     *
+     * Configures the complete middleware stack including:
+     * - CORS, JSON parsing, authentication, logging, Sentry, OpenAPI
+     * - All registered model routers and plugins
+     * - Error handling middleware
+     *
+     * Use this method when you need the Express app instance for testing
+     * or custom server setup. For normal use, call `start()` instead.
+     *
+     * @returns Configured Express application instance
+     *
+     * @example
+     * ```typescript
+     * const app = new TerrenoApp({ userModel: User })
+     *   .register(todoRouter)
+     *   .build();
+     *
+     * // Use app for testing with supertest
+     * await request(app).get("/todos").expect(200);
+     * ```
+     */
+    TerrenoApp.prototype.build = function () {
+        var e_1, _a, e_2, _b;
+        var _c;
+        (0, logger_1.setupLogging)(this.options.loggingOptions);
+        var app = (0, express_1.default)();
+        var options = this.options;
+        app.set("query parser", function (str) { var _a; return qs_1.default.parse(str, { arrayLimit: (_a = options.arrayLimit) !== null && _a !== void 0 ? _a : 200 }); });
+        app.use((0, cors_1.default)({ origin: (_c = options.corsOrigin) !== null && _c !== void 0 ? _c : "*" }));
+        try {
+            // Apply custom middleware before JSON parsing
+            for (var _d = __values(this.middlewareFns), _e = _d.next(); !_e.done; _e = _d.next()) {
+                var fn = _e.value;
+                if (fn.length <= 3) {
+                    // express.RequestHandler (req, res, next)
+                    app.use(fn);
+                }
+                else {
+                    // Function that receives the app
+                    fn(app);
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_e && !_e.done && (_a = _d.return)) _a.call(_d);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        app.use(express_1.default.json());
+        // Auth routes (login/signup/refresh_token) before JWT middleware
+        (0, auth_1.addAuthRoutes)(app, options.userModel, options.authOptions);
+        (0, auth_1.setupAuth)(app, options.userModel);
+        if (options.logRequests !== false) {
+            app.use(expressServer_1.logRequests);
+        }
+        // Store logging options on the response locals
+        app.use(function (_req, res, next) {
+            res.locals.loggingOptions = options.loggingOptions;
+            next();
+        });
+        // Sentry scopes
+        app.all("*", function (req, _res, next) {
+            var _a;
+            var transactionId = req.header("X-Transaction-ID");
+            var sessionId = req.header("X-Session-ID");
+            if (transactionId) {
+                Sentry.getCurrentScope().setTag("transaction_id", transactionId);
+            }
+            if (sessionId) {
+                Sentry.getCurrentScope().setTag("session_id", sessionId);
+            }
+            if ((_a = req.user) === null || _a === void 0 ? void 0 : _a._id) {
+                Sentry.getCurrentScope().setTag("user", req.user._id);
+            }
+            next();
+        });
+        // OpenAPI
+        app.use(openApiEtag_1.openApiEtagMiddleware);
+        var oapi = (0, openapi_1.default)({
+            info: {
+                description: "Generated docs from an Express api",
+                title: "Express Application",
+                version: "1.0.0",
+            },
+            openapi: "3.0.0",
+        });
+        app.use(oapi);
+        if (process.env.ENABLE_SWAGGER === "true") {
+            app.use("/swagger", oapi.swaggerui());
+        }
+        (0, auth_1.addMeRoutes)(app, options.userModel, options.authOptions);
+        // GitHub OAuth
+        if (options.githubAuth) {
+            (0, githubAuth_1.setupGitHubAuth)(app, options.userModel, options.githubAuth);
+            (0, githubAuth_1.addGitHubAuthRoutes)(app, options.userModel, options.githubAuth, options.authOptions);
+        }
+        try {
+            // Mount registered model routers and plugins
+            for (var _f = __values(this.registrations), _g = _f.next(); !_g.done; _g = _f.next()) {
+                var registration = _g.value;
+                if (this.isModelRouterRegistration(registration)) {
+                    app.use(registration.path, registration.router);
+                }
+                else {
+                    registration.register(app);
+                }
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        // Inject openApi into model router options for registered routers
+        // The openApi middleware handles this via the oapi instance already mounted on the app
+        Sentry.setupExpressErrorHandler(app);
+        // Error middleware
+        app.use(errors_1.apiUnauthorizedMiddleware);
+        app.use(errors_1.apiErrorMiddleware);
+        app.use(function onError(err, _req, res, _next) {
+            logger_1.logger.error("Fallthrough error: ".concat(err).concat((err === null || err === void 0 ? void 0 : err.stack) ? "\n".concat(err.stack) : "", "}"));
+            Sentry.captureException(err);
+            res.statusCode = 500;
+            res.end("".concat(res.sentry, "\n"));
+        });
+        return app;
+    };
+    /**
+     * Build the Express application and start listening on the configured port.
+     *
+     * Calls `build()` to configure the application, then starts an HTTP server
+     * listening on the port specified by the `PORT` environment variable (default: 9000).
+     * If `skipListen` option is true, the app is built but the server is not started.
+     *
+     * @returns Configured Express application instance
+     *
+     * @throws Process exits with code 1 if the server fails to start
+     *
+     * @example
+     * ```typescript
+     * // Start server on port 3000
+     * process.env.PORT = "3000";
+     * const app = new TerrenoApp({ userModel: User })
+     *   .register(todoRouter)
+     *   .start();
+     * ```
+     */
+    TerrenoApp.prototype.start = function () {
+        var app = this.build();
+        if (!this.options.skipListen) {
+            var port_1 = process.env.PORT || "9000";
+            try {
+                app.listen(port_1, function () {
+                    logger_1.logger.info("Listening on port ".concat(port_1));
+                });
+            }
+            catch (error) {
+                logger_1.logger.error("Error trying to start HTTP server: ".concat(error, "\n").concat(error.stack));
+                process.exit(1);
+            }
+        }
+        return app;
+    };
+    TerrenoApp.prototype.isModelRouterRegistration = function (registration) {
+        return registration.__type === "modelRouter";
+    };
+    return TerrenoApp;
+}());
+exports.TerrenoApp = TerrenoApp;

package/dist/terrenoApp.test.d.ts

@@ -0,0 +1 @@
+export {};