@porulle/core 0.10.6 → 0.11.0

package/src/interfaces/rest/routes/admin/entity-field-definitions.ts

@@ -0,0 +1,89 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Kernel } from "../../../../runtime/kernel.js";
+import type {
+  CreateEntityFieldDefinitionInput,
+  UpdateEntityFieldDefinitionInput,
+} from "../../../../modules/catalog/service.js";
+import {
+  archiveEntityFieldDefinitionRoute,
+  createEntityFieldDefinitionRoute,
+  listEntityFieldDefinitionsRoute,
+  updateEntityFieldDefinitionRoute,
+} from "../../schemas/admin-entity-field-definitions.js";
+import {
+  type AppEnv,
+  mapErrorToResponse,
+  mapErrorToStatus,
+  requirePerm,
+} from "../../utils.js";
+
+export function adminEntityFieldDefinitionRoutes(kernel: Kernel) {
+  const router = new OpenAPIHono<AppEnv>();
+
+  router.use("/entity-field-definitions", requirePerm("catalog:update"));
+  router.use("/entity-field-definitions/:id", requirePerm("catalog:update"));
+  router.use(
+    "/entity-field-definitions/:id/archive",
+    requirePerm("catalog:update"),
+  );
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(createEntityFieldDefinitionRoute, async (c) => {
+    const result = await kernel.services.catalog.createEntityFieldDefinition(
+      c.req.valid("json") as CreateEntityFieldDefinitionInput,
+      c.get("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(listEntityFieldDefinitionsRoute, async (c) => {
+    const entityType = c.req.query("entityType");
+    const result = await kernel.services.catalog.listEntityFieldDefinitions(
+      c.get("actor"),
+      entityType,
+    );
+    if (!result.ok)
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(updateEntityFieldDefinitionRoute, async (c) => {
+    const result = await kernel.services.catalog.updateEntityFieldDefinition(
+      c.req.param("id"),
+      c.req.valid("json") as UpdateEntityFieldDefinitionInput,
+      c.get("actor"),
+    );
+    if (!result.ok)
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(archiveEntityFieldDefinitionRoute, async (c) => {
+    const result = await kernel.services.catalog.archiveEntityFieldDefinition(
+      c.req.param("id"),
+      c.get("actor"),
+    );
+    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/catalog.ts

@@ -19,6 +19,8 @@ import {
   listEntitiesRoute,
   getEntityRoute,
   getEntityAttributesRoute,
+  listFieldOwnershipRoute,
+  setFieldOwnershipRoute,
   listCategoriesRoute,
   listBrandsRoute,
   deleteEntityRoute,
@@ -34,6 +36,8 @@ import {
   createEntityRoute,
   updateEntityRoute,
   setEntityAttributesRoute,
+  approveCustomFieldRoute,
+  rejectCustomFieldRoute,
   createCategoryRoute,
   archiveCategoryRoute,
   restoreCategoryRoute,
@@ -54,11 +58,58 @@ import {
   parseInclude,
   parsePagination,
   parseSort,
+  requirePerm,
 } from "../utils.js";
 
 export function catalogRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
+  router.use("/entities/:id/custom-fields/:fieldName/approve", requirePerm("catalog:update"));
+  router.use("/entities/:id/custom-fields/:fieldName/reject", requirePerm("catalog:update"));
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(listFieldOwnershipRoute, async (c) => {
+    const result = await kernel.services.catalog.listFieldOwnership(
+      c.req.param("id"),
+      c.get("actor"),
+      undefined,
+      c.req.query("storeId"),
+    );
+    if (!result.ok) {
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    }
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(setFieldOwnershipRoute, async (c) => {
+    const body = c.req.valid("json") as {
+      fieldPath: string;
+      owner: "platform" | "store" | "shared";
+      storeId?: string | null;
+      variantId?: string | null;
+    };
+    const result = await kernel.services.catalog.setFieldOwner(
+      c.req.param("id"),
+      body.fieldPath,
+      body.storeId ?? null,
+      body.owner,
+      c.get("actor"),
+      undefined,
+      body.variantId ?? null,
+    );
+    if (!result.ok) {
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    }
+    return c.json({ data: { updated: true } });
+  });
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(listEntitiesRoute, async (c) => {
     try {
@@ -101,6 +152,7 @@ export function catalogRoutes(kernel: Kernel) {
           includeMedia: include.has("media"),
           includeInventory: include.has("inventory"),
           includePricing: include.has("pricing"),
+          includeCustomFields: include.has("customFields"),
         };
         const hydrated = await Promise.all(
           result.value.items.map(async (item) => {
@@ -143,6 +195,7 @@ export function catalogRoutes(kernel: Kernel) {
         includeMedia: include.has("media"),
         includeInventory: include.has("inventory"),
         includePricing: include.has("pricing"),
+        includeCustomFields: include.has("customFields"),
       };
 
       const actor = c.get("actor");
@@ -268,6 +321,38 @@ export function catalogRoutes(kernel: Kernel) {
     return c.json({ data: { updated: true } });
   });
 
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(approveCustomFieldRoute, async (c) => {
+    const result = await kernel.services.catalog.approveCustomField(
+      c.req.param("id"),
+      c.req.param("fieldName"),
+      c.req.query("locale") ?? "en",
+      c.get("actor"),
+    );
+    if (!result.ok)
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    return c.json({ data: result.value });
+  });
+
+  // @ts-expect-error -- openapi handler union return type
+  router.openapi(rejectCustomFieldRoute, async (c) => {
+    const result = await kernel.services.catalog.rejectCustomField(
+      c.req.param("id"),
+      c.req.param("fieldName"),
+      c.req.query("locale") ?? "en",
+      c.get("actor"),
+    );
+    if (!result.ok)
+      return c.json(
+        mapErrorToResponse(result.error),
+        mapErrorToStatus(result.error),
+      );
+    return c.json({ data: result.value });
+  });
+
   // @ts-expect-error -- openapi handler union return type
   router.openapi(getEntityAttributesRoute, async (c) => {
     const result = await kernel.services.catalog.getAttributes(

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

@@ -22,7 +22,8 @@ import type { PluginDb } from "../../../kernel/database/plugin-types.js";
 import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
 import { isCommerceError } from "../../../kernel/errors.js";
 import { assertPermission } from "../../../auth/permissions.js";
-import { makeId } from "../../../utils/id.js";
+import { resolveOrgId } from "../../../auth/org.js";
+import { makeDeterministicId, makeId } from "../../../utils/id.js";
 import type { ShippingAddress } from "../../../modules/shipping/calculator.js";
 import type { Actor } from "../../../auth/types.js";
 
@@ -126,8 +127,12 @@ export function checkoutRoutes(kernel: Kernel) {
       }
     }
 
+    const orderId = body.idempotencyKey
+      ? await makeDeterministicId(`checkout:${resolveOrgId(actor)}:${body.idempotencyKey}`)
+      : makeId();
     const checkoutData: CheckoutData = {
       checkoutId: makeId(),
+      orderId,
       cartId: body.cartId,
       currency: body.currency ?? "USD",
       paymentMethodId: body.paymentMethodId,
@@ -235,6 +240,7 @@ export function checkoutRoutes(kernel: Kernel) {
       );
 
       const orderPayload = {
+        id: processed.orderId ?? orderId,
         ...(body.idempotencyKey !== undefined
           ? { idempotencyKey: body.idempotencyKey }
           : {}),

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

@@ -3,6 +3,8 @@ 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";
+import type { Actor } from "../../../auth/types.js";
+import { toCommerceError } from "../../../kernel/errors.js";
 
 type Db = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
 
@@ -16,44 +18,62 @@ export function paymentRoutes(kernel: Kernel) {
     }
 
     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 } });
-    }
+    const outcome = await kernel.database.transaction(async (transaction) => {
+      const db = transaction as Db;
+
+      // Claim and process in one transaction. If reconciliation throws, the
+      // claim rolls back so Stripe can safely retry instead of receiving a
+      // false 2xx for an event that never changed commerce state.
+      const [inserted] = await db
+        .insert(processedWebhookEvents)
+        .values({
+          eventId: event.id,
+          provider: "stripe",
+          eventType: event.type,
+        })
+        .onConflictDoNothing()
+        .returning({ id: processedWebhookEvents.id });
+
+      if (!inserted) return { 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,
-        );
+      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") {
+          const actor: Actor = {
+            type: "api_key",
+            userId: "stripe-webhook",
+            email: null,
+            name: "Stripe webhook",
+            vendorId: null,
+            organizationId:
+              typeof metadata.organizationId === "string"
+                ? metadata.organizationId
+                : null,
+            role: "system",
+            permissions: ["orders:update"],
+          };
+          const changed = await kernel.services.orders.changeStatus(
+            {
+              orderId: metadata.orderId,
+              newStatus: "confirmed",
+              reason: "stripe_webhook_payment_intent_succeeded",
+            },
+            actor,
+            {
+              tx: transaction,
+              actor,
+              requestId: c.get("requestId"),
+            },
+          );
+          if (!changed.ok) throw toCommerceError(changed.error);
+        }
       }
-    }
 
-    return c.json({ data: { received: true } });
+      return { duplicate: false };
+    });
+
+    return c.json({ data: { received: true, ...(outcome.duplicate ? { duplicate: true } : {}) } });
   });
 
   return router;

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

@@ -3,6 +3,8 @@ import type { Kernel } from "../../../runtime/kernel.js";
 import { searchRoute, suggestRoute } from "../schemas/search.js";
 import { type AppEnv, mapErrorToResponse, mapErrorToStatus } from "../utils.js";
 
+const SAFE_ATTRIBUTE_NAME = /^[A-Za-z0-9_-]+$/;
+
 export function searchRoutes(kernel: Kernel) {
   const router = new OpenAPIHono<AppEnv>();
 
@@ -21,6 +23,19 @@ export function searchRoutes(kernel: Kernel) {
         .map((facet) => facet.trim())
         .filter(Boolean);
 
+      const attributes: Record<string, string | string[]> = {};
+      for (const [key, values] of Object.entries(c.req.queries())) {
+        if (!key.startsWith("attr.")) continue;
+        const name = key.slice("attr.".length);
+        if (!SAFE_ATTRIBUTE_NAME.test(name)) {
+          return c.json(
+            { error: "invalid_argument", field: key, message: `Invalid attribute filter name: ${name}` },
+            422,
+          );
+        }
+        attributes[name] = values.length === 1 ? values[0]! : values;
+      }
+
       const result = await kernel.services.search.query({
         query: q,
         page,
@@ -30,6 +45,7 @@ export function searchRoutes(kernel: Kernel) {
           ...(category ? { category } : {}),
           ...(brand ? { brand } : {}),
           ...(status ? { status } : {}),
+          ...(Object.keys(attributes).length > 0 ? { attributes } : {}),
         },
         ...(facets.length > 0 ? { facets } : {}),
       }, { actor: c.get("actor"), tx: null, requestId: "" });

package/src/interfaces/rest/schemas/admin-custom-field-proposals.ts

@@ -0,0 +1,29 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+const ProposalResponse = z.object({
+  data: z.object({
+    items: z.array(z.any()),
+    total: z.number(),
+    page: z.number(),
+    limit: z.number(),
+  }),
+});
+
+const ListQuery = z.object({
+  entityType: z.string().min(1).optional(),
+  page: z.string().max(10).optional(),
+  limit: z.string().max(10).optional(),
+});
+
+export const listCustomFieldProposalsRoute = createRoute({
+  method: "get",
+  path: "/custom-field-proposals",
+  tags: ["Admin"],
+  summary: "List proposed custom-field values",
+  request: { query: ListQuery },
+  responses: {
+    200: { content: { "application/json": { schema: ProposalResponse } }, description: "Proposed custom fields." },
+    ...errorResponses,
+  },
+});

package/src/interfaces/rest/schemas/admin-entity-field-definitions.ts

@@ -0,0 +1,120 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+const FieldType = z.enum([
+  "text",
+  "number",
+  "boolean",
+  "date",
+  "json",
+  "relation",
+  "select",
+]);
+
+const CreateBody = z
+  .object({
+    entityType: z.string().min(1),
+    name: z.string().min(1),
+    type: FieldType,
+    unit: z.string().nullable().optional(),
+    options: z.array(z.string()).nullable().optional(),
+    target: z.string().nullable().optional(),
+    filterable: z.boolean().optional(),
+    localized: z.boolean().optional(),
+    sortOrder: z.number().int().optional(),
+  })
+  .openapi("CreateEntityFieldDefinitionRequest");
+
+const UpdateBody = z
+  .object({
+    entityType: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+    type: FieldType.optional(),
+    unit: z.string().nullable().optional(),
+    options: z.array(z.string()).nullable().optional(),
+    target: z.string().nullable().optional(),
+    filterable: z.boolean().optional(),
+    localized: z.boolean().optional(),
+    sortOrder: z.number().int().optional(),
+  })
+  .openapi("UpdateEntityFieldDefinitionRequest");
+
+const IdParam = z.object({ id: z.uuid() });
+const ListQuery = z.object({ entityType: z.string().min(1).optional() });
+const DataResponse = z
+  .object({ data: z.any() })
+  .openapi("EntityFieldDefinitionResponse");
+
+export const createEntityFieldDefinitionRoute = createRoute({
+  method: "post",
+  path: "/entity-field-definitions",
+  tags: ["Admin"],
+  summary: "Create a runtime entity field definition",
+  request: {
+    body: {
+      content: { "application/json": { schema: CreateBody } },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: DataResponse } },
+      description: "Definition created.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const listEntityFieldDefinitionsRoute = createRoute({
+  method: "get",
+  path: "/entity-field-definitions",
+  tags: ["Admin"],
+  summary: "List runtime entity field definitions",
+  request: { query: ListQuery },
+  responses: {
+    200: {
+      content: { "application/json": { schema: DataResponse } },
+      description: "Definitions.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const updateEntityFieldDefinitionRoute = createRoute({
+  method: "patch",
+  path: "/entity-field-definitions/{id}",
+  tags: ["Admin"],
+  summary: "Update a runtime entity field definition",
+  request: {
+    params: IdParam,
+    body: {
+      content: { "application/json": { schema: UpdateBody } },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: DataResponse } },
+      description: "Definition updated.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const archiveEntityFieldDefinitionRoute = createRoute({
+  method: "post",
+  path: "/entity-field-definitions/{id}/archive",
+  tags: ["Admin"],
+  summary: "Archive a runtime entity field definition",
+  request: { params: IdParam },
+  responses: {
+    200: {
+      content: { "application/json": { schema: DataResponse } },
+      description: "Definition archived.",
+    },
+    ...errorResponses,
+  },
+});
+
+export type CreateEntityFieldDefinitionBody = z.infer<typeof CreateBody>;
+export type UpdateEntityFieldDefinitionBody = z.infer<typeof UpdateBody>;

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

@@ -19,6 +19,17 @@ import {
 
 const DataResponse = CatalogEntityResponse;
 const DataWithPaginationResponse = CatalogEntityListResponse;
+const FieldOwnershipSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  entityId: z.string(),
+  variantId: z.string().nullable(),
+  storeId: z.string().nullable(),
+  fieldPath: z.string(),
+  owner: z.enum(["platform", "store", "shared"]),
+  updatedAt: z.string(),
+}).openapi("CatalogFieldOwnership");
+const FieldOwnershipListResponse = z.object({ data: z.array(FieldOwnershipSchema) }).openapi("CatalogFieldOwnershipListResponse");
 
 // ─── Path Params ────────────────────────────────────────────────────────────
 
@@ -35,6 +46,15 @@ const EntityIdLocaleParam = z.object({
   locale: z.string().min(1).openapi({ example: "en" }),
 });
 
+const EntityCustomFieldParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+  fieldName: z.string().min(1).openapi({ example: "warranty" }),
+});
+
+const CustomFieldReviewQuery = z.object({
+  locale: z.string().min(1).optional().openapi({ example: "en" }),
+});
+
 const CategoryIdParam = z.object({
   categoryId: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
 });
@@ -104,6 +124,48 @@ export const getEntityAttributesRoute = createRoute({
   },
 });
 
+export const listFieldOwnershipRoute = createRoute({
+  method: "get",
+  path: "/entities/{id}/field-ownership",
+  tags: ["Catalog"],
+  summary: "List field ownership for a catalog entity",
+  request: {
+    params: EntityIdParam,
+    query: z.object({ storeId: z.string().optional() }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: FieldOwnershipListResponse } }, description: "Success" },
+    ...errorResponses,
+  },
+});
+
+export const setFieldOwnershipRoute = createRoute({
+  method: "put",
+  path: "/entities/{id}/field-ownership",
+  tags: ["Catalog"],
+  summary: "Set field ownership for a catalog entity",
+  request: {
+    params: EntityIdParam,
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            fieldPath: z.string().min(1),
+            owner: z.enum(["platform", "store", "shared"]),
+            storeId: z.string().min(1).nullable().optional(),
+            variantId: z.uuid().nullable().optional(),
+          }),
+        },
+      },
+      required: true,
+    },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: z.object({ data: z.object({ updated: z.literal(true) }) }) } }, description: "Updated" },
+    ...errorResponses,
+  },
+});
+
 export const listCategoriesRoute = createRoute({
   method: "get",
   path: "/categories",
@@ -312,6 +374,36 @@ export const setEntityAttributesRoute = createRoute({
   },
 });
 
+export const approveCustomFieldRoute = createRoute({
+  method: "post",
+  path: "/entities/{id}/custom-fields/{fieldName}/approve",
+  tags: ["Catalog"],
+  summary: "Approve a proposed custom-field value",
+  request: {
+    params: EntityCustomFieldParam,
+    query: CustomFieldReviewQuery,
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Approved" },
+    ...errorResponses,
+  },
+});
+
+export const rejectCustomFieldRoute = createRoute({
+  method: "post",
+  path: "/entities/{id}/custom-fields/{fieldName}/reject",
+  tags: ["Catalog"],
+  summary: "Reject a proposed custom-field value",
+  request: {
+    params: EntityCustomFieldParam,
+    query: CustomFieldReviewQuery,
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Rejected" },
+    ...errorResponses,
+  },
+});
+
 export const createCategoryRoute = createRoute({
   method: "post",
   path: "/categories",

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

@@ -8,6 +8,8 @@ export const searchRoute = createRoute({
   path: "/",
   tags: ["Search"],
   summary: "Search catalog entities",
+  description:
+    "Attribute filters use repeatable `attr.<name>=<value>` query parameters: repeated values for one name are ORed, distinct names are ANDed. Attribute names must match `^[A-Za-z0-9_-]+$`; anything else returns 422. Request attribute facet counts by naming the attribute in `facets`.",
   request: {
     query: z.object({
       q: z.string().max(500).optional(),

package/src/kernel/error-mapper.ts

@@ -11,6 +11,9 @@ const statusByCode: Record<string, ContentfulStatusCode> = {
   CONFLICT: 409,
   INVALID_TRANSITION: 422,
   ORG_RESOLUTION_FAILED: 503,
+  WEBHOOK_SIGNATURE_MISSING: 400,
+  WEBHOOK_VERIFICATION_FAILED: 400,
+  WEBHOOK_SECRET_MISSING: 503,
 };
 
 export function mapErrorToStatus(error: unknown): ContentfulStatusCode {