@porulle/core 0.1.0 → 0.5.0

package/src/modules/inventory/service.ts

@@ -310,40 +310,87 @@ export class InventoryService {
     });
   }
 
-  async adjust(
+  /**
+   * Adjust inventory with optional add/remove/set modes, returning before /
+   * after / delta and the movement id. `mode` omitted ⇒ signed-delta (legacy)
+   * behavior using `adjustment`. `remove` clamps at 0; `set` writes an absolute
+   * value. The lock, compute, write, and movement all happen in one transaction
+   * so concurrent adjustments can't lose updates.
+   */
+  async adjustDetailed(
     input: InventoryAdjustInput,
     actor?: Actor | null,
     ctx?: TxContext,
-  ): Promise<Result<InventoryLevel>> {
+  ): Promise<
+    Result<{
+      level: InventoryLevel;
+      before: number;
+      after: number;
+      delta: number;
+      movementId: string;
+    }>
+  > {
     try {
       assertPermission(actor ?? null, "inventory:adjust");
     } catch (error) {
       return Err(toCommerceError(error));
     }
 
+    // Cross-field validation: mode form needs `amount`; legacy form needs `adjustment`.
+    if (input.mode) {
+      if (input.amount === undefined) {
+        return Err(new CommerceValidationError("`amount` is required when `mode` is set."));
+      }
+    } else if (input.adjustment === undefined) {
+      return Err(new CommerceValidationError("`adjustment` is required when `mode` is omitted."));
+    }
+
     const warehouseId = input.warehouseId ?? (await this.pickWarehouse(actor, ctx));
     const variantId = input.variantId ?? null;
     const performedBy = input.performedBy ?? actor?.userId ?? "system";
 
-    const doAdjust = async (txCtx: TxContext): Promise<Result<InventoryLevel>> => {
-      const orgId = resolveOrgId(
-        actor ?? txCtx.actor ?? null,
-        undefined,
-        this.deps.config,
-      );
-      // Row-locked read + atomic SQL increment prevents lost updates
-      const lockResult = await this.repo.adjustWithLock(
+    const doAdjust = async (txCtx: TxContext) => {
+      const orgId = resolveOrgId(actor ?? txCtx.actor ?? null, undefined, this.deps.config);
+
+      // Lock the level first so `before` and the write are atomic.
+      const existing = await this.repo.findLevelForUpdate(
         orgId,
         input.entityId,
         variantId,
         warehouseId,
-        input.adjustment,
         txCtx,
       );
+      const before = existing?.quantityOnHand ?? 0;
+
+      const amount = input.amount ?? 0;
+      let effectiveAdjustment: number;
+      switch (input.mode) {
+        case "add":
+          effectiveAdjustment = amount;
+          break;
+        case "remove":
+          effectiveAdjustment = -amount;
+          break;
+        case "set":
+          effectiveAdjustment = amount - before;
+          break;
+        default:
+          effectiveAdjustment = input.adjustment ?? 0;
+          break;
+      }
 
       let level: InventoryLevel;
-      if (lockResult.ok) {
-        level = lockResult.level;
+      if (existing) {
+        // Row-locked atomic SQL increment (GREATEST(0, qoh + delta)).
+        const lockResult = await this.repo.adjustWithLock(
+          orgId,
+          input.entityId,
+          variantId,
+          warehouseId,
+          effectiveAdjustment,
+          txCtx,
+        );
+        level = lockResult.ok ? lockResult.level : existing;
       } else {
         // No existing level — create is safe; unique index on
         // (entityId, variantId, warehouseId) prevents duplicate inserts.
@@ -352,35 +399,30 @@ export class InventoryService {
             organizationId: orgId,
             entityId: input.entityId,
             warehouseId,
-            quantityOnHand: Math.max(0, input.adjustment),
+            quantityOnHand: Math.max(0, effectiveAdjustment),
             quantityReserved: 0,
             quantityIncoming: 0,
-            ...(input.variantId !== undefined
-              ? { variantId: input.variantId }
-              : {}),
+            ...(input.variantId !== undefined ? { variantId: input.variantId } : {}),
           },
           txCtx,
         );
       }
 
-      await this.repo.createMovement(
+      const after = level.quantityOnHand;
+      const delta = after - before;
+
+      const movement = await this.repo.createMovement(
         {
           organizationId: orgId,
           entityId: input.entityId,
           warehouseId,
           type: "adjustment",
-          quantity: input.adjustment,
+          quantity: delta,
           reason: input.reason,
           performedBy,
-          ...(input.variantId !== undefined
-            ? { variantId: input.variantId }
-            : {}),
-          ...(input.referenceType !== undefined
-            ? { referenceType: input.referenceType }
-            : {}),
-          ...(input.referenceId !== undefined
-            ? { referenceId: input.referenceId }
-            : {}),
+          ...(input.variantId !== undefined ? { variantId: input.variantId } : {}),
+          ...(input.referenceType !== undefined ? { referenceType: input.referenceType } : {}),
+          ...(input.referenceId !== undefined ? { referenceId: input.referenceId } : {}),
         },
         txCtx,
       );
@@ -403,7 +445,7 @@ export class InventoryService {
         hookCtx,
       );
 
-      return Ok(level);
+      return Ok({ level, before, after, delta, movementId: movement.id });
     };
 
     return this.withTransaction(ctx, async (tx) => {
@@ -412,6 +454,19 @@ export class InventoryService {
     });
   }
 
+  /**
+   * Back-compat wrapper: adjust inventory and return just the level. Existing
+   * callers and the signed-delta `adjustment` form are unchanged.
+   */
+  async adjust(
+    input: InventoryAdjustInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<InventoryLevel>> {
+    const result = await this.adjustDetailed(input, actor, ctx);
+    return result.ok ? Ok(result.value.level) : result;
+  }
+
   /**
    * Set inventory to an absolute quantity (not a delta).
    *

package/src/modules/media/noop-adapter.ts

@@ -0,0 +1,36 @@
+import type { CommerceError } from "../../kernel/errors.js";
+import { Ok, Err, type Result } from "../../kernel/result.js";
+import type { StorageAdapter } from "./adapter.js";
+
+const notSupported = (op: string): Result<never, CommerceError> =>
+  Err({
+    code: "STORAGE_NOT_SUPPORTED",
+    message: `storage.${op} is disabled — no storage adapter is configured.`,
+  });
+
+/**
+ * The default `StorageAdapter` used when `defineConfig` is given no `storage`.
+ *
+ * Lets a catalog-only deployment boot with zero storage config: read-only
+ * `getUrl` passes the key through (so catalog projections keep working), while
+ * the mutating media operations return a typed `STORAGE_NOT_SUPPORTED` error.
+ * Configure a real adapter (local/S3/R2) to enable media.
+ */
+export const noopStorageAdapter: StorageAdapter = {
+  providerId: "noop",
+  async upload() {
+    return notSupported("upload");
+  },
+  async getUrl(key) {
+    return Ok(key);
+  },
+  async getSignedUrl() {
+    return notSupported("getSignedUrl");
+  },
+  async delete() {
+    return Ok(undefined);
+  },
+  async list() {
+    return Ok([]);
+  },
+};

package/src/modules/orders/repository/index.ts

@@ -1,10 +1,23 @@
-import { eq, and, desc, sql } from "drizzle-orm";
+import { eq, and, or, gte, lte, desc, sql } from "drizzle-orm";
 import type { TxContext } from "../../../kernel/database/tx-context.js";
 import type {
   DrizzleDatabase,
   DbOrTx,
 } from "../../../kernel/database/drizzle-db.js";
 import { orders, orderLineItems, orderStatusHistory } from "../schema.js";
+import { customers } from "../../customers/schema.js";
+
+export interface OrderLookupRow {
+  id: string;
+  orderNumber: string;
+  placedAt: Date;
+  status: string;
+  grandTotal: number;
+  customerId: string | null;
+  firstName: string | null;
+  lastName: string | null;
+  phone: string | null;
+}
 
 // Infer types from Drizzle schema
 export type Order = typeof orders.$inferSelect;
@@ -66,6 +79,55 @@ export class OrdersRepository {
       .orderBy(desc(orders.placedAt));
   }
 
+  /**
+   * Fuzzy lookup across order number, customer email/name/phone, and the
+   * walk-in label. Phone matches ignore non-digits on both sides. Org-scoped.
+   */
+  async lookup(
+    orgId: string,
+    q: string,
+    opts: { from?: Date; to?: Date },
+    ctx?: TxContext,
+  ): Promise<OrderLookupRow[]> {
+    const db = this.getDb(ctx);
+    const like = `%${q}%`;
+    const qDigits = q.replace(/\D/g, "");
+
+    const matchers = [
+      sql`${orders.orderNumber} ILIKE ${like}`,
+      sql`${customers.email} ILIKE ${like}`,
+      sql`(coalesce(${customers.firstName}, '') || ' ' || coalesce(${customers.lastName}, '')) ILIKE ${like}`,
+      sql`(${orders.metadata} ->> 'customerLabel') ILIKE ${like}`,
+    ];
+    if (qDigits.length >= 3) {
+      matchers.push(
+        sql`regexp_replace(coalesce(${customers.phone}, ''), '[^0-9]', '', 'g') ILIKE ${`%${qDigits}%`}`,
+      );
+    }
+
+    const filters = [eq(orders.organizationId, orgId), or(...matchers)];
+    if (opts.from) filters.push(gte(orders.placedAt, opts.from));
+    if (opts.to) filters.push(lte(orders.placedAt, opts.to));
+
+    return db
+      .select({
+        id: orders.id,
+        orderNumber: orders.orderNumber,
+        placedAt: orders.placedAt,
+        status: orders.status,
+        grandTotal: orders.grandTotal,
+        customerId: customers.id,
+        firstName: customers.firstName,
+        lastName: customers.lastName,
+        phone: customers.phone,
+      })
+      .from(orders)
+      .leftJoin(customers, eq(orders.customerId, customers.id))
+      .where(and(...filters))
+      .orderBy(desc(orders.placedAt))
+      .limit(50) as Promise<OrderLookupRow[]>;
+  }
+
   async findByStatus(orgId: string, status: string, ctx?: TxContext): Promise<Order[]> {
     const db = this.getDb(ctx);
     return db

package/src/modules/orders/service.ts

@@ -64,6 +64,14 @@ export interface ListOrdersParams {
   page?: number;
   limit?: number;
   status?: string;
+  /** When true, listByCustomer also returns a lifetime-spend rollup. */
+  includeTotals?: boolean;
+}
+
+export interface CustomerOrderTotals {
+  count: number;
+  lifetimeSpend: number;
+  averageBasket: number;
 }
 
 export interface ChangeStatusInput {
@@ -82,7 +90,11 @@ export interface OrderServiceDeps {
 }
 
 export type HydratedOrder = Order & { lineItems: OrderLineItem[] };
-type OrderListResult = { items: HydratedOrder[]; pagination: Pagination };
+type OrderListResult = {
+  items: HydratedOrder[];
+  pagination: Pagination;
+  totals?: CustomerOrderTotals;
+};
 type BeforeCreateOrderHook = BeforeHook<CreateOrderInput>;
 type AfterCreateOrderHook = AfterHook<HydratedOrder>;
 type StatusChangeHookInput = {
@@ -324,6 +336,23 @@ export class OrderService {
     }
 
     items.sort((a, b) => b.placedAt.getTime() - a.placedAt.getTime());
+
+    // Lifetime rollup over the full (un-paginated) set, computed server-side.
+    // Refunds/voids are excluded from lifetimeSpend.
+    let totals: CustomerOrderTotals | undefined;
+    if (params.includeTotals) {
+      const excluded = new Set(["refunded", "voided"]);
+      const count = items.length;
+      const lifetimeSpend = items
+        .filter((order) => !excluded.has(order.status))
+        .reduce((sum, order) => sum + order.grandTotal, 0);
+      totals = {
+        count,
+        lifetimeSpend,
+        averageBasket: count > 0 ? Math.round(lifetimeSpend / count) : 0,
+      };
+    }
+
     const paged = paginate(items, params.page ?? 1, params.limit ?? 20);
     const hydratedItems = await Promise.all(
       paged.items.map((order) => this.hydrateOrder(order, ctx)),
@@ -332,9 +361,63 @@ export class OrderService {
     return Ok({
       items: hydratedItems,
       pagination: paged.pagination,
+      ...(totals ? { totals } : {}),
     });
   }
 
+  /**
+   * Fuzzy order lookup for receipt-less returns / support: matches across
+   * order number, customer email/name/phone (digits-normalized), and the
+   * walk-in label. Returns a compact result; <3 chars returns a hint.
+   */
+  async lookup(
+    q: string,
+    opts: { from?: Date; to?: Date },
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<
+    Result<{
+      items: Array<{
+        id: string;
+        orderNumber: string;
+        placedAt: Date;
+        status: string;
+        grandTotal: number;
+        customer: { id: string; name: string | null; phone: string | null } | null;
+      }>;
+      hint?: string;
+    }>
+  > {
+    try {
+      assertPermission(actor ?? null, "orders:read");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+
+    const term = (q ?? "").trim();
+    if (term.length < 3) {
+      return Ok({ items: [], hint: "Enter at least 3 characters to search." });
+    }
+
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const rows = await this.repo.lookup(orgId, term, opts, ctx);
+    const items = rows.map((r) => ({
+      id: r.id,
+      orderNumber: r.orderNumber,
+      placedAt: r.placedAt,
+      status: r.status,
+      grandTotal: r.grandTotal,
+      customer: r.customerId
+        ? {
+            id: r.customerId,
+            name: `${r.firstName ?? ""} ${r.lastName ?? ""}`.trim() || null,
+            phone: r.phone ?? null,
+          }
+        : null,
+    }));
+    return Ok({ items });
+  }
+
   async changeStatus(
     input: ChangeStatusInput,
     actor: Actor | null,
@@ -556,8 +639,8 @@ export class OrderService {
       ctx,
     );
 
-    // Audit logging is now automatic via audit hooks (RFC-005)
-    // registered in kernel boot — no manual audit.record() needed.
+    // Audit logging is automatic via the audit hooks registered at kernel
+    // boot — no manual audit.record() call needed here.
 
     const hydrated = await this.hydrateOrder(cas, ctx);
     const report = await runAfterHooks(

package/src/modules/payments/repository/index.ts

@@ -1,6 +1,5 @@
 import type { TxContext } from "../../../kernel/database/tx-context.js";
 
 export interface PaymentsRepository {
-  // RFC-002 scaffold: module repositories become the only persistence boundary.
   ping(ctx: TxContext): Promise<void>;
 }

package/src/modules/promotions/schemas.ts

@@ -2,16 +2,29 @@ import { z } from "@hono/zod-openapi";
 
 // ─── Zod Body Schemas (single source of truth) ─────────────────────────────
 
-export const CreatePromotionBodySchema = z.object({
-  name: z.string().openapi({ example: "Summer Sale" }),
-  type: z.enum([
+/**
+ * The valid promotion `type` values. Single source of truth for the REST
+ * body schema, the OpenAPI enum, the service-layer validation, and the
+ * exported {@link PromotionType} union.
+ */
+export const promotionTypeEnum = z
+  .enum([
     "percentage_off_order",
     "fixed_off_order",
     "percentage_off_item",
     "fixed_off_item",
     "free_shipping",
     "buy_x_get_y",
-  ]).openapi({ example: "percentage_off_order" }),
+  ])
+  .openapi("PromotionType", { example: "percentage_off_order" });
+
+/** Valid promotion type discriminator. @see promotionTypeEnum */
+export type PromotionType = z.infer<typeof promotionTypeEnum>;
+
+export const CreatePromotionBodySchema = z.object({
+  name: z.string().openapi({ example: "Summer Sale" }),
+  /** @see PromotionType for valid values */
+  type: promotionTypeEnum,
   value: z.number().openapi({ example: 10 }),
   code: z.string().optional().openapi({ example: "SUMMER10" }),
   buyQuantity: z.number().int().optional(),
@@ -33,6 +46,10 @@ export const CreatePromotionBodySchema = z.object({
   metadata: z.record(z.string(), z.unknown()).optional(),
 }).openapi("CreatePromotionRequest");
 
+// Edit any subset of the create body. Validated the same way create is.
+export const UpdatePromotionBodySchema = CreatePromotionBodySchema.partial();
+
 // ─── Derived Input Types ────────────────────────────────────────────────────
 
 export type CreatePromotionInput = z.infer<typeof CreatePromotionBodySchema>;
+export type UpdatePromotionInput = z.infer<typeof UpdatePromotionBodySchema>;

package/src/modules/promotions/service.ts

@@ -15,20 +15,17 @@ import type {
   PromotionsRepository,
   Promotion,
   PromotionUsage,
+  PromotionInsert,
 } from "./repository/index.js";
 import type { CatalogRepository } from "../catalog/repository/index.js";
 import type { OrdersRepository } from "../orders/repository/index.js";
 import { resolveOrgId } from "../../auth/org.js";
 import type { Actor } from "../../auth/types.js";
 
-// Re-export PromotionType for external use
-export type PromotionType =
-  | "percentage_off_order"
-  | "fixed_off_order"
-  | "percentage_off_item"
-  | "fixed_off_item"
-  | "free_shipping"
-  | "buy_x_get_y";
+// PromotionType is derived from the zod enum (single source of truth) in
+// ./schemas.js; re-export it here for backwards-compatible imports.
+import { promotionTypeEnum, type PromotionType } from "./schemas.js";
+export type { PromotionType };
 
 /** Filter status for listing promotions. Used by the REST API and service layer. */
 export type PromotionStatusFilter = "active" | "inactive" | "expired" | "scheduled";
@@ -88,7 +85,7 @@ export interface PromotionConditions {
 }
 
 export type { CreatePromotionInput } from "./schemas.js";
-import type { CreatePromotionInput } from "./schemas.js";
+import type { CreatePromotionInput, UpdatePromotionInput } from "./schemas.js";
 
 export interface AppliedPromotion {
   promotionId: string;
@@ -182,15 +179,8 @@ export class PromotionService {
       );
     }
 
-    // Validate promotion type
-    const validTypes: PromotionType[] = [
-      "percentage_off_order",
-      "fixed_off_order",
-      "percentage_off_item",
-      "fixed_off_item",
-      "free_shipping",
-      "buy_x_get_y",
-    ];
+    // Validate promotion type against the single-source enum
+    const validTypes = promotionTypeEnum.options;
     if (!validTypes.includes(input.type)) {
       return Err(
         new CommerceValidationError(
@@ -269,6 +259,88 @@ export class PromotionService {
     return Ok(updated);
   }
 
+  /**
+   * Edit any subset of a promotion's fields. Validated the same way create is
+   * (value bounds, type enum, code uniqueness). Only provided keys are written.
+   */
+  async update(
+    orgId: string,
+    id: string,
+    input: UpdatePromotionInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Promotion>> {
+    const existing = await this.repo.findById(orgId, id, ctx);
+    if (!existing) {
+      return Err(new CommerceNotFoundError("Promotion not found."));
+    }
+
+    if (input.value !== undefined && input.value < 0) {
+      return Err(new CommerceValidationError("Promotion value cannot be negative."));
+    }
+
+    if (input.type !== undefined) {
+      const validTypes = promotionTypeEnum.options;
+      if (!validTypes.includes(input.type)) {
+        return Err(
+          new CommerceValidationError(
+            `Invalid promotion type "${input.type}". Must be one of: ${validTypes.join(", ")}`,
+          ),
+        );
+      }
+    }
+
+    let normalizedCode: string | null | undefined;
+    if (input.code !== undefined) {
+      normalizedCode = input.code ? input.code.trim().toUpperCase() : null;
+      if (normalizedCode) {
+        const other = await this.repo.findByCode(orgId, normalizedCode, ctx);
+        if (other && other.id !== id) {
+          return Err(
+            new CommerceValidationError(`Promotion code ${normalizedCode} already exists.`),
+          );
+        }
+      }
+    }
+
+    const patch: Partial<Omit<PromotionInsert, "id">> = {};
+    if (input.name !== undefined) patch.name = input.name;
+    if (input.type !== undefined) patch.type = input.type;
+    if (input.value !== undefined) patch.value = roundMoney(input.value);
+    if (input.isAutomatic !== undefined) patch.isAutomatic = input.isAutomatic;
+    if (input.isActive !== undefined) patch.isActive = input.isActive;
+    if (input.priority !== undefined) patch.priority = input.priority;
+    if (input.conditions !== undefined) patch.conditions = input.conditions as Record<string, unknown>;
+    if (input.metadata !== undefined) patch.metadata = input.metadata;
+    if (normalizedCode !== undefined) patch.code = normalizedCode;
+    if (input.buyQuantity !== undefined) patch.buyQuantity = input.buyQuantity;
+    if (input.getQuantity !== undefined) patch.getQuantity = input.getQuantity;
+    if (input.usageLimitTotal !== undefined) patch.usageLimitTotal = input.usageLimitTotal;
+    if (input.usageLimitPerCustomer !== undefined) {
+      patch.usageLimitPerCustomer = input.usageLimitPerCustomer;
+    }
+    if (input.validFrom !== undefined) patch.validFrom = input.validFrom;
+    if (input.validUntil !== undefined) patch.validUntil = input.validUntil;
+
+    const updated = await this.repo.update(id, patch, ctx);
+    if (!updated) {
+      return Err(new CommerceNotFoundError("Promotion not found."));
+    }
+
+    const afterHooks = this.deps.hooks.resolve(
+      "promotions.afterUpdate",
+    ) as AfterHook<Promotion>[];
+    const hctx = hookContext(
+      actor ?? ctx?.actor ?? null,
+      this.deps.services,
+      this.deps.database,
+      ctx?.tx ?? null,
+    );
+    await runAfterHooks(afterHooks, existing, updated, "update", hctx);
+
+    return Ok(updated);
+  }
+
   async list(
     filter?: { status?: PromotionStatusFilter },
     actor?: Actor | null,

package/src/modules/search/repository/index.ts

@@ -1,6 +1,5 @@
 import type { TxContext } from "../../../kernel/database/tx-context.js";
 
 export interface SearchRepository {
-  // RFC-002 scaffold: module repositories become the only persistence boundary.
   ping(ctx: TxContext): Promise<void>;
 }

package/src/modules/shipping/repository/index.ts

@@ -1,6 +1,5 @@
 import type { TxContext } from "../../../kernel/database/tx-context.js";
 
 export interface ShippingRepository {
-  // RFC-002 scaffold: module repositories become the only persistence boundary.
   ping(ctx: TxContext): Promise<void>;
 }

package/src/modules/tax/repository/index.ts

@@ -1,6 +1,5 @@
 import type { TxContext } from "../../../kernel/database/tx-context.js";
 
 export interface TaxRepository {
-  // RFC-002 scaffold: module repositories become the only persistence boundary.
   ping(ctx: TxContext): Promise<void>;
 }

package/src/runtime/client-ip.ts

@@ -0,0 +1,49 @@
+/**
+ * Client-IP resolution for rate limiting.
+ *
+ * The Node default reads `c.req.raw.socket.remoteAddress` — which is always
+ * undefined on edge runtimes (Cloudflare Workers, Deno Deploy, Vercel Edge),
+ * collapsing every client onto a single rate-limit key (a trivial DoS). Edge
+ * deployments inject `runtime.getClientIp` to read the platform header instead
+ * (CF: `cf-connecting-ip`, Vercel Edge: `x-real-ip`, Fly: `fly-client-ip`).
+ */
+
+export interface ClientIpContext {
+  req: { raw: unknown; header(name: string): string | undefined };
+}
+
+export type ClientIpResolver = (c: ClientIpContext) => string;
+
+export interface RuntimeConfig {
+  /** Resolve the client IP from the request (used as the rate-limit key). */
+  getClientIp?: ClientIpResolver;
+  /** Direct-connection IP of the trusted reverse proxy (Node default only). */
+  trustedProxyIp?: string;
+}
+
+/**
+ * Build the client-IP resolver. Prefers an injected `runtime.getClientIp`;
+ * otherwise falls back to the Node behavior (socket address, trusting
+ * X-Forwarded-For only from `trustedProxyIp` / `TRUSTED_PROXY_IP`).
+ */
+export function createClientIpResolver(config: {
+  runtime?: RuntimeConfig;
+}): ClientIpResolver {
+  if (config.runtime?.getClientIp) {
+    return config.runtime.getClientIp;
+  }
+
+  const trustedProxyIp =
+    config.runtime?.trustedProxyIp ??
+    (typeof process !== "undefined" ? process.env?.TRUSTED_PROXY_IP : undefined);
+
+  return (c: ClientIpContext): string => {
+    const raw = c.req.raw as { socket?: { remoteAddress?: string } } | undefined;
+    const remoteAddress = raw?.socket?.remoteAddress;
+    if (trustedProxyIp && remoteAddress === trustedProxyIp) {
+      const xff = c.req.header("x-forwarded-for")?.split(",")[0]?.trim();
+      if (xff) return xff;
+    }
+    return remoteAddress ?? "unknown";
+  };
+}