@fluree/client

Typed browser/Node client for a Fluree Solo stack. Query, transact, and mint Space app tokens — with policy enforced at the ledger, below the API. The client carries no policy logic and no privileged credential.

The model in 20 seconds

• A Space is the sandbox: its datasets, agents, grants, and policy classes define everything an app can ever touch.
• A Space app token is a scoped, non-privileged, short-lived credential into that Space. It identifies as the end user, is narrowed to (user ∩ Space), and only carries datasets with explicit policy classes — a dataset without them is excluded at mint and denied at enforcement (fail closed). Even an admin using your app is narrowed.
• API keys are intentionally unsupported. On a Fluree stack an API key is the privileged path that bypasses ledger policy; it must never ship in an app.

Usage

import { createSpaceAppClient } from "@fluree/client";

const app = createSpaceAppClient({
  endpoint: "https://your-stack.example.com",
  spaceId: "space-abc",
  // The user's own credential — used ONLY to mint/refresh the app token.
  userAuth: { tokenProvider: () => session.getToken() },
});

// Data calls ride the scoped app token, auto-refreshed before expiry.
const leads = await app.query("leads", {
  "@context": { ex: "https://example.org/" },
  select: { "?lead": ["*"] },
  where: [{ "@id": "?lead", "@type": "ex:Lead" }],
});

await app.insert("leads", {
  "@context": { ex: "https://example.org/" },
  "@type": "ex:Lead",
  "ex:email": "[email protected]",
  "ex:campaign": "trailhead",
});

// What can this app actually reach? (renders a capability panel)
console.log(app.capabilities()?.datasets);
console.log(app.capabilities()?.excludedDatasets); // and *why* they're out

Space primitives ride the same token: app.tasks, app.agents, app.conversations, app.artifacts, app.findings, and app.actions.

Integration actions

Deterministic direct invocation of integration actions (SaaS and custom Connector) — no LLM or MCP tool-name dependency. actionId is opaque and stable; address actions by id, never by display name.

// The Space's grant-gated action catalog (invocable actions only).
const [update] = await app.actions.list({
  operation: "update",
  objectType: "crm_contact",
});

const result = await app.actions.invoke(
  update.actionId,
  { recordId: "provider-record-id", name: "Acme Corporation" },
  { idempotencyKey: "rename-acme-2026-07" },
);
// result.data carries the provider payload; result.success / statusCode
// carry the dispatch outcome. On failure, result.errorCategory is a
// small normalized taxonomy (auth, not-found, conflict, rate-limit,
// client-error, server-error, output-schema, transport) so you never
// parse provider bodies to classify; result.schemaErrors lists strict
// outputSchema violations for custom actions.

approvalRequired on a catalog entry is an AI-agent control (agent executions route through Tasks approval in that Space); direct invoke() calls are deliberate application intent and are governed by the grant triple-gate alone. Pass a stable idempotencyKey for operations you may retry: it's forwarded to the provider where the action supports one (custom idempotency headers, SaaS create), making your retries replay instead of duplicate.

Canonical business metadata

Catalog entries carry canonical Business Model metadata: resourceClass (the full class IRI, e.g. https://ns.flur.ee/business/Contact) and, when the installation declares a field mapping, a compiled canonicalContract. Actions with a contract accept the canonical envelope — Business Model property IRIs plus a separately-carried record identity, which the server translates to the provider payload:

const [update] = await app.actions.list({
  resourceClass: "https://ns.flur.ee/business/Account",
  operation: "update",
});

await app.actions.invokeCanonical(update.actionId, {
  recordId: "provider-record-id",
  properties: { "https://schema.org/name": "Acme Corporation" },
});

Record identity always rides recordId, never the properties. Unknown properties are rejected server-side with the supported set listed, and provider-required properties are enforced at translation time rather than failing later at the provider. Provider-shaped input goes through app.actions.invoke(actionId, input).

The canonical envelope is transitional: the app-facing write API is converging on the JSON-LD transaction shape in Business Model vocabulary (the node shape app.upsert(ledger, …) already takes), where the ledger will select the system, the node's @type will select the contract, and the platform will route source-owned predicates outbound. That routing is not built yet — an upsert today writes to the graph only. Expect this section to shrink rather than grow.

Joining records across systems

When two systems describe the same person or company under no shared key, the resolved join lives in the stack's identity graph. Read it through the Space, not as a dataset:

const { entities } = await fluree.space.identityEntities({
  type: "person", // or "company" | "product"
  labelField: "id:label", // a SourceLink predicate — omit and you get IRIs only
});

// One identity, one link per system it was seen in.
for (const e of entities) {
  const byLedger = new Map(
    e.links.map((l) => [l.sourceLedger, l.sourceRecord]),
  );
  const hr = byLedger.get("workday:main");
  const crm = byLedger.get("salesforce:main");
}

sourceRecord is the source system's own record IRI, so the two halves key straight into your ordinary queries against each dataset.

There is no _identity dataset to grant. It is stack-global rather than Space-scoped, so no app token will ever carry it, and it also holds match evidence, resolution decisions and phone-dedup keys that no app should read. This call is the supported door: the stack reads the identity graph for you and returns only entities with at least one link in a dataset your Space can reach, with out-of-reach links stripped — so an app cannot learn that an entity exists somewhere it cannot see. Check truncated; when true the list is incomplete rather than exhausted.

For scripts/tools with a token in hand, createFlureeClient({ endpoint, auth: { bearer } }) gives the same surface without the Space binding.

Error handling

Every non-2xx response throws FlureeError with status and the raw body. error.isPolicyDenial (403) is the ledger's policy saying no — that's the governance working, not a bug in your app.

Install

npm i @fluree/client

The only runtime dependency is zod. The package ships ESM + CJS with bundled type declarations, and is self-contained — the contract schema types it uses are inlined at build time.

Development

Inside the monorepo the package is consumed from source (exports → src/index.ts); the published artifact is built separately. bun run build emits the self-contained dist/ bundle via tsup; bun run prepare-publish assembles the publish-ready staging directory under publish/.