@reactionary/magento 0.0.1 → 0.10.18

package/factories/profile/profile.factory.js

@@ -0,0 +1,61 @@
+class MagentoProfileFactory {
+  profileSchema;
+  constructor(profileSchema) {
+    this.profileSchema = profileSchema;
+  }
+  parseProfile(context, data) {
+    const customer = data;
+    const phone = customer.custom_attributes?.find((a) => a.attribute_code === "phone")?.value ?? "";
+    const addresses = customer.addresses ?? [];
+    const billingId = customer.default_billing;
+    const shippingId = customer.default_shipping;
+    let billingAddress;
+    let shippingAddress;
+    const alternateShippingAddresses = [];
+    for (const address of addresses) {
+      const parsed = this.parseAddress(context, address);
+      const id = address.id !== void 0 ? String(address.id) : void 0;
+      if (id && billingId && id === billingId) {
+        billingAddress = parsed;
+      } else if (id && shippingId && id === shippingId) {
+        shippingAddress = parsed;
+      } else {
+        alternateShippingAddresses.push(parsed);
+      }
+    }
+    const result = {
+      identifier: {
+        userId: String(customer.id)
+      },
+      email: customer.email,
+      emailVerified: true,
+      phone,
+      phoneVerified: false,
+      billingAddress,
+      shippingAddress,
+      alternateShippingAddresses,
+      createdAt: new Date(customer.created_at || Date.now()).toISOString(),
+      updatedAt: new Date(customer.updated_at || Date.now()).toISOString()
+    };
+    return this.profileSchema.parse(result);
+  }
+  parseAddress(_context, address) {
+    const street = address.street ?? [];
+    return {
+      identifier: {
+        nickName: address.company || ""
+      },
+      firstName: address.firstname || "",
+      lastName: address.lastname || "",
+      streetAddress: street[0] || "",
+      streetNumber: street[1] || "",
+      city: address.city || "",
+      region: address.region?.region || "",
+      postalCode: address.postcode || "",
+      countryCode: address.country_id || ""
+    };
+  }
+}
+export {
+  MagentoProfileFactory
+};

package/index.js

@@ -5,6 +5,8 @@ export * from "./core/initialize.js";
 export * from "./core/initialize.types.js";
 export * from "./core/client.js";
 export * from "./factories/index.js";
+export * from "./utils/magento-product.js";
+export * from "./utils/magento-review.js";
 export * from "./capabilities/product.capability.js";
 export * from "./capabilities/product-search.capability.js";
 export * from "./capabilities/category.capability.js";
@@ -12,3 +14,10 @@ export * from "./capabilities/inventory.capability.js";
 export * from "./capabilities/price.capability.js";
 export * from "./capabilities/identity.capability.js";
 export * from "./capabilities/cart.capability.js";
+export * from "./capabilities/profile.capability.js";
+export * from "./capabilities/order-search.capability.js";
+export * from "./capabilities/order.capability.js";
+export * from "./capabilities/checkout.capability.js";
+export * from "./capabilities/product-associations.capability.js";
+export * from "./capabilities/product-recommendations.capability.js";
+export * from "./capabilities/product-reviews.capability.js";

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@reactionary/magento",
-  "version": "0.0.1",
-  "private": false,
+  "version": "0.10.18",
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Solteq/reactionary.git"
+  },
   "dependencies": {
-    "@reactionary/core": "0.0.1",
+    "@reactionary/core": "0.10.18",
     "zod": "4.1.9",
     "debug": "^4.4.3"
   },
-  "sideEffets": false
-
-}
+  "devDependencies": {
+    "vitest": "^4.0.9"
+  },
+  "sideEffects": false
+}

package/schema/capabilities.schema.js

@@ -16,7 +16,14 @@ const MagentoCapabilitiesSchema = CapabilitiesSchema.pick({
   inventory: true,
   price: true,
   identity: true,
-  cart: true
+  cart: true,
+  profile: true,
+  orderSearch: true,
+  order: true,
+  checkout: true,
+  productAssociations: true,
+  productRecommendations: true,
+  productReviews: true
 }).extend({
   product: OverridableCapabilitySchema.optional(),
   productSearch: OverridableCapabilitySchema.optional(),
@@ -24,7 +31,14 @@ const MagentoCapabilitiesSchema = CapabilitiesSchema.pick({
   category: OverridableCapabilitySchema.optional(),
   price: OverridableCapabilitySchema.optional(),
   inventory: OverridableCapabilitySchema.optional(),
-  identity: DirectCapabilitySchema.optional()
+  identity: DirectCapabilitySchema.optional(),
+  profile: OverridableCapabilitySchema.optional(),
+  orderSearch: OverridableCapabilitySchema.optional(),
+  order: OverridableCapabilitySchema.optional(),
+  checkout: OverridableCapabilitySchema.optional(),
+  productAssociations: OverridableCapabilitySchema.optional(),
+  productRecommendations: DirectCapabilitySchema.optional(),
+  productReviews: OverridableCapabilitySchema.optional()
 }).partial();
 export {
   MagentoCapabilitiesSchema

package/schema/configuration.schema.js

@@ -3,10 +3,14 @@ const MagentoConfigurationSchema = z.looseObject({
   adminApiKey: z.string().meta({ description: "The API key for Magento admin operations. Needed for the few tasks that require admin access." }),
   baseUrl: z.string().meta({ description: "The base URL for the Magento installation." }),
   mediaUrl: z.string().optional().meta({ description: "The base URL for media files. If not provided, it will be derived from the baseUrl." }),
+  mediaSource: z.enum(["EXTERNAL", "DEFAULT"]).default("DEFAULT").meta({ description: "Where product imagery is taken from. DEFAULT uses the Magento media gallery. EXTERNAL uses the `original_dam_reference` attribute, which holds the PIM-sorted list of DAM image URLs." }),
   defaultCurrency: z.string().default(""),
   rootCategoryId: z.string().default("2").meta({ description: 'The ID of the root category in Magento. Typically "2" for the default Magento setup.' }),
   allCurrencies: z.array(z.string()),
-  storeCode: z.string().default("")
+  graphqlUrl: z.string().optional().meta({ description: "The GraphQL endpoint. Defaults to `{baseUrl}/graphql`. Reviews and ratings have no REST equivalent in Magento, so the product reviews capability goes through GraphQL." }),
+  reviewRatingCode: z.string().optional().meta({ description: 'The name of the Magento review rating (as listed by `productReviewRatingsMetadata`) that carries the overall star rating. Defaults to "Rating"; the first available rating is used as a fallback.' }),
+  storeCode: z.string().default(""),
+  authStoreCode: z.string().default("default").meta({ description: "The store/website scope used for customer authentication and account operations (token, customers/me). Customers typically live on the default website, which may differ from the catalog storeCode." })
 });
 export {
   MagentoConfigurationSchema

package/src/capabilities/cart.capability.d.ts

@@ -8,6 +8,11 @@ export declare class MagentoCartCapability<TFactory extends CartFactory = Magent
     protected factory: CartFactoryWithOutput<TFactory>;
     constructor(config: MagentoConfiguration, cache: Cache, context: RequestContext, magentoApi: MagentoClient, factory: CartFactoryWithOutput<TFactory>);
     getById(payload: CartQueryById): Promise<Result<CartFactoryCartOutput<TFactory>, NotFoundError>>;
+    /**
+     * Fetches the cart (with merged totals) and parses it into the model. Shared
+     * by all mutations that return the resulting cart.
+     */
+    protected respondWithCart(key: string): Promise<Result<CartFactoryCartOutput<TFactory>>>;
     add(payload: CartMutationItemAdd): Promise<Result<CartFactoryCartOutput<TFactory>>>;
     remove(payload: CartMutationItemRemove): Promise<Result<CartFactoryCartOutput<TFactory>>>;
     changeQuantity(payload: CartMutationItemQuantityChange): Promise<Result<CartFactoryCartOutput<TFactory>>>;

package/src/capabilities/checkout.capability.d.ts

@@ -0,0 +1,30 @@
+import { CheckoutCapability, type Address, type Cache, type CheckoutFactory, type CheckoutFactoryCheckoutOutput, type CheckoutFactoryPaymentMethodOutput, type CheckoutFactoryShippingMethodOutput, type CheckoutFactoryWithOutput, type CheckoutIdentifier, type CheckoutMutationAddPaymentInstruction, type CheckoutMutationFinalizeCheckout, type CheckoutMutationInitiateCheckout, type CheckoutMutationRemovePaymentInstruction, type CheckoutMutationSetShippingAddress, type CheckoutMutationSetShippingInstruction, type CheckoutQueryById, type CheckoutQueryForAvailablePaymentMethods, type CheckoutQueryForAvailableShippingMethods, type NotFoundError, type RequestContext, type Result } from '@reactionary/core';
+import type { MagentoClient } from '../core/client.js';
+import { type MagentoCheckoutFactory } from '../factories/checkout/checkout.factory.js';
+import type { MagentoConfiguration } from '../schema/configuration.schema.js';
+import type { MagentoCart, MagentoCartTotals, MagentoCheckoutAddress, MagentoCheckoutState } from '../schema/magento.types.js';
+export declare class CheckoutNotReadyForFinalizationError extends Error {
+    checkoutIdentifier: CheckoutIdentifier;
+    constructor(checkoutIdentifier: CheckoutIdentifier);
+}
+export declare class MagentoCheckoutCapability<TFactory extends CheckoutFactory = MagentoCheckoutFactory> extends CheckoutCapability<CheckoutFactoryCheckoutOutput<TFactory>, CheckoutFactoryShippingMethodOutput<TFactory>, CheckoutFactoryPaymentMethodOutput<TFactory>> {
+    magentoApi: MagentoClient;
+    protected config: MagentoConfiguration;
+    protected factory: CheckoutFactoryWithOutput<TFactory>;
+    constructor(config: MagentoConfiguration, cache: Cache, context: RequestContext, magentoApi: MagentoClient, factory: CheckoutFactoryWithOutput<TFactory>);
+    protected toMagentoAddress(address: Omit<Address, 'identifier'>, email?: string): MagentoCheckoutAddress;
+    protected loadCartAndTotals(cartKey: string): Promise<{
+        cart: MagentoCart;
+        totals?: MagentoCartTotals;
+    }>;
+    protected buildCheckout(cartKey: string, state: MagentoCheckoutState): Promise<CheckoutFactoryCheckoutOutput<TFactory>>;
+    initiateCheckoutForCart(payload: CheckoutMutationInitiateCheckout): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
+    getById(payload: CheckoutQueryById): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>, NotFoundError>>;
+    setShippingAddress(payload: CheckoutMutationSetShippingAddress): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
+    getAvailableShippingMethods(payload: CheckoutQueryForAvailableShippingMethods): Promise<Result<CheckoutFactoryShippingMethodOutput<TFactory>[]>>;
+    getAvailablePaymentMethods(payload: CheckoutQueryForAvailablePaymentMethods): Promise<Result<CheckoutFactoryPaymentMethodOutput<TFactory>[]>>;
+    addPaymentInstruction(payload: CheckoutMutationAddPaymentInstruction): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
+    removePaymentInstruction(payload: CheckoutMutationRemovePaymentInstruction): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
+    setShippingInstruction(payload: CheckoutMutationSetShippingInstruction): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
+    finalizeCheckout(payload: CheckoutMutationFinalizeCheckout): Promise<Result<CheckoutFactoryCheckoutOutput<TFactory>>>;
+}

package/src/capabilities/order-search.capability.d.ts

@@ -0,0 +1,16 @@
+import type { Cache, OrderSearchFactory, OrderSearchFactoryOutput, OrderSearchFactoryWithOutput, OrderSearchQueryByTerm, RequestContext, Result } from '@reactionary/core';
+import { OrderSearchCapability } from '@reactionary/core';
+import type { MagentoClient } from '../core/client.js';
+import type { MagentoOrderSearchFactory } from '../factories/order-search/order-search.factory.js';
+import type { MagentoConfiguration } from '../schema/configuration.schema.js';
+export declare class MagentoOrderSearchCapability<TFactory extends OrderSearchFactory = MagentoOrderSearchFactory> extends OrderSearchCapability<OrderSearchFactoryOutput<TFactory>> {
+    magentoApi: MagentoClient;
+    protected config: MagentoConfiguration;
+    protected factory: OrderSearchFactoryWithOutput<TFactory>;
+    constructor(config: MagentoConfiguration, cache: Cache, context: RequestContext, magentoApi: MagentoClient, factory: OrderSearchFactoryWithOutput<TFactory>);
+    protected emptyResult(payload: OrderSearchQueryByTerm): ReturnType<TFactory["parseOrderSearchResult"]>;
+    protected resolveCustomerId(): Promise<string | null>;
+    protected buildSearchParams(payload: OrderSearchQueryByTerm, customerId: string): URLSearchParams;
+    queryByTerm(payload: OrderSearchQueryByTerm): Promise<Result<OrderSearchFactoryOutput<TFactory>>>;
+    protected filterByPartNumber(response: any, partNumbers: string[]): any;
+}

package/src/capabilities/order.capability.d.ts

@@ -0,0 +1,12 @@
+import type { Cache, NotFoundError, OrderFactory, OrderFactoryOutput, OrderFactoryWithOutput, OrderQueryById, RequestContext, Result } from '@reactionary/core';
+import { OrderCapability } from '@reactionary/core';
+import type { MagentoClient } from '../core/client.js';
+import type { MagentoOrderFactory } from '../factories/order/order.factory.js';
+import type { MagentoConfiguration } from '../schema/configuration.schema.js';
+export declare class MagentoOrderCapability<TFactory extends OrderFactory = MagentoOrderFactory> extends OrderCapability<OrderFactoryOutput<TFactory>> {
+    magentoApi: MagentoClient;
+    protected config: MagentoConfiguration;
+    protected factory: OrderFactoryWithOutput<TFactory>;
+    constructor(config: MagentoConfiguration, cache: Cache, context: RequestContext, magentoApi: MagentoClient, factory: OrderFactoryWithOutput<TFactory>);
+    getById(payload: OrderQueryById): Promise<Result<OrderFactoryOutput<TFactory>, NotFoundError>>;
+}

package/src/capabilities/product-associations.capability.d.ts

@@ -0,0 +1,23 @@
+import { ProductAssociationsCapability, type Cache, type ProductAssociationsFactory, type ProductAssociationsFactoryOutput, type ProductAssociationsFactoryWithOutput, type ProductAssociationsGetAccessoriesQuery, type ProductAssociationsGetReplacementsQuery, type ProductAssociationsGetSparepartsQuery, type ProductIdentifier, type RequestContext, type Result } from '@reactionary/core';
+import type { MagentoClient } from '../core/client.js';
+import type { MagentoProductAssociationsFactory } from '../factories/product-associations/product-associations.factory.js';
+import type { MagentoConfiguration } from '../schema/configuration.schema.js';
+import type { MagentoProduct, MagentoProductLinkType } from '../schema/magento.types.js';
+/**
+ * Maps the reactionary association types onto Magento's native product links.
+ * Each mapping is an extension point so projects can re-wire them.
+ */
+export declare class MagentoProductAssociationsCapability<TFactory extends ProductAssociationsFactory = MagentoProductAssociationsFactory> extends ProductAssociationsCapability<ProductAssociationsFactoryOutput<TFactory>> {
+    magentoApi: MagentoClient;
+    protected config: MagentoConfiguration;
+    protected factory: ProductAssociationsFactoryWithOutput<TFactory>;
+    constructor(config: MagentoConfiguration, cache: Cache, context: RequestContext, magentoApi: MagentoClient, factory: ProductAssociationsFactoryWithOutput<TFactory>);
+    protected getAccessoriesLinkType(): MagentoProductLinkType;
+    protected getSparepartsLinkType(): MagentoProductLinkType;
+    protected getReplacementsLinkType(): MagentoProductLinkType;
+    protected fetchAssociatedProductsFor(forProduct: ProductIdentifier, linkType: MagentoProductLinkType, maxNumberOfAssociations: number): Promise<MagentoProduct[]>;
+    protected toAssociations(forProduct: ProductIdentifier, associationType: string, products: MagentoProduct[]): ProductAssociationsFactoryOutput<TFactory>[];
+    getAccessories(query: ProductAssociationsGetAccessoriesQuery): Promise<Result<ProductAssociationsFactoryOutput<TFactory>[]>>;
+    getSpareparts(query: ProductAssociationsGetSparepartsQuery): Promise<Result<ProductAssociationsFactoryOutput<TFactory>[]>>;
+    getReplacements(query: ProductAssociationsGetReplacementsQuery): Promise<Result<ProductAssociationsFactoryOutput<TFactory>[]>>;
+}

package/src/capabilities/product-recommendations.capability.d.ts

@@ -0,0 +1,24 @@
+import { ProductRecommendationsCapability, type Cache, type ProductIdentifier, type ProductRecommendation, type ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery, type ProductRecommendationAlgorithmRelatedProductsQuery, type ProductRecommendationAlgorithmSimilarProductsQuery, type ProductRecommendationAlgorithmTrendingInCategoryQuery, type ProductRecommendationsByCollectionQuery, type RequestContext, type Result } from '@reactionary/core';
+import type { MagentoClient } from '../core/client.js';
+import type { MagentoConfiguration } from '../schema/configuration.schema.js';
+import type { MagentoProduct, MagentoProductLinkType } from '../schema/magento.types.js';
+/**
+ * Magento has no recommendation engine, so recommendations are derived from the
+ * catalogue itself: native product links for the product based algorithms, and
+ * the category tree for collections and category trends.
+ */
+export declare class MagentoProductRecommendationsCapability extends ProductRecommendationsCapability {
+    magentoApi: MagentoClient;
+    protected config: MagentoConfiguration;
+    constructor(config: MagentoConfiguration, cache: Cache, context: RequestContext, magentoApi: MagentoClient);
+    protected getRelatedLinkType(): MagentoProductLinkType;
+    protected getSimilarLinkType(): MagentoProductLinkType;
+    protected getFrequentlyBoughtTogetherLinkType(): MagentoProductLinkType;
+    protected toRecommendations(algorithm: string, keyPrefix: string, products: MagentoProduct[]): ProductRecommendation[];
+    protected fetchLinkedProducts(sourceProduct: ProductIdentifier, linkType: MagentoProductLinkType, numberOfRecommendations: number): Promise<MagentoProduct[]>;
+    getCollection(query: ProductRecommendationsByCollectionQuery): Promise<Result<ProductRecommendation[]>>;
+    protected getRelatedProductsRecommendations(query: ProductRecommendationAlgorithmRelatedProductsQuery): Promise<ProductRecommendation[]>;
+    protected getSimilarProductsRecommendations(query: ProductRecommendationAlgorithmSimilarProductsQuery): Promise<ProductRecommendation[]>;
+    protected getFrequentlyBoughtTogetherRecommendations(query: ProductRecommendationAlgorithmFrequentlyBoughtTogetherQuery): Promise<ProductRecommendation[]>;
+    protected getTrendingInCategoryRecommendations(query: ProductRecommendationAlgorithmTrendingInCategoryQuery): Promise<ProductRecommendation[]>;
+}

package/src/capabilities/product-reviews.capability.d.ts

@@ -0,0 +1,35 @@
+import { ProductReviewsCapability, type Cache, type ProductReviewMutationSubmit, type ProductReviewsFactory, type ProductReviewsFactoryRatingOutput, type ProductReviewsFactoryReviewOutput, type ProductReviewsFactoryReviewPaginatedOutput, type ProductReviewsFactoryWithOutput, type ProductReviewsGetRatingSummaryQuery, type ProductReviewsListQuery, type RequestContext, type Result } from '@reactionary/core';
+import type { MagentoClient } from '../core/client.js';
+import type { MagentoProductReviewsFactory } from '../factories/product-reviews/product-reviews.factory.js';
+import type { MagentoConfiguration } from '../schema/configuration.schema.js';
+import type { MagentoCreateProductReviewRating, MagentoReviewableProduct } from '../schema/magento.types.js';
+/**
+ * Magento's REST API carries no reviews or ratings at all, so this capability
+ * talks to the GraphQL endpoint (`products.rating_summary`, `products.reviews`
+ * and the `createProductReview` mutation) through {@link MagentoClient}.
+ *
+ * Two consequences of that schema are worth knowing about:
+ *  - there is no per-star distribution, so `ratingDistribution` is undefined;
+ *  - reviews have no identifier, so keys are derived (see `buildProductReviewKey`).
+ */
+export declare class MagentoProductReviewsCapability<TFactory extends ProductReviewsFactory = MagentoProductReviewsFactory> extends ProductReviewsCapability<ProductReviewsFactoryRatingOutput<TFactory>, ProductReviewsFactoryReviewPaginatedOutput<TFactory>, ProductReviewsFactoryReviewOutput<TFactory>> {
+    magentoApi: MagentoClient;
+    protected config: MagentoConfiguration;
+    protected factory: ProductReviewsFactoryWithOutput<TFactory>;
+    constructor(config: MagentoConfiguration, cache: Cache, context: RequestContext, magentoApi: MagentoClient, factory: ProductReviewsFactoryWithOutput<TFactory>);
+    /**
+     * The name of the Magento rating that carries the overall star score. Stores
+     * can define several named ratings; override to pick a different one.
+     */
+    protected getReviewRatingCode(): string;
+    protected fetchRatingSummary(sku: string): Promise<MagentoReviewableProduct | null>;
+    protected fetchReviews(sku: string, pageSize: number, pageNumber: number): Promise<MagentoReviewableProduct | null>;
+    /**
+     * Magento will not accept a star count directly — the rating has to be sent
+     * as an opaque `value_id` looked up through `productReviewRatingsMetadata`.
+     */
+    protected resolveRatingInput(rating: number): Promise<MagentoCreateProductReviewRating[] | null>;
+    getRatingSummary(query: ProductReviewsGetRatingSummaryQuery): Promise<Result<ProductReviewsFactoryRatingOutput<TFactory>>>;
+    findReviews(query: ProductReviewsListQuery): Promise<Result<ProductReviewsFactoryReviewPaginatedOutput<TFactory>>>;
+    submitReview(mutation: ProductReviewMutationSubmit): Promise<Result<ProductReviewsFactoryReviewOutput<TFactory>>>;
+}

package/src/capabilities/profile.capability.d.ts

@@ -0,0 +1,24 @@
+import { type Address, type Cache, type NotFoundError, ProfileCapability, type ProfileFactory, type ProfileFactoryOutput, type ProfileFactoryWithOutput, type ProfileMutationAddShippingAddress, type ProfileMutationMakeShippingAddressDefault, type ProfileMutationRemoveShippingAddress, type ProfileMutationSetBillingAddress, type ProfileMutationUpdate, type ProfileMutationUpdateShippingAddress, type ProfileQuerySelf as ProfileQueryById, type RequestContext, type Result } from '@reactionary/core';
+import type { MagentoClient } from '../core/client.js';
+import type { MagentoAddress, MagentoCustomer, MagentoProfileFactory } from '../factories/profile/profile.factory.js';
+import type { MagentoConfiguration } from '../schema/configuration.schema.js';
+export declare class MagentoProfileCapability<TFactory extends ProfileFactory = MagentoProfileFactory> extends ProfileCapability<ProfileFactoryOutput<TFactory>> {
+    magentoApi: MagentoClient;
+    protected config: MagentoConfiguration;
+    protected factory: ProfileFactoryWithOutput<TFactory>;
+    constructor(config: MagentoConfiguration, cache: Cache, context: RequestContext, magentoApi: MagentoClient, factory: ProfileFactoryWithOutput<TFactory>);
+    protected fetchCustomer(): Promise<MagentoCustomer | null>;
+    protected buildMagentoAddress(address: Address, flags?: {
+        default_billing?: boolean;
+        default_shipping?: boolean;
+    }, existing?: MagentoAddress): MagentoAddress;
+    protected findByNickName(customer: MagentoCustomer, nickName: string): MagentoAddress | undefined;
+    getById(payload: ProfileQueryById): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    update(payload: ProfileMutationUpdate): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    addShippingAddress(payload: ProfileMutationAddShippingAddress): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    updateShippingAddress(payload: ProfileMutationUpdateShippingAddress): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    removeShippingAddress(payload: ProfileMutationRemoveShippingAddress): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    makeShippingAddressDefault(payload: ProfileMutationMakeShippingAddressDefault): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    setBillingAddress(payload: ProfileMutationSetBillingAddress): Promise<Result<ProfileFactoryOutput<TFactory>, NotFoundError>>;
+    protected preserveAddresses(customer: MagentoCustomer): MagentoAddress[];
+}

package/src/core/client.d.ts

@@ -1,6 +1,13 @@
 import type { MagentoConfiguration } from '../schema/configuration.schema.js';
 import type { RequestContext } from '@reactionary/core';
+import type { MagentoCheckoutAddress, MagentoCheckoutState, MagentoCreateProductReviewInput, MagentoCreateProductReviewResult, MagentoPaymentMethod, MagentoPlaceOrderPayload, MagentoProductLink, MagentoProductReview, MagentoProductReviewRatingMetadata, MagentoProductReviewRatingsMetadataQueryResult, MagentoProductReviewsQueryResult, MagentoProductSearchResult, MagentoReviewableProduct, MagentoShippingInformationPayload, MagentoShippingInformationResult, MagentoShippingMethod } from '../schema/magento.types.js';
 export declare const SESSION_KEY = "MAGENTO_PROVIDER";
+/**
+ * Magento enforces a password complexity policy (min. number of character
+ * classes). Deterministically pad the password so it always satisfies the
+ * policy; the same transform is applied on both register and login.
+ */
+export declare function ensureMagentoPasswordPolicy(password: string): string;
 export interface MagentoCustomStorage {
     getItem(key: string): Promise<string | null>;
     setItem(key: string, value: string): Promise<void>;
@@ -22,12 +29,30 @@ declare class MagentoRest {
     protected apiUrl: string;
     constructor(baseUrl: string, storeCode: string, getAuthHeader: () => Promise<Record<string, string>>);
     private normalizeUrl;
-    request<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: unknown): Promise<T>;
+    request<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: unknown, options?: {
+        allowNotFound?: boolean;
+    }): Promise<T>;
+}
+/**
+ * Reviews and ratings are absent from the Magento REST API, so they are read
+ * and written over GraphQL. The store scope travels in the `Store` header
+ * rather than in the path, which is the one structural difference from REST.
+ */
+export declare class MagentoGraphQL {
+    private endpoint;
+    private storeCode;
+    private getAuthHeader;
+    constructor(endpoint: string, storeCode: string, getAuthHeader: () => Promise<Record<string, string>>);
+    request<T>(document: string, variables?: Record<string, unknown>): Promise<T>;
 }
 export declare class Magento {
     private rest;
     private tokenStore;
-    constructor(rest: MagentoRest, tokenStore: RequestContextTokenStore);
+    private graphql?;
+    private authRest;
+    private adminRest;
+    constructor(rest: MagentoRest, tokenStore: RequestContextTokenStore, authRest?: MagentoRest, adminRest?: MagentoRest, graphql?: MagentoGraphQL | undefined);
+    private get gql();
     auth: {
         login: (email: string, password: string) => Promise<string>;
         logout: () => Promise<void>;
@@ -36,10 +61,18 @@ export declare class Magento {
         customer: {
             register: (customer: any, password?: string) => Promise<any>;
             me: () => Promise<any>;
+            update: (customer: any) => Promise<any>;
         };
         product: {
             getBySKU: (sku: string) => Promise<any>;
             search: (params: URLSearchParams) => Promise<any>;
+            getLinks: (sku: string, linkType: string) => Promise<MagentoProductLink[]>;
+        };
+        productReviews: {
+            getSummary: (sku: string) => Promise<MagentoProductReviewsQueryResult>;
+            list: (sku: string, pageSize: number, currentPage: number) => Promise<MagentoProductReviewsQueryResult>;
+            getRatingsMetadata: () => Promise<MagentoProductReviewRatingsMetadataQueryResult>;
+            create: (input: MagentoCreateProductReviewInput) => Promise<MagentoCreateProductReviewResult>;
         };
         category: {
             getById: (categoryId: string) => Promise<any>;
@@ -50,6 +83,17 @@ export declare class Magento {
             getStockStatus: (sku: string) => Promise<any>;
             getSourceItems: (params: URLSearchParams) => Promise<any>;
         };
+        order: {
+            list: (params: URLSearchParams) => Promise<any>;
+            get: (id: string) => Promise<any>;
+        };
+        checkout: {
+            estimateShippingMethods: (cartId: string | null, address: MagentoCheckoutAddress, customerToken?: string | null) => Promise<MagentoShippingMethod[]>;
+            getPaymentMethods: (cartId: string | null, customerToken?: string | null) => Promise<MagentoPaymentMethod[]>;
+            setShippingInformation: (cartId: string | null, payload: MagentoShippingInformationPayload, customerToken?: string | null) => Promise<MagentoShippingInformationResult>;
+            setBillingAddress: (cartId: string | null, address: MagentoCheckoutAddress, customerToken?: string | null) => Promise<number>;
+            placeOrder: (cartId: string | null, payload: MagentoPlaceOrderPayload, customerToken?: string | null) => Promise<number>;
+        };
         cart: {
             create: (customerToken?: string | null) => Promise<string>;
             get: (cartId?: string | null, customerToken?: string | null) => Promise<any>;
@@ -62,6 +106,11 @@ export declare class Magento {
         };
     };
 }
+/**
+ * Magento serves GraphQL from a fixed `/graphql` path next to the REST tree,
+ * unless the installation was reverse-proxied elsewhere.
+ */
+export declare function resolveGraphQLEndpoint(config: MagentoConfiguration): string;
 export declare class MagentoAdminClient {
     protected rest: MagentoRest;
     protected client: Magento;
@@ -72,15 +121,34 @@ export declare class MagentoClient {
     protected config: MagentoConfiguration;
     protected tokenStore: RequestContextTokenStore;
     protected rest: MagentoRest;
+    protected authRest: MagentoRest;
+    protected adminRest: MagentoRest;
+    protected graphql: MagentoGraphQL;
     protected client: Promise<Magento> | undefined;
     constructor(config: MagentoConfiguration, context: RequestContext);
     getClient(): Promise<Magento>;
     login(email: string, password: string): Promise<string>;
     logout(): Promise<void>;
     getMe(): Promise<any>;
+    getCustomerToken(): Promise<string | null>;
+    getActiveCartId(): Promise<string | null>;
+    setActiveCartId(cartId: string): Promise<void>;
+    clearActiveCartId(): Promise<void>;
     register(customer: any, password?: string): Promise<any>;
+    updateMe(customer: any): Promise<any>;
+    searchOrders(params: URLSearchParams): Promise<any>;
+    /** Returns undefined (not a thrown error) when Magento returns a 404 — no order with this entity_id. */
+    getOrderById(id: string): Promise<any>;
     getProductBySKU(sku: string): Promise<any>;
     resolveProductForSKU(sku: string): Promise<any>;
+    searchProducts(params: URLSearchParams): Promise<MagentoProductSearchResult>;
+    getProductLinks(sku: string, linkType: string): Promise<MagentoProductLink[]>;
+    /** Returns null when no product matches the SKU in the current store scope. */
+    getProductReviewSummary(sku: string): Promise<MagentoReviewableProduct | null>;
+    /** Returns null when no product matches the SKU in the current store scope. */
+    getProductReviews(sku: string, pageSize: number, currentPage: number): Promise<MagentoReviewableProduct | null>;
+    getProductReviewRatingsMetadata(): Promise<MagentoProductReviewRatingMetadata[]>;
+    createProductReview(input: MagentoCreateProductReviewInput): Promise<MagentoProductReview | null>;
     createCart(): Promise<string>;
     getCart(cartId?: string | null): Promise<any>;
     getCartTotals(cartId?: string | null): Promise<any>;
@@ -89,5 +157,12 @@ export declare class MagentoClient {
     removeCartItem(cartId: string | null, itemId: number): Promise<any>;
     applyCoupon(cartId: string | null, couponCode: string): Promise<any>;
     removeCoupon(cartId: string | null): Promise<any>;
+    estimateShippingMethods(cartId: string | null, address: MagentoCheckoutAddress): Promise<MagentoShippingMethod[]>;
+    getPaymentMethods(cartId: string | null): Promise<MagentoPaymentMethod[]>;
+    setShippingInformation(cartId: string | null, payload: MagentoShippingInformationPayload): Promise<MagentoShippingInformationResult>;
+    setCheckoutBillingAddress(cartId: string | null, address: MagentoCheckoutAddress): Promise<number>;
+    placeOrder(cartId: string | null, payload: MagentoPlaceOrderPayload): Promise<number>;
+    getCheckoutState(cartKey: string): Promise<MagentoCheckoutState>;
+    setCheckoutState(cartKey: string, state: MagentoCheckoutState): Promise<void>;
 }
 export {};

package/src/core/initialize.types.d.ts

@@ -1,4 +1,4 @@
-import type { CartFactory, CategoryFactory, ClientFromCapabilities, InventoryFactory, PriceFactory, ProductFactory, ProductSearchFactory } from '@reactionary/core';
+import type { CartFactory, CategoryFactory, ClientFromCapabilities, InventoryFactory, PriceFactory, ProductFactory, ProductSearchFactory, ProfileFactory, OrderSearchFactory, OrderFactory, CheckoutFactory, ProductAssociationsFactory, ProductReviewsFactory } from '@reactionary/core';
 import type { MagentoCapabilities } from '../schema/capabilities.schema.js';
 import type { MagentoCartFactory } from '../factories/cart/cart.factory.js';
 import type { MagentoCategoryFactory } from '../factories/category/category.factory.js';
@@ -6,6 +6,12 @@ import type { MagentoInventoryFactory } from '../factories/inventory/inventory.f
 import type { MagentoPriceFactory } from '../factories/price/price.factory.js';
 import type { MagentoProductFactory } from '../factories/product/product.factory.js';
 import type { MagentoProductSearchFactory } from '../factories/product-search/product-search.factory.js';
+import type { MagentoProfileFactory } from '../factories/profile/profile.factory.js';
+import type { MagentoOrderSearchFactory } from '../factories/order-search/order-search.factory.js';
+import type { MagentoOrderFactory } from '../factories/order/order.factory.js';
+import type { MagentoCheckoutFactory } from '../factories/checkout/checkout.factory.js';
+import type { MagentoProductAssociationsFactory } from '../factories/product-associations/product-associations.factory.js';
+import type { MagentoProductReviewsFactory } from '../factories/product-reviews/product-reviews.factory.js';
 import type { MagentoCartCapability } from '../capabilities/cart.capability.js';
 import type { MagentoCategoryCapability } from '../capabilities/category.capability.js';
 import type { MagentoIdentityCapability } from '../capabilities/identity.capability.js';
@@ -13,14 +19,22 @@ import type { MagentoInventoryCapability } from '../capabilities/inventory.capab
 import type { MagentoPriceCapability } from '../capabilities/price.capability.js';
 import type { MagentoProductCapability } from '../capabilities/product.capability.js';
 import type { MagentoProductSearchCapability } from '../capabilities/product-search.capability.js';
-type OverridableCapabilityKey = 'product' | 'productSearch' | 'cart' | 'category' | 'price' | 'inventory';
+import type { MagentoProfileCapability } from '../capabilities/profile.capability.js';
+import type { MagentoOrderSearchCapability } from '../capabilities/order-search.capability.js';
+import type { MagentoOrderCapability } from '../capabilities/order.capability.js';
+import type { MagentoCheckoutCapability } from '../capabilities/checkout.capability.js';
+import type { MagentoProductAssociationsCapability } from '../capabilities/product-associations.capability.js';
+import type { MagentoProductRecommendationsCapability } from '../capabilities/product-recommendations.capability.js';
+import type { MagentoProductReviewsCapability } from '../capabilities/product-reviews.capability.js';
+type OverridableCapabilityKey = 'product' | 'productSearch' | 'cart' | 'category' | 'price' | 'inventory' | 'profile' | 'orderSearch' | 'order' | 'checkout' | 'productAssociations' | 'productReviews';
+type DirectCapabilityKey = 'identity' | 'productRecommendations';
 type EnabledCapability<TCapability> = TCapability extends {
     enabled: true;
 } ? true : false;
-type NormalizeConfiguredCapabilities<T extends MagentoCapabilities> = Omit<T, OverridableCapabilityKey | 'identity'> & {
+type NormalizeConfiguredCapabilities<T extends MagentoCapabilities> = Omit<T, OverridableCapabilityKey | DirectCapabilityKey> & {
     [K in OverridableCapabilityKey]?: EnabledCapability<T[K]>;
 } & {
-    identity?: EnabledCapability<T['identity']>;
+    [K in DirectCapabilityKey]?: EnabledCapability<T[K]>;
 };
 type ExtractCapabilityFactory<TCapability, TContract, TDefaultFactory> = TCapability extends {
     enabled: true;
@@ -37,6 +51,12 @@ type FactoryContractMap = {
     category: CategoryFactory;
     price: PriceFactory;
     inventory: InventoryFactory;
+    profile: ProfileFactory;
+    orderSearch: OrderSearchFactory;
+    order: OrderFactory;
+    checkout: CheckoutFactory;
+    productAssociations: ProductAssociationsFactory;
+    productReviews: ProductReviewsFactory;
 };
 type DefaultFactoryMap = {
     product: MagentoProductFactory;
@@ -45,6 +65,12 @@ type DefaultFactoryMap = {
     category: MagentoCategoryFactory;
     price: MagentoPriceFactory;
     inventory: MagentoInventoryFactory;
+    profile: MagentoProfileFactory;
+    orderSearch: MagentoOrderSearchFactory;
+    order: MagentoOrderFactory;
+    checkout: MagentoCheckoutFactory;
+    productAssociations: MagentoProductAssociationsFactory;
+    productReviews: MagentoProductReviewsFactory;
 };
 type ResolvedFactoryMap<T extends MagentoCapabilities> = {
     [K in OverridableCapabilityKey]: ExtractCapabilityFactory<T[K], FactoryContractMap[K], DefaultFactoryMap[K]>;
@@ -56,17 +82,24 @@ type DefaultCapabilityMap<T extends MagentoCapabilities> = {
     category: MagentoCategoryCapability<ResolvedFactoryMap<T>['category']>;
     price: MagentoPriceCapability<ResolvedFactoryMap<T>['price']>;
     inventory: MagentoInventoryCapability<ResolvedFactoryMap<T>['inventory']>;
+    profile: MagentoProfileCapability<ResolvedFactoryMap<T>['profile']>;
+    orderSearch: MagentoOrderSearchCapability<ResolvedFactoryMap<T>['orderSearch']>;
+    order: MagentoOrderCapability<ResolvedFactoryMap<T>['order']>;
+    checkout: MagentoCheckoutCapability<ResolvedFactoryMap<T>['checkout']>;
+    productAssociations: MagentoProductAssociationsCapability<ResolvedFactoryMap<T>['productAssociations']>;
+    productReviews: MagentoProductReviewsCapability<ResolvedFactoryMap<T>['productReviews']>;
+    productRecommendations: MagentoProductRecommendationsCapability;
     identity: MagentoIdentityCapability;
 };
 type CapabilityImplementationMap<T extends MagentoCapabilities> = {
-    [K in OverridableCapabilityKey | 'identity']: ExtractCapabilityImplementation<T[K], DefaultCapabilityMap<T>[K]>;
+    [K in OverridableCapabilityKey | DirectCapabilityKey]: ExtractCapabilityImplementation<T[K], DefaultCapabilityMap<T>[K]>;
 };
 type EnabledCapabilityOverrideMap<T extends MagentoCapabilities> = {
-    [K in OverridableCapabilityKey | 'identity' as T[K] extends {
+    [K in OverridableCapabilityKey | DirectCapabilityKey as T[K] extends {
         enabled: true;
     } ? K : never]: CapabilityImplementationMap<T>[K];
 };
-export type MagentoClientFromCapabilities<T extends MagentoCapabilities> = Omit<ClientFromCapabilities<NormalizeConfiguredCapabilities<T>>, OverridableCapabilityKey | 'identity'> & EnabledCapabilityOverrideMap<T>;
+export type MagentoClientFromCapabilities<T extends MagentoCapabilities> = Omit<ClientFromCapabilities<NormalizeConfiguredCapabilities<T>>, OverridableCapabilityKey | DirectCapabilityKey> & EnabledCapabilityOverrideMap<T>;
 export declare function resolveCapabilityWithFactory<TFactory, TResolvedCapability, TCapabilityArgs>(capability: {
     factory?: TFactory;
     capability?: (args: TCapabilityArgs) => TResolvedCapability;

package/src/core/product-reviews.graphql.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Magento's REST API carries no reviews or ratings, so everything the product
+ * reviews capability needs is fetched through the GraphQL endpoint. Reviews are
+ * reachable only as a nested field on `products`, which is why every document
+ * here starts from a single-SKU product lookup.
+ */
+export declare const PRODUCT_RATING_SUMMARY_QUERY = "\n  query ReactionaryProductRatingSummary($sku: String!) {\n    products(filter: { sku: { eq: $sku } }, pageSize: 1, currentPage: 1) {\n      items {\n        sku\n        rating_summary\n        review_count\n      }\n    }\n  }\n";
+export declare const PRODUCT_REVIEWS_QUERY = "\n  query ReactionaryProductReviews($sku: String!, $pageSize: Int!, $currentPage: Int!) {\n    products(filter: { sku: { eq: $sku } }, pageSize: 1, currentPage: 1) {\n      items {\n        sku\n        rating_summary\n        review_count\n        reviews(pageSize: $pageSize, currentPage: $currentPage) {\n          items {\n\n  average_rating\n  created_at\n  nickname\n  summary\n  text\n  ratings_breakdown {\n    name\n    value\n  }\n\n          }\n          page_info {\n            page_size\n            current_page\n            total_pages\n          }\n        }\n      }\n    }\n  }\n";
+export declare const PRODUCT_REVIEW_RATINGS_METADATA_QUERY = "\n  query ReactionaryProductReviewRatingsMetadata {\n    productReviewRatingsMetadata {\n      items {\n        id\n        name\n        values {\n          value_id\n          value\n        }\n      }\n    }\n  }\n";
+export declare const CREATE_PRODUCT_REVIEW_MUTATION = "\n  mutation ReactionaryCreateProductReview($input: CreateProductReviewInput!) {\n    createProductReview(input: $input) {\n      review {\n\n  average_rating\n  created_at\n  nickname\n  summary\n  text\n  ratings_breakdown {\n    name\n    value\n  }\n\n      }\n    }\n  }\n";

package/src/factories/category/category.factory.d.ts

@@ -1,4 +1,4 @@
-import { type AnyCategoryPaginatedResultSchema, type AnyCategorySchema, type CategoryFactory, type CategoryPaginatedResultSchema, type CategorySchema, type RequestContext } from '@reactionary/core';
+import { type AnyCategoryPaginatedResultSchema, type AnyCategorySchema, type CategoryFactory, type CategoryPaginatedResultSchema, type CategoryQueryForChildCategories, type CategoryQueryForTopCategories, type CategorySchema, type RequestContext } from '@reactionary/core';
 import type * as z from 'zod';
 import type { MagentoCategory, MagentoCategorySearchResult } from '../../schema/magento.types.js';
 export interface MagentoCategoryPaginatedInput extends MagentoCategorySearchResult {
@@ -10,5 +10,5 @@ export declare class MagentoCategoryFactory<TCategorySchema extends AnyCategoryS
     readonly categoryPaginatedResultSchema: TCategoryPaginatedSchema;
     constructor(categorySchema: TCategorySchema, categoryPaginatedResultSchema: TCategoryPaginatedSchema);
     parseCategory(_context: RequestContext, data: MagentoCategory): z.output<TCategorySchema>;
-    parseCategoryPaginatedResult(context: RequestContext, data: MagentoCategoryPaginatedInput): z.output<TCategoryPaginatedSchema>;
+    parseCategoryPaginatedResult(context: RequestContext, data: MagentoCategoryPaginatedInput, _query: CategoryQueryForTopCategories | CategoryQueryForChildCategories): z.output<TCategoryPaginatedSchema>;
 }