# Reddit API integration — research and implementation plan
# Ref: https://www.reddit.com/dev/api, https://github.com/reddit-archive/reddit/wiki/OAuth2,
#      https://support.reddithelp.com/hc/en-us/articles/16160319875092-Reddit-Data-API-Wiki

scope: tools/reddit
research_summary:
  auth:
    - All API traffic MUST use OAuth; "Traffic not using OAuth or login credentials will be blocked."
    - Web app: create app at https://www.reddit.com/prefs/apps (type "web app"), get client_id (under app name) and client_secret (secret field).
    - Authorize URL: GET https://www.reddit.com/api/v1/authorize?client_id=&response_type=code&state=&redirect_uri=&duration=permanent&scope=
    - Token URL: POST https://www.reddit.com/api/v1/access_token with Basic Auth (client_id:client_secret), body application/x-www-form-urlencoded: grant_type=authorization_code&code=&redirect_uri=
    - Response: access_token, token_type bearer, expires_in (seconds), scope, refresh_token (if duration=permanent).
    - Refresh: POST same URL, body grant_type=refresh_token&refresh_token=
    - All authenticated API requests go to https://oauth.reddit.com (NOT www.reddit.com).
  user_agent:
    - REQUIRED. Format: "<platform>:<app ID>:<version> (by /u/<reddit username>)"
    - Never lie; default UAs (e.g. Python/urllib) are "drastically limited".
    - Example: "User-Agent: web:TSTP-AutoBiz-V3:1.0 (by /u/TSTP)"
  rate_limits:
    - Free: 100 queries per minute (QPM) per OAuth client_id (averaged over ~10 min).
    - Headers: X-Ratelimit-Reset, X-Ratelimit-Remaining, X-Ratelimit-Used.
  data_rules:
    - Remove deleted user content; recommend deleting stored user data within 48 hours.
    - When user deletes account, remove all t2_* and author-identifying info.
  scopes_used:
    - identity: GET /api/v1/me (current user).
    - read: read listings, subreddit info, etc.
    - submit: POST /api/submit, POST /api/comment.
  key_endpoints:
    - GET /api/v1/me → identity (scope: identity). Use raw_json=1 for unescaped JSON.
    - POST /api/submit → sr, title, kind (self|link), text (for self), url (for link). scope: submit.
    - POST /api/comment → thing_id (parent fullname), text. scope: submit.
  quirks:
    - Legacy JSON encoding: <, >, & are escaped in responses unless raw_json=1.
    - Modhash not required when using OAuth.
    - redirect_uri must match exactly what is registered for the app.

phases:
  - name: Config and reddit.php
    steps:
      - config: REDDIT_SCOPE = 'identity read submit'; TOOL_BASE_URL; REDDIT_USER_AGENT constant.
      - build_oauth_url: add duration=permanent.
      - exchange_code_for_token: POST with Basic Auth, form body; return access_token, refresh_token, expires_in.
      - refresh_reddit_token(client_id, client_secret, refresh_token).
      - reddit_request(access_token, method, path, query, body): oauth.reddit.com + User-Agent + raw_json=1.
      - ensure_access_token: refresh if expired, update token_data (caller saves).
      - get_reddit_profile(access_token): GET /api/v1/me.
      - submit_post(access_token, sr, title, kind, text, url): POST /api/submit.
  - name: Callback and index
    steps:
      - callback: exchange returns full token; save access_token, refresh_token, expires_in/expires_at; fetch profile.
      - index/callback use TOOL_BASE_URL from config.
  - name: API and widgets
    steps:
      - api: profile (ensure_access_token, get_reddit_profile), submit (ensure_access_token, submit_post).
      - Widgets: profile display, submit test post (subreddit, title, kind, text/url).

validation:
  - PHP syntax check all files.
  - User-Agent sent on every request to oauth.reddit.com.
  - Token refresh on 401/expiry and persist new token.
