@reactionary/core 0.0.37 → 0.0.39

package/index.js

@@ -4,7 +4,6 @@ export * from "./cache/redis-cache";
 export * from "./cache/noop-cache";
 export * from "./client/client";
 export * from "./client/client-builder";
-export * from "./decorators/trpc.decorators";
 export * from "./providers/analytics.provider";
 export * from "./providers/base.provider";
 export * from "./providers/cart.provider";
@@ -13,6 +12,7 @@ export * from "./providers/inventory.provider";
 export * from "./providers/price.provider";
 export * from "./providers/product.provider";
 export * from "./providers/search.provider";
+export * from "./providers/category.provider";
 export * from "./schemas/capabilities.schema";
 export * from "./schemas/session.schema";
 export * from "./schemas/models/base.model";
@@ -24,6 +24,7 @@ export * from "./schemas/models/inventory.model";
 export * from "./schemas/models/price.model";
 export * from "./schemas/models/product.model";
 export * from "./schemas/models/search.model";
+export * from "./schemas/models/category.model";
 export * from "./schemas/mutations/base.mutation";
 export * from "./schemas/mutations/cart.mutation";
 export * from "./schemas/mutations/identity.mutation";
@@ -31,10 +32,4 @@ export * from "./schemas/mutations/inventory.mutation";
 export * from "./schemas/mutations/price.mutation";
 export * from "./schemas/mutations/product.mutation";
 export * from "./schemas/mutations/search.mutation";
-export * from "./schemas/queries/base.query";
-export * from "./schemas/queries/cart.query";
-export * from "./schemas/queries/identity.query";
-export * from "./schemas/queries/inventory.query";
-export * from "./schemas/queries/price.query";
-export * from "./schemas/queries/product.query";
-export * from "./schemas/queries/search.query";
+export * from "./schemas/queries";

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@reactionary/core",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "main": "index.js",
   "types": "src/index.d.ts",
   "dependencies": {
     "zod": "4.0.0-beta.20250430T185432",
-    "@upstash/redis": "^1.34.9",
-    "reflect-metadata": "0.2.2"
+    "@upstash/redis": "^1.34.9"
   }
 }

package/providers/analytics.provider.js

@@ -1,5 +1,8 @@
 import { BaseProvider } from "./base.provider";
 class AnalyticsProvider extends BaseProvider {
+  getResourceName() {
+    return "analytics";
+  }
 }
 export {
   AnalyticsProvider

package/providers/base.provider.js

@@ -1,3 +1,4 @@
+import { createPaginatedResponseSchema } from "../schemas/models/base.model";
 class BaseProvider {
   constructor(schema, cache) {
     this.schema = schema;
@@ -20,10 +21,28 @@ class BaseProvider {
    * Handler for parsing a response from a remote provider and converting it
    * into the typed domain model.
    */
-  parseSingle(_body) {
+  parseSingle(_body, session) {
     const model = this.newModel();
     return this.assert(model);
   }
+  parsePaginatedResult(_body, session) {
+    return createPaginatedResponseSchema(this.schema).parse({});
+  }
+  generateCacheKeyPaginatedResult(resultSetName, res, session) {
+    const type = this.getResourceName();
+    const langPart = session.languageContext.locale;
+    const currencyPart = session.languageContext.currencyCode || "default";
+    const storePart = session.storeIdentifier?.key || "default";
+    return `${type}-${resultSetName}-paginated|pageNumber:${res.pageNumber}|pageSize:${res.pageSize}|store:${storePart}|lang:${langPart}|currency:${currencyPart}`;
+  }
+  generateCacheKeySingle(identifier, session) {
+    const type = this.getResourceName();
+    const idPart = Object.entries(identifier).map(([k, v]) => `${k}:${v.key}`).join("#");
+    const langPart = session.languageContext.locale;
+    const currencyPart = session.languageContext.currencyCode || "default";
+    const storePart = session.storeIdentifier?.key || "default";
+    return `${type}-${idPart}|store:${storePart}|lang:${langPart}|currency:${currencyPart}`;
+  }
 }
 export {
   BaseProvider

package/providers/cart.provider.js

@@ -1,5 +1,8 @@
 import { BaseProvider } from "./base.provider";
 class CartProvider extends BaseProvider {
+  getResourceName() {
+    return "cart";
+  }
 }
 export {
   CartProvider

package/providers/category.provider.js

@@ -0,0 +1,9 @@
+import { BaseProvider } from "./base.provider";
+class CategoryProvider extends BaseProvider {
+  getResourceName() {
+    return "category";
+  }
+}
+export {
+  CategoryProvider
+};

package/providers/identity.provider.js

@@ -1,5 +1,8 @@
 import { BaseProvider } from "./base.provider";
 class IdentityProvider extends BaseProvider {
+  getResourceName() {
+    return "identity";
+  }
 }
 export {
   IdentityProvider

package/providers/inventory.provider.js

@@ -1,5 +1,8 @@
 import { BaseProvider } from "./base.provider";
 class InventoryProvider extends BaseProvider {
+  getResourceName() {
+    return "inventory";
+  }
 }
 export {
   InventoryProvider

package/providers/price.provider.js

@@ -1,5 +1,31 @@
 import { BaseProvider } from "./base.provider";
 class PriceProvider extends BaseProvider {
+  /**
+   * Utility function to create an empty price result, with a value of -1.
+   * This is used when no price is found for a given SKU + currency combination.
+   * You should check for meta.placeholder to see if this is a real price or a placeholder.
+   * @param sku
+   * @param currency
+   * @returns
+   */
+  getEmptyPriceResult(sku, currency) {
+    const base = this.newModel();
+    base.identifier = {
+      sku: { key: sku }
+    };
+    base.unitPrice = {
+      value: -1,
+      currency
+    };
+    base.meta = {
+      cache: { hit: false, key: `price-${sku}-${currency}` },
+      placeholder: true
+    };
+    return this.assert(base);
+  }
+  getResourceName() {
+    return "price";
+  }
 }
 export {
   PriceProvider

package/providers/product.provider.js

@@ -1,5 +1,8 @@
 import { BaseProvider } from "./base.provider";
 class ProductProvider extends BaseProvider {
+  getResourceName() {
+    return "product";
+  }
 }
 export {
   ProductProvider

package/providers/search.provider.js

@@ -1,5 +1,8 @@
 import { BaseProvider } from "./base.provider";
 class SearchProvider extends BaseProvider {
+  getResourceName() {
+    return "product-search";
+  }
 }
 export {
   SearchProvider

package/schemas/capabilities.schema.js

@@ -6,7 +6,8 @@ const CapabilitiesSchema = z.looseInterface({
   identity: z.boolean(),
   cart: z.boolean(),
   inventory: z.boolean(),
-  price: z.boolean()
+  price: z.boolean(),
+  category: z.boolean()
 });
 export {
   CapabilitiesSchema

package/schemas/models/base.model.js

@@ -10,8 +10,31 @@ const MetaSchema = z.looseInterface({
 const BaseModelSchema = z.looseInterface({
   meta: MetaSchema.default(() => MetaSchema.parse({}))
 });
+const PaginationOptionsSchema = z.looseInterface({
+  pageNumber: z.number().default(1).describe("Current page number, starting from 1"),
+  pageSize: z.number().default(20).describe("Number of items per page")
+});
+function createPaginatedResponseSchema(itemSchema) {
+  return z.object({
+    meta: MetaSchema.default(() => MetaSchema.parse({})),
+    pageNumber: z.number().min(1).describe("Current page number, starting from 1"),
+    pageSize: z.number().min(1).max(50).describe("Number of items per page"),
+    totalCount: z.number().min(0).describe("Total number of items available"),
+    totalPages: z.number().min(0).describe("Total number of pages available"),
+    items: z.array(itemSchema)
+  });
+}
+const ImageSchema = z.looseInterface({
+  sourceUrl: z.string().default("").describe("The original source URL of the image. Pass this through your image resizing and transcoding service to get the desired size, and generate thumbnails as needed"),
+  altText: z.string().default("").describe("Alternative text for the image, for accessibility purposes. Must always be set, and non-empty"),
+  width: z.number().optional().describe("Width of the original image, in pixels, if known"),
+  height: z.number().optional().describe("Height of the original image, in pixels, if known")
+});
 export {
   BaseModelSchema,
   CacheInformationSchema,
-  MetaSchema
+  ImageSchema,
+  MetaSchema,
+  PaginationOptionsSchema,
+  createPaginatedResponseSchema
 };

package/schemas/models/cart.model.js

@@ -1,16 +1,37 @@
 import { z } from "zod";
 import { CartIdentifierSchema, CartItemIdentifierSchema, ProductIdentifierSchema } from "../models/identifiers.model";
 import { BaseModelSchema } from "./base.model";
+import { MonetaryAmountSchema } from "./price.model";
+const CostBreakDownSchema = z.looseObject({
+  totalTax: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The amount of tax paid on the cart. This may include VAT, GST, sales tax, etc."),
+  totalDiscount: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The amount of discount applied to the cart."),
+  totalSurcharge: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The amount of surcharge applied to the cart."),
+  totalShipping: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The amount of shipping fees for the cart."),
+  totalProductPrice: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The total price of products in the cart."),
+  grandTotal: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The total price for the cart including all taxes, discounts, and shipping.")
+});
+const ItemCostBreakdownSchema = z.looseObject({
+  unitPrice: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The price per single unit of the item."),
+  unitDiscount: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The discount applied per single unit of the item."),
+  totalPrice: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The total price for all units of the item."),
+  totalDiscount: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The total discount applied to all units of the item.")
+});
 const CartItemSchema = z.looseInterface({
   identifier: CartItemIdentifierSchema.default(() => CartItemIdentifierSchema.parse({})),
   product: ProductIdentifierSchema.default(() => ProductIdentifierSchema.parse({})),
-  quantity: z.number().default(0)
+  quantity: z.number().default(0),
+  price: ItemCostBreakdownSchema.default(() => ItemCostBreakdownSchema.parse({}))
 });
 const CartSchema = BaseModelSchema.extend({
   identifier: CartIdentifierSchema.default(() => CartIdentifierSchema.parse({})),
-  items: z.array(CartItemSchema).default(() => [])
+  items: z.array(CartItemSchema).default(() => []),
+  price: CostBreakDownSchema.default(() => CostBreakDownSchema.parse({})),
+  name: z.string().default(""),
+  description: z.string().default("")
 });
 export {
   CartItemSchema,
-  CartSchema
+  CartSchema,
+  CostBreakDownSchema,
+  ItemCostBreakdownSchema
 };

package/schemas/models/category.model.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { BaseModelSchema, createPaginatedResponseSchema, ImageSchema } from "./base.model";
+import { CategoryIdentifierSchema } from "./identifiers.model";
+const CategorySchema = BaseModelSchema.extend({
+  identifier: CategoryIdentifierSchema.default(() => CategoryIdentifierSchema.parse({})),
+  name: z.string().default(""),
+  slug: z.string().default(""),
+  text: z.string().default(""),
+  images: z.array(ImageSchema.required()).default(() => []),
+  parentCategory: CategoryIdentifierSchema.optional()
+});
+const CategoryPaginatedResultSchema = createPaginatedResponseSchema(CategorySchema);
+export {
+  CategoryPaginatedResultSchema,
+  CategorySchema
+};

package/schemas/models/identifiers.model.js

@@ -27,13 +27,30 @@ const CartItemIdentifierSchema = z.looseInterface({
 const PriceIdentifierSchema = z.looseInterface({
   sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({}))
 });
+const CategoryIdentifierSchema = z.looseInterface({
+  key: z.string().default("").nonoptional()
+});
+const WebStoreIdentifierSchema = z.looseInterface({
+  key: z.string().default("").nonoptional()
+});
+const InventoryChannelIdentifierSchema = z.looseInterface({
+  key: z.string().default("online").nonoptional()
+});
+const InventoryIdentifierSchema = z.looseInterface({
+  sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({})),
+  channelId: InventoryChannelIdentifierSchema.default(() => InventoryChannelIdentifierSchema.parse({}))
+});
 export {
   CartIdentifierSchema,
   CartItemIdentifierSchema,
+  CategoryIdentifierSchema,
   FacetIdentifierSchema,
   FacetValueIdentifierSchema,
+  InventoryChannelIdentifierSchema,
+  InventoryIdentifierSchema,
   PriceIdentifierSchema,
   ProductIdentifierSchema,
   SKUIdentifierSchema,
-  SearchIdentifierSchema
+  SearchIdentifierSchema,
+  WebStoreIdentifierSchema
 };

package/schemas/models/inventory.model.js

@@ -1,7 +1,11 @@
 import { z } from "zod";
 import { BaseModelSchema } from "./base.model";
+import { InventoryIdentifierSchema } from "./identifiers.model";
 const InventorySchema = BaseModelSchema.extend({
-  quantity: z.number().default(0)
+  identifier: InventoryIdentifierSchema.default(() => InventoryIdentifierSchema.parse({})),
+  sku: z.string().default(""),
+  quantity: z.number().default(0),
+  status: z.enum(["inStock", "outOfStock", "onBackOrder", "preOrder", "discontinued"]).default("inStock")
 });
 export {
   InventorySchema

package/schemas/models/price.model.js

@@ -3,14 +3,20 @@ import { BaseModelSchema } from "./base.model";
 import { PriceIdentifierSchema } from "./identifiers.model";
 import { CurrencySchema } from "./currency.model";
 const MonetaryAmountSchema = z.looseInterface({
-  cents: z.number().default(0).describe("The monetary amount in cent-precision."),
+  value: z.number().default(0).describe("The monetary amount in decimal-precision."),
   currency: CurrencySchema.default("XXX").describe("The currency associated with the amount, as a ISO 4217 standardized code.")
 });
+const TieredPriceSchema = z.looseObject({
+  minimumQuantity: z.number().default(0).describe("The minimum quantity required to be eligible for the tiered price."),
+  price: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe("The monetary amount for the tiered price.")
+});
 const PriceSchema = BaseModelSchema.extend({
   identifier: PriceIdentifierSchema.default(() => PriceIdentifierSchema.parse({})),
-  value: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({}))
+  unitPrice: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})),
+  tieredPrices: z.array(TieredPriceSchema).default(() => [])
 });
 export {
   MonetaryAmountSchema,
-  PriceSchema
+  PriceSchema,
+  TieredPriceSchema
 };

package/schemas/queries/category.query.js

@@ -0,0 +1,27 @@
+import z from "zod";
+import { CategoryIdentifierSchema } from "../models/identifiers.model";
+import { BaseQuerySchema } from "./base.query";
+import { PaginationOptionsSchema } from "../models/base.model";
+const CategoryQueryById = BaseQuerySchema.extend({
+  id: CategoryIdentifierSchema.default(() => CategoryIdentifierSchema.parse({}))
+});
+const CategoryQueryBySlug = BaseQuerySchema.extend({
+  slug: z.string().default("")
+});
+const CategoryQueryForBreadcrumb = BaseQuerySchema.extend({
+  id: CategoryIdentifierSchema.default(() => CategoryIdentifierSchema.parse({}))
+});
+const CategoryQueryForChildCategories = BaseQuerySchema.extend({
+  parentId: CategoryIdentifierSchema.default(() => CategoryIdentifierSchema.parse({})),
+  paginationOptions: PaginationOptionsSchema.default(() => PaginationOptionsSchema.parse({}))
+});
+const CategoryQueryForTopCategories = BaseQuerySchema.extend({
+  paginationOptions: PaginationOptionsSchema.default(() => PaginationOptionsSchema.parse({}))
+});
+export {
+  CategoryQueryById,
+  CategoryQueryBySlug,
+  CategoryQueryForBreadcrumb,
+  CategoryQueryForChildCategories,
+  CategoryQueryForTopCategories
+};

package/schemas/queries/index.js

@@ -0,0 +1,9 @@
+export * from "./analytics.query";
+export * from "./base.query";
+export * from "./cart.query";
+export * from "./category.query";
+export * from "./identity.query";
+export * from "./inventory.query";
+export * from "./price.query";
+export * from "./product.query";
+export * from "./search.query";

package/schemas/queries/inventory.query.js

@@ -1,8 +1,13 @@
 import { z } from "zod";
 import { BaseQuerySchema } from "./base.query";
-const InventoryQuerySchema = BaseQuerySchema.extend({
-  sku: z.string()
+import { ProductIdentifierSchema } from "../models/identifiers.model";
+const InventoryQueryBySKUSchema = BaseQuerySchema.extend({
+  query: z.literal("sku"),
+  sku: ProductIdentifierSchema.default(() => ProductIdentifierSchema.parse({}))
 });
+const InventoryQuerySchema = z.union([InventoryQueryBySKUSchema]);
+;
 export {
+  InventoryQueryBySKUSchema,
   InventoryQuerySchema
 };

package/schemas/session.schema.js

@@ -1,9 +1,19 @@
 import { z } from "zod";
 import { IdentitySchema } from "./models/identity.model";
+import { WebStoreIdentifierSchema } from "./models/identifiers.model";
+import { CurrencySchema } from "./models/currency.model";
+const LanguageContextSchema = z.looseObject({
+  locale: z.string().default("en-US"),
+  currencyCode: CurrencySchema.default(() => CurrencySchema.parse({})),
+  countryCode: z.string().default("US")
+});
 const SessionSchema = z.looseObject({
   id: z.string(),
-  identity: IdentitySchema.default(() => IdentitySchema.parse({}))
+  identity: IdentitySchema.default(() => IdentitySchema.parse({})),
+  languageContext: LanguageContextSchema.default(() => LanguageContextSchema.parse({})),
+  storeIdentifier: WebStoreIdentifierSchema.default(() => WebStoreIdentifierSchema.parse({}))
 });
 export {
+  LanguageContextSchema,
   SessionSchema
 };

package/src/client/client.d.ts

@@ -6,6 +6,7 @@ import { CartProvider } from "../providers/cart.provider";
 import { PriceProvider } from "../providers/price.provider";
 import { InventoryProvider } from "../providers/inventory.provider";
 import { Cache } from "../cache/cache.interface";
+import { CategoryProvider } from "../providers/category.provider";
 export interface Client {
     product: ProductProvider;
     search: SearchProvider;
@@ -15,6 +16,7 @@ export interface Client {
     analytics: Array<AnalyticsProvider>;
     price: PriceProvider;
     inventory: InventoryProvider;
+    category: CategoryProvider;
 }
 export interface BuildClientOptions {
     cache?: Cache;

package/src/index.d.ts

@@ -4,7 +4,6 @@ export * from './cache/redis-cache';
 export * from './cache/noop-cache';
 export * from './client/client';
 export * from './client/client-builder';
-export * from './decorators/trpc.decorators';
 export * from './providers/analytics.provider';
 export * from './providers/base.provider';
 export * from './providers/cart.provider';
@@ -13,6 +12,7 @@ export * from './providers/inventory.provider';
 export * from './providers/price.provider';
 export * from './providers/product.provider';
 export * from './providers/search.provider';
+export * from './providers/category.provider';
 export * from './schemas/capabilities.schema';
 export * from './schemas/session.schema';
 export * from './schemas/models/base.model';
@@ -24,6 +24,7 @@ export * from './schemas/models/inventory.model';
 export * from './schemas/models/price.model';
 export * from './schemas/models/product.model';
 export * from './schemas/models/search.model';
+export * from './schemas/models/category.model';
 export * from './schemas/mutations/base.mutation';
 export * from './schemas/mutations/cart.mutation';
 export * from './schemas/mutations/identity.mutation';
@@ -31,10 +32,4 @@ export * from './schemas/mutations/inventory.mutation';
 export * from './schemas/mutations/price.mutation';
 export * from './schemas/mutations/product.mutation';
 export * from './schemas/mutations/search.mutation';
-export * from './schemas/queries/base.query';
-export * from './schemas/queries/cart.query';
-export * from './schemas/queries/identity.query';
-export * from './schemas/queries/inventory.query';
-export * from './schemas/queries/price.query';
-export * from './schemas/queries/product.query';
-export * from './schemas/queries/search.query';
+export * from './schemas/queries';

package/src/providers/analytics.provider.d.ts

@@ -1,4 +1,5 @@
 import { AnalyticsEvent } from '../schemas/models/analytics.model';
 import { BaseProvider } from './base.provider';
 export declare abstract class AnalyticsProvider<T extends AnalyticsEvent = AnalyticsEvent> extends BaseProvider<T> {
+    protected getResourceName(): string;
 }

package/src/providers/base.provider.d.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
-import { BaseModel } from '../schemas/models/base.model';
+import { BaseModel, createPaginatedResponseSchema } from '../schemas/models/base.model';
 import { Cache } from '../cache/cache.interface';
+import { Session } from '../schemas/session.schema';
+import { IdentifierType } from '../schemas/models/identifiers.model';
 /**
  * Base capability provider, responsible for mutations (changes) and queries (fetches)
  * for a given business object domain.
@@ -22,5 +24,12 @@ export declare abstract class BaseProvider<T extends BaseModel = BaseModel> {
      * Handler for parsing a response from a remote provider and converting it
      * into the typed domain model.
      */
-    protected parseSingle(_body: unknown): T;
+    protected parseSingle(_body: unknown, session: Session): T;
+    protected parsePaginatedResult(_body: unknown, session: Session): z.infer<ReturnType<typeof createPaginatedResponseSchema<typeof this.schema>>>;
+    protected generateCacheKeyPaginatedResult(resultSetName: string, res: ReturnType<typeof this.parsePaginatedResult>, session: Session): string;
+    protected generateCacheKeySingle(identifier: IdentifierType, session: Session): string;
+    /**
+     * Returns the abstract resource name provided by the remote system.
+     */
+    protected abstract getResourceName(): string;
 }

package/src/providers/cart.provider.d.ts

@@ -8,4 +8,5 @@ export declare abstract class CartProvider<T extends Cart = Cart> extends BasePr
     abstract add(payload: CartMutationItemAdd, session: Session): Promise<T>;
     abstract remove(payload: CartMutationItemRemove, session: Session): Promise<T>;
     abstract changeQuantity(payload: CartMutationItemQuantityChange, session: Session): Promise<T>;
+    protected getResourceName(): string;
 }

package/src/providers/category.provider.d.ts

@@ -0,0 +1,67 @@
+import { Category } from "../schemas/models/category.model";
+import { CategoryQueryById, CategoryQueryBySlug, CategoryQueryForBreadcrumb, CategoryQueryForChildCategories, CategoryQueryForTopCategories } from "../schemas/queries/category.query";
+import { Session } from "../schemas/session.schema";
+import { BaseProvider } from "./base.provider";
+/**
+ * CategoryProvider
+ *
+ * This provider allows fetching of single or sets of categories.
+ *
+ * We only allow fetching one hierachy level at a time, for now. This is to avoid development patterns of "fetch 5000 categories in one go.."
+ *
+ */
+export declare abstract class CategoryProvider<T extends Category = Category> extends BaseProvider<T> {
+    /**
+     * Get a single category by its ID. Cannot return null, because HOW did you come across a categories ID that does not exist?
+     *
+     * DISCUSSION: What do you persist in, say, a CMS or Recommendation engine? The seo slug or the ID?
+     * We have previous discussed, that the ID is not necessarily the DATABASE id, but rather an externally unique identifier for the category.
+     *
+     * So, if you persist that externally, you could actually end up with an ID that does not exist in the current system.
+     *
+     * For now, the result will be en empty category, but we should probably throw an error instead.
+     *
+     * Use case: You have received a list of category ids from a recommendation engine, and you need to show a tile of this.
+     * Future optimization: getByIds(ids: CategoryIdentifier[], session: Session): Promise<T[]>
+     * @param id
+     * @param session
+     */
+    abstract getById(payload: CategoryQueryById, session: Session): Promise<T>;
+    /**
+     * Gets a single category by its seo slug
+     *
+     * Usecase: You are rendering a category page, and you have the slug from the URL.
+     * @param slug the slug
+     * @param session
+     */
+    abstract getBySlug(payload: CategoryQueryBySlug, session: Session): Promise<T | null>;
+    /**
+     * Gets the breadcrumb path to the category, i.e. all parents up to the root.
+     * The returned order is from root to leaf.
+     *
+     * Usecase: You are rendering a category or product page, and you need to show the breadcrumb path.
+     * @param id
+     * @param session
+     */
+    abstract getBreadcrumbPathToCategory(payload: CategoryQueryForBreadcrumb, session: Session): Promise<T[]>;
+    /**
+     * Finds all child categories of a given category.
+     *
+     * Usecase: You are rendering a top menu, or mega menu, and you need the show the child categories of a given category.
+     *
+     * NOTE: it is recommended to create a navigational service, that allows combining CMS and Static pages into this, rather than fetching categories directly.
+     *
+     * @param id The ID of the parent category.
+     * @param session The session information.
+     */
+    abstract findChildCategories(payload: CategoryQueryForChildCategories, session: Session): Promise<ReturnType<typeof this.parsePaginatedResult>>;
+    /**
+     * Returns all top categories, i.e. categories without a parent.
+     *
+     * Usecase: You are rendering a top menu, or mega menu, and you need the show the top level categories.
+     * @param paginationOptions
+     * @param session
+     */
+    abstract findTopCategories(payload: CategoryQueryForTopCategories, session: Session): Promise<ReturnType<typeof this.parsePaginatedResult>>;
+    protected getResourceName(): string;
+}

package/src/providers/identity.provider.d.ts

@@ -7,4 +7,5 @@ export declare abstract class IdentityProvider<T extends Identity = Identity> ex
     abstract getSelf(payload: IdentityQuerySelf, session: Session): Promise<T>;
     abstract login(payload: IdentityMutationLogin, session: Session): Promise<T>;
     abstract logout(payload: IdentityMutationLogout, session: Session): Promise<T>;
+    protected getResourceName(): string;
 }

package/src/providers/inventory.provider.d.ts

@@ -4,4 +4,5 @@ import { Session } from '../schemas/session.schema';
 import { BaseProvider } from './base.provider';
 export declare abstract class InventoryProvider<T extends Inventory = Inventory> extends BaseProvider<T> {
     abstract getBySKU(payload: InventoryQuery, session: Session): Promise<T>;
+    protected getResourceName(): string;
 }