npm package: @qaecy/cue-sdk
Description: 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`.
Latest version: 0.0.3

# @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

```bash
npm install @qaecy/cue-sdk firebase
```

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

## Quick start

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

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: 'user@example.com', 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 |
| `appId` | `string` | ✅ | Firebase App ID |
| `measurementId` | `string` | ✅ | Firebase Measurement ID |
| `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:

```typescript
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:

```typescript
const user = await cue.auth.signIn('password', {
  email: 'user@example.com',
  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`):

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

### `cue.auth.signOut()`

```typescript
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.

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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`:

```typescript
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:

```typescript
const firebaseAuth = cue.auth.firebaseAuth;
```

## License

MIT