SalesforceCommerceCloud
diff --git a/‎.circleci/config.yml‎
Lines changed: 6 additions & 3 deletions b/‎.circleci/config.yml‎
Lines changed: 6 additions & 3 deletions
diff --git a/‎.gitignore‎
Lines changed: 0 additions & 1 deletion b/‎.gitignore‎
Lines changed: 0 additions & 1 deletion
diff --git a/‎README.md‎
Lines changed: 20 additions & 9 deletions b/‎README.md‎
Lines changed: 20 additions & 9 deletions
diff --git a/‎docs/SessionManagement.png‎
49 KB b/‎docs/SessionManagement.png‎
49 KB
diff --git a/‎docs/architecture.md‎
Lines changed: 7 additions & 3 deletions b/‎docs/architecture.md‎
Lines changed: 7 additions & 3 deletions
diff --git a/‎docs/authenticationFlow.png‎
36.7 KB b/‎docs/authenticationFlow.png‎
36.7 KB
diff --git a/‎docs/componentExtension.md‎
Lines changed: 86 additions & 0 deletions b/‎docs/componentExtension.md‎
Lines changed: 86 additions & 0 deletions
diff --git a/‎docs/sessionManagement.md‎
Lines changed: 88 additions & 0 deletions b/‎docs/sessionManagement.md‎
Lines changed: 88 additions & 0 deletions
diff --git a/‎lerna.json‎
Lines changed: 1 addition & 1 deletion b/‎lerna.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎package.json‎
Lines changed: 2 additions & 1 deletion b/‎package.json‎
Lines changed: 2 additions & 1 deletion
@@ -1,3 +1,6 @@
+orbs:
+  node: circleci/[email protected]
+
 jobs:
     build:
       working_directory: ~/build_only
@@ -7,10 +10,10 @@ jobs:
       steps:
         - checkout
         - run: yarn install
+        - run: yarn lint
         - run: yarn build
         - run: yarn test
+        - run: yarn clean:stats
         - store_test_results:
             path: ~/
-orbs:
-  node: circleci/[email protected]
-version: 2.1
+version: 2.1
@@ -11,7 +11,6 @@ coverage
 *.iml
 jest-report
 yarn-error.log
-tsconfig.json
 .idea
 
 **/package-lock.json
 
@@ -23,17 +23,20 @@ To set up the sample application:
 2. Change into the `sfcc-sample-apps` folder:
 `cd sfcc-sample-apps`
 
-3. Copy the `api.example.mjs` file located at `/packages/storefront-lwc/scripts/`, save it as `api.mjs`, and make sure `api.mjs` is added to your `.gitignore` file.
+3. Copy the `api.example.js` file located at `/packages/storefront-lwc/app/`, save it as `api.js`, and make sure `api.js` is added to your `.gitignore` file.
 
-4. In the `api.mjs` file, provide values for the following variables (you can obtain these values from your Account Executive (AE) or Customer Support Manager (CSM)):
+4. In the `api.js` file, provide values for the following variables (you can obtain these values from your Account Executive (AE) or Customer Support Manager (CSM)):
 <table>
 <tr><th>Variable</th><th>Description</th></tr>
-<tr><td><code>COMMERCE_CLIENT_API_SITE_ID</code></td><td>A unique site ID (for example, RefArch or SiteGenesis).</td></tr>
-<tr><td><code>COMMERCE_CLIENT_CLIENT_ID</code></td><td>A unique ID used exclusively for API access. See <a href="https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/AccountManager/AccountManagerAddAPIClientID.html">Add a Client API</a> for more information.</td></tr>
-<tr><td><code>COMMERCE_CLIENT_REALM_ID</code></td><td>A unique four-character ID (for example, bblx).</td></tr>
-<tr><td><code>COMMERCE_CLIENT_INSTANCE_ID</code></td><td>Instance ID within a realm (for example, 015).</td></tr>
-<tr><td><code>COMMERCE_CLIENT_SHORT_CODE</code></td><td>Region-specific merchant identifier (for example, staging-001).</td></tr>
+<tr><td><code>COMMERCE_CLIENT_API_SITE_ID</code></td><td>Unique site ID (for example, RefArch or SiteGenesis).</td></tr>
+<tr><td><code>COMMERCE_CLIENT_CLIENT_ID</code></td><td>Unique ID used exclusively for API access. See <a href="https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/AccountManager/AccountManagerAddAPIClientID.html">Add a Client API</a> for more information.</td></tr>
+<tr><td><code>COMMERCE_CLIENT_REALM_ID</code></td><td>Unique four-character realm ID (for example, bblx).</td></tr>
+<tr><td><code>COMMERCE_CLIENT_INSTANCE_ID</code></td><td>Unique instance ID within a realm (for example, 015).</td></tr>
+<tr><td><code>COMMERCE_CLIENT_SHORT_CODE</code></td><td>Unique region-specific merchant ID (for example, staging-001).</td></tr>
+<tr><td><code>COMMERCE_SESSION_SECRET</code></td><td>Unique ID for session management (for example, thisisasecretkey).</td></tr>
+<tr><td><code>COMMERCE_CORS</code></td><td>Optionally enable <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS">CORS</a> for GraphQL on the defined domains (for example, enable all domains with "\*").</td></tr>
 </table>
+Note: If the COMMERCE_SESSION_SECRET key is not unique per customer application, session information can be unintentionally shared between ecommerce sites. 
 
 5. Install dependencies:
 `yarn`
@@ -45,7 +48,7 @@ To set up the sample application:
 `yarn start:dev` (development mode) or
 `yarn start` (production mode)
 
-8. To access the sample application in development mode, open the browser to http://localhost:3000 (for production mode, open to http://localhost:3002).
+8. To access the application, open the browser to http://localhost:3000
 
 You can optionally test the sample application:
 `yarn test`
@@ -55,7 +58,7 @@ You can optionally test the sample application:
 We recommend Visual Studio Code inbuilt debugger to troubleshoot the code. The `.vscode` launch configuration is included in the repo. To debug using VSCode, see [VS Code Debugging](https://code.visualstudio.com/docs/editor/debugging).
 
 ## Configuration
-* You can change the logging levels by modifying the `COMMERCE_LOG_LEVEL` property in `api.mjs`. The supported log levels are:
+* You can change the logging levels by modifying the `COMMERCE_LOG_LEVEL` property in `api.js`. The supported log levels are:
     * `TRACE`
     * `DEBUG`
     * `INFO`
@@ -74,6 +77,14 @@ We recommend Visual Studio Code inbuilt debugger to troubleshoot the code. The `
 * [Jest](https://jestjs.io/docs/en/getting-started)
 * [Visual Studio Code](https://code.visualstudio.com/docs)
 
+## Library of Components
+The sample app currently includes the following components:
+* [Home Page](https://github.com/SalesforceCommerceCloud/sfcc-sample-apps/tree/master/packages/storefront-lwc/src/modules/commerce/home)
+* [Product Detail](https://github.com/SalesforceCommerceCloud/sfcc-sample-apps/tree/master/packages/storefront-lwc/src/modules/commerce/productDetail)
+* [Product Search Results](https://github.com/SalesforceCommerceCloud/sfcc-sample-apps/tree/master/packages/storefront-lwc/src/modules/commerce/productSearchResults)
+* [Basket](https://github.com/SalesforceCommerceCloud/sfcc-sample-apps/tree/integration/packages/storefront-lwc/src/modules/commerce/basket)
+
+
 ## Contributing
 
 * See [Contributing](CONTRIBUTING.md)
 
@@ -30,8 +30,12 @@ Data source implementation for the Salesforce Commerce API. It includes the Grap
 #### storefront-lwc
 Front-end application, built with [lwc-services](https://www.npmjs.com/package/lwc-services).
 
+## Session Management
+
+To learn about session management in the sample app please see [session management](sessionManagement.md) 
+
 ## Customizing and Extending
-When customizing or extending the sample app, do not modify the packages within `@sfcc-bff` and `@sfcc-core`. These packages will be published and consumed via NPM. Instead, create a new custom package within the monorepo that registers itself with `@sfcc-core` and provides access to data from a third-party service.
+When customizing or extending the sample app, do not modify the packages within `@sfcc-bff` and `@sfcc-core`. These packages will be published and consumed via NPM. Instead, create a new custom package within the monorepo that registers itself with `@sfcc-core` and provides access to data from a third-party service. For more information, see [Component Extension](docs/componentExtension.md).
 
 ![Sample App Project Layout](project-layout.png)
 
@@ -40,7 +44,7 @@ The core-graphql module within `@sfcc-core` is responsible for getting all the r
 ## What's Not Included?
 This is a sample application, and is not intended to be a full reference architecture. There are multiple components missing, some of which will be added in the future. Specifically, the app does not currently include:
 
-1. **Authentication** - Required for a fully functional cart and checkout experience.
+1. **Authentication** - Required for a fully functional basket and checkout experience.
 2. **CMS Integration** - Required to customize the storefront experience per user.
 3. **Server-side Rendering** - Required for product listing search engine optimization.
-4. **Component Portability** - Work needs to be done to re-use components outside of the sample app context.
+4. **Component Portability** - Work needs to be done to re-use components outside of the sample app context.
@@ -0,0 +1,86 @@
+## Customizing and Extending Components
+
+As mentioned in the [architecture document](architecture.md), when customizing or extending the sample app component, you should not modify the packages within `@sfcc-bff` and `@sfcc-core`. These packages will be published and consumed via `npm`. Instead, create a new custom package either within the monorepo or a new module that registers itself with `@sfcc-core\core` and provides access to data from a third-party service. Then we will need to extend the data model and extend the query for the client component.
+
+
+This example below shows how to create a product recommendations extension for the product details component:
+
+Background: The Product Details Page shows the product name, product id, color swatches, images, price, and so on. Our goal is to extend this component to also show the product's recommendations. 
+
+1. In the storefront-lwc `app` directory, create a new extension called `productDetailExtension.js`
+
+2. In the `productDetailExtension.js` file, register the extension with core using the `API_EXTENSIONS_KEY` key. Extensions can have multiple entries per extension key, so we can simply register a new extension with the existing key: 
+
+```
+core.registerExtension(API_EXTENSIONS_KEY, function (config) {
+    return new ProductDetailExtensions();
+});
+```
+
+3. To Extend the data model, define the Recommendation type and use it to extend the Product type: 
+
+```
+const productRecommendationTypeDef = gql`
+    type Recommendation {
+        productId: String
+        productName: String
+        image: Image
+    }
+    extend type Product {
+        recommendations: [Recommendation]
+    }
+`;
+``` 
+
+4. Resolve the recommendations for a Product
+```
+const productRecommendationResolver = (config) => {
+    return {
+        Product: {
+            recommendations: async (product) => {
+                if (product.recommendations) {
+                    return Promise.all(product.recommendations.map( async recommendation => {
+                        const apiProduct = await getClientProduct(config, recommendation.recommendedItemId);
+                            return {productId: apiProduct.id, productName:apiProduct.name, image: new Image(apiProduct.imageGroups[2].images[0])};
+                        })
+                    )
+                }
+            }
+        }
+    }
+}
+```
+
+5. Add the product recommendation extension to the Backend For Frontend (BFF) by importing the extension created in step 1 to the `sample-app.js` file. 
+```
+import './extension/productDetailExtension';
+```
+
+6. To Extend the query for client component, In the `productdetailadapator.js` file, specify the query for product recommendations.
+```
+recommendations {
+    productId
+    productName
+    image {
+        title
+        link
+        alt
+    }
+}
+```
+
+7. In the `productdetail.html` file, consume the recommendations data (if any) returned from the BFF.
+``` 
+<!-- Product Recommendations -->
+<template if:true={product.recommendations}>
+    <div class="recommendation">
+        <template for:each={product.recommendations} for:item="recommendation">
+            <div class='col-6 col-sm-4 grid-gutter' key={recommendation.productId} >
+                <div class='product' >
+                    <commerce-product-tile product={recommendation}></commerce-product-tile>
+                </div>
+            </div>
+        </template>
+    </div>
+</template>
+```
@@ -0,0 +1,88 @@
+# Session Management
+
+When the client loads the Sample App, the Sample App is initialized with the express authentication middleware, [passportjs](http://www.passportjs.org/). After initialization, `passport.session` is invoked to generate a session. A cookie is also generated (using [express-session](https://www.npmjs.com/package/express-session) to represent the session. 
+
+The Sample App uses `GraphQLLocalStrategy` from the [graphql-passport](https://www.npmjs.com/package/graphql-passport) package for its authentication strategy. 
+
+Authentication enables end users to perform actions like creating a basket. 
+
+After successful authentication, the anonymous user ID is stored in the session corresponding to the generated cookie. 
+
+
+## Session Management and Authentication Flow
+
+![session management and authentication flow](SessionManagement.png)
+
+The Sample App uses the `express-session` module to generate a unique cookie that represents the session. The default cookie used for the session ID is `connect.sid`. When the cookie expires, the module automatically creates a new one.
+
+Passport middleware provides functions to serialize and deserialize a user to and from the session. As stated in the [architecture document](architecture.md), the front-end client communicates with the BFF via GraphQL. In the Sample App, every query using GraphQL uses the `/api` route. GraphQL separates queries based on resolvers in Sample App. 
+
+An authentication request is needed to get an access token that allows the Sample App to perform certain actions, such as creating a basket or adding products to a basket. The Sample App uses the package `graphql-passport` to provide the functionality to authenticate with passport.
+
+![authentication flow](authenticationFlow.png)
+
+GraphQL provides a `context` object which is the third parameter passed to any resolver. The `context` object is generated per request and can store data used by the resolver. The Sample App populates this `context` object in the `[graphql.ts](../packages/@sfcc-core/core-graphql/src/graphql.ts)` file (which is in the `core-graphql` package). The `context` function defined in `graphql.ts` takes two parameters, request (req) and response (res).
+
+```typescript
+this.apolloServer = new ApolloServer({
+    schema,
+    context: ({ req, res }) => ({
+        ...graphqlPassport.buildContext({ req, res }),
+        setSessionProperty(key: string, value: string) {
+            (req as Request).session[key] = value;
+        },
+        getSessionProperty(key: string) {
+            return (req as Request).session[key];
+        },
+    }),
+});
+```
+
+The request parameter is the same request object that express generates and is the actual web service call that contains the request headers, cookies, and so on. In the context function, the helper function `buildContext()` (which is provided by graphql-passport) helps build a context that is unique for each user, adding methods to the context to help authenticate using passport. After the `context` object is built, a resolver can ensure that the user is authenticated.
+
+The resolvers in Sample App need to retrieve the user from the context. To help with this operation, Sample App defines a function `getUserFromContext()`. This function calls the `context.authenticate()` function provided by graphql-passport. 
+
+```typescript
+export async function getUserFromContext(context: AppContext) {
+    let user = context.getUser();
+    const token = user ? user.token : '';
+    if (!token) {
+        const res = await context.authenticate('graphql-local', { token });
+        context.login(res.user);
+        user = res.user;
+    }
+    return user;
+}
+```
+
+The `context.authenticate` function calls the graphql-passport strategy configured in [runtime.js](../packages/storefront-lwc/scripts/runtime.js). This is the central location to perform the authentication logic.
+
+```typescript
+passport.use(
+    new graphqlPassport.GraphQLLocalStrategy(function(user, pass, done) {
+        const clientConfig = getCommerceClientConfig(config);
+        CommerceSdk.helpers
+            .getShopperToken(clientConfig, { type: 'guest' })
+            .then(token => {
+                const customerId = JSON.parse(token.decodedToken.sub)
+                    .customer_info.customer_id;
+                done(null, {
+                    id: customerId,
+                    token: token.getBearerHeader(),
+                });
+            })
+            .catch(error => done(error));
+    }),
+);
+```
+
+In Sample App’s authentication configuration, the shopper token is retrieved from the Commerce SDK. From this token, the anonymous user customer ID is determined. If authentication is successful, a user is returned containing the id and the bearer token. Following successful authentication, the `getUserFromContext()` function calls `context.login()` -- which invokes `passport.serializeUser`:
+
+```typescript
+passport.serializeUser(function(user, done) {
+    users.set(user.id, user);
+    done(null, user.id);
+});
+```
+
+The above function is used to serialize the user to the in-memory `users` object for the session.
@@ -1,7 +1,7 @@
 {
     "lerna": "2.11.0",
     "exact": true,
-    "version": "0.18.23",
+    "version": "1.0.0-alpha.2",
     "npmClient": "yarn",
     "command": {
         "init": {
 
@@ -14,6 +14,7 @@
     "lint": "lerna run lint --stream",
     "lint:fix": "lerna run lint:fix --stream",
     "clean": "lerna run clean --stream",
+    "clean:stats": "lerna run clean:stats --stream",
     "test": "lerna run test:unit --stream",
     "test:watch": "lerna run test:unit:watch --stream",
     "start": "yarn start:lwc",
@@ -66,6 +67,6 @@
     }
   },
   "lint-staged": {
-    "*.{js}": "prettier --write"
+    "*.{js,ts,mjs}": "prettier --write"
   }
 }
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"lerna": "2.11.0",`
`3`	`3`	`"exact": true,`
`4`		`- "version": "0.18.23",`
	`4`	`+ "version": "1.0.0-alpha.2",`
`5`	`5`	`"npmClient": "yarn",`
`6`	`6`	`"command": {`
`7`	`7`	`"init": {`
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@`
`14`	`14`	`"lint": "lerna run lint --stream",`
`15`	`15`	`"lint:fix": "lerna run lint:fix --stream",`
`16`	`16`	`"clean": "lerna run clean --stream",`
	`17`	`+ "clean:stats": "lerna run clean:stats --stream",`
`17`	`18`	`"test": "lerna run test:unit --stream",`
`18`	`19`	`"test:watch": "lerna run test:unit:watch --stream",`
`19`	`20`	`"start": "yarn start:lwc",`
`@@ -66,6 +67,6 @@`
`66`	`67`	`}`
`67`	`68`	`},`
`68`	`69`	`"lint-staged": {`
`69`		`- "*.{js}": "prettier --write"`
	`70`	`+ "*.{js,ts,mjs}": "prettier --write"`
`70`	`71`	`}`
`71`	`72`	`}`