@sails-pay/bachs 0.0.3 → 0.0.5

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

@@ -81,7 +81,11 @@ function buildCheckoutSessionPayload(inputs, adapterConfig = {}) {
     return_url: returnUrl,
     cancel_url: inputs.cancelUrl || adapterConfig.cancelUrl,
     reference: inputs.reference,
-    metadata: inputs.metadata || checkoutData.custom
+    metadata: inputs.metadata || checkoutData.custom,
+    transfer_data: inputs.connect && {
+      destination: inputs.connect.destination
+    },
+    platform_fee: inputs.connect && inputs.connect.platformFee
   })
 }
 

package/helpers/validate-checkout-connect.js

@@ -0,0 +1,54 @@
+const allowedFields = new Set(['destination', 'platformFee'])
+const decimalStringPattern = /^\d+(?:\.\d+)?$/
+
+function invalid(field, message) {
+  return {
+    field,
+    message: `${field} ${message}`
+  }
+}
+
+/**
+ * Validates the `connect` checkout input that splits a checkout between a
+ * connected account and the platform. Returns an error object, or null.
+ */
+function validateCheckoutConnect(connect, { isCheckoutSession }) {
+  if (!connect || typeof connect !== 'object' || Array.isArray(connect)) {
+    return invalid('connect', 'must be an object.')
+  }
+
+  if (!isCheckoutSession) {
+    return invalid(
+      'connect',
+      'is only supported on product checkout sessions (items or productCollectionId).'
+    )
+  }
+
+  for (const field of Object.keys(connect)) {
+    if (!allowedFields.has(field)) {
+      return invalid(
+        `connect.${field}`,
+        'is not supported. Use connect.destination and connect.platformFee.'
+      )
+    }
+  }
+
+  if (typeof connect.destination !== 'string' || !connect.destination) {
+    return invalid('connect.destination', 'must be a connected account ID.')
+  }
+
+  if (
+    typeof connect.platformFee !== 'string' ||
+    !decimalStringPattern.test(connect.platformFee) ||
+    Number(connect.platformFee) <= 0
+  ) {
+    return invalid(
+      'connect.platformFee',
+      'must be a positive decimal string, e.g. "500.00".'
+    )
+  }
+
+  return null
+}
+
+module.exports = validateCheckoutConnect

package/machines/checkout.js

@@ -4,6 +4,7 @@ const {
   buildPureCheckoutPayload
 } = require('../helpers/payloads')
 const validateCheckoutItems = require('../helpers/validate-checkout-items')
+const validateCheckoutConnect = require('../helpers/validate-checkout-connect')
 const parameters = require('../helpers/parameters')
 
 module.exports = require('machine').build({
@@ -116,6 +117,11 @@ module.exports = require('machine').build({
     simulatedOutcome: {
       type: 'string',
       description: 'Sandbox-only forced outcome.'
+    },
+    connect: {
+      type: 'ref',
+      description:
+        'Splits a checkout session with a connected account: { destination, platformFee }. The account receives the rest of the sale when it settles.'
     }
   },
   exits: {
@@ -158,6 +164,16 @@ module.exports = require('machine').build({
       }
     }
 
+    if (inputs.connect !== undefined) {
+      const connectError = validateCheckoutConnect(inputs.connect, {
+        isCheckoutSession: shouldUseCheckoutSession
+      })
+
+      if (connectError) {
+        return exits.invalidRequest(connectError)
+      }
+    }
+
     const path = shouldUseCheckoutSession ? '/checkout-sessions' : '/checkouts'
     const payload = shouldUseCheckoutSession
       ? buildCheckoutSessionPayload(inputs, adapterConfig)

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)
+    }
+  }
+})

package/machines/connect/payout/create.js

@@ -0,0 +1,114 @@
+const fetch = require('../../../helpers/fetch')
+const parameters = require('../../../helpers/parameters')
+const { toPayout } = require('../../../helpers/connect')
+
+module.exports = require('machine').build({
+  friendlyName: 'Create connected account payout',
+  description:
+    "Withdraws from a connected account's balance to one of its payout destinations, defaulting to the account's default destination for the currency.",
+  moreInfoUrl: 'https://docs.bachs.io/connect/payouts',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    account: {
+      type: 'string',
+      required: true,
+      description: 'The connected account withdrawing.'
+    },
+    amount: {
+      type: 'string',
+      required: true,
+      description: 'Decimal amount the destination should receive.'
+    },
+    currency: {
+      type: 'string',
+      description:
+        'ISO 4217 currency. Required when destination is omitted, so the default destination can be found.'
+    },
+    destination: {
+      type: 'string',
+      description: 'A payout destination ID. Omit to use the default one.'
+    },
+    reference: {
+      type: 'string',
+      maxLength: 128,
+      description: 'Your reference for the payout.'
+    },
+    idempotencyKey: {
+      type: 'string',
+      description: 'Prevents a retry from paying out twice.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The payout accepted for delivery.',
+      outputVariableName: 'payout',
+      outputType: 'ref'
+    },
+    noDestination: {
+      description:
+        'No destination was given and the account has no usable destination for the currency.',
+      outputVariableName: 'error',
+      outputType: 'ref'
+    },
+    couldNotCreatePayout: {
+      description: 'The payout could not be created.',
+      outputVariableName: 'error',
+      outputType: 'ref'
+    }
+  },
+  fn: async function (inputs, exits) {
+    const adapterConfig = require('../../../adapter').config
+    const request = {
+      apiKey: inputs.apiKey || adapterConfig.apiKey,
+      baseUrl: inputs.baseUrl || adapterConfig.baseUrl,
+      headers: { 'X-Account-Id': inputs.account }
+    }
+
+    let destination = inputs.destination
+    if (!destination) {
+      if (!inputs.currency) {
+        return exits.noDestination({
+          message: 'Pass a destination, or a currency to use the default one.'
+        })
+      }
+
+      try {
+        const { destinations = [] } = await fetch(
+          `/payouts/destinations?currency=${encodeURIComponent(
+            inputs.currency
+          )}`,
+          { method: 'GET', ...request }
+        )
+        const usable = destinations.filter((candidate) => candidate.is_usable)
+        const chosen =
+          usable.find((candidate) => candidate.is_default) || usable[0]
+        if (!chosen) {
+          return exits.noDestination({
+            message: `The account has no usable ${inputs.currency} payout destination.`
+          })
+        }
+        destination = chosen.id
+      } catch (error) {
+        return exits.couldNotCreatePayout(error.bachs || error)
+      }
+    }
+
+    try {
+      const payout = await fetch('/payouts', {
+        method: 'POST',
+        ...request,
+        idempotencyKey: inputs.idempotencyKey || inputs.reference,
+        body: {
+          destination,
+          amount: inputs.amount,
+          ...(inputs.reference && { reference: inputs.reference })
+        }
+      })
+
+      return exits.success(toPayout(payout, { account: inputs.account }))
+    } catch (error) {
+      return exits.couldNotCreatePayout(error.bachs || error)
+    }
+  }
+})

package/machines/connect/transfer/create.js

@@ -0,0 +1,71 @@
+const fetch = require('../../../helpers/fetch')
+const parameters = require('../../../helpers/parameters')
+const { toTransfer } = require('../../../helpers/connect')
+
+module.exports = require('machine').build({
+  friendlyName: 'Create transfer',
+  description:
+    "Moves funds from the platform balance into a connected account's balance.",
+  moreInfoUrl: 'https://docs.bachs.io/connect/transfers',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    account: {
+      type: 'string',
+      required: true,
+      description: 'The connected account receiving the funds.'
+    },
+    amount: {
+      type: 'string',
+      required: true,
+      description: 'Decimal amount, e.g. "10000.00".'
+    },
+    currency: {
+      type: 'string',
+      required: true,
+      description: 'ISO 4217 currency, e.g. "NGN".'
+    },
+    group: {
+      type: 'string',
+      description: 'Groups related transfers, e.g. one payrun.'
+    },
+    idempotencyKey: {
+      type: 'string',
+      description: 'Prevents a retry from transferring twice.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The created transfer.',
+      outputVariableName: 'transfer',
+      outputType: 'ref'
+    },
+    couldNotCreateTransfer: {
+      description: 'The transfer could not be created.',
+      outputVariableName: 'error',
+      outputType: 'ref'
+    }
+  },
+  fn: async function (inputs, exits) {
+    const adapterConfig = require('../../../adapter').config
+
+    try {
+      const transfer = await fetch('/transfers', {
+        method: 'POST',
+        apiKey: inputs.apiKey || adapterConfig.apiKey,
+        baseUrl: inputs.baseUrl || adapterConfig.baseUrl,
+        idempotencyKey: inputs.idempotencyKey,
+        body: {
+          destination: inputs.account,
+          amount: inputs.amount,
+          currency: inputs.currency,
+          ...(inputs.group && { transfer_group: inputs.group })
+        }
+      })
+
+      return exits.success(toTransfer(transfer))
+    } catch (error) {
+      return exits.couldNotCreateTransfer(error.bachs || error)
+    }
+  }
+})

package/machines/index.js

@@ -4,6 +4,22 @@ checkout.get = require('./checkout/get')
 
 module.exports = {
   checkout,
+  connect: {
+    account: {
+      create: require('./connect/account/create'),
+      get: require('./connect/account/get'),
+      link: require('./connect/account/link')
+    },
+    transfer: {
+      create: require('./connect/transfer/create')
+    },
+    balance: {
+      get: require('./connect/balance/get')
+    },
+    payout: {
+      create: require('./connect/payout/create')
+    }
+  },
   customer: {
     portal: require('./customer/portal')
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sails-pay/bachs",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Bachs adapter for Sails Pay",
   "main": "adapter.js",
   "scripts": {

package/test/checkout.test.js

@@ -363,3 +363,159 @@ test('adapter exposes checkout.get as the uniform checkout lookup API', async ()
   )
   assert.equal(calls[0].options.method, 'GET')
 })
+
+test('checkout splits a checkout session with a connected account', async () => {
+  const calls = []
+
+  fetch.setFetchImplementation(async (url, options) => {
+    calls.push({ url, options })
+
+    return {
+      ok: true,
+      status: 201,
+      statusText: 'Created',
+      text: async () =>
+        JSON.stringify({
+          checkout_id: 'chk_split',
+          checkout_url: 'https://pay.bachs.io/c/split'
+        })
+    }
+  })
+
+  const checkoutUrl = await checkout({
+    apiKey: 'sk_sandbox_123',
+    items: [{ product: 'prod_abc123', amount: '10500.00' }],
+    reference: 'sponsorship_1',
+    connect: {
+      destination: 'acct_123',
+      platformFee: '500.00'
+    }
+  })
+
+  assert.equal(checkoutUrl, 'https://pay.bachs.io/c/split')
+  assert.equal(
+    calls[0].url,
+    'https://sandbox-api.bachs.io/v1/checkout-sessions'
+  )
+  assert.equal(calls[0].options.headers['X-Account-Id'], undefined)
+
+  const body = JSON.parse(calls[0].options.body)
+  assert.deepEqual(body.transfer_data, { destination: 'acct_123' })
+  assert.equal(body.platform_fee, '500.00')
+  assert.equal(body.connect, undefined)
+})
+
+test('checkout without connect sends no split fields', async () => {
+  const calls = []
+
+  fetch.setFetchImplementation(async (url, options) => {
+    calls.push({ url, options })
+
+    return {
+      ok: true,
+      status: 201,
+      statusText: 'Created',
+      text: async () =>
+        JSON.stringify({ checkout_url: 'https://pay.bachs.io/c/plain' })
+    }
+  })
+
+  await checkout({
+    apiKey: 'sk_sandbox_123',
+    items: [{ product: 'prod_abc123' }]
+  })
+
+  const body = JSON.parse(calls[0].options.body)
+  assert.equal('transfer_data' in body, false)
+  assert.equal('platform_fee' in body, false)
+})
+
+const invalidConnectCases = [
+  {
+    name: 'connect that is not an object',
+    inputs: { items: [{ product: 'prod_abc123' }], connect: 'acct_123' },
+    field: 'connect',
+    message: /must be an object/
+  },
+  {
+    name: 'connect on a pure checkout',
+    inputs: {
+      amount: '10500.00',
+      currency: 'NGN',
+      connect: { destination: 'acct_123', platformFee: '500.00' }
+    },
+    field: 'connect',
+    message: /only supported on product checkout sessions/
+  },
+  {
+    name: 'connect without a destination',
+    inputs: {
+      items: [{ product: 'prod_abc123' }],
+      connect: { platformFee: '500.00' }
+    },
+    field: 'connect.destination',
+    message: /connected account ID/
+  },
+  {
+    name: 'connect without a platform fee',
+    inputs: {
+      items: [{ product: 'prod_abc123' }],
+      connect: { destination: 'acct_123' }
+    },
+    field: 'connect.platformFee',
+    message: /positive decimal string/
+  },
+  {
+    name: 'a numeric platform fee',
+    inputs: {
+      items: [{ product: 'prod_abc123' }],
+      connect: { destination: 'acct_123', platformFee: 500 }
+    },
+    field: 'connect.platformFee',
+    message: /positive decimal string/
+  },
+  {
+    name: 'a zero platform fee',
+    inputs: {
+      items: [{ product: 'prod_abc123' }],
+      connect: { destination: 'acct_123', platformFee: '0.00' }
+    },
+    field: 'connect.platformFee',
+    message: /positive decimal string/
+  },
+  {
+    name: 'an unknown connect field',
+    inputs: {
+      items: [{ product: 'prod_abc123' }],
+      connect: {
+        destination: 'acct_123',
+        platformFee: '500.00',
+        amount: '10000.00'
+      }
+    },
+    field: 'connect.amount',
+    message: /is not supported/
+  }
+]
+
+for (const invalidCase of invalidConnectCases) {
+  test(`checkout rejects ${invalidCase.name} before calling Bachs`, async () => {
+    let fetchCalls = 0
+
+    fetch.setFetchImplementation(async () => {
+      fetchCalls += 1
+    })
+
+    await assert.rejects(
+      () => checkout({ apiKey: 'sk_sandbox_123', ...invalidCase.inputs }),
+      (error) => {
+        assert.equal(error.exit, 'invalidRequest')
+        assert.equal(error.raw.field, invalidCase.field)
+        assert.match(error.raw.message, invalidCase.message)
+        return true
+      }
+    )
+
+    assert.equal(fetchCalls, 0)
+  })
+}

package/test/connect.test.js

@@ -0,0 +1,390 @@
+const { test, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const adapter = require('../adapter')
+const fetch = require('../helpers/fetch')
+
+afterEach(() => {
+  adapter.config = {}
+  fetch.resetFetchImplementation()
+})
+
+function jsonResponse(body, status = 200) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status >= 200 && status < 300 ? 'OK' : 'Request failed',
+    text: async () => JSON.stringify(body)
+  }
+}
+
+function recordCalls(responses) {
+  const calls = []
+  fetch.setFetchImplementation(async (url, options) => {
+    calls.push({ url, options })
+    const next = responses[calls.length - 1]
+    return jsonResponse(next.body, next.status)
+  })
+  return calls
+}
+
+test('adapter exposes exactly the Connect surface', () => {
+  assert.deepEqual(Object.keys(adapter.connect).sort(), [
+    'account',
+    'balance',
+    'payout',
+    'transfer'
+  ])
+  assert.deepEqual(Object.keys(adapter.connect.account).sort(), [
+    'create',
+    'get',
+    'link'
+  ])
+  assert.deepEqual(Object.keys(adapter.connect.transfer), ['create'])
+  assert.deepEqual(Object.keys(adapter.connect.balance), ['get'])
+  assert.deepEqual(Object.keys(adapter.connect.payout), ['create'])
+})
+
+test('connect.account.create requests a recipient account and normalizes it', async () => {
+  const calls = recordCalls([
+    {
+      status: 201,
+      body: {
+        id: 'acct_123',
+        display_name: 'Ada Obi',
+        country: 'NG',
+        capabilities: {
+          transfers: { status: 'pending', requested: true },
+          payouts: { status: 'unrequested', requested: false }
+        },
+        requirements: { currently_due: ['payout_destination'] }
+      }
+    }
+  ])
+
+  const account = await adapter.connect.account.create({
+    apiKey: 'sk_sandbox_123',
+    email: 'ada@example.com',
+    name: 'Ada Obi',
+    idempotencyKey: 'maintainer-42'
+  })
+
+  assert.equal(calls[0].url, 'https://sandbox-api.bachs.io/v1/accounts')
+  assert.equal(calls[0].options.method, 'POST')
+  assert.equal(calls[0].options.headers['Idempotency-Key'], 'maintainer-42')
+  assert.equal(calls[0].options.headers['X-Account-Id'], undefined)
+  assert.deepEqual(JSON.parse(calls[0].options.body), {
+    contact_email: 'ada@example.com',
+    display_name: 'Ada Obi',
+    country: 'NG',
+    entity_type: 'individual',
+    configuration: {
+      recipient: {
+        capabilities: {
+          transfers: { requested: true },
+          payouts: { requested: true }
+        }
+      }
+    }
+  })
+
+  assert.equal(account.id, 'acct_123')
+  assert.equal(account.email, 'ada@example.com')
+  assert.equal(account.name, 'Ada Obi')
+  assert.equal(account.country, 'NG')
+  assert.deepEqual(account.capabilities, {
+    transfers: 'pending',
+    payouts: 'inactive'
+  })
+  assert.deepEqual(account.requirements, ['payout_destination'])
+  assert.equal(account.raw.id, 'acct_123')
+})
+
+test('connect.account.get reads the account by id', async () => {
+  const calls = recordCalls([
+    {
+      body: {
+        id: 'acct_1/2',
+        capabilities: { payouts: { status: 'active' } },
+        requirements: { currently_due: [] }
+      }
+    }
+  ])
+
+  const account = await adapter.connect.account.get({
+    apiKey: 'sk_sandbox_123',
+    account: 'acct_1/2'
+  })
+
+  assert.equal(
+    calls[0].url,
+    'https://sandbox-api.bachs.io/v1/accounts/acct_1%2F2'
+  )
+  assert.equal(calls[0].options.method, 'GET')
+  assert.deepEqual(account.capabilities, { payouts: 'active' })
+  assert.deepEqual(account.requirements, [])
+})
+
+test('connect.account.link creates a hosted onboarding link', async () => {
+  const calls = recordCalls([
+    {
+      body: {
+        url: 'https://connect.bachs.io/l/abc',
+        expires_at: '2026-09-14T16:00:00Z'
+      }
+    }
+  ])
+
+  const link = await adapter.connect.account.link({
+    apiKey: 'sk_sandbox_123',
+    account: 'acct_123',
+    returnUrl: 'https://flossafrica.com/payouts/return',
+    refreshUrl: 'https://flossafrica.com/payouts/refresh'
+  })
+
+  assert.equal(
+    calls[0].url,
+    'https://sandbox-api.bachs.io/v1/accounts/acct_123/account-links'
+  )
+  assert.deepEqual(JSON.parse(calls[0].options.body), {
+    type: 'onboarding',
+    refresh_url: 'https://flossafrica.com/payouts/refresh',
+    return_url: 'https://flossafrica.com/payouts/return'
+  })
+  assert.equal(link.url, 'https://connect.bachs.io/l/abc')
+  assert.equal(link.expiresAt, '2026-09-14T16:00:00Z')
+})
+
+test('connect.transfer.create moves platform funds to the account', async () => {
+  const calls = recordCalls([
+    {
+      status: 201,
+      body: {
+        id: 'tr_1',
+        destination: 'acct_123',
+        amount: '10000.00',
+        currency: 'NGN',
+        transfer_group: 'pool-2026-09',
+        status: 'paid'
+      }
+    }
+  ])
+
+  const transfer = await adapter.connect.transfer.create({
+    apiKey: 'sk_sandbox_123',
+    account: 'acct_123',
+    amount: '10000.00',
+    currency: 'NGN',
+    group: 'pool-2026-09',
+    idempotencyKey: 'pool-2026-09-acct_123'
+  })
+
+  assert.equal(calls[0].url, 'https://sandbox-api.bachs.io/v1/transfers')
+  assert.equal(calls[0].options.headers['X-Account-Id'], undefined)
+  assert.equal(
+    calls[0].options.headers['Idempotency-Key'],
+    'pool-2026-09-acct_123'
+  )
+  assert.deepEqual(JSON.parse(calls[0].options.body), {
+    destination: 'acct_123',
+    amount: '10000.00',
+    currency: 'NGN',
+    transfer_group: 'pool-2026-09'
+  })
+  assert.deepEqual(
+    { ...transfer, raw: undefined },
+    {
+      id: 'tr_1',
+      account: 'acct_123',
+      amount: '10000.00',
+      currency: 'NGN',
+      group: 'pool-2026-09',
+      status: 'paid',
+      raw: undefined
+    }
+  )
+})
+
+test('connect.balance.get acts as the account and returns one entry per currency', async () => {
+  const calls = recordCalls([
+    {
+      body: {
+        account_id: 'acct_123',
+        balances: [
+          {
+            currency: 'NGN',
+            available_balance: '12000.00',
+            pending_balance: '0.00'
+          },
+          {
+            currency: 'USD',
+            available_balance: '5.00',
+            pending_balance: '1.00'
+          }
+        ],
+        total_balance_usd: '13.00'
+      }
+    }
+  ])
+
+  const balances = await adapter.connect.balance.get({
+    apiKey: 'sk_sandbox_123',
+    account: 'acct_123'
+  })
+
+  assert.equal(calls[0].url, 'https://sandbox-api.bachs.io/v1/balances')
+  assert.equal(calls[0].options.headers['X-Account-Id'], 'acct_123')
+  assert.deepEqual(balances, [
+    { currency: 'NGN', available: '12000.00', pending: '0.00' },
+    { currency: 'USD', available: '5.00', pending: '1.00' }
+  ])
+})
+
+test('connect.payout.create resolves the default destination for the currency', async () => {
+  const calls = recordCalls([
+    {
+      body: {
+        destinations: [
+          { id: 'pd_old', is_usable: true, is_default: false },
+          { id: 'pd_broken', is_usable: false, is_default: false },
+          { id: 'pd_default', is_usable: true, is_default: true }
+        ],
+        total: 3,
+        limit: 20,
+        offset: 0
+      }
+    },
+    {
+      body: {
+        id: 'pay_1',
+        status: 'processing',
+        amount: '9000.00',
+        currency: 'NGN',
+        fee: '50.00',
+        total_debited: '9050.00',
+        destination: 'pd_default'
+      }
+    }
+  ])
+
+  const payout = await adapter.connect.payout.create({
+    apiKey: 'sk_sandbox_123',
+    account: 'acct_123',
+    amount: '9000.00',
+    currency: 'NGN',
+    reference: 'withdrawal-1',
+    idempotencyKey: 'withdrawal-1-attempt-1'
+  })
+
+  assert.equal(
+    calls[0].url,
+    'https://sandbox-api.bachs.io/v1/payouts/destinations?currency=NGN'
+  )
+  assert.equal(calls[0].options.headers['X-Account-Id'], 'acct_123')
+  assert.equal(calls[1].url, 'https://sandbox-api.bachs.io/v1/payouts')
+  assert.equal(calls[1].options.headers['X-Account-Id'], 'acct_123')
+  assert.equal(
+    calls[1].options.headers['Idempotency-Key'],
+    'withdrawal-1-attempt-1'
+  )
+  assert.deepEqual(JSON.parse(calls[1].options.body), {
+    destination: 'pd_default',
+    amount: '9000.00',
+    reference: 'withdrawal-1'
+  })
+  assert.deepEqual(
+    { ...payout, raw: undefined },
+    {
+      id: 'pay_1',
+      account: 'acct_123',
+      amount: '9000.00',
+      currency: 'NGN',
+      fee: '50.00',
+      destination: 'pd_default',
+      status: 'pending',
+      raw: undefined
+    }
+  )
+})
+
+test('connect.payout.create uses an explicit destination without a lookup', async () => {
+  const calls = recordCalls([
+    {
+      body: {
+        id: 'pay_2',
+        status: 'completed',
+        amount: '100.00',
+        currency: 'NGN',
+        destination: 'pd_1'
+      }
+    }
+  ])
+
+  const payout = await adapter.connect.payout.create({
+    apiKey: 'sk_sandbox_123',
+    account: 'acct_123',
+    amount: '100.00',
+    destination: 'pd_1',
+    idempotencyKey: 'withdrawal-2'
+  })
+
+  assert.equal(calls.length, 1)
+  assert.equal(payout.status, 'paid')
+})
+
+test('connect.payout.create exits noDestination when nothing is usable', async () => {
+  recordCalls([
+    {
+      body: {
+        destinations: [{ id: 'pd_review', is_usable: false }],
+        total: 1,
+        limit: 20,
+        offset: 0
+      }
+    }
+  ])
+
+  await assert.rejects(
+    adapter.connect.payout.create({
+      apiKey: 'sk_sandbox_123',
+      account: 'acct_123',
+      amount: '100.00',
+      currency: 'NGN'
+    }),
+    (error) => error.exit === 'noDestination'
+  )
+})
+
+test('connect.payout.create exits noDestination without a destination or currency', async () => {
+  const calls = recordCalls([])
+
+  await assert.rejects(
+    adapter.connect.payout.create({
+      apiKey: 'sk_sandbox_123',
+      account: 'acct_123',
+      amount: '100.00'
+    }),
+    (error) => error.exit === 'noDestination'
+  )
+  assert.equal(calls.length, 0)
+})
+
+test('Connect errors surface the normalized Bachs error', async () => {
+  recordCalls([
+    {
+      status: 400,
+      body: { error_code: 'INSUFFICIENT_BALANCE', detail: 'Not enough funds' }
+    }
+  ])
+
+  await assert.rejects(
+    adapter.connect.transfer.create({
+      apiKey: 'sk_sandbox_123',
+      account: 'acct_123',
+      amount: '1.00',
+      currency: 'NGN'
+    }),
+    (error) =>
+      error.exit === 'couldNotCreateTransfer' &&
+      error.raw.code === 'INSUFFICIENT_BALANCE'
+  )
+})