sfcc-ocapi-documents

SFCC Shop API documents

TypeScript types based on the official OCAPI documentation

• SFCC Shop API documents
  • Usage
    • Installation
    • For the latest OCAPI version
    • For other versions
    • Additional OCAPI response attributes
  • Supported
    • OCAPI versions
      • Usage
    • Documents
  • Examples can be found here
  • Extending the Document objects
  • Utility types
    • Date
    • DateTime
    • DayOfWeek
    • LocalTime
    • Localized
    • TimeOfDay
    • WithCustom<T>
    • Typed<T>
    • Response<T>
  • Contribution

Usage

Installation

using npm:

npm install sfcc-ocapi-documents

using yarn:

yarn add sfcc-ocapi-documents

For the latest OCAPI version

    import OCAPI from 'sfcc-ocapi-documents'

    const basket: OCAPI.Basket 

For other versions

    import OCAPI from 'sfcc-ocapi-documents/20.10'

    const basket: OCAPI.Basket = {...}

Additional OCAPI response attributes

    import OCAPI, {Util} from 'sfcc-ocapi-documents/20.10'

    const basket: Util.Response<OCAPI.Basket> = {...}

Supported

OCAPI versions

• latest
• previous
• 20.2
• 20.3
• 20.4
• 20.8
• 20.9
• 20.10
• 21.2
• 21.6
• 21.8

Usage

    // latest
    import OCAPI from 'sfcc-ocapi-documents'
    // equivalent to above
    import OCAPI from 'sfcc-ocapi-documents/latest'

    // specific version 
    import OCAPI from 'sfcc-ocapi-documents/21.2'

Documents

• ApproachingDiscount
• Basket
• BasketReference
• BonusDiscountLineItem
• BundledProduct
• Category
• ChannelType
• CouponItem
• Content
• CustomObject
• ContentFolder
• Customer
• CustomerAddress
• CustomerInfo
• CustomerPaymentInstrument
• CustomerProductList
• CustomerProductListItem
• CustomerProductListItemPurchase
• Discount
• Fault
• Flash
• GiftCertificate
• GiftCertificateItem
• Image
• ImageGroup
• Inventory
• Master
• Note
• Option
• OptionItem
• OptionValue
• Order
• OrderAddress
• OrderPaymentInstrument
• PaymentMethod
• PriceAdjustment
• PriceAdjustmentLimit
• PublicProductList
• PublicProductListLink
• PublicProductListItem
• Product
• ProductDetailsLink
• ProductItem
• ProductLink
• ProductListItemReference
• ProductListLink
• ProductListEvent
• ProductPromotion
• ProductSearchHit
• ProductSearchRefinement
• ProductType
• PromotionCampaignAssignment
• PromotionLink
• Promotion
• Recommendation
• RecommendationType
• Shipment
• ShippingItem
• ShippingMethod
• ShippingPromotion
• SimpleLink
• SiteSpecific
• Store
• StoreResult
• Suggestion
• Taxation
• Variant
• Query
• Filter
• VariationAttribute
• VariationAttributeValue
• VariationGroup
• ProductSearchSortingOption
• Locale
• ProductSearchRefinementValue
• ProductSimpleLink
• Site
• SuggestedCategory
• SuggestedContent
• SuggestedPhrase
• SuggestedProduct
• SuggestedTerm
• SuggestedTerms

Examples can be found here

Extending the Document objects

To add custom properties to the documents you can create a OCAPI.d.ts (example). If the keys of the interface are not prefixed with c_ - they will be automatically prefixed

declare namespace OCAPI {
  namespace Custom {
    interface ProductItem {
        customAttribute: boolean
        c_otherCustomAttribute: boolean
    }
  }
}

Utility types

Date

Dash separated numbers

    import { Util } from 'sfcc-ocapi-documents'
    const date: Util.Date = '2020-10-10';

DateTime

the ISO 8601 standard: "2012-03-19T07:22:59Z".

    import { Util } from 'sfcc-ocapi-documents'
    export const dateTime: Util.DateTime = "2012-03-19T07:22:59Z";

DayOfWeek

Lowercase day of the week

    import { Util } from 'sfcc-ocapi-documents'
    const day: Util.DayOfWeek = "friday";

LocalTime

    import { Util } from 'sfcc-ocapi-documents'
    const time: Util.LocalTime = "23:59:59";

Localized

Placeholder indicating the value may be localized

    import { Util } from 'sfcc-ocapi-documents'
    const str: Util.Localized<string> = "супер кул";

TimeOfDay

Object indicating time interval

    import { Util } from 'sfcc-ocapi-documents'
    const timeOfDay: Util.TimeOfDay = {
        time_from: "11:59:59",
        time_to: "23:59:59"
    };

WithCustom<T>

Ensures the keys of the given object are prefixed with c_

    import { Util } from 'sfcc-ocapi-documents'
    type CustomData = {
        c_attr1: "value 1",
        attr2: boolean
    }
    const obj: Util.WithCustom<CustomData> = {
        c_attr1: "value 1",
        c_attr2: true
    }

Typed<T>

If given an object ensures it has optional _type property with string value and all of it's nested objects

    import { Util } from 'sfcc-ocapi-documents'
    type Data = {
        prop1: string
        prop2: {
            nestedProp: boolean
        },
        prop3:  {
            nestedProp: boolean
        }
    }
    const typedData: Util.Typed<Data> = {
        _type: "data",
        prop1: "val",
        prop2: {
            _type: "nested",
            nestedProp: true
        },
        prop3: {
            nestedProp: false
        }
    }

Response<T>

Adds _v: string, _resource_state?: string; and _flash?: Typed<Flash>[]; to the given object and ensures the rest of the properties are Typed

Contribution

PRs are welcome for adding missing interfaces or versions