@rivi-software/radiotools-contract 0.2.0

package/graphql/schema.graphql

@@ -0,0 +1,214 @@
+scalar JSON
+
+  type Query {
+    station: Station!
+    schemas(type: String, version: Int): [ContentSchema!]!
+    content(type: String!, cursor: ID, limit: Int = 25): ContentCollection!
+    contentRecord(id: ID!): PublishedRecord!
+    schedule(fromDate: String!, throughDate: String!): Schedule!
+    programs(fromDate: String!, throughDate: String!): Programs!
+    currentBroadcast: CurrentBroadcast!
+    nowPlaying: NowPlaying!
+    trackHistory(cursor: String, limit: Int = 25): TrackHistory!
+    weather: Weather
+    traffic: Traffic
+  }
+
+  type Mutation {
+    previewEditorial(input: PreviewInput!): RevisionPreview!
+  }
+
+  type Station {
+    contractVersion: Int!
+    id: ID!
+    slug: String!
+    name: String!
+    timezone: String!
+    publishingLanguage: String!
+    resources: StationResources!
+    delivery: StationDelivery!
+  }
+
+  type StationResources {
+    schemas: String!
+    content: String
+    schedule: String
+    programs: String
+    broadcast: String
+    nowPlaying: String
+    trackHistory: String
+    socket: String
+    weather: String
+    traffic: String
+    media: String!
+  }
+
+  type StationDelivery {
+    cache: String!
+    conditional: String!
+    pollIntervalSeconds: Int!
+  }
+
+  type ContentSchema {
+    key: String!
+    label: String!
+    version: Int!
+    archived: Boolean!
+    fields: JSON!
+  }
+
+  type ContentCollection {
+    records: [PublishedRecord!]!
+    nextCursor: ID
+  }
+
+  type PublishedRecord {
+    id: ID!
+    publicationId: ID!
+    revision: Int!
+    type: String!
+    schemaVersion: Int!
+    publishedAt: String!
+    values: JSON!
+    document: JSON!
+    media: [PublicMedia!]!
+  }
+
+  type PublicMedia {
+    assetId: ID!
+    versionId: ID!
+    kind: String!
+    url: String!
+    credits: String!
+    mime: String!
+  }
+
+  type Schedule {
+    contractVersion: Int!
+    timezone: String!
+    broadcasts: [Broadcast!]!
+    truncated: Boolean!
+  }
+
+  type Programs {
+    contractVersion: Int!
+    timezone: String!
+    fromDate: String!
+    throughDate: String!
+    programs: [ProgramSummary!]!
+    truncated: Boolean!
+  }
+
+  type ProgramSummary {
+    id: ID!
+    title: String!
+    profileId: ID
+  }
+
+  type CurrentBroadcast {
+    contractVersion: Int!
+    timezone: String!
+    asOf: String!
+    broadcast: Broadcast
+  }
+
+  type NowPlaying {
+    contractVersion: Int!
+    stationId: ID!
+    timezone: String!
+    track: PlaybackTrack
+    elapsedSeconds: Int
+    endsAt: String
+    freshness: PlaybackFreshness!
+  }
+
+  type PlaybackTrack {
+    artist: String!
+    title: String!
+    album: String
+    durationSeconds: Int
+    artworkUrl: String
+    isPlaying: Boolean!
+    observedAt: String!
+    receivedAt: String!
+  }
+
+  type PlaybackFreshness {
+    status: String!
+    thresholdSeconds: Int!
+    ageSeconds: Int
+    observedAt: String
+    receivedAt: String
+  }
+
+  type TrackHistory {
+    contractVersion: Int!
+    stationId: ID!
+    items: [HistoryEntry!]!
+    nextCursor: String
+  }
+
+  type HistoryEntry {
+    id: ID!
+    artist: String!
+    title: String!
+    album: String
+    durationSeconds: Int
+    artworkUrl: String
+    isPlaying: Boolean!
+    observedAt: String!
+    receivedAt: String!
+  }
+
+  type Broadcast {
+    id: ID!
+    title: String!
+    startsAt: String!
+    endsAt: String!
+    timezone: String!
+    localDate: String!
+    resolution: String!
+    status: String!
+    cancellationReason: String!
+    repeatOfId: ID
+    program: BroadcastProgram!
+    presenters: [BroadcastPresenter!]!
+  }
+
+  type BroadcastProgram {
+    id: ID!
+    title: String!
+    profileId: ID
+  }
+
+  type BroadcastPresenter {
+    id: ID!
+    title: String!
+  }
+
+  type Weather {
+    stationId: ID!
+    timezone: String!
+    snapshots: JSON!
+  }
+
+  type Traffic {
+    stationId: ID!
+    snapshot: JSON!
+  }
+
+  input PreviewInput {
+    stationId: ID!
+    recordId: ID!
+    revision: Int!
+    audience: String!
+  }
+
+  type RevisionPreview {
+    id: ID!
+    revision: Int!
+    schemaVersion: Int!
+    values: JSON!
+    document: JSON!
+    media: [PublicMedia!]!
+  }

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@rivi-software/radiotools-contract",
+  "version": "0.2.0",
+  "description": "RadioTools listener API contract (manifest and GraphQL schema)",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./graphql": "./graphql/schema.graphql"
+  },
+  "files": [
+    "src",
+    "graphql"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RIVI-Software/radiotools-sdk.git",
+    "directory": "packages/contract"
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export {
+  LISTENER_CONTRACT_VERSION,
+  PUBLIC_SOCKET_PROTOCOL,
+  listenerSdkManifest,
+  type AuthScope,
+  type SdkClientMethod,
+  type SdkEnvVar,
+  type SdkManifest,
+} from "./manifest";
+
+const packageDir = dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the checked-in GraphQL schema for this contract version. */
+export function graphqlSchemaPath(): string {
+  return join(packageDir, "..", "graphql", "schema.graphql");
+}
+
+export function readGraphqlSchema(): string {
+  return readFileSync(graphqlSchemaPath(), "utf8");
+}

package/src/manifest.ts

@@ -0,0 +1,207 @@
+/** Canonical listener SDK surface — used by @rivi-software/radiotools-sdk-generator targets. */
+
+export const LISTENER_CONTRACT_VERSION = 1 as const;
+export const PUBLIC_SOCKET_PROTOCOL = "radiotools.public.v1" as const;
+
+export type AuthScope = "listener:read" | "ingest:write";
+
+export type SdkEnvVar = {
+  name: string;
+  required: boolean;
+  description: string;
+};
+
+export type SdkClientMethod = {
+  name: string;
+  scope: AuthScope | "either";
+  description: string;
+  graphqlField?: string;
+  rest?: {
+    method: "GET" | "POST";
+    pathPattern: string;
+    resourceKey?: string;
+  };
+};
+
+export type SdkManifest = {
+  contractVersion: typeof LISTENER_CONTRACT_VERSION;
+  socketProtocol: typeof PUBLIC_SOCKET_PROTOCOL;
+  packageNames: {
+    typescript: "@rivi-software/radiotools-sdk";
+    python: "radiotools_sdk";
+    react: "@rivi-software/radiotools-sdk-react";
+    vue: "@rivi-software/radiotools-sdk-vue";
+    svelte: "@rivi-software/radiotools-sdk-svelte";
+    go: "github.com/radiotools/radiotools-sdk-go";
+    csharp: "RadioTools.Sdk";
+    ruby: "radiotools_sdk";
+    php: "radiotools/sdk";
+    openapi: "@rivi-software/radiotools-openapi";
+    kotlin: "com.radiotools.sdk";
+    swift: "RadioToolsSDK";
+    next: "@rivi-software/radiotools-sdk-next";
+  };
+  env: SdkEnvVar[];
+  clientMethods: SdkClientMethod[];
+  integrations: {
+    playback: {
+      method: "POST";
+      path: "/api/v1/integrations/playback";
+      scope: "ingest:write";
+    };
+  };
+};
+
+export const listenerSdkManifest: SdkManifest = {
+  contractVersion: LISTENER_CONTRACT_VERSION,
+  socketProtocol: PUBLIC_SOCKET_PROTOCOL,
+  packageNames: {
+    typescript: "@rivi-software/radiotools-sdk",
+    python: "radiotools_sdk",
+    react: "@rivi-software/radiotools-sdk-react",
+    vue: "@rivi-software/radiotools-sdk-vue",
+    svelte: "@rivi-software/radiotools-sdk-svelte",
+    go: "github.com/radiotools/radiotools-sdk-go",
+    csharp: "RadioTools.Sdk",
+    ruby: "radiotools_sdk",
+    php: "radiotools/sdk",
+    openapi: "@rivi-software/radiotools-openapi",
+    kotlin: "com.radiotools.sdk",
+    swift: "RadioToolsSDK",
+    next: "@rivi-software/radiotools-sdk-next",
+  },
+  env: [
+    {
+      name: "RADIOTOOLS_BASE_URL",
+      required: true,
+      description: "RadioTools origin (no trailing slash).",
+    },
+    {
+      name: "RADIOTOOLS_STATION_SLUG",
+      required: true,
+      description: "Station slug for published reads and default playback ingest.",
+    },
+    {
+      name: "RADIOTOOLS_API_TOKEN",
+      required: false,
+      description: "Station key with listener:read for published JSON and the public socket.",
+    },
+    {
+      name: "RADIOTOOLS_INGEST_TOKEN",
+      required: false,
+      description: "Integration key named playback with ingest:write for encoder observations.",
+    },
+  ],
+  clientMethods: [
+    {
+      name: "getStation",
+      scope: "listener:read",
+      description: "Published station metadata and resource hrefs.",
+      graphqlField: "station",
+      rest: { method: "GET", pathPattern: "/api/v1/stations/{stationSlug}" },
+    },
+    {
+      name: "getSchemas",
+      scope: "listener:read",
+      description: "Content type schemas for published editorial.",
+      graphqlField: "schemas",
+      rest: { method: "GET", pathPattern: "{resources.schemas}", resourceKey: "schemas" },
+    },
+    {
+      name: "getContent",
+      scope: "listener:read",
+      description: "Paginated published content records.",
+      graphqlField: "content",
+      rest: { method: "GET", pathPattern: "{resources.content}", resourceKey: "content" },
+    },
+    {
+      name: "getContentRecord",
+      scope: "listener:read",
+      description: "One published content record by id.",
+      graphqlField: "contentRecord",
+      rest: { method: "GET", pathPattern: "{resources.content}/{id}", resourceKey: "content" },
+    },
+    {
+      name: "getSchedule",
+      scope: "listener:read",
+      description: "Broadcast schedule for a date window (1–31 inclusive days).",
+      graphqlField: "schedule",
+      rest: { method: "GET", pathPattern: "{resources.schedule}", resourceKey: "schedule" },
+    },
+    {
+      name: "getPrograms",
+      scope: "listener:read",
+      description: "Program summaries for a date window (1–31 inclusive days).",
+      graphqlField: "programs",
+      rest: { method: "GET", pathPattern: "{resources.programs}", resourceKey: "programs" },
+    },
+    {
+      name: "getCurrentBroadcast",
+      scope: "listener:read",
+      description: "Current on-air broadcast state.",
+      graphqlField: "currentBroadcast",
+      rest: { method: "GET", pathPattern: "{resources.broadcast}", resourceKey: "broadcast" },
+    },
+    {
+      name: "getNowPlaying",
+      scope: "listener:read",
+      description: "Now playing track and freshness.",
+      graphqlField: "nowPlaying",
+      rest: { method: "GET", pathPattern: "{resources.nowPlaying}", resourceKey: "nowPlaying" },
+    },
+    {
+      name: "getTrackHistory",
+      scope: "listener:read",
+      description: "Paginated recently played tracks.",
+      graphqlField: "trackHistory",
+      rest: {
+        method: "GET",
+        pathPattern: "{resources.trackHistory}",
+        resourceKey: "trackHistory",
+      },
+    },
+    {
+      name: "getWeather",
+      scope: "listener:read",
+      description: "Weather snapshot when enabled; otherwise null without a second request.",
+      graphqlField: "weather",
+      rest: { method: "GET", pathPattern: "{resources.weather}", resourceKey: "weather" },
+    },
+    {
+      name: "getTraffic",
+      scope: "listener:read",
+      description: "Traffic snapshot when enabled; otherwise null without a second request.",
+      graphqlField: "traffic",
+      rest: { method: "GET", pathPattern: "{resources.traffic}", resourceKey: "traffic" },
+    },
+    {
+      name: "recommendedPollIntervalMs",
+      scope: "listener:read",
+      description: "Suggested poll interval from station.delivery.pollIntervalSeconds.",
+    },
+    {
+      name: "previewEditorial",
+      scope: "listener:read",
+      description: "Preview unpublished editorial with a grant (not from query strings).",
+      graphqlField: "previewEditorial",
+    },
+    {
+      name: "reportPlayback",
+      scope: "ingest:write",
+      description: "Send one encoder playback observation.",
+      rest: { method: "POST", pathPattern: "/api/v1/integrations/playback" },
+    },
+    {
+      name: "subscribe",
+      scope: "listener:read",
+      description: "Public WebSocket subscription (server adapter required for Authorization).",
+    },
+  ],
+  integrations: {
+    playback: {
+      method: "POST",
+      path: "/api/v1/integrations/playback",
+      scope: "ingest:write",
+    },
+  },
+};