@thatopen/services 0.16.0 → 0.17.0

package/src/core/examples/file-metadata.ts

@@ -0,0 +1,94 @@
+// description: "File metadata and versioning — get, update, and delete per-version metadata; list, archive, recover, and permanently delete versions."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  if (!PROJECT_ID) {
+    console.log('Set PROJECT_ID in .env to run this example.');
+    return;
+  }
+
+  // Create a test file to work with.
+  const blob = new Blob([JSON.stringify({ test: true })], { type: 'application/json' });
+  const fileName = `__example-test__-${Date.now()}.json`;
+  const created = await client.createFile({ file: blob, name: fileName, versionTag: 'v1', projectId: PROJECT_ID });
+  const fileId = created.item._id;
+  console.log(`\nCreated test file: [${fileId}] ${created.item.name}`);
+
+  // --- Get metadata (empty on a fresh version) ---
+  // Returns {} when the version exists but has no metadata yet — not null or 404.
+  const empty = await client.getFileVersionMetadata(fileId, 'v1');
+  console.log(`\nMetadata on v1 (fresh): ${JSON.stringify(empty)}`);
+
+  // --- Update metadata ---
+  const updated = await client.updateFileVersionMetadata(fileId, 'v1', {
+    discipline: 'structural',
+    approved: 'true',
+  });
+  console.log(`\nUpdated metadata: ${JSON.stringify(updated)}`);
+
+  // --- Get metadata (after update) ---
+  const meta = await client.getFileVersionMetadata(fileId, 'v1');
+  console.log(`\nMetadata on v1 (after update): ${JSON.stringify(meta)}`);
+
+  // --- Upload a second version and set metadata on it ---
+  const blobV2 = new Blob([JSON.stringify({ test: true, version: 2 })], { type: 'application/json' });
+  await client.updateFile(fileId, { file: blobV2, versionTag: 'v2' });
+  await client.updateFileVersionMetadata(fileId, 'v2', { discipline: 'architecture' });
+  console.log('\nUploaded v2 with its own metadata.');
+
+  // Metadata is per-version — each version holds its own independent metadata object.
+  const metaV1 = await client.getFileVersionMetadata(fileId, 'v1');
+  const metaV2 = await client.getFileVersionMetadata(fileId, 'v2');
+  console.log(`\nv1 metadata: ${JSON.stringify(metaV1)}`);
+  console.log(`v2 metadata: ${JSON.stringify(metaV2)}`);
+
+  // --- List versions ---
+  const versions = await client.listVersions(fileId);
+  console.log(`\nVersions (${versions.length}):`);
+  for (const v of versions) {
+    console.log(`  [${v.tag}] created: ${v.createdAt}`);
+  }
+
+  // --- Archive a version ---
+  // A version must be archived before it can be permanently deleted.
+  await client.archiveVersion(fileId, 'v1');
+  console.log('\nArchived v1.');
+
+  const versionsAfterArchive = await client.listVersions(fileId, { archived: false });
+  console.log(`Active versions after archiving v1: ${versionsAfterArchive.map(v => v.tag).join(', ')}`);
+
+  // --- Recover a version ---
+  await client.recoverVersion(fileId, 'v1');
+  console.log('Recovered v1.');
+
+  // --- Delete metadata ---
+  await client.deleteFileVersionMetadata(fileId, 'v1');
+  const afterDelete = await client.getFileVersionMetadata(fileId, 'v1');
+  console.log(`\nMetadata on v1 after delete: ${JSON.stringify(afterDelete)}`);
+
+  // --- Delete a version permanently ---
+  // archiveVersion first is required — deleteVersion on an active version returns an error.
+  await client.archiveVersion(fileId, 'v1');
+  await client.deleteVersion(fileId, 'v1');
+  console.log('\nPermanently deleted v1.');
+
+  // --- Cleanup ---
+  await client.archiveFile(fileId);
+  console.log(`\nArchived test file [${fileId}] — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/files.ts

@@ -0,0 +1,81 @@
+// description: "File lifecycle — list, get with versions, create, rename, upload new version, download by version, archive, and recover."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  // --- List ---
+  const files = await client.listFiles();
+  console.log(`\nFound ${files.length} file(s):`);
+  for (const file of files) {
+    console.log(`  [${file._id}] ${file.name}`);
+  }
+
+  // --- Get ---
+  if (files.length > 0) {
+    const detail = await client.getFile(files[0]._id, { showVersions: true });
+    console.log('\nFirst file detail (with versions):');
+    console.log(JSON.stringify(detail, null, 2));
+  }
+
+  if (!PROJECT_ID) {
+    console.log('\nSkipping create/update/download/archive — set PROJECT_ID in .env to run the full cycle.');
+    return;
+  }
+
+  // --- Create ---
+  // projectId is required — the backend rejects uploads without one.
+  const fileName = `__example-test__-${Date.now()}.json`;
+  const blob = new Blob([JSON.stringify({ test: true })], { type: 'application/json' });
+  const created = await client.createFile({ file: blob, name: fileName, versionTag: 'v1', projectId: PROJECT_ID });
+  console.log(`\nCreated file: [${created.item._id}] ${created.item.name}`);
+
+  const fileId = created.item._id;
+
+  // --- Update (rename) ---
+  const renamed = await client.updateFile(fileId, { name: `${fileName}-renamed` });
+  console.log(`\nRenamed to: ${renamed.item?.name}`);
+
+  // --- Update (new version) ---
+  const blobV2 = new Blob([JSON.stringify({ test: true, version: 2 })], { type: 'application/json' });
+  const versioned = await client.updateFile(fileId, { file: blobV2, versionTag: 'v2' });
+  console.log(`\nUploaded new version: ${versioned.version?.tag}`);
+
+  // --- Download ---
+  // Without versionTag, always downloads the latest version — not necessarily the one from createFile.
+  const response = await client.downloadFile(fileId);
+  const text = await response.text();
+  console.log(`\nDownloaded content (latest version): ${text}`);
+
+  const responseV1 = await client.downloadFile(fileId, { versionTag: 'v1' });
+  const textV1 = await responseV1.text();
+  console.log(`Downloaded content (v1): ${textV1}`);
+
+  // --- Archive / Recover ---
+  // archiveFile is a soft-delete — the file can be recovered with recoverFile.
+  await client.archiveFile(fileId);
+  console.log(`\nArchived file [${fileId}]`);
+
+  // recoverFile returns no body — confirm by re-fetching the file.
+  await client.recoverFile(fileId);
+  const recovered = await client.getFile(fileId);
+  console.log(`Recovered file: ${recovered.name}`);
+
+  // Archive again to leave the account clean.
+  await client.archiveFile(fileId);
+  console.log(`Re-archived test file [${fileId}] — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/folders.ts

@@ -0,0 +1,82 @@
+// description: "Folder lifecycle — list, get, create nested folders, list files inside a folder, rename, download as ZIP, archive, and recover."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  // --- List ---
+  const folders = await client.listFolders();
+  console.log(`\nFound ${folders.length} folder(s):`);
+  for (const folder of folders) {
+    console.log(`  [${folder._id}] ${folder.name}`);
+  }
+
+  // --- Get ---
+  if (folders.length > 0) {
+    const detail = await client.getFolder(folders[0]._id);
+    console.log('\nFirst folder detail:');
+    console.log(JSON.stringify(detail, null, 2));
+  }
+
+  if (!PROJECT_ID) {
+    console.log('\nSkipping create/update/download/archive — set PROJECT_ID in .env to run the full cycle.');
+    return;
+  }
+
+  // --- Create (parent) ---
+  const folderName = `__example-test__-${Date.now()}`;
+  const parent = await client.createFolder(folderName, undefined, PROJECT_ID);
+  console.log(`\nCreated folder: [${parent._id}] ${parent.name}`);
+
+  // --- Create (nested) ---
+  // parentId nests the folder inside another — omitting it creates a root-level folder.
+  const child = await client.createFolder(`${folderName}-child`, parent._id, PROJECT_ID);
+  console.log(`Created nested folder: [${child._id}] ${child.name}`);
+
+  // --- List by parent ---
+  // NOTE: listFolders({ parentFolderId }) returned 0 even after creating a child with that parentId.
+  // The backend may not index parentFolderId for filtering, or the field name differs internally.
+  const children = await client.listFolders({ parentFolderId: parent._id });
+  console.log(`\nChildren of [${parent._id}]: ${children.length} folder(s)`);
+
+  // --- List files inside a folder ---
+  const filesInFolder = await client.listFiles({ folderId: parent._id });
+  console.log(`Files inside folder: ${filesInFolder.length}`);
+
+  // --- Update (rename) ---
+  const renamed = await client.updateFolder(parent._id, { name: `${folderName}-renamed` });
+  console.log(`\nRenamed to: ${renamed.name}`);
+
+  // --- Download as ZIP ---
+  const zip = await client.downloadFolder(parent._id);
+  const buffer = await zip.arrayBuffer();
+  console.log(`\nDownloaded folder ZIP: ${buffer.byteLength} bytes`);
+
+  // --- Archive / Recover ---
+  // archiveFolder is a soft-delete — recoverable with recoverFolder.
+  // Archiving a parent cascades to all children: sub-folders and their files are archived too.
+  await client.archiveFolder(child._id);
+  console.log(`\nArchived child folder [${child._id}]`);
+
+  await client.recoverFolder(child._id);
+  console.log(`Recovered child folder [${child._id}]`);
+
+  // Archive both to clean up.
+  await client.archiveFolder(child._id);
+  await client.archiveFolder(parent._id);
+  console.log(`Re-archived folders — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/hidden-files.ts

@@ -0,0 +1,88 @@
+// description: "Hidden file lifecycle — create, get, list by parent, download, and delete."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  if (!PROJECT_ID) {
+    console.log('Set PROJECT_ID in .env to run this example.');
+    return;
+  }
+
+  // Hidden files are always attached to a parent item — they have no standalone existence.
+  // Create a parent file to work with.
+  const parentBlob = new Blob([JSON.stringify({ test: true })], { type: 'application/json' });
+  const parentName = `__example-test__-${Date.now()}.json`;
+  const parent = await client.createFile({ file: parentBlob, name: parentName, versionTag: 'v1', projectId: PROJECT_ID });
+  const parentId = parent.item._id;
+  console.log(`\nCreated parent file: [${parentId}] ${parent.item.name}`);
+
+  // --- Create hidden files ---
+  const hiddenBlob1 = new Blob([JSON.stringify({ hidden: 1 })], { type: 'application/json' });
+  const hiddenBlob2 = new Blob([JSON.stringify({ hidden: 2 })], { type: 'application/json' });
+
+  const hidden1 = await client.createHiddenFile(hiddenBlob1, parentId);
+  console.log(`\nCreated hidden file 1: [${hidden1.hiddenFileId}]`);
+
+  const hidden2 = await client.createHiddenFile(hiddenBlob2, parentId);
+  console.log(`Created hidden file 2: [${hidden2.hiddenFileId}]`);
+
+  // --- Tags ---
+  // The tag is optional on upload; a batch upload applies one tag to every file in it.
+  // Filtering by tag returns that tag's files in creation order.
+  const tagged = await client.createHiddenFile(hiddenBlob1, parentId, 'example:tagged');
+  const taggedList = await client.getHiddenFilesByParent(parentId, 'example:tagged');
+  console.log(`\nHidden files tagged 'example:tagged': ${taggedList.length} (first: [${tagged.hiddenFileId}] tag=${taggedList[0]?.tag})`);
+
+  // --- Get ---
+  const fetched = await client.getHiddenFile(hidden1.hiddenFileId);
+  console.log(`\nHidden file 1 detail:`);
+  console.log(JSON.stringify(fetched, null, 2));
+
+  // --- List by parent ---
+  const allHidden = await client.getHiddenFilesByParent(parentId);
+  console.log(`\nHidden files attached to parent: ${allHidden.length}`);
+  for (const h of allHidden) {
+    console.log(`  [${h._id}]`);
+  }
+
+  // --- Download ---
+  const response = await client.downloadHiddenFile(hidden1.hiddenFileId);
+  const text = await response.text();
+  console.log(`\nDownloaded hidden file 1: ${text}`);
+
+  // --- Delete one ---
+  await client.deleteHiddenFile(hidden1.hiddenFileId);
+  console.log(`\nDeleted hidden file 1 [${hidden1.hiddenFileId}]`);
+
+  // NOTE: getHiddenFilesByParent may still return deleted files immediately after deletion —
+  // the backend list appears to be eventually consistent.
+  const afterDelete = await client.getHiddenFilesByParent(parentId);
+  console.log(`Hidden files remaining: ${afterDelete.length}`);
+
+  // --- Delete all by parent ---
+  // deleteHiddenFilesByParent removes all hidden files attached to the parent in one call.
+  await client.deleteHiddenFilesByParent(parentId);
+  console.log(`\nDeleted all remaining hidden files for parent [${parentId}]`);
+
+  const afterDeleteAll = await client.getHiddenFilesByParent(parentId);
+  console.log(`Hidden files remaining: ${afterDeleteAll.length}`);
+
+  // --- Cleanup ---
+  await client.archiveFile(parentId);
+  console.log(`\nArchived parent file [${parentId}] — account is clean.`);
+}
+
+main().catch(console.error);

package/src/core/examples/icons.ts

@@ -0,0 +1,68 @@
+// description: "Item icon management — upload, download, and remove icons on any item (file, app, or component)."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { EngineServicesClient } from '../client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const ACCESS_TOKEN = process.env.ACCESS_TOKEN;
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+if (!ACCESS_TOKEN || !API_URL) {
+  throw new Error('ACCESS_TOKEN and API_URL are required in src/core/examples/.env');
+}
+
+async function main() {
+  const client = new EngineServicesClient(ACCESS_TOKEN!, API_URL!);
+
+  if (!PROJECT_ID) {
+    console.log('Set PROJECT_ID in .env to run this example.');
+    return;
+  }
+
+  // Create a test file to attach an icon to.
+  const blob = new Blob([JSON.stringify({ test: true })], { type: 'application/json' });
+  const fileName = `__example-test__-${Date.now()}.json`;
+  const created = await client.createFile({ file: blob, name: fileName, versionTag: 'v1', projectId: PROJECT_ID });
+  const itemId = created.item._id;
+  console.log(`\nCreated test file: [${itemId}] ${created.item.name}`);
+
+  // --- Upload icon ---
+  // Accepted formats: PNG, WebP, or ICO — max 512 KB.
+  // uploadItemIcon replaces any existing icon; there is no separate "update icon" method.
+  const iconPng = generateMinimalPng();
+  const updated = await client.uploadItemIcon(itemId, iconPng);
+  console.log(`\nUploaded icon. iconFileId: ${updated.iconFileId}, mimeType: ${updated.iconMimeType}`);
+
+  // --- Download icon ---
+  const iconResponse = await client.getItemIcon(itemId);
+  const iconBuffer = await iconResponse.arrayBuffer();
+  console.log(`\nDownloaded icon: ${iconBuffer.byteLength} bytes`);
+
+  // --- Remove icon ---
+  const removed = await client.removeItemIcon(itemId);
+  console.log(`\nRemoved icon. iconFileId: ${removed.iconFileId ?? 'null'}`);
+
+  // --- Cleanup ---
+  await client.archiveFile(itemId);
+  console.log(`\nArchived test file [${itemId}] — account is clean.`);
+}
+
+// Generates the smallest valid PNG (1x1 transparent pixel) as a Blob.
+function generateMinimalPng(): Blob {
+  const bytes = new Uint8Array([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, // PNG signature
+    0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52, // IHDR chunk length + type
+    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, // width=1, height=1
+    0x08, 0x06, 0x00, 0x00, 0x00, 0x1f, 0x15, 0xc4, // bit depth=8, colorType=6 (RGBA)
+    0x89, 0x00, 0x00, 0x00, 0x0b, 0x49, 0x44, 0x41, // IHDR CRC + IDAT chunk
+    0x54, 0x78, 0x9c, 0x62, 0x00, 0x00, 0x00, 0x02, // IDAT data (zlib compressed)
+    0x00, 0x01, 0xe2, 0x21, 0xbc, 0x33, 0x00, 0x00, // IDAT CRC
+    0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, // IEND chunk
+    0x60, 0x82,
+  ]);
+  return new Blob([bytes], { type: 'image/png' });
+}
+
+main().catch(console.error);

package/src/core/examples/permissions.ts

@@ -0,0 +1,87 @@
+// description: "Permission checks — single and batch permission verification using PlatformClient (requires user JWT, not API token)."
+import { config } from 'dotenv';
+import { resolve } from 'path';
+import { PlatformClient } from '../platform-client';
+
+config({ path: resolve(__dirname, '.env') });
+
+const API_URL = process.env.API_URL;
+const PROJECT_ID = process.env.PROJECT_ID;
+
+// PlatformClient requires a user JWT — not the API token used by EngineServicesClient.
+// To run this example:
+//   1. Open the platform in your browser and log in.
+//   2. Open DevTools → Network → click any /api request.
+//   3. Copy the Authorization header value (without the "Bearer " prefix).
+//   4. Set it as JWT in src/core/examples/.env.
+const JWT = process.env.JWT;
+
+if (!API_URL) {
+  throw new Error('API_URL is required in src/core/examples/.env');
+}
+
+if (!JWT) {
+  throw new Error(
+    'JWT is required to run permissions.ts.\n' +
+    'Get it from DevTools → Network → any /api request → Authorization header (without "Bearer ").\n' +
+    'Set it as JWT in src/core/examples/.env.',
+  );
+}
+
+if (!PROJECT_ID) {
+  throw new Error('PROJECT_ID is required in src/core/examples/.env');
+}
+
+async function main() {
+  // PlatformClient extends EngineServicesClient and forces useBearer: true.
+  // It owns the JWT-only routes — checkPermission, checkPermissionBatch, getProject, getProjectData.
+  // These routes are guarded server-side and are not reachable with an API token.
+  const client = new PlatformClient(JWT!, API_URL!);
+
+  // --- Single permission check ---
+  const result = await client.checkPermission({
+    resourceType: 'STORAGE',
+    action: 'READ',
+    projectId: PROJECT_ID,
+  });
+  console.log('\nSTORAGE:READ check:');
+  console.log(`  hasPermission: ${result.hasPermission}`);
+  // scope indicates HOW the permission was granted:
+  //   'global'  — admin/owner bypass
+  //   'project' — role-level grant on the project
+  //   'entity'  — per-entity override
+  //   'none'    — denied
+  console.log(`  scope: ${result.scope}`);
+
+  // --- Batch permission check ---
+  // Evaluates multiple checks in a single round-trip — useful to hydrate
+  // action visibility for many rows without N+1 calls.
+  const checks = [
+    { resourceType: 'STORAGE', action: 'READ', projectId: PROJECT_ID },
+    { resourceType: 'STORAGE', action: 'WRITE', projectId: PROJECT_ID },
+    { resourceType: 'STORAGE', action: 'DELETE', projectId: PROJECT_ID },
+  ];
+  const results = await client.checkPermissionBatch(checks);
+  console.log('\nBatch permission check:');
+  for (let i = 0; i < checks.length; i++) {
+    const { resourceType, action } = checks[i];
+    const { hasPermission, scope } = results[i];
+    console.log(`  ${resourceType}:${action} → hasPermission: ${hasPermission}, scope: ${scope}`);
+  }
+
+  // --- Get project ---
+  const project = await client.getProject(PROJECT_ID!);
+  console.log('\nProject:');
+  console.log(JSON.stringify(project, null, 2));
+
+  // --- Get project data ---
+  // getProjectData returns the full project snapshot: users, roles, files, folders.
+  // User data is stripped of sensitive fields server-side.
+  const data = await client.getProjectData(PROJECT_ID!);
+  console.log('\nProject data (summary):');
+  console.log(`  users: ${data.users?.length ?? 0}`);
+  console.log(`  files: ${data.files?.length ?? 0}`);
+  console.log(`  folders: ${data.folders?.length ?? 0}`);
+}
+
+main().catch(console.error);