Skill (en)

# Skill: Create Guest (iiko)

## What it does
Creates (or updates) a guest in iiko based on a `cardTrack` + `cardNumber` pair.

If the guest already exists, the function returns it instead of creating a new one.

## Inputs
- `settings: IikoSettings` (client configuration loaded from environment variables)
- `organization_id: str` (optional explicit iiko loyalty organization id)
- `all_organizations: bool` (when `True`, process all discovered organizations one by one; otherwise use the first discovered organization by default)
- `card_track: str` (guest track number)
- `card_number: str` (card number)
- `name: str` (guest display name, used as a fallback)
- `transport: IikoTransport` (HTTP transport; can be mocked for tests)
- `token_provider: Callable[[IikoSettings], Awaitable[str]]` (defaults to `shared.auth.get_access_token`)

CLI also supports `--use-local-env` / `--no-use-local-env`; the MCP tool accepts `use_local_env` (see `IIKO_DEFAULT_USE_LOCAL_ENV`).

## Output
`dict[str, str]` with one of the following shapes:
- Existing guest:
  - `status: "existing"`
  - `guest_id: <customer id>`
  - `name: <existing name or provided name>`
- Newly created guest:
  - `status: "created"`
  - `guest_id: <customer id>`
  - `name: <provided name>`

## How it works (implementation)
1. Acquire an iiko access token via `shared.auth.get_access_token` (or injected `token_provider`).
2. Resolve organizations:
   - use `organization_id` if it was provided
   - otherwise use the first discovered organization by default
   - if `all_organizations=True`, run the command for each discovered organization one by one
3. Lookup guest by `cardTrack` using:
   - `shared.customers.get_customer_by_card_track`
   - POST `/loyalty/iiko/customer/info`
4. Handle the “not found” case:
   - if `IikoApiError.status_code == 404`, treat it as “guest not found” and proceed
   - for any other status code, re-raise the error
5. Create/update the guest using:
   - `shared.customers.create_customer_with_card_track`
   - POST `/loyalty/iiko/customer/create_or_update`
6. Return a small structured result intended for both CLI output and future MCP tool output.

## Shared components used
- `src/iiko_api_mcp_server/config.py` (`IikoSettings`)
- `src/iiko_api_mcp_server/shared/auth.py` (`get_access_token`)
- `src/iiko_api_mcp_server/shared/http.py` (`IikoTransport`, `IikoApiError` mapping)
- `src/iiko_api_mcp_server/shared/customers.py` (customer lookup + create/update helpers)
- `src/iiko_api_mcp_server/commands/create_guest.py` (orchestration logic)

## Testing
Unit tests live in:
- `tests/commands/test_create_guest.py`

The tests validate:
- existing guest path (returns `status="existing"` and does only the info call)
- created guest path (handles 404 and then performs create/update)
- first discovered organization is used by default when several organizations are returned
- `--all-organizations` opt-in behavior is passed through the CLI

Tests use an in-memory `RecordingTransport` and a fake token provider to avoid live iiko calls.

## Debugging checklist
1. Run the focused tests:
   - `python -m pytest tests/commands/test_create_guest.py -v`
2. If a request shape looks wrong, inspect what `RecordingTransport.calls` captured.
3. If you get an unexpected exception, confirm whether it is:
   - `IikoApiError` with `status_code == 404` (expected “not found”)
   - or another status code (should be propagated)