@tapthrough/expo 0.0.0-stage → 0.1.1

package/src/core/ideas.ts

@@ -0,0 +1,337 @@
+import type { Platform } from '@tapthrough/protocol'
+import type { PreviewContext } from './feedback.js'
+
+export type IdeaStatus =
+  | 'grooming'
+  | 'needs_answers'
+  | 'ready'
+  | 'building'
+  | 'built'
+  | 'ready_to_test'
+  | 'approved'
+  | 'merged'
+  | 'closed'
+  | 'declined'
+  | 'failed'
+  | 'not_set_up'
+
+export type IdeaAction = 'answer' | 'build' | 'approve' | 'retry'
+
+/** One step from sent to merged: done, in progress, not reached yet, or where it stopped. */
+export interface IdeaStage {
+  key: 'sent' | 'written' | 'built' | 'preview' | 'merged'
+  title: string
+  state: 'done' | 'active' | 'waiting' | 'failed'
+  detail: string | null
+  at: string | null
+}
+
+/** An idea someone sent from the app, as Tapthrough reports it. */
+export interface Idea {
+  id: string
+  status: IdeaStatus
+  body: string
+  title: string | null
+  summary: string | null
+  questions: string[]
+  steps: { action: string; expect: string }[]
+  authorName: string | null
+  issueNumber: number | null
+  issueUrl: string | null
+  prNumber: number | null
+  prUrl: string | null
+  previewUrl: string | null
+  note: string | null
+  /** e.g. "Claude has a question", from the server so wording can change without an app update. */
+  statusLine: string
+  /** Older servers send none; the app then shows the status line only. */
+  stages?: IdeaStage[]
+  /** Something looks stuck or slow; null when all is well. */
+  warning?: string | null
+  runUrl?: string | null
+  actionsUrl?: string
+  createdAt: string
+  actions: IdeaAction[]
+}
+
+/** An open PR with a preview, for switching builds without going back to GitHub. */
+export interface OpenPr {
+  number: number
+  title: string
+  author: string | null
+  draft: boolean
+  current: boolean
+  openUrl: string | null
+  needsNewBuild: boolean
+  fromIdea: boolean
+  updatedAt: string
+}
+
+export type ApproveOutcome = 'review' | 'auto_merge' | 'merged'
+
+type Result<T> = ({ ok: true } & T) | { ok: false; message: string }
+
+interface Options {
+  apiUrl: string
+  fetch?: typeof fetch
+}
+
+const OFFLINE = "Couldn't reach Tapthrough. Check your connection and try again."
+
+/**
+ * Who's asking: a PR build, proved by its running update, or a staging or
+ * TestFlight build, proved by the repo's app key.
+ */
+export type Caller = { kind: 'build'; preview: PreviewContext } | { kind: 'key'; appKey: string }
+
+function credential(caller: Caller, platform: Platform) {
+  return caller.kind === 'build'
+    ? {
+        apiVersion: 1,
+        updateGroupId: caller.preview.updateGroupId,
+        projectId: caller.preview.projectId,
+        platform,
+      }
+    : { apiVersion: 1, appKey: caller.appKey, platform }
+}
+
+function query(caller: Caller, platform: Platform) {
+  return new URLSearchParams(
+    caller.kind === 'build'
+      ? {
+          updateGroupId: caller.preview.updateGroupId,
+          projectId: caller.preview.projectId,
+          platform,
+        }
+      : { appKey: caller.appKey, platform },
+  )
+}
+
+async function call<T>(
+  options: Options,
+  path: string,
+  init: { method: 'GET' } | { method: 'POST'; body: unknown },
+  pick: (body: Record<string, unknown>) => T | undefined,
+): Promise<Result<T>> {
+  const doFetch = options.fetch ?? fetch
+  let response: Response
+  try {
+    response = await doFetch(`${options.apiUrl.replace(/\/$/, '')}${path}`, {
+      method: init.method,
+      ...(init.method === 'POST'
+        ? { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(init.body) }
+        : {}),
+    })
+  } catch {
+    return { ok: false, message: OFFLINE }
+  }
+  const body = (await response.json().catch(() => undefined)) as
+    | (Record<string, unknown> & { error?: { message?: string } })
+    | undefined
+  const value = response.ok && body ? pick(body) : undefined
+  if (value !== undefined) return { ok: true, ...value }
+  // A server from before ideas answers 404 without an error code.
+  if (response.status === 404 && !body?.error) {
+    return { ok: false, message: 'This version of Tapthrough doesn’t take ideas yet.' }
+  }
+  return { ok: false, message: body?.error?.message ?? `Tapthrough returned ${response.status}.` }
+}
+
+const pickIdea = (body: Record<string, unknown>) =>
+  body.idea && typeof body.idea === 'object' ? { idea: body.idea as Idea } : undefined
+
+export interface IdeaDraft {
+  body: string
+  authorName?: string
+  authorEmail?: string
+  route?: string
+  device?: { os?: string; osVersion?: string; model?: string }
+  screenshot?: { contentType: 'image/jpeg' | 'image/png'; base64: string }
+}
+
+/** Sends an idea; Claude starts writing it up in the repo's fix workflow. Never throws. */
+export function submitIdea(
+  input: { caller: Caller; platform: Platform; draft: IdeaDraft },
+  options: Options,
+) {
+  const { draft } = input
+  return call(
+    options,
+    '/api/v1/ideas',
+    {
+      method: 'POST',
+      body: {
+        ...credential(input.caller, input.platform),
+        body: draft.body,
+        ...(draft.authorName ? { authorName: draft.authorName } : {}),
+        ...(draft.authorEmail ? { authorEmail: draft.authorEmail } : {}),
+        ...(draft.route ? { route: draft.route } : {}),
+        ...(draft.device ? { device: draft.device } : {}),
+        ...(draft.screenshot ? { screenshot: draft.screenshot } : {}),
+      },
+    },
+    pickIdea,
+  )
+}
+
+/** The app's recent ideas, newest first; an empty list when Tapthrough can't say. */
+export async function fetchIdeas(
+  caller: Caller,
+  platform: Platform,
+  options: Options,
+): Promise<Idea[]> {
+  const path = `/api/v1/ideas?${query(caller, platform)}`
+  const result = await call(options, path, { method: 'GET' }, (body) =>
+    Array.isArray(body.ideas) ? { ideas: body.ideas as Idea[] } : undefined,
+  )
+  return result.ok ? result.ideas : []
+}
+
+/** The repo's open PRs with previews; null when Tapthrough can't say. */
+export async function fetchOpenPrs(
+  preview: PreviewContext,
+  platform: Platform,
+  options: Options,
+): Promise<OpenPr[] | null> {
+  const path = `/api/v1/pulls?${query({ kind: 'build', preview }, platform)}`
+  const result = await call(options, path, { method: 'GET' }, (body) =>
+    Array.isArray(body.pulls) ? { pulls: body.pulls as OpenPr[] } : undefined,
+  )
+  return result.ok ? result.pulls : null
+}
+
+/** Answers Claude's questions; it writes the idea up again with them. Never throws. */
+export function answerIdea(
+  input: {
+    caller: Caller
+    platform: Platform
+    id: string
+    answers: string[]
+    by?: string
+  },
+  options: Options,
+) {
+  return call(
+    options,
+    `/api/v1/ideas/${encodeURIComponent(input.id)}/answers`,
+    {
+      method: 'POST',
+      body: {
+        ...credential(input.caller, input.platform),
+        answers: input.answers,
+        ...(input.by ? { by: input.by } : {}),
+      },
+    },
+    pickIdea,
+  )
+}
+
+/** Build It, Retry or Approve on one idea. Never throws. */
+export function ideaAction(
+  input: {
+    caller: Caller
+    platform: Platform
+    id: string
+    action: 'build' | 'retry' | 'approve'
+    by?: string
+  },
+  options: Options,
+) {
+  return call(
+    options,
+    `/api/v1/ideas/${encodeURIComponent(input.id)}/${input.action}`,
+    {
+      method: 'POST',
+      body: { ...credential(input.caller, input.platform), ...(input.by ? { by: input.by } : {}) },
+    },
+    (body) => {
+      const picked = pickIdea(body)
+      if (!picked) return undefined
+      const result = body.result
+      return {
+        ...picked,
+        approve:
+          result === 'review' || result === 'auto_merge' || result === 'merged'
+            ? (result as ApproveOutcome)
+            : null,
+      }
+    },
+  )
+}
+
+/** Ideas waiting on a person: questions to answer, or a build to test. */
+export function ideasNeedingYou(ideas: Idea[]): number {
+  return ideas.filter((idea) => idea.status === 'needs_answers' || idea.status === 'ready_to_test')
+    .length
+}
+
+/** What Approve did, in plain words. */
+export function approveMessage(outcome: ApproveOutcome | null): string {
+  if (outcome === 'merged') return 'Approved and merged.'
+  if (outcome === 'auto_merge') return 'Approved. It merges once its checks pass.'
+  return 'Approved. An engineer reviews and merges it.'
+}
+
+/** Grooming, building or waiting on a preview: worth refreshing often while someone watches. */
+export function isMoving(idea: Idea): boolean {
+  return idea.status === 'grooming' || idea.status === 'building' || idea.status === 'built'
+}
+
+/** "2:41 PM" today, "Nov 10" before, for a timeline step. */
+export function stepTime(iso: string | null, now = new Date()): string | null {
+  if (!iso) return null
+  const date = new Date(iso)
+  if (Number.isNaN(date.getTime())) return null
+  const sameDay = date.toDateString() === now.toDateString()
+  return sameDay
+    ? date.toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' })
+    : date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
+}
+
+export interface StaffReport {
+  body: string
+  reporterName?: string
+  route?: string
+  device?: { os?: string; osVersion?: string; model?: string }
+  app?: { version?: string; build?: string }
+  screenshot?: { contentType: 'image/jpeg' | 'image/png'; base64: string }
+  annotations?: unknown[]
+  diagnostics?: unknown
+}
+
+/**
+ * Files a report from a staging or TestFlight build. There's no PR to comment
+ * on, so Tapthrough opens a GitHub issue. Never throws.
+ */
+export function sendStaffReport(
+  input: { appKey: string; platform: Platform; report: StaffReport },
+  options: Options,
+) {
+  const { report } = input
+  return call(
+    options,
+    '/api/v1/reports',
+    {
+      method: 'POST',
+      body: {
+        apiVersion: 1,
+        appKey: input.appKey,
+        platform: input.platform,
+        body: report.body,
+        ...(report.reporterName ? { reporterName: report.reporterName } : {}),
+        ...(report.route ? { route: report.route } : {}),
+        ...(report.device ? { device: report.device } : {}),
+        ...(report.app ? { app: report.app } : {}),
+        ...(report.screenshot ? { screenshot: report.screenshot } : {}),
+        ...(report.screenshot && report.annotations?.length
+          ? { annotations: report.annotations }
+          : {}),
+        ...(report.diagnostics ? { diagnostics: report.diagnostics } : {}),
+      },
+    },
+    (body) =>
+      typeof body.issueNumber === 'number' && typeof body.issueUrl === 'string'
+        ? { issueNumber: body.issueNumber, issueUrl: body.issueUrl }
+        : undefined,
+  )
+}

package/src/core/launch.ts

@@ -0,0 +1,119 @@
+import { ErrorResponse, type Flags, resolveRoute, SeedHookResponse } from '@tapthrough/protocol'
+import { decodeTokenClaims } from './feedback.js'
+
+/** Logs the app in with the session the seed hook created. */
+export interface AuthAdapter {
+  signIn(session: Record<string, unknown>): Promise<void>
+}
+
+/** Clears one piece of local state, e.g. a query cache or a persisted store. */
+export type ResetTarget = () => void | Promise<void>
+
+export interface LaunchDeps {
+  seedHookUrl: string
+  /**
+   * The app's own IDs (iOS bundle ID, Android package). A token for any other
+   * app is refused before anything changes, so a stray link can't swap accounts.
+   */
+  expectedAudiences?: string[]
+  auth: AuthAdapter
+  reset?: ResetTarget[]
+  applyFlags?: (flags: Flags) => void
+  navigate: (path: string) => void | Promise<void>
+  fetch?: typeof fetch
+  /** Called as each part of the launch starts, so a UI can show progress. */
+  onStage?: (stage: LaunchStage) => void
+}
+
+/** The parts of a launch, in order. */
+export type LaunchStage = 'seeding' | 'resetting' | 'signing_in' | 'opening'
+
+export interface LaunchError {
+  code: string
+  /** Shown to the reviewer as is. */
+  message: string
+}
+
+export type LaunchResult = { ok: true; path: string } | { ok: false; error: LaunchError }
+
+const fail = (code: string, message: string): LaunchResult => ({
+  ok: false,
+  error: { code, message },
+})
+
+/**
+ * The launch sequence for one link token: ask the seed hook for a session,
+ * clear local state, log in, apply flags, then open the scenario's screen.
+ * Never throws; every failure comes back as a reviewer-facing message.
+ */
+export async function runLaunch(token: string, deps: LaunchDeps): Promise<LaunchResult> {
+  const doFetch = deps.fetch ?? fetch
+
+  if (deps.expectedAudiences?.length) {
+    const aud = decodeTokenClaims(token)?.aud
+    const audiences = Array.isArray(aud) ? aud : [aud]
+    if (!audiences.some((a) => typeof a === 'string' && deps.expectedAudiences?.includes(a))) {
+      return fail('wrong_app', 'This link is for a different app.')
+    }
+  }
+
+  deps.onStage?.('seeding')
+  let response: Response
+  try {
+    response = await doFetch(deps.seedHookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ token }),
+    })
+  } catch {
+    return fail('network', "Couldn't reach the seed hook. Check your connection and try again.")
+  }
+
+  const body: unknown = await response.json().catch(() => undefined)
+  if (!response.ok) {
+    const error = ErrorResponse.safeParse(body)
+    if (error.success) return { ok: false, error: error.data.error }
+    return fail('seed_hook_failed', `The seed hook returned ${response.status}.`)
+  }
+  const seeded = SeedHookResponse.safeParse(body)
+  if (!seeded.success) {
+    return fail('bad_response', 'The seed hook returned a response this app version cannot read.')
+  }
+
+  // Resolve before changing anything, so a bad route leaves the app untouched.
+  let path: string
+  try {
+    path = resolveRoute(seeded.data.route, seeded.data.refs)
+  } catch (error) {
+    return fail('bad_route', error instanceof Error ? error.message : 'Could not resolve the route')
+  }
+
+  // Reset before signing in, so clearing persisted keys can't remove the new session.
+  deps.onStage?.('resetting')
+  try {
+    for (const target of deps.reset ?? []) await target()
+  } catch (error) {
+    return fail('reset_failed', `Couldn't clear local data: ${messageOf(error)}`)
+  }
+
+  deps.onStage?.('signing_in')
+  try {
+    await deps.auth.signIn(seeded.data.session)
+  } catch (error) {
+    return fail('sign_in_failed', `Couldn't sign in as the test user: ${messageOf(error)}`)
+  }
+
+  deps.onStage?.('opening')
+  deps.applyFlags?.(seeded.data.flags)
+
+  try {
+    await deps.navigate(path)
+  } catch (error) {
+    return fail('navigation_failed', `Couldn't open ${path}: ${messageOf(error)}`)
+  }
+  return { ok: true, path }
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/core/reset.ts

@@ -0,0 +1,28 @@
+import type { ResetTarget } from './launch.js'
+
+/** Clears a TanStack Query cache so the test user never sees the previous user's data. */
+export function resetQueryClient(queryClient: { clear(): void }): ResetTarget {
+  return () => queryClient.clear()
+}
+
+/** Removes persisted keys from AsyncStorage, MMKV or anything with `removeItem`. */
+export function resetStorage(
+  storage: { removeItem(key: string): void | Promise<void> },
+  keys: string[],
+): ResetTarget {
+  return async () => {
+    for (const key of keys) await storage.removeItem(key)
+  }
+}
+
+interface ResettableStore {
+  getInitialState(): unknown
+  setState(state: never, replace: true): void
+}
+
+/** Puts Zustand stores back to their initial state. */
+export function resetStores(stores: ResettableStore[]): ResetTarget {
+  return () => {
+    for (const store of stores) store.setState(store.getInitialState() as never, true)
+  }
+}

package/src/core/review.ts

@@ -0,0 +1,148 @@
+import { type Bounds, BUBBLE_SIZE, EDGE_MARGIN, type Point } from './bubble.js'
+import type {
+  Checklist,
+  ChecklistScenario,
+  LibraryEntry,
+  SetupLine,
+  StepResultValue,
+} from './feedback.js'
+import type { LaunchStage } from './launch.js'
+
+/** Step results keyed `scenario:index`, with the reviewer's own taps applied on top. */
+export type Results = Record<string, StepResultValue | undefined>
+
+export const stepId = (scenarioKey: string, index: number) => `${scenarioKey}:${index}`
+
+/** The results the server already has for each step. */
+export function resultsFrom(checklist: Checklist | null): Results {
+  if (!checklist) return {}
+  return Object.fromEntries(
+    checklist.scenarios.flatMap((scenario) =>
+      scenario.steps.map((step) => [stepId(scenario.key, step.index), step.result?.result]),
+    ),
+  )
+}
+
+export interface ScenarioProgress {
+  total: number
+  /** Steps with any result, skips included. */
+  checked: number
+  passed: number
+  failed: number
+  state: 'new' | 'partial' | 'passed' | 'failed'
+}
+
+export function scenarioProgress(scenario: ChecklistScenario, results: Results): ScenarioProgress {
+  const values = scenario.steps.map((step) => results[stepId(scenario.key, step.index)])
+  const checked = values.filter(Boolean).length
+  const passed = values.filter((v) => v === 'pass').length
+  const failed = values.filter((v) => v === 'fail').length
+  const total = values.length
+  const state =
+    checked === 0 ? 'new' : checked < total ? 'partial' : failed > 0 ? 'failed' : 'passed'
+  return { total, checked, passed, failed, state }
+}
+
+/**
+ * Position in `scenario.steps` of the first step without a result, starting at
+ * `from` and wrapping round. -1 when every step has one.
+ */
+export function nextOpenStep(scenario: ChecklistScenario, results: Results, from = 0): number {
+  const n = scenario.steps.length
+  for (let k = 0; k < n; k++) {
+    const i = (((from + k) % n) + n) % n
+    const step = scenario.steps[i]
+    if (step && !results[stepId(scenario.key, step.index)]) return i
+  }
+  return -1
+}
+
+/** The next scenario with a step left, after `afterKey` and wrapping round. */
+export function nextOpenScenario(
+  checklist: Checklist,
+  results: Results,
+  afterKey?: string,
+): ChecklistScenario | undefined {
+  const list = checklist.scenarios
+  const start = afterKey ? list.findIndex((s) => s.key === afterKey) + 1 : 0
+  for (let k = 0; k < list.length; k++) {
+    const scenario = list[(start + k) % list.length]
+    if (scenario && nextOpenStep(scenario, results) >= 0) return scenario
+  }
+  return undefined
+}
+
+/** Scenarios in the run that aren't in the PR's plan, for "Other states". */
+export function otherStates(checklist: Checklist): LibraryEntry[] {
+  const planned = new Set(checklist.scenarios.map((s) => s.key))
+  return (checklist.library ?? []).filter((entry) => !entry.picked && !planned.has(entry.key))
+}
+
+export interface Placement {
+  side: 'left' | 'right'
+  /** Distance from the screen's `side` edge. */
+  inset: number
+  width: number
+  vertical: 'above' | 'below'
+  /** Distance from the screen's bottom (above the button) or top (below it). */
+  offset: number
+  maxHeight: number
+}
+
+/**
+ * Where the popover goes for a button resting at `anchor`: on the button's
+ * side of the screen, and above or below it, whichever has more room.
+ */
+export function popoverPlacement(
+  anchor: Point,
+  bounds: Bounds,
+  preferred: { width: number; maxHeight: number } = { width: 320, maxHeight: 560 },
+  size = BUBBLE_SIZE,
+  gap = 10,
+): Placement {
+  const side = anchor.x + size / 2 < bounds.width / 2 ? 'left' : 'right'
+  const width = Math.min(preferred.width, bounds.width - EDGE_MARGIN * 2)
+  const above = anchor.y - gap - bounds.insetTop
+  const below = bounds.height - bounds.insetBottom - (anchor.y + size + gap)
+  const vertical = above >= below ? 'above' : 'below'
+  const room = Math.max(vertical === 'above' ? above : below, 0)
+  return {
+    side,
+    inset: EDGE_MARGIN,
+    width,
+    vertical,
+    offset: vertical === 'above' ? bounds.height - anchor.y + gap : anchor.y + size + gap,
+    maxHeight: Math.min(preferred.maxHeight, room),
+  }
+}
+
+export type SetupProgress = 'requesting' | LaunchStage | 'done'
+export type LineState = 'waiting' | 'active' | 'done'
+
+const RANK: Record<SetupProgress, number> = {
+  requesting: 0,
+  seeding: 1,
+  resetting: 2,
+  signing_in: 3,
+  opening: 4,
+  done: 5,
+}
+// The seed hook makes the account and data; sign-in uses the account; flags and
+// navigation come last. Each line is done once the launch is past its part.
+const ACTIVE_AT: Record<SetupLine['kind'], number> = { data: 1, account: 3, flag: 4, screen: 4 }
+const DONE_AT: Record<SetupLine['kind'], number> = { data: 2, account: 4, flag: 4, screen: 5 }
+
+/** How far along each setup line is, for ticking them off while a launch runs. */
+export function setupLineStates(lines: SetupLine[], progress: SetupProgress): LineState[] {
+  const rank = RANK[progress]
+  const states = lines.map(
+    (line): LineState =>
+      rank >= DONE_AT[line.kind] ? 'done' : rank >= ACTIVE_AT[line.kind] ? 'active' : 'waiting',
+  )
+  // Something is always visibly happening until the end.
+  if (!states.includes('active')) {
+    const first = states.indexOf('waiting')
+    if (first >= 0) states[first] = 'active'
+  }
+  return states
+}

package/src/core/url.ts

@@ -0,0 +1,21 @@
+/** Path the preview link opens: `<scheme>://tapthrough/launch?t=<token>`, or the same path on a universal link. */
+export const LAUNCH_PATH = 'tapthrough/launch'
+
+// Parsed by hand: React Native's URL polyfill doesn't handle custom schemes everywhere.
+const LAUNCH_URL = /(?:^|\/)tapthrough\/launch\/?\?(?:[^#]*&)?t=([^&#]+)/
+
+/**
+ * Returns the link token from a launch URL or path, or null for any other URL.
+ * Accepts `myapp://tapthrough/launch?t=…`, `https://host/tapthrough/launch?t=…`
+ * and the bare path Expo Router passes to `+native-intent`.
+ */
+export function parseLaunchUrl(url: string | null | undefined): string | null {
+  if (!url) return null
+  const match = LAUNCH_URL.exec(url)
+  if (!match?.[1]) return null
+  try {
+    return decodeURIComponent(match[1])
+  } catch {
+    return null
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,15 @@
+import { useCallback, useSyncExternalStore } from 'react'
+import type { LaunchState } from './core/controller.js'
+import { getFlagOverride, subscribeToFlagOverrides } from './core/flags.js'
+import { controller } from './runtime.js'
+
+/** The scenario's value for a flag, or undefined when the scenario doesn't set it. */
+export function useFlagOverride(name: string): boolean | string | undefined {
+  const get = useCallback(() => getFlagOverride(name), [name])
+  return useSyncExternalStore(subscribeToFlagOverrides, get, get)
+}
+
+/** Where the current launch is: idle, launching, done or error. */
+export function useLaunchState(): LaunchState {
+  return useSyncExternalStore(controller.subscribe, controller.getState, controller.getState)
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { LaunchState } from './core/controller.js'
+export { getFlagOverride, getFlagOverrides } from './core/flags.js'
+export type { AuthAdapter, LaunchError, ResetTarget } from './core/launch.js'
+export { resetQueryClient, resetStorage, resetStores } from './core/reset.js'
+export { LAUNCH_PATH, parseLaunchUrl } from './core/url.js'
+export { useFlagOverride, useLaunchState } from './hooks.js'
+export { handleLaunchPath, redirectSystemPath } from './native-intent.js'
+export { Tapthrough, type TapthroughProps } from './Tapthrough.js'