# MetaApi - Meta Marketing API Provider Service

Standalone microservice for Meta (Facebook/Instagram) advertising integration. Mirrors the GoogleApi architecture pattern — the Gateway routes `provider="meta"` requests here via internal HTTP.

## Architecture

```
Gateway  ──(POST /internal/execute)──►  MetaApi  ──(Graph API)──►  Meta Marketing API
         X-Internal-Key auth             │
                                         ├── Emulated mode (default)
                                         └── Real API mode (Meta__EnableRealApi=true)
```

## Key Differences from GoogleApi

| Aspect | GoogleApi | MetaApi |
|--------|-----------|---------|
| Auth | OAuth refresh tokens | System User token (no expiry) |
| SDK | Google.Ads.GoogleAds NuGet | HttpClient → graph.facebook.com |
| Account format | Numeric customer ID | `act_XXXXXXXXXXXXXXX` |
| Hierarchy | Campaign → Ad Group → Ad | Campaign → Ad Set → Ad |
| API versioning | SDK version | URL path (`/v21.0/`) |

## Operations

| Operation | Description | Real API |
|-----------|-------------|----------|
| Ping / TestPing | Health check | N/A |
| CreateCampaign | Create Meta campaign | ✅ |
| GetCampaign | Retrieve campaign details | ✅ |
| UpdateCampaign | Update name/status/budget | ✅ |
| ListCampaigns | List campaigns with filters | ✅ |
| GetCampaignInsights | Campaign performance metrics | Emulated only |
| GetAccountInsights | Account-level metrics | Emulated only |
| CreateAdAccount | Create ad account under BM | ✅ |
| ListAdAccounts | List BM-owned ad accounts | ✅ |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `META_INTERNAL_KEY` | Yes | Gateway→MetaApi shared auth key |
| `Meta__EnableRealApi` | No | `false` (default) = emulated responses |
| `Meta__AppId` | For real API | Meta App ID from Developer Portal |
| `Meta__AppSecret` | For real API | Meta App Secret |
| `Meta__SystemUserToken` | For real API | System User token from Business Manager |
| `Meta__BusinessManagerId` | For real API | USIM's Business Manager numeric ID |
| `Meta__ApiVersion` | No | Graph API version (default: `v21.0`) |

## Local Development

```bash
dotnet run --project MetaApi
# → http://localhost:5300
# → Swagger: http://localhost:5300/swagger
```

## Deploy to Azure Container Apps

```bash
az containerapp create \
  --name usim-adp-metaapi \
  --resource-group USIM-AdPlatform \
  --environment usim-adp-env \
  --image <registry>/usim-adp-metaapi:latest \
  --target-port 5300 \
  --ingress internal \
  --env-vars \
    META_INTERNAL_KEY=secretref:meta-internal-key \
    Meta__EnableRealApi=false
```

## Gateway Integration

Add to Gateway environment:
```
META_PROVIDER_URL=https://usim-adp-metaapi.internal.<env>.azurecontainerapps.io
META_INTERNAL_KEY=<matching-key>
```

Gateway's `ExecutionService.GetProviderUrl()` already routes `provider="meta"` to `META_PROVIDER_URL`.

## Project Structure

```
MetaApi/
├── Configuration/
│   └── MetaConfig.cs          # Config + MetaApiContext
├── Controllers/
│   └── InternalController.cs  # /internal/execute + /internal/health
├── Models/
│   ├── OperationPayloads.cs   # Meta-specific request payloads + enums
│   └── ProviderModels.cs      # ProviderRequest/Response (Gateway contract)
├── Security/
│   └── InternalAuthFilter.cs  # X-Internal-Key validation
├── Services/
│   ├── MetaGraphClient.cs     # HTTP wrapper for graph.facebook.com
│   └── MetaMarketingService.cs # Operation dispatcher (emulated/real)
├── Program.cs
├── appsettings.json
└── MetaApi.csproj
```