# GWT AAF custom app — AI-agent guide (single source)

This project is generated by **`create-exotel-gwt-app`**.

AAF SDK load + init is already wired in **`app/aaf/`** (`loadAafSdkIfNeeded.ts`, `registerAafSdk.generated.ts`, or **`EventLoggerView`** for the debugger template). Your job is to build **use-case UI** and subscribe to **official** events/methods only when the use case needs them.

## Start here (use an AI agent)

After **`npm install`** in this folder, open this file and copy/paste the block below into your AI chat. The agent should ask a few questions first, then implement in this repo.

```bash
npm install
```

## Day-to-day commands

```bash
npm run dev          # local preview (AmeyoClient only inside GWT iframe)
npm run ship         # build + gwt-upload.aaex
```

Upload **`gwt-upload.aaex`** in **App Manager**. Keep **`manifest.json`** `name` / `version` aligned with the hosted `/si/.../.../` path.

## Reference (for implementation — not the first message)

| Doc | Purpose |
|-----|---------|
| `docs/GWT_AAF_SDK_REFERENCE.md` | Event payloads, method args, error codes |
| `docs/GWT_AGENT_IMPLEMENTATION_REFERENCE.md` | Use case → events/APIs, SDK surface table |
| `AGENTS.md` | Technical rules and anti-patterns |

## Non-negotiables

- **Do not** change SDK load/init unless official docs require it: `app/aaf/loadAafSdkIfNeeded.ts`, generated `registerAafSdk.generated.ts` (except adding listeners), and for **`global-events-logger`** do not replace `EventLoggerView` ownership of init.
- **Signal Design System only** — imports from `@exotel-npm-dev/signal-design-system`; `scripts/check-signal-imports.cjs` fails on direct `@mui/material` (except `@mui/material/styles`).
- **Light theme only** — `app/theme/AppTheme.tsx` uses `ExotelThemeProvider defaultMode="light"`; `index.html` has `class="light"` and `color-scheme: light`. Do **not** add a dark-mode toggle or `defaultMode="dark"`.
- **Facade only** — host calls via `app/aaf/gwtAafSdk.ts` and sibling `gwt*.ts` files, not scattered `client.*` usage.

## Where to implement

- **Screens & flows:** `app/components/`, `app/App.tsx`
- **SDK registration:** `app/aaf/registerAafSdk.generated.ts` (or `EventLoggerView` for logger template)
- **Use case key (generated):** `app/generated/useCaseKey.ts` — `blank-app` \| `call-session-monitor` \| `global-events-logger`

## UX requirements

- **Responsive** — same build may run in narrow workbench slots or wider panels
- **Signal** overlays: `Drawer`, `StructuredDialog`, `Popover`, `Snackbar`, `Tooltip`
- **Light, clean UI** — readable hierarchy; avoid dense debug-style layouts unless the product is the logger template

---

## Copy/paste into an AI agent (the contract)

```
You are an AI coding agent editing THIS Exotel GWT AAF custom app repo (generated by create-exotel-gwt-app).

EXECUTION-FIRST BEHAVIOR (MANDATORY)
- Do NOT start by summarizing DEVELOPER.md, listing project status, or describing what you will do.
- Do NOT dump tables of "current state", "suggested path", or long questionnaires in the first reply.
- Read ONLY app/generated/useCaseKey.ts for GWT_USE_CASE_KEY, then ask EXACTLY the three questions under FIRST MESSAGE — nothing else in that first reply.
- After the user answers 1–3, implement end-to-end OR ask follow-ups only when required below.
- You MUST NOT stop after writing a plan. Keep going until the use case is implemented, builds, and you provide run + ship commands.

GOAL
- Capture use case, slot, and success criteria (questions 1–3), then implement in this codebase.

FIRST MESSAGE (ASK EXACTLY THESE 3 — NOTHING ELSE IN THE FIRST REPLY)
1) What is the use case (1–2 sentences)?
2) Where will this app run (workbench slot / modal / navBar / background — or "not sure")?
3) What is success criteria (what should the agent see or do in the UI)?

TEMPLATE NOTE (read GWT_USE_CASE_KEY — do NOT ask the user to re-pick the CLI template)
- blank-app → minimal shell; you wire events and APIs for their use case.
- call-session-monitor → callConnected / callHungup already registered; build on top.
- global-events-logger → EventLoggerView is the product (Events + Methods tabs); ask what they want to debug or validate, not a full greenfield UI unless they say so.

FOLLOW-UP (only after 1–3 are answered)
- APIs: if the use case needs Ameyo REST data, ask for paths or a sample response ONCE; if unspecified, use dummy data + one adapter file and continue.
- Events/methods: use docs/GWT_AGENT_IMPLEMENTATION_REFERENCE.md and docs/GWT_AAF_SDK_REFERENCE.md — register only what the use case needs.
- blank-app: do not auto-fetch or auto-run heavy workflows on load unless the user asks.
- call-session-monitor: you may react to callConnected / callHungup already wired in registerAafSdk.generated.ts.

NON-NEGOTIABLES
- DO NOT change SDK load wiring: app/aaf/loadAafSdkIfNeeded.ts.
- For global-events-logger, DO NOT move SDK init out of EventLoggerView.
- Signal components only (@exotel-npm-dev/signal-design-system). No direct @mui/material imports.
- LIGHT THEME ONLY: keep ExotelThemeProvider defaultMode="light" in AppTheme.tsx; keep index.html class="light" and meta color-scheme light; never add dark mode or a theme toggle.

OFFICIAL SDK CONTRACT
- globalEvent names: ONLY strings in app/aaf/gwtGlobalEvents.ts → GWT_GLOBAL_EVENTS_ECC (28 ECC events). Never register callEnded, chatEnded, userStateBreak, callStageHold (doc aliases → 121).
- globalData.get first argument is a plain string: client.globalData.get("loggedInUser") — not { dataObject: "..." }.
- contextEvent (tabChange, ticketSavedByUser, …) is NOT globalEvent.
- Prefer helpers in app/aaf/gwt*.ts over raw client calls.

DESIGN / UX
- Use Signal components (Button, Chip, Tabs, Table, Drawer, StructuredDialog, Typography, Stack, EnhancedTextField, …).
- Light theme only (see above).
- Progressive disclosure; works in narrow iframe widths.

IMPLEMENTATION CHECKLIST
- Add or update views under app/components/
- Wire in app/App.tsx (respect GWT_USE_CASE_KEY)
- Extend app/aaf/registerAafSdk.generated.ts with official event names only (unless global-events-logger)
- Run npm run build (or predev checks) and fix TypeScript errors

OUTPUT
- Summarize files changed and how to run:
  - npm run dev
  - npm run ship  → gwt-upload.aaex
```

---

## Troubleshooting

- **`AmeyoClient` not available locally** — normal outside the GWT iframe. Test on ECC with `origin` / `instanceId`; optional `?sdkBaseUrl=https://host:port/ameyo40`.
- **No `aaf_sdk.js` in Network** — fix `main.*.js` 404 first; then check `loadAafSdkIfNeeded.ts` and `sdkBaseUrl` / `origin` query params.
- **403 or `//static/js/`** — prefer relative build (default `base: "./"`); see ship layout notes below.
- **Theme looks wrong** — confirm `AppTheme.tsx` has `defaultMode="light"`, `index.html` has `class="light"`, and parent iframe is not forcing dark `color-scheme` only.
- **`npm warn deprecated whatwg-encoding` / `glob`** — fixed via `package.json` `overrides` on `@figma/code-connect`.
- **Signal `eval` warning on build** — from published design-system bundle; build still succeeds.

### Ship layout (`.aaex`)

Production build uses **`base: "./"`** so `index.html` references `./static/js/main.<hash>.js` (aligned with ECC GWT sample apps). Optional: `VITE_GWT_BASE=/si/MyApp/1.0.0/ npm run build`.

After `vite build`, `dist/` contains `index.html`, `asset-manifest.json`, `manifest.json`, logos, and `static/js/main.*.js` — zipped as **`gwt-upload.aaex`**.