Prerequisites

Node.js >= 18.3
An Openfuse account (sign up)

Install the SDK

npm install @openfuseio/sdk

Initialize the client

import { OpenfuseCloud } from '@openfuseio/sdk'

const openfuse = new OpenfuseCloud({
  system: 'payments',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
})

openfuse.init()

init() authenticates with the Openfuse API and pre-caches breaker states. It never throws. If the API is unreachable, the SDK retries in the background.

Protect a call

const customer = await openfuse.breaker('stripe-get-customer').protect(
  () => stripe.customers.retrieve(customerId),
)

If the breaker is open, the call fails fast. Otherwise it executes normally and metrics are recorded.

Add a fallback

const customer = await openfuse.breaker('stripe-get-customer').protect(
  () => stripe.customers.retrieve(customerId),
  { fallback: () => cachedCustomer },
)

When the breaker is open, the fallback runs instead of your function.

Add a timeout

const customer = await openfuse.breaker('stripe-get-customer').protect(
  (signal) => stripe.customers.retrieve(customerId, { signal }),
  { timeout: 3000, fallback: () => cachedCustomer },
)

If stripe.customers.retrieve doesn't resolve within 3 seconds, the SDK throws a TimeoutError. Pass the signal parameter to downstream libraries for cooperative cancellation.

Shut down gracefully

process.on('SIGTERM', async () => {
  await openfuse.close()
  process.exit(0)
})

close() flushes pending metrics and stops background timers.

Full example

Create a shared client module:

lib/openfuse.ts

import { OpenfuseCloud } from '@openfuseio/sdk'

export const openfuse = new OpenfuseCloud({
  system: 'payments',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
})

Protect your calls:

app.ts

import express from 'express'
import Stripe from 'stripe'
import { openfuse } from './lib/openfuse.js'

const stripe = new Stripe('YOUR_STRIPE_KEY')
export const app = express()

app.use(express.json())

app.get('/customers/:id', async (req, res) => {
  const customer = await openfuse.breaker('stripe-get-customer').protect(
    (signal) => stripe.customers.retrieve(req.params.id, { signal }),
    { timeout: 3000, fallback: () => cachedCustomer },
  )
  res.json(customer)
})

Initialize and shut down gracefully:

server.ts

import { openfuse } from './lib/openfuse.js'
import { app } from './app.js'

openfuse.init()

app.listen(3000)

process.on('SIGTERM', async () => {
  await openfuse.close()
  process.exit(0)
})

For frequently used breakers, save the handle for reuse:

const stripeBreaker = openfuse.breaker('stripe-get-customer')

const customer = await stripeBreaker.protect(
  () => stripe.customers.retrieve(customerId),
  { fallback: () => cachedCustomer },
)