# Twitter/X API tool improvements
# Testing, usage examples, spending tracking, and per-user limits

scope: tools/twitter
goals:
  - Send test messages (post tweet) via API and Console
  - Update API usage examples for all capabilities (status, user_lookup, tweet_lookup, search_recent, create_tweet, get_usage)
  - Track X API spending (integrate GET /2/usage/tweets, display on dashboard)
  - Set and enforce per-token daily request limits for granted users

phases:
  - name: X Usage API and spending display
    steps:
      - Add get_x_usage(bearer) in twitter.php → GET /2/usage/tweets
      - Cache response in data/x_usage.json (TTL e.g. 10 min)
      - Dashboard: show project_cap, daily_project_usage (tweets consumed), link to Developer Console
      - API action get_usage (returns cached X usage for admin)
  - name: Token limits (per-user caps)
    steps:
      - Add token_limits.json and helpers: get_token_daily_limit(hash), set_token_daily_limit(hash, limit)
      - In api.php: for non-admin requests, check calls_today vs limit; if over, return 429
      - Admin UI: set/edit daily_request_limit per allowed token (Console → Users & tokens)
      - API: set_token_limit (admin), get_token_limits (admin)
  - name: API usage examples
    steps:
      - Dashboard (locked): expand Usage with "API examples" details – cURL for each action
      - Console: API Usage subsection with same examples (status, user_lookup, tweet_lookup, search_recent, get_usage, create_tweet)
      - Include base URL, Authorization header, and query/body for each
  - name: Send test tweet
    steps:
      - Optional OAuth 2.0 access token in token.json (for posting); dashboard field to paste and save
      - twitter.php: create_tweet(user_access_token, text) → POST /2/tweets
      - API action create_tweet (POST, text in body); require user token or return clear error
      - Widget "Send test tweet" in Console

validation:
  - PHP syntax check all modified files
  - Dashboard shows X usage when Bearer connected
  - Granted user over daily limit receives 429
  - API examples copy-paste works with valid token
  - Create tweet succeeds when OAuth token is set
