@reactionary/source 0.0.52 → 0.2.16

package/core/src/providers/product.provider.ts

@@ -1,19 +1,78 @@
 import type { Product } from '../schemas/models/product.model.js';
 import { BaseProvider } from './base.provider.js';
-import type { RequestContext } from '../schemas/session.schema.js';
 import type { ProductQueryById, ProductQueryBySKU, ProductQueryBySlug } from '../schemas/queries/product.query.js';
+import type { Result } from '../schemas/result.js';
+import type { NotFoundError } from '../schemas/index.js';
+
+export abstract class ProductProvider extends BaseProvider {
+
+
+  /**
+   * Get a product by its ID.
+   * @param payload The query payload containing the product ID.
+   * @param reqCtx The request context.
+   *
+   * Usecase: Not clear. Maybe if you get a reference from marketing? But that would most likely be a partnumber.
+   * But what if the marketing system recommends products instead of variants? A product does not have a partnumber, or gtin.
+   * Marketing will TYPICALLY recommend products, and in some cases maybe HeroVariants of a product.
+   * In that case, you would need to resolve the product to its hero variant first, and then get the SKU from there.
+   */
+  public abstract getById(payload: ProductQueryById): Promise<Result<Product>>;
+
+
+  /**
+   * Get a product by its slug.
+   * @param payload The query payload containing the product slug.
+   * @param reqCtx The request context.
+   *
+   * Usecase: You are rendering a product detail page, and you need to fetch the product by its slug.
+   */
+  public abstract getBySlug(payload: ProductQueryBySlug): Promise<Result<Product, NotFoundError>>;
+
+
+  /**
+   * Get a product by its SKU
+   * @param payload
+   * @param reqCtx
+   *
+   * Usecase: you want to look up product details for a cart item. Or you have a SKU from an external system (e.g. ERP, PIM, Marketing, OMS/Order History),
+   * and you need to fetch the product details for that SKU. You will get the a Product back, with the variant matching the SKU set as heroSku.
+   * It might also be used on a quick-order page, or product recommendations from external system.
+   */
+  public abstract getBySKU(payload: ProductQueryBySKU): Promise<Result<Product>>;
+
+  protected createEmptyProduct(id: string): Product {
+    // FIXME: We can probably get rid of this once we switch to errors as values, as we shouldn't even
+    // be materializing an empty product...
+    const product = {
+      brand: '',
+      description: '',
+      identifier: {
+        key: id
+      },
+      longDescription: '',
+      mainVariant: {
+        barcode: '',
+        ean: '',
+        gtin: '',
+        identifier: {
+          sku: ''
+        },
+        images: [],
+        name: '',
+        options: [],
+        upc: ''
+      },
+      manufacturer: '',
+      name: '',
+      options: [],
+      parentCategories: [],
+      published: false,
+      sharedAttributes: [],
+      slug: '',
+      variants: [],
+    } satisfies Product;
 
-export abstract class ProductProvider<
-  T extends Product = Product
-> extends BaseProvider<T> {
-  public abstract getById(payload: ProductQueryById, reqCtx: RequestContext): Promise<T>;
-  public abstract getBySlug(payload: ProductQueryBySlug, reqCtx: RequestContext): Promise<T | null>;
-  public abstract getBySKU(payload: ProductQueryBySKU | ProductQueryBySKU[], reqCtx: RequestContext): Promise<T>;
-
-  protected createEmptyProduct(id: string): T {
-    const product = this.newModel();
-    product.identifier = { key: id };
-    product.meta.placeholder = true;
     return product;
   }
 

package/core/src/providers/profile.provider.ts

@@ -1,20 +1,80 @@
+import type { InvalidInputError, NotFoundError } from '../schemas/index.js';
 import type { Profile } from '../schemas/models/index.js';
-import type { ProfileMutationUpdate } from '../schemas/mutations/index.js';
-import type { ProfileQuerySelf } from '../schemas/queries/index.js';
-import type { RequestContext } from '../schemas/session.schema.js';
+import type { ProfileMutationAddShippingAddress, ProfileMutationMakeShippingAddressDefault, ProfileMutationRemoveShippingAddress, ProfileMutationSetBillingAddress, ProfileMutationUpdate, ProfileMutationUpdateShippingAddress } from '../schemas/mutations/index.js';
+import type { ProfileQuerySelf as ProfileQueryById } from '../schemas/queries/index.js';
+import type { Result } from '../schemas/result.js';
 import { BaseProvider } from './base.provider.js';
 
-export abstract class ProfileProvider<
-  T extends Profile = Profile
-> extends BaseProvider<T> {
-  public abstract getSelf(
-    payload: ProfileQuerySelf,
-    reqCtx: RequestContext
-  ): Promise<T>;
-  public abstract update(
-    payload: ProfileMutationUpdate,
-    reqCtx: RequestContext
-  ): Promise<T>;
+export abstract class ProfileProvider extends BaseProvider {
+
+  /**
+   * Returns the profile of the currently authenticated (registered) user.
+   *
+   * Usecase: Fetch the profile of the logged-in user for display in header, or account settings.
+   * @param payload
+   */
+  public abstract getById(payload: ProfileQueryById): Promise<Result<Profile, NotFoundError>>;
+
+  /**
+   * Updates the base profile information of the currently authenticated (registered) user.
+   *
+   * TODO: This should include first/lastname.
+   * TODO: In some systems, updating email/phone may require re-verification.
+   * TODO: Handle conflicts if email/phone is already in use by another user.
+   * TODO: In some systems the email might not be editable.
+   *
+   * Usecase: Update the user's name, email, or phone number.
+   * @param payload
+   */
+  public abstract update(payload: ProfileMutationUpdate): Promise<Result<Profile, NotFoundError>>;
+
+  /**
+   * Creates a new shipping address for the currently authenticated (registered) user.
+   * Does not set it as default automatically.
+   *
+   * Usecase: User adds a new shipping address in their profile or during checkout. Ideally, any address manipulation
+   * done at checkout should be considered local to that session, unless the addressbook is empty.
+   * @param payload
+   */
+  public abstract addShippingAddress(payload: ProfileMutationAddShippingAddress): Promise<Result<Profile, NotFoundError>>;
+
+  /**
+   * Updates an existing shipping address for the currently authenticated (registered) user.
+   *
+   * Usecase: User edits an existing shipping address in their profile. Ideally, any address manipulation
+   * done at checkout should be considered local to that session/order, unless the addressbook is empty.
+   * @param payload
+   */
+  public abstract updateShippingAddress(payload: ProfileMutationUpdateShippingAddress): Promise<Result<Profile, NotFoundError>>;
+
+  /**
+   * Removes an existing shipping address for the currently authenticated (registered) user.
+   *
+   * If the removed address was the default shipping address, the default shipping address is set to a random other address.
+   *
+   * Usecase: User deletes a shipping address from their profile.
+   * @param payload
+   */
+  public abstract removeShippingAddress(payload: ProfileMutationRemoveShippingAddress): Promise<Result<Profile, NotFoundError>>;
+
+  /**
+   * Configures an existing shipping address as the default shipping address for the currently authenticated (registered) user.
+   *
+   * Usecase: User selects a default shipping address in their profile.
+   * @param payload
+   */
+  public abstract makeShippingAddressDefault(payload: ProfileMutationMakeShippingAddressDefault): Promise<Result<Profile, NotFoundError>>;
+
+  /**
+   * Sets the current/active billing address for the currently authenticated (registered) user.
+   *
+   * Usecase: User sets or updates their billing address in their profile or during checkout.
+   *
+   * It was a design decision not to support multiple billing addresses. The billing address represents who you are as the commercial
+   * entity being billed, and as such it makes sense to have a single authoritative billing address.
+   * @param payload
+   */
+  public abstract setBillingAddress(payload: ProfileMutationSetBillingAddress): Promise<Result<Profile, NotFoundError>>;
 
   protected override getResourceName(): string {
     return 'profile';

package/core/src/providers/store.provider.ts

@@ -1,12 +1,10 @@
 import type { Store } from '../schemas/models/store.model.js';
 import type { StoreQueryByProximity } from '../schemas/queries/index.js';
-import type { RequestContext } from '../schemas/session.schema.js';
+import type { Result } from '../schemas/result.js';
 import { BaseProvider } from './base.provider.js';
 
-export abstract class StoreProvider<
-  T extends Store = Store
-> extends BaseProvider<T> {
-  public abstract queryByProximity(payload: StoreQueryByProximity, reqCtx: RequestContext): Promise<Array<T>>;
+export abstract class StoreProvider extends BaseProvider {
+  public abstract queryByProximity(payload: StoreQueryByProximity): Promise<Result<Array<Store>>>;
 
   protected override getResourceName(): string {
     return 'store';

package/core/src/schemas/capabilities.schema.ts

@@ -1,17 +1,24 @@
 import { z } from 'zod';
+import type { InferType } from '../zod-utils.js';
+import type { Client } from '../client/client.js';
 
 export const CapabilitiesSchema = z.looseObject({
     product: z.boolean(),
-    search: z.boolean(),
+    productSearch: z.boolean(),
     analytics: z.boolean(),
     identity: z.boolean(),
     cart: z.boolean(),
     checkout: z.boolean(),
     order: z.boolean(),
+    orderSearch: z.boolean(),
     inventory: z.boolean(),
     price: z.boolean(),
     category: z.boolean(),
-    store: z.boolean()
+    store: z.boolean(),
+    profile: z.boolean()
 });
 
-export type Capabilities = z.infer<typeof CapabilitiesSchema>;
+export type Capabilities = InferType<typeof CapabilitiesSchema>;
+export type ClientFromCapabilities<C extends Partial<Capabilities>> = {
+  [K in keyof C & keyof Client as C[K] extends true ? K : never]: Client[K];
+};

package/core/src/schemas/errors/generic.error.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import type { InferType } from '../../zod-utils.js';
+
+export const GenericErrorSchema = z.looseObject({
+    type: z.literal('Generic'),
+    message: z.string().nonempty()
+});
+
+export type GenericError = InferType<typeof GenericErrorSchema>;

package/core/src/schemas/errors/index.ts

@@ -0,0 +1,4 @@
+export * from './generic.error.js';
+export * from './invalid-input.error.js';
+export * from './invalid-output.error.js';
+export * from './not-found.error.js';

package/core/src/schemas/errors/invalid-input.error.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import type { InferType } from '../../zod-utils.js';
+
+export const InvalidInputErrorSchema = z.looseObject({
+    type: z.literal('InvalidInput'),
+    error: z.ZodError
+});
+
+export type InvalidInputError = InferType<typeof InvalidInputErrorSchema>;

package/core/src/schemas/errors/invalid-output.error.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import type { InferType } from '../../zod-utils.js';
+
+export const InvalidOutputErrorSchema = z.looseObject({
+    type: z.literal('InvalidOutput'),
+    error: z.ZodError
+});
+
+export type InvalidOutputError = InferType<typeof InvalidOutputErrorSchema>;

package/core/src/schemas/errors/not-found.error.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import type { InferType } from '../../zod-utils.js';
+
+export const NotFoundErrorSchema = z.looseObject({
+    type: z.literal('NotFound'),
+    identifier: z.unknown()
+});
+
+export type NotFoundError = InferType<typeof NotFoundErrorSchema>;

package/core/src/schemas/index.ts

@@ -0,0 +1,7 @@
+export * from './errors/index.js';
+export * from './models/index.js';
+export * from './mutations/index.js';
+export * from './queries/index.js';
+export * from './capabilities.schema.js';
+export * from './session.schema.js';
+export * from './result.js';

package/core/src/schemas/models/analytics.model.ts

@@ -1,7 +1,8 @@
 import type { z } from 'zod';
 import { BaseModelSchema } from './base.model.js';
+import type { InferType } from '../../zod-utils.js';
 
 export const AnalyticsEventSchema = BaseModelSchema.extend({
 });
 
-export type AnalyticsEvent = z.infer<typeof AnalyticsEventSchema>;
+export type AnalyticsEvent = InferType<typeof AnalyticsEventSchema>;

package/core/src/schemas/models/base.model.ts

@@ -1,31 +1,14 @@
 import { z } from 'zod';
-
-export const CacheInformationSchema = z.looseObject({
-    hit: z.boolean().default(false),
-    key: z.string().default('')
-})
-
-export const MetaSchema = z.looseObject({
-    cache: CacheInformationSchema.default(() => CacheInformationSchema.parse({})),
-    placeholder: z.boolean().default(false).describe('Whether or not the entity exists in a remote system, or is a default placeholder.')
-});
+import type { InferType } from '../../zod-utils.js';
 
 export const BaseModelSchema = z.looseObject({
-    meta: MetaSchema.default(() => MetaSchema.parse({}))
 });
 
-export type CacheInformation = z.infer<typeof CacheInformationSchema>;
-export type Meta = z.infer<typeof MetaSchema>;
-export type BaseModel = z.infer<typeof BaseModelSchema>;
-
-
 export const PaginationOptionsSchema = z.looseObject({
     pageNumber: z.number().default(1).describe('Current page number, starting from 1'),
-    pageSize: z.number().default(20).describe('Number of items per page'),
+    pageSize: z.number().min(1).max(50).default(20).describe('Number of items per page'),
 });
 
-export type PaginationOptions = z.infer<typeof PaginationOptionsSchema>;
-
 /**
  * This seemed like the right way to do it, but we need to be able to pass in the item schema even later than this
  *
@@ -34,9 +17,8 @@ export function createPaginatedResponseSchema<ItemType extends z.ZodTypeAny>(
   itemSchema: ItemType,
 ) {
   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'),
+    pageSize: z.number().min(1).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),
@@ -55,6 +37,6 @@ export const ImageSchema = z.looseObject({
     height: z.number().optional().describe('Height of the original image, in pixels, if known'),
 });
 
-export type Image = z.infer<typeof ImageSchema>;
-
-
+export type Image = InferType<typeof ImageSchema>;
+export type PaginationOptions = InferType<typeof PaginationOptionsSchema>;
+export type BaseModel = InferType<typeof BaseModelSchema>;

package/core/src/schemas/models/cart.model.ts

@@ -1,29 +1,26 @@
 import { z } from 'zod';
-import { CartIdentifierSchema, CartItemIdentifierSchema, IdentityIdentifierSchema, ProductIdentifierSchema, SKUIdentifierSchema } from '../models/identifiers.model.js';
+import { CartIdentifierSchema, CartItemIdentifierSchema, IdentityIdentifierSchema, ProductIdentifierSchema, ProductVariantIdentifierSchema } from '../models/identifiers.model.js';
 import { CostBreakDownSchema, ItemCostBreakdownSchema } from './cost.model.js';
 import { BaseModelSchema } from './base.model.js';
+import type { InferType } from '../../zod-utils.js';
 
 export const CartItemSchema = z.looseObject({
     identifier: CartItemIdentifierSchema.default(() => CartItemIdentifierSchema.parse({})),
     product: ProductIdentifierSchema.default(() => ProductIdentifierSchema.parse({})),
-    sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({})),
+    variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({})),
     quantity: z.number().default(0),
     price: ItemCostBreakdownSchema.default(() => ItemCostBreakdownSchema.parse({})),
 });
 
 export const CartSchema = BaseModelSchema.extend({
     identifier: CartIdentifierSchema.default(() => CartIdentifierSchema.parse({})),
-
     userId: IdentityIdentifierSchema.default(() => IdentityIdentifierSchema.parse({})),
-
     items: z.array(CartItemSchema).default(() => []),
     price: CostBreakDownSchema.default(() => CostBreakDownSchema.parse({})),
     name: z.string().default(''),
     description: z.string().default(''),
-
-
 });
 
 
-export type CartItem = z.infer<typeof CartItemSchema>;
-export type Cart = z.infer<typeof CartSchema>;
+export type CartItem = InferType<typeof CartItemSchema>;
+export type Cart = InferType<typeof CartSchema>;

package/core/src/schemas/models/category.model.ts

@@ -1,13 +1,8 @@
-// getBySeoSlug
-// getBreadcrumbPathToCategory
-// getById
-// getByExternalId
-// getChildCategories
-
-
 import { z } from 'zod';
 import { BaseModelSchema, createPaginatedResponseSchema, ImageSchema } from './base.model.js';
 import { CategoryIdentifierSchema } from './identifiers.model.js';
+import type { InferType } from '../../zod-utils.js';
+
 export const CategorySchema = BaseModelSchema.extend({
     identifier:  CategoryIdentifierSchema.default(() => CategoryIdentifierSchema.parse({})),
     name: z.string().default(''),
@@ -17,7 +12,7 @@ export const CategorySchema = BaseModelSchema.extend({
     parentCategory: CategoryIdentifierSchema.optional(),
 });
 
-export type Category = z.infer<typeof CategorySchema>;
+export type Category = InferType<typeof CategorySchema>;
 
 export const CategoryPaginatedResultSchema  = createPaginatedResponseSchema(CategorySchema);
-export type CategoryPaginatedResult = z.infer<typeof CategoryPaginatedResultSchema>;
+export type CategoryPaginatedResult = InferType<typeof CategoryPaginatedResultSchema>;

package/core/src/schemas/models/checkout.model.ts

@@ -1,16 +1,15 @@
-
-
 import { z } from 'zod';
 import { BaseModelSchema } from './base.model.js';
-import { CartIdentifierSchema, CheckoutIdentifierSchema, CheckoutItemIdentifierSchema, OrderIdentifierSchema, SKUIdentifierSchema } from './identifiers.model.js';
+import { CartIdentifierSchema, CheckoutIdentifierSchema, CheckoutItemIdentifierSchema, OrderIdentifierSchema, ProductVariantIdentifierSchema } from './identifiers.model.js';
 import { CostBreakDownSchema, ItemCostBreakdownSchema } from './cost.model.js';
 import { AddressSchema } from './profile.model.js';
 import { ShippingInstructionSchema } from './shipping-method.model.js';
 import { PaymentInstructionSchema } from './payment.model.js';
+import type { InferType } from '../../zod-utils.js';
 
 export const CheckoutItemSchema = z.looseObject({
     identifier: CheckoutItemIdentifierSchema.default(() => CheckoutItemIdentifierSchema.parse({})),
-    sku: SKUIdentifierSchema.default(() => SKUIdentifierSchema.parse({})),
+    variant: ProductVariantIdentifierSchema.default(() => ProductVariantIdentifierSchema.parse({})),
     quantity: z.number().default(0),
     price: ItemCostBreakdownSchema.default(() => ItemCostBreakdownSchema.parse({})),
 });
@@ -43,7 +42,7 @@ export const CheckoutSchema = BaseModelSchema.extend({
     description: z.string().default(''),
 
 
-    billingAddress: AddressSchema.optional(),
+    billingAddress: AddressSchema.optional().nullable(),
 
     /**
      * Shipping and billing details can be changed on the checkout, but not items or quantities.
@@ -62,5 +61,5 @@ export const CheckoutSchema = BaseModelSchema.extend({
 
 
 
-export type CheckoutItem = z.infer<typeof CheckoutItemSchema>;
-export type Checkout = z.infer<typeof CheckoutSchema>;
+export type CheckoutItem = InferType<typeof CheckoutItemSchema>;
+export type Checkout = InferType<typeof CheckoutSchema>;

package/core/src/schemas/models/cost.model.ts

@@ -1,5 +1,6 @@
-import z from "zod";
+import { z } from "zod";
 import { MonetaryAmountSchema } from "./price.model.js";
+import type { InferType } from '../../zod-utils.js';
 
 export 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.'),
@@ -17,5 +18,5 @@ export const ItemCostBreakdownSchema = z.looseObject({
     totalDiscount: MonetaryAmountSchema.default(() => MonetaryAmountSchema.parse({})).describe('The total discount applied to all units of the item.'),
 });
 
-export type CostBreakDown = z.infer<typeof CostBreakDownSchema>;
-export type ItemCostBreakdown = z.infer<typeof ItemCostBreakdownSchema>;
+export type CostBreakDown = InferType<typeof CostBreakDownSchema>;
+export type ItemCostBreakdown = InferType<typeof ItemCostBreakdownSchema>;

package/core/src/schemas/models/currency.model.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { InferType } from '../../zod-utils.js';
 
 export const CurrencySchema = z.enum([
   'AED',
@@ -184,4 +185,4 @@ export const CurrencySchema = z.enum([
   'ZWL',
 ]);
 
-export type Currency = z.infer<typeof CurrencySchema>;
+export type Currency = InferType<typeof CurrencySchema>;