E-Com Plus Application Starter

🐶 Boilerplate for E-Com Plus apps with Firebase Cloud Functions and GitHub Actions.

CHANGELOG

Getting started

1. Start creating a Firebase project:

   • Analytics is not needed;
   • Set a nice project name (ID) and remember it;

2. Enter the project, go to Firestore page (on menu) and create database:

   • Just bypass with default production mode and rules;

3. Firebase free plan doesn't support sending external HTTP requests, so you'll need to upgrade to Blaze (on demand) plan;

4. Get your Firebase token from CLI:

npx firebase-tools login:ci

# OR with firebase-tools installed globally
npm install -g firebase-tools
firebase login:ci

5. Use this template to generate a new repository for your application;

6. Go to your repository settings tab and set the following secrets:

   • FIREBASE_PROJECT_ID: The ID (name) of your Firebase project;
   • FIREBASE_TOKEN: The token generated with firebase-tools;
   • SERVER_OPERATOR_TOKEN: Random (at least 16 bytes) admin token generated from CLI or here;
   • MARKET_TOKEN (optional): Your E-Com Plus Market personal token to publish the app automatically;

Next steps

Almost ready, time to ☕ and code!

Edit functions/ecom.config.js to set correct app_id, title and optionally more fields on base app body.

If you're not yet familiarized with this boilerplate, read with attention the comments and instructions at the configuration file. You can also setup procedures from there to specify the web-hooks your app should receive.

E-Com common routes

All endpoints inside /ecom/ path MUST BE PRIVATE (trey are by default), accessible only for E-Com Plus official servers or with X-Operator-Token header (equal to SERVER_OPERATOR_TOKEN env).

Requests to E-Com routes must have X-Store-ID header or store_id parameter on URL query string.

auth-callback

Handle authentication callback request and save tokens to database, also create Store API procedures if configured.

You can edit it to send custom requests to external server notifying new store installation or setup.

get-auth

Returns Store API authentication data based on received Store ID, for external usage.

Sample response:

{
  "application_id": "a00000000000000000000012",
  "application_app_id": 9000,
  "store_id": 1011,
  "authentication_id": "120000000000000000000012",
  "access_token": "eyJhbGciOi.eyYzdWIi.ZEONFh7HgQ"
}

You should consume it if you want to use this boilerplate as an authentication backend only. By getting this data (HTTP GET) you'll be able to run authenticated requests to Store API from your own server, with your preferred language, framework...

refresh-tokens

Call update service to start refreshing old access tokens.

webhook

Receives E-Com Plus notification POSTs for configured procedures.

You may want to edit it to properly treat trigger body and do your custom stuff for each notification type.

modules/*

Endpoints for E-Com Plus Mods API.

You should edit the respective ones for enabled modules (on ecom.config.js).

For payment apps

You should start from modules/list-payments.js and modules/create-transaction.js, enable both (uncomment) in ecom.config.js. Probably you will also need a custom route to receive payment notifications (webhooks) and update order status, and maybe a client-side script to tokenize credit cards (as this one). Check examples here.

Additional Store API handlers

If the app works with admin_settings (configuration), use getAppData to get the application data/hidden_data configured by merchant from dashboard through Store API (Application Object).

We recommend treating Store API clients (40x) and server (50x) errors with errorHandling abstraction.

Application SDK

You may want to use appSdk to make custom authenticated requests to Store API or deeper coding out of our examples.

Custom integration scripts

• Add third party libraries to functions/package.json dependencies;
• Add custom web app routes by creating new files to functions/routes folder;
• Add new methods/handlers at functions/lib folder;

Optional setup for Market

You may want to make your app public and available to install within E-Com Plus dashboard, to do this:

• Edit ecomplus-market.json to set a short description and category between shipping, sales, tools, customer-service, marketing, inventory or product-sourcing;
• Overwrite the default PNG icon at hosting/icon.png;
• Write a good markdown description for the app at hosting/description.md;
• Take note about publication;

If you are not yet a registered partner, start by filling out this form and wait a little for our response 🤝

Examples

😎 Awesome E-Com Plus applications to get inspired!

Continuous integration

Every commit will trigger a new deploy (with GitHub Actions), then your app will be accessible at:

https://us-central1-<project-id>.cloudfunctions.net/app/ 😊

The assets/application.json will be updated automatically with some package info and current Cloud Function endpoints, you can use it as body to Create new Application on Store API.

You can skip deploy workflow by adding [skip ci] to the commit message.

Also, your app's access tokens to Store API will be automatically refreshed every 8 hours by scheduled workflow.

Publication

If MARKET_TOKEN secret is set, the app will be automatically published to Market every time assets/application.json is changed, then merchants will be able to install it with up to date version.

Developing and testing locally

📢 On Windows you must use Git Bash to execute the commands below.

Setup the project normally by cloning your repository and installing npm dependencies:

git clone [email protected]:$username/$app_repository.git
cd $app_repository
npm i
cd functions
npm i

Due to our GitHub Actions workflows, you probably don't need and we don't recommend to deploy locally because it may vary with your environment, if you don't have a special motivation to run it on CLI, just commit, push to GitHub and trust on CI 😄

Then you can call npm run deploy locally getting configuration from .env file on project root. You can also set a different FIREBASE_PROJECT_ID locally for test purpose only.

When you're done, you can publish the app by running npm run publish:market.

Execute functions locally

After deploying the project at least once (may be out of date with your local source) you can emulate Cloud Functions by running npm run serve from repository root.

Firebase tools

You can also use firebase-tools CLI to run tests/deploy with custom config or scripts.