@elqnt/admin

Admin APIs and types for the Eloquent platform. Handles onboarding flows, organization management, billing/subscriptions, user management, and team invitations.

Installation

npm install @elqnt/admin

Entry Points

React Hooks

useOrgAdmin

Hook for organization CRUD operations with loading/error states.

import { useOrgAdmin } from "@elqnt/admin/hooks";

const { loading, error, listOrgs, getOrg, getOrgInfo, createOrg, updateOrg, deleteOrg } = useOrgAdmin({
  baseUrl: apiGatewayUrl,
  orgId: selectedOrgId,
  userId: user?.id,
  userEmail: user?.email,
});

// List all organizations (admin scope required)
const orgs = await listOrgs();

// Get organization by ID
const org = await getOrg("org-uuid");

// Get lightweight org info
const orgInfo = await getOrgInfo("org-uuid");

// Create organization
const newOrg = await createOrg({ title: "Acme Corp", mainDomain: "acme.com" });

// Update organization
const updated = await updateOrg("org-uuid", { title: "Acme Inc" });

// Delete organization
const success = await deleteOrg("org-uuid");

Methods:

useUsersAdmin

Hook for user CRUD operations with loading/error states.

import { useUsersAdmin } from "@elqnt/admin/hooks";

const {
  loading,
  error,
  listUsers,
  getUser,
  getUserByEmail,
  createUser,
  updateUser,
  deleteUser,
  getUserSettings,
  updateUserSettings,
} = useUsersAdmin({
  baseUrl: apiGatewayUrl,
  orgId: selectedOrgId,
});

// List all users in organization
const users = await listUsers();

// Get user by ID
const user = await getUser("user-uuid");

// Get user by email
const user = await getUserByEmail("user@example.com");

// Create user
const newUser = await createUser({
  email: "new@example.com",
  firstName: "John",
  lastName: "Doe",
});

// Update user
const updated = await updateUser("user-uuid", { firstName: "Jane" });

// Delete user
const success = await deleteUser("user-uuid");

// Get user settings
const settings = await getUserSettings("user-uuid");

// Update user settings
const updatedSettings = await updateUserSettings("user-uuid", {
  settings: { theme: "dark", language: "en" },
  notificationPreferences: { pushEnabled: true, newMessages: true },
});

Methods:

useInvitesAdmin

Hook for invitation CRUD operations with loading/error states.

import { useInvitesAdmin } from "@elqnt/admin/hooks";

const {
  loading,
  error,
  listInvites,
  getInvite,
  sendInvite,
  sendInvites,
  resendInvite,
  revokeInvite,
  acceptInvite,
} = useInvitesAdmin({
  baseUrl: apiGatewayUrl,
  orgId: selectedOrgId,
});

// List all invites
const invites = await listInvites();

// Get invite by ID
const invite = await getInvite("invite-uuid");

// Send single invite
const newInvite = await sendInvite({ email: "user@example.com", role: "member" });

// Send bulk invites
const result = await sendInvites([
  { email: "user1@example.com", role: "member" },
  { email: "user2@example.com", role: "admin" },
]);

// Resend invite
const resent = await resendInvite("invite-uuid");

// Revoke invite
const revoked = await revokeInvite("invite-uuid");

// Accept invite (called by invited user)
const accepted = await acceptInvite("invite-uuid");

Methods:

useOrgSettings

Hook for organization settings CRUD operations with loading/error states.

import { useOrgSettings } from "@elqnt/admin/hooks";

const {
  loading,
  error,
  getSettings,
  createSettings,
  updateSettings,
} = useOrgSettings({
  baseUrl: apiGatewayUrl,
  orgId: selectedOrgId,
});

// Get organization settings
const settings = await getSettings();

// Create organization settings (first time setup)
const created = await createSettings({
  title: "My Organization",
  timezone: "America/New_York",
  defaultLang: "en",
});

// Update organization settings
const updated = await updateSettings({
  timezone: "Europe/London",
  logoUrl: "https://example.com/logo.png",
});

Methods:

Onboarding API

Functions for managing user onboarding flows. These are standalone API functions (not hooks) as onboarding is typically a one-time flow.

import {
  getOnboardingStatusApi,
  startOnboardingApi,
  createPaymentSessionApi,
  createOrganizationApi,
  sendOnboardingInvitesApi,
  createOnboardingKnowledgeApi,
  createOnboardingAgentApi,
  createAgentWithSkillsApi,
  completeOnboardingApi,
  skipOnboardingStepApi,
} from "@elqnt/admin/api";

// Get current onboarding status
const status = await getOnboardingStatusApi({
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

// Start onboarding flow
const started = await startOnboardingApi({
  baseUrl: config.apiGatewayUrl,
});

// Create payment session (Stripe checkout)
const payment = await createPaymentSessionApi(
  { plan: "pro", billingCycle: "monthly", seats: 5, successUrl: "/success", cancelUrl: "/cancel" },
  { baseUrl: config.apiGatewayUrl }
);

// Create organization during onboarding
const result = await createOrganizationApi(
  { name: "My Company", size: "small", industry: "tech", stripeSessionId: "sess_xxx" },
  { baseUrl: config.apiGatewayUrl }
);

// Send invites during onboarding
const invites = await sendOnboardingInvitesApi(
  [{ email: "team@example.com", role: "member" }],
  { baseUrl: config.apiGatewayUrl, orgId: result.data?.org?.id }
);

// Create knowledge graph during onboarding
const knowledge = await createOnboardingKnowledgeApi(
  { name: "Company Knowledge", websites: ["https://example.com"] },
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

// Create agent during onboarding
const agent = await createOnboardingAgentApi(
  { name: "Support Agent", goal: "Help customers" },
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

// Skip an onboarding step
const skipped = await skipOnboardingStepApi("knowledge", {
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

// Complete onboarding
const complete = await completeOnboardingApi({
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

Organization Settings API

Functions for managing organization-level settings.

import {
  getOrgSettingsApi,
  createOrgSettingsApi,
  updateOrgSettingsApi,
  updateOrgAgentsApi,
  updateEntityDefinitionsApi,
  updateWorkflowDefinitionsApi,
} from "@elqnt/admin/api";

// Get organization settings
const settings = await getOrgSettingsApi({
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

// Create organization settings
const created = await createOrgSettingsApi(
  { title: "My Org", timezone: "America/New_York" },
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

// Update organization settings
await updateOrgSettingsApi(
  { title: "New Title", timezone: "Europe/London" },
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

// Update enabled agents for org
await updateOrgAgentsApi(
  ["agent-id-1", "agent-id-2"],
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

// Update enabled entity definitions for org
await updateEntityDefinitionsApi(
  ["contacts", "leads"],
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

// Update enabled workflow definitions for org
await updateWorkflowDefinitionsApi(
  ["workflow-id-1", "workflow-id-2"],
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

Billing API

Functions for managing billing, subscriptions, and credits.

import {
  getBillingPlansApi,
  getSubscriptionApi,
  getCreditsApi,
  createCheckoutSessionApi,
  createPortalSessionApi,
  cancelSubscriptionApi,
  purchaseCreditsApi,
} from "@elqnt/admin/api";

// Get available plans
const plans = await getBillingPlansApi({
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

// Get current subscription
const subscription = await getSubscriptionApi({
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

// Get credit balance
const credits = await getCreditsApi({
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

// Create Stripe checkout session
const checkout = await createCheckoutSessionApi(
  { priceId: "price_xxx", seats: 5, successUrl: "/success", cancelUrl: "/cancel" },
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

// Open Stripe billing portal
const portal = await createPortalSessionApi(
  { returnUrl: "/settings/billing" },
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

// Cancel subscription
const cancelled = await cancelSubscriptionApi({
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

// Purchase additional credits
const creditsPurchase = await purchaseCreditsApi(
  { packageId: "pkg_xxx", successUrl: "/success", cancelUrl: "/cancel" },
  { baseUrl: config.apiGatewayUrl, orgId: config.orgId }
);

Models

User & Organization

import type {
  User,
  UserSettings,
  UserOrgAccess,
  NotificationPreferences,
  Org,
  OrgInfo,
  OrgRole,
  Permission,
  Address,
} from "@elqnt/admin/models";

interface User {
  id?: string;
  email: string;
  firstName: string;
  lastName: string;
  authProviderName: string;
  orgAccess?: UserOrgAccess[];
  enabled?: boolean;
  source?: UserSourceTS;
  settings?: UserSettings;
  notificationPreferences?: NotificationPreferences;
  onboarding?: UserOnboarding;
  isSysAdmin?: boolean;
  metadata?: Record<string, any>;
  createdAt?: number;
  updatedAt?: number;
}

interface UserSettings {
  theme?: string; // "system" | "light" | "dark"
  language?: string; // "auto" | "en" | "ar" | etc.
  timezone?: string; // "auto" | "America/New_York" | etc.
  occupation?: string;
  company?: string;
}

interface NotificationPreferences {
  pushEnabled: boolean;
  newChatAssignment: boolean;
  newMessages: boolean;
  escalations: boolean;
  urgentOnly: boolean;
  soundEnabled: boolean;
  doNotDisturb: boolean;
  dndStart?: string; // "22:00" format
  dndEnd?: string; // "08:00" format
}

interface Org {
  id?: string;
  title: string;
  logoUrl: string;
  mainDomain: string;
  address: Address;
  apps: SystemAppTS[];
  status: OrgStatusTS;
  enabled: boolean;
  type: OrgTypeTS;
  size?: OrgSizeTS;
  industry?: string;
  tags?: string[];
  subscription?: OrgSubscription;
  userCount: number;
  onboarding?: OrgOnboarding;
  provisioning?: OrgProvisioning;
  template?: OrgTemplate;
  roles: string[];
  metadata?: Record<string, any>;
  createdAt?: number;
  updatedAt?: number;
}

interface OrgInfo {
  id?: string;
  title: string;
  logoUrl: string;
  mainDomain?: string;
  apps: SystemAppTS[];
}

Invite Types

import type {
  Invite,
  InviteInput,
  InvitesResult,
  InviteSentStatus,
} from "@elqnt/admin/models";

interface Invite {
  id?: string;
  orgId: string;
  email: string;
  role: string;
  invitedBy: string;
  status: InviteStatusTS;
  acceptedBy?: string;
  acceptedAt?: number;
  expiresAt?: number;
  createdAt?: number;
  updatedAt?: number;
}

interface InviteInput {
  email: string;
  role: string;
}

interface InvitesResult {
  sent: InviteSentStatus[];
  failed: string[];
  nextStep: string;
  metadata: ResponseMetadata;
}

Billing Types

import type {
  Plan,
  OrganizationBilling,
  CreditBalance,
  UsageSummary,
  CreditPackage,
  UsagePeriod,
  Payment,
} from "@elqnt/admin/models";

interface Plan {
  id: string;
  stripeProductId?: string;
  stripePriceId?: string;
  name: string;
  tier: string;
  priceCents: number;
  currency: string;
  billingInterval: string;
  chatSessionsLimit: number;
  tokenAllowance: number;
  agentsLimit: number;
  usersLimit: number;
  knowledgeGraphMb: number;
  tokenOverageRateCents: number;
  sessionOverageRateCents: number;
  features: Record<string, any>;
  isActive: boolean;
}

interface OrganizationBilling {
  orgId: string;
  stripeCustomerId?: string;
  stripeSubscriptionId?: string;
  planId?: string;
  plan?: Plan;
  status: string;
  currentPeriodStart?: string;
  currentPeriodEnd?: string;
  trialStart?: string;
  trialEnd?: string;
  billingEmail?: string;
  affiliateCode?: string;
}

interface UsageSummary {
  orgId: string;
  planTier: string;
  billingPeriodStart: string;
  billingPeriodEnd: string;
  daysRemaining: number;
  tokensUsed: number;
  tokensAllowance: number;
  tokensPercentage: number;
  tokensRemaining: number;
  sessionsUsed: number;
  sessionsAllowance: number;
  sessionsPercentage: number;
  sessionsRemaining: number;
  creditsRemaining: number;
  projectedTokenOverage: number;
  projectedOverageCents: number;
}

interface CreditBalance {
  id: string;
  orgId: string;
  creditType: string;
  amount: number;
  remaining: number;
  description?: string;
  expiresAt?: string;
}

Onboarding Types

import type {
  OnboardingState,
  OnboardingStep,
  OrgInput,
  OrgOnboarding,
  OrgProvisioning,
} from "@elqnt/admin/models";

interface OnboardingState {
  status: string; // pending, in_progress, completed
  currentStep: number;
  steps: OnboardingStep[];
  user?: User;
  org?: Org;
}

interface OnboardingStep {
  step: number;
  name: string;
  status: string; // pending, in_progress, completed, skipped
  required: boolean;
}

interface OrgOnboarding {
  status: OnboardingStatus;
  currentStep: number;
  completedAt?: number;
  skippedSteps?: number[];
}

interface OrgProvisioning {
  status: ProvisioningStatus;
  defaultAgentId?: string;
  defaultKnowledgeGraphId?: string;
  completedAt?: number;
  error?: string;
}

Status Enums

import {
  OrgStatuses,
  OrgTypes,
  OrgSizes,
  OrgSubscriptionStatuses,
  InviteStatuses,
  OnboardingStatuses,
  ProvisioningStatuses,
  UserSources,
  ThemeOptions,
  SystemApps,
} from "@elqnt/admin/models";

// Organization statuses
OrgStatuses.active.label; // "Active"
OrgStatuses.suspended.label; // "Suspended"

// Organization types
OrgTypes["self-serve"].label; // "Self-Serve"
OrgTypes.enterprise.label; // "Enterprise"

// Organization sizes
OrgSizes.solo.label; // "Just me"
OrgSizes.small.label; // "2-10"
OrgSizes.medium.label; // "11-50"
OrgSizes.large.label; // "51-200"
OrgSizes.enterprise.label; // "200+"

// Subscription statuses
OrgSubscriptionStatuses.trialing.label; // "Trialing"
OrgSubscriptionStatuses.active.label; // "Active"
OrgSubscriptionStatuses.past_due.label; // "Past Due"
OrgSubscriptionStatuses.cancelled.label; // "Cancelled"

// Invite statuses
InviteStatuses.pending.label; // "Pending"
InviteStatuses.accepted.label; // "Accepted"
InviteStatuses.expired.label; // "Expired"
InviteStatuses.revoked.label; // "Revoked"

// Onboarding statuses
OnboardingStatuses.pending.label; // "Pending"
OnboardingStatuses.in_progress.label; // "In Progress"
OnboardingStatuses.completed.label; // "Completed"
OnboardingStatuses.skipped.label; // "Skipped"

// User sources
UserSources.signup.label; // "Signup"
UserSources.invite.label; // "Invite"
UserSources.sso.label; // "SSO"
UserSources.api.label; // "API"

// Theme options
ThemeOptions.system.label; // "System"
ThemeOptions.light.label; // "Light"
ThemeOptions.dark.label; // "Dark"

// System apps
SystemApps.admin.label; // "Admin"
SystemApps.helpdesk.label; // "Helpdesk"
SystemApps.workflow.label; // "Workflow"

NATS Subjects

For backend service communication:

import {
  // Admin subjects
  AdminOrgCreate,
  AdminOrgList,
  AdminOrgGet,
  AdminOrgGetInfo,
  AdminOrgUpdate,
  AdminOrgDelete,
  AdminUsersGet,
  AdminUsersGetOne,
  AdminUsersGetOneByEmail,
  AdminUsersCreate,
  AdminUsersUpdate,
  AdminUsersDelete,
  AdminUsersGetSettings,
  AdminUsersUpdateSettings,
  // Billing subjects
  SubscriptionGet,
  SubscriptionCreate,
  SubscriptionCancel,
  CreditsBalance,
  CreditsPurchase,
  PlansGetAll,
  PortalSessionCreate,
} from "@elqnt/admin/models";

API Gateway Routes

Type Generation

Admin types are generated from Go using tygo:

cd backend && tygo generate

Billing types are manually maintained in @elqnt/admin/models/billing.ts (Go source removed).

See Also

• Architecture - Platform overview
• @elqnt/agents - OrgSettings types (re-exported)
• @elqnt/api-client - HTTP client used by API functions
• API Gateway - API routing