@pintahub/database-schemas 4.5.0 → 4.6.0

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -68,96 +68,46 @@ index.js              # Exports path to schemas/ directory
 
 ## Schema Catalog
 
+> Field-level documentation is in JSDoc comments within each schema file. This catalog provides a quick overview.
+
 ### Accounts & Auth
-- **Account** — Seller accounts (email, password, role, status)
-- **User** — User-to-Store relationship (refs: store, account)
-- **Store** — Main store entity (subdomain, primary_domain, status, users[])
-- **Shop** — Shop within a Store (handle, products_count)
-- **ShopifyAPI** — Shopify API credentials per store
+Account, User, Store, Shop, ShopifyAPI
 
 ### Products
-- **Product** — Core product (title, handle, status, price_range, tags, collections). Full-text index on title/alternative_title/code/tags
-- **ProductFeature** — Extended details (body_html, size_guide, shipping_time, video)
-- **ProductImage** — Product images with dimensions and upload status
-- **ProductRaw** — Raw synced product data from source platforms
-- **ProductType** — Product type classification
-- **ProductTag** — Tag with aggregated counts
-- **ProductImport** — Import job tracking (url, platform, status)
-- **Customize** — Product customization config
-- **CustomField** — Dynamic fields for customization
+Product, ProductFeature, ProductImage, ProductRaw, ProductType, ProductTag, ProductImport, Customize, CustomField
 
 ### Collections & Groups
-- **Collection** — Product collections (title, handle, SEO, featured_image)
-- **Group** — Product grouping/bundles (items_count, style, tags)
-- **GroupItem** — Items within a group (refs: group, product)
-- **GroupArtwork** — Artwork assigned to groups
+Collection, Group, GroupItem, GroupArtwork
 
 ### Orders & Fulfillment
-- **Order** — Orders (shipping_address, fulfillment_status, financial_status, total_price). Full-text index on name/id/email/phone
-- **OrderItem** — Line items (quantity, price, variant info)
-- **Fulfillment** — Shipment tracking (tracking_number, tracking_url)
-- **Payout** — Payment payouts (net amount, status, type)
+Order, OrderItem, Fulfillment, Payout
 
 ### Content & Pages
-- **Post** — Blog posts (title, body_html, excerpt, author, tags, SEO)
-- **Menu** / **MenuItem** — Navigation menus (hierarchical via parent ref)
-- **AnnouncementBar** — Store banner announcements
+Post, Menu, MenuItem, AnnouncementBar
 
 ### Media & Assets
-- **Image** — Stored images (path, dimension, mimetype, size)
-- **Artwork** — Design artwork uploads with processing status
-- **Media** — General media files
-- **MediaUpload** — Media upload tracking per product
+Image, Artwork, Media, MediaUpload
 
 ### Analytics & Tracking
-- **StoreEvent** — Store activity events (TTL index on created_at)
-- **LatestEvent** — Latest event snapshots (TTL: 30 days)
-- **RecentView** — Recently viewed products (TTL: 90 days)
-- **SearchTerm** — Search term tracking
-- **FavoriteItem** — Favorited products per session
-- **TrackPage** — Page access logs (TTL: 7 days)
-- **MarketingCost** — Ad campaign cost tracking per product
+StoreEvent, LatestEvent, RecentView, SearchTerm, FavoriteItem, TrackPage, MarketingCost
 
 ### Short URLs
-- **ShortUrl** — Short links (slug + domain, clicks_count)
-- **ShortDomain** — Short link domains
-- **ShortLog** — Click tracking for short URLs
-- **LogURL** — General URL logging
+ShortUrl, ShortDomain, ShortLog, LogURL
 
 ### Jobs & Events
-- **ExportJob** — Data export jobs (status, path_file)
-- **TransferJob** — Product transfer between stores
-- **WebhookEvent** — Webhook event queue (TTL: 2 days)
+ExportJob, TransferJob, WebhookEvent
 
 ### Settings & Config
-- **StoreSetting** — Store configuration (brand, logo, socials, integrations)
-- **BlockedLocation** — Geographic blocking rules
-- **Publication** — Product publication channels
-- **ShopifyObject** — Synced Shopify data
+StoreSetting, BlockedLocation, Publication, ShopifyObject
 
 ### Reports
-- **CreatorReport** — Monthly creator performance report per store (account ref, period "YYYY-MM", orders_count, items_sold, revenue, ads_spent, profit, status: active|completed|deleted, last_aggregated_at)
+CreatorReport, ProductReport
 
 ### Reviews
-- **Review** — Product reviews (vote_value, content, country_code, source)
-
-## Common Embedded Types
-
-Used as sub-documents across multiple schemas:
-
-| Type | Fields | Used In |
-|------|--------|---------|
-| **MoneyObject** | amount, currency (default: 'USD') | Order, OrderItem, Payout, MarketingCost |
-| **ImageObject** | id, altText, url, width, height | Product, Collection, Post, StoreSetting |
-| **DimensionObject** | width, height | Image, ProductImage |
-| **SeoObject** | title, description | Collection, ProductRaw |
-| **VideoObject** | id, url, width, height, mime_type | ProductFeature |
-| **MediaObject** | id, url, alt_text, width, height, mime_type, content_type | ProductRaw |
-| **PriceRange** | minVariantPrice, maxVariantPrice | Product |
-
-### Store Setting Types (schemas/types/)
+Review
 
-BrandSettings, DMCASetting, FacebookObject, FooterSetting, FreeShippingSetting, GoogleAnalytics, KlaviyoObject, MerchizeSettings, SocialsObject, TopBarSettings, TrustpilotObject
+### Embedded Types (schemas/types/, schemas/products/)
+MoneyObject, ImageObject, DimensionObject, PriceRange, SeoObject, VideoObject, MediaObject, BrandSettings, DMCASetting, FacebookObject, FooterSetting, FreeShippingSetting, GoogleAnalytics, KlaviyoObject, MerchizeSettings, SocialsObject, TopBarSettings, TrustpilotObject
 
 ## Conventions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pintahub/database-schemas",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "",
   "main": "index.js",
   "scripts": {

package/schemas/Account.js

@@ -1,36 +1,43 @@
 const {Schema} = require('mongoose')
 
 
+/** Seller account with authentication credentials and role */
 const Account = new Schema({
+    /** Display name */
     name: {
         type: String,
         trim: true,
         index: true
     },
 
+    /** Login email address */
     email: {
         type: String,
         trim: true,
         required: true
     },
 
+    /** Hashed password */
     password: {
         type: String,
         trim: true
     },
 
+    /** Account role, e.g. 'seller', 'admin' */
     role: {
         type: String,
         trim: true,
         default: 'seller'
     },
 
+    /** Whether this account is a creator */
     is_creator: {
         type: Boolean,
         default: false,
         index: true
     },
 
+    /** Account status, e.g. 'active', 'inactive' */
     status: {
         type: String,
         trim: true,
@@ -38,20 +45,24 @@ const Account = new Schema({
         default: 'active'
     },
 
+    /** Last time the account was active */
     last_active_at: {
         type: Date
     },
 
+    /** Linked advertising account IDs */
     ad_accounts: {
         type: [String],
         default: []
     },
 
+    /** Last update timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Record creation timestamp */
     created_at: {
         type: Date,
         default: Date.now
@@ -59,4 +70,3 @@ const Account = new Schema({
 })
 
 module.exports = Account
-

package/schemas/AnnouncementBar.js

@@ -1,13 +1,16 @@
 const {Schema} = require('mongoose')
 
 
+/** Store banner announcement displayed to visitors */
 const AnnouncementBar = new Schema({
+    /** @ref Store */
     store: {
         type: Schema.Types.ObjectId,
         index: true,
         required: true,
     },
 
+    /** Announcement identifier */
     id: {
         type: String,
         trim: true,
@@ -15,49 +18,58 @@ const AnnouncementBar = new Schema({
         index: true,
     },
 
+    /** Announcement name */
     name: {
         type: String,
         trim: true,
         required: true,
     },
 
+    /** Placement zone on the page */
     zone: {
         type: String,
         trim: true,
         required: true,
     },
 
+    /** Banner display text */
     content: {
         type: String,
         trim: true,
     },
 
+    /** CTA button text */
     action_text: {
         type: String,
         trim: true,
     },
 
+    /** CTA button link */
     action_url: {
         type: String,
         trim: true,
     },
 
+    /** CTA button tooltip */
     action_title: {
         type: String,
         trim: true,
     },
 
+    /** Shopify sync identifier */
     sync_id: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Last update timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Record creation timestamp */
     created_at: {
         type: Date,
         default: Date.now
@@ -65,4 +77,3 @@ const AnnouncementBar = new Schema({
 })
 
 module.exports = AnnouncementBar
-

package/schemas/Artwork.js

@@ -1,38 +1,46 @@
 const {Schema} = require('mongoose')
 
 
+/** Design artwork upload with processing status */
 const Artwork = new Schema({
+    /** @ref Store */
     store: {
         type: Schema.Types.ObjectId,
         index: true,
         required: true,
     },
 
+    /** Public URL of the artwork */
     url: {
         type: String,
         trim: true,
     },
 
+    /** Storage file path */
     path_file: {
         type: String,
         trim: true,
     },
 
+    /** MIME type, e.g. 'image/png' */
     mimetype: {
         type: String,
         trim: true,
     },
 
+    /** File size in bytes */
     size: {
         type: Number,
     },
 
+    /** Storage zone: 'internal' or external */
     zone: {
         type: String,
         trim: true,
         default: 'internal',
     },
 
+    /** Processing status, e.g. 'pending', 'completed', 'failed' */
     status: {
         type: String,
         trim: true,
@@ -40,21 +48,25 @@ const Artwork = new Schema({
         index: true,
     },
 
+    /** Dominant color extracted from artwork */
     color: {
         type: String,
         trim: true,
     },
 
+    /** Processing retry count */
     attempts: {
         type: Number,
         default: 0,
     },
 
+    /** Last update timestamp */
     updated_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Record creation timestamp */
     created_at: {
         type: Date,
         default: Date.now
@@ -62,4 +74,3 @@ const Artwork = new Schema({
 })
 
 module.exports = Artwork
-

package/schemas/BlockedLocation.js

@@ -1,13 +1,16 @@
 const {Schema} = require('mongoose')
 
 
+/** Geographic blocking rule for a store */
 const BlockedLocation = new Schema({
+    /** @ref Store */
     store: {
         type: Schema.Types.ObjectId,
         required: true,
         index: true,
     },
 
+    /** Blocking level, e.g. 'country' */
     type: {
         type: String,
         required: true,
@@ -15,17 +18,20 @@ const BlockedLocation = new Schema({
         default: 'country'
     },
 
+    /** Blocked value, e.g. country code 'US', 'VN' */
     value: {
         type: String,
         required: true,
         index: true,
     },
 
+    /** Last update timestamp */
     updated_at: {
         type: Date,
         default: Date.now,
     },
 
+    /** Record creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,

package/schemas/Collection.js

@@ -2,27 +2,33 @@ const {Schema} = require('mongoose')
 const ImageObject = require('./ImageObject')
 
 
+/** Embedded SEO metadata */
 const SeoObject = new Schema({
     _id: false,
 
+    /** Display title */
     title: {
         type: String,
         trim: true,
     },
 
+    /** Description */
     description: {
         type: String,
         trim: true,
     },
 })
 
+/** Product collection for organizing and grouping products */
 const Collection = new Schema({
+    /** @ref Store */
     store: {
         type: Schema.Types.ObjectId,
         required: true,
         index: true,
     },
 
+    /** Shopify collection ID */
     id: {
         type: String,
         trim: true,
@@ -30,17 +36,20 @@ const Collection = new Schema({
         index: true,
     },
 
+    /** Display title */
     title: {
         type: String,
         trim: true,
     },
 
+    /** Internal collection code */
     code: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Collection status, e.g. 'active', 'inactive' */
     status: {
         type: String,
         trim: true,
@@ -49,6 +58,7 @@ const Collection = new Schema({
         index: true,
     },
 
+    /** Visibility on storefront: 'visible' or 'hidden' */
     visibility: {
         type: String,
         trim: true,
@@ -56,73 +66,87 @@ const Collection = new Schema({
         default: 'visible',
     },
 
+    /** Alternative/secondary title */
     alternative_title: {
         type: String,
         trim: true,
     },
 
+    /** URL-friendly slug */
     handle: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Featured image */
     featured_image: {
         type: ImageObject,
     },
 
+    /** Description */
     description: {
         type: String,
         trim: true,
     },
 
+    /** HTML-formatted description */
     description_html: {
         type: String,
         trim: true,
     },
 
+    /** Number of products */
     products_count: {
         type: Number,
         index: true,
     },
 
+    /** Display this collection on homepage */
     show_on_homepage: {
         type: Boolean,
         default: false,
         index: true
     },
 
+    /** Last Shopify sync timestamp */
     last_synced_at: {
         type: Date,
         default: Date.now
     },
 
+    /** Include sensitive/adult products in this collection */
     show_sensitive_products: {
         type: Boolean,
         default: false,
     },
 
+    /** Product display mode for this collection */
     show_items_mode: {
         type: String,
         trim: true,
         default: ''
     },
 
+    /** SEO metadata */
     seo: {
         type: SeoObject,
     },
 
+    /** Shopify sync identifier */
     sync_id: {
         type: String,
         trim: true,
         index: true,
     },
 
+    /** Last update timestamp */
     updated_at: {
         type: Date,
         default: Date.now,
     },
 
+    /** Record creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,

package/schemas/CreatorReport.js

@@ -4,28 +4,38 @@ const MoneyObject = require('./MoneyObject')
 
 const AdAccountStat = new Schema({
     _id: false,
+    /** Display name */
     name: {
         type: String,
         trim: true,
     },
+    /** Ad account cost */
     cost: {
         type: MoneyObject,
     }
 })
 
+/**
+ * Monthly creator performance report per store.
+ * Aggregated by a daily schedule job for the current month (status: active).
+ * When the month ends, status transitions to "completed".
+ */
 const CreatorReport = new Schema({
+    /** @ref Store */
     store: {
         type: Schema.Types.ObjectId,
         index: true,
         required: true,
     },
 
+    /** @ref Account — the creator account */
     account: {
         type: Schema.Types.ObjectId,
         index: true,
         required: true,
     },
 
+    /** Monthly period in "YYYY-MM" format, e.g. "2026-04" */
     period: {
         type: String,
         trim: true,
@@ -33,39 +43,52 @@ const CreatorReport = new Schema({
         index: true,
     },
 
+    /** Total number of orders in this period */
     orders_count: {
         type: Number,
         default: 0,
     },
 
+    /** Total quantity of items sold */
     items_sold: {
         type: Number,
         default: 0,
     },
 
+    /** Total revenue */
     revenue: {
         type: MoneyObject,
     },
 
+    /** Total advertising spend */
     ads_spent: {
         type: MoneyObject,
     },
 
+    /** Net profit (revenue - ads_spent - costs) */
     profit: {
         type: MoneyObject,
     },
 
+    /** Per-ad-account cost breakdown */
     ad_accounts: {
         type: [AdAccountStat],
         default: [],
     },
 
+    /** Campaign IDs excluded from aggregation */
     exclude_campaigns: {
         type: [String],
         trim: true,
         default: []
     },
 
+    /**
+     * Report lifecycle status:
+     * - active: current month, updated daily by schedule
+     * - completed: past month, finalized
+     * - deleted: soft-deleted
+     */
     status: {
         type: String,
         trim: true,
@@ -74,6 +97,12 @@ const CreatorReport = new Schema({
         index: true,
     },
 
+    /**
+     * Aggregation job status:
+     * - pending: not yet processed
+     * - processing: aggregation in progress
+     * - completed: aggregation finished
+     */
     aggregation_status: {
         type: String,
         trim: true,
@@ -81,21 +110,25 @@ const CreatorReport = new Schema({
         enum: ['pending', 'processing', 'completed'],
     },
 
+    /** Admin notes */
     note: {
         type: String,
         trim: true,
     },
 
+    /** Timestamp of the last successful aggregation run */
     last_aggregated_at: {
         type: Date,
         index: true,
     },
 
+    /** Last update timestamp */
     updated_at: {
         type: Date,
         default: Date.now,
     },
 
+    /** Record creation timestamp */
     created_at: {
         type: Date,
         default: Date.now,