@porulle/core 0.8.0 → 0.10.0

package/src/kernel/jobs/runner.ts

@@ -1,7 +1,7 @@
 import { eq, and, sql } from "drizzle-orm";
 import type { DrizzleDatabase } from "../database/drizzle-db.js";
 import type { Logger, ServiceContainer } from "../hooks/types.js";
-import type { TaskDefinition } from "./types.js";
+import type { JobProcessingOrder, TaskDefinition } from "./types.js";
 import { commerceJobs } from "./schema.js";
 
 export interface RunPendingJobsArgs {
@@ -9,10 +9,53 @@ export interface RunPendingJobsArgs {
   tasks: Map<string, TaskDefinition>;
   queue?: string;
   limit?: number;
+  processingOrder?: JobProcessingOrder;
   logger: Logger;
   services: ServiceContainer;
 }
 
+type CommerceJob = typeof commerceJobs.$inferSelect;
+
+function isExclusiveTask(task: TaskDefinition | undefined): boolean {
+  return Boolean(task?.concurrency && task.concurrency.exclusive !== false);
+}
+
+function compareByProcessingOrder(
+  processingOrder: JobProcessingOrder | undefined,
+): (left: CommerceJob, right: CommerceJob) => number {
+  if (typeof processingOrder === "function") {
+    return (left, right) =>
+      processingOrder(
+        {
+          ...left,
+          input: left.input as Record<string, unknown>,
+        },
+        {
+          ...right,
+          input: right.input as Record<string, unknown>,
+        },
+      );
+  }
+
+  const field = processingOrder?.field ?? "createdAt";
+  const direction = processingOrder?.direction === "desc" ? -1 : 1;
+  return (left, right) => {
+    const leftValue = left[field];
+    const rightValue = right[field];
+    const compared =
+      leftValue instanceof Date && rightValue instanceof Date
+        ? leftValue.getTime() - rightValue.getTime()
+        : typeof leftValue === "number" && typeof rightValue === "number"
+          ? leftValue - rightValue
+          : String(leftValue).localeCompare(String(rightValue));
+    if (compared !== 0) return compared * direction;
+    return (
+      left.createdAt.getTime() - right.createdAt.getTime() ||
+      left.id.localeCompare(right.id)
+    );
+  };
+}
+
 /**
  * Claims and processes pending jobs from the `commerce_jobs` table.
  *
@@ -29,16 +72,24 @@ export async function runPendingJobs(
     tasks,
     queue = "default",
     limit = 10,
+    processingOrder,
     logger,
     services,
   } = args;
 
-  let processed = 0;
-  let failed = 0;
-
   // Phase 1: Claim jobs atomically
   const claimed = await db.transaction(async (tx) => {
-    const pending = await tx
+    const processing = await tx
+      .select({ concurrencyKey: commerceJobs.concurrencyKey })
+      .from(commerceJobs)
+      .where(eq(commerceJobs.status, "processing"));
+    const processingKeys = new Set(
+      processing.flatMap((job) =>
+        job.concurrencyKey ? [job.concurrencyKey] : [],
+      ),
+    );
+
+    const candidates = await tx
       .select()
       .from(commerceJobs)
       .where(
@@ -48,9 +99,34 @@ export async function runPendingJobs(
           sql`(${commerceJobs.waitUntil} IS NULL OR ${commerceJobs.waitUntil} <= now())`,
         ),
       )
-      .orderBy(commerceJobs.createdAt)
-      .limit(limit)
-      .for("update", { skipLocked: true });
+      .orderBy(commerceJobs.createdAt);
+
+    candidates.sort(compareByProcessingOrder(processingOrder));
+
+    const pending: CommerceJob[] = [];
+    for (const candidate of candidates) {
+      if (pending.length >= limit) break;
+      if (
+        candidate.concurrencyKey &&
+        isExclusiveTask(tasks.get(candidate.taskSlug)) &&
+        processingKeys.has(candidate.concurrencyKey)
+      ) {
+        continue;
+      }
+
+      const [locked] = await tx
+        .select()
+        .from(commerceJobs)
+        .where(
+          and(
+            eq(commerceJobs.id, candidate.id),
+            eq(commerceJobs.status, "pending"),
+          ),
+        )
+        .limit(1)
+        .for("update", { skipLocked: true });
+      if (locked) pending.push(locked);
+    }
 
     for (const job of pending) {
       await tx
@@ -63,95 +139,141 @@ export async function runPendingJobs(
         .where(eq(commerceJobs.id, job.id));
     }
 
-    return pending;
-  });
+    const oldestByKey = new Map<string, CommerceJob>();
+    const jobsToRun: CommerceJob[] = [];
+    const jobsToRelease: CommerceJob[] = [];
 
-  // Phase 2: Execute each claimed job outside the claim transaction
-  for (const job of claimed) {
-    const task = tasks.get(job.taskSlug);
-
-    if (!task) {
-      logger.warn("Unknown task slug — job marked as failed. Register the task handler in config.jobs.tasks.", {
-        taskSlug: job.taskSlug,
-        jobId: job.id,
-      });
-      await db
-        .update(commerceJobs)
-        .set({
-          status: "failed",
-          error: `Unknown task slug: ${job.taskSlug}`,
-          updatedAt: new Date(),
-          completedAt: new Date(),
-        })
-        .where(eq(commerceJobs.id, job.id));
-      failed++;
-      continue;
+    for (const job of pending) {
+      if (!job.concurrencyKey || !isExclusiveTask(tasks.get(job.taskSlug))) {
+        jobsToRun.push(job);
+        continue;
+      }
+
+      const oldest = oldestByKey.get(job.concurrencyKey);
+      if (!oldest) {
+        oldestByKey.set(job.concurrencyKey, job);
+        continue;
+      }
+
+      if (job.createdAt < oldest.createdAt) {
+        oldestByKey.set(job.concurrencyKey, job);
+        jobsToRelease.push(oldest);
+      } else {
+        jobsToRelease.push(job);
+      }
     }
 
-    try {
-      const result = await task.handler({
-        input: job.input as Record<string, unknown>,
-        ctx: { logger, db, services },
-        job: {
-          attemptNumber: job.attempts + 1,
-          maxAttempts: job.maxAttempts,
-        },
-      });
+    jobsToRun.push(...oldestByKey.values());
 
-      await db
+    for (const job of jobsToRelease) {
+      await tx
         .update(commerceJobs)
         .set({
-          status: "succeeded",
-          output: result.output,
-          attempts: job.attempts + 1,
+          status: "pending",
+          processingStartedAt: null,
           updatedAt: new Date(),
-          completedAt: new Date(),
         })
         .where(eq(commerceJobs.id, job.id));
+    }
+
+    return jobsToRun.sort(compareByProcessingOrder(processingOrder));
+  });
 
-      processed++;
-    } catch (err) {
-      logger.error("Job handler failed", {
-        taskSlug: job.taskSlug,
-        jobId: job.id,
-        error: err instanceof Error ? err.message : String(err),
-      });
-      const attempts = job.attempts + 1;
-      const maxAttempts = job.maxAttempts;
-
-      if (attempts >= maxAttempts) {
+  // Phase 2: Execute each claimed job outside the claim transaction
+  const outcomes = await Promise.all(
+    claimed.map(async (job) => {
+      const task = tasks.get(job.taskSlug);
+
+      if (!task) {
+        logger.warn(
+          "Unknown task slug — job marked as failed. Register the task handler in config.jobs.tasks.",
+          {
+            taskSlug: job.taskSlug,
+            jobId: job.id,
+          },
+        );
         await db
           .update(commerceJobs)
           .set({
             status: "failed",
-            error: err instanceof Error ? err.message : String(err),
-            attempts,
+            error: `Unknown task slug: ${job.taskSlug}`,
             updatedAt: new Date(),
             completedAt: new Date(),
           })
           .where(eq(commerceJobs.id, job.id));
-        failed++;
-      } else {
-        // Compute backoff delay
-        const retries = task.retries;
-        const delay =
-          retries?.backoff?.type === "exponential"
-            ? retries.backoff.delay * Math.pow(2, attempts - 1)
-            : (retries?.backoff?.delay ?? 1000);
+        return "failed" as const;
+      }
+
+      try {
+        const result = await task.handler({
+          input: job.input as Record<string, unknown>,
+          ctx: { logger, db, services },
+          job: {
+            attemptNumber: job.attempts + 1,
+            maxAttempts: job.maxAttempts,
+          },
+        });
 
         await db
           .update(commerceJobs)
           .set({
-            status: "pending",
-            error: err instanceof Error ? err.message : String(err),
-            attempts,
-            waitUntil: new Date(Date.now() + delay),
+            status: "succeeded",
+            output: result.output,
+            attempts: job.attempts + 1,
             updatedAt: new Date(),
+            completedAt: new Date(),
           })
           .where(eq(commerceJobs.id, job.id));
+
+        return "processed" as const;
+      } catch (err) {
+        logger.error("Job handler failed", {
+          taskSlug: job.taskSlug,
+          jobId: job.id,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        const attempts = job.attempts + 1;
+        const maxAttempts = job.maxAttempts;
+
+        if (attempts >= maxAttempts) {
+          await db
+            .update(commerceJobs)
+            .set({
+              status: "failed",
+              error: err instanceof Error ? err.message : String(err),
+              attempts,
+              updatedAt: new Date(),
+              completedAt: new Date(),
+            })
+            .where(eq(commerceJobs.id, job.id));
+          return "failed" as const;
+        } else {
+          // Compute backoff delay
+          const retries = task.retries;
+          const delay =
+            retries?.backoff?.type === "exponential"
+              ? retries.backoff.delay * Math.pow(2, attempts - 1)
+              : (retries?.backoff?.delay ?? 1000);
+
+          await db
+            .update(commerceJobs)
+            .set({
+              status: "pending",
+              error: err instanceof Error ? err.message : String(err),
+              attempts,
+              waitUntil: new Date(Date.now() + delay),
+              processingStartedAt: null,
+              updatedAt: new Date(),
+            })
+            .where(eq(commerceJobs.id, job.id));
+          return "retrying" as const;
+        }
       }
-    }
-  }
+    }),
+  );
 
-  return { processed, failed };
+  return {
+    processed: outcomes.filter((outcome) => outcome === "processed").length,
+    failed: outcomes.filter((outcome) => outcome === "failed").length,
+  };
 }

package/src/kernel/jobs/types.ts

@@ -17,6 +17,31 @@ export interface TaskRetryConfig {
   backoff?: { type: "fixed" | "exponential"; delay: number };
 }
 
+export interface JobProcessingOrderRecord {
+  id: string;
+  taskSlug: string;
+  input: Record<string, unknown>;
+  attempts: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export type JobProcessingOrderField =
+  | "createdAt"
+  | "updatedAt"
+  | "attempts"
+  | "taskSlug";
+
+export type JobProcessingOrder =
+  | {
+      field: JobProcessingOrderField;
+      direction?: "asc" | "desc";
+    }
+  | ((
+      left: JobProcessingOrderRecord,
+      right: JobProcessingOrderRecord,
+    ) => number);
+
 /** Present when the handler is invoked by `runPendingJobs` (not for ad-hoc calls). */
 export interface TaskJobMeta {
   attemptNumber: number;

package/src/kernel/plugin/manifest.ts

@@ -14,6 +14,7 @@ import type {
   CommercePlugin,
   PluginPermission,
 } from "../../config/types.js";
+import type { TaskDefinition } from "../jobs/types.js";
 
 // ─── Plugin Logger ────────────────────────────────────────────────────
 
@@ -147,6 +148,7 @@ export interface CommercePluginManifest {
   hooks?: () => PluginHookRegistration[];
   routes?: (ctx: PluginContext) => PluginRouteRegistration[];
   analyticsModels?: () => unknown[];
+  jobs?: () => TaskDefinition[];
   /**
    * Named API-key scopes this plugin mints credentials under (issue #51),
    * merged into `config.auth.apiKeyScopes`. User-defined scopes with the
@@ -158,6 +160,9 @@ export interface CommercePluginManifest {
     permissions?: Record<string, string[]>;
     /** Expiry bounds in DAYS (fractions allowed — 1/24 = one hour). */
     keyExpiration?: { minExpiresIn?: number; maxExpiresIn?: number };
+    /** Better Auth ownership model for keys minted under this scope. */
+    references?: "user" | "organization";
+    enableMetadata?: boolean;
   }>;
 }
 
@@ -341,6 +346,16 @@ export function defineCommercePlugin(
       };
     }
 
+    if (manifest.jobs) {
+      result = {
+        ...result,
+        jobs: {
+          ...(result.jobs ?? {}),
+          tasks: [...(result.jobs?.tasks ?? []), ...manifest.jobs()],
+        },
+      };
+    }
+
     return result;
   };
 }

package/src/modules/analytics/drizzle-adapter.ts

@@ -216,6 +216,17 @@ export class DrizzleAnalyticsAdapter implements AnalyticsAdapter {
       }
     }
 
+    // Validate that requested time dimensions exist in the cube
+    for (const td of params.timeDimensions ?? []) {
+      const shortName = td.dimension.split(".")[1];
+      if (shortName && !cube.dimensions[shortName]) {
+        const available = Object.keys(cube.dimensions).map((d) => `${cubeName}.${d}`).join(", ");
+        return Err(new CommerceValidationError(
+          `Unknown time dimension: "${td.dimension}". Available dimensions for ${cubeName}: ${available}`,
+        ));
+      }
+    }
+
     try {
       const rows = await this.executeQuery(cube, params, scope);
       return Ok({
@@ -330,14 +341,17 @@ export class DrizzleAnalyticsAdapter implements AnalyticsAdapter {
       const shortName = dim.split(".")[1]!;
       const dimDef = cube.dimensions[shortName];
       if (!dimDef) continue;
-      selectParts.push(sql.raw(`${dimDef.sql} AS "${dim}"`));
+      const alias = `${cube.name}.${shortName}`;
+      selectParts.push(sql.raw(`${dimDef.sql} AS "${alias}"`));
       groupByParts.push(sql.raw(dimDef.sql));
     }
 
     // Time dimensions → SELECT + GROUP BY + WHERE (dateRange)
     for (const td of params.timeDimensions ?? []) {
+      const shortName = td.dimension.split(".")[1]!;
       const selectExpr = compileTimeDimensionSelect(cube, td);
-      selectParts.push(sql`${selectExpr} AS ${sql.raw(`"${td.dimension}"`)}`);
+      const alias = `${cube.name}.${shortName}`;
+      selectParts.push(sql`${selectExpr} AS ${sql.raw(`"${alias}"`)}`);
       groupByParts.push(selectExpr);
 
       // Date range filter
@@ -357,7 +371,9 @@ export class DrizzleAnalyticsAdapter implements AnalyticsAdapter {
 
     // Measures → SELECT
     for (const measure of params.measures) {
-      selectParts.push(sql`${compileMeasure(cube, measure)} AS ${sql.raw(`"${measure}"`)}`);
+      const shortName = measure.split(".")[1]!;
+      const alias = `${cube.name}.${shortName}`;
+      selectParts.push(sql`${compileMeasure(cube, measure)} AS ${sql.raw(`"${alias}"`)}`);
     }
 
     // If no select parts (shouldn't happen with validation), bail

package/src/modules/cart/service.ts

@@ -227,8 +227,9 @@ export class CartService {
       );
     }
 
-    // Validate entity exists
-    const entity = await this.catalogRepo.findEntityById(input.entityId, ctx);
+    // Validate entity exists AND belongs to the actor's org (org-scoped lookup
+    // so another tenant's entity id cannot be added to this cart).
+    const entity = await this.catalogRepo.findEntityById(input.entityId, ctx, orgId);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
 
     // Check if entity has variants

package/src/modules/catalog/entity-service.ts

@@ -98,6 +98,10 @@ export class EntityService {
     }
   }
 
+  private assertEntityWritable(entity: SellableEntity, actor: Actor | null): void {
+    if (entity.sourceStoreId != null) assertPermission(actor, "catalog:sync");
+  }
+
   private async validateAndCreateCustomFields(entityId: string, entityType: string, customFields: Record<string, unknown> | undefined, ctx?: TxContext): Promise<Result<void>> {
     if (!customFields) return Ok(undefined);
     const entityConfig = this.deps.config.entities?.[entityType];
@@ -212,7 +216,8 @@ export class EntityService {
     const afterHooks = this.deps.hooks.resolve("catalog.afterCreate") as CatalogCreateAfterHook[];
     const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.create"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
     const processedInput = await runBeforeHooks(beforeHooks, input, "create", context);
-    const entity = await this.repo.createEntity({ organizationId: orgId, type: processedInput.type, slug: processedInput.slug, status: "draft", isVisible: false, ...(processedInput.taxClass !== undefined ? { taxClass: processedInput.taxClass } : {}), metadata: processedInput.metadata ?? {} }, ctx);
+    if (processedInput.sourceStoreId != null) assertPermission(actor, "catalog:sync");
+    const entity = await this.repo.createEntity({ organizationId: orgId, type: processedInput.type, slug: processedInput.slug, status: "draft", isVisible: false, ...(processedInput.sourceStoreId !== undefined ? { sourceStoreId: processedInput.sourceStoreId } : {}), ...(processedInput.taxClass !== undefined ? { taxClass: processedInput.taxClass } : {}), metadata: processedInput.metadata ?? {} }, ctx);
     if (processedInput.attributes) {
       await this.repo.createAttribute({ entityId: entity.id, locale: processedInput.attributes.locale ?? "en", title: processedInput.attributes.title, subtitle: processedInput.attributes.subtitle, description: processedInput.attributes.description, richDescription: processedInput.attributes.richDescription, seoTitle: processedInput.attributes.seoTitle, seoDescription: processedInput.attributes.seoDescription }, ctx);
     }
@@ -228,6 +233,7 @@ export class EntityService {
     const existing = await this.repo.findEntityById(id, ctx);
     if (!existing) return Err(new CommerceNotFoundError("Entity not found."));
     this.assertSameOrg(existing, actor);
+    this.assertEntityWritable(existing, actor);
     const beforeHooks = this.deps.hooks.resolve("catalog.beforeUpdate") as CatalogUpdateBeforeHook[];
     const afterHooks = this.deps.hooks.resolve("catalog.afterUpdate") as CatalogUpdateAfterHook[];
     const context: HookContext = createHookContext({ actor, tx: ctx?.tx ?? null, logger: createLogger("catalog.update"), services: this.deps.services, context: { moduleName: "catalog" }, ...hookDatabaseArg(this.deps.database) });
@@ -244,6 +250,7 @@ export class EntityService {
     const existing = await this.repo.findEntityById(id, ctx);
     if (!existing) return Err(new CommerceNotFoundError("Entity not found."));
     this.assertSameOrg(existing, actor);
+    this.assertEntityWritable(existing, actor);
     await this.repo.deleteAttributesByEntityId(id, ctx);
     await this.repo.deleteCustomFieldsByEntityId(id, ctx);
     await this.repo.deleteEntityCategoriesByEntityId(id, ctx);
@@ -271,7 +278,12 @@ export class EntityService {
         entity = refetched;
       }
     }
-    if (actor && entity.organizationId && entity.organizationId !== resolveOrgId(actor)) return Err(new CommerceNotFoundError("Entity not found."));
+    const resolvedActor = actor ?? ctx?.actor ?? null;
+    try {
+      this.assertSameOrg(entity, resolvedActor);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
     const result = await this.hydrateEntity(entity, processed.options ?? options, ctx);
     const entityAfterHooks = this.deps.hooks.resolve(`catalog.${entity.type}.afterRead`) as CatalogReadAfterHook[];
     const report = mergeHookReports(await runAfterHooks(globalAfterHooks, null, result, "read", context), await runAfterHooks(entityAfterHooks, null, result, "read", context));
@@ -377,6 +389,7 @@ export class EntityService {
     const entity = await this.repo.findEntityById(id, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
     try { this.assertSameOrg(entity, actor); } catch (error) { return Err(toCommerceError(error)); }
+    try { this.assertEntityWritable(entity, actor); } catch (error) { return Err(toCommerceError(error)); }
     const updateData: Partial<SellableEntity> = { status };
     if (status === "active") { updateData.publishedAt = new Date(); updateData.isVisible = true; }
     const updated = await this.repo.updateEntity(id, updateData, ctx);
@@ -407,6 +420,11 @@ export class EntityService {
     assertPermission(actor, "catalog:update");
     const entity = await this.repo.findEntityById(input.entityId, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    try {
+      this.assertSameOrg(entity, actor);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
     const optionType = await this.repo.createOptionType({ entityId: input.entityId, name: input.name, displayName: input.name, sortOrder: 0 }, ctx);
     if (input.values) {
       for (const value of input.values) {
@@ -420,6 +438,13 @@ export class EntityService {
     assertPermission(actor, "catalog:update");
     const optionType = await this.repo.findOptionTypeById(input.optionTypeId, ctx);
     if (!optionType) return Err(new CommerceNotFoundError("Option type not found."));
+    const entity = await this.repo.findEntityById(optionType.entityId, ctx);
+    if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    try {
+      this.assertSameOrg(entity, actor);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
     return Ok(await this.repo.createOptionValue({ optionTypeId: input.optionTypeId, value: input.value, displayValue: input.value, sortOrder: 0, metadata: {} }, ctx));
   }
 
@@ -427,6 +452,11 @@ export class EntityService {
     assertPermission(actor, "catalog:update");
     const entity = await this.repo.findEntityById(input.entityId, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    try {
+      this.assertSameOrg(entity, actor);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
     const entityOptionTypes = await this.repo.findOptionTypesByEntityId(input.entityId, ctx);
     const optionValueIds: string[] = [];
     for (const [optName, optVal] of Object.entries(input.options)) {
@@ -461,6 +491,11 @@ export class EntityService {
     }
     const entity = await this.repo.findEntityById(entityId, ctx);
     if (!entity) return Err(new CommerceNotFoundError("Entity not found."));
+    try {
+      this.assertSameOrg(entity, actor);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
     const entityOptionTypes = await this.repo.findOptionTypesByEntityId(entityId, ctx);
     const sortedOptionTypes = entityOptionTypes.sort((a, b) => a.sortOrder - b.sortOrder);
     const optionValueGroups: string[][] = [];

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

@@ -1,5 +1,6 @@
 import { eq, and, inArray, type SQL } from "drizzle-orm";
 import type { TxContext } from "../../../kernel/database/tx-context.js";
+import { CommerceNotFoundError } from "../../../kernel/errors.js";
 import type {
   DrizzleDatabase,
   DbOrTx,
@@ -698,15 +699,24 @@ export class CatalogRepository {
     return rows[0];
   }
 
-  async createVariant(data: VariantInsert, ctx?: TxContext): Promise<Variant> {
+  async createVariant(
+    data: Omit<VariantInsert, "organizationId" | "sourceStoreId">,
+    ctx?: TxContext,
+  ): Promise<Variant> {
     const db = this.getDb(ctx);
-    const rows = await db.insert(variants).values(data).returning();
+    const entity = await this.findEntityById(data.entityId, ctx);
+    if (!entity) throw new CommerceNotFoundError("Entity not found.");
+    const rows = await db.insert(variants).values({
+      ...data,
+      organizationId: entity.organizationId,
+      sourceStoreId: entity.sourceStoreId,
+    }).returning();
     return rows[0]!;
   }
 
   async updateVariant(
     id: string,
-    data: Partial<Omit<VariantInsert, "id">>,
+    data: Partial<Omit<VariantInsert, "id" | "organizationId" | "sourceStoreId">>,
     ctx?: TxContext,
   ): Promise<Variant | undefined> {
     const db = this.getDb(ctx);