### Development Installation

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/README.md

Steps to install the extension in development mode, including Python and JupyterLab setup.

```bash
pip install -e .
jupyter labextension develop . --overwrite
jupyter server extension enable jupyter_firefly_extensions
jlpm run build
```

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

### Start Firefly Viewer with Configuration

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/slate-command-ext.md

Usage example for starting the Firefly viewer. It first retrieves the Firefly configuration and then calls the startViewer method on the widget.

```typescript
const { firefly, fireflyURL, fireflyHtmlFile } = await findFirefly();
widget.startViewer(firefly, 'firefly-viewer-tab-id', fireflyURL, fireflyHtmlFile);

```

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

### Install from TestPyPI

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/new-release-procedure.md

Installs the package from the TestPyPI index after uploading a test release. Use this to verify the installation process and package integrity.

```bash
pip uninstall jupyter_firefly_extensions
pip install --verbose --index-url https://testpypi.python.org/pypi jupyter_firefly_extensions
```

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

### Local Development with Firefly Docker Container

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Example demonstrating how to run Firefly in a Docker container and then start JupyterLab with the necessary environment variable configuration for local development.

```bash
docker run -d -p 8080:8080 ipac/firefly:latest
```

```bash
export FIREFLY_URL=http://localhost:8080/firefly
jupyter lab
```

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

### Uploading a File with Query Parameters

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/handler-ts.md

This example shows how to upload a file by making a GET request to a 'sendToFirefly' endpoint with a 'path' query parameter. It demonstrates handling a text response containing a cache key.

```typescript
// Upload file request with query parameter
const filePath = 'path/to/file.fits';
try {
  const response = await requestAPI(
    `sendToFirefly?path=${encodeURIComponent(filePath)}`,
    { method: 'get' }
  );
  const cacheKey = await response.text();
  console.log('File uploaded with key:', cacheKey);
} catch (error) {
  console.error('Upload failed:', error);
}
```

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

### generate_file_names Usage Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Example demonstrating the usage of the generate_file_names static method, showing the list of potential file paths it returns.

```python
paths = generate_file_names('data.fits', '/home/user/notebooks')
# Returns:
# ['/home/user/notebooks/data.fits',
#  '/home/user/notebooks/absolute/data.fits',  # if path looks absolute
#  '/home/user/data.fits']
```

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

### Conda Environment Setup for Jupyter and Firefly

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Creates a conda environment, installs necessary packages including JupyterLab and firefly-client, sets the FIREFLY_URL, and installs the jupyter-firefly-extensions.

```bash
conda create -n jupyter-firefly \
  -c conda-forge \
  python=3.10 \
  jupyterlab \
  firefly-client \
  astropy

conda activate jupyter-firefly

# Set Firefly URL
export FIREFLY_URL=http://localhost:8080/firefly

# Install extension
pip install jupyter-firefly-extensions

# Run
jupyter lab
```

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

### Jupyter Server Configuration Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/SUMMARY.txt

Example of configuring the Jupyter Firefly extensions via the Jupyter server configuration file. This allows for persistent settings across server restarts.

```json
{
  "ServerApp": {
    "jpserver_extensions": {
      "jupyter_firefly_extensions": true
    }
  },
  "Firefly": {
    "server_url": "http://localhost:8081/firefly",
    "auth_token_file": "~/.firefly_token"
  }
}
```

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

### Clone and Install Jupyter Firefly Extensions for Development

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/README.md

Clone the repository, install the package in development mode, and link it with JupyterLab for active development.

```bash
git clone https://github.com/Caltech-IPAC/jupyter_firefly_extensions
cd jupyter_firefly_extensions

# Install package in development mode (changes in python source will reflect automatically)
pip install -e .

# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite

# Enable the server extension
jupyter server extension enable jupyter_firefly_extensions

# Build extension TS/JS source
jlpm run build
```

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

### Install Firefly Client in Development Mode

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/README.md

Install the firefly_client package in editable mode from its source directory. This is useful when developing the client library.

```bash
pip install -e .
```

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

### Making a GET Request to Retrieve Firefly Location Config

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/handler-ts.md

This example demonstrates a simple GET request to the 'fireflyLocation' endpoint to retrieve configuration. It shows how to handle the JSON response and potential errors.

```typescript
import { requestAPI } from './handler';

// Simple GET request to retrieve firefly location config
try {
  const response = await requestAPI('fireflyLocation', { method: 'get' });
  const config = await response.json();
  console.log('Firefly URL:', config.fireflyURL);
} catch (error) {
  console.error('Failed to get Firefly config:', error);
}
```

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

### FitsViewerWidget Usage Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/fits-viewer-ext.md

An example demonstrating how a FitsViewerWidget instance is created. This is primarily for internal use by the widget factory and is not typically called directly by users.

```typescript
// Created automatically by widget factory when FITS file is opened
// Internal usage only - not called directly by users
const widget = new FitsViewerWidget(context);

```

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

### Example Base URL Construction for sendToFirefly

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/endpoints.md

This example shows how the full URL for the 'sendToFirefly' endpoint is constructed by combining the Jupyter server base URL, the extension namespace, and the specific endpoint path with a query parameter.

```url
http://localhost:8888/jupyter-firefly-extensions/sendToFirefly?path=data.fits
```

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

### SendToFireflyHandler Success Response Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Example of a successful response from the SendToFireflyHandler, indicating the cache key for the uploaded file.

```text
${upload-directory}/filename.fits
```

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

### Example Log Entries for sendToFirefly

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/endpoints.md

These are example log entries demonstrating the 'sendToFirefly' endpoint's activity, including upload initiation, progress, and success. They show the logger name and relevant details of the operation.

```log
[I 2024-06-05 14:35:01.234 ServerApp.jupyter_firefly_extensions] sendToFirefly: uploading to http://localhost:8080/firefly
```

```log
[I 2024-06-05 14:35:02.456 ServerApp.jupyter_firefly_extensions] sendToFirefly: starting upload: /home/user/notebooks/data.fits
```

```log
[I 2024-06-05 14:35:03.789 ServerApp.jupyter_firefly_extensions] sendToFirefly: upload succeeded; file on server key: ${firefly_upload/2024/06/05/xyz}
```

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

### Setup Handlers for Extension

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/extension-initialization.md

Initializes the extension's HTTP endpoints, configures Firefly connection details, and registers handlers for sending data and retrieving URL data.

```python
def setup_handlers(server_app):
    """
    Called when the extension is loaded.
    
    Args:
        server_app (NotebookWebApplication): handle to the Notebook webserver instance.
    """
    global firefly_config
    
    # Configuration sourcing
    logger = server_app.log.getChild('jupyter_firefly_extensions')
    config_url = server_app.config.get('Firefly', {}).get('url', 
                                       'http://localhost:8080/firefly')
    
    # Precedence: Environment > Config > Default
    url = os.environ.get('FIREFLY_URL', config_url)
    html_file = os.environ.get('FIREFLY_HTML')
    
    # Store configuration
    web_app = server_app.web_app
    web_app.settings['fireflyURL'] = url
    web_app.settings['fireflyHtmlFile'] = html_file
    
    # Generate session channel
    hostname = platform.node()
    timestamp = int(time.time())
    random_num = random.randint(1, 100)
    channel = f'ffChan-{hostname}-{timestamp}-{random_num}'
    
    # Create config dict
    firefly_config = {
        'fireflyLabExtension': 'true',
        'fireflyURL': url,
        'fireflyHtmlFile': html_file,
        'fireflyChannel': channel
    }
    
    # Set environment variables for subprocesses
    os.environ['fireflyChannelLab'] = channel
    os.environ['fireflyURLLab'] = url
    os.environ['fireflyHtmlFile'] = html_file or ''
    os.environ['fireflyLabExtension'] = 'true'
    
    # Register HTTP endpoints
    host_pattern = '.*$'
    send_pattern = url_path_join(
        web_app.settings['base_url'],
        'jupyter-firefly-extensions',
        'sendToFirefly'
    )
    get_ff_data_pattern = url_path_join(
        web_app.settings['base_url'],
        'jupyter-firefly-extensions',
        'fireflyLocation'
    )
    
    web_app.add_handlers(host_pattern, [ 
        (send_pattern, SendToFireflyHandler, {
            'notebook_dir': server_app.notebook_dir,
            'firefly_url': url,
            'logger': logger
        }),
        (get_ff_data_pattern, GetFireflyUrlData, {
            'logger': logger
        })
    ])
```

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

### Install Jupyter Firefly Extensions

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/README.md

Install the jupyter-firefly-extensions package using pip in your activated environment.

```bash
pip install jupyter-firefly-extensions
```

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

### HTTP Request Example (Python)

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/SUMMARY.txt

Example of making an HTTP request using Python's 'requests' library to upload a file to the Firefly server. This is a common pattern for server-side or script-based interactions.

```python
import requests

url = "http://localhost:8888/firefly/upload"
files = {'file': open('/path/to/your/file.fits', 'rb')}

response = requests.post(url, files=files)

if response.status_code == 200:
  print(response.json())
else:
  print(f"Error: {response.status_code}")
```

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

### Firefly Configuration Structure Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Illustrates the expected structure of the firefly_config dictionary, including keys for enabling the Firefly lab extension, specifying the Firefly URL, channel, and an optional HTML file.

```python
{
  'fireflyLabExtension': 'true',
  'fireflyURL': 'http://localhost:8080/firefly',
  'fireflyChannel': 'ffChan-hostname-timestamp-random',
  'fireflyHtmlFile': ''  # or custom value
}
```

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

### Example Usage of findFirefly()

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/types.md

Demonstrates how to retrieve and use the Firefly configuration object obtained from `findFirefly()`. Shows accessing the Firefly URL, channel, and action dispatcher.

```typescript
const config = await findFirefly();
console.log(config.fireflyURL);      // "http://localhost:8080/firefly"
console.log(config.channel);         // "ffChan-myhost-1717584901-42"
console.log(config.firefly.action);  // Firefly action dispatcher
```

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

### Example Usage of DocumentRegistry.IContext

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/types.md

Demonstrates how to use the `DocumentRegistry.IContext` interface within a constructor to access the file path and connect to content change signals.

```typescript
constructor(context: DocumentRegistry.IContext<DocumentModel>) {
  this.filename = context.path;
  context.model.contentChanged.connect(this.renderModel, this);
}
```

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

### HTTP Request Example (TypeScript)

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/SUMMARY.txt

Example of making an HTTP request using TypeScript to upload a file to the Firefly server. This demonstrates client-side interaction with the extension's API.

```typescript
async function uploadFile(file: File) {
  const formData = new FormData();
  formData.append('file', file);

  const response = await fetch('/firefly/upload', {
    method: 'POST',
    body: formData,
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}
```

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

### SendToFireflyHandler Logging Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Example log messages generated by the SendToFireflyHandler during file upload operations, showing the upload process and success.

```text
ServerApp.jupyter_firefly_extensions: sendToFirefly: uploading to http://localhost:8080/firefly
ServerApp.jupyter_firefly_extensions: sendToFirefly: starting upload: /path/to/file.fits
ServerApp.jupyter_firefly_extensions: sendToFirefly: upload succeeded; file on server key: ${cache/key}
```

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

### List Jupyter Server Extensions

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/README.md

Command to display a list of all installed Jupyter server extensions.

```bash
jupyter server extension list
```

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

### Setup Function for Jupyter Firefly Extensions

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Initializes the extension's HTTP endpoints and Firefly configuration. This function is called during server startup and reads configuration from environment variables or Jupyter config.

```python
def setup_handlers(server_app: NotebookWebApplication) -> None:
    pass
```

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

### SendToFireflyHandler Failure Response Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Example of a failed response from the SendToFireflyHandler, showing the error message and the paths that were searched.

```text
FAILED: /path/to/notebook_dir/file.fits, /absolute/path/to/file.fits, /home/user/file.fits
```

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

### HTTP Request Example (cURL)

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/SUMMARY.txt

Example of making an HTTP request using cURL to interact with the Firefly server. This is useful for testing API endpoints or scripting interactions.

```bash
curl -X POST \
  http://localhost:8888/firefly/upload \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/your/file.fits'
```

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

### List Installed JupyterLab Extensions

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/index-ts.md

Displays a list of all installed JupyterLab extensions to help verify if the target extension is recognized.

```bash
jupyter labextension list
```

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

### Configure PyPI Upload Credentials

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/new-release-procedure.md

Sets up the .pypirc file for authenticating with PyPI using an API token. This is a one-time setup for automated uploads.

```ini
[distutils]
index-servers =
   jupyter-firefly-extensions

[jupyter-firefly-extensions]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-token-you-created
```

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

### List Jupyter Lab Extensions

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/README.md

Command to display a list of all installed Jupyter Lab extensions.

```bash
jupyter lab extension list
```

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

### Connecting to Content Changed Signal Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/types.md

An example demonstrating how to connect a callback function to the 'contentChanged' signal of a document context. The provided callback function will be executed whenever the document's content is modified.

```typescript
context.model.contentChanged.connect(this.renderModel, this);
// this.renderModel is called whenever content changes
```

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

### Remote Firefly Server with Authentication

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Example for connecting to a remote Firefly server and providing authentication credentials using environment variables for both the URL and the access token.

```bash
export FIREFLY_URL=https://firefly.example.com/firefly
export ACCESS_TOKEN=abc123defghijk
jupyter lab
```

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

### Development with Python Config

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Example of configuring the Firefly URL using a Python configuration file for development purposes. It also shows how to import os and socket, though their direct use in this snippet is not shown.

```python
import os
import socket
```

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

### Frontend Usage Example for SendToFireflyHandler

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Demonstrates how a frontend application can call the sendToFirefly endpoint to upload a file and retrieve its cache key.

```typescript
const filePath = 'data/sample.parquet';
const response = await requestAPI(
  `sendToFirefly?path=${encodeURIComponent(filePath)}`
);
const cacheKey = await response.text();
if (cacheKey.startsWith('${')) {
  console.log('File uploaded:', cacheKey);
}
```

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

### Build Python Distribution

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/new-release-procedure.md

Builds the Python distribution package, which includes the prebuilt extension. Ensure 'build' is installed and run from the package root.

```bash
pip install --upgrade build
python -m build
```

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

### Dispose FitsViewerWidget Usage Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/fits-viewer-ext.md

An example showing how to manually dispose of a FitsViewerWidget instance. This is typically handled automatically by JupyterLab when the widget is no longer needed.

```typescript
widget.dispose(); // Called automatically by JupyterLab

```

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

### Python Handler Example

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/SUMMARY.txt

Example of a Python handler for the Jupyter Firefly extensions. This demonstrates how to define endpoints and handle requests within the Jupyter server environment.

```python
from jupyter_server.base.handlers import APIHandler
from jupyter_server.utils import url_path_join
import tornado.web

class FireflyUploadHandler(APIHandler):
    @tornado.web.authenticated
    async def post(self):
        file_info = self.request.files.get('file', [None])[0]
        if not file_info:
            raise tornado.web.HTTPError(400, 'No file uploaded')
        
        # Process the file (e.g., save it, analyze it)
        filename = file_info['filename']
        content = file_info['body']
        
        self.finish({'message': f'File {filename} uploaded successfully', 'size': len(content)})

def setup_handlers(web_app, url_path):
    host_pattern = "r'.*'"
    base_url = web_app.settings['base_url']
    
    handlers = [
        (url_path_join(base_url, url_path, 'upload'), FireflyUploadHandler)
    ]
    
    web_app.add_handlers(host_pattern, handlers)
```

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

### Run Jupyter Lab

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/README.md

Command to start the JupyterLab application.

```bash
jupyter lab
```

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

### Auto-Start Behavior for Extensions

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/extension-initialization.md

Specifies that extensions should automatically start on JupyterLab startup. This enables immediate availability of commands and file handlers, with Firefly loading deferred until first use.

```typescript
autoStart: true
```

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

### FireflyUtilMethods

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/types.md

Offers utility methods for interacting with Firefly, including adding action listeners, starting the application, and fetching data from URLs.

```APIDOC
## FireflyUtilMethods

### Description
Offers utility methods for interacting with Firefly, including adding action listeners, starting the application, and fetching data from URLs.

### Methods

#### `addActionListener(actions: string[], callback: (action: any) => void): void`
Adds a listener for specified actions.

#### `startAsAppFromApi(elementId: string, props: object): ControlApp`
Starts Firefly as an application from a given HTML element.

#### `fetchUrl(url: string, options: FetchOptions): Promise<Response>`
Fetches data from a given URL.
```

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

### Instantiate and Add SlateRootWidget

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/slate-command-ext.md

Example of how to create and add a SlateRootWidget to the JupyterLab application shell. This is typically done internally by the extension.

```typescript
// Created internally by openSlateSingleOnly()
const widget = new SlateRootWidget('firefly-viewer-tab-id');
app.shell.add(widget, 'main');

```

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

### Upload Distribution to PyPI

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/new-release-procedure.md

Uploads the built distribution files (from the dist directory) to the Python Package Index using twine. Ensure twine is installed and PyPI credentials are configured.

```bash
pip install --upgrade twine
twine upload dist/* --repository jupyter-firefly-extensions
```

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

### Start Jupyter Lab with Autoreload

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/README.md

Run JupyterLab with the --autoreload flag to enable automatic reloading of Python source code changes.

```bash
jupyter lab --autoreload
```

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

### JupyterLab Extension Plugin Definitions

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/extension-initialization.md

Defines three example JupyterFrontEndPlugin objects for a JupyterLab extension. Each plugin specifies its ID, description, auto-start behavior, required services, and activation function.

```typescript
const showSlateExt: JupyterFrontEndPlugin<void> = {
  id: 'jupyter_firefly_extensions:showSlate',
  description: 'Show Firefly Viewer',
  autoStart: true,                    // Activate without user action
  requires: [ICommandPalette],        // Required service
  optional: [ILauncher],              // Optional service
  activate: activateSlateCommandExt   // Activation function
};

const fitsViewerExt: JupyterFrontEndPlugin<void> = {
  id: 'jupyter_firefly_extensions:fitsviewer',
  description: 'View a FITS file',
  autoStart: true,
  requires: [ILayoutRestorer],
  activate: activateFitsViewerExt
};

const anyFileViewerExt: JupyterFrontEndPlugin<void> = {
  id: 'jupyter_firefly_extensions:anyfileviewer',
  description: 'Open files with Firefly Viewer',
  autoStart: true,
  requires: [ILayoutRestorer],
  activate: activateAnyFileViewerExt
};

export default [showSlateExt, fitsViewerExt, anyFileViewerExt];
```

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

### setup_handlers

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Initializes the extension's HTTP endpoints and Firefly configuration. This function is called by the Jupyter server during extension loading.

```APIDOC
## setup_handlers()

### Description
Initializes the extension's HTTP endpoints and Firefly configuration.

### Method Signature
```python
def setup_handlers(server_app: NotebookWebApplication) -> None
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Called By
- `_load_jupyter_server_extension()` in `__init__.py` during server startup

### Configuration Sources (precedence order)
1. Environment variable `FIREFLY_URL` (highest priority)
2. Jupyter config: `c.Firefly.url` in `jupyter_config.py`
3. Default: `http://localhost:8080/firefly`

### Optional Configuration
- `FIREFLY_HTML` environment variable for custom Firefly HTML file

### Behavior
1. Reads Firefly URL from config, env var, or default.
2. Generates unique channel ID for this JupyterLab session: `ffChan-{hostname}-{timestamp}-{random}`.
3. Stores configuration in module-level `firefly_config` dict.
4. Registers HTTP endpoints: `GET /jupyter-firefly-extensions/sendToFirefly` and `GET /jupyter-firefly-extensions/fireflyLocation`.
5. Passes configuration to the page for frontend access.
6. Sets environment variables for Python subprocesses.
7. Logs configuration details to Jupyter server logs.

### Environment Variables Set
- `fireflyChannelLab`: Generated channel ID
- `fireflyURLLab`: Firefly server URL
- `fireflyHtmlFile`: HTML file or empty string
- `fireflyLabExtension`: `'true'`

### Source
`jupyter_firefly_extensions/handlers.py:94-158`
```

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

### Configure Firefly URL via Environment Variable

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/endpoints.md

Set the Firefly server URL using the `FIREFLY_URL` environment variable before starting JupyterLab. This method takes precedence over configuration files.

```bash
export FIREFLY_URL=http://localhost:8080/firefly
jupyter lab
```

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

### Firefly Configuration API Response

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/README.md

Example JSON response from the GET /jupyter-firefly-extensions/fireflyLocation endpoint, detailing Firefly connection and server information.

```json
{
  "fireflyURL": "http://localhost:8080/firefly",
  "fireflyChannel": "ffChan-hostname-...",
  "fireflyLabExtension": "true",
  "fireflyHtmlFile": ""
}
```

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

### JupyterHub Configuration for Multiple Firefly Servers

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Example of configuring JupyterHub to point to a specific Firefly server URL using a system-wide JSON configuration file. This allows users to share the same Firefly backend.

```json
{
  "Firefly": {
    "url": "http://firefly-hub.example.com:8080/firefly"
  }
}
```

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

### Firefly Client Initialization with Access Token

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Demonstrates how to use the _get_access_token function to obtain a token and then initialize a FireflyClient. This is used internally by SendToFireflyHandler.get() for authentication.

```python
access_token = _get_access_token()
fc = FireflyClient.make_client(
  url=self.firefly_url,
  token=access_token,
  launch_browser=False
)
```

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

### GET Method for GetFireflyUrlData Handler

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Handles GET requests to the /jupyter-firefly-extensions/fireflyLocation endpoint. Returns the global firefly_config dictionary as JSON.

```python
@tornado.web.authenticated
def get(self):
    pass
```

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

### SendToFireflyHandler get Method Signature

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Signature for the get method of SendToFireflyHandler, the main handler for file upload requests, protected by authentication.

```python
@tornado.web.authenticated
def get(self)
```

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

### Initialize Firefly Client with Access Token

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/endpoints.md

When the Firefly server requires authentication, initialize the `FireflyClient` with an access token obtained from a file or environment variable. Ensure `launch_browser` is set appropriately.

```python
token = _get_access_token()
fc = FireflyClient.make_client(
  url=self.firefly_url,
  token=token,
  launch_browser=False
)
```

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

### Initialize Firefly Client

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/examples/slate-demo-explicit.ipynb

Initializes the Firefly client for use in a lab environment. This is the first step before interacting with Firefly.

```python
from firefly_client import FireflyClient
fc = FireflyClient.make_lab_client()
```

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

### Get Firefly Viewer Configuration

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/endpoints.md

Retrieves Firefly viewer configuration and connection details. Use this to get the base URL and channel ID for Firefly.

```typescript
import { requestAPI } from './handler';

async function getFfConfig() {
  try {
    const response = await requestAPI('fireflyLocation', { method: 'get' });
    const config = await response.json();
    console.log('Firefly Server:', config.fireflyURL);
    console.log('Channel:', config.fireflyChannel);
    return config;
  } catch (error) {
    console.error('Failed to get Firefly config:', error);
    throw error;
  }
}
```

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

### JupyterLab Extension Lifecycle Flow

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/index-ts.md

Illustrates the sequence of events from JupyterLab startup to extension activation and registration.

```text
JupyterLab Startup
    ↓
Load package.json → "main": "lib/index.js"
    ↓
Evaluate index.ts (compiled to index.js)
    ↓
Import activation functions from sub-modules
    ↓
Export plugin array [showSlateExt, fitsViewerExt, anyFileViewerExt]
    ↓
For each plugin:
  1. Check if required services are available
  2. Call activate() function with app and services
  3. Plugin performs registration (commands, file types, etc.)
    ↓
Extensions are now active and ready to use
```

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

### Build Production Extension

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/new-release-procedure.md

Creates a production-ready build of the JupyterLab extension. This command should be run from the root directory of the package.

```bash
jlpm build:prod
```

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

### Load Jupyter Server Extension

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/extension-initialization.md

Activates the extension by registering API handlers for frontend communication. Logs a registration message upon successful activation.

```python
def _load_jupyter_server_extension(server_app):
    """
    Registers the API handler to receive HTTP requests from the frontend extension.
    
    Parameters
    ----------
    server_app: jupyterlab.labapp.LabApp
        JupyterLab application instance
    """
    setup_handlers(server_app)
    name = "jupyter_firefly_extensions"
    server_app.log.info(f"Registered {name} server extension")
```

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

### Build Production Build

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/README.md

Command to perform a production build for the project.

```bash
jlpm build:prod # Production build
```

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

### Build Firefly for Development

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Rebuilds the Firefly server for a development environment using Gradle.

```bash
cd firefly
gradle clean
gradle -Penv=dev firefly:bAD  # Build and deploy for development
```

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

### Get Firefly Location

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/README.md

Retrieves the Firefly configuration and server details, including the Firefly URL and channel information.

```APIDOC
## GET /jupyter-firefly-extensions/fireflyLocation

### Description
Returns Firefly configuration and server details.

### Method
GET

### Endpoint
/jupyter-firefly-extensions/fireflyLocation

### Response
#### Success Response (200)
- **fireflyURL** (string) - The URL of the Firefly server.
- **fireflyChannel** (string) - The Firefly communication channel.
- **fireflyLabExtension** (string) - Indicates if the Firefly Lab extension is enabled.
- **fireflyHtmlFile** (string) - Path to the Firefly HTML file.

#### Response Example
```json
{
  "fireflyURL": "http://localhost:8080/firefly",
  "fireflyChannel": "ffChan-hostname-...",
  "fireflyLabExtension": "true",
  "fireflyHtmlFile": ""
}
```
```

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

### Initialize Firefly Client

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/examples/slate-demo-explicit2.ipynb

Initializes the Firefly client for use within a Jupyter environment. Ensure the FIREFLY_URL environment variable is set or accessible.

```python
from firefly_client import FireflyClient
import astropy.utils.data

fc = FireflyClient.make_lab_client(start_browser_tab=False)
```

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

### GET /jupyter-firefly-extensions/sendToFirefly

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/endpoints.md

Uploads an astronomical data file to the Firefly server and returns a server-side cache key for referencing the uploaded file.

```APIDOC
## GET /jupyter-firefly-extensions/sendToFirefly

### Description
Uploads an astronomical data file to the Firefly server and returns the server-side cache key.

### Method
GET

### Endpoint
/jupyter-firefly-extensions/sendToFirefly

### Parameters
#### Query Parameters
- **path** (string) - Required - File path relative to notebook directory or absolute path (URL-encoded)

### Request Headers
```
Accept: text/plain
X-Requested-With: XMLHttpRequest
```

### Response
#### Success Response (200 OK)
Returns a cache key string starting with `${`.

#### Response Example
```
${firefly_upload/2024/06/05/abc123_sample_data.fits}
```

#### Failure Response
Returns error message starting with `FAILED:`.

#### Failure Response Example
```
FAILED: /home/user/notebooks/data.fits, /data.fits, /home/user/data.fits
```

### Error Responses
- **200 OK** - File not found - returns `FAILED:` response (not a true HTTP error)
- **401 Unauthorized** - User is not authenticated
- **403 Forbidden** - User lacks permission
- **400 Bad Request** - Missing `path` parameter
```

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

### Server Base URL Construction Logic

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/handler-ts.md

Illustrates how the server base URL is constructed by joining the Jupyter server base URL with the 'jupyter-firefly-extensions' namespace and the provided endpoint using URLExt.join().

```plaintext
{baseUrl}/jupyter-firefly-extensions/{endPoint}
```

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

### Clean and Build Firefly Development Environment

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/README.md

Use this command to clean the existing Firefly build and then build and deploy it in the development environment. This is useful for resolving rendering issues with local Firefly servers.

```bash
gradle clean
gradle -Penv=dev firefly:bAD
```

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

### Configure Firefly Access Token via File

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Securely provide a Firefly server access token by storing it in a file named `.access_token`. Ensure the file has restricted permissions (600) for security.

```bash
echo "your-access-token-here" > ~/.access_token
chmod 600 ~/.access_token
```

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

### Frontend API Call to Get Firefly Configuration

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Demonstrates how a frontend application can call the Firefly location API endpoint and access the returned configuration.

```typescript
const response = await requestAPI('fireflyLocation');
const config = await response.json();
console.log('Firefly URL:', config.fireflyURL);
```

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

### List Jupyter Configuration Directories

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Displays all directories where Jupyter looks for configuration files.

```bash
jupyter --paths
```

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

### Activate Any File Viewer Extension

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/any-file-viewer-ext.md

Extension activation function called by JupyterLab on startup. Registers supported file types and installs a global error handler.

```typescript
export function activateAnyFileViewerExt(
  app: JupyterLab,
  _restorer: ILayoutRestorer
): void

```

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

### Add Heatmap to Slate Viewer

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/examples/slate-demo-explicit2.ipynb

Creates a heatmap visualization in a specified cell, displaying density relationships between different photometric bands from the 'wiseCatTbl'.

```python
# Add second chart - heatmap  (plot.ly direct plot) 
# in cell 2, 0, 2, 3
viewer_id = 'heatMapContainer'
r = fc.add_cell(2, 0, 2, 3,'xyPlots', viewer_id)

if r['success']:
    dataHM = [
                {
                    'type': 'fireflyHeatmap',
                    'name': 'w1 vs. w2',
                    'tbl_id': 'wiseCatTbl',
                    'x': "tables::w1mpro",
                    'y': "tables::w2mpro",
                    'colorscale': 'Blues'
                },
                {
                    'type': 'fireflyHeatmap',
                    'name': 'w1 vs. w3',
                    'tbl_id': 'wiseCatTbl',
                    'x': "tables::w1mpro",
                    'y': "tables::w3mpro",
                    'colorscale': 'Reds',
                    'reversescale': True
                },
                {
                    'type': 'fireflyHeatmap',
                    'name': 'w1 vs. w4',
                    'tbl_id': 'wiseCatTbl',
                    'x': "tables::w1mpro",
                    'y': "tables::w4mpro",
                    'colorscale': 'Greens'
                }]

    layout_hm = {'title': 'Magnitude-magnitude densities', 
                 'xaxis': {'title': 'w1 photometry (mag)'}, 'yaxis': {'title': ''},
                 'firefly': {'xaxis': {'min': 5, 'max': 20}, 'yaxis': {'min': 4, 'max': 18}}}  

    fc.show_chart(group_id=viewer_id, layout=layout_hm, data=dataHM)
```

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

### API Handler Class

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/types.md

The base handler class for API endpoints in Jupyter Server. It provides authenticated GET and POST methods and includes a logger instance.

```python
class APIHandler(tornado.web.RequestHandler):
  log: logging.Logger
  
  @tornado.web.authenticated
  def get(self): ...
  
  @tornado.web.authenticated  
  def post(self): ...
```

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

### GET /jupyter-firefly-extensions/fireflyLocation

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/endpoints.md

Retrieves Firefly viewer configuration and connection details, including the Firefly server URL and a unique channel ID for the current JupyterLab session.

```APIDOC
## GET /jupyter-firefly-extensions/fireflyLocation

### Description
Retrieves Firefly viewer configuration and connection details.

### Method
GET

### Endpoint
/jupyter-firefly-extensions/fireflyLocation

### Parameters
#### Query Parameters
None

### Request Headers
```
Accept: application/json
X-Requested-With: XMLHttpRequest
```

### Response
#### Success Response (200 OK)
- **fireflyLabExtension** (string) - Extension availability marker (always `"true"` when responding)
- **fireflyURL** (string) - Base URL of the Firefly server (e.g., `http://localhost:8080/firefly`)
- **fireflyChannel** (string) - Unique channel ID for this JupyterLab session (format: `ffChan-{hostname}-{unix_timestamp}-{random}`)
- **fireflyHtmlFile** (string) - Custom Firefly HTML file name if configured, empty string otherwise

#### Response Example
```json
{
  "fireflyLabExtension": "true",
  "fireflyURL": "http://localhost:8080/firefly",
  "fireflyChannel": "ffChan-hostname-1717584901-42",
  "fireflyHtmlFile": ""
}
```

### Error Responses
- **401 Unauthorized** - User is not authenticated with Jupyter Server
- **403 Forbidden** - User lacks permission to access server extension
```

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

### File Structure Overview

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/README.md

Illustrates the directory structure of the jupyter_firefly_extensions project, including TypeScript source, Python package, and configuration files.

```text
jupyter_firefly_extensions/
  ├── src/                          # TypeScript source
  │   ├── index.ts                 # Entry point
  │   ├── SlateCommandExt.js       # Firefly tab
  │   ├── FitsViewerExt.js         # FITS viewer
  │   ├── AnyFileViewerExt.js      # Multi-format viewer
  │   ├── FireflyCommonUtils.js    # Utilities
  │   ├── handler.ts               # API wrapper
  │   └── svg.d.ts                 # Type definitions
  ├── jupyter_firefly_extensions/  # Python package
  │   ├── __init__.py              # Extension setup
  │   ├── handlers.py              # HTTP handlers
  │   ├── _version.py              # Version info
  │   └── tests/                   # Python tests
  ├── package.json                 # NPM configuration
  ├── pyproject.toml              # Python build config
  ├── tsconfig.json               # TypeScript config
  └── README.md                   # User documentation
```

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

### Get Access Token Function Signature

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Defines the signature for the private function _get_access_token, which retrieves an access token for Firefly server authentication. It returns an optional string.

```python
def _get_access_token() -> Optional[str]
```

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

### Build Development Build

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/README.md

Command to perform a development build for the project.

```bash
jlpm build       # Dev build
```

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

### SendToFireflyHandler Class Definition

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

Defines the SendToFireflyHandler class, inheriting from APIHandler, with methods for initialization, handling GET requests, checking file readability, and generating file names.

```python
class SendToFireflyHandler(APIHandler):
  def initialize(self, notebook_dir, firefly_url, logger=None)
  @tornado.web.authenticated
  def get(self)
  @staticmethod
  def can_read(f: str) -> bool
  @staticmethod
  def generate_file_names(path: str, notebook_dir: str) -> List[str]
```

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

### Clean Distribution and Build Files

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/new-release-procedure.md

Removes old distribution and build artifacts before creating a new release. Ensure you are in the root directory of the package.

```bash
rm -rf dist/*
jlpm clean:all
```

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

### Get Firefly Location Configuration

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/firefly-common-utils.md

Fetches the Firefly configuration from the server, including the URL, channel, and HTML file. This endpoint is cached to avoid redundant server requests.

```APIDOC
## GET /jupyter-firefly-extensions/fireflyLocation

### Description
Retrieves the Firefly server configuration, including the URL, channel, and HTML file path. This data is cached on the client to improve performance for subsequent calls.

### Method
GET

### Endpoint
/jupyter-firefly-extensions/fireflyLocation

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **fireflyURL** (string) - The base URL for the Firefly service.
- **fireflyChannel** (string) - The communication channel for Firefly.
- **fireflyHtmlFile** (string) - The path to the main HTML file for Firefly.

#### Response Example
{
  "fireflyURL": "http://example.com/firefly",
  "fireflyChannel": "ws://example.com/firefly/channel",
  "fireflyHtmlFile": "/path/to/firefly.html"
}
```

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

### Firefly Utility Methods Interface

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/types.md

Defines common utility methods available in Firefly. Use these for tasks such as adding action listeners, starting the app, or fetching URLs.

```typescript
interface FireflyUtilMethods {
  addActionListener(actions: string[], callback: (action: any) => void): void
  startAsAppFromApi(elementId: string, props: object): ControlApp
  fetchUrl(url: string, options: FetchOptions): Promise<Response>
}
```

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

### RequestInit Interface for Fetch API

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/types.md

Defines the structure for request initialization options, mirroring the standard Fetch API's RequestInit interface. Use this to configure parameters like method, headers, and cache behavior for network requests.

```typescript
interface RequestInit {
  method?: string
  headers?: Record<string, string>
  body?: string | Blob
  mode?: 'cors' | 'no-cors' | 'same-origin'
  credentials?: 'omit' | 'same-origin' | 'include'
  cache?: 'default' | 'no-store' | 'reload' | 'no-cache' | 'force-cache'
}
```

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

### SlateRootWidget Constructor

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/slate-command-ext.md

Creates a JupyterLab widget for the Firefly Viewer. It initializes the DOM element, sets the widget title, loads Firefly configuration, and starts the viewer asynchronously.

```typescript
export class SlateRootWidget extends Widget {
  constructor(id: string, fireflyHtmlFile?: string)
  startViewer(firefly: Object, id: string, fireflyURL: string, fireflyHtmlFile: string): void
  dispose(): void
  close(): void
  activate(): void
}

```

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

### Development Environment Configuration

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Sets the Firefly URL for development and enables debug mode with autoreload for JupyterLab.

```bash
export FIREFLY_URL=http://localhost:8080/firefly
export DEBUG=1
jupyter lab --autoreload
```

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

### Project File Organization

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/TABLE_OF_CONTENTS.md

Illustrates the directory structure of the Jupyter Firefly Extensions project, highlighting the location of key markdown files and the API reference directory.

```text
output/
├── README.md                         ← START HERE
├── TABLE_OF_CONTENTS.md             ← You are here
├── Configuration.md
├── Endpoints.md
├── Extension-Initialization.md
├── Types.md
└── api-reference/
    ├── index-ts.md
    ├── handler-ts.md
    ├── firefly-common-utils.md
    ├── slate-command-ext.md
    ├── fits-viewer-ext.md
    ├── any-file-viewer-ext.md
    └── python-handlers.md
```

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

### Example Server Response for Firefly Location

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/types.md

Illustrates a typical JSON response from the server's `/fireflyLocation` endpoint, detailing the Firefly extension's configuration and connection parameters.

```json
{
  "fireflyLabExtension": "true",
  "fireflyURL": "http://localhost:8080/firefly",
  "fireflyChannel": "ffChan-hostname-1717584901-42",
  "fireflyHtmlFile": ""
}
```

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

### Activate Slate Command Extension

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/extension-initialization.md

Activation function for the 'Show Firefly Viewer' command. It loads Firefly configuration, sets up action listeners, registers a command, and adds it to the palette and launcher.

```typescript
export function activateSlateCommandExt(app, palette, launcher) {
  // 1. Load Firefly configuration
  findFirefly().then( (ffConfig) => {
    const {firefly}= ffConfig;
    
    // 2. Set up action listeners from Firefly
    firefly.util.addActionListener(['StartLabWindow'], (action) => {
      openSlateSingleOnly(app, TAB_ID, action.payload?.fireflyHtmlFile);
    });
    firefly.util.addActionListener(['StartBrowserTab'], (action) => {
      firefly.setViewerConfig(firefly.ViewerType.Grid);
      firefly.getViewer(action.payload.channel).openViewer();
    });
  });

  // 3. Register command
  app.commands.addCommand(SLATE_CMD_ID, {
    label: SLATE_CMD_LABEL,
    caption: SLATE_CMD_CAPTION,
    icon: new LabIcon({...}),
    isEnabled: () => true,
    execute: () => {
      openSlateSingleOnly(app, TAB_ID);
    }
  });

  // 4. Add to palette
  palette.addItem({ command: SLATE_CMD_ID, category: 'Firefly' });
  
  // 5. Add to launcher if available
  if (launcher) launcher.add({ command: SLATE_CMD_ID, category: 'Firefly' });
}
```

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

### Configure Firefly Access Token via Environment Variable

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/configuration.md

Provide a Firefly server access token using the `ACCESS_TOKEN` environment variable. This method is prioritized over reading from an access token file.

```bash
export ACCESS_TOKEN=your-access-token-here
jupyter lab
```

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

### FITS File Type Definition

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/types.md

An example of a FileTypeSpec for FITS files. This configuration specifies the name, display name, format, MIME type, and file extensions associated with FITS files.

```typescript
const fitsIFileType: FileTypeSpec = {
  name: 'FITS',
  displayName: 'FITS file',
  fileFormat: null,
  format: 'base64',
  mimeTypes: ['application/fits'],
  extensions: ['.fits']
}
```

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

### JupyterLab Extension Entry Point

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/index-ts.md

Specifies the main JavaScript file for a JupyterLab extension in package.json.

```json
"main": "lib/index.js"
```

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

### SendToFireflyHandler

Source: https://github.com/caltech-ipac/jupyter_firefly_extensions/blob/master/_autodocs/api-reference/python-handlers.md

HTTP handler that uploads files to the Firefly server. It handles GET requests to upload a specified file and returns a cache key upon success or an error message on failure.

```APIDOC
## GET /jupyter-firefly-extensions/sendToFirefly

### Description
Uploads a specified file to the Firefly server and returns a cache key for the uploaded file.

### Method
GET

### Endpoint
/jupyter-firefly-extensions/sendToFirefly?path=...

### Parameters
#### Query Parameters
- **path** (string) - Required - File path to upload (URL-encoded)

### Request Example
```typescript
const filePath = 'data/sample.parquet';
const response = await requestAPI(
  `sendToFirefly?path=${encodeURIComponent(filePath)}`
);
const cacheKey = await response.text();
if (cacheKey.startsWith('${')) {
  console.log('File uploaded:', cacheKey);
}
```

### Response
#### Success Response (200)
Cache key for the uploaded file (e.g., `${upload-directory}/filename.fits`)

#### Response Example
```
${upload-directory}/filename.fits
```

#### Error Response
- **401 Unauthorized** - User not authenticated
- **403 Forbidden** - User lacks permission
- **400 Bad Request** - Missing or invalid `path` parameter
- **Failure Message** - Error message starting with `FAILED:` (e.g., `FAILED: /path/to/notebook_dir/file.fits`)
```