xpref 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xpref",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "",
   "main": "index.js",
   "repository": {

package/request-forwarder/forwarder.d.ts

@@ -1,2 +1,2 @@
 import type { RequestForwarder, Response, Request, NextFunction } from '../types';
-export default function requestFowarder(props: RequestForwarder): (req: Request, res: Response, next: NextFunction) => import("node:http").ClientRequest;
+export default function requestFowarder(props: RequestForwarder): (req: Request, res: Response, next: NextFunction) => import("http").ClientRequest;

package/request-forwarder/pass-to-next.d.ts

@@ -1,4 +1,7 @@
 import type { ProxyResult, Request, Response } from '../types';
 import type { IncomingMessage } from 'http';
+type ProxyBody = string | Buffer | Record<string, unknown>;
+export declare const parseProxyBody: (body: Buffer, headers: IncomingMessage['headers']) => ProxyBody;
 export declare const applyProxyResultToRequest: (req: Request, res: Response, result: ProxyResult) => void;
 export declare const collectProxyResult: (proxyResponse: IncomingMessage) => Promise<ProxyResult>;
+export {};

package/request-forwarder/pass-to-next.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.collectProxyResult = exports.applyProxyResultToRequest = void 0;
+exports.collectProxyResult = exports.applyProxyResultToRequest = exports.parseProxyBody = void 0;
 const normalizeProxyHeaders = (headers) => (Object.entries(headers).reduce((acc, [key, value]) => {
     if (value === undefined)
         return acc;
@@ -22,9 +22,10 @@ const parseProxyBody = (body, headers) => {
         return body.toString('utf8');
     }
 };
+exports.parseProxyBody = parseProxyBody;
 const applyProxyResultToRequest = (req, res, result) => {
     const upstreamHeaders = normalizeProxyHeaders(result.headers);
-    req.body = parseProxyBody(result.body, result.headers);
+    req.body = (0, exports.parseProxyBody)(result.body, result.headers);
     req.headers = { ...req.headers, ...upstreamHeaders };
     res.statusCode = result.statusCode;
     Object.entries(upstreamHeaders).forEach(([key, value]) => {

package/request-forwarder/proxy.d.ts

@@ -5,4 +5,4 @@
  * with it's prototol (http or https).
  */
 import type { Request, Response, RequestForwarder } from '../types';
-export default function requestFowarder(props: RequestForwarder): (req: Request, res: Response) => import("node:http").ClientRequest;
+export default function requestFowarder(props: RequestForwarder): (req: Request, res: Response) => import("http").ClientRequest;

package/seo/index.d.ts

@@ -0,0 +1,2 @@
+export { default as seoMiddleware } from './seo.middleware';
+export type { SeoProps } from './type';

package/seo/index.js

@@ -0,0 +1,8 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seoMiddleware = void 0;
+var seo_middleware_1 = require("./seo.middleware");
+Object.defineProperty(exports, "seoMiddleware", { enumerable: true, get: function () { return __importDefault(seo_middleware_1).default; } });

package/seo/seo.middleware.d.ts

@@ -0,0 +1,9 @@
+import type { Request, Response, NextFunction } from '../types';
+import type { SeoProps } from './type';
+type SeoProxyProps = {
+    siteName: string;
+    templatePath?: string;
+};
+type CallbackData = (data: any, req?: Request) => SeoProps | Promise<SeoProps>;
+export default function prepareTemplate(props: SeoProxyProps, onData: CallbackData): (req: Request, res: Response, next: NextFunction) => void | Promise<void | Response<any, Record<string, any>>> | Response<any, Record<string, any>>;
+export {};

package/seo/seo.middleware.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = prepareTemplate;
+const path_1 = __importDefault(require("path"));
+const readResPayload = (req) => {
+    const payload = req.body;
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new Error('Invalid Application Request');
+    }
+    return payload;
+};
+const isValidCrawler = (req) => {
+    const strBool = String(req.headers['is-certified-crawler'] || '');
+    return strBool.trim() === 'true';
+};
+const getTemplatePath = (props) => {
+    const templatePath = props.templatePath || '';
+    if (templatePath !== '')
+        return templatePath;
+    return path_1.default.join(__dirname, 'seo.template.ejs');
+};
+const getSeoProps = (req, dataHandler) => {
+    const data = readResPayload(req);
+    if (!(data || false))
+        throw new Error('Invalid Response.');
+    const result = dataHandler(data, req);
+    if (result instanceof Promise)
+        return result.then((value) => value);
+    return Promise.resolve(result);
+};
+function prepareTemplate(props, onData) {
+    return (req, res, next) => {
+        var _a;
+        if (req.method === 'OPTIONS')
+            return next();
+        if (req.method !== 'GET')
+            return next();
+        if (!isValidCrawler(req))
+            return next();
+        const statusCode = Number(res.statusCode || 200);
+        if (statusCode >= 400) {
+            const message = ((_a = req.body) === null || _a === void 0 ? void 0 : _a.message)
+                || 'Something goes wrong.';
+            return res.status(statusCode).json({ message });
+        }
+        return getSeoProps(req, onData)
+            .then((payload) => {
+            const templatePath = getTemplatePath(props);
+            res.removeHeader('content-type');
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            return res.status(200).render(templatePath, {
+                title: payload.title,
+                description: payload.description,
+                canonicalUrl: payload.canonicalUrl,
+                mediaType: payload.mediaType,
+                imageUrl: payload.imageUrl,
+                siteName: props.siteName,
+                redirectUrlJson: JSON.stringify(payload.canonicalUrl),
+            });
+        })
+            .catch((error) => {
+            const { message } = error;
+            return res.status(400).json({ message });
+        });
+    };
+}

package/seo/type.d.ts

@@ -0,0 +1,12 @@
+type OpenGrapType = 'website' | 'article' | 'product' | 'profile' | 'music.song' | 'music.album' | 'music.playlist' | 'music.radio_station' | 'video.movie' | 'video.episode' | 'video.tv_show' | 'video.other';
+export type MovieSubTag = 'video.actor:role' | 'video:director' | 'video:writer' | 'video:duration' | 'video:release_date' | 'video:tag';
+export type MusicSubTag = 'music:duration' | 'music:album' | 'music:album:disc' | 'music:album:track' | 'music:musician';
+export type SeoProps = {
+    siteName: string;
+    title: string;
+    description: string | null;
+    imageUrl: string;
+    canonicalUrl: string;
+    mediaType?: OpenGrapType;
+};
+export {};

package/seo/type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/README.md

@@ -1,442 +0,0 @@
-# xpref
-
-Express.js application bootstrap for APIs — nested routing, request validation, OpenAPI docs, idempotency, proxying, and i18n.
-
-## Features
-
-### Core server
-- Express 5 app bootstrap with a single `xpref()` call
-- Automatic port fallback when the configured port is in use
-- Manual start control via `manuallyStart`
-- `onInit` hook (runs before built-in middleware)
-- `interceptor` hook (runs after built-in middleware, before routes)
-- Startup banner with app name, environment, and port
-- TypeScript-first types and exports
-
-### Security & request pipeline
-- Helmet security headers
-- CORS enabled
-- Trust proxy enabled
-- JSON body parsing (8MB limit)
-- URL-encoded body parsing
-- Unique request ID (`Request-Id` / `request-id`) on every request and response
-- `getRequestId()` helper to read the current request ID
-
-### Routing
-- Declarative nested route trees (parent path + children)
-- Per-route middleware arrays
-- HTTP methods: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`
-- Handler as a function, array of functions, or `{ action, params, description }`
-- Static file serving via `staticRoutes`
-
-### Request validation (AJV)
-- Shared schemas via the top-level `schemas` option
-- Per-method validation for `query`, `path` (`params`), and `body`
-- Type coercion, `$data`, and `ajv-errors` support
-- Human-readable field error messages (400 responses)
-
-### Request logging
-- Morgan console access logs (app name, env, request ID, method, status, URL, timing, user-agent)
-- Optional external logger integration (e.g. `@core/log-client`)
-- Structured log payload: request ID, IP, country, language, device ID, origin, referer, and base64 body for non-GET
-
-### OpenAPI / Swagger (`xpref/api-docs`)
-- OpenAPI 3.0 document generation from routes and schemas
-- Swagger UI middleware (`swagger-ui-express`)
-- Tags and external docs metadata
-- Bearer (JWT) and API key security schemes
-
-### Idempotency (`xpref/idempotency`)
-- POST-only idempotency via `idempotency-key` header (UUID v4)
-- Optional enforcement per route
-- Configurable TTL (default 5 minutes)
-- In-progress (`202`), cached success replay, and expired (`410`) responses
-- Optional `validateResponse` callback for custom success rules
-- JSON and `x-www-form-urlencoded` bodies
-
-### Request forwarder / proxy (`xpref/request-forwarder`)
-- `forwarder` — proxy HTTP/HTTPS upstream with body forwarding
-- `proxy` — stream pipe to upstream
-- Custom host, `proxyPrefix`, `withPrefix`, extra headers
-- `onUrlConstructed` URL rewrite hook
-- `passToNext` — collect upstream result and continue the middleware chain
-
-### Internationalization (`xpref/i18n`)
-- Locale JSON files loaded at init
-- `translate(key, replace?, lang?)` with `{placeholder}` substitution
-- Fallback language support (`fallbackLang`, `fallbackLangOnly`)
-
-## Usage
-
-### Basic server setup
-
-```typescript
-import xpref from 'xpref';
-
-xpref({
-  appName: 'my-app',
-  appEnv: 'development',
-  port: 3000,
-  routes: {
-    '/api/users': [
-      'users',
-      [],
-      {
-        get: (req, res) => {
-          res.json({ users: [] });
-        },
-      },
-      {},
-    ],
-  },
-}).then(({ port, app }) => {
-  console.log(`Server running on port ${port}`);
-});
-```
-
-### Nested routes and middleware
-
-```typescript
-xpref({
-  appName: 'my-app',
-  appEnv: 'development',
-  port: 3000,
-  interceptor: (app) => {
-    app.use((req, res, next) => {
-      console.log('Custom middleware');
-      next();
-    });
-  },
-  routes: {
-    '/api/users': [
-      'users',
-      [],
-      {
-        get: (req, res) => res.json({ users: [] }),
-        post: (req, res) => res.json({ message: 'User created' }),
-      },
-      {
-        '/:id': [
-          'user-by-id',
-          [authMiddleware],
-          {
-            get: (req, res) => res.json({ id: req.params.id }),
-            put: (req, res) => res.json({ message: 'Updated' }),
-            delete: (req, res) => res.json({ message: 'Deleted' }),
-          },
-        ],
-      },
-    ],
-  },
-});
-```
-
-### Request validation
-
-```typescript
-xpref({
-  appName: 'my-app',
-  appEnv: 'development',
-  port: 3000,
-  schemas: {
-    email: { type: 'string', format: 'email' },
-    name: { type: 'string', minLength: 1 },
-  },
-  routes: {
-    '/api/users': [
-      'users',
-      [],
-      {
-        post: {
-          description: 'Create a user',
-          params: {
-            body: {
-              type: 'object',
-              properties: ['email', 'name'],
-              required: ['email', 'name'],
-            },
-          },
-          action: (req, res) => {
-            res.json({ message: 'User created', ...req.body });
-          },
-        },
-      },
-    ],
-  },
-});
-```
-
-### With request logging
-
-```typescript
-import xpref from 'xpref';
-import { createLogger } from '@core/log-client';
-
-const logger = createLogger({
-  appName: 'my-app',
-  appEnv: 'development',
-});
-
-xpref({
-  appName: 'my-app',
-  appEnv: 'development',
-  port: 3000,
-  logger,
-  routes: {
-    '/api/logs': [
-      'logs',
-      [],
-      {
-        get: (req, res) => res.json({ logs: [] }),
-      },
-    ],
-  },
-});
-```
-
-### Static files
-
-```typescript
-xpref({
-  appName: 'my-app',
-  appEnv: 'development',
-  port: 3000,
-  staticRoutes: {
-    '/public': './public',
-    '/uploads': './uploads',
-  },
-  routes: {
-    '/api/files': [
-      'files',
-      [],
-      {
-        get: (req, res) => res.json({ files: [] }),
-      },
-    ],
-  },
-});
-```
-
-### Manual start
-
-```typescript
-xpref({
-  appName: 'my-app',
-  appEnv: 'development',
-  port: 3000,
-  manuallyStart: ({ app, port }) =>
-    new Promise((resolve) => {
-      const server = app.listen(port, () => {
-        resolve({ port, app, server });
-      });
-    }),
-  routes: {
-    '/api/health': [
-      'health',
-      [],
-      {
-        get: (req, res) => res.json({ status: 'ok' }),
-      },
-    ],
-  },
-});
-```
-
-### Idempotency
-
-```typescript
-import type { Route } from 'xpref';
-import idempotency from 'xpref/idempotency';
-
-const routes = {
-  '/wallets': [
-    'wallets',
-    [],
-    {},
-    {
-      '/transfer': [
-        'transfer',
-        [idempotency({ enforced: true, ttl: 300 })],
-        {
-          post: walletTransferAction,
-        },
-      ],
-    },
-  ],
-} as Route;
-```
-
-Clients send `idempotency-key: <uuid-v4>` on POST. Retry on `5xx`, `422`, `429`, and similar failures with exponential backoff.
-
-### Request forwarder / proxy
-
-```typescript
-import { forwarder, proxy } from 'xpref/request-forwarder';
-
-// As middleware: forward and respond from upstream
-app.use('/upstream', forwarder({
-  host: 'https://api.example.com',
-  proxyPrefix: '/v1',
-  headers: { 'x-api-key': 'secret' },
-}));
-
-// Collect upstream result and continue the chain
-app.use('/gateway', forwarder({
-  host: 'https://api.example.com',
-  passToNext: true,
-}), (req, res) => {
-  // Upstream status/headers/body available via applyProxyResultToRequest
-  res.json({ ok: true });
-});
-
-// Stream pipe proxy
-app.use('/proxy', proxy({
-  host: 'https://api.example.com',
-  withPrefix: true,
-  onUrlConstructed: (url) => url.replace(/\/+$/, ''),
-}));
-```
-
-### i18n
-
-```typescript
-import { i18n } from 'xpref';
-
-const t = i18n({
-  locale: {
-    en: './locales/en.json',
-    km: './locales/km.json',
-  },
-  fallbackLang: 'en',
-});
-
-t('welcome.message', { name: 'Ada' }, 'en');
-```
-
-### OpenAPI / Swagger UI
-
-```typescript
-import setupApiDocs from 'xpref/api-docs';
-
-const [serve, setup] = setupApiDocs(
-  {
-    info: {
-      title: 'My API',
-      version: '1.0.0',
-      description: 'API documentation',
-    },
-    bearerAuth: true,
-    apiKeys: ['x-api-key'],
-    tags: {
-      users: { description: 'User endpoints' },
-    },
-  },
-  { routes, schemas },
-);
-
-app.use('/docs', serve, setup);
-```
-
-## API reference
-
-### `xpref(props: Xpref): Promise<{ port: number; app: Application }>`
-
-| Option | Type | Description |
-| --- | --- | --- |
-| `appName` | `string` | Application name |
-| `appEnv` | `string` | Environment (e.g. `development`, `production`) |
-| `port` | `number` | Listen port (default `3000`; auto-increments if in use) |
-| `routes` | `Route` | Nested route configuration |
-| `schemas` | `Record<string, any>` | Shared AJV schemas for method validation |
-| `staticRoutes` | `Record<string, string>` | URL path → filesystem path |
-| `logger` | `any` | Optional logger factory used by request logging |
-| `onInit` | `(app) => void` | Hook before built-in middleware |
-| `interceptor` | `(app) => void` | Hook after built-in middleware |
-| `manuallyStart` | `({ app, port }) => Promise` | Skip auto-listen; start the server yourself |
-
-### Route configuration
-
-```typescript
-type MethodOptions =
-  | CallableFunction
-  | CallableFunction[]
-  | {
-      action: CallableFunction | CallableFunction[];
-      params?: { query?: any; path?: any; body?: any };
-      description?: string | [string, string];
-    };
-
-type PathDetail = [
-  string, // route name
-  any[], // middleware
-  MethodHandler, // get/post/put/delete/patch
-  Record<string, PathDetail>?, // children
-];
-
-type Route = Record<string, PathDetail>;
-```
-
-### Exports
-
-| Export | From | Description |
-| --- | --- | --- |
-| default `xpref` | `xpref` | Create and start the app |
-| `getRequestId` | `xpref` | Read request ID from a request |
-| `i18n` | `xpref` | Initialize translations |
-| Express types / `urlencoded` | `xpref` | Re-exported for convenience |
-| `idempotency` | `xpref/idempotency` | Idempotency middleware |
-| `setupApiDocs` | `xpref/api-docs` | OpenAPI + Swagger UI |
-| `forwarder`, `proxy` | `xpref/request-forwarder` | Upstream proxy helpers |
-
-## Example project structure
-
-```
-src/
-  ├── routes/
-  │   ├── users.ts
-  │   └── auth.ts
-  ├── middleware/
-  │   └── auth.ts
-  ├── locales/
-  │   └── en.json
-  ├── static/
-  │   └── public/
-  └── index.ts
-```
-
-```typescript
-// src/index.ts
-import xpref from 'xpref';
-import { createLogger } from '@core/log-client';
-import userRoutes from './routes/users';
-import authRoutes from './routes/auth';
-import authMiddleware from './middleware/auth';
-
-const logger = createLogger({
-  appName: 'my-api',
-  appEnv: process.env.NODE_ENV || 'development',
-});
-
-xpref({
-  appName: 'my-api',
-  appEnv: process.env.NODE_ENV || 'development',
-  port: 3000,
-  staticRoutes: {
-    '/public': './static/public',
-  },
-  interceptor: (app) => {
-    app.use('/api/protected', authMiddleware);
-  },
-  logger,
-  routes: {
-    ...userRoutes,
-    ...authRoutes,
-  },
-}).then(({ port }) => {
-  console.log(`Server running on port ${port}`);
-});
-```
-
-## License
-
-ISC