HETIBANK SDK

Open-source UI kits, clients and plugin tooling for the HETIBANK real-estate API.

One typed contract, four surfaces: build a brokerage website, an agent app (MCP Apps / ChatGPT), a chat surface, or a published plugin — with the same figures, the same evidence, and the same honesty about what is known, estimated, unverified or missing.

@hetibank/contracts ── @hetibank/client
        │                    │
        ├── @hetibank/theme ─┴── @hetibank/ui
        │                          │
        │        ┌─────────────────┼─────────────────┐
        │   @hetibank/websites  @hetibank/chat  @hetibank/apps
        │                          │
        └────────────────── @hetibank/plugins (manifest SDK, CLI, MCP server)

Why this exists

Real-estate data platforms usually ship an OpenAPI file and leave the hard parts to the customer: which figure is sourced, what a payment assumes, how a result is presented in an agent, and how a brand theme stops being accessible. This SDK packages the answers:

• Payment-first property cards. Estimated monthly payment and cash needed lead; list price is a

secondary detail. Every figure is labelled with its certainty and as-of date.

• One presentation registry. Text, Markdown, a component, or a full-page handoff — REST, MCP and

the UI kits read the same descriptor instead of each surface inventing its own.

• A real brand gate. Brokerage themes change color, type and logo; createBrandTheme rejects an

accent that fails WCAG contrast.

• No client math. The API computes; the SDK formats. No duplicated amortization in the browser.
• Plugins that validate. Manifest schema, review-case checks, secret rejection, deterministic

bundling and an MCP server with scoped, read-only tools.

Packages

Quickstart

pnpm add @hetibank/websites @hetibank/ui @hetibank/theme @hetibank/contracts react react-dom

import { ThemeProvider, AppShell, ShellHeader, ShellFooter, BrandMark } from "@hetibank/ui";
import { PropertyCard, BuyerUiComponentView } from "@hetibank/websites";
import { createBrandTheme } from "@hetibank/theme";
import "@hetibank/theme/styles.css";
import "@hetibank/ui/styles.css";
import "@hetibank/websites/styles.css";

const theme = createBrandTheme({
  brand: { name: "Desert Bloom Realty", primary: "#5b3a29", accent: "#c2703d" },
});

export function SearchPage({ card }) {
  return (
    <ThemeProvider theme={theme} as="section">
      <AppShell header={<ShellHeader brand={<BrandMark name={theme.brand.name} />} />}
                footer={<ShellFooter attribution="Listing data © Las Vegas REALTORS®" />}>
        <PropertyCard component={card} onAction={(key) => console.log(key)} />
        <BuyerUiComponentView component={card} />
      </AppShell>
    </ThemeProvider>
  );
}

The card is a canonical property_card envelope from the API — not hand-built props:

{
  "contract": "hetibank.buyer-ui.v1",
  "component": "property_card",
  "summary": "Estimated $2,940/mo with $47,500 cash needed",
  "asOf": "2026-11-01",
  "nextAction": { "key": "view_home", "label": "View home", "path": "/property/ABC123" },
  "data": {
    "listingKey": "ABC123",
    "address": "123 Desert Bloom Ave, Henderson, NV",
    "estimatedMonthlyPayment": { "value": 2940, "unit": "usd_per_month", "certainty": "estimated", "asOf": "2026-11-01" },
    "cashNeeded": { "value": 47500, "unit": "usd", "certainty": "estimated" },
    "confidence": "estimated",
    "loan": { "program": "FHA", "balance": { "value": 312000, "unit": "usd", "certainty": "unverified" } },
    "price": { "value": 389000, "unit": "usd", "certainty": "known" },
    "path": "/property/ABC123"
  }
}

Each surface has a guide and a runnable example:

• Websites guide · example
• Chat guide · example
• Apps guide · example
• Plugins guide · example
• API + OpenAPI guide · Theming guide

Design rules the code enforces

1. No client-side financial math. Figures are API facts; the SDK formats them.
2. Certainty is never hidden. missing renders as “Unavailable”, never 0.
3. Errors keep { code, message, request_id } and the UI shows the request id.
4. Contrast is a gate, not a suggestion: createBrandTheme throws on an inaccessible accent.
5. No raw HTML. Agent output renders through SafeMarkdown.
6. No secrets. Browser bundles get a browser key and a token getter — never a server secret.

pnpm verify fails the build on violations of 4–6.

Compatibility

• Node >= 20.11, ESM only, React 18.2+ / 19 peer.
• API contract: HETIBANK OpenAPI 3.1 (spec/hetibank.openapi.yaml, 301 operations).
• Contract version: hetibank.buyer-ui.v1; SDK version 0.1.x is the MVP line.
• Provenance: see docs/PROVENANCE.md.

Development

pnpm install --ignore-scripts
pnpm build
pnpm test
pnpm verify                     # build + typecheck + tests + contrast + safety scans
node tools/pm/pm.mjs check --all # record the launch board
node tools/pm/pm.mjs board       # regenerate pm/board.md

Hosting the demos

sdk.hetibank.com is currently a ChatGPT Site mock. Recommended layout:

• Cloudflare Pages for this static site (zero ops, free TLS/CDN, one-click rollback).
• Hostinger VPS later for the application/API and the plugin MCP server (stateful Node workloads).

pnpm -r --filter "./examples/*" build   # three demo bundles
pnpm site                               # assemble dist/site/ (landing + demos + docs)
pnpm site:serve                         # preview at http://127.0.0.1:4321/

Deploy to Pages:

npx wrangler pages project create hetibank-sdk --production-branch main   # once
npx wrangler pages deploy dist/site --project-name hetibank-sdk --branch main

dist/site/ is a plain static directory with a CSP _headers file, _redirects and an nginx server block for the VPS alternative. The full comparison, both deploy paths, Cloudflare settings and rollback: deploy/cloudflare.md.

• docs/AGENT-CONTRACT.md — interfaces and rules for contributors/agents
• pm/board.md — the verifiable launch board
• tools/shadcn-catalog — shadcn.io catalog MCP for component discovery

Status

MVP 0.1.0. Stability: contracts, theme, UI, websites and chat are the stable surface; the Apps bridge and plugin publishing tooling follow the MCP Apps and agent-plugins specifications, which are still moving. Nothing in this repo is loan approval, a rate quote, or a guarantee of savings.

License

Apache-2.0. See LICENSE and NOTICE.