nixamp 0.28.38 → 0.28.41

package/dist/watch-party.js

@@ -200,6 +200,27 @@ export class WatchParties {
             return null;
         return { party: partyFrom(row, event), event };
     }
+    /**
+     * A party by its code alone, for somebody who has only the code.
+     *
+     * A code is unique per origin, not across them; a person typing one into
+     * nixamp.com is not asked which site it came from. The one still live, or
+     * the most recently touched, is the one they mean.
+     */
+    async byAnyCode(partyCode) {
+        await this.ensure();
+        const code = cleanPartyCode(partyCode);
+        const { rows } = await this.options.db.query(`SELECT p.* FROM ${TABLE} p JOIN live_events e ON e.id = p.event_id
+        WHERE p.party_code = $1
+        ORDER BY (e.status = 'live') DESC, p.updated_at DESC LIMIT 1`, [code]);
+        const row = rows[0];
+        if (!row)
+            return null;
+        const event = await this.options.events.get(String(row["event_id"] ?? ""));
+        if (!event)
+            return null;
+        return { party: partyFrom(row, event), event };
+    }
     /** The party behind a nixamp room or slug, for a client that has only that. */
     async byEvent(reference) {
         await this.ensure();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.28.38",
+  "version": "0.28.41",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",
@@ -47,12 +47,12 @@
   "dependencies": {
     "@profullstack/auth-system": "^0.6.0",
     "@profullstack/hqtui": "^0.5.0",
+    "@profullstack/notifications": "^0.1.0",
     "@profullstack/synconfig": "^0.1.2",
     "@profullstack/throttle": "0.2.2",
-    "@profullstack/x402-gateway": "0.6.0",
+    "@profullstack/x402-gateway": "^0.7.0",
     "acme-client": "5.4.0",
-    "pg": "^8.23.0",
-    "web-push": "^3.6.7"
+    "pg": "^8.23.0"
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^4.2.0"
@@ -60,7 +60,6 @@
   "devDependencies": {
     "@types/node": "^26",
     "@types/pg": "^8.23.1",
-    "@types/web-push": "^3.6.4",
     "typescript": "^7.0.2"
   },
   "trustedDependencies": [
@@ -82,6 +81,7 @@
   },
   "overrides": {
     "https-proxy-agent": "7.0.6",
-    "tslib": "2.8.1"
+    "tslib": "2.8.1",
+    "@profullstack/x402-gateway": "^0.7.0"
   }
 }

package/src/live-api.ts

@@ -36,6 +36,12 @@ export interface LiveApiOptions {
   site?: string;
   email?: (to: string, note: { title: string; body: string; url: string }) => Promise<boolean>;
   onEventUpdated?: (event: LiveEvent, previous: LiveEvent) => void;
+  /**
+   * The account's own card -- name, homepage, photo -- so a class made
+   * without them carries the host's instead of nothing. What the class
+   * says explicitly still wins.
+   */
+  hostProfile?: (userId: string) => Promise<{ hostName: string; homepageUrl: string; avatarUrl: string }>;
 }
 
 const CORS = {
@@ -309,6 +315,13 @@ export async function handleLiveApi(
         const account = await requiredAccount(request, response, options);
         if (!account) return true;
         const input = await body(request);
+        if (options.hostProfile) {
+          const card = await options.hostProfile(account.id);
+          for (const key of ["hostName", "homepageUrl", "avatarUrl"] as const) {
+            const given = input[key];
+            if (card[key] && (given === undefined || given === null || given === "")) input[key] = card[key];
+          }
+        }
         const event = await options.events.create(account.id, { ...input, title: input["title"] });
         json(response, 201, view(event, account));
         return true;

package/src/live-voice.ts

@@ -6,6 +6,7 @@ import type { VoiceProfile } from "./voice-profile.ts";
 import { Guard } from "./guard.ts";
 import type { TranslationMeter } from "./translation-passes.ts";
 import type { Queryable } from "./follows.ts";
+import { voiceProviderFailure } from "./voice-provider.ts";
 
 export const LIVE_VOICE_MODEL = "eleven_flash_v2_5";
 export const LIVE_VOICE_RATE = 16_000;
@@ -37,6 +38,20 @@ export class LiveVoice {
   private readonly dailyAudioSeconds: number;
   private readonly userDailyChars: number;
   private readonly userDailyAudioSeconds: number;
+  private providerPause: { until: number; error: SpeechError } | null = null;
+
+  private checkProvider(): void {
+    if (this.providerPause && this.providerPause.until > this.now()) throw this.providerPause.error;
+  }
+
+  private async providerFailed(response: Response, operation: string): Promise<never> {
+    const failure = await voiceProviderFailure(response);
+    const until = this.now() + failure.cooldownMs;
+    // Another in-flight response must not shorten an existing billing pause.
+    if (!this.providerPause || this.providerPause.until < until) this.providerPause = { until, error: failure.error };
+    console.error(JSON.stringify({ event: "voice_provider_failure", provider: "elevenlabs", operation, status: response.status, code: failure.code, cooldownMs: failure.cooldownMs }));
+    throw failure.error;
+  }
 
   constructor(options: { apiKey?: string; fetcher?: typeof fetch; now?: () => number; charsPerMinute?: number; dailyChars?: number; dailyAudioSeconds?: number; userDailyChars?: number; userDailyAudioSeconds?: number; db?: Queryable; billing?: TranslationMeter } = {}) {
     this.key = options.apiKey ?? process.env["ELEVENLABS_API_KEY"] ?? "";
@@ -60,6 +75,7 @@ export class LiveVoice {
   async hear(bytes: Uint8Array, by: string, signal?: AbortSignal, meter = this.billing, resource = ""): Promise<SpeakerTranscript> {
     if (!this.available()) throw new SpeechError("speaker voices are unavailable", 503);
     await meter?.require(by, resource);
+    this.checkProvider();
     const wav = decodeWav(bytes);
     const seconds = wav.samples.length / wav.rate;
     if (wav.rate !== 16000 || wav.channels !== 1 || seconds < 0.2 || seconds > 15.1) throw new SpeechError("send up to 15 seconds of mono 16 kHz WAV", 400);
@@ -77,6 +93,7 @@ export class LiveVoice {
       await this.reserve(`scribe:user:${by}`, billed, this.userDailyAudioSeconds, 86_400_000);
       await this.reserve("scribe:server", billed, this.dailyAudioSeconds, 86_400_000);
       signal?.throwIfAborted();
+      this.checkProvider();
       const form = new FormData();
       // Canonical PCM prevents a crafted container from billing more audio
       // than the duration we validated, and removes uploaded metadata.
@@ -91,8 +108,9 @@ export class LiveVoice {
         method: "POST", headers: { "xi-api-key": this.key }, body: form,
         signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
       });
-      if (!answer.ok) throw new SpeechError("speaker transcription could not run; check provider quota and permissions", answer.status === 429 ? 429 : 502);
+      if (!answer.ok) await this.providerFailed(answer, "transcription");
       accepted = true;
+      console.info(JSON.stringify({ event: "voice_provider_usage", provider: "elevenlabs", operation: "transcription", account: createHash("sha256").update(by).digest("hex").slice(0, 16), audioSeconds: seconds }));
       if (reservation) await meter!.commit(reservation);
       return speakerTurns(await answer.json() as ScribeResult, wav);
     } catch (error) {
@@ -103,12 +121,13 @@ export class LiveVoice {
 
   async voices(): Promise<LiveVoiceChoice[]> {
     if (!this.available()) throw new SpeechError("translated audio needs ELEVENLABS_API_KEY on the account server", 503);
+    this.checkProvider();
     if (!this.catalog || this.now() >= this.catalogUntil) {
       this.catalogUntil = this.now() + 3600_000;
       this.catalog = this.fetcher("https://api.elevenlabs.io/v2/voices?page_size=100&voice_type=default", {
         headers: { "xi-api-key": this.key }, signal: AbortSignal.timeout(8000),
       }).then(async response => {
-        if (!response.ok) throw new SpeechError("ElevenLabs could not list voices; check the server key and its voice permissions", 503);
+        if (!response.ok) await this.providerFailed(response, "voices");
         const body = await response.json() as { voices: { voice_id: string; name: string; labels?: Record<string, string> }[] };
         return body.voices.filter(voice => /^[a-zA-Z0-9_-]+$/.test(voice.voice_id)).map(voice => ({
           id: voice.voice_id, name: voice.name, gender: voice.labels?.["gender"] ?? "neutral", language: voice.labels?.["language"] ?? "",
@@ -238,6 +257,7 @@ export class LiveVoice {
     let accepted = false;
     try {
       await this.charge(by, ask.channel ?? "direct", text.length);
+      this.checkProvider();
       signal?.throwIfAborted();
       reservation = await meter?.reserve(by, "voice", text.length, ask.channel);
       const response = await this.fetcher(`https://api.elevenlabs.io/v1/text-to-speech/${voice.id}/stream?output_format=pcm_16000`, {
@@ -246,9 +266,11 @@ export class LiveVoice {
         body: JSON.stringify({ text, model_id: LIVE_VOICE_MODEL, language_code: ask.language }),
         signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
       });
-      if (!response.ok || !response.body) throw new SpeechError(response.status === 429 ? "ElevenLabs audio quota is temporarily exhausted" : "ElevenLabs could not generate audio; check the server key and quota", response.status === 429 ? 429 : 502);
+      if (!response.ok) await this.providerFailed(response, "synthesis");
+      if (!response.body) throw new SpeechError("ElevenLabs returned no audio", 502);
       // Once the provider accepts, aborting playback cannot refund heard audio.
       accepted = true;
+      console.info(JSON.stringify({ event: "voice_provider_usage", provider: "elevenlabs", operation: "synthesis", account: createHash("sha256").update(by).digest("hex").slice(0, 16), characters: text.length }));
       if (reservation) await meter!.commit(reservation);
       const [play, keep] = response.body.tee();
       void (async () => {

package/src/nixamp-link-api.ts

@@ -0,0 +1,220 @@
+/**
+ * The routes behind "Connect nixamp" on a site that runs on this codebase
+ * but is not nixamp.com.
+ *
+ *   GET    /api/v1/nixamp/connect     send the browser to nixamp.com's consent page
+ *   GET    /api/v1/nixamp/callback    the code comes back; tokens are kept
+ *   GET    /api/v1/nixamp/connection  whether this account is connected, and as whom
+ *   DELETE /api/v1/nixamp/connection  withdraw the grant, both sides
+ *   GET    /api/v1/nixamp/streams     the servers you run on nixamp, and what is live
+ *
+ * All five want the site's own session: the person, signed in here. What
+ * they hold on nixamp's side is a client token, and it never leaves the
+ * server -- the page only ever learns a handle and a list of streams.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { tokenFrom, type Accounts } from "./accounts.ts";
+import type { NixampLinks } from "./nixamp-link.ts";
+import type { ServerStreams, StreamPick } from "./nixamp-link-types.ts";
+export type { ServerStreams, StreamPick } from "./nixamp-link-types.ts";
+
+export interface NixampLinkApiOptions {
+  links: NixampLinks;
+  accounts: Accounts;
+  /** nixamp.com, or whatever is the issuer. */
+  issuer: string;
+  /** This site, as the redirect URI is built from it: https://backtoschool.help. */
+  site: string;
+  /** The redirect URIs the client registered on the issuer; the callback must be one. */
+  redirectUris: string[];
+  /** Where the browser lands after the callback. */
+  home?: string;
+  secureCookies?: boolean;
+  fetcher?: typeof fetch;
+}
+
+const COOKIE = "nixamp_connect";
+const CALLBACK = "/api/v1/nixamp/callback";
+
+export function nixampLinkPath(path: string): boolean {
+  return path === "/api/v1/nixamp/connect" || path === CALLBACK || path === "/api/v1/nixamp/connection" || path === "/api/v1/nixamp/streams";
+}
+
+function json(response: ServerResponse, code: number, body: unknown, headers: Record<string, string> = {}): void {
+  const value = JSON.stringify(body);
+  response.writeHead(code, {
+    ...headers,
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(value),
+    "cache-control": "no-store",
+  });
+  response.end(value);
+}
+
+function cookieValue(headers: IncomingMessage["headers"], name: string): string {
+  const raw = headers.cookie ?? "";
+  for (const part of raw.split(";")) {
+    const [key, ...rest] = part.trim().split("=");
+    if (key === name) return decodeURIComponent(rest.join("="));
+  }
+  return "";
+}
+
+function legCookie(value: string, secure: boolean): string {
+  const parts = [`${COOKIE}=${encodeURIComponent(value)}`, `Path=${CALLBACK}`, "Max-Age=600", "SameSite=Lax", "HttpOnly"];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+function clearedLegCookie(): string {
+  return `${COOKIE}=; Path=${CALLBACK}; Max-Age=0; SameSite=Lax; HttpOnly`;
+}
+
+function landing(home: string, outcome: string, reason = ""): string {
+  const url = new URL(home, "http://placeholder.invalid");
+  url.searchParams.set("nixamp", outcome);
+  if (reason) url.searchParams.set("reason", reason.slice(0, 200));
+  return `${url.pathname}${url.search}${url.hash || "#settings"}`;
+}
+
+/**
+ * Every server the nixamp account remembers, asked what it is doing.
+ *
+ * The account's own list comes from nixamp.com with the client token; each
+ * server is then asked directly, with the share key the account kept for it,
+ * and given four seconds. One that does not answer is listed as out of
+ * reach rather than dropped, so a host sees why a stream is missing.
+ */
+export async function streamsFor(token: string, issuer: string, pageSite: string, fetcher: typeof fetch): Promise<ServerStreams[]> {
+  const base = issuer.replace(/\/+$/, "");
+  let servers: { id: string; name: string; url: string; key: string }[] = [];
+  const answer = await fetcher(`${base}/api/v1/servers`, {
+    headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+    signal: AbortSignal.timeout(8000),
+  });
+  if (!answer.ok) throw new Error(answer.status === 401 ? "nixamp.com no longer accepts this connection" : `nixamp.com answered ${answer.status}`);
+  const body = (await answer.json().catch(() => ({}))) as { servers?: typeof servers };
+  servers = Array.isArray(body.servers) ? body.servers : [];
+  const page = pageSite.replace(/\/+$/, "");
+  const linkTo = (address: string, play: string): string => `${page}/?url=${encodeURIComponent(address)}&play=${encodeURIComponent(play)}`;
+  return Promise.all(servers.map(async (server): Promise<ServerStreams> => {
+    const out: ServerStreams = { id: server.id, name: server.name || server.url, url: server.url, reachable: false, playing: false, nowPlaying: "", live: "", channels: [] };
+    try {
+      const url = new URL("/api/streams", server.url.endsWith("/") ? server.url : `${server.url}/`);
+      if (server.key) url.searchParams.set("k", server.key);
+      const response = await fetcher(url.href, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(4000) });
+      if (!response.ok) return out;
+      const data = (await response.json()) as {
+        server?: { name?: string; nowPlaying?: string; playing?: boolean; url?: string };
+        channels?: { id: string; name: string; kind?: string; listeners?: number }[];
+      };
+      // What a viewer link is built on: the server's own view-only address
+      // when it publishes one, else its plain address. Never the key the
+      // account kept, which may open the controls.
+      const viewer = data.server?.url && /^https?:\/\//.test(data.server.url) ? data.server.url : server.url;
+      out.reachable = true;
+      out.name = data.server?.name || out.name;
+      out.playing = data.server?.playing === true;
+      out.nowPlaying = data.server?.nowPlaying ?? "";
+      out.live = out.playing ? linkTo(viewer, "live") : "";
+      out.channels = (data.channels ?? []).map((one): StreamPick => ({
+        server: out.name,
+        serverUrl: server.url,
+        id: one.id,
+        name: one.name,
+        kind: one.kind ?? "audio",
+        listeners: typeof one.listeners === "number" ? one.listeners : 0,
+        link: linkTo(viewer, `channel:${one.id}`),
+      }));
+    } catch {
+      // Out of reach: said so, above.
+    }
+    return out;
+  }));
+}
+
+export async function handleNixampLinkApi(
+  request: IncomingMessage,
+  response: ServerResponse,
+  url: URL,
+  options: NixampLinkApiOptions,
+): Promise<boolean> {
+  const path = url.pathname;
+  if (!nixampLinkPath(path)) return false;
+  const home = options.home ?? "/";
+  const redirectUri = `${options.site.replace(/\/+$/, "")}${CALLBACK}`;
+  const registered = options.redirectUris.includes(redirectUri);
+
+  const account = await options.accounts.whoIs(tokenFrom(request.headers));
+  if (account === null) {
+    if (path === CALLBACK) {
+      response.writeHead(302, { location: landing(home, "failed", "sign in here first, then connect again"), "set-cookie": clearedLegCookie() });
+      response.end();
+      return true;
+    }
+    json(response, 401, { error: "sign in first" });
+    return true;
+  }
+
+  if (path === "/api/v1/nixamp/connect") {
+    if (request.method !== "GET") { json(response, 405, { error: "GET only" }); return true; }
+    if (!registered) { json(response, 400, { error: "this site is not registered as a nixamp client" }); return true; }
+    const leg = options.links.begin(redirectUri);
+    response.writeHead(302, { location: leg.url, "set-cookie": legCookie(`${leg.state}.${leg.verifier}`, options.secureCookies ?? false), "cache-control": "no-store" });
+    response.end();
+    return true;
+  }
+
+  if (path === CALLBACK) {
+    if (request.method !== "GET") { json(response, 405, { error: "GET only" }); return true; }
+    const kept = cookieValue(request.headers, COOKIE);
+    const dot = kept.indexOf(".");
+    const state = dot > 0 ? kept.slice(0, dot) : "";
+    const verifier = dot > 0 ? kept.slice(dot + 1) : "";
+    const headers = { "set-cookie": clearedLegCookie(), "cache-control": "no-store" };
+    const refused = url.searchParams.get("error");
+    if (refused) {
+      response.writeHead(302, { ...headers, location: landing(home, refused === "access_denied" ? "denied" : "failed", url.searchParams.get("error_description") ?? refused) });
+      response.end();
+      return true;
+    }
+    const code = url.searchParams.get("code") ?? "";
+    if (state === "" || url.searchParams.get("state") !== state || code === "") {
+      response.writeHead(302, { ...headers, location: landing(home, "failed", "that link is not the one this browser started; try again") });
+      response.end();
+      return true;
+    }
+    try {
+      await options.links.finish(account.id, { code, verifier, redirectUri });
+      response.writeHead(302, { ...headers, location: landing(home, "connected") });
+    } catch (error) {
+      response.writeHead(302, { ...headers, location: landing(home, "failed", (error as Error).message) });
+    }
+    response.end();
+    return true;
+  }
+
+  if (path === "/api/v1/nixamp/connection") {
+    if (request.method === "GET") {
+      json(response, 200, { ...(await options.links.of(account.id)), available: registered });
+      return true;
+    }
+    if (request.method === "DELETE") {
+      json(response, 200, { ok: true, withdrawn: await options.links.disconnect(account.id) });
+      return true;
+    }
+    json(response, 405, { error: "GET or DELETE" });
+    return true;
+  }
+
+  // /api/v1/nixamp/streams
+  if (request.method !== "GET") { json(response, 405, { error: "GET only" }); return true; }
+  const token = await options.links.accessToken(account.id);
+  if (token === "") { json(response, 409, { error: "connect your nixamp account first", connected: false }); return true; }
+  try {
+    json(response, 200, { servers: await streamsFor(token, options.issuer, options.issuer, options.fetcher ?? fetch) });
+  } catch (error) {
+    json(response, 502, { error: (error as Error).message });
+  }
+  return true;
+}

package/src/nixamp-link-types.ts

@@ -0,0 +1,36 @@
+/**
+ * What "Connect nixamp" looks like from a page: a leaf module, so a client
+ * bundle can name these shapes without pulling the server in behind them.
+ */
+
+/** The connection as the account holder sees it. Never the tokens. */
+export interface LinkView {
+  connected: boolean;
+  handle: string;
+  nixampUserId: string;
+  scope: string;
+  since: number | null;
+}
+
+/** A stream somebody could pick: a channel on one of their servers, as a link a classroom accepts. */
+export interface StreamPick {
+  server: string;
+  serverUrl: string;
+  id: string;
+  name: string;
+  kind: string;
+  listeners: number;
+  link: string;
+}
+
+export interface ServerStreams {
+  id: string;
+  name: string;
+  url: string;
+  reachable: boolean;
+  playing: boolean;
+  nowPlaying: string;
+  /** A link to what the server itself is playing, when it is. */
+  live: string;
+  channels: StreamPick[];
+}