@pintahub/database-schemas 4.3.7 → 4.3.8

package/CLAUDE.md

@@ -0,0 +1,174 @@
+# @pintahub/database-schemas
+
+Shared Mongoose schema definitions for PintaHub microservices. This package is the single source of truth for all MongoDB data models — services import schemas from here to ensure consistency.
+
+## Usage
+
+This package is used via the **schemis** library — it does not work standalone.
+
+### Database Connection Setup
+
+```js
+// src/connections/database.js
+const {createConnection, createStore} = require('schemis')
+const schemas = require('@pintahub/database-schemas')
+
+const uri = process.env.MONGODB_URI || 'mongodb://localhost:27017/dev'
+const connection = createConnection(uri)
+
+const store = createStore({
+    connection,
+    schemas
+})
+
+module.exports = store
+```
+
+### Using Models in Actions
+
+```js
+const {getModel} = require('../../connections/database')
+
+const Product = getModel('Product')
+
+// Standard Mongoose operations
+const product = await Product.findOne({_id: productId, store: storeId}).lean()
+await Product.updateOne({_id: productId}, {$set: {status: 'active', updated_at: Date.now()}})
+```
+
+### Populate with Explicit Model
+
+```js
+const {getModel} = require('../../connections/database')
+
+const TransferJob = getModel('TransferJob')
+const Product = getModel('Product')
+const Store = getModel('Store')
+
+const items = await TransferJob
+    .find({store: storeId})
+    .populate({path: 'product', model: Product, select: {title: 1, code: 1}})
+    .populate({path: 'destination_store', model: Store, select: {name: 1}})
+    .lean()
+```
+
+## Dependencies
+
+- **mongoose** `^9.1.3` (peer dependency)
+- **schemis** `^2.0.2` — used by consumers to create database store and register models from schemas
+
+## Directory Structure
+
+```
+schemas/              # Main schema files (~60 schemas)
+schemas/types/        # Embedded sub-document types (BrandSettings, FacebookObject, etc.)
+schemas/products/     # Product-specific embedded types (MediaObject, SeoObject, VideoObject)
+index.js              # Exports path to schemas/ directory
+```
+
+## Schema Catalog
+
+### 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
+
+### 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
+- **ProductProfile** — Per-product-type settings (features_html, ship_from)
+- **ProductImport** — Import job tracking (url, platform, status)
+- **Customize** — Product customization config
+- **CustomField** — Dynamic fields for customization
+
+### 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
+
+### 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)
+
+### Content & Pages
+- **Page** — Static pages (handle, title, body_html)
+- **Post** — Blog posts (title, body_html, excerpt, author, tags, SEO)
+- **Menu** / **MenuItem** — Navigation menus (hierarchical via parent ref)
+- **AnnouncementBar** — Store banner announcements
+
+### 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
+
+### 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
+
+### Short URLs
+- **ShortUrl** — Short links (slug + domain, clicks_count)
+- **ShortDomain** — Short link domains
+- **ShortLog** — Click tracking for short URLs
+- **LogURL** — General URL logging
+
+### Jobs & Events
+- **ExportJob** — Data export jobs (status, path_file)
+- **TransferJob** — Product transfer between stores
+- **WebhookEvent** — Webhook event queue (TTL: 2 days)
+
+### Settings & Config
+- **StoreSetting** — Store configuration (brand, logo, socials, integrations)
+- **BlockedLocation** — Geographic blocking rules
+- **Publication** — Product publication channels
+- **ShopifyObject** — Synced Shopify data
+
+### 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/)
+
+BrandSettings, DMCASetting, FacebookObject, FooterSetting, FreeShippingSetting, GoogleAnalytics, KlaviyoObject, MerchizeSettings, SocialsObject, TopBarSettings, TrustpilotObject
+
+## Conventions
+
+- Each schema file exports a Mongoose Schema (not a Model) — consumers register models themselves
+- All schemas with store data include a `store` ref field indexed for query performance
+- Timestamps: most schemas use `created_at` / `updated_at` fields (not Mongoose timestamps option)
+- Status fields use string enums (e.g., `'active'|'inactive'`, `'pending'|'completed'|'failed'`)
+- Embedded types in `schemas/types/` and `schemas/products/` have `{ _id: false }`
+- TTL indexes are used for ephemeral data (events, webhooks, page tracking)
+- Text indexes exist on Product (title, alternative_title, code, tags) and Order (name, id, email, phone)
+- Consumers use `schemis` to create a store: `createStore({connection, schemas})` → `store.getModel('Name')`
+- Use `.lean()` for read-only queries (returns plain objects instead of Mongoose documents)
+- Use `.populate()` with explicit `model` parameter for references
+- Use `Promise.all()` for parallel queries (e.g., fetch + countDocuments)
+- Multi-tenancy: most queries filter by `store` field

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pintahub/database-schemas",
-  "version": "4.3.7",
+  "version": "4.3.8",
   "description": "",
   "main": "index.js",
   "scripts": {
@@ -15,7 +15,8 @@
   "license": "ISC",
   "homepage": "https://gitlab.com/pintahub/packages/database-schemas#readme",
   "peerDependencies": {
-    "mongoose": "^9.1.3"
+    "mongoose": "^9.1.3",
+    "schemis": "^2.0.2"
   },
   "devDependencies": {
     "mongoose": "^9.1.3"