Skip to content

REST /v1 (mobile)

Base path /v1, built with @hono/zod-openapi. It exists for the mobile app in the sibling tcgkl repo.

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.

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.

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.com

The Origin header is required on credentialed requests. withSession middleware attaches the session to every /v1 request.

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.

The spec has the full request and response shapes. This section covers what the spec doesn’t make obvious.

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 (or mediaUrls) is an array, stored in metadata.clips and metadata.mediaUrls. If no images are 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, textStyle and fontSize are stored as-is in mobile_posts.metadata for the app to re-render. The server does not burn them into the video.
  • Also accepts visibility (public / followers / private, default public), hubCategory, locationName, locationId and allowComments (default true).
  • Inserts the post as processing and fires a request to the media worker (MEDIA_WORKER_URL, or VIDEO_WORKER_URL) at /process-video or /process-image, sending MEDIA_WORKER_SECRET as the x-worker-secret header when set (must match the worker’s WORKER_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.

  • GET /v1/profile/me also returns the user’s state (from the audience preferences) and the effective per-user app flags enableEventButton, canDoTicketPayment and canAccessContest. These are the global mobile app config merged with the user’s overrides. PATCH /v1/profile/me accepts state, where "" clears it.
  • Avatar fallback. /v1/auth/* and /v1/profile/* responses use avatar_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, and profile.update maps '' to NULL. The web header menu and /profile use the same fallback.

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.

  • POST /v1/notifications/push-token registers the device’s FCM token, with platform set to ios, android or unknown (the default). Expo tokens are ignored at send time.

  • Delivery. packages/core/src/server/mobile/push.ts sends through the FCM HTTP v1 REST endpoint with fetch, with a 15-second timeout. firebase-admin is kept only for service-account OAuth. Its own messaging client uses node: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 an INVALID_ARGUMENT registration token, is deleted at send time.

  • Errors are surfaced. Each send returns { sent, failed, error? }. A missing FIREBASE_SERVICE_ACCOUNT_KEY comes back as a readable error instead of a silent zero. A campaign that sends nothing is marked failed with lastError, 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.

  1. The business rule belongs in a tRPC procedure in packages/core.
  2. Add the route in apps/api/src/v1/routes/<group>.ts with its Zod request and response schemas, so it appears in the OpenAPI output.
  3. Call the procedure through createCaller (apps/api/src/v1/middleware.ts).
  4. Tag it so it lands in the right section of the docs.