@porulle/core 0.1.0

package/src/interfaces/rest/routes/payments.ts

@@ -0,0 +1,60 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+import { processedWebhookEvents } from "../../../modules/webhooks/schema.js";
+
+type Db = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
+
+export function paymentRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.post("/webhook", async (c) => {
+    const result = await kernel.services.payments.verifyWebhook(c.req.raw);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+
+    const event = result.value;
+    const db = kernel.database.db as Db;
+
+    // Atomic idempotency: INSERT ... ON CONFLICT DO NOTHING ... RETURNING
+    // If the row already exists, RETURNING yields zero rows → duplicate.
+    // If the row is new, RETURNING yields one row → process the event.
+    // No TOCTOU race: the UNIQUE constraint on event_id is the single source of truth.
+    const [inserted] = await db
+      .insert(processedWebhookEvents)
+      .values({
+        eventId: event.id,
+        provider: "stripe",
+        eventType: event.type,
+      })
+      .onConflictDoNothing()
+      .returning({ id: processedWebhookEvents.id });
+
+    if (!inserted) {
+      // Row already existed — this is a duplicate delivery
+      return c.json({ data: { received: true, duplicate: true } });
+    }
+
+    // Process the event (first time only)
+    if (event.type === "payment_intent.succeeded") {
+      const data = event.data as Record<string, unknown> | undefined;
+      const metadata = data?.metadata as Record<string, unknown> | undefined;
+      if (typeof metadata?.orderId === "string") {
+        await kernel.services.orders.changeStatus(
+          {
+            orderId: metadata.orderId,
+            newStatus: "confirmed",
+            reason: "stripe_webhook_payment_intent_succeeded",
+          },
+          null,
+        );
+      }
+    }
+
+    return c.json({ data: { received: true } });
+  });
+
+  return router;
+}

package/src/interfaces/rest/routes/pricing.ts

@@ -0,0 +1,78 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { resolveOrgId } from "../../../auth/org.js";
+import { CommerceValidationError } from "../../../kernel/errors.js";
+import type { DrizzleDatabase } from "../../../kernel/database/drizzle-db.js";
+import { CatalogRepository } from "../../../modules/catalog/repository/index.js";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { setBasePriceRoute, createModifierRoute, listPricesRoute } from "../schemas/pricing.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+
+export function pricingRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/prices", requirePerm("pricing:manage"));
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (201 | 400 | 422). The route definition documents the
+  // contract; the handler returns dynamic status.
+  router.openapi(setBasePriceRoute, async (c) => {
+    const actor = c.get("actor");
+    const result = await kernel.services.pricing.setBasePrice(c.req.valid("json"), actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listPricesRoute, async (c) => {
+    const entityId = c.req.query("entityId");
+    const variantId = c.req.query("variantId");
+    const currency = c.req.query("currency");
+    const customerGroupId = c.req.query("customerGroupId");
+    const actor = c.get("actor");
+
+    const result = await kernel.services.pricing.listPrices({
+      ...(entityId !== undefined ? { entityId } : {}),
+      ...(variantId !== undefined ? { variantId } : {}),
+      ...(currency !== undefined ? { currency } : {}),
+      ...(customerGroupId !== undefined ? { customerGroupId } : {}),
+    }, actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
+
+  router.use("/modifiers", requirePerm("pricing:manage"));
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (201 | 400 | 422). The route definition documents the
+  // contract; the handler returns dynamic status.
+  router.openapi(createModifierRoute, async (c) => {
+    const actor = c.get("actor");
+    const input = c.req.valid("json");
+
+    if (input.entityId) {
+      const catalogRepo = new CatalogRepository(kernel.database.db as DrizzleDatabase);
+      const orgId = resolveOrgId(actor);
+      const entity = await catalogRepo.findEntityById(input.entityId);
+      if (!entity || entity.organizationId !== orgId) {
+        return c.json(
+          mapErrorToResponse(
+            new CommerceValidationError("entityId does not belong to this organization."),
+          ),
+          422,
+        );
+      }
+    }
+
+    const result = await kernel.services.pricing.createModifier(input, actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value }, 201);
+  });
+
+  return router;
+}

package/src/interfaces/rest/routes/promotions.ts

@@ -0,0 +1,96 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { rateLimiter } from "hono-rate-limiter";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { createPromotionRoute, validatePromotionRoute, deactivatePromotionRoute, listPromotionsRoute } from "../schemas/promotions.js";
+import type { PromotionStatusFilter } from "../../../modules/promotions/service.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+import { resolveOrgId } from "../../../auth/org.js";
+
+export function promotionRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  // Rate limit promo code validation — prevents brute-force code enumeration
+  router.use(
+    "/validate",
+    rateLimiter({
+      windowMs: 60 * 1000,
+      limit: 10,
+      keyGenerator: (c) => {
+        // Node.js Request has a socket property; Hono types it as unknown.
+        const socket = (c.req.raw as { socket?: { remoteAddress?: string } }).socket;
+        return socket?.remoteAddress ?? "unknown";
+      },
+    }),
+  );
+
+  router.use("/", requirePerm("promotions:manage"));
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (201 | 400 | 422). The route definition documents the
+  // contract; the handler returns dynamic status.
+  router.openapi(createPromotionRoute, async (c) => {
+    const body = c.req.valid("json");
+    const actor = c.get("actor");
+    const result = await kernel.services.promotions.create(body, actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value }, 201);
+  });
+
+  // List promotions — supports ?status= filter (active/inactive/expired/scheduled)
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listPromotionsRoute, async (c) => {
+    const actor = c.get("actor");
+    const status = c.req.query("status") as PromotionStatusFilter | undefined;
+    const result = await kernel.services.promotions.list(
+      status ? { status } : undefined,
+      actor,
+    );
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (200 | 400 | 404). The route definition documents the
+  // contract; the handler returns dynamic status.
+  router.openapi(validatePromotionRoute, async (c) => {
+    const payload = c.req.valid("json");
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+
+    const result = await kernel.services.promotions.validate(payload.code, {
+      orgId,
+      currency: payload.currency,
+      subtotal: payload.subtotal,
+      lineItems: payload.lineItems,
+      ...(payload.customerId !== undefined ? { customerId: payload.customerId } : {}),
+      ...(payload.customerGroupIds !== undefined ? { customerGroupIds: payload.customerGroupIds } : {}),
+    });
+
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+
+    return c.json({ data: result.value });
+  });
+
+  router.use("/:id/deactivate", requirePerm("promotions:manage"));
+
+  // @ts-expect-error -- openapi() enforces strict response typing but our handler
+  // returns union responses (200 | 400 | 404). The route definition documents the
+  // contract; the handler returns dynamic status.
+  router.openapi(deactivatePromotionRoute, async (c) => {
+    const actor = c.get("actor");
+    const orgId = resolveOrgId(actor);
+    const result = await kernel.services.promotions.deactivate(orgId, c.req.param("id"));
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value });
+  });
+
+  return router;
+}

package/src/interfaces/rest/routes/search.ts

@@ -0,0 +1,81 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { searchRoute, suggestRoute } from "../schemas/search.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
+
+export function searchRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(searchRoute, async (c) => {
+    try {
+      const q = c.req.query("q") ?? "";
+      const type = c.req.query("type");
+      const category = c.req.query("category");
+      const brand = c.req.query("brand");
+      const status = c.req.query("status");
+      const page = Number.parseInt(c.req.query("page") ?? "1", 10);
+      const limit = Number.parseInt(c.req.query("limit") ?? "20", 10);
+      const facets = (c.req.query("facets") ?? "")
+        .split(",")
+        .map((facet) => facet.trim())
+        .filter(Boolean);
+
+      const result = await kernel.services.search.query({
+        query: q,
+        page,
+        limit,
+        filters: {
+          ...(type ? { type } : {}),
+          ...(category ? { category } : {}),
+          ...(brand ? { brand } : {}),
+          ...(status ? { status } : {}),
+        },
+        ...(facets.length > 0 ? { facets } : {}),
+      }, { actor: c.get("actor"), tx: null, requestId: "" });
+
+      if (!result.ok) {
+        return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+      }
+
+      return c.json({
+        data: result.value.hits,
+        meta: {
+          total: result.value.total,
+          page: result.value.page,
+          limit: result.value.limit,
+          facets: result.value.facets,
+        },
+      });
+    } catch (error) {
+      console.error("[search] Route handler failed:", error instanceof Error ? error.message : error);
+      return c.json({ data: [], meta: { total: 0, page: 1, limit: 20, facets: {} } });
+    }
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(suggestRoute, async (c) => {
+    try {
+      const prefix = c.req.query("prefix") ?? "";
+      const type = c.req.query("type");
+      const limit = Number.parseInt(c.req.query("limit") ?? "10", 10);
+
+      const result = await kernel.services.search.suggest({
+        prefix,
+        ...(type ? { type } : {}),
+        limit,
+      }, { actor: c.get("actor"), tx: null, requestId: "" });
+
+      if (!result.ok) {
+        return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+      }
+
+      return c.json({ data: result.value });
+    } catch (error) {
+      console.error("[search] Suggest route failed:", error instanceof Error ? error.message : error);
+      return c.json({ data: [] });
+    }
+  });
+
+  return router;
+}

package/src/interfaces/rest/routes/webhooks.ts

@@ -0,0 +1,49 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../runtime/kernel.js";
+import { createWebhookEndpointRoute, listWebhookEndpointsRoute, deleteWebhookEndpointRoute } from "../schemas/webhooks.js";
+import { type AppEnv, mapErrorToResponse, mapErrorToStatus, requirePerm } from "../utils.js";
+
+export function webhookRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/*", requirePerm("webhooks:manage"));
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createWebhookEndpointRoute, async (c) => {
+    const body = c.req.valid("json") as Parameters<typeof kernel.services.webhooks.createEndpoint>[0];
+    // Generate a default secret if none provided (Zod schema marks it optional for API convenience)
+    if (!body.secret) {
+      body.secret = `whsec_${crypto.randomUUID().replace(/-/g, "")}`;
+    }
+    const actor = c.get("actor");
+    const result = await kernel.services.webhooks.createEndpoint(body, actor);
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: result.value }, 201);
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listWebhookEndpointsRoute, async (c) => {
+    const result = await kernel.services.webhooks.listEndpoints(c.get("actor"));
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    const sanitized = result.value.map(({ secret: _secret, ...rest }) => rest);
+    return c.json({ data: sanitized });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(deleteWebhookEndpointRoute, async (c) => {
+    const result = await kernel.services.webhooks.deleteEndpoint(
+      c.req.param("id"),
+      c.get("actor"),
+    );
+    if (!result.ok) {
+      return c.json(mapErrorToResponse(result.error), mapErrorToStatus(result.error));
+    }
+    return c.json({ data: { deleted: true } });
+  });
+
+  return router;
+}

package/src/interfaces/rest/schemas/admin-jobs.ts

@@ -0,0 +1,40 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { JobListResponse } from "./responses.js";
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const listFailedJobsRoute = createRoute({
+  method: "get",
+  path: "/jobs/failed",
+  tags: ["Admin Jobs"],
+  summary: "List failed jobs",
+  request: {
+    query: z.object({
+      limit: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: JobListResponse } },
+      description: "Failed jobs",
+    },
+  },
+});
+
+export const retryJobRoute = createRoute({
+  method: "post",
+  path: "/jobs/{id}/retry",
+  tags: ["Admin Jobs"],
+  summary: "Retry a failed job",
+  request: {
+    params: z.object({
+      id: z.string().min(1).openapi({ example: "job-uuid" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.object({ retried: z.literal(true) }) }) } },
+      description: "Job retried",
+    },
+  },
+});

package/src/interfaces/rest/schemas/admin-permissions.ts

@@ -0,0 +1,27 @@
+import { z, createRoute } from "@hono/zod-openapi";
+
+const PluginPermissionEntrySchema = z.object({
+  scope: z.string(),
+  description: z.string(),
+  plugin: z.string(),
+});
+
+export const listAdminPermissionsRoute = createRoute({
+  method: "get",
+  path: "/permissions",
+  tags: ["Admin"],
+  summary: "List core and plugin permission scopes",
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            core: z.array(z.string()),
+            plugin: z.array(PluginPermissionEntrySchema),
+          }),
+        },
+      },
+      description: "Role-derived core permissions and plugin-declared scopes",
+    },
+  },
+});

package/src/interfaces/rest/schemas/audit.ts

@@ -0,0 +1,46 @@
+import { z, createRoute } from "@hono/zod-openapi";
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const listAuditRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Audit"],
+  summary: "List audit entries",
+  request: {
+    query: z.object({
+      entityType: z.string().optional(),
+      entityId: z.string().optional(),
+      event: z.string().optional(),
+      actorId: z.string().optional(),
+      from: z.string().optional(),
+      to: z.string().optional(),
+      limit: z.string().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+      description: "Audit entries",
+    },
+  },
+});
+
+export const listEntityAuditRoute = createRoute({
+  method: "get",
+  path: "/{entityType}/{entityId}",
+  tags: ["Audit"],
+  summary: "List audit history for a specific entity",
+  request: {
+    params: z.object({
+      entityType: z.string().min(1).openapi({ example: "order" }),
+      entityId: z.string().min(1).openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: z.object({ data: z.array(z.record(z.string(), z.unknown())) }) } },
+      description: "Entity audit history",
+    },
+  },
+});

package/src/interfaces/rest/schemas/carts.ts

@@ -0,0 +1,125 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { ErrorSchema, errorResponses, UuidParamSchema, DeletedResponseSchema } from "./shared.js";
+import { CartResponse } from "./responses.js";
+import {
+  CreateCartBodySchema,
+  AddCartItemBodySchema,
+  UpdateCartItemQuantityBodySchema,
+} from "../../../modules/cart/schemas.js";
+
+export { CreateCartBodySchema, AddCartItemBodySchema, UpdateCartItemQuantityBodySchema };
+
+// ─── Response Schemas ───────────────────────────────────────────────────────
+
+export const CartResponseSchema = CartResponse;
+
+// ─── Path Params ────────────────────────────────────────────────────────────
+
+const CartIdParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+const CartItemParams = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+  itemId: z.uuid().openapi({ example: "660e8400-e29b-41d4-a716-446655440000" }),
+});
+
+// ─── Route Definitions ──────────────────────────────────────────────────────
+
+export const getCartRoute = createRoute({
+  method: "get",
+  path: "/{id}",
+  tags: ["Carts"],
+  summary: "Get a cart by ID",
+  request: { params: CartIdParam },
+  responses: {
+    200: {
+      content: { "application/json": { schema: CartResponseSchema } },
+      description: "Cart retrieved.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const removeCartItemRoute = createRoute({
+  method: "delete",
+  path: "/{id}/items/{itemId}",
+  tags: ["Carts"],
+  summary: "Remove an item from a cart",
+  request: { params: CartItemParams },
+  responses: {
+    200: {
+      content: { "application/json": { schema: DeletedResponseSchema } },
+      description: "Item removed.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const createCartRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Carts"],
+  summary: "Create a new cart",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: CreateCartBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: CartResponseSchema } },
+      description: "Cart created successfully.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const addCartItemRoute = createRoute({
+  method: "post",
+  path: "/{id}/items",
+  tags: ["Carts"],
+  summary: "Add an item to a cart",
+  request: {
+    params: CartIdParam,
+    body: {
+      content: {
+        "application/json": { schema: AddCartItemBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: CartResponseSchema } },
+      description: "Item added to cart.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const updateCartItemQuantityRoute = createRoute({
+  method: "patch",
+  path: "/{id}/items/{itemId}",
+  tags: ["Carts"],
+  summary: "Update the quantity of a cart line item",
+  request: {
+    params: CartItemParams,
+    body: {
+      content: {
+        "application/json": { schema: UpdateCartItemQuantityBodySchema },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: CartResponseSchema } },
+      description: "Cart item quantity updated.",
+    },
+    ...errorResponses,
+  },
+});