@epilot/file-client 1.17.0 → 1.18.0

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "File API",
-    "version": "1.1.1",
+    "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"
         ],
@@ -1336,7 +1346,8 @@
       "get": {
         "operationId": "getGlobalFileFolders",
         "summary": "getGlobalFileFolders",
-        "description": "Gets all global file folders for a specific schema",
+        "deprecated": true,
+        "description": "Gets all global file folders for a specific schema. Deprecated - use getGlobalFileCollections instead.",
         "tags": [
           "File Folders"
         ],
@@ -1368,6 +1379,281 @@
           }
         }
       }
+    },
+    "/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": {
@@ -1402,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": {
@@ -1944,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",
@@ -1957,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": {
@@ -2042,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,6 +1,6 @@
 {
   "name": "@epilot/file-client",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Client library for the epilot File API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",