npm package: @stackone/files-sdk
Description: Files SDK to ease the integration with file storage providers
Author: StackOne
Latest version: 0.31.1

# Files SDK

## Description

The Files SDK eases the integration with file storage providers

The teck stack used inside in this package is composed by:

- [Node.js](https://nodejs.org) - JavaScript runtime
- [TypeScript](https://www.typescriptlang.org/) - Typed JavaScript
- [Rollup](https://rollupjs.org/) - Module bundler
- [Vitest](https://vitest.dev) - Testing framework
- [Biome](https://biomejs.dev) - Linting and formatting

## Requirements

Node.js 20+ is required to run this project. The recommended way to install and manage Node.js versions is using
[Volta](https://volta.sh/).

## Installation

```bash
# install dependencies
$ npm install
```

This command will also install husky to ensure that all the commits follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.

## Available commands

```bash
# clean build output
$ npm run clean
```

```bash
# build package
$ npm run build
```

```bash
# run tests
$ npm run test
```

```bash
# run tests with coverage report
$ npm run test:coverage
```

```bash
# run linter
$ npm run lint
```

```bash
# run linter and try to fix any error
$ npm run lint:fix
```

## API Documentation

### Types

#### `StorageSite`

Represents a storage site with the following properties:

```typescript
interface StorageSite {
    id: string;
    displayName: string;
    description?: string;
    url: string;
    createdAt: string;
}
```

#### `StorageFile`

Represents a file in the storage with the following properties:

```typescript
interface StorageFile {
    id: string;
    name: string;
    description?: string;
    url?: string;
    size?: number;
    path?: string;
    ownerId?: string;
    createdAt?: string;
    updatedAt?: string;
}
```

#### `IFileStorageClient`

The interface that all storage provider clients must implement:

```typescript
interface IFileStorageClient {
    initialize(config: unknown): Promise<void>;
    login(scopes?: string[]): Promise<string>;
    getAccessToken(scopes?: string[]): Promise<string>;
    listSites(): Promise<StorageSite[]>;
    openNativeFilePicker(options: {
        baseUrl: string;
        siteIdentifier?: string;
        rootElementId?: string;
    }): Promise<void>;
    closeNativeFilePicker(): Promise<void>;
}
```

### Classes

#### `FileStorageClientFactory`

A factory class that creates storage client instances based on the provider type.

```typescript
import { FileStorageClientFactory, StorageType } from '@stackone/files-sdk';

const factory = new FileStorageClientFactory();
const client = factory.build('sharepoint');

await client.initialize({
    clientId: 'your-client-id',
    redirectUri: 'your-redirect-uri',
    tenantId: 'your-tenant-id'
});

// Login to get an access token
const token = await client.login(['your-scopes']);

// List available sites
const sites = await client.listSites();

// Open the native file picker
await client.openNativeFilePicker({
    baseUrl: 'your-sharepoint-url',
    siteIdentifier: 'optional-site-id',
    rootElementId: 'your-container-id'
});

// Close the native file picker
await client.closeNativeFilePicker();
```

## Convential Commits

This project uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to ensure that all the commits
follow a standard. This is done to ensure that the changelog can be automatically generated and to allow the automatic
versioning of the package.