@shoppinggivesos/impact-sdk v0.3.3

About The Project

The ShoppingGives SDK provides all the nessasery methods for the development of custom experiences, mainly focusing on the development of custom widgets, the SDK provides the data needed to power a custom UI.

This SDK does not provide any UI elements only the data needed to power custom UI.

This SDK is in active development and subject to breaking changes.

Built With

• Typescript
• Rollbar
• Vite
• Husky
• Jest

Prerequisites

In order to use the SDK you will need a shoppingGives store id

Getting Starte

To get a local copy up and running follow these simple steps.

Installation

1. Install the NPM package

   npm i @shoppinggivesos/impact-sdk --legacy-peer-deps

Usage

The first thing you need to do after installing the package is select the type of context you want to setup, we currently support two types of context. Cart and Product. if you plan to use the SDK to power a custom experience on the product page then you need to use the ProductHandler, likewise if you plan to power a custom experience on the cart page use the CartHandler.

Initialization:

import { CartHandler, Environments } from '@shoppingGives/widget-sdk';

let config = {
    storeId: '00000000-0000-0000-0000-000000000000', // ShoppingGives store id
    environment: Environments.Production, // ShoppingGives store environment for most people you will select Production here, but if you have a Staging store id, you can test the SDK using your Staging store id.
    testMode: false, // Sets the tracking to be test purchases that do not create a real donation!
    logger: {
        error: (message) => {},
        debug: (message) => {},
        warn: (message) => {},
    }, // Optional: Custom logging implementation, if you omit this param the SDK uses console.log by default.
    persistence: {
        get: (key) => {},
        set: (key, value) => {},
        delete: (key) => {},
    }, // Optional: Custom persistence cache implementation, if you omit this param the SDK uses session storage by default.
};

// bootstrap the client
const client = new CartHandler(config);

// register any events if you want to use the event system vs async / awaiting the methods. (more information can be found below)
// events need to be registered before the initialize method is called.
client.on('SDK::Ready', (data) => {
    // handle SDK::Ready event
});

// initialize the client with current cart state
let data = await client.initialize({
    lineItems: [], // All current line items in the cart or an empty array if no items are in the cart.
    discount: 0, // The discount applied to the cart if any is set. This is the $ amount not the % percentage.
});

Handling Updates

1. We support two main ways to work with our methods, all public facing methods return promises, so you can use async / await or then / catch to retrieve the returned data. for example:

   async / await

   const results = await client.search('Happys Porch', 0, 25);

   then / catch

   let results = [];
   
   client
       .search('Happys Porch', 0, 25)
       .then((data) => {
           results = data;
       })
       .catch((error) => {});

2. Alternatively we have an events system, you can subscribe to the events and handle changes with callback functions

   client.on('Cause::Updated', (data) => {
       // handle the updating of the selected cause.
   });

SDK Events:

Handling Errors

We provide two systems for dealing with errors that can happen inside of the SDK, by default the SDK will throw an error that you will need to catch. the other way you can handle errors is by using the SDK::Error event and setup a callback to handle errors in a centralized place.

The error payload includes a 'type' property that specifies the type of error that occurred. This can be used to distinguish between different types of errors and to tailor your error handling logic accordingly.

try {
    results = await client.search(searchTerm, 0, 25);
} catch (error) {
    // handle error based on the type property:
    switch (error.type) {
      case "ShoppingGivesApiError":
        // handle error, hide UI or show error state
        break;
      case "ShoppingGivesValidationError"
        // handle validation error
      default:
        break;
    }
}

Alternatively you can handle errors by subscribing to the event SDK::Error, the event is emitted whenever an error occurs inside the SDK. This event is intended to provide a mechanism for handling errors that may occur while using the SDK, so that you can gracefully handle or recover from them in your code.

To handle this event, you can add an event listener that gets called whenever the event is emitted. The event listener function should accept an 'error' parameter, which will contain an instance of an error object with additional information about the error.

Here is an example of how you might handle the 'SDK::Error' event:

client.on('SDK::Error', (error) => {
  switch (error.type) {
    case "ShoppingGivesApiError":
      // handle error, hide UI or show error state
      break;
    case "ShoppingGivesValidationError"
      // handle validation error
    default:
      break;
  }
});

WIP, More To Come

Testing

1. Start up the tests

   npm run test