hp-copy-proofing/README.md

# HP Studio Copy Proofing Tool

A web-based tool for proofing and validating copy in creative assets stored in Box.

## Overview

The HP Studio Copy Proofing Tool allows studio teams to validate the spelling, grammar, and overall correctness of copy in creative assets. The tool works by:

1. Taking a Box file URL as input
2. Extracting the file ID 
3. Sending it to a webhook for processing
4. Displaying the results in a clean, organized interface

## Features

- **Microsoft Authentication**: Secure login using Microsoft Azure AD credentials
- **User Tracking**: Automatically captures and logs username/email with each submission
- **Language Detection**: Identifies the language and dialect used in the copy
- **Grammar Checking**: Highlights grammatical issues found in the text
- **Spelling Validation**: Identifies and suggests corrections for spelling errors
- **Text Evaluation**: Provides a comprehensive review of all text, marking items as approved or needing correction
- **Debug Mode**: Includes a collapsible debug section to view the raw JSON response

## Requirements

- PHP 7.0 or higher
- cURL extension enabled
- Web server (Apache, Nginx, etc.)
- Internet connection to access Box and the webhook service

## Installation

1. Clone this repository to your web server:
   ```bash
   git clone git@bitbucket.org:zlalani/hp-copy-proofing.git
   cd hp-copy-proofing
   ```

2. Configure the webhook URL by editing `config.php`:
   ```php
   $config = [
     'webhook_url' => 'https://your-webhook-url.com/endpoint',
   ];
   ```

3. Configure Microsoft Authentication in `index.php` (search for `msalConfig`):
   - Set `clientId` to your Azure AD application ID
   - Set `authority` to your tenant ID URL: `https://login.microsoftonline.com/YOUR_TENANT_ID`
   - Set `redirectUri` to your application's URL (must match Azure AD app registration)

4. Ensure the web server has proper permissions and PHP cURL extension is enabled.

## Usage

1. Access the tool via your web browser at `http://your-server/hp-studio-copy-proofing-tool/`

2. **Sign in** with your Microsoft account credentials when prompted

3. Enter a valid Box file URL in the format `https://oliver-na.app.box.com/file/1234567890` (only image files are supported: gif, jpeg, jpg, png, webp)

4. Click "Process File" and wait for the analysis to complete

5. Review the results:
   - Document Summary shows language information and issue count
   - Grammar Issues highlights any grammatical errors
   - Spelling Errors shows any misspelled words with context and suggested corrections
   - Text Evaluation provides an assessment of all text content

6. For debugging, click "View Raw JSON Response" to see the full API response

## Webhook Data Sent

When a file is submitted, the following data is sent to the webhook:

```json
{
  "url": "https://oliver-na.app.box.com/file/1697251331911",
  "file_id": "1697251331911",
  "username": "user@example.com",
  "timestamp": "2024-01-15 14:30:45"
}
```

## Response Format

The webhook service should return a JSON response in the following format. The application automatically handles responses wrapped in markdown code fences (```json...```):

```json
{
  "document_analysis": {
    "language_detected": [
      {
        "language": "English",
        "type": "US",
        "spelling_status": "correct"
      }
    ],
    "grammar_issues": [
      {
        "section": "Text on the left shelf",
        "error": "Missing possessive apostrophe in 'Hellmanns'.",
        "suggestion": "Add an apostrophe to read 'Hellmann's'."
      }
    ],
    "spelling_errors": [
      {
        "word": "Hellmanns",
        "context": "Hellmanns on both shelf stoppers",
        "correct_spelling": "Hellmann's",
        "status": "incorrect"
      }
    ],
    "text_evaluation": [
      {
        "text": "Make it irresistibly rich & creamy",
        "status": "good"
      }
    ]
  }
}
```

## Troubleshooting

- **Invalid URL Error**: Ensure the Box URL is in the correct format with a valid file ID
- **Webhook Connection Error**: Verify the webhook URL in `config.php` is correct and accessible
- **No Results Displayed**:
  - Check if the webhook is returning properly formatted JSON
  - The application automatically strips markdown code fences from responses
  - Check browser console and network tab for additional errors
- **Authentication Loop**: If login popup keeps appearing, clear browser sessionStorage and try again
- **Results Not Persisting**: Ensure sessionStorage is enabled in your browser

## Security Considerations

- This tool requires Microsoft Azure AD authentication for access
- User credentials are managed through Microsoft's authentication system
- Username/email is captured and sent with each webhook request for audit tracking
- This tool is designed for internal use only
- The webhook URL should be secured and properly authenticated
- No sensitive data is stored locally on the server
- Session data is stored in browser sessionStorage and cleared on logout

## Recent Changes

### October 23, 2025
- ✅ Added Microsoft Azure AD authentication with MSAL
- ✅ Implemented user tracking - username/email captured and sent with each webhook request
- ✅ Fixed session persistence to prevent authentication loop after form submission
- ✅ Fixed JSON parsing to handle webhook responses wrapped in markdown code fences
- ✅ Improved error handling and response processing
- ✅ Clean user interface showing only results (debug mode removed from display)

## Technical Details

### Authentication Flow
1. User accesses the application
2. MSAL triggers Microsoft login popup
3. User authenticates with Azure AD credentials
4. Access token and username stored in sessionStorage
5. Protected content (form) becomes visible
6. Username automatically included with each submission

### Data Flow
1. User submits Box file URL
2. Application extracts file ID
3. Data sent to webhook: `{url, file_id, username, timestamp}`
4. Webhook processes and returns JSON (with or without markdown fences)
5. Application strips markdown fences if present
6. JSON decoded and results displayed to user

## License

Copyright © 2024 HP Inc. All rights reserved.

## Credits

Developed by the HP Studio Tool Team