Creates a new Drive Items API client instance
Initializes the drive items client with the appropriate endpoint URI and model class for handling drive item operations.
The constructor sets up the API endpoint to /drive/:driveId/item (or ${uri}/drive/:driveId/item if a base URI is provided),
which corresponds to the Mosaia API's drive items endpoint.
Base URI path. Typically /drive/:driveId where :driveId is the drive ID.
If not provided, defaults to /drive/item.
Get entities with optional filtering and pagination
This method retrieves entities from the API. When called without an ID, it returns a list of entities with optional filtering and pagination. When called with an ID, it returns a specific entity.
Optional query parameters for filtering and pagination
Query parameters interface for API requests
Used to define common query parameters that can be passed to API endpoints for filtering, sorting, and pagination.
Additional custom query parameters
Optionalq?: stringSearch term for text-based filtering
Optionallimit?: numberMaximum number of items to return
Optionaloffset?: numberNumber of items to skip (for offset-based pagination)
Optionaltags?: string[]Array of tags to filter by
Optionalactive?: booleanFilter by active status
Optionalexternal_id?: stringFilter by external ID
Optional specific entity ID to retrieve
Promise resolving to:
- BatchAPIResponse
Get multiple entities with filtering:
const result = await collection.get({
limit: 10,
offset: 0,
q: 'search term',
active: true,
tags: ['tag1', 'tag2']
});
console.log('Items:', result.data);
console.log('Total:', result.paging?.total);
Get entities with optional filtering and pagination
This method retrieves entities from the API. When called without an ID, it returns a list of entities with optional filtering and pagination. When called with an ID, it returns a specific entity.
Optionalparams: QueryParamsOptional query parameters for filtering and pagination
Query parameters interface for API requests
Used to define common query parameters that can be passed to API endpoints for filtering, sorting, and pagination.
Additional custom query parameters
Optionalq?: stringSearch term for text-based filtering
Optionallimit?: numberMaximum number of items to return
Optionaloffset?: numberNumber of items to skip (for offset-based pagination)
Optionaltags?: string[]Array of tags to filter by
Optionalactive?: booleanFilter by active status
Optionalexternal_id?: stringFilter by external ID
Promise resolving to:
- BatchAPIResponse
Get multiple entities with filtering:
const result = await collection.get({
limit: 10,
offset: 0,
q: 'search term',
active: true,
tags: ['tag1', 'tag2']
});
console.log('Items:', result.data);
console.log('Total:', result.paging?.total);
Create a new entity
This method creates a new entity in the system. The entity ID will be automatically generated by the server. The method returns a new model instance initialized with the created entity's data.
Entity data for the new entity (without ID)
Promise resolving to a new model instance
Create a new user:
const newUser = await users.create({
email: 'user@example.com',
firstName: 'John',
lastName: 'Doe',
active: true
});
console.log('Created user:', newUser.id);
Update an existing entity
This method updates an existing entity in the system. Only the fields provided in the update data will be updated.
The entity ID to update
Partial entity data for the update (only provided fields will be updated)
Optionalparams: QueryParamsOptional query parameters for the request
Promise resolving to the updated model instance
Delete an entity
This method permanently deletes an entity from the system. This action cannot be undone.
The entity ID to delete
Optionalparams: QueryParamsOptional query parameters object. Can include:
force: Force deletion even if entity has dependencies (boolean)Promise that resolves when deletion is successful
Upload files to the drive using presigned URLs
Uploads one or more files to the drive using presigned URLs for direct S3 uploads. Each file gets its own UploadJob for independent tracking. This method supports batch file uploads and directory uploads with structure preservation. The backend returns presigned URLs that you can use to upload files directly to S3.
Array of File objects to upload (required for file uploads)
Optionaloptions: {Optional upload options
Optionalpath?: stringBase path where files should be uploaded (defaults to '/')
OptionalrelativePaths?: string | string[]Array of relative paths for directory structure preservation
OptionalpreserveStructure?: booleanBoolean flag to enable/disable structure preservation (default: true if relativePaths provided)
OptionalonProgress?: (uploadJob: UploadJob, progress: number) => voidOptional progress callback that receives the UploadJob and progress (0-100) for each file
Promise resolving to upload information with UploadJob instances
// Single file upload
const fileInput = document.getElementById('fileInput') as HTMLInputElement;
const file = fileInput.files[0];
const result = await items.uploadFiles([file], {
path: '/documents',
onProgress: (uploadJob, progress) => {
console.log(`${uploadJob.filename}: ${progress}%`);
}
});
// Files are automatically uploaded to S3
console.log('Upload jobs:', result.uploadJobs);
// Batch file upload with directory structure
const files = Array.from(fileInput.files);
const result = await items.uploadFiles(files, {
path: '/uploads',
relativePaths: ['folder1/file1.txt', 'folder2/file2.txt'],
preserveStructure: true
});
// Each file can be tracked independently
for (let i = 0; i < result.uploadJobs.length; i++) {
const uploadJob = result.uploadJobs[i];
const file = files[i];
console.log(`Uploading ${uploadJob.filename}...`);
try {
await uploadJob.upload(file, {
onProgress: (progress) => {
console.log(`${uploadJob.filename}: ${progress}%`);
}
});
} catch (error) {
console.error(`Failed to upload ${uploadJob.filename}:`, error);
await uploadJob.markFailed(error.message);
}
}
Find a drive item or directory by URL path
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.
URL path like '/documents/report.pdf' or '/folder1/subfolder/file.txt'
Optionaloptions: { caseSensitive?: boolean }Optional options for path resolution
OptionalcaseSensitive?: booleanWhether filename matching is case-sensitive (default: true)
Promise resolving to DriveItem for files, DriveItem[] for directories, or null if not found
Find a file by path:
const item = await items.findByPath('/documents/report.pdf');
if (item) {
console.log('Found file:', item.filename);
}
Find a directory (returns array):
const items = await items.findByPath('/documents');
if (Array.isArray(items)) {
console.log(`Directory contains ${items.length} items`);
items.forEach(item => console.log(item.filename));
}
Drive Items API client for the Mosaia SDK
Provides CRUD operations for managing drive items (files and documents) in the Mosaia platform. Drive items are files and documents stored within drives.
This class inherits from BaseCollection and provides the following functionality:
Example