Initial import into Gitea

MetaApi/README.md

@@ -0,0 +1,102 @@
+# 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
+```