@rivi-software/radiotools-sdk-generator 0.2.0

package/dist/targets/kotlin.js

@@ -0,0 +1,180 @@
+import { listenerSdkManifest } from "@rivi-software/radiotools-contract";
+function renderKotlinClient() {
+    const manifest = listenerSdkManifest;
+    return `// Generated by @rivi-software/radiotools-sdk-generator — do not edit by hand.
+package com.radiotools.sdk
+
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.put
+import okhttp3.HttpUrl.Companion.toHttpUrl
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.MediaType.Companion.toMediaType
+import java.io.IOException
+import java.util.concurrent.TimeUnit
+
+class StationClient private constructor(
+    private val baseUrl: String,
+    private val stationSlug: String,
+    private val apiToken: String?,
+    private val ingestToken: String?,
+    private val http: OkHttpClient,
+    private val json: Json,
+) {
+    companion object {
+        fun create(
+            baseUrl: String,
+            stationSlug: String,
+            apiToken: String? = null,
+            ingestToken: String? = null,
+            http: OkHttpClient? = null,
+        ): StationClient {
+            require(!apiToken.isNullOrBlank() || !ingestToken.isNullOrBlank()) {
+                "apiToken or ingestToken is required"
+            }
+            val client =
+                http
+                    ?: OkHttpClient.Builder()
+                        .connectTimeout(30, TimeUnit.SECONDS)
+                        .readTimeout(30, TimeUnit.SECONDS)
+                        .build()
+            return StationClient(
+                baseUrl.trimEnd('/'),
+                stationSlug,
+                apiToken?.trim()?.takeIf { it.isNotEmpty() },
+                ingestToken?.trim()?.takeIf { it.isNotEmpty() },
+                client,
+                Json { ignoreUnknownKeys = true },
+            )
+        }
+    }
+
+    @Throws(IOException::class)
+    fun getStation(): JsonObject = getJson("/api/v1/stations/\${encode(stationSlug)}", ingest = false)
+
+    @Throws(IOException::class)
+    fun getNowPlaying(): JsonObject {
+        val station = getStation()
+        val href =
+            station["resources"]?.let { it as? JsonObject }?.get("nowPlaying")?.toString()?.trim('"')
+                ?: error("nowPlaying resource unavailable")
+        return getJson(href, ingest = false)
+    }
+
+    @Throws(IOException::class)
+    fun getWeather(): JsonObject? {
+        val href =
+            getStation()["resources"]?.let { it as? JsonObject }?.get("weather")?.toString()?.trim('"')
+        if (href.isNullOrEmpty()) return null
+        return getJson(href, ingest = false)
+    }
+
+    @Throws(IOException::class)
+    fun getTraffic(): JsonObject? {
+        val href =
+            getStation()["resources"]?.let { it as? JsonObject }?.get("traffic")?.toString()?.trim('"')
+        if (href.isNullOrEmpty()) return null
+        return getJson(href, ingest = false)
+    }
+
+    @Throws(IOException::class)
+    fun reportPlayback(observation: JsonObject, stationId: String? = null): JsonObject {
+        val query =
+            if (!stationId.isNullOrBlank()) {
+                "stationId=\${encode(stationId)}"
+            } else {
+                "stationSlug=\${encode(stationSlug)}"
+            }
+        val path = "${manifest.integrations.playback.path}?\$query"
+        return postJson(path, observation, ingest = true)
+    }
+
+    private fun getJson(path: String, ingest: Boolean): JsonObject {
+        val url = if (path.startsWith("http")) path else "\$baseUrl\$path"
+        val request =
+            Request.Builder()
+                .url(url.toHttpUrl())
+                .header("Authorization", bearer(ingest))
+                .get()
+                .build()
+        http.newCall(request).execute().use { response ->
+            val body = response.body?.string() ?: "{}"
+            if (!response.isSuccessful) error("GET \${'$'}url failed: \${response.code} \${'$'}body")
+            return json.decodeFromString(JsonObject.serializer(), body)
+        }
+    }
+
+    private fun postJson(path: String, body: JsonObject, ingest: Boolean): JsonObject {
+        val url = "\$baseUrl\$path".toHttpUrl()
+        val mediaType = "application/json; charset=utf-8".toMediaType()
+        val payload = json.encodeToString(JsonObject.serializer(), body)
+        val request =
+            Request.Builder()
+                .url(url)
+                .header("Authorization", bearer(ingest))
+                .post(payload.toRequestBody(mediaType))
+                .build()
+        http.newCall(request).execute().use { response ->
+            val text = response.body?.string() ?: "{}"
+            if (!response.isSuccessful) error("POST \${'$'}url failed: \${response.code} \${'$'}text")
+            return json.decodeFromString(JsonObject.serializer(), text)
+        }
+    }
+
+    private fun bearer(ingest: Boolean): String {
+        val token = if (ingest) ingestToken else apiToken
+        require(!token.isNullOrBlank()) { "Missing bearer token" }
+        return "Bearer \$token"
+    }
+
+    private fun encode(value: String): String =
+        java.net.URLEncoder.encode(value, Charsets.UTF_8.name()).replace("+", "%20")
+}
+`;
+}
+export const kotlinTarget = {
+    id: "kotlin",
+    description: "Kotlin/Android OkHttp client stubs (packages/sdk-kotlin)",
+    outputDir: (repoRoot) => `${repoRoot}/packages/sdk-kotlin/src/main/kotlin/com/radiotools/sdk`,
+    generate: (repoRoot) => [
+        { path: "StationClient.kt", contents: renderKotlinClient() },
+        {
+            path: `${repoRoot}/packages/sdk-kotlin/build.gradle.kts`,
+            contents: `plugins {
+    kotlin("jvm") version "2.1.0"
+    kotlin("plugin.serialization") version "2.1.0"
+}
+
+group = "com.radiotools"
+version = "0.2.0"
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation("com.squareup.okhttp3:okhttp:4.12.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.0")
+}
+
+kotlin {
+    jvmToolchain(17)
+}
+`,
+        },
+        {
+            path: `${repoRoot}/packages/sdk-kotlin/README.md`,
+            contents: `# RadioTools Kotlin SDK
+
+Generated Android/JVM REST stubs (OkHttp + kotlinx.serialization).
+
+Regenerate: \`bun run --filter @rivi-software/radiotools-sdk-generator generate --target kotlin\`
+
+OpenAPI models: see \`packages/openapi/openapi.json\` (from Zod \`sdkSchemas\`).
+`,
+        },
+    ],
+};

package/dist/targets/next.d.ts

@@ -0,0 +1,2 @@
+import type { SdkTarget } from "../types";
+export declare const nextTarget: SdkTarget;

package/dist/targets/next.js

@@ -0,0 +1,80 @@
+import { ZERO_ARG_READ_METHODS } from "../shared/reads";
+function renderNextServerHelpers() {
+    const cachedReads = ZERO_ARG_READ_METHODS.map((method) => {
+        const fnName = `fetch${method.charAt(0).toUpperCase()}${method.slice(1)}`;
+        return `export async function ${fnName}(client: StationClient) {
+  return client.${method}();
+}`;
+    }).join("\n\n");
+    const routeHandlers = ZERO_ARG_READ_METHODS.map((method) => {
+        const suffix = method.replace(/^get/, "");
+        const exportName = `jsonResponse${suffix}`;
+        const routeName = suffix.replace(/([A-Z])/g, "-$1").toLowerCase();
+        return `/** App Router helper for \`/api/radiotools/${routeName}\` */
+export async function ${exportName}(client: StationClient) {
+  const data = await client.${method}();
+  return NextResponse.json(data);
+}`;
+    }).join("\n\n");
+    return `/** Generated by @rivi-software/radiotools-sdk-generator — do not edit by hand. */
+import "server-only";
+
+import {
+  createStationClientFromEnv,
+  type CreateStationClientOptions,
+  type StationClient,
+} from "@rivi-software/radiotools-sdk";
+import { unstable_cache } from "next/cache";
+import { NextResponse } from "next/server";
+
+const DEFAULT_REVALIDATE_SECONDS = 30;
+
+export function createRadioToolsServerClient(
+  overrides: Partial<CreateStationClientOptions> = {},
+): StationClient {
+  return createStationClientFromEnv(undefined, overrides);
+}
+
+export function createCachedRadioToolsReader<T>(
+  cacheKey: string,
+  read: (client: StationClient) => Promise<T>,
+  revalidateSeconds: number = DEFAULT_REVALIDATE_SECONDS,
+) {
+  return unstable_cache(async () => read(createRadioToolsServerClient()), [cacheKey], {
+    revalidate: revalidateSeconds,
+  });
+}
+
+${cachedReads}
+
+export async function fetchRecommendedPollIntervalMs(client: StationClient) {
+  return client.recommendedPollIntervalMs();
+}
+
+export const cachedGetStation = createCachedRadioToolsReader("radiotools:station", (c) => c.getStation());
+export const cachedGetNowPlaying = createCachedRadioToolsReader("radiotools:now-playing", (c) =>
+  c.getNowPlaying(),
+);
+export const cachedGetCurrentBroadcast = createCachedRadioToolsReader(
+  "radiotools:current-broadcast",
+  (c) => c.getCurrentBroadcast(),
+);
+
+${routeHandlers}
+
+export type { StationClient, CreateStationClientOptions };
+`;
+}
+export const nextTarget = {
+    id: "next",
+    description: "Next.js App Router server helpers (packages/sdk-next)",
+    outputDir: (repoRoot) => `${repoRoot}/packages/sdk-next/src`,
+    generate: () => [
+        { path: "server.generated.ts", contents: renderNextServerHelpers() },
+        {
+            path: "index.ts",
+            contents: `export * from "./server.generated";
+`,
+        },
+    ],
+};

package/dist/targets/openapi.d.ts

@@ -0,0 +1,2 @@
+import type { SdkTarget } from "../types";
+export declare const openapiTarget: SdkTarget;

package/dist/targets/openapi.js

@@ -0,0 +1,223 @@
+import { listenerSdkManifest } from "@rivi-software/radiotools-contract";
+import { buildZodOpenApiComponents, jsonSchemaRef, operationResponseSchemas, } from "../openapi/zod-components";
+function errorResponseContent() {
+    return {
+        "application/json": {
+            schema: jsonSchemaRef("ErrorResponse"),
+        },
+    };
+}
+function successResponse(operationId) {
+    const mapping = operationResponseSchemas[operationId];
+    if (!mapping) {
+        return { description: "Success" };
+    }
+    const schema = jsonSchemaRef(mapping.schema);
+    return {
+        description: mapping.description,
+        content: {
+            "application/json": {
+                schema: mapping.nullable ? { anyOf: [schema, { type: "null" }] } : schema,
+            },
+        },
+    };
+}
+function renderOpenApi() {
+    const manifest = listenerSdkManifest;
+    const envDescriptions = Object.fromEntries(manifest.env.map((entry) => [entry.name, entry.description]));
+    const zodComponents = buildZodOpenApiComponents();
+    const paths = {
+        "/api/v1/stations/{stationSlug}": {
+            get: {
+                operationId: "getStation",
+                summary: "Published station metadata",
+                tags: ["listener"],
+                security: [{ bearerListener: [] }],
+                parameters: [
+                    {
+                        name: "stationSlug",
+                        in: "path",
+                        required: true,
+                        schema: { type: "string" },
+                    },
+                ],
+                responses: {
+                    "200": successResponse("getStation"),
+                    "401": { description: "Missing or invalid listener token", content: errorResponseContent() },
+                    "404": { description: "Station not found", content: errorResponseContent() },
+                },
+            },
+        },
+        [manifest.integrations.playback.path]: {
+            post: {
+                operationId: "reportPlayback",
+                summary: "Encoder playback observation",
+                tags: ["ingest"],
+                security: [{ bearerIngest: [] }],
+                parameters: [
+                    {
+                        name: "stationSlug",
+                        in: "query",
+                        required: false,
+                        schema: { type: "string" },
+                    },
+                    {
+                        name: "stationId",
+                        in: "query",
+                        required: false,
+                        schema: { type: "string" },
+                    },
+                ],
+                requestBody: {
+                    required: true,
+                    content: {
+                        "application/json": {
+                            schema: jsonSchemaRef("PlaybackObservationIngestBody"),
+                        },
+                    },
+                },
+                responses: {
+                    "200": successResponse("reportPlayback"),
+                    "401": { description: "Missing or invalid ingest token", content: errorResponseContent() },
+                    "503": { description: "Temporary failure", content: errorResponseContent() },
+                },
+            },
+        },
+    };
+    const queryParamsByOperation = {
+        getContent: [
+            { name: "type", required: true, schema: { type: "string" } },
+            { name: "cursor", schema: { type: "string", format: "uuid" } },
+            { name: "limit", schema: { type: "integer", minimum: 1, maximum: 50, default: 25 } },
+        ],
+        getSchedule: [
+            { name: "fromDate", required: true, schema: { type: "string", format: "date" } },
+            { name: "throughDate", required: true, schema: { type: "string", format: "date" } },
+        ],
+        getPrograms: [
+            { name: "fromDate", required: true, schema: { type: "string", format: "date" } },
+            { name: "throughDate", required: true, schema: { type: "string", format: "date" } },
+        ],
+        getTrackHistory: [
+            { name: "cursor", schema: { type: "string" } },
+            { name: "limit", schema: { type: "integer", minimum: 1, maximum: 50, default: 25 } },
+        ],
+    };
+    for (const method of manifest.clientMethods) {
+        if (!method.rest || method.rest.method !== "GET" || !method.rest.resourceKey)
+            continue;
+        if (method.name === "getStation")
+            continue;
+        const pathKey = method.rest.resourceKey === "content"
+            ? `/api/v1/stations/{stationSlug}/content`
+            : method.rest.resourceKey === "schemas"
+                ? `/api/v1/stations/{stationSlug}/schemas`
+                : `/api/v1/stations/{stationSlug}/${method.rest.resourceKey}`;
+        const extraParams = queryParamsByOperation[method.name] ?? [];
+        paths[pathKey] = {
+            get: {
+                operationId: method.name,
+                summary: method.description,
+                tags: ["listener"],
+                security: [{ bearerListener: [] }],
+                parameters: [
+                    { name: "stationSlug", in: "path", required: true, schema: { type: "string" } },
+                    ...extraParams.map((param) => ({
+                        name: param.name,
+                        in: "query",
+                        required: param.required ?? false,
+                        schema: param.schema,
+                    })),
+                ],
+                responses: {
+                    "200": successResponse(method.name),
+                    "401": { description: "Unauthorized", content: errorResponseContent() },
+                    "404": { description: "Resource disabled or not found", content: errorResponseContent() },
+                },
+            },
+        };
+        if (method.name === "getContent") {
+            paths[`/api/v1/stations/{stationSlug}/content/{id}`] = {
+                get: {
+                    operationId: "getContentRecord",
+                    summary: "One published content record by id",
+                    tags: ["listener"],
+                    security: [{ bearerListener: [] }],
+                    parameters: [
+                        { name: "stationSlug", in: "path", required: true, schema: { type: "string" } },
+                        { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
+                    ],
+                    responses: {
+                        "200": successResponse("getContentRecord"),
+                        "404": { description: "Not found", content: errorResponseContent() },
+                    },
+                },
+            };
+        }
+    }
+    const doc = {
+        openapi: "3.1.0",
+        info: {
+            title: "RadioTools Listener API",
+            version: `${manifest.contractVersion}.0.0`,
+            description: "OpenAPI generated from @rivi-software/radiotools-contract paths and @rivi-software/radiotools-sdk Zod schemas (sdkSchemas). Station resource hrefs may differ from these templates.",
+        },
+        servers: [
+            {
+                url: "{RADIOTOOLS_BASE_URL}",
+                variables: { RADIOTOOLS_BASE_URL: { default: "https://radio.example" } },
+            },
+        ],
+        tags: [
+            { name: "listener", description: "Requires listener:read (RADIOTOOLS_API_TOKEN)" },
+            { name: "ingest", description: "Requires ingest:write (RADIOTOOLS_INGEST_TOKEN)" },
+        ],
+        components: {
+            securitySchemes: {
+                bearerListener: {
+                    type: "http",
+                    scheme: "bearer",
+                    description: envDescriptions.RADIOTOOLS_API_TOKEN ?? "Station listener key",
+                },
+                bearerIngest: {
+                    type: "http",
+                    scheme: "bearer",
+                    description: envDescriptions.RADIOTOOLS_INGEST_TOKEN ?? "Playback ingest key",
+                },
+            },
+            schemas: {
+                ...zodComponents.schemas,
+            },
+        },
+        paths,
+        "x-radiotools": {
+            contractVersion: manifest.contractVersion,
+            socketProtocol: manifest.socketProtocol,
+            zodSchemaSource: "@rivi-software/radiotools-sdk/schemas#sdkSchemas",
+            graphqlSchema: "@rivi-software/radiotools-contract/graphql",
+        },
+    };
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+export const openapiTarget = {
+    id: "openapi",
+    description: "OpenAPI 3.1 with components from Zod sdkSchemas (packages/openapi)",
+    outputDir: (repoRoot) => `${repoRoot}/packages/openapi`,
+    generate: () => [
+        { path: "openapi.json", contents: renderOpenApi() },
+        {
+            path: "README.md",
+            contents: `# RadioTools OpenAPI
+
+\`openapi.json\` is generated from:
+
+- REST paths in \`@rivi-software/radiotools-contract\`
+- Response and request bodies from \`@rivi-software/radiotools-sdk\` **Zod** types (\`sdkSchemas\`) via \`z.toJSONSchema\`
+
+\`\`\`bash
+bun run --filter @rivi-software/radiotools-sdk-generator generate --target openapi
+\`\`\`
+`,
+        },
+    ],
+};

package/dist/targets/php.d.ts

@@ -0,0 +1,2 @@
+import type { SdkTarget } from "../types";
+export declare const phpTarget: SdkTarget;

package/dist/targets/php.js

@@ -0,0 +1,165 @@
+import { listenerSdkManifest } from "@rivi-software/radiotools-contract";
+function renderPhpClient() {
+    const playbackPath = listenerSdkManifest.integrations.playback.path;
+    return `<?php
+// Generated by @rivi-software/radiotools-sdk-generator — do not edit by hand.
+declare(strict_types=1);
+
+namespace RadioTools\\Sdk;
+
+final class StationClient
+{
+    public function __construct(
+        private readonly string $baseUrl,
+        private readonly string $stationSlug,
+        private readonly ?string $apiToken = null,
+        private readonly ?string $ingestToken = null,
+    ) {
+        if (($this->apiToken ?? '') === '' && ($this->ingestToken ?? '') === '') {
+            throw new \\InvalidArgumentException('apiToken or ingestToken is required');
+        }
+    }
+
+    public static function fromEnv(): self
+    {
+        $base = trim(getenv('RADIOTOOLS_BASE_URL') ?: '');
+        $slug = trim(getenv('RADIOTOOLS_STATION_SLUG') ?: '');
+        if ($base === '' || $slug === '') {
+            throw new \\RuntimeException('Set RADIOTOOLS_BASE_URL and RADIOTOOLS_STATION_SLUG');
+        }
+        return new self(
+            $base,
+            $slug,
+            getenv('RADIOTOOLS_API_TOKEN') ?: null,
+            getenv('RADIOTOOLS_INGEST_TOKEN') ?: null,
+        );
+    }
+
+    /** @return array<string, mixed> */
+    public function getStation(): array
+    {
+        $path = '/api/v1/stations/' . rawurlencode($this->stationSlug);
+        return $this->getJson($path, ingest: false);
+    }
+
+    /** @return array<string, mixed>|null */
+    public function getWeather(): ?array
+    {
+        $station = $this->getStation();
+        $href = $station['resources']['weather'] ?? null;
+        if (!is_string($href) || $href === '') {
+            return null;
+        }
+        return $this->getJson($href, ingest: false);
+    }
+
+    /** @return array<string, mixed>|null */
+    public function getTraffic(): ?array
+    {
+        $station = $this->getStation();
+        $href = $station['resources']['traffic'] ?? null;
+        if (!is_string($href) || $href === '') {
+            return null;
+        }
+        return $this->getJson($href, ingest: false);
+    }
+
+    /** @param array<string, mixed> $observation
+     *  @return array<string, mixed>
+     */
+    public function reportPlayback(array $observation, ?string $stationId = null): array
+    {
+        $query = $stationId !== null
+            ? 'stationId=' . rawurlencode($stationId)
+            : 'stationSlug=' . rawurlencode($this->stationSlug);
+        return $this->postJson('${playbackPath}?' . $query, $observation, ingest: true);
+    }
+
+    /** @return array<string, mixed> */
+    private function getJson(string $path, bool $ingest): array
+    {
+        $url = str_starts_with($path, 'http') ? $path : rtrim($this->baseUrl, '/') . $path;
+        return $this->request('GET', $url, null, $ingest);
+    }
+
+    /** @param array<string, mixed> $body
+     *  @return array<string, mixed>
+     */
+    private function postJson(string $path, array $body, bool $ingest): array
+    {
+        $url = rtrim($this->baseUrl, '/') . $path;
+        return $this->request('POST', $url, json_encode($body, JSON_THROW_ON_ERROR), $ingest);
+    }
+
+    /** @return array<string, mixed> */
+    private function request(string $method, string $url, ?string $body, bool $ingest): array
+    {
+        $token = $ingest ? $this->ingestToken : $this->apiToken;
+        if ($token === null || $token === '') {
+            throw new \\RuntimeException('Missing bearer token');
+        }
+
+        $ch = curl_init($url);
+        if ($ch === false) {
+            throw new \\RuntimeException('curl_init failed');
+        }
+
+        $headers = [
+            'Authorization: Bearer ' . $token,
+            'Accept: application/json',
+        ];
+        if ($body !== null) {
+            $headers[] = 'Content-Type: application/json';
+        }
+
+        curl_setopt_array($ch, [
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_CUSTOMREQUEST => $method,
+            CURLOPT_HTTPHEADER => $headers,
+            CURLOPT_POSTFIELDS => $body,
+        ]);
+
+        $raw = curl_exec($ch);
+        $code = (int) curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
+        curl_close($ch);
+
+        if ($raw === false || $code >= 400) {
+            throw new \\RuntimeException("HTTP {$code}: " . (string) $raw);
+        }
+
+        /** @var array<string, mixed> */
+        return json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
+    }
+}
+`;
+}
+export const phpTarget = {
+    id: "php",
+    description: "PHP curl client stubs (packages/sdk-php)",
+    outputDir: (repoRoot) => `${repoRoot}/packages/sdk-php/src`,
+    generate: () => [
+        { path: "StationClient.php", contents: renderPhpClient() },
+        {
+            path: "../composer.json",
+            contents: JSON.stringify({
+                name: "radiotools/sdk",
+                description: "Generated RadioTools listener REST stubs",
+                type: "library",
+                license: "MIT",
+                require: { php: ">=8.2" },
+                autoload: {
+                    "psr-4": {
+                        "RadioTools\\Sdk\\": "src/",
+                    },
+                },
+            }, null, 2),
+        },
+        {
+            path: "../README.md",
+            contents: `# radiotools/sdk (PHP)
+
+Generated REST stubs. Regenerate: \`bun run --filter @rivi-software/radiotools-sdk-generator generate --target php\`.
+`,
+        },
+    ],
+};

package/dist/targets/python.d.ts

@@ -0,0 +1,2 @@
+import type { SdkTarget } from "../types";
+export declare const pythonTarget: SdkTarget;