Class Drive

Drive class for managing file storage drives

This class represents a drive in the Mosaia platform, which is a container for organizing and managing files and documents. Drives can be scoped to users or organizations.

Features:

  • Drive configuration management
  • File and document organization
  • Access control
  • Metadata management

Remarks

Drives provide:

  • File storage organization
  • User/org-scoped storage
  • File metadata management
  • Access control

Example

Basic drive setup:

import { Drive } from 'mosaia-node-sdk';

// Create a new drive
const drive = new Drive({
  name: 'My Documents',
  description: 'Personal document storage'
});

await drive.save();

Example

Managing drive items:

// Get all items in the drive
const items = await drive.items.get();

// Create a new item (metadata-only)
const item = await drive.items.create({
  name: 'document.pdf',
  path: '/documents'
});

Hierarchy (View Summary)

Constructors

constructor

Accessors

items uploads indexes access

Methods

isActive toJSON toAPIPayload update save delete findItemByPath

Constructors

constructor

  • new Drive(data: Partial<DriveInterface>, uri?: string): Drive

    Creates a new Drive instance

    Initializes a drive with the provided configuration data and optional URI. The drive represents a container for organizing files and documents.

    Parameters

    • data: Partial<DriveInterface>

      Drive configuration data

    • Optionaluri: string

      Optional URI path for the drive endpoint. Defaults to '/drive'

    Returns Drive

    Example

    const drive = new Drive({
      name: 'Project Files',
      description: 'Storage for project documents'
    });

Accessors

items

  • get items(): DriveItems

    Get the drive's items collection

    This getter provides access to the drive's items through the DriveItems collection. It enables management of all files and documents within the drive.

    Returns DriveItems

    DriveItems collection for managing drive items

    Example

    List items:

    const items = await drive.items.get();
    items.forEach(item => {
      console.log(`Item: ${item.name}`);
    });

    Example

    Create item:

    const item = await drive.items.create({
      name: 'document.pdf',
      path: '/documents',
      size: 1024
    });

uploads

  • get uploads(): UploadJobs

    Get the drive's upload jobs collection

    This getter provides access to the drive's upload jobs through the UploadJobs collection. It enables management of all upload jobs for the drive.

    Returns UploadJobs

indexes

  • get indexes(): VectorIndexes

    Get the drive's vector indexes collection

    This getter provides access to the drive's vector indexes through the VectorIndexes collection. It enables management of all vector indexes associated with this drive.

    Returns VectorIndexes

    VectorIndexes collection for managing vector indexes

    Example

    List indexes:

    const drive = await client.drives.get({}, driveId);
    const indexes = await drive.indexes.get({ active: true });
    indexes.forEach(index => {
      console.log(`Index: ${index.name}`);
    });

    Example

    Create index:

    const drive = await client.drives.get({}, driveId);
    const index = await drive.indexes.create({
      name: 'Document Search Index',
      description: 'Index for searching documents'
    });

access

  • get access(): Access

    Get the access control functionality for this drive

    This getter provides access to the drive's access control methods through the Access class. It allows for granting and revoking permissions to users, org users, agents, and clients.

    Available roles for drives: READ_ONLY, VIEWER, CONTRIBUTOR, EDITOR, MANAGER

    Returns Access

    An Access instance configured for this drive

    Example

    Grant access with different roles:

    const drive = await client.drives.get({}, driveId);

    // Grant viewer role (read-only)
    await drive.access.grantByRole({ org_user: 'orguser123' }, 'VIEWER');

    // Grant editor role (read, create, update)
    await drive.access.grantByRole({ org_user: 'orguser123' }, 'EDITOR');

    // Grant manager role (full access)
    await drive.access.grantByRole({ org_user: 'orguser123' }, 'MANAGER');

    Example

    Grant access with cascade to items:

    const drive = await client.drives.get({}, driveId);

    // Grant manager role and cascade to all items
    await drive.access.grantByRole(
      { org_user: 'orguser123' },
      'MANAGER',
      { cascade_to_items: true }
    );

    // Cascade only to folders
    await drive.access.grantByRole(
      { org_user: 'orguser123' },
      'EDITOR',
      { cascade_to_folders: true }
    );

    Example

    List all accessors:

    const drive = await client.drives.get({}, driveId);

    const result = await drive.access.list();
    console.log(`Drive has ${result.accessors.length} accessors`);

    result.accessors.forEach(accessor => {
      console.log(`${accessor.accessor_type}: ${accessor.accessor_id} - ${accessor.role}`);
    });

    Example

    Revoke access:

    const drive = await client.drives.get({}, driveId);

    // Revoke all access from a user
    const result = await drive.access.revoke({ org_user: 'orguser123' });
    console.log(`Revoked ${result.revoked_count} permissions`);

    // Revoke all access from an agent
    const agent = await client.agents.get({}, agentId);
    const result = await drive.access.revoke({ agent: agent });
    console.log(`Removed ${result.revoked_count} permissions`);

Methods

isActive

  • isActive(): boolean

    Check if the entity is active

    This method checks the active status of the entity. Most entities in the system can be active or inactive, which affects their availability and usability in the platform.

    Returns boolean

    True if the entity is active, false otherwise

    Example

    const user = new User(userData);
    if (user.isActive()) {
      // Perform operations with active user
    } else {
      console.log('User is inactive');
    }

toJSON

  • toJSON(): DriveInterface

    Convert model instance to interface data

    This method serializes the model instance to a plain object that matches the interface type. This is useful for:

    • Sending data to the API
    • Storing data in a database
    • Passing data between components
    • Debugging model state

    Returns DriveInterface

    The model data as a plain object matching the interface type

    Example

    const user = new User({
      email: 'user@example.com',
      firstName: 'John'
    });

    const data = user.toJSON();
    console.log(data); // { email: '...', firstName: '...' }

    // Use with JSON.stringify
    const json = JSON.stringify(user);

toAPIPayload

  • toAPIPayload(): Partial<DriveInterface>

    Convert model instance to API payload

    This method creates a payload suitable for API requests by:

    • Converting the model to a plain object
    • Removing read-only fields (like 'id')
    • Ensuring proper data format for the API

    Returns Partial<DriveInterface>

    A clean object suitable for API requests

    Example

    const user = new User({
      id: '123',           // Will be removed from payload
      email: 'new@example.com',
      firstName: 'John'
    });

    const payload = user.toAPIPayload();
    // payload = { email: '...', firstName: '...' }
    // Note: 'id' is removed as it's read-only

    await apiClient.POST('/users', payload);

update

  • update(updates: Partial<DriveInterface>): void

    Update model data with new values

    This method updates the model's data and instance properties with new values. It performs a shallow merge of the updates with existing data, allowing for partial updates of the model's properties.

    Parameters

    • updates: Partial<DriveInterface>

      Object containing properties to update

    Returns void

    Example

    const user = new User({
      email: 'old@example.com',
      firstName: 'John'
    });

    // Update multiple properties
    user.update({
      email: 'new@example.com',
      lastName: 'Doe'
    });

    // Save changes to API
    await user.save();

    Remarks

    This method only updates the local model instance. To persist changes to the API, call save after updating.

save

  • save(): Promise<DriveInterface>

    Save the model instance to the API

    This method persists the current state of the model to the API using a PUT request. It requires the model to have an ID (existing instance). For new instances, use the collection's create method instead.

    The method:

    1. Validates the model has an ID
    2. Sends current data to the API
    3. Updates local instance with API response

    Returns Promise<DriveInterface>

    Promise resolving to the updated model data

    Throws

    When model has no ID

    Throws

    When API request fails

    Example

    const user = new User({
      id: '123',
      email: 'user@example.com'
    });

    // Update and save
    user.update({ firstName: 'John' });
    await user.save();

    Example

    Error handling:

    try {
      await user.save();
    } catch (error) {
      if (error.message.includes('ID is required')) {
        // Handle missing ID error
      } else {
        // Handle API errors
      }
    }

delete

  • delete(params?: object): Promise<void>

    Delete the model instance from the API

    This method permanently deletes the model instance from the API and clears the local data. This operation cannot be undone.

    The method:

    1. Validates the model has an ID
    2. Sends DELETE request to the API
    3. Clears local instance data on success

    Parameters

    • Optionalparams: object

      Optional query parameters for deletion (e.g., { delete: true, deleteS3: true })

    Returns Promise<void>

    Promise that resolves when deletion is successful

    Throws

    When model has no ID

    Throws

    When API request fails

    Example

    Basic deletion:

    const user = await users.get({}, 'user-id');
    if (user) {
      await user.delete();
      // User is now deleted and instance is cleared
    }

    Example

    Error handling:

    try {
      await user.delete();
      console.log('User deleted successfully');
    } catch (error) {
      if (error.message.includes('ID is required')) {
        console.error('Cannot delete - no ID');
      } else {
        console.error('Deletion failed:', error.message);
      }
    }

    Example

    Delete with query parameters:

    // Hard delete
    await item.delete({ delete: true });

    // Delete with S3 cleanup
    await item.delete({ deleteS3: true, delete: true });

findItemByPath

  • findItemByPath(
        path: string,
        options?: { caseSensitive?: boolean },
    ): Promise<null | DriveItem | DriveItem[]>

    Find a drive item or directory by URL path within this drive

    Convenience method that wraps DriveItems.findByPath() for this drive instance. Resolves a URL path to a drive item by traversing the folder hierarchy. If the path resolves to a directory, returns an array of all items within that directory. If the path resolves to a file, returns a single DriveItem.

    Parameters

    • path: string

      URL path like '/documents/report.pdf' or '/folder1/subfolder/file.txt'

    • Optionaloptions: { caseSensitive?: boolean }

      Optional options for path resolution

      • OptionalcaseSensitive?: boolean

        Whether name matching is case-sensitive (default: true)

    Returns Promise<null | DriveItem | DriveItem[]>

    Promise resolving to DriveItem for files, DriveItem[] for directories, or null if not found

    Example

    Find a file by path:

    const drive = await client.drives.get({}, driveId);
    const item = await drive.findItemByPath('/documents/report.pdf');
    if (item) {
      console.log('Found file:', item.name);
    }

    Example

    Find a directory (returns array):

    const drive = await client.drives.get({}, driveId);
    const items = await drive.findItemByPath('/documents');
    if (Array.isArray(items)) {
      console.log(`Directory contains ${items.length} items`);
      items.forEach(item => console.log(item.name));
    }

    Example

    Case-insensitive matching:

    const item = await drive.findItemByPath('/Report.PDF', { caseSensitive: false });

    Throws

    When path resolution fails or API error occurs

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods