# AuthX

This project contains the server and client code for the Apps Script AuthX service. Due to organizational restrictions, `clasp` is **not** used for deployment. Updates must be performed manually by copying the build artifacts to the Google Apps Script editor.

## Environments

- **[Prod](https://script.google.com/a/macros/sonymusic-pde.com/s/AKfycbxEm0Bu-LJtHQXlAekWK-BGPusXelZec4ilChsrfP49fq3Pd0ZeIsA1BQePz0dt1jpxlw/exec)**
- **[QA](https://script.google.com/a/macros/sonymusic-pde.com/s/AKfycbws8P-pVVBlAHc4cEx6mu7mBndTD6JJyL3SvhD3Mpkryp4hbn300xn9os2KrhXk95zpYw/exec)**
- **[Dev](https://script.google.com/a/macros/sonymusic-pde.com/s/AKfycbzU81ru-Wv23WBn3DWP03gj_wIvekW5ffUUoiaxxEW169S_SPy95AwuCVyqrx4KuZzYIw/exec)**

## Project Structure

- `api/`: Contains an API client for use by other projects to call the API.
- `server/`: Contains the Google Apps Script server-side code (TypeScript).
- `client/`: Contains the React-based client-side code (Vite + TypeScript).

## Deployment

### Note on Clasp

We do not use `clasp` for this project due to organizational security restrictions. All deployments are manual copy-paste operations as described below.

### API (Client Library)

The API client is built as a library for use by other projects.

> [!NOTE]
> The API requires a valid Google bearer token for authentication.

1.  **Navigate to the api directory:**
    ```bash
    cd api
    ```

2.  **Install dependencies:**
    ```bash
    pnpm install
    ```

3.  **Build the project:**
    ```bash
    pnpm run build
    ```

### Server (Apps Script)

The server code is built into a single JavaScript bundle: `server.gs`

1.  **Navigate to the server directory:**
    ```bash
    cd server
    ```

2.  **Install dependencies:**
    ```bash
    pnpm install
    ```

3.  **Build the project:**
    ```bash
    pnpm run build
    ```
    This will generate the build artifacts in the `dist/` directory.

4.  **Publish:**
    - Open the Google Apps Script project editor in your browser.
    - Create or locate the file `server.gs`.
    - Copy and paste the newly generated file into the project's file.
    - Save the project.

### Client (React)

The client code is built into a single HTML file with inlined assets: `client.html`.

1.  **Navigate to the client directory:**
    ```bash
    cd client
    ```

2.  **Install dependencies:**
    ```bash
    pnpm install
    ```

3.  **Build the project:**
    ```bash
    pnpm run build
    ```
    This will generate the build artifacts in the `dist/` directory.

4.  **Publish:**
    - Open the Google Apps Script project editor in your browser.
    - Create or locate the file `client.html`.
    - Copy and paste the newly generated file into the project's file.
    - Save the project.

### Local Client Development

Depending on your goal, use the appropriate command:

#### 1. For Coding & Testing (Recommended)
**`pnpm run dev`**
- **Best for:** Daily development, UI building, and logic testing.
- **Features:**
    - **Hot Module Replacement (HMR):** Instant updates in the browser without reloading.
    - **Mock Server:** Simulates backend API calls locally (since `google.script.run` doesn't exist locally), allowing you to test the full flow.
- **Note:** This does *not* generate the final deployable file.

#### 2. For Deployment Preparation
**`pnpm run watch`**
- **Best for:** When you are actively deploying changes to Apps Script.
- **Features:** Automatically rebuilds the single `dist/index.html` file whenever you save.
- **Workflow:** Keep this running in a separate terminal so your `dist/` folder is always ready to be copy-pasted into the Apps Script editor.

#### 3. For Final Verification
**`pnpm run preview`**
- **Best for:** Checking the final build before deployment.
- **Features:** Serves the actual `dist/index.html` file to ensure the single-file bundling worked correctly.

## Testing with Test Deployments

Before creating a new public deployment, you should verify your changes using a **Test Deployment**. This allows you to run the latest saved code without affecting the production URL.

1.  **Click on "Deploy":** In the top-right corner of the Apps Script editor.
2.  **Select "Test deployments":**
3.  **Configure the test:**
    - Ensure the type is set to **"Web app"**.
    - The URL provided here will always point to the **latest saved version** of your code.
4.  **Open the Test URL:** Use this URL to verify that both the server and client are functioning as expected.

> [!IMPORTANT]
> Test deployments only work for users with edit access to the script. They are ideal for internal verification before performing a formal "Manage deployments" update.

## Making the Deployment Public

After updating the code in the Apps Script editor, you must create a new deployment (or update an existing one) to make the changes public.

1.  **Click on "Deploy":** In the top-right corner of the Apps Script editor.
2.  **Select "Manage deployments":**
    - If this is the first time, select **"New deployment"**.
    - If you are updating an existing deployment, click the **"Edit"** (pencil icon) on the active deployment.
3.  **Configure the deployment:**
    - **Select type:** Ensure `Web app` is selected.
    - **Description:** Provide a version description (e.g., "v1.0.0 - Initial Release").
    - **Execute as:** Ensure `User accessing the web app` is selected.
    - **Who has access:** Select `Anyone within The Orchard` to make the app accessible.
4.  **Deploy/Update:** Click the "Deploy" button.

## Configuration

The application configuration is stored in the Google Apps Script **Script Properties**.

### Updating the Config

1.  Open the Google Apps Script editor.
2.  Click on the **Project Settings** (gear icon) in the left sidebar.
3.  Scroll down to the **Script Properties** section.
4.  Add or edit the property named `config`.
5.  The value should be a JSON string matching the `AppConfig` interface. Refer to `server/config.shadow.json` for an example.
6.  Click **Save script properties**.