feat: allow loading mods without a Steam API key

Add fetchModFromUrl/fetchModFileFromUrl and accept a fileUrl query param on /items routes so the frontend can download saves directly from a search result's file_url, with no key required.

apps/proxy/src/routes/items.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { ItemNotFoundError, SteamApiError } from '@tts/tts';
+import { ItemNotFoundError, SteamApiError, TtsError } from '@tts/tts';
 import type { TTSMod } from '@tts/shared';
 import items from './items.js';
 
@@ -16,12 +16,34 @@ describe('items route', () => {
     expect(await res.json()).toEqual({ error: 'Item ID must be a number' });
   });
 
-  it('returns 500 when the API key is missing', async () => {
+  it('returns 500 when the API key is missing and no fileUrl is given', async () => {
+    vi.spyOn(await import('@tts/tts'), 'fetchMod').mockRejectedValue(
+      new TtsError('STEAM_API_KEY is not configured', 500),
+    );
     const res = await items.request('/123', {}, { STEAM_API_KEY: '', PORT: 3000 });
     expect(res.status).toBe(500);
     expect(await res.json()).toEqual({ error: 'STEAM_API_KEY is not configured' });
   });
 
+  it('loads from a fileUrl without an API key', async () => {
+    const mod: TTSMod = {
+      GameMode: 'Tabletop',
+      Date: '2024-01-01',
+      ObjectStates: [],
+    };
+    const fetchModFromUrl = vi
+      .spyOn(await import('@tts/tts'), 'fetchModFromUrl')
+      .mockResolvedValue(mod);
+    const res = await items.request(
+      '/123?fileUrl=https%3A%2F%2Fexample.com%2Fsave.json',
+      {},
+      { STEAM_API_KEY: '', PORT: 3000 },
+    );
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual(mod);
+    expect(fetchModFromUrl).toHaveBeenCalledWith('https://example.com/save.json');
+  });
+
   it('returns the parsed mod on success', async () => {
     const mod: TTSMod = {
       GameMode: 'Tabletop',
@@ -75,6 +97,27 @@ describe('items file route', () => {
     expect(await res.arrayBuffer()).toEqual(new Uint8Array([1, 2, 3]).buffer);
   });
 
+  it('serves the raw file from a fileUrl without an API key', async () => {
+    const fetchModFileFromUrl = vi
+      .spyOn(await import('@tts/tts'), 'fetchModFileFromUrl')
+      .mockResolvedValue({
+        data: new Uint8Array([1, 2, 3]).buffer,
+        filename: 'mod.json',
+      });
+    const res = await items.request(
+      '/123/file?fileUrl=https%3A%2F%2Fexample.com%2Fsave.json',
+      {},
+      { STEAM_API_KEY: '', PORT: 3000 },
+    );
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-disposition')).toBe(
+      'attachment; filename="mod.json"',
+    );
+    expect(fetchModFileFromUrl).toHaveBeenCalledWith(
+      'https://example.com/save.json',
+    );
+  });
+
   it('maps SteamApiError to 502', async () => {
     vi.spyOn(await import('@tts/tts'), 'fetchModFile').mockRejectedValue(
       new SteamApiError('Steam API responded 500'),

apps/proxy/src/routes/items.ts

@@ -1,6 +1,12 @@
 import { Hono } from 'hono';
 import { itemIdSchema, type TTSMod } from '@tts/shared';
-import { fetchMod, fetchModFile, TtsError } from '@tts/tts';
+import {
+  fetchMod,
+  fetchModFile,
+  fetchModFileFromUrl,
+  fetchModFromUrl,
+  TtsError,
+} from '@tts/tts';
 import type { Bindings } from '../env.js';
 
 const app = new Hono<{ Bindings: Bindings }>();
@@ -11,13 +17,13 @@ app.get('/:id', async (c) => {
     return c.json({ error: 'Item ID must be a number' }, 400);
   }
 
-  const apiKey = c.env.STEAM_API_KEY;
-  if (!apiKey) {
-    return c.json({ error: 'STEAM_API_KEY is not configured' }, 500);
-  }
-
   try {
-    const mod = await fetchMod(id, apiKey);
+    const fileUrl = c.req.query('fileUrl');
+    // With no Steam API key, the caller must supply the save URL (e.g. from a
+    // search result). Otherwise resolve it via the Steam API.
+    const mod: TTSMod = fileUrl
+      ? await fetchModFromUrl(fileUrl)
+      : await fetchMod(id, c.env.STEAM_API_KEY ?? '');
     return c.json<TTSMod>(mod);
   } catch (err) {
     if (err instanceof TtsError) {
@@ -33,13 +39,11 @@ app.get('/:id/file', async (c) => {
     return c.json({ error: 'Item ID must be a number' }, 400);
   }
 
-  const apiKey = c.env.STEAM_API_KEY;
-  if (!apiKey) {
-    return c.json({ error: 'STEAM_API_KEY is not configured' }, 500);
-  }
-
   try {
-    const { data, filename } = await fetchModFile(id, apiKey);
+    const fileUrl = c.req.query('fileUrl');
+    const { data, filename } = fileUrl
+      ? await fetchModFileFromUrl(fileUrl)
+      : await fetchModFile(id, c.env.STEAM_API_KEY ?? '');
     return new Response(data, {
       headers: {
         'Content-Type': 'application/octet-stream',

apps/web/src/api.ts

@@ -18,11 +18,17 @@ export function searchWorkshop(q: string, page = 1): Promise<SearchResult> {
 }
 
 /** Fetch a full parsed TTS save. */
-export function fetchMod(id: string): Promise<TTSMod> {
-  return getJson<TTSMod>(`/items/${id}`);
+export function fetchMod(id: string, fileUrl?: string): Promise<TTSMod> {
+  const params = new URLSearchParams();
+  if (fileUrl) params.set('fileUrl', fileUrl);
+  const qs = params.toString();
+  return getJson<TTSMod>(`/items/${id}${qs ? `?${qs}` : ''}`);
 }
 
 /** Build a URL for the raw save file download. */
-export function modFileUrl(id: string): string {
-  return `${BASE}/items/${id}/file`;
+export function modFileUrl(id: string, fileUrl?: string): string {
+  const params = new URLSearchParams();
+  if (fileUrl) params.set('fileUrl', fileUrl);
+  const qs = params.toString();
+  return `/items/${id}/file${qs ? `?${qs}` : ''}`;
 }

apps/web/src/pages/ModPage.tsx

@@ -2,15 +2,17 @@ import { useEffect } from 'react';
 import { useParams } from 'react-router-dom';
 import { collectRefs, flattenObjects } from '@tts/extract';
 import { useModStore } from '../stores/modStore';
+import { useSearchStore } from '../stores/searchStore';
 import { modFileUrl } from '../api';
 
 export default function ModPage() {
   const { id } = useParams<{ id: string }>();
   const { mod, loading, error, load } = useModStore();
+  const item = useSearchStore((s) => s.items.find((i) => i.id === id));
 
   useEffect(() => {
-    if (id) load(id);
-  }, [id, load]);
+    if (id) load(id, item?.fileUrl);
+  }, [id, item?.fileUrl, load]);
 
   if (loading) return <p className="text-sm text-zinc-400">Loading mod…</p>;
   if (error) return <p className="text-sm text-red-400">{error}</p>;
@@ -28,7 +30,7 @@ export default function ModPage() {
           asset refs
         </p>
         <a
-          href={modFileUrl(id!)}
+          href={modFileUrl(id!, item?.fileUrl)}
           className="mt-3 inline-block rounded-lg bg-zinc-100 px-4 py-2 text-sm font-medium text-zinc-900 hover:bg-zinc-300"
         >
           Download save file

apps/web/src/stores/modStore.ts

@@ -4,26 +4,28 @@ import { fetchMod } from '../api';
 
 interface ModState {
   id: string | null;
+  fileUrl?: string;
   mod: TTSMod | null;
   loading: boolean;
   error: string | null;
-  load: (id: string) => Promise<void>;
+  load: (id: string, fileUrl?: string) => Promise<void>;
   clear: () => void;
 }
 
 export const useModStore = create<ModState>((set) => ({
   id: null,
+  fileUrl: undefined,
   mod: null,
   loading: false,
   error: null,
-  load: async (id) => {
-    set({ loading: true, error: null, id });
+  load: async (id, fileUrl) => {
+    set({ loading: true, error: null, id, fileUrl });
     try {
-      const mod = await fetchMod(id);
+      const mod = await fetchMod(id, fileUrl);
       set({ mod, loading: false });
     } catch (err) {
       set({ loading: false, error: String(err) });
     }
   },
-  clear: () => set({ id: null, mod: null, error: null, loading: false }),
+  clear: () => set({ id: null, fileUrl: undefined, mod: null, error: null, loading: false }),
 }));