@lovelace-ai/elemental-api

Elemental API OpenAPI specifications and TypeScript client for the Lovelace project.

Installation

npm install @lovelace-ai/elemental-api
# or
pnpm add @lovelace-ai/elemental-api

Package exports

| Export | Use for | |------------|---------| | @lovelace-ai/elemental-api | Spec only: elementalSpec, elementalSpecPath, version | | @lovelace-ai/elemental-api/client | Wrapped client, raw client functions, and types | | @lovelace-ai/elemental-api/config | configureElementalClient() and ElementalFetchConfig |

Usage

The Orval-generated client uses global config: you set base URL and optional fetch once, and every call (wrapped, raw, or a mix of both) uses that config. Do this once at app init regardless of how you intend to use the API.

1. Configure once (required)

Set your base URL and optional custom fetch. All client calls—whether you use the wrapped API, the raw functions, or both—use this same global config.

import { configureElementalClient } from "@lovelace-ai/elemental-api/config";

configureElementalClient({
  baseUrl: "https://stable-query.lovelace.ai",
  fetch: async (url, options) => {
    const res = await fetch(url, {
      ...options,
      headers: {
        ...options?.headers,
        Authorization: `Bearer ${yourToken}`,
      },
    });
    const data = await res.json().catch(() => ({}));
    return { data, status: res.status, headers: res.headers };
  },
});

Your fetch must return { data, status, headers } (not a raw Response).

2. Call the API

Wrapped — Use useElementalClient() when you want methods to return response data on success and throw on non-2xx. Best for most call sites.

import { useElementalClient } from "@lovelace-ai/elemental-api/client";

const client = useElementalClient();
const article = await client.getArticle(artid);        // data only
const report = await client.getNamedEntityReport(neid);

Raw — Use the exported functions (getArticle, findEntities, etc.) when you need status codes or headers (e.g. custom error handling). They return { data, status, headers }.

import { getArticle, findEntities } from "@lovelace-ai/elemental-api/client";

const response = await getArticle(artid);
if (response.status === 200) {
  console.log(response.data);
} else if (response.status === 404) {
  // handle not found
}

3. Types

Import API types from the client entrypoint; import ElementalFetchConfig from the config entrypoint when typing options for configureElementalClient:

import type { MentionDetail, NamedEntityReport, ArticleDetail } from "@lovelace-ai/elemental-api/client";
import type { ElementalFetchConfig } from "@lovelace-ai/elemental-api/config";

4. Spec only (no client)

If you only need the OpenAPI spec:

const { elementalSpec, elementalSpecPath, version } = require("@lovelace-ai/elemental-api");
// or
import { elementalSpec, elementalSpecPath } from "@lovelace-ai/elemental-api";

Development

The OpenAPI spec is built from the query project’s specs (see scripts/merge-elemental-specs.mjs): we currently merge the legacy and new Elemental specs into one, then generate the client from that (see orval.config.mjs). Long-term, the legacy spec will be dropped and this package will consume a single spec from the query project. The spec and generated code live under generated/ and are not checked in. Run npm run build (or npm run generate:client then npm run validate) before npm run validate.

Important: Use the Cursor command instead of running these commands manually.

In Cursor, run the command defined in .cursor/commands/elemental_api_update.md which handles the full workflow: regenerating specs from Go annotations, updating skill docs, running tests, and optionally publishing packages.

# Build spec from query project + generate client + emit types
npm run build

# Or step by step:
npm run generate:client   # merge specs from query dir → generated/elemental-api-spec.json, then orval
npm run build:types        # emit .d.ts for /client and /config

# Publish (build runs automatically via prepublishOnly)
npm publish