feat: scaffold workspace with search, fetch, and extract packages

packages/tts/src/errors.ts

@@ -0,0 +1,35 @@
+/** Errors thrown by the TTS fetcher. */
+
+export class TtsError extends Error {
+  constructor(
+    message: string,
+    readonly status: number = 500,
+  ) {
+    super(message);
+    this.name = 'TtsError';
+  }
+}
+
+/** The Steam API returned no details for the requested item. */
+export class ItemNotFoundError extends TtsError {
+  constructor(id: string) {
+    super(`No Workshop item found for id ${id}`, 404);
+    this.name = 'ItemNotFoundError';
+  }
+}
+
+/** The item exists but has no downloadable `file_url`. */
+export class NoFileError extends TtsError {
+  constructor(id: string) {
+    super(`Workshop item ${id} has no downloadable save file`, 404);
+    this.name = 'NoFileError';
+  }
+}
+
+/** The Steam API rejected the request (bad key, rate limit, etc.). */
+export class SteamApiError extends TtsError {
+  constructor(message: string, status = 502) {
+    super(message, status);
+    this.name = 'SteamApiError';
+  }
+}

packages/tts/src/index.ts

@@ -0,0 +1,113 @@
+import { deserialize } from 'bson';
+import type { TTSMod } from '@tts/shared';
+import { ItemNotFoundError, NoFileError, SteamApiError } from './errors.js';
+
+const STEAM_API_URL =
+  'https://api.steampowered.com/ISteamRemoteStorage/GetPublishedFileDetails/v1/';
+
+interface SteamPublishedFileDetails {
+  publishedfileid: string;
+  title: string;
+  creator: string;
+  preview_url: string;
+  file_url?: string;
+  description?: string;
+  tags?: { tag: string }[];
+  time_created?: number;
+  time_updated?: number;
+}
+
+interface SteamResponse {
+  response: {
+    result: number;
+    resultcount: number;
+    publishedfiledetails?: SteamPublishedFileDetails[];
+  };
+}
+
+/**
+ * Fetch a full TTS save for a Workshop item and BSON-deserialize it.
+ *
+ * @param id Workshop item ID (digits only).
+ * @param apiKey Steam Web API key.
+ */
+export async function fetchMod(id: string, apiKey: string): Promise<TTSMod> {
+  const fileUrl = await getFileUrl(id, apiKey);
+
+  const saveRes = await fetch(fileUrl);
+  if (!saveRes.ok) {
+    throw new SteamApiError(
+      `Failed to download save file (${saveRes.status})`,
+      502,
+    );
+  }
+
+  const buffer = await saveRes.arrayBuffer();
+  return deserialize(new Uint8Array(buffer)) as TTSMod;
+}
+
+/**
+ * Derive a filename from a `content-disposition` header.
+ * Parses `filename="..."`; falls back to the URL path, then a default.
+ */
+export function getFileName(url: string, disposition: string | null): string {
+  if (disposition) {
+    const match = disposition.match(/filename\*?=(?:"([^"]*)"|([^;\s]*))/i);
+    const name = match?.[1] ?? match?.[2];
+    if (name) {
+      return name;
+    }
+  }
+  return new URL(url).pathname.split('/').pop() || 'save.json';
+}
+
+/**
+ * Fetch the raw save file bytes for a Workshop item.
+ * Returns the bytes plus a derived filename.
+ */
+export async function fetchModFile(
+  id: string,
+  apiKey: string,
+): Promise<{ data: ArrayBuffer; filename: string }> {
+  const fileUrl = await getFileUrl(id, apiKey);
+
+  const res = await fetch(fileUrl);
+  if (!res.ok) {
+    throw new SteamApiError(
+      `Failed to download save file (${res.status})`,
+      502,
+    );
+  }
+
+  const data = await res.arrayBuffer();
+  const filename = getFileName(fileUrl, res.headers.get('content-disposition'));
+  return { data, filename };
+}
+
+/** Resolve the `file_url` for a Workshop item via the Steam API. */
+async function getFileUrl(id: string, apiKey: string): Promise<string> {
+  const params = new URLSearchParams();
+  params.append('key', apiKey);
+  params.append('itemcount', '1');
+  params.append('publishedfileids[0]', id);
+
+  const res = await fetch(STEAM_API_URL, {
+    method: 'POST',
+    body: params,
+  });
+  if (!res.ok) {
+    throw new SteamApiError(`Steam API responded ${res.status}`, 502);
+  }
+
+  const json = (await res.json()) as SteamResponse;
+  const details = json.response.publishedfiledetails?.[0];
+  if (!details) {
+    throw new ItemNotFoundError(id);
+  }
+  if (!details.file_url) {
+    throw new NoFileError(id);
+  }
+  return details.file_url;
+}
+
+export * from './errors.js';