@reactionary/hcl 0.9.8 → 0.9.12

package/src/schema/capabilities.schema.d.ts

@@ -1,4 +1,4 @@
-import type { Cache, RequestContext, CartFactory, CartFactoryWithOutput, CartCapability, CategoryFactory, CategoryFactoryWithOutput, CategoryCapability, CheckoutFactory, CheckoutFactoryWithOutput, CheckoutCapability, InventoryFactory, InventoryFactoryWithOutput, InventoryCapability, PriceFactory, PriceFactoryWithOutput, PriceCapability, ProductFactory, ProductFactoryWithOutput, ProductCapability, ProductSearchFactory, ProductSearchFactoryWithOutput, ProductSearchCapability } from '@reactionary/core';
+import type { Cache, RequestContext, CartFactory, CartFactoryWithOutput, CartCapability, CategoryFactory, CategoryFactoryWithOutput, CategoryCapability, CheckoutFactory, CheckoutFactoryWithOutput, CheckoutCapability, IdentityFactory, IdentityFactoryWithOutput, IdentityCapability, InventoryFactory, InventoryFactoryWithOutput, InventoryCapability, OrderFactory, OrderFactoryWithOutput, OrderCapability, OrderSearchFactory, OrderSearchFactoryWithOutput, OrderSearchCapability, PriceFactory, PriceFactoryWithOutput, PriceCapability, ProductFactory, ProductFactoryWithOutput, ProductCapability, ProductSearchFactory, ProductSearchFactoryWithOutput, ProductSearchCapability, ProfileFactory, ProfileFactoryWithOutput, ProfileCapability } from '@reactionary/core';
 import type { HclConfiguration } from './configuration.schema.js';
 import type { HclClient } from '../core/client.js';
 import * as z from 'zod';
@@ -33,11 +33,31 @@ export declare const HclCapabilitiesSchema: z.ZodObject<{
         factory: z.ZodOptional<z.ZodUnknown>;
         capability: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$loose>>>;
+    identity: z.ZodOptional<z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        factory: z.ZodOptional<z.ZodUnknown>;
+        capability: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>>>;
     productSearch: z.ZodOptional<z.ZodOptional<z.ZodObject<{
         enabled: z.ZodBoolean;
         factory: z.ZodOptional<z.ZodUnknown>;
         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>>>;
+    order: 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>>>;
 }, z.core.$loose>;
 export type HclCapabilities = z.infer<typeof HclCapabilitiesSchema>;
 export interface HclCapabilityFactoryArgs {
@@ -61,3 +81,7 @@ export type HclInventoryCapabilityConfig = HclCapabilityConfig<InventoryFactoryW
 export type HclPriceCapabilityConfig = HclCapabilityConfig<PriceFactoryWithOutput<PriceFactory>, PriceCapability>;
 export type HclProductCapabilityConfig = HclCapabilityConfig<ProductFactoryWithOutput<ProductFactory>, ProductCapability>;
 export type HclProductSearchCapabilityConfig = HclCapabilityConfig<ProductSearchFactoryWithOutput<ProductSearchFactory>, ProductSearchCapability>;
+export type HclIdentityCapabilityConfig = HclCapabilityConfig<IdentityFactoryWithOutput<IdentityFactory>, IdentityCapability>;
+export type HclProfileCapabilityConfig = HclCapabilityConfig<ProfileFactoryWithOutput<ProfileFactory>, ProfileCapability>;
+export type HclOrderCapabilityConfig = HclCapabilityConfig<OrderFactoryWithOutput<OrderFactory>, OrderCapability>;
+export type HclOrderSearchCapabilityConfig = HclCapabilityConfig<OrderSearchFactoryWithOutput<OrderSearchFactory>, OrderSearchCapability>;

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

@@ -15,5 +15,11 @@ export declare const HclConfigurationSchema: z.ZodObject<{
         productSearch: z.ZodDefault<z.ZodString>;
         categoryBrowse: z.ZodDefault<z.ZodString>;
     }, z.core.$loose>>;
+    /**
+     * Optional price rule ID passed to /display_price?q=byPartNumbersAndPriceRuleId.
+     * When omitted the server applies its default configured price rule.
+     * In Karkkainen this is '10003'.
+     */
+    priceRuleId: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export type HclConfiguration = z.infer<typeof HclConfigurationSchema>;

package/src/schema/hcl.schema.d.ts

@@ -8,6 +8,108 @@ export interface HclPrice {
     description: string;
     currency: string;
     value: string;
+    /** B2B contract identifier. Present on Offer-usage entries when a contract price applies. */
+    contractId?: string;
+}
+/**
+ * A single unit price entry in a /display_price response item.
+ * `value` is already a number (unlike the inline `HclPrice.value` which is a string).
+ */
+export interface HclDisplayPriceUnitPrice {
+    price?: {
+        currency?: string;
+        /** Numeric value — already a number, not a string. */
+        value?: number;
+    };
+    quantity?: {
+        value?: number;
+        uom?: string;
+    };
+}
+/**
+ * A single item in the `resultList` of a /display_price response.
+ * Returned for both `byPartNumbersAndPriceRuleId` and `byCatalogEntryIds*` query variants.
+ */
+export interface HclDisplayPriceItem {
+    partNumber: string;
+    priceRuleId?: string;
+    priceRuleName?: string;
+    catalogEntryId?: string;
+    unitPrice?: HclDisplayPriceUnitPrice[];
+    userDataField?: {
+        value?: string;
+        key: string;
+    }[];
+}
+/** Top-level response from GET /wcs/resources/store/{storeId}/display_price */
+export interface HclDisplayPriceResponse {
+    resourceId?: string;
+    resourceName?: string;
+    resultList?: HclDisplayPriceItem[];
+}
+/**
+ * A single unit price entry in a /price?q=byPartNumbers response item.
+ * Note: HCL uses `UnitPrice` (capital U) on this endpoint.
+ */
+export interface HclEntitledPriceUnitPrice {
+    price?: {
+        currency?: string;
+        /** Numeric value. */
+        value?: number;
+    };
+    quantity?: {
+        value?: number;
+        uom?: string;
+    };
+}
+/**
+ * A single item in the `EntitledPrice` array of a /price?q=byPartNumbers response.
+ */
+export interface HclEntitledPriceItem {
+    partNumber?: string;
+    productId?: string;
+    contractId?: string;
+    UnitPrice?: HclEntitledPriceUnitPrice[];
+}
+/** Top-level response from GET /wcs/resources/store/{storeId}/price?q=byPartNumbers */
+export interface HclEntitledPriceResponse {
+    resourceId?: string;
+    resourceName?: string;
+    EntitledPrice?: HclEntitledPriceItem[];
+}
+/**
+ * A single item in the `InventoryAvailability` array of the inventoryavailability response.
+ */
+export interface HclInventoryAvailabilityItem {
+    /** Internal HCL product ID (numeric string). */
+    productId?: string;
+    /** Inventory status string, e.g. 'Available'. */
+    inventoryStatus?: string;
+    /** Available quantity as a string (format: double). */
+    availableQuantity?: string;
+    unitOfMeasure?: string;
+    /** ID of the physical store, if this is a store-specific record. */
+    physicalStoreId?: string;
+    /** Name/key of the physical store, e.g. '1004/0001'. */
+    physicalStoreName?: string;
+    /** Name/key of the online store. Present on online inventory records. */
+    onlineStoreName?: string;
+    /** Online store ID. Present on online inventory records. */
+    onlineStoreId?: string;
+    availabilityDateTime?: string;
+    x_customField1?: string | null;
+    x_customField2?: string | null;
+    x_customField3?: string | null;
+    userDataField?: {
+        value?: string;
+        key: string;
+    }[];
+}
+/** Top-level response from GET /wcs/resources/store/{storeId}/inventoryavailability/byPartNumber/{partNumbers} */
+export interface HclInventoryAvailabilityResponse {
+    resourceId: string;
+    resourceName: string;
+    InventoryAvailability?: HclInventoryAvailabilityItem[];
 }
 export interface HclProductAttributeValue {
     identifier: string | string[];
@@ -310,3 +412,285 @@ export interface HclFindProductsQuery {
      */
     facets?: string[];
 }
+/**
+ * Response from POST /wcs/resources/store/{storeId}/guestidentity
+ * and POST /wcs/resources/store/{storeId}/loginidentity.
+ */
+export interface HclWcsIdentityResponse {
+    /** Opaque session token — must be forwarded as `WCToken` header on subsequent requests. */
+    WCToken: string;
+    /** Trusted token — must be forwarded as `WCTrustedToken` header. */
+    WCTrustedToken: string;
+    /** Numeric user ID string assigned by WCS. */
+    userId: string;
+    /** Personalization tracking ID. */
+    personalizationID?: string;
+    resourceName?: string;
+}
+/**
+ * A single entry in a WCS person address book (contact list).
+ * Returned as part of the GET /person/@self response (contact[] field)
+ * and used for POST/PUT /person/@self/contact operations.
+ */
+export interface HclWcsPersonContact {
+    /** Unique identifier / display name for this address (e.g. 'Home', 'Work', 'Billing'). */
+    nickName: string;
+    firstName?: string;
+    lastName?: string;
+    /** Street address lines. Index 0 = street, index 1 = apartment / second line. */
+    addressLine?: string[];
+    /** Alternative single-field address (some WCS endpoint variants). */
+    address1?: string;
+    city?: string;
+    stateOrProvinceName?: string;
+    zipCode?: string;
+    /** ISO country code, e.g. 'US'. */
+    country?: string;
+    phone1?: string;
+    email1?: string;
+    /** '1' marks this as the default / primary shipping address. */
+    primary?: string;
+    addressType?: string;
+}
+/**
+ * Response from GET /wcs/resources/store/{storeId}/person/@self.
+ * Only the fields we use are typed; the full WCS schema has many more.
+ */
+export interface HclPersonResponse {
+    /** Numeric user ID string. */
+    userId: string;
+    /** Customer's email / logon ID. Only populated for registered users. */
+    logonId?: string;
+    email1?: string;
+    firstName?: string;
+    lastName?: string;
+    phone1?: string;
+    resourceName?: string;
+    /** Organization ID. `-2000` indicates the default anonymous org. */
+    orgizationId?: string;
+    /** Address book entries embedded in the person/@self response. */
+    contact?: HclWcsPersonContact[];
+}
+/** A single order item embedded in a WCS cart/@self response. */
+export interface HclWcsOrderItem {
+    orderItemId: string;
+    /** Internal HCL catalog entry ID (numeric string). */
+    productId?: string;
+    /** SKU part number. Use this as the variant identifier. */
+    partNumber: string;
+    /** Quantity as a string — coerce with Number(). */
+    quantity: string;
+    /** Total line price as a string (unitPrice × quantity). */
+    orderItemPrice: string;
+    /** Price per single unit as a string. */
+    unitPrice: string;
+    /** ISO 4217 currency code. */
+    currency: string;
+    orderItemInventoryStatus?: string;
+    /** 'true' | 'false' — marks free-gift promotional items. */
+    freeGift?: string;
+    comments?: string;
+    /** Ship mode ID assigned to this item (present in shipping_info response). */
+    shipModeId?: string;
+    shipModeCode?: string;
+    shipModeDescription?: string;
+    carrier?: string;
+    shippingCharge?: string;
+}
+/** A single price adjustment on a WCS cart (discount, surcharge, tax, shipping). */
+export interface HclWcsAdjustment {
+    code: string;
+    /** Adjustment amount as a string — negative for discounts. */
+    amount: string;
+    currency: string;
+    /** 'Order' | 'OrderItem' | 'Shipping' */
+    displayLevel?: string;
+    /** 'Discount' | 'Tax' | 'Surcharge' | 'Shipping' */
+    usage?: string;
+    description?: string;
+}
+/** A promotion/coupon code applied to a WCS cart. */
+export interface HclWcsPromoCode {
+    code: string;
+    reason?: string;
+    associatedPromotion?: {
+        promotionId?: string;
+        promotionCode?: string;
+    }[];
+}
+/** Key-value pair carried in a WCS payment instruction. */
+export interface HclWcsPaymentProtocolData {
+    name: string;
+    value: string;
+}
+/** A payment instruction attached to a WCS cart. */
+export interface HclWcsPaymentInstruction {
+    piId: string;
+    payMethodId: string;
+    /** Authorized amount as a string. */
+    piAmount?: string;
+    currency?: string;
+    protocolData?: HclWcsPaymentProtocolData[];
+    piStatus?: string;
+    piDescription?: string;
+}
+/** An address embedded in a WCS cart/order response. */
+export interface HclWcsAddress {
+    addressId?: string;
+    firstName?: string;
+    lastName?: string;
+    /** Array of street address lines — index 0 is the primary line. */
+    addressLine?: string[];
+    /** Single-field street address (some WCS endpoints prefer this over addressLine). */
+    address1?: string;
+    city?: string;
+    /** State/province/region code. */
+    state?: string;
+    zipCode?: string;
+    country?: string;
+    phone1?: string;
+    email1?: string;
+    addressType?: string;
+    nickName?: string;
+}
+/** A single available ship mode returned by the WCS shipping_info endpoint. */
+export interface HclWcsShipMode {
+    shipModeId: string;
+    carrier: string;
+    shipModeCode: string;
+    shipModeDescription: string;
+    /** Store-defined extra field (varies by HCL configuration). */
+    field1?: string;
+    /** Estimated delivery time (store-defined). */
+    field2?: string;
+}
+/**
+ * Top-level response from GET /wcs/resources/store/{storeId}/cart/@self.
+ * All monetary amounts are returned as strings and must be parsed with Number().
+ */
+export interface HclWcsCartResponse {
+    orderId: string;
+    storeId?: string;
+    buyerId?: string;
+    orgUniqueID?: string;
+    grandTotal?: string;
+    grandTotalCurrency?: string;
+    totalProductPrice?: string;
+    totalProductPriceCurrency?: string;
+    totalShippingCharge?: string;
+    totalShippingChargeCurrency?: string;
+    totalAdjustment?: string;
+    totalAdjustmentCurrency?: string;
+    totalSalesTax?: string;
+    totalSalesTaxCurrency?: string;
+    totalShippingTax?: string;
+    /** Shipping address embedded in the cart (when set). */
+    x_shippingAddress?: HclWcsAddress;
+    /** Billing address embedded in the cart (when set). */
+    x_billingAddress?: HclWcsAddress;
+    orderItem?: HclWcsOrderItem[];
+    adjustment?: HclWcsAdjustment[];
+    promotionCode?: HclWcsPromoCode[];
+    paymentInstruction?: HclWcsPaymentInstruction[];
+    /** Currently selected shipping mode ID. */
+    shipModeId?: string;
+    shipModeCode?: string;
+    shipModeDescription?: string;
+    carrier?: string;
+    /** '0' | '1' — locked orders cannot be modified. */
+    x_isPurchaseLocked?: string;
+    /** WCS order status, e.g. 'P' = pending, 'C' = submitted. */
+    orderStatus?: string;
+    lastUpdateDate?: string;
+    /** Order description / name as persisted in WCS. Returned by GET /order/{orderId} and GET /order/byStatus/P. */
+    orderDescription?: string;
+}
+/**
+ * Response from GET /store/{storeId}/order/byStatus/P.
+ * Returns a list of pending orders (multi-cart B2B support).
+ */
+export interface HclWcsOrderListResponse {
+    Order: HclWcsCartResponse[];
+    recordSetTotal?: string;
+    recordSetCount?: string;
+    recordSetComplete?: string;
+    recordSetStartNumber?: string;
+}
+/** Response from the precheckout / checkout endpoints. */
+export interface HclWcsOrderIdContainer {
+    orderId: string;
+    resourceName?: string;
+}
+/** Response from GET cart/@self/shipping_info with usable shipping modes. */
+export interface HclWcsShipModesResponse {
+    /** Present in newer WCS versions when using IBM_usableShippingMode profile. */
+    usableShippingMode?: HclWcsShipMode[];
+    /** Present in older WCS versions — shipping mode embedded per orderItem. */
+    orderItem?: Array<{
+        orderItemId: string;
+        shipModeId?: string;
+        shipModeCode?: string;
+        shipModeDescription?: string;
+        carrier?: string;
+        description?: string;
+    }>;
+}
+/** A single usable payment method entry returned by WCS. */
+export interface HclWcsPaymentMethod {
+    paymentMethodName: string;
+    xucc?: string;
+    description?: string;
+}
+/** Response listing available payment methods for the store. */
+export interface HclWcsPaymentMethodsResponse {
+    usablePaymentInformation?: HclWcsPaymentMethod[];
+}
+/** Minimal response from addOrderItem / updateOrderItem operations. */
+export interface HclWcsOrderItemUpdateResponse {
+    orderId: string;
+    orderItem?: {
+        orderItemId: string;
+    }[];
+}
+/** Response from POST /store/{storeId}/cart/create_order */
+export interface HclWcsCreateOrderResponse {
+    /** The newly created order ID. */
+    outOrderId: string;
+    redirecturl?: string;
+    viewTaskName?: string;
+}
+/**
+ * A full order as returned by GET /wcs/resources/store/{storeId}/order/{orderId}.
+ * Extends the cart response shape with the `placedDate` field that is only
+ * present on placed (non-active) orders.
+ */
+export interface HclWcsOrderDetailResponse extends HclWcsCartResponse {
+    /** Date/time when the order was placed, e.g. '2024-01-15T10:30:00.000Z'. */
+    placedDate?: string;
+}
+/**
+ * A single summary entry in a GET /wcs/resources/store/{storeId}/order/@history response.
+ * Contains only the fields available in the history list; use getById for full detail.
+ */
+export interface HclWcsOrderHistoryItem {
+    orderId: string;
+    /** WCS order status code, e.g. 'P', 'M', 'S', 'X'. */
+    status: string;
+    placedDate?: string;
+    grandTotal?: string;
+    grandTotalCurrency?: string;
+    totalProductPrice?: string;
+    orderDescription?: string;
+    buyerDistinguishedName?: string;
+}
+/**
+ * Top-level response from GET /wcs/resources/store/{storeId}/order/@history.
+ * Returns a paginated list of the buyer's past orders.
+ */
+export interface HclWcsOrderHistoryResponse {
+    Order?: HclWcsOrderHistoryItem[];
+    recordSetTotal?: string;
+    recordSetCount?: string;
+    recordSetStartNumber?: string;
+    recordSetComplete?: string;
+}

package/src/test/test-utils.d.ts

@@ -5,11 +5,15 @@ export declare function createHclClient(contextOverrides?: Partial<RequestContex
     product?: true | undefined;
     productSearch?: true | undefined;
     price?: false | undefined;
+    order?: false | undefined;
     cart?: false | undefined;
     checkout?: false | undefined;
+    identity?: false | undefined;
+    profile?: false | undefined;
     inventory?: false | undefined;
     category?: true | undefined;
-}>, "product" | "productSearch" | "price" | "cart" | "checkout" | "inventory" | "category"> & {
+    orderSearch?: false | undefined;
+}>, "product" | "productSearch" | "price" | "order" | "cart" | "checkout" | "identity" | "profile" | "inventory" | "category" | "orderSearch"> & {
     product: import("../index.js").HclProductCapability<import("../index.js").HclProductFactory<import("zod").ZodObject<{
         identifier: import("zod").ZodObject<{
             key: import("zod").ZodString;