REST /v1 (mobile)
Base path /v1, built with @hono/zod-openapi. It exists for the mobile app in
the sibling tcgkl repo.
Browse the spec
Section titled “Browse the spec”| Production | Beta | |
|---|---|---|
| Interactive docs | api.tcgkl.com/v1/docs | api-staging.tcgkl.com/v1/docs |
| OpenAPI 3.1 JSON | /v1/openapi.json |
/v1/openapi.json |
The spec is generated from the route definitions, so it cannot drift from the code. Do not hand-maintain a copy of it here.
Route groups
Section titled “Route groups”apps/api/src/v1/routes/: auth, events, tickets, checkout, stamping,
contests, profile, feed, social, messaging, notifications,
catalog, upload. The OpenAPI tags are finer-grained: Auth, Events, Tickets,
Checkout, Stamping, Contests, Profile, Feed, Interactions, Comments, Follows,
Moderation, Messaging, Notifications, Catalog, Shops, Search, Upload.
Authentication
Section titled “Authentication”Sessions are Better Auth sessions. POST /v1/auth/verify-otp or
/v1/auth/social-login returns a session token — also in the set-auth-token
response header — which the client sends as:
Authorization: Bearer <token>Origin: https://api.tcgkl.comThe Origin header is required on credentialed requests. withSession
middleware attaches the session to every /v1 request.
Errors
Section titled “Errors”One envelope for everything, from apps/api/src/v1/errors.ts. A schema failure
returns 400 with the first Zod issue rendered as path: message; an unknown
route returns 404. This matches the contract the Fastify-era API had, so old
clients keep working.
Notable behaviour by group
Section titled “Notable behaviour by group”The spec has the full request and response shapes. This section covers what the spec doesn’t make obvious.
Feed: creating a post
Section titled “Feed: creating a post”POST /v1/feed/posts (apps/api/src/v1/routes/feed.ts). The client uploads
media first through POST /v1/upload/presign, then creates the post with the
resulting URLs. The handler then:
- Stores storage keys, not URLs. Full
https://URLs are reduced to their path. - Accepts multiple clips.
clips(ormediaUrls) is an array, stored inmetadata.clipsandmetadata.mediaUrls. If noimagesare sent, it is also used as the image list. - Stores text-overlay state as metadata.
textOverlays/texts(an array of{ text, colours, fontSize, offset/translate, scale, rotation, style, isEmoji }, with extra keys passed through),containerDimensions,rawState,textPosition,textScale,textRotation,textStyleandfontSizeare stored as-is inmobile_posts.metadatafor the app to re-render. The server does not burn them into the video. - Also accepts
visibility(public/followers/private, defaultpublic),hubCategory,locationName,locationIdandallowComments(defaulttrue). - Inserts the post as
processingand fires a request to the media worker (MEDIA_WORKER_URL, orVIDEO_WORKER_URL) at/process-videoor/process-image, sendingMEDIA_WORKER_SECRETas thex-worker-secretheader when set (must match the worker’sWORKER_SECRET). If that request fails, the worker’s polling picks the post up anyway.
Processed videos are HLS (.m3u8). Browsers other than Safari can’t play HLS
natively, so the admin post and ad dialogs play it through
apps/web/src/components/ui/HlsVideoPlayer.tsx (hls.js). Use that component
for any other admin view that plays mobile video.
Profile
Section titled “Profile”GET /v1/profile/mealso returns the user’sstate(from the audience preferences) and the effective per-user app flagsenableEventButton,canDoTicketPaymentandcanAccessContest. These are the global mobile app config merged with the user’s overrides.PATCH /v1/profile/meacceptsstate, where""clears it.- Avatar fallback.
/v1/auth/*and/v1/profile/*responses useavatar_url || user.image, so an empty string falls through to the Google or Apple picture. The old-app import had written''instead of NULL. Migration 0140 nulled those rows, andprofile.updatemaps''to NULL. The web header menu and/profileuse the same fallback.
Contests
Section titled “Contests”GET /v1/contests/{slug} (and the web’s contestPublic router behind it)
returns only the admin-picked prize winners. There is no public top-N
leaderboard any more, and the full ranking stays in admin. Names go through
publicEntrantName(), which never shows generated user_… handles.
Push notifications
Section titled “Push notifications”-
POST /v1/notifications/push-tokenregisters the device’s FCM token, withplatformset toios,androidorunknown(the default). Expo tokens are ignored at send time. -
Delivery.
packages/core/src/server/mobile/push.tssends through the FCM HTTP v1 REST endpoint withfetch, with a 15-second timeout.firebase-adminis kept only for service-account OAuth. Its own messaging client usesnode:http2, which resets mid-request under Bun (“socket hang up”), so it isn’t used for delivery. -
Dead tokens. A token that FCM reports as
UNREGISTERED, or as anINVALID_ARGUMENTregistration token, is deleted at send time. -
Errors are surfaced. Each send returns
{ sent, failed, error? }. A missingFIREBASE_SERVICE_ACCOUNT_KEYcomes back as a readable error instead of a silent zero. A campaign that sends nothing is markedfailedwithlastError, and the admin test-send toast shows the FCM reason. -
Admin tools on
/admin/mobile/notifications(admin, editor):- Reset My Registered Devices (
mobilePushNotifications.resetMyTokens) clears the caller’s own tokens. - Clean Up Invalid Device Tokens (
cleanupInvalidTokens) dry-runs up to 500 tokens against FCM (validate_only) and deletes the dead ones. Optionally it also deletes tokens rejected for APNs credential or bundle-ID mismatches (THIRD_PARTY_AUTH_ERROR).
Both are audit-logged.
- Reset My Registered Devices (
Adding a route
Section titled “Adding a route”- The business rule belongs in a tRPC procedure in
packages/core. - Add the route in
apps/api/src/v1/routes/<group>.tswith its Zod request and response schemas, so it appears in the OpenAPI output. - Call the procedure through
createCaller(apps/api/src/v1/middleware.ts). - Tag it so it lands in the right section of the docs.
