Under the Hood

// Convex is a regenerable projection of live ESI data keyed by the Neon
// identities (userId + characterId) — never the system of record, never a
// home for SDE/domain data. Wiping these tables and re-syncing must
// reproduce the same state from Neon + ESI.
//
// Since MIGRATE.B the engine serves a SINGLE live consumer — onlineStatus.

export default defineSchema({
  syncSubjects: defineTable({
    dataset: v.literal('onlineStatus'),
    userId: v.string(),
    status: v.union(v.literal('idle'), v.literal('running')),
    lastRequestedAt: v.number(),
    workId: v.union(v.string(), v.null()),
    nextDueAt: v.union(v.number(), v.null()),
    minExpiresAt: v.union(v.number(), v.null()),
    syncedCharacterIds: v.array(v.number()),
  }).index('by_user_dataset', ['userId', 'dataset']),

  characterOnline: defineTable({
    userId: v.string(),
    characterId: v.number(),
    online: v.boolean(),
    etag: v.union(v.string(), v.null()),
  })
    .index('by_user', ['userId'])
    .index('by_user_character', ['userId', 'characterId']),
});

// Validation of the spine's Convex-facing JWT. The minting side lives in the
// Next.js app (Better Auth jwt plugin): ES256, `iss` = BETTER_AUTH_URL,
// `aud` = 'convex', `sub` = the Better Auth user id.
//
// No EVE credentials ever live in Convex; token custody and refresh stay on
// the Neon side.

const issuer = process.env.AUTH_ISSUER_URL;
const jwks = process.env.AUTH_JWKS;

export default {
  providers:
    issuer && jwks
      ? [
          {
            type: 'customJwt',
            issuer,
            algorithm: 'ES256',
            jwks,
            applicationID: 'convex',
          },
        ]
      : [],
} satisfies AuthConfig;

// NEXT_PUBLIC_CONVEX_URL is a literal static read by design: Next inlines it
// into every bundle at build time, and on Vercel the value exists ONLY in the
// build env. When unset, the client is null and every consumer degrades
// gracefully — the rest of the site runs.

export const convexClient: ConvexReactClient | null = url ? new ConvexReactClient(url) : null;

function useAuthForConvex() {
  const { session, loading } = useAuth();
  const isAuthenticated = session !== null;

  const fetchAccessToken = useCallback(async () => {
    try {
      const result = await apiFetch(tokenEndpoint);
      return result.ok ? result.data.token : null;
    } catch {
      return null;
    }
  }, []);

  return useMemo(
    () => ({ isLoading: loading, isAuthenticated, fetchAccessToken }),
    [loading, isAuthenticated, fetchAccessToken],
  );
}

export function ConvexClientProvider({ children }: { children: React.ReactNode }) {
  if (convexClient === null) return <>{children}</>;
  return (
    <ConvexProviderWithAuth client={convexClient} useAuth={useAuthForConvex}>
      {children}
    </ConvexProviderWithAuth>
  );
}

// THE presence-gated sync engine. A subject (dataset × user) is refreshed on
// its dataset's cadence only while some visible tab is heartbeating it; cost
// scales with concurrently-watched subjects, never with total linked characters.
//
// Mechanism: heartbeats maintain presence and dispatch immediately when the
// data is stale; a static 30s cron scans subjects whose nextDueAt has arrived,
// skips cold or still-running ones, and dispatches the rest through the Workpool.

const pool = new Workpool(components.workpool, { maxParallelism: 4 });

const rateLimiter = new RateLimiter(components.rateLimiter, {
  syncDispatch: { kind: 'token bucket', period: MINUTE, rate: 30, capacity: 10 },
});

const syncDatasetValidator = v.literal('onlineStatus');

const SYNC_REFS = {
  onlineStatus: internal.onlineStatusSync.syncUser,
} satisfies Record<SyncDataset, unknown>;

export const SCAN_DISPATCH_BATCH = 1024;

// The COLD-equivalent viewer wire: the calling user's per-character online flag.
// The apply writes that table ONLY on a genuine online↔offline change, so this
// query re-fires only when a character's online state actually flips.

export const forViewer = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (identity === null) return null;
    const userId = identity.subject;
    const docs = await ctx.db
      .query('characterOnline')
      .withIndex('by_user', (q) => q.eq('userId', userId))
      .collect();
    return {
      characters: docs.map((doc) => ({ characterId: doc.characterId, online: doc.online })),
    };
  },
});

async function applyOnlineResult(ctx, userId, result, existing) {
  if (result.error !== null) return null;
  if (result.online === null) return result.expiresAt;

  if (existing === undefined) {
    await ctx.db.insert('characterOnline', {
      userId,
      characterId: result.characterId,
      online: result.online,
      etag: result.etag,
    });
  } else if (existing.online !== result.online || existing.etag !== result.etag) {
    await ctx.db.patch(existing._id, { online: result.online, etag: result.etag });
  }
  return result.expiresAt;
}

// The client half of the presence-gated sync engine: a visibility-gated
// heartbeat. While the tab is visible, beat every HEARTBEAT_MS; on hide, stop;
// on return, beat immediately so a stale view refreshes at once.

export function useSyncSubject(dataset: SyncDataset, characterIds: number[]) {
  const heartbeat = useMutation(api.engine.heartbeat);
  const characterIdsKey = characterIds.join(',');

  useEffect(() => {
    if (characterIdsKey === '') return;
    const characterIdsHint = characterIdsKey.split(',').map(Number);
    const beat = (reason: 'mount' | 'visible' | 'interval') =>
      void heartbeat({ dataset, characterIdsHint, reason });

    let timer: ReturnType<typeof setInterval> | null = null;
    const start = (reason: 'mount' | 'visible') => {
      beat(reason);
      timer = setInterval(() => beat('interval'), HEARTBEAT_MS);
    };
    const stop = () => {
      if (timer !== null) clearInterval(timer);
      timer = null;
    };

    if (document.visibilityState === 'visible') start('mount');
    document.addEventListener('visibilitychange', onVisibilityChange);
    return () => {
      stop();
      document.removeEventListener('visibilitychange', onVisibilityChange);
    };
  }, [dataset, characterIdsKey, heartbeat]);
}

// The engine serves a SINGLE live consumer: onlineStatus. The three slow
// trackers moved to Neon stale-gated on-view reads in MIGRATE.B.

export const SYNC_DATASETS = ['onlineStatus'] as const;

export const SYNC_DATASET_CONFIG: Record<
  SyncDataset,
  { cadenceFloorMs: number; tokenGroup: string }
> = {
  onlineStatus: { cadenceFloorMs: 60_000, tokenGroup: 'char-online' },
};

export const HEARTBEAT_MS = 20_000;
export const COLD_AFTER_MS = 60_000;
export const RETENTION_MS = 7 * 24 * 60 * 60_000;

export function isColdFromPresence(lastSeenAt: number | null, now: number): boolean {
  return lastSeenAt === null || isCold(lastSeenAt, now);
}

export function isRunningFresh(
  status: 'idle' | 'running',
  lastRequestedAt: number,
  now: number,
): boolean {
  return status === 'running' && now - lastRequestedAt < STALE_RUNNING_MS;
}

// THE presence-gated sync engine. A subject (dataset × user) is refreshed on
// its dataset's cadence only while some visible tab is heartbeating it; cost
// scales with concurrently-watched subjects, never with total linked characters.
//
// Mechanism: heartbeats maintain presence and dispatch immediately when the
// data is stale; a static 30s cron scans subjects whose nextDueAt has arrived,
// skips cold or still-running ones, and dispatches the rest through the Workpool.

const pool = new Workpool(components.workpool, { maxParallelism: 4 });

const rateLimiter = new RateLimiter(components.rateLimiter, {
  syncDispatch: { kind: 'token bucket', period: MINUTE, rate: 30, capacity: 10 },
});

const syncDatasetValidator = v.literal('onlineStatus');

const SYNC_REFS = {
  onlineStatus: internal.onlineStatusSync.syncUser,
} satisfies Record<SyncDataset, unknown>;

export const SCAN_DISPATCH_BATCH = 1024;