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

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

Dry-run:

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:

bun run test

Run endpoint UAT:

./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.