@qaecy/cue-sdk

Headless JavaScript SDK for building apps on the QAECY Cue platform. A framework-agnostic client that handles authentication, project management, and API access — the programmatic counterpart to the @qaecy/cue-widget.

Installation

npm install @qaecy/cue-sdk firebase

firebase is a peer dependency and must be installed alongside the SDK.

Quick start

Demo app

import { Cue } from '@qaecy/cue-sdk';

// Use default demo app (prints a warning — fine for evaluation)
const cue = new Cue();

// Or supply your own configuration
const cue = new Cue({
  apiKey: 'YOUR_FIREBASE_API_KEY',
  appId: 'YOUR_FIREBASE_APP_ID',
  measurementId: 'YOUR_MEASUREMENT_ID',
});

// Listen for auth state changes
cue.auth.onAuthStateChanged((user) => {
  console.log(user ? `Signed in as ${user.displayName}` : 'Signed out');
});

// Sign in
await cue.auth.signIn('google');
// or
await cue.auth.signIn('microsoft');
// or
await cue.auth.signIn('password', { email: '[email protected]', password: 'secret' });

// List projects
const projects = await cue.api.projects.listProjects();

// Search documents
const results = await cue.api.search({
  term: 'What are the fire safety requirements?',
  projectId: projects[0].id,
});

console.log(results.response);
console.log(results.sources);

// Sign out
await cue.auth.signOut();

Configuration

| Option | Type | Required | Description | |---|---|---|---| | apiKey | string | — | Firebase API key (defaults to QAECY demo app) | | appId | string | — | Firebase App ID (defaults to QAECY demo app) | | measurementId | string | — | Firebase Measurement ID (defaults to QAECY demo app) | | environment | 'production' \| 'emulator' | — | Target environment (default: 'production') | | endpoints | Partial<CueEndpoints> | — | Override individual endpoint URLs (takes precedence over environment) |

Auth

cue.auth.signIn(provider)

Sign in with Google or Microsoft via a browser popup:

const user = await cue.auth.signIn('google');
const user = await cue.auth.signIn('microsoft');

cue.auth.signIn('password', credentials)

Sign in with email and password:

const user = await cue.auth.signIn('password', {
  email: '[email protected]',
  password: 's3cr3t',
});

cue.auth.signInWithApiKey(cueApiKey, projectId)

Sign in using a Cue API key. Intended for non-interactive/server-side use (e.g. via CueNode):

const user = await cue.auth.signInWithApiKey('MY_CUE_API_KEY', 'my-project-id');

cue.auth.signInWithCustomToken(token)

Sign in using a Firebase custom token. Intended for server-issued auth flows such as MCP tools or OAuth-protected backends where the server mints a token on behalf of the user.

Typical flow (e.g. MCP + Google OAuth):

1. The server receives a Google OAuth access token (e.g. via the MCP host's OAuth dance).
2. The server looks up the Firebase UID for the Google sub claim and mints a custom token using Firebase Admin:

   // Server side (Node.js / Firebase Admin)
   import * as admin from 'firebase-admin';
   
   async function mintCustomToken(googleAccessToken: string): Promise<string> {
     const res = await fetch('https://www.googleapis.com/oauth2/v3/userinfo', {
       headers: { Authorization: `Bearer ${googleAccessToken}` },
     });
     const { sub } = await res.json(); // Google UID
   
     const user = await admin.auth().getUserByProviderUid('google.com', sub);
     return admin.auth().createCustomToken(user.uid);
   }

3. The custom token is passed to the browser/view (e.g. via structuredContent).
4. The client signs in instantly — no popup, no redirect, no polling:

   // Browser / view side
   const cue = new Cue();
   await cue.auth.signInWithCustomToken(customToken);
   // cue is now fully authenticated

cue.auth.signOut()

await cue.auth.signOut();

cue.auth.currentUser

Returns the currently signed-in Firebase User, or null.

cue.auth.onAuthStateChanged(listener)

Subscribe to auth state changes. Returns an unsubscribe function.

const unsubscribe = cue.auth.onAuthStateChanged((user) => {
  if (user) startApp(user);
});

// Later:
unsubscribe();

cue.auth.getToken(forceRefresh?)

Get the Firebase ID token for the current user:

const token = await cue.auth.getToken();

API

All API methods require the user to be authenticated first.

cue.api.search(request)

Search project documents using natural language:

const results = await cue.api.search({
  term: 'fire resistance requirements',
  projectId: 'my-project-id',
  categories: ['buildings', 'regulations'], // optional
});

// results.response  — AI-generated answer
// results.sources   — source documents

cue.api.sparql(query, projectId)

Execute a SPARQL query against the project's triplestore:

const data = await cue.api.sparql(
  `SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10`,
  'my-project-id',
);

cue.api.language / cue.api.setLanguage(lang)

Active language used for language-sensitive SPARQL label queries (e.g. schema category labels and document text fields). Defaults to 'en'. All project classes (CueProjectSchema, CueProjectDocuments, CueProjectEntities) read this shared value at query time.

cue.api.setLanguage('da');
console.log(cue.api.language); // 'da'

When using CueProjectView, prefer calling view.setLanguage(lang) — it updates api.language and reloads language-sensitive cached data (schema labels, document subjects/summaries) for the new language.

Projects

Manage Cue projects via cue.api.projects (CueProjects).

cue.api.projects.listProjects()

List all projects where the authenticated user is a member, syncer, or admin:

const projects = await cue.api.projects.listProjects();
projects.forEach((p) => console.log(p.id, p.name));

cue.api.projects.getProject(projectId)

Fetch a single project by ID. Returns null if not found:

const project = await cue.api.projects.getProject('my-project-id');

cue.api.projects.createProject(options)

Create a new project. The authenticated user is automatically set as admin, syncer, and member:

const project = await cue.api.projects.createProject({
  name: 'My Project',
  organizationID: 'my-org-id',
  id: 'optional-custom-id', // defaults to a new UUID
});

Entities

Entity data for a project is accessed via a CueProjectView. Create a view with cue.createProjectView(projectId) and use view.entities (CueProjectEntities) for all entity-level operations.

view.entities.entitiesByCategory(categoryIris, includeMetadata?)

Fetch all canonical entities that belong to at least one of the given category IRIs. Accepts both full HTTP IRIs and prefixed forms.

By default returns { iri, uuid }[] — the IRI is built locally from the project base URL so no extra data is fetched from the endpoint. Pass true to also receive value and categories.

// Lean — iri + uuid, no extra SPARQL traffic (default)
const entities = await view.entities.entitiesByCategory([
  'qcy:Building',
  'qcy:BuildingStorey',
]);
view.entities.requestEntityData(entities.map((e) => e.uuid));

// With metadata
const entities = await view.entities.entitiesByCategory(
  ['https://cue.qaecy.com/ontology#Building'],
  true,
);
entities.forEach((e) => console.log(e.uuid, e.value, e.categories));

| Parameter | Type | Description | |---|---|---| | categoryIris | string[] | Full IRIs (https://…) or prefixed forms (qcy:…) | | includeMetadata | boolean | false (default) → { iri, uuid }[]; true → adds value and categories |

view.entities.contentCategoriesInProject(orderByOccurrences?)

Fetch all qcy:EntityCategory IRIs present in this project with their preferred labels:

const cats = await view.entities.contentCategoriesInProject();
cats.forEach((c) => console.log(c.iri, c.label));

view.entities.buildSummaryGraph(format?)

Fetches a project-level summary of entity category relationships: how many times entities of one category point to entities of another via each predicate, ordered by descending occurrence count.

| Parameter | Type | Description | |---|---|---| | format | 'graph' | 'md' | undefined | 'graph' returns structured nodes + edges (SummaryGraphData); 'md' returns a compact aligned text table; omit for the raw SPARQL JSON result |

// Structured graph — nodes and edges separated
const g = await view.entities.buildSummaryGraph('graph');
// g.entities  → [{ iri: 'https://…FloorPlanDrawing' }, …]
// g.relations → [{ sourceID, predicate, targetID, weight }, …]

// Compact markdown table
const md = await view.entities.buildSummaryGraph('md');
// qcy:FloorPlanDrawing -> qcy:includesBuildingEntity -> qcy:BuildingZone     (5652)
// qcy:Activity         -> qcy:involvesBuildingEntity -> qcy:BuildingElement  (4003)
// qcy:BuildingElement  -> qcy:elementHasMaterial     -> qcy:Material         (3551)

// Raw SPARQL JSON result
const raw = await view.entities.buildSummaryGraph();

Documents

Document data for a project is accessed via view.documents (CueProjectDocuments). Use fetchOverview() to get aggregate counts and the methods below to retrieve document lists.

view.documents.documentsBySuffix(suffixes, includeMetadata?)

Fetch all documents whose file extension matches one of the given suffixes. The leading dot is optional — both 'ifc' and '.ifc' are accepted.

By default returns { iri, uuid }[] — the IRI is built locally from the project base URL, no extra data fetched. Pass true to also receive path, suffix, and size.

// Lean — iri + uuid, no extra SPARQL traffic (default)
const docs = await view.documents.documentsBySuffix(['.ifc', '.rvt']);
view.documents.requestDocumentData(docs.map((d) => d.uuid));

// With file metadata
const docs = await view.documents.documentsBySuffix(['pdf', 'docx'], true);
docs.forEach((d) => console.log(d.path, d.suffix, d.size));

view.documents.documentsByFileType(fileTypes, includeMetadata?)

Fetch documents by semantic FileType category. Resolves all matching suffixes automatically from the built-in fileExtensionsInfo map.

import { FileType } from 'js/models';

// All BIM and CAD files — iri + uuid
const docs = await view.documents.documentsByFileType([
  FileType.BIM,
  FileType.CAD,
]);

// With metadata
const docs = await view.documents.documentsByFileType([FileType.IMAGE], true);

view.documents.documentsByMime(mimeTypes, includeMetadata?)

Fetch documents whose MIME type matches one of the given strings:

// Just iri + uuid
const docs = await view.documents.documentsByMime([
  'application/x-step',  // .ifc
  'application/pdf',
]);

// With metadata
const docs = await view.documents.documentsByMime(
  ['image/png', 'image/jpeg'],
  true,
);

| Method | Filters by | Default return | With true | |---|---|---|---| | documentsBySuffix | File extension string(s) | { iri, uuid }[] | adds path, suffix, size | | documentsByFileType | FileType enum value(s) | { iri, uuid }[] | adds path, suffix, size | | documentsByMime | MIME type string(s) | { iri, uuid }[] | adds path, suffix, size |

Node.js — file sync

For server-side or CLI use with file-sync capabilities, import from @qaecy/cue-sdk/node:

import { CueNode } from '@qaecy/cue-sdk/node';

const cue = new CueNode({
  apiKey: 'YOUR_FIREBASE_API_KEY',
  appId: 'YOUR_FIREBASE_APP_ID',
  measurementId: 'YOUR_MEASUREMENT_ID',
});

// Use an API key for non-interactive sign-in
await cue.auth.signInWithApiKey('MY_CUE_API_KEY', 'my-project-id');

// Sync local files into a project
const result = await cue.api.sync.sync(localFiles, {
  spaceId: 'my-project-id',
  providerId: 'my-provider',
  userId: cue.auth.currentUser!.uid,
  verbose: true,
});

console.log(`Synced ${result.syncCount} files (${result.failedUploads} failed)`);

cue.api.sync.sync(localFiles, options)

Compares local files against the remote project and uploads any that are missing or changed.

| Option | Type | Description | |---|---|---| | spaceId | string | Project ID to sync into | | providerId | string | Identifier for the file source (e.g. 'local') | | userId | string | Authenticated user ID | | verbose | boolean | Enable progress logging (default: false) |

Returns a SyncResult:

| Field | Type | Description | |---|---|---| | syncCount | number | Files successfully synced | | syncSize | number | Bytes synced | | failedUploads | number | Files that failed to upload | | totalCount | number | Total file count (local + remote) | | totalSize | number | Total size across all files | | rdfWritten | boolean | Whether any RDF metadata was written |

GIS

Reactive GIS service for querying spatial features within a map viewport. Accessed via the lazy getter cue.gis — the CueGis instance is created on first access and reused for the lifetime of the Cue object.

The js/cue-gis library (gateway routing, adapters, OpenStreetMap, Matrikel, etc.) is bundled inside the SDK — no extra install needed.

Quick example

const gis = cue.gis;

// Set the active project (drives the Cue-authenticated data source)
gis.setProjectId('my-project-id');

// Subscribe to results
const unsubCats = gis.onAvailableCategories((cats) => {
  console.log('Available categories:', cats.map(c => c.label));
});

const unsubFeatures = gis.onFeaturesChange((featuresMap) => {
  for (const [category, features] of featuresMap) {
    console.log(`${category}: ${features.length} features`);
  }
});

gis.onLoadingChange((loading) => console.log('Loading:', loading));

// On every map pan/zoom (e.g. from a Mapbox moveend event):
map.on('moveend', () => {
  const b = map.getBounds();
  gis.setBbox([b.getWest(), b.getSouth(), b.getEast(), b.getNorth()]);
});

// When the user toggles a category:
gis.setSelectedCategories(new Set(['cadastre', 'building']));

// Cleanup (e.g. on sign-out or component destroy):
unsubCats();
unsubFeatures();
gis.destroy();

cue.gis.setProjectId(projectId)

Set the active project. Triggers a new query when a bbox is set. Pass null to clear.

cue.gis.setProjectId('my-project-id');
cue.gis.setProjectId(null); // clear

cue.gis.setBbox(bbox)

Set the current map viewport as [west, south, east, north] (WGS-84). Triggers a debounced query (1.5 s) to list available categories and reload selected features.

cue.gis.setBbox([8.5, 47.3, 8.6, 47.4]);

cue.gis.setSelectedCategories(categories)

Replace the full set of selected categories. Features for newly selected categories are fetched immediately; deselected ones are dropped from the results.

cue.gis.setSelectedCategories(new Set(['cadastre', 'building', 'greenspace']));

cue.gis.onAvailableCategories(callback) → unsubscribe

Subscribe to the list of feature-category descriptors available in the current viewport. Replays the current value immediately.

const unsub = cue.gis.onAvailableCategories((cats) => {
  // cats: GisCategoryDescriptor[]
  renderCategoryPanel(cats);
});

cue.gis.onFeaturesChange(callback) → unsubscribe

Subscribe to the live feature map (category → features). Replays the current value immediately.

const unsub = cue.gis.onFeaturesChange((map) => {
  // map: Map<FeatureCategory, GisFeature[]>
  for (const [cat, features] of map) renderLayer(cat, features);
});

cue.gis.onLoadingChange(callback) → unsubscribe

Subscribe to the global loading state. true while any query is in flight.

const unsub = cue.gis.onLoadingChange((loading) => showSpinner(loading));

cue.gis.destroy()

Cancel all in-flight requests, clear all listeners, and reset internal state. Call on sign-out or component teardown.

Types

| Type | Description | |---|---| | GisBBox | [west, south, east, north] — WGS-84 decimal degrees | | FeatureCategory | 'address' \| 'poi' \| 'railway' \| 'natural' \| 'manmade' \| 'cadastre' \| 'building' \| 'greenspace' \| 'paved' \| 'zone' | | GisCategoryDescriptor | { category, label, description, preferredColor } | | GisFeature | Full feature record with geometry, properties, tier, source info | | GisFeaturesMap | Map<FeatureCategory, GisFeature[]> | | CueGis | The class exposed via cue.gis |

Advanced

Access the raw Firebase Auth instance for advanced use cases:

const firebaseAuth = cue.auth.firebaseAuth;

E2E tests

The SDK ships integration tests in e2e/ that run against the local Firebase emulator stack.

Prerequisites

Start the frontend emulator stack from the e2e repo (requires Docker):

# From /path/to/e2e
docker compose up firebase-emulator frontend-seed

This spins up Firebase Auth, Firestore, and Storage emulators and seeds the following password-enabled test accounts:

| Email | Password | Role | |-------|----------|------| | [email protected] | Test1234! | member | | [email protected] | Test1234! | superadmin |

Run

npx nx run js-cue-sdk:e2e

Or directly with vitest (from libs/js/cue-sdk/):

npx vitest run --config vitest.e2e.config.mts

What is tested

| Suite | Tests | |-------|-------| | CueAuth — reactive signals | user, token, isSuperAdmin (false), checkSuperAdmin(), userIds | | CueProfile — password management | getSignInMethods, updatePassword → sign-in with new pw, old pw rejected, restore | | CueAuth — superadmin claim | isSuperAdmin signal (true), checkSuperAdmin() (true) |

License

MIT