@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.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',
);

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
});

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 |

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