trailpack-proxy-generics

trailpack-proxy-generics

An adapter protocol for common functions, built with love from Cali-Style

Looking for Proxy Engine?

Generics are common features that web applications need but implement differently. The result of a Generic is a normalized way of handling these different services.

A generic is a great way to implement 3rd parties. You can write your application to implement a single service but easily swap out the the 3rd party.

Generics can add their own Models, Controllers, Services, and Policies so they can support things like vendor specific webhooks or extend functionality.

Current Generics: Email Provider, Payment Processors, Tax Provider, Shipping Provider, Fulfillment, Geolocation, Image Manipulation, HTML rendering, whatever you need!

Can you think of a generic or method we missed? Create a PR!

Install

$ npm install --save trailpack-proxy-generics

Configure

// config/main.js
module.exports = {
  packs: [
    // ... other trailpacks
    require('trailpack-proxy-generics')
  ]
}

// config/proxyGenerics.js
module.exports = {
  // ... any generic
  payment_processor: {
      adapter: require('<adapter>'),
      options: {
          whatever_key: '<what ever you need here>'
      },
      api: require('<adapter>/api')
  }
}

Usage

Many different modules in Proxy Engine will rely on a generic to complete a task. Generics are easy to create and use.

Validation

Every Generic call is validated twice:

• When data is passed to the generic.
• When there is a successful response from the generic.

This allows for generics to stay consistent with their requests and responses.

NOTE: If a an instance of a model is passed to the generic, then the generic must mutate it return the same instance.

Currently Supported Generics

Email Provider

The Email Provider handles sending emails from different email providers eg. Mandrill, MailGun

EmailGenericService.send

Sends an Email

EmailGenericService.sendTemplate

Sends an Email Template

Creating an Email Provider Generic

Supported Email Providers

• Mandrill

Geolocation Provider

The Geolocation Provider handles resolving geographical locations.

GeolocationGenericService.locate

Resolves the geolocation of an address, validates an address, normalizes an address.

Creating a Geolocation Provider Generic

TODO

Supported Geolocation Providers

• Google Maps

Payment Processor

The Payment Processor handles payments from different merchant processors/terminals eg. Stripe, Authorize.net.

PaymentGenericService.authorize

Authorizes a purchase transaction

PaymentGenericService.capture

Captures an authorized purchase transaction

PaymentGenericService.sale

Authorizes and captures a purchase transaction

PaymentGenericService.void

Voids an authorized purchase transaction

PaymentGenericService.refund

Partially Refunds/Refunds a purchase transaction

PaymentGenericService.createCustomer

Create a Customer Account

PaymentGenericService.updateCustomer

Update a Customer Account

PaymentGenericService.findCustomer

Find a Created Customer Account

PaymentGenericService.getCustomerSources

Get Customer Sources (Payment Methods)

PaymentGenericService.createCustomerSource

Create Customer Source (Payment Methods)

PaymentGenericService.updateCustomerSource

Update Customer Source (Payment Methods)

PaymentGenericService.findCustomerSource

Find a Customer Source (Payment Methods)

PaymentGenericService.removeCustomerSource

Remove a Customer Source (Payment Methods)

Creating a Payment Processor Generic

TODO EXAMPLE

Supported Payment Processors

• Stripe
• Authorize.net

Tax Provider

The Tax Provider handles sales tax for items sold from different tax providers eg. TaxBundle

TaxGenericService.getRate

Gets the tax rate for a purchase transaction.

Creating a Tax Provider Generic

TODO EXAMPLE

Supported Tax Providers

• Taxjar

Shipping Provider (TODO)

The Shipping Provider handles shipping rates from a location to a destination from different shipping providers eg. Shipstation, USPS, FedEx, UPS

ShippingGenericService.getRate

Gets a single carrier rate.

ShippingGenericService.getRates

Gets all carrier rates

Creating a Shipping Provider Generic

TODO EXAMPLE

Supported Shipping Providers

• Shippo
• Shipstation

Fulfillment Provider (TODO)

The Fulfillment Provider handles fulfillment events from a location to a destination from different fulfillment providers eg. Shipstation, Amazon, Custom

FulfillmentGenericService.createOrder

Creates an order in fulfillment

FulfillmentGenericService.createOrders

Creates multiple orders in fulfillment

FulfillmentGenericService.updateOrder

Updates an order in fulfillment

FulfillmentGenericService.updateOrders

Updates multiple orders in fulfillment

FulfillmentGenericService.destroyOrder

Destroys an order in fulfillment

FulfillmentGenericService.destroyOrders

Destroys multiple orders in fulfillment

FulfillmentGenericService.getOrder

Retrieves an order in fulfillment

FulfillmentGenericService.getOrders

Retrieves multiple orders in fulfillment

FulfillmentGenericService.holdOrder

Creates an order hold in fulfillment

FulfillmentGenericService.holdOrders

Creates multiple order holds in fulfillment

Creating a Fulfillment Provider Generic

TODO EXAMPLE

Supported Fulfillment Providers

• Shippo
• Shipstation

Data Store Provider

The Data Store provider handles uploads and downloads to a remote data store eg. AWS, gCloud, and some permissions.

DataStoreGenericService.upload

Uploads a buffer to a data store

DataStoreGenericService.uploadFile

Uploads a file to a data store

DataStoreGenericService.uploadFiles

Uploads files to a data store

Creating a Data Store Provider Plugin

TODO EXAMPLE

Supported Data Store Providers

• Gcloud

Image Provider

Handles image manipulation

Creating an Image Provider Plugin

TODO EXAMPLE

Render Service

Handles rendering of html and Metadata

RenderGenericService.render

Render a markdown/html string into HTML and returns YAML metadata as object

{
    document: '<h1>Hello World</h1>'
    meta: {
      key: 'Look at Me!'
    }
}

RenderGenericService.render

Renders markdown/html string asynchronously.

RenderGenericService.renderSync

Renders markdown/html string synchronously.

Creating an Render Service Plugin

TODO EXAMPLE

Supported Render Services

• Render