Improve docs

Author: SpaceK33z

README.md

@@ -1,10 +1,10 @@
 # GraphQL Authentication
 
-**Work in progress, do not use yet**
+_Previously called Prisma Auth_
 
 A very opinionated user authentication package for [GraphQL](https://graphql.org/). It uses old-school email/password authentication.
 
-This package does not access your data layer (e.g. an ORM); for that you need to write a _adapter_ (which is not hard to do).
+This package provides **a GraphQL schema and GraphQL resolvers** for everything you need related to authentication. It does not access your data layer (e.g. an ORM); for that you need to write an _adapter_ (which is not hard to do).
 If you use Prisma, there is already an adapter for you, **[graphql-authentication-prisma](https://github.com/Volst/graphql-authentication/tree/master/packages/graphql-authentication-prisma)**.
 
 **Features:**
@@ -19,7 +19,7 @@ If you use Prisma, there is already an adapter for you, **[graphql-authenticatio
 
 # Motivation
 
-Adding user authentication seems simple; there are lots of examples on how to write a "login" and a "signup" resolver. You implement it in your own project and continue working. After a while you'll have users forgetting their password so you need to build something for that. Then you want to be able to invite users, ... you get the idea. After a while you have a lot of boilerplate code related to user authentication.
+Adding user authentication seems simple; there are lots of examples on how to write a "login" and a "signup" resolver. You implement it in your own project and continue working. After a while you'll have users forgetting their password so you need to build something for that. Then you want to be able to invite users, ... you get the idea. In the end you have a lot of boilerplate code related to user authentication.
 
 The intention with this package is **to let you write as less user-related code as possible**, while being flexible enough to support different use cases like open sign up, invitation-only signup, extra fields on the User model etc.
 
@@ -36,16 +36,80 @@ npm i graphql-authentication email-templates
 
 # Usage
 
+## Using the schema
+
+In your own GraphQL schema you can import all the types this package provides:
+
+```graphql
+# import Query.*, Mutation.* from "node_modules/graphql-authentication/schema.graphql"
+```
+
+> This only works if you use [graphql-import](https://github.com/prismagraphql/graphql-import). If you are using graphql-yoga this will work out of the box!
+
+Alternatively you can only import the types you want to expose, for example:
+
+```graphql
+# import Query.currentUser, Mutation.signupByInvite, Mutation.inviteUser, Mutation.login from "node_modules/graphql-authentication/schema.graphql"
+```
+
+## Configuration
+
+We need to add some configuration to get this package to work. The following example uses [graphql-yoga](https://github.com/graphcool/graphql-yoga/), but it should also work with Apollo Server.
+
 ```js
-class GraphqlAuthenticationSequelizeAdapter {
-  //
-}
+import { graphqlAuthenticationConfig } from 'graphql-authentication';
+import * as Email from 'email-templates';
+
+const server = new GraphQLServer({
+  typeDefs: './schema.graphql',
+  resolvers,
+  context: req => ({
+    ...req,
+    graphqlAuthentication: graphqlAuthenticationConfig({
+      // Required, see for more info the "Writing an adapter" section on this page
+      adapter: new GraphqlAuthenticationSequelizeAdapter(),
+      // Required, used for signing JWT tokens
+      secret: 'wheredidthesodago',
+      // Optional, for sending emails with email-templates (https://www.npmjs.com/package/email-templates)
+      mailer: new Email(),
+      // Optional, the URL to your frontend which is used in emails
+      mailAppUrl: 'http://example.com'
+    })
+  })
+});
+```
+
+## Adding the resolvers
 
-graphqlAuthentication: GraphqlAuthenticationSequelizeAdapter({
-  adapter: new GraphqlAuthentication()
+You need to expose the resolvers this package provides for you to your own GraphQL server. For example:
+
+```js
+import { authQueries, authMutations } from 'graphql-authentication';
+
+const resolvers = {
+  Query: {
+    ...authQueries
+  },
+  Mutation: {
+    ...authMutations
+  }
+};
+```
+
+## Emails
+
+Lastly, this project can optionally send emails for you (e.g. the password reset link). [`email-templates`](https://www.npmjs.com/package/email-templates) is used for this. Be sure to configure it in the options:
+
+```js
+import * as Email from 'email-templates';
+
+graphqlAuthentication: graphqlAuthenticationConfig({
+  mailer: new Email()
 });
 ```
 
+However, this package does not provide the email templates itself for you, since these differ too much. You can [**copy the email templates**](./example/emails) from our example to get started.
+
 # Documentation
 
 ## GraphQL endpoints
@@ -188,3 +252,15 @@ graphqlAuthentication: graphqlAuthenticationConfig({
   requiredConfirmedEmailForLogin: true
 });
 ```
+
+## Writing an adapter
+
+An adapter sits between GraphQL Authentication and your own ORM/database thingy. If you are using Prisma, there is already [graphql-authentication-prisma](https://github.com/Volst/graphql-authentication/tree/master/packages/graphql-authentication-prisma) for you.
+
+However, if you don't use Prisma, that's totally fine! Writing an adapter shouldn't take very long.
+
+In [the tests](https://github.com/Volst/prisma-auth/blob/refactor/packages/graphql-authentication/src/__tests__/setup.ts) there is a good example of an adapter.
+
+You can keep the adapter class directly in your own project, make a separate npm package for it or write a PR to add it here (please do)!
+
+> TODO: this section needs to be improved

packages/graphql-authentication-prisma/README.md

@@ -15,58 +15,25 @@ npm i graphql-authentication graphql-authentication-prisma email-templates
 
 ## Step 1
 
-In your Prisma `datamodel.graphql` file, add this [User model](./example/datamodel.graphql).
+Read the [Usage](https://github.com/Volst/graphql-authentication/blob/master/README.md#usage) section in the full documentation first.
 
 ## Step 2
 
-In your `schema.graphql` for your own server, add something like the following (you can also import specific endpoints only):
-
-```graphql
-# import Query.*, Mutation.* from "node_modules/graphql-authentication/schema.graphql"
-```
-
-## Step 3
-
-In your server we now need to map these types to resolvers and pass in some options. The following example uses [graphql-yoga](https://github.com/graphcool/graphql-yoga/), but it should also work with Apollo Server.
+After configuring the basics, you can now add this package as an adapter. Pseudo-code example:
 
 ```js
-import { authQueries, authMutations, graphqlAuthenticationConfig } from 'graphql-authentication';
 import { GraphqlAuthenticationPrismaAdapter } from 'graphql-authentication-prisma';
-import * as Email from 'email-templates';
-
-const resolvers = {
-  Query: {
-    ...authQueries
-  },
-  Mutation: {
-    ...authMutations
-  }
-};
 
-const server = new GraphQLServer({
-  typeDefs: './schema.graphql',
-  resolvers,
-  context: req => ({
-    ...req,
-    db: new Prisma({...}),
-    graphqlAuthentication: graphqlAuthenticationConfig({
-      adapter: new GraphqlAuthenticationPrismaAdapter({
-        // Optional, defaults to 'db'
-        prismaContextName: 'db'
-      }),
-      // Required, used for signing JWT tokens
-      secret: 'wheredidthesodago',
-      // Optional, for sending emails with email-templates (https://www.npmjs.com/package/email-templates)
-      mailer: new Email(),
-      // Optional, the URL to your frontend which is used in emails
-      mailAppUrl: 'http://example.com',
-    })
+graphqlAuthentication: graphqlAuthenticationConfig({
+  adapter: new GraphqlAuthenticationPrismaAdapter({
+    // Optional, defaults to 'db'
+    prismaContextName: 'db'
   })
 });
 ```
 
-## Step 4
+## Step 3
 
-Lastly, if you want to send emails, you should copy the email templates to your own project. Checkout [the example email templates](./example/emails).
+In your Prisma `datamodel.graphql` file, add this [User model](./example/datamodel.graphql). Run `prisma deploy` to run the migrations.
 
 ### [Full Documentation](https://github.com/Volst/graphql-authentication/blob/master/README.md#documentation)

packages/graphql-authentication/src/__tests__/setup.ts

@@ -1,7 +1,13 @@
 import { GraphQLServer } from 'graphql-yoga';
 import { GraphQLClient } from 'graphql-request';
-import { graphqlAuthenticationConfig, authQueries, authMutations } from '..';
-import { GraphqlAuthenticationAdapter, User, ID } from '..';
+import {
+  graphqlAuthenticationConfig,
+  authQueries,
+  authMutations,
+  GraphqlAuthenticationAdapter,
+  User,
+  ID
+} from '..';
 
 export class FakeAdapter implements GraphqlAuthenticationAdapter {
   users: User[] = [
@@ -35,16 +41,14 @@ export class FakeAdapter implements GraphqlAuthenticationAdapter {
     return Promise.resolve(this.users.some(user => user.email === email));
   }
   createUserBySignup(ctx: any, data: any) {
-    const lastUser = this.users[this.users.length - 1];
     const user = { id: this._generateId(), ...data };
     this.users.push(user);
-    return user;
+    return Promise.resolve(user);
   }
   createUserByInvite(ctx: any, data: any) {
-    const lastUser = this.users[this.users.length - 1];
     const user = { id: this._generateId(), ...data };
     this.users.push(user);
-    return user;
+    return Promise.resolve(user);
   }
   async updateUserLastLogin(ctx: any, userId: string, data: any) {
     const user = await this.findUserById(ctx, userId);