tredi-sdk 0.1.0

package/docs/architecture.md

@@ -0,0 +1,172 @@
+# tredi-sdk — Architecture
+
+How the SDK is put together and why. Read this if you're maintaining the SDK,
+reviewing it, or integrating it deeply. For usage see the
+[API reference](./api-reference.md) and [guides](./guides.md).
+
+## Design goals
+
+1. **Faithful to the docs** — only documented endpoints, fields, and scopes. No invented surface.
+2. **Production-safe by default** — timeouts, retries, and error typing are on out of the box; retries never duplicate a write.
+3. **Secure** — tokens and secrets never reach logs.
+4. **Lean** — zero runtime dependencies; native `fetch`; no abstraction without a second caller.
+5. **Portable** — ESM + CJS, Node 18+/Bun/Deno/edge; `fetch` is injectable.
+
+## Module map
+
+```mermaid
+graph TD
+  index["index.ts (public exports)"]
+  client["client.ts — ThreadsClient"]
+  http["http.ts — send() engine"]
+  errors["errors.ts"]
+  logger["logger.ts (redaction)"]
+  constants["constants.ts"]
+  oauth["oauth.ts (standalone)"]
+  base["resources/base.ts (ThreadsRequester)"]
+  res["resources/* (profile, posts, publishing,<br/>replies, insights, mentions, search)"]
+
+  index --> client
+  index --> oauth
+  index --> errors
+  index --> logger
+  index --> constants
+  client --> http
+  client --> res
+  res --> base
+  oauth --> http
+  http --> errors
+  http --> logger
+  http --> constants
+  errors --> constants
+```
+
+Two things talk to the network — `client.request()` and the `oauth.*`
+functions — and both go through the single `send()` engine in `http.ts`.
+Resources never touch `fetch`; they only build params and call
+`ThreadsRequester.request()`. That narrow interface (defined in
+[`resources/base.ts`](../src/resources/base.ts)) keeps the dependency graph
+acyclic and makes resources trivial to test.
+
+| File | Responsibility |
+|---|---|
+| `client.ts` | Config resolution, resource wiring, URL building, escape hatch |
+| `http.ts` | Timeout, retry/backoff, request building, response parsing |
+| `errors.ts` | Typed error hierarchy + Graph error mapping |
+| `logger.ts` | Logger interface + secret redaction |
+| `oauth.ts` | Authorization URL + token exchanges (no client needed) |
+| `constants.ts` | Hosts, version, defaults, scope list — the only "magic strings" |
+| `types.ts` | API response/request types (erased at runtime) |
+| `resources/*` | One file per API area; thin param-builders |
+
+## Request lifecycle
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant R as Resource
+  participant C as ThreadsClient
+  participant S as send()
+  participant F as fetch
+
+  App->>R: publishing.publishText("hi")
+  R->>C: request({ method, path, params })
+  C->>S: send({ url, accessToken, timeout, retry, logger })
+  loop attempt 0..maxRetries
+    S->>F: fetch(url, { signal: timeout })
+    alt 2xx
+      F-->>S: Response
+      S->>S: parse JSON
+      S-->>C: data (logs request.success)
+    else non-2xx / network / timeout
+      F-->>S: error
+      S->>S: toApiError + isRetryable(method, err)?
+      alt retryable
+        S->>S: sleep(backoff + jitter), retry
+      else not retryable
+        S-->>C: throw typed error (logs request.failure)
+      end
+    end
+  end
+  C-->>App: ContainerRef | throws ThreadsError
+```
+
+- **Timeout** — every attempt runs under an `AbortController` armed with `timeoutMs`. A caller `signal` is linked so external cancellation also works.
+- **Token placement** — GET puts `access_token` in the query (Graph requirement); POST puts it in the form **body**, keeping it out of the URL. Either way it's never logged.
+- **Parsing** — the body is read as text and JSON-parsed defensively; non-2xx maps to a typed error via `toApiError`.
+
+## Retry & idempotency model
+
+Retries use exponential backoff with **equal jitter** (`delay = cap/2 +
+random(0, cap/2)`), capped at `maxDelayMs`, and honor a server `Retry-After`
+when present. The retry decision is **method-aware** so a publish is never
+duplicated:
+
+| Failure | GET | POST |
+|---|---|---|
+| Network error (no response) | retry | retry |
+| HTTP 429 (rejected before processing) | retry | retry |
+| Timeout | retry | **no** |
+| HTTP 5xx | retry | **no** |
+| HTTP 4xx (except 429) | no | no |
+
+The reasoning: a POST that times out or 5xxes may have already taken effect
+(e.g. a published post), so re-sending could create a duplicate. A 429 means the
+request was rejected before processing, and a network error means no response was
+received — both are safe to retry on any method. This lives in `isRetryable()`
+([http.ts](../src/http.ts)) and is unit-tested across the full matrix.
+
+## Error mapping
+
+`toApiError(status, body, headers)` reads the Graph error envelope
+(`error.{message,type,code,error_subcode,fbtrace_id}`) and picks the most
+specific subtype:
+
+```mermaid
+graph LR
+  R[non-2xx response] --> A{status 401<br/>or code 190?}
+  A -- yes --> AUTH[ThreadsAuthError]
+  A -- no --> B{status 429<br/>or throttle code?}
+  B -- yes --> RL[ThreadsRateLimitError]
+  B -- no --> API[ThreadsAPIError]
+```
+
+The primary rate-limit signal is HTTP 429; a small set of well-documented Graph
+throttle codes (4, 17, 32, 613) act as a secondary signal. Everything else stays
+a generic `ThreadsAPIError` with the code exposed, so callers can branch without
+the SDK guessing at semantics it can't verify.
+
+## Security model
+
+- **No logging of secrets** — the SDK never calls `console`. It calls the injected `logger`, and the only request field logged is the URL, run through `redactUrl()`. Tokens are appended *inside* `send()` after the logged value is computed, so they cannot leak. A test asserts the token never appears in any log entry.
+- **Secrets server-side** — `exchangeCodeForToken` / `exchangeForLongLivedToken` need the app secret; the docstrings and README mark them server-side only.
+- **Per-token instances** — a client is bound to one token; `withToken()` returns a fresh instance for another user rather than mutating shared state.
+- **At-rest encryption is the host's job** — the SDK holds tokens only in memory; storage/encryption (e.g. Supabase Vault) is left to the application.
+
+## Key decisions & trade-offs
+
+| Decision | Why | Trade-off |
+|---|---|---|
+| **Zero runtime deps, native `fetch`** | Smallest install, no supply-chain surface, runs everywhere | Requires Node 18+ or an injected `fetch` |
+| **Class client with resource namespaces** | Familiar DX (Stripe/Octokit-style), discoverable | The client unit isn't maximally tree-shakeable — mitigated by keeping OAuth/errors/types standalone |
+| **Single `send()` engine** | One place for timeout/retry/errors/logging; reused by OAuth | Slightly more plumbing in callers (they build URLs) |
+| **Idempotency-aware retries** | Never double-publish | POST 5xx/timeout surface as errors for the caller to handle |
+| **Dual ESM + CJS** | Works as a standalone package and as an internal dep in a CJS app | Two output formats to ship |
+| **No auto-pagination helper** | YAGNI; cursors are exposed and a 5-line loop covers it | Callers page manually (see guides) |
+| **Post deletion omitted** | Exact method/path not confirmed in the docs pass; "don't invent" | Add once verified — flagged in README/CHANGELOG |
+
+## Testing strategy
+
+Tests inject a mock `fetch` (no network, no framework magic — see
+[`test/helpers.ts`](../test/helpers.ts)) and assert on the recorded request
+shape and the parsed result. Coverage concentrates on the engine (retry,
+timeout, error mapping, redaction, request shaping, OAuth, container polling)
+rather than thin pass-through resource methods. Run `pnpm test:coverage` for the
+current numbers.
+
+## Build & distribution
+
+`tsup` bundles `src/index.ts` to `dist/` as ESM (`index.js`), CJS
+(`index.cjs`), and declarations (`index.d.ts` / `index.d.cts`), with source maps
+and tree-shaking enabled. `package.json` sets `sideEffects: false` and an
+`exports` map so bundlers pick the right format and can drop unused code.

package/docs/guides.md

@@ -0,0 +1,322 @@
+# tredi-sdk — Guides
+
+Task-based recipes. Each is self-contained. For exhaustive signatures see the
+[API reference](./api-reference.md); runnable versions of several recipes live in
+[`../examples`](../examples).
+
+- [1. Server-side OAuth](#1-server-side-oauth)
+- [2. Storing & refreshing tokens](#2-storing--refreshing-tokens)
+- [3. Publishing posts](#3-publishing-posts)
+- [4. Automating replies](#4-automating-replies)
+- [5. Reading analytics](#5-reading-analytics)
+- [6. Monitoring keywords & mentions](#6-monitoring-keywords--mentions)
+- [7. Errors & rate limits](#7-errors--rate-limits)
+- [8. Pagination](#8-pagination)
+- [9. Custom runtime / injecting fetch](#9-custom-runtime--injecting-fetch)
+- [10. Logging](#10-logging)
+
+---
+
+## 1. Server-side OAuth
+
+The full handshake. Token exchanges require the app secret — keep them on the
+server. A complete version is in [`examples/oauth-flow.ts`](../examples/oauth-flow.ts).
+
+```ts
+import {
+  getAuthorizationUrl,
+  exchangeCodeForToken,
+  exchangeForLongLivedToken,
+} from 'tredi-sdk'
+
+// Route: GET /auth/threads/login
+export function login(req, res) {
+  const state = crypto.randomUUID()
+  saveState(req.session, state) // verify on callback (CSRF)
+  res.redirect(
+    getAuthorizationUrl({
+      clientId: process.env.THREADS_APP_ID!,
+      redirectUri: process.env.THREADS_REDIRECT_URI!,
+      scopes: ['threads_basic', 'threads_content_publish', 'threads_manage_replies'],
+      state,
+    }),
+  )
+}
+
+// Route: GET /auth/threads/callback?code=...&state=...
+export async function callback(req, res) {
+  if (req.query.state !== readState(req.session)) return res.status(403).end()
+
+  const short = await exchangeCodeForToken({
+    clientId: process.env.THREADS_APP_ID!,
+    clientSecret: process.env.THREADS_APP_SECRET!,
+    code: req.query.code,
+    redirectUri: process.env.THREADS_REDIRECT_URI!,
+  })
+
+  const long = await exchangeForLongLivedToken({
+    clientSecret: process.env.THREADS_APP_SECRET!,
+    shortLivedToken: short.access_token,
+  })
+
+  await saveToken(short.user_id, long.access_token, long.expires_in) // encrypt at rest
+  res.redirect('/dashboard')
+}
+```
+
+---
+
+## 2. Storing & refreshing tokens
+
+Long-lived tokens last ~60 days and must be refreshed while still valid (and at
+least 24h old). Run a daily job over tokens nearing expiry.
+
+```ts
+import { refreshLongLivedToken } from 'tredi-sdk'
+
+async function refreshExpiringTokens() {
+  const soon = await db.tokens.dueForRefresh() // e.g. expiring within 7 days
+  for (const row of soon) {
+    try {
+      const { access_token, expires_in } = await refreshLongLivedToken({
+        longLivedToken: row.token,
+      })
+      await db.tokens.update(row.userId, { token: access_token, expiresIn: expires_in })
+    } catch (err) {
+      // A token not refreshed within 60 days expires permanently — re-auth the user.
+      await notifyReauthNeeded(row.userId)
+    }
+  }
+}
+```
+
+> Store tokens encrypted (e.g. Supabase Vault). The SDK keeps them in memory only.
+
+---
+
+## 3. Publishing posts
+
+The convenience methods run the create-container → publish flow for you.
+
+```ts
+import { ThreadsClient } from 'tredi-sdk'
+const threads = new ThreadsClient({ accessToken: token })
+
+// Text
+await threads.publishing.publishText('gm ☕')
+
+// Image (with alt text for accessibility)
+await threads.publishing.publishImage({
+  imageUrl: 'https://cdn.example.com/a.jpg',
+  text: 'Morning shot',
+  altText: 'A latte on a wooden table',
+})
+
+// Video — waits for server-side processing before publishing
+await threads.publishing.publishVideo({ videoUrl: 'https://cdn.example.com/v.mp4' })
+
+// Carousel — ≥2 items
+await threads.publishing.publishCarousel({
+  items: [{ imageUrl: 'https://…/1.jpg' }, { imageUrl: 'https://…/2.jpg' }],
+  text: 'A set',
+})
+```
+
+Need control over timing (e.g. publish a video later)? Drive the steps yourself:
+
+```ts
+const { id: creationId } = await threads.publishing.createContainer({
+  mediaType: 'VIDEO',
+  videoUrl: 'https://…/v.mp4',
+})
+
+// Poll until ready, then publish when you choose.
+let status = await threads.publishing.getContainerStatus(creationId)
+while (status.status === 'IN_PROGRESS') {
+  await new Promise((r) => setTimeout(r, 3000))
+  status = await threads.publishing.getContainerStatus(creationId)
+}
+if (status.status === 'FINISHED') await threads.publishing.publishContainer(creationId)
+```
+
+Check quota before bulk publishing:
+
+```ts
+const limit = await threads.publishing.getPublishingLimit()
+console.log(`${limit.quota_usage}/${limit.config?.quota_total} posts used (24h)`)
+```
+
+---
+
+## 4. Automating replies
+
+Poll a post, auto-answer new replies, and hide spam. Full version in
+[`examples/reply-autopilot.ts`](../examples/reply-autopilot.ts).
+
+```ts
+const seen = new Set<string>()
+
+async function tick(mediaId: string) {
+  const { data } = await threads.replies.list(mediaId, { reverse: true })
+  for (const reply of data) {
+    if (!reply.id || seen.has(reply.id)) continue
+    seen.add(reply.id)
+
+    if (isSpam(reply)) {
+      await threads.replies.hide(reply.id)
+      continue
+    }
+    const text = await generateReply(reply) // your AI / rules
+    await threads.replies.publish(mediaId, text)
+  }
+}
+```
+
+If reply approvals are enabled on the post, work the queue instead:
+
+```ts
+const pending = await threads.replies.listPending(mediaId, { approvalStatus: 'pending' })
+for (const r of pending.data) {
+  await threads.replies.managePending(r.id!, !isSpam(r)) // approve or reject
+}
+```
+
+---
+
+## 5. Reading analytics
+
+```ts
+// Account level
+const account = await threads.insights.user({
+  metrics: ['views', 'likes', 'followers_count'],
+})
+for (const m of account.data) {
+  const value = m.total_value?.value ?? m.values?.at(-1)?.value
+  console.log(m.name, value)
+}
+
+// Follower demographics (breakdown is required by the API)
+await threads.insights.user({ metrics: ['follower_demographics'], breakdown: 'country' })
+
+// Per-post
+const post = await threads.insights.media('MEDIA_ID', ['views', 'likes', 'replies'])
+```
+
+---
+
+## 6. Monitoring keywords & mentions
+
+```ts
+// Keyword search (needs threads_keyword_search)
+const recent = await threads.search.keyword('cold brew', {
+  searchType: 'RECENT',
+  mediaType: 'TEXT',
+  limit: 50,
+})
+
+// Mentions of the authenticated user
+const mentions = await threads.mentions.list({ limit: 25 })
+```
+
+---
+
+## 7. Errors & rate limits
+
+Catch broadly with `ThreadsError`, or narrow to act on specific failures.
+
+```ts
+import {
+  ThreadsAuthError,
+  ThreadsRateLimitError,
+  ThreadsValidationError,
+  ThreadsError,
+} from 'tredi-sdk'
+
+try {
+  await threads.publishing.publishText('hi')
+} catch (err) {
+  if (err instanceof ThreadsAuthError) {
+    await refreshTokenAndRetry()             // token expired/invalid
+  } else if (err instanceof ThreadsRateLimitError) {
+    await wait(err.retryAfterMs ?? 60_000)   // throttled
+  } else if (err instanceof ThreadsValidationError) {
+    throw err                                // bug in your input — fix it
+  } else if (err instanceof ThreadsError) {
+    report(err)                              // ThreadsAPIError / Network / Timeout
+  }
+}
+```
+
+The SDK already retries transient failures (network, 429, and 5xx/timeouts on
+GETs) with backoff. Tune or disable it:
+
+```ts
+new ThreadsClient({ accessToken, retry: { maxRetries: 4, maxDelayMs: 15_000 } })
+new ThreadsClient({ accessToken, retry: false }) // handle retries yourself
+```
+
+Writes (POST) are **not** retried on 5xx/timeout to avoid duplicate posts — see
+[architecture.md](./architecture.md#retry--idempotency-model).
+
+---
+
+## 8. Pagination
+
+List endpoints return `{ data, paging: { cursors: { after } } }`. Loop with the
+`after` cursor:
+
+```ts
+async function* allPosts(threads: ThreadsClient) {
+  let after: string | undefined
+  do {
+    const page = await threads.posts.list({ limit: 50, after })
+    yield* page.data
+    after = page.paging?.cursors?.after
+  } while (after)
+}
+
+for await (const post of allPosts(threads)) {
+  console.log(post.id, post.text)
+}
+```
+
+The same pattern works for `replies.list`, `mentions.list`, and `search.keyword`.
+
+---
+
+## 9. Custom runtime / injecting fetch
+
+On runtimes without global `fetch`, or in tests, pass your own:
+
+```ts
+import { ThreadsClient } from 'tredi-sdk'
+
+const threads = new ThreadsClient({
+  accessToken: token,
+  fetch: myFetch,        // any (url, init) => Promise<Response>
+  baseUrl: 'https://graph.threads.net',
+  timeoutMs: 15_000,
+})
+```
+
+In unit tests, a fake `fetch` lets you assert request shape without a network —
+see [`test/helpers.ts`](../test/helpers.ts).
+
+---
+
+## 10. Logging
+
+Wire the logger to your stack. Secrets are redacted before they reach you.
+
+```ts
+import pino from 'pino'
+const log = pino()
+
+const threads = new ThreadsClient({
+  accessToken: token,
+  logger: { log: (level, msg, ctx) => log[level]({ ...ctx }, msg) },
+})
+// emits: threads.request.success { method, url: "…access_token=REDACTED", attempt, durationMs }
+```
+
+Pass nothing to stay silent (the default `noopLogger`).

package/examples/fetch-insights.ts

@@ -0,0 +1,32 @@
+/**
+ * Pull account + recent-post analytics.
+ *
+ *   THREADS_TOKEN=... node --experimental-strip-types examples/fetch-insights.ts
+ */
+
+import { ThreadsClient } from 'tredi-sdk'
+
+const threads = new ThreadsClient({ accessToken: process.env.THREADS_TOKEN! })
+
+async function main() {
+  const me = await threads.profile.get()
+  console.log(`@${me.username} (${me.id})`)
+
+  const account = await threads.insights.user({ metrics: ['views', 'likes', 'followers_count'] })
+  for (const metric of account.data) {
+    const value = metric.total_value?.value ?? metric.values?.at(-1)?.value
+    console.log(`  ${metric.name}: ${value ?? 'n/a'}`)
+  }
+
+  const posts = await threads.posts.list({ limit: 5 })
+  for (const post of posts.data) {
+    const stats = await threads.insights.media(post.id!, { metrics: ['views', 'likes', 'replies'] })
+    const summary = stats.data.map((m) => `${m.name}=${m.total_value?.value ?? 0}`).join(' ')
+    console.log(`  ${post.id} → ${summary}`)
+  }
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

package/examples/oauth-flow.ts

@@ -0,0 +1,55 @@
+/**
+ * OAuth flow (server-side). Shows the four steps end to end.
+ * Run pieces of this inside your web framework's route handlers.
+ *
+ *   THREADS_APP_ID=... THREADS_APP_SECRET=... node --experimental-strip-types examples/oauth-flow.ts
+ */
+
+import {
+  exchangeCodeForToken,
+  exchangeForLongLivedToken,
+  getAuthorizationUrl,
+  refreshLongLivedToken,
+} from 'tredi-sdk'
+
+const APP_ID = process.env.THREADS_APP_ID!
+const APP_SECRET = process.env.THREADS_APP_SECRET!
+const REDIRECT_URI = 'https://app.example.com/auth/threads/callback'
+
+// Step 1 — send the user here (store `state` to verify on return).
+export function loginUrl(state: string): string {
+  return getAuthorizationUrl({
+    clientId: APP_ID,
+    redirectUri: REDIRECT_URI,
+    scopes: ['threads_basic', 'threads_content_publish', 'threads_manage_replies'],
+    state,
+  })
+}
+
+// Steps 2–3 — handle the redirect: code → short token → long-lived token.
+export async function handleCallback(code: string) {
+  const short = await exchangeCodeForToken({
+    clientId: APP_ID,
+    clientSecret: APP_SECRET,
+    code,
+    redirectUri: REDIRECT_URI,
+  })
+
+  const long = await exchangeForLongLivedToken({
+    clientSecret: APP_SECRET,
+    shortLivedToken: short.access_token,
+  })
+
+  // Persist long.access_token + expiry against short.user_id (encrypted at rest).
+  return { userId: short.user_id, token: long.access_token, expiresIn: long.expires_in }
+}
+
+// Step 4 — run on a schedule before the 60-day expiry (token must be ≥24h old).
+export async function refresh(token: string) {
+  const refreshed = await refreshLongLivedToken({ longLivedToken: token })
+  return { token: refreshed.access_token, expiresIn: refreshed.expires_in }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  console.log('Authorize URL:\n', loginUrl('demo-state'))
+}

package/examples/publish-text.ts

@@ -0,0 +1,39 @@
+/**
+ * Publish a post and read back its insights.
+ *
+ *   THREADS_TOKEN=... node --experimental-strip-types examples/publish-text.ts "Hello, Threads"
+ */
+
+import { ThreadsClient, ThreadsRateLimitError } from 'tredi-sdk'
+
+const threads = new ThreadsClient({
+  accessToken: process.env.THREADS_TOKEN!,
+  logger: { log: (level, message, ctx) => console[level === 'debug' ? 'log' : level](message, ctx ?? '') },
+})
+
+async function main() {
+  const text = process.argv[2] ?? 'Posted via tredi-sdk'
+
+  // Check quota before publishing.
+  const limit = await threads.publishing.getPublishingLimit()
+  console.log('Posts used in last 24h:', limit.quota_usage, '/', limit.config?.quota_total)
+
+  try {
+    const post = await threads.publishing.publishText(text)
+    console.log('Published post id:', post.id)
+
+    const insights = await threads.insights.media(post.id, { metrics: ['views', 'likes'] })
+    console.log('Insights:', insights.data.map((m) => `${m.name}=${m.total_value?.value ?? 0}`))
+  } catch (err) {
+    if (err instanceof ThreadsRateLimitError) {
+      console.error(`Rate limited. Retry after ~${(err.retryAfterMs ?? 60_000) / 1000}s`)
+    } else {
+      throw err
+    }
+  }
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

package/examples/reply-autopilot.ts

@@ -0,0 +1,62 @@
+/**
+ * Autopilot reply bot: poll a post's replies, auto-answer new ones, and hide
+ * spam. Swap `generateReply` / `isSpam` for your own AI/moderation logic — the
+ * SDK supplies every Threads call this loop needs.
+ *
+ *   THREADS_TOKEN=... node --experimental-strip-types examples/reply-autopilot.ts MEDIA_ID
+ */
+
+import { ThreadsClient, type ThreadsReply } from 'tredi-sdk'
+
+const threads = new ThreadsClient({ accessToken: process.env.THREADS_TOKEN! })
+const POLL_INTERVAL_MS = 30_000
+
+// Replace these with real implementations (Claude, a classifier, rules, …).
+function isSpam(reply: ThreadsReply): boolean {
+  return /https?:\/\/|free money|crypto/i.test(reply.text ?? '')
+}
+async function generateReply(reply: ThreadsReply): Promise<string> {
+  return `Thanks for the reply, @${reply.username}! 🙌`
+}
+
+async function processNewReplies(mediaId: string, seen: Set<string>) {
+  const { data } = await threads.replies.list(mediaId, { reverse: true })
+
+  for (const reply of data) {
+    if (!reply.id || seen.has(reply.id) || reply.is_reply === false) continue
+    seen.add(reply.id)
+
+    if (isSpam(reply)) {
+      await threads.replies.hide(reply.id)
+      console.log(`Hid spam reply ${reply.id}`)
+      continue
+    }
+
+    const text = await generateReply(reply)
+    const answer = await threads.replies.publish(mediaId, text)
+    console.log(`Replied ${answer.id} → ${reply.id}`)
+  }
+}
+
+async function main() {
+  const mediaId = process.argv[2]
+  if (!mediaId) throw new Error('Usage: reply-autopilot.ts <MEDIA_ID>')
+
+  const seen = new Set<string>()
+  console.log(`Autopilot watching ${mediaId} every ${POLL_INTERVAL_MS / 1000}s…`)
+
+  for (;;) {
+    try {
+      await processNewReplies(mediaId, seen)
+    } catch (err) {
+      // The SDK already retried transient failures; log and keep the loop alive.
+      console.error('poll failed:', err instanceof Error ? err.message : err)
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS))
+  }
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})