@elqnt/sdk — the Eloquent SDK

Typed, gateway-mediated building blocks for building apps, agents, and interfaces on the Eloquent platform. Installing this meta-package pulls in every @elqnt/* package and ships the SDK's root docs (this file, SDK-REFERENCE.md, and AGENTS.md) right into your node_modules — so you and your AI coding agent have the full contract offline.

npm install @elqnt/sdk
# or add only what you need:
npm install @elqnt/api-client @elqnt/entity @elqnt/agents @elqnt/chat

You don't import from @elqnt/sdk directly — it's a docs + one-install convenience. Import from the individual packages (@elqnt/entity/hooks, …).

How it works

your app → @elqnt/<pkg>/hooks → @elqnt/api-client → API Gateway → Go service
                 │                       │
            your domain types     (one auth/transport seam)

Every package wraps part of the backend behind the same shape — universal types (/models) → browser/server API (/api) → React hooks (/hooks) — all flowing through one API Gateway with orgId + product + a gateway JWT.

Quick start

import { ElqntConfigProvider } from "@elqnt/api-client/react";
import { useEntityRecords } from "@elqnt/entity/hooks";
import type { EntityRecord } from "@elqnt/entity/models";

// Inject baseUrl/orgId/product ONCE (baseUrl from your gateway URL, server-side):
<ElqntConfigProvider config={{ baseUrl, orgId, product: "my-product" }}>…</ElqntConfigProvider>

// Then anywhere in the tree — methods never throw; they set `error`:
const { queryRecords, createRecord, loading, error } = useEntityRecords({ entityName: "ticket" });
const { records } = await queryRecords({ filters: { status: "open" } });

You also expose a /api/gateway-token route in your app that mints the short-lived gateway JWT (the browser fetches it automatically). See any package's SKILL.md for the exact token flow.

The packages

| Package | What it does | |---|---| | @elqnt/api-client | The transport core: gateway auth + ElqntConfigProvider + the useResource hook factory. | | @elqnt/entity | Dynamic, schema-driven records — CRUD, query, aggregation, relationships. | | @elqnt/docs | Document libraries — upload + embeddings, semantic search. | | @elqnt/agents | AI agents — design/save agents, skills, tools, jobs, schedules. | | @elqnt/chat | Chat — history + realtime SSE, monitoring, human-agent sessions. | | @elqnt/kg | Knowledge graph — nodes/edges, semantic query, ingest. | | @elqnt/admin | Org / users / invites / settings administration. | | @elqnt/analytics | Product analytics — events + usage. | | @elqnt/notifications | Transactional email. | | @elqnt/workflow | Workflows — definitions, templates, instances. | | @elqnt/types | Shared TypeScript types. |

Full hook + function reference: SDK-REFERENCE.md (ships in this package). Per-package guide: each package ships its own SKILL.md — read node_modules/@elqnt/<pkg>/SKILL.md.

Using it with an AI coding agent

Point your agent (Cursor, Claude Code, Copilot, …) at AGENTS.md (ships in this package). The short version:

• Read node_modules/@elqnt/<pkg>/SKILL.md for the package you're using, and node_modules/@elqnt/sdk/SDK-REFERENCE.md for the full hook list.
• Import hooks from @elqnt/<pkg>/hooks, types from @elqnt/<pkg>/models.
• Type-check against the published .d.ts — it is the contract.
• Never call the backend directly or bypass the gateway.

The contract & conventions

• Hooks are imperative — async (...args) => Promise<Result> — and never throw (they resolve to a default and set error); they don't auto-fetch on mount.
• Components never import @elqnt/* directly — wrap the hook in one app file and expose your own domain type (see the "domain layer" pattern in any package's SKILL.md).
• The published .d.ts of each package is the source of truth your code type-checks against.