@qaecy/cue-sdk 0.0.27 → 0.0.28

package/README.md

@@ -234,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.
@@ -258,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`: