@pintahub/database-schemas 4.7.0 → 4.7.2

package/CLAUDE.md

@@ -1,125 +1,34 @@
-# @pintahub/database-schemas
+# CLAUDE.md — @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.
+Shared Mongoose schema package for PintaHub microservices. See [README.md](./README.md) for package overview, install, usage examples, full schema catalog, and conventions.
 
-## Usage
+This file contains only the rules Claude needs to edit safely. Do not duplicate README content here.
 
-This package is used via the **schemis** library — it does not work standalone.
+## Editing rules
 
-### Database Connection Setup
+- **CommonJS only.** This codebase uses `require` / `module.exports`. Do **not** convert to ES modules — overrides the global "prefer ES modules" preference.
+- **Export Schema, not Model.** Each file in `schemas/` exports a `new Schema({...})` instance. Consumers register models themselves through `schemis`.
+- **JSDoc every field.** Use `/** ... */` immediately above each field — this is the documentation source of truth (no separate docs site).
+- **Embedded sub-documents** declared in `schemas/types/`, `schemas/products/`, or co-located in `schemas/` (e.g. `MoneyObject`) must be created with `{_id: false}`.
+- **Multi-tenancy.** Domain schemas keep an indexed `store` ObjectId ref. When adding a new schema with tenant data, include `store: {type: Schema.Types.ObjectId, ref: 'Store', index: true}`.
+- **Timestamps.** Use explicit `created_at` / `updated_at` Date fields. Do **not** add Mongoose's `timestamps: true` option — it breaks consistency with the rest of the codebase.
+- **Indexes.**
+  - Default to `index: true` on the field for single-field indexes.
+  - Use `Schema.index({...})` at the bottom of the file for compound or text indexes.
+  - **Do not add a B-tree index for fields whose only purpose is Atlas Search** — Atlas Search uses its own Lucene index, and a redundant B-tree wastes write throughput.
+- **No schema-level pre/post hooks** unless explicitly requested. Compute logic happens at the consumer write-path so behavior is visible to service authors.
+- **Version bump on every schema change.** See README "Versioning". Update `package.json` in the same commit:
+  - new field / new schema / new index → minor
+  - rename / remove / type change → major
+  - JSDoc-only → patch
 
-```js
-// src/connections/database.js
-const {createConnection, createStore} = require('schemis')
-const schemas = require('@pintahub/database-schemas')
+## Project context
 
-const uri = process.env.MONGODB_URI || 'mongodb://localhost:27017/dev'
-const connection = createConnection(uri)
+- **Atlas Search migration in progress** for `storefront-api` product search (replacing the legacy `$text` index on Product). The legacy text index stays in place until the migration is complete.
+- **`Product.display_title`** (added 2026-04-17) is the precomputed `alternative_title || title` value used by Atlas Search and frontend display. Consumer services set it at write time — do not add a schema hook for it.
 
-const store = createStore({
-    connection,
-    schemas
-})
+## Common tasks
 
-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
-
-> Field-level documentation is in JSDoc comments within each schema file. This catalog provides a quick overview.
-
-### Accounts & Auth
-Account, User, Store, Shop, ShopifyAPI
-
-### Products
-Product, ProductFeature, ProductImage, ProductRaw, ProductType, ProductTag, ProductImport, Customize, CustomField
-
-### Collections & Groups
-Collection, Group, GroupItem, GroupArtwork
-
-### Orders & Fulfillment
-Order, OrderItem, Fulfillment, Payout
-
-### Content & Pages
-Post, Menu, MenuItem, AnnouncementBar
-
-### Media & Assets
-Image, Artwork, Media, MediaUpload
-
-### Analytics & Tracking
-StoreEvent, LatestEvent, RecentView, SearchTerm, FavoriteItem, TrackPage, MarketingCost
-
-### Short URLs
-ShortUrl, ShortDomain, ShortLog, LogURL
-
-### Jobs & Events
-ExportJob, TransferJob, WebhookEvent
-
-### Settings & Config
-StoreSetting, BlockedLocation, Publication, ShopifyObject
-
-### Reports
-CreatorReport, ProductReport
-
-### Reviews
-Review
-
-### 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
-
-- 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
+- **Add a field to an existing schema:** edit the schema file, add JSDoc + field def, bump `package.json` minor, commit.
+- **Add a new schema:** create `schemas/<Name>.js` exporting `new Schema({...})`, follow conventions above, bump minor.
+- **Add an index:** prefer `index: true` on the field; use `Schema.index({...})` for compound/text indexes; never duplicate Atlas Search coverage.

package/README.md

@@ -1 +1,150 @@
 # @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.
+
+## Installation
+
+```bash
+yarn add @pintahub/database-schemas
+```
+
+Peer dependencies (must be installed by the consumer):
+
+- `mongoose` `^9.1.3`
+- `schemis` `^2.0.2`
+
+## Usage
+
+This package does not work standalone — it ships raw schemas that are registered through the [`schemis`](https://www.npmjs.com/package/schemis) library.
+
+### 1. Set up the database store
+
+```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
+```
+
+### 2. Use models in actions
+
+```js
+const {getModel} = require('../../connections/database')
+
+const Product = getModel('Product')
+
+const product = await Product.findOne({_id: productId, store: storeId}).lean()
+await Product.updateOne(
+    {_id: productId},
+    {$set: {status: 'active', updated_at: Date.now()}}
+)
+```
+
+### 3. Populate references 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()
+```
+
+## Directory Structure
+
+```
+schemas/              # Main schema files (~60 schemas)
+schemas/types/        # Embedded sub-document types (BrandSettings, FacebookObject, …)
+schemas/products/     # Product-specific embedded types (MediaObject, SeoObject, VideoObject)
+index.js              # Exports the absolute path to schemas/ for schemis to load
+```
+
+## Schema Catalog
+
+> Field-level documentation lives in JSDoc comments inside each schema file. This catalog is a quick map.
+
+### Accounts & Auth
+Account, User, Store, Shop, ShopifyAPI
+
+### Products
+Product, ProductFeature, ProductImage, ProductRaw, ProductType, ProductTag, ProductImport, Customize, CustomField, FieldSetting
+
+### Collections & Groups
+Collection, Group, GroupItem, GroupArtwork
+
+### Orders & Fulfillment
+Order, OrderItem, Fulfillment, Payout
+
+### Content & Pages
+Post, Menu, MenuItem, AnnouncementBar
+
+### Media & Assets
+Image, Artwork, Media, MediaUpload
+
+### Analytics & Tracking
+StoreEvent, LatestEvent, RecentView, SearchTerm, FavoriteItem, TrackPage, MarketingCost
+
+### Short URLs
+ShortUrl, ShortDomain, ShortLog, LogURL
+
+### Jobs & Events
+ExportJob, TransferJob, WebhookEvent
+
+### Settings & Config
+StoreSetting, BlockedLocation, Publication, ShopifyObject
+
+### Reports
+CreatorReport, ProductReport
+
+### Reviews
+Review
+
+### Embedded Types
+`schemas/types/`: BrandSettings, DMCASetting, FacebookObject, FooterSetting, FreeShippingSetting, GoogleAnalytics, KlaviyoObject, MerchizeSettings, SocialsObject, TopBarSettings, TrustpilotObject
+
+`schemas/products/`: MediaObject, SeoObject, VideoObject
+
+`schemas/` (root, embedded): MoneyObject, ImageObject, DimensionObject, PriceRange, FieldSetting
+
+## Conventions
+
+- Each schema file exports a Mongoose **Schema** (not a Model) — consumers register models themselves via `schemis`.
+- Multi-tenancy: most domain schemas include a `store` ObjectId ref, indexed for query performance.
+- Timestamps: schemas use explicit `created_at` / `updated_at` Date fields (not Mongoose's `timestamps` option).
+- Status fields use string enums (e.g. `'active'|'inactive'`, `'pending'|'completed'|'failed'`).
+- Embedded types in `schemas/types/` and `schemas/products/` are declared with `{_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`).
+- The Product schema also exposes a precomputed `display_title` field (`alternative_title || title`) for storefront search/display. Consumer services are responsible for setting it at write time.
+
+## Querying Tips
+
+- Use `.lean()` for read-only queries — returns plain objects instead of Mongoose documents.
+- Use `.populate()` with an explicit `model` parameter when crossing collections.
+- Use `Promise.all()` for independent queries (e.g. `find` + `countDocuments`).
+- Always filter by `store` for multi-tenant data.
+
+## Versioning
+
+This package follows semver:
+
+- **Patch** — JSDoc / docs only.
+- **Minor** — new fields, new schemas, new indexes (backward compatible).
+- **Major** — removing/renaming fields or schemas, changing field types, breaking index changes.
+
+Bump the version in `package.json` whenever a schema change is committed.

package/package.json

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

package/.claude/settings.local.json

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