Integrate with an agent

Three sequenced prompts, and how to review what they build.

The intended path. Hand your agent the prompts below, review the diff, ship.

Works with Claude Code, Cursor, Codex, Windsurf or anything else that can read files in your repo.

Before you start

Install the packages and put your environment values in .env. The agent needs the packages present, because the files it reads ship inside them.

What the agent reads

node_modules/@xborglabs/fanbase-react/llms.txt
node_modules/@xborglabs/fanbase-react/quest.md
node_modules/@xborglabs/fanbase-react/bind.md
node_modules/@xborglabs/fanbase-react/prize.md
node_modules/@xborglabs/fanbase-react/battlepass.md
node_modules/@xborglabs/fanbase-react/store.md
node_modules/@xborglabs/fanbase-react/newsfeed.md
node_modules/@xborglabs/fanbase-react/leaderboard.md
node_modules/@xborglabs/fanbase-react/prompt.md
node_modules/@xborglabs/fanbase-react/skills/fanbase/SKILL.md

llms.txt is the entry point. Each of the feature files covers one feature end to end, and each one ends with a "Done when" the agent can check itself against. They ship inside the package, so they always match the version you installed.

After upgrading the packages, have the agent re-copy skills/fanbase/SKILL.md. A skill left over from an older version can miss features that llms.txt lists.

Order

Three prompts, run in sequence. Sign-in first, questing second, then any other feature, one at a time. Do not combine them. A working sign-in is what makes everything after it verifiable, and an agent given everything at once tends to stub the auth and produce something that looks finished and is not.

Prompt 1: sign-in

Implement Fanbase OAuth in this app.

Read node_modules/@xborglabs/fanbase-react/llms.txt first, sections
Portal, FanbaseProvider, OAuth and Env. Do not invent APIs. If something
is not in that file, stop and ask.

Install if missing: @xborglabs/fanbase-core and @xborglabs/fanbase-react.
This app owns its QueryClient.

Wrap the app in FanbaseProvider with:
- tenant, slug, appId
- httpOptions: { gamerBaseUrl, locale }
- a session adapter { get, set, clear }, localStorage is fine
- our queryClient

Read config from these env keys, see .env:
  VITE_FANBASE_TENANT
  VITE_FANBASE_COMMUNITY_SLUG
  VITE_FANBASE_APP_ID
  VITE_FANBASE_GAMER_BASE_URL
  VITE_FANBASE_LOCALE
  VITE_FANBASE_OAUTH_PROXY_URL
  VITE_FANBASE_OAUTH_PROXY_SECRET
  VITE_FANBASE_OAUTH_REDIRECT_URL

Sign-in:
1. buildOAuthProxyUrl({ oauthProxyUrl, proxySecret })
2. buildLoginUrl({ oauthProxyUrl, provider, redirectUrl })
   provider is one of google, discord, twitter, twitch. It is the
   identity provider. Never pass a tenant or community slug here.
3. Carry the provider forward on the redirect as ?provider= and in
   sessionStorage. The proxy returns only ?token=.

Callback page, at the exact URL in VITE_FANBASE_OAUTH_REDIRECT_URL:
- Wait for useFanbase().state.ready before doing anything
- parseOAuthCallbackToken(window.location.href)
- actions.loginWithToken({ provider, token })
- Handle a missing token with a message, not an endless spinner
- Replace the history entry after success, the token is single use

Logout is actions.logout().

Done when: the callback exchanges ?token= using the same provider that
started sign-in, state.session has accessToken and refreshToken, a page
refresh keeps the fan signed in, and logout clears the adapter.

Prompt 2: questing

Run after sign-in works end to end.

Implement Fanbase questing in this app.

Read, in this order:
- node_modules/@xborglabs/fanbase-react/llms.txt
- quest.md, the whole quest feature, including its reward catalog
- quest-templates.md, for requirement UI and submit payloads
- quest-description.md, for Parser, Quest.Description and the theme object
- bind.md, for linking an account a quest needs
- prize.md, for prize detail forms and the lootbox claim
- skills/fanbase/SKILL.md, an agent skill. If your tool loads skills from the
  project, it finds this one and follows `llms.txt` without being told to.

Do not invent template names or payload shapes. If a template is not in
quest-templates.md, route it to the default empty-body branch.

List page:
- useQuestsList() only. One GET /v1/quests for the whole page.
- No per-quest detail calls and no allocation fetches for cards.
- Render our own card component from each row.
- Resolve quest status through resolveMessage('Quests.status.' + status).
  Never render the raw enum, INACTIVE does not mean what it looks like.

Detail page:
- Quest.Provider with questId, and quest={row} seeded from the list.
  Let the provider own that row. Do not copy it into local state.
- Pass fetchRewards, a flag, so the claim button knows a reward is waiting.
- Pass authProfile={{ socials, wallets }}. socials from useLinkedSocials(),
  never from the profile, which omits expiry dates. wallets from
  GET /v1/user/profile. Without it, gated quests stay disabled.
- Pass claimPayload, built with toAllocationClaimPayload, when a prize
  requires details such as an email.
- Quest.Frame wraps our UI.
- Quest.Description with a theme object mapping to our classes.
- Requirement UI switched on a family you map from template.name, using the
  Catalog in quest.md. Never switch on getApiType or getQuestType: they return
  the submit path and a number, not a family.
  - typed families (text, answer, prediction, quiz, poll, email, wallet,
    image) use actions.submit(payload), not Quest.Submit
  - empty-body families (visit, bind, progress, auto, unknown) use
    Quest.Submit
  - visit: an outbound <a target="_blank">, then a CTA bound to
    state.canSubmit. Do not build a separate enabled flag.
  - bind: a plain <a> to buildBindUrl, carrying the account type in the
    redirect URL, plus the CTA. The callback redeems with useBind() within
    five minutes. Follow bind.md.
- CTA copy comes from state.buttonLabel. Disabled state comes from
  state.canSubmit or state.canClaim. Show state.disabledReasonLabel when
  the fan cannot act.

Rewards:
- resolveQuestRewardChrome({ reward, quest }) for presentation. It returns
  undefined for an unknown slug: render nothing then.
- Show rewards before completion, from quest.rewards, not only after
- Claim with Quest.Claim or actions.claimAllAllocated(), never actions.claim()
  alone, which claims a single allocation and leaves the rest
- give_lootboxes: after claim, poll getQuestRewardAllocations until
  lootboxOpening.selectedItem appears, then useLootboxes for the possible
  items and resolveLootboxSelectedItem for the winner. Cover the wait with
  an animation and cap it with a timeout.
- Only call claimLootbox when resolvePrizeClaimState says
  REQUIREMENTS_REQUIRED.

Use our existing design system components and class names throughout.
Add no CSS of your own.

Done when: the list issues exactly one GET /v1/quests, a signed-in fan
can submit and claim at least one quest, statuses render as readable
labels, the description renders through Quest.Description, and a lootbox
claim opens a reveal.

Prompt 3: one more feature

Run once questing works, once per feature. Replace FEATURE with one of battlepass, store, newsfeed or leaderboard.

Implement the Fanbase FEATURE feature in this app.

Read node_modules/@xborglabs/fanbase-react/FEATURE.md in full before
writing anything, then the Membership section of llms.txt. Do not invent
APIs, fields or reason codes. If something is not in those files, stop
and ask.

Follow the file's Process section in order. Each step ends with a
"Done when". Do not move to the next step until the current one holds.

Rules that apply to every feature:
- Never pass a communityId, containerId or COMMUNITY_ID. The SDK resolves
  the community from the slug on FanbaseProvider.
- Render the gate and reason values the SDK computes. Never recompute
  membership, stock, balance or lock state yourself.
- Name the membership tier that would unlock something, from
  requiredTierName. Never write a generic "Premium".
- Structured descriptions go through Parser, plain on cards.
- Every write is already optimistic and already invalidates what it
  touched. Do not add your own setQueryData or refetch calls.

Use our existing design system components and class names throughout.
Add no CSS of your own.

Done when: every "Done when" in FEATURE.md holds, and every item in its
Smoke list passes.

The feature guides on this site cover the same ground for a person reading: Battlepass, Store, Newsfeed, Leaderboard.

Reviewing what it built

Agents get this mostly right. The things worth checking by hand:

  • Request count. Open the network tab on the list page. One GET /v1/quests. Fanning out per card is the most common thing to fix.
  • Status labels. Any raw INACTIVE on screen means resolveMessage was skipped.
  • The detail page after a submit. Submit a quest and watch the label and status change without a refresh. If they freeze, the row was mirrored into local state.
  • A social-gated quest signed in. If it is disabled with no explanation, authProfile is not being passed.
  • A premium item as a free fan. A battlepass tier, a store listing or a post. It should be locked and name the tier. If it shows a claim or buy button, the gate is being skipped.
  • A store purchase that fails. Check the retry path never mints a new nonce. That is the one mistake that charges a fan twice.
  • No hardcoded community id. Search the diff for communityId and containerId. Neither should be a literal.
  • Typecheck. On a Vite app, npx tsc -p tsconfig.app.json --noEmit. The root config is references-only and exits 0 having checked nothing.
  • Your CSS. No new stylesheet should have appeared.

When the agent gets stuck

The prompts say to stop and ask rather than invent. If yours asks a question, the answer is usually in Quest templates or Hooks. If it is in neither, send it to us, because a question an agent has to ask is a page we owe you.

On this page