fusion-framework 0.0.1 → 1.1.2

package/README.md

@@ -0,0 +1,76 @@
+# Fusion Framework (Node.js)
+
+Class-based HTTP APIs on a shared Rust core (`fusion-core`).
+
+Handlers use `this.params` / `this.query` / `this.body` / `this.state` (no signature param injection — that is Python-only DX).
+
+## Links
+
+- **Docs:** [fusion.cipherunit.xyz](https://fusion.cipherunit.xyz/)
+- **GitHub:** [cipherunits/fusion-framework](https://github.com/cipherunits/fusion-framework)
+- **CLI:** [cipherunits/fusion-tool](https://github.com/cipherunits/fusion-tool)
+
+## Install
+
+```bash
+cd crates/fusion-node
+npm install
+npm run build:debug
+```
+
+Or after publish:
+
+```bash
+npm i fusion-framework
+```
+
+## Quick start
+
+```js
+import { FusionBaseApi, route, status, FusionApp, getSettings, settings } from 'fusion-framework'
+
+export const ItemModule = route('/api/[module]/{id}')(
+  class ItemModule extends FusionBaseApi {
+    get() {
+      return this.response({ id: this.params.id }, status.HTTP_SUCCESS)
+    }
+  },
+)
+
+const MIDDLEWARE = [] // optional — framework has no defaults
+
+settings.ensureLoaded()
+const app = new FusionApp(getSettings())
+for (const mw of MIDDLEWARE) app.use(mw)
+await app.listen()
+```
+
+## Middleware
+
+```js
+import { bearerJwt, requireRoles, route } from 'fusion-framework'
+
+const MIDDLEWARE = [bearerJwt()] // or bearerJwt({ verify })
+
+route('/api/admin', { roles: ['admin', 'super_admin'] })(
+  class AdminModule extends FusionBaseApi {
+    get() {
+      return this.response({ user: this.state.jwt?.sub })
+    }
+  },
+)
+```
+
+Sync or async: `(request, callNext) => …` / `async (request, callNext) => await callNext(request)`.
+
+## Status codes
+
+```js
+import { status } from 'fusion-framework'
+status.HTTP_SUCCESS // 200
+status.HTTP_404_NOT_FOUND
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,127 @@
+export class App {
+  constructor()
+  route(method: string, path: string, handler: (req: FusionRequest) => FusionResponse | string): void
+  listen(host: string, port: number): Promise<void>
+}
+
+export class Settings {
+  constructor()
+  loadJson(path?: string | null, env?: string | null, extraRoots?: string[]): void
+  ensureLoaded(extraRoots?: string[]): void
+  merge(values: Record<string, unknown>): void
+  get(key: string, defaultValue?: unknown): unknown
+  readonly host: string
+  readonly port: number
+  readonly debug: boolean
+  readonly env: string
+}
+
+export class FusionBaseApi {
+  request: FusionRequest
+  constructor(request: FusionRequest)
+  readonly method: string
+  readonly path: string
+  readonly body: string
+  readonly headers: Record<string, string>
+  readonly params: Record<string, string>
+  readonly query: Record<string, string>
+  readonly state: Record<string, unknown>
+  response(body?: unknown, status?: number, headers?: Record<string, string>): FusionResponse
+}
+
+export class HTTPException extends Error {
+  status: number
+  detail: unknown
+  headers: Record<string, string>
+  constructor(status: number, detail?: unknown, headers?: Record<string, string>)
+  toResponse(): FusionResponse
+}
+
+export class FusionApp {
+  constructor(settings?: Partial<FusionSettings>)
+  use(middleware: FusionMiddleware): void
+  mount(): void
+  listen(host?: string, port?: number): Promise<void>
+}
+
+export type RouteOptions = {
+  tags?: string[]
+  desc?: string
+  title?: string
+  version?: string
+  deprecated?: boolean
+  middleware?: FusionMiddleware[]
+  roles?: string[]
+  roleClaim?: string
+  roleStateKey?: string
+}
+
+export function router(path: string, options?: RouteOptions): <T>(ApiClass: T) => T
+/** Alias of `router`. */
+export function route(path: string, options?: RouteOptions): <T>(ApiClass: T) => T
+
+export function bearerJwt(options?: {
+  stateKey?: string
+  header?: string
+  verify?: (token: string) => Record<string, unknown> | null
+}): FusionMiddleware
+
+export function requireRoles(...roles: string[]): FusionMiddleware
+export function requireRoles(options: {
+  roles: string[]
+  claim?: string
+  stateKey?: string
+}): FusionMiddleware
+
+export function runMiddlewareChain(
+  request: FusionRequest,
+  middlewares: FusionMiddleware[],
+  handler: (request: FusionRequest) => unknown | Promise<unknown>,
+): Promise<unknown>
+
+export function apiResourceName(cls: { name: string } | string): string
+export function resolveRoutePath(path: string, cls: { name: string }): string
+export function configure(settings: Record<string, unknown>): FusionSettings
+export function getSettings(): FusionSettings
+export function run(
+  options?: string | { settingsModule?: string; middleware?: FusionMiddleware[] },
+): Promise<FusionApp>
+export function coerceParam(raw: string, kind?: string): unknown
+export function getHttpMethods(): string[]
+export function apiResourceNameJs(className: string): string
+export function resolveRoutePathJs(template: string, className: string): string
+export function coerceParamJs(raw: string, kind?: string): unknown
+
+export const settings: Settings
+export const status: Record<string, number>
+export const HTTP_METHODS: string[]
+
+export interface FusionSettings {
+  host: string
+  port: number
+  debug: boolean
+  env?: string
+}
+
+export interface FusionRequest {
+  method: string
+  path: string
+  body: string
+  headers: Record<string, string>
+  params: Record<string, string>
+  query: Record<string, string>
+  state?: Record<string, unknown>
+}
+
+export type FusionMiddleware = (
+  request: FusionRequest,
+  callNext: (request: FusionRequest) => unknown | Promise<unknown>,
+) => unknown | Promise<unknown>
+
+export type FusionResponse =
+  | string
+  | {
+      status?: number
+      body?: unknown
+      headers?: Record<string, string>
+    }

package/index.js

@@ -0,0 +1,652 @@
+const path = require('path')
+const fs = require('fs')
+const { platform, arch } = process
+
+function napiTriple() {
+  const plat =
+    platform === 'win32' ? 'win32' : platform === 'darwin' ? 'darwin' : platform === 'linux' ? 'linux' : platform
+  const cpu =
+    arch === 'x64' ? 'x64' : arch === 'arm64' ? 'arm64' : arch === 'ia32' ? 'ia32' : arch
+
+  if (plat === 'win32' && cpu === 'x64') return 'win32-x64-msvc'
+  if (plat === 'darwin' && cpu === 'arm64') return 'darwin-arm64'
+  if (plat === 'darwin' && cpu === 'x64') return 'darwin-x64'
+  if (plat === 'linux' && cpu === 'x64') return 'linux-x64-gnu'
+  if (plat === 'linux' && cpu === 'arm64') return 'linux-arm64-gnu'
+  return `${plat}-${cpu}`
+}
+
+function loadNative() {
+  const triple = napiTriple()
+  const candidates = [
+    path.join(__dirname, `fusion-node.${triple}.node`),
+    path.join(__dirname, 'fusion-node.node'),
+    path.join(__dirname, 'fusion_node.node'),
+  ]
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return require(candidate)
+    }
+  }
+  throw new Error(
+    `fusion-framework native addon not found for ${triple}. ` +
+      `Run \`npm run build\` in crates/fusion-node or install a published package.`,
+  )
+}
+
+const native = loadNative()
+const NativeApp = native.App
+const NativeSettings = native.Settings
+
+const HTTP_METHODS = native.getHttpMethods()
+const settings = new NativeSettings()
+const registry = []
+let activeGlobalMiddleware = []
+
+const status = Object.create(null)
+if (typeof native.getHttpStatusCodes === 'function') {
+  for (const entry of native.getHttpStatusCodes()) {
+    status[entry.name] = entry.code
+  }
+} else {
+  // Fallback if native addon is older
+  Object.assign(status, {
+    HTTP_SUCCESS: 200,
+    HTTP_200_OK: 200,
+    HTTP_201_CREATED: 201,
+    HTTP_204_NO_CONTENT: 204,
+    HTTP_400_BAD_REQUEST: 400,
+    HTTP_401_UNAUTHORIZED: 401,
+    HTTP_403_FORBIDDEN: 403,
+    HTTP_404_NOT_FOUND: 404,
+    HTTP_500_INTERNAL_SERVER_ERROR: 500,
+  })
+}
+
+class FusionBaseApi {
+  constructor(request) {
+    this.request = request
+  }
+
+  get method() {
+    return String(this.request.method || '').toUpperCase()
+  }
+
+  get path() {
+    return String(this.request.path || '')
+  }
+
+  get body() {
+    return String(this.request.body || '')
+  }
+
+  get headers() {
+    return this.request.headers || {}
+  }
+
+  get params() {
+    return this.request.params || {}
+  }
+
+  get query() {
+    return this.request.query || {}
+  }
+
+  get state() {
+    return this.request.state || {}
+  }
+
+  response(body = '', status = 200, headers = {}) {
+    // Keep this helper thin: content-type inference lives in fusion-core.
+    const out = { status, body }
+    const keys = headers ? Object.keys(headers) : []
+    if (keys.length) out.headers = { ...headers }
+    return out
+  }
+}
+
+function apiResourceName(cls) {
+  const name = typeof cls === 'string' ? cls : cls.name
+  return native.apiResourceNameJs(name)
+}
+
+function resolveRoutePath(routePath, ApiClass) {
+  return native.resolveRoutePathJs(routePath, ApiClass.name)
+}
+
+function ensureState(request) {
+  if (!request.state || typeof request.state !== 'object') {
+    request.state = {}
+  }
+  return request.state
+}
+
+function isResponse(value) {
+  return value && typeof value === 'object' && 'status' in value
+}
+
+async function runMiddlewareChain(request, middlewares, handler) {
+  ensureState(request)
+  let index = 0
+
+  async function dispatch(i, req) {
+    if (i >= middlewares.length) {
+      return await handler(req)
+    }
+    const middleware = middlewares[i]
+    const callNext = (nextReq) => dispatch(i + 1, nextReq)
+    let result = middleware(req, callNext)
+    if (result && typeof result.then === 'function') {
+      result = await result
+    }
+    if (isResponse(result)) return result
+    return result
+  }
+
+  return dispatch(0, request)
+}
+
+function requireRoles(...rolesOrOptions) {
+  let roles = rolesOrOptions
+  let claim = 'roles'
+  let stateKey = 'jwt'
+  if (
+    rolesOrOptions.length === 1 &&
+    rolesOrOptions[0] &&
+    typeof rolesOrOptions[0] === 'object' &&
+    !Array.isArray(rolesOrOptions[0])
+  ) {
+    const opts = rolesOrOptions[0]
+    roles = Array.isArray(opts.roles) ? opts.roles : []
+    if (opts.claim) claim = opts.claim
+    if (opts.stateKey) stateKey = opts.stateKey
+  }
+  const allowed = new Set(roles.map(String))
+  return (request, callNext) => {
+    const payload = ensureState(request)[stateKey]
+    if (!payload) {
+      return { status: 401, body: { detail: 'Authentication required' } }
+    }
+    let userRoles = payload[claim]
+    if (userRoles == null) {
+      return { status: 403, body: { detail: `Missing '${claim}' claim` } }
+    }
+    if (typeof userRoles === 'string') userRoles = [userRoles]
+    if (!Array.isArray(userRoles)) {
+      return { status: 403, body: { detail: `Invalid '${claim}' claim` } }
+    }
+    const hasRole = userRoles.some((r) => allowed.has(String(r)))
+    if (!hasRole) {
+      return { status: 403, body: { detail: 'Insufficient permissions', required: [...allowed] } }
+    }
+    return callNext(request)
+  }
+}
+
+function bearerJwt(options = {}) {
+  const stateKey = options.stateKey || 'jwt'
+  const headerName = options.header || 'Authorization'
+  const verify = typeof options.verify === 'function' ? options.verify : null
+
+  return (request, callNext) => {
+    const headers = request.headers || {}
+    const auth =
+      headers[headerName] || headers[headerName.toLowerCase()] || headers[headerName.toUpperCase()]
+    if (!auth || !String(auth).toLowerCase().startsWith('bearer ')) {
+      return { status: 401, body: { detail: 'Missing bearer token' } }
+    }
+    const token = String(auth).slice(7).trim()
+    try {
+      let payload
+      if (verify) {
+        payload = verify(token)
+        if (!payload || typeof payload !== 'object') {
+          return { status: 401, body: { detail: 'Invalid token' } }
+        }
+      } else {
+        const parts = token.split('.')
+        if (parts.length !== 3) throw new Error('bad token')
+        const payloadB64 = parts[1] + '='.repeat((4 - (parts[1].length % 4)) % 4)
+        payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'))
+      }
+      ensureState(request)[stateKey] = payload
+      return callNext(request)
+    } catch {
+      return { status: 401, body: { detail: 'Invalid token' } }
+    }
+  }
+}
+
+function router(routePath, options = {}) {
+  return function decorate(ApiClass) {
+    const resolvedBase = resolveRoutePath(routePath, ApiClass)
+
+    const v = (options.version ?? '').toString().trim()
+    const resolved =
+      v.length > 0 ? `${v}/${resolvedBase.replace(/^\/+/, '')}` : resolvedBase
+
+    ApiClass.__fusion_path__ = resolved
+    ApiClass.__fusion_path_template__ = routePath
+
+    const routeMiddleware = Array.isArray(options.middleware) ? [...options.middleware] : []
+    if (Array.isArray(options.roles) && options.roles.length) {
+      routeMiddleware.push(
+        requireRoles({
+          roles: options.roles,
+          claim: options.roleClaim || 'roles',
+          stateKey: options.roleStateKey || 'jwt',
+        }),
+      )
+    }
+
+    registry.push({
+      path: resolved,
+      ApiClass,
+      middleware: routeMiddleware,
+      swagger: {
+        tags: Array.isArray(options.tags) ? options.tags : [],
+        description: options.desc ?? null,
+        title: options.title ?? null,
+        deprecated: !!options.deprecated,
+      },
+      version_prefix: v,
+    })
+    return ApiClass
+  }
+}
+
+function configure(next = {}) {
+  settings.merge(next)
+  return getSettings()
+}
+
+function getSettings() {
+  settings.ensureLoaded()
+  return {
+    host: settings.host,
+    port: settings.port,
+    debug: settings.debug,
+    env: settings.env,
+  }
+}
+
+function definesMethod(ApiClass, methodName) {
+  let current = ApiClass
+  while (current && current !== Function.prototype) {
+    if (current === FusionBaseApi) break
+    if (Object.prototype.hasOwnProperty.call(current.prototype, methodName)) {
+      return true
+    }
+    current = Object.getPrototypeOf(current)
+  }
+  return false
+}
+
+class HTTPException extends Error {
+  constructor(status, detail = null, headers = {}) {
+    super(typeof detail === 'string' ? detail : `HTTP ${status}`)
+    this.status = Number(status)
+    this.detail = detail == null ? '' : detail
+    this.headers = headers || {}
+  }
+
+  toResponse() {
+    const headers = { ...this.headers }
+    const body = this.detail
+    // Keep this helper thin: content-type inference lives in fusion-core.
+    const out = { status: this.status, body }
+    const keys = headers ? Object.keys(headers) : []
+    if (keys.length) out.headers = headers
+    return out
+  }
+}
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+}
+
+function asList(value) {
+  return Array.isArray(value) ? value : []
+}
+
+function truthyEnabled(value, defaultValue = true) {
+  if (value === undefined || value === null) return defaultValue
+  if (value === false || value === 0 || value === 'false' || value === '0' || value === 'off' || value === 'no') {
+    return false
+  }
+  if (value === true || value === 1 || value === 'true' || value === '1' || value === 'on' || value === 'yes') {
+    return true
+  }
+  return Boolean(value)
+}
+
+function readSwaggerSettings() {
+  if (!truthyEnabled(settings.get('swagger.enabled', true))) {
+    return { enabled: false }
+  }
+
+  let pathValue = settings.get('swagger.path', '/swagger')
+  if (pathValue === false || pathValue === null || pathValue === '' || pathValue === 'false' || pathValue === 'off') {
+    return { enabled: false }
+  }
+
+  let prefix = String(pathValue).replace(/\/+$/, '') || '/swagger'
+  if (!prefix.startsWith('/')) prefix = `/${prefix}`
+
+  const info = asObject(settings.get('swagger.info', {}))
+  for (const key of ['title', 'version', 'description', 'termsOfService', 'contact', 'license']) {
+    const flat = settings.get(`swagger.${key}`, undefined)
+    if (flat !== undefined && flat !== null && info[key] === undefined) info[key] = flat
+  }
+  if (!info.title) info.title = 'fusion-framework'
+  if (!info.version) info.version = '1.0.0'
+
+  const pageTitle = settings.get('swagger.title', null) || info.title || 'Fusion API Docs'
+
+  const authRaw = asObject(settings.get('swagger.auth', {}))
+  const schemes = asObject(authRaw.schemes)
+  const oauth = asObject(authRaw.oauth)
+  const globalSecurity = asList(authRaw.global)
+  let persistAuth = authRaw.persistAuthorization
+  if (persistAuth === undefined) persistAuth = false
+
+  const navbarRaw = asObject(settings.get('swagger.navbar', {}))
+  const navbar = {
+    enabled: truthyEnabled(navbarRaw.enabled, true),
+    showUrlInput: truthyEnabled(navbarRaw.showUrlInput, true),
+    urls: Array.isArray(navbarRaw.urls) ? navbarRaw.urls : null,
+  }
+
+  const ui = {
+    deepLinking: true,
+    displayOperationId: false,
+    defaultModelsExpandDepth: 1,
+    defaultModelExpandDepth: 1,
+    defaultModelRendering: 'example',
+    docExpansion: 'list',
+    filter: true,
+    tryItOutEnabled: true,
+    persistAuthorization: Boolean(persistAuth),
+    displayRequestDuration: true,
+    showExtensions: false,
+    showCommonExtensions: false,
+    syntaxHighlight: { activated: true, theme: 'agate' },
+    withCredentials: false,
+    validatorUrl: 'https://validator.swagger.io/validator',
+    ...asObject(settings.get('swagger.ui', {})),
+  }
+  if (Object.prototype.hasOwnProperty.call(authRaw, 'persistAuthorization')) {
+    ui.persistAuthorization = Boolean(persistAuth)
+  }
+
+  let servers = settings.get('swagger.servers', null)
+  if (!Array.isArray(servers)) servers = []
+
+  return {
+    enabled: true,
+    path: prefix,
+    pageTitle: String(pageTitle),
+    info,
+    servers,
+    auth: {
+      schemes,
+      global: globalSecurity,
+      oauth,
+      persistAuthorization: Boolean(persistAuth),
+    },
+    navbar,
+    ui,
+  }
+}
+
+function applySwaggerOpenApi(openapi, swagger) {
+  openapi.info = { ...asObject(openapi.info), ...swagger.info }
+  if (swagger.servers?.length) openapi.servers = swagger.servers
+  if (swagger.auth?.schemes && Object.keys(swagger.auth.schemes).length) {
+    openapi.components = asObject(openapi.components)
+    openapi.components.securitySchemes = {
+      ...asObject(openapi.components.securitySchemes),
+      ...swagger.auth.schemes,
+    }
+  }
+  if (swagger.auth?.global?.length) openapi.security = swagger.auth.global
+  return openapi
+}
+
+function swaggerUiHtml(swagger, openapiUrl) {
+  const uiOpts = { ...swagger.ui }
+  delete uiOpts.presets
+  delete uiOpts.plugins
+  delete uiOpts.layout
+
+  if (swagger.navbar?.urls?.length) {
+    delete uiOpts.url
+    uiOpts.urls = swagger.navbar.urls
+  } else {
+    uiOpts.url = openapiUrl
+    delete uiOpts.urls
+  }
+  uiOpts.dom_id = '#swagger-ui'
+
+  const uiJson = JSON.stringify(uiOpts).replace(/</g, '\\u003c')
+  const oauth = swagger.auth?.oauth && Object.keys(swagger.auth.oauth).length ? swagger.auth.oauth : null
+  const oauthJson = JSON.stringify(oauth).replace(/</g, '\\u003c')
+  const title = String(swagger.pageTitle)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+
+  const navbarEnabled = !!swagger.navbar?.enabled
+  const showUrlInput = swagger.navbar?.showUrlInput !== false
+  const hideUrlCss =
+    navbarEnabled && !showUrlInput
+      ? `<style>.topbar .download-url-wrapper { display: none !important; }</style>`
+      : ''
+  const standaloneScript = navbarEnabled
+    ? `<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js"></script>`
+    : ''
+
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css" />
+    ${hideUrlCss}
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
+    ${standaloneScript}
+    <script>
+      window.onload = function() {
+        var opts = ${uiJson};
+        opts.presets = [SwaggerUIBundle.presets.apis];
+        opts.plugins = [SwaggerUIBundle.plugins.DownloadUrl];
+        if (${navbarEnabled ? 'true' : 'false'} && typeof SwaggerUIStandalonePreset !== 'undefined') {
+          opts.presets.push(SwaggerUIStandalonePreset);
+          opts.layout = 'StandaloneLayout';
+        } else {
+          opts.layout = 'BaseLayout';
+        }
+        var ui = SwaggerUIBundle(opts);
+        var oauth = ${oauthJson};
+        if (oauth && typeof ui.initOAuth === 'function') {
+          ui.initOAuth(oauth);
+        }
+        window.ui = ui;
+      };
+    </script>
+  </body>
+</html>`
+}
+
+class FusionApp {
+  constructor(customSettings) {
+    if (customSettings) settings.merge(customSettings)
+    this.settings = getSettings()
+    this.engine = new NativeApp()
+    this.mounted = false
+    this._middleware = []
+  }
+
+  use(middleware) {
+    this._middleware.push(middleware)
+  }
+
+  mount() {
+    if (this.mounted) return
+    activeGlobalMiddleware = [...this._middleware]
+
+    for (const { path: routePath, ApiClass, middleware: routeMiddleware = [] } of registry) {
+      for (const methodName of HTTP_METHODS) {
+        if (!definesMethod(ApiClass, methodName)) continue
+        this.engine.route(methodName.toUpperCase(), routePath, async (request) => {
+          const chain = [...activeGlobalMiddleware, ...routeMiddleware]
+          const handler = async (req) => {
+            try {
+              const instance = new ApiClass(req)
+              const fn = instance[methodName]
+              return await Promise.resolve(fn.call(instance))
+            } catch (err) {
+              if (err instanceof HTTPException) return err.toResponse()
+              throw err
+            }
+          }
+          return runMiddlewareChain(request, chain, handler)
+        })
+      }
+    }
+
+    const swagger = readSwaggerSettings()
+    if (swagger.enabled) {
+      const prefix = swagger.path
+
+      const openapi = applySwaggerOpenApi(
+        {
+          openapi: '3.0.3',
+          info: { ...swagger.info },
+          paths: {},
+        },
+        swagger,
+      )
+
+      const parsePathParams = (pattern) => {
+        return String(pattern)
+          .split('/')
+          .filter((seg) => (seg.startsWith('{') && seg.endsWith('}')) || (seg.startsWith('[') && seg.endsWith(']')))
+          .map((seg) => seg.slice(1, -1))
+      }
+
+      for (const item of registry) {
+        const { path: p, ApiClass, swagger: routeSwagger } = item
+        const pathParams = parsePathParams(p)
+        const resolvedPath = p.startsWith('/') ? p : `/${p}`
+
+        if (!openapi.paths[resolvedPath]) openapi.paths[resolvedPath] = {}
+
+        for (const methodName of HTTP_METHODS) {
+          if (!definesMethod(ApiClass, methodName)) continue
+
+          const methodUpper = String(methodName).toUpperCase()
+          const methodLower = String(methodName).toLowerCase()
+
+          const params = pathParams.map((name) => ({
+            name,
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+          }))
+
+          openapi.paths[resolvedPath][methodLower] = {
+            tags: routeSwagger?.tags?.length ? routeSwagger.tags : [],
+            summary: routeSwagger?.title ?? `${ApiClass.name}.${methodUpper}`,
+            description: routeSwagger?.description ?? '',
+            deprecated: !!routeSwagger?.deprecated,
+            operationId: `${ApiClass.name}_${methodLower}`,
+            parameters: params,
+            responses: { '200': { description: 'OK' } },
+          }
+        }
+      }
+
+      this.engine.route('GET', `${prefix}/openapi.json`, async () => openapi)
+      this.engine.route('GET', prefix, async () => ({
+        status: 200,
+        body: swaggerUiHtml(swagger, `${prefix}/openapi.json`),
+        headers: { 'content-type': 'text/html' },
+      }))
+    }
+
+    this.mounted = true
+  }
+
+  async listen(host, port) {
+    this.mount()
+    const snapshot = getSettings()
+    const h = host ?? snapshot.host
+    const p = port ?? snapshot.port
+    if (snapshot.debug) {
+      console.log(`fusion listening on http://${h}:${p}`)
+    }
+    await this.engine.listen(h, Number(p))
+  }
+}
+
+async function run(options = {}) {
+  const settingsModulePath =
+    typeof options === 'string' ? options : options && options.settingsModule
+  const middleware = Array.isArray(options?.middleware) ? options.middleware : []
+
+  settings.ensureLoaded([process.cwd()])
+  if (settingsModulePath) {
+    const mod = await import(pathToFileUrl(settingsModulePath))
+    const overlay = {}
+    if (mod.HOST !== undefined) overlay.host = mod.HOST
+    if (mod.PORT !== undefined) overlay.port = mod.PORT
+    if (mod.DEBUG !== undefined) overlay.debug = mod.DEBUG
+    if (Object.keys(overlay).length) settings.merge(overlay)
+  }
+  const app = new FusionApp()
+  for (const mw of middleware) app.use(mw)
+  await app.listen()
+  return app
+}
+
+function coerceParam(raw, kind = 'auto') {
+  return native.coerceParamJs(String(raw), kind)
+}
+
+function pathToFileUrl(filePath) {
+  const resolved = path.resolve(filePath)
+  return require('url').pathToFileURL(resolved).href
+}
+
+const route = router
+
+module.exports = {
+  App: NativeApp,
+  Settings: NativeSettings,
+  FusionApp,
+  FusionBaseApi,
+  HTTPException,
+  router,
+  route,
+  apiResourceName,
+  resolveRoutePath,
+  configure,
+  getSettings,
+  settings,
+  status,
+  HTTP_METHODS,
+  run,
+  bearerJwt,
+  requireRoles,
+  runMiddlewareChain,
+  coerceParam,
+  getHttpMethods: () => HTTP_METHODS,
+  apiResourceNameJs: native.apiResourceNameJs,
+  resolveRoutePathJs: native.resolveRoutePathJs,
+  coerceParamJs: native.coerceParamJs,
+}

package/package.json

@@ -1,10 +1,78 @@
 {
   "name": "fusion-framework",
-  "version": "0.0.1",
-  "description": "Test package for npm trusted publishing",
+  "version": "1.1.2",
+  "description": "Build high-performance class-based HTTP APIs in Node.js on a shared Rust core — routing, middleware, JWT auth, and TypeScript types",
+  "keywords": [
+    "http",
+    "framework",
+    "nodejs",
+    "node",
+    "rust",
+    "napi",
+    "http-server",
+    "web-framework",
+    "rest-api",
+    "api",
+    "routing",
+    "middleware",
+    "jwt",
+    "typescript",
+    "openapi",
+    "swagger",
+    "hyper",
+    "fusion"
+  ],
+  "homepage": "https://fusion.cipherunit.xyz/",
+  "bugs": {
+    "url": "https://github.com/cipherunits/fusion-framework/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cipherunits/fusion-framework.git",
+    "directory": "crates/fusion-node"
+  },
+  "author": "CipherUnits <cipherunit.dev@gmail.com>",
   "license": "MIT",
+  "main": "index.js",
+  "types": "index.d.ts",
   "files": [
-    "index.js"
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "*.node"
   ],
-  "main": "index.js"
+  "napi": {
+    "name": "fusion-node",
+    "triples": {
+      "defaults": true,
+      "additional": [
+        "aarch64-unknown-linux-gnu",
+        "aarch64-apple-darwin"
+      ]
+    }
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "prepublishOnly": "napi prepublish -t npm --skip-gh-release"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4"
+  },
+  "optionalDependencies": {
+    "fusion-framework-win32-x64-msvc": "1.1.2",
+    "fusion-framework-darwin-x64": "1.1.2",
+    "fusion-framework-linux-x64-gnu": "1.1.2",
+    "fusion-framework-linux-arm64-gnu": "1.1.2",
+    "fusion-framework-darwin-arm64": "1.1.2"
+  }
 }