---
name: swagger-sync-manager
description: This skill should be used when regenerating Swagger/OpenAPI TypeScript API clients in the ISA-Frontend monorepo. It handles generation of all 10 API clients (or specific ones), Unicode cleanup, breaking change detection, TypeScript validation, and affected test execution. Use this skill when the user requests API sync, mentions "regenerate swagger", or indicates backend API changes.
---

# Swagger Sync Manager

## Overview

Automate the regeneration of TypeScript API clients from Swagger/OpenAPI specifications. Handles 10 API clients with automatic post-processing, breaking change detection, impact analysis, and validation.

## When to Use This Skill

Invoke when user requests:
- API client regeneration
- "sync swagger" or "update API clients"
- Backend API changes need frontend updates

## Available APIs

availability-api, cat-search-api, checkout-api, crm-api, eis-api, inventory-api, isa-api, oms-api, print-api, wws-api

## Sync Workflow

### Step 1: Pre-Generation Check

```bash
# Check uncommitted changes
git status generated/swagger/
```

If changes exist, warn user and ask to proceed.

### Step 2: Backup Current State (Optional)

```bash
cp -r generated/swagger generated/swagger.backup.$(date +%s)
```

### Step 3: Run Generation

```bash
# All APIs
npm run generate:swagger

# Specific API (if api-name provided)
npm run generate:swagger:[api-name]
```

### Step 4: Verify Unicode Cleanup

Check `tools/fix-files.js` executed. Scan for remaining Unicode issues:

```bash
grep -r "\\\\u00" generated/swagger/ || echo "✅ No Unicode issues"
```

### Step 5: Detect Breaking Changes

For each modified API:

```bash
git diff generated/swagger/[api-name]/
```

Identify:
- 🔴 Removed properties
- 🔴 Changed types
- 🔴 Removed endpoints
- ✅ Added properties (safe)
- ✅ New endpoints (safe)

### Step 6: Impact Analysis

Use `Explore` agent to find affected files:
- Search for imports from `@generated/swagger/[api-name]`
- List data-access services using changed APIs
- Estimate refactoring scope

### Step 7: Validate

```bash
# TypeScript compilation
npx tsc --noEmit

# Run affected tests
npx nx affected:test --skip-nx-cache

# Lint affected
npx nx affected:lint
```

### Step 8: Generate Report

```
Swagger Sync Complete
=====================

APIs Regenerated: [all | specific]
Files Changed: XX
Breaking Changes: XX

🔴 Breaking Changes
-------------------
- [API]: [Property removed/type changed]
- Affected files: [list]

✅ Compatible Changes
---------------------
- [API]: [New properties/endpoints]

📊 Validation
-------------
TypeScript: ✅/❌
Tests: XX/XX passing
Lint: ✅/❌

💡 Next Steps
-------------
[Fix breaking changes / Deploy]
```

## Error Handling

**Generation fails**: Check OpenAPI spec URLs in package.json

**Unicode cleanup fails**: Run `node tools/fix-files.js` manually

**TypeScript errors**: Review breaking changes, update affected services

## References

- CLAUDE.md API Integration section
- package.json swagger generation scripts
