### Clone TypeX, Install Dependencies, Compile, and Start

Source: https://github.com/diced/zipline/wiki/Installation-&-Running

A sequence of commands to clone the TypeX repository, navigate into the directory, compile the TypeScript code, and start the application. This is the primary installation and startup sequence.

```sh
git clone https://github.com/dicedtomatoreal/typex
cd typex
tsc -p .
npm start
```

--------------------------------

### List User Files Request Example

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example of a GET request to list user files with pagination and search parameters.

```http
GET /api/user/files?page=1&perpage=20&searchField=name&searchQuery=document HTTP/1.1
```

--------------------------------

### Get Single File Response Example

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example of a successful (200) JSON response when retrieving a single user file.

```json
{
  "id": "f1a2b3c4",
  "name": "document.pdf",
  "size": 2048000,
  "type": "application/pdf",
  "views": 5,
  "favorite": false,
  "createdAt": "2025-01-05T14:32:01Z",
  "url": "https://files.example.com/u/document.pdf"
}
```

--------------------------------

### Example Environment File

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/configuration.md

This is a comprehensive example of an environment file, showcasing required and optional configurations for core, files, URLs, storage, and development settings.

```bash
# Required
CORE_SECRET="change-this-to-a-random-32-character-secret-string-please"
DATABASE_URL="postgresql://zipline:password@localhost:5432/zipline"

# Core
CORE_PORT=3000
CORE_HOSTNAME=0.0.0.0
CORE_RETURN_HTTPS_URLS=false
CORE_DEFAULT_DOMAIN=files.example.com

# Files
FILES_ROUTE=/u
FILES_LENGTH=6
FILES_DEFAULT_FORMAT=random
FILES_MAX_FILE_SIZE=100mb
FILES_DISABLED_EXTENSIONS=exe,bat,com

# URLs
URLS_ROUTE=/go
URLS_LENGTH=6

# Storage
DATASOURCE_TYPE=local
DATASOURCE_LOCAL_DIRECTORY=./uploads

# Development
DEBUG=zipline
NODE_ENV=development

```

--------------------------------

### Install Zipline Dependencies

Source: https://github.com/diced/zipline/blob/trunk/README.md

Install project dependencies using pnpm. Ensure Node.js LTS and pnpm are installed globally.

```bash
pnpm install
```

--------------------------------

### List User Files Response Example

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example of a successful (200) JSON response when listing user files, including file details, pagination info, and search context.

```json
{
  "page": [
    {
      "id": "f1a2b3c4",
      "name": "document.pdf",
      "originalName": "My Document.pdf",
      "size": 2048000,
      "type": "application/pdf",
      "views": 5,
      "maxViews": 10,
      "favorite": false,
      "createdAt": "2025-01-05T14:32:01Z",
      "updatedAt": "2025-01-05T14:32:01Z",
      "deletesAt": "2025-01-12T14:32:01Z",
      "password": false,
      "folderId": null,
      "tags": [
        {
          "id": "t1",
          "name": "work",
          "color": "#FF0000"
        }
      ],
      "url": "https://files.example.com/u/document.pdf"
    }
  ],
  "total": 42,
  "pages": 3,
  "search": {
    "field": "name",
    "query": "document"
  }
}
```

--------------------------------

### Get Server Settings Response

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example JSON response for the GET /api/server/settings endpoint, displaying server configuration and runtime overrides.

```json
{
  "settings": {
    "port": 3000,
    "hostname": "0.0.0.0",
    "returnHttpsUrls": false,
    "defaultDomain": "files.example.com",
    "filesRoute": "/u",
    "filesMaxFileSize": "100mb",
    "filesDefaultFormat": "random",
    "datasourceType": "local",
    "datasourceLocalDirectory": "/uploads"
  },
  "tampered": ["CORE_SECRET", "DATABASE_URL"]
}
```

--------------------------------

### Install MySQL Driver

Source: https://github.com/diced/zipline/wiki/Installation-&-Running

Installs the MySQL database driver using npm. Use this command if you plan to connect to a MySQL database.

```sh
npm i mysql --save-dev
```

--------------------------------

### Get Single File Request Example

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example of a GET request to retrieve a single user file by its name.

```http
GET /api/user/files/document.pdf HTTP/1.1
```

--------------------------------

### Start Zipline Development Server

Source: https://github.com/diced/zipline/blob/trunk/README.md

Run the Zipline development server. This command starts the application with hot-reloading and other development-specific features enabled.

```bash
pnpm dev
```

--------------------------------

### Install PostgreSQL Driver

Source: https://github.com/diced/zipline/wiki/Installation-&-Running

Installs the PostgreSQL database driver using npm. Use this command if you plan to connect to a PostgreSQL database.

```sh
npm i pg --save-dev
```

--------------------------------

### Install MariaDB Driver

Source: https://github.com/diced/zipline/wiki/Installation-&-Running

Installs the MariaDB database driver using npm. Use this command if you plan to connect to a MariaDB database.

```sh
npm i mariadb --save-dev
```

--------------------------------

### Update File Request Examples

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Examples of PATCH requests to update file properties, tags, or move files to different folders.

```json
{
  "action": "favorite",
  "favorite": true
}
```

```json
{
  "action": "tag",
  "tags": ["tag-id-1", "tag-id-2"]
}
```

```json
{
  "action": "move",
  "folderId": "folder-id"
}
```

--------------------------------

### Verify Node.js and TypeScript Installation

Source: https://github.com/diced/zipline/wiki/Installation-&-Running

Checks the installed versions of TypeScript, npm, and Node.js. Ensure these commands output version numbers.

```sh
tsc -v
npm -v
node -v
```

--------------------------------

### Example Zipline Environment Variables

Source: https://github.com/diced/zipline/blob/trunk/README.md

Configure your Zipline application's behavior using environment variables. This example `.env` file shows required and optional settings for debugging, core secrets, database connections, and data source configurations (local or S3).

```bash
DEBUG=zipline

# required
CORE_SECRET="a secret that is 32 characters long"

# required
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/zipline?schema=public"

# these are optional
CORE_PORT=3000
CORE_HOSTNAME=0.0.0.0

# one of these is required
DATASOURCE_TYPE="local"
# DATASOURCE_TYPE="s3"

# if DATASOURCE_TYPE=local
DATASOURCE_LOCAL_DIRECTORY="/path/to/your/local/files"

# if DATASOURCE_TYPE=s3
# DATASOURCE_S3_ACCESS_KEY_ID="your-access-key-id"
# DATASOURCE_S3_SECRET_ACCESS_KEY="your-secret-access-key"
# DATASOURCE_S3_REGION="your-region"
# DATASOURCE_S3_BUCKET="your-bucket"
# DATASOURCE_S3_ENDPOINT="your-endpoint"
# ^ if using a custom endpoint other than aws s3
```

--------------------------------

### Create Folder Response (200)

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example JSON response for a successful folder creation, returning the details of the newly created folder.

```json
{
  "id": "folder-789",
  "userId": "user-456",
  "parentId": null,
  "name": "New Project",
  "isPublic": false,
  "createdAt": "2025-01-05T14:32:01Z",
  "updatedAt": "2025-01-05T14:32:01Z"
}
```

--------------------------------

### Install TypeScript Globally

Source: https://github.com/diced/zipline/wiki/Installation-&-Running

Installs the TypeScript compiler globally using npm. This is a prerequisite for compiling TypeScript code.

```sh
npm i typescript -g
```

--------------------------------

### Install CockroachDB Driver

Source: https://github.com/diced/zipline/wiki/Installation-&-Running

Installs the CockroachDB database driver using npm. Use this command if you plan to connect to a CockroachDB database.

```sh
npm i cockroachdb --save-dev
```

--------------------------------

### Upload Files Request Example

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Demonstrates a sample POST request to the /api/upload endpoint, including multipart/form-data and custom headers for configuration.

```http
POST /api/upload HTTP/1.1
Content-Type: multipart/form-data
X-Zipline-Format: date
X-Zipline-Password: secret123
X-Zipline-Max-Views: 10
X-Zipline-Deletes-At: 7d

[multipart file data]
```

--------------------------------

### S3 Setup (MinIO - self-hosted)

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/configuration.md

Configure Zipline to use a self-hosted MinIO instance for S3 compatible storage. This includes endpoint and path style settings.

```bash
DATASOURCE_TYPE=s3
DATASOURCE_S3_ACCESS_KEY_ID=minioadmin
DATASOURCE_S3_SECRET_ACCESS_KEY=minioadmin
DATASOURCE_S3_REGION=us-east-1
DATASOURCE_S3_BUCKET=zipline
DATASOURCE_S3_ENDPOINT=http://minio:9000
DATASOURCE_S3_FORCE_PATH_STYLE=true

```

--------------------------------

### Local Storage Setup

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/configuration.md

Configure Zipline to use local storage by specifying the data source type and the directory for uploads.

```bash
DATASOURCE_TYPE=local
DATASOURCE_LOCAL_DIRECTORY=/var/lib/zipline/uploads

```

--------------------------------

### Start Zipline with Docker Compose

Source: https://github.com/diced/zipline/blob/trunk/README.md

Command to start the Zipline server in detached mode using Docker Compose. Access the application at http://localhost:3000 or your configured port.

```bash
docker compose up -d
```

--------------------------------

### Delete File Request Example

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example of a DELETE request to remove a user file permanently.

```http
DELETE /api/user/files/document.pdf HTTP/1.1
```

--------------------------------

### Install Microsoft SQL Server Driver

Source: https://github.com/diced/zipline/wiki/Installation-&-Running

Installs the Microsoft SQL Server database driver using npm. Use this command if you plan to connect to a Microsoft SQL Server database.

```sh
npm i mssql --save-dev
```

--------------------------------

### GET /api/server/settings

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Retrieves all current server settings, including any runtime overrides.

```APIDOC
## GET /api/server/settings

### Description
Get all server settings.

### Method
GET

### Endpoint
/api/server/settings

### Response
#### Success Response (200)
- **settings** (object) - All config database fields
- **tampered** (string[]) - Config keys overridden at runtime

#### Response Example
```json
{
  "settings": {
    "key1": "value1",
    "key2": 123
  },
  "tampered": ["key1"]
}
```
```

--------------------------------

### List OAuth Providers Response

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example JSON response for the GET /api/auth/oauth endpoint, showing linked OAuth accounts.

```json
[
  {
    "id": "oauth-1",
    "provider": "GITHUB",
    "username": "johndoe",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  },
  {
    "id": "oauth-2",
    "provider": "DISCORD",
    "username": "johndoe#1234",
    "createdAt": "2025-01-02T00:00:00Z",
    "updatedAt": "2025-01-02T00:00:00Z"
  }
]
```

--------------------------------

### List User Folders Response (200)

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example JSON response for a successful request to list user folders, including folder details and associated files.

```json
[
  {
    "id": "folder-123",
    "userId": "user-456",
    "parentId": null,
    "name": "Projects",
    "isPublic": false,
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-05T14:32:01Z",
    "files": [
      {
        "id": "file-1",
        "name": "project.zip",
        "size": 5242880
      }
    ],
    "_count": {
      "children": 2,
      "files": 5
    }
  }
]
```

--------------------------------

### S3 Setup (AWS)

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/configuration.md

Set up Zipline to use AWS S3 for storage. Ensure you provide valid AWS credentials, region, and bucket name.

```bash
DATASOURCE_TYPE=s3
DATASOURCE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
DATASOURCE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
DATASOURCE_S3_REGION=us-west-2
DATASOURCE_S3_BUCKET=my-zipline-files

```

--------------------------------

### Upload Files Error Handling Examples

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Provides code examples for common error scenarios during file uploads, including extension blocking, file size limits, quota exceeded, and folder access issues.

```typescript
// Extension blocked
if (config.files.disabledExtensions.includes(extension)) {
  throw new ApiError(1006, `file[${i}]: ${extension} not allowed`);
}
```

```typescript
// File too large
if (file.size > bytes(config.files.maxFileSize)) {
  throw new ApiError(5001);
}
```

```typescript
// Quota exceeded
const quotaCheck = await checkQuota(req.user, totalSize, files.length);
if (quotaCheck !== true) {
  throw new ApiError(5002, quotaCheck);
}
```

```typescript
// Folder not accessible
if (options.folder) {
  const folder = await prisma.folder.findFirst({ where: { id: options.folder } });
  if (!folder || (!req.user && !folder.allowUploads)) {
    throw new ApiError(4001);
  }
}
```

--------------------------------

### Virtual-hosted Style URL

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Example of a virtual-hosted style URL for accessing objects in an S3 bucket.

```text
https://bucket.s3.amazonaws.com/user-id-1/file.jpg
```

--------------------------------

### Upload Files Response Example (200 OK)

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Illustrates a successful response from the /api/upload endpoint, detailing uploaded file information and deletion timestamp.

```json
{
  "files": [
    {
      "id": "f1a2b3c4-d5e6-7f8g",
      "name": "2025-01-05_14-32-01.jpg",
      "type": "image/jpeg",
      "url": "https://files.example.com/u/2025-01-05_14-32-01.jpg",
      "removedGps": true,
      "compressed": {
        "mimetype": "image/webp",
        "ext": "webp"
      }
    }
  ],
  "deletesAt": "2025-01-12T14:32:01.000Z",
  "assumedMimetypes": [false]
}
```

--------------------------------

### Run Zipline Production Version

Source: https://github.com/diced/zipline/blob/trunk/README.md

Start the Zipline application after it has been built for production. This command is used for running the deployed application.

```bash
pnpm start
```

--------------------------------

### Get Server Settings

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Retrieves all current server settings and a list of keys that have been overridden at runtime. Requires admin authentication.

```typescript
{
  settings: {
    // All config database fields
    [key: string]: any;
  };
  tampered: string[]; // Config keys overridden at runtime
}
```

--------------------------------

### List Tags API Response

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example JSON response for listing all tags created by a user.

```json
[
  {
    "id": "tag-1",
    "userId": "user-456",
    "name": "work",
    "color": "#FF0000",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
]
```

--------------------------------

### Accessing Global Configuration

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/configuration.md

Import the global config object to access current settings. Examples show accessing core, file, and datasource configurations.

```typescript
// Global config object
import { config } from '@/lib/config';

// Current values
config.core.port          // 3000
config.files.maxFileSize  // "100mb"
config.datasource.type    // "local" | "s3"
```

--------------------------------

### Example Error Responses

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/errors.md

Illustrates the structure of typical error responses, including basic and extended context.

```APIDOC
## Example Error Response

### Basic Error Response
```json
{
  "error": "E1038: Username already exists",
  "code": 1038,
  "statusCode": 400
}
```

### Error Response with Additional Context
```json
{
  "error": "E1010: file[2]: mimetype application/pdf was not recognized",
  "code": 1010,
  "statusCode": 400,
  "fileIndex": 2,
  "receivedType": "application/pdf"
}
```
```

--------------------------------

### Allow Direnv for Nix Development

Source: https://github.com/diced/zipline/blob/trunk/README.md

Use this command to allow direnv to manage your shell environment when using Nix for Zipline development. Ensure Nix and direnv are installed.

```bash
direnv allow
```

--------------------------------

### Run Compiled TypeX Application

Source: https://github.com/diced/zipline/wiki/Installation-&-Running

Executes the compiled JavaScript code from the 'out/src' directory to start the TypeX web server. This command should be run after the TypeScript code has been compiled.

```sh
node out/src
```

--------------------------------

### Docker Compose Configuration for Zipline

Source: https://github.com/diced/zipline/blob/trunk/README.md

This is the recommended Docker Compose setup for running Zipline with a PostgreSQL database. Ensure your .env file contains the necessary PostgreSQL credentials.

```yaml
services:
  postgresql:
    image: postgres:16
    restart: unless-stopped
    env_file:
      - .env
    environment:
      POSTGRES_USER: ${POSTGRESQL_USER:-zipline}
      POSTGRES_PASSWORD: ${POSTGRESQL_PASSWORD:?POSTGRESSQL_PASSWORD is required}
      POSTGRES_DB: ${POSTGRESQL_DB:-zipline}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD', 'pg_isready', '-U', 'zipline']
      interval: 10s
      timeout: 5s
      retries: 5

  zipline:
    image: ghcr.io/diced/zipline
    ports:
      - '3000:3000'
    env_file:
      - .env
    environment:
      - DATABASE_URL=postgres://${POSTGRESQL_USER:-zipline}:${POSTGRESQL_PASSWORD}@postgresql:5432/${POSTGRESQL_DB:-zipline}
    depends_on:
      postgresql:
        condition: service_healthy
    volumes:
      - './uploads:/zipline/uploads'
      - './public:/zipline/public'
      - './themes:/zipline/themes'
    healthcheck:
      test: ['CMD', 'wget', '-q', '--spider', 'http://localhost:3000/api/healthcheck']
      interval: 15s
      timeout: 2s
      retries: 2

volumes:
  pgdata:
```

--------------------------------

### Path Style URL

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Example of a path style URL for accessing objects in an S3 bucket, used when `forcePathStyle` is set to true.

```text
https://s3.amazonaws.com/bucket/user-id-1/file.jpg
```

--------------------------------

### Create Shortened URL API Request Headers

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example headers for creating a shortened URL, specifying max views, password, domains, and JSON output preference.

```typescript
{
  "x-zipline-max-views": "100",
  "x-zipline-password": "secret",
  "x-zipline-domain": "short.example.com, s.example.com",
  "x-zipline-no-json": "false"
}
```

--------------------------------

### Complete Configuration Object Type

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/types.md

This type represents the full configuration object, which can be loaded from environment variables or a database. It covers all aspects of the application's setup.

```typescript
{
  core: {
    port: number;
    hostname: string;
    secret: string;
    returnHttpsUrls: boolean;
    defaultDomain: string | null;
    tempDirectory: string;
    trustProxy: boolean;
    databaseUrl: string;
    database: {
      username: string | null;
      password: string | null;
      host: string | null;
      port: number | null;
      name: string | null;
    };
  };
  chunks: {
    max: string;
    size: string;
    enabled: boolean;
  };
  tasks: {
    deleteInterval: string;
    clearInvitesInterval: string;
    maxViewsInterval: string;
    thumbnailsInterval: string;
    metricsInterval: string;
    cleanThumbnailsInterval: string;
  };
  files: {
    route: string;
    length: number;
    defaultFormat: 'random' | 'date' | 'uuid' | 'name' | 'gfycat' | 'random-words';
    disabledTypes: string[];
    disabledTypesDefault: string | null;
    disabledExtensions: string[];
    maxFileSize: string;
    defaultExpiration: string | null;
    maxExpiration: string | null;
    assumeMimetypes: boolean;
    defaultDateFormat: string;
    removeGpsMetadata: boolean;
    randomWordsNumAdjectives: number;
    randomWordsSeparator: string;
    defaultCompressionFormat: string;
    maxFilesPerUpload: number;
    extensionlessUrls: boolean;
  };
  urls: {
    route: string;
    length: number;
  };
  datasource: {
    type: 'local' | 's3';
    s3?: {
      accessKeyId: string;
      secretAccessKey: string;
      region: string;
      bucket: string;
      endpoint: string | null;
      forcePathStyle: boolean;
      subdirectory: string | null;
    };
    local?: {
      directory: string;
    };
  };
  // ... additional config sections
}
```

--------------------------------

### Zipline Logger Output Format

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/middleware-and-plugins.md

Example of the structured log output format, including timestamp, level, namespace, message, and data payload.

```plaintext
[timestamp] [level] [namespace] message data=value
2025-01-05T14:32:01.123Z INFO api:upload processing file size=1048576 type=image/jpeg
```

--------------------------------

### Enter Nix Shell for Development

Source: https://github.com/diced/zipline/blob/trunk/README.md

If not using direnv, this command allows you to enter a Nix shell pre-configured for Zipline development. The `--no-pure-eval` flag is used for compatibility.

```bash
nix develop --no-pure-eval
```

--------------------------------

### Get File Extension

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-library-reference.md

Retrieves the file extension, correctly handling double extensions like .tar.gz. Use this to reliably get the extension for any filename.

```typescript
function getExtension(filename: string, override?: string): string

getExtension("archive.tar.gz")           // ".tar.gz"
getExtension("image.jpg", ".png")        // ".png"
getExtension("document.txt")             // ".txt"
```

--------------------------------

### Fetch All Settings

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/configuration.md

Retrieves all current server settings and the tampering list. This endpoint is admin-only.

```APIDOC
## GET /api/server/settings

### Description
Fetches all settings and tampering list.

### Method
GET

### Endpoint
/api/server/settings
```

--------------------------------

### Instantiate Datasource based on Configuration

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Selects and instantiates the appropriate datasource (local or S3) based on the provided configuration. Logs an error and exits if an unsupported type is encountered.

```typescript
function getDatasource(config?: Config): Datasource | void

switch (config.datasource.type) {
  case 'local':
    return new LocalDatasource(config.datasource.local!.directory);
  
  case 's3':
    return new S3Datasource({
      accessKeyId: config.datasource.s3!.accessKeyId,
      secretAccessKey: config.datasource.s3!.secretAccessKey,
      region: config.datasource.s3?.region,
      bucket: config.datasource.s3!.bucket,
      endpoint: config.datasource.s3?.endpoint,
      forcePathStyle: config.datasource.s3?.forcePathStyle,
      subdirectory: config.datasource.s3?.subdirectory
    });
  
default:
    log('datasource').error(`Type ${type} not supported`);
    process.exit(1);
}
```

--------------------------------

### MinIO Configuration

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Environment variables for configuring the S3 datasource to connect to a self-hosted MinIO instance.

```bash
DATASOURCE_TYPE=s3
DATASOURCE_S3_ACCESS_KEY_ID=minioadmin
DATASOURCE_S3_SECRET_ACCESS_KEY=minioadmin
DATASOURCE_S3_BUCKET=zipline
DATASOURCE_S3_ENDPOINT=http://minio:9000
DATASOURCE_S3_FORCE_PATH_STYLE=true
DATASOURCE_S3_REGION=us-east-1
```

--------------------------------

### Generate Database Migration File

Source: https://github.com/diced/zipline/blob/trunk/README.md

Create a new migration file for database schema changes using Prisma. This command should be run after modifying the `prisma.schema` file. Zipline applies migrations on startup.

```bash
pnpm db:migrate
```

--------------------------------

### Get Single File

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Retrieves a single file's details by its name or ID.

```APIDOC
## GET /api/user/files/[id]

### Description
Retrieve single file by name or ID.

### Method
GET

### Endpoint
/api/user/files/[id]

### Response
#### Success Response (200)
- **id** (string) - The file's unique identifier.
- **name** (string) - The file's name.
- **size** (number) - The file's size in bytes.
- **type** (string) - The file's MIME type.
- **views** (number) - Current number of views.
- **favorite** (boolean) - Whether the file is favorited.
- **createdAt** (string) - The date and time the file was created (ISO 8601 format).
- **url** (string) - The URL to access the file.

### Response Example
{
  "id": "f1a2b3c4",
  "name": "document.pdf",
  "size": 2048000,
  "type": "application/pdf",
  "views": 5,
  "favorite": false,
  "createdAt": "2025-01-05T14:32:01Z",
  "url": "https://files.example.com/u/document.pdf"
}
```

--------------------------------

### Get Specific User Folder

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Retrieves details for a specific user folder by its ID.

```APIDOC
## GET /api/user/folders/[id]

### Description
Get specific folder.

### Method
GET

### Endpoint
/api/user/folders/[id]

### Path Parameters
- **id** (string) - Required - Folder ID

### Response
#### Success Response (200)
Single Folder object
```

--------------------------------

### Get specific file details

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Retrieves the details of a specific file using its ID.

```APIDOC
## GET /api/user/files/[id]

### Description
Get specific file details.

### Method
GET

### Endpoint
/api/user/files/[id]

### Path Parameters
- **id** (string) - Required - File name or ID

### Response (200)
Single File object.
```

--------------------------------

### Local Datasource Upload Process

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Details the steps involved in uploading a file using the LocalDatasource, including directory creation, file copying, and path generation.

```typescript
async upload(filepath, filename, userId, expiresAt) {
  // 1. Create directory if needed
  //    ${directory}/${userId}/
  
  // 2. Copy file from temp location
  //    copyFile(filepath, targetPath)
  
  // 3. Return relative path for database
  //    return `${userId}/${filename}`
  
  // 4. Schedule deletion if expiresAt provided
  //    tasks.queue('delete-files', { expiresAt })
}
```

--------------------------------

### GET /api/user/tags

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Lists all tags associated with the authenticated user. Returns an array of Tag objects.

```APIDOC
## GET /api/user/tags

### Description
List tags for authenticated user.

### Method
GET

### Endpoint
/api/user/tags

### Response (200)
Array of Tag objects

### Tag Schema
```typescript
{
  id: string;
  userId: string;
  name: string;
  color: string; // Hex color
  createdAt: Date;
  updatedAt: Date;
  files?: Array<{ id: string }>;
}
```
```

--------------------------------

### List URLs API Response

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example JSON response for listing shortened URLs with pagination details.

```json
[
  {
    "id": "url-123",
    "code": "abc123",
    "vanity": "my-project",
    "destination": "https://example.com/…",
    "enabled": true,
    "views": 5,
    "createdAt": "2025-01-05T14:32:01Z"
  }
]
```

--------------------------------

### Run Zipline Control Utility Command

Source: https://github.com/diced/zipline/blob/trunk/README.md

Execute commands using the `zipline-ctl` utility after it has been built. Use `pnpm ctl help` to see available commands.

```bash
pnpm ctl help
```

--------------------------------

### Create Shortened URL API Response

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example JSON response after successfully creating a shortened URL.

```json
{
  "id": "url-123",
  "code": "abc123",
  "vanity": "my-project",
  "destination": "https://example.com/very/long/url",
  "enabled": true,
  "maxViews": 100,
  "views": 0,
  "createdAt": "2025-01-05T14:32:01Z",
  "updatedAt": "2025-01-05T14:32:01Z",
  "url": "https://short.example.com/my-project"
}
```

--------------------------------

### Delete Folder API Request

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Example of an HTTP DELETE request to remove a specific folder by its ID.

```typescript
DELETE /api/user/folders/folder-123 HTTP/1.1
```

--------------------------------

### Accessing Configuration in TypeScript

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/configuration.md

Demonstrates how to import and access configuration values within a TypeScript application, as well as how to reload settings from the database.

```typescript
import { config } from '@/lib/config';

// Accessing current values
const port = config.core.port;
const maxFileSize = config.files.maxFileSize;
const datasourceType = config.datasource.type;

import { reloadSettings } from '@/lib/config';

// Reload settings from the database
await reloadSettings();
```

--------------------------------

### Get Current User

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Fetches the authenticated user's profile information and the current session token.

```APIDOC
## GET /api/user

### Description
Fetch authenticated user profile and current session token.

### Method
GET

### Endpoint
/api/user

### Response
#### Success Response (200)
- **user** (object) - User profile details including id, username, role, timestamps, view settings, quota information, avatar, and OAuth providers.
- **token** (string) - The current session token.
```

--------------------------------

### Get Authenticated User

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Retrieves the currently authenticated user's information along with their associated token.

```APIDOC
## GET /api/user

### Description
Get authenticated user and their token.

### Method
GET

### Endpoint
/api/user

### Authentication
Required

### Response (200)
- **user** (User) - Optional - The user object.
- **token** (string) - Optional - The authentication token.

### Response Example
```json
{
  "user": {
    "id": "string",
    "username": "string",
    "role": "USER" | "ADMIN" | "SUPERADMIN",
    "createdAt": "Date",
    "updatedAt": "Date",
    "sessions": "UserSession[]",
    "oauthProviders": "OAuthProvider[]",
    "totpSecret": "string | null",
    "passkeys": "UserPasskey[]",
    "quota": "UserQuota | null",
    "avatar": "string | null",
    "view": "UserViewSettings",
    "token": "string | null"
  },
  "token": "string"
}
```
```

--------------------------------

### Apply Database Schema Changes (Prototype)

Source: https://github.com/diced/zipline/blob/trunk/README.md

Directly apply schema changes to the database without generating a migration file. This is intended for testing purposes only and should not be used in production environments.

```bash
pnpm db:prototype
```

--------------------------------

### Health Check Endpoint Response

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/middleware-and-plugins.md

The standard JSON response for a successful health check at GET /api/healthcheck.

```json
{
  "ok": true,
  "uptime": 3600,
  "timestamp": "2025-01-05T14:32:01Z"
}
```

--------------------------------

### Get Authenticated User

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Retrieves the currently authenticated user's details and their associated token. Requires authentication.

```typescript
{
  user?: User;
  token?: string;
}
```

--------------------------------

### GET /api/user/urls

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Retrieves a list of all shortened URLs created by the authenticated user, supporting standard pagination parameters.

```APIDOC
## GET /api/user/urls

### Description
List shortened URLs.

### Method
GET

### Endpoint
/api/user/urls

### Query Parameters
Standard pagination (page, perpage)

### Response (200)
Array of URL objects
```

--------------------------------

### Generate Zipline Secrets

Source: https://github.com/diced/zipline/blob/trunk/README.md

Generates a secure PostgreSQL password and a CORE_SECRET for Zipline. The CORE_SECRET is mandatory for Zipline to start.

```bash
echo "POSTGRESQL_PASSWORD=$(openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32 | tr -d '\n')" > .env
echo "CORE_SECRET=$(openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32 | tr -d '\n')" >> .env
```

--------------------------------

### Create Folder

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Creates a new folder for the user. Allows specifying the folder name, public status, parent folder, and initial files to associate.

```APIDOC
## POST /api/user/folders

### Description
Create a new folder for the user.

### Method
POST

### Endpoint
/api/user/folders

#### Request Body
- **name** (string) - Required - The name of the new folder.
- **isPublic** (boolean) - Optional - Whether the folder is public. Defaults to false.
- **parentId** (string | null) - Optional - The ID of the parent folder. Null for root folders.
- **files** (array of strings) - Optional - An array of file IDs to associate with the new folder.

### Request Example
{
  "example": "{
  \"name\": \"New Project\",
  \"isPublic\": false,
  \"parentId\": null,
  \"files\": [\"file-id-1\", \"file-id-2\"]
}"
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the newly created folder.
- **userId** (string) - The identifier of the user who owns the folder.
- **parentId** (string | null) - The identifier of the parent folder, or null if it's a root folder.
- **name** (string) - The name of the folder.
- **isPublic** (boolean) - Indicates if the folder is public.
- **createdAt** (string) - The timestamp when the folder was created.
- **updatedAt** (string) - The timestamp when the folder was last updated.

### Response Example
{
  "example": "{
  \"id\": \"folder-789\",
  \"userId\": \"user-456\",
  \"parentId\": null,
  \"name\": \"New Project\",
  \"isPublic\": false,
  \"createdAt\": \"2025-01-05T14:32:01Z\",
  \"updatedAt\": \"2025-01-05T14:32:01Z\"
}"
}
```

--------------------------------

### Session Creation with iron-session

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/middleware-and-plugins.md

Demonstrates how to create and save user sessions using iron-session for secure, encrypted cookies. This is part of the authentication flow.

```typescript
import { getSession, saveSession } from '@/server/session'

const session = await getSession(req, res);
await saveSession(session, user, refreshToken);
```

--------------------------------

### Datasource Operations

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Provides methods for interacting with the configured datasource, such as uploading, deleting, renaming files, and getting file statistics.

```APIDOC
## Datasource Operations

### Description
Provides methods for interacting with the configured datasource, such as uploading, deleting, renaming files, and getting file statistics.

### Usage
```typescript
import { datasource } from '@/lib/datasource';

// Upload file
const key = await datasource.upload(
  tempPath,
  'document.pdf',
  userId,
  new Date('2025-01-12')
);

// Delete file
await datasource.delete('document.pdf', userId);

// Rename file
await datasource.rename('old.jpg', 'new.jpg');

// Get file size
const { size } = await datasource.stat('document.pdf');
```

### Methods

#### upload(tempPath, filename, userId, expirationDate)

- **Description**: Uploads a file to the configured storage backend.
- **Parameters**:
  - `tempPath` (string) - The temporary path of the file to upload.
  - `filename` (string) - The desired name for the file in storage.
  - `userId` (string) - The ID of the user performing the upload.
  - `expirationDate` (Date) - The date when the file will expire.
- **Returns**: `Promise<string>` - The key or path of the uploaded file.

#### delete(filename, userId)

- **Description**: Deletes a file from the configured storage backend.
- **Parameters**:
  - `filename` (string) - The name of the file to delete.
  - `userId` (string) - The ID of the user performing the deletion.
- **Returns**: `Promise<void>`

#### rename(oldFilename, newFilename)

- **Description**: Renames a file in the configured storage backend.
- **Parameters**:
  - `oldFilename` (string) - The current name of the file.
  - `newFilename` (string) - The new name for the file.
- **Returns**: `Promise<void>`

#### stat(filename)

- **Description**: Retrieves statistics about a file, such as its size.
- **Parameters**:
  - `filename` (string) - The name of the file to get statistics for.
- **Returns**: `Promise<{ size: number }>` - An object containing the file size.
```

--------------------------------

### DigitalOcean Spaces Configuration

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Environment variables for configuring the S3 datasource to connect to DigitalOcean Spaces.

```bash
DATASOURCE_TYPE=s3
DATASOURCE_S3_ACCESS_KEY_ID=...
DATASOURCE_S3_SECRET_ACCESS_KEY=...
DATASOURCE_S3_REGION=nyc3
DATASOURCE_S3_BUCKET=zipline
DATASOURCE_S3_ENDPOINT=https://nyc3.digitaloceanspaces.com
```

--------------------------------

### Build Zipline Control Utility

Source: https://github.com/diced/zipline/blob/trunk/README.md

Compile the `zipline-ctl` command-line utility. This is a prerequisite for running `zipline-ctl` commands.

```bash
pnpm build:server
```

--------------------------------

### List and Search User Files

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Use this endpoint to list files for the authenticated user and apply various filters and search queries. Supports pagination and sorting.

```typescript
{
  page: Array<File>;
  search?: {
    field: 'name' | 'originalName' | 'type' | 'tags' | 'id';
    query: string | string[];
  };
  total?: number;
  pages?: number;
}
```

```typescript
{
  id: string;
  name: string;
  originalName: string | null;
  size: number;
  type: string;
  views: number;
  maxViews: number | null;
  favorite: boolean;
  createdAt: string | Date;
  updatedAt: string | Date;
  deletesAt: string | Date | null;
  password: string | boolean | null;
  folderId: string | null;
  anonymous?: boolean;
  thumbnail?: { path: string } | null;
  tags?: Tag[];
  url?: string;
  similarity?: number;
}
```

--------------------------------

### Test Local Datasource Operations

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Demonstrates basic operations like upload, stat, rename, and delete using the LocalDatasource. Ensure the './test-uploads' directory exists and './temp/file.txt' is available for testing.

```typescript
const datasource = new LocalDatasource('./test-uploads');

// Test upload
const key = await datasource.upload(
  './temp/file.txt',
  'file.txt',
  'test-user-1'
);
// key = 'test-user-1/file.txt'

// Test stat
const { size } = await datasource.stat(key);

// Test rename
await datasource.rename(key, 'test-user-1/renamed.txt');

// Test delete
await datasource.delete('test-user-1/renamed.txt');
```

--------------------------------

### Local Datasource Configuration

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Configuration variables for the local datasource, specifying the storage type and the directory for storing files.

```bash
DATASOURCE_TYPE=local
DATASOURCE_LOCAL_DIRECTORY=/var/lib/zipline/uploads
```

--------------------------------

### Get Current User API Response

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

This JSON structure represents the successful response when fetching the authenticated user's profile and session token.

```json
{
  "user": {
    "id": "user-456",
    "username": "john_doe",
    "role": "USER",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-05T14:32:01Z",
    "view": {
      "enabled": true,
      "align": "center",
      "embed": false
    },
    "quota": {
      "filesQuota": "BY_BYTES",
      "maxBytes": "10gb",
      "maxFiles": 1000,
      "maxUrls": 50
    },
    "avatar": "https://gravatar.com/...",
    "oauthProviders": [
      {
        "provider": "GITHUB",
        "username": "johndoe"
      }
    ]
  },
  "token": "eyJ0eXAi..."
}
```

--------------------------------

### Build Zipline Production Version

Source: https://github.com/diced/zipline/blob/trunk/README.md

Compile Zipline into a production-ready build. This command optimizes the code for deployment.

```bash
pnpm build
```

--------------------------------

### Create User Folder

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/endpoints.md

Creates a new folder for the authenticated user. Allows specifying name, public status, files, and parent folder.

```APIDOC
## POST /api/user/folders

### Description
Create a new folder.

### Method
POST

### Endpoint
/api/user/folders

### Request Body
```json
{
  "name": "string", // Trimmed, min 1 char
  "isPublic": "boolean", // Optional
  "files": ["string"], // File IDs to add, Optional
  "parentId": "string" // Optional
}
```

### Response
#### Success Response (200)
Created Folder object

### Error Responses
- **4007 (404)** - Parent folder not found
- **3003 (403)** - Parent folder doesn't belong to user
```

--------------------------------

### Get or Create Session

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/middleware-and-plugins.md

Use this function to retrieve an existing session or create a new one for the current request. It handles session encryption and cookie management.

```typescript
import { getSession } from '@/server/session'

const session = await getSession(req, res);
```

--------------------------------

### AWS S3 Configuration

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Environment variables for configuring the S3 datasource to connect to AWS S3.

```bash
DATASOURCE_TYPE=s3
DATASOURCE_S3_ACCESS_KEY_ID=AKIA...
DATASOURCE_S3_SECRET_ACCESS_KEY=wJalr...
DATASOURCE_S3_REGION=us-west-2
DATASOURCE_S3_BUCKET=zipline-files
```

--------------------------------

### encryptToken()

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-library-reference.md

Creates an encrypted API token. The format is 'date64.encrypted64'.

```APIDOC
## encryptToken()

### Description
Creates an encrypted API token. The format is 'date64.encrypted64'.

### Function Signature
```typescript
function encryptToken(token: string, secret: string): string
```

### Returns
"date64.encrypted64"

### Example
```typescript
const stored = encryptToken(token, config.core.secret);
```
```

--------------------------------

### List User Folders Query Parameters

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-routes-detailed.md

Available query parameters for filtering and controlling the response of the list folders endpoint.

```typescript
{
  noincl?: boolean;        // Exclude files
  user?: string;           // Another user's folders (permission check)
  parentId?: string;       // Filter by parent
  root?: boolean;          // Root folders only
}
```

--------------------------------

### getDatasource()

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/datasources.md

Initializes and returns a Datasource instance based on the provided configuration. It supports 'local' and 's3' types.

```APIDOC
## getDatasource()

### Description
Initializes and returns a Datasource instance based on the provided configuration. It supports 'local' and 's3' types.

### Signature
```typescript
function getDatasource(config?: Config): Datasource | void
```

### Usage Example
```typescript
import { getDatasource } from '@/lib/datasource';

const config = {
  datasource: {
    type: 'local',
    local: {
      directory: '/path/to/local/storage'
    }
  }
};

const datasource = getDatasource(config);

if (datasource) {
  // Use the datasource
}
```
```

--------------------------------

### Basic Error Response Example

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/errors.md

A standard JSON structure for API errors, including a human-readable error message, a numeric code, and the corresponding HTTP status code.

```json
{
  "error": "E1038: Username already exists",
  "code": 1038,
  "statusCode": 400
}
```

--------------------------------

### findFileByName()

Source: https://github.com/diced/zipline/blob/trunk/_autodocs/api-library-reference.md

Queries for a file by its name or name prefix. It sanitizes the filename, checks for an exact match first, and if extensionless URLs are enabled and no dot is found, it attempts a startsWith match.

```APIDOC
## findFileByName()

### Description
Queries for a file by its name or name prefix. It sanitizes the filename, checks for an exact match first, and if extensionless URLs are enabled and no dot is found, it attempts a startsWith match.

### Function Signature
```typescript
async function findFileByName<TResult>(id: string, query: (where: Prisma.FileWhereInput, orderBy?: Prisma.FileOrderByWithRelationInput) => Promise<TResult | null>): Promise<TResult | null>
```

### Behavior
- Sanitizes filename
- Checks exact name first
- If extensionless URLs enabled and no dot found, tries startsWith

### Example
```typescript
const file = await findFileByName('document', (where) =>
  prisma.file.findFirst({ where })
);
```
```