@alumbwe/anvil 1.0.20 → 1.0.21

package/vendor/@anvil/common/src/constants/anvil-onboarding-gate.ts

@@ -0,0 +1,55 @@
+/**
+ * Who gets shown the onboarding form.
+ *
+ * Nothing here is a permission check. Onboarding never refuses a request on any
+ * surface — the entire mechanism is one redirect, to a form with a Skip button,
+ * fired at most once per browser. What this decides is who is interrupted.
+ *
+ * The answer is: **anyone who has not answered, once.** New signups get it on
+ * their way in; a long-standing account gets it the next time they sign in
+ * through the web portal. There is deliberately no cutover date any more. One
+ * existed when the form was a blocking gate, to keep existing users from being
+ * locked out of a product they already used — with nothing to lock them out of,
+ * a cutover only means never learning anything about the 200,000 accounts we
+ * already have. The Skip button and the seen-cookie are what protect them now,
+ * and they cost a single dismissible screen instead of an exemption.
+ *
+ * The polarity is deliberate: **an unset or `off` switch shows it to NOBODY.**
+ * Absence of config disables the feature rather than enabling it universally.
+ * This repo has already paid for the opposite convention once — a deleted env
+ * var silently activating a default is documented in
+ * db-capacity-and-scaling.md §10.6 — and here that mistake would present as
+ * every user meeting a form nobody decided to launch.
+ */
+
+export type OnboardingRequirementInput = {
+  /** Parsed `ANVIL_ONBOARDING_ENABLED`. */
+  enabled: boolean
+  /** Whether the user has answered every question. */
+  complete: boolean
+}
+
+export type OnboardingRequirement =
+  | { required: false; reason: 'gate_disabled' | 'already_complete' }
+  | { required: true }
+
+export function evaluateOnboardingRequirement(
+  input: OnboardingRequirementInput,
+): OnboardingRequirement {
+  // Not switched on — nobody is asked. See the polarity note above.
+  if (!input.enabled) return { required: false, reason: 'gate_disabled' }
+  if (input.complete) return { required: false, reason: 'already_complete' }
+  return { required: true }
+}
+
+/**
+ * Read the on/off switch.
+ *
+ * Anything other than an explicit affirmative is off, so a typo, an empty
+ * string or a deleted variable all fail the same safe way.
+ */
+export function parseOnboardingEnabled(raw: string | null | undefined): boolean {
+  const trimmed = raw?.trim().toLowerCase()
+  return trimmed === 'on' || trimmed === 'true' || trimmed === '1'
+}
+

package/vendor/@anvil/common/src/constants/anvil-onboarding.ts

@@ -0,0 +1,307 @@
+/**
+ * The post-signup onboarding questionnaire.
+ *
+ * Five questions, each a fixed option list plus a free-text "Other". Shared
+ * between the form, the persistence layer and the admin view so a renamed
+ * option cannot silently split one answer into two in the analytics.
+ *
+ * Why the option ids are opaque and permanent
+ * -------------------------------------------
+ * The stored value is the id, never the label. Labels are copy and will be
+ * reworded; ids are data. Changing a label is free, changing an id
+ * retroactively rewrites history — so ids here are append-only. Retire an
+ * option by removing it from the list, never by renaming it.
+ *
+ * When an option is retired or broadened, its old answers do not disappear:
+ * `ONBOARDING_LEGACY_OPTION_IDS` below maps the retired id onto whichever
+ * current option now covers it, and the admin tally applies that at read time.
+ * Nothing rewrites what is stored — the stored answer stays exactly what the
+ * person picked on the day they picked it.
+ */
+
+export type OnboardingQuestionId =
+  | 'referral_source'
+  | 'role'
+  | 'proficiency'
+  | 'intended_use'
+  | 'subscriptions'
+
+export type OnboardingOption = {
+  /** Stored verbatim. Append-only — see the note above. */
+  id: string
+  label: string
+  /** Choosing this clears every other option, and vice versa. Only meaningful
+   *  on a multi-select — "none of them" and "these ones" cannot both be true. */
+  exclusive?: boolean
+}
+
+export type OnboardingQuestion = {
+  id: OnboardingQuestionId
+  prompt: string
+  options: OnboardingOption[]
+  /** Whether more than one option may be chosen. */
+  multi: boolean
+  /** `scale` renders as a slider: the options are an ordered ramp, so the
+   *  distance between two answers means something and the control should say
+   *  so. Everything else is a chip list. Storage is identical either way. */
+  kind?: 'choice' | 'scale'
+}
+
+/** Every question offers this. The accompanying free text is stored separately
+ *  so "other" stays countable while the text stays readable. */
+export const OTHER_OPTION_ID = 'other'
+
+export const ANVIL_ONBOARDING_QUESTIONS: readonly OnboardingQuestion[] = [
+  {
+    id: 'referral_source',
+    prompt: 'Where did you hear about Anvil?',
+    // Attribution is the one answer we cannot reconstruct later: referrer
+    // headers are stripped, and self-report is the only signal for word of
+    // mouth, which is where most of it actually comes from.
+    //
+    // Instagram leads because it was the single largest write-in by a distance,
+    // and it shares an audience with TikTok closely enough that splitting them
+    // would buy two thin numbers instead of one usable one.
+    options: [
+      // Keeps the `tiktok` id: those answers are the same audience, and a new
+      // id would restart the count from zero for the sake of a tidier string.
+      { id: 'tiktok', label: 'Instagram / TikTok' },
+      { id: 'youtube', label: 'YouTube' },
+      { id: 'x_twitter', label: 'X / Twitter' },
+      { id: 'search', label: 'Google / AI search' },
+      { id: 'friend', label: 'A friend' },
+      { id: 'reddit', label: 'Reddit' },
+      { id: 'github', label: 'GitHub' },
+      { id: OTHER_OPTION_ID, label: 'Somewhere else' },
+    ],
+    multi: false,
+  },
+  {
+    id: 'role',
+    prompt: 'What best describes you?',
+    options: [
+      { id: 'professional_dev', label: 'Developer' },
+      { id: 'founder', label: 'Founder' },
+      { id: 'student', label: 'Student' },
+      { id: 'hobbyist', label: 'Hobbyist' },
+      { id: 'pm', label: 'Designer or PM' },
+      { id: 'non_technical', label: 'Non-technical' },
+      { id: OTHER_OPTION_ID, label: 'Something else' },
+    ],
+    multi: false,
+  },
+  {
+    id: 'proficiency',
+    prompt: 'How much do you code?',
+    options: [
+      { id: 'none', label: 'Not at all' },
+      { id: 'beginner', label: 'Beginner' },
+      { id: 'intermediate', label: 'Intermediate' },
+      { id: 'advanced', label: 'Advanced' },
+      { id: 'expert', label: 'Expert' },
+    ],
+    // No Other: this is an ordered scale, and a free-text answer on an ordinal
+    // question is unusable for the segmentation it exists to support.
+    multi: false,
+    kind: 'scale',
+  },
+  {
+    id: 'intended_use',
+    prompt: 'What will you build with Anvil?',
+    options: [
+      { id: 'website', label: 'Websites and apps' },
+      { id: 'work', label: 'Work projects' },
+      { id: 'side_projects', label: 'Side projects' },
+      { id: 'learning', label: 'Learning to code' },
+      { id: 'automation', label: 'Scripts and automation' },
+      { id: OTHER_OPTION_ID, label: 'Something else' },
+    ],
+    multi: true,
+  },
+  {
+    id: 'subscriptions',
+    prompt: 'Current subscriptions that you’ve had, cancelled or will cancel',
+    // The one question here that prices the product rather than describing the
+    // user: what someone already pays for — and is willing to stop paying for —
+    // says who we actually compete with. Deliberately loose about tense, since
+    // "about to cancel" is the same competitive signal as "already did" and
+    // splitting the two would buy two thin numbers instead of one usable one.
+    options: [
+      { id: 'none', label: 'None', exclusive: true },
+      { id: 'claude_code', label: 'Claude Code' },
+      { id: 'cursor', label: 'Cursor' },
+      { id: 'opencode', label: 'opencode' },
+      { id: 'copilot', label: 'GitHub Copilot' },
+      { id: 'codex', label: 'Codex' },
+      { id: 'gemini', label: 'Gemini' },
+      { id: 'app_builder', label: 'Lovable / Replit' },
+      { id: OTHER_OPTION_ID, label: 'Something else' },
+    ],
+    multi: true,
+  },
+] as const
+
+/**
+ * Retired option id → the current option that now covers it.
+ *
+ * Read-time only, applied by the admin tally. A retired option's answers are
+ * still real answers; folding them into their successor keeps a broadened
+ * option's count honest instead of resetting it to zero on the day of the edit.
+ * An id with no successor here is simply not counted.
+ */
+export const ONBOARDING_LEGACY_OPTION_IDS: Partial<
+  Record<OnboardingQuestionId, Record<string, string>>
+> = {
+  // Discord and blog/newsletter were dropped as options; both are honestly
+  // "somewhere else" rather than any of the channels that remain.
+  referral_source: { discord: OTHER_OPTION_ID, blog_news: OTHER_OPTION_ID },
+  // Data/ML folded into the broader developer bucket, designer into the
+  // designer-or-PM one.
+  role: { data_ml: 'professional_dev', designer: 'pm' },
+  // Prototypes and demos are websites and apps; code review has no successor
+  // narrow enough to claim it, so it goes to "something else".
+  intended_use: { prototyping: 'website', debugging: OTHER_OPTION_ID },
+}
+
+/**
+ * Write-in text → the option it should have been.
+ *
+ * People type an answer that already exists on the list, at volume: Instagram
+ * was the top write-in on a question that did not offer it, and every variant
+ * of "ChatGPT" is the AI-search answer. Matching is read-time and deliberately
+ * narrow — a pattern that fires on an ambiguous word buys a wrong count, which
+ * is worse than the "other" bucket it came from.
+ */
+export const ONBOARDING_OTHER_TEXT_RULES: Partial<
+  Record<OnboardingQuestionId, { optionId: string; pattern: RegExp }[]>
+> = {
+  referral_source: [
+    { optionId: 'tiktok', pattern: /insta|\btiktok\b|\btik tok\b|\big\b/i },
+    {
+      optionId: 'search',
+      pattern:
+        /\bai\b|chat\s?gpt|\bgpt\b|claude|gemini|perplexity|copilot|grok|deepseek/i,
+    },
+  ],
+}
+
+/**
+ * Which option a write-in should be counted as, if any.
+ *
+ * Rules are tried in order and the first match wins, so the more specific
+ * pattern must come first — "insta" before the AI catch-all, since "instagram
+ * AI" is an Instagram answer.
+ */
+export function classifyOnboardingOtherText(
+  questionId: OnboardingQuestionId,
+  text: string,
+): string | null {
+  const rules = ONBOARDING_OTHER_TEXT_RULES[questionId]
+  if (!rules) return null
+  for (const rule of rules) {
+    if (rule.pattern.test(text)) return rule.optionId
+  }
+  return null
+}
+
+export type OnboardingAnswer = {
+  questionId: OnboardingQuestionId
+  /** Chosen option ids. Single-choice questions carry exactly one. */
+  optionIds: string[]
+  /** Free text, only when `other` is among the chosen ids. */
+  otherText?: string
+}
+
+export type OnboardingSubmission = {
+  answers: OnboardingAnswer[]
+}
+
+export const ONBOARDING_OTHER_TEXT_MAX = 200
+
+export type OnboardingValidationError = {
+  /** Null when the complaint is about the submission as a whole rather than
+   *  about one question — the only such case is an entirely empty one. */
+  questionId: OnboardingQuestionId | null
+  message: string
+}
+
+/**
+ * Validate a submission against the question set.
+ *
+ * Deliberately strict about ids and lenient about text: an unknown option id
+ * means the client is out of date or forged, and accepting it would put a value
+ * in the analytics that no question can explain. Free text is merely trimmed
+ * and truncated — it is never interpreted, only displayed.
+ */
+export function validateOnboardingSubmission(
+  submission: OnboardingSubmission,
+  questions: readonly OnboardingQuestion[] = ANVIL_ONBOARDING_QUESTIONS,
+): { ok: true; answers: OnboardingAnswer[] } | { ok: false; errors: OnboardingValidationError[] } {
+  const errors: OnboardingValidationError[] = []
+  const cleaned: OnboardingAnswer[] = []
+
+  for (const question of questions) {
+    const answer = submission.answers.find((a) => a.questionId === question.id)
+    const optionIds = answer?.optionIds ?? []
+
+    if (optionIds.length === 0) {
+      errors.push({ questionId: question.id, message: 'Please choose an option.' })
+      continue
+    }
+    if (!question.multi && optionIds.length > 1) {
+      errors.push({ questionId: question.id, message: 'Choose one option.' })
+      continue
+    }
+
+    const valid = new Set(question.options.map((o) => o.id))
+    const unknown = optionIds.filter((id) => !valid.has(id))
+    if (unknown.length > 0) {
+      errors.push({ questionId: question.id, message: 'Unrecognised option.' })
+      continue
+    }
+
+    const exclusive = question.options.filter((o) => o.exclusive).map((o) => o.id)
+    if (optionIds.length > 1 && optionIds.some((id) => exclusive.includes(id))) {
+      errors.push({
+        questionId: question.id,
+        message: 'That answer cannot be combined with the others.',
+      })
+      continue
+    }
+
+    const wantsOther = optionIds.includes(OTHER_OPTION_ID)
+    const otherText = answer?.otherText?.trim()
+    if (wantsOther && !otherText) {
+      errors.push({
+        questionId: question.id,
+        message: 'Tell us a little more.',
+      })
+      continue
+    }
+
+    cleaned.push({
+      questionId: question.id,
+      optionIds,
+      // Dropped unless `other` was chosen, so stray text cannot ride along on
+      // an answer that has nowhere to show it.
+      ...(wantsOther && otherText
+        ? { otherText: otherText.slice(0, ONBOARDING_OTHER_TEXT_MAX) }
+        : {}),
+    })
+  }
+
+  return errors.length > 0 ? { ok: false, errors } : { ok: true, answers: cleaned }
+}
+
+/** Every question answered. Decides only whether someone who returns to the
+ *  form still sees it — nothing is withheld either way. */
+export function isOnboardingComplete(
+  answers: readonly OnboardingAnswer[] | null | undefined,
+  questions: readonly OnboardingQuestion[] = ANVIL_ONBOARDING_QUESTIONS,
+): boolean {
+  if (!answers || answers.length === 0) return false
+  const answered = new Set(
+    answers.filter((a) => a.optionIds.length > 0).map((a) => a.questionId),
+  )
+  return questions.every((q) => answered.has(q.id))
+}

package/vendor/@anvil/common/src/constants/anvil-referral-tiers.ts

@@ -0,0 +1,87 @@
+/**
+ * Anvil referral program constants.
+ *
+ * The referral REWARD is consolidated (2026-07-30) to exactly two things,
+ * both session-shaped and both defined next to the pools they feed:
+ *
+ *   - FULL access tier: +1 daily GLM 5.2 session per qualified referral,
+ *     uncapped (glmWeeklySessionsFromStats in packages/billing).
+ *   - LIMITED access tier: +1 daily free session per qualified referral,
+ *     capped at REFERRAL_CLI_DAILY_SESSION_BONUS_CAP (GLM is geo-gated).
+ *
+ * The old web tier ladder (tiered daily message limits + deploy-watermark
+ * removal) is GONE: the limits were never enforced anywhere — real limits are
+ * the session pools in anvil-models.ts — and the "Powered by Anvil"
+ * deploy watermark is globally disabled (prod_branding_injection_enabled =
+ * false), so both perks were marketing for things users didn't get. What
+ * remains in this file is the qualification machinery: GitHub account-age
+ * bars, attribution windows, and anti-farming ceilings.
+ */
+
+/** Referred users must have a GitHub account at least this old for the
+ *  referral to count. Younger accounts can still sign up normally — the
+ *  referrer just gets no credit (anti-farming). */
+export const MIN_GITHUB_ACCOUNT_AGE_MONTHS = 4
+
+/** GLM 5.2 referral program uses a stricter account-age bar than the web
+ *  program (no public-repo requirement, but the account must be a full year
+ *  old) since the reward — paid GLM serverless time — costs more to abuse. */
+export const MIN_GITHUB_ACCOUNT_AGE_MONTHS_GLM = 12
+
+/**
+ * Unified referral system (docs/referrals.md): a single 4-month GitHub
+ * account-age bar for ALL products (no public-repo requirement), consolidating
+ * the old per-program bars (cli/glm = 12mo, web = 4mo).
+ */
+export const MIN_GITHUB_ACCOUNT_AGE_MONTHS_REFERRAL = 4
+
+/**
+ * Anvil CLI limited-tier perk: each qualified referral whose referred user
+ * activated at the *limited* access tier grants +1 daily free-mode session,
+ * capped here (e.g. 6 base + 3 = 9/day). Full-access referrals instead grant
+ * GLM sessions, which are uncapped.
+ */
+export const REFERRAL_CLI_DAILY_SESSION_BONUS_CAP = 3
+
+/**
+ * Max attributed web signups (pending + completed) per referrer. The shared
+ * `user.referral_limit` column (default 5) governs the CLI program; the web
+ * program needs its own headroom — generous enough for unqualified signups,
+ * small enough to bound farming.
+ */
+export const ANVIL_WEB_REFERRAL_LIMIT = 20
+
+/**
+ * A referral can only be attributed within this many days of the referred
+ * user's signup — stops a referrer from claiming long-pre-existing accounts.
+ * Shared by the unified referral_v2 redemption path and its clients.
+ */
+export const REFERRAL_SIGNUP_WINDOW_DAYS = 30
+
+/**
+ * Max attributed referrals (referral_v2 rows) a single referrer may accumulate.
+ * Since the GLM reward was uncapped (2026-07-30) this is no longer a pure
+ * anti-spam ceiling: GLM entitlement now scales 1:1 with qualified referrals,
+ * so this limit IS the effective maximum (100 GLM sessions/day). The other
+ * rewards are still capped at read time (the web tier ladder, the CLI bonus at
+ * REFERRAL_CLI_DAILY_SESSION_BONUS_CAP), so for those it stays a formality.
+ */
+export const ANVIL_REFERRAL_SIGNUP_LIMIT = 100
+
+/** Whether a GitHub account created at `githubCreatedAtMs` satisfies the
+ *  referral age requirement at time `nowMs`. Months are computed on the
+ *  calendar (e.g. created Jan 15 qualifies on/after May 15). `minMonths`
+ *  defaults to the web bar; the GLM program passes
+ *  MIN_GITHUB_ACCOUNT_AGE_MONTHS_GLM. */
+export function isGithubAccountOldEnoughForReferral(
+  githubCreatedAtMs: number | null | undefined,
+  nowMs: number = Date.now(),
+  minMonths: number = MIN_GITHUB_ACCOUNT_AGE_MONTHS,
+): boolean {
+  if (githubCreatedAtMs == null || !Number.isFinite(githubCreatedAtMs)) {
+    return false
+  }
+  const threshold = new Date(githubCreatedAtMs)
+  threshold.setUTCMonth(threshold.getUTCMonth() + minMonths)
+  return nowMs >= threshold.getTime()
+}

package/vendor/@anvil/common/src/constants/anvil-signup-block.ts

@@ -0,0 +1,68 @@
+/**
+ * Signup-refusal reasons and their user-facing copy.
+ *
+ * Lives in `common`, not in `packages/auth`, because the login pages are client
+ * components: importing this from the auth barrel would drag `db`, `stripe` and
+ * the server env schema into the browser bundle. The decision logic stays in
+ * `@anvil/auth/signup-gate`; only the vocabulary is shared.
+ */
+
+/** Why a signup was refused. Also the `?error=` code on the login redirect. */
+export type SignupBlockReason =
+  | 'captcha_missing'
+  | 'captcha_invalid'
+  // Deliberately distinct from the two above rather than folded into them.
+  // The providers fail for different populations — a filter that blocks
+  // challenges.cloudflare.com usually does not block www.google.com, and vice
+  // versa — so a shared reason code would make the one question worth asking
+  // after a refusal spike ("which provider is failing?") unanswerable from the
+  // logs. That is exactly the ambiguity that cost four attempts on 2026-08-12.
+  | 'recaptcha_missing'
+  | 'recaptcha_invalid'
+  | 'mailbox_already_registered'
+  | 'privacy_egress'
+  | 'untrusted_client_ip'
+  | 'ip_signup_velocity'
+  | 'prefix_signup_velocity'
+
+/**
+ * Deliberately actionable and non-accusatory.
+ *
+ * Someone hitting `privacy_egress` is far more likely to be a privacy-conscious
+ * developer on a VPN than a reseller, and the message they get should name the
+ * one thing that fixes it rather than implying they did something wrong. A
+ * refused signup with no explanation is indistinguishable from the product
+ * being broken, and generates a support ticket instead of a retry.
+ */
+export const SIGNUP_BLOCK_MESSAGES: Record<SignupBlockReason, string> = {
+  captcha_missing:
+    'Please complete the verification check on the sign-in page and try again.',
+  captcha_invalid:
+    'That verification check could not be confirmed. Please try again.',
+  // Names the host, because the overwhelmingly likely cause is an extension or
+  // DNS filter blocking it — a cause the user can fix in ten seconds if they
+  // know it and cannot fix at all if they do not. Retrying does not help here,
+  // so "please try again" alone would be actively misleading.
+  recaptcha_missing:
+    'Please complete the verification check on the sign-in page and try again. If it never appeared, an ad blocker or network filter may be blocking www.google.com/recaptcha.',
+  recaptcha_invalid:
+    'That verification check could not be confirmed. Please try again.',
+  mailbox_already_registered:
+    'An account already exists for this email address. Try signing in instead.',
+  privacy_egress:
+    'Accounts cannot be created over a VPN, proxy, or hosting provider. Please turn it off and try again — you can turn it back on afterwards.',
+  untrusted_client_ip:
+    'We could not verify where this request came from. Please try again, or contact support if it keeps happening.',
+  ip_signup_velocity:
+    'Too many accounts have been created from this network today. Please try again tomorrow, or contact support if you are on a shared connection.',
+  prefix_signup_velocity:
+    'Too many accounts have been created from this network today. Please try again tomorrow, or contact support if you are on a shared connection.',
+}
+
+/** True when `code` is a reason this module has copy for. Narrows an untrusted
+ *  query-string value without a cast at every call site. */
+export function isSignupBlockReason(
+  code: string | null | undefined,
+): code is SignupBlockReason {
+  return Boolean(code) && code! in SIGNUP_BLOCK_MESSAGES
+}