Adjust docs to reflect returned session from #217

Add docs reference to changelog
Shopify · Oct 27, 2021 · e3e3c2a · e3e3c2a
1 parent 77035cc
commit e3e3c2a
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 18 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,7 +20,11 @@ and adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 ## [1.4.1] - 2021-06-11
 
 - Don't include extra params when calculating local hmac [#196](https://github.com/Shopify/shopify-node-api/pull/196)
+- Add a 5 second `clockTolerance` to fix `jwt not active` error [#227](https://github.com/Shopify/shopify-node-api/pull/227)
+- [Breaking] Change default for OAuth.beginAuth to online sessions [#203](https://github.com/Shopify/shopify-node-api/pull/203)
+  - see [oauth.md](https://github.com/Shopify/shopify-node-api/blob/main/docs/usage/oauth.md) for updated docs
 - [Breaking] Return and delete session in `validateAuthCallback` [#217](https://github.com/Shopify/shopify-node-api/pull/217)
+  - see [oauth.md](https://github.com/Shopify/shopify-node-api/blob/main/docs/usage/oauth.md) for updated usage
 - [Breaking] Extract `addHandler` and `getHandler` methods for webhooks out of `register` [#205](https://github.com/Shopify/shopify-node-api/pull/205)
 - [Breaking] Sessions no longer default to `false` for `isOnline` [#169](https://github.com/Shopify/shopify-node-api/pull/169)
 - Required `Session` arguments must be passed to the constructor [#169](https://github.com/Shopify/shopify-node-api/pull/169)

diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -111,6 +111,8 @@ First of all, in your `src/index.ts` file, you'll need to set up your applicatio
 
 While setting up `Context`, you'll be able to set [which version of the Admin API](https://shopify.dev/concepts/about-apis/versioning) your app will be using. All supported versions are available in `ApiVersion`, including `'unstable'`. The `Context.API_VERSION` setting will be applied to all requests made by the library.
 
+(See [oauth](./usage/oauth.md#add-your-oauth-callback-route) for use of `ACTIVE_SHOPIFY_SHOPS`)
+
 <details>
   <summary>Node.js</summary>
 
@@ -145,14 +147,13 @@ async function onRequest(
   const pathName: string | null = url.parse(req_url).pathname;
   const queryString: string = String(url.parse(req_url).query);
   const query: Record<string, any> = querystring.parse(queryString);
+  // Storing the currently active shops in memory will force them to re-login when your server restarts. You should
+  // persist this object in your app.
+  const ACTIVE_SHOPIFY_SHOPS = {};
 
   if (pathName === '/') {
-    // check if we're logged in/authorized
-    const currentSession = await Shopify.Utils.loadCurrentSession(
-      request,
-      response,
-    );
-    if (!currentSession) {
+    // This shop hasn't been seen yet, go through OAuth to create a session
+    if (ACTIVE_SHOPIFY_SHOPS[shop] === undefined) {
       // not logged in, redirect to login
       response.writeHead(302, {Location: `/#`});
       response.end();
@@ -189,9 +190,22 @@ Shopify.Context.initialize({
   IS_EMBEDDED_APP: {boolean},
   API_VERSION: ApiVersion.{version} // all supported versions are available, as well as "unstable" and "unversioned"
 });
+// Storing the currently active shops in memory will force them to re-login when your server restarts. You should
+// persist this object in your app.
+const ACTIVE_SHOPIFY_SHOPS = {};
 
 // the rest of the example code goes here
 
+app.get("/", async (req, res) => {
+   // This shop hasn't been seen yet, go through OAuth to create a session
+  if (ACTIVE_SHOPIFY_SHOPS[shop] === undefined) {
+     // not logged in, redirect to login
+    res.redirect(`/#`);
+  } else {
+    // do something amazing with your application!
+  }
+}
+
 app.listen(3000, () => {
   console.log('your app is now listening on port 3000');
 });

diff --git a/docs/usage/oauth.md b/docs/usage/oauth.md
@@ -8,14 +8,13 @@ To do that, you can follow the steps below.
 
 The route for starting the OAuth process (in this case `/#`) will use the library's `beginAuth` method. The method will return a URI that will be used for redirecting the user to the Shopify Authentication screen.
 
-| Parameter | Type | Required? | Default Value | Notes |
-| --- | --- | :---: | :---: | --- |
-| `request` | `http.IncomingMessage` | Yes | - | The HTTP Request. |
-| `response` | `http.ServerResponse` | Yes | - | The HTTP Response. |
-| `shop` | `string` | Yes | - | A Shopify domain name in the form `{exampleshop}.myshopify.com`. |
-| `redirectPath` | `string` | Yes | - | The redirect path used for callback with a leading `/`. The route should be allowed under the app settings. |
-| `isOnline` | `bool` | No | `true` | `true` if the session is online and `false` otherwise. |
-
+| Parameter      | Type                   | Required? | Default Value | Notes                                                                                                       |
+| -------------- | ---------------------- | :-------: | :-----------: | ----------------------------------------------------------------------------------------------------------- |
+| `request`      | `http.IncomingMessage` |    Yes    |       -       | The HTTP Request.                                                                                           |
+| `response`     | `http.ServerResponse`  |    Yes    |       -       | The HTTP Response.                                                                                          |
+| `shop`         | `string`               |    Yes    |       -       | A Shopify domain name in the form `{exampleshop}.myshopify.com`.                                            |
+| `redirectPath` | `string`               |    Yes    |       -       | The redirect path used for callback with a leading `/`. The route should be allowed under the app settings. |
+| `isOnline`     | `bool`                 |    No     |    `true`     | `true` if the session is online and `false` otherwise.                                                      |
 
 <details>
 <summary>Node.js</summary>
@@ -56,7 +55,13 @@ http.createServer(onRequest).listen(3000);
 
 ```ts
 app.get('/#', async (req, res) => {
-  let authRoute = await Shopify.Auth.beginAuth(req, res, SHOP, '/auth/callback', false);
+  let authRoute = await Shopify.Auth.beginAuth(
+    req,
+    res,
+    SHOP,
+    '/auth/callback',
+    false,
+  );
   return res.redirect(authRoute);
 });
 ```
@@ -65,7 +70,7 @@ app.get('/#', async (req, res) => {
 
 ## Add your OAuth callback route
 
-After the app is authenticated with Shopify, the Shopify platform will send a request back to your app using this route (which you provided as a parameter to `beginAuth`, above). Your app will now use the provided `validateAuthCallback` method to finalize the OAuth process. This method _has no return value_, so you should `catch` any errors it may throw.
+After the app is authenticated with Shopify, the Shopify platform will send a request back to your app using this route (which you provided as a parameter to `beginAuth`, above). Your app will now use the provided `validateAuthCallback` method to finalize the OAuth process. This method returns the `session` object.
 
 <details>
 <summary>Node.js</summary>
@@ -75,8 +80,10 @@ After the app is authenticated with Shopify, the Shopify platform will send a re
 
   if (pathName === '/auth/callback') {
     try {
-      await Shopify.Auth.validateAuthCallback(request, response, query as AuthQuery);
+      const session = await Shopify.Auth.validateAuthCallback(request, response, query as AuthQuery);
+      ACTIVE_SHOPIFY_SHOPS[SHOP] = session.scope;
 
+      console.log(session.accessToken);
       // all good, redirect to '/'
       response.writeHead(302, { 'Location': '/' });
       response.end();
@@ -107,11 +114,13 @@ http.createServer(onRequest).listen(3000);
 ```ts
 app.get('/auth/callback', async (req, res) => {
   try {
-    await Shopify.Auth.validateAuthCallback(
+    const session = await Shopify.Auth.validateAuthCallback(
       req,
       res,
       req.query as unknown as AuthQuery,
     ); // req.query must be cast to unkown and then AuthQuery in order to be accepted
+    ACTIVE_SHOPIFY_SHOPS[SHOP] = session.scope;
+    console.log(session.accessToken);
   } catch (error) {
     console.error(error); // in practice these should be handled more gracefully
   }