Documentation improvements

[paulomarg]

Overview/summary

Now that the library has been released, we noticed a couple of pain points that we can help remedy via documentation. This PR aggregates them so we can address them at once.

1. Document the methods and parameters for the REST and GraphQL clients (using the same table format from the withSession docs).
2. Add a concrete production-valid example of how to use CustomSessionStorage in the session notes. We could show how to implement the callbacks using Redis.
   2.1. We may want to consider adding a few tips (and what-not-to-dos!) on using this feature to help developers choose their preferred method.

Checklist

• I have described this enhancement in a way that is actionable (if possible)

[Wilddata]

It would be nice to have examples/doc to show how to make requests using private apps

[paulomarg]

Thanks @Wilddata! In case anyone ends up here from a search, to use private apps you should set

Shopify.Context.initialize({
  ...
  IS_PRIVATE_APP: true,
});

The clients work the same as for public / custom apps, but you don't need an access token. You could make REST requests like so for private apps:

const client = new Shopify.Clients.Rest(shop);
await client.get({ ... });

We'll add some information around that to the docs as well.

[thecodepixi]

Based on #124 we may also need better documentation around webhooks 🤔

[paulomarg]

I think webhooks are fairly well covered since they're mentioned at the top level of the docs, though it seems a parameter table for them would also be helpful.

The changes you made to the GraphQL client docs should make the purpose of the query param more evident (even if it may never be used for GraphQL), but we could add a very simple example of a query with variables to the docs to make that clearer.

[supa-freak]

It would be highly appreciated to get some example for production.
It would clarify the difference of the SESSION_STORAGE object with its 3 methods and the
ACTIVE_SHOPIFY_SHOPS object (as it is used shopify's widely used node app boilerplate) and how to effectively persist them.

[mitas1]

Maybe I'm just blind but I want to create CustomSessionStorage using typescript. How can I import Session type? import { Session } from @shopify/shopify-api does not work for me.

[mitas1]

I found the way: import { Session } from '@shopify/shopify-api/dist/auth/session'. But cannot we expose it in a more reachable point?

Btw: @paulomarg would not be helpful having some kind of serialization and deserialization of Session so that it will be easier to store and load session tokens? E.g.:

const session: Session = new Session({id: "id"});
const sessionPlainObject = session.serialize() // returns just plain js object
const session2: Session = new Session(sessionPlainObject);

[paulomarg]

Hey folks, thanks for your comments! Here are my thoughts:

• @supa-freak we're adding that Redis-based example to the docs, to make it easier to see how this is supposed to work, but we can't really cover how to store ACTIVE_SHOPIFY_SHOPS because different apps can use different means.
  • That said, Redis is also a valid option for that. You can also store it in your database for a more 'permanent' solution, as long as you make sure to delete it using the APP_UNINSTALLED webhook.
• @mitas1 you can create Session objects using new Shopify.Session.Session(); from the main import.
• Yes, we were actually working on adding support for loading Sessions from a plain object: Allow plain objects in Custom loadSession method #126. With this you should be able to do this:

const session: Session = new Session({id: "id"});

function storeSession(session) {
  MyStorage.store(JSON.stringify(session));
}

function loadSession(id) {
  const json = MyStorage.load(id);
  return JSON.parse(json);
}

So you can just return JSON.parse from your loadSession callback and we'll convert it to a proper Session object for you.

[kato-takaomi-ams]

https://github.com/Shopify/shopify-node-api/blob/main/docs/issues.md#notes-on-session-handling

Actually I had to import Session Class from dist.

src/my_session_storage.ts

- import { SessionStorage } from '@shopify/shopify-api';
+ import { Session } from '@shopify/shopify-api/dist/auth/session';

  async function storeCallback(session: Session): Promise<boolean> { ... }
  async function loadCallback(id: string): Promise<Session | Record<string, unknown> | undefined> { ... }
  async function deleteCallback(id: string): Promise<boolean> { ... }

  const mySessionStorage = new Shopify.Session.CustomSessionStorage(
    storeCallback,
    loadCallback,
    deleteCallback,
  );

[paulomarg]

Thanks @kato-takaomi-ams, we should probably make that easier to use as a type.

[ADTC]

@paulomarg I'm so confused looking at the documentation for over 2 to 3 hours now. I cannot even do the simple task of creating a private app that connects to Shopify Admin API and runs a GraphQL query (or mutation). I don't understand the examples, and they are split up over various pages with no proper guidance on what's what.

In contrast, I got it working with MONEI/Shopify-api-node in 10 minutes or so:

const Shopify = require('shopify-api-node');

const shopify = new Shopify({
  shopName: myShopifyDomain,
  apiKey: api_key,
  password: password
});

await shopify.customer
  .list({ limit: 5 })
  .then((customer) => console.log(customer))
  .catch((err) => console.error(err));

const query = `{
  shop {
    name
  }
}`;

await shopify
  .graphql(query)
  .then((result) => console.log(result))
  .catch((err) => console.error(err));

How can it be so bad here?