@sails-pay/bachs 0.0.2 → 0.0.4

package/adapter.js

@@ -4,6 +4,7 @@ module.exports = {
   identity: 'sails-bachs',
   config: {},
   checkout: methods.checkout,
+  connect: methods.connect,
   customer: {
     portal: methods.customer.portal
   },

package/helpers/connect.js

@@ -0,0 +1,86 @@
+/**
+ * Translates Bachs Connect responses into the provider-agnostic shapes
+ * returned by `sails.pay.connect`. Every adapter that implements Connect
+ * returns these same shapes, so application code never reads provider fields.
+ */
+
+function capabilityStatus(capability) {
+  const status = capability && capability.status
+  if (status === 'active' || status === 'pending') return status
+  return 'inactive'
+}
+
+function toAccount(account, { email } = {}) {
+  const capabilities = {}
+  for (const [name, capability] of Object.entries(
+    (account && account.capabilities) || {}
+  )) {
+    capabilities[name] = capabilityStatus(capability)
+  }
+
+  return {
+    id: account.id,
+    email: account.contact_email || email || null,
+    name: account.display_name || account.name || null,
+    country: account.country || null,
+    capabilities,
+    requirements:
+      (account.requirements && account.requirements.currently_due) || [],
+    raw: account
+  }
+}
+
+function toLink(link) {
+  return {
+    url: link.url,
+    expiresAt: link.expires_at || null,
+    raw: link
+  }
+}
+
+function toTransfer(transfer) {
+  return {
+    id: transfer.id,
+    account: transfer.destination,
+    amount: transfer.amount,
+    currency: transfer.currency,
+    group: transfer.transfer_group || null,
+    status: transfer.status === 'paid' ? 'paid' : 'pending',
+    raw: transfer
+  }
+}
+
+function toBalances(response) {
+  return ((response && response.balances) || []).map((balance) => ({
+    currency: balance.currency,
+    available: balance.available_balance,
+    pending: balance.pending_balance
+  }))
+}
+
+function payoutStatus(status) {
+  if (status === 'completed') return 'paid'
+  if (status === 'failed') return 'failed'
+  return 'pending'
+}
+
+function toPayout(payout, { account }) {
+  return {
+    id: payout.id,
+    account,
+    amount: payout.amount,
+    currency: payout.currency,
+    fee: payout.fee || null,
+    destination: payout.destination || null,
+    status: payoutStatus(payout.status),
+    raw: payout
+  }
+}
+
+module.exports = {
+  toAccount,
+  toLink,
+  toTransfer,
+  toBalances,
+  toPayout
+}

package/helpers/payloads.js

@@ -44,13 +44,22 @@ function buildProductCart(items) {
     return undefined
   }
 
-  return items.map((item) =>
-    withoutUndefined({
+  return items.map((item) => {
+    const pricing =
+      item.amount !== undefined
+        ? normalizePricing({
+            type: 'fixed',
+            amount: item.amount
+          })
+        : normalizePricing(item.pricing)
+
+    return withoutUndefined({
       product_id: item.product || item.productId,
       quantity: item.quantity,
-      amount: item.amount
+      pricing,
+      amount: item.chosenAmount
     })
-  )
+  })
 }
 
 function buildCheckoutSessionPayload(inputs, adapterConfig = {}) {
@@ -76,25 +85,44 @@ function buildCheckoutSessionPayload(inputs, adapterConfig = {}) {
   })
 }
 
-function buildPricingPayload(inputs) {
-  let pricing
+function normalizePricing(pricing, fallbackCurrencyOptions) {
+  if (!pricing || typeof pricing !== 'object' || Array.isArray(pricing)) {
+    return undefined
+  }
 
-  if (inputs.pricing) {
-    const { currencyOptions, ...pricingInput } = inputs.pricing
+  const {
+    type,
+    presetAmount,
+    minimumAmount,
+    maximumAmount,
+    currencyOptions,
+    ...pricingInput
+  } = pricing
+  const normalizedPricing = withoutUndefined({
+    ...pricingInput,
+    price_type: type,
+    preset_amount: presetAmount,
+    minimum_amount: minimumAmount,
+    maximum_amount: maximumAmount,
+    currency_options:
+      currencyOptions === undefined ? fallbackCurrencyOptions : currencyOptions
+  })
 
-    pricing = withoutUndefined({
-      ...pricingInput,
-      currency_options: currencyOptions || inputs.currencyOptions
-    })
-  } else {
-    pricing = withoutUndefined({
-      currency: inputs.currency,
-      amount: inputs.amount,
-      currency_options: inputs.currencyOptions
-    })
+  return Object.keys(normalizedPricing).length > 0
+    ? normalizedPricing
+    : undefined
+}
+
+function buildPricingPayload(inputs) {
+  if (inputs.pricing) {
+    return normalizePricing(inputs.pricing, inputs.currencyOptions)
   }
 
-  return Object.keys(pricing).length > 0 ? pricing : undefined
+  return normalizePricing({
+    currency: inputs.currency,
+    amount: inputs.amount,
+    currencyOptions: inputs.currencyOptions
+  })
 }
 
 function buildPureCheckoutPayload(inputs, adapterConfig = {}) {
@@ -142,5 +170,6 @@ module.exports = {
   buildRefundPayload,
   buildProductCart,
   buildCustomerPayload,
+  normalizePricing,
   withoutUndefined
 }

package/helpers/validate-checkout-items.js

@@ -0,0 +1,177 @@
+const pricingTypes = new Set(['fixed', 'custom', 'free'])
+const pricingMoneyFields = [
+  'amount',
+  'presetAmount',
+  'minimumAmount',
+  'maximumAmount'
+]
+const customPricingFields = ['presetAmount', 'minimumAmount', 'maximumAmount']
+const decimalStringPattern = /^\d+(?:\.\d+)?$/
+
+function fieldWasProvided(object, field) {
+  return object[field] !== undefined
+}
+
+function invalid(field, message) {
+  return {
+    field,
+    message: `${field} ${message}`
+  }
+}
+
+function validateMoney(value, field) {
+  if (typeof value !== 'string' || !decimalStringPattern.test(value)) {
+    return invalid(field, 'must be a non-negative decimal string.')
+  }
+}
+
+function validatePricingMoney(pricing, itemPath) {
+  for (const field of pricingMoneyFields) {
+    if (fieldWasProvided(pricing, field)) {
+      const error = validateMoney(
+        pricing[field],
+        `${itemPath}.pricing.${field}`
+      )
+
+      if (error) {
+        return error
+      }
+    }
+  }
+}
+
+function validateItem(item, index) {
+  const itemPath = `items[${index}]`
+
+  if (!item || typeof item !== 'object' || Array.isArray(item)) {
+    return invalid(itemPath, 'must be an object.')
+  }
+
+  if (
+    fieldWasProvided(item, 'quantity') &&
+    (!Number.isInteger(item.quantity) || item.quantity < 1)
+  ) {
+    return invalid(`${itemPath}.quantity`, 'must be an integer of at least 1.')
+  }
+
+  const hasAmount = fieldWasProvided(item, 'amount')
+  const hasPricing = fieldWasProvided(item, 'pricing')
+  const hasChosenAmount = fieldWasProvided(item, 'chosenAmount')
+
+  if (hasAmount && hasPricing) {
+    return invalid(
+      itemPath,
+      'must not provide both amount and pricing; amount is the fixed-price shorthand.'
+    )
+  }
+
+  if (hasAmount) {
+    const error = validateMoney(item.amount, `${itemPath}.amount`)
+
+    if (error) {
+      return error
+    }
+
+    if (hasChosenAmount) {
+      return invalid(
+        `${itemPath}.chosenAmount`,
+        'can only be used with catalog custom pricing or ad-hoc custom pricing.'
+      )
+    }
+  }
+
+  if (hasChosenAmount) {
+    const error = validateMoney(item.chosenAmount, `${itemPath}.chosenAmount`)
+
+    if (error) {
+      return error
+    }
+  }
+
+  if (!hasPricing) {
+    return
+  }
+
+  if (
+    !item.pricing ||
+    typeof item.pricing !== 'object' ||
+    Array.isArray(item.pricing)
+  ) {
+    return invalid(`${itemPath}.pricing`, 'must be an object.')
+  }
+
+  const pricing = item.pricing
+
+  if (!pricingTypes.has(pricing.type)) {
+    return invalid(
+      `${itemPath}.pricing.type`,
+      'must be fixed, custom, or free.'
+    )
+  }
+
+  if (pricing.type === 'fixed') {
+    if (!fieldWasProvided(pricing, 'amount')) {
+      return invalid(
+        `${itemPath}.pricing.amount`,
+        'is required for fixed pricing.'
+      )
+    }
+
+    const customField = customPricingFields.find((field) =>
+      fieldWasProvided(pricing, field)
+    )
+
+    if (customField) {
+      return invalid(
+        `${itemPath}.pricing.${customField}`,
+        'is not allowed with fixed pricing.'
+      )
+    }
+
+    if (hasChosenAmount) {
+      return invalid(
+        `${itemPath}.chosenAmount`,
+        'can only be used with catalog custom pricing or ad-hoc custom pricing.'
+      )
+    }
+  }
+
+  if (pricing.type === 'custom' && fieldWasProvided(pricing, 'amount')) {
+    return invalid(
+      `${itemPath}.pricing.amount`,
+      'is not allowed with custom pricing.'
+    )
+  }
+
+  if (pricing.type === 'free') {
+    const monetaryField = pricingMoneyFields.find((field) =>
+      fieldWasProvided(pricing, field)
+    )
+
+    if (monetaryField) {
+      return invalid(
+        `${itemPath}.pricing.${monetaryField}`,
+        'is not allowed with free pricing.'
+      )
+    }
+
+    if (hasChosenAmount) {
+      return invalid(
+        `${itemPath}.chosenAmount`,
+        'is not allowed with free pricing.'
+      )
+    }
+  }
+
+  return validatePricingMoney(pricing, itemPath)
+}
+
+module.exports = function validateCheckoutItems(items) {
+  for (let index = 0; index < items.length; index++) {
+    const error = validateItem(items[index], index)
+
+    if (error) {
+      return error
+    }
+  }
+}

package/machines/checkout.js

@@ -3,6 +3,7 @@ const {
   buildCheckoutSessionPayload,
   buildPureCheckoutPayload
 } = require('../helpers/payloads')
+const validateCheckoutItems = require('../helpers/validate-checkout-items')
 const parameters = require('../helpers/parameters')
 
 module.exports = require('machine').build({
@@ -16,7 +17,7 @@ module.exports = require('machine').build({
     items: {
       type: 'ref',
       description:
-        'Product items for Bachs Checkout Sessions. Each item should use product or productId plus optional quantity and amount.'
+        'Product items for Bachs Checkout Sessions. Supports catalog pricing, fixed amount shorthand, advanced pricing, and chosenAmount.'
     },
     productCollectionId: {
       type: 'string',
@@ -141,10 +142,6 @@ module.exports = require('machine').build({
       inputs.productCollectionId || inputs.productCollection
     )
     const shouldUseCheckoutSession = hasItems || hasProductCollection
-    const path = shouldUseCheckoutSession ? '/checkout-sessions' : '/checkouts'
-    const payload = shouldUseCheckoutSession
-      ? buildCheckoutSessionPayload(inputs, adapterConfig)
-      : buildPureCheckoutPayload(inputs, adapterConfig)
 
     if (shouldUseCheckoutSession && hasItems === hasProductCollection) {
       return exits.invalidRequest({
@@ -153,6 +150,19 @@ module.exports = require('machine').build({
       })
     }
 
+    if (hasItems) {
+      const validationError = validateCheckoutItems(inputs.items)
+
+      if (validationError) {
+        return exits.invalidRequest(validationError)
+      }
+    }
+
+    const path = shouldUseCheckoutSession ? '/checkout-sessions' : '/checkouts'
+    const payload = shouldUseCheckoutSession
+      ? buildCheckoutSessionPayload(inputs, adapterConfig)
+      : buildPureCheckoutPayload(inputs, adapterConfig)
+
     if (!shouldUseCheckoutSession && !payload.pricing) {
       return exits.invalidRequest({
         message:

package/machines/connect/account/create.js

@@ -0,0 +1,77 @@
+const fetch = require('../../../helpers/fetch')
+const parameters = require('../../../helpers/parameters')
+const { toAccount } = require('../../../helpers/connect')
+
+module.exports = require('machine').build({
+  friendlyName: 'Create connected account',
+  description:
+    'Creates a recipient account with its own balance that the platform can transfer to and that can withdraw.',
+  moreInfoUrl: 'https://docs.bachs.io/connect/guides/create-an-account',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    email: {
+      type: 'string',
+      required: true,
+      isEmail: true,
+      description: 'Contact email of the person or business being onboarded.'
+    },
+    name: {
+      type: 'string',
+      description: 'Display name for the account.'
+    },
+    country: {
+      type: 'string',
+      defaultsTo: 'NG',
+      description: 'ISO 3166-1 alpha-2 country of the account.'
+    },
+    capabilities: {
+      type: ['string'],
+      defaultsTo: ['transfers', 'payouts'],
+      description: 'Capabilities to request, e.g. ["transfers", "payouts"].'
+    },
+    idempotencyKey: {
+      type: 'string',
+      description: 'Prevents a retry from creating a duplicate account.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The created account.',
+      outputVariableName: 'account',
+      outputType: 'ref'
+    },
+    couldNotCreateAccount: {
+      description: 'The account could not be created.',
+      outputVariableName: 'error',
+      outputType: 'ref'
+    }
+  },
+  fn: async function (inputs, exits) {
+    const adapterConfig = require('../../../adapter').config
+    const capabilities = {}
+    for (const capability of inputs.capabilities) {
+      capabilities[capability] = { requested: true }
+    }
+
+    try {
+      const account = await fetch('/accounts', {
+        method: 'POST',
+        apiKey: inputs.apiKey || adapterConfig.apiKey,
+        baseUrl: inputs.baseUrl || adapterConfig.baseUrl,
+        idempotencyKey: inputs.idempotencyKey,
+        body: {
+          contact_email: inputs.email,
+          ...(inputs.name && { display_name: inputs.name }),
+          country: inputs.country,
+          entity_type: 'individual',
+          configuration: { recipient: { capabilities } }
+        }
+      })
+
+      return exits.success(toAccount(account, { email: inputs.email }))
+    } catch (error) {
+      return exits.couldNotCreateAccount(error.bachs || error)
+    }
+  }
+})

package/machines/connect/account/get.js

@@ -0,0 +1,49 @@
+const fetch = require('../../../helpers/fetch')
+const parameters = require('../../../helpers/parameters')
+const { toAccount } = require('../../../helpers/connect')
+
+module.exports = require('machine').build({
+  friendlyName: 'Get connected account',
+  description:
+    'Retrieves a connected account with its capability statuses and currently due requirements.',
+  moreInfoUrl: 'https://docs.bachs.io/connect/accounts',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    account: {
+      type: 'string',
+      required: true,
+      description: 'The connected account ID.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The connected account.',
+      outputVariableName: 'account',
+      outputType: 'ref'
+    },
+    couldNotGetAccount: {
+      description: 'The account could not be retrieved.',
+      outputVariableName: 'error',
+      outputType: 'ref'
+    }
+  },
+  fn: async function (inputs, exits) {
+    const adapterConfig = require('../../../adapter').config
+
+    try {
+      const account = await fetch(
+        `/accounts/${encodeURIComponent(inputs.account)}`,
+        {
+          method: 'GET',
+          apiKey: inputs.apiKey || adapterConfig.apiKey,
+          baseUrl: inputs.baseUrl || adapterConfig.baseUrl
+        }
+      )
+
+      return exits.success(toAccount(account))
+    } catch (error) {
+      return exits.couldNotGetAccount(error.bachs || error)
+    }
+  }
+})

package/machines/connect/account/link.js

@@ -0,0 +1,71 @@
+const fetch = require('../../../helpers/fetch')
+const parameters = require('../../../helpers/parameters')
+const { toLink } = require('../../../helpers/connect')
+
+module.exports = require('machine').build({
+  friendlyName: 'Create connected account link',
+  description:
+    'Creates a short-lived hosted link that walks a connected account through its outstanding requirements.',
+  moreInfoUrl: 'https://docs.bachs.io/connect/guides/hosted-onboarding',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    account: {
+      type: 'string',
+      required: true,
+      description: 'The connected account ID.'
+    },
+    type: {
+      type: 'string',
+      isIn: ['onboarding', 'update'],
+      defaultsTo: 'onboarding',
+      description:
+        'Use "onboarding" for new accounts and "update" to edit details.'
+    },
+    returnUrl: {
+      type: 'string',
+      required: true,
+      description: 'Where the account lands after leaving the hosted flow.'
+    },
+    refreshUrl: {
+      type: 'string',
+      required: true,
+      description: 'Where an expired or already used link sends the account.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The hosted link.',
+      outputVariableName: 'link',
+      outputType: 'ref'
+    },
+    couldNotCreateLink: {
+      description: 'The hosted link could not be created.',
+      outputVariableName: 'error',
+      outputType: 'ref'
+    }
+  },
+  fn: async function (inputs, exits) {
+    const adapterConfig = require('../../../adapter').config
+
+    try {
+      const link = await fetch(
+        `/accounts/${encodeURIComponent(inputs.account)}/account-links`,
+        {
+          method: 'POST',
+          apiKey: inputs.apiKey || adapterConfig.apiKey,
+          baseUrl: inputs.baseUrl || adapterConfig.baseUrl,
+          body: {
+            type: inputs.type,
+            refresh_url: inputs.refreshUrl,
+            return_url: inputs.returnUrl
+          }
+        }
+      )
+
+      return exits.success(toLink(link))
+    } catch (error) {
+      return exits.couldNotCreateLink(error.bachs || error)
+    }
+  }
+})

package/machines/connect/balance/get.js

@@ -0,0 +1,47 @@
+const fetch = require('../../../helpers/fetch')
+const parameters = require('../../../helpers/parameters')
+const { toBalances } = require('../../../helpers/connect')
+
+module.exports = require('machine').build({
+  friendlyName: 'Get connected account balance',
+  description:
+    'Retrieves the available and pending balance of a connected account in every currency it holds.',
+  moreInfoUrl: 'https://docs.bachs.io/connect/balances',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    account: {
+      type: 'string',
+      required: true,
+      description: 'The connected account ID.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'One entry per currency.',
+      outputVariableName: 'balances',
+      outputType: 'ref'
+    },
+    couldNotGetBalance: {
+      description: 'The balance could not be retrieved.',
+      outputVariableName: 'error',
+      outputType: 'ref'
+    }
+  },
+  fn: async function (inputs, exits) {
+    const adapterConfig = require('../../../adapter').config
+
+    try {
+      const response = await fetch('/balances', {
+        method: 'GET',
+        apiKey: inputs.apiKey || adapterConfig.apiKey,
+        baseUrl: inputs.baseUrl || adapterConfig.baseUrl,
+        headers: { 'X-Account-Id': inputs.account }
+      })
+
+      return exits.success(toBalances(response))
+    } catch (error) {
+      return exits.couldNotGetBalance(error.bachs || error)
+    }
+  }
+})