Skip to content

Latest commit

 

History

History
201 lines (152 loc) · 5.42 KB

README.md

File metadata and controls

201 lines (152 loc) · 5.42 KB

SHOPLINE SDK

Installation

yarn add https://github.com/shoplineapp/shopline-sdk-node.git

Feature

Developer OAuth

Configuration

const developerOAuth = new DeveloperOAuth({
  endpoint: process.env.DEVELOPER_OAUTH_ENDPOINT,
  clientId: process.env.DEVELOPER_OAUTH_APP_CLIENT_ID,
  clientSecret: process.env.DEVELOPER_OAUTH_APP_CLIENT_SECRET,
  redirectUri: process.env.DEVELOPER_OAUTH_APP_REDIRECT_URI,
  scope: process.env.DEVELOPER_OAUTH_APP_SCOPE,
  logger: log,
}),

API References

Authenticate Middleware
  • authenticate
    • The following fields would be added into res.locals
      • res.locals.currentMerchantId
      • res.locals.currentToken
      • res.locals.performerId
      • res.locals.performerMerchantIds
await developerOAuth.authenticate(req, res, next)

developerOAuth.authenticate will inject currentMerchantId, currentToken, performerId and performerMerchantIds into req.locals

Callback Middleware
  • callback
    • Used as a callback handler under redirect_uri to inject access token to express session
    • Exchanged token would be added to req.session.accessTokens
await developerOAuth.callback(req, res, next)

⚠️ For development environment with multiple machines: Session redis should be separated for multiple machines, as we will attempt to get latest token for redirect uri, and it may cause problem when redirecting.

developerOAuth.callback will handle OAuth callbacks and inject accessTokens into req.session.accessTokens

Error Handler

When request passing through authenticate middleware, error may throw during the authentication process. You can override the default error handling by pass in middlewares to DeveloperOAuth constructor

const myErrorHandleFunc = async (req, res, next, error) => {
  req.session.destroy();
  res.redirect('/');
}

const errorHandler = {
  ConfigurationError: myErrorHandleFunc,
  SessionError: myErrorHandleFunc,
  RefreshTokenError: myErrorHandleFunc,
  DecodeTokenError: myErrorHandleFunc,
}

const developerOAuth = new DeveloperOAuth({
  endpoint: process.env.DEVELOPER_OAUTH_ENDPOINT,
  clientId: process.env.DEVELOPER_OAUTH_APP_CLIENT_ID,
  clientSecret: process.env.DEVELOPER_OAUTH_APP_CLIENT_SECRET,
  redirectUri: process.env.DEVELOPER_OAUTH_APP_REDIRECT_URI,
  scope: process.env.DEVELOPER_OAUTH_APP_SCOPE,
  errorHandler: errorHandler,
  logger: log,
}),
Ensure Login Session Configuration

DeveloperOAuth will ensure the access token login session with oauth service behind by default. But this requires your app hosted in the same domain of the oauth service. i.e. *.shoplineapp.com. If your app is hosted outside our domain, or you don't want the feature, you can disable it by setting ensureLoginSession to false when initialize.

const developerOAuth = new DeveloperOAuth({
  endpoint: process.env.DEVELOPER_OAUTH_ENDPOINT,
  clientId: process.env.DEVELOPER_OAUTH_APP_CLIENT_ID,
  clientSecret: process.env.DEVELOPER_OAUTH_APP_CLIENT_SECRET,
  redirectUri: process.env.DEVELOPER_OAUTH_APP_REDIRECT_URI,
  scope: process.env.DEVELOPER_OAUTH_APP_SCOPE,
  ensureLoginSession: false,
  logger: log,
}),
Trust Proxy

If your app is behind proxy, please set trust proxy in express. Without doing so, it might affect the protocol, ip and host of the Request object passed in when express needs to read real values from X-Forward- headers

ref: https://expressjs.com/en/guide/behind-proxies.html

app.set('trust proxy', 1)

OpenAPI Client

Configuration
const openApiClient = new OpenApiClient({
  baseURL: process.env.OPEN_API_ENDPOINT,
  accessToken: res.locals.currentToken,
  logger: log,
});

API References

  • Get Merchant 
    await openApiClient.getMerchant(merchantId, fields)
  • Get Staff 
    await openApiClient.getStaff(merchantId, fields, include_fields)
  • Get Staff Permission 
    await openApiClient.getStaffPermission(merchantId, fields)
  • request (axios request config) 
    await openApiClient.request(options)

App Bridge

Configuration

const appBridge = new AppBridge({
  developerOAuth: new DeveloperOauth({...}),
  tokenStore: new MyTokenStore()
})

TokenStore

Token store is responsible to saving and fetch token data from storage. You need to implement the interface and pass to AppBridge when initializing it.

interface TokenStoreInterface {
  async fetch(clientId: string, merchantId: string, staffId: string): Promise<any>
  async save(clientId: string, merchantId: string, staffId: string, tokenData: any): Promise<any>
}

API References

StartAuth Middleware
  • startAuth
    • Used as starting point handler of OAuth flow triggered by app bridge frontend
await appBridge.startAuth()
Callback Middleware
  • callback
    • Used as a callback handler under redirect_uri to store access token through tokenStore provided
await appBridge.callback()
Authenticate Middleware
  • authenticate
    • Validating the session token passed along with request
    • Ensure access token exists in tokenStore if needed
    • The following fields would be added into res.locals
      • res.locals.currentMerchantId
      • res.locals.currentToken
      • res.locals.performerId
await appBridge.authenticate( { requireAccessToken: <bool> } )