@porulle/core 0.10.8 → 0.13.0

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

@@ -1,4 +1,4 @@
-import { eq, and, inArray, type SQL } from "drizzle-orm";
+import { eq, and, asc, count, desc, gt, inArray, isNull, lt, max, ne, or, type SQL } from "drizzle-orm";
 import type { TxContext } from "../../../kernel/database/tx-context.js";
 import { CommerceNotFoundError } from "../../../kernel/errors.js";
 import type {
@@ -9,15 +9,21 @@ import {
   sellableEntities,
   sellableAttributes,
   sellableCustomFields,
+  entityFieldDefinitions,
   categories,
   entityCategories,
   brands,
   entityBrands,
+  entityTags,
   optionTypes,
   optionValues,
   variants,
   variantOptionValues,
+  sellableEntityRevisions,
+  catalogFieldOwnership,
+  type SellableEntityRevisionSnapshot,
 } from "../schema.js";
+import { entityMedia } from "../../media/schema.js";
 
 // Infer types from Drizzle schema
 export type SellableEntity = typeof sellableEntities.$inferSelect;
@@ -27,6 +33,8 @@ export type SellableAttributeInsert = typeof sellableAttributes.$inferInsert;
 export type SellableCustomField = typeof sellableCustomFields.$inferSelect;
 export type SellableCustomFieldInsert =
   typeof sellableCustomFields.$inferInsert;
+export type EntityFieldDefinitionRecord = typeof entityFieldDefinitions.$inferSelect;
+export type EntityFieldDefinitionInsert = typeof entityFieldDefinitions.$inferInsert;
 export type Category = typeof categories.$inferSelect;
 export type CategoryInsert = typeof categories.$inferInsert;
 export type EntityCategory = typeof entityCategories.$inferSelect;
@@ -43,6 +51,14 @@ export type Variant = typeof variants.$inferSelect;
 export type VariantInsert = typeof variants.$inferInsert;
 export type VariantOptionValue = typeof variantOptionValues.$inferSelect;
 export type VariantOptionValueInsert = typeof variantOptionValues.$inferInsert;
+export type SellableEntityRevision = typeof sellableEntityRevisions.$inferSelect;
+export type SellableEntityRevisionInsert = typeof sellableEntityRevisions.$inferInsert;
+export type CatalogFieldOwnership = typeof catalogFieldOwnership.$inferSelect;
+export type CatalogFieldOwnershipInsert = typeof catalogFieldOwnership.$inferInsert;
+export type ProposedCustomField = SellableCustomField & {
+  entitySlug: string;
+  entityType: string;
+};
 
 /**
  * CatalogRepository provides type-safe database operations for catalog entities.
@@ -108,6 +124,7 @@ export class CatalogRepository {
     filter?: {
       type?: string;
       status?: string;
+      isVisible?: boolean;
       ids?: string[];
     },
     ctx?: TxContext,
@@ -123,6 +140,9 @@ export class CatalogRepository {
         eq(sellableEntities.status, filter.status as SellableEntity["status"]),
       );
     }
+    if (filter?.isVisible !== undefined) {
+      conditions.push(eq(sellableEntities.isVisible, filter.isVisible));
+    }
     if (filter?.ids && filter.ids.length > 0) {
       conditions.push(inArray(sellableEntities.id, filter.ids));
     }
@@ -165,6 +185,247 @@ export class CatalogRepository {
     return result.length > 0;
   }
 
+  async findFieldOwnership(
+    entityId: string,
+    ctx?: TxContext,
+    storeId?: string,
+  ): Promise<CatalogFieldOwnership[]> {
+    const db = this.getDb(ctx);
+    const conditions = [eq(catalogFieldOwnership.entityId, entityId)];
+    if (storeId !== undefined) {
+      conditions.push(or(isNull(catalogFieldOwnership.storeId), eq(catalogFieldOwnership.storeId, storeId))!);
+    }
+    return db
+      .select()
+      .from(catalogFieldOwnership)
+      .where(and(...conditions))
+      .orderBy(asc(catalogFieldOwnership.fieldPath), asc(catalogFieldOwnership.updatedAt));
+  }
+
+  async findFieldOwnershipForResolution(
+    entityId: string,
+    storeId: string,
+    variantId: string | null,
+    ctx?: TxContext,
+  ): Promise<CatalogFieldOwnership[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(catalogFieldOwnership)
+      .where(and(
+        eq(catalogFieldOwnership.entityId, entityId),
+        or(isNull(catalogFieldOwnership.storeId), eq(catalogFieldOwnership.storeId, storeId)),
+        variantId == null
+          ? isNull(catalogFieldOwnership.variantId)
+          : or(isNull(catalogFieldOwnership.variantId), eq(catalogFieldOwnership.variantId, variantId)),
+      ));
+  }
+
+  async upsertFieldOwnership(
+    data: CatalogFieldOwnershipInsert,
+    ctx?: TxContext,
+  ): Promise<CatalogFieldOwnership> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .insert(catalogFieldOwnership)
+      .values(data)
+      .onConflictDoUpdate({
+        target: [
+          catalogFieldOwnership.organizationId,
+          catalogFieldOwnership.entityId,
+          catalogFieldOwnership.variantId,
+          catalogFieldOwnership.storeId,
+          catalogFieldOwnership.fieldPath,
+        ],
+        set: {
+          owner: data.owner,
+          updatedAt: data.updatedAt ?? new Date(),
+        },
+      })
+      .returning();
+    return rows[0]!;
+  }
+
+  async seedFieldOwnership(
+    data: CatalogFieldOwnershipInsert[],
+    ctx?: TxContext,
+  ): Promise<void> {
+    if (data.length === 0) return;
+    const db = this.getDb(ctx);
+    await db.insert(catalogFieldOwnership).values(data).onConflictDoNothing();
+  }
+
+  async findRevisionsByEntityId(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<SellableEntityRevision[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(sellableEntityRevisions)
+      .where(eq(sellableEntityRevisions.entityId, entityId))
+      .orderBy(asc(sellableEntityRevisions.revision));
+  }
+
+  async findRevisionMarkers(
+    entityId: string,
+    since?: Date,
+    ctx?: TxContext,
+  ): Promise<Array<Pick<SellableEntityRevision, "createdAt" | "reason">>> {
+    const db = this.getDb(ctx);
+    return db
+      .select({
+        createdAt: sellableEntityRevisions.createdAt,
+        reason: sellableEntityRevisions.reason,
+      })
+      .from(sellableEntityRevisions)
+      .where(and(
+        eq(sellableEntityRevisions.entityId, entityId),
+        ...(since ? [gt(sellableEntityRevisions.createdAt, since)] : []),
+      ))
+      .orderBy(asc(sellableEntityRevisions.createdAt));
+  }
+
+  async findLatestRevision(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<SellableEntityRevision | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(sellableEntityRevisions)
+      .where(eq(sellableEntityRevisions.entityId, entityId))
+      .orderBy(desc(sellableEntityRevisions.revision))
+      .limit(1);
+    return rows[0];
+  }
+
+  async findRevisionById(
+    entityId: string,
+    id: string,
+    ctx?: TxContext,
+  ): Promise<SellableEntityRevision | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(sellableEntityRevisions)
+      .where(
+        and(
+          eq(sellableEntityRevisions.entityId, entityId),
+          eq(sellableEntityRevisions.id, id),
+        ),
+      );
+    return rows[0];
+  }
+
+  async createRevision(
+    data: Omit<SellableEntityRevisionInsert, "id" | "revision" | "pinned">,
+    ctx?: TxContext,
+  ): Promise<SellableEntityRevision> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select({ revision: max(sellableEntityRevisions.revision) })
+      .from(sellableEntityRevisions)
+      .where(eq(sellableEntityRevisions.entityId, data.entityId));
+    const revision = (rows[0]?.revision ?? 0) + 1;
+    const inserted = await db
+      .insert(sellableEntityRevisions)
+      .values({
+        ...data,
+        revision,
+        pinned: revision === 1,
+      })
+      .returning();
+    return inserted[0]!;
+  }
+
+  async updateRevision(
+    id: string,
+    data: Partial<Pick<SellableEntityRevisionInsert, "createdAt" | "pinned">>,
+    ctx?: TxContext,
+  ): Promise<SellableEntityRevision | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(sellableEntityRevisions)
+      .set(data)
+      .where(eq(sellableEntityRevisions.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async deleteRevisionsOlderThan(
+    organizationId: string,
+    cutoff: Date,
+    ctx?: TxContext,
+  ): Promise<number> {
+    const db = this.getDb(ctx);
+    const deleted = await db
+      .delete(sellableEntityRevisions)
+      .where(
+        and(
+          eq(sellableEntityRevisions.organizationId, organizationId),
+          lt(sellableEntityRevisions.createdAt, cutoff),
+          eq(sellableEntityRevisions.pinned, false),
+          gt(sellableEntityRevisions.revision, 1),
+        ),
+      )
+      .returning({ id: sellableEntityRevisions.id });
+    return deleted.length;
+  }
+
+  async snapshotEntity(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<SellableEntityRevisionSnapshot> {
+    const entity = await this.findEntityById(entityId, ctx);
+    if (!entity) throw new CommerceNotFoundError("Entity not found.");
+    const [attributes, customFields, categoriesForEntity, brandsForEntity, media, tagsForEntity] = await Promise.all([
+      this.findAttributesByEntityId(entityId, ctx),
+      this.findAllCustomFieldsByEntityId(entityId, ctx),
+      this.findEntityCategories(entityId, ctx),
+      this.findEntityBrands(entityId, ctx),
+      this.findEntityMedia(entityId, ctx),
+      this.findEntityTags(entityId, ctx),
+    ]);
+    return {
+      entity: entity as unknown as Record<string, unknown>,
+      attributes: attributes.sort((a, b) => a.locale.localeCompare(b.locale) || a.id.localeCompare(b.id)) as unknown as Array<Record<string, unknown>>,
+      customFields: customFields.sort((a, b) => a.locale.localeCompare(b.locale) || a.fieldName.localeCompare(b.fieldName) || a.id.localeCompare(b.id)) as unknown as Array<Record<string, unknown>>,
+      media: media.sort((a, b) => a.mediaAssetId.localeCompare(b.mediaAssetId) || (a.variantId ?? "").localeCompare(b.variantId ?? "")) as unknown as Array<Record<string, unknown>>,
+      categories: categoriesForEntity.sort((a, b) => a.categoryId.localeCompare(b.categoryId)) as unknown as Array<Record<string, unknown>>,
+      brands: brandsForEntity.sort((a, b) => a.brandId.localeCompare(b.brandId)) as unknown as Array<Record<string, unknown>>,
+      tags: tagsForEntity.sort((a, b) => a.tagId.localeCompare(b.tagId)) as unknown as Array<Record<string, unknown>>,
+    };
+  }
+
+  async findEntityMedia(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<Array<typeof entityMedia.$inferSelect>> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(entityMedia)
+      .where(eq(entityMedia.entityId, entityId));
+  }
+
+  async deleteEntityMediaByEntityId(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<void> {
+    const db = this.getDb(ctx);
+    await db.delete(entityMedia).where(eq(entityMedia.entityId, entityId));
+  }
+
+  async createEntityMedia(
+    data: typeof entityMedia.$inferInsert,
+    ctx?: TxContext,
+  ): Promise<typeof entityMedia.$inferSelect> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(entityMedia).values(data).returning();
+    return rows[0]!;
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────
   // Sellable Attributes
   // ─────────────────────────────────────────────────────────────────────────────
@@ -252,6 +513,22 @@ export class CatalogRepository {
   async findCustomFieldsByEntityId(
     entityId: string,
     ctx?: TxContext,
+  ): Promise<SellableCustomField[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(sellableCustomFields)
+      .where(
+        and(
+          eq(sellableCustomFields.entityId, entityId),
+          eq(sellableCustomFields.status, "approved"),
+        ),
+      );
+  }
+
+  async findAllCustomFieldsByEntityId(
+    entityId: string,
+    ctx?: TxContext,
   ): Promise<SellableCustomField[]> {
     const db = this.getDb(ctx);
     return db
@@ -260,6 +537,137 @@ export class CatalogRepository {
       .where(eq(sellableCustomFields.entityId, entityId));
   }
 
+  async findProposedCustomField(
+    entityId: string,
+    fieldName: string,
+    locale = "en",
+    ctx?: TxContext,
+  ): Promise<SellableCustomField | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(sellableCustomFields)
+      .where(
+        and(
+          eq(sellableCustomFields.entityId, entityId),
+          eq(sellableCustomFields.fieldName, fieldName),
+          eq(sellableCustomFields.locale, locale),
+          eq(sellableCustomFields.status, "proposed"),
+        ),
+      )
+      .orderBy(desc(sellableCustomFields.createdAt), desc(sellableCustomFields.id))
+      .limit(1);
+    return rows[0];
+  }
+
+  async updateProposedCustomField(
+    id: string,
+    data: Partial<Omit<SellableCustomFieldInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<SellableCustomField | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(sellableCustomFields)
+      .set({ ...data, updatedAt: new Date() })
+      .where(
+        and(
+          eq(sellableCustomFields.id, id),
+          eq(sellableCustomFields.status, "proposed"),
+        ),
+      )
+      .returning();
+    return rows[0];
+  }
+
+  async rejectOtherProposedCustomFields(
+    entityId: string,
+    fieldName: string,
+    locale: string,
+    excludeId: string,
+    ctx?: TxContext,
+  ): Promise<number> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(sellableCustomFields)
+      .set({ status: "rejected", updatedAt: new Date() })
+      .where(
+        and(
+          eq(sellableCustomFields.entityId, entityId),
+          eq(sellableCustomFields.fieldName, fieldName),
+          eq(sellableCustomFields.locale, locale),
+          eq(sellableCustomFields.status, "proposed"),
+          ne(sellableCustomFields.id, excludeId),
+        ),
+      )
+      .returning({ id: sellableCustomFields.id });
+    return rows.length;
+  }
+
+  async listProposedCustomFields(
+    organizationId: string,
+    pagination: { page: number; limit: number },
+    filter?: { entityType?: string },
+    ctx?: TxContext,
+  ): Promise<{ items: ProposedCustomField[]; total: number }> {
+    const db = this.getDb(ctx);
+    const page = Math.max(1, pagination.page);
+    const limit = Math.max(1, pagination.limit);
+    const conditions: SQL[] = [
+      eq(sellableCustomFields.status, "proposed"),
+      eq(sellableEntities.organizationId, organizationId),
+    ];
+    if (filter?.entityType !== undefined) {
+      conditions.push(eq(sellableEntities.type, filter.entityType));
+    }
+    const where = and(...conditions);
+    const rows = await db
+      .select({
+        customField: sellableCustomFields,
+        entitySlug: sellableEntities.slug,
+        entityType: sellableEntities.type,
+      })
+      .from(sellableCustomFields)
+      .innerJoin(sellableEntities, eq(sellableCustomFields.entityId, sellableEntities.id))
+      .where(where)
+      .orderBy(asc(sellableCustomFields.createdAt), asc(sellableCustomFields.id))
+      .limit(limit)
+      .offset((page - 1) * limit);
+    const totalRows = await db
+      .select({ count: count() })
+      .from(sellableCustomFields)
+      .innerJoin(sellableEntities, eq(sellableCustomFields.entityId, sellableEntities.id))
+      .where(where);
+    return {
+      items: rows.map(({ customField, entitySlug, entityType }) => ({
+        ...customField,
+        entitySlug,
+        entityType,
+      })),
+      total: totalRows[0]?.count ?? 0,
+    };
+  }
+
+  async findCustomFieldByName(
+    entityId: string,
+    fieldName: string,
+    locale = "en",
+    ctx?: TxContext,
+  ): Promise<SellableCustomField | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(sellableCustomFields)
+      .where(
+        and(
+          eq(sellableCustomFields.entityId, entityId),
+          eq(sellableCustomFields.fieldName, fieldName),
+          eq(sellableCustomFields.locale, locale),
+          eq(sellableCustomFields.status, "approved"),
+        ),
+      );
+    return rows[0];
+  }
+
   async createCustomField(
     data: SellableCustomFieldInsert,
     ctx?: TxContext,
@@ -269,6 +677,54 @@ export class CatalogRepository {
     return rows[0]!;
   }
 
+  async updateCustomField(
+    id: string,
+    data: Partial<Omit<SellableCustomFieldInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<SellableCustomField | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(sellableCustomFields)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(sellableCustomFields.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async upsertCustomField(
+    entityId: string,
+    fieldName: string,
+    locale: string,
+    data: Omit<SellableCustomFieldInsert, "entityId" | "fieldName">,
+    ctx?: TxContext,
+  ): Promise<SellableCustomField> {
+    const existing = await this.findCustomFieldByName(entityId, fieldName, locale, ctx);
+    if (existing) {
+      const updated = await this.updateCustomField(existing.id, data, ctx);
+      return updated!;
+    }
+    return this.createCustomField({ ...data, entityId, fieldName, locale }, ctx);
+  }
+
+  async deleteCustomField(
+    entityId: string,
+    fieldName: string,
+    locale = "en",
+    ctx?: TxContext,
+  ): Promise<void> {
+    const db = this.getDb(ctx);
+    await db
+      .delete(sellableCustomFields)
+      .where(
+        and(
+          eq(sellableCustomFields.entityId, entityId),
+          eq(sellableCustomFields.fieldName, fieldName),
+          eq(sellableCustomFields.locale, locale),
+          eq(sellableCustomFields.status, "approved"),
+        ),
+      );
+  }
+
   async deleteCustomFieldsByEntityId(
     entityId: string,
     ctx?: TxContext,
@@ -279,6 +735,79 @@ export class CatalogRepository {
       .where(eq(sellableCustomFields.entityId, entityId));
   }
 
+  async findEntityFieldDefinitions(
+    organizationId: string,
+    entityType?: string,
+    ctx?: TxContext,
+  ): Promise<EntityFieldDefinitionRecord[]> {
+    const db = this.getDb(ctx);
+    const conditions = [eq(entityFieldDefinitions.organizationId, organizationId)];
+    if (entityType !== undefined) {
+      conditions.push(eq(entityFieldDefinitions.entityType, entityType));
+    }
+    return db
+      .select()
+      .from(entityFieldDefinitions)
+      .where(and(...conditions))
+      .orderBy(asc(entityFieldDefinitions.entityType), asc(entityFieldDefinitions.sortOrder), asc(entityFieldDefinitions.name));
+  }
+
+  async findActiveEntityFieldDefinitions(
+    organizationId: string,
+    entityType: string,
+    ctx?: TxContext,
+  ): Promise<EntityFieldDefinitionRecord[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(entityFieldDefinitions)
+      .where(
+        and(
+          eq(entityFieldDefinitions.organizationId, organizationId),
+          eq(entityFieldDefinitions.entityType, entityType),
+          eq(entityFieldDefinitions.status, "active"),
+        ),
+      )
+      .orderBy(asc(entityFieldDefinitions.sortOrder), asc(entityFieldDefinitions.name));
+  }
+
+  async findEntityFieldDefinitionById(
+    organizationId: string,
+    id: string,
+    ctx?: TxContext,
+  ): Promise<EntityFieldDefinitionRecord | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(entityFieldDefinitions)
+      .where(and(eq(entityFieldDefinitions.organizationId, organizationId), eq(entityFieldDefinitions.id, id)));
+    return rows[0];
+  }
+
+  async createEntityFieldDefinition(
+    data: EntityFieldDefinitionInsert,
+    ctx?: TxContext,
+  ): Promise<EntityFieldDefinitionRecord> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(entityFieldDefinitions).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateEntityFieldDefinition(
+    organizationId: string,
+    id: string,
+    data: Partial<Omit<EntityFieldDefinitionInsert, "id" | "organizationId">>,
+    ctx?: TxContext,
+  ): Promise<EntityFieldDefinitionRecord | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(entityFieldDefinitions)
+      .set({ ...data, updatedAt: new Date() })
+      .where(and(eq(entityFieldDefinitions.organizationId, organizationId), eq(entityFieldDefinitions.id, id)))
+      .returning();
+    return rows[0];
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────
   // Categories
   // ─────────────────────────────────────────────────────────────────────────────
@@ -286,12 +815,17 @@ export class CatalogRepository {
   async findCategoryById(
     id: string,
     ctx?: TxContext,
+    orgId?: string,
   ): Promise<Category | undefined> {
     const db = this.getDb(ctx);
     const rows = await db
       .select()
       .from(categories)
-      .where(eq(categories.id, id));
+      .where(
+        orgId
+          ? and(eq(categories.id, id), eq(categories.organizationId, orgId))
+          : eq(categories.id, id),
+      );
     return rows[0];
   }
 
@@ -438,9 +972,16 @@ export class CatalogRepository {
   // Brands
   // ─────────────────────────────────────────────────────────────────────────────
 
-  async findBrandById(id: string, ctx?: TxContext): Promise<Brand | undefined> {
+  async findBrandById(id: string, ctx?: TxContext, orgId?: string): Promise<Brand | undefined> {
     const db = this.getDb(ctx);
-    const rows = await db.select().from(brands).where(eq(brands.id, id));
+    const rows = await db
+      .select()
+      .from(brands)
+      .where(
+        orgId
+          ? and(eq(brands.id, id), eq(brands.organizationId, orgId))
+          : eq(brands.id, id),
+      );
     return rows[0];
   }
 
@@ -511,6 +1052,27 @@ export class CatalogRepository {
       .where(eq(entityBrands.entityId, entityId));
   }
 
+  async findEntityTags(
+    entityId: string,
+    ctx?: TxContext,
+  ): Promise<Array<typeof entityTags.$inferSelect>> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(entityTags)
+      .where(eq(entityTags.entityId, entityId));
+  }
+
+  async addEntityTag(entityId: string, tagId: string, ctx?: TxContext): Promise<void> {
+    const db = this.getDb(ctx);
+    await db.insert(entityTags).values({ entityId, tagId }).onConflictDoNothing();
+  }
+
+  async deleteEntityTagsByEntityId(entityId: string, ctx?: TxContext): Promise<void> {
+    const db = this.getDb(ctx);
+    await db.delete(entityTags).where(eq(entityTags.entityId, entityId));
+  }
+
   async addEntityToBrand(
     entityId: string,
     brandId: string,

package/src/modules/catalog/revision.ts

@@ -0,0 +1,35 @@
+import type { SellableEntityRevisionSnapshot } from "./schema.js";
+
+export function canonicalSerialize(value: unknown): string {
+  if (value instanceof Date) return JSON.stringify(value.toISOString());
+  if (Array.isArray(value)) return `[${value.map(canonicalSerialize).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalSerialize(record[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+// Row bookkeeping timestamps are excluded from comparison only at row roots,
+// never inside nested jsonb where a user key may share the same name.
+function stripRowTimestamps(row: Record<string, unknown>): Record<string, unknown> {
+  const { createdAt, updatedAt, ...rest } = row;
+  void createdAt;
+  void updatedAt;
+  return rest;
+}
+
+export function comparableSerialize(snapshot: SellableEntityRevisionSnapshot): string {
+  return canonicalSerialize({
+    entity: stripRowTimestamps(snapshot.entity),
+    attributes: snapshot.attributes.map(stripRowTimestamps),
+    customFields: snapshot.customFields.map(stripRowTimestamps),
+    media: snapshot.media.map(stripRowTimestamps),
+    categories: snapshot.categories.map(stripRowTimestamps),
+    brands: snapshot.brands.map(stripRowTimestamps),
+    tags: (snapshot.tags ?? []).map(stripRowTimestamps),
+  });
+}