@pintahub/database-schemas 5.8.0 → 6.0.1

package/dist/schemas/types/TrustpilotObject.d.ts

@@ -0,0 +1,31 @@
+import { Schema } from 'mongoose';
+/** Embedded Trustpilot review integration settings */
+declare const TrustpilotObject: Schema<any, import("mongoose").Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, import("mongoose").DefaultSchemaOptions, Record<string, any>, import("mongoose").Document<unknown, {}, Record<string, any>, {
+    id: string;
+}, import("mongoose").ResolveSchemaOptions<import("mongoose").DefaultSchemaOptions>> & Omit<Record<string, any> & Required<{
+    _id: unknown;
+}> & {
+    __v: number;
+}, "id"> & {
+    id: string;
+}, {
+    [path: string]: import("mongoose").SchemaDefinitionProperty<undefined, any, any>;
+} | {
+    [x: string]: import("mongoose").SchemaDefinitionProperty<any, any, import("mongoose").Document<unknown, {}, Record<string, any>, {
+        id: string;
+    }, import("mongoose").ResolveSchemaOptions<import("mongoose").DefaultSchemaOptions>> & Omit<Record<string, any> & Required<{
+        _id: unknown;
+    }> & {
+        __v: number;
+    }, "id"> & {
+        id: string;
+    }> | undefined;
+}, {
+    [x: string]: any;
+} & Required<{
+    _id: unknown;
+}> & {
+    __v: number;
+}>;
+export = TrustpilotObject;
+//# sourceMappingURL=TrustpilotObject.d.ts.map

package/dist/schemas/types/TrustpilotObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrustpilotObject.d.ts","sourceRoot":"","sources":["../../../src/schemas/types/TrustpilotObject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAA;AAC/B,sDAAsD;AACtD,QAAA,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBpB,CAAA;AAEF,SAAS,gBAAgB,CAAA"}

package/{schemas → dist/schemas}/types/TrustpilotObject.js

@@ -1,27 +1,23 @@
-const {Schema} = require('mongoose')
-
-
+"use strict";
+const mongoose_1 = require("mongoose");
 /** Embedded Trustpilot review integration settings */
-const TrustpilotObject = new Schema({
+const TrustpilotObject = new mongoose_1.Schema({
     _id: false,
-
     /** Trustpilot Business Unit ID */
     business_unit_id: {
         type: String,
         trim: true,
     },
-
     /** Review widget template ID */
     template_id: {
         type: String,
         trim: true,
     },
-
     /** Trustpilot profile URL */
     url: {
         type: String,
         trim: true,
     },
-})
-
-module.exports = TrustpilotObject
+});
+module.exports = TrustpilotObject;
+//# sourceMappingURL=TrustpilotObject.js.map

package/dist/schemas/types/TrustpilotObject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrustpilotObject.js","sourceRoot":"","sources":["../../../src/schemas/types/TrustpilotObject.ts"],"names":[],"mappings":";AAAA,uCAA+B;AAC/B,sDAAsD;AACtD,MAAM,gBAAgB,GAAG,IAAI,iBAAM,CAAsB;IACrD,GAAG,EAAE,KAAK;IAEV,kCAAkC;IAClC,gBAAgB,EAAE;QACd,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,IAAI;KACb;IAED,gCAAgC;IAChC,WAAW,EAAE;QACT,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,IAAI;KACb;IAED,6BAA6B;IAC7B,GAAG,EAAE;QACD,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,IAAI;KACb;CACJ,CAAC,CAAA;AAEF,iBAAS,gBAAgB,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+export type { IAccount } from './interfaces/Account';
+export type { IAnnouncementBar } from './interfaces/AnnouncementBar';
+export type { IArtwork } from './interfaces/Artwork';
+export type { IBlockedLocation } from './interfaces/BlockedLocation';
+export type { ICollection } from './interfaces/Collection';
+export type { ICreatorReport } from './interfaces/CreatorReport';
+export type { ICustomField } from './interfaces/CustomField';
+export type { ICustomize } from './interfaces/Customize';
+export type { IDimensionObject } from './interfaces/DimensionObject';
+export type { IExportJob } from './interfaces/ExportJob';
+export type { IFavoriteItem } from './interfaces/FavoriteItem';
+export type { IFieldSetting } from './interfaces/FieldSetting';
+export type { IFulfillment } from './interfaces/Fulfillment';
+export type { IGroup } from './interfaces/Group';
+export type { IGroupArtwork } from './interfaces/GroupArtwork';
+export type { IGroupItem } from './interfaces/GroupItem';
+export type { IImage } from './interfaces/Image';
+export type { IImageObject } from './interfaces/ImageObject';
+export type { ILatestEvent } from './interfaces/LatestEvent';
+export type { ILogURL } from './interfaces/LogURL';
+export type { IMarketingCost } from './interfaces/MarketingCost';
+export type { IMedia } from './interfaces/Media';
+export type { IMediaUpload } from './interfaces/MediaUpload';
+export type { IMenu } from './interfaces/Menu';
+export type { IMenuItem } from './interfaces/MenuItem';
+export type { IMoneyObject } from './interfaces/MoneyObject';
+export type { IOrder } from './interfaces/Order';
+export type { IOrderItem } from './interfaces/OrderItem';
+export type { IPayout } from './interfaces/Payout';
+export type { IPost } from './interfaces/Post';
+export type { IPriceRange } from './interfaces/PriceRange';
+export type { IProduct } from './interfaces/Product';
+export type { IProductFeature } from './interfaces/ProductFeature';
+export type { IProductImage } from './interfaces/ProductImage';
+export type { IProductImport } from './interfaces/ProductImport';
+export type { IProductRaw } from './interfaces/ProductRaw';
+export type { IProductReport } from './interfaces/ProductReport';
+export type { IProductTag } from './interfaces/ProductTag';
+export type { IProductType } from './interfaces/ProductType';
+export type { IPublication } from './interfaces/Publication';
+export type { IRecentView } from './interfaces/RecentView';
+export type { IRelatedProduct } from './interfaces/RelatedProduct';
+export type { IReview } from './interfaces/Review';
+export type { ISearchTerm } from './interfaces/SearchTerm';
+export type { IShop } from './interfaces/Shop';
+export type { IShopifyAPI } from './interfaces/ShopifyAPI';
+export type { IShopifyAPIRequest } from './interfaces/ShopifyAPIRequest';
+export type { IShopifyObject } from './interfaces/ShopifyObject';
+export type { IShortDomain } from './interfaces/ShortDomain';
+export type { IShortLog } from './interfaces/ShortLog';
+export type { IShortUrl } from './interfaces/ShortUrl';
+export type { IStore } from './interfaces/Store';
+export type { IStoreEvent } from './interfaces/StoreEvent';
+export type { IStoreSetting } from './interfaces/StoreSetting';
+export type { ITempUpload } from './interfaces/TempUpload';
+export type { ITrackPage } from './interfaces/TrackPage';
+export type { ITransferJob } from './interfaces/TransferJob';
+export type { IUser } from './interfaces/User';
+export type { IWebhookEvent } from './interfaces/WebhookEvent';
+export type { IMediaObject } from './interfaces/products/MediaObject';
+export type { ISeoObject } from './interfaces/products/SeoObject';
+export type { IVideoObject } from './interfaces/products/VideoObject';
+export type { IBrandSettings } from './interfaces/types/BrandSettings';
+export type { IDMCASetting } from './interfaces/types/DMCASetting';
+export type { IFacebookObject } from './interfaces/types/FacebookObject';
+export type { IFooterSetting } from './interfaces/types/FooterSetting';
+export type { IFreeShippingSetting } from './interfaces/types/FreeShippingSetting';
+export type { IGoogleAnalytics } from './interfaces/types/GoogleAnalytics';
+export type { IKlaviyoObject } from './interfaces/types/KlaviyoObject';
+export type { IMerchizeSettings } from './interfaces/types/MerchizeSettings';
+export type { ISocialsObject } from './interfaces/types/SocialsObject';
+export type { ITopBarSettings } from './interfaces/types/TopBarSettings';
+export type { ITrustpilotObject } from './interfaces/types/TrustpilotObject';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/contributing.md

@@ -0,0 +1,278 @@
+# Contributing — schemas, interfaces, and releases
+
+This is the editing guide for anyone adding fields, schemas, or indexes to `@pintahub/database-schemas`. Read [CLAUDE.md](../CLAUDE.md) for the short-form rules; this doc expands on the *why* and walks the common workflows.
+
+## Repo layout
+
+```
+src/
+├── index.ts                # public CJS entry — exports the path to dist/schemas
+├── types.ts                # public type re-exports — consumed via /types subpath
+├── interfaces/             # pure TypeScript types, no runtime
+│   ├── Order.ts            # export interface IOrder { … }
+│   ├── …
+│   ├── types/              # interfaces for embedded sub-schemas
+│   └── products/           # product-specific interface helpers
+└── schemas/                # Mongoose Schema runtime
+    ├── Order.ts            # export = new Schema({…})
+    ├── …
+    ├── types/              # embedded sub-schemas (BrandSettings, …)
+    └── products/           # product-specific embedded schemas
+
+dist/                       # compiled output (gitignored, but shipped to npm)
+scripts/
+├── convert.js              # one-off v5 → v6 converter, historical
+├── snapshot.js             # parity check against the legacy schemas/ folder
+└── smoke-schemas-ts.mts    # loads dist/ through schemas-ts to verify the bridge
+```
+
+## Editing rules (must-follow)
+
+These come from [CLAUDE.md](../CLAUDE.md). Repeated here so contributors see them in one place.
+
+- **CommonJS at runtime.** Each schema file uses `export = SchemaInstance`. TypeScript compiles this to `module.exports = SchemaInstance`, which is what both `schemis` (via `require`) and `schemas-ts` (via dynamic `import()` with `.default || .module.exports`) expect.
+- **Export Schema, not Model.** Never call `mongoose.model(...)` in this package. Consumers register models via their resolver.
+- **JSDoc every field.** A `/** ... */` block immediately above each field is the documentation source of truth. There is no separate docs site.
+- **Embedded sub-documents use `{_id: false}`.** Anything in `schemas/types/`, `schemas/products/`, or any inline embedded schema in `schemas/` must declare `_id: false`. Sub-docs are pure value objects; auto-generated `_id`s create churn on parent updates.
+- **Multi-tenant `store` ref.** Domain schemas keep an indexed `store: {type: Schema.Types.ObjectId, ref: 'Store', index: true}`. New tenant-scoped schemas must include it.
+- **Explicit timestamps.** Use `created_at` and `updated_at` as `Date` fields. **Do not** add Mongoose's `timestamps: true` option — historical writes in the codebase set these fields manually, and `timestamps: true` would silently overwrite them.
+- **No schema-level pre/post hooks** unless explicitly requested. Compute logic happens at the consumer write path so it's visible to service authors.
+
+## Index policy
+
+- Single-field index → put `index: true` on the field def.
+- Compound, text, partial, or TTL index → use `Schema.index({...}, {...})` at the **bottom** of the file.
+- Compound indexes should put the highest-selectivity field first (typically `store`).
+- **Do not add a B-tree index for fields whose only purpose is Atlas Search.** Atlas Search builds its own Lucene index; a duplicate B-tree just wastes write throughput.
+- Drop indexes that are superseded by a new compound index in the same PR. `git log` makes the intent clear.
+
+## Adding a field to an existing schema
+
+1. Open `src/schemas/<Name>.ts`. Add the field def with a `/** … */` block above it.
+2. Open `src/interfaces/<Name>.ts`. Add the matching field to the interface. Default to optional (`field?: T`) unless the field is required at insert time.
+3. If the field is a sub-document, reuse an existing embedded schema from `schemas/types/` or `schemas/products/` if one fits; otherwise add a new one (see below).
+4. Bump `package.json` — **minor** for any new field.
+5. Commit. The build runs in CI on tag publish, but locally you can run `yarn build` to sanity-check.
+
+Example diff:
+
+```ts
+// src/schemas/Store.ts
+/** Time the store was first set up (separate from created_at, which can be backdated for imports) */
+onboarded_at: {
+    type: Date,
+},
+```
+
+```ts
+// src/interfaces/Store.ts
+export interface IStore {
+    // …
+    onboarded_at?: Date
+}
+```
+
+## Adding a new schema
+
+1. Create `src/schemas/<Name>.ts`:
+
+   ```ts
+   import {Schema} from 'mongoose'
+
+   /** Top-of-file JSDoc describing the collection */
+   const MySchema = new Schema(<Record<string, any>>{
+       /** @ref Store */
+       store: {
+           type: Schema.Types.ObjectId,
+           ref: 'Store',
+           index: true,
+       },
+
+       /** Display name */
+       name: {
+           type: String,
+           trim: true,
+       },
+
+       /** Created timestamp — set by the service at write time */
+       created_at: {
+           type: Date,
+           default: Date.now,
+       },
+       updated_at: Date,
+   })
+
+   MySchema.index({store: 1, created_at: -1})
+
+   export = MySchema
+   ```
+
+   Notes:
+   - `<Record<string, any>>` on the schema definition silences Mongoose's strict shape-inference; the public type comes from the interface file.
+   - `export = MySchema` (not `export default`) — this compiles to `module.exports = MySchema`, which is what both resolvers expect.
+
+2. Create `src/interfaces/<Name>.ts`:
+
+   ```ts
+   import type {Types} from 'mongoose'
+
+   export interface IMy {
+       store: Types.ObjectId
+       name?: string
+       created_at?: Date
+       updated_at?: Date
+   }
+   ```
+
+   - The `store` ref is `Types.ObjectId` and **not** optional, because multi-tenant queries always require it.
+   - Other fields default to optional.
+
+3. Re-export the interface from `src/types.ts` (keep the file alphabetically sorted):
+
+   ```ts
+   export type {IMy} from './interfaces/My'
+   ```
+
+4. Bump `package.json` — **minor** for a new schema.
+
+5. Run `yarn build` and verify `dist/schemas/<Name>.js` exists and compiles.
+
+## Adding an embedded type
+
+Embedded types live in `src/schemas/types/` (generic) or `src/schemas/products/` (product-specific). They are reused across multiple parent schemas.
+
+```ts
+// src/schemas/types/Coordinates.ts
+import {Schema} from 'mongoose'
+
+/** Embedded geo coordinates */
+const Coordinates = new Schema(<Record<string, any>>{
+    _id: false,
+
+    /** Latitude, decimal degrees, WGS84 */
+    lat: {
+        type: Number,
+    },
+
+    /** Longitude, decimal degrees, WGS84 */
+    lng: {
+        type: Number,
+    },
+})
+
+export = Coordinates
+```
+
+```ts
+// src/interfaces/types/Coordinates.ts
+export interface ICoordinates {
+    lat?: number
+    lng?: number
+}
+```
+
+Re-export from `src/types.ts`. Use the embedded schema in parent schemas via `import = require('...')`:
+
+```ts
+// src/schemas/Store.ts
+import Coordinates = require('./types/Coordinates')
+
+const Store = new Schema(<Record<string, any>>{
+    // …
+    location: {
+        type: Coordinates,
+    },
+})
+```
+
+And on the interface side, reference the embedded type:
+
+```ts
+import type {ICoordinates} from './types/Coordinates'
+
+export interface IStore {
+    location?: ICoordinates
+}
+```
+
+## Versioning
+
+Semver, no exceptions:
+
+| Change                                                       | Bump  |
+| ------------------------------------------------------------ | ----- |
+| New field, new schema, new index (backward compatible)       | minor |
+| JSDoc/comment-only changes                                   | patch |
+| Renaming a field, removing a field/schema, changing a type   | major |
+| Removing/changing an existing index (writes behave differently) | major |
+| Build/format change (e.g. v6.0.0 TS rewrite)                 | major |
+
+Bump in the **same commit** as the change. If you forget, the publish will still go through but consumers won't know they need to update.
+
+## Build & verification
+
+```bash
+yarn install
+yarn build                          # tsc → dist/
+yarn dev                            # tsc --watch during development
+node scripts/snapshot.js            # diffs dist/schemas/ vs legacy schemas/ (when present)
+node --import tsx scripts/smoke-schemas-ts.mts
+                                    # loads dist/ through schemas-ts to verify the bridge works
+```
+
+The smoke script is the most useful check before publishing — it catches the case where a `export =` was accidentally changed to `export default`, which breaks `schemis`'s `require()` consumer.
+
+## Publishing
+
+The npm tarball is `dist/` only (see `"files": ["dist"]` in `package.json`). Make sure:
+
+1. `yarn build` produced a clean `dist/`.
+2. `package.json` version is bumped.
+3. Commit, tag, push. CI publishes on tag.
+
+Do **not** edit `dist/` directly. It is gitignored and regenerated on every build.
+
+## House style for JSDoc
+
+Field-level JSDoc is the doc site. Conventions:
+
+- Lead with what the field stores, not its type — the type is right there in the def.
+- For enums, list every legal value:
+
+  ```ts
+  /**
+   * Order status:
+   * - pending: awaiting payment
+   * - paid: payment captured
+   * - cancelled: cancelled by buyer or merchant
+   */
+  status: {
+      type: String,
+      enum: ['pending', 'paid', 'cancelled'],
+  },
+  ```
+
+- For ObjectId refs, use `@ref ModelName`:
+
+  ```ts
+  /** @ref Store */
+  store: {
+      type: Schema.Types.ObjectId,
+      ref: 'Store',
+      index: true,
+  },
+  ```
+
+- For TTL or partial indexes, document the rationale at the `Schema.index` call:
+
+  ```ts
+  // 60-day TTL — ShortLog entries are only interesting for the recent past.
+  ShortLog.index({created_at: 1}, {expireAfterSeconds: 60 * 24 * 60 * 60})
+  ```
+
+## Useful references
+
+- [usage-js.md](./usage-js.md) — consumer guide for CJS services
+- [usage-ts.md](./usage-ts.md) — consumer guide for TS services
+- [migration.md](./migration.md) — v5 → v6 upgrade walkthrough
+- [CLAUDE.md](../CLAUDE.md) — short-form rules (the one Claude reads)