Added changes for issue 33

Author: joeljoby02

README.md

@@ -26,6 +26,27 @@ Stores important bits of knowledge in structured JSON-LD objects:
 1. **Open and Free**—expose all contributions immediately without charge to write or read;
 1. **Attributed and Versioned**—always include asserted ownership and transaction metadata so consumers can evaluate trustworthiness and relevance.
 
+### Programmatic usage
+This project exposes a single public entry point at the package root (`index.js`).  Only a few
+functions are exported – everything else lives in internal modules and is intentionally
+kept private.  Example:
+
+```js
+import { app, createServer, start } from 'rerum_server'
+
+// `app` is the configured Express application; you can pass it to Supertest or reuse it
+// inside another HTTP stack.
+
+const server = createServer(8080)   // returns a http.Server but does not listen
+server.listen()
+
+// or simply
+start(8080) // convenience helper that both creates and listens
+```
+
+Consumers no longer need to reach into `./app.js` or other deep paths – if it isn't
+exported here it isn't part of the stable API.
+
 ## What we add
 You will find a `__rerum` property on anything you read from this repository. This is written onto
 all objects by the server and is not editable by the client applications. While applications may assert

__tests__/public_api.test.js

@@ -0,0 +1,22 @@
+import { app, createServer, start } from '../index.js'
+
+describe('public API entry point', () => {
+  test('exports an express app instance', () => {
+    expect(app).toBeDefined()
+    expect(typeof app.use).toBe('function') // express app
+  })
+
+  test('createServer returns a http.Server', () => {
+    const server = createServer(0) // port 0 for ephemeral
+    expect(server).toBeDefined()
+    expect(typeof server.listen).toBe('function')
+    server.close()
+  })
+
+  test('start starts the server and returns it', (done) => {
+    const server = start(0)
+    server.on('listening', () => {
+      server.close(() => done())
+    })
+  })
+})

__tests__/routes_mounted.test.js

@@ -7,7 +7,8 @@
 
 import request from "supertest"
 import api_routes from "../routes/api-routes.js"
-import app from "../app.js"
+// leverage the public entry point instead of a deep path
+import app from "../index.js"
 import fs from "fs"
 
 let app_stack = app.router.stack

index.js

@@ -0,0 +1,64 @@
+// Public entry point for the RERUM API v1 server library
+// Only the things exported here are considered a supported, stable
+// API.  Internal helpers and modules (controllers, database, routes,
+// etc.) remain private and are not re-exported.  Consumers of the
+// package should be able to import from the package root rather than
+// reach into deep paths.
+
+import http from 'http'
+import app from './app.js'
+
+/**
+ * Express application instance used throughout the project.  Exported
+ * primarily for testing or embedding inside another server.
+ *
+ * ```js
+ * import { app } from 'rerum_server'
+ * ```
+ */
+export { app }
+
+/**
+ * Default export is the express app largely for backwards compatibility
+ * with consumers that do `import app from 'rerum_server'`.
+ */
+export default app
+
+/**
+ * Helper that creates an HTTP server for the configured express app.
+ * The returned server is **not** listening yet; caller may attach
+ * additional listeners or configure timeouts before calling
+ * `server.listen(...)`.
+ *
+ * @param {number|string} [port=process.env.PORT||3001] port to assign to
+ *        the express app and eventually listen on
+ * @returns {import('http').Server} http server instance
+ */
+export function createServer(port = process.env.PORT ?? 3001) {
+  app.set('port', port)
+  const server = http.createServer(app)
+
+  // mirror the configuration from bin/rerum_v1.js so that programmatic
+  // users get the same keep-alive behaviour as the CLI entry point.
+  server.keepAliveTimeout = 8 * 1000
+  server.headersTimeout = 8.5 * 1000
+
+  return server
+}
+
+/**
+ * Convenience function to start the server immediately.  Returns the
+ * server instance so callers can close it in tests or hook events.
+ *
+ * @param {number|string} [port] optional port override
+ * @returns {import('http').Server}
+ */
+export function start(port) {
+  const p = port ?? process.env.PORT ?? 3001
+  const server = createServer(p)
+  server.listen(p)
+  server.on('listening', () => {
+    console.log('LISTENING ON ' + p)
+  })
+  return server
+}

package.json

@@ -23,6 +23,7 @@
     "node": ">=24.12.0",
     "npm": ">=11.7.0"
   },
+  "main": "index.js",
   "scripts": {
     "start": "node ./bin/rerum_v1.js",
     "test": "jest",