Skip to content

Latest commit

 

History

History
196 lines (140 loc) · 6.09 KB

README.md

File metadata and controls

196 lines (140 loc) · 6.09 KB
Raw

shopify-token

Version npm Build Status Coverage Status

This module helps you retrieve an access token for the Shopify REST API. It provides some convenience methods that can be used when implementing the OAuth 2.0 flow. No assumptions are made about your server-side architecture, allowing the module to easily adapt to any setup.

Install

npm install --save shopify-token

API

The module exports a class whose constructor takes an options object.

new ShopifyToken(options)

Creates a new ShopifyToken instance.

Arguments

  • options - A plain JavaScript object, e.g. { apiKey: 'YOUR_API_KEY' }.

Options

  • apiKey - Required - A string that specifies the API key of your app.
  • sharedSecret - Required - A string that specifies the shared secret of your app.
  • redirectUri - Required - A string that specifies the URL where you want to redirect the users after they authorize the app.
  • scopes - Optional - An array of strings or a comma-separated string that specifies the list of scopes e.g. 'read_content,read_themes'. Defaults to 'read_content'.
  • timeout - Optional - A number that specifies the milliseconds to wait for the server to send a response to the HTTPS request initiated by the getAccessToken method before aborting it. Defaults to 60000, or 1 minute.
  • accessMode - Optional - A string representing the API access modes. Set this option to 'per-user' to receive an access token that respects the user's permission level when making API requests (called online access). This is strongly recommended for embedded apps. Defaults to offline access mode.
  • agent - Optional - An HTTPS agent which will be passed to the HTTPS request made for obtaining the auth token. This is useful when trying to obtain a token from a server that has restrictions on internet access.

Return value

A ShopifyToken instance.

Exceptions

Throws a Error exception if the required options are missing.

Example

const ShopifyToken = require('shopify-token');

const shopifyToken = new ShopifyToken({
  sharedSecret: '8ceb18e8ca581aee7cad1ddd3991610b',
  redirectUri: 'http://localhost:8080/callback',
  apiKey: 'e74d25b9a6f2b15f2836c954ea8c1711'
});

shopifyToken.generateNonce()

Generates a random nonce.

Return value

A string representing the nonce.

Example

const nonce = shopifyToken.generateNonce();

console.log(nonce);
// => 212a8b839860d1aefb258aaffcdbd63f

shopifyToken.generateAuthUrl(shop[, scopes[, nonce[, accessMode]]])

Builds and returns the authorization URL where you should redirect the user.

Arguments

  • shop - A string that specifies the name of the user's shop.
  • scopes - An optional array of strings or comma-separated string to specify the list of scopes. This allows you to override the default scopes.
  • nonce - An optional string representing the nonce. If not provided it will be generated automatically.
  • accessMode - An optional string dictating the API access mode. If not provided the access mode defined by the accessMode constructor option will be used.

Return value

A string representing the URL where the user should be redirected.

Example

const url = shopifyToken.generateAuthUrl('dolciumi');

console.log(url);
// => https://dolciumi.myshopify.com/admin/oauth/authorize?scope=read_content&state=7194ee27dd47ac9efb0ad04e93750e64&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&client_id=e74d25b9a6f2b15f2836c954ea8c1711

shopifyToken.verifyHmac(query)

Every request or redirect from Shopify to the client server includes a hmac parameter that can be used to ensure that it came from Shopify. This method validates the hmac parameter.

Arguments

  • query - The parsed query string object.

Return value

true if the hmac is valid, else false.

Example

const ok = shopifyToken.verifyHmac({
  hmac: 'd1c59b480761bdabf7ee7eb2c09a3d84e71b1d37991bc2872bea8a4c43f8b2b3',
  signature: '184559898f5bbd1301606e7919c6e67f',
  state: 'b77827e928ee8eee614b5808d3276c8a',
  code: '4d732838ad8c22cd1d2dd96f8a403fb7',
  shop: 'dolciumi.myshopify.com',
  timestamp: '1452342558'
});

console.log(ok);
// => true

shopifyToken.getAccessToken(hostname, code)

Exchanges the authorization code for a permanent access token.

Arguments

  • hostname - A string that specifies the hostname of the user's shop. e.g. foo.myshopify.com. You can get this from the shop parameter passed by Shopify in the confirmation redirect.
  • code - The authorization Code. You can get this from the code parameter passed by Shopify in the confirmation redirect.

Return value

A Promise which gets resolved with an access token and additional data. When the exchange fails, you can read the HTTPS response status code and body from the statusCode and responseBody properties which are added to the error object.

Example

const code = '4d732838ad8c22cd1d2dd96f8a403fb7';
const hostname = 'dolciumi.myshopify.com';

shopifyToken
  .getAccessToken(hostname, code)
  .then((data) => {
    console.log(data);
    // => { access_token: 'f85632530bf277ec9ac6f649fc327f17', scope: 'read_content' }
  })
  .catch((err) => console.err(err));

License

MIT