@reactionary/magento 0.0.1 → 0.10.18

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

@@ -0,0 +1,32 @@
+import { type Address, type AnyCheckoutSchema, type AnyPaymentMethodSchema, type AnyShippingMethodSchema, type CheckoutFactory, type CheckoutItem, type CheckoutSchema, type CostBreakDown, type Currency, type ItemCostBreakdown, type PaymentInstruction, type PaymentMethodSchema, type RequestContext, type ShippingInstruction, type ShippingMethodSchema } from '@reactionary/core';
+import type * as z from 'zod';
+import type { MagentoConfiguration } from '../../schema/configuration.schema.js';
+import type { MagentoCart, MagentoCartItem, MagentoCartTotals, MagentoCheckoutAddress, MagentoCheckoutState, MagentoStoredPaymentInstruction } from '../../schema/magento.types.js';
+export interface MagentoCheckoutData {
+    cart: MagentoCart;
+    totals?: MagentoCartTotals;
+    state?: MagentoCheckoutState;
+    requestedKey?: string;
+}
+/**
+ * Builds a stable shipping-method identifier key from a Magento carrier/method
+ * pair, and parses it back. Magento identifies a rate by both codes.
+ */
+export declare function encodeShippingMethodKey(carrierCode: string, methodCode: string): string;
+export declare class MagentoCheckoutFactory<TCheckoutSchema extends AnyCheckoutSchema = typeof CheckoutSchema, TShippingMethodSchema extends AnyShippingMethodSchema = typeof ShippingMethodSchema, TPaymentMethodSchema extends AnyPaymentMethodSchema = typeof PaymentMethodSchema> implements CheckoutFactory<TCheckoutSchema, TShippingMethodSchema, TPaymentMethodSchema> {
+    readonly checkoutSchema: TCheckoutSchema;
+    readonly shippingMethodSchema: TShippingMethodSchema;
+    readonly paymentMethodSchema: TPaymentMethodSchema;
+    protected readonly config: MagentoConfiguration;
+    constructor(checkoutSchema: TCheckoutSchema, shippingMethodSchema: TShippingMethodSchema, paymentMethodSchema: TPaymentMethodSchema, config: MagentoConfiguration);
+    protected resolveCurrency(data: MagentoCheckoutData): Currency;
+    protected parseAddress(address: MagentoCheckoutAddress): Address;
+    protected parseCostBreakdown(data: MagentoCheckoutData, currency: Currency): CostBreakDown;
+    protected parseItemPrice(item: MagentoCartItem, currency: Currency): ItemCostBreakdown;
+    protected parseCheckoutItem(item: MagentoCartItem, currency: Currency): CheckoutItem;
+    protected parsePaymentInstruction(stored: MagentoStoredPaymentInstruction): PaymentInstruction;
+    protected parseShippingInstruction(state: MagentoCheckoutState): ShippingInstruction | undefined;
+    parseCheckout(_context: RequestContext, data: unknown): z.output<TCheckoutSchema>;
+    parseShippingMethod(_context: RequestContext, data: unknown): z.output<TShippingMethodSchema>;
+    parsePaymentMethod(_context: RequestContext, data: unknown): z.output<TPaymentMethodSchema>;
+}

package/src/factories/index.d.ts

@@ -5,3 +5,9 @@ export * from './inventory/inventory.factory.js';
 export * from './price/price.factory.js';
 export * from './product/product.factory.js';
 export * from './product-search/product-search.factory.js';
+export * from './profile/profile.factory.js';
+export * from './order-search/order-search.factory.js';
+export * from './order/order.factory.js';
+export * from './checkout/checkout.factory.js';
+export * from './product-associations/product-associations.factory.js';
+export * from './product-reviews/product-reviews.factory.js';

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

@@ -0,0 +1,77 @@
+import { type Address, type AnyOrderSchema, type CostBreakDown, type Currency, type Order, type OrderFactory, type OrderItem, type OrderSchema, type PaymentInstruction, type RequestContext, type ShippingMethod } from '@reactionary/core';
+import type * as z from 'zod';
+export interface MagentoOrderDetailAddress {
+    firstname?: string;
+    lastname?: string;
+    street?: string[];
+    city?: string;
+    region?: string;
+    postcode?: string;
+    country_id?: string;
+    telephone?: string;
+    email?: string;
+    entity_id?: number;
+}
+export interface MagentoOrderDetailItem {
+    item_id: number;
+    sku: string;
+    name?: string;
+    qty_ordered?: number;
+    price?: number;
+    row_total?: number;
+}
+export interface MagentoOrderDetailPayment {
+    method?: string;
+    amount_ordered?: number;
+}
+export interface MagentoOrderDetail {
+    entity_id: number;
+    increment_id?: string;
+    customer_id?: number;
+    customer_email?: string;
+    customer_firstname?: string;
+    customer_lastname?: string;
+    status?: string;
+    state?: string;
+    created_at?: string;
+    order_currency_code?: string;
+    grand_total?: number;
+    subtotal?: number;
+    shipping_amount?: number;
+    discount_amount?: number;
+    tax_amount?: number;
+    shipping_description?: string;
+    items?: MagentoOrderDetailItem[];
+    billing_address?: MagentoOrderDetailAddress;
+    payment?: MagentoOrderDetailPayment;
+    extension_attributes?: {
+        shipping_assignments?: Array<{
+            shipping?: {
+                address?: MagentoOrderDetailAddress;
+                method?: string;
+            };
+        }>;
+    };
+}
+/**
+ * Fields the confirmation-page use case needs that core's Order schema
+ * doesn't declare (no date field at all, no contact info on Address). Order
+ * schemas are z.looseObject-based, so these survive orderSchema.parse()
+ * unchanged even though the base Order type doesn't know about them.
+ */
+export interface MagentoOrderOutput extends Order {
+    orderDate: string;
+    incrementId?: string;
+    customerEmail?: string;
+    customerPhone?: string;
+}
+export declare class MagentoOrderFactory<TOrderSchema extends AnyOrderSchema = typeof OrderSchema> implements OrderFactory<TOrderSchema> {
+    readonly orderSchema: TOrderSchema;
+    constructor(orderSchema: TOrderSchema);
+    protected parseAddress(address?: MagentoOrderDetailAddress): Address | undefined;
+    protected parseOrderItem(order: MagentoOrderDetail, item: MagentoOrderDetailItem, currency: Currency): OrderItem;
+    protected parseCostBreakdown(order: MagentoOrderDetail, currency: Currency): CostBreakDown;
+    protected parsePaymentInstruction(order: MagentoOrderDetail, currency: Currency): PaymentInstruction;
+    protected parseShippingMethod(order: MagentoOrderDetail, method: string | undefined, currency: Currency): ShippingMethod | undefined;
+    parseOrder(_context: RequestContext, data: unknown): z.output<TOrderSchema>;
+}

package/src/factories/order-search/order-search.factory.d.ts

@@ -0,0 +1,43 @@
+import { type Address, type AnyOrderSearchResultSchema, type OrderSearchFactory, type OrderSearchQueryByTerm, type OrderSearchResultItem, type OrderSearchResultSchema, type OrderStatus, type RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+export interface MagentoOrderAddress {
+    firstname?: string;
+    lastname?: string;
+    street?: string[];
+    city?: string;
+    region?: string;
+    region_code?: string;
+    postcode?: string;
+    country_id?: string;
+    entity_id?: number;
+}
+export interface MagentoOrder {
+    entity_id: number;
+    increment_id?: string;
+    customer_id?: number;
+    customer_email?: string;
+    customer_firstname?: string;
+    customer_lastname?: string;
+    status?: string;
+    state?: string;
+    grand_total?: number;
+    order_currency_code?: string;
+    created_at?: string;
+    billing_address?: MagentoOrderAddress;
+}
+export interface MagentoOrderListResponse {
+    items?: MagentoOrder[];
+    total_count?: number;
+    search_criteria?: {
+        page_size?: number;
+        current_page?: number;
+    };
+}
+export declare function mapMagentoOrderStatus(status?: string): OrderStatus;
+export declare class MagentoOrderSearchFactory<TOrderSearchResultSchema extends AnyOrderSearchResultSchema = typeof OrderSearchResultSchema> implements OrderSearchFactory<TOrderSearchResultSchema> {
+    readonly orderSearchResultSchema: TOrderSearchResultSchema;
+    constructor(orderSearchResultSchema: TOrderSearchResultSchema);
+    protected parseAddress(address: MagentoOrderAddress): Address;
+    protected parseOrderSearchResultItem(_context: RequestContext, order: MagentoOrder): OrderSearchResultItem;
+    parseOrderSearchResult(context: RequestContext, data: unknown, query: OrderSearchQueryByTerm): z.output<TOrderSearchResultSchema>;
+}

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

@@ -1,4 +1,4 @@
-import { type AnyProductSchema, type ProductAttribute, type ProductFactory, type ProductSchema, type ProductVariant, type RequestContext } from '@reactionary/core';
+import { type AnyProductSchema, type Image, type ProductAttribute, type ProductFactory, type ProductSchema, type ProductVariant, type RequestContext } from '@reactionary/core';
 import type * as z from 'zod';
 import type { MagentoConfiguration } from '../../schema/configuration.schema.js';
 import type { MagentoProduct } from '../../schema/magento.types.js';
@@ -8,6 +8,7 @@ export declare class MagentoProductFactory<TProductSchema extends AnyProductSche
     constructor(productSchema: TProductSchema, config: MagentoConfiguration);
     parseProduct(_context: RequestContext, data: MagentoProduct): z.output<TProductSchema>;
     protected parseVariant(product: MagentoProduct): ProductVariant;
+    protected parseImages(product: MagentoProduct): Image[];
     protected createSynthAttribute(key: string, name: string, value: string): ProductAttribute;
     protected parseAttributes(product: MagentoProduct): Array<ProductAttribute>;
 }

package/src/factories/product-associations/product-associations.factory.d.ts

@@ -0,0 +1,15 @@
+import { type AnyProductAssociationSchema, type ProductAssociationSchema, type ProductAssociationsFactory, type ProductAssociationsIdentifier, type ProductSearchResultItem, type RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+import type { MagentoConfiguration } from '../../schema/configuration.schema.js';
+import type { MagentoProduct } from '../../schema/magento.types.js';
+export interface MagentoProductAssociationFactoryInput {
+    product: MagentoProduct;
+    identifier: ProductAssociationsIdentifier;
+}
+export declare class MagentoProductAssociationsFactory<TProductAssociationSchema extends AnyProductAssociationSchema = typeof ProductAssociationSchema> implements ProductAssociationsFactory<TProductAssociationSchema> {
+    readonly productAssociationSchema: TProductAssociationSchema;
+    protected readonly config: MagentoConfiguration;
+    constructor(productAssociationSchema: TProductAssociationSchema, config: MagentoConfiguration);
+    protected parseProduct(_context: RequestContext, product: MagentoProduct): ProductSearchResultItem;
+    parseAssociation(context: RequestContext, data: MagentoProductAssociationFactoryInput): z.output<TProductAssociationSchema>;
+}

package/src/factories/product-reviews/product-reviews.factory.d.ts

@@ -0,0 +1,40 @@
+import type { AnyProductRatingSummarySchema, AnyProductReviewPaginatedSchema, AnyProductReviewSchema, ProductIdentifier, ProductRatingSummarySchema, ProductReviewPaginatedResultSchema, ProductReviewSchema, ProductReviewsFactory, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+import type { MagentoProductReview } from '../../schema/magento.types.js';
+export interface MagentoProductRatingSummaryFactoryInput {
+    product: ProductIdentifier;
+    /** Magento's `rating_summary`, a percentage (0-100). */
+    ratingSummary: number | null | undefined;
+    /** Magento's `review_count`. */
+    reviewCount: number | null | undefined;
+}
+export interface MagentoProductReviewFactoryInput {
+    product: ProductIdentifier;
+    sku: string;
+    review: MagentoProductReview;
+}
+export interface MagentoProductReviewPaginatedFactoryInput {
+    product: ProductIdentifier;
+    sku: string;
+    reviews: MagentoProductReview[];
+    totalCount: number;
+    pageSize: number;
+    pageNumber: number;
+}
+export declare class MagentoProductReviewsFactory<TRatingSummarySchema extends AnyProductRatingSummarySchema = typeof ProductRatingSummarySchema, TReviewSchema extends AnyProductReviewSchema = typeof ProductReviewSchema, TReviewPaginatedSchema extends AnyProductReviewPaginatedSchema = typeof ProductReviewPaginatedResultSchema> implements ProductReviewsFactory<TRatingSummarySchema, TReviewSchema, TReviewPaginatedSchema> {
+    readonly ratingSummarySchema: TRatingSummarySchema;
+    readonly reviewSchema: TReviewSchema;
+    readonly reviewPaginatedSchema: TReviewPaginatedSchema;
+    constructor(ratingSummarySchema: TRatingSummarySchema, reviewSchema: TReviewSchema, reviewPaginatedSchema: TReviewPaginatedSchema);
+    /**
+     * Magento's GraphQL schema offers no per-star breakdown, so the distribution
+     * is left undefined rather than reconstructed from the current page.
+     */
+    parseRatingSummary(_context: RequestContext, data: MagentoProductRatingSummaryFactoryInput): z.output<TRatingSummarySchema>;
+    /**
+     * Magento does not expose whether a review came from a confirmed purchase, so
+     * `verified` is always false.
+     */
+    parseReview(_context: RequestContext, data: MagentoProductReviewFactoryInput): z.output<TReviewSchema>;
+    parseReviewPaginatedResult(context: RequestContext, data: MagentoProductReviewPaginatedFactoryInput): z.output<TReviewPaginatedSchema>;
+}

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

@@ -0,0 +1,43 @@
+import type { Address, AnyProfileSchema, ProfileFactory, ProfileSchema, RequestContext } from '@reactionary/core';
+import type * as z from 'zod';
+export interface MagentoAddress {
+    id?: number;
+    customer_id?: number;
+    company?: string;
+    firstname?: string;
+    lastname?: string;
+    street?: string[];
+    city?: string;
+    region?: {
+        region_code?: string;
+        region?: string;
+        region_id?: number;
+    };
+    region_id?: number;
+    postcode?: string;
+    country_id?: string;
+    telephone?: string;
+    default_billing?: boolean;
+    default_shipping?: boolean;
+}
+export interface MagentoCustomer {
+    id: number;
+    email: string;
+    firstname?: string;
+    lastname?: string;
+    created_at?: string;
+    updated_at?: string;
+    default_billing?: string;
+    default_shipping?: string;
+    addresses?: MagentoAddress[];
+    custom_attributes?: {
+        attribute_code: string;
+        value: string;
+    }[];
+}
+export declare class MagentoProfileFactory<TProfileSchema extends AnyProfileSchema = typeof ProfileSchema> implements ProfileFactory<TProfileSchema> {
+    readonly profileSchema: TProfileSchema;
+    constructor(profileSchema: TProfileSchema);
+    parseProfile(context: RequestContext, data: unknown): z.output<TProfileSchema>;
+    protected parseAddress(_context: RequestContext, address: MagentoAddress): Address;
+}

package/src/index.d.ts

@@ -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/src/schema/capabilities.schema.d.ts

@@ -1,4 +1,4 @@
-import type { CartFactory, CartFactoryWithOutput, CartCapability, CategoryFactory, CategoryFactoryWithOutput, CategoryCapability, IdentityCapability, InventoryFactory, InventoryFactoryWithOutput, InventoryCapability, PriceFactory, PriceFactoryWithOutput, PriceCapability, ProductFactory, ProductFactoryWithOutput, ProductCapability, ProductSearchFactory, ProductSearchFactoryWithOutput, ProductSearchCapability, RequestContext, Cache } from '@reactionary/core';
+import type { CartFactory, CartFactoryWithOutput, CartCapability, CategoryFactory, CategoryFactoryWithOutput, CategoryCapability, IdentityCapability, InventoryFactory, InventoryFactoryWithOutput, InventoryCapability, PriceFactory, PriceFactoryWithOutput, PriceCapability, ProductFactory, ProductFactoryWithOutput, ProductCapability, ProductSearchFactory, ProductSearchFactoryWithOutput, ProductSearchCapability, ProfileFactory, ProfileFactoryWithOutput, ProfileCapability, OrderSearchFactory, OrderSearchFactoryWithOutput, OrderSearchCapability, OrderFactory, OrderFactoryWithOutput, OrderCapability, CheckoutFactory, CheckoutFactoryWithOutput, CheckoutCapability, ProductAssociationsFactory, ProductAssociationsFactoryWithOutput, ProductAssociationsCapability, ProductRecommendationsCapability, ProductReviewsFactory, ProductReviewsFactoryWithOutput, ProductReviewsCapability, RequestContext, Cache } from '@reactionary/core';
 import type { MagentoConfiguration } from './configuration.schema.js';
 import type { MagentoClient } from '../core/client.js';
 import * as z from 'zod';
@@ -37,6 +37,40 @@ export declare const MagentoCapabilitiesSchema: z.ZodObject<{
         enabled: z.ZodBoolean;
         capability: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$loose>>>;
+    profile: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    orderSearch: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    order: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    checkout: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    productAssociations: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    productRecommendations: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
+    productReviews: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
 }, z.core.$loose>;
 export interface MagentoCapabilityFactoryArgs {
     cache: Cache;
@@ -63,7 +97,14 @@ export type MagentoCategoryCapabilityConfig = MagentoCapabilityConfig<CategoryFa
 export type MagentoPriceCapabilityConfig = MagentoCapabilityConfig<PriceFactoryWithOutput<PriceFactory>, PriceCapability>;
 export type MagentoInventoryCapabilityConfig = MagentoCapabilityConfig<InventoryFactoryWithOutput<InventoryFactory>, InventoryCapability>;
 export type MagentoIdentityCapabilityConfig = MagentoDirectCapabilityConfig<IdentityCapability>;
-export type MagentoCapabilities<TProductFactory extends ProductFactory = ProductFactory, TProductCapability extends ProductCapability = ProductCapability, TProductSearchFactory extends ProductSearchFactory = ProductSearchFactory, TProductSearchCapability extends ProductSearchCapability = ProductSearchCapability, TCartFactory extends CartFactory = CartFactory, TCartCapability extends CartCapability = CartCapability, TCategoryFactory extends CategoryFactory = CategoryFactory, TCategoryCapability extends CategoryCapability = CategoryCapability, TPriceFactory extends PriceFactory = PriceFactory, TPriceCapability extends PriceCapability = PriceCapability, TInventoryFactory extends InventoryFactory = InventoryFactory, TInventoryCapability extends InventoryCapability = InventoryCapability, TIdentityCapability extends IdentityCapability = IdentityCapability> = {
+export type MagentoProfileCapabilityConfig = MagentoCapabilityConfig<ProfileFactoryWithOutput<ProfileFactory>, ProfileCapability>;
+export type MagentoOrderSearchCapabilityConfig = MagentoCapabilityConfig<OrderSearchFactoryWithOutput<OrderSearchFactory>, OrderSearchCapability>;
+export type MagentoOrderCapabilityConfig = MagentoCapabilityConfig<OrderFactoryWithOutput<OrderFactory>, OrderCapability>;
+export type MagentoCheckoutCapabilityConfig = MagentoCapabilityConfig<CheckoutFactoryWithOutput<CheckoutFactory>, CheckoutCapability>;
+export type MagentoProductAssociationsCapabilityConfig = MagentoCapabilityConfig<ProductAssociationsFactoryWithOutput<ProductAssociationsFactory>, ProductAssociationsCapability>;
+export type MagentoProductRecommendationsCapabilityConfig = MagentoDirectCapabilityConfig<ProductRecommendationsCapability>;
+export type MagentoProductReviewsCapabilityConfig = MagentoCapabilityConfig<ProductReviewsFactoryWithOutput<ProductReviewsFactory>, ProductReviewsCapability>;
+export type MagentoCapabilities<TProductFactory extends ProductFactory = ProductFactory, TProductCapability extends ProductCapability = ProductCapability, TProductSearchFactory extends ProductSearchFactory = ProductSearchFactory, TProductSearchCapability extends ProductSearchCapability = ProductSearchCapability, TCartFactory extends CartFactory = CartFactory, TCartCapability extends CartCapability = CartCapability, TCategoryFactory extends CategoryFactory = CategoryFactory, TCategoryCapability extends CategoryCapability = CategoryCapability, TPriceFactory extends PriceFactory = PriceFactory, TPriceCapability extends PriceCapability = PriceCapability, TInventoryFactory extends InventoryFactory = InventoryFactory, TInventoryCapability extends InventoryCapability = InventoryCapability, TIdentityCapability extends IdentityCapability = IdentityCapability, TProfileFactory extends ProfileFactory = ProfileFactory, TProfileCapability extends ProfileCapability = ProfileCapability, TOrderSearchFactory extends OrderSearchFactory = OrderSearchFactory, TOrderSearchCapability extends OrderSearchCapability = OrderSearchCapability, TOrderFactory extends OrderFactory = OrderFactory, TOrderCapability extends OrderCapability = OrderCapability, TCheckoutFactory extends CheckoutFactory = CheckoutFactory, TCheckoutCapability extends CheckoutCapability = CheckoutCapability, TProductAssociationsFactory extends ProductAssociationsFactory = ProductAssociationsFactory, TProductAssociationsCapability extends ProductAssociationsCapability = ProductAssociationsCapability, TProductRecommendationsCapability extends ProductRecommendationsCapability = ProductRecommendationsCapability, TProductReviewsFactory extends ProductReviewsFactory = ProductReviewsFactory, TProductReviewsCapability extends ProductReviewsCapability = ProductReviewsCapability> = {
     product?: MagentoCapabilityConfig<ProductFactoryWithOutput<TProductFactory>, TProductCapability>;
     productSearch?: MagentoCapabilityConfig<ProductSearchFactoryWithOutput<TProductSearchFactory>, TProductSearchCapability>;
     cart?: MagentoCapabilityConfig<CartFactoryWithOutput<TCartFactory>, TCartCapability>;
@@ -71,4 +112,11 @@ export type MagentoCapabilities<TProductFactory extends ProductFactory = Product
     price?: MagentoCapabilityConfig<PriceFactoryWithOutput<TPriceFactory>, TPriceCapability>;
     inventory?: MagentoCapabilityConfig<InventoryFactoryWithOutput<TInventoryFactory>, TInventoryCapability>;
     identity?: MagentoDirectCapabilityConfig<TIdentityCapability>;
+    profile?: MagentoCapabilityConfig<ProfileFactoryWithOutput<TProfileFactory>, TProfileCapability>;
+    orderSearch?: MagentoCapabilityConfig<OrderSearchFactoryWithOutput<TOrderSearchFactory>, TOrderSearchCapability>;
+    order?: MagentoCapabilityConfig<OrderFactoryWithOutput<TOrderFactory>, TOrderCapability>;
+    checkout?: MagentoCapabilityConfig<CheckoutFactoryWithOutput<TCheckoutFactory>, TCheckoutCapability>;
+    productAssociations?: MagentoCapabilityConfig<ProductAssociationsFactoryWithOutput<TProductAssociationsFactory>, TProductAssociationsCapability>;
+    productRecommendations?: MagentoDirectCapabilityConfig<TProductRecommendationsCapability>;
+    productReviews?: MagentoCapabilityConfig<ProductReviewsFactoryWithOutput<TProductReviewsFactory>, TProductReviewsCapability>;
 };

package/src/schema/configuration.schema.d.ts

@@ -3,9 +3,16 @@ export declare const MagentoConfigurationSchema: z.ZodObject<{
     adminApiKey: z.ZodString;
     baseUrl: z.ZodString;
     mediaUrl: z.ZodOptional<z.ZodString>;
+    mediaSource: z.ZodDefault<z.ZodEnum<{
+        EXTERNAL: "EXTERNAL";
+        DEFAULT: "DEFAULT";
+    }>>;
     defaultCurrency: z.ZodDefault<z.ZodString>;
     rootCategoryId: z.ZodDefault<z.ZodString>;
     allCurrencies: z.ZodArray<z.ZodString>;
+    graphqlUrl: z.ZodOptional<z.ZodString>;
+    reviewRatingCode: z.ZodOptional<z.ZodString>;
     storeCode: z.ZodDefault<z.ZodString>;
+    authStoreCode: z.ZodDefault<z.ZodString>;
 }, z.core.$loose>;
 export type MagentoConfiguration = z.infer<typeof MagentoConfigurationSchema>;

package/src/schema/magento.types.d.ts

@@ -25,6 +25,7 @@ export interface MagentoExtensionAttributes {
     category_links?: MagentoCategoryLink[];
     website_ids?: number[];
     stock_item?: MagentoStockItem;
+    external_id?: string | number;
     [key: string]: unknown;
 }
 export interface MagentoStockItem {
@@ -198,3 +199,221 @@ export interface MagentoProductSearchResult {
     search_criteria?: Record<string, unknown>;
     total_count: number;
 }
+/** The native Magento product link types. */
+export type MagentoProductLinkType = 'related' | 'upsell' | 'crosssell';
+export interface MagentoProductLink {
+    sku: string;
+    link_type: string;
+    linked_product_sku: string;
+    linked_product_type?: string;
+    position?: number;
+}
+/**
+ * A Magento quote (checkout) address as accepted/returned by the checkout
+ * REST endpoints (estimate-shipping-methods, shipping-information, billing-address).
+ */
+export interface MagentoCheckoutAddress {
+    id?: number;
+    region?: string;
+    region_id?: number;
+    region_code?: string;
+    country_id?: string;
+    street?: string[];
+    company?: string;
+    telephone?: string;
+    postcode?: string;
+    city?: string;
+    firstname?: string;
+    lastname?: string;
+    email?: string;
+    same_as_billing?: number;
+    save_in_address_book?: number;
+}
+export interface MagentoShippingMethod {
+    carrier_code: string;
+    method_code: string;
+    carrier_title?: string;
+    method_title?: string;
+    amount: number;
+    base_amount?: number;
+    available: boolean;
+    error_message?: string;
+    price_excl_tax?: number;
+    price_incl_tax?: number;
+}
+export interface MagentoPaymentMethod {
+    code: string;
+    title: string;
+}
+export interface MagentoTotalSegment {
+    code: string;
+    title?: string;
+    value: number | null;
+}
+export interface MagentoCartTotals {
+    grand_total?: number;
+    base_grand_total?: number;
+    subtotal?: number;
+    base_subtotal?: number;
+    discount_amount?: number;
+    base_discount_amount?: number;
+    tax_amount?: number;
+    base_tax_amount?: number;
+    shipping_amount?: number;
+    base_shipping_amount?: number;
+    quote_currency_code?: string;
+    base_currency_code?: string;
+    items?: MagentoCartItem[];
+    total_segments?: MagentoTotalSegment[];
+}
+export interface MagentoShippingInformationResult {
+    payment_methods?: MagentoPaymentMethod[];
+    totals?: MagentoCartTotals;
+}
+/**
+ * The payment method payload for placing an order via payment-information.
+ */
+export interface MagentoPaymentMethodPayload {
+    method: string;
+    po_number?: string;
+    additional_data?: Record<string, string> | string[];
+}
+export interface MagentoPlaceOrderPayload {
+    email?: string;
+    paymentMethod: MagentoPaymentMethodPayload;
+    billingAddress?: MagentoCheckoutAddress;
+}
+export interface MagentoShippingInformationPayload {
+    addressInformation: {
+        shipping_address: MagentoCheckoutAddress;
+        billing_address?: MagentoCheckoutAddress;
+        shipping_method_code: string;
+        shipping_carrier_code: string;
+    };
+}
+/**
+ * A payment instruction the checkout capability keeps in the request session,
+ * because Magento does not persist pre-order payment intents on the quote.
+ */
+export interface MagentoStoredPaymentInstruction {
+    key: string;
+    method: string;
+    name: string;
+    paymentProcessor: string;
+    amountValue: number;
+    amountCurrency: string;
+    protocolData: Array<{
+        key: string;
+        value: string;
+    }>;
+    status: string;
+}
+export interface MagentoStoredShippingInstruction {
+    shippingMethodKey: string;
+    carrierCode: string;
+    methodCode: string;
+    instructions: string;
+    pickupPoint: string;
+    consentForUnattendedDelivery: boolean;
+}
+/**
+ * Checkout state the capability persists in the request session to bridge the
+ * gap between the reactionary checkout model and Magento's stateless quote flow.
+ */
+export interface MagentoCheckoutState {
+    email?: string;
+    phone?: string;
+    billingAddress?: MagentoCheckoutAddress;
+    shippingAddress?: MagentoCheckoutAddress;
+    shippingInstruction?: MagentoStoredShippingInstruction;
+    paymentInstructions?: MagentoStoredPaymentInstruction[];
+    orderId?: string;
+}
+/**
+ * The Magento REST API exposes no review or rating surface at all, so the
+ * product reviews capability talks to the GraphQL endpoint instead. These are
+ * the slices of Magento's `ProductReview` schema that the capability consumes.
+ */
+export interface MagentoGraphQLError {
+    message: string;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+export interface MagentoGraphQLResponse<TData> {
+    data?: TData;
+    errors?: MagentoGraphQLError[];
+}
+export interface MagentoProductReviewRatingBreakdown {
+    name: string;
+    value: string;
+}
+/**
+ * `average_rating` is a percentage (0-100), not a star count.
+ * Magento emits `created_at` as a MySQL datetime in UTC ("2024-05-04 12:00:00").
+ */
+export interface MagentoProductReview {
+    average_rating: number;
+    created_at: string;
+    nickname: string;
+    summary: string;
+    text: string;
+    ratings_breakdown?: MagentoProductReviewRatingBreakdown[];
+}
+export interface MagentoProductReviewsPageInfo {
+    page_size?: number;
+    current_page?: number;
+    total_pages?: number;
+}
+export interface MagentoProductReviews {
+    items: MagentoProductReview[];
+    page_info?: MagentoProductReviewsPageInfo;
+}
+/**
+ * `rating_summary` is a percentage (0-100) across all approved reviews.
+ * There is no rating distribution in the GraphQL schema.
+ */
+export interface MagentoReviewableProduct {
+    sku: string;
+    rating_summary?: number | null;
+    review_count?: number | null;
+    reviews?: MagentoProductReviews;
+}
+export interface MagentoProductReviewsQueryResult {
+    products?: {
+        items?: MagentoReviewableProduct[];
+    };
+}
+export interface MagentoProductReviewRatingValue {
+    value_id: string;
+    value: string;
+}
+export interface MagentoProductReviewRatingMetadata {
+    id: string;
+    name: string;
+    values: MagentoProductReviewRatingValue[];
+}
+export interface MagentoProductReviewRatingsMetadataQueryResult {
+    productReviewRatingsMetadata?: {
+        items?: MagentoProductReviewRatingMetadata[];
+    };
+}
+/**
+ * `value_id` is an opaque, store-specific id that has to be looked up through
+ * `productReviewRatingsMetadata` — the plain star count is not accepted.
+ */
+export interface MagentoCreateProductReviewRating {
+    id: string;
+    value_id: string;
+}
+export interface MagentoCreateProductReviewInput {
+    sku: string;
+    nickname: string;
+    summary: string;
+    text: string;
+    ratings: MagentoCreateProductReviewRating[];
+}
+export interface MagentoCreateProductReviewResult {
+    createProductReview?: {
+        review?: MagentoProductReview;
+    };
+}

package/src/utils/magento-product-lookup.d.ts

@@ -0,0 +1,15 @@
+import type { MagentoClient } from '../core/client.js';
+import type { MagentoCategory, MagentoProduct } from '../schema/magento.types.js';
+/**
+ * Reactionary addresses products by their `external_id`, while the Magento
+ * catalogue endpoints key off SKU. Falls back to `entity_id` and finally to
+ * treating the key as a SKU directly.
+ */
+export declare function resolveProductSku(magentoApi: MagentoClient, key: string): Promise<string | null>;
+export declare function fetchProductsBySkus(magentoApi: MagentoClient, skus: string[]): Promise<MagentoProduct[]>;
+export declare function fetchProductsInCategory(magentoApi: MagentoClient, categoryId: string, limit: number): Promise<MagentoProduct[]>;
+/**
+ * Magento has no notion of a product collection, so a collection name is
+ * resolved against the category tree by `external_id`, `url_key` and `name`.
+ */
+export declare function findCategoryByName(magentoApi: MagentoClient, collectionName: string): Promise<MagentoCategory | null>;