SDK Coming soon

The betterfound SDK provides type-safe wrappers around the REST API and the widget JavaScript API, making it easy to build custom integrations in TypeScript, Node.js, Python, and PHP.

JavaScript / TypeScript SDK

Install

npm install @betterfound/sdk

Initialise

import { Betterfound } from '@betterfound/sdk'

const client = new Betterfound({
  apiKey:   process.env.BETTERFOUND_API_KEY,
  tenantId: process.env.BETTERFOUND_TENANT_ID,
})

Search products

const results = await client.products.search({
  query:   'waterproof hiking boots under £100',
  filters: { in_stock: true },
  limit:   8,
})

for (const product of results.products) {
  console.log(product.name, product.price)
}

Trigger enrichment

const job = await client.enrichment.trigger('ds_abc123')
console.log('Enrichment job:', job.id)

// Poll until done
const result = await client.enrichment.waitForCompletion(job.id)
console.log('Tags generated:', result.vocab.length)

Widget control API

// Control the widget from your own UI
import { BetterfoundWidget } from '@betterfound/sdk/widget'

const widget = BetterfoundWidget.getInstance()

widget.open()                          // Open the widget
widget.close()                         // Close the widget
widget.send('show me running shoes')   // Pre-fill a message
widget.on('product_click', (e) => {    // Listen to events
  analytics.track('product_viewed', e.product)
})

Python SDK (planned)

pip install betterfound

from betterfound import Betterfound

client = Betterfound(api_key="sk-sm-xxxx", tenant_id="your-tenant")

results = client.products.search(
    query="waterproof jacket",
    filters={"max_price": 200},
    limit=5,
)

for product in results.products:
    print(product.name, product.price)

Node.js server-side rendering

Use the SDK in Next.js Server Components to pre-fetch products and hydrate the widget with an initial result set — eliminating the first-query round-trip for landing pages:

// app/products/page.tsx (Server Component)
import { Betterfound } from '@betterfound/sdk'

const client = new Betterfound({ apiKey: process.env.BETTERFOUND_API_KEY })

export default async function ProductsPage() {
  const initial = await client.products.search({
    query: 'featured products',
    limit: 8,
  })

  return (
    <>
      <BetterfoundWidget initialProducts={initial.products} />
    </>
  )
}