# Client Finder - Bun + TypeScript Implementation

This document describes the Bun + TypeScript implementation of the client-finder skill.

## Overview

The client-finder skill is implemented with Bun + TypeScript, providing:

- Type safety
- Modular structure
- Easier testing
- Robust error handling

## Project Structure

```
client-finder/
├── src/
│   ├── index.ts         # Main entry point and orchestration logic
│   ├── expansion.ts     # Query expansion logic (LLM and rule-based)
│   ├── workflow.ts      # Workflow API calls
│   └── types.ts         # TypeScript type definitions
├── scripts/
│   ├── run.ts           # Bun CLI entry point
│   ├── test.ts          # Test suite
│   └── skill-run-uat.sh # Endpoint UAT script
├── package.json
├── SKILL.md
└── output_schema.json
```

## Runtime Flow

1. Exchange token: `POST /auth/skill-credit/session` with `clientKey`
2. Read `accessToken`
3. Start workflow: `POST /ecom/cold-outreach/run-flow` with `Authorization: Bearer <accessToken>`
4. If response indicates runtime session expired (`401/403`), `@clawd/auth-runtime` auto refreshes token and retries once
5. Return accepted immediately

Note: this skill does not pass `webhook_url`/`webhook_token` in body. Webhook config is resolved from client-key binding by backend.

## Run

```bash
bun run scripts/run.ts --client-key='<sk_xxx.yyy>' "office machine" "us"
```

Dry-run:

```bash
bun run scripts/run.ts --client-key='<sk_xxx.yyy>' "office machine" "us" --dry-run
```

## Environment

- `AUTH_BASE` (default: `https://api-gw-test.yuanwei-lnc.com`)
- `CLIENT_KEY` (required for live)
- `QUERY_EXPANSION_JSON` (optional)
- `AUTH_CACHE_DIR` (optional)
- `AUTH_MIN_TTL_SEC` (optional)

`--client-key` and `--auth-base` CLI args override env values.

## Testing

Run unit-like checks:

```bash
bun run test
```

Run endpoint UAT:

```bash
./scripts/skill-run-uat.sh --live
```

## Notes

- Output must match `output_schema.json`.
- This skill is async fire-and-return: no local polling/finalize/hook emission.