hono-utils 0.3.0 → 0.3.2

package/dist/index.d.cts

@@ -4,7 +4,7 @@ import { Logger, Details } from 'hierarchical-area-logger';
 import * as hono_utils_http_status from 'hono/utils/http-status';
 import { ContentfulStatusCode, SuccessStatusCode, ClientErrorStatusCode, StatusCode } from 'hono/utils/http-status';
 import z$1, { z, ZodObject } from 'zod';
-import { Message, MessageBatch, Queue } from '@cloudflare/workers-types';
+import { Message, MessageBatch, Queue, Iso3166Alpha2Code, ContinentCode } from '@cloudflare/workers-types';
 import * as hono_utils_types from 'hono/utils/types';
 import { hc, ClientResponse } from 'hono/client';
 
@@ -304,6 +304,110 @@ declare const response: hono.MiddlewareHandler<{
     Variables: HonoResponseVariables & HonoLoggerVariables;
 }, string, {}, Response>;
 
+type CFData = {
+    isEUCountry: boolean;
+    latitude: string;
+    longitude: string;
+    city: string;
+    country: Iso3166Alpha2Code | 'T1';
+    continent: ContinentCode;
+    region?: string;
+    regionCode?: string;
+    postalCode: string;
+    timezone: string;
+    colo: string;
+    asn?: number;
+};
+type UserAgentData = {
+    browser: {
+        name: string;
+        version: string;
+    };
+    device: {
+        model: string;
+        vendor: string;
+        type: UAParser.IDevice['type'] | 'desktop';
+    };
+    engine: {
+        name: string;
+        version: string;
+    };
+    os: {
+        name: string;
+        version: string;
+    };
+    cpu: string;
+};
+type HonoClientInfoVariables = {
+    client: CFData & {
+        ip: string;
+        userAgent: string;
+        securityHash: string;
+    } & UserAgentData;
+};
+/**
+ * Hono middleware that extracts and injects comprehensive client information
+ * into the request context, including geolocation data from Cloudflare and
+ * parsed User-Agent details.
+ * @param {Object} [config] - Optional configuration for the middleware.
+ * @param {Function} [config.securityHashString] - A custom function to generate the seed string
+ * used for the security hash. Receives Cloudflare and User-Agent data as input.
+ * Defaults to `${city}${country}${continent}`.
+ * @param {string} [config.hashSecretBinding] - The name of the environment variable
+ * containing the hash secret. Defaults to 'HASH_SECRET'.
+ * @returns {MiddlewareHandler} A Hono middleware handler.
+ * @throws {Error} Throws an error if Cloudflare (`req.raw.cf`) data is missing.
+ * @example
+ * ```ts
+ * const app = new Hono<{ Variables: HonoClientInfoVariables }>();
+ *
+ * app.use('*', clientInfo());
+ *
+ * app.get('/me', (c) => {
+ *  const client = c.get('client');
+ *  return c.json({
+ *    location: `${client.city}, ${client.country}`,
+ *    device: client.device.type
+ *  });
+ * });
+ * ```
+ */
+declare const clientInfo: (config?: {
+    hashSecretBinding?: string;
+    securityHashString?: (content: CFData & UserAgentData & {
+        ip: string;
+    }) => string;
+}) => hono.MiddlewareHandler<{
+    Bindings: Record<string, string>;
+    Variables: HonoClientInfoVariables;
+}, string, {}, Response>;
+
+/**
+ * A Hono middleware factory that hydrates a context variable based on environment bindings or other variables.
+ * @template {Record<string, unknown>} Bindings - The environment bindings (e.g., Cloudflare Env).
+ * @template {Record<string, unknown>} Variables - The Hono context variables.
+ * @template HidratedResult - The resulting type of the hydrated variable.
+ * @param {Object} options - The configuration options for hydration.
+ * @param {keyof Variables} options.variableName - The name of the variable in the context to be set.
+ * @param {(c: Bindings & { get: <T>(key: keyof Variables) => T }) => HidratedResult} options.hydrate -
+ * A function that takes the environment and a getter, returning the hydrated value.
+ * @returns {import("hono").MiddlewareHandler} A Hono middleware that performs the hydration and calls next().
+ * @example
+ * const middleware = hydrateVariable({
+ *   variableName: 'userProfile',
+ *   hydrate: (c) => new UserProfile(c.USER_ID)
+ * });
+ */
+declare const hydrateVariable: <Bindings extends Record<string, unknown>, Variables extends Record<string, unknown>, HidratedResult>({ variableName, hydrate, }: {
+    variableName: keyof Variables;
+    hydrate: (c: Bindings & {
+        get: <T>(key: keyof Variables) => T;
+    }) => HidratedResult;
+}) => hono.MiddlewareHandler<{
+    Bindings: Bindings;
+    Variables: Record<string, HidratedResult>;
+}, string, {}, Response>;
+
 /**
  * Derives a secure hex-encoded hash from an input string using PBKDF2-HMAC-SHA256.
  * * @example
@@ -375,4 +479,4 @@ interface CreateTypedClientOptions {
 }
 declare const createTypedClient: <TApp extends Hono<any, any, any>>(options: CreateTypedClientOptions) => <TSuccessData>(fn: (c: ReturnType<typeof hc<TApp>>) => Promise<ClientResponse<TSuccessData>>) => Promise<TSuccessData>;
 
-export { type ContextFn, type CreateTypedClientOptions, type HonoI18nVariables, type HonoIsBotVariables, type HonoLanguageVariables, type HonoLoggerVariables, type HonoResponseVariables, type MessageHandlers, pbkdf2 as PBKDF2, QueueHandler, sha as SHA, type WrappableMiddleware, createTypedClient, i18n, isBot, jsonValidator, logger, onError, onNotFound, queue, response, withLogger };
+export { type ContextFn, type CreateTypedClientOptions, type HonoClientInfoVariables, type HonoI18nVariables, type HonoIsBotVariables, type HonoLanguageVariables, type HonoLoggerVariables, type HonoResponseVariables, type MessageHandlers, pbkdf2 as PBKDF2, QueueHandler, sha as SHA, type WrappableMiddleware, clientInfo, createTypedClient, hydrateVariable, i18n, isBot, jsonValidator, logger, onError, onNotFound, queue, response, withLogger };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { Logger, Details } from 'hierarchical-area-logger';
 import * as hono_utils_http_status from 'hono/utils/http-status';
 import { ContentfulStatusCode, SuccessStatusCode, ClientErrorStatusCode, StatusCode } from 'hono/utils/http-status';
 import z$1, { z, ZodObject } from 'zod';
-import { Message, MessageBatch, Queue } from '@cloudflare/workers-types';
+import { Message, MessageBatch, Queue, Iso3166Alpha2Code, ContinentCode } from '@cloudflare/workers-types';
 import * as hono_utils_types from 'hono/utils/types';
 import { hc, ClientResponse } from 'hono/client';
 
@@ -304,6 +304,110 @@ declare const response: hono.MiddlewareHandler<{
     Variables: HonoResponseVariables & HonoLoggerVariables;
 }, string, {}, Response>;
 
+type CFData = {
+    isEUCountry: boolean;
+    latitude: string;
+    longitude: string;
+    city: string;
+    country: Iso3166Alpha2Code | 'T1';
+    continent: ContinentCode;
+    region?: string;
+    regionCode?: string;
+    postalCode: string;
+    timezone: string;
+    colo: string;
+    asn?: number;
+};
+type UserAgentData = {
+    browser: {
+        name: string;
+        version: string;
+    };
+    device: {
+        model: string;
+        vendor: string;
+        type: UAParser.IDevice['type'] | 'desktop';
+    };
+    engine: {
+        name: string;
+        version: string;
+    };
+    os: {
+        name: string;
+        version: string;
+    };
+    cpu: string;
+};
+type HonoClientInfoVariables = {
+    client: CFData & {
+        ip: string;
+        userAgent: string;
+        securityHash: string;
+    } & UserAgentData;
+};
+/**
+ * Hono middleware that extracts and injects comprehensive client information
+ * into the request context, including geolocation data from Cloudflare and
+ * parsed User-Agent details.
+ * @param {Object} [config] - Optional configuration for the middleware.
+ * @param {Function} [config.securityHashString] - A custom function to generate the seed string
+ * used for the security hash. Receives Cloudflare and User-Agent data as input.
+ * Defaults to `${city}${country}${continent}`.
+ * @param {string} [config.hashSecretBinding] - The name of the environment variable
+ * containing the hash secret. Defaults to 'HASH_SECRET'.
+ * @returns {MiddlewareHandler} A Hono middleware handler.
+ * @throws {Error} Throws an error if Cloudflare (`req.raw.cf`) data is missing.
+ * @example
+ * ```ts
+ * const app = new Hono<{ Variables: HonoClientInfoVariables }>();
+ *
+ * app.use('*', clientInfo());
+ *
+ * app.get('/me', (c) => {
+ *  const client = c.get('client');
+ *  return c.json({
+ *    location: `${client.city}, ${client.country}`,
+ *    device: client.device.type
+ *  });
+ * });
+ * ```
+ */
+declare const clientInfo: (config?: {
+    hashSecretBinding?: string;
+    securityHashString?: (content: CFData & UserAgentData & {
+        ip: string;
+    }) => string;
+}) => hono.MiddlewareHandler<{
+    Bindings: Record<string, string>;
+    Variables: HonoClientInfoVariables;
+}, string, {}, Response>;
+
+/**
+ * A Hono middleware factory that hydrates a context variable based on environment bindings or other variables.
+ * @template {Record<string, unknown>} Bindings - The environment bindings (e.g., Cloudflare Env).
+ * @template {Record<string, unknown>} Variables - The Hono context variables.
+ * @template HidratedResult - The resulting type of the hydrated variable.
+ * @param {Object} options - The configuration options for hydration.
+ * @param {keyof Variables} options.variableName - The name of the variable in the context to be set.
+ * @param {(c: Bindings & { get: <T>(key: keyof Variables) => T }) => HidratedResult} options.hydrate -
+ * A function that takes the environment and a getter, returning the hydrated value.
+ * @returns {import("hono").MiddlewareHandler} A Hono middleware that performs the hydration and calls next().
+ * @example
+ * const middleware = hydrateVariable({
+ *   variableName: 'userProfile',
+ *   hydrate: (c) => new UserProfile(c.USER_ID)
+ * });
+ */
+declare const hydrateVariable: <Bindings extends Record<string, unknown>, Variables extends Record<string, unknown>, HidratedResult>({ variableName, hydrate, }: {
+    variableName: keyof Variables;
+    hydrate: (c: Bindings & {
+        get: <T>(key: keyof Variables) => T;
+    }) => HidratedResult;
+}) => hono.MiddlewareHandler<{
+    Bindings: Bindings;
+    Variables: Record<string, HidratedResult>;
+}, string, {}, Response>;
+
 /**
  * Derives a secure hex-encoded hash from an input string using PBKDF2-HMAC-SHA256.
  * * @example
@@ -375,4 +479,4 @@ interface CreateTypedClientOptions {
 }
 declare const createTypedClient: <TApp extends Hono<any, any, any>>(options: CreateTypedClientOptions) => <TSuccessData>(fn: (c: ReturnType<typeof hc<TApp>>) => Promise<ClientResponse<TSuccessData>>) => Promise<TSuccessData>;
 
-export { type ContextFn, type CreateTypedClientOptions, type HonoI18nVariables, type HonoIsBotVariables, type HonoLanguageVariables, type HonoLoggerVariables, type HonoResponseVariables, type MessageHandlers, pbkdf2 as PBKDF2, QueueHandler, sha as SHA, type WrappableMiddleware, createTypedClient, i18n, isBot, jsonValidator, logger, onError, onNotFound, queue, response, withLogger };
+export { type ContextFn, type CreateTypedClientOptions, type HonoClientInfoVariables, type HonoI18nVariables, type HonoIsBotVariables, type HonoLanguageVariables, type HonoLoggerVariables, type HonoResponseVariables, type MessageHandlers, pbkdf2 as PBKDF2, QueueHandler, sha as SHA, type WrappableMiddleware, clientInfo, createTypedClient, hydrateVariable, i18n, isBot, jsonValidator, logger, onError, onNotFound, queue, response, withLogger };

package/dist/index.js

@@ -13957,6 +13957,10 @@ var response = createMiddleware6(async (c, next) => {
   await next();
 });
 
+// src/middleware/clientInfo.ts
+import { createMiddleware as createMiddleware7 } from "hono/factory";
+import { UAParser } from "ua-parser-js";
+
 // src/crypto/pbkdf2.ts
 var pbkdf2_exports = {};
 __export(pbkdf2_exports, {
@@ -14038,6 +14042,91 @@ async function hash3({
   return hashedString;
 }
 
+// src/middleware/clientInfo.ts
+var clientInfo = (config2) => createMiddleware7(async ({ env, req, set: set2 }, next) => {
+  if (!req.raw.cf) {
+    throw new Error("Cloudflare data is not available");
+  }
+  const hashSecret = env[config2?.hashSecretBinding ?? "HASH_SECRET"];
+  if (!hashSecret) {
+    throw new Error("Hash secret is not available");
+  }
+  const {
+    latitude,
+    longitude,
+    city,
+    country,
+    continent,
+    colo,
+    asn,
+    isEUCountry,
+    region,
+    regionCode,
+    postalCode,
+    timezone
+  } = req.raw.cf;
+  const cf = {
+    latitude,
+    longitude,
+    city,
+    country,
+    continent,
+    colo,
+    asn,
+    isEUCountry: Boolean(isEUCountry),
+    region,
+    regionCode,
+    postalCode,
+    timezone
+  };
+  const userAgent = req.raw.headers.get("user-agent") ?? "Unknown";
+  const parser = new UAParser(userAgent);
+  const userAgentParsed = parser.getResult();
+  const { browser, device, engine, os, cpu } = userAgentParsed;
+  const ua = {
+    browser: {
+      name: browser.name ?? "Unknown",
+      version: browser.version ?? "Unknown"
+    },
+    device: {
+      model: device.model ?? "Unknown",
+      vendor: device.vendor ?? "Unknown",
+      type: device.type ?? "desktop"
+    },
+    engine: {
+      name: engine.name ?? "Unknown",
+      version: engine.version ?? "Unknown"
+    },
+    os: {
+      name: os.name ?? "Unknown",
+      version: os.version ?? "Unknown"
+    },
+    cpu: cpu.architecture ?? "Unknown"
+  };
+  const ip = req.raw.headers.get("CF-Connecting-IP") ?? "127.0.0.1";
+  const clientContent = { ...cf, ...ua, ip };
+  set2("client", {
+    ...clientContent,
+    userAgent,
+    securityHash: await sha_exports.hash({
+      input: config2?.securityHashString?.(clientContent) ?? `${ip}${city}${country}${userAgent}`,
+      algorithm: "SHA-512",
+      pepper: hashSecret
+    })
+  });
+  next();
+});
+
+// src/middleware/hydrateVariable.ts
+import { createMiddleware as createMiddleware8 } from "hono/factory";
+var hydrateVariable = ({
+  variableName,
+  hydrate
+}) => createMiddleware8(async ({ set: set2, env, get }, next) => {
+  set2(variableName, hydrate({ ...env, get }));
+  await next();
+});
+
 // src/queue/QueueHandler.ts
 import { init } from "@paralleldrive/cuid2";
 var QueueHandler = class {
@@ -14190,7 +14279,9 @@ export {
   pbkdf2_exports as PBKDF2,
   QueueHandler,
   sha_exports as SHA,
+  clientInfo,
   createTypedClient,
+  hydrateVariable,
   i18n,
   isBot,
   jsonValidator,