Eloquent Packages

The @elqnt/* npm packages provide shared code, types, APIs, and React hooks for building applications on the Eloquent platform.

Package Overview

Core Infrastructure

Domain Packages

Installation

npm install @elqnt/api-client @elqnt/types @elqnt/agents

Package Structure

Each package follows a consistent structure:

@elqnt/{name}/
├── models/     # TypeScript types (tygo-generated)
├── api/        # Browser API functions
├── api/server  # Server-side API (SSR)
├── hooks/      # React hooks
└── utils/      # Utility functions

Import Patterns

// Types
import type { Agent } from "@elqnt/agents/models";

// Browser API
import { getAgentsApi } from "@elqnt/agents/api";

// Server API (SSR)
import { getAgentsServer } from "@elqnt/agents/api/server";

// React Hooks
import { useAgents } from "@elqnt/agents/hooks";

Quick Start

1. Configure API Client

// Browser
import { browserApiRequest } from "@elqnt/api-client/browser";

const agents = await browserApiRequest("/api/v1/agents", {
  baseUrl: config.apiGatewayUrl,
  orgId: config.orgId,
});

// Server (SSR)
import { createServerClient } from "@elqnt/api-client/server";

const client = createServerClient({
  gatewayUrl: process.env.API_GATEWAY_URL!,
  jwtSecret: process.env.JWT_SECRET!,
});

2. Use React Hooks

import { useAgents } from "@elqnt/agents/hooks";

function AgentList() {
  const { agents, loading, createAgent } = useAgents({
    baseUrl: config.apiGatewayUrl,
    orgId: config.orgId,
  });

  return (
    <ul>
      {agents.map((agent) => (
        <li key={agent.id}>{agent.name}</li>
      ))}
    </ul>
  );
}

Publishing

Version Bump

cd packages/@elqnt/{name}
npm version patch  # or minor, major

Publish to npm

npm publish --access public

GitHub Release

gh release create @elqnt/{name}@1.2.3 \
  --title "@elqnt/{name} v1.2.3" \
  --notes "- Added feature\n- Fixed bug"

Type Generation

Types are generated from Go using tygo:

cd backend && tygo generate

See Type System for details.

Best Practices

1. Use type imports - import type { ... } for types-only
2. Don't duplicate types - Use generated types from packages
3. Version carefully - Breaking changes require major bump
4. Document changes - Update CHANGELOG.md with each release
5. Test before publish - Run npm run typecheck first

Full Reference

See the Package Reference for detailed API documentation for each package.