adobe-ps-scripts-loreal/README.md

# Adobe Photoshop Text Layer Management

This repository contains tools for interacting with Adobe Photoshop files using both local scripts and the Adobe Photoshop API.

## Current Status (April 22, 2025)

### API Integration Status

We have successfully implemented the Adobe Photoshop API integration with the following components:

- ✅ **Authentication**: Using client credentials to obtain OAuth tokens
- ✅ **External Storage**: Google Cloud Storage for file uploads and downloads
- ✅ **API Endpoint Integration**: Correct Adobe API endpoints identified and integrated
- ✅ **Asynchronous Processing**: Status URL monitoring and file download
- ✅ **Text Updating**: Successfully updating text content using layer names (note: uses default font)

### Recent Fixes and Improvements

1. **Fixed API Text Layer Updates**:
   - Layer name-based identification is now working
   - Text content updates successfully
   - Output files are properly saved and named
   - Temporary files are automatically cleaned up

2. **File Management**:
   - Output files now use clear naming with `api_updated_` prefix
   - Files are saved in the same directory as the original
   - Google Cloud Storage temporary files are automatically deleted

3. **Known Limitation**:
   - The API uses Arial font instead of preserving the original font
   - All other aspects (content, line breaks) are properly updated

See `API-UPDATE-FIX.md` for detailed information about the fixes.

## Using the Adobe API Text Update Tools

### Single File Update

To update a single PSD file using the API:

```bash
python simplified_payload.py /path/to/your-textonly.json /path/to/your.psd
```

This will:
1. Upload the PSD to Google Cloud Storage
2. Make the API request to update text layers
3. Download the processed file with the `api_updated_` prefix
4. Clean up temporary files in Google Cloud Storage

### Batch Processing

To process multiple files at once:

```bash
python update_text_with_api.py --directory /path/to/directory
```

This will:
1. Find all JSON files with text layer data in the directory
2. Process each file and its corresponding PSD
3. Save updated files in the same location as originals with `api_updated_` prefix

### File Organization

- **Input Files**: 
  - PSD files: Original Photoshop files
  - JSON files: Text content data extracted from PSDs

- **Output Files**:
  - Output files are saved in the same directory as the originals
  - Files are named with `api_updated_` prefix (e.g., `api_updated_your_file.psd`)
  - No nested directories are created

### Text Content Format

The JSON files should contain text layer data in this format:

```json
{
  "documentName": "your_file.psd",
  "psdPath": "/path/to/your_file.psd",
  "textLayers": [
    {
      "name": "Layer Name",
      "text": "Original text",
      "updatedText": "New text content"
    }
  ]
}
```

The `updatedText` field is used for the new content.

## Other Available Options

### Local Script Workflow (Font Preservation)

If you need to preserve font styling exactly:

1. **Extract text** from PSD files using the local scripts:
   ```bash
   python mac_ps_extract.py /path/to/psd_files -o /path/to/output_dir
   ```

2. **Edit** the extracted JSON files

3. **Update text** using local scripts:
   ```bash
   python mac_ps_update.py /path/to/json_files -p /path/to/psd_files --save
   ```

### Direct ExtendScript (Alternative)

For direct text updates without Python:

1. Open the PSD file in Photoshop
2. Run `ExtractTextWithBreaks.jsx` to extract text
3. Edit the JSON file
4. Run `updateTextLayers.jsx` to apply the changes

## Adobe API Integration Details

The Adobe Photoshop API integration follows these steps:

1. Upload PSD file to Google Cloud Storage
2. Generate signed URLs for input and output files
3. Send API request to `https://image.adobe.io/pie/psdService/text`
4. Monitor processing status via the status URL
5. Download the processed file when complete

### Authentication

To authenticate with Adobe APIs:

1. Use the client credentials provided by Adobe
2. Set the correct scope:
   - Photoshop API: `openid,AdobeID,read_organizations`
   - Firefly API: `openid,AdobeID,firefly_api,ff_apis`

Tokens can be generated using:

```bash
python adobe_ps_api.py generate-token --client-secret YOUR_CLIENT_SECRET
```

### API Commands

```bash
# Test connectivity to API endpoints
python adobe_ps_api.py test-api

# Test text edit functionality
python adobe_ps_api.py test-text-edit

# Test Google Cloud Storage upload
python adobe_ps_api.py test-gcs /path/to/file.psd

# Update text (dry run)
python adobe_ps_api.py update-text /path/to/file.json --dry-run

# Update text with API
python adobe_ps_api.py update-text /path/to/file.json
```

## Troubleshooting

### API Issues

- **Font Changes**: The API currently replaces fonts with Arial. Use local scripts if font preservation is essential.
- **Authentication Errors**: Check client credentials and token expiration.
- **File Not Found**: Ensure paths are correct and files exist.
- **Failed Downloads**: Check GCS permissions and bucket configuration.

### Local Script Issues

- If layers aren't being found, ensure layer names match exactly
- If JSON parsing fails, check for valid JSON syntax
- For more details, see the troubleshooting section in the script headers

## Documentation

For more detailed information, see:
- [API-UPDATE-FIX.md](API-UPDATE-FIX.md) - Latest fixes to the API integration
- [API-STATUS.md](API-STATUS.md) - Current integration status and issues
- [MAC-SCRIPTS.md](MAC-SCRIPTS.md) - MacOS-specific script documentation