# Cat API Documentation

## Overview

The Cat API provides endpoints for uploading CV documents, scripts, and retrieving the latest images for a given client from Google Cloud Storage. These endpoints are designed to support dynamic web content management and client-specific customizations.

## Authentication

*Not required*
## Base URL

`https://asia-east1-chichat-cat.cloudfunctions.net`

## API Endpoint

### `/cv_uploader`

This endpoint supports POST requests for uploading CVs.

#### HTTP Method

`POST`

#### Headers

*Not required*

#### Request Parameters

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `ccid` | String | Client's unique identifier. | Yes |
| `is_click_push` | Boolean | Flag to indicate if the upload was triggered by a click. | Yes |

#### Request Body Example

{
  "ccid": "client123",
  "is_click_push": false
}

#### Error Codes

The `cv_uploader` function is responsible for uploading `click.js` and `conversion.js` files based on the provided `ccid` to Google Cloud Storage. During its operation, various errors can occur due to request handling, parameter validation, or server-side processing. Below is a list of potential error codes, their meanings, and common causes.

| Error Code | Description | Common Causes |
|------------|-------------|---------------|
| 400 | Bad Request | This error occurs if the request body is empty, the `ccid` is missing or empty, or the `is_click_push` flag is not properly provided. It indicates that the server cannot process the request due to client-side input errors. |
| 405 | Method Not Allowed | An unsupported HTTP method was used for the request. The `cv_uploader` function only supports POST requests, and using GET or any other method will result in this error. |
| 404 | Not Found | This error is returned if there is no client data associated with the provided `ccid`. It indicates that the specified `ccid` does not exist in the Firestore database. |
| 500 | Internal Server Error | General server-side errors can trigger this response. This could be due to issues with Firestore or Cloud Storage interactions, unhandled exceptions in the `cv_uploader` function, or other backend failures. |

---
### `/script_uploader`

These endpoints support POST requests for uploading scripts.

#### HTTP Method

`POST`

#### Headers

*Not required*

#### Request Parameters

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `ccid` | String | The unique identifier for the client. | Yes |
| `url` | String | The URL scheme associated with the script. | Yes |
| `function_flag` | Boolean | Indicates whether a specific function is enabled. | Yes |
| `function_name` | String | The name of the function to be enabled, if any. | Yes |
| `img_name` | String | The name of the image to be used within the script. | Yes |
| `time_auto_modal` | Boolean | Determines if a modal should automatically pop up after a certain time. | Yes |
| `time_auto_sec` | Integer | The number of seconds to wait before the automatic modal pops up. | Yes |
| `scroll_modal` | Boolean | Indicates whether a modal should appear upon scrolling a certain percentage of the page. | Yes |
| `scroll_percent` | Integer | The page scroll percentage required to trigger the modal. | Yes |
| `visibility_flag` | Boolean | Controls the visibility of certain elements in the script. | Yes |
| `popup_again_min` | Integer | The minimum number of minutes before the popup can be shown again to the same user. | Yes |
| `ai_log_flag` | Boolean | Enables or disables logging for AI-related activities. | Yes |
| `ai_popup_flag` | Boolean | Determines whether AI-driven popups are enabled. | Yes |
| `back_popup_flag` | Boolean | Enables or disables popups when navigating back in browser history. | Yes |
| `show_rate` | Integer | The percentage rate at which AI-driven popups should appear. | Yes |
| `banner_size` | String | Specifies the size of the banner to be used. | Yes |
| `device_popup_flag` | String | Controls the popup behavior based on the device type. | Yes |
| `dev_flag` | Boolean | Control whether sending request to dev endpoint. | Yes |
| `ab_test_flag` | Boolean | Enables A/B testing for the script. | Yes |
| `image_name_a` | String | The image name for variant A in A/B testing. | Yes |
| `image_name_b` | String | The image name for variant B in A/B testing. | Yes |
| `back_same_domain_flag` | Boolean | Controls the back button behavior for the same domain. | Yes |
| `wait_same_domain_flag` | Boolean | Adds a wait condition for actions within the same domain. | Yes |
| `scroll_same_domain_flag` | Boolean | Controls scroll behavior for the same domain. | Yes |
| `visibility_same_domain_flag` | Boolean | Manages visibility settings for elements within the same domain. | Yes |

#### Request Body Example

{
  "ccid": "your_client_id_here",
  "url": "your_url_scheme_here",
  "function_flag": false,
  "function_name": "your_function_name_here",
  "img_name": "your_image_name_here",
  "time_auto_modal": false,
  "time_auto_sec": 20,
  "scroll_modal": false,
  "scroll_percent": 50,
  "visibility_flag": false,
  "popup_again_min": 20,
  "ai_log_flag": false,
  "ai_popup_flag": false,
  "back_popup_flag": false,
  "show_rate": 80,
  "banner_size": "defaultSize",
  "device_popup_flag": "default",
  "dev_flag": false,
  "ab_test_flag": false,
  "image_name_a": "your_image_name_A_here",
  "image_name_b": "your_image_name_B_here",
  "back_same_domain_flag": false,
  "wait_same_domain_flag": false,
  "scroll_same_domain_flag": false,
  "visibility_same_domain_flag": false
}

#### Error Codes

During the operation of the `scriptUploader`, various errors can occur due to file uploads, parameter validation, server-side processing, or HTTP method restrictions. Below is a list of potential error codes, their meanings, and common causes.

| Error Code | Description | Common Causes |
|------------|-------------|---------------|
| 400 | Bad Request | Invalid parameters were provided to the `ScriptUploader`. This could be due to missing required fields, incorrect data types, or invalid values. Additionally, an empty request body will also result in this error. |
| 405 | Method Not Allowed | An unsupported HTTP method was used for the request. Only POST requests are allowed, and using GET or any other method will result in this error. |
| 500 | Internal Server Error | General server-side errors. This could be due to issues with the `ProcessStorage` service, file read/write errors, or other unhandled exceptions within the `ScriptUploader`. |

---

### `/get_gcs_client_images`

#### HTTP Method

`GET`

Retrieves the latest image for a given client based on the `client_id` parameter.

#### Parameters

- **client_id** (required): The unique identifier for the client whose images you want to retrieve.

#### Headers

*Not required for local execution. For cloud function deployment, CORS headers are automatically handled.*

#### Request Parameters

- `client_id` (required): The unique identifier for the client whose images you want to retrieve. This should be passed as a query parameter in the GET request URL.

Example: `?client_id=12345`

#### Response

The response is a JSON object containing an array with the most recent image's URL and its creation timestamp.

##### Success Response Example

{
  "image_url": [
    {
      "url": "https://cdn.chichat.tw/clients/{client_id}/public/images/latest_image.jpg",
      "time_created": "2024-01-31T12:00:00Z"
    }
  ]
}

#### Error Codes

| Error Code | Description | Common Causes |
|------------|-------------|---------------|
| 400 | Bad Request | The `client_id` query parameter is missing or invalid. |
| 404 | Not Found | No images found for the provided `client_id`. Note: The current implementation does not explicitly handle this case; it returns an empty list instead. |
| 500 | Internal Server Error | Server-side errors such as issues with Google Cloud Storage client initialization, failure in listing blobs, or any unhandled exceptions. |
| 503 | Service Unavailable | Temporary issues with the Google Cloud Storage service or network connectivity problems preventing access to the storage bucket. |

---
### `/uploader`

#### HTTP Method

`POST`

Uploads images and HTML content for a given client.

#### Headers

- `Content-Type`: `multipart/form-data` is required for uploading files.

#### Request Parameters

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `ccid` | String | Client's unique identifier. | Yes |
| `url_scheme` | String | URL scheme to be used in HTML content. | Yes |
| `file_length` | String | Number of image files to upload. | Yes |
| `img_X` | File | Image file where X is the index starting from 0. Must match the number specified in `file_length`. | Conditional |
| `gta_script` | String | Google Tag Assistant Script. Include if applicable. | Yes |
| `gat_no_script` | String | Google Tag Assistant NoScript. Include if applicable. | Yes |
#### Request Form Example

{ 
    "client": "test_client_001"
    "ccid": "b241f282-e7c1-4260-bb8d-630762a7e9bd"
    "url_scheme":"https://example.com"
    "gta_script":""
    "gta_no_script":""
    "img_0": "[object File]"
    "img_1": "[object File]"
    "file_length":"2"
}

#### Success Response

The response includes a JSON object with URLs for the uploaded images, redirect HTML, and script files.

##### Example

{
  "images": ["https://cdn.chichat.tw/clients/{ccid}/public/images/img_0.jpg"],
  "redirect_url": ["https://cdn.chichat.tw/clients/{ccid}/public/static/banner.html"],
  "script_url": ["https://cdn.chichat.tw/clients/{ccid}/public/scripts/script.js"]
}

#### Error Codes
| Error Code | Description | Common Causes |
|------------|-------------|---------------|
| 400 | Bad Request | Returned if required form fields are missing or invalid, or if an uploaded file is not an image.
| 500 | Internal Server Error | Server-side errors such as issues with Google Cloud Storage client initialization, failure in listing blobs, or any unhandled exceptions. |