@unisim/sdk

Shared React SDK for the Universal Suite — Ergo Assess UK, Cyber Assess UK, Workplace Assess, plus the central hub at app.unisim.co.uk. One package for auth, multi-tenant org data, branding, entitlements, changelog, and trial gating, so every product reads the same source of truth.

No product should import @supabase/supabase-js directly — go through the SDK so the underlying backend stays swappable.

Install

npm install @unisim/sdk @supabase/supabase-js react

React 18+ is a peer dependency.

Quick start

Wrap your app in <UniversalProvider> once, then call hooks anywhere.

import { UniversalProvider, useUser, useOrgBranding } from '@unisim/sdk'

const config = {
  supabaseUrl:     process.env.NEXT_PUBLIC_PLATFORM_SUPABASE_URL!,
  supabaseAnonKey: process.env.NEXT_PUBLIC_PLATFORM_SUPABASE_ANON_KEY!,
  product:         'ergo_assess',
  cookieDomain:    process.env.NODE_ENV === 'production' ? '.unisim.co.uk' : undefined,
}

function App() {
  return (
    <UniversalProvider config={config}>
      <Header />
      {/* … */}
    </UniversalProvider>
  )
}

function Header() {
  const { user } = useUser()
  const branding = useOrgBranding()
  return (
    <header>
      {branding.logo_url && <img src={branding.logo_url} alt="" />}
      <span>{user?.email ?? 'Guest'}</span>
    </header>
  )
}

What you get

Auth + session

• useUniversal() — raw { supabase, session, activeOrgId, … }
• useUser() — { user, loading }
• useOrg() — active org + list of orgs the user belongs to
• signInWithPassword(supabase, email, password)
• signOut(supabase)

Trial mode (anonymous-auth users)

• useTrialMode() — { isTrial, hasSession, email } for gating exports / multi-user
• <TrialBadge /> — small "PRO" chip you append to gated buttons
• <UpgradeWall feature="export PDFs" /> — full feature-replacement card

Suite-wide entities (all org-scoped, RLS-gated)

• usePeople() + createPerson / deletePerson
• useTeams() + useTeamMemberships() + createTeam / assignPersonToTeam / …
• usePlaces() + createPlace / deletePlace
• useProjects() + createProject / updateProjectStatus / deleteProject
• useOrgBranding() — logo URL + brand colour
• useOrgMembers() — org membership list with profile data

Subscriptions + entitlements

• useSubscription() — { tier, status, seat_count, current_period_end, credits }
• useCredits() — convenience wrapper for the metered balance
• useHasAccess(productCode) — feature/product entitlement check
• useHasFeature(productCode, feature)
• useSeat(productCode)

Org admin

• useOrgMembers() / useOrgSeats() / useAuditLog()
• assignSeat / revokeSeat / reassignSeat

Suite navigation

• <SuiteSwitcher current="ergo_assess" /> — top-right product switcher with the canonical product list
• <CompanyMenu /> — "My Company" dropdown linking to the central hub
• <UniversalBar /> — the 4 px gradient brand strip across every product header
• <UKFlag /> — region indicator for UK products

Changelog

• useChangelog() — fetches the suite-wide changelog feed (defaults to https://changelog.unisim.co.uk/changelog.json)

Multi-tenant model

This SDK is the client side of a Supabase-backed multi-tenant schema (see universal-platform/supabase/migrations). Every read/write is scoped to the user's active org via the is_org_member() helper in RLS policies. Anonymous-auth users get the same hooks; trial caps (3 people / 1 team / 2 places / 1 project) are enforced server-side by the enforce_anonymous_trial_caps() trigger.

Publishing

cd packages/sdk
./publish.sh patch       # or minor / major

This runs npm version, builds, publishes, commits the version bump, and pushes — see publish.sh for the exact sequence. prepublishOnly runs typecheck && build as a safety net, and the dist/ folder is the only thing shipped (per files).

License

MIT © Universal Simulation Ltd