Golden Hippo Salesforce Service

Overview

This package is an SDK around the REST API available within the Golden Hippo Salesforce instance. It provides a simple interface to interact with this API, including request validation and error handling (failed responses simply throw an exception).

Installation

To install this package, simply run:

npm install @goldenhippo/hippo-salesforce-service

Usage

To use this package, you will need the generic access credentials for the TouchCR application (Salesforce package). Once you establish these credentials, you can use the SalesforceService class to retrieve brand-specific details and credentials. Future requests should be used with the brand-specific credentials. Below is a simple demo of initiating the SDK and some simple usage of the services:

import {
    ApiConfiguration,
    SalesforceService,
    AccountService,
    PaymentOptionService,
    OrderService,
    ServiceConfig
} from "@goldenhippo/hippo-salesforce-service";

const config = new ApiConfiguration({
    apiUrl: 'https://example.salesforce.com',
    genericLogin: '[email protected]',
    genericPass: 'passwordTOKEN',
    clientID: 'clientID',
    clientSecret: 'clientSecret',
})

const salesforceService = new SalesforceService(config);

class Demo {
    async test() {
        // Typically, you would cache this data in redis or similar
        const brandSettings = await salesforceService.getBrandSettings();

        // This assumes you "find" a match. You should handle the case where the brand is not found
        const myBrand = brandSettings.find(brand => brand.name === 'myBrand');

        // Typically, you would also cache this (one for each brand) and refresh it periodically (e.g. every 30min)
        const brandSpecificAccessToken = await salesforceService.getBrandedAccessToken({
            clientId: myBrand?.auth.clientId || '', // You should null check yourself instead
            clientSecret: myBrand?.auth.clientSecret || '' // You should null check yourself instead
        })

        /**
         * Once you have a branded access token, you can define a ServiceConfig to reuse more easily
         * When handling a request, you would typically use the brand specific access token. Failing to pass the brand
         * specific access token will cause the records to be created/modified by the Generic API User.
         *
         * !!! WARNING !!!
         * You can actually generate an OAuth token for ANY user in the Salesforce Org.
         * This would allow you to operate under their permissions. Those permissions are
         * likely more restricted so it would be more likely to return errors.
         *
         */
        const serviceConfig: ServiceConfig = {
            salesforceService: salesforceService,
            accessToken: brandSpecificAccessToken
        }

        const accountService = new AccountService(serviceConfig)

        const account = await accountService.getAccountByEmail({
            email: '[email protected]',
            brand: 'Golden Hippo'
        })

        const paymentOptionService = new PaymentOptionService(serviceConfig)

        const paymentOptions = await paymentOptionService.getAllPaymentOptionsByAccount(account.id, account.brandName)
        console.log(paymentOptions)

        const brandedOrderService = new OrderService(serviceConfig)

        const orders = await brandedOrderService.getOrdersByAccountId(account.id)
        console.log(orders)
    }
}

Development

This package is a mirror of the Salesforce REST API exposed by the TouchCR package. Any changes made here should only be made if/when that API changes. This package should be kept in sync with the Salesforce API as closely as possible.

Versioning

This package uses SemVer for versioning. For the versions available, see the tags on this repository.

When changes are made to the underlying API, this package is extended to reflect those changes. However, all efforts are made to ensure non-breaking changes. As such, major version increases should be exceedingly rare.

Documentation

View the full documentation here.

The documentation for this package is generated using TypeDoc. To generate the documentation, run:

npm run docs

The documentation will be generated in the docs directory.