@qaecy/cue-sdk 0.0.26 → 0.0.28

package/README.md

@@ -94,6 +94,37 @@ Sign in using a Cue API key. Intended for non-interactive/server-side use (e.g.
 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:
+   ```typescript
+   // 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:
+   ```typescript
+   // Browser / view side
+   const cue = new Cue();
+   await cue.auth.signInWithCustomToken(customToken);
+   // cue is now fully authenticated
+   ```
+
 ### `cue.auth.signOut()`
 
 ```typescript
@@ -203,6 +234,43 @@ const project = await cue.api.projects.createProject({
 
 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 only `{ iri, uuid }` — suitable for feeding directly into `requestEntityData()` for lazy detail loading. Pass `true` to also receive `value` and `categories`.
+
+```typescript
+// Lean — just IRIs + UUIDs (default)
+const entities = await view.entities.entitiesByCategory([
+  'qcy:Building',
+  'qcy:BuildingStorey',
+]);
+const uuids = entities.map((e) => e.uuid);
+view.entities.requestEntityData(uuids); // lazy-loads labels + categories
+
+// 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:
+
+```typescript
+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.
@@ -227,6 +295,68 @@ const md = await view.entities.buildSummaryGraph('md');
 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 only `{ iri, uuid }` for pairing with `requestDocumentData()`. Pass `true` to also receive `path`, `suffix`, and `size`.
+
+```typescript
+// Lean — just IRIs + UUIDs (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.
+
+```typescript
+import { FileType } from 'js/models';
+
+// All BIM and CAD files
+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:
+
+```typescript
+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 | Extra metadata (`true`) |
+|---|---|---|
+| `documentsBySuffix` | File extension string(s) | `path`, `suffix`, `size` |
+| `documentsByFileType` | `FileType` enum value(s) | `path`, `suffix`, `size` |
+| `documentsByMime` | MIME type string(s) | `path`, `suffix`, `size` |
+
+All three exclude alternative representations (e.g. derived `.fragments` tiles) from results.
+
 ## Node.js — file sync
 
 For server-side or CLI use with file-sync capabilities, import from `@qaecy/cue-sdk/node`: