@porulle/core 0.1.0

package/src/modules/media/adapter.ts

@@ -0,0 +1,17 @@
+import type { Result } from "../../kernel/result.js";
+
+export interface StoredFile {
+  key: string;
+  url: string;
+  contentType: string;
+  size?: number;
+}
+
+export interface StorageAdapter {
+  readonly providerId: string;
+  upload(key: string, data: ArrayBuffer | ReadableStream, contentType: string): Promise<Result<StoredFile>>;
+  getUrl(key: string): Promise<Result<string>>;
+  getSignedUrl(key: string, expiresIn: number): Promise<Result<string>>;
+  delete(key: string): Promise<Result<void>>;
+  list(prefix: string): Promise<Result<StoredFile[]>>;
+}

package/src/modules/media/index.ts

@@ -0,0 +1 @@
+export { mediaModule } from "./module.js";

package/src/modules/media/module.ts

@@ -0,0 +1,25 @@
+import type { CommerceConfig } from "../../config/types.js";
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
+import { defineModule } from "../../kernel/module/index.js";
+import { CatalogRepository } from "../catalog/repository/index.js";
+import { MediaRepository } from "./repository/index.js";
+import { MediaService } from "./service.js";
+import { entityMedia, mediaAssets } from "./schema.js";
+
+export const mediaModule = defineModule({
+  id: "media",
+  schema: () => ({ mediaAssets, entityMedia }),
+  service: (deps) => {
+    const db = deps.db.db as DrizzleDatabase;
+    const storage = (deps.config as CommerceConfig).storage;
+    if (storage == null) {
+      throw new Error("Media module requires config.storage");
+    }
+    return new MediaService({
+      repository: new MediaRepository(db),
+      catalogRepository: new CatalogRepository(db),
+      storage,
+      config: deps.config as CommerceConfig,
+    });
+  },
+});

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

@@ -0,0 +1,274 @@
+import { eq, and, inArray } from "drizzle-orm";
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+import type {
+  DrizzleDatabase,
+  DbOrTx,
+} from "../../../kernel/database/drizzle-db.js";
+import { mediaAssets, entityMedia } from "../schema.js";
+
+// Infer types from Drizzle schema
+export type MediaAsset = typeof mediaAssets.$inferSelect;
+export type MediaAssetInsert = typeof mediaAssets.$inferInsert;
+export type EntityMedia = typeof entityMedia.$inferSelect;
+export type EntityMediaInsert = typeof entityMedia.$inferInsert;
+
+/**
+ * MediaRepository provides type-safe database operations for media assets.
+ *
+ * This repository manages media assets and their associations with entities.
+ * All methods support an optional TxContext parameter for transaction participation.
+ */
+export class MediaRepository {
+  constructor(private readonly db: DrizzleDatabase) {}
+
+  private getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? this.db;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Media Assets
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findAssetById(
+    id: string,
+    ctx?: TxContext,
+    orgId?: string,
+  ): Promise<MediaAsset | undefined> {
+    const db = this.getDb(ctx);
+    const conditions = [eq(mediaAssets.id, id)];
+    if (orgId) {
+      conditions.push(eq(mediaAssets.organizationId, orgId));
+    }
+    const rows = await db
+      .select()
+      .from(mediaAssets)
+      .where(and(...conditions));
+    return rows[0];
+  }
+
+  async findAssetByStorageKey(
+    storageKey: string,
+    ctx?: TxContext,
+  ): Promise<MediaAsset | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(mediaAssets)
+      .where(eq(mediaAssets.storageKey, storageKey));
+    return rows[0];
+  }
+
+  async findAssetsByIds(ids: string[], ctx?: TxContext): Promise<MediaAsset[]> {
+    if (ids.length === 0) return [];
+    const db = this.getDb(ctx);
+    return db.select().from(mediaAssets).where(inArray(mediaAssets.id, ids));
+  }
+
+  async createAsset(
+    data: MediaAssetInsert,
+    ctx?: TxContext,
+  ): Promise<MediaAsset> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(mediaAssets).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateAsset(
+    id: string,
+    data: Partial<Omit<MediaAssetInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<MediaAsset | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(mediaAssets)
+      .set(data)
+      .where(eq(mediaAssets.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async deleteAsset(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .delete(mediaAssets)
+      .where(eq(mediaAssets.id, id))
+      .returning();
+    return result.length > 0;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Entity Media (Associations)
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findEntityMedia(
+    entityId: string,
+    variantId?: string,
+    ctx?: TxContext,
+  ): Promise<EntityMedia[]> {
+    const db = this.getDb(ctx);
+
+    if (variantId === undefined) {
+      // Find media for entity only (not variant-specific)
+      const rows = await db
+        .select()
+        .from(entityMedia)
+        .where(eq(entityMedia.entityId, entityId));
+      return rows.filter((r) => r.variantId === null);
+    }
+
+    return db
+      .select()
+      .from(entityMedia)
+      .where(
+        and(
+          eq(entityMedia.entityId, entityId),
+          eq(entityMedia.variantId, variantId),
+        ),
+      );
+  }
+
+  async findEntityMediaByRole(
+    entityId: string,
+    role: EntityMedia["role"],
+    variantId?: string,
+    ctx?: TxContext,
+  ): Promise<EntityMedia[]> {
+    const db = this.getDb(ctx);
+    const conditions = [
+      eq(entityMedia.entityId, entityId),
+      eq(entityMedia.role, role),
+    ];
+
+    if (variantId !== undefined) {
+      conditions.push(eq(entityMedia.variantId, variantId));
+    }
+
+    const rows = await db
+      .select()
+      .from(entityMedia)
+      .where(and(...conditions));
+
+    if (variantId === undefined) {
+      return rows.filter((r) => r.variantId === null);
+    }
+    return rows;
+  }
+
+  async findPrimaryMedia(
+    entityId: string,
+    variantId?: string,
+    ctx?: TxContext,
+  ): Promise<EntityMedia | undefined> {
+    const media = await this.findEntityMediaByRole(
+      entityId,
+      "primary",
+      variantId,
+      ctx,
+    );
+    return media[0];
+  }
+
+  async createEntityMedia(
+    data: EntityMediaInsert,
+    ctx?: TxContext,
+  ): Promise<EntityMedia> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(entityMedia).values(data).returning();
+    return rows[0]!;
+  }
+
+  async createEntityMediaBatch(
+    data: EntityMediaInsert[],
+    ctx?: TxContext,
+  ): Promise<EntityMedia[]> {
+    if (data.length === 0) return [];
+    const db = this.getDb(ctx);
+    return db.insert(entityMedia).values(data).returning();
+  }
+
+  async updateEntityMediaSortOrder(
+    entityId: string,
+    mediaAssetId: string,
+    sortOrder: number,
+    variantId?: string,
+    ctx?: TxContext,
+  ): Promise<EntityMedia | undefined> {
+    const db = this.getDb(ctx);
+    const conditions = [
+      eq(entityMedia.entityId, entityId),
+      eq(entityMedia.mediaAssetId, mediaAssetId),
+    ];
+
+    if (variantId !== undefined) {
+      conditions.push(eq(entityMedia.variantId, variantId));
+    }
+
+    const rows = await db
+      .update(entityMedia)
+      .set({ sortOrder })
+      .where(and(...conditions))
+      .returning();
+
+    if (variantId === undefined) {
+      return rows.find((r) => r.variantId === null);
+    }
+    return rows[0];
+  }
+
+  async removeEntityMedia(
+    entityId: string,
+    mediaAssetId: string,
+    variantId?: string,
+    ctx?: TxContext,
+  ): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const conditions = [
+      eq(entityMedia.entityId, entityId),
+      eq(entityMedia.mediaAssetId, mediaAssetId),
+    ];
+
+    if (variantId !== undefined) {
+      conditions.push(eq(entityMedia.variantId, variantId));
+    }
+
+    const result = await db
+      .delete(entityMedia)
+      .where(and(...conditions))
+      .returning();
+
+    if (variantId === undefined) {
+      return result.some((r) => r.variantId === null);
+    }
+    return result.length > 0;
+  }
+
+  async removeAllEntityMedia(entityId: string, ctx?: TxContext): Promise<void> {
+    const db = this.getDb(ctx);
+    await db.delete(entityMedia).where(eq(entityMedia.entityId, entityId));
+  }
+
+  async removeAllMediaByAssetId(
+    mediaAssetId: string,
+    ctx?: TxContext,
+  ): Promise<void> {
+    const db = this.getDb(ctx);
+    await db
+      .delete(entityMedia)
+      .where(eq(entityMedia.mediaAssetId, mediaAssetId));
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Aggregates
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findAssetsForEntity(
+    entityId: string,
+    variantId?: string,
+    ctx?: TxContext,
+  ): Promise<MediaAsset[]> {
+    const associations = await this.findEntityMedia(entityId, variantId, ctx);
+    const assetIds = associations.map((a) => a.mediaAssetId);
+    if (assetIds.length === 0) return [];
+    return this.findAssetsByIds(assetIds, ctx);
+  }
+}

package/src/modules/media/schema.ts

@@ -0,0 +1,41 @@
+import { index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema.js";
+import { sellableEntities, variants } from "../catalog/schema.js";
+
+export const mediaAssets = pgTable(
+  "media_assets",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    storageKey: text("storage_key").notNull(),
+    filename: text("filename").notNull(),
+    contentType: text("content_type").notNull(),
+    size: integer("size").notNull(),
+    width: integer("width"),
+    height: integer("height"),
+    alt: text("alt"),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+    uploadedAt: timestamp("uploaded_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => ({
+    orgIdx: index("idx_media_assets_org").on(table.organizationId),
+  }),
+);
+
+export const entityMedia = pgTable("entity_media", {
+  entityId: uuid("entity_id")
+    .references(() => sellableEntities.id, { onDelete: "cascade" })
+    .notNull(),
+  variantId: uuid("variant_id").references(() => variants.id, {
+    onDelete: "cascade",
+  }),
+  mediaAssetId: uuid("media_asset_id")
+    .references(() => mediaAssets.id, { onDelete: "cascade" })
+    .notNull(),
+  role: text("role", {
+    enum: ["primary", "gallery", "thumbnail", "video", "document"],
+  }).notNull(),
+  sortOrder: integer("sort_order").notNull().default(0),
+});

package/src/modules/media/service.ts

@@ -0,0 +1,237 @@
+import { resolveOrgId } from "../../auth/org.js";
+import type { Actor } from "../../auth/types.js";
+import type { CommerceConfig } from "../../config/types.js";
+import type { StorageAdapter, StoredFile } from "./adapter.js";
+import { Err, Ok, type Result } from "../../kernel/result.js";
+import {
+  CommerceNotFoundError,
+  CommerceValidationError,
+} from "../../kernel/errors.js";
+import type { MediaRepository } from "./repository/index.js";
+import type { CatalogRepository } from "../catalog/repository/index.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import { makeId } from "../../utils/id.js";
+
+export interface UploadMediaInput {
+  filename: string;
+  contentType: string;
+  data: ArrayBuffer;
+  alt?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AttachMediaInput {
+  entityId: string;
+  mediaAssetId: string;
+  role: "primary" | "gallery" | "thumbnail" | "video" | "document";
+  variantId?: string;
+  sortOrder?: number;
+}
+
+interface MediaServiceDeps {
+  repository: MediaRepository;
+  catalogRepository: CatalogRepository;
+  storage: StorageAdapter;
+  config: CommerceConfig;
+}
+
+const DEFAULT_ALLOWED_MIME_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "application/pdf",
+];
+
+function isSvgOrXml(buffer: Uint8Array): boolean {
+  const prefix = new TextDecoder()
+    .decode(buffer.slice(0, 256))
+    .trimStart()
+    .toLowerCase();
+  return prefix.startsWith("<?xml") || prefix.startsWith("<svg");
+}
+
+export function detectMimeFromBuffer(buffer: Uint8Array): string | null {
+  if (buffer.length >= 8 &&
+    buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47 &&
+    buffer[4] === 0x0d && buffer[5] === 0x0a && buffer[6] === 0x1a && buffer[7] === 0x0a
+  ) return "image/png";
+
+  if (buffer.length >= 3 &&
+    buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff
+  ) return "image/jpeg";
+
+  if (buffer.length >= 6 &&
+    buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38 &&
+    (buffer[4] === 0x37 || buffer[4] === 0x39) && buffer[5] === 0x61
+  ) return "image/gif";
+
+  if (buffer.length >= 12 &&
+    buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 &&
+    buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50
+  ) return "image/webp";
+
+  if (buffer.length >= 4 &&
+    buffer[0] === 0x25 && buffer[1] === 0x50 && buffer[2] === 0x44 && buffer[3] === 0x46
+  ) return "application/pdf";
+
+  return null;
+}
+
+export class MediaService {
+  private readonly repo: MediaRepository;
+  private readonly catalogRepo: CatalogRepository;
+
+  constructor(private deps: MediaServiceDeps) {
+    this.repo = deps.repository;
+    this.catalogRepo = deps.catalogRepository;
+  }
+
+  async upload(
+    input: UploadMediaInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ id: string; url: string }>> {
+    if (!input.filename || !input.contentType) {
+      return Err(
+        new CommerceValidationError("filename and contentType are required."),
+      );
+    }
+
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const bytes = new Uint8Array(input.data);
+    const detectedMime = detectMimeFromBuffer(bytes);
+    const allowSvg = this.deps.config.media?.allowSvg === true;
+    const allowedMimeTypes = this.deps.config.media?.allowedMimeTypes ?? DEFAULT_ALLOWED_MIME_TYPES;
+    if (isSvgOrXml(bytes) && !allowSvg) {
+      return Err(new CommerceValidationError("SVG uploads are disabled."));
+    }
+    if (detectedMime && input.contentType !== detectedMime) {
+      return Err(
+        new CommerceValidationError(
+          `Content type mismatch — declared ${input.contentType}, detected ${detectedMime}.`,
+        ),
+      );
+    }
+    const effectiveMime = detectedMime ?? input.contentType;
+    if (!allowedMimeTypes.includes(effectiveMime)) {
+      return Err(
+        new CommerceValidationError(`Unsupported content type: ${effectiveMime}.`),
+      );
+    }
+
+    const id = makeId();
+    const key = `${new Date().getFullYear()}/${id}-${input.filename}`;
+    const uploaded = await this.deps.storage.upload(
+      key,
+      input.data,
+      effectiveMime,
+    );
+    if (!uploaded.ok) return uploaded as Result<never>;
+
+    await this.repo.createAsset(
+      {
+        organizationId: orgId,
+        id,
+        storageKey: key,
+        filename: input.filename,
+        contentType: effectiveMime,
+        size: input.data.byteLength,
+        metadata: input.metadata ?? {},
+        uploadedAt: new Date(),
+        ...(input.alt !== undefined ? { alt: input.alt } : {}),
+      },
+      ctx,
+    );
+
+    const url = await this.deps.storage.getUrl(key);
+    if (!url.ok) return url as Result<never>;
+
+    return Ok({ id, url: url.value });
+  }
+
+  // VAPT r2 (codex) finding: getUrl/getSignedUrl/delete loaded media by
+  // global id with no actor/org filter even though the repo accepts orgId.
+  // A tenant who knew or guessed a media UUID could read or delete another
+  // tenant's assets — same class as the prior catalog CRITICAL-2 fix.
+  // All three now resolve the actor's org and pass it to findAssetById,
+  // and delete additionally requires the actor to pass cross-tenant
+  // ownership (any actor without *:* must be in the asset's org).
+  async getUrl(
+    id: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<string>> {
+    const orgId = resolveOrgId(actor ?? null);
+    const asset = await this.repo.findAssetById(id, ctx, orgId);
+    if (!asset) return Err(new CommerceNotFoundError("Media asset not found."));
+    return this.deps.storage.getUrl(asset.storageKey);
+  }
+
+  async getSignedUrl(
+    id: string,
+    expiresIn = 60 * 15,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<string>> {
+    const orgId = resolveOrgId(actor ?? null);
+    const asset = await this.repo.findAssetById(id, ctx, orgId);
+    if (!asset) return Err(new CommerceNotFoundError("Media asset not found."));
+    return this.deps.storage.getSignedUrl(asset.storageKey, expiresIn);
+  }
+
+  async delete(
+    id: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const orgId = resolveOrgId(actor ?? null);
+    const asset = await this.repo.findAssetById(id, ctx, orgId);
+    if (!asset) return Err(new CommerceNotFoundError("Media asset not found."));
+
+    const deleted = await this.deps.storage.delete(asset.storageKey);
+    if (!deleted.ok) return deleted;
+
+    await this.repo.removeAllMediaByAssetId(id, ctx);
+    await this.repo.deleteAsset(id, ctx);
+    return Ok(undefined);
+  }
+
+  async list(prefix = ""): Promise<Result<StoredFile[]>> {
+    const listed = await this.deps.storage.list(prefix);
+    if (!listed.ok) return listed;
+    return Ok(listed.value);
+  }
+
+  async attachToEntity(
+    input: AttachMediaInput,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<void>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const entity = await this.catalogRepo.findEntityById(input.entityId, ctx, orgId);
+    if (!entity) {
+      return Err(new CommerceNotFoundError("Entity not found."));
+    }
+
+    const asset = await this.repo.findAssetById(input.mediaAssetId, ctx, orgId);
+    if (!asset) {
+      return Err(new CommerceNotFoundError("Media asset not found."));
+    }
+
+    await this.repo.createEntityMedia(
+      {
+        entityId: input.entityId,
+        mediaAssetId: input.mediaAssetId,
+        role: input.role,
+        sortOrder: input.sortOrder ?? 0,
+        ...(input.variantId !== undefined
+          ? { variantId: input.variantId }
+          : {}),
+      },
+      ctx,
+    );
+
+    return Ok(undefined);
+  }
+}

package/src/modules/orders/module.ts

@@ -0,0 +1,66 @@
+import type { CommerceConfig } from "../../config/types.js";
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
+import { defineModule } from "../../kernel/module/index.js";
+import { extendOrderStateMachine } from "../../kernel/state-machine/machine.js";
+import type { CartService } from "../cart/service.js";
+import type { FulfillmentService } from "../fulfillment/service.js";
+import type { InventoryService } from "../inventory/service.js";
+import type { PaymentsService } from "../payments/service.js";
+import type { PricingService } from "../pricing/service.js";
+import type { PromotionService } from "../promotions/service.js";
+import type { TaxService } from "../tax/service.js";
+import { OrdersRepository } from "./repository/index.js";
+import {
+  orderLineItems,
+  orders,
+  orderStatusHistory,
+} from "./schema.js";
+import { OrderService } from "./service.js";
+
+type OrdersModuleDeps = {
+  cart: CartService;
+  inventory: InventoryService;
+  payments: PaymentsService;
+  pricing: PricingService;
+  promotions: PromotionService;
+  fulfillment: FulfillmentService;
+  tax: TaxService;
+};
+
+export const ordersModule = defineModule<
+  {
+    orders: typeof orders;
+    orderLineItems: typeof orderLineItems;
+    orderStatusHistory: typeof orderStatusHistory;
+  },
+  OrderService,
+  OrdersModuleDeps
+>({
+  id: "orders",
+  dependencies: [
+    "cart",
+    "inventory",
+    "payments",
+    "pricing",
+    "promotions",
+    "fulfillment",
+    "tax",
+  ],
+  schema: () => ({ orders, orderLineItems, orderStatusHistory }),
+  service: (deps) => {
+    const config = deps.config as CommerceConfig;
+    return new OrderService({
+      repository: new OrdersRepository(deps.db.db as DrizzleDatabase),
+      hooks: deps.hooks,
+      services: deps.services,
+      database: deps.db,
+      ...(config.orders?.customTransitions
+        ? {
+            stateMachine: extendOrderStateMachine(
+              config.orders.customTransitions,
+            ),
+          }
+        : {}),
+    });
+  },
+});