feat(docs): Add docs on Channels & update README

README.md

@@ -44,7 +44,7 @@ The root directory has a `package.json` which contains build-related dependencie
 
 `yarn bootstrap`
 
-This runs the Lerna "bootstrap" command, which installs dependencies for all packages.
+This runs the Lerna "bootstrap" command, which cross-links monorepo dependencies.
 
 ### 3. Build all packages
 
@@ -59,11 +59,16 @@ Note that this can take a few minutes.
 The server requires an SQL database to be available. I am currently using [bitnami-docker-phpmyadmin](https://github.com/bitnami/bitnami-docker-phpmyadmin) Docker image,
 which is MariaDB including phpMyAdmin. However, the simplest option is to use SQLite.
 
-Vendure uses [TypeORM](http://typeorm.io), so it is compatible with any database which works with TypeORM.
+Vendure uses [TypeORM](http://typeorm.io), and officially supports **MySQL**, **PostgreSQL** and **SQLite**, though other TypeORM-supported databases may work.
 
 1. Configure the [dev config](./packages/dev-server/dev-config.ts), making sure the connection settings in the `getDbConfig()` function are correct for the database type you will be using.
 2. Create the database using your DB admin tool of choice (e.g. phpMyAdmin if you are using the docker image suggested above). Name it according to the `getDbConfig()` settings. If you are using SQLite, you can skip this step.
-3. Populate mock data with `DB=<mysql|postgres|sqlite> yarn dev-server:populate`. If you do not specify the `db` argument, it will default to "mysql".
+3. Populate mock data: 
+   ```bash
+    cd packages/dev-server
+    DB=<mysql|postgres|sqlite> yarn populate
+    ```
+   If you do not specify the `DB` variable, it will default to "mysql".
 
 ### 5. Run the dev server
 
@@ -71,7 +76,7 @@ Vendure uses [TypeORM](http://typeorm.io), so it is compatible with any database
 DB=<mysql|postgres|sqlite> yarn dev-server:start
 ```
 
- If you do not specify the `db` argument, it will default to "mysql".
+If you do not specify the `DB` argument, it will default to "mysql".
 
 ### 6. Launch the admin ui
 
@@ -81,42 +86,32 @@ DB=<mysql|postgres|sqlite> yarn dev-server:start
 
 ### Code generation
 
-[graphql-code-generator](https://github.com/dotansimha/graphql-code-generator) is used to automatically create TypeScript interfaces
-for all GraphQL server operations and admin ui queries. These generated interfaces are used in both the admin ui and the server.
+[graphql-code-generator](https://github.com/dotansimha/graphql-code-generator) is used to automatically create TypeScript interfaces for all GraphQL server operations and admin ui queries. These generated interfaces are used in both the admin ui and the server.
 
 Running `yarn codegen` will generate the following files:
 
 * [`packages/common/src/generated-types.ts`](./packages/common/src/generated-types.ts): Types, Inputs & resolver args relating to the Admin API
 * [`packages/common/src/generated-shop-types.ts`](./packages/common/src/generated-shop-types.ts): Types, Inputs & resolver args relating to the Shop API
-* [`admin-ui/src/app/common/generated-types.ts`](./admin-ui/src/app/common/generated-types.ts): Types & operations relating to the admin-ui queries & mutations.
-* [`packages/core/e2e/graphql/generated-e2e-admin-types.ts`](./packages/core/e2e/graphql/generated-e2e-admin-types.ts): Types used in e2e tests of the Admin API
-* [`packages/core/e2e/graphql/generated-e2e-shop-types.ts`](./packages/core/e2e/graphql/generated-e2e-shop-types.ts): Types used in e2e tests of the Shop API
+* [`packages/admin-ui/src/lib/core/src/common/generated-types.ts`](./packages/admin-ui/src/lib/core/src/common/generated-types.ts): Types & operations relating to the admin-ui queries & mutations.
+* [`packages/admin-ui/src/lib/core/src/common/introspection-result.ts`](./packages/admin-ui/src/lib/core/src/common/introspection-result.ts): Used by the Apollo Client [`IntrospectionFragmentMatcher`](https://www.apollographql.com/docs/react/data/fragments/#fragments-on-unions-and-interfaces) to correctly handle fragements in the Admin UI.
+* Also generates types used in e2e tests in those packages which feature e2e tests (core, elasticsearch-plugin, asset-server-plugin etc).
 
 ### Testing
 
 #### Server Unit Tests
 
-The server has unit tests which are run with `yarn test:common` and `yarn test:core`.
+The core and several other packages have unit tests which are can be run all together by running `yarn test` from the root directory, or individually by running it from the package directory.
 
 Unit tests are co-located with the files which they test, and have the suffix `.spec.ts`.
 
-#### Server e2e Tests
+#### End-to-end Tests
 
-The server has e2e tests which test the API with real http calls and against a real Sqlite database powered by [sql.js](https://github.com/kripken/sql.js/). 
-The tests are run with `yarn test:e2e`
+Certain packages have e2e tests, which are located at `/packages/<name>/e2e/`. All e2e tests can be run by running `yarn e2e` from the root directory, or individually by running it from the package directory.
 
-The e2e tests are located in [`/packages/core/e2e`](./packages/core/e2e). Each test suite (file) has the suffix `.e2e-spec.ts`. The first time the e2e tests are run,
-sqlite files will be generated in the `__data__` directory. These files are used to speed up subsequent runs of the e2e tests. They can be freely deleted
-and will be re-created the next time the e2e tests are run.
+e2e tests use the `@vendure/testing` package. For details of how the setup works, see the [Testing docs](https://www.vendure.io/docs/developer-guide/testing/)
 
 When **debugging e2e tests**, set an environment variable `E2E_DEBUG=true` which will increase the global Jest timeout and allow you to step through the e2e tests without the tests automatically failing due to timeout.
 
-#### Admin UI Unit Tests
-
-The Admin UI has unit tests which are run with `yarn test:admin-ui`.
-
-Unit tests are co-located with the files which they test, and have the suffix `.spec.ts`.
-
 ### Release Process
 
 All packages in this repo are released at every version change (using [Lerna's fixed mode](https://github.com/lerna/lerna#fixedlocked-mode-default)). This simplifies both the development (tracking multiple disparate versions is tough) and also the developer experience for users of the framework (it is simple to see that all packages are up-to-date and compatible).
@@ -135,46 +130,6 @@ Finally the command will create changelog entries for this release.
 
 The reason we do not rely on Lerna to push the release to Git is that this repo has a lengthy pre-push hook which runs all tests and builds the admin ui. This long wait then invalidates the npm OTP and the publish will fail. So the solution is to publish first and then push.
 
-
-## User Guide
-
-TODO: Move this info to the docs
-
-### Localization
-
-Vendure server will detect the most suitable locale based on the `Accept-Language` header of the client.
-This can be overridden by appending a `lang` query parameter to the url (e.g. `http://localhost:3000/api?lang=de`). 
-
-All locales in Vendure are represented by 2-character [ISO 639-1 language codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
-
-Translations for localized strings are located in the [i18n/messages](./packages/core/src/i18n/messages) directory.
-
-### Errors
-
-All errors thrown by the Vendure server can be found in the [errors.ts file](./packages/core/src/common/error/errors.ts). 
-
-All errors extend from `I18nError`, which means that the error messages are localized as described above. Each error type
-has a distinct code which can be used by the front-end client in order to correctly handle the error.
-
-### Orders Process
-
-The orders process is governed by a finite state machine which allows each Order to transition only from one valid state
-to another, as defined by the [OrderState definitions](packages/core/src/service/helpers/order-state-machine/order-state.ts):
-
-```TypeScript
-export type OrderState =
-    | 'AddingItems'
-    | 'ArrangingPayment'
-    | 'PaymentAuthorized'
-    | 'PaymentSettled'
-    | 'OrderComplete'
-    | 'Cancelled';
-```
-
-This process can augmented with extra states according to the needs of the business, and these states are defined
-in the `orderProcessOptions` property of the VendureConfig object which is used to bootstrap Vendure. Additional
-logic can also be defined which will be executed on transition from one state to another.
-
 ## License
 
 MIT

docs/content/docs/developer-guide/channels.md

@@ -0,0 +1,27 @@
+---
+title: "Channels"
+showtoc: true
+---
+
+# Channels
+
+Channels are a feature of Vendure which allows multiple sales channels to be represented in a single Vendure instance. A Channel allows you to:
+
+* Set a channel-specific currency, tax and shipping defaults
+* Assign only specific Products to the Channel (with Channel-specific prices)
+* Create Administrator roles limited to the Channel
+* Assign only specific Promotions, Collections & ShippingMethods to the Channel (to be implemented)
+
+Every Vendure server always has a **default Channel**, which contains _all_ entities. Subsequent channels can then contain a subset of the above entities.
+
+Use-cases of Channels include:
+
+* Multi-region stores, where there is a distinct website for each territory with its own available inventory, pricing, tax and shipping rules.
+* Creating distinct rules and inventory for different sales channels such as Amazon.
+* Specialized stores offering a subset of the main inventory.
+
+## Multi-Tenant (Marketplace) Support
+
+In its current form, the Channels feature is not suitable for a multi-tenant or marketplace solution. This is because many entities are still shared across all Channels, e.g. Orders, Customers, Assets.
+
+Multi-tenancy could still be achieved through a dedicated plugin, but would require significant custom work. An out-of-the-box solution will be considered for a future plugin offering.

docs/content/docs/storefront/shop-api-guide.md

@@ -12,6 +12,17 @@ This is an overview of the GraphQL Shop API, which is used when implementing a s
 This guide only lists some of the more common operations you'll need for your storefront. Please consult [the Shop API reference]({{< relref "/docs/graphql-api/shop" >}}) for a complete guide.
 {{% /alert %}}
 
+## Universal Parameters
+
+There are a couple of query parameters which are valid for all GraphQL operations:
+
+* `languageCode`: This sets the current langauge for the request. Any translatable types (e.g. Products, Facets, Collections) will be returned in that language, if a translation is defined for that language. If not, they will fall back to the default language. The value should be one of the ISO 639-1 codes defined by the [`LanguageCode` enum]({{< relref "language-code" >}}).
+
+  ```text
+  POST http://localhost:3000/shop-api?languageCode=de
+  ```
+* `vendure-token`: If your Vendure instance features more than a single [Channel]({{< relref "channels" >}}), the token of the active Channel can be specified by token as either a query parameter _or_ as a header. The name of the key can be configured by the [`channelTokenKey` config option]({{< relref "vendure-config" >}}#channeltokenkey).
+
 ## Browsing the catalogue
 
 * {{< shop-api-operation operation="collections" type="query" >}}: List available Collections. Useful for creating navigation menus.