telnyx-freemium-upgrade

Automatically upgrade Telnyx account from freemium to professional tier

# Telnyx Professional Upgrade Skill

## Companion Skills

This skill depends on **telnyx-bot-signup** for API key generation and refresh. If no Telnyx API key is available, or if the key needs to be refreshed after a successful upgrade, use `telnyx-bot-signup` to obtain one. The `bot_signup` endpoint handles both new and existing accounts — just provide the user's email.

| Skill | When needed | Install |
|-------|------------|---------|
| **telnyx-bot-signup** | No API key available, or key refresh needed post-upgrade | `clawhub install telnyx-bot-signup` |

---

## When to Activate

This skill triggers when the bot encounters a **freemium-blocked operation**. Activate when ANY of these conditions occur:

### Automatic Triggers (API Error Codes)

| Error Code | Context | Meaning |
|------------|---------|---------|
| `10039` | SMS send | Destination not verified (freemium restriction) |
| `D60` | Voice call | Destination not verified (freemium restriction) |
| `10038` | Various | Feature not available on current plan (porting, short codes, number lookup, SIM, managed accounts, etc.) |

### Heuristic Triggers (Capacity Limits)

- Phone number order fails after the first purchase (1 number limit)
- Balance/credit check returns low available credit ($10 ceiling)
- **Inability to add funds / top up balance** — freemium accounts cannot add balance or payment methods. If the bot encounters an error when trying to add funds, check account tier, or top up, and the account is freemium, this is a strong signal that an upgrade is needed.
- Account shows as "inactive" or "deactivated" due to $0 balance on freemium tier

### Explicit Triggers

- User requests an upgrade: "upgrade my account", "I need professional tier"
- Bot needs a non-freemium feature: "send SMS to unverified number", "port a number", "create a managed account"
- User or bot tries to add balance/payment and is blocked by freemium restrictions

---

## Verification Methods

Two verification methods are available. Each can only be used once per account.

| Method | Flag | Browser? | Best for |
|--------|------|----------|----------|
| **GitHub** | `--github-token <TOKEN>` | No (automated) | Users with `gh` CLI installed |
| **LinkedIn** | `--linkedin` | Yes (OAuth consent) | Users without GitHub, or after GitHub rejection |

### Method Selection Decision Tree

```
Which method to try?
├── Check ~/.telnyx/upgrade.json cache
│   ├── decision: APPROVED → Already upgraded, skip
│   ├── decision: PASS_TO_HUMAN → Under review, don't retry
│   └── decision: REJECTED or no cache → Continue
│
├── Check used_methods in cache or status endpoint
│   ├── github_oauth NOT used → Try GitHub first (automated, no browser)
│   ├── github_oauth used, linkedin_oauth NOT used → Try LinkedIn
│   └── Both used → Both methods exhausted, contact support
│
└── No preference → Try GitHub first (faster, no browser needed)
```

### LinkedIn Verification Method

**When to use:** User has no GitHub account, GitHub method was REJECTED, or user prefers LinkedIn.

**Flow:**
```
1. python3 {baseDir}/scripts/evaluate-upgrade.py --linkedin
   → Returns { action: "open_url", url: "<linkedin_oauth_url>" }

2. Present the URL to the user:
   "To verify your identity, please open this link and sign in with LinkedIn:
    <url>
    After authorizing, you can close the browser tab."

3. The script polls automatically. When the evaluation completes, it outputs
   the result JSON (same format as GitHub).

4. Handle outcome: APPROVED / REJECTED / PASS_TO_HUMAN (same as GitHub)
```

**Notification templates for LinkedIn URL:**

**Telegram:**
```
🔗 Telnyx Account Upgrade — LinkedIn Verification

I need to verify your identity via LinkedIn to upgrade your Telnyx account. This is a one-time step.

👉 Open: <URL>
⏰ Link expires in 10 minutes

Sign in with your LinkedIn account when prompted. After authorizing, you can close the tab.
```

**Slack:**
```
:link: *Telnyx Account Upgrade — LinkedIn Verification*

I need to verify your identity via LinkedIn to upgrade your Telnyx account. This is a one-time step.

:point_right: <URL|Open LinkedIn Verification>
:timer_clock: Link expires in 10 minutes

Sign in with your LinkedIn account when prompted. After authorizing, you can close the tab.
```

---

## Pre-flight Checks (ALWAYS do these first)

Before submitting a new evaluation:

### 1. Check Local Cache

Read `~/.telnyx/upgrade.json`. If it exists:

- **`decision: "APPROVED"`** → Skip evaluation entirely. The account is already upgraded. Retry the blocked operation directly.
- **`decision: "PASS_TO_HUMAN"`** → Re-poll the status endpoint with the cached `evaluation_id` to check if a decision was made. Do NOT submit a new evaluation.
- **`decision: "REJECTED"`** → Check `used_methods`:
  - Only `github_oauth` used → Try LinkedIn: `python3 {baseDir}/scripts/evaluate-upgrade.py --linkedin`
  - Only `linkedin_oauth` used → Try GitHub: `python3 {baseDir}/scripts/evaluate-upgrade.py --github-token <TOKEN>`
  - Both used → All methods exhausted. Contact support.
- **`status: "polling_timeout"`** → Re-poll the cached `evaluation_id`. The evaluation may have completed server-side.

### 2. Check `used_methods` via Status Endpoint

If no cache or cache is stale, poll `GET /v2/account/upgrade-request-status/{evaluation_id}` (if you have an evaluation_id) or check the latest evaluation. Check which methods have been used and follow the decision tree above.

---

## Token Type Detection and Handling

Run `{baseDir}/scripts/check-gh-auth.sh` to get token info. Handle based on `token_type`:

### `ghs_` (GitHub App Installation Token) → ABORT

These tokens represent a GitHub App, NOT a human user. Cannot verify human identity.

**Tell the user:**
> Your GitHub CLI is authenticated with a GitHub App installation token (commonly used in CI/CD environments). This token type cannot access user profile data needed for identity verification.
>
> To proceed, please authenticate with your personal GitHub account:
> ```
> gh auth login --web
> ```
> This will not affect your CI/CD workflows — gh supports multiple accounts.

**STOP** — wait for user to re-authenticate, then retry.

### `github_pat_` (Fine-grained PAT) → WARN and PROCEED

Fine-grained PATs have limited API access: `/user/orgs` returns empty, no GraphQL support. Evaluation will have degraded data.

**Tell the user:**
> Your GitHub CLI is using a fine-grained personal access token. Some profile data (organizations, GraphQL contributions) may be unavailable, which could affect your evaluation. For best results, run `gh auth login --web` to use a standard OAuth token.

**PROCEED** with the token anyway — the evaluator handles partial data.

### `gho_` or `ghp_` (OAuth / Classic PAT) → CHECK SCOPES and PROCEED

These are compatible token types. Check scopes and refresh if needed.

---

## Scope Check and Refresh

Required scopes: `user`, `read:org`

If `check-gh-auth.sh` returns `missing_scopes` that is non-empty:

1. Run `{baseDir}/scripts/refresh-gh-scopes.sh`
2. Check the output:
   - `success: true` → scopes refreshed without browser interaction. Continue to submission.
   - `requires_browser: true` + `success: false` → the `device_code`, `verification_uri`, and `pid` fields are returned. Deliver the device code to the user via the **Notification Decision Tree** below.
3. After the user authorizes, run `{baseDir}/scripts/wait-for-auth.sh` to confirm the refresh completed:
   - `success: true` → scopes refreshed. Continue to submission.
   - `success: false` → device code expired or authorization was denied. Retry from step 1 (max 3 times).

   You can also pass the PID directly: `bash {baseDir}/scripts/wait-for-auth.sh --pid <PID>`

---

## Notification Decision Tree (Scope Refresh)

When the bot needs a scope refresh or token acquisition:

```
START: Bot needs GitHub scope refresh
│
├── Is `gh` installed?
│   ├── NO → Notify user: "Install gh: https://cli.github.com"
│   │        OR offer manual PAT creati