Merge 796d9c0 into 8f6c1b0

packages/core/docs/commercetools/configuration.md

@@ -1,14 +1,126 @@
 # Configuration
 
-```javascript
+
+Commercetools configuration is located in two places:
+
+- nuxt.config.js is a place where you're configuring properties related only to the frontend part of your application.
+
+- middleware.config.js is a place where you're configuring the Commercetools SDK, Apollo and extensions. You will put there API keys, integration configurations, custom GraphQL queries and new API endpoints.
+
+## Nuxt Commercetools configuration
+
+
+```js
 ['@vue-storefront/commercetools/nuxt', {
-  /* configuration */
+  i18n: {
+    useNuxtI18nConfig: true
+  }
 }]
 ```
 
-- `api: ApiConfig`
+## Middleware Commercetools configuration
+
+
+```js
+// middleware.config.js
+ct: {
+  location: '@vue-storefront/commercetools-api/server',
+  configuration: {
+    api: {
+      /* your api configuration object */
+    }
+  }
+}
+```
+
+Minimal configuration object:
+
 ```js
-export interface ApiConfig {
+ct: {
+  location: '@vue-storefront/commercetools-api/server',
+  configuration: {
+    api: {
+      uri: 'https://<DOMAIN_NAME>.com/<PROJECT_KEY>/graphql',
+      authHost: 'https://auth.sphere.io',
+      projectKey: '<PROJECT_KEY>',
+      clientId: '<CLIENT_ID>',
+      clientSecret: '<CLIENT_SECRET>',
+      scopes: [
+        'manage_products:<PROJECT_KEY>',
+        /* other scope rules */
+      ]
+    },
+    currency: 'USD',
+    country: 'US'
+  }
+}
+```
+
+### uri
+
+Link to your Commercetools GraphQL API instance. It should look like this:
+`https://<DOMAIN_NAME>.com/<PROJECT_KEY>/graphql`
+
+### authHost
+
+Link to Commercetools Authentication Server. It is used to request an access token from commercetools OAuth 2.0 service. To choose the nearest service, please visit [Commercetools hosts list](https://docs.commercetools.com/api/authorization)
+
+### projectKey
+
+i.e. `my-awesome-vsf-project`
+
+### clientId
+
+Unique Commercetools Client ID. Visit [Commercetools documentation](https://docs.commercetools.com/tutorials/getting-started#creating-an-api-client) for more details about creating an API Client
+
+### clientSecret
+
+Commercetools secret API key. Visit [Commercetools documentation](https://docs.commercetools.com/tutorials/getting-started#creating-an-api-client) for more details about creating an API Client
+
+### scopes
+
+The scope constrains the endpoints to which a client has access, and whether a client has read or write access to an endpoint. Visit [Commercetools documentation](https://docs.commercetools.com/api/scopes#top) for more details about Scopes.
+
+
+Full configuration:
+
+```js
+interface Config<T = any> {
+  client?: ApolloClient<T>;
+  api: ApiConfig;
+  customOptions?: ApolloClientOptions<any>;
+  currency: string;
+  locale: string;
+  country: string;
+  countries: LocaleItem[];
+  currencies: LocaleItem[];
+  locales: LocaleItem[];
+  languageMap: Record<string, any>;
+  acceptLanguage: string[];
+  cookies: CookiesConfig;
+  auth?: Auth;
+  forceToken?: boolean;
+  handleIsTokenUserSession: (token: Token) => boolean;
+}
+```
+
+#### `client`
+
+Connection to the Commercetools client. `SdkAuth` and `TokenProvider` are imported from `@commercetools/sdk-auth`
+
+```js
+interface ClientInstance extends ApolloClient<any> {
+  sdkAuth?: SdkAuth;
+  tokenProvider?: TokenProvider;
+}
+```
+
+#### `api`
+
+Commercetools API configuration from `middleware.config.js`
+
+```js
+interface ApiConfig {
   uri: string;
   authHost: string;
   projectKey: string;
@@ -17,53 +129,67 @@ export interface ApiConfig {
   scopes: string[];
 }
 ```
-- `customOptions?: ApolloClientOptions<TCacheShape>`
-- `currency?: string`
-- `locale?: string`
-- `languageMap?: object`
-- `acceptLanguage?: string[]`
-- `country?: string`
-- `countries?: LocaleItem[]`
+
+#### `countries`, `currencies`, `locales`
+
+Array of accepted items
+
 ```js
-export interface LocaleItem {
+interface LocaleItem {
   name: string;
   label: string;
 }
 ```
-- `currencies?: LocaleItem[]`
-- `locales?: LocaleItem[]`
-- `cookies?: CookiesConfig`
+
+#### `cookies`
+
+Cookie names for `currency`, `country`, and `locale`
+
 ```js
-export interface CookiesConfig {
+interface CookiesConfig {
   currencyCookieName: string;
   countryCookieName: string;
   localeCookieName: string;
 }
 ```
-- `auth?: Auth`
+
+#### `auth`
+
+Token Authentication object. Later extended with custom extension `tokenExtension`
+
 ```js
-export interface Auth {
+interface Auth {
   onTokenChange?: (token: Token) => void;
   onTokenRead?: () => string;
   onTokenRemove?: () => void;
 }
-```
 
+interface Token {
+  access_token: string;
+  expires_at: number;
+  expires_in: number;
+  scope: string;
+  token_type: string;
+  refresh_token: string;
+}
+```
 
-### Localisation
+#### `acceptLanguage`
 
 Commercetools supports querying localised fields via an array of accepted languages - `acceptLanguage`.
+
 ```js
 acceptLanguage: ['en-gb', 'en-us']
 ```
 
+#### `languageMap`
+
 If you supply a `languageMap` during setup this will be used to map a locale to the accepted languages.
+
 ```js
 languageMap: {
   'en-gb': ['en-gb', 'en-us'],
   'en-us': ['en-us', 'en-gb'],
 }
 ```
 
-
-

packages/core/docs/commercetools/getting-started.md

@@ -5,32 +5,36 @@
 
 If you [generated your project from our CLI](/general/getting-started.html) your shop will be connected to our demo Commercetools instance.
 
-If you havn't generated your project just to play with Vue Storefront and understand its capabilities the first thing you should do after setting it up is changing the credentials to point into your instance.
+If you haven't generated your project just to play with Vue Storefront and understand its capabilities the first thing you should do after setting it up is changing the credentials to point into your instance.
 
 You can generate credentials for Commercetools API in Commercetools Merchant Center by going into:
 
 _Settings > API clients > "Create new api Client"_ and picking _"Mobile & single-page application client"_ template.
 
-Then paste those credentials into `@vue-storefront/commercetools/nuxt` module configuration in `nuxt.config.js`:
+Then paste these credentials into `ct` config object inside `integrations` in `middleware.config.js`:
 
 ```js
-['@vue-storefront/commercetools/nuxt', {
-  api: {
-    uri: 'https://yourshop.com/vsf-ct-dev/graphql',
-    authHost: 'https://auth.sphere.io',
-    projectKey: 'vsf-ct-dev',
-    clientId: '<your_client_id>',
-    clientSecret: '<your_client_secret>',
-    scopes: [
-      //* scopes */
-    ]
-  }
-}]
+    ct: {
+      location: '@vue-storefront/commercetools-api/server',
+      configuration: {
+        api: {
+          uri: 'https://<SHOP_DOMAIN>.com/vsf-ct-dev/graphql',
+          authHost: 'https://auth.sphere.io',
+          projectKey: 'vsf-ct-dev',
+          clientId: '<CLIENT_ID>',
+          clientSecret: '<CLIENT_SECRET>',
+          scopes: [
+            //* scopes */
+          ]
+        },
+        currency: 'USD',
+        country: 'US'
+      }
+    }
 ```
 
-There is plenty fo other configuration options and you can check them [here](./configuration.md)
+There is plenty of other configuration options and you can check them [here](./configuration.md)
 
 ## Configuring other integrations
 
-Depending on the configuration and if you're using Enterprise ersion you could hae additional integrations to set up. You will find their configurations in `nuxt.config.js`
-
+Depending on the configuration and if you're using Enterprise version you could have additional integrations to set up. You will find their configurations in `middleware.config.js`