@or-sdk/files

OneReach Files API client — upload, download, list, and manage account files (SERVICE_KEY: eks-files-api).

Requires v3.0.0+ (EKS Files API). For the legacy Files API, pin @or-sdk/[email protected] or earlier.

When to use

• Store, list, download, or delete user/account files and folders on the OneReach platform.
• Need signed private download URLs or public file URLs.
• Need folder CRUD, search by key prefix, privacy changes, or TTL/expiry.

When not to use

• Browser cookie / login session handling — use @or-sdk/authorizer (or your app auth), not Files.
• Generic HTTP to other platform services — use the dedicated @or-sdk/* client for that service.
• IDW Web Skill iframe protocol — use @or-sdk/idw-skill.

Installation

npm install @or-sdk/files

Usage

Prefer a direct Files API URL when you have it — faster init and no discovery round-trip. Pass a token string or () => string getter.

import { Files } from '@or-sdk/files';

// Recommended — direct service URL
const files = new Files({
  token: () => myToken,
  filesApiUrl: 'https://files-api.svc.<env>.api.onereach.ai',
});

// Fallback — resolve Files API via discovery (extra network call)
const filesViaDiscovery = new Files({
  token: () => myToken,
  discoveryUrl: 'https://discovery.<env>.api.onereach.ai',
});

filesApiUrl and discoveryUrl are mutually exclusive (TypeScript enforced).

Object keys (critical)

Keys are S3-style object keys. The SDK does not normalize paths — values are sent as-is.

| Rule | Correct | Wrong | |------|---------|-------| | No leading / | uploads/report.pdf | /uploads/report.pdf | | Upload prefix ends with / | uploads/ | uploads (becomes uploadsreport.pdf) | | Root listing prefix | '' | '/' |

uploadFileV2 / getUploadUrlV2 build the key as `${prefix ?? ''}${fileName}` with no separator.

Common operations

Prefer V2/V3 methods. V1 upload helpers are deprecated.

// Upload
const url = await files.uploadFileV2(
  {
    fileContent: file, // File | Blob | Buffer
    fileName: file.name,
    contentType: file.type || 'application/octet-stream',
    prefix: 'uploads/',
    isPublic: false,
    onUploadProgress: (e) => { /* e.loaded / e.total */ },
  },
  { waitTillFileAddedInDb: true },
);

// List ('' = root)
const items = await files.getItemsList('uploads/', false);

// Signed or public download URL
const downloadUrl = await files.getDownloadUrl('uploads/report.pdf', false, 24 * 60 * 60 * 1000);

// Delete / folder
await files.deleteFile('uploads/report.pdf', false);
await files.createFolder('uploads/archive');
await files.deleteFolder('uploads/archive');

Method map

| Method | Purpose | |--------|---------| | uploadFileV2(...) | Upload file; returns URL. Prefer over uploadFile. | | uploadSystemFileV3(...) | Upload under system folder (does not count against user quota). | | getUploadUrlV2(...) | Signed upload URL only. | | getItemsList(prefix, isPublic?) | List files + folders under prefix. | | getFoldersList(prefix) | List folders only. | | getFile(key, isPublic, attributes?) | One file metadata + download URL. | | getFolder(key) / getFolderSize(key) | Folder metadata / size. | | getDownloadUrl(key, isPublic, expireMs?) | Private signed or public permanent URL. | | search(term, isPublic?) | Search by key prefix. | | renameFile / duplicateFile / deleteFile | Mutate files. | | createFolder / deleteFolder / createRootFolder | Folders. | | changePrivacy(key, newPrivacy, isPublic) | 'private' ↔ 'public'. | | addTtl / updateTtl / deleteTtl | Auto-expiry. |

FileItem: { key, contentType, size, isPublic, downloadUrl, parentFolder, createdAt, lastModified, updatedAt, ttl }.

Auth

• token is a OneReach bearer token (string or getter).
• In browser apps, supply the logged-in user token.
• In OneReach HTTP Flow / API steps, use the runtime authorization from the step config (e.g. step.config.authorization) — do not invent a separate token secret when that context already exists.

Privacy

• isPublic: false (default) — private; use getDownloadUrl for time-limited links.
• isPublic: true — permanent public URL.

More detail

Type signatures and parameter docs live in src/Files.ts and dist/types/. This README is the integration guide; types are the API contract.

Additional API reference

Methods below were missing from the package guide. Signatures and return types are taken directly from the exported source API.

Files

| Method | Returns | Purpose | |---|---|---| | getFolderSize(key: string, options?: RequestOptions) | Promise<number> | Get folder size | | createRootFolder(options?: RequestOptions) | Promise<void> | Create ROOT folder | | createFolder(folderName: string, options?: RequestOptions) | Promise<void> | Create new folder | | renameFile(key: string, newKey: string, isPublic: boolean, abortSignal?: AbortSignal) | Promise<void> | Rename exist file | | duplicateFile(key: string, newKey: string, isPublic: boolean) | Promise<void> | Duplicate file | | deleteFile(key: string, isPublic: boolean, abortSignal?: AbortSignal) | Promise<void> | Delete file | | deleteFolder(key: string, options?: RequestOptions) | Promise<void> | Delete folder | | deleteSystemFile(path: string, options?: RequestOptions) | Promise<void> | Delete system file | | addTtl(key: string, isPublic: boolean, expiresAt: DateTime) | Promise<void> | Set ttl for a specific file or folder | | updateTtl(key: string, isPublic: boolean, newExpiresAt: DateTime) | Promise<void> | Update ttl for a specific file or folder | | deleteTtl(key: string, isPublic: boolean) | Promise<void> | Delete ttl for a specific file or folder | | uploadFile({ name, prefix, fileModel, type, isPublic = false, rewriteMode, maxFileSize, knownLength, cacheControl = 'no-cache', ttl, waitTillFileAddedInDb, abortSignal, progress, }: UploadFilePropsLegacy, signal?: AbortSignal) | Promise<string> | Upload the file to File service | | getUploadUrl(params: UploadUrlPropsLegacy, isPublic?: boolean, ttl?: number, abortSignal?: AbortSignal) | Promise<UploadUrlResponse> | Get a link for uploading specific file, JUST FOR INNER USE | | uploadSystemFile(prefix: string, file: File, cacheControl = 'max-age=3600', abortSignal?: AbortSignal) | Promise<string> | Upload system file to S3 bucket, will not affect total size for user storage | | uploadSystemFileV2({ fileName, prefix, file, contentType, cacheControl = 'max-age=3600', ttl, knownLength, abortSignal, }: UploadSystemFileParamsLegacy) | Promise<string> | Upload system file to S3 bucket, will not affect total size for user storage |