Ninety-nine Pitchers of Malt

    @satel/shopify-app-utils

    2.0.0-beta.0 • Public • Published

    Disclaimers

    This is beta software. Use in production at your own risk.

    Currently validateRequest and handleCallback only support online mode.

    About

    Provides functionality for some of the more tedious requirements when building a Shopify app such as consistent hmac validation behavior for authentication, proxies, etc. Provided as general use functions but can easily be adapted for use as express middleware.

    This is not meant to be a batteries included solution. For that checkout shopify-express

    Installation

    Note: requires NodeJS >= 8.6.0

    npm install @satel/shopify-app-utils

    or

    yarn add @satel/shopify-app-utils

    Documentation

    Table of Contents

    createOAuth

    Creates instances of validateRequest & handleCallback wrapped in a closure

    Parameters

    • options object
      • options.host string the base url of the app
      • options.redirectRoute string the route where oauth2 redirects will be handled
      • options.scope Array<string> scope your app will require
      • options.key string shopify app api key
      • options.secret string shopify app shared secret
      • options.online boolean do you require an online token (optional, default false)
      • options.offline boolean do you require an offline token (optional, default false)

    Examples

    const oauth = require('@satel/shopify-app-utils');
    
    const { validateRequest, handleCallback } = oauth.create({
      host: 'https://my-app.com',
      redirectRoute: '/redirect',
      scope: ['read_products'],
      key: 'MY_KEY',
      secret: 'MY_SECRET',
      online: true,
    });

    validateRequest

    TODO

    Parameters

    validateRequest~generateNonce

    Used to generate a nonce to be used in a redirect url

    Type: Function

    Parameters

    Returns string

    validateRequest~onAuthenticated

    Called when a request is authorized

    Type: Function

    Parameters

    • options object
      • options.shop string the .myshopify domain
      • options.appScope Array<string> the application scope (when jwt was generated)
      • options.userScope (Array<string> | undefined) the user scope (only applicable to online tokens)
      • options.decoded object decoded body of the jwt

    validateRequest~onRedirect

    Called when a redirect is required

    Type: Function

    Parameters

    • options object
      • options.url string the redirect url
      • options.html string a js based redirect for use in iframes

    validateRequest~onFailed

    Called when unable to redirect or authorize

    Type: Function

    Parameters

    handleCallback

    Parameters

    handleCallback~validateNonce

    Used to validate a previously generated nonce

    Type: Function

    Parameters

    • options object
      • options.shop string the .myshopify domain
      • options.nonce string the retrieved nonce

    Returns (boolean | Promise<boolean>)

    handleCallback~onAuthenticated

    Called when a request is authorized

    Type: Function

    Parameters

    • options object
      • options.token string the shopify access token
      • options.online string indicates if the current token is online or offline
      • options.jwt string a jwt token
      • options.shop string the .myshopify domain
      • options.appScope Array<string> the application scope (when jwt was generated)
      • options.userScope (Array<string> | undefined) the user scope (only applicable to online tokens)

    handleCallback~onFailed

    Called when request cannot be authorized

    Type: Function

    Parameters

    validateHMAC

    Parses the url and validates the HMAC provided by shopify

    Parameters

    Examples

    // Import
    import { oauth } from '@satel/shopify-app-utils';
    const { oauth } = require('@satel/shopify-app-utils');
    const { validateHMAC } = oauth;
    
    // Directly
    const validateHMAC = require('@satel/shopify-app-utils/oauth/hmac');
    
    // General
    const validHMAC = validateHMAC({ url, secret: 'hush' });
    
    // Express
    app.use(req => {
      const validHMAC = validateHMAC({ url: req.url, secret: 'hush' });
    });

    Returns boolean

    generateRedirect

    Generates the url / html based redirect to start the oauth2 process

    Parameters

    Examples

    // Full Page App
    res.redirect(
      generateRedirect({
        shop: 'example.myshopify.com',
        apiKey: 'MY_APP_API_KEY',
        nonce: 'unique-request-identifier',
        redirect: 'https://my-app.com/path/to/redirect',
        scope: ['read_products', 'write_products', 'etc'],
      }),
    );
    
    // Embedded online app
    res.send(
      generateRedirect({
        shop: 'example.myshopify.com',
        apiKey: 'MY_APP_API_KEY',
        nonce: 'unique-request-identifier',
        redirect: 'https://my-app.com/path/to/redirect',
        scope: ['read_products', 'write_products', 'etc'],
        online: true,
        iframe: true,
      }),
    );

    Returns string

    generateJSRedirect

    Pass in a url and it returns an html document that will redirect top rather than the iFrame

    Parameters

    Returns string

    validateDomain

    Checks if a string is a valid .myshopify.com domain (exclude the protocol)

    Parameters

    Examples

    const validDomain = validateDomain({ shop: 'my-shop.myshopify.com' });

    Returns boolean

    validateTimestamp

    Verifies the shopify timestamp generally provided with authenticated responses from shopify

    Parameters

    • $0 Object
      • $0.timestamp
      • $0.margin (optional, default 60)
    • options Object
    • timestamp string
    • margin number Timestamp must be withing margin of now (optional, default 60)

    Examples

    const validTimestamp = validateTimestamp({ timestamp: '1533160800', margin: 60 * 5 });

    Returns boolean

    validateSignature

    Parses the url and validates proxied requests from Shopify

    Parameters

    Examples

    // Import
    import { proxy } from '@satel/shopify-app-utils';
    const { proxy } = require('@satel/shopify-app-utils');
    const { validateSignature } = proxy;
    
    // Directly
    const validateSignature = require('@satel/shopify-app-utils/oauth/proxy');
    
    // General
    const valid = validateSignature({ url, secret: 'hush' });
    
    // Express
    app.use(req => {
      const valid = validateSignature({ url: req.url, secret: 'hush' });
    });

    Returns boolean

    computeHMAC

    Produces a hex encoded Sha256 hmac

    Parameters

    Examples

    const hash = computeHMAC({
      text: 'message',
      secret: 'hush',
    });

    Returns string

    Install

    npm i @satel/shopify-app-utils

    DownloadsWeekly Downloads

    7

    Version

    2.0.0-beta.0

    License

    MIT

    Unpacked Size

    60.4 kB

    Total Files

    35

    Last publish

    Collaborators

    • dexterchan94
    • qw-in
    • satelcreative