@rivi-software/radiotools-sdk 0.0.0-stage → 0.2.0

package/src/graphql.ts

@@ -0,0 +1,297 @@
+import type { PublicJsonRequestOptions } from "./http";
+import { postJson, RadioToolsApiError } from "./http";
+import { sdkSchemas } from "./schemas";
+
+export type GraphqlRequestOptions = PublicJsonRequestOptions & {
+  previewGrant?: string;
+};
+
+type GraphqlEnvelope<T> = {
+  data?: T;
+  errors?: { message: string; extensions?: { code?: string } }[];
+};
+
+export async function graphqlRequest<TData>(
+  endpoint: string,
+  query: string,
+  variables: Record<string, unknown> | undefined,
+  options: GraphqlRequestOptions = {},
+): Promise<TData> {
+  const headers: Record<string, string> = {};
+  if (options.apiToken) headers.authorization = `Bearer ${options.apiToken}`;
+  if (options.previewGrant) headers["x-preview-grant"] = options.previewGrant;
+  const body = await postJson<GraphqlEnvelope<TData>>(
+    endpoint,
+    { query, variables },
+    { parse: (value) => value as GraphqlEnvelope<TData> },
+    {
+      fetch: options.fetch,
+      headers,
+      cache: options.cache ?? "no-store",
+      credentials: options.credentials ?? "omit",
+      retries: options.retries,
+    },
+  );
+  if (body.errors?.length) {
+    const code = body.errors[0]?.extensions?.code ?? "INTERNAL_ERROR";
+    throw Object.assign(new Error(body.errors[0]?.message ?? "GraphQL error"), {
+      name: "RadioToolsGraphqlError",
+      code,
+      errors: body.errors,
+    });
+  }
+  if (!body.data) throw new Error("GraphQL response missing data");
+  return body.data;
+}
+
+export function isGraphqlUnavailable(error: unknown): boolean {
+  if (error instanceof RadioToolsApiError) return error.status === 404;
+  return error instanceof Error && error.message.includes("(404)");
+}
+
+const broadcastFields = `
+  id
+  title
+  startsAt
+  endsAt
+  timezone
+  localDate
+  resolution
+  status
+  cancellationReason
+  repeatOfId
+  program { id title profileId }
+  presenters { id title }
+`;
+
+export const stationQuery = /* GraphQL */ `
+  query SdkStation {
+    station {
+      contractVersion
+      id
+      slug
+      name
+      timezone
+      publishingLanguage
+      resources {
+        schemas
+        content
+        schedule
+        programs
+        broadcast
+        nowPlaying
+        trackHistory
+        socket
+        weather
+        traffic
+        media
+      }
+      delivery { cache conditional pollIntervalSeconds }
+    }
+  }
+`;
+
+export const schemasQuery = /* GraphQL */ `
+  query SdkSchemas {
+    schemas { key label version archived fields }
+  }
+`;
+
+export const contentQuery = /* GraphQL */ `
+  query SdkContent($type: String!, $cursor: ID, $limit: Int) {
+    content(type: $type, cursor: $cursor, limit: $limit) {
+      nextCursor
+      records {
+        id
+        publicationId
+        revision
+        type
+        schemaVersion
+        publishedAt
+        values
+        document
+        media { assetId versionId kind url credits mime }
+      }
+    }
+  }
+`;
+
+export const contentRecordQuery = /* GraphQL */ `
+  query SdkContentRecord($id: ID!) {
+    contentRecord(id: $id) {
+      id
+      publicationId
+      revision
+      type
+      schemaVersion
+      publishedAt
+      values
+      document
+      media { assetId versionId kind url credits mime }
+    }
+  }
+`;
+
+export const nowPlayingQuery = /* GraphQL */ `
+  query SdkNowPlaying {
+    nowPlaying {
+      contractVersion
+      stationId
+      timezone
+      track {
+        artist
+        title
+        album
+        durationSeconds
+        artworkUrl
+        isPlaying
+        observedAt
+        receivedAt
+      }
+      elapsedSeconds
+      endsAt
+      freshness { status thresholdSeconds ageSeconds observedAt receivedAt }
+    }
+  }
+`;
+
+export const trackHistoryQuery = /* GraphQL */ `
+  query SdkTrackHistory($cursor: String, $limit: Int) {
+    trackHistory(cursor: $cursor, limit: $limit) {
+      contractVersion
+      stationId
+      items {
+        id
+        artist
+        title
+        album
+        durationSeconds
+        artworkUrl
+        isPlaying
+        observedAt
+        receivedAt
+      }
+      nextCursor
+    }
+  }
+`;
+
+export const scheduleQuery = /* GraphQL */ `
+  query SdkSchedule($fromDate: String!, $throughDate: String!) {
+    schedule(fromDate: $fromDate, throughDate: $throughDate) {
+      contractVersion
+      timezone
+      truncated
+      broadcasts { ${broadcastFields} }
+    }
+  }
+`;
+
+export const programsQuery = /* GraphQL */ `
+  query SdkPrograms($fromDate: String!, $throughDate: String!) {
+    programs(fromDate: $fromDate, throughDate: $throughDate) {
+      contractVersion
+      timezone
+      fromDate
+      throughDate
+      truncated
+      programs { id title profileId }
+    }
+  }
+`;
+
+export const currentBroadcastQuery = /* GraphQL */ `
+  query SdkCurrentBroadcast {
+    currentBroadcast {
+      contractVersion
+      timezone
+      asOf
+      broadcast { ${broadcastFields} }
+    }
+  }
+`;
+
+export const weatherQuery = /* GraphQL */ `
+  query SdkWeather {
+    weather { stationId timezone snapshots }
+  }
+`;
+
+export const trafficQuery = /* GraphQL */ `
+  query SdkTraffic {
+    traffic { stationId snapshot }
+  }
+`;
+
+export const previewMutation = /* GraphQL */ `
+  mutation SdkPreview($input: PreviewInput!) {
+    previewEditorial(input: $input) {
+      id
+      revision
+      schemaVersion
+      values
+      document
+      media { assetId versionId kind url credits mime }
+    }
+  }
+`;
+
+export function parseGraphqlStation(data: { station: unknown }) {
+  return sdkSchemas.PublicStation.parse(data.station);
+}
+
+export function parseGraphqlSchemas(data: { schemas: unknown[] }) {
+  return sdkSchemas.PublicSchemaList.parse({ contractVersion: 1, types: data.schemas });
+}
+
+export function parseGraphqlContent(
+  type: string,
+  data: { content: { records: unknown[]; nextCursor: string | null } },
+  limit: number,
+) {
+  const nextCursor = data.content.nextCursor;
+  return sdkSchemas.PublishedCollection.parse({
+    contractVersion: 1,
+    type,
+    records: data.content.records.map((record) => ({
+      contractVersion: 1,
+      ...(record as object),
+    })),
+    nextCursor,
+    page: { limit, nextCursor },
+  });
+}
+
+export function parseGraphqlSchedule(data: { schedule: unknown }) {
+  return sdkSchemas.PublicSchedule.parse(data.schedule);
+}
+
+export function parseGraphqlPrograms(data: { programs: unknown }) {
+  return sdkSchemas.PublicPrograms.parse(data.programs);
+}
+
+export function parseGraphqlCurrentBroadcast(data: { currentBroadcast: unknown }) {
+  return sdkSchemas.PublicCurrentBroadcast.parse(data.currentBroadcast);
+}
+
+export function parseGraphqlNowPlaying(data: { nowPlaying: unknown }) {
+  return sdkSchemas.PublicNowPlaying.parse(data.nowPlaying);
+}
+
+export function parseGraphqlTrackHistory(data: { trackHistory: unknown }) {
+  return sdkSchemas.PublicTrackHistory.parse(data.trackHistory);
+}
+
+export function parseGraphqlWeather(data: { weather: unknown }) {
+  if (data.weather == null) return null;
+  return sdkSchemas.WeatherPublic.parse({ contractVersion: 1, ...(data.weather as object) });
+}
+
+export function parseGraphqlTraffic(data: { traffic: unknown }) {
+  if (data.traffic == null) return null;
+  return sdkSchemas.TrafficPublic.parse({ contractVersion: 1, ...(data.traffic as object) });
+}
+
+export function parseGraphqlPreview(data: { previewEditorial: unknown }) {
+  return sdkSchemas.RevisionPreview.parse(data.previewEditorial);
+}

package/src/http.ts

@@ -0,0 +1,167 @@
+import { type SdkErrorCode, type SdkErrorResponse, sdkSchemas } from "./schemas";
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export class RadioToolsApiError extends Error {
+  readonly code: SdkErrorCode | null;
+  readonly requestId: string | null;
+  readonly status: number;
+  readonly issues?: SdkErrorResponse["error"]["issues"];
+
+  constructor(status: number, body: SdkErrorResponse | { error: string }) {
+    super(typeof body.error === "string" ? body.error : body.error.message);
+    this.name = "RadioToolsApiError";
+    this.status = status;
+    if (typeof body.error === "string") {
+      this.code = null;
+      this.requestId = null;
+      return;
+    }
+    this.code = body.error.code;
+    this.requestId = body.error.requestId;
+    this.issues = body.error.issues;
+  }
+}
+
+export type EtagEntry<T> = { etag: string; data: T };
+
+/** In-memory conditional GET cache. Keys include a hash of the listener token. */
+export type EtagCache = Map<string, EtagEntry<unknown>>;
+
+export function createEtagCache(): EtagCache {
+  return new Map();
+}
+
+export type PublicJsonRequestOptions = {
+  fetch?: FetchLike;
+  /** Station credential with listener:read. Keep it on the station's server. */
+  apiToken?: string;
+  etagCache?: EtagCache;
+  cache?: RequestCache;
+  credentials?: RequestCredentials;
+  /** Extra attempts after a 429 or 503. Defaults to 2. */
+  retries?: number;
+};
+
+const defaultPublicInit = {
+  cache: "no-store" as RequestCache,
+  credentials: "omit" as RequestCredentials,
+};
+
+function throwResponseError(status: number, body: unknown): never {
+  const structured = sdkSchemas.ErrorResponse.safeParse(body);
+  if (structured.success) throw new RadioToolsApiError(status, structured.data);
+  const ingest = sdkSchemas.IngestErrorResponse.safeParse(body);
+  if (ingest.success) throw new RadioToolsApiError(status, ingest.data);
+  throw new Error(`RadioTools request failed (${status})`);
+}
+
+async function readErrorBody(response: Response): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch {
+    throw new Error(`RadioTools request failed (${response.status})`);
+  }
+}
+
+function retryDelayMs(response: Response, attempt: number): number {
+  const retryAfter = response.headers.get("retry-after");
+  if (retryAfter && /^\d+$/.test(retryAfter)) return Math.min(Number(retryAfter) * 1000, 5000);
+  return Math.min(250 * 2 ** (attempt - 1), 5000);
+}
+
+async function sendWithRetry(
+  call: FetchLike,
+  url: string,
+  init: RequestInit,
+  retries: number,
+): Promise<Response> {
+  let attempt = 0;
+  while (true) {
+    const response = await call(url, init);
+    const retryable = response.status === 429 || response.status === 503;
+    if (!retryable || attempt >= retries) return response;
+    attempt += 1;
+    const delay = retryDelayMs(response, attempt);
+    await response.body?.cancel().catch(() => undefined);
+    if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));
+  }
+}
+
+async function tokenDigest(apiToken: string): Promise<string> {
+  const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(apiToken));
+  return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export async function readPublicJson<T>(
+  url: string,
+  schema: { parse: (data: unknown) => T },
+  options: PublicJsonRequestOptions = {},
+): Promise<{ data: T; etag: string | null; notModified: boolean }> {
+  const call = options.fetch ?? fetch;
+  const cache = options.etagCache;
+  const digest = options.apiToken ? await tokenDigest(options.apiToken) : "";
+  const cacheKey = `${url}#${digest}`;
+  const cached = cache?.get(cacheKey) as EtagEntry<T> | undefined;
+  const headers = new Headers();
+  if (options.apiToken) headers.set("authorization", `Bearer ${options.apiToken}`);
+  if (cached?.etag) headers.set("if-none-match", cached.etag);
+
+  const response = await sendWithRetry(
+    call,
+    url,
+    {
+      method: "GET",
+      headers,
+      cache: options.cache ?? defaultPublicInit.cache,
+      credentials: options.credentials ?? defaultPublicInit.credentials,
+    },
+    options.retries ?? 2,
+  );
+
+  if (response.status === 304 && cached) {
+    return { data: cached.data, etag: cached.etag, notModified: true };
+  }
+
+  if (!response.ok) throwResponseError(response.status, await readErrorBody(response));
+
+  const data = schema.parse(await response.json());
+  const etag = response.headers.get("etag");
+  if (cache && etag) cache.set(cacheKey, { etag, data });
+  return { data, etag, notModified: false };
+}
+
+export async function postJson<T>(
+  url: string,
+  body: unknown,
+  schema: { parse: (data: unknown) => T },
+  init: {
+    fetch?: FetchLike;
+    headers?: HeadersInit;
+    cache?: RequestCache;
+    credentials?: RequestCredentials;
+    retries?: number;
+    rawBody?: string;
+  } = {},
+): Promise<T> {
+  const call = init.fetch ?? fetch;
+  const payload = init.rawBody ?? JSON.stringify(body);
+  const response = await sendWithRetry(
+    call,
+    url,
+    {
+      method: "POST",
+      headers: (() => {
+        const headers = new Headers(init.headers);
+        headers.set("content-type", "application/json");
+        return headers;
+      })(),
+      body: payload,
+      cache: init.cache ?? "no-store",
+      credentials: init.credentials ?? "omit",
+    },
+    init.retries ?? 2,
+  );
+  if (!response.ok) throwResponseError(response.status, await readErrorBody(response));
+  return schema.parse(await response.json());
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+export {
+  type ContentListOptions,
+  type CreateStationClientOptions,
+  createStationClient,
+  type ReportPlaybackTarget,
+  type ScheduleWindow,
+  type StationClient,
+  type StationClientTransport,
+  type TrackHistoryOptions,
+} from "./client";
+export { createStationClientFromEnv, type RadioToolsEnv, stationClientOptionsFromEnv } from "./env";
+export { type EtagCache, type FetchLike, RadioToolsApiError, createEtagCache } from "./http";
+export { type PublicMediaVariant, publicMediaUrl } from "./media";
+export { type ReportPlaybackOptions, reportPlayback } from "./playback";
+export { type PreviewEditorialOptions, previewEditorial } from "./preview";
+export {
+  type PublicSocketHandlers,
+  type PublicSocketSubscription,
+  subscribePublicSocket,
+} from "./realtime";
+export {
+  LISTENER_CONTRACT_VERSION,
+  PUBLIC_SOCKET_PROTOCOL,
+  type SdkErrorCode,
+  type SdkErrorResponse,
+  type SdkPlaybackObservation,
+  type SdkPlaybackObservationResult,
+  type SdkPreviewInput,
+  type SdkPublicCurrentBroadcast,
+  type SdkPublicNowPlaying,
+  type SdkPublicOnAir,
+  type SdkPublicPrograms,
+  type SdkPublicSchedule,
+  type SdkPublicSchemaList,
+  type SdkPublicSocketEvent,
+  type SdkPublicStation,
+  type SdkPublicTrackHistory,
+  type SdkPublishedCollection,
+  type SdkPublishedRecord,
+  type SdkRevisionPreview,
+  type SdkTrafficPublic,
+  type SdkWeatherPublic,
+  sdkSchemas,
+} from "./schemas";

package/src/media.ts

@@ -0,0 +1,14 @@
+export type PublicMediaVariant = "thumb" | "display";
+
+/** Build a public media URL. RadioTools serves the bytes. The SDK does not download them. */
+export function publicMediaUrl(
+  baseUrl: string,
+  mediaResourcePrefix: string,
+  versionId: string,
+  variant?: PublicMediaVariant,
+): string {
+  const path = variant
+    ? `${mediaResourcePrefix}/${versionId}/${variant}`
+    : `${mediaResourcePrefix}/${versionId}`;
+  return new URL(path, baseUrl).href;
+}

package/src/playback.ts

@@ -0,0 +1,58 @@
+import type { FetchLike } from "./http";
+import { postJson } from "./http";
+import {
+  type SdkPlaybackObservation,
+  type SdkPlaybackObservationResult,
+  sdkSchemas,
+} from "./schemas";
+
+const MAX_PLAYBACK_BODY_BYTES = 8192;
+
+export type ReportPlaybackOptions = {
+  baseUrl: string;
+  /** Integration credential with integration name `playback` and scope `ingest:write`. */
+  ingestToken: string;
+  stationSlug?: string;
+  stationId?: string;
+  observation: SdkPlaybackObservation;
+  fetch?: FetchLike;
+  retries?: number;
+};
+
+/**
+ * Send one encoder observation to `POST /api/v1/integrations/playback`.
+ * Exactly one of `stationSlug` or `stationId` is sent. A missing `eventId` is
+ * assigned once so retries of this call stay idempotent.
+ */
+export async function reportPlayback(
+  options: ReportPlaybackOptions,
+): Promise<SdkPlaybackObservationResult> {
+  const ingestToken = options.ingestToken.trim();
+  if (!ingestToken) throw new Error("Playback ingest token is required");
+  if (options.stationId && options.stationSlug) {
+    throw new Error("Send exactly one of stationId or stationSlug");
+  }
+  if (!options.stationId && !options.stationSlug) {
+    throw new Error("stationSlug or stationId is required");
+  }
+
+  const parsed = sdkSchemas.PlaybackObservationIngestBody.parse(options.observation);
+  const body = { ...parsed, eventId: parsed.eventId ?? crypto.randomUUID() };
+  const payload = JSON.stringify(body);
+  if (new TextEncoder().encode(payload).byteLength > MAX_PLAYBACK_BODY_BYTES) {
+    throw new Error("Playback observation exceeds 8 KiB");
+  }
+
+  const url = new URL("/api/v1/integrations/playback", options.baseUrl);
+  if (options.stationId) url.searchParams.set("stationId", options.stationId);
+  else if (options.stationSlug) url.searchParams.set("stationSlug", options.stationSlug);
+
+  return postJson(url.href, body, sdkSchemas.PlaybackObservationResult, {
+    fetch: options.fetch,
+    headers: { authorization: `Bearer ${ingestToken}` },
+    cache: "no-store",
+    credentials: "omit",
+    retries: options.retries,
+    rawBody: payload,
+  });
+}

package/src/preview.ts

@@ -0,0 +1,65 @@
+import { graphqlRequest, parseGraphqlPreview, previewMutation } from "./graphql";
+import type { FetchLike } from "./http";
+import { postJson } from "./http";
+import { type SdkPreviewInput, type SdkRevisionPreview, sdkSchemas } from "./schemas";
+
+export type PreviewEditorialOptions = {
+  baseUrl: string;
+  /** Short-lived preview grant. Pass it explicitly. Never read it from the query string. */
+  grant: string;
+  /** Required for GraphQL preview. REST preview uses only the grant. */
+  apiToken?: string;
+  input: SdkPreviewInput;
+  fetch?: FetchLike;
+  /** Listener site origin for browser preview CORS on the HTTP preview route. */
+  listenerOrigin?: string;
+  transport?: "http" | "graphql";
+  stationSlug?: string;
+  retries?: number;
+};
+
+/**
+ * Preview unpublished editorial content with a Bearer grant.
+ * Studio session cookies are never sent.
+ */
+export async function previewEditorial(
+  options: PreviewEditorialOptions,
+): Promise<SdkRevisionPreview> {
+  const grant = options.grant.trim();
+  if (!grant) throw new Error("Preview grant is required");
+
+  if (options.transport === "graphql") {
+    if (!options.stationSlug) throw new Error("stationSlug is required for GraphQL preview");
+    if (!options.apiToken) throw new Error("Listener API token is required for GraphQL preview");
+    const endpoint = new URL(
+      `/api/v1/stations/${encodeURIComponent(options.stationSlug)}/graphql`,
+      options.baseUrl,
+    ).href;
+    const data = await graphqlRequest<{ previewEditorial: unknown }>(
+      endpoint,
+      previewMutation,
+      { input: options.input },
+      {
+        fetch: options.fetch,
+        apiToken: options.apiToken,
+        previewGrant: grant,
+        credentials: "omit",
+        cache: "no-store",
+        retries: options.retries,
+      },
+    );
+    return parseGraphqlPreview(data);
+  }
+
+  const url = new URL("/api/v1/preview/editorial", options.baseUrl).href;
+  const headers: Record<string, string> = { authorization: `Bearer ${grant}` };
+  if (options.listenerOrigin) headers.origin = options.listenerOrigin;
+
+  return postJson(url, options.input, sdkSchemas.RevisionPreview, {
+    fetch: options.fetch,
+    headers,
+    cache: "no-store",
+    credentials: "omit",
+    retries: options.retries,
+  });
+}