React SDK

Copy

$ npm install @rootcx/sdk

$ pnpm add @rootcx/sdk

$ yarn add @rootcx/sdk

Copy

// src/main.tsx
import { RuntimeProvider } from "@rootcx/sdk";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <RuntimeProvider baseUrl="https://<your-ref>.rootcx.com">
    <App />
  </RuntimeProvider>
);

Copy

import { useAuth } from "@rootcx/sdk";

const {
  user,            // AuthUser | null -- current user, null if not authenticated
  isAuthenticated, // boolean
  loading,         // boolean -- true while checking session or performing auth
  login,           // (username: string, password: string) => Promise<void>
  register,        // (data: RegisterInput) => Promise<void>
  logout,          // () => Promise<void>
} = useAuth();

Copy

// src/LoginPage.tsx
import { useAuth } from "@rootcx/sdk";
import { useState } from "react";

export function LoginPage() {
  const { login, loading } = useAuth();
  const [username, setUsername] = useState("");
  const [password, setPassword] = useState("");

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    await login(username, password);
    // On success, user state updates and isAuthenticated becomes true
  };

  return (
    <form onSubmit={handleSubmit}>
      <input value={username} onChange={e => setUsername(e.target.value)} />
      <input type="password" value={password} onChange={e => setPassword(e.target.value)} />
      <button type="submit" disabled={loading}>
        {loading ? "Signing in..." : "Sign in"}
      </button>
    </form>
  );
}

Copy

import { useAppCollection } from "@rootcx/sdk";

const {
  data,       // T[] -- array of records
  total,      // number -- total record count
  loading,    // boolean
  error,      // string | null
  create,     // (data: Record<string, unknown>) => Promise<T>
  bulkCreate, // (data: Record<string, unknown>[]) => Promise<T[]>
  update,     // (id: string, data: Record<string, unknown>) => Promise<T>
  remove,     // (id: string) => Promise<void>
  refetch,    // () => void -- manually re-fetch
} = useAppCollection<T>("appId", "entityName", query?);

Copy

useAppCollection<Contact>("crm", "contacts", {
  where: { stage: "lead" },
  orderBy: "created_at",
  order: "desc",
  limit: 50,
  offset: 0,
});

Copy

// src/ContactsList.tsx
import { useAppCollection } from "@rootcx/sdk";

type Contact = {
  id: string;
  first_name: string;
  last_name: string;
  email: string;
  created_at: string;
};

export function ContactsList() {
  const { data, loading, error, create, remove } = useAppCollection<Contact>(
    "crm",
    "contacts"
  );

  const addContact = async () => {
    await create({
      first_name: "Bob",
      last_name: "Smith",
      email: "bob@example.com",
    });
    // data array updates automatically
  };

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div>
      <button onClick={addContact}>Add Contact</button>
      <ul>
        {data.map(c => (
          <li key={c.id}>
            {c.first_name} {c.last_name} -- {c.email}
            <button onClick={() => remove(c.id)}>Delete</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

Copy

import { useAppRecord } from "@rootcx/sdk";

const {
  data,      // T | null
  loading,   // boolean
  error,     // string | null
  refetch,   // () => void -- manually re-fetch
  update,    // (data: Record<string, unknown>) => Promise<T>
  remove,    // () => Promise<void>
} = useAppRecord<T>("appId", "entityName", recordId); // recordId: string | null

Copy

// src/ContactDetail.tsx
import { useAppRecord } from "@rootcx/sdk";

export function ContactDetail({ id }: { id: string }) {
  const { data, loading, update } = useAppRecord<Contact>(
    "crm", "contacts", id
  );

  if (loading) return <Spinner />;
  if (!data) return <div>Not found</div>;

  return (
    <div>
      <h1>{data.first_name} {data.last_name}</h1>
      <button onClick={() => update({ email: "new@email.com" })}>
        Update email
      </button>
    </div>
  );
}

Copy

import { usePermissions } from "@rootcx/sdk";

const {
  roles,       // string[] -- resolved roles for the current user
  permissions, // string[] -- flat list of permission strings
  can,         // (permission: string) => boolean
  loading,     // boolean
  error,       // string | null
  refetch,     // () => void
} = usePermissions("appId");

Copy

import { usePermissions } from "@rootcx/sdk";

export function ContactActions({ contactId }: { contactId: string }) {
  const { can } = usePermissions("crm");

  return (
    <div>
      {can("contacts.update") && (
        <button>Edit</button>
      )}
      {can("contacts.delete") && (
        <button className="text-red-500">Delete</button>
      )}
    </div>
  );
}

Copy

import { AuthGate } from "@rootcx/sdk";

function App() {
  return (
    <AuthGate>
      <MyProtectedApp />
    </AuthGate>
  );
}

Copy

import { Authorized } from "@rootcx/sdk";

<Authorized appId="crm" permission="contacts.delete">
  <button>Delete Contact</button>
</Authorized>

Copy

import { useIntegration } from "@rootcx/sdk";

const {
  connected,         // boolean -- whether the integration is authenticated
  loading,           // boolean
  connect,           // () => Promise<{ type: string; schema?: Record<string, unknown> } | void>
  submitCredentials, // (credentials: Record<string, string>) => Promise<void>
  disconnect,        // () => Promise<void>
  call,              // (action: string, input?: Record<string, unknown>) => Promise<unknown>
} = useIntegration("myApp", "slack");

// Call an action once connected
await call("send_message", { channel: "#general", text: "Hello!" });

Copy

import { RuntimeClient } from "@rootcx/sdk";

const client = new RuntimeClient({ baseUrl: "https://<your-ref>.rootcx.com" });

// Authenticate
await client.login("alice", "password");

// CRUD
const contacts = await client.listRecords("crm", "contacts");
const created = await client.createRecord("crm", "contacts", {
  first_name: "Alice",
  email: "alice@example.com",
});

// RPC
const result = await client.rpc("crm", "sendWelcomeEmail", {
  contactId: created.id,
});

Copy

// Authenticated user
export interface AuthUser {
  id: string;
  username: string;
  email: string | null;
  displayName: string | null;
  createdAt: string;
}

// Login response
export interface LoginResponse {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
  user: AuthUser;
}

// Registration input
export interface RegisterInput {
  username: string;
  password: string;
  email?: string;
  displayName?: string;
}

// Effective permissions for a user in an app
export interface EffectivePermissions {
  roles: string[];
  permissions: string[];
}