2.0.0-beta.0 • Published 7 years ago

@satel/shopify-app-utils v2.0.0-beta.0

Weekly downloads
-
License
MIT
Repository
github
Last release
7 years ago

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

shopifyexpressmiddlewarehmacsignature
jsonwebtokennode-fetchshortid
@infinitebrahmanuniverse/nolb-_sat@everything-registry/sub-chunk-808
2.0.0-beta.0

7 years ago

1.1.0-beta.0

7 years ago

1.0.0-beta.2

7 years ago

1.0.0-beta.1

7 years ago

1.0.0-beta.0

7 years ago

0.0.1-beta.6

7 years ago

0.0.1-beta.1

7 years ago