@porulle/core 0.10.8 → 0.13.0

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/interfaces/rest/utils.ts

@@ -3,6 +3,25 @@ import { mapErrorToStatus } from "../../kernel/error-mapper.js";
 import { toCommerceError } from "../../kernel/errors.js";
 import type { Actor } from "../../auth/types.js";
 
+export const ROUTE_PERMISSION_GUARD = Symbol("porulle.routePermissionGuard");
+
+type RouteGuardHandler = {
+  [ROUTE_PERMISSION_GUARD]?: { methods?: readonly string[] };
+};
+
+export function markRoutePermissionGuard<T>(handler: T, methods?: readonly string[]): T {
+  if (typeof handler === "function") {
+    Object.defineProperty(handler, ROUTE_PERMISSION_GUARD, { value: { methods } });
+  }
+  return handler;
+}
+
+type PermissionContext = {
+  get(key: string): unknown;
+  json(data: unknown, status: number): unknown;
+  req: { method: string };
+};
+
 /**
  * Shared Hono environment type for all sub-routers.
  * Matches the Variables set by middleware in the top-level server app.
@@ -61,7 +80,7 @@ export { mapErrorToStatus };
  * Usage: router.post("/", requirePerm("webhooks:manage"), handler);
  */
 export function requirePerm(permission: string) {
-  return async (c: { get(key: string): unknown; json(data: unknown, status: number): unknown }, next: () => Promise<void>) => {
+  const middleware = async (c: { get(key: string): unknown; json(data: unknown, status: number): unknown }, next: () => Promise<void>) => {
     const actor = c.get("actor") as { permissions?: string[] } | null;
     if (!actor) {
       return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
@@ -79,6 +98,46 @@ export function requirePerm(permission: string) {
     }
     return c.json({ error: { code: "FORBIDDEN", message: `Permission '${permission}' is required.` } }, 403);
   };
+  return markRoutePermissionGuard(middleware);
+}
+
+export function requireAnyPerm(permissions: readonly string[]) {
+  const middleware = async (c: { get(key: string): unknown; json(data: unknown, status: number): unknown }, next: () => Promise<void>) => {
+    const actor = c.get("actor") as { permissions?: string[] } | null;
+    const granted = actor?.permissions ?? [];
+    const allowed = permissions.some((permission) =>
+      granted.includes(permission) ||
+      granted.includes("*:*") ||
+      granted.includes(`${permission.split(":")[0]}:*`),
+    );
+    if (!actor) {
+      return c.json({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }, 401);
+    }
+    if (allowed) {
+      await next();
+      return;
+    }
+    return c.json({ error: { code: "FORBIDDEN", message: `One of these permissions is required: ${permissions.join(", ")}.` } }, 403);
+  };
+  return markRoutePermissionGuard(middleware);
+}
+
+export function requireMethodPerm(methods: readonly string[], permission: string) {
+  const permissionGuard = requirePerm(permission);
+  const middleware = async (c: PermissionContext, next: () => Promise<void>) => {
+    if (!methods.includes(c.req.method)) {
+      await next();
+      return;
+    }
+    return permissionGuard(c, next);
+  };
+  return markRoutePermissionGuard(middleware, methods);
+}
+
+export function isRoutePermissionGuard(handler: unknown, method?: string): boolean {
+  if (typeof handler !== "function") return false;
+  const guard = (handler as unknown as RouteGuardHandler)[ROUTE_PERMISSION_GUARD];
+  return Boolean(guard && (!method || !guard.methods || guard.methods.includes(method)));
 }
 
 export function parseSort(
@@ -100,5 +159,5 @@ export function parseSort(
 }
 
 export function isUUID(value: string): boolean {
-  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
 }

package/src/kernel/compensation/executor.ts

@@ -1,4 +1,4 @@
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import type { CompensationContext, Step } from "./types.js";
 import type { Result } from "../result.js";
 
@@ -85,7 +85,7 @@ export async function runCompensationChain<TInput>(
           );
           if (ctx.failureRepository) {
             try {
-              const orgId = resolveOrgId(ctx.hook.actor);
+              const orgId = resolveOrgIdForCommerce(ctx.hook.actor, ctx.hook.commerceConfig);
               const recordResult = await ctx.failureRepository.record(
                 {
                   organizationId: orgId,

package/src/kernel/database/tx-context.ts

@@ -6,11 +6,19 @@ export interface TxContext<TTx = unknown> {
   tx: TTx;
   actor: Actor | null;
   requestId: string;
+  hookContext?: Record<string, unknown>;
 }
 
+export interface HookContextCarrier {
+  hookContext?: Record<string, unknown>;
+}
+
+export type CatalogWriteContext<TTx = unknown> = TxContext<TTx> | HookContextCarrier;
+
 export interface WithTransactionOptions {
   actor: Actor | null;
   requestId?: string;
+  hookContext?: Record<string, unknown>;
 }
 
 export function createTxContext<TTx>(
@@ -21,6 +29,7 @@ export function createTxContext<TTx>(
     tx,
     actor: options.actor,
     requestId: options.requestId ?? randomUUID(),
+    ...(options.hookContext ? { hookContext: options.hookContext } : {}),
   };
 }
 
@@ -44,3 +53,19 @@ export function reuseOrCreateTxContext<TTx>(
   }
   return createTxContext(tx, options);
 }
+
+function hookContextFromWriteContext(ctx?: CatalogWriteContext): Record<string, unknown> | undefined {
+  return ctx?.hookContext;
+}
+
+function isTransactionalWriteContext<TTx>(ctx: CatalogWriteContext<TTx>): ctx is TxContext<TTx> {
+  return "tx" in ctx && ctx.tx != null;
+}
+
+export function resolveWriteContextHookContext(ctx?: CatalogWriteContext): Record<string, unknown> | undefined {
+  return hookContextFromWriteContext(ctx);
+}
+
+export function isWriteContextTransactional<TTx>(ctx?: CatalogWriteContext<TTx>): ctx is TxContext<TTx> {
+  return ctx != null && isTransactionalWriteContext(ctx);
+}

package/src/kernel/hooks/create-context.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { Actor } from "../../auth/types.js";
+import type { CommerceConfig } from "../../config/types.js";
 import type { JobsAdapter } from "../jobs/adapter.js";
 import { NullJobsAdapter } from "../jobs/adapter.js";
 import type { PluginDb } from "../database/plugin-types.js";
@@ -21,6 +22,7 @@ export interface CreateHookContextArgs {
    * @deprecated Pass {@link CreateHookContextArgs.database} or {@link CreateHookContextArgs.db} instead.
    */
   kernel?: { database: { db: PluginDb } };
+  commerceConfig?: CommerceConfig | null;
 }
 
 const nullJobs = new NullJobsAdapter();
@@ -48,5 +50,6 @@ export function createHookContext(args: CreateHookContextArgs): HookContext {
     origin: args.origin ?? "rest",
     jobs: args.jobs ?? nullJobs,
     db,
+    ...(args.commerceConfig !== undefined ? { commerceConfig: args.commerceConfig } : {}),
   };
 }

package/src/kernel/hooks/types.ts

@@ -1,4 +1,5 @@
 import type { Actor } from "../../auth/types.js";
+import type { CommerceConfig } from "../../config/types.js";
 import type { JobsAdapter } from "../jobs/adapter.js";
 import type { PluginDb } from "../database/plugin-types.js";
 
@@ -40,6 +41,7 @@ export interface HookContext {
    * Populated by `createHookContext` when callers pass `db`, `database`, or `kernel`.
    */
   db: PluginDb;
+  commerceConfig?: CommerceConfig | null;
 }
 
 export type BeforeHook<TData> = (args: {

package/src/kernel/plugin/manifest.ts

@@ -2,7 +2,8 @@ import type { Hono } from "hono";
 import type { OpenAPIHono, RouteConfig } from "@hono/zod-openapi";
 import type { PluginDb } from "../database/plugin-types.js";
 import type { DatabaseAdapter } from "../database/adapter.js";
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
+import { isRoutePermissionGuard, markRoutePermissionGuard } from "../../interfaces/rest/utils.js";
 import { createScopedDb } from "../database/scoped-db.js";
 import {
   getPluginDatabaseScopeOrganizationId,
@@ -97,7 +98,7 @@ function buildPluginContextDatabase(
 ): PluginContext["database"] {
   const orgGetter = () =>
     getPluginDatabaseScopeOrganizationId() ??
-    resolveOrgId(null, undefined, commerceConfig);
+    resolveOrgIdForCommerce(null, commerceConfig);
 
   const scopedDb = createScopedDb(rawDb, orgGetter);
   const warnUnscoped = createRateLimitedUnscopedAccessWarning(logger);
@@ -288,7 +289,7 @@ export function defineCommercePlugin(
             const wrappedHandler = async (...args: unknown[]) => {
               const c = args[0] as { get?: (key: string) => unknown } | undefined;
               const actor = c?.get?.("actor");
-              const orgId = resolveOrgId(actor, undefined, k.config);
+              const orgId = resolveOrgIdForCommerce(actor, k.config);
               try {
                 return await runWithPluginDatabaseScope(orgId, async () => {
                   const out = originalHandler(...args);
@@ -305,19 +306,22 @@ export function defineCommercePlugin(
                 throw err; // re-throw so global handler still catches
               }
             };
+            const registeredHandler = isRoutePermissionGuard(originalHandler)
+              ? markRoutePermissionGuard(wrappedHandler)
+              : wrappedHandler;
 
             if ("openapi" in route) {
               // OpenAPI route: validated by Zod, appears in /api/doc
               // Hono type interop — OpenAPIHono.openapi() expects strict RouteConfig+Handler
               // generics that can't be statically resolved for dynamic plugin routes.
               // @ts-expect-error -- dynamic plugin routes cannot satisfy Hono's strict handler generics
-              (app as OpenAPIHono).openapi(route.openapi, wrappedHandler);
+              (app as OpenAPIHono).openapi(route.openapi, registeredHandler);
             } else {
               // Legacy route: raw handler, invisible to OpenAPI spec.
               // Explicit dispatch avoids casting Hono to a Record.
               // Handler cast is a single `as any` (Hono's overloaded method
               // signatures can't unify with our generic handler shape).
-              const h = wrappedHandler as any;
+              const h = registeredHandler as any;
               switch (route.method.toLowerCase()) {
                 case "get":     app.get(route.path, h); break;
                 case "post":    app.post(route.path, h); break;

package/src/modules/analytics/service.ts

@@ -9,7 +9,7 @@
 import type { CommerceConfig } from "../../config/types.js";
 import { CommerceValidationError } from "../../kernel/errors.js";
 import { Err, Ok, type Result } from "../../kernel/result.js";
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import type { Actor } from "../../auth/types.js";
 import type { ReportParams, RetailReportsEngine } from "./reports.js";
 import { RETAIL_REPORTS } from "./reports.js";
@@ -135,7 +135,7 @@ export class AnalyticsService {
     if (!this.deps.reports) {
       return Err(new CommerceValidationError("Retail reports are not available."));
     }
-    const orgId = resolveOrgId(actor ?? null);
+    const orgId = resolveOrgIdForCommerce(actor ?? null, this.deps.config);
     return this.deps.reports.run(name, params, orgId);
   }
 

package/src/modules/audit/service.ts

@@ -3,7 +3,7 @@ import type { InferSelectModel } from "drizzle-orm";
 import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
 import type { TxContext } from "../../kernel/database/tx-context.js";
 import type { HookContext } from "../../kernel/hooks/types.js";
-import { resolveOrgId } from "../../auth/org.js";
+import { resolveOrgIdForCommerce } from "../../auth/org.js";
 import { auditLog } from "./schema.js";
 
 export type AuditEntry = InferSelectModel<typeof auditLog>;
@@ -47,7 +47,7 @@ export function createNullAuditService(): AuditService {
     async record(args) {
       entries.push({
         id: crypto.randomUUID(),
-        organizationId: resolveOrgId(args.ctx.actor),
+        organizationId: resolveOrgIdForCommerce(args.ctx.actor, args.ctx.commerceConfig),
         entityType: args.entityType,
         entityId: args.entityId,
         event: args.event,
@@ -94,7 +94,7 @@ export function createAuditService(db: DrizzleDatabase): AuditService {
           : db;
 
       await dbOrTx.insert(auditLog).values({
-        organizationId: resolveOrgId(ctx.actor),
+        organizationId: resolveOrgIdForCommerce(ctx.actor, ctx.commerceConfig),
         entityType,
         entityId,
         event,

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

@@ -130,34 +130,48 @@ export class CartRepository {
   }
 
   /**
-   * Atomically transitions a cart from "active" to "checking_out".
-   * Returns the updated cart if the transition succeeded, or undefined if
-   * the cart was not in "active" status (e.g., a concurrent checkout already
-   * claimed it). This prevents TOCTOU race conditions on double-checkout.
+   * Atomically transitions a cart from "active" to "checking_out" and records
+   * `claimToken` as the holder of that claim. Returns the updated cart if the
+   * transition succeeded, or undefined if the cart was not in "active" status
+   * (e.g., a concurrent checkout already claimed it). This prevents TOCTOU race
+   * conditions on double-checkout.
    */
   async transitionToCheckingOut(
     id: string,
+    claimToken: string,
     ctx?: TxContext,
   ): Promise<Cart | undefined> {
     const db = this.getDb(ctx);
     const rows = await db
       .update(carts)
-      .set({ status: "checking_out", updatedAt: new Date() })
+      .set({ status: "checking_out", checkoutClaimToken: claimToken, updatedAt: new Date() })
       .where(and(eq(carts.id, id), eq(carts.status, "active")))
       .returning();
     return rows[0];
   }
 
-  /** Release only an in-progress checkout claim; terminal cart states are untouched. */
+  /**
+   * Release an in-progress checkout claim held by `claimToken`. Terminal cart
+   * states are untouched, and so is a claim held by a different checkout
+   * attempt — a losing attempt's failure path must not reopen the cart the
+   * winner is still checking out.
+   */
   async releaseCheckoutClaim(
     id: string,
+    claimToken: string,
     ctx?: TxContext,
   ): Promise<Cart | undefined> {
     const db = this.getDb(ctx);
     const rows = await db
       .update(carts)
-      .set({ status: "active", updatedAt: new Date() })
-      .where(and(eq(carts.id, id), eq(carts.status, "checking_out")))
+      .set({ status: "active", checkoutClaimToken: null, updatedAt: new Date() })
+      .where(
+        and(
+          eq(carts.id, id),
+          eq(carts.status, "checking_out"),
+          eq(carts.checkoutClaimToken, claimToken),
+        ),
+      )
       .returning();
     return rows[0];
   }

package/src/modules/cart/schema.ts

@@ -15,6 +15,10 @@ export const carts = pgTable("carts", {
   // Shopper contact for guest carts — enables abandoned-checkout recovery
   email: text("email"),
   secret: text("secret"),
+  // Owner of an in-progress `checking_out` claim. Minted by the checkout
+  // attempt that wins the CAS; only that holder may release the claim, so a
+  // losing attempt's failure path cannot unwind the winner's claim.
+  checkoutClaimToken: text("checkout_claim_token"),
   metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
   expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
   createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),