@flipgive/shopcloud

FlipgiveSDK

Shop Cloud

Shop Cloud (The Shop) is FlipGive's drop-in cashback store. If you would like to know more please visit www.flipgive.com/cloud or contact us at [e-mail].

Links of Interest

• FlipGive
• API Documentation

Installation

To begin using @flipgive/shop-cloud, you should have obtained an ID and Secret pair from FlipGive, store these securely so that they are accessible in your application (env variables, etc). If you haven't received credentials, please contact us at [e-mail].

Add the @flipgive/shopcloud package to your package.json:

npm install --save @flipgive/shopcloud git+https://github.com/BetterTheWorld/FlipGiveSDK_node.git

After you have installed the package include the code below to initialize the ShopCloud:

import ShopCloud from '@flipgive/shopcloud';

ShopCloud(shop_cloud_id, shop_cloud_secret).then(shopCloud => { ... });

ShopCloud is now ready to use.

Usage

The main purpose of @flipgive/shopcloud is to generate Tokens to gain access to FlipGive's Shop Cloud API. There are 6 methods on the package's public API.

ShopCloud

This method is used to initialize the SDK, as described on the setup section of this document. It takes 2 arguments, the shop_cloud_id and the shop_cloud_secret.

readToken

This method is used to decode a token that has been generated with your credentials. It takes a single string as an argument and, if able to decode the token, it will return a hash.

token = "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4R0NNIn0..demoToken.g8PZPWb1KDFcAkTsufZq0w@A2DE537C";

shopCloud.readToken(token).then(payload => { console.log(payload) });
=> { "user_data": { "id": 1, "name": "Emmett Brown", "email": "[e-mail]", "country": "USA" } }

identifiedToken

This method is used to generate a token that will identify a user or campaign. It accepts a Payload Object as an argument and it returns an encrypted token.

payload = {
  user_data: user_data,
  campaign_data: campaign_data,
  group_data: group_data,
  organization_data: organization_data
};

shopCloud.identifiedToken(payload).then(token => { console.log(token) });
=> "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4R0NNIn0..demoToken.g8PZPWb1KDFcAkTsufZq0w@A2DE537C"

The variable in this example uses other variables, (user_data, campaign_data, etc.). let's look at each one of them:

• user_data: required when campaign_data is not present in the payload, otherwise optional. It represents the user using the Shop, and must contain:

  • id: required. A string representing the user's ID in your system.
  • email: required. A string with the user's email.
  • name: required. A string with the user's name.
  • country: required. A string with the ISO code of the user's country, which must be 'CAN' or 'USA' at this time.

  user_data = {
    id: 19850703,
    name: "Emmett Brown",
    email: "[e-mail]",
    country: "USA"
  };
  

• campaign_data: Required when user_data is not present in the payload, otherwise optional. It represents the fundraising campaign and it must contain:

  • id: required A string representing the user's ID in your system.
  • name: required A string with the campaign's email.
  • category: required A string with the campaign's category. We will try to match it with one of our existing categories, or assign a default. You can see a list of our categories here.
  • country: required A string with the ISO code of the campaign's country, which must be 'CAD' or 'USA' at this time.
  • admin_data: required The user information for the campaign's admin. It must contain the same information as $user_data

  campaign_data = {
    id: 19551105,
    name: "The Time Travelers",
    category: "Events & Trips",
    country: "USA",
    admin_data: user_data
  };
  

• group_data: Always optional. Groups are aggregators for users within a campaign. For example, a group can be a Player on a sport's team and the users would be the people supporting them.

  • name: required. A string with the group's name.
  • player_number: Optional. A sport's player number on the team.

  group_data = {
    name: "Marty McFly"
  };
  

• organization_data: Always optional. Organizations are used to group campaigns. As an example: A School (organization) has many Grades (campaigns), with Students (groups) and Parents (users) shopping to support their student.

  • id: required. A string with the organization's ID.
  • name: required. A string with the organization's name.
  • organization_admin: required. The user information for the organization's admin. It must contain the same information as $user_data

  organization_data = {
    id: 980,
    name: "Back to the Future",
    admin_data: user_data
  };
  

validIdentified

This method is used to validate a payload, without attempting to generate a token. It returns a Boolean. The same rules for identifiedToken apply here as well.

payload = {
  user_data: user_data
};

shopCloud.validIdentified(payload);
=> true

getPartnerToken

This method is used to generate a token that can only be used by the Shop Cloud partner (that's you) to access reports and other API endpoints. It is only valid for an hour.

shopCloud.getPartnerToken().then(token => console.log(token));
=> "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4R0NNIn0..demoToken.h9QXQEn2LFGVSlTdiGXW1e@A2DE537C"

getErrors

Validation errors that occur while attempting to generate a token can be retrieved here.

user_data["country"] = "ENG";

payload = {
  user_data: user_data
};

shopCloud.validIdentified(payload);

# InvalidPayloadException

shopCloud.getErrors();

=> [{ "user_data": "Country must be one of: 'CAN, USA'." }]

Support

For developer support please open an issue on this repository.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/BetterTheWorld/FlipGiveSDK_node.

License

This library is distributed under the Apache License, version 2.0

copyright 2023. FlipGive, inc. all rights reserved.

licensed under the apache license, version 2.0 (the "license");
you may not use this file except in compliance with the license.
you may obtain a copy of the license at

    http://www.apache.org/licenses/license-2.0

unless required by applicable law or agreed to in writing, software
distributed under the license is distributed on an "as is" basis,
without warranties or conditions of any kind, either express or implied.
see the license for the specific language governing permissions and
limitations under the license.