@thetechfossil/upfiles 1.0.9 → 1.0.12

package/README.md

@@ -1,10 +1,10 @@
 # @thetechfossil/upfiles
 
-Lightweight JavaScript client and React component to upload files via a presigned S3 flow. Similar to UploadThing-like DX.
+Lightweight JavaScript client and React component to upload files via a presigned S3 flow with excellent developer experience.
 
 ## Documentation
 
-📚 **Full documentation available at:** [https://ttf-upfiles-docs.netlify.app/](https://ttf-upfiles-docs.netlify.app/)
+📚 **Full documentation available at:** [https://ktw-upfiles-docs.netlify.app/](https://ktw-upfiles-docs.netlify.app/)
 
 For detailed API reference, guides, examples, and more information, visit the documentation site.
 
@@ -12,6 +12,14 @@ For detailed API reference, guides, examples, and more information, visit the do
 - React `<Uploader />`: drag/drop, progress, single/multiple, accepts/types, size limits
 - React `<ProjectFilesWidget />`: list all files for a project (Plugin API), pick one, and optionally auto-save to your app
 
+## API Key Permissions (Scopes)
+
+API keys can have granular scopes. When using an API key with this SDK, ensure it has the necessary scopes:
+
+- **`read`**: access `getProjectFiles`, `getThumbnails`, `download`
+- **`write`**: access `upload`, `generateThumbnails`
+- **`delete`**: access file deletion
+
 ## Installation
 
 ```bash

package/dist/index.d.mts

@@ -26,6 +26,14 @@ type Thumbnail = {
     sizeType?: string;
     createdAt?: string;
 };
+type Folder = {
+    id: string;
+    name: string;
+    parentId: string | null;
+    projectId: string;
+    createdAt: string;
+    updatedAt: string;
+};
 type FileListItem = {
     key: string;
     originalName: string;
@@ -37,7 +45,7 @@ type FileListItem = {
 /**
  * Upfiles Client - JavaScript client for Upfiles Plugin API
  *
- * 📚 Full documentation: https://ttf-upfiles-docs.netlify.app/
+ * 📚 Full documentation: https://ktw-upfiles-docs.netlify.app/
  *
  * @example
  * ```ts
@@ -57,12 +65,13 @@ type UpfilesClientOptions = {
     apiKeyHeader?: 'authorization' | 'x-api-key' | 'x-up-api-key';
     thumbnailsPath?: string;
     completionPath?: string;
+    foldersPath?: string;
     callCompletionEndpoint?: boolean;
 };
 /**
  * UpfilesClient - Main client class for interacting with Upfiles Plugin API
  *
- * 📚 Documentation: https://ttf-upfiles-docs.netlify.app/
+ * 📚 Documentation: https://ktw-upfiles-docs.netlify.app/
  *
  * @example
  * ```ts
@@ -84,6 +93,7 @@ declare class UpfilesClient {
     private apiKeyHeader;
     private thumbnailsPath;
     private completionPath;
+    private foldersPath;
     private callCompletionEndpoint;
     constructor(opts: UpfilesClientOptions);
     getPresignedUrl(params: {
@@ -106,7 +116,23 @@ declare class UpfilesClient {
         size: number;
         contentType: string;
         projectId?: string;
-    }): Promise<void>;
+    }): Promise<{
+        success: boolean;
+        file: {
+            id: string;
+            key: string;
+            originalName: string;
+            size: number;
+            contentType: string;
+            url: string;
+            uploadedAt: string;
+        };
+        thumbnails?: Thumbnail[];
+        masterWebp?: {
+            key: string;
+            url: string;
+        };
+    }>;
     getThumbnails(fileKey: string): Promise<Thumbnail[]>;
     generateThumbnails(fileKey: string): Promise<{
         masterWebp?: {
@@ -115,9 +141,15 @@ declare class UpfilesClient {
         };
         thumbnails: Thumbnail[];
     }>;
+    getFolders(parentId?: string): Promise<Folder[]>;
+    createFolder(name: string, parentId?: string): Promise<Folder>;
     getProjectFiles(params?: {
         folderPath?: string;
-    }): Promise<FileListItem[]>;
+    }): Promise<{
+        files: FileListItem[];
+        updatedAt: string | null;
+    }>;
+    getEventsUrl(projectId?: string): string;
 }
 
 type UploaderFile = {
@@ -183,6 +215,7 @@ type ProjectFilesWidgetProps = {
     onDelete?: (key: string) => Promise<void>;
     deleteUrl?: string;
     showDelete?: boolean;
+    refreshInterval?: number;
 };
 declare const ProjectFilesWidget: React.FC<ProjectFilesWidgetProps>;
 
@@ -237,7 +270,10 @@ declare function connectUsingApiKey(opts: {
     client: UpfilesClient;
 };
 
-declare function fetchProjectFiles(clientOptions: UpfilesClientOptions, folderPath?: string): Promise<FileListItem[]>;
+declare function fetchProjectFiles(clientOptions: UpfilesClientOptions, folderPath?: string): Promise<{
+    files: FileListItem[];
+    updatedAt: string | null;
+}>;
 declare function fetchFileThumbnails(clientOptions: UpfilesClientOptions, fileKey: string): Promise<Thumbnail[]>;
 type ImageWithThumbs = FileListItem & {
     thumbnails?: Thumbnail[];
@@ -245,7 +281,10 @@ type ImageWithThumbs = FileListItem & {
 declare function fetchProjectImagesWithThumbs(clientOptions: UpfilesClientOptions, opts?: {
     folderPath?: string;
     limitConcurrent?: number;
-}): Promise<ImageWithThumbs[]>;
+}): Promise<{
+    items: ImageWithThumbs[];
+    updatedAt: string | null;
+}>;
 
 type ImageManagerProps = {
     open: boolean;
@@ -270,6 +309,13 @@ type ImageManagerProps = {
             size: number;
             sizeType?: string;
         }[];
+        selectedThumbnail?: {
+            id: string;
+            key: string;
+            url: string;
+            size: number;
+            sizeType?: string;
+        };
     }) => void;
     onDelete?: (key: string) => Promise<void>;
     deleteUrl?: string;
@@ -279,7 +325,8 @@ type ImageManagerProps = {
     maxFiles?: number;
     mode?: 'full' | 'browse' | 'upload';
     showDelete?: boolean;
+    refreshInterval?: number;
 };
 declare function ImageManager(props: ImageManagerProps): react_jsx_runtime.JSX.Element;
 
-export { type ConnectOptions, ConnectProjectDialog, type ConnectProjectDialogProps, type FileListItem, ImageManager, type ImageManagerProps, type ImageWithThumbs, type PresignResponse, type Project, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps, addApiKeyManually, connectProject, connectUsingApiKey, createClientWithKey, createProject, fetchFileThumbnails, fetchProjectFiles, fetchProjectImagesWithThumbs, listProjects };
+export { type ConnectOptions, ConnectProjectDialog, type ConnectProjectDialogProps, type FileListItem, type Folder, ImageManager, type ImageManagerProps, type ImageWithThumbs, type PresignResponse, type Project, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps, addApiKeyManually, connectProject, connectUsingApiKey, createClientWithKey, createProject, fetchFileThumbnails, fetchProjectFiles, fetchProjectImagesWithThumbs, listProjects };

package/dist/index.d.ts

@@ -26,6 +26,14 @@ type Thumbnail = {
     sizeType?: string;
     createdAt?: string;
 };
+type Folder = {
+    id: string;
+    name: string;
+    parentId: string | null;
+    projectId: string;
+    createdAt: string;
+    updatedAt: string;
+};
 type FileListItem = {
     key: string;
     originalName: string;
@@ -37,7 +45,7 @@ type FileListItem = {
 /**
  * Upfiles Client - JavaScript client for Upfiles Plugin API
  *
- * 📚 Full documentation: https://ttf-upfiles-docs.netlify.app/
+ * 📚 Full documentation: https://ktw-upfiles-docs.netlify.app/
  *
  * @example
  * ```ts
@@ -57,12 +65,13 @@ type UpfilesClientOptions = {
     apiKeyHeader?: 'authorization' | 'x-api-key' | 'x-up-api-key';
     thumbnailsPath?: string;
     completionPath?: string;
+    foldersPath?: string;
     callCompletionEndpoint?: boolean;
 };
 /**
  * UpfilesClient - Main client class for interacting with Upfiles Plugin API
  *
- * 📚 Documentation: https://ttf-upfiles-docs.netlify.app/
+ * 📚 Documentation: https://ktw-upfiles-docs.netlify.app/
  *
  * @example
  * ```ts
@@ -84,6 +93,7 @@ declare class UpfilesClient {
     private apiKeyHeader;
     private thumbnailsPath;
     private completionPath;
+    private foldersPath;
     private callCompletionEndpoint;
     constructor(opts: UpfilesClientOptions);
     getPresignedUrl(params: {
@@ -106,7 +116,23 @@ declare class UpfilesClient {
         size: number;
         contentType: string;
         projectId?: string;
-    }): Promise<void>;
+    }): Promise<{
+        success: boolean;
+        file: {
+            id: string;
+            key: string;
+            originalName: string;
+            size: number;
+            contentType: string;
+            url: string;
+            uploadedAt: string;
+        };
+        thumbnails?: Thumbnail[];
+        masterWebp?: {
+            key: string;
+            url: string;
+        };
+    }>;
     getThumbnails(fileKey: string): Promise<Thumbnail[]>;
     generateThumbnails(fileKey: string): Promise<{
         masterWebp?: {
@@ -115,9 +141,15 @@ declare class UpfilesClient {
         };
         thumbnails: Thumbnail[];
     }>;
+    getFolders(parentId?: string): Promise<Folder[]>;
+    createFolder(name: string, parentId?: string): Promise<Folder>;
     getProjectFiles(params?: {
         folderPath?: string;
-    }): Promise<FileListItem[]>;
+    }): Promise<{
+        files: FileListItem[];
+        updatedAt: string | null;
+    }>;
+    getEventsUrl(projectId?: string): string;
 }
 
 type UploaderFile = {
@@ -183,6 +215,7 @@ type ProjectFilesWidgetProps = {
     onDelete?: (key: string) => Promise<void>;
     deleteUrl?: string;
     showDelete?: boolean;
+    refreshInterval?: number;
 };
 declare const ProjectFilesWidget: React.FC<ProjectFilesWidgetProps>;
 
@@ -237,7 +270,10 @@ declare function connectUsingApiKey(opts: {
     client: UpfilesClient;
 };
 
-declare function fetchProjectFiles(clientOptions: UpfilesClientOptions, folderPath?: string): Promise<FileListItem[]>;
+declare function fetchProjectFiles(clientOptions: UpfilesClientOptions, folderPath?: string): Promise<{
+    files: FileListItem[];
+    updatedAt: string | null;
+}>;
 declare function fetchFileThumbnails(clientOptions: UpfilesClientOptions, fileKey: string): Promise<Thumbnail[]>;
 type ImageWithThumbs = FileListItem & {
     thumbnails?: Thumbnail[];
@@ -245,7 +281,10 @@ type ImageWithThumbs = FileListItem & {
 declare function fetchProjectImagesWithThumbs(clientOptions: UpfilesClientOptions, opts?: {
     folderPath?: string;
     limitConcurrent?: number;
-}): Promise<ImageWithThumbs[]>;
+}): Promise<{
+    items: ImageWithThumbs[];
+    updatedAt: string | null;
+}>;
 
 type ImageManagerProps = {
     open: boolean;
@@ -270,6 +309,13 @@ type ImageManagerProps = {
             size: number;
             sizeType?: string;
         }[];
+        selectedThumbnail?: {
+            id: string;
+            key: string;
+            url: string;
+            size: number;
+            sizeType?: string;
+        };
     }) => void;
     onDelete?: (key: string) => Promise<void>;
     deleteUrl?: string;
@@ -279,7 +325,8 @@ type ImageManagerProps = {
     maxFiles?: number;
     mode?: 'full' | 'browse' | 'upload';
     showDelete?: boolean;
+    refreshInterval?: number;
 };
 declare function ImageManager(props: ImageManagerProps): react_jsx_runtime.JSX.Element;
 
-export { type ConnectOptions, ConnectProjectDialog, type ConnectProjectDialogProps, type FileListItem, ImageManager, type ImageManagerProps, type ImageWithThumbs, type PresignResponse, type Project, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps, addApiKeyManually, connectProject, connectUsingApiKey, createClientWithKey, createProject, fetchFileThumbnails, fetchProjectFiles, fetchProjectImagesWithThumbs, listProjects };
+export { type ConnectOptions, ConnectProjectDialog, type ConnectProjectDialogProps, type FileListItem, type Folder, ImageManager, type ImageManagerProps, type ImageWithThumbs, type PresignResponse, type Project, ProjectFilesWidget, type ProjectFilesWidgetProps, type Thumbnail, UpfilesClient, type UpfilesClientOptions, type UploadedFileResult, Uploader, type UploaderFile, type UploaderProps, addApiKeyManually, connectProject, connectUsingApiKey, createClientWithKey, createProject, fetchFileThumbnails, fetchProjectFiles, fetchProjectImagesWithThumbs, listProjects };