@epilot/file-client 1.16.1 → 1.18.0

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "File API",
-    "version": "1.0.0",
+    "version": "1.3.0",
     "description": "Upload and manage epilot Files\n\n## Changelog\n<a href=\"changelog\">View API Changelog</a>\n"
   },
   "tags": [
@@ -33,7 +33,11 @@
     },
     {
       "name": "File Folders",
-      "description": "Folder management for organizing files within entities"
+      "description": "Folder management for organizing files within entities (deprecated - use File Collections)"
+    },
+    {
+      "name": "File Collections",
+      "description": "Collection management for organizing files within entities"
     }
   ],
   "x-tagGroups": [
@@ -44,6 +48,7 @@
         "Preview",
         "Public Links",
         "Session",
+        "File Collections",
         "File Folders",
         "Deprecated"
       ]
@@ -1098,7 +1103,8 @@
       "get": {
         "operationId": "getFileFolders",
         "summary": "getFileFolders",
-        "description": "Gets a list of folders that exist for an entity",
+        "deprecated": true,
+        "description": "Gets a list of folders that exist for an entity. Deprecated - use getFileCollections instead.",
         "tags": [
           "File Folders"
         ],
@@ -1143,7 +1149,8 @@
       "post": {
         "operationId": "createFileFolder",
         "summary": "createFileFolder",
-        "description": "Creates a new file folder for the specified entity",
+        "deprecated": true,
+        "description": "Creates a new file folder for the specified entity. Deprecated - use createFileCollection instead.",
         "tags": [
           "File Folders"
         ],
@@ -1183,7 +1190,8 @@
       "put": {
         "operationId": "updateFileFolder",
         "summary": "updateFileFolder",
-        "description": "Updates a specific file folder by slug",
+        "deprecated": true,
+        "description": "Updates a specific file folder by slug. Deprecated - use updateFileCollection instead.",
         "tags": [
           "File Folders"
         ],
@@ -1231,7 +1239,8 @@
       "delete": {
         "operationId": "deleteFileFolder",
         "summary": "deleteFileFolder",
-        "description": "Deletes a specific file folder by slug",
+        "deprecated": true,
+        "description": "Deletes a specific file folder by slug. Deprecated - use deleteFileCollection instead.",
         "tags": [
           "File Folders"
         ],
@@ -1264,7 +1273,8 @@
       "get": {
         "operationId": "getFilesInFolder",
         "summary": "getFilesInFolder",
-        "description": "Gets all files within a specific folder for an entity",
+        "deprecated": true,
+        "description": "Gets all files within a specific folder for an entity. Deprecated - use getFilesInCollection instead.",
         "tags": [
           "File Folders"
         ],
@@ -1331,6 +1341,319 @@
           }
         }
       }
+    },
+    "/v1/folders/{schemaSlug}": {
+      "get": {
+        "operationId": "getGlobalFileFolders",
+        "summary": "getGlobalFileFolders",
+        "deprecated": true,
+        "description": "Gets all global file folders for a specific schema. Deprecated - use getGlobalFileCollections instead.",
+        "tags": [
+          "File Folders"
+        ],
+        "parameters": [
+          {
+            "name": "schemaSlug",
+            "in": "path",
+            "required": true,
+            "description": "The schema slug (e.g., order, opportunity)",
+            "schema": {
+              "type": "string",
+              "example": "order"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of global folders for the schema",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/FileFolderItem"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/entity/{id}/collections": {
+      "get": {
+        "operationId": "getFileCollections",
+        "summary": "getFileCollections",
+        "description": "Gets a list of collections that exist for an entity",
+        "tags": [
+          "File Collections"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/EntityIdPathParam"
+          },
+          {
+            "name": "parents",
+            "in": "query",
+            "description": "Optional array of parent collection slugs to filter by",
+            "required": false,
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "style": "form",
+            "explode": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of collections for the entity",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/FileCollectionItem"
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFoundError"
+          }
+        }
+      },
+      "post": {
+        "operationId": "createFileCollection",
+        "summary": "createFileCollection",
+        "description": "Creates a new file collection for the specified entity",
+        "tags": [
+          "File Collections"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/EntityIdPathParam"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FileCollectionCreateRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "File collection created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/FileCollectionItem"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFoundError"
+          }
+        }
+      }
+    },
+    "/v1/entity/{id}/collections/{collectionSlug}": {
+      "put": {
+        "operationId": "updateFileCollection",
+        "summary": "updateFileCollection",
+        "description": "Updates a specific file collection by slug",
+        "tags": [
+          "File Collections"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/EntityIdPathParam"
+          },
+          {
+            "name": "collectionSlug",
+            "in": "path",
+            "required": true,
+            "description": "The slug identifier for the collection",
+            "schema": {
+              "type": "string",
+              "example": "documents"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FileCollectionAttributes"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "File collection updated successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/FileCollectionItem"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFoundError"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteFileCollection",
+        "summary": "deleteFileCollection",
+        "description": "Deletes a specific file collection by slug",
+        "tags": [
+          "File Collections"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/EntityIdPathParam"
+          },
+          {
+            "name": "collectionSlug",
+            "in": "path",
+            "required": true,
+            "description": "The slug identifier for the collection",
+            "schema": {
+              "type": "string",
+              "example": "documents"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "File collection deleted successfully"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFoundError"
+          }
+        }
+      }
+    },
+    "/v1/entity/{id}/collections/{collectionSlug}/files": {
+      "get": {
+        "operationId": "getFilesInCollection",
+        "summary": "getFilesInCollection",
+        "description": "Gets all files within a specific collection for an entity",
+        "tags": [
+          "File Collections"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/EntityIdPathParam"
+          },
+          {
+            "name": "collectionSlug",
+            "in": "path",
+            "required": true,
+            "description": "The slug identifier for the collection",
+            "schema": {
+              "type": "string",
+              "example": "documents"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of files in the collection",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/FileEntity"
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "User must have permission to view this entity to access its files",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string",
+                      "example": "User must have permission to view this entity to access its files"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Entity or collection not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string",
+                      "example": "Entity not found"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/collections/{schemaSlug}": {
+      "get": {
+        "operationId": "getGlobalFileCollections",
+        "summary": "getGlobalFileCollections",
+        "description": "Gets all global file collections for a specific schema",
+        "tags": [
+          "File Collections"
+        ],
+        "parameters": [
+          {
+            "name": "schemaSlug",
+            "in": "path",
+            "required": true,
+            "description": "The schema slug (e.g., order, opportunity)",
+            "schema": {
+              "type": "string",
+              "example": "order"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of global collections for the schema",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/FileCollectionItem"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -1365,7 +1688,18 @@
         "example": "01F130Q52Q6MWSNS8N2AVXV4JN"
       },
       "FileEntityId": {
-        "type": "string",
+        "oneOf": [
+          {
+            "type": "string",
+            "maxLength": 0,
+            "description": "Empty string (used when file ID not yet assigned)"
+          },
+          {
+            "type": "string",
+            "format": "uuid",
+            "description": "Valid UUID v4"
+          }
+        ],
         "example": "ef7d985c-2385-44f4-9c71-ae06a52264f8"
       },
       "FileAttributes": {
@@ -1907,8 +2241,8 @@
         "properties": {
           "slug": {
             "type": "string",
-            "description": "Full slug for the folder",
-            "example": "_system_files_collection_entity-123:documents"
+            "description": "Full slug for the folder. Format depends on collection type:\n- User collection: `_system_files_collection_{entity_uuid}_{user_id}:{collection_name}`\n  Example: `_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234:documents`\n- Global collection: `_system_files_collection_schema_{schema_slug}:{collection_name}`\n  Example: `_system_files_collection_schema_opportunity:templates`\n",
+            "example": "_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234:documents"
           },
           "name": {
             "type": "string",
@@ -1920,12 +2254,12 @@
           },
           "parents": {
             "type": "array",
-            "description": "Array of parent folder slugs, empty array if top-level folder",
+            "description": "Array of parent folder slugs, empty array if top-level folder. Format depends on collection type:\n- User collection: `_system_files_collection_{entity_uuid}_{user_id}`\n  Example: `[\"_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234\"]`\n- Global collection: `_system_files_collection_schema_{schema_slug}`\n  Example: `[\"_system_files_collection_schema_opportunity\"]`\n",
             "items": {
               "type": "string"
             },
             "example": [
-              "_system_files_collection_entity-123"
+              "_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234"
             ]
           },
           "starred": {
@@ -1933,6 +2267,11 @@
             "description": "Whether the folder is starred / favorited",
             "example": false
           },
+          "order": {
+            "type": "number",
+            "description": "Display order for the folder",
+            "example": 0
+          },
           "created_at": {
             "type": "string",
             "format": "date-time",
@@ -2000,6 +2339,100 @@
             ]
           }
         ]
+      },
+      "FileCollectionId": {
+        "description": "Generated uuid for a file collection",
+        "type": "string",
+        "format": "uuid"
+      },
+      "FileCollectionItem": {
+        "description": "A file collection with identifiers and timestamps",
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string",
+            "description": "Full slug for the collection. Format depends on collection type:\n- User collection: `_system_files_collection_{entity_uuid}_{user_id}:{collection_name}`\n  Example: `_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234:documents`\n- Global collection: `_system_files_collection_schema_{schema_slug}:{collection_name}`\n  Example: `_system_files_collection_schema_opportunity:templates`\n",
+            "example": "_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234:documents"
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name of the collection",
+            "example": "Documents"
+          },
+          "id": {
+            "$ref": "#/components/schemas/FileCollectionId"
+          },
+          "parents": {
+            "type": "array",
+            "description": "Array of parent collection slugs, empty array if top-level collection. Format depends on collection type:\n- User collection: `_system_files_collection_{entity_uuid}_{user_id}`\n  Example: `[\"_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234\"]`\n- Global collection: `_system_files_collection_schema_{schema_slug}`\n  Example: `[\"_system_files_collection_schema_opportunity\"]`\n",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234"
+            ]
+          },
+          "starred": {
+            "type": "boolean",
+            "description": "Whether the collection is starred / favorited",
+            "example": false
+          },
+          "order": {
+            "type": "number",
+            "description": "Display order for the collection",
+            "example": 0
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the collection was created",
+            "example": "2024-01-01T12:00:00Z"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the collection was last updated",
+            "example": "2024-01-02T12:00:00Z"
+          }
+        },
+        "required": [
+          "name"
+        ]
+      },
+      "FileCollectionAttributes": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Name of the collection"
+          },
+          "parents": {
+            "type": "array",
+            "description": "Array of parent collection slugs, empty array if top-level collection",
+            "items": {
+              "type": "string"
+            }
+          },
+          "starred": {
+            "type": "boolean",
+            "description": "Whether the collection is starred / favorited",
+            "default": false
+          }
+        }
+      },
+      "FileCollectionCreateRequest": {
+        "description": "Request body for creating a file collection",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/FileCollectionAttributes"
+          },
+          {
+            "type": "object",
+            "required": [
+              "name"
+            ]
+          }
+        ]
       }
     },
     "parameters": {

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "@epilot/file-client",
-  "version": "1.16.1",
+  "version": "1.18.0",
   "description": "Client library for the epilot File API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "epilot GmbH",
   "license": "MIT",
   "private": false,
+  "scripts": {
+    "test": "jest",
+    "typescript": "tsc",
+    "bundle-definition": "webpack",
+    "openapi": "node ../../scripts/update-openapi.js https://docs.api.epilot.io/file.yaml",
+    "typegen": "openapi typegen src/openapi.json --client -b '/* eslint-disable */' > src/openapi.d.ts",
+    "build": "tsc && npm run build:patch && npm run bundle-definition",
+    "build:patch": "sed -i'' -e '/^__exportStar.*openapi.*$/d' dist/index.js",
+    "build:watch": "npm run build && tsc -w",
+    "prepublishOnly": "npm run typegen && npm run build",
+    "lint": "pnpm exec eslint src"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/epilot-dev/sdk-js.git",
@@ -59,16 +71,5 @@
     "webpack": "^5.18.0",
     "webpack-cli": "^4.4.0"
   },
-  "gitHead": "39426e86cfb320fa3227dc03f60ee6a10848e7c7",
-  "scripts": {
-    "test": "jest",
-    "typescript": "tsc",
-    "bundle-definition": "webpack",
-    "openapi": "node ../../scripts/update-openapi.js https://docs.api.epilot.io/file.yaml",
-    "typegen": "openapi typegen src/openapi.json --client -b '/* eslint-disable */' > src/openapi.d.ts",
-    "build": "tsc && npm run build:patch && npm run bundle-definition",
-    "build:patch": "sed -i'' -e '/^__exportStar.*openapi.*$/d' dist/index.js",
-    "build:watch": "npm run build && tsc -w",
-    "lint": "pnpm exec eslint src"
-  }
-}
+  "gitHead": "39426e86cfb320fa3227dc03f60ee6a10848e7c7"
+}

package/LICENSE

@@ -1,21 +0,0 @@
-The MIT License (MIT)
-
-Copyright (c) 2025 epilot GmbH
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.