TradeOS / SDK
SDK

Build at every layer

From a one-line script tag to raw Effect Schemas. Four tiers of integration depth -- pick the layer that matches your team's control appetite.

01
Hosted flow
Drop-in <script>
02
React components
<QuoteFlow tenant=... />
03
Headless hooks
useQuote(...)
04
Schema
Effect Schema · raw
$ npm install @tradeos/react
v2.14.0MIT LicenseTypeScript 5.7+React 19+Effect 3.x
01

Hosted flow

Drop-in <script>
When to reach for this

Marketing site that needs a quote widget without touching your build pipeline. Paste the snippet, configure via data-attributes, done.

install: Paste before </body>
  • Zero build step -- works with any CMS or static site
  • Auto-detects vertical from tenant config
  • Responsive overlay or inline mount via data-mount
  • Event hooks: onQuoteComplete, onStepChange, onError
  • CDN-delivered, < 42 kB gzipped
1<!-- TradeOS hosted flow -->
2<script
3  src="https://cdn.tradeos.app/v1/flow.js"
4  data-tenant="mph-heating"
5  data-vertical="boilers"
6  data-theme="auto"
7  data-position="bottom-right"
8  defer
9></script>
10
11<!-- optional: mount target -->
12<div id="tradeos-root"></div>
02

React components

<QuoteFlow tenant=... />
When to reach for this

React or Next.js app where you want the full quote experience as a first-class component. Bring your own layout, TradeOS handles state, validation, and submission.

install: npm install @tradeos/react
  • Full form engine with multi-step wizard UX
  • Built-in AI chat assistant per step
  • Server-validated via tRPC -- zero client trust
  • Theming via CSS vars or Tailwind config
  • Tree-shakeable: only import the vertical you need
  • SSR-safe with streaming hydration support
1import { QuoteFlow, QuoteProvider } from "@tradeos/react"
2import { BoilerSchema } from "@tradeos/verticals/boilers"
3
4export default function QuotePage() {
5  return (
6    <QuoteProvider
7      tenant="mph-heating"
8      vertical={BoilerSchema}
9      onComplete={(quote) => router.push(`/confirm/${quote.id}`)}
10    >
11      <QuoteFlow
12        showProgress
13        theme="dark"
14        className="my-flow"
15      />
16    </QuoteProvider>
17  )
18}
03

Headless hooks

useQuote(...)
When to reach for this

You want total control over the UI but still want TradeOS to handle validation, pricing, AI, and submission. Build your own form, wire our hooks.

install: npm install @tradeos/react
  • useQuote -- session lifecycle, submission, pricing
  • useField -- per-field state, validation, error messages
  • useAI -- streaming chat, extraction, suggestions
  • useFinance -- Stax finance quotes, affordability checks
  • useInspection -- booking flow, slot picker, confirmation
  • All hooks are SSR-safe and suspense-compatible
1import { useQuote, useField, useAI } from "@tradeos/react"
2
3function CustomForm() {
4  const quote = useQuote({
5    tenant: "mph-heating",
6    vertical: "boilers",
7  })
8
9  const postcode = useField(quote, "postcode")
10  const fuelType = useField(quote, "fuelType")
11  const ai = useAI(quote)
12
13  return (
14    <form onSubmit={quote.submit}>
15      <input {...postcode.inputProps} />
16      {postcode.error && <span>{postcode.error}</span>}
17      <select {...fuelType.inputProps}>
18        {fuelType.options.map(o => <option key={o.value}>{o.label}</option>)
19      </select>
20      <button type="submit" disabled={!quote.isValid}>Get quote</button>
21    </form>
22  )
23}
04

Schema

Effect Schema · raw
When to reach for this

You are building a backend integration, a custom pricing engine, or a non-JS client. Import the raw Effect Schemas and branded types directly.

install: npm install @tradeos/schema
  • Effect Schema types with full encode/decode round-trip
  • Branded newtypes: Pence, UKMobile, UKPostcode, QuoteId
  • Vertical-specific form schemas with discriminated unions
  • Zero runtime overhead -- schemas are trees of descriptions
  • Works with any language via JSON Schema export
  • Versioned and semver-stable public API
1import { Schema } from "effect"
2import { BoilerQuoteForm, UKPostcode, Pence } from "@tradeos/schema/boilers"
3
4// Decode and validate raw input
5const decode = Schema.decodeSync(BoilerQuoteForm)
6
7const form = decode({
8  postcode: "AB10 1XG",
9  fuelType: "gas",
10  bedrooms: 3,
11  currentBoiler: "combi",
12  desiredBoiler: "combi",
13  urgency: "within-month",
14})
15
16// Use branded types for type safety
17const price: Pence = Pence(349900) // £3,499.00
18const postcode: UKPostcode = UKPostcode("AB10 1XG")
Primitives

Everything you can import

QuoteFlow
@tradeos/react
Full multi-step quote wizard component
useQuote
@tradeos/react
Headless session, validation, and pricing
Schema.Struct
effect
Declarative form shape definitions
UKPostcode
@tradeos/schema
Branded postcode type with validation
FuelType
@tradeos/schema
Gas / Oil / Electric / LPG enum
PricingTier
@tradeos/schema
Tier definitions for quote pricing
useFinance
@tradeos/react
Stax finance integration hook
InspectionPolicy
@tradeos/schema
Inspection scheduling rules
CRMSync
@tradeos/react
CRM push/pull sync adapter