This is page 34 of 43. Use http://codebase.md/taurgis/sfcc-dev-mcp?page={x} to view the full context.
# Directory Structure
```
├── .DS_Store
├── .github
│ ├── dependabot.yml
│ ├── instructions
│ │ ├── mcp-node-tests.instructions.md
│ │ └── mcp-yml-tests.instructions.md
│ ├── ISSUE_TEMPLATE
│ │ ├── bug_report.yml
│ │ ├── config.yml
│ │ ├── documentation.yml
│ │ ├── feature_request.yml
│ │ └── question.yml
│ ├── PULL_REQUEST_TEMPLATE
│ │ ├── bug_fix.md
│ │ ├── documentation.md
│ │ └── new_tool.md
│ ├── pull_request_template.md
│ └── workflows
│ ├── ci.yml
│ ├── deploy-pages.yml
│ ├── publish.yml
│ └── update-docs.yml
├── .gitignore
├── .husky
│ └── pre-commit
├── aegis.config.docs-only.json
├── aegis.config.json
├── aegis.config.with-dw.json
├── AGENTS.md
├── ai-instructions
│ ├── claude-desktop
│ │ └── claude_custom_instructions.md
│ ├── cursor
│ │ └── .cursor
│ │ └── rules
│ │ ├── debugging-workflows.mdc
│ │ ├── hooks-development.mdc
│ │ ├── isml-templates.mdc
│ │ ├── job-framework.mdc
│ │ ├── performance-optimization.mdc
│ │ ├── scapi-endpoints.mdc
│ │ ├── security-patterns.mdc
│ │ ├── sfcc-development.mdc
│ │ ├── sfra-controllers.mdc
│ │ ├── sfra-models.mdc
│ │ ├── system-objects.mdc
│ │ └── testing-patterns.mdc
│ └── github-copilot
│ └── copilot-instructions.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── docs
│ ├── best-practices
│ │ ├── cartridge_creation.md
│ │ ├── isml_templates.md
│ │ ├── job_framework.md
│ │ ├── localserviceregistry.md
│ │ ├── ocapi_hooks.md
│ │ ├── performance.md
│ │ ├── scapi_custom_endpoint.md
│ │ ├── scapi_hooks.md
│ │ ├── security.md
│ │ ├── sfra_client_side_js.md
│ │ ├── sfra_controllers.md
│ │ ├── sfra_models.md
│ │ └── sfra_scss.md
│ ├── dw_campaign
│ │ ├── ABTest.md
│ │ ├── ABTestMgr.md
│ │ ├── ABTestSegment.md
│ │ ├── AmountDiscount.md
│ │ ├── ApproachingDiscount.md
│ │ ├── BonusChoiceDiscount.md
│ │ ├── BonusDiscount.md
│ │ ├── Campaign.md
│ │ ├── CampaignMgr.md
│ │ ├── CampaignStatusCodes.md
│ │ ├── Coupon.md
│ │ ├── CouponMgr.md
│ │ ├── CouponRedemption.md
│ │ ├── CouponStatusCodes.md
│ │ ├── Discount.md
│ │ ├── DiscountPlan.md
│ │ ├── FixedPriceDiscount.md
│ │ ├── FixedPriceShippingDiscount.md
│ │ ├── FreeDiscount.md
│ │ ├── FreeShippingDiscount.md
│ │ ├── PercentageDiscount.md
│ │ ├── PercentageOptionDiscount.md
│ │ ├── PriceBookPriceDiscount.md
│ │ ├── Promotion.md
│ │ ├── PromotionMgr.md
│ │ ├── PromotionPlan.md
│ │ ├── SlotContent.md
│ │ ├── SourceCodeGroup.md
│ │ ├── SourceCodeInfo.md
│ │ ├── SourceCodeStatusCodes.md
│ │ └── TotalFixedPriceDiscount.md
│ ├── dw_catalog
│ │ ├── Catalog.md
│ │ ├── CatalogMgr.md
│ │ ├── Category.md
│ │ ├── CategoryAssignment.md
│ │ ├── CategoryLink.md
│ │ ├── PriceBook.md
│ │ ├── PriceBookMgr.md
│ │ ├── Product.md
│ │ ├── ProductActiveData.md
│ │ ├── ProductAttributeModel.md
│ │ ├── ProductAvailabilityLevels.md
│ │ ├── ProductAvailabilityModel.md
│ │ ├── ProductInventoryList.md
│ │ ├── ProductInventoryMgr.md
│ │ ├── ProductInventoryRecord.md
│ │ ├── ProductLink.md
│ │ ├── ProductMgr.md
│ │ ├── ProductOption.md
│ │ ├── ProductOptionModel.md
│ │ ├── ProductOptionValue.md
│ │ ├── ProductPriceInfo.md
│ │ ├── ProductPriceModel.md
│ │ ├── ProductPriceTable.md
│ │ ├── ProductSearchHit.md
│ │ ├── ProductSearchModel.md
│ │ ├── ProductSearchRefinementDefinition.md
│ │ ├── ProductSearchRefinements.md
│ │ ├── ProductSearchRefinementValue.md
│ │ ├── ProductVariationAttribute.md
│ │ ├── ProductVariationAttributeValue.md
│ │ ├── ProductVariationModel.md
│ │ ├── Recommendation.md
│ │ ├── SearchModel.md
│ │ ├── SearchRefinementDefinition.md
│ │ ├── SearchRefinements.md
│ │ ├── SearchRefinementValue.md
│ │ ├── SortingOption.md
│ │ ├── SortingRule.md
│ │ ├── Store.md
│ │ ├── StoreGroup.md
│ │ ├── StoreInventoryFilter.md
│ │ ├── StoreInventoryFilterValue.md
│ │ ├── StoreMgr.md
│ │ ├── Variant.md
│ │ └── VariationGroup.md
│ ├── dw_content
│ │ ├── Content.md
│ │ ├── ContentMgr.md
│ │ ├── ContentSearchModel.md
│ │ ├── ContentSearchRefinementDefinition.md
│ │ ├── ContentSearchRefinements.md
│ │ ├── ContentSearchRefinementValue.md
│ │ ├── Folder.md
│ │ ├── Library.md
│ │ ├── MarkupText.md
│ │ └── MediaFile.md
│ ├── dw_crypto
│ │ ├── CertificateRef.md
│ │ ├── CertificateUtils.md
│ │ ├── Cipher.md
│ │ ├── Encoding.md
│ │ ├── JWE.md
│ │ ├── JWEHeader.md
│ │ ├── JWS.md
│ │ ├── JWSHeader.md
│ │ ├── KeyRef.md
│ │ ├── Mac.md
│ │ ├── MessageDigest.md
│ │ ├── SecureRandom.md
│ │ ├── Signature.md
│ │ ├── WeakCipher.md
│ │ ├── WeakMac.md
│ │ ├── WeakMessageDigest.md
│ │ ├── WeakSignature.md
│ │ └── X509Certificate.md
│ ├── dw_customer
│ │ ├── AddressBook.md
│ │ ├── AgentUserMgr.md
│ │ ├── AgentUserStatusCodes.md
│ │ ├── AuthenticationStatus.md
│ │ ├── Credentials.md
│ │ ├── Customer.md
│ │ ├── CustomerActiveData.md
│ │ ├── CustomerAddress.md
│ │ ├── CustomerCDPData.md
│ │ ├── CustomerContextMgr.md
│ │ ├── CustomerGroup.md
│ │ ├── CustomerList.md
│ │ ├── CustomerMgr.md
│ │ ├── CustomerPasswordConstraints.md
│ │ ├── CustomerPaymentInstrument.md
│ │ ├── CustomerStatusCodes.md
│ │ ├── EncryptedObject.md
│ │ ├── ExternalProfile.md
│ │ ├── OrderHistory.md
│ │ ├── ProductList.md
│ │ ├── ProductListItem.md
│ │ ├── ProductListItemPurchase.md
│ │ ├── ProductListMgr.md
│ │ ├── ProductListRegistrant.md
│ │ ├── Profile.md
│ │ └── Wallet.md
│ ├── dw_extensions.applepay
│ │ ├── ApplePayHookResult.md
│ │ └── ApplePayHooks.md
│ ├── dw_extensions.facebook
│ │ ├── FacebookFeedHooks.md
│ │ └── FacebookProduct.md
│ ├── dw_extensions.paymentrequest
│ │ ├── PaymentRequestHookResult.md
│ │ └── PaymentRequestHooks.md
│ ├── dw_extensions.payments
│ │ ├── SalesforceBancontactPaymentDetails.md
│ │ ├── SalesforceCardPaymentDetails.md
│ │ ├── SalesforceEpsPaymentDetails.md
│ │ ├── SalesforceIdealPaymentDetails.md
│ │ ├── SalesforceKlarnaPaymentDetails.md
│ │ ├── SalesforcePaymentDetails.md
│ │ ├── SalesforcePaymentIntent.md
│ │ ├── SalesforcePaymentMethod.md
│ │ ├── SalesforcePaymentRequest.md
│ │ ├── SalesforcePaymentsHooks.md
│ │ ├── SalesforcePaymentsMgr.md
│ │ ├── SalesforcePaymentsSiteConfiguration.md
│ │ ├── SalesforcePayPalOrder.md
│ │ ├── SalesforcePayPalOrderAddress.md
│ │ ├── SalesforcePayPalOrderPayer.md
│ │ ├── SalesforcePayPalPaymentDetails.md
│ │ ├── SalesforceSepaDebitPaymentDetails.md
│ │ └── SalesforceVenmoPaymentDetails.md
│ ├── dw_extensions.pinterest
│ │ ├── PinterestAvailability.md
│ │ ├── PinterestFeedHooks.md
│ │ ├── PinterestOrder.md
│ │ ├── PinterestOrderHooks.md
│ │ └── PinterestProduct.md
│ ├── dw_io
│ │ ├── CSVStreamReader.md
│ │ ├── CSVStreamWriter.md
│ │ ├── File.md
│ │ ├── FileReader.md
│ │ ├── FileWriter.md
│ │ ├── InputStream.md
│ │ ├── OutputStream.md
│ │ ├── PrintWriter.md
│ │ ├── RandomAccessFileReader.md
│ │ ├── Reader.md
│ │ ├── StringWriter.md
│ │ ├── Writer.md
│ │ ├── XMLIndentingStreamWriter.md
│ │ ├── XMLStreamConstants.md
│ │ ├── XMLStreamReader.md
│ │ └── XMLStreamWriter.md
│ ├── dw_job
│ │ ├── JobExecution.md
│ │ └── JobStepExecution.md
│ ├── dw_net
│ │ ├── FTPClient.md
│ │ ├── FTPFileInfo.md
│ │ ├── HTTPClient.md
│ │ ├── HTTPRequestPart.md
│ │ ├── Mail.md
│ │ ├── SFTPClient.md
│ │ ├── SFTPFileInfo.md
│ │ ├── WebDAVClient.md
│ │ └── WebDAVFileInfo.md
│ ├── dw_object
│ │ ├── ActiveData.md
│ │ ├── CustomAttributes.md
│ │ ├── CustomObject.md
│ │ ├── CustomObjectMgr.md
│ │ ├── Extensible.md
│ │ ├── ExtensibleObject.md
│ │ ├── Note.md
│ │ ├── ObjectAttributeDefinition.md
│ │ ├── ObjectAttributeGroup.md
│ │ ├── ObjectAttributeValueDefinition.md
│ │ ├── ObjectTypeDefinition.md
│ │ ├── PersistentObject.md
│ │ ├── SimpleExtensible.md
│ │ └── SystemObjectMgr.md
│ ├── dw_order
│ │ ├── AbstractItem.md
│ │ ├── AbstractItemCtnr.md
│ │ ├── Appeasement.md
│ │ ├── AppeasementItem.md
│ │ ├── Basket.md
│ │ ├── BasketMgr.md
│ │ ├── BonusDiscountLineItem.md
│ │ ├── CouponLineItem.md
│ │ ├── CreateAgentBasketLimitExceededException.md
│ │ ├── CreateBasketFromOrderException.md
│ │ ├── CreateCouponLineItemException.md
│ │ ├── CreateOrderException.md
│ │ ├── CreateTemporaryBasketLimitExceededException.md
│ │ ├── GiftCertificate.md
│ │ ├── GiftCertificateLineItem.md
│ │ ├── GiftCertificateMgr.md
│ │ ├── GiftCertificateStatusCodes.md
│ │ ├── Invoice.md
│ │ ├── InvoiceItem.md
│ │ ├── LineItem.md
│ │ ├── LineItemCtnr.md
│ │ ├── Order.md
│ │ ├── OrderAddress.md
│ │ ├── OrderItem.md
│ │ ├── OrderMgr.md
│ │ ├── OrderPaymentInstrument.md
│ │ ├── OrderProcessStatusCodes.md
│ │ ├── PaymentCard.md
│ │ ├── PaymentInstrument.md
│ │ ├── PaymentMethod.md
│ │ ├── PaymentMgr.md
│ │ ├── PaymentProcessor.md
│ │ ├── PaymentStatusCodes.md
│ │ ├── PaymentTransaction.md
│ │ ├── PriceAdjustment.md
│ │ ├── PriceAdjustmentLimitTypes.md
│ │ ├── ProductLineItem.md
│ │ ├── ProductShippingCost.md
│ │ ├── ProductShippingLineItem.md
│ │ ├── ProductShippingModel.md
│ │ ├── Return.md
│ │ ├── ReturnCase.md
│ │ ├── ReturnCaseItem.md
│ │ ├── ReturnItem.md
│ │ ├── Shipment.md
│ │ ├── ShipmentShippingCost.md
│ │ ├── ShipmentShippingModel.md
│ │ ├── ShippingLineItem.md
│ │ ├── ShippingLocation.md
│ │ ├── ShippingMethod.md
│ │ ├── ShippingMgr.md
│ │ ├── ShippingOrder.md
│ │ ├── ShippingOrderItem.md
│ │ ├── SumItem.md
│ │ ├── TaxGroup.md
│ │ ├── TaxItem.md
│ │ ├── TaxMgr.md
│ │ ├── TrackingInfo.md
│ │ └── TrackingRef.md
│ ├── dw_order.hooks
│ │ ├── CalculateHooks.md
│ │ ├── OrderHooks.md
│ │ ├── PaymentHooks.md
│ │ ├── ReturnHooks.md
│ │ └── ShippingOrderHooks.md
│ ├── dw_rpc
│ │ ├── SOAPUtil.md
│ │ ├── Stub.md
│ │ └── WebReference.md
│ ├── dw_suggest
│ │ ├── BrandSuggestions.md
│ │ ├── CategorySuggestions.md
│ │ ├── ContentSuggestions.md
│ │ ├── CustomSuggestions.md
│ │ ├── ProductSuggestions.md
│ │ ├── SearchPhraseSuggestions.md
│ │ ├── SuggestedCategory.md
│ │ ├── SuggestedContent.md
│ │ ├── SuggestedPhrase.md
│ │ ├── SuggestedProduct.md
│ │ ├── SuggestedTerm.md
│ │ ├── SuggestedTerms.md
│ │ ├── Suggestions.md
│ │ └── SuggestModel.md
│ ├── dw_svc
│ │ ├── FTPService.md
│ │ ├── FTPServiceDefinition.md
│ │ ├── HTTPFormService.md
│ │ ├── HTTPFormServiceDefinition.md
│ │ ├── HTTPService.md
│ │ ├── HTTPServiceDefinition.md
│ │ ├── LocalServiceRegistry.md
│ │ ├── Result.md
│ │ ├── Service.md
│ │ ├── ServiceCallback.md
│ │ ├── ServiceConfig.md
│ │ ├── ServiceCredential.md
│ │ ├── ServiceDefinition.md
│ │ ├── ServiceProfile.md
│ │ ├── ServiceRegistry.md
│ │ ├── SOAPService.md
│ │ └── SOAPServiceDefinition.md
│ ├── dw_system
│ │ ├── AgentUserStatusCodes.md
│ │ ├── Cache.md
│ │ ├── CacheMgr.md
│ │ ├── HookMgr.md
│ │ ├── InternalObject.md
│ │ ├── JobProcessMonitor.md
│ │ ├── Log.md
│ │ ├── Logger.md
│ │ ├── LogNDC.md
│ │ ├── OrganizationPreferences.md
│ │ ├── Pipeline.md
│ │ ├── PipelineDictionary.md
│ │ ├── RemoteInclude.md
│ │ ├── Request.md
│ │ ├── RequestHooks.md
│ │ ├── Response.md
│ │ ├── RESTErrorResponse.md
│ │ ├── RESTResponseMgr.md
│ │ ├── RESTSuccessResponse.md
│ │ ├── SearchStatus.md
│ │ ├── Session.md
│ │ ├── Site.md
│ │ ├── SitePreferences.md
│ │ ├── Status.md
│ │ ├── StatusItem.md
│ │ ├── System.md
│ │ └── Transaction.md
│ ├── dw_util
│ │ ├── ArrayList.md
│ │ ├── Assert.md
│ │ ├── BigInteger.md
│ │ ├── Bytes.md
│ │ ├── Calendar.md
│ │ ├── Collection.md
│ │ ├── Currency.md
│ │ ├── DateUtils.md
│ │ ├── Decimal.md
│ │ ├── FilteringCollection.md
│ │ ├── Geolocation.md
│ │ ├── HashMap.md
│ │ ├── HashSet.md
│ │ ├── Iterator.md
│ │ ├── LinkedHashMap.md
│ │ ├── LinkedHashSet.md
│ │ ├── List.md
│ │ ├── Locale.md
│ │ ├── Map.md
│ │ ├── MapEntry.md
│ │ ├── MappingKey.md
│ │ ├── MappingMgr.md
│ │ ├── PropertyComparator.md
│ │ ├── SecureEncoder.md
│ │ ├── SecureFilter.md
│ │ ├── SeekableIterator.md
│ │ ├── Set.md
│ │ ├── SortedMap.md
│ │ ├── SortedSet.md
│ │ ├── StringUtils.md
│ │ ├── Template.md
│ │ └── UUIDUtils.md
│ ├── dw_value
│ │ ├── EnumValue.md
│ │ ├── MimeEncodedText.md
│ │ ├── Money.md
│ │ └── Quantity.md
│ ├── dw_web
│ │ ├── ClickStream.md
│ │ ├── ClickStreamEntry.md
│ │ ├── Cookie.md
│ │ ├── Cookies.md
│ │ ├── CSRFProtection.md
│ │ ├── Form.md
│ │ ├── FormAction.md
│ │ ├── FormElement.md
│ │ ├── FormElementValidationResult.md
│ │ ├── FormField.md
│ │ ├── FormFieldOption.md
│ │ ├── FormFieldOptions.md
│ │ ├── FormGroup.md
│ │ ├── FormList.md
│ │ ├── FormListItem.md
│ │ ├── Forms.md
│ │ ├── HttpParameter.md
│ │ ├── HttpParameterMap.md
│ │ ├── LoopIterator.md
│ │ ├── PageMetaData.md
│ │ ├── PageMetaTag.md
│ │ ├── PagingModel.md
│ │ ├── Resource.md
│ │ ├── URL.md
│ │ ├── URLAction.md
│ │ ├── URLParameter.md
│ │ ├── URLRedirect.md
│ │ ├── URLRedirectMgr.md
│ │ └── URLUtils.md
│ ├── sfra
│ │ ├── account.md
│ │ ├── address.md
│ │ ├── billing.md
│ │ ├── cart.md
│ │ ├── categories.md
│ │ ├── content.md
│ │ ├── locale.md
│ │ ├── order.md
│ │ ├── payment.md
│ │ ├── price-default.md
│ │ ├── price-range.md
│ │ ├── price-tiered.md
│ │ ├── product-bundle.md
│ │ ├── product-full.md
│ │ ├── product-line-items.md
│ │ ├── product-search.md
│ │ ├── product-tile.md
│ │ ├── querystring.md
│ │ ├── render.md
│ │ ├── request.md
│ │ ├── response.md
│ │ ├── server.md
│ │ ├── shipping.md
│ │ ├── store.md
│ │ ├── stores.md
│ │ └── totals.md
│ └── TopLevel
│ ├── APIException.md
│ ├── arguments.md
│ ├── Array.md
│ ├── ArrayBuffer.md
│ ├── BigInt.md
│ ├── Boolean.md
│ ├── ConversionError.md
│ ├── DataView.md
│ ├── Date.md
│ ├── Error.md
│ ├── ES6Iterator.md
│ ├── EvalError.md
│ ├── Fault.md
│ ├── Float32Array.md
│ ├── Float64Array.md
│ ├── Function.md
│ ├── Generator.md
│ ├── global.md
│ ├── Int16Array.md
│ ├── Int32Array.md
│ ├── Int8Array.md
│ ├── InternalError.md
│ ├── IOError.md
│ ├── Iterable.md
│ ├── Iterator.md
│ ├── JSON.md
│ ├── Map.md
│ ├── Math.md
│ ├── Module.md
│ ├── Namespace.md
│ ├── Number.md
│ ├── Object.md
│ ├── QName.md
│ ├── RangeError.md
│ ├── ReferenceError.md
│ ├── RegExp.md
│ ├── Set.md
│ ├── StopIteration.md
│ ├── String.md
│ ├── Symbol.md
│ ├── SyntaxError.md
│ ├── SystemError.md
│ ├── TypeError.md
│ ├── Uint16Array.md
│ ├── Uint32Array.md
│ ├── Uint8Array.md
│ ├── Uint8ClampedArray.md
│ ├── URIError.md
│ ├── WeakMap.md
│ ├── WeakSet.md
│ ├── XML.md
│ ├── XMLList.md
│ └── XMLStreamError.md
├── docs-site
│ ├── .gitignore
│ ├── App.tsx
│ ├── components
│ │ ├── Badge.tsx
│ │ ├── BreadcrumbSchema.tsx
│ │ ├── CodeBlock.tsx
│ │ ├── Collapsible.tsx
│ │ ├── ConfigBuilder.tsx
│ │ ├── ConfigHero.tsx
│ │ ├── ConfigModeTabs.tsx
│ │ ├── icons.tsx
│ │ ├── Layout.tsx
│ │ ├── LightCodeContainer.tsx
│ │ ├── NewcomerCTA.tsx
│ │ ├── NextStepsStrip.tsx
│ │ ├── OnThisPage.tsx
│ │ ├── Search.tsx
│ │ ├── SEO.tsx
│ │ ├── Sidebar.tsx
│ │ ├── StructuredData.tsx
│ │ ├── ToolCard.tsx
│ │ ├── ToolFilters.tsx
│ │ ├── Typography.tsx
│ │ └── VersionBadge.tsx
│ ├── constants.tsx
│ ├── index.html
│ ├── main.tsx
│ ├── metadata.json
│ ├── package-lock.json
│ ├── package.json
│ ├── pages
│ │ ├── AIInterfacesPage.tsx
│ │ ├── ConfigurationPage.tsx
│ │ ├── DevelopmentPage.tsx
│ │ ├── ExamplesPage.tsx
│ │ ├── FeaturesPage.tsx
│ │ ├── HomePage.tsx
│ │ ├── SecurityPage.tsx
│ │ ├── ToolsPage.tsx
│ │ └── TroubleshootingPage.tsx
│ ├── postcss.config.js
│ ├── public
│ │ ├── .well-known
│ │ │ └── security.txt
│ │ ├── 404.html
│ │ ├── android-chrome-192x192.png
│ │ ├── android-chrome-512x512.png
│ │ ├── apple-touch-icon.png
│ │ ├── explain-product-pricing-methods-no-mcp.png
│ │ ├── explain-product-pricing-methods.png
│ │ ├── favicon-16x16.png
│ │ ├── favicon-32x32.png
│ │ ├── favicon.ico
│ │ ├── llms.txt
│ │ ├── robots.txt
│ │ ├── site.webmanifest
│ │ └── sitemap.xml
│ ├── README.md
│ ├── scripts
│ │ ├── generate-search-index.js
│ │ ├── generate-sitemap.js
│ │ └── search-dev.js
│ ├── src
│ │ └── styles
│ │ ├── input.css
│ │ └── prism-theme.css
│ ├── tailwind.config.js
│ ├── tsconfig.json
│ ├── types.ts
│ ├── utils
│ │ ├── search.ts
│ │ └── toolsData.ts
│ └── vite.config.ts
├── eslint.config.js
├── jest.config.js
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── scripts
│ └── convert-docs.js
├── SECURITY.md
├── server.json
├── src
│ ├── clients
│ │ ├── base
│ │ │ ├── http-client.ts
│ │ │ ├── oauth-token.ts
│ │ │ └── ocapi-auth-client.ts
│ │ ├── best-practices-client.ts
│ │ ├── cartridge-generation-client.ts
│ │ ├── docs
│ │ │ ├── class-content-parser.ts
│ │ │ ├── class-name-resolver.ts
│ │ │ ├── documentation-scanner.ts
│ │ │ ├── index.ts
│ │ │ └── referenced-types-extractor.ts
│ │ ├── docs-client.ts
│ │ ├── log-client.ts
│ │ ├── logs
│ │ │ ├── index.ts
│ │ │ ├── log-analyzer.ts
│ │ │ ├── log-client.ts
│ │ │ ├── log-constants.ts
│ │ │ ├── log-file-discovery.ts
│ │ │ ├── log-file-reader.ts
│ │ │ ├── log-formatter.ts
│ │ │ ├── log-processor.ts
│ │ │ ├── log-types.ts
│ │ │ └── webdav-client-manager.ts
│ │ ├── ocapi
│ │ │ ├── code-versions-client.ts
│ │ │ ├── site-preferences-client.ts
│ │ │ └── system-objects-client.ts
│ │ ├── ocapi-client.ts
│ │ └── sfra-client.ts
│ ├── config
│ │ ├── configuration-factory.ts
│ │ └── dw-json-loader.ts
│ ├── core
│ │ ├── handlers
│ │ │ ├── abstract-log-tool-handler.ts
│ │ │ ├── base-handler.ts
│ │ │ ├── best-practices-handler.ts
│ │ │ ├── cartridge-handler.ts
│ │ │ ├── client-factory.ts
│ │ │ ├── code-version-handler.ts
│ │ │ ├── docs-handler.ts
│ │ │ ├── job-log-handler.ts
│ │ │ ├── job-log-tool-config.ts
│ │ │ ├── log-handler.ts
│ │ │ ├── log-tool-config.ts
│ │ │ ├── sfra-handler.ts
│ │ │ ├── system-object-handler.ts
│ │ │ └── validation-helpers.ts
│ │ ├── server.ts
│ │ └── tool-definitions.ts
│ ├── index.ts
│ ├── main.ts
│ ├── services
│ │ ├── file-system-service.ts
│ │ ├── index.ts
│ │ └── path-service.ts
│ ├── tool-configs
│ │ ├── best-practices-tool-config.ts
│ │ ├── cartridge-tool-config.ts
│ │ ├── code-version-tool-config.ts
│ │ ├── docs-tool-config.ts
│ │ ├── job-log-tool-config.ts
│ │ ├── log-tool-config.ts
│ │ ├── sfra-tool-config.ts
│ │ └── system-object-tool-config.ts
│ ├── types
│ │ └── types.ts
│ └── utils
│ ├── cache.ts
│ ├── job-log-tool-config.ts
│ ├── job-log-utils.ts
│ ├── log-cache.ts
│ ├── log-tool-config.ts
│ ├── log-tool-constants.ts
│ ├── log-tool-utils.ts
│ ├── logger.ts
│ ├── ocapi-url-builder.ts
│ ├── path-resolver.ts
│ ├── query-builder.ts
│ ├── utils.ts
│ └── validator.ts
├── tests
│ ├── __mocks__
│ │ ├── docs-client.ts
│ │ ├── src
│ │ │ └── clients
│ │ │ └── base
│ │ │ └── http-client.js
│ │ └── webdav.js
│ ├── base-handler.test.ts
│ ├── base-http-client.test.ts
│ ├── best-practices-handler.test.ts
│ ├── cache.test.ts
│ ├── cartridge-handler.test.ts
│ ├── class-content-parser.test.ts
│ ├── class-name-resolver.test.ts
│ ├── client-factory.test.ts
│ ├── code-version-handler.test.ts
│ ├── code-versions-client.test.ts
│ ├── config.test.ts
│ ├── configuration-factory.test.ts
│ ├── docs-handler.test.ts
│ ├── documentation-scanner.test.ts
│ ├── file-system-service.test.ts
│ ├── job-log-handler.test.ts
│ ├── job-log-utils.test.ts
│ ├── log-client.test.ts
│ ├── log-handler.test.ts
│ ├── log-processor.test.ts
│ ├── logger.test.ts
│ ├── mcp
│ │ ├── AGENTS.md
│ │ ├── node
│ │ │ ├── activate-code-version-advanced.full-mode.programmatic.test.js
│ │ │ ├── code-versions.full-mode.programmatic.test.js
│ │ │ ├── generate-cartridge-structure.docs-only.programmatic.test.js
│ │ │ ├── get-available-best-practice-guides.docs-only.programmatic.test.js
│ │ │ ├── get-available-sfra-documents.programmatic.test.js
│ │ │ ├── get-best-practice-guide.docs-only.programmatic.test.js
│ │ │ ├── get-hook-reference.docs-only.programmatic.test.js
│ │ │ ├── get-job-execution-summary.full-mode.programmatic.test.js
│ │ │ ├── get-job-log-entries.full-mode.programmatic.test.js
│ │ │ ├── get-latest-debug.full-mode.programmatic.test.js
│ │ │ ├── get-latest-error.full-mode.programmatic.test.js
│ │ │ ├── get-latest-info.full-mode.programmatic.test.js
│ │ │ ├── get-latest-job-log-files.full-mode.programmatic.test.js
│ │ │ ├── get-latest-warn.full-mode.programmatic.test.js
│ │ │ ├── get-log-file-contents.full-mode.programmatic.test.js
│ │ │ ├── get-sfcc-class-documentation.docs-only.programmatic.test.js
│ │ │ ├── get-sfcc-class-info.docs-only.programmatic.test.js
│ │ │ ├── get-sfra-categories.docs-only.programmatic.test.js
│ │ │ ├── get-sfra-document.programmatic.test.js
│ │ │ ├── get-sfra-documents-by-category.docs-only.programmatic.test.js
│ │ │ ├── get-system-object-definition.full-mode.programmatic.test.js
│ │ │ ├── get-system-object-definitions.docs-only.programmatic.test.js
│ │ │ ├── get-system-object-definitions.full-mode.programmatic.test.js
│ │ │ ├── list-log-files.full-mode.programmatic.test.js
│ │ │ ├── list-sfcc-classes.docs-only.programmatic.test.js
│ │ │ ├── search-best-practices.docs-only.programmatic.test.js
│ │ │ ├── search-custom-object-attribute-definitions.full-mode.programmatic.test.js
│ │ │ ├── search-job-logs-by-name.full-mode.programmatic.test.js
│ │ │ ├── search-job-logs.full-mode.programmatic.test.js
│ │ │ ├── search-logs.full-mode.programmatic.test.js
│ │ │ ├── search-sfcc-classes.docs-only.programmatic.test.js
│ │ │ ├── search-sfcc-methods.docs-only.programmatic.test.js
│ │ │ ├── search-sfra-documentation.docs-only.programmatic.test.js
│ │ │ ├── search-site-preferences.full-mode.programmatic.test.js
│ │ │ ├── search-system-object-attribute-definitions.full-mode.programmatic.test.js
│ │ │ ├── search-system-object-attribute-groups.full-mode.programmatic.test.js
│ │ │ ├── summarize-logs.full-mode.programmatic.test.js
│ │ │ ├── tools.docs-only.programmatic.test.js
│ │ │ └── tools.full-mode.programmatic.test.js
│ │ ├── README.md
│ │ ├── test-fixtures
│ │ │ └── dw.json
│ │ └── yaml
│ │ ├── activate-code-version.docs-only.test.mcp.yml
│ │ ├── activate-code-version.full-mode.test.mcp.yml
│ │ ├── get_latest_error.test.mcp.yml
│ │ ├── get-available-best-practice-guides.docs-only.test.mcp.yml
│ │ ├── get-available-best-practice-guides.full-mode.test.mcp.yml
│ │ ├── get-available-sfra-documents.docs-only.test.mcp.yml
│ │ ├── get-available-sfra-documents.full-mode.test.mcp.yml
│ │ ├── get-best-practice-guide.docs-only.test.mcp.yml
│ │ ├── get-best-practice-guide.full-mode.test.mcp.yml
│ │ ├── get-code-versions.docs-only.test.mcp.yml
│ │ ├── get-code-versions.full-mode.test.mcp.yml
│ │ ├── get-hook-reference.docs-only.test.mcp.yml
│ │ ├── get-hook-reference.full-mode.test.mcp.yml
│ │ ├── get-job-execution-summary.full-mode.test.mcp.yml
│ │ ├── get-job-log-entries.full-mode.test.mcp.yml
│ │ ├── get-latest-debug.full-mode.test.mcp.yml
│ │ ├── get-latest-error.full-mode.test.mcp.yml
│ │ ├── get-latest-info.full-mode.test.mcp.yml
│ │ ├── get-latest-job-log-files.full-mode.test.mcp.yml
│ │ ├── get-latest-warn.full-mode.test.mcp.yml
│ │ ├── get-log-file-contents.full-mode.test.mcp.yml
│ │ ├── get-sfcc-class-documentation.docs-only.test.mcp.yml
│ │ ├── get-sfcc-class-documentation.full-mode.test.mcp.yml
│ │ ├── get-sfcc-class-info.docs-only.test.mcp.yml
│ │ ├── get-sfcc-class-info.full-mode.test.mcp.yml
│ │ ├── get-sfra-categories.docs-only.test.mcp.yml
│ │ ├── get-sfra-categories.full-mode.test.mcp.yml
│ │ ├── get-sfra-document.docs-only.test.mcp.yml
│ │ ├── get-sfra-document.full-mode.test.mcp.yml
│ │ ├── get-sfra-documents-by-category.docs-only.test.mcp.yml
│ │ ├── get-sfra-documents-by-category.full-mode.test.mcp.yml
│ │ ├── get-system-object-definition.docs-only.test.mcp.yml
│ │ ├── get-system-object-definition.full-mode.test.mcp.yml
│ │ ├── get-system-object-definitions.docs-only.test.mcp.yml
│ │ ├── get-system-object-definitions.full-mode.test.mcp.yml
│ │ ├── list-log-files.full-mode.test.mcp.yml
│ │ ├── list-sfcc-classes.docs-only.test.mcp.yml
│ │ ├── list-sfcc-classes.full-mode.test.mcp.yml
│ │ ├── search-best-practices.docs-only.test.mcp.yml
│ │ ├── search-best-practices.full-mode.test.mcp.yml
│ │ ├── search-custom-object-attribute-definitions.docs-only.test.mcp.yml
│ │ ├── search-custom-object-attribute-definitions.test.mcp.yml
│ │ ├── search-job-logs-by-name.full-mode.test.mcp.yml
│ │ ├── search-job-logs.full-mode.test.mcp.yml
│ │ ├── search-logs.full-mode.test.mcp.yml
│ │ ├── search-sfcc-classes.docs-only.test.mcp.yml
│ │ ├── search-sfcc-classes.full-mode.test.mcp.yml
│ │ ├── search-sfcc-methods.docs-only.test.mcp.yml
│ │ ├── search-sfcc-methods.full-mode.test.mcp.yml
│ │ ├── search-sfra-documentation.docs-only.test.mcp.yml
│ │ ├── search-sfra-documentation.full-mode.test.mcp.yml
│ │ ├── search-site-preferences.docs-only.test.mcp.yml
│ │ ├── search-site-preferences.full-mode.test.mcp.yml
│ │ ├── search-system-object-attribute-definitions.docs-only.test.mcp.yml
│ │ ├── search-system-object-attribute-definitions.full-mode.test.mcp.yml
│ │ ├── search-system-object-attribute-groups.docs-only.test.mcp.yml
│ │ ├── search-system-object-attribute-groups.full-mode.test.mcp.yml
│ │ ├── summarize-logs.full-mode.test.mcp.yml
│ │ ├── tools.docs-only.test.mcp.yml
│ │ └── tools.full-mode.test.mcp.yml
│ ├── oauth-token.test.ts
│ ├── ocapi-auth-client.test.ts
│ ├── ocapi-client.test.ts
│ ├── path-service.test.ts
│ ├── query-builder.test.ts
│ ├── referenced-types-extractor.test.ts
│ ├── servers
│ │ ├── sfcc-mock-server
│ │ │ ├── mock-data
│ │ │ │ └── ocapi
│ │ │ │ ├── code-versions.json
│ │ │ │ ├── custom-object-attributes-customapi.json
│ │ │ │ ├── custom-object-attributes-globalsettings.json
│ │ │ │ ├── custom-object-attributes-versionhistory.json
│ │ │ │ ├── site-preferences-ccv.json
│ │ │ │ ├── site-preferences-fastforward.json
│ │ │ │ ├── site-preferences-sfra.json
│ │ │ │ ├── site-preferences-storefront.json
│ │ │ │ ├── site-preferences-system.json
│ │ │ │ ├── system-object-attribute-groups-campaign.json
│ │ │ │ ├── system-object-attribute-groups-category.json
│ │ │ │ ├── system-object-attribute-groups-order.json
│ │ │ │ ├── system-object-attribute-groups-product.json
│ │ │ │ ├── system-object-attribute-groups-sitepreferences.json
│ │ │ │ ├── system-object-attributes-customeraddress.json
│ │ │ │ ├── system-object-attributes-product-expanded.json
│ │ │ │ ├── system-object-attributes-product.json
│ │ │ │ ├── system-object-definition-category.json
│ │ │ │ ├── system-object-definition-customer.json
│ │ │ │ ├── system-object-definition-customeraddress.json
│ │ │ │ ├── system-object-definition-order.json
│ │ │ │ ├── system-object-definition-product.json
│ │ │ │ ├── system-object-definitions-old.json
│ │ │ │ └── system-object-definitions.json
│ │ │ ├── package-lock.json
│ │ │ ├── package.json
│ │ │ ├── README.md
│ │ │ ├── scripts
│ │ │ │ └── setup-logs.js
│ │ │ ├── server.js
│ │ │ └── src
│ │ │ ├── app.js
│ │ │ ├── config
│ │ │ │ └── server-config.js
│ │ │ ├── middleware
│ │ │ │ ├── auth.js
│ │ │ │ ├── cors.js
│ │ │ │ └── logging.js
│ │ │ ├── routes
│ │ │ │ ├── ocapi
│ │ │ │ │ ├── code-versions-handler.js
│ │ │ │ │ ├── oauth-handler.js
│ │ │ │ │ ├── ocapi-error-utils.js
│ │ │ │ │ ├── ocapi-utils.js
│ │ │ │ │ ├── site-preferences-handler.js
│ │ │ │ │ └── system-objects-handler.js
│ │ │ │ ├── ocapi.js
│ │ │ │ └── webdav.js
│ │ │ └── utils
│ │ │ ├── mock-data-loader.js
│ │ │ └── webdav-xml.js
│ │ └── sfcc-mock-server-manager.ts
│ ├── sfcc-mock-server.test.ts
│ ├── site-preferences-client.test.ts
│ ├── system-objects-client.test.ts
│ ├── utils.test.ts
│ ├── validation-helpers.test.ts
│ └── validator.test.ts
├── tsconfig.json
└── tsconfig.test.json
```
# Files
--------------------------------------------------------------------------------
/tests/log-client.test.ts:
--------------------------------------------------------------------------------
```typescript
import { SFCCLogClient } from '../src/clients/log-client';
import { SFCCConfig, LogLevel } from '../src/types/types';
// Use manual mock for webdav
// eslint-disable-next-line @typescript-eslint/no-require-imports
const webdav = require('webdav');
const mockWebdavClient = webdav.__mockWebdavClient;
// Mock the logger
jest.mock('../src/utils/logger', () => ({
Logger: {
initialize: jest.fn(),
getInstance: jest.fn(() => ({
methodEntry: jest.fn(),
methodExit: jest.fn(),
debug: jest.fn(),
warn: jest.fn(),
error: jest.fn(),
timing: jest.fn(),
log: jest.fn(),
info: jest.fn(),
})),
getChildLogger: jest.fn(() => ({
methodEntry: jest.fn(),
methodExit: jest.fn(),
debug: jest.fn(),
warn: jest.fn(),
error: jest.fn(),
timing: jest.fn(),
log: jest.fn(),
info: jest.fn(),
})),
},
}));
// Mock utils
jest.mock('../src/utils/utils', () => ({
getCurrentDate: jest.fn(() => '20250815'),
formatBytes: jest.fn((bytes: number) => `${bytes} bytes`),
parseLogEntries: jest.fn((content: string, level: string) => {
// Better mock implementation - split by lines and filter by level, return the actual lines
return content.split('\n').filter(line => line.includes(level));
}),
extractUniqueErrors: jest.fn((errors: string[]) => {
// Mock implementation that returns unique error messages
return [...new Set(errors.map(error => error.trim()))];
}),
normalizeFilePath: jest.fn((path: string) => path),
}));
describe('SFCCLogClient', () => {
let logClient: SFCCLogClient;
let config: SFCCConfig;
beforeEach(() => {
// Setup test config
config = {
hostname: 'test.demandware.net',
username: 'testuser',
password: 'testpass',
};
logClient = new SFCCLogClient(config);
// Setup default mock for stat method (small file size so it uses getFileContents)
mockWebdavClient.stat.mockResolvedValue({ size: 1024 });
});
afterEach(() => {
jest.clearAllMocks();
});
describe('constructor', () => {
it('should create client with username/password authentication', () => {
const config: SFCCConfig = {
hostname: 'test.demandware.net',
username: 'testuser',
password: 'testpass',
};
new SFCCLogClient(config);
expect(webdav.createClient).toHaveBeenCalledWith(
'https://test.demandware.net/on/demandware.servlet/webdav/Sites/Logs/',
{
username: 'testuser',
password: 'testpass',
timeout: 30000,
maxBodyLength: 10 * 1024 * 1024,
maxContentLength: 10 * 1024 * 1024,
},
);
});
it('should create client with OAuth authentication', () => {
const config: SFCCConfig = {
hostname: 'test.demandware.net',
clientId: 'testclientid',
clientSecret: 'testclientsecret',
};
new SFCCLogClient(config);
expect(webdav.createClient).toHaveBeenCalledWith(
'https://test.demandware.net/on/demandware.servlet/webdav/Sites/Logs/',
{
username: 'testclientid',
password: 'testclientsecret',
timeout: 30000,
maxBodyLength: 10 * 1024 * 1024,
maxContentLength: 10 * 1024 * 1024,
},
);
});
it('should throw error when no authentication provided', () => {
const config: SFCCConfig = {
hostname: 'test.demandware.net',
};
expect(() => new SFCCLogClient(config)).toThrow(
'Either username/password or clientId/clientSecret must be provided',
);
});
});
describe('getLogFiles', () => {
it('should return log files for specified date', async () => {
const mockContents = [
{ type: 'file', filename: 'error-20250815-blade1-001.log' },
{ type: 'file', filename: 'warn-20250815-blade1-001.log' },
{ type: 'file', filename: 'info-20250815-blade1-001.log' },
{ type: 'file', filename: 'debug-20250815-blade1-001.log' },
{ type: 'file', filename: 'error-20250814-blade1-001.log' }, // Different date
{ type: 'directory', filename: 'somedir' }, // Directory
{ type: 'file', filename: 'not-a-log.txt' }, // Not a log file
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const result = await logClient.getLogFiles('20250815');
expect(result).toEqual([
{ filename: 'error-20250815-blade1-001.log', lastmod: expect.any(String) },
{ filename: 'warn-20250815-blade1-001.log', lastmod: expect.any(String) },
{ filename: 'info-20250815-blade1-001.log', lastmod: expect.any(String) },
{ filename: 'debug-20250815-blade1-001.log', lastmod: expect.any(String) },
]);
expect(mockWebdavClient.getDirectoryContents).toHaveBeenCalledWith('/');
});
it('should use current date when no date provided', async () => {
mockWebdavClient.getDirectoryContents.mockResolvedValue([]);
await logClient.getLogFiles();
// Should call getCurrentDate() from utils which returns '20250815'
expect(mockWebdavClient.getDirectoryContents).toHaveBeenCalledWith('/');
});
it('should return empty array when no log files found', async () => {
mockWebdavClient.getDirectoryContents.mockResolvedValue([]);
const result = await logClient.getLogFiles('20250815');
expect(result).toEqual([]);
});
});
describe('getLatestLogs', () => {
describe('standard log files', () => {
beforeEach(() => {
const mockContents = [
{ type: 'file', filename: 'error-20250815-blade1-001.log' },
{ type: 'file', filename: 'error-20250815-blade1-002.log' },
{ type: 'file', filename: 'warn-20250815-blade1-001.log' },
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
});
it('should return latest error logs', async () => {
const mockLogContent = 'ERROR Line 1\nERROR Line 2\nERROR Line 3\nERROR Line 4\nERROR Line 5';
mockWebdavClient.getFileContents.mockResolvedValue(mockLogContent);
const result = await logClient.getLatestLogs('error' as LogLevel, 3, '20250815');
expect(result).toContain('Latest 3 error messages');
expect(result).toContain('error-20250815-blade1-002.log'); // Should use the latest file
// Since files are small (1024 bytes), getFileContentsTail should call getFileContents
expect(mockWebdavClient.getFileContents).toHaveBeenCalledWith(
'error-20250815-blade1-002.log',
{ format: 'text' },
);
});
it('should return warning when no files found for level', async () => {
const mockContents = [
{ type: 'file', filename: 'info-20250815-blade1-001.log' },
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const result = await logClient.getLatestLogs('error' as LogLevel, 10, '20250815');
expect(result).toContain('No error log files found');
expect(result).toContain('Available files: info-20250815-blade1-001.log');
});
});
describe('custom log files support', () => {
it('should include both standard and custom log files for warn level', async () => {
const mockContents = [
{ type: 'file', filename: 'warn-odspod-0-appserver-20250815.log' },
{ type: 'file', filename: 'customwarn-odspod-0-appserver-20250815.log' }, // Same date
{ type: 'file', filename: 'warn-blade1-20250815.log' }, // Another warn file same date
{ type: 'file', filename: 'error-odspod-0-appserver-20250815.log' }, // Different level - should be ignored
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const mockWarnContent = 'WARN Entry from standard warn file';
const mockCustomWarnContent = 'WARN Entry from custom warn file';
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockWarnContent) // newest standard file first
.mockResolvedValueOnce(mockWarnContent) // second standard file
.mockResolvedValueOnce(mockCustomWarnContent); // custom file
const result = await logClient.getLatestLogs('warn' as LogLevel, 5, '20250815');
expect(result).toContain('Latest 5 warn messages from files');
expect(result).toContain('warn-odspod-0-appserver-20250815.log'); // Should include newest standard
expect(result).toContain('customwarn-odspod-0-appserver-20250815.log'); // Should include custom
expect(mockWebdavClient.getFileContents).toHaveBeenCalledTimes(3); // All matching files
});
it('should include both standard and custom log files for error level', async () => {
const mockContents = [
{ type: 'file', filename: 'error-odspod-0-appserver-20250815.log' },
{ type: 'file', filename: 'customerror-odspod-0-appserver-20250815.log' },
{ type: 'file', filename: 'warn-odspod-0-appserver-20250815.log' }, // Different level - should be ignored
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const mockErrorContent = 'ERROR Standard error entry';
const mockCustomErrorContent = 'ERROR Custom error entry';
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockErrorContent) // newest standard file
.mockResolvedValueOnce(mockCustomErrorContent); // custom file same day
const result = await logClient.getLatestLogs('error' as LogLevel, 3, '20250815');
expect(result).toContain('Latest 3 error messages from files');
expect(result).toContain('error-odspod-0-appserver-20250815.log');
expect(result).toContain('customerror-odspod-0-appserver-20250815.log');
expect(mockWebdavClient.getFileContents).toHaveBeenCalledTimes(2); // Only files for the specified date
});
});
describe('chronological sorting with real-world filenames', () => {
it('should process files by lastmod timestamp (newest first)', async () => {
// Real-world log files with different lastmod timestamps
const mockContents = [
{
type: 'file',
filename: 'warn-blade1-20250815.log',
lastmod: '2025-08-15T06:30:00.000Z', // Older timestamp
},
{
type: 'file',
filename: 'warn-odspod-0-appserver-20250815.log',
lastmod: '2025-08-15T08:15:00.000Z', // Middle timestamp
},
{
type: 'file',
filename: 'warn-xyz-server-20250815.log',
lastmod: '2025-08-15T10:45:00.000Z', // Newest timestamp
},
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
// Mock content for each warn file
const mockContent1 = 'WARN 06:32:07 Warning from blade1\nWARN 06:30:00 Another warning from blade1';
const mockContent2 = 'WARN 08:16:33 Warning from odspod\nWARN 08:15:00 Another warning from odspod';
const mockContent3 = 'WARN 10:45:12 Warning from xyz\nWARN 10:44:00 Another warning from xyz';
// Files should be processed by lastmod order (newest first): xyz, odspod, blade1
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockContent3) // warn-xyz-server- (newest lastmod, processed first)
.mockResolvedValueOnce(mockContent2) // warn-odspod- (middle lastmod)
.mockResolvedValueOnce(mockContent1); // warn-blade1- (oldest lastmod, processed last)
const result = await logClient.getLatestLogs('warn' as LogLevel, 4, '20250815');
expect(result).toContain('Latest 4 warn messages');
expect(result).toContain('warn-xyz-server-20250815.log');
expect(result).toContain('warn-odspod-0-appserver-20250815.log');
expect(result).toContain('warn-blade1-20250815.log');
expect(mockWebdavClient.getFileContents).toHaveBeenCalledTimes(3);
// Verify the processing order matches chronological sorting by lastmod
expect(mockWebdavClient.getFileContents).toHaveBeenNthCalledWith(1, 'warn-xyz-server-20250815.log', { format: 'text' });
expect(mockWebdavClient.getFileContents).toHaveBeenNthCalledWith(2, 'warn-odspod-0-appserver-20250815.log', { format: 'text' });
expect(mockWebdavClient.getFileContents).toHaveBeenNthCalledWith(3, 'warn-blade1-20250815.log', { format: 'text' });
});
it('should handle custom log files in chronological sorting', async () => {
const mockContents = [
{
type: 'file',
filename: 'customwarn-alpha-20250815.log',
lastmod: '2025-08-15T10:00:00.000Z', // Newest timestamp
},
{
type: 'file',
filename: 'warn-beta-20250815.log',
lastmod: '2025-08-15T08:00:00.000Z', // Oldest timestamp
},
{
type: 'file',
filename: 'customwarn-gamma-20250815.log',
lastmod: '2025-08-15T09:00:00.000Z', // Middle timestamp
},
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const mockContent1 = 'WARN 10:00:00 Custom warning from alpha';
const mockContent2 = 'WARN 08:00:00 Standard warning from beta';
const mockContent3 = 'WARN 09:00:00 Custom warning from gamma';
// Expected chronological order by lastmod: alpha (10:00), gamma (09:00), beta (08:00)
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockContent1) // customwarn-alpha- (newest lastmod, processed first)
.mockResolvedValueOnce(mockContent3) // customwarn-gamma- (middle lastmod)
.mockResolvedValueOnce(mockContent2); // warn-beta- (oldest lastmod, processed last)
const result = await logClient.getLatestLogs('warn' as LogLevel, 3, '20250815');
expect(result).toContain('Latest 3 warn messages');
expect(mockWebdavClient.getFileContents).toHaveBeenCalledTimes(3);
// Verify processing order follows chronological sorting by lastmod
expect(mockWebdavClient.getFileContents).toHaveBeenNthCalledWith(1, 'customwarn-alpha-20250815.log', { format: 'text' });
expect(mockWebdavClient.getFileContents).toHaveBeenNthCalledWith(2, 'customwarn-gamma-20250815.log', { format: 'text' });
expect(mockWebdavClient.getFileContents).toHaveBeenNthCalledWith(3, 'warn-beta-20250815.log', { format: 'text' });
});
it('should handle missing lastmod gracefully with fallback', async () => {
const mockContents = [
{
type: 'file',
filename: 'warn-file1-20250815.log',
lastmod: '2025-08-15T08:00:00.000Z',
},
{
type: 'file',
filename: 'warn-file2-20250815.log',
// Missing lastmod - should use fallback
},
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const mockContent1 = 'WARN Content from file1';
const mockContent2 = 'WARN Content from file2';
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockContent2) // file2 (fallback to current time, processed first)
.mockResolvedValueOnce(mockContent1); // file1 (has lastmod, processed second)
const result = await logClient.getLatestLogs('warn' as LogLevel, 2, '20250815');
expect(result).toContain('Latest 2 warn messages');
expect(mockWebdavClient.getFileContents).toHaveBeenCalledTimes(2);
// Should handle both files even with missing lastmod
expect(result).toContain('warn-file1-20250815.log');
expect(result).toContain('warn-file2-20250815.log');
});
});
describe('file sorting and date filtering', () => {
it('should only process files matching the specified date', async () => {
// Mix of files from different dates
const mockContents = [
{ type: 'file', filename: 'error-odspod-0-appserver-20250815.log' }, // Target date
{ type: 'file', filename: 'error-blade1-20250815.log' }, // Target date
{ type: 'file', filename: 'error-odspod-0-appserver-20250814.log' }, // Previous day
{ type: 'file', filename: 'error-blade1-20250816.log' }, // Next day
{ type: 'file', filename: 'error-xyz-20250813.log' }, // Older date
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
// Mock content for the target date files only
const targetDateContent1 = 'ERROR 05:17:54 Error from target date file 1\nERROR 05:16:00 Another error from file 1';
const targetDateContent2 = 'ERROR 11:24:07 Error from target date file 2\nERROR 11:20:00 Another error from file 2';
mockWebdavClient.getFileContents
.mockResolvedValueOnce(targetDateContent1) // error-odspod-0-appserver-20250815.log
.mockResolvedValueOnce(targetDateContent2); // error-blade1-20250815.log
const result = await logClient.getLatestLogs('error' as LogLevel, 3, '20250815');
// Should only process files from the target date (20250815)
expect(result).toContain('Latest 3 error messages from files');
expect(result).toContain('error-odspod-0-appserver-20250815.log');
expect(result).toContain('error-blade1-20250815.log');
// Should NOT contain files from other dates
expect(result).not.toContain('20250814');
expect(result).not.toContain('20250816');
expect(result).not.toContain('20250813');
// Should only call getFileContents for files matching the target date
expect(mockWebdavClient.getFileContents).toHaveBeenCalledTimes(2);
expect(mockWebdavClient.getFileContents).toHaveBeenCalledWith('error-odspod-0-appserver-20250815.log', { format: 'text' });
expect(mockWebdavClient.getFileContents).toHaveBeenCalledWith('error-blade1-20250815.log', { format: 'text' });
});
it('should handle multiple dates correctly when getLogFiles filters by specific date', async () => {
// Test with a different date to ensure date filtering works correctly
const mockContents = [
{ type: 'file', filename: 'warn-server1-20250810.log' },
{ type: 'file', filename: 'warn-server2-20250810.log' },
{ type: 'file', filename: 'customwarn-server3-20250810.log' },
{ type: 'file', filename: 'warn-server1-20250815.log' }, // Different date - should be filtered out
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const mockContent1 = 'WARN 08:00:00 Warning from server1 on 20250810';
const mockContent2 = 'WARN 09:00:00 Warning from server2 on 20250810';
const mockContent3 = 'WARN 10:00:00 Custom warning from server3 on 20250810';
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockContent1)
.mockResolvedValueOnce(mockContent2)
.mockResolvedValueOnce(mockContent3);
const result = await logClient.getLatestLogs('warn' as LogLevel, 5, '20250810');
expect(result).toContain('Latest 5 warn messages');
expect(result).toContain('warn-server1-20250810.log');
expect(result).toContain('warn-server2-20250810.log');
expect(result).toContain('customwarn-server3-20250810.log');
// Should not include the file from 20250815
expect(result).not.toContain('20250815');
// Should process 3 files from the target date only
expect(mockWebdavClient.getFileContents).toHaveBeenCalledTimes(3);
});
});
it('should handle file read errors gracefully and continue processing other files', async () => {
const mockContents = [
{ type: 'file', filename: 'warn-20250815-blade1-001.log' },
{ type: 'file', filename: 'warn-20250815-blade1-002.log' },
{ type: 'file', filename: 'warn-20250815-blade1-003.log' },
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const mockContent = 'WARN Working file content';
// Clear previous mocks to ensure clean state
mockWebdavClient.getFileContents.mockClear();
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockContent) // First file succeeds
.mockRejectedValueOnce(new Error('File read error')) // Second file fails
.mockResolvedValueOnce(mockContent); // Third file succeeds
const result = await logClient.getLatestLogs('warn' as LogLevel, 5, '20250815');
expect(result).toContain('Latest 5 warn messages');
// With our new implementation using getFileContentsTail, the call pattern may be different
// The important thing is that it handles errors gracefully and continues processing
expect(mockWebdavClient.getFileContents.mock.calls.length).toBeGreaterThanOrEqual(3);
// Should complete processing despite errors - verifies error resilience
expect(result).toContain('warn-20250815-blade1');
});
});
describe('summarizeLogs', () => {
it('should return summary when no log files found', async () => {
mockWebdavClient.getDirectoryContents.mockResolvedValue([]);
const result = await logClient.summarizeLogs('20250815');
expect(result).toBe('No log files found for date 20250815');
});
it('should generate comprehensive log summary', async () => {
const mockContents = [
{ type: 'file', filename: 'error-20250815-blade1-001.log' },
{ type: 'file', filename: 'warn-20250815-blade1-001.log' },
{ type: 'file', filename: 'info-20250815-blade1-001.log' },
{ type: 'file', filename: 'debug-20250815-blade1-001.log' },
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
// Update content to match what the actual summarizeLogs method expects
const mockErrorContent = 'First line\n ERROR Something went wrong\nAnother line\n ERROR Another error\n INFO Some info';
const mockWarnContent = 'Start line\n WARN Warning message\n INFO Info message';
const mockInfoContent = 'Header\n INFO First info\n INFO Second info\n INFO Third info';
const mockDebugContent = 'Prefix\n DEBUG Debug message 1\n DEBUG Debug message 2\n DEBUG Debug message 3';
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockErrorContent)
.mockResolvedValueOnce(mockWarnContent)
.mockResolvedValueOnce(mockInfoContent)
.mockResolvedValueOnce(mockDebugContent);
const result = await logClient.summarizeLogs('20250815');
expect(result).toContain('Log Summary for 20250815');
expect(result).toContain('Errors: 2');
expect(result).toContain('Warnings: 1');
expect(result).toContain('Info: 5'); // 1 from error file + 1 from warn file + 3 from info file
expect(result).toContain('Debug: 3');
expect(result).toContain('Log Files (4)');
});
it('should handle file read errors gracefully', async () => {
const mockContents = [
{ type: 'file', filename: 'error-20250815-blade1-001.log' },
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
mockWebdavClient.getFileContents.mockRejectedValue(new Error('File read error'));
const result = await logClient.summarizeLogs('20250815');
expect(result).toContain('Log Summary for 20250815');
expect(result).toContain('Errors: 0');
expect(result).toContain('Debug: 0');
});
});
describe('searchLogs', () => {
beforeEach(() => {
const mockContents = [
{ type: 'file', filename: 'error-20250815-blade1-001.log' },
{ type: 'file', filename: 'warn-20250815-blade1-001.log' },
{ type: 'file', filename: 'customwarn-20250815-blade1-001.log' },
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
});
it('should search across all log files when no level specified', async () => {
const mockErrorContent = 'ERROR: Database connection failed\nINFO: System started';
const mockWarnContent = 'WARN: Database connection slow\nINFO: Cache cleared';
const mockCustomWarnContent = 'WARN: Custom database warning';
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockErrorContent)
.mockResolvedValueOnce(mockWarnContent)
.mockResolvedValueOnce(mockCustomWarnContent);
const result = await logClient.searchLogs('database', undefined, 20, '20250815');
expect(result).toContain('Found 3 matches for "database"');
expect(result).toContain('Database connection failed');
expect(result).toContain('Database connection slow');
expect(result).toContain('Custom database warning');
});
it('should filter by log level including custom files when specified', async () => {
const mockWarnContent = 'WARN: Standard warning message with the word warning';
const mockCustomWarnContent = 'WARN: Custom warning message with the word warning';
mockWebdavClient.getFileContents
.mockResolvedValueOnce(mockWarnContent)
.mockResolvedValueOnce(mockCustomWarnContent);
const result = await logClient.searchLogs('warning', 'warn' as LogLevel, 20, '20250815');
expect(mockWebdavClient.getFileContents).toHaveBeenCalledTimes(2); // Both warn files
expect(mockWebdavClient.getFileContents).toHaveBeenCalledWith('warn-20250815-blade1-001.log', { format: 'text' });
expect(mockWebdavClient.getFileContents).toHaveBeenCalledWith('customwarn-20250815-blade1-001.log', { format: 'text' });
expect(result).toContain('Standard warning message');
expect(result).toContain('Custom warning message');
});
it('should return no matches message when pattern not found', async () => {
mockWebdavClient.getFileContents.mockResolvedValue('No matching content here');
const result = await logClient.searchLogs('nonexistent', undefined, 20, '20250815');
expect(result).toContain('No matches found for "nonexistent" in logs for 20250815');
});
it('should handle search errors gracefully', async () => {
mockWebdavClient.getFileContents.mockRejectedValue(new Error('Search error'));
const result = await logClient.searchLogs('pattern', undefined, 20, '20250815');
expect(result).toContain('No matches found for "pattern"');
});
});
describe('listLogFiles', () => {
it('should return formatted list of log files sorted by modification date', async () => {
const mockContents = [
{
type: 'file',
filename: 'warn-odspod-0-appserver-20250815.log',
size: 46387,
lastmod: 'Fri, 15 Aug 2025 06:32:07 GMT',
},
{
type: 'file',
filename: 'error-odspod-0-appserver-20250815.log',
size: 2560,
lastmod: 'Fri, 15 Aug 2025 05:17:54 GMT',
},
{
type: 'file',
filename: 'warn-odspod-0-appserver-20250814.log',
size: 139161,
lastmod: 'Thu, 14 Aug 2025 23:59:25 GMT',
},
{ type: 'directory', filename: 'log_archive' }, // Should be filtered out
{ type: 'file', filename: 'not-a-log.txt' }, // Should be filtered out
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const result = await logClient.listLogFiles();
expect(result).toContain('Available log files:');
expect(result).toContain('📄 warn-odspod-0-appserver-20250815.log');
expect(result).toContain('📄 error-odspod-0-appserver-20250815.log');
expect(result).toContain('📄 warn-odspod-0-appserver-20250814.log');
// Should show newest file first
const warnIndex = result.indexOf('warn-odspod-0-appserver-20250815.log');
const errorIndex = result.indexOf('error-odspod-0-appserver-20250815.log');
const oldWarnIndex = result.indexOf('warn-odspod-0-appserver-20250814.log');
expect(warnIndex).toBeLessThan(errorIndex); // Newest file first
expect(errorIndex).toBeLessThan(oldWarnIndex); // Then by date
// Should not contain non-log files
expect(result).not.toContain('log_archive');
expect(result).not.toContain('not-a-log.txt');
});
it('should show total count when more than 50 files', async () => {
// Create 60 mock log files
const mockContents = Array.from({ length: 60 }, (_, i) => ({
type: 'file',
filename: `log-file-${i.toString().padStart(3, '0')}.log`,
size: 1000,
lastmod: new Date(2025, 7, 15, 12, i).toISOString(),
}));
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
const result = await logClient.listLogFiles();
expect(result).toContain('(showing latest 50 of 60 total)');
});
it('should handle errors when listing files', async () => {
mockWebdavClient.getDirectoryContents.mockRejectedValue(new Error('List error'));
await expect(logClient.listLogFiles()).rejects.toThrow('Failed to list log files: List error');
});
});
describe('getLogFileContents', () => {
it('should read full file content when tailOnly is false and no maxBytes', async () => {
const mockFileContent = 'This is a full log file content\nLine 2\nLine 3\nLine 4';
mockWebdavClient.getFileContents.mockResolvedValue(mockFileContent);
const result = await logClient.getLogFileContents('test.log', undefined, false);
expect(mockWebdavClient.getFileContents).toHaveBeenCalledWith('test.log', { format: 'text' });
expect(result).toContain('This is a full log file content');
expect(result).toContain('Line 4');
});
it('should respect maxBytes when tailOnly is false and maxBytes is specified', async () => {
const mockFileContent = 'This is a very long log file content that should be truncated';
const mockStat = { size: 1000 }; // Simulate a large file
mockWebdavClient.stat.mockResolvedValue(mockStat);
// Mock the stream for range request from start
const mockStream = {
on: jest.fn((event, callback) => {
if (event === 'data') {
callback(Buffer.from(mockFileContent.substring(0, 50))); // First 50 bytes
} else if (event === 'end') {
callback();
}
}),
};
mockWebdavClient.createReadStream.mockReturnValue(mockStream);
const result = await logClient.getLogFileContents('test.log', 50, false);
expect(mockWebdavClient.stat).toHaveBeenCalledWith('test.log');
expect(mockWebdavClient.createReadStream).toHaveBeenCalledWith('test.log', {
range: { start: 0, end: 49 },
});
expect(result).toContain('This is a very long log file content that should');
});
it('should read tail content when tailOnly is true', async () => {
const mockFileContent = 'Tail content from the end of the file';
const mockStat = { size: 1000 };
mockWebdavClient.stat.mockResolvedValue(mockStat);
// Mock the stream for range request
const mockStream = {
on: jest.fn((event, callback) => {
if (event === 'data') {
callback(Buffer.from(mockFileContent));
} else if (event === 'end') {
callback();
}
}),
};
mockWebdavClient.createReadStream.mockReturnValue(mockStream);
const result = await logClient.getLogFileContents('test.log', 200, true);
expect(mockWebdavClient.stat).toHaveBeenCalledWith('test.log');
expect(mockWebdavClient.createReadStream).toHaveBeenCalledWith('test.log', {
range: { start: 800, end: 999 },
});
expect(result).toContain('Tail content from the end');
});
it('should handle file that is smaller than maxBytes when using tail', async () => {
const mockFileContent = 'Small file';
const mockStat = { size: 10 };
mockWebdavClient.stat.mockResolvedValue(mockStat);
mockWebdavClient.getFileContents.mockResolvedValue(mockFileContent);
const result = await logClient.getLogFileContents('test.log', 200, true);
// Should read full file since it's smaller than maxBytes
expect(mockWebdavClient.getFileContents).toHaveBeenCalledWith('test.log', { format: 'text' });
expect(result).toContain('Small file');
});
});
describe('error handling', () => {
it('should handle WebDAV connection errors in getLogFiles', async () => {
mockWebdavClient.getDirectoryContents.mockRejectedValue(new Error('Connection failed'));
await expect(logClient.getLogFiles()).rejects.toThrow('Connection failed');
});
it('should handle file read errors gracefully in getLatestLogs', async () => {
const mockContents = [
{ type: 'file', filename: 'error-20250815-blade1-001.log' },
];
mockWebdavClient.getDirectoryContents.mockResolvedValue(mockContents);
mockWebdavClient.getFileContents.mockRejectedValue(new Error('File not found'));
// Should not throw error but handle gracefully and return empty result
const result = await logClient.getLatestLogs('error' as LogLevel, 10, '20250815');
expect(result).toContain('Latest 10 error messages from files');
expect(result).toContain('error-20250815-blade1-001.log');
// Should handle the error gracefully and continue
});
});
});
```
--------------------------------------------------------------------------------
/tests/mcp/node/search-custom-object-attribute-definitions.full-mode.programmatic.test.js:
--------------------------------------------------------------------------------
```javascript
import { test, describe, before, after, beforeEach } from 'node:test';
import { strict as assert } from 'node:assert';
import { connect } from 'mcp-aegis';
describe('search_custom_object_attribute_definitions - Full Mode Programmatic Tests', () => {
let client;
before(async () => {
client = await connect('./aegis.config.with-dw.json');
});
after(async () => {
if (client?.connected) {
await client.disconnect();
}
});
beforeEach(() => {
// CRITICAL: Clear all buffers to prevent leaking into next tests
client.clearAllBuffers();
});
// ============================================================================
// HELPER FUNCTIONS - Custom Assertion Helpers for SFCC-specific validation
// ============================================================================
/**
* Assert that a result is a valid MCP response
*/
function assertValidMCPResponse(result, shouldBeError = false) {
assert.ok(result.content, 'Result should have content');
assert.ok(Array.isArray(result.content), 'Content should be array');
assert.equal(typeof result.isError, 'boolean', 'isError should be boolean');
assert.equal(result.isError, shouldBeError, `isError should be ${shouldBeError}`);
}
/**
* Assert that a result contains valid SFCC attribute definition search response
*/
function assertValidAttributeSearchResponse(result) {
assertValidMCPResponse(result, false);
assert.equal(result.content[0].type, 'text');
const responseData = JSON.parse(result.content[0].text);
assert.equal(responseData._type, 'object_attribute_definition_search_result');
assert.ok(typeof responseData.count === 'number', 'Should have count');
assert.ok(typeof responseData.total === 'number', 'Should have total');
assert.ok(Array.isArray(responseData.hits), 'Should have hits array');
assert.ok(responseData.query, 'Should have query object');
return responseData;
}
/**
* Assert that an attribute definition has required SFCC fields
*/
function assertValidAttributeDefinition(attribute) {
assert.equal(attribute._type, 'object_attribute_definition');
assert.ok(attribute.id, 'Attribute should have id');
assert.ok(attribute.value_type, 'Attribute should have value_type');
assert.ok(typeof attribute.mandatory === 'boolean', 'Attribute should have mandatory boolean');
assert.ok(typeof attribute.queryable === 'boolean', 'Attribute should have queryable boolean');
assert.ok(typeof attribute.system === 'boolean', 'Attribute should have system boolean');
assert.ok(attribute.creation_date, 'Attribute should have creation_date');
assert.ok(attribute.last_modified, 'Attribute should have last_modified');
}
/**
* Assert that error response contains expected SFCC error structure
*/
function assertSFCCErrorResponse(result, errorType = null) {
assertValidMCPResponse(result, true);
const errorText = result.content[0].text;
if (errorType) {
assert.ok(errorText.includes(errorType), `Error should contain ${errorType}`);
}
// Check if it's a structured SFCC error (JSON format)
if (errorText.startsWith('Error: Request failed:')) {
const jsonMatch = errorText.match(/\{.*\}/s);
if (jsonMatch) {
const errorData = JSON.parse(jsonMatch[0]);
assert.ok(errorData.fault, 'SFCC error should have fault object');
assert.ok(errorData.fault.type, 'SFCC error should have fault type');
assert.ok(errorData.fault.message, 'SFCC error should have fault message');
}
}
}
// ============================================================================
// PROTOCOL COMPLIANCE TESTS
// ============================================================================
describe('Protocol Compliance', () => {
test('should complete MCP handshake successfully', async () => {
assert.ok(client.connected, 'Client should be connected after handshake');
});
test('should list search_custom_object_attribute_definitions in available tools', async () => {
const tools = await client.listTools();
assert.ok(Array.isArray(tools), 'Tools should be an array');
const targetTool = tools.find(tool => tool.name === 'search_custom_object_attribute_definitions');
assert.ok(targetTool, 'search_custom_object_attribute_definitions should be available');
assert.ok(targetTool.description, 'Tool should have description');
assert.ok(targetTool.inputSchema, 'Tool should have input schema');
assert.equal(targetTool.inputSchema.type, 'object', 'Schema should be object type');
// Validate required parameters
const requiredParams = targetTool.inputSchema.required || [];
assert.ok(requiredParams.includes('objectType'), 'objectType should be required');
});
});
// ============================================================================
// BASIC FUNCTIONALITY TESTS
// ============================================================================
describe('Basic Functionality', () => {
test('should search VersionHistory custom object attributes successfully', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
},
start: 0,
count: 10
}
});
const responseData = assertValidAttributeSearchResponse(result);
assert.ok(responseData.hits.length > 0, 'Should return some attributes');
// Validate each attribute definition
responseData.hits.forEach(attribute => {
assertValidAttributeDefinition(attribute);
});
});
test('should handle minimal parameters with default search', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory'
});
const responseData = assertValidAttributeSearchResponse(result);
assert.ok(responseData.hits.length > 0, 'Should return attributes with default search');
assert.equal(responseData.query.match_all_query._type, 'match_all_query');
});
});
// ============================================================================
// COMPLEX QUERY BUILDING AND FILTERING TESTS
// ============================================================================
describe('Complex Query Building', () => {
test('should execute text search queries correctly', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
text_query: {
fields: ['id', 'display_name'],
search_phrase: 'UUID'
}
},
start: 0,
count: 5
}
});
const responseData = assertValidAttributeSearchResponse(result);
// Should find UUID attribute
const uuidAttribute = responseData.hits.find(attr => attr.id === 'UUID');
if (uuidAttribute) {
assertValidAttributeDefinition(uuidAttribute);
assert.equal(uuidAttribute.value_type, 'string');
assert.equal(uuidAttribute.system, true);
}
});
test('should handle complex boolean queries with multiple conditions', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
bool_query: {
must: [
{
term_query: {
fields: ['value_type'],
operator: 'is',
values: ['string']
}
}
],
should: [
{
text_query: {
fields: ['id'],
search_phrase: 'user'
}
},
{
text_query: {
fields: ['id'],
search_phrase: 'locale'
}
}
]
}
}
}
});
const responseData = assertValidAttributeSearchResponse(result);
// Check that we get attributes and can distinguish types
responseData.hits.forEach(attribute => {
assertValidAttributeDefinition(attribute);
assert.ok(['string', 'datetime', 'text', 'int', 'double', 'boolean'].includes(attribute.value_type),
`Attribute should have valid value_type, got: ${attribute.value_type}`);
});
// Log type distribution for debugging
const stringAttrs = responseData.hits.filter(attr => attr.value_type === 'string').length;
const totalAttrs = responseData.hits.length;
console.log(`Found ${stringAttrs} string attributes out of ${totalAttrs} total attributes`);
});
test('should support pagination with different start and count values', async () => {
// Get first page
const firstPage = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
},
start: 0,
count: 3
}
});
const firstPageData = assertValidAttributeSearchResponse(firstPage);
assert.ok(firstPageData.hits.length <= 3, 'First page should have max 3 results');
// Get second page
const secondPage = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
},
start: 3,
count: 3
}
});
const secondPageData = assertValidAttributeSearchResponse(secondPage);
// Verify pagination consistency
assert.equal(firstPageData.total, secondPageData.total, 'Total count should be consistent');
assert.equal(firstPageData.start, 0, 'First page start should be 0');
assert.equal(secondPageData.start, 3, 'Second page start should be 3');
// Ensure no overlap between pages
const firstPageIds = firstPageData.hits.map(attr => attr.id);
const secondPageIds = secondPageData.hits.map(attr => attr.id);
const overlap = firstPageIds.filter(id => secondPageIds.includes(id));
assert.equal(overlap.length, 0, 'Pages should not have overlapping results');
});
test('should apply sorting parameters correctly', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
},
sorts: [
{
field: 'id',
sort_order: 'asc'
}
],
count: 10
}
});
const responseData = assertValidAttributeSearchResponse(result);
if (responseData.hits.length > 1) {
// Verify ascending sort order by id
for (let i = 1; i < responseData.hits.length; i++) {
const current = responseData.hits[i].id;
const previous = responseData.hits[i - 1].id;
assert.ok(current >= previous, `Results should be sorted ascending: ${previous} <= ${current}`);
}
}
});
});
// ============================================================================
// MULTI-STEP WORKFLOW TESTS
// ============================================================================
describe('Multi-Step Workflows', () => {
test('should support discovery and detailed analysis workflow', async () => {
// Step 1: Discover all custom objects first (this would typically use get_system_object_definitions)
// For this test, we'll use known custom objects from our mock
const knownCustomObjects = ['VersionHistory', 'CustomAPI', 'GlobalSettings'];
const attributesByObjectType = new Map();
// Step 2: For each custom object, get its attribute definitions
for (const objectType of knownCustomObjects) {
try {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: objectType,
searchRequest: {
query: {
match_all_query: {}
}
}
});
if (!result.isError) {
const responseData = assertValidAttributeSearchResponse(result);
attributesByObjectType.set(objectType, responseData.hits);
}
} catch (error) {
// Some objects might not exist, continue with others
console.log(`Skipping ${objectType}: ${error.message}`);
}
}
// Step 3: Analyze collected attributes for patterns
let totalAttributes = 0;
let systemAttributes = 0;
let mandatoryAttributes = 0;
const valueTypeDistribution = new Map();
for (const [, attributes] of attributesByObjectType) {
totalAttributes += attributes.length;
attributes.forEach(attr => {
if (attr.system) systemAttributes++;
if (attr.mandatory) mandatoryAttributes++;
const valueType = attr.value_type;
valueTypeDistribution.set(valueType, (valueTypeDistribution.get(valueType) || 0) + 1);
});
}
// Step 4: Validate analysis results
assert.ok(totalAttributes > 0, 'Should have found some attributes');
assert.ok(systemAttributes > 0, 'Should have some system attributes');
assert.ok(valueTypeDistribution.has('string'), 'Should have string type attributes');
console.log(`Analysis complete: ${totalAttributes} total attributes across ${attributesByObjectType.size} objects`);
console.log(`System attributes: ${systemAttributes}, Mandatory: ${mandatoryAttributes}`);
console.log('Value type distribution:', Object.fromEntries(valueTypeDistribution));
});
test('should support attribute comparison across different custom objects', async () => {
const comparisonResults = [];
const objectTypes = ['VersionHistory', 'CustomAPI'];
// Collect attributes for each object type
for (const objectType of objectTypes) {
try {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: objectType,
searchRequest: {
query: {
match_all_query: {}
}
}
});
if (!result.isError) {
const responseData = assertValidAttributeSearchResponse(result);
comparisonResults.push({
objectType,
attributes: responseData.hits,
count: responseData.total
});
}
} catch {
// Continue with available objects
}
}
assert.ok(comparisonResults.length >= 1, 'Should have results for at least one object type');
// Compare common attributes across object types
if (comparisonResults.length > 1) {
const [first, second] = comparisonResults;
const firstIds = new Set(first.attributes.map(attr => attr.id));
const secondIds = new Set(second.attributes.map(attr => attr.id));
const commonAttributes = [...firstIds].filter(id => secondIds.has(id));
console.log(`Common attributes between ${first.objectType} and ${second.objectType}:`, commonAttributes);
// System attributes like 'ID', 'UUID' should be common
assert.ok(commonAttributes.includes('ID'), 'ID should be common across custom objects');
}
});
});
// ============================================================================
// ERROR RECOVERY AND RESILIENCE TESTS
// ============================================================================
describe('Error Recovery and Resilience', () => {
test('should handle unknown custom object types gracefully', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'NonExistentCustomObject',
searchRequest: {
query: {
match_all_query: {}
}
}
});
assertSFCCErrorResponse(result, 'ObjectTypeNotFoundException');
});
test('should recover from invalid queries and continue working', async () => {
// Try invalid query structure
const invalidResult = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
invalidStructure: 'badData'
}
});
assertSFCCErrorResponse(invalidResult, 'PropertyConstraintViolationException');
// Verify system still works with valid query
const validResult = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
}
}
});
assertValidAttributeSearchResponse(validResult);
});
test('should handle parameter validation errors consistently', async () => {
const testCases = [
{ params: {}, expectedError: 'objectType' },
{ params: { objectType: '' }, expectedError: 'objectType must be a non-empty string' },
{ params: { objectType: null }, expectedError: 'objectType' },
{ params: { objectType: 123 }, expectedError: 'objectType' }
];
for (const testCase of testCases) {
const result = await client.callTool('search_custom_object_attribute_definitions', testCase.params);
assertValidMCPResponse(result, true);
assert.ok(
result.content[0].text.includes(testCase.expectedError),
`Should contain error message about ${testCase.expectedError}`
);
}
});
test('should maintain consistency across multiple rapid requests', async () => {
const results = [];
const requestCount = 5;
// Execute multiple sequential requests (no Promise.all as per guidelines)
for (let i = 0; i < requestCount; i++) {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
}
}
});
assertValidAttributeSearchResponse(result);
results.push(JSON.parse(result.content[0].text));
}
// Verify consistency across all requests
const firstResult = results[0];
for (let i = 1; i < results.length; i++) {
assert.equal(results[i].total, firstResult.total, 'Total count should be consistent');
assert.equal(results[i].count, firstResult.count, 'Result count should be consistent');
assert.deepEqual(results[i].hits, firstResult.hits, 'Results should be identical');
}
});
});
// ============================================================================
// DYNAMIC VALIDATION AND BUSINESS LOGIC TESTS
// ============================================================================
describe('Dynamic Validation and Business Logic', () => {
test('should validate SFCC attribute definition constraints', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
}
}
});
const responseData = assertValidAttributeSearchResponse(result);
// Validate SFCC business rules
responseData.hits.forEach(attribute => {
assertValidAttributeDefinition(attribute);
// Key attributes should be mandatory
if (attribute.key) {
assert.equal(attribute.mandatory, true, 'Key attributes should be mandatory');
}
// System attributes should be read-only
if (attribute.system) {
assert.equal(attribute.read_only, true, 'System attributes should be read-only');
}
// Validate effective_id patterns
if (attribute.id !== 'ID' && attribute.id !== 'UUID' && !attribute.system) {
assert.ok(
attribute.effective_id.startsWith('c_'),
`Custom attribute ${attribute.id} should have effective_id starting with c_`
);
}
// Validate value types
const validValueTypes = ['string', 'number', 'boolean', 'datetime', 'date', 'text', 'email', 'password'];
assert.ok(
validValueTypes.includes(attribute.value_type),
`${attribute.value_type} should be a valid SFCC value type`
);
// String attributes with field_length should be reasonable
if (attribute.value_type === 'string' && attribute.field_length) {
assert.ok(
attribute.field_length > 0 && attribute.field_length <= 4000,
'String field length should be reasonable'
);
}
});
});
test('should analyze attribute relationships and dependencies', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
}
}
});
const responseData = assertValidAttributeSearchResponse(result);
// Analyze attribute patterns
const analysis = {
totalAttributes: responseData.hits.length,
systemAttributes: responseData.hits.filter(attr => attr.system).length,
customAttributes: responseData.hits.filter(attr => !attr.system).length,
mandatoryAttributes: responseData.hits.filter(attr => attr.mandatory).length,
queryableAttributes: responseData.hits.filter(attr => attr.queryable).length,
searchableAttributes: responseData.hits.filter(attr => attr.searchable).length,
localizableAttributes: responseData.hits.filter(attr => attr.localizable).length
};
// Validate basic patterns for custom object attributes
assert.ok(analysis.totalAttributes > 0, 'Should have some attributes');
// Log actual attribute names for debugging
const attributeNames = responseData.hits.map(attr => attr.id);
console.log(`Found attributes: ${attributeNames.join(', ')}`);
// Check for common SFCC patterns (flexible validation based on actual mock data)
const hasIdAttribute = responseData.hits.some(attr => attr.id === 'ID' || attr.id.toLowerCase().includes('id'));
const hasDateAttributes = responseData.hits.some(attr => attr.value_type === 'datetime');
if (hasIdAttribute) {
console.log('✓ Found ID-related attributes');
}
if (hasDateAttributes) {
console.log('✓ Found datetime attributes');
}
// System attributes should be a subset of mandatory and queryable (if any exist)
const systemAttrs = responseData.hits.filter(attr => attr.system);
if (systemAttrs.length > 0) {
const mandatorySystemAttrs = systemAttrs.filter(attr => attr.mandatory);
assert.ok(mandatorySystemAttrs.length >= 0, 'System attributes should have consistent mandatory status');
}
console.log('Attribute analysis for VersionHistory:', analysis);
});
test('should validate search query effectiveness', async () => {
// Test different query types and compare effectiveness
const queryTests = [
{
name: 'match_all',
query: { match_all_query: {} }
},
{
name: 'text_search_id',
query: {
text_query: {
fields: ['id'],
search_phrase: 'component'
}
}
},
{
name: 'term_search_string_type',
query: {
term_query: {
fields: ['value_type'],
operator: 'is',
values: ['string']
}
}
}
];
const queryResults = [];
for (const queryTest of queryTests) {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: queryTest.query
}
});
if (!result.isError) {
const responseData = assertValidAttributeSearchResponse(result);
queryResults.push({
name: queryTest.name,
resultCount: responseData.count,
totalCount: responseData.total
});
}
}
assert.ok(queryResults.length > 0, 'Should have successful query results');
// match_all should return the most results
const matchAllResult = queryResults.find(r => r.name === 'match_all');
if (matchAllResult) {
queryResults.forEach(result => {
if (result.name !== 'match_all') {
assert.ok(
result.resultCount <= matchAllResult.resultCount,
`${result.name} should return <= results than match_all`
);
}
});
}
console.log('Query effectiveness results:', queryResults);
});
});
// ============================================================================
// EDGE CASES AND BOUNDARY CONDITIONS
// ============================================================================
describe('Edge Cases and Boundary Conditions', () => {
test('should handle empty search results gracefully', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
text_query: {
fields: ['id'],
search_phrase: 'NonExistentAttributeName'
}
}
}
});
const responseData = assertValidAttributeSearchResponse(result);
// Mock server may not implement proper filtering, so we need flexible validation
console.log(`Search for non-existent attribute returned ${responseData.count} results`);
if (responseData.count === 0) {
// Ideal behavior - search properly filters
assert.equal(responseData.hits.length, 0, 'Hits array should be empty');
assert.equal(responseData.total, 0, 'Total should be 0');
console.log('✓ Mock server properly filters non-existent attributes');
} else {
// Mock server returns all results regardless of filter
console.log('⚠ Mock server does not filter search results - this is acceptable for testing');
assert.ok(responseData.hits.length >= 0, 'Should return valid hits array');
assert.ok(responseData.total >= 0, 'Should return valid total count');
}
});
test('should handle large count parameters appropriately', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
},
count: 1000 // Large count
}
});
const responseData = assertValidAttributeSearchResponse(result);
// Should either return all available attributes or handle large count gracefully
assert.ok(responseData.count <= responseData.total, 'Count should not exceed total');
assert.ok(responseData.hits.length <= 1000, 'Should not return more than requested');
});
test('should handle extreme pagination boundaries', async () => {
// First, get total count
const countResult = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
},
count: 1
}
});
const countData = assertValidAttributeSearchResponse(countResult);
const totalCount = countData.total;
if (totalCount > 1) {
// Test pagination beyond available results
const beyondResult = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
},
start: totalCount + 10,
count: 5
}
});
const beyondData = assertValidAttributeSearchResponse(beyondResult);
assert.equal(beyondData.count, 0, 'Should return 0 results when start > total');
assert.equal(beyondData.hits.length, 0, 'Should have empty hits array');
}
});
test('should handle special characters in object type names', async () => {
// Test with object type that might have special characters (if any exist in mock)
const specialCases = ['Version-History', 'Version_History', 'version history'];
for (const objectType of specialCases) {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: objectType,
searchRequest: {
query: {
match_all_query: {}
}
}
});
// These should typically fail with ObjectTypeNotFoundException
if (result.isError) {
assertSFCCErrorResponse(result, 'ObjectTypeNotFoundException');
}
}
});
test('should validate property selector functionality', async () => {
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
},
select: '(id,value_type,mandatory)' // Limited property selection
}
});
// Note: Property selector might not be fully implemented in mock,
// but should not cause errors
assertValidAttributeSearchResponse(result);
});
});
// ============================================================================
// INTEGRATION AND FUNCTIONAL MONITORING
// ============================================================================
describe('Integration and Functional Monitoring', () => {
test('should maintain response time consistency', async () => {
const responseTimes = [];
const iterations = 3;
for (let i = 0; i < iterations; i++) {
const startTime = Date.now();
const result = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
}
}
});
const endTime = Date.now();
const responseTime = endTime - startTime;
assertValidAttributeSearchResponse(result);
responseTimes.push(responseTime);
}
// Calculate response time statistics (functional monitoring)
const avgResponseTime = responseTimes.reduce((a, b) => a + b, 0) / responseTimes.length;
const maxResponseTime = Math.max(...responseTimes);
const minResponseTime = Math.min(...responseTimes);
console.log(`Response time stats: avg=${avgResponseTime}ms, min=${minResponseTime}ms, max=${maxResponseTime}ms`);
// Functional validation rather than strict performance requirements
assert.ok(avgResponseTime > 0, 'Should have measurable response time');
assert.ok(maxResponseTime < 10000, 'Should complete within reasonable time (10s)');
});
test('should validate complete tool lifecycle', async () => {
// Full lifecycle test: discovery -> parameter validation -> execution -> analysis
// 1. Tool discovery
const tools = await client.listTools();
const targetTool = tools.find(tool => tool.name === 'search_custom_object_attribute_definitions');
assert.ok(targetTool, 'Tool should be discoverable');
// 2. Parameter validation (schema-based)
const schema = targetTool.inputSchema;
assert.ok(schema.properties.objectType, 'Should have objectType parameter');
assert.ok(schema.properties.searchRequest, 'Should have searchRequest parameter');
// 3. Successful execution
const successResult = await client.callTool('search_custom_object_attribute_definitions', {
objectType: 'VersionHistory',
searchRequest: {
query: {
match_all_query: {}
}
}
});
const responseData = assertValidAttributeSearchResponse(successResult);
// 4. Response analysis and validation
assert.ok(responseData.hits.every(attr => attr._type === 'object_attribute_definition'));
assert.ok(responseData.query.match_all_query._type === 'match_all_query');
assert.equal(responseData.start, 0);
assert.ok(responseData.total >= responseData.count);
console.log(`Lifecycle test complete: Found ${responseData.total} attributes for VersionHistory`);
});
});
});
```
--------------------------------------------------------------------------------
/tests/mcp/node/search-best-practices.docs-only.programmatic.test.js:
--------------------------------------------------------------------------------
```javascript
/**
* Programmatic tests for search_best_practices tool
*
* These tests provide advanced verification capabilities beyond YAML pattern matching,
* including dynamic validation, comprehensive content analysis,
* search quality metrics, cross-guide relationship analysis, pattern recognition,
* and comprehensive error categorization for the SFCC best practices search functionality.
*
* Response format discovered via aegis query:
* - Success: { content: [{ type: "text", text: "[{"name":"guide_name","title":"Guide Title","matches":[...]}]" }], isError: false }
* - Empty: { content: [{ type: "text", text: "[]" }], isError: false }
* - Error: { content: [{ type: "text", text: "Error: ..." }], isError: true }
* - Search results include guide metadata, match relevance, and content excerpts
*/
import { test, describe, before, after, beforeEach } from 'node:test';
import { strict as assert } from 'node:assert';
import { connect } from 'mcp-aegis';
/**
* Search results analyzer for comprehensive search quality assessment
*/
class SearchResultsAnalyzer {
constructor() {
this.knownGuides = [
'cartridge_creation', 'isml_templates', 'job_framework', 'localserviceregistry',
'ocapi_hooks', 'scapi_hooks', 'sfra_controllers', 'sfra_models',
'sfra_client_side_js', 'sfra_scss', 'scapi_custom_endpoint', 'performance', 'security'
];
this.searchTermPatterns = {
validation: {
expectedGuides: ['isml_templates', 'ocapi_hooks', 'scapi_hooks', 'sfra_controllers', 'sfra_client_side_js', 'sfra_scss', 'security'],
requiredTerms: ['validation', 'validate', 'check', 'verify'],
contextTerms: ['form', 'input', 'parameter', 'data', 'error']
},
security: {
expectedGuides: ['security', 'ocapi_hooks', 'scapi_hooks', 'sfra_controllers'],
requiredTerms: ['security', 'secure', 'auth', 'encrypt', 'protect'],
contextTerms: ['CSRF', 'XSS', 'authorization', 'authentication', 'cryptography']
},
performance: {
expectedGuides: ['performance', 'sfra_controllers', 'sfra_client_side_js', 'sfra_scss', 'cartridge_creation'],
requiredTerms: ['performance', 'optimize', 'cache', 'memory', 'speed'],
contextTerms: ['monitoring', 'metrics', 'throughput', 'latency', 'scalability']
},
controller: {
expectedGuides: ['sfra_controllers', 'sfra_models'],
requiredTerms: ['controller', 'middleware', 'route', 'endpoint'],
contextTerms: ['server.get', 'server.post', 'append', 'prepend', 'replace']
},
cartridge: {
expectedGuides: ['cartridge_creation'],
requiredTerms: ['cartridge', 'deployment', 'override', 'path'],
contextTerms: ['plugin', 'app_storefront_base', 'upload', 'structure']
}
};
}
analyzeResults(searchQuery, resultsArray) {
return {
searchMeta: this.analyzeSearchMetadata(searchQuery, resultsArray),
relevanceScoring: this.calculateRelevanceScores(searchQuery, resultsArray),
contentQuality: this.assessContentQuality(resultsArray),
crossGuideAnalysis: this.analyzeCrossGuideRelationships(resultsArray),
comprehensiveness: this.assessComprehensiveness(searchQuery, resultsArray),
searchEffectiveness: this.calculateSearchEffectiveness(searchQuery, resultsArray)
};
}
analyzeSearchMetadata(searchQuery, resultsArray) {
const uniqueGuides = new Set(resultsArray.map(result => result.guide));
const totalMatches = resultsArray.reduce((sum, result) => sum + result.matches.length, 0);
return {
query: searchQuery,
resultCount: resultsArray.length,
uniqueGuides: uniqueGuides.size,
guidesFound: Array.from(uniqueGuides),
totalMatches,
avgMatchesPerGuide: resultsArray.length > 0 ? totalMatches / resultsArray.length : 0,
searchCoverage: (uniqueGuides.size / this.knownGuides.length) * 100
};
}
calculateRelevanceScores(searchQuery, resultsArray) {
const scores = resultsArray.map(result => {
const titleRelevance = this.calculateTextRelevance(searchQuery, result.title);
const contentRelevance = result.matches.map(match =>
this.calculateTextRelevance(searchQuery, match.content)
);
const avgContentRelevance = contentRelevance.length > 0 ?
contentRelevance.reduce((a, b) => a + b, 0) / contentRelevance.length : 0;
return {
guide: result.guide,
titleRelevance,
avgContentRelevance,
overallScore: (titleRelevance * 0.3) + (avgContentRelevance * 0.7),
matchCount: result.matches.length
};
});
return {
individualScores: scores,
avgRelevanceScore: scores.length > 0 ?
scores.reduce((sum, score) => sum + score.overallScore, 0) / scores.length : 0,
mostRelevant: scores.reduce((best, current) =>
current.overallScore > best.overallScore ? current : best, scores[0] || {}),
relevanceDistribution: this.categorizeRelevanceScores(scores)
};
}
calculateTextRelevance(query, text) {
const queryTerms = query.toLowerCase().split(/\s+/);
const textLower = text.toLowerCase();
let score = 0;
queryTerms.forEach(term => {
if (textLower.includes(term)) {
// Exact match
score += 1;
// Bonus for word boundaries
if (new RegExp(`\\b${term}\\b`).test(textLower)) {
score += 0.5;
}
}
});
return score / queryTerms.length;
}
categorizeRelevanceScores(scores) {
const categories = { high: 0, medium: 0, low: 0 };
scores.forEach(score => {
if (score.overallScore >= 0.7) categories.high++;
else if (score.overallScore >= 0.3) categories.medium++;
else categories.low++;
});
return categories;
}
assessContentQuality(resultsArray) {
const qualityMetrics = resultsArray.map(result => {
const matches = result.matches;
const avgContentLength = matches.reduce((sum, match) =>
sum + match.content.length, 0) / Math.max(matches.length, 1);
const hasCodeExamples = matches.some(match =>
/```|`[^`]+`/.test(match.content));
const hasStructuredContent = matches.some(match =>
/#{1,6}\s|\*\*|-\s|\d+\.\s/.test(match.content));
const hasTechnicalTerms = matches.some(match =>
/dw\.|SFRA|OCAPI|SCAPI|server\.|middleware/.test(match.content));
return {
guide: result.guide,
avgContentLength,
hasCodeExamples,
hasStructuredContent,
hasTechnicalTerms,
matchQualityScore: this.calculateMatchQualityScore(matches)
};
});
return {
individualQuality: qualityMetrics,
avgContentLength: qualityMetrics.reduce((sum, q) => sum + q.avgContentLength, 0) / Math.max(qualityMetrics.length, 1),
guidesWithCode: qualityMetrics.filter(q => q.hasCodeExamples).length,
guidesWithStructure: qualityMetrics.filter(q => q.hasStructuredContent).length,
technicalAccuracy: qualityMetrics.filter(q => q.hasTechnicalTerms).length / Math.max(qualityMetrics.length, 1)
};
}
calculateMatchQualityScore(matches) {
let score = 0;
matches.forEach(match => {
if (match.content.length > 100) score += 1; // Substantial content
if (/```[\s\S]*?```/.test(match.content)) score += 2; // Code blocks
if (/#{1,6}\s/.test(match.content)) score += 1; // Headers
if (/\*\*[^*]+\*\*/.test(match.content)) score += 0.5; // Bold text
if (/`[^`]+`/.test(match.content)) score += 0.5; // Inline code
});
return score / Math.max(matches.length, 1);
}
analyzeCrossGuideRelationships(resultsArray) {
const sharedTopics = new Map();
resultsArray.forEach(result => {
const guide = result.guide;
result.matches.forEach(match => {
// Extract technical terms and concepts
const terms = this.extractTechnicalTerms(match.content);
terms.forEach(term => {
if (!sharedTopics.has(term)) {
sharedTopics.set(term, new Set());
}
sharedTopics.get(term).add(guide);
});
});
});
// Find interconnected guides
const interconnections = [];
for (const [topic, guides] of sharedTopics.entries()) {
if (guides.size > 1) {
interconnections.push({
topic,
guides: Array.from(guides),
connectionStrength: guides.size
});
}
}
return {
totalSharedTopics: sharedTopics.size,
interconnections: interconnections.sort((a, b) => b.connectionStrength - a.connectionStrength),
mostConnectedTopic: interconnections[0] || null,
guideConnectivity: this.calculateGuideConnectivity(interconnections)
};
}
extractTechnicalTerms(content) {
const terms = new Set();
// SFCC API patterns
const apiMatches = content.match(/dw\.\w+(\.\w+)*/g) || [];
apiMatches.forEach(match => terms.add(match));
// SFRA patterns
const sfraMatches = content.match(/server\.\w+|middleware|controller|model/gi) || [];
sfraMatches.forEach(match => terms.add(match.toLowerCase()));
// Technical concepts
const concepts = ['validation', 'authentication', 'authorization', 'encryption', 'caching', 'transaction', 'middleware', 'hook', 'endpoint'];
concepts.forEach(concept => {
if (new RegExp(concept, 'i').test(content)) {
terms.add(concept);
}
});
return Array.from(terms);
}
calculateGuideConnectivity(interconnections) {
const guideConnections = new Map();
interconnections.forEach(connection => {
connection.guides.forEach(guide => {
if (!guideConnections.has(guide)) {
guideConnections.set(guide, 0);
}
guideConnections.set(guide, guideConnections.get(guide) + connection.connectionStrength);
});
});
return Array.from(guideConnections.entries())
.map(([guide, connectivity]) => ({ guide, connectivity }))
.sort((a, b) => b.connectivity - a.connectivity);
}
assessComprehensiveness(searchQuery, resultsArray) {
const pattern = this.searchTermPatterns[searchQuery.toLowerCase()];
if (!pattern) {
return { patternRecognized: false, customAnalysis: this.performCustomComprehensiveness(searchQuery, resultsArray) };
}
const foundGuides = new Set(resultsArray.map(r => r.guide));
const expectedGuides = new Set(pattern.expectedGuides);
const missingGuides = pattern.expectedGuides.filter(guide => !foundGuides.has(guide));
const unexpectedGuides = resultsArray.filter(r => !expectedGuides.has(r.guide)).map(r => r.guide);
const termCoverage = this.assessTermCoverage(pattern, resultsArray);
return {
patternRecognized: true,
expectedGuides: pattern.expectedGuides,
foundGuides: Array.from(foundGuides),
missingGuides,
unexpectedGuides,
guideCoverage: (foundGuides.size - unexpectedGuides.length) / Math.max(expectedGuides.size, 1),
termCoverage,
comprehensivenessScore: this.calculateComprehensiveness(foundGuides, expectedGuides, termCoverage)
};
}
performCustomComprehensiveness(searchQuery, resultsArray) {
return {
message: `No predefined pattern for query: ${searchQuery}`,
resultCount: resultsArray.length,
uniqueGuides: new Set(resultsArray.map(r => r.guide)).size,
avgMatchesPerGuide: resultsArray.reduce((sum, r) => sum + r.matches.length, 0) / Math.max(resultsArray.length, 1)
};
}
assessTermCoverage(pattern, resultsArray) {
const allContent = resultsArray.flatMap(r => r.matches.map(m => m.content)).join(' ').toLowerCase();
const requiredTermsFound = pattern.requiredTerms.filter(term => allContent.includes(term));
const contextTermsFound = pattern.contextTerms.filter(term => allContent.includes(term));
return {
requiredTerms: pattern.requiredTerms.length,
requiredTermsFound: requiredTermsFound.length,
requiredTermsCoverage: requiredTermsFound.length / Math.max(pattern.requiredTerms.length, 1),
contextTerms: pattern.contextTerms.length,
contextTermsFound: contextTermsFound.length,
contextTermsCoverage: contextTermsFound.length / Math.max(pattern.contextTerms.length, 1),
foundTerms: { required: requiredTermsFound, context: contextTermsFound }
};
}
calculateComprehensiveness(foundGuides, expectedGuides, termCoverage) {
const guideCoverage = foundGuides.size / Math.max(expectedGuides.size, 1);
const termScore = (termCoverage.requiredTermsCoverage * 0.7) + (termCoverage.contextTermsCoverage * 0.3);
return (guideCoverage * 0.6) + (termScore * 0.4);
}
calculateSearchEffectiveness(searchQuery, resultsArray) {
let totalMatches = 0;
let relevantMatches = 0;
resultsArray.forEach(result => {
result.matches.forEach(match => {
totalMatches++;
const matchRelevance = this.calculateTextRelevance(searchQuery, match.content);
if (matchRelevance > 0.3) relevantMatches++;
});
});
const precision = totalMatches > 0 ? relevantMatches / totalMatches : 0;
const diversityScore = new Set(resultsArray.map(r => r.guide)).size / Math.max(resultsArray.length, 1);
return {
totalMatches,
relevantMatches,
precision,
diversityScore,
effectivenessScore: (precision * 0.7) + (diversityScore * 0.3),
searchQuality: this.categorizeSearchQuality(precision, diversityScore)
};
}
categorizeSearchQuality(precision, diversityScore) {
const overallScore = (precision * 0.7) + (diversityScore * 0.3);
if (overallScore >= 0.8) return 'excellent';
if (overallScore >= 0.6) return 'good';
if (overallScore >= 0.4) return 'fair';
return 'poor';
}
}
/**
* Query analyzer for intelligent query pattern recognition and optimization
*/
class QueryAnalyzer {
constructor() {
this.queryPatterns = {
technical: /\b(dw\.|server\.|middleware|controller|model|API|endpoint|hook)\b/i,
security: /\b(security|auth|encrypt|CSRF|XSS|validation|sanitiz)\b/i,
performance: /\b(performance|optimize|cache|memory|speed|monitoring)\b/i,
framework: /\b(SFRA|OCAPI|SCAPI|cartridge|ISML|template|SCSS|SASS)\b/i,
development: /\b(development|coding|implementation|best practice|guideline)\b/i
};
this.commonTerms = [
'validation', 'security', 'performance', 'controller', 'middleware',
'cartridge', 'template', 'hook', 'API', 'authentication', 'authorization',
'encryption', 'caching', 'transaction', 'error', 'configuration',
'scss', 'styling'
];
}
analyzeQuery(query) {
return {
originalQuery: query,
queryLength: query.length,
wordCount: query.split(/\s+/).length,
patterns: this.identifyPatterns(query),
complexity: this.assessComplexity(query),
suggestions: this.generateQuerySuggestions(query),
expectedResultTypes: this.predictResultTypes(query)
};
}
identifyPatterns(query) {
const patterns = {};
for (const [patternName, regex] of Object.entries(this.queryPatterns)) {
patterns[patternName] = regex.test(query);
}
return patterns;
}
assessComplexity(query) {
const words = query.split(/\s+/);
let complexityScore = 0;
if (words.length === 1) complexityScore = 1; // Simple
else if (words.length <= 3) complexityScore = 2; // Moderate
else complexityScore = 3; // Complex
// Adjust for technical terms
if (this.queryPatterns.technical.test(query)) complexityScore += 1;
return {
score: Math.min(complexityScore, 4),
category: this.categorizeComplexity(complexityScore),
factors: this.identifyComplexityFactors(query)
};
}
categorizeComplexity(score) {
if (score <= 1) return 'simple';
if (score <= 2) return 'moderate';
if (score <= 3) return 'complex';
return 'very_complex';
}
identifyComplexityFactors(query) {
const factors = [];
if (query.split(/\s+/).length > 3) factors.push('multiple_terms');
if (this.queryPatterns.technical.test(query)) factors.push('technical_terminology');
if (query.includes('"')) factors.push('quoted_phrases');
if (query.includes('AND') || query.includes('OR')) factors.push('boolean_operators');
return factors;
}
generateQuerySuggestions(query) {
const suggestions = [];
const queryLower = query.toLowerCase();
// Find related terms
this.commonTerms.forEach(term => {
if (queryLower.includes(term.toLowerCase().substring(0, 3)) && !queryLower.includes(term.toLowerCase())) {
suggestions.push(`Try searching for: "${term}"`);
}
});
// Pattern-based suggestions
if (this.queryPatterns.security.test(query)) {
suggestions.push('Consider also searching: "authentication", "authorization", "CSRF"');
}
if (this.queryPatterns.performance.test(query)) {
suggestions.push('Consider also searching: "caching", "optimization", "monitoring"');
}
return suggestions;
}
predictResultTypes(query) {
const predictions = [];
if (this.queryPatterns.security.test(query)) {
predictions.push({ type: 'security_guides', confidence: 0.9 });
}
if (this.queryPatterns.performance.test(query)) {
predictions.push({ type: 'performance_guides', confidence: 0.8 });
}
if (this.queryPatterns.framework.test(query)) {
predictions.push({ type: 'framework_documentation', confidence: 0.85 });
}
if (this.queryPatterns.development.test(query)) {
predictions.push({ type: 'development_practices', confidence: 0.7 });
}
return predictions.sort((a, b) => b.confidence - a.confidence);
}
}
/**
* Error categorization utility for comprehensive error analysis
*/
class ErrorAnalyzer {
static categorizeError(errorText) {
const patterns = [
{ type: 'validation', keywords: ['required', 'invalid', 'missing', 'empty string', 'non-empty'] },
{ type: 'not_found', keywords: ['not found', 'does not exist', 'null'] },
{ type: 'permission', keywords: ['permission', 'unauthorized', 'forbidden'] },
{ type: 'network', keywords: ['connection', 'timeout', 'unreachable'] },
{ type: 'format', keywords: ['format', 'parse', 'json', 'syntax'] }
];
const errorLower = errorText.toLowerCase();
for (const pattern of patterns) {
if (pattern.keywords.some(keyword => errorLower.includes(keyword))) {
return pattern.type;
}
}
return 'unknown';
}
static assessErrorQuality(errorText) {
const hasSpecificMessage = !errorText.includes('generic error');
const hasSuggestion = errorText.includes('should') || errorText.includes('try') || errorText.includes('use');
const isActionable = errorText.includes('required') || errorText.includes('must') || errorText.includes('invalid');
return {
category: this.categorizeError(errorText),
isInformative: hasSpecificMessage && errorText.length > 20,
isActionable,
hasSuggestion,
qualityScore: [hasSpecificMessage, isActionable, hasSuggestion].filter(Boolean).length / 3
};
}
}
// Assertion helpers for comprehensive validation
function assertValidMCPResponse(result, expectError = false) {
assert.ok(result.content, 'Should have content');
assert.ok(Array.isArray(result.content), 'Content should be array');
assert.equal(typeof result.isError, 'boolean', 'isError should be boolean');
assert.equal(result.isError, expectError, `isError should be ${expectError}`);
}
function assertSearchResults(result) {
assertValidMCPResponse(result, false);
assert.equal(result.content[0].type, 'text');
const responseText = result.content[0].text;
assert.ok(responseText.startsWith('['), 'Response should be JSON array');
assert.ok(responseText.endsWith(']'), 'Response should end with ]');
const resultsArray = JSON.parse(responseText);
assert.ok(Array.isArray(resultsArray), 'Parsed response should be array');
// Validate result structure if not empty
if (resultsArray.length > 0) {
resultsArray.forEach(result => {
assert.ok(result.guide, 'Each result should have guide');
assert.ok(result.title, 'Each result should have title');
assert.ok(Array.isArray(result.matches), 'Each result should have matches array');
result.matches.forEach(match => {
assert.ok(match.section, 'Each match should have section');
assert.ok(match.content, 'Each match should have content');
});
});
}
return resultsArray;
}
function assertErrorResponse(result, expectedErrorType) {
assertValidMCPResponse(result, true);
assert.equal(result.content[0].type, 'text');
const errorText = result.content[0].text;
assert.ok(errorText.includes('Error:'), 'Should be error message');
const errorAnalysis = ErrorAnalyzer.assessErrorQuality(errorText);
assert.ok(errorAnalysis.isInformative, 'Error should be informative');
if (expectedErrorType) {
assert.equal(errorAnalysis.category, expectedErrorType,
`Error should be categorized as ${expectedErrorType}`);
}
return errorAnalysis;
}
describe('search_best_practices Tool - Advanced Programmatic Tests', () => {
let client;
let searchAnalyzer;
let queryAnalyzer;
before(async () => {
client = await connect('./aegis.config.docs-only.json');
searchAnalyzer = new SearchResultsAnalyzer();
queryAnalyzer = new QueryAnalyzer();
});
after(async () => {
if (client?.connected) {
await client.disconnect();
}
});
beforeEach(() => {
// CRITICAL: Clear all buffers to prevent leaking between tests
client.clearAllBuffers(); // Recommended - comprehensive protection
});
describe('Basic Search Functionality', () => {
test('should handle common search terms with comprehensive analysis', async () => {
const searchTerms = ['validation', 'security', 'performance', 'controller', 'middleware', 'scss'];
for (const term of searchTerms) {
const result = await client.callTool('search_best_practices', { query: term });
const resultsArray = assertSearchResults(result);
const searchAnalysis = searchAnalyzer.analyzeResults(term, resultsArray);
// Basic validation
assert.ok(resultsArray.length > 0, `Should find results for ${term}`);
// More lenient analysis - allow for varied content quality
if (resultsArray.length > 0) {
assert.ok(searchAnalysis.relevanceScoring.avgRelevanceScore >= 0,
`Results for ${term} should have valid relevance score (score: ${searchAnalysis.relevanceScoring.avgRelevanceScore})`);
// Some technical terms may not always be present in general searches
}
}
});
test('should surface SFRA SCSS guide for styling queries', async () => {
const result = await client.callTool('search_best_practices', { query: 'scss' });
const resultsArray = assertSearchResults(result);
assert.ok(resultsArray.some(r => r.guide === 'sfra_scss'), 'Should include sfra_scss guide in results');
const sfraScssGuide = resultsArray.find(r => r.guide === 'sfra_scss');
assert.ok(sfraScssGuide?.matches?.length > 0, 'SFRA SCSS guide should provide match excerpts');
const analysis = searchAnalyzer.analyzeResults('scss', resultsArray);
assert.ok(analysis.searchMeta.guidesFound.includes('sfra_scss'), 'Search metadata should track sfra_scss guide');
});
test('should demonstrate search result quality with detailed metrics', async () => {
const testQuery = 'validation';
const result = await client.callTool('search_best_practices', { query: testQuery });
const resultsArray = assertSearchResults(result);
const analysis = searchAnalyzer.analyzeResults(testQuery, resultsArray);
// Comprehensive quality assertions
assert.ok(analysis.contentQuality.avgContentLength > 50, 'Content should be substantial');
assert.ok(analysis.contentQuality.guidesWithCode > 0, 'Should include code examples');
assert.ok(analysis.relevanceScoring.relevanceDistribution.high > 0, 'Should have highly relevant results');
assert.ok(analysis.searchEffectiveness.precision > 0.4, 'Search precision should be reasonable');
// Cross-guide analysis
if (analysis.crossGuideAnalysis.interconnections.length > 0) {
assert.ok(analysis.crossGuideAnalysis.mostConnectedTopic, 'Should identify connected topics');
}
// Comprehensiveness assessment
if (analysis.comprehensiveness.patternRecognized) {
assert.ok(analysis.comprehensiveness.guideCoverage >= 0, 'Guide coverage should be measurable');
}
});
});
describe('Advanced Search Pattern Recognition', () => {
test('should recognize and analyze technical search patterns', async () => {
const technicalQueries = [
{ query: 'dw.crypto', expectedPattern: 'technical' },
{ query: 'server.middleware', expectedPattern: 'framework' },
{ query: 'OCAPI hooks', expectedPattern: 'framework' },
{ query: 'authentication security', expectedPattern: 'security' }
];
for (const { query, expectedPattern } of technicalQueries) {
const queryAnalysis = queryAnalyzer.analyzeQuery(query);
const result = await client.callTool('search_best_practices', { query });
const resultsArray = assertSearchResults(result);
const searchAnalysis = searchAnalyzer.analyzeResults(query, resultsArray);
// Pattern recognition validation - more flexible matching
const hasExpectedPattern = queryAnalysis.patterns[expectedPattern];
// Allow for pattern flexibility - if expected pattern isn't found, check if any technical pattern is found
const hasTechnicalPattern = Object.keys(queryAnalysis.patterns).some(p => queryAnalysis.patterns[p] &&
['technical', 'framework', 'security', 'performance'].includes(p));
assert.ok(hasExpectedPattern || hasTechnicalPattern,
`Query "${query}" should match ${expectedPattern} pattern or another technical pattern`);
// Result quality for technical queries - more lenient validation
if (resultsArray.length > 0) {
// Technical queries may or may not return technical content depending on the search algorithm
assert.ok(searchAnalysis.relevanceScoring.avgRelevanceScore >= 0,
`Technical query "${query}" should have valid relevance score`);
}
}
});
test('should provide intelligent query suggestions and predictions', async () => {
const ambiguousQueries = ['auth', 'perf', 'valid'];
for (const query of ambiguousQueries) {
const queryAnalysis = queryAnalyzer.analyzeQuery(query);
assert.ok(queryAnalysis.suggestions.length >= 0, 'Should provide suggestions for ambiguous queries');
assert.ok(queryAnalysis.expectedResultTypes.length >= 0, 'Should predict result types');
if (queryAnalysis.suggestions.length > 0) {
assert.ok(queryAnalysis.suggestions.every(s => typeof s === 'string'), 'Suggestions should be strings');
}
if (queryAnalysis.expectedResultTypes.length > 0) {
const topPrediction = queryAnalysis.expectedResultTypes[0];
assert.ok(topPrediction.type, 'Top prediction should have type');
assert.ok(topPrediction.confidence >= 0, 'Top prediction should have valid confidence');
}
}
});
});
describe('Cross-Guide Relationship Analysis', () => {
test('should identify relationships between different guides', async () => {
const result = await client.callTool('search_best_practices', { query: 'validation' });
const resultsArray = assertSearchResults(result);
const analysis = searchAnalyzer.analyzeResults('validation', resultsArray);
if (analysis.crossGuideAnalysis.interconnections.length > 0) {
const interconnections = analysis.crossGuideAnalysis.interconnections;
// Should identify shared concepts
assert.ok(interconnections.length > 0, 'Should find interconnected topics');
// Analyze connection strength
const strongConnections = interconnections.filter(conn => conn.connectionStrength >= 3);
if (strongConnections.length > 0) {
assert.ok(strongConnections.every(conn => conn.topic && conn.guides.length > 0),
'Strong connections should have valid structure');
}
// Guide connectivity analysis
const connectivity = analysis.crossGuideAnalysis.guideConnectivity;
if (connectivity.length > 0) {
const mostConnected = connectivity[0];
assert.ok(mostConnected.guide && mostConnected.connectivity >= 0,
'Most connected guide should have valid structure');
}
}
});
test('should analyze search comprehensiveness for known patterns', async () => {
const knownPatterns = ['validation', 'security', 'performance'];
for (const pattern of knownPatterns) {
const result = await client.callTool('search_best_practices', { query: pattern });
const resultsArray = assertSearchResults(result);
const analysis = searchAnalyzer.analyzeResults(pattern, resultsArray);
if (analysis.comprehensiveness.patternRecognized) {
const comp = analysis.comprehensiveness;
assert.ok(Array.isArray(comp.expectedGuides), 'Should have expected guides');
assert.ok(Array.isArray(comp.foundGuides), 'Should have found guides');
// Analyze coverage
if (comp.missingGuides.length > 0) {
assert.ok(comp.missingGuides.every(g => typeof g === 'string'), 'Missing guides should be strings');
}
if (comp.unexpectedGuides.length > 0) {
assert.ok(comp.unexpectedGuides.every(g => typeof g === 'string'), 'Unexpected guides should be strings');
}
assert.ok(comp.guideCoverage >= 0, 'Guide coverage should be calculable');
}
}
});
});
describe('Error Handling and Edge Cases', () => {
test('should handle various error conditions gracefully', async () => {
const errorTestCases = [
{ query: '', expectedError: 'validation', description: 'empty query' },
{ query: ' ', expectedError: 'validation', description: 'whitespace only' },
{ query: 'zzznomatchesexpected', expectedError: null, description: 'no matches' }
];
for (const { query, expectedError, description } of errorTestCases) {
const result = await client.callTool('search_best_practices', { query });
if (expectedError) {
const errorAnalysis = assertErrorResponse(result, expectedError);
assert.ok(errorAnalysis.isInformative, `Error for ${description} should be informative`);
assert.ok(errorAnalysis.qualityScore > 0.5, `Error quality for ${description} should be good`);
} else {
// No matches case
assertValidMCPResponse(result, false);
const responseText = result.content[0].text;
const resultsArray = JSON.parse(responseText);
assert.equal(resultsArray.length, 0, `${description} should return empty array`);
}
}
});
test('should handle missing parameters with detailed error analysis', async () => {
try {
const result = await client.callTool('search_best_practices', {});
const errorAnalysis = assertErrorResponse(result, 'validation');
assert.ok(errorAnalysis.isActionable, 'Missing parameter error should be actionable');
assert.ok(errorAnalysis.category === 'validation', 'Should be categorized as validation error');
} catch (error) {
// Some implementations might throw instead of returning error result
assert.ok(error.message.includes('required') || error.message.includes('query'),
'Error should mention required query parameter');
}
});
});
describe('Search Effectiveness and Quality Metrics', () => {
test('should demonstrate high-quality search capabilities', async () => {
const qualityTestQueries = [
'validation patterns',
'security best practices',
'performance optimization',
'SFRA controller architecture',
'SFRA SCSS best practices'
];
for (const query of qualityTestQueries) {
const result = await client.callTool('search_best_practices', { query });
const resultsArray = assertSearchResults(result);
const analysis = searchAnalyzer.analyzeResults(query, resultsArray);
if (resultsArray.length > 0) {
// Quality assertions
assert.ok(analysis.searchEffectiveness.precision > 0.3,
`Search precision for "${query}" should be reasonable`);
assert.ok(analysis.contentQuality.technicalAccuracy > 0.3,
`Technical accuracy for "${query}" should be good`);
// Effectiveness categorization
const effectiveness = analysis.searchEffectiveness.searchQuality;
assert.ok(['poor', 'fair', 'good', 'excellent'].includes(effectiveness),
'Search quality should be categorized');
assert.ok(analysis.searchEffectiveness.precision >= 0 && analysis.searchEffectiveness.precision <= 1,
'Search precision should be between 0 and 1');
}
}
});
});
});
```
--------------------------------------------------------------------------------
/docs-site/pages/TroubleshootingPage.tsx:
--------------------------------------------------------------------------------
```typescript
import React from 'react';
import { NavLink } from 'react-router-dom';
import SEO from '../components/SEO';
import BreadcrumbSchema from '../components/BreadcrumbSchema';
import StructuredData from '../components/StructuredData';
import CodeBlock, { InlineCode } from '../components/CodeBlock';
import { H1, PageSubtitle, H2, H3 } from '../components/Typography';
import Collapsible from '../components/Collapsible';
import Badge from '../components/Badge';
import { SITE_DATES } from '../constants';
const TroubleshootingPage: React.FC = () => {
const troubleshootingStructuredData = {
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Troubleshooting & Debugging - SFCC Development MCP Server",
"description": "Common issues and solutions for the SFCC Development MCP Server. Includes authentication problems, network connectivity, AI interface integration, and debugging tips.",
"author": {
"@type": "Person",
"name": "Thomas Theunen"
},
"publisher": {
"@type": "Person",
"name": "Thomas Theunen"
},
"datePublished": SITE_DATES.PUBLISHED,
"dateModified": SITE_DATES.MODIFIED,
"url": "https://sfcc-mcp-dev.rhino-inquisitor.com/troubleshooting/",
"mainEntity": {
"@type": "Guide",
"name": "SFCC MCP Troubleshooting Guide"
}
};
return (
<div className="max-w-6xl mx-auto px-6 py-12">
<SEO
title="Troubleshooting & Debugging"
description="Common issues and solutions for the SFCC Development MCP Server. Includes authentication problems, network connectivity, AI interface integration, and debugging tips."
keywords="SFCC troubleshooting, Commerce Cloud debugging, MCP server issues, SFCC authentication problems, OCAPI troubleshooting, WebDAV issues"
canonical="/troubleshooting/"
ogType="article"
/>
<BreadcrumbSchema items={[
{ name: "Home", url: "/" },
{ name: "Troubleshooting", url: "/troubleshooting/" }
]} />
<StructuredData data={troubleshootingStructuredData} />
<H1 id="troubleshooting">🐛 Troubleshooting & Debugging</H1>
<PageSubtitle>Quick solutions to get you back to developing SFCC features with AI assistance.</PageSubtitle>
<p className="mt-2 text-[11px] uppercase tracking-wide text-gray-400">Surface: <strong>36+ specialized tools</strong> (docs, best practices, SFRA, cartridge gen, runtime logs, job logs, system & custom objects, site preferences, code versions)</p>
{/* Quick Diagnostics Checklist */}
<div className="bg-gradient-to-r from-blue-50 to-indigo-50 border border-blue-200 rounded-xl p-6 mb-8">
<h2 className="text-lg font-bold text-blue-900 mb-4 flex items-center">
⚡ Quick Diagnostics Checklist
</h2>
<div className="grid md:grid-cols-2 gap-4">
<div>
<h3 className="font-semibold text-blue-800 mb-2">Basic Checks</h3>
<ul className="space-y-1 text-sm">
<li className="flex items-center"><span className="text-green-500 mr-2">✓</span> Node.js 18+ installed</li>
<li className="flex items-center"><span className="text-green-500 mr-2">✓</span> Package installed via npm</li>
<li className="flex items-center"><span className="text-green-500 mr-2">✓</span> Valid dw.json file (600 permissions)</li>
<li className="flex items-center"><span className="text-green-500 mr-2">✓</span> SFCC instance is active</li>
</ul>
</div>
<div>
<h3 className="font-semibold text-blue-800 mb-2">Quick Test</h3>
<CodeBlock language="bash" code="npx -y sfcc-dev-mcp --debug" />
<p className="text-xs text-blue-700 mt-1">Should start without errors. (<code>-y</code> skips the npx install confirmation so AI clients/scripts don't hang.)</p>
</div>
</div>
</div>
<H2 id="startup-issues">🚀 Startup & Connectivity Issues</H2>
<Collapsible title="Server Won't Start" intent="danger" id="server-wont-start" className="mb-6">
<div className="space-y-4">
<div>
<div className="flex items-baseline gap-2 mb-3">
<Badge variant="error" size="sm" className="mt-1">Common</Badge>
<h4 className="font-semibold">Node.js Version Mismatch</h4>
</div>
<CodeBlock language="bash" code={`# Check version (requires 18+)
node --version
# Update if needed
nvm install 18 && nvm use 18`} />
<div className="bg-orange-50 border-l-4 border-orange-400 p-4 mt-4">
<h5 className="font-semibold text-orange-800 mb-2">Working with Older SFRA/SiteGenesis Projects</h5>
<p className="text-sm text-orange-700 mb-3">
When working with older SFRA or SiteGenesis projects that require Node.js 8, 12, or 16,
you need to set a higher Node.js version as the <strong>default</strong> for MCP to work.
Simply switching via <InlineCode>nvm use</InlineCode> is not sufficient.
</p>
<CodeBlock language="bash" code={`# Set Node 24 as default for MCP compatibility
nvm alias default 24
# For project work, switch to older version as needed
nvm use 12.22.6
# Verify MCP still works with npx
npx -y sfcc-dev-mcp --version`} />
<p className="text-xs text-orange-600 mt-2">
<strong>Why this works:</strong> npx uses the default Node version for global packages,
while your terminal session can use a different version for project compilation.
</p>
</div>
</div>
<div>
<div className="flex items-baseline gap-2 mb-3">
<Badge variant="warning" size="sm" className="mt-1">Frequent</Badge>
<h4 className="font-semibold">File Permission Issues</h4>
</div>
<CodeBlock language="bash" code={`# Fix dw.json permissions
chmod 600 dw.json
# Verify permissions
ls -la dw.json
# Should show: -rw------- (600)`} />
</div>
<div>
<div className="flex items-baseline gap-2 mb-3">
<Badge variant="info" size="sm" className="mt-1">Setup</Badge>
<h4 className="font-semibold">Package Installation</h4>
</div>
<CodeBlock language="bash" code={`# Global installation
npm install -g sfcc-dev-mcp
# Or use npx (recommended)
npx -y sfcc-dev-mcp --version`} />
</div>
</div>
</Collapsible>
<Collapsible title="AI Interface Not Connecting" intent="warn" id="ai-not-connecting" className="mb-6">
<div className="space-y-4">
<div>
<h4 className="font-semibold mb-2">Claude Desktop Configuration</h4>
<div className="bg-gray-50 rounded-lg p-4 mb-4">
<h5 className="font-medium mb-2">Config File Locations:</h5>
<ul className="text-sm space-y-1">
<li><strong>macOS:</strong> <InlineCode>~/Library/Application Support/Claude/</InlineCode></li>
<li><strong>Windows:</strong> <InlineCode>%APPDATA%\Claude\</InlineCode></li>
<li><strong>Linux:</strong> <InlineCode>~/.config/Claude/</InlineCode></li>
</ul>
</div>
<CodeBlock language="json" code={`{
"mcpServers": {
"sfcc-dev": {
"command": "npx",
"args": ["sfcc-dev-mcp", "--dw-json", "/absolute/path/to/dw.json"]
}
}
}`} />
<div className="mt-3">
<h5 className="font-medium mb-1">Validation Commands:</h5>
<CodeBlock language="bash" code={`# Validate JSON syntax
python -m json.tool claude_desktop_config.json
# Test server manually
npx -y sfcc-dev-mcp --debug`} />
</div>
</div>
</div>
</Collapsible>
<H2 id="authentication-issues">🔐 Authentication & Credentials</H2>
<Collapsible title="SFCC Authentication Failures" intent="danger" id="sfcc-auth-failures" className="mb-6">
<div className="space-y-4">
<div className="grid md:grid-cols-2 gap-4">
<div>
<h4 className="font-semibold text-red-700 mb-2">Common Symptoms</h4>
<ul className="text-sm space-y-1">
<li>401 Unauthorized errors</li>
<li>System object tools failing</li>
<li>Log analysis not working</li>
<li>"OAuth authentication failed"</li>
</ul>
</div>
<div>
<h4 className="font-semibold text-green-700 mb-2">Quick Test</h4>
<CodeBlock language="bash" code={`# Test connectivity
curl -I https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com`} />
</div>
</div>
<div className="bg-yellow-50 border-l-4 border-yellow-400 p-4">
<h4 className="font-semibold text-yellow-800 mb-2">Update dw.json Credentials</h4>
<CodeBlock language="json" code={`{
"hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
"username": "current-username",
"password": "current-password",
"client-id": "current-client-id",
"client-secret": "current-client-secret",
"site-id": "SiteGenesis",
"code-version": "version1"
}`} />
</div>
<div className="bg-blue-50 border-l-4 border-blue-400 p-4">
<h4 className="font-semibold text-blue-800 mb-2">Business Manager Permissions</h4>
<ol className="text-sm space-y-1">
<li>1. Login to Business Manager</li>
<li>2. Administration → Organization → Users</li>
<li>3. Verify "Administrator" or "Developer" role</li>
<li>4. Check OCAPI Settings in Site Development</li>
</ol>
</div>
<div className="bg-green-50 border-l-4 border-green-400 p-4">
<h4 className="font-semibold text-green-800 mb-2">Regenerate API Credentials</h4>
<p className="text-sm mb-2">Go to Account Manager → API Client → Create new client</p>
<CodeBlock language="bash" code={`# Test new credentials
curl -X POST \\
https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/dw/oauth2/access_token \\
-H "Content-Type: application/x-www-form-urlencoded" \\
-d "grant_type=client_credentials&client_id=NEW_ID&client_secret=NEW_SECRET"`} />
</div>
</div>
</Collapsible>
<H2 id="tool-issues">📊 Tool-Specific Issues</H2>
<Collapsible title="Log Analysis Tools Not Working" intent="warn" id="log-tools-failing" className="mb-6">
<div className="space-y-4">
<div>
<div className="flex items-baseline gap-2 mb-3">
<Badge variant="error" size="sm" className="mt-1">Common</Badge>
<h4 className="font-semibold">"No logs found" Error</h4>
</div>
<p className="text-sm text-gray-600 mb-2">Usually caused by WebDAV access issues</p>
<CodeBlock language="bash" code={`# Test WebDAV access
curl -u "username:password" \\
https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.servlet/webdav/Sites/Logs/`} />
</div>
<div>
<div className="flex items-baseline gap-2 mb-3">
<Badge variant="warning" size="sm" className="mt-1">Frequent</Badge>
<h4 className="font-semibold">Wrong Date Format</h4>
</div>
<CodeBlock language="javascript" code={`// ✅ Correct format (YYYYMMDD)
get_latest_error({ date: "20241218" })
// ❌ Wrong formats
get_latest_error({ date: "2024-12-18" })
get_latest_error({ date: "12/18/2024" })`} />
</div>
<div>
<div className="flex items-baseline gap-2 mb-3">
<Badge variant="info" size="sm" className="mt-1">Check</Badge>
<h4 className="font-semibold">Instance Activity</h4>
</div>
<ul className="text-sm space-y-1">
<li>Ensure SFCC instance is active</li>
<li>Check if logs are being generated</li>
<li>Verify log retention settings</li>
</ul>
</div>
</div>
</Collapsible>
<Collapsible title="System & Custom Object / Site Preference Tools Failing" intent="warn" id="system-object-issues" className="mb-6">
<div className="space-y-6">
<div>
<h4 className="font-semibold mb-2">Canonical Data API Resource Mapping (Matches Configuration Page)</h4>
<p className="text-sm text-gray-600 mb-3">Business Manager → Administration → Site Development → Open Commerce API Settings → Data API tab. Add (or verify) a client with the resources below. This is the <strong>source of truth</strong> for all metadata, search and code version tools.</p>
<CodeBlock language="json" code={`{
"_v": "23.2",
"clients": [{
"client_id": "YOUR_CLIENT_ID",
"resources": [
{ "resource_id": "/system_object_definitions", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
{ "resource_id": "/system_object_definitions/*", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
{ "resource_id": "/system_object_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
{ "resource_id": "/system_object_definitions/*/attribute_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
{ "resource_id": "/system_object_definitions/*/attribute_group_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
{ "resource_id": "/custom_object_definitions/*/attribute_definition_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
{ "resource_id": "/site_preferences/preference_groups/*/*/preference_search", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" },
{ "resource_id": "/code_versions", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" },
{ "resource_id": "/code_versions/*", "methods": ["get", "patch"], "read_attributes": "(**)", "write_attributes": "(**)" }
]
}]
}`} />
<ul className="mt-4 text-xs text-gray-600 space-y-1 list-disc pl-5">
<li><strong>Search endpoints use POST</strong> (definition_search / preference_search) – required for filtering & pagination tools.</li>
<li><strong>(**)</strong> read/write attributes maximize introspection; narrow later for principle-of-least-privilege.</li>
<li><strong>code_versions/* patch</strong> enables activation (switch active code version).</li>
<li>Older examples using <InlineCode>/site_preferences/*</InlineCode> or <InlineCode>/custom_object_definitions/*</InlineCode> with only <InlineCode>get</InlineCode> are incomplete for search tools.</li>
<li>Password-type site preference values remain masked—design constraint, not a permission issue.</li>
</ul>
</div>
<div>
<h4 className="font-semibold mb-2">Client Scope Requirements</h4>
<p className="text-sm text-gray-600 mb-2">Account Manager → API Client must include scopes:</p>
<div className="flex flex-wrap gap-2">
<Badge variant="info">SALESFORCE_COMMERCE_API:CONFIGURE</Badge>
<Badge variant="info">SALESFORCE_COMMERCE_API:READ_ONLY</Badge>
</div>
</div>
<div className="bg-yellow-50 border-l-4 border-yellow-400 p-4">
<h4 className="font-semibold text-yellow-800 mb-2">Empty Search Results?</h4>
<ul className="list-disc pl-5 text-xs space-y-1 text-yellow-800">
<li>Confirm <InlineCode>definition_search</InlineCode> endpoints are present (POST) – not just wildcard GET.</li>
<li>Remove filters: use <InlineCode>match_all_query</InlineCode> then refine client-side.</li>
<li>Check attribute group existence with <InlineCode>search_system_object_attribute_groups</InlineCode>.</li>
<li>Validate client_id matches dw.json entry (no trailing spaces).</li>
<li>Rare replication lag? Wait 1–2 minutes after BM changes.</li>
</ul>
</div>
</div>
</Collapsible>
<Collapsible title="Job Log Tools Issues" intent="info" id="job-log-issues" className="mb-6">
<div className="space-y-6">
<div>
<h4 className="font-semibold mb-2">Job Log Access</h4>
<p className="text-sm text-gray-600 mb-3">Job logs are stored in deeper folder structure: <InlineCode>/Logs/jobs/[job-name-id]/</InlineCode> (all levels in a single file).</p>
<CodeBlock language="bash" code={`# Test job log access root
curl -u "username:password" \\
https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.servlet/webdav/Sites/Logs/jobs/`} />
</div>
<div>
<h4 className="font-semibold mb-2">Minimal Health Flow</h4>
<CodeBlock language="bash" code={`# 1. Name filter (fast existence check)
aegis query search_job_logs_by_name 'jobName:MyJob|limit:3'
# 2. Tail entries
aegis query get_job_log_entries 'jobName:MyJob|limit:40'
# 3. Summary
aegis query get_job_execution_summary 'jobName:MyJob'`} />
</div>
<div>
<h4 className="font-semibold mb-2">No Logs Returned?</h4>
<ul className="list-disc pl-5 text-sm space-y-1 text-gray-600">
<li>Confirm job executed recently</li>
<li>Check filename prefix (Job-)</li>
<li>Limit too small (increase to 100)</li>
<li>WebDAV credential mismatch</li>
</ul>
</div>
</div>
</Collapsible>
<H2 id="ai-interfaces">🤖 AI Interface Setup</H2>
<Collapsible title="GitHub Copilot Integration" intent="info" id="github-copilot-setup" className="mb-6">
<div className="space-y-4">
<div>
<h4 className="font-semibold mb-2">Instructions File Location</h4>
<p className="text-sm text-gray-600 mb-2">File must be in project root for VS Code to detect:</p>
<CodeBlock language="bash" code={`# Verify file exists
ls -la .github/copilot-instructions.md
# Check VS Code Copilot extension
code --list-extensions | grep copilot`} />
</div>
<div className="bg-blue-50 border border-blue-200 rounded-lg p-4">
<h5 className="font-semibold text-blue-800 mb-2">Troubleshooting Steps</h5>
<ul className="text-sm space-y-1">
<li>Ensure GitHub Copilot subscription is active</li>
<li>Update VS Code Copilot extension</li>
<li>Restart VS Code to reload instructions</li>
<li>Check if instructions file is in correct location</li>
</ul>
</div>
</div>
</Collapsible>
<Collapsible title="Cursor Editor Setup" intent="info" id="cursor-setup" className="mb-6">
<div className="space-y-4">
<div>
<h4 className="font-semibold mb-2">Rules Directory Structure</h4>
<CodeBlock language="bash" code={`# Check rules directory
ls -la .cursor/
# Verify rule files
find .cursor -name "*.md" -o -name "*.mdc"`} />
</div>
<div>
<h4 className="font-semibold mb-2">Common Issues</h4>
<ul className="text-sm space-y-1">
<li>Rules directory doesn't exist</li>
<li>Wrong file extension (.md vs .mdc)</li>
<li>Cursor version compatibility</li>
</ul>
</div>
</div>
</Collapsible>
<H2 id="performance-debug">🔍 Performance & Debug</H2>
<Collapsible title="Enable Debug Logging" intent="plain" id="debug-logging" className="mb-6">
<div className="space-y-4">
<div>
<h4 className="font-semibold mb-2">Debug Mode Commands</h4>
<CodeBlock language="bash" code={`# Enable debug mode
npx -y sfcc-dev-mcp --debug --dw-json /Users/username/sfcc-project/dw.json
# Documentation-only debug mode
npx -y sfcc-dev-mcp --debug
# Disable debug explicitly
npx -y sfcc-dev-mcp --debug false --dw-json /Users/username/sfcc-project/dw.json`} />
</div>
<div className="bg-yellow-50 border border-yellow-200 rounded-lg p-4">
<p className="text-yellow-800 text-sm">
<strong>Note:</strong> Environment variables like <InlineCode>DEBUG=sfcc-dev-mcp:*</InlineCode> are not supported.
Use the <InlineCode>--debug</InlineCode> command-line argument.
</p>
</div>
</div>
</Collapsible>
<Collapsible title="Log File Locations" intent="plain" id="log-locations" className="mb-6">
<div className="space-y-4">
<div>
<h4 className="font-semibold mb-2">OS-Specific Paths</h4>
<div className="space-y-2 text-sm">
<div><strong>macOS:</strong> <InlineCode>/var/folders/{'{user-id}'}/T/sfcc-mcp-logs/</InlineCode></div>
<div><strong>Linux:</strong> <InlineCode>/tmp/sfcc-mcp-logs/</InlineCode></div>
<div><strong>Windows:</strong> <InlineCode>%TEMP%\sfcc-mcp-logs\</InlineCode></div>
</div>
</div>
<div>
<h4 className="font-semibold mb-2">Find Your Path</h4>
<CodeBlock language="bash" code={`# Get exact path
node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"`} />
</div>
<div>
<h4 className="font-semibold mb-2">Generated Log Files</h4>
<ul className="text-sm space-y-1">
<li><InlineCode>sfcc-mcp-info.log</InlineCode> - Startup and informational messages</li>
<li><InlineCode>sfcc-mcp-warn.log</InlineCode> - Warning messages</li>
<li><InlineCode>sfcc-mcp-error.log</InlineCode> - Error messages and stack traces</li>
<li><InlineCode>sfcc-mcp-debug.log</InlineCode> - Debug messages (when --debug enabled)</li>
</ul>
</div>
<div>
<h4 className="font-semibold mb-2">View Logs Real-Time</h4>
<CodeBlock language="bash" code={`# macOS - Find and tail error logs
find /var/folders -name "sfcc-mcp-error.log" 2>/dev/null | head -1 | xargs tail -f
# Linux - Direct path
tail -f /tmp/sfcc-mcp-logs/sfcc-mcp-error.log
# Windows - PowerShell
Get-Content -Wait "$env:TEMP\\sfcc-mcp-logs\\sfcc-mcp-error.log"`} />
</div>
</div>
</Collapsible>
<Collapsible title="Testing & Validation" intent="plain" id="testing-validation" className="mb-6">
<div className="space-y-4">
<div>
<h4 className="font-semibold mb-2">Basic Functionality Tests</h4>
<CodeBlock language="bash" code={`# Test documentation-only mode
npx -y sfcc-dev-mcp
# Test with debug mode
npx -y sfcc-dev-mcp --debug
# Test with SFCC credentials
npx -y sfcc-dev-mcp --dw-json /Users/username/sfcc-project/dw.json --debug`} />
</div>
<div>
<h4 className="font-semibold mb-2">Manual Validation</h4>
<CodeBlock language="bash" code={`# Validate dw.json syntax
python -m json.tool dw.json
# Test SFCC connectivity
curl -I https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com
# Test WebDAV access
curl -u "username:password" \\
https://your-instance.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.servlet/webdav/Sites/`} />
</div>
</div>
</Collapsible>
<H2 id="getting-help">🆘 Getting Help</H2>
<Collapsible title="Collect Support Information" intent="info" id="support-info" className="mb-6">
<div className="space-y-4">
<div>
<h4 className="font-semibold mb-2">Diagnostic Data Collection</h4>
<CodeBlock language="bash" code={`# System information
echo "Node.js: $(node --version)" > debug-info.txt
echo "npm: $(npm --version)" >> debug-info.txt
echo "OS: $(uname -a)" >> debug-info.txt
# Package version
npm list sfcc-dev-mcp >> debug-info.txt 2>&1
# dw.json structure (sanitized)
cat dw.json | jq 'keys' >> debug-info.txt 2>/dev/null`} />
</div>
<div className="bg-red-50 border border-red-200 rounded-lg p-4">
<h5 className="font-semibold text-red-800 mb-2">⚠️ Sanitize Sensitive Data</h5>
<CodeBlock language="bash" code={`# Remove sensitive information before sharing
sed 's/password":"[^"]*"/password":"***"/g' dw.json > dw-safe.json
sed 's/client-secret":"[^"]*"/client-secret":"***"/g' dw-safe.json > dw-final.json`} />
</div>
</div>
</Collapsible>
<Collapsible title="Common Error Codes" intent="plain" id="error-codes" className="mb-6">
<div className="overflow-x-auto">
<table className="min-w-full border-collapse border border-gray-300">
<thead>
<tr className="bg-gray-100">
<th className="border border-gray-300 px-4 py-2 text-left">Error Code</th>
<th className="border border-gray-300 px-4 py-2 text-left">Meaning</th>
<th className="border border-gray-300 px-4 py-2 text-left">Quick Fix</th>
</tr>
</thead>
<tbody>
<tr>
<td className="border border-gray-300 px-4 py-2"><Badge variant="error" size="sm">ECONNREFUSED</Badge></td>
<td className="border border-gray-300 px-4 py-2">Cannot connect to SFCC</td>
<td className="border border-gray-300 px-4 py-2">Check hostname and network</td>
</tr>
<tr>
<td className="border border-gray-300 px-4 py-2"><Badge variant="error" size="sm">401</Badge></td>
<td className="border border-gray-300 px-4 py-2">Invalid credentials</td>
<td className="border border-gray-300 px-4 py-2">Update username/password/API keys</td>
</tr>
<tr>
<td className="border border-gray-300 px-4 py-2"><Badge variant="warning" size="sm">403</Badge></td>
<td className="border border-gray-300 px-4 py-2">Insufficient permissions / missing OCAPI resource</td>
<td className="border border-gray-300 px-4 py-2">Add required resource entry & redeploy settings</td>
</tr>
<tr>
<td className="border border-gray-300 px-4 py-2"><Badge variant="warning" size="sm">404</Badge></td>
<td className="border border-gray-300 px-4 py-2">Resource not found</td>
<td className="border border-gray-300 px-4 py-2">Verify URLs and paths</td>
</tr>
<tr>
<td className="border border-gray-300 px-4 py-2"><Badge variant="info" size="sm">409</Badge></td>
<td className="border border-gray-300 px-4 py-2">Concurrent code version activation</td>
<td className="border border-gray-300 px-4 py-2">Retry after ensuring no parallel activation</td>
</tr>
<tr>
<td className="border border-gray-300 px-4 py-2"><Badge variant="info" size="sm">429</Badge></td>
<td className="border border-gray-300 px-4 py-2">Rate limiting</td>
<td className="border border-gray-300 px-4 py-2">Wait and retry</td>
</tr>
</tbody>
</table>
</div>
</Collapsible>
{/* Next Steps */}
<div className="mb-24">
<div className="text-center mb-8">
<h2 id="next-steps-troubleshooting" className="text-2xl font-bold text-gray-900 mb-2">🔗 Next Steps</h2>
<PageSubtitle className="text-base text-gray-600">Now that you've resolved your issues, explore the full capabilities.</PageSubtitle>
</div>
<div className="flex flex-col sm:flex-row gap-4 justify-center">
<NavLink to="/configuration/" className="group bg-gradient-to-r from-blue-600 to-purple-600 text-white px-8 py-4 rounded-xl font-semibold text-lg shadow-lg hover:shadow-xl transition-all duration-300 transform hover:-translate-y-1 no-underline hover:no-underline focus:no-underline">
Configuration Guide
<span className="ml-2 group-hover:translate-x-1 inline-block transition-transform">→</span>
</NavLink>
<NavLink to="/tools/" className="border-2 border-gray-300 text-gray-700 px-8 py-4 rounded-xl font-semibold text-lg hover:border-blue-500 hover:text-blue-600 transition-all duration-300 no-underline hover:no-underline focus:no-underline">
Available Tools
</NavLink>
</div>
</div>
</div>
);
};
export default TroubleshootingPage;
```
--------------------------------------------------------------------------------
/docs/dw_catalog/ProductActiveData.md:
--------------------------------------------------------------------------------
```markdown
## Package: dw.catalog
# Class ProductActiveData
## Inheritance Hierarchy
- Object
- dw.object.PersistentObject
- dw.object.ExtensibleObject
- dw.object.ActiveData
- dw.catalog.ProductActiveData
## Description
Represents the active data for a Product in Commerce Cloud Digital.
## Properties
### availableDate
**Type:** Date (Read Only)
The date the product became available on the site, or
null if none has been set.
### avgGrossMarginPercentDay
**Type:** Number (Read Only)
The average gross margin percentage of the product,
over the most recent day for the site, or null
if none has been set or the value is no longer valid.
### avgGrossMarginPercentMonth
**Type:** Number (Read Only)
The average gross margin percentage of the product,
over the most recent 30 days for the site, or null
if none has been set or the value is no longer valid.
### avgGrossMarginPercentWeek
**Type:** Number (Read Only)
The average gross margin percentage of the product,
over the most recent 7 days for the site, or null
if none has been set or the value is no longer valid.
### avgGrossMarginPercentYear
**Type:** Number (Read Only)
The average gross margin percentage of the product,
over the most recent 365 days for the site, or null
if none has been set or the value is no longer valid.
### avgGrossMarginValueDay
**Type:** Number (Read Only)
The average gross margin value of the product,
over the most recent day for the site, or null
if none has been set or the value is no longer valid.
### avgGrossMarginValueMonth
**Type:** Number (Read Only)
The average gross margin value of the product,
over the most recent 30 days for the site, or null
if none has been set or the value is no longer valid.
### avgGrossMarginValueWeek
**Type:** Number (Read Only)
The average gross margin value of the product,
over the most recent 7 days for the site, or null
if none has been set or the value is no longer valid.
### avgGrossMarginValueYear
**Type:** Number (Read Only)
The average gross margin value of the product,
over the most recent 365 days for the site, or null
if none has been set or the value is no longer valid.
### avgSalesPriceDay
**Type:** Number (Read Only)
The average sales price for the product, over the most recent day
for the site, or null if none has been set or the value
is no longer valid.
### avgSalesPriceMonth
**Type:** Number (Read Only)
The average sales price for the product, over the most recent 30 days
for the site, or null if none has been set or the value
is no longer valid.
### avgSalesPriceWeek
**Type:** Number (Read Only)
The average sales price for the product, over the most recent 7 days
for the site, or null if none has been set or the value
is no longer valid.
### avgSalesPriceYear
**Type:** Number (Read Only)
The average sales price for the product, over the most recent 365 days
for the site, or null if none has been set or the value
is no longer valid.
### conversionDay
**Type:** Number (Read Only)
The conversion rate of the product, over the most recent day
for the site, or null if none has been set or the value
is no longer valid.
### conversionMonth
**Type:** Number (Read Only)
The conversion rate of the product, over the most recent 30 days
for the site, or null if none has been set or the value
is no longer valid.
### conversionWeek
**Type:** Number (Read Only)
The conversion rate of the product, over the most recent 7 days
for the site, or null if none has been set or the value
is no longer valid.
### conversionYear
**Type:** Number (Read Only)
The conversion rate of the product, over the most recent 365 days
for the site, or null if none has been set or the value
is no longer valid.
### costPrice
**Type:** Number (Read Only)
The cost price for the product for the site,
or null if none has been set or the value is no longer valid.
### daysAvailable
**Type:** Number (Read Only)
The number of days the product has been available on the site.
The number is calculated based on the current date and the date the
product became available on the site, or if that date has not been set,
the date the product was created in the system.
### impressionsDay
**Type:** Number (Read Only)
The impressions of the product, over the most recent day
for the site, or null if none has been set or the value
is no longer valid.
### impressionsMonth
**Type:** Number (Read Only)
The impressions of the product, over the most recent 30 days
for the site, or null if none has been set or the value
is no longer valid.
### impressionsWeek
**Type:** Number (Read Only)
The impressions of the product, over the most recent 7 days
for the site, or null if none has been set or the value
is no longer valid.
### impressionsYear
**Type:** Number (Read Only)
The impressions of the product, over the most recent 365 days
for the site, or null if none has been set or the value
is no longer valid.
### lookToBookRatioDay
**Type:** Number (Read Only)
The look to book ratio of the product, over the most recent day
for the site, or null if none has been set or the value
is no longer valid.
### lookToBookRatioMonth
**Type:** Number (Read Only)
The look to book ratio of the product, over the most recent 30 days
for the site, or null if none has been set or the value
is no longer valid.
### lookToBookRatioWeek
**Type:** Number (Read Only)
The look to book ratio of the product, over the most recent 7 days
for the site, or null if none has been set or the value
is no longer valid.
### lookToBookRatioYear
**Type:** Number (Read Only)
The look to book ratio of the product, over the most recent 365 days
for the site, or null if none has been set or the value
is no longer valid.
### ordersDay
**Type:** Number (Read Only)
The number of orders containing the product, over the most
recent day for the site, or null if none has been set
or the value is no longer valid.
### ordersMonth
**Type:** Number (Read Only)
The number of orders containing the product, over the most
recent 30 days for the site, or null if none has been set
or the value is no longer valid.
### ordersWeek
**Type:** Number (Read Only)
The number of orders containing the product, over the most
recent 7 days for the site, or null if none has been set
or the value is no longer valid.
### ordersYear
**Type:** Number (Read Only)
The number of orders containing the product, over the most
recent 365 days for the site, or null if none has been set
or the value is no longer valid.
### returnRate
**Type:** Number (Read Only)
The return rate for the product for the site,
or null if none has been set or the value is no longer valid.
### revenueDay
**Type:** Number (Read Only)
The revenue of the product, over the most recent day
for the site, or null if none has been set or the value
is no longer valid.
### revenueMonth
**Type:** Number (Read Only)
The revenue of the product, over the most recent 30 days
for the site, or null if none has been set or the value
is no longer valid.
### revenueWeek
**Type:** Number (Read Only)
The revenue of the product, over the most recent 7 days
for the site, or null if none has been set or the value
is no longer valid.
### revenueYear
**Type:** Number (Read Only)
The revenue of the product, over the most recent 365 days
for the site, or null if none has been set or the value
is no longer valid.
### salesVelocityDay
**Type:** Number (Read Only)
The sales velocity of the product, over the most recent day
for the site, or null if none has been set or the value
is no longer valid.
### salesVelocityMonth
**Type:** Number (Read Only)
The sales velocity of the product, over the most recent 30 days
for the site, or null if none has been set or the value
is no longer valid.
### salesVelocityWeek
**Type:** Number (Read Only)
The sales velocity of the product, over the most recent 7 days
for the site, or null if none has been set or the value
is no longer valid.
### salesVelocityYear
**Type:** Number (Read Only)
The sales velocity of the product, over the most recent 365 days
for the site, or null if none has been set or the value
is no longer valid.
### unitsDay
**Type:** Number (Read Only)
The units of the product ordered over the most recent day
for the site, or null if none has been set or the value
is no longer valid.
### unitsMonth
**Type:** Number (Read Only)
The units of the product ordered over the most recent 30 days
for the site, or null if none has been set or the value
is no longer valid.
### unitsWeek
**Type:** Number (Read Only)
The units of the product ordered over the most recent 7 days
for the site, or null if none has been set or the value
is no longer valid.
### unitsYear
**Type:** Number (Read Only)
The units of the product ordered over the most recent 365 days
for the site, or null if none has been set or the value
is no longer valid.
### viewsDay
**Type:** Number (Read Only)
The views of the product, over the most recent day
for the site, or null if none has been set or the value
is no longer valid.
### viewsMonth
**Type:** Number (Read Only)
The views of the product, over the most recent 30 days
for the site, or null if none has been set or the value
is no longer valid.
### viewsWeek
**Type:** Number (Read Only)
The views of the product, over the most recent 7 days
for the site, or null if none has been set or the value
is no longer valid.
### viewsYear
**Type:** Number (Read Only)
The views of the product, over the most recent 365 days
for the site, or null if none has been set or the value
is no longer valid.
## Constructor Summary
## Method Summary
### getAvailableDate
**Signature:** `getAvailableDate() : Date`
Returns the date the product became available on the site, or null if none has been set.
### getAvgGrossMarginPercentDay
**Signature:** `getAvgGrossMarginPercentDay() : Number`
Returns the average gross margin percentage of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getAvgGrossMarginPercentMonth
**Signature:** `getAvgGrossMarginPercentMonth() : Number`
Returns the average gross margin percentage of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getAvgGrossMarginPercentWeek
**Signature:** `getAvgGrossMarginPercentWeek() : Number`
Returns the average gross margin percentage of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getAvgGrossMarginPercentYear
**Signature:** `getAvgGrossMarginPercentYear() : Number`
Returns the average gross margin percentage of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getAvgGrossMarginValueDay
**Signature:** `getAvgGrossMarginValueDay() : Number`
Returns the average gross margin value of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getAvgGrossMarginValueMonth
**Signature:** `getAvgGrossMarginValueMonth() : Number`
Returns the average gross margin value of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getAvgGrossMarginValueWeek
**Signature:** `getAvgGrossMarginValueWeek() : Number`
Returns the average gross margin value of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getAvgGrossMarginValueYear
**Signature:** `getAvgGrossMarginValueYear() : Number`
Returns the average gross margin value of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getAvgSalesPriceDay
**Signature:** `getAvgSalesPriceDay() : Number`
Returns the average sales price for the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getAvgSalesPriceMonth
**Signature:** `getAvgSalesPriceMonth() : Number`
Returns the average sales price for the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getAvgSalesPriceWeek
**Signature:** `getAvgSalesPriceWeek() : Number`
Returns the average sales price for the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getAvgSalesPriceYear
**Signature:** `getAvgSalesPriceYear() : Number`
Returns the average sales price for the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getConversionDay
**Signature:** `getConversionDay() : Number`
Returns the conversion rate of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getConversionMonth
**Signature:** `getConversionMonth() : Number`
Returns the conversion rate of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getConversionWeek
**Signature:** `getConversionWeek() : Number`
Returns the conversion rate of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getConversionYear
**Signature:** `getConversionYear() : Number`
Returns the conversion rate of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getCostPrice
**Signature:** `getCostPrice() : Number`
Returns the cost price for the product for the site, or null if none has been set or the value is no longer valid.
### getDaysAvailable
**Signature:** `getDaysAvailable() : Number`
Returns the number of days the product has been available on the site.
### getImpressionsDay
**Signature:** `getImpressionsDay() : Number`
Returns the impressions of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getImpressionsMonth
**Signature:** `getImpressionsMonth() : Number`
Returns the impressions of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getImpressionsWeek
**Signature:** `getImpressionsWeek() : Number`
Returns the impressions of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getImpressionsYear
**Signature:** `getImpressionsYear() : Number`
Returns the impressions of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getLookToBookRatioDay
**Signature:** `getLookToBookRatioDay() : Number`
Returns the look to book ratio of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getLookToBookRatioMonth
**Signature:** `getLookToBookRatioMonth() : Number`
Returns the look to book ratio of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getLookToBookRatioWeek
**Signature:** `getLookToBookRatioWeek() : Number`
Returns the look to book ratio of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getLookToBookRatioYear
**Signature:** `getLookToBookRatioYear() : Number`
Returns the look to book ratio of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getOrdersDay
**Signature:** `getOrdersDay() : Number`
Returns the number of orders containing the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getOrdersMonth
**Signature:** `getOrdersMonth() : Number`
Returns the number of orders containing the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getOrdersWeek
**Signature:** `getOrdersWeek() : Number`
Returns the number of orders containing the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getOrdersYear
**Signature:** `getOrdersYear() : Number`
Returns the number of orders containing the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getReturnRate
**Signature:** `getReturnRate() : Number`
Returns the return rate for the product for the site, or null if none has been set or the value is no longer valid.
### getRevenueDay
**Signature:** `getRevenueDay() : Number`
Returns the revenue of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getRevenueMonth
**Signature:** `getRevenueMonth() : Number`
Returns the revenue of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getRevenueWeek
**Signature:** `getRevenueWeek() : Number`
Returns the revenue of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getRevenueYear
**Signature:** `getRevenueYear() : Number`
Returns the revenue of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getSalesVelocityDay
**Signature:** `getSalesVelocityDay() : Number`
Returns the sales velocity of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getSalesVelocityMonth
**Signature:** `getSalesVelocityMonth() : Number`
Returns the sales velocity of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getSalesVelocityWeek
**Signature:** `getSalesVelocityWeek() : Number`
Returns the sales velocity of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getSalesVelocityYear
**Signature:** `getSalesVelocityYear() : Number`
Returns the sales velocity of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getUnitsDay
**Signature:** `getUnitsDay() : Number`
Returns the units of the product ordered over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getUnitsMonth
**Signature:** `getUnitsMonth() : Number`
Returns the units of the product ordered over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getUnitsWeek
**Signature:** `getUnitsWeek() : Number`
Returns the units of the product ordered over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getUnitsYear
**Signature:** `getUnitsYear() : Number`
Returns the units of the product ordered over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
### getViewsDay
**Signature:** `getViewsDay() : Number`
Returns the views of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
### getViewsMonth
**Signature:** `getViewsMonth() : Number`
Returns the views of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
### getViewsWeek
**Signature:** `getViewsWeek() : Number`
Returns the views of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
### getViewsYear
**Signature:** `getViewsYear() : Number`
Returns the views of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
## Method Detail
## Method Details
### getAvailableDate
**Signature:** `getAvailableDate() : Date`
**Description:** Returns the date the product became available on the site, or null if none has been set.
**Returns:**
the date the product became available.
---
### getAvgGrossMarginPercentDay
**Signature:** `getAvgGrossMarginPercentDay() : Number`
**Description:** Returns the average gross margin percentage of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average gross margin percentage over the last day.
---
### getAvgGrossMarginPercentMonth
**Signature:** `getAvgGrossMarginPercentMonth() : Number`
**Description:** Returns the average gross margin percentage of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average gross margin percentage over the last 30 days.
---
### getAvgGrossMarginPercentWeek
**Signature:** `getAvgGrossMarginPercentWeek() : Number`
**Description:** Returns the average gross margin percentage of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average gross margin percentage over the last 7 days.
---
### getAvgGrossMarginPercentYear
**Signature:** `getAvgGrossMarginPercentYear() : Number`
**Description:** Returns the average gross margin percentage of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average gross margin percentage over the last 365 days.
---
### getAvgGrossMarginValueDay
**Signature:** `getAvgGrossMarginValueDay() : Number`
**Description:** Returns the average gross margin value of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average gross margin value over the last day.
---
### getAvgGrossMarginValueMonth
**Signature:** `getAvgGrossMarginValueMonth() : Number`
**Description:** Returns the average gross margin value of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average gross margin value over the last 30 days.
---
### getAvgGrossMarginValueWeek
**Signature:** `getAvgGrossMarginValueWeek() : Number`
**Description:** Returns the average gross margin value of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average gross margin value over the last 7 days.
---
### getAvgGrossMarginValueYear
**Signature:** `getAvgGrossMarginValueYear() : Number`
**Description:** Returns the average gross margin value of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average gross margin value over the last 365 days.
---
### getAvgSalesPriceDay
**Signature:** `getAvgSalesPriceDay() : Number`
**Description:** Returns the average sales price for the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average sales price over the last day.
---
### getAvgSalesPriceMonth
**Signature:** `getAvgSalesPriceMonth() : Number`
**Description:** Returns the average sales price for the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average sales price over the last 30 days.
---
### getAvgSalesPriceWeek
**Signature:** `getAvgSalesPriceWeek() : Number`
**Description:** Returns the average sales price for the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average sales price over the last 7 days.
---
### getAvgSalesPriceYear
**Signature:** `getAvgSalesPriceYear() : Number`
**Description:** Returns the average sales price for the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the average sales price over the last 365 days.
---
### getConversionDay
**Signature:** `getConversionDay() : Number`
**Description:** Returns the conversion rate of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the conversion over the last day.
---
### getConversionMonth
**Signature:** `getConversionMonth() : Number`
**Description:** Returns the conversion rate of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the conversion over the last 30 days.
---
### getConversionWeek
**Signature:** `getConversionWeek() : Number`
**Description:** Returns the conversion rate of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the conversion over the last 7 days.
---
### getConversionYear
**Signature:** `getConversionYear() : Number`
**Description:** Returns the conversion rate of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the conversion over the last 365 days.
---
### getCostPrice
**Signature:** `getCostPrice() : Number`
**Description:** Returns the cost price for the product for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the cost price.
---
### getDaysAvailable
**Signature:** `getDaysAvailable() : Number`
**Description:** Returns the number of days the product has been available on the site. The number is calculated based on the current date and the date the product became available on the site, or if that date has not been set, the date the product was created in the system.
**Returns:**
the age in days.
**See Also:**
getAvailableDate()
---
### getImpressionsDay
**Signature:** `getImpressionsDay() : Number`
**Description:** Returns the impressions of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the impressions over the last day.
---
### getImpressionsMonth
**Signature:** `getImpressionsMonth() : Number`
**Description:** Returns the impressions of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the impressions over the last 30 days.
---
### getImpressionsWeek
**Signature:** `getImpressionsWeek() : Number`
**Description:** Returns the impressions of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the impressions over the last 7 days.
---
### getImpressionsYear
**Signature:** `getImpressionsYear() : Number`
**Description:** Returns the impressions of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the impressions over the last 365 days.
---
### getLookToBookRatioDay
**Signature:** `getLookToBookRatioDay() : Number`
**Description:** Returns the look to book ratio of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the look to book ratio over the last day.
---
### getLookToBookRatioMonth
**Signature:** `getLookToBookRatioMonth() : Number`
**Description:** Returns the look to book ratio of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the look to book ratio over the last 30 days.
---
### getLookToBookRatioWeek
**Signature:** `getLookToBookRatioWeek() : Number`
**Description:** Returns the look to book ratio of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the look to book ratio over the last 7 days.
---
### getLookToBookRatioYear
**Signature:** `getLookToBookRatioYear() : Number`
**Description:** Returns the look to book ratio of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the look to book ratio over the last 365 days.
---
### getOrdersDay
**Signature:** `getOrdersDay() : Number`
**Description:** Returns the number of orders containing the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the orders over the last day.
---
### getOrdersMonth
**Signature:** `getOrdersMonth() : Number`
**Description:** Returns the number of orders containing the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the orders over the last 30 days.
---
### getOrdersWeek
**Signature:** `getOrdersWeek() : Number`
**Description:** Returns the number of orders containing the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the orders over the last 7 days.
---
### getOrdersYear
**Signature:** `getOrdersYear() : Number`
**Description:** Returns the number of orders containing the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the orders over the last 365 days.
---
### getReturnRate
**Signature:** `getReturnRate() : Number`
**Description:** Returns the return rate for the product for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the return rate.
---
### getRevenueDay
**Signature:** `getRevenueDay() : Number`
**Description:** Returns the revenue of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the revenue over the last day.
---
### getRevenueMonth
**Signature:** `getRevenueMonth() : Number`
**Description:** Returns the revenue of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the revenue over the last 30 days.
---
### getRevenueWeek
**Signature:** `getRevenueWeek() : Number`
**Description:** Returns the revenue of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the revenue over the last 7 days.
---
### getRevenueYear
**Signature:** `getRevenueYear() : Number`
**Description:** Returns the revenue of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the revenue over the last 365 days.
---
### getSalesVelocityDay
**Signature:** `getSalesVelocityDay() : Number`
**Description:** Returns the sales velocity of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the sales velocity over the last day.
---
### getSalesVelocityMonth
**Signature:** `getSalesVelocityMonth() : Number`
**Description:** Returns the sales velocity of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the sales velocity over the last 30 days.
---
### getSalesVelocityWeek
**Signature:** `getSalesVelocityWeek() : Number`
**Description:** Returns the sales velocity of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the sales velocity over the last 7 days.
---
### getSalesVelocityYear
**Signature:** `getSalesVelocityYear() : Number`
**Description:** Returns the sales velocity of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the sales velocity over the last 365 days.
---
### getUnitsDay
**Signature:** `getUnitsDay() : Number`
**Description:** Returns the units of the product ordered over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the units over the last day.
---
### getUnitsMonth
**Signature:** `getUnitsMonth() : Number`
**Description:** Returns the units of the product ordered over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the units over the last 30 days.
---
### getUnitsWeek
**Signature:** `getUnitsWeek() : Number`
**Description:** Returns the units of the product ordered over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the units over the last 7 days.
---
### getUnitsYear
**Signature:** `getUnitsYear() : Number`
**Description:** Returns the units of the product ordered over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the units over the last 365 days.
---
### getViewsDay
**Signature:** `getViewsDay() : Number`
**Description:** Returns the views of the product, over the most recent day for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the views over the last day.
---
### getViewsMonth
**Signature:** `getViewsMonth() : Number`
**Description:** Returns the views of the product, over the most recent 30 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the views over the last 30 days.
---
### getViewsWeek
**Signature:** `getViewsWeek() : Number`
**Description:** Returns the views of the product, over the most recent 7 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the views over the last 7 days.
---
### getViewsYear
**Signature:** `getViewsYear() : Number`
**Description:** Returns the views of the product, over the most recent 365 days for the site, or null if none has been set or the value is no longer valid.
**Returns:**
the views over the last 365 days.
---
```