npm package: @sthg-sdk/filesystem.api
Description: Filesystem API client for STHG Tiangong SDK
Latest version: 1.2.7

# @sthg-sdk/filesystem.api

Filesystem API client for STHG Tiangong SDK - provides a comprehensive interface for managing spaces, projects, folders, and resources in the filesystem service.

## Installation

```bash
npm install @sthg-sdk/filesystem.api
```

## Usage

```typescript
import { HttpClient } from '@sthg-sdk/shared.client';
import * as FilesystemAPI from '@sthg-sdk/filesystem.api';

// Initialize the HTTP client
const client = new HttpClient({
  baseUrl: 'https://your-api-endpoint.com',
  defaultHeaders: {
    'Authorization': 'Bearer your-auth-token',
    'Content-Type': 'application/json'
  }
});

// Create a space
const space = await FilesystemAPI.createSpace(client, {
  enName: 'my-workspace',
  displayName: 'My Workspace',
  description: 'A workspace for my projects'
});

// Create a project in the space
const project = await FilesystemAPI.createProject(client, space.data.rid, {
  displayName: 'My Project',
  description: 'A sample project'
});

// Create a folder in the project
const folder = await FilesystemAPI.createFolder(client, project.data.rid, {
  displayName: 'Data',
  description: 'Data storage folder'
});

// Upload a file
const formData = new FormData();
formData.append('file', fileBlob);
formData.append('projectRid', project.data.rid);
formData.append('spaceRid', space.data.rid);
formData.append('parentFolderRid', folder.data.rid);

const uploadResult = await FilesystemAPI.uploadFile(client, formData);
```

## API Methods

### Spaces
- `listSpaces(client, params?)` - List all spaces with pagination
- `createSpace(client, request)` - Create a new space
- `getSpace(client, spaceRid)` - Get space details
- `updateSpace(client, spaceRid, request)` - Update space information
- `deleteSpace(client, spaceRid)` - Delete a space
- `getSpaceConfig(client, spaceRid)` - Get space configuration
- `getSpaceStatistics(client, spaceRid)` - Get space statistics
- `getAllFolderAndResource(client, spaceRid, params?)` - Get all visible folders and resources

### Projects
- `listProjects(client, spaceRid, params?)` - List projects in a space
- `createProject(client, spaceRid, request)` - Create a new project
- `getProject(client, projectRid)` - Get project details
- `updateProject(client, projectRid, request)` - Update project information
- `deleteProject(client, projectRid)` - Permanently delete a project
- `moveProjectToTrash(client, projectRid)` - Move project to trash
- `restoreProjectFromTrash(client, projectRid)` - Restore project from trash
- `getProjectTree(client, projectRid)` - Get project tree structure
- `getProjectStatistics(client, projectRid)` - Get project statistics
- `getProjectContent(client, projectRid, params?)` - Get project content
- `listProjectResources(client, projectRid, params?)` - List project resources

### Folders
- `listFolders(client, projectRid, params?)` - List folders in a project
- `createFolder(client, projectRid, request)` - Create a new folder
- `getFolder(client, folderRid)` - Get folder details
- `updateFolder(client, folderRid, request)` - Update folder information
- `deleteFolder(client, folderRid)` - Permanently delete a folder
- `moveFolder(client, folderRid, request)` - Move folder to new location
- `moveFolderToTrash(client, folderRid, projectRid)` - Move folder to trash
- `restoreFolderFromTrash(client, folderRid)` - Restore folder from trash
- `getFolderTree(client, folderRid)` - Get folder tree structure
- `getFolderStatistics(client, folderRid)` - Get folder statistics
- `getFolderContent(client, folderRid, params?)` - Get folder content

### Resources
- `createResource(client, request, params?)` - Create a new resource
- `getResource(client, resourceRid)` - Get resource details
- `updateResource(client, resourceRid, request)` - Update resource information
- `deleteResource(client, resourceRid)` - Permanently delete a resource
- `moveResource(client, resourceRid, request)` - Move resource to new location
- `batchMoveResources(client, request)` - Move multiple resources
- `copyResource(client, resourceRid, request)` - Copy resource to new location
- `addResourceMarkings(client, resourceRid, request)` - Add security markings
- `removeResourceMarkings(client, resourceRid, request)` - Remove security markings
- `moveResourceToTrash(client, resourceRid, projectRid)` - Move resource to trash
- `restoreResourceFromTrash(client, resourceRid)` - Restore resource from trash
- `getProjectResourceStatistics(client, projectRid)` - Get project resource statistics

### File Upload/Download
- `uploadFile(client, formData)` - Upload a single file
- `batchUploadFiles(client, formData)` - Upload multiple files
- `uploadDocumentation(client, formData)` - Upload documentation
- `getDownloadUrl(client, resourceRid, spaceRid, expiresInHours?)` - Get download URL
- `deleteFile(client, resourceRid)` - Delete file from storage

### Trash Management
- `getTrashItems(client, params?)` - List items in trash
- `getTrashFolders(client, params?)` - List folders in trash

### Utilities
- `generateRid(client, resourceType, namespace?, scope?)` - Generate unique RID
- `getEntityInfo(client, rid)` - Get entity information by RID
- `getTreeStructure(client, rid, params?)` - Get tree structure
- `healthCheck(client)` - Check service health

## Types

All TypeScript types are re-exported from `@sthg-sdk/tiangong.core` for convenience:

```typescript
import type {
  Space,
  Project,
  Folder,
  Resource,
  CreateSpaceRequest,
  CreateProjectRequest,
  // ... and many more
} from '@sthg-sdk/filesystem.api';
```

## Error Handling

The client returns responses wrapped in `ApiResponseUnion` which includes both success and error cases:

```typescript
const result = await client.getSpace(spaceRid);

if (result.success) {
  console.log('Space:', result.data);
} else {
  console.error('Error:', result.error);
}
```

## License

Apache-2.0