@stackone/files-sdk

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 - JavaScript runtime
• TypeScript - Typed JavaScript
• Rollup - Module bundler
• Vitest - Testing framework
• Biome - 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.

Installation

# install dependencies
$ npm install

This command will also install husky to ensure that all the commits follow the Conventional Commits specification.

Available commands

# clean build output
$ npm run clean

# build package
$ npm run build

# run tests
$ npm run test

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

# run linter
$ npm run lint

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

API Documentation

Types

StorageSite

Represents a storage site with the following properties:

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

StorageFile

Represents a file in the storage with the following properties:

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:

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.

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 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.