@sails-pay/bachs 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 The Sailscasts Company
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/adapter.js

@@ -0,0 +1,14 @@
+const methods = require('./machines')
+
+module.exports = {
+  identity: 'sails-bachs',
+  config: {},
+  checkout: methods.checkout,
+  verify: methods.verify,
+  webhooks: {
+    verify: methods.webhooks.verify
+  },
+  refund: {
+    create: methods.refund.create
+  }
+}

package/helpers/fetch.js

@@ -0,0 +1,88 @@
+const { fetch: undiciFetch } = require('undici')
+const normalizeError = require('./normalize-error')
+
+const liveBaseUrl = 'https://api.bachs.io'
+const sandboxBaseUrl = 'https://sandbox-api.bachs.io'
+const defaultHeaders = {
+  Accept: 'application/json',
+  'Content-Type': 'application/json'
+}
+
+let fetchImpl = typeof global.fetch !== 'undefined' ? global.fetch : undiciFetch
+
+function resolveBaseUrl({ apiKey, baseUrl } = {}) {
+  if (baseUrl) {
+    return baseUrl
+  }
+
+  if (apiKey && apiKey.startsWith('sk_sandbox_')) {
+    return sandboxBaseUrl
+  }
+
+  return liveBaseUrl
+}
+
+function getVersionedPath(path) {
+  if (path.startsWith('/v1/')) {
+    return path
+  }
+
+  return `/v1${path.startsWith('/') ? path : `/${path}`}`
+}
+
+async function parseJsonResponse(response) {
+  const text = await response.text()
+
+  if (!text) {
+    return null
+  }
+
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    return text
+  }
+}
+
+const fetch = async (path, options = {}) => {
+  const { apiKey, baseUrl, idempotencyKey, headers, body, ...requestOptions } =
+    options
+  const url = new URL(
+    getVersionedPath(path),
+    resolveBaseUrl({ apiKey, baseUrl })
+  ).toString()
+
+  const mergedHeaders = {
+    ...defaultHeaders,
+    ...(apiKey && { Authorization: `Bearer ${apiKey}` }),
+    ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey }),
+    ...(headers || {})
+  }
+
+  const response = await fetchImpl(url, {
+    ...requestOptions,
+    headers: mergedHeaders,
+    ...(body !== undefined && {
+      body: typeof body === 'string' ? body : JSON.stringify(body)
+    })
+  })
+  const responseBody = await parseJsonResponse(response)
+
+  if (!response.ok) {
+    const error = new Error('Bachs API request failed')
+    error.bachs = normalizeError(responseBody, response)
+    throw error
+  }
+
+  return responseBody
+}
+
+fetch.resolveBaseUrl = resolveBaseUrl
+fetch.setFetchImplementation = function setFetchImplementation(implementation) {
+  fetchImpl = implementation
+}
+fetch.resetFetchImplementation = function resetFetchImplementation() {
+  fetchImpl = typeof global.fetch !== 'undefined' ? global.fetch : undiciFetch
+}
+
+module.exports = fetch

package/helpers/normalize-error.js

@@ -0,0 +1,20 @@
+function normalizeError(error, response) {
+  const body = error || {}
+  const nestedError = body.error || {}
+
+  return {
+    statusCode: response && response.status,
+    statusText: response && response.statusText,
+    code: body.error_code || nestedError.code,
+    message:
+      body.detail ||
+      body.message ||
+      nestedError.message ||
+      (response && response.statusText) ||
+      'Bachs API request failed',
+    errors: body.errors || nestedError.details,
+    body
+  }
+}
+
+module.exports = normalizeError

package/helpers/parameters.js

@@ -0,0 +1,47 @@
+/**
+ * Common input definitions shared by the Bachs machines.
+ *
+ * @type {Dictionary}
+ * @constant
+ */
+
+module.exports = {
+  BACHS_API_KEY: {
+    type: 'string',
+    friendlyName: 'API Key',
+    description: 'A valid Bachs secret API key.',
+    protect: true,
+    whereToGet: {
+      url: 'https://bachs.io',
+      description: 'Generate a secret key in your Bachs dashboard.'
+    }
+  },
+  BACHS_BASE_URL: {
+    type: 'string',
+    friendlyName: 'Base URL',
+    description:
+      'Optional Bachs API base URL. Defaults from the API key environment.'
+  },
+  BACHS_WEBHOOK_SECRET: {
+    type: 'string',
+    friendlyName: 'Webhook Secret',
+    description: 'The signing secret for your Bachs webhook destination.',
+    protect: true
+  },
+  BACHS_RETURN_URL: {
+    type: 'string',
+    friendlyName: 'Return URL',
+    description:
+      'Default URL Bachs redirects to after checkout-session payment.'
+  },
+  BACHS_SUCCESS_URL: {
+    type: 'string',
+    friendlyName: 'Success URL',
+    description: 'Default URL Bachs redirects to after pure checkout payment.'
+  },
+  BACHS_CANCEL_URL: {
+    type: 'string',
+    friendlyName: 'Cancel URL',
+    description: 'Default URL Bachs redirects to when checkout is cancelled.'
+  }
+}

package/helpers/payloads.js

@@ -0,0 +1,146 @@
+function withoutUndefined(value) {
+  if (Array.isArray(value)) {
+    return value.map(withoutUndefined)
+  }
+
+  if (!value || typeof value !== 'object') {
+    return value
+  }
+
+  return Object.entries(value).reduce((memo, [key, entryValue]) => {
+    if (entryValue !== undefined) {
+      memo[key] = withoutUndefined(entryValue)
+    }
+
+    return memo
+  }, {})
+}
+
+function buildCustomerPayload(inputs) {
+  const checkoutData = inputs.checkoutData || {}
+  const customer = inputs.customer || {}
+  const customerId = customer.customerId || customer.id
+
+  if (customerId) {
+    return withoutUndefined({
+      customer_id: customerId
+    })
+  }
+
+  return withoutUndefined({
+    email:
+      customer.email ||
+      inputs.customerEmail ||
+      inputs.email ||
+      checkoutData.email,
+    name:
+      customer.name || inputs.customerName || inputs.name || checkoutData.name,
+    phone_number: customer.phoneNumber || inputs.phoneNumber
+  })
+}
+
+function buildProductCart(items) {
+  if (!items) {
+    return undefined
+  }
+
+  return items.map((item) =>
+    withoutUndefined({
+      product_id: item.product || item.productId,
+      quantity: item.quantity,
+      amount: item.amount
+    })
+  )
+}
+
+function buildCheckoutSessionPayload(inputs, adapterConfig = {}) {
+  const productCollectionId =
+    inputs.productCollectionId || inputs.productCollection
+  const checkoutData = inputs.checkoutData || {}
+  const returnUrl =
+    inputs.returnUrl ||
+    inputs.successUrl ||
+    adapterConfig.returnUrl ||
+    adapterConfig.successUrl
+
+  return withoutUndefined({
+    customer: buildCustomerPayload(inputs),
+    product_cart: buildProductCart(inputs.items),
+    product_collection_id: productCollectionId,
+    billing_currency: inputs.billingCurrency,
+    allowed_payment_method_types: inputs.allowedPaymentMethodTypes,
+    return_url: returnUrl,
+    cancel_url: inputs.cancelUrl || adapterConfig.cancelUrl,
+    reference: inputs.reference,
+    metadata: inputs.metadata || checkoutData.custom
+  })
+}
+
+function buildPricingPayload(inputs) {
+  let pricing
+
+  if (inputs.pricing) {
+    const { currencyOptions, ...pricingInput } = inputs.pricing
+
+    pricing = withoutUndefined({
+      ...pricingInput,
+      currency_options: currencyOptions || inputs.currencyOptions
+    })
+  } else {
+    pricing = withoutUndefined({
+      currency: inputs.currency,
+      amount: inputs.amount,
+      currency_options: inputs.currencyOptions
+    })
+  }
+
+  return Object.keys(pricing).length > 0 ? pricing : undefined
+}
+
+function buildPureCheckoutPayload(inputs, adapterConfig = {}) {
+  const checkoutData = inputs.checkoutData || {}
+  const customer = inputs.customer || {}
+
+  return withoutUndefined({
+    pricing: buildPricingPayload(inputs),
+    customer_email:
+      inputs.customerEmail ||
+      inputs.email ||
+      customer.email ||
+      checkoutData.email,
+    customer_name:
+      inputs.customerName || inputs.name || customer.name || checkoutData.name,
+    success_url:
+      inputs.successUrl ||
+      inputs.returnUrl ||
+      adapterConfig.successUrl ||
+      adapterConfig.returnUrl,
+    cancel_url: inputs.cancelUrl || adapterConfig.cancelUrl,
+    reference: inputs.reference,
+    metadata: inputs.metadata || checkoutData.custom,
+    expires_in_minutes: inputs.expiresInMinutes,
+    simulated_outcome: inputs.simulatedOutcome
+  })
+}
+
+function buildRefundPayload(inputs) {
+  return withoutUndefined({
+    charge_id: inputs.chargeId,
+    reference: inputs.reference,
+    refund_address: inputs.refundAddress,
+    amount: inputs.amount,
+    fee_bearer: inputs.feeBearer,
+    reason: inputs.reason,
+    idempotency_key: inputs.idempotencyKey,
+    simulated_outcome: inputs.simulatedOutcome
+  })
+}
+
+module.exports = {
+  buildCheckoutSessionPayload,
+  buildPureCheckoutPayload,
+  buildRefundPayload,
+  buildProductCart,
+  buildCustomerPayload,
+  withoutUndefined
+}

package/machines/checkout/get.js

@@ -0,0 +1,47 @@
+const fetch = require('../../helpers/fetch')
+const parameters = require('../../helpers/parameters')
+
+module.exports = require('machine').build({
+  friendlyName: 'Get checkout',
+  description: 'Retrieves a Bachs checkout by checkout ID.',
+  moreInfoUrl: 'https://docs.bachs.io/api-reference/checkouts/get-checkout',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    checkoutId: {
+      type: 'string',
+      required: true,
+      description: 'The Bachs checkout ID.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The Bachs checkout.',
+      outputVariableName: 'checkout',
+      outputType: 'ref'
+    },
+    couldNotGetCheckout: {
+      description: 'Checkout could not be retrieved.',
+      outputVariableName: 'errors',
+      outputType: 'ref'
+    }
+  },
+  fn: async function ({ apiKey, baseUrl, checkoutId }, exits) {
+    const adapterConfig = require('../../adapter').config
+
+    try {
+      const checkout = await fetch(
+        `/checkouts/${encodeURIComponent(checkoutId)}`,
+        {
+          method: 'GET',
+          apiKey: apiKey || adapterConfig.apiKey,
+          baseUrl: baseUrl || adapterConfig.baseUrl
+        }
+      )
+
+      return exits.success(checkout)
+    } catch (error) {
+      return exits.couldNotGetCheckout(error.bachs || error)
+    }
+  }
+})

package/machines/checkout.js

@@ -0,0 +1,181 @@
+const fetch = require('../helpers/fetch')
+const {
+  buildCheckoutSessionPayload,
+  buildPureCheckoutPayload
+} = require('../helpers/payloads')
+const parameters = require('../helpers/parameters')
+
+module.exports = require('machine').build({
+  friendlyName: 'Checkout',
+  description:
+    'Creates and returns a Bachs hosted checkout URL using products or pricing.',
+  moreInfoUrl: 'https://docs.bachs.io/guides/checkout/checkout-sessions',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    items: {
+      type: 'ref',
+      description:
+        'Product items for Bachs Checkout Sessions. Each item should use product or productId plus optional quantity and amount.'
+    },
+    productCollectionId: {
+      type: 'string',
+      description:
+        'Bachs product collection ID for selection-mode checkout sessions.'
+    },
+    productCollection: {
+      type: 'string',
+      description:
+        'Alias for productCollectionId. Bachs maps this to product_collection_id.'
+    },
+    billingCurrency: {
+      type: 'string',
+      description:
+        'Currency code used to select a product price row for checkout sessions.'
+    },
+    allowedPaymentMethodTypes: {
+      type: 'ref',
+      description: 'Payment method allowlist, e.g. ["bank_transfer", "card"].'
+    },
+    returnUrl: {
+      type: 'string',
+      description:
+        'URL Bachs redirects to after a checkout-session payment. Maps to return_url.'
+    },
+    successUrl: {
+      type: 'string',
+      description:
+        'URL Bachs redirects to after a pure checkout payment. Maps to success_url.'
+    },
+    cancelUrl: parameters.BACHS_CANCEL_URL,
+    customer: {
+      type: 'ref',
+      description:
+        'Customer details. Use customerId for existing customers or email/name/phoneNumber for new customers.'
+    },
+    customerEmail: {
+      type: 'string',
+      description: "Customer's email address."
+    },
+    customerName: {
+      type: 'string',
+      description: "Customer's full name."
+    },
+    phoneNumber: {
+      type: 'string',
+      description: "Customer's phone number."
+    },
+    email: {
+      type: 'string',
+      description: 'Compatibility alias for customerEmail.'
+    },
+    name: {
+      type: 'string',
+      description: 'Compatibility alias for customerName.'
+    },
+    reference: {
+      type: 'string',
+      description:
+        'Merchant reference for the checkout. Bachs requires this to be unique per organization when supplied.'
+    },
+    metadata: {
+      type: 'ref',
+      description: 'Metadata returned in Bachs webhook payloads.'
+    },
+    checkoutData: {
+      type: 'ref',
+      description:
+        'Compatibility shape for checkoutData.email, checkoutData.name, and checkoutData.custom.'
+    },
+    idempotencyKey: {
+      type: 'string',
+      description:
+        'Optional Idempotency-Key header. Defaults to reference when available.'
+    },
+    pricing: {
+      type: 'ref',
+      description: 'Pure Checkout pricing object.'
+    },
+    amount: {
+      type: 'string',
+      description: 'Pure Checkout amount, e.g. "50.00".'
+    },
+    currency: {
+      type: 'string',
+      description: 'Pure Checkout currency, e.g. "USD" or "NGN".'
+    },
+    currencyOptions: {
+      type: 'ref',
+      description: 'Pure Checkout per-currency amount overrides.'
+    },
+    expiresInMinutes: {
+      type: 'number',
+      description: 'Pure Checkout expiry in minutes.'
+    },
+    simulatedOutcome: {
+      type: 'string',
+      description: 'Sandbox-only forced outcome.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The hosted checkout URL.',
+      outputVariableName: 'checkoutUrl',
+      outputType: 'string'
+    },
+    invalidRequest: {
+      description: 'The Bachs checkout request is missing required input.',
+      outputVariableName: 'errors',
+      outputType: 'ref'
+    },
+    couldNotCreateCheckoutUrl: {
+      description: 'Checkout URL could not be created.',
+      outputVariableName: 'errors',
+      outputType: 'ref'
+    }
+  },
+  fn: async function (inputs, exits) {
+    const adapterConfig = require('../adapter').config
+    const hasItems = Array.isArray(inputs.items) && inputs.items.length > 0
+    const hasProductCollection = Boolean(
+      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({
+        message:
+          'Provide exactly one of items or productCollectionId for a Bachs checkout session.'
+      })
+    }
+
+    if (!shouldUseCheckoutSession && !payload.pricing) {
+      return exits.invalidRequest({
+        message:
+          'Provide product items/productCollectionId or pure checkout pricing.'
+      })
+    }
+
+    try {
+      const checkout = await fetch(path, {
+        method: 'POST',
+        apiKey: inputs.apiKey || adapterConfig.apiKey,
+        baseUrl: inputs.baseUrl || adapterConfig.baseUrl,
+        idempotencyKey: inputs.idempotencyKey || inputs.reference,
+        body: payload
+      })
+
+      if (!checkout || !checkout.checkout_url) {
+        return exits.couldNotCreateCheckoutUrl(checkout)
+      }
+
+      return exits.success(checkout.checkout_url)
+    } catch (error) {
+      return exits.couldNotCreateCheckoutUrl(error.bachs || error)
+    }
+  }
+})

package/machines/index.js

@@ -0,0 +1,14 @@
+const checkout = require('./checkout')
+
+checkout.get = require('./checkout/get')
+
+module.exports = {
+  checkout,
+  verify: require('./verify'),
+  webhooks: {
+    verify: require('./webhooks/verify')
+  },
+  refund: {
+    create: require('./refund/create')
+  }
+}

package/machines/refund/create.js

@@ -0,0 +1,79 @@
+const fetch = require('../../helpers/fetch')
+const { buildRefundPayload } = require('../../helpers/payloads')
+const parameters = require('../../helpers/parameters')
+
+module.exports = require('machine').build({
+  friendlyName: 'Create refund',
+  description: 'Creates a Bachs refund for a completed payment.',
+  moreInfoUrl: 'https://docs.bachs.io/api-reference/refunds/create-refund',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    chargeId: {
+      type: 'string',
+      required: true,
+      description: 'The Bachs charge ID to refund.'
+    },
+    reference: {
+      type: 'string',
+      required: true,
+      description:
+        'Your unique refund reference. Bachs requires this per organization and environment.'
+    },
+    refundAddress: {
+      type: 'string',
+      description: 'Destination wallet address for crypto refunds.'
+    },
+    amount: {
+      type: 'string',
+      description:
+        'Optional partial refund amount in the charge settlement currency.'
+    },
+    feeBearer: {
+      type: 'string',
+      description: 'Who bears the refund fee: org or customer.'
+    },
+    reason: {
+      type: 'string',
+      description: 'Human-readable reason for the refund.'
+    },
+    idempotencyKey: {
+      type: 'string',
+      description:
+        'Optional idempotency key. Sent as both body idempotency_key and Idempotency-Key header.'
+    },
+    simulatedOutcome: {
+      type: 'string',
+      description: 'Sandbox-only forced refund outcome.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The Bachs refund.',
+      outputVariableName: 'refund',
+      outputType: 'ref'
+    },
+    couldNotCreateRefund: {
+      description: 'Refund could not be created.',
+      outputVariableName: 'errors',
+      outputType: 'ref'
+    }
+  },
+  fn: async function (inputs, exits) {
+    const adapterConfig = require('../../adapter').config
+
+    try {
+      const refund = await fetch('/payments/refunds', {
+        method: 'POST',
+        apiKey: inputs.apiKey || adapterConfig.apiKey,
+        baseUrl: inputs.baseUrl || adapterConfig.baseUrl,
+        idempotencyKey: inputs.idempotencyKey || inputs.reference,
+        body: buildRefundPayload(inputs)
+      })
+
+      return exits.success(refund)
+    } catch (error) {
+      return exits.couldNotCreateRefund(error.bachs || error)
+    }
+  }
+})

package/machines/verify.js

@@ -0,0 +1,47 @@
+const fetch = require('../helpers/fetch')
+const parameters = require('../helpers/parameters')
+
+module.exports = require('machine').build({
+  friendlyName: 'Verify charge',
+  description: 'Retrieves the status and details of a Bachs charge.',
+  moreInfoUrl: 'https://docs.bachs.io/guides/payments/get-charge-status',
+  inputs: {
+    apiKey: parameters.BACHS_API_KEY,
+    baseUrl: parameters.BACHS_BASE_URL,
+    chargeId: {
+      type: 'string',
+      required: true,
+      description: 'The Bachs charge ID.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The Bachs charge.',
+      outputVariableName: 'charge',
+      outputType: 'ref'
+    },
+    couldNotVerifyCharge: {
+      description: 'Charge could not be verified.',
+      outputVariableName: 'errors',
+      outputType: 'ref'
+    }
+  },
+  fn: async function ({ apiKey, baseUrl, chargeId }, exits) {
+    const adapterConfig = require('../adapter').config
+
+    try {
+      const charge = await fetch(
+        `/payments/charges/${encodeURIComponent(chargeId)}`,
+        {
+          method: 'GET',
+          apiKey: apiKey || adapterConfig.apiKey,
+          baseUrl: baseUrl || adapterConfig.baseUrl
+        }
+      )
+
+      return exits.success(charge)
+    } catch (error) {
+      return exits.couldNotVerifyCharge(error.bachs || error)
+    }
+  }
+})

package/machines/webhooks/verify.js

@@ -0,0 +1,103 @@
+const crypto = require('crypto')
+const parameters = require('../../helpers/parameters')
+
+function normalizeRawBody(rawBody) {
+  if (Buffer.isBuffer(rawBody)) {
+    return rawBody.toString('utf8')
+  }
+
+  return rawBody
+}
+
+function safelyCompare(expected, received) {
+  const expectedBuffer = Buffer.from(expected)
+  const receivedBuffer = Buffer.from(received)
+
+  if (expectedBuffer.length !== receivedBuffer.length) {
+    return false
+  }
+
+  return crypto.timingSafeEqual(expectedBuffer, receivedBuffer)
+}
+
+module.exports = require('machine').build({
+  friendlyName: 'Verify Bachs webhook signature',
+  description: 'Verifies X-Bachs-Timestamp and X-Bachs-Signature.',
+  moreInfoUrl: 'https://docs.bachs.io/guides/webhooks/overview',
+  inputs: {
+    webhookSecret: parameters.BACHS_WEBHOOK_SECRET,
+    rawBody: {
+      type: 'ref',
+      required: true,
+      description: 'The exact raw request body string or Buffer.'
+    },
+    timestamp: {
+      type: 'string',
+      required: true,
+      description: 'The X-Bachs-Timestamp header value.'
+    },
+    signature: {
+      type: 'string',
+      required: true,
+      description: 'The X-Bachs-Signature header value.'
+    },
+    toleranceSeconds: {
+      type: 'number',
+      defaultsTo: 300,
+      description: 'Maximum allowed timestamp skew in seconds.'
+    }
+  },
+  exits: {
+    success: {
+      description: 'The signature is valid.',
+      outputVariableName: 'valid',
+      outputType: 'boolean'
+    },
+    invalidSignature: {
+      description: 'The signature is missing, stale, or invalid.',
+      outputVariableName: 'error',
+      outputType: 'ref'
+    }
+  },
+  fn: async function (
+    { webhookSecret, rawBody, timestamp, signature, toleranceSeconds },
+    exits
+  ) {
+    const adapterConfig = require('../../adapter').config
+    const secret = webhookSecret || adapterConfig.webhookSecret
+
+    if (!secret || !timestamp || !signature) {
+      return exits.invalidSignature({
+        message: 'Missing Bachs webhook signing data.'
+      })
+    }
+
+    const parsedTimestamp = Number.parseInt(timestamp, 10)
+
+    if (!Number.isFinite(parsedTimestamp)) {
+      return exits.invalidSignature({
+        message: 'Invalid Bachs webhook timestamp.'
+      })
+    }
+
+    if (Math.abs(Date.now() / 1000 - parsedTimestamp) > toleranceSeconds) {
+      return exits.invalidSignature({
+        message: 'Stale Bachs webhook timestamp.'
+      })
+    }
+
+    const rawBodyString = normalizeRawBody(rawBody)
+    const expected = crypto
+      .createHmac('sha256', secret)
+      .update(`${timestamp}.${rawBodyString}`, 'utf8')
+      .digest('hex')
+
+    if (!safelyCompare(expected, signature)) {
+      return exits.invalidSignature({
+        message: 'Invalid Bachs webhook signature.'
+      })
+    }
+
+    return exits.success(true)
+  }
+})

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@sails-pay/bachs",
+  "version": "0.0.1",
+  "description": "Bachs adapter for Sails Pay",
+  "main": "adapter.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "homepage": "https://github.com/sailscastshq/sails-pay#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sailscastshq/sails-pay.git",
+    "directory": "packages/sails-bachs"
+  },
+  "bugs": {
+    "url": "https://github.com/sailscastshq/sails-pay/issues"
+  },
+  "keywords": [
+    "Bachs",
+    "Sails",
+    "Pay",
+    "Payments",
+    "payment-gateway",
+    "online-payments",
+    "sails",
+    "sails.js",
+    "payment-integration"
+  ],
+  "author": "Kelvin Omereshone <kelvin@sailscasts.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "machine": "^15.2.3",
+    "undici": "^6.19.2"
+  }
+}

package/test/checkout.test.js

@@ -0,0 +1,100 @@
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const adapter = require('../adapter')
+const checkout = require('../machines/checkout')
+const fetch = require('../helpers/fetch')
+
+test('checkout creates a Bachs checkout session from camelCase inputs', 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_123',
+          checkout_url: 'https://pay.bachs.io/c/test'
+        })
+    }
+  })
+
+  const checkoutUrl = await checkout({
+    apiKey: 'sk_sandbox_123',
+    items: [{ product: 'prod_abc123', quantity: 1 }],
+    customer: {
+      email: 'customer@example.com',
+      name: 'Jane Doe'
+    },
+    returnUrl: 'https://example.com/return',
+    cancelUrl: 'https://example.com/cancel',
+    reference: 'order_123'
+  })
+
+  assert.equal(checkoutUrl, 'https://pay.bachs.io/c/test')
+  assert.equal(
+    calls[0].url,
+    'https://sandbox-api.bachs.io/v1/checkout-sessions'
+  )
+  assert.equal(calls[0].options.headers['Idempotency-Key'], 'order_123')
+  assert.deepEqual(JSON.parse(calls[0].options.body), {
+    customer: {
+      email: 'customer@example.com',
+      name: 'Jane Doe'
+    },
+    product_cart: [
+      {
+        product_id: 'prod_abc123',
+        quantity: 1
+      }
+    ],
+    return_url: 'https://example.com/return',
+    cancel_url: 'https://example.com/cancel',
+    reference: 'order_123'
+  })
+
+  fetch.resetFetchImplementation()
+})
+
+test('adapter exposes checkout.get as the uniform checkout lookup API', async () => {
+  const calls = []
+
+  fetch.setFetchImplementation(async (url, options) => {
+    calls.push({ url, options })
+
+    return {
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      text: async () =>
+        JSON.stringify({
+          checkout_id: 'chk_123',
+          status: 'COMPLETED',
+          charge: {
+            charge_id: 'chr_123',
+            status: 'succeeded'
+          }
+        })
+    }
+  })
+
+  const result = await adapter.checkout.get({
+    apiKey: 'sk_sandbox_123',
+    checkoutId: 'chk_123'
+  })
+
+  assert.equal(typeof adapter.checkout, 'function')
+  assert.equal(typeof adapter.checkout.get, 'function')
+  assert.equal(result.checkout_id, 'chk_123')
+  assert.equal(result.charge.charge_id, 'chr_123')
+  assert.equal(
+    calls[0].url,
+    'https://sandbox-api.bachs.io/v1/checkouts/chk_123'
+  )
+  assert.equal(calls[0].options.method, 'GET')
+
+  fetch.resetFetchImplementation()
+})

package/test/fetch.test.js

@@ -0,0 +1,104 @@
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const fetch = require('../helpers/fetch')
+
+test('resolveBaseUrl uses configured URL first', () => {
+  assert.equal(
+    fetch.resolveBaseUrl({
+      apiKey: 'sk_sandbox_123',
+      baseUrl: 'https://example.test'
+    }),
+    'https://example.test'
+  )
+})
+
+test('resolveBaseUrl derives sandbox URL from sandbox keys', () => {
+  assert.equal(
+    fetch.resolveBaseUrl({ apiKey: 'sk_sandbox_123' }),
+    'https://sandbox-api.bachs.io'
+  )
+})
+
+test('resolveBaseUrl defaults to live URL', () => {
+  assert.equal(
+    fetch.resolveBaseUrl({ apiKey: 'sk_live_123' }),
+    'https://api.bachs.io'
+  )
+})
+
+test('fetch prefixes /v1, sends auth, idempotency, and JSON body', 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/test' })
+    }
+  })
+
+  const response = await fetch('/checkout-sessions', {
+    method: 'POST',
+    apiKey: 'sk_sandbox_123',
+    idempotencyKey: 'order_123',
+    body: {
+      reference: 'order_123'
+    }
+  })
+
+  assert.deepEqual(response, {
+    checkout_url: 'https://pay.bachs.io/c/test'
+  })
+  assert.equal(
+    calls[0].url,
+    'https://sandbox-api.bachs.io/v1/checkout-sessions'
+  )
+  assert.equal(calls[0].options.method, 'POST')
+  assert.equal(calls[0].options.headers.Authorization, 'Bearer sk_sandbox_123')
+  assert.equal(calls[0].options.headers['Idempotency-Key'], 'order_123')
+  assert.equal(calls[0].options.body, '{"reference":"order_123"}')
+
+  fetch.resetFetchImplementation()
+})
+
+test('fetch normalizes non-2xx Bachs errors', async () => {
+  fetch.setFetchImplementation(async () => ({
+    ok: false,
+    status: 400,
+    statusText: 'Bad Request',
+    text: async () =>
+      JSON.stringify({
+        detail: 'Invalid request parameters',
+        error_code: 'VALIDATION_ERROR',
+        errors: [
+          {
+            field: 'customer.email',
+            message: 'Invalid email',
+            type: 'value_error'
+          }
+        ]
+      })
+  }))
+
+  await assert.rejects(
+    () =>
+      fetch('/checkout-sessions', {
+        method: 'POST',
+        apiKey: 'sk_sandbox_123',
+        body: {}
+      }),
+    (error) => {
+      assert.equal(error.bachs.statusCode, 400)
+      assert.equal(error.bachs.code, 'VALIDATION_ERROR')
+      assert.equal(error.bachs.message, 'Invalid request parameters')
+      assert.equal(error.bachs.errors[0].field, 'customer.email')
+      return true
+    }
+  )
+
+  fetch.resetFetchImplementation()
+})

package/test/payloads.test.js

@@ -0,0 +1,143 @@
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const {
+  buildCheckoutSessionPayload,
+  buildPureCheckoutPayload,
+  buildRefundPayload
+} = require('../helpers/payloads')
+
+test('buildCheckoutSessionPayload maps product checkout inputs to Bachs snake case', () => {
+  const payload = buildCheckoutSessionPayload(
+    {
+      items: [{ product: 'prod_abc123', quantity: 2, amount: '50.00' }],
+      customer: {
+        email: 'customer@example.com',
+        name: 'Jane Doe',
+        phoneNumber: '+2348012345678'
+      },
+      billingCurrency: 'NGN',
+      allowedPaymentMethodTypes: ['bank_transfer', 'card'],
+      returnUrl: 'https://example.com/return',
+      cancelUrl: 'https://example.com/cancel',
+      reference: 'order_9876',
+      metadata: {
+        orderId: '9876'
+      }
+    },
+    {}
+  )
+
+  assert.deepEqual(payload, {
+    customer: {
+      email: 'customer@example.com',
+      name: 'Jane Doe',
+      phone_number: '+2348012345678'
+    },
+    product_cart: [
+      {
+        product_id: 'prod_abc123',
+        quantity: 2,
+        amount: '50.00'
+      }
+    ],
+    billing_currency: 'NGN',
+    allowed_payment_method_types: ['bank_transfer', 'card'],
+    return_url: 'https://example.com/return',
+    cancel_url: 'https://example.com/cancel',
+    reference: 'order_9876',
+    metadata: {
+      orderId: '9876'
+    }
+  })
+})
+
+test('buildCheckoutSessionPayload maps productCollectionId and configured return URL', () => {
+  const payload = buildCheckoutSessionPayload(
+    {
+      productCollectionId: 'pgrp_123',
+      customer: {
+        customerId: 'cust_123'
+      }
+    },
+    {
+      returnUrl: 'https://example.com/after',
+      cancelUrl: 'https://example.com/cancel'
+    }
+  )
+
+  assert.deepEqual(payload, {
+    customer: {
+      customer_id: 'cust_123'
+    },
+    product_collection_id: 'pgrp_123',
+    return_url: 'https://example.com/after',
+    cancel_url: 'https://example.com/cancel'
+  })
+})
+
+test('buildPureCheckoutPayload maps amount checkout inputs to Bachs snake case', () => {
+  const payload = buildPureCheckoutPayload(
+    {
+      amount: '50.00',
+      currency: 'USD',
+      currencyOptions: {
+        NGN: '75000.00'
+      },
+      email: 'customer@example.com',
+      name: 'Jane Doe',
+      successUrl: 'https://example.com/success',
+      cancelUrl: 'https://example.com/cancel',
+      reference: 'order_9876',
+      metadata: {
+        orderId: '9876'
+      },
+      expiresInMinutes: 30,
+      simulatedOutcome: 'success'
+    },
+    {}
+  )
+
+  assert.deepEqual(payload, {
+    pricing: {
+      currency: 'USD',
+      amount: '50.00',
+      currency_options: {
+        NGN: '75000.00'
+      }
+    },
+    customer_email: 'customer@example.com',
+    customer_name: 'Jane Doe',
+    success_url: 'https://example.com/success',
+    cancel_url: 'https://example.com/cancel',
+    reference: 'order_9876',
+    metadata: {
+      orderId: '9876'
+    },
+    expires_in_minutes: 30,
+    simulated_outcome: 'success'
+  })
+})
+
+test('buildRefundPayload maps refund inputs to Bachs snake case', () => {
+  const payload = buildRefundPayload({
+    chargeId: 'chr_123',
+    reference: 'refund_123',
+    refundAddress: 'wallet-address',
+    amount: '25.00',
+    feeBearer: 'org',
+    reason: 'Customer request',
+    idempotencyKey: 'refund_123',
+    simulatedOutcome: 'success'
+  })
+
+  assert.deepEqual(payload, {
+    charge_id: 'chr_123',
+    reference: 'refund_123',
+    refund_address: 'wallet-address',
+    amount: '25.00',
+    fee_bearer: 'org',
+    reason: 'Customer request',
+    idempotency_key: 'refund_123',
+    simulated_outcome: 'success'
+  })
+})

package/test/webhooks.test.js

@@ -0,0 +1,82 @@
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const crypto = require('crypto')
+const adapter = require('../adapter')
+const verify = require('../machines/webhooks/verify')
+
+function sign({ rawBody, secret, timestamp }) {
+  return crypto
+    .createHmac('sha256', secret)
+    .update(`${timestamp}.${rawBody}`, 'utf8')
+    .digest('hex')
+}
+
+test('webhooks.verify accepts a valid Bachs webhook signature', async () => {
+  const rawBody = '{"id":"evt_123","type":"collection.succeeded"}'
+  const timestamp = Math.floor(Date.now() / 1000).toString()
+  const signature = sign({
+    rawBody,
+    secret: 'whsec_123',
+    timestamp
+  })
+
+  const valid = await verify({
+    webhookSecret: 'whsec_123',
+    rawBody,
+    timestamp,
+    signature
+  })
+
+  assert.equal(valid, true)
+})
+
+test('webhooks.verify rejects invalid signatures', async () => {
+  const rawBody = '{"id":"evt_123","type":"collection.succeeded"}'
+  const timestamp = Math.floor(Date.now() / 1000).toString()
+
+  await assert.rejects(
+    () =>
+      verify({
+        webhookSecret: 'whsec_123',
+        rawBody,
+        timestamp,
+        signature: 'bad-signature'
+      }),
+    (error) => {
+      assert.equal(error.exit, 'invalidSignature')
+      assert.equal(error.raw.message, 'Invalid Bachs webhook signature.')
+      return true
+    }
+  )
+})
+
+test('webhooks.verify rejects stale timestamps', async () => {
+  const rawBody = '{"id":"evt_123","type":"collection.succeeded"}'
+  const timestamp = '100'
+  const signature = sign({
+    rawBody,
+    secret: 'whsec_123',
+    timestamp
+  })
+
+  await assert.rejects(
+    () =>
+      verify({
+        webhookSecret: 'whsec_123',
+        rawBody,
+        timestamp,
+        signature,
+        toleranceSeconds: 300
+      }),
+    (error) => {
+      assert.equal(error.exit, 'invalidSignature')
+      assert.equal(error.raw.message, 'Stale Bachs webhook timestamp.')
+      return true
+    }
+  )
+})
+
+test('adapter exposes webhooks.verify as the uniform webhook verification API', () => {
+  assert.equal(typeof adapter.webhooks.verify, 'function')
+  assert.deepEqual(Object.keys(adapter.webhooks), ['verify'])
+})