@epilot/sdk 2.1.0-rc.1 → 2.1.0

package/docs/file.md

@@ -0,0 +1,1453 @@
+# File API
+
+- **Base URL:** `https://file.sls.epilot.io`
+- **Full API Docs:** [https://docs.epilot.io/api/file](https://docs.epilot.io/api/file)
+
+## Usage
+
+```ts
+import { epilot } from '@epilot/sdk'
+
+epilot.authorize(() => '<token>')
+const { data } = await epilot.file.uploadFileV2(...)
+```
+
+### Tree-shakeable import
+
+```ts
+import { getClient, authorize } from '@epilot/sdk/file'
+
+const fileClient = getClient()
+authorize(fileClient, () => '<token>')
+const { data } = await fileClient.uploadFileV2(...)
+```
+
+## Operations
+
+**File**
+- [`uploadFileV2`](#uploadfilev2)
+- [`saveFileV2`](#savefilev2)
+- [`getFile`](#getfile)
+- [`deleteFile`](#deletefile)
+- [`downloadFile`](#downloadfile)
+- [`downloadS3File`](#downloads3file)
+- [`downloadFiles`](#downloadfiles)
+- [`verifyCustomDownloadUrl`](#verifycustomdownloadurl)
+- [`uploadFilePublic`](#uploadfilepublic)
+
+**Preview**
+- [`previewFile`](#previewfile)
+- [`previewS3File`](#previews3file)
+- [`previewS3FileGet`](#previews3fileget)
+- [`previewPublicFile`](#previewpublicfile)
+
+**Session**
+- [`getSession`](#getsession)
+- [`deleteSession`](#deletesession)
+
+**Public Links**
+- [`generatePublicLink`](#generatepubliclink)
+- [`listPublicLinksForFile`](#listpubliclinksforfile)
+- [`accessPublicLink`](#accesspubliclink)
+- [`revokePublicLink`](#revokepubliclink)
+
+**File Collections**
+- [`getUserSchemaFileCollections`](#getuserschemafilecollections)
+- [`createUserSchemaFileCollection`](#createuserschemafilecollection)
+- [`updateUserSchemaFileCollection`](#updateuserschemafilecollection)
+- [`deleteUserSchemaFileCollection`](#deleteuserschemafilecollection)
+- [`getFilesInCollection`](#getfilesincollection)
+- [`getGlobalFileCollections`](#getglobalfilecollections)
+
+**Schemas**
+- [`EntityId`](#entityid)
+- [`EntitySlug`](#entityslug)
+- [`ActivityId`](#activityid)
+- [`FileEntityId`](#fileentityid)
+- [`FileAttributes`](#fileattributes)
+- [`FileType`](#filetype)
+- [`CustomDownloadUrl`](#customdownloadurl)
+- [`FileEntity`](#fileentity)
+- [`CommonSaveFilePayload`](#commonsavefilepayload)
+- [`SaveS3FilePayload`](#saves3filepayload)
+- [`SaveFileFromSourceURLPayload`](#savefilefromsourceurlpayload)
+- [`SaveCustomFilePayload`](#savecustomfilepayload)
+- [`SaveFilePayload`](#savefilepayload)
+- [`SaveFilePayloadV2`](#savefilepayloadv2)
+- [`BatchSaveFileVersionPayload`](#batchsavefileversionpayload)
+- [`UploadFilePayload`](#uploadfilepayload)
+- [`FileUpload`](#fileupload)
+- [`DownloadFilesPayload`](#downloadfilespayload)
+- [`VerifyCustomDownloadUrlPayload`](#verifycustomdownloadurlpayload)
+- [`S3Reference`](#s3reference)
+- [`S3Ref`](#s3ref)
+- [`FileItem`](#fileitem)
+- [`FileRelationItem`](#filerelationitem)
+- [`PublicLink`](#publiclink)
+- [`BaseEntityOwner`](#baseentityowner)
+- [`BaseEntityAcl`](#baseentityacl)
+- [`ErrorObject`](#errorobject)
+- [`FileCollectionId`](#filecollectionid)
+- [`FileCollectionItem`](#filecollectionitem)
+- [`FileCollectionAttributes`](#filecollectionattributes)
+- [`FileCollectionCreateRequest`](#filecollectioncreaterequest)
+
+### `uploadFileV2`
+
+Create pre-signed S3 URL to upload a file to keep temporarily (one week).
+
+`POST /v2/files/upload`
+
+```ts
+const { data } = await client.uploadFileV2(
+  {
+    file_entity_id: 'example',
+  },
+  {
+    filename: 'document.pdf',
+    mime_type: 'application/pdf',
+    index_tag: '2f6a377c8e78',
+    metadata: {
+      color: 'blue'
+    }
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "s3ref": {
+    "bucket": "epilot-prod-user-content",
+    "key": "123/temp/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf"
+  },
+  "upload_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/temp/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf?AWSParams=123",
+  "public_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf"
+}
+```
+
+</details>
+
+---
+
+### `saveFileV2`
+
+Saves a permanent file entity. Updates an existing file entity when `_id` is passed.
+
+`POST /v2/files`
+
+```ts
+const { data } = await client.saveFileV2(
+  {
+    activity_id: 'example',
+    fill_activity: true,
+    strict: true,
+    async: true,
+    delete_temp_file: true,
+    version_only: true,
+  },
+  {
+    _id: 'ef7d985c-2385-44f4-9c71-ae06a52264f8',
+    file_entity_id: 'string',
+    relations: [
+      {
+        entity_id: 'ef7d985c-2385-44f4-9c71-ae06a52264f8',
+        _schema: 'contact',
+        _tags: ['string']
+      }
+    ],
+    _tags: ['tag1', 'tag2'],
+    _purpose: ['8d396871-95a0-4c9d-bb4d-9eda9c35776c', 'da7cdf9a-01be-40c9-a29c-9a8f9f0de6f8'],
+    _manifest: ['123e4567-e89b-12d3-a456-426614174000'],
+    filename: 'document.pdf',
+    type: 'document',
+    mime_type: 'application/pdf',
+    size_bytes: 1234,
+    readable_size: '1.2 MB',
+    access_control: 'private',
+    public_url: 'https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf',
+    custom_download_url: 'https://some-api-url.com/download?file_id=123',
+    s3ref: {}
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "_title": "document.pdf",
+  "_schema": "file",
+  "_org": "123",
+  "_id": "ef7d985c-2385-44f4-9c71-ae06a52264f8",
+  "_tags": ["tag1", "tag2"],
+  "_purpose": ["8d396871-95a0-4c9d-bb4d-9eda9c35776c", "da7cdf9a-01be-40c9-a29c-9a8f9f0de6f8"],
+  "_manifest": ["123e4567-e89b-12d3-a456-426614174000"],
+  "filename": "document.pdf",
+  "type": "document",
+  "mime_type": "application/pdf",
+  "size_bytes": 1234,
+  "readable_size": "1.2 MB",
+  "access_control": "private",
+  "public_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf",
+  "custom_download_url": "https://some-api-url.com/download?file_id=123",
+  "source_url": "https://productengineer-content.s3.eu-west-1.amazonaws.com/product-engineer-checklist.pdf",
+  "s3ref": {},
+  "versions": [
+    {
+      "s3ref": {},
+      "filename": "document.pdf",
+      "size_bytes": 1234,
+      "readable_size": "1.2 MB",
+      "mime_type": "image/jpeg"
+    }
+  ],
+  "_updated_at": "1970-01-01T00:00:00.000Z",
+  "_created_at": "1970-01-01T00:00:00.000Z",
+  "_acl": {
+    "view": ["org:456"],
+    "edit": ["org:456"],
+    "delete": ["org:456"]
+  },
+  "_owners": [
+    {
+      "org_id": "123",
+      "user_id": "123"
+    }
+  ],
+  "__additional": {}
+}
+```
+
+</details>
+
+---
+
+### `getFile`
+
+Get a file entity by id
+
+`GET /v2/files/{id}`
+
+```ts
+const { data } = await client.getFile({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  source_url: true,
+  strict: true,
+  async: true,
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "_title": "document.pdf",
+  "_schema": "file",
+  "_org": "123",
+  "_id": "ef7d985c-2385-44f4-9c71-ae06a52264f8",
+  "_tags": ["tag1", "tag2"],
+  "_purpose": ["8d396871-95a0-4c9d-bb4d-9eda9c35776c", "da7cdf9a-01be-40c9-a29c-9a8f9f0de6f8"],
+  "_manifest": ["123e4567-e89b-12d3-a456-426614174000"],
+  "filename": "document.pdf",
+  "type": "document",
+  "mime_type": "application/pdf",
+  "size_bytes": 1234,
+  "readable_size": "1.2 MB",
+  "access_control": "private",
+  "public_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf",
+  "custom_download_url": "https://some-api-url.com/download?file_id=123",
+  "source_url": "https://productengineer-content.s3.eu-west-1.amazonaws.com/product-engineer-checklist.pdf",
+  "s3ref": {},
+  "versions": [
+    {
+      "s3ref": {},
+      "filename": "document.pdf",
+      "size_bytes": 1234,
+      "readable_size": "1.2 MB",
+      "mime_type": "image/jpeg"
+    }
+  ],
+  "_updated_at": "1970-01-01T00:00:00.000Z",
+  "_created_at": "1970-01-01T00:00:00.000Z",
+  "_acl": {
+    "view": ["org:456"],
+    "edit": ["org:456"],
+    "delete": ["org:456"]
+  },
+  "_owners": [
+    {
+      "org_id": "123",
+      "user_id": "123"
+    }
+  ],
+  "__additional": {}
+}
+```
+
+</details>
+
+---
+
+### `deleteFile`
+
+Delete a file entity by id
+
+`DELETE /v2/files/{id}`
+
+```ts
+const { data } = await client.deleteFile({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  purge: true,
+  activity_id: 'example',
+  strict: true,
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "_title": "document.pdf",
+  "_schema": "file",
+  "_org": "123",
+  "_id": "ef7d985c-2385-44f4-9c71-ae06a52264f8",
+  "_tags": ["tag1", "tag2"],
+  "_purpose": ["8d396871-95a0-4c9d-bb4d-9eda9c35776c", "da7cdf9a-01be-40c9-a29c-9a8f9f0de6f8"],
+  "_manifest": ["123e4567-e89b-12d3-a456-426614174000"],
+  "filename": "document.pdf",
+  "type": "document",
+  "mime_type": "application/pdf",
+  "size_bytes": 1234,
+  "readable_size": "1.2 MB",
+  "access_control": "private",
+  "public_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf",
+  "custom_download_url": "https://some-api-url.com/download?file_id=123",
+  "source_url": "https://productengineer-content.s3.eu-west-1.amazonaws.com/product-engineer-checklist.pdf",
+  "s3ref": {},
+  "versions": [
+    {
+      "s3ref": {},
+      "filename": "document.pdf",
+      "size_bytes": 1234,
+      "readable_size": "1.2 MB",
+      "mime_type": "image/jpeg"
+    }
+  ],
+  "_updated_at": "1970-01-01T00:00:00.000Z",
+  "_created_at": "1970-01-01T00:00:00.000Z",
+  "_acl": {
+    "view": ["org:456"],
+    "edit": ["org:456"],
+    "delete": ["org:456"]
+  },
+  "_owners": [
+    {
+      "org_id": "123",
+      "user_id": "123"
+    }
+  ],
+  "__additional": {}
+}
+```
+
+</details>
+
+---
+
+### `downloadFile`
+
+Generate a pre-signed download URL for a file.
+
+`GET /v1/files/{id}/download`
+
+```ts
+const { data } = await client.downloadFile({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  version: 1,
+  attachment: true,
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "download_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/temp/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf?AWSParams=123"
+}
+```
+
+</details>
+
+---
+
+### `downloadS3File`
+
+Generate a pre-signed download URL for a file using its S3 reference.
+
+`POST /v1/files:downloadS3`
+
+```ts
+const { data } = await client.downloadS3File({
+  s3_key: 'example',
+  s3_bucket: 'example',
+  attachment: true,
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "download_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/temp/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf?AWSParams=123"
+}
+```
+
+</details>
+
+---
+
+### `downloadFiles`
+
+Bulk generate pre-signed download URLs for multiple files in a single request.
+
+`POST /v1/files:downloadFiles`
+
+```ts
+const { data } = await client.downloadFiles(
+  null,
+  [
+    {
+      id: 'ef7d985c-2385-44f4-9c71-ae06a52264f8',
+      version: 0
+    }
+  ],
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+[
+  {
+    "download_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/temp/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf?AWSParams=123",
+    "file_entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+  }
+]
+```
+
+</details>
+
+---
+
+### `previewFile`
+
+Generate a thumbnail preview for a file entity.
+
+`GET /v1/files/{id}/preview`
+
+```ts
+const { data } = await client.previewFile({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  version: 1,
+  w: 1,
+  h: 1,
+})
+```
+
+---
+
+### `previewS3File`
+
+Generate a thumbnail preview from an S3 reference.
+
+`POST /v1/files:previewS3`
+
+```ts
+const { data } = await client.previewS3File(
+  {
+    w: 1,
+    h: 1,
+  },
+  {},
+)
+```
+
+---
+
+### `previewS3FileGet`
+
+Get a thumbnail preview from an S3 reference using query parameters.
+
+`GET /v1/files:previewS3`
+
+```ts
+const { data } = await client.previewS3FileGet({
+  key: 'example',
+  bucket: 'example',
+  w: 1,
+  h: 1,
+})
+```
+
+---
+
+### `previewPublicFile`
+
+Generate a thumbnail preview for a public file entity.
+
+`GET /v1/files/public/{id}/preview`
+
+```ts
+const { data } = await client.previewPublicFile({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  version: 1,
+  w: 1,
+  h: 1,
+  org_id: 'example',
+})
+```
+
+---
+
+### `getSession`
+
+Start a browser session by converting a Bearer token into a server-side cookie.
+
+`GET /v1/files/session`
+
+```ts
+const { data } = await client.getSession()
+```
+
+---
+
+### `deleteSession`
+
+End a browser session by deleting the token cookie.
+
+`DELETE /v1/files/session`
+
+```ts
+const { data } = await client.deleteSession()
+```
+
+---
+
+### `generatePublicLink`
+
+Generate a public link to share a private file externally.
+
+`POST /v1/files/{id}/public/links`
+
+```ts
+const { data } = await client.generatePublicLink({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+"string"
+```
+
+</details>
+
+---
+
+### `listPublicLinksForFile`
+
+**Not yet implemented.**
+
+`GET /v1/files/{id}/public/links`
+
+```ts
+const { data } = await client.listPublicLinksForFile({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "results": [
+    {
+      "id": "3ef5c6d9-818d-45e6-8efb-b1de59079a1c",
+      "link": "https://file.sls.epilot.io/v1/files/public/links/3ef5c6d9-818d-45e6-8efb-b1de59079a1c",
+      "last_accessed_at": "string"
+    }
+  ]
+}
+```
+
+</details>
+
+---
+
+### `accessPublicLink`
+
+Access a file via its public link.
+
+`GET /v1/files/public/links/{id}/{filename}`
+
+```ts
+const { data } = await client.accessPublicLink({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  filename: 'example',
+  hash: 'example',
+})
+```
+
+---
+
+### `revokePublicLink`
+
+**Not yet implemented.**
+
+`DELETE /v1/files/public/links/{id}`
+
+```ts
+const { data } = await client.revokePublicLink({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+})
+```
+
+---
+
+### `verifyCustomDownloadUrl`
+
+Verify that a custom download URL is valid and has not expired.
+
+`POST /v1/files/download:verify`
+
+```ts
+const { data } = await client.verifyCustomDownloadUrl(
+  null,
+  {
+    custom_download_url: 'https://some-api-url.com?file_id=123&expires_at=1699273500029&signature=abcdefg'
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "valid": true
+}
+```
+
+</details>
+
+---
+
+### `uploadFilePublic`
+
+Create a pre-signed S3 URL for uploading a file without authentication.
+
+`POST /v1/files/public/upload`
+
+```ts
+const { data } = await client.uploadFilePublic(
+  null,
+  {
+    filename: 'document.pdf',
+    mime_type: 'application/pdf',
+    index_tag: '2f6a377c8e78',
+    metadata: {
+      color: 'blue'
+    }
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "s3ref": {
+    "bucket": "epilot-prod-user-content",
+    "key": "123/temp/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf"
+  },
+  "upload_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/temp/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf?AWSParams=123",
+  "error": "File entity not found"
+}
+```
+
+</details>
+
+---
+
+### `getUserSchemaFileCollections`
+
+Get all file collections for the current user within a specific schema.
+
+`GET /v1/{slug}/collections`
+
+```ts
+const { data } = await client.getUserSchemaFileCollections({
+  slug: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+[
+  {
+    "slug": "_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234:documents",
+    "name": "Documents",
+    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    "parents": ["_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234"],
+    "starred": false,
+    "order": 0,
+    "enabled_locations": ["string"],
+    "enabled_purposes": ["9eefcb98-93cf-4c5b-a040-f1d26d57c177", "5c544c09-a691-43ed-a7fa-0a8b44b5b161"],
+    "created_at": "2024-01-01T12:00:00Z",
+    "updated_at": "2024-01-02T12:00:00Z"
+  }
+]
+```
+
+</details>
+
+---
+
+### `createUserSchemaFileCollection`
+
+Create a new file collection for the current user within a specific schema.
+
+`POST /v1/{slug}/collections`
+
+```ts
+const { data } = await client.createUserSchemaFileCollection(
+  {
+    slug: 'example',
+  },
+  {
+    name: 'string',
+    parents: ['string'],
+    starred: false,
+    enabled_locations: ['string'],
+    enabled_purposes: ['string']
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "slug": "_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234:documents",
+  "name": "Documents",
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "parents": ["_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234"],
+  "starred": false,
+  "order": 0,
+  "enabled_locations": ["string"],
+  "enabled_purposes": ["9eefcb98-93cf-4c5b-a040-f1d26d57c177", "5c544c09-a691-43ed-a7fa-0a8b44b5b161"],
+  "created_at": "2024-01-01T12:00:00Z",
+  "updated_at": "2024-01-02T12:00:00Z"
+}
+```
+
+</details>
+
+---
+
+### `updateUserSchemaFileCollection`
+
+Update an existing file collection.
+
+`PUT /v1/{slug}/collections/{collectionSlug}`
+
+```ts
+const { data } = await client.updateUserSchemaFileCollection(
+  {
+    slug: 'example',
+    collectionSlug: 'example',
+  },
+  {
+    name: 'string',
+    parents: ['string'],
+    starred: false,
+    enabled_locations: ['string'],
+    enabled_purposes: ['string']
+  },
+)
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+{
+  "slug": "_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234:documents",
+  "name": "Documents",
+  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+  "parents": ["_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234"],
+  "starred": false,
+  "order": 0,
+  "enabled_locations": ["string"],
+  "enabled_purposes": ["9eefcb98-93cf-4c5b-a040-f1d26d57c177", "5c544c09-a691-43ed-a7fa-0a8b44b5b161"],
+  "created_at": "2024-01-01T12:00:00Z",
+  "updated_at": "2024-01-02T12:00:00Z"
+}
+```
+
+</details>
+
+---
+
+### `deleteUserSchemaFileCollection`
+
+Delete a file collection.
+
+`DELETE /v1/{slug}/collections/{collectionSlug}`
+
+```ts
+const { data } = await client.deleteUserSchemaFileCollection({
+  slug: 'example',
+  collectionSlug: 'example',
+})
+```
+
+---
+
+### `getFilesInCollection`
+
+Get all files within a specific collection for an entity.
+
+`GET /v1/entity/{id}/collections/{collectionSlug}/files`
+
+```ts
+const { data } = await client.getFilesInCollection({
+  id: '123e4567-e89b-12d3-a456-426614174000',
+  collectionSlug: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+[
+  {
+    "_title": "document.pdf",
+    "_schema": "file",
+    "_org": "123",
+    "_id": "ef7d985c-2385-44f4-9c71-ae06a52264f8",
+    "_tags": ["tag1", "tag2"],
+    "_purpose": ["8d396871-95a0-4c9d-bb4d-9eda9c35776c", "da7cdf9a-01be-40c9-a29c-9a8f9f0de6f8"],
+    "_manifest": ["123e4567-e89b-12d3-a456-426614174000"],
+    "filename": "document.pdf",
+    "type": "document",
+    "mime_type": "application/pdf",
+    "size_bytes": 1234,
+    "readable_size": "1.2 MB",
+    "access_control": "private",
+    "public_url": "https://epilot-prod-user-content.s3.eu-central-1.amazonaws.com/123/4d689aeb-1497-4410-a9fe-b36ca9ac4389/document.pdf",
+    "custom_download_url": "https://some-api-url.com/download?file_id=123",
+    "source_url": "https://productengineer-content.s3.eu-west-1.amazonaws.com/product-engineer-checklist.pdf",
+    "s3ref": {},
+    "versions": [
+      {
+        "s3ref": {},
+        "filename": "document.pdf",
+        "size_bytes": 1234,
+        "readable_size": "1.2 MB",
+        "mime_type": "image/jpeg"
+      }
+    ],
+    "_updated_at": "1970-01-01T00:00:00.000Z",
+    "_created_at": "1970-01-01T00:00:00.000Z",
+    "_acl": {
+      "view": ["org:456"],
+      "edit": ["org:456"],
+      "delete": ["org:456"]
+    },
+    "_owners": [
+      {
+        "org_id": "123",
+        "user_id": "123"
+      }
+    ],
+    "__additional": {}
+  }
+]
+```
+
+</details>
+
+---
+
+### `getGlobalFileCollections`
+
+Get all global file collections for a specific schema.
+
+`GET /v1/collections/{schemaSlug}`
+
+```ts
+const { data } = await client.getGlobalFileCollections({
+  schemaSlug: 'example',
+})
+```
+
+<details>
+<summary>Response</summary>
+
+```json
+[
+  {
+    "slug": "_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234:documents",
+    "name": "Documents",
+    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    "parents": ["_system_files_collection_3fa85f64-5717-4562-b3fc-2c963f66afa6_10234"],
+    "starred": false,
+    "order": 0,
+    "enabled_locations": ["string"],
+    "enabled_purposes": ["9eefcb98-93cf-4c5b-a040-f1d26d57c177", "5c544c09-a691-43ed-a7fa-0a8b44b5b161"],
+    "created_at": "2024-01-01T12:00:00Z",
+    "updated_at": "2024-01-02T12:00:00Z"
+  }
+]
+```
+
+</details>
+
+---
+
+## Schemas
+
+### `EntityId`
+
+```ts
+type EntityId = string
+```
+
+### `EntitySlug`
+
+URL-friendly identifier for the entity schema
+
+```ts
+type EntitySlug = string
+```
+
+### `ActivityId`
+
+See https://github.com/ulid/spec
+
+```ts
+type ActivityId = string // ulid
+```
+
+### `FileEntityId`
+
+```ts
+type FileEntityId = string | string // uuid
+```
+
+### `FileAttributes`
+
+```ts
+type FileAttributes = {
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+}
+```
+
+### `FileType`
+
+```ts
+type FileType = "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+```
+
+### `CustomDownloadUrl`
+
+Custom external download url used for the file
+
+```ts
+type CustomDownloadUrl = string // uri
+```
+
+### `FileEntity`
+
+```ts
+type FileEntity = {
+  _title: string
+  _schema: "file"
+  _org: string
+  _id: string | string // uuid
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename: string
+  type: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+  source_url?: string
+  s3ref?: object
+  versions: Array<{
+    s3ref?: unknown
+    filename?: string
+    size_bytes?: number
+    readable_size?: string
+    mime_type?: string
+  }>
+  _updated_at?: string // date-time
+  _created_at?: string // date-time
+  _acl?: {
+    view?: string[]
+    edit?: string[]
+    delete?: string[]
+  }
+  _owners?: Array<{
+    org_id: string
+    user_id?: string
+  }>
+  __additional?: Record<string, unknown>
+}
+```
+
+### `CommonSaveFilePayload`
+
+```ts
+type CommonSaveFilePayload = {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+}
+```
+
+### `SaveS3FilePayload`
+
+```ts
+type SaveS3FilePayload = {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+  s3ref?: unknown
+}
+```
+
+### `SaveFileFromSourceURLPayload`
+
+```ts
+type SaveFileFromSourceURLPayload = {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+  source_url?: string // uri
+}
+```
+
+### `SaveCustomFilePayload`
+
+```ts
+type SaveCustomFilePayload = {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+}
+```
+
+### `SaveFilePayload`
+
+```ts
+type SaveFilePayload = {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+  s3ref?: unknown
+} | {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+  source_url?: string // uri
+} | {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+}
+```
+
+### `SaveFilePayloadV2`
+
+```ts
+type SaveFilePayloadV2 = {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+  s3ref?: unknown
+} | {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+  source_url?: string // uri
+} | {
+  _id?: object
+  file_entity_id?: string
+  relations?: Array<{
+    entity_id: string
+    _schema?: string
+    _tags?: string[]
+  }>
+  _tags?: string[]
+  _purpose?: string[]
+  _manifest?: string // uuid[]
+  filename?: string
+  type?: "document" | "document_template" | "text" | "image" | "video" | "audio" | "spreadsheet" | "presentation" | "font" | "archive" | "application" | "unknown"
+  mime_type?: string
+  size_bytes?: number
+  readable_size?: string
+  access_control?: "private" | "public-read"
+  public_url?: string // url
+  custom_download_url?: string // uri
+}
+```
+
+### `BatchSaveFileVersionPayload`
+
+Payload for batch version save. Only s3ref payloads are supported.
+
+```ts
+type BatchSaveFileVersionPayload = {
+  _id?: object
+  file_entity_id?: string
+  filename?: string
+  mime_type?: string
+  access_control?: "private" | "public-read"
+  s3ref: unknown
+}
+```
+
+### `UploadFilePayload`
+
+```ts
+type UploadFilePayload = {
+  filename: string
+  mime_type?: string
+  index_tag?: string
+  metadata?: Record<string, string>
+}
+```
+
+### `FileUpload`
+
+```ts
+type FileUpload = {
+  s3ref?: object
+  upload_url?: string // url
+  public_url?: string // url
+}
+```
+
+### `DownloadFilesPayload`
+
+```ts
+type DownloadFilesPayload = Array<{
+  id: string | string // uuid
+  version?: number
+}>
+```
+
+### `VerifyCustomDownloadUrlPayload`
+
+```ts
+type VerifyCustomDownloadUrlPayload = {
+  custom_download_url: string
+}
+```
+
+### `S3Reference`
+
+```ts
+type S3Reference = {
+  bucket: string
+  key: string
+}
+```
+
+### `S3Ref`
+
+```ts
+type S3Ref = {
+  bucket: string
+  key: string
+}
+```
+
+### `FileItem`
+
+```ts
+type FileItem = {
+  s3ref?: unknown
+  filename?: string
+  size_bytes?: number
+  readable_size?: string
+  mime_type?: string
+}
+```
+
+### `FileRelationItem`
+
+```ts
+type FileRelationItem = {
+  entity_id: string
+  _schema?: string
+  _tags?: string[]
+}
+```
+
+### `PublicLink`
+
+```ts
+type PublicLink = {
+  id?: string
+  link?: string
+  last_accessed_at?: string
+}
+```
+
+### `BaseEntityOwner`
+
+The user / organization owning this entity.
+
+Note: Owner implicitly has access to the entity regardless of ACLs.
+
+
+```ts
+type BaseEntityOwner = {
+  org_id: string
+  user_id?: string
+}
+```
+
+### `BaseEntityAcl`
+
+Access control list (ACL) for an entity. Defines sharing access to external orgs or users.
+
+```ts
+type BaseEntityAcl = {
+  view?: string[]
+  edit?: string[]
+  delete?: string[]
+}
+```
+
+### `ErrorObject`
+
+A generic error returned by the API
+
+```ts
+type ErrorObject = {
+  status?: number
+  error?: string
+}
+```
+
+### `FileCollectionId`
+
+Generated uuid for a file collection
+
+```ts
+type FileCollectionId = string // uuid
+```
+
+### `FileCollectionItem`
+
+A file collection with identifiers and timestamps
+
+```ts
+type FileCollectionItem = {
+  slug?: string
+  name: string
+  id?: string // uuid
+  parents?: string[]
+  starred?: boolean
+  order?: number
+  enabled_locations?: string[]
+  enabled_purposes?: string[]
+  created_at?: string // date-time
+  updated_at?: string // date-time
+}
+```
+
+### `FileCollectionAttributes`
+
+```ts
+type FileCollectionAttributes = {
+  name?: string
+  parents?: string[]
+  starred?: boolean
+  enabled_locations?: string[]
+  enabled_purposes?: string[]
+}
+```
+
+### `FileCollectionCreateRequest`
+
+Request body for creating a file collection
+
+```ts
+type FileCollectionCreateRequest = {
+  name: string
+  parents?: string[]
+  starred?: boolean
+  enabled_locations?: string[]
+  enabled_purposes?: string[]
+}
+```