@syra.fm/sdk 0.9.0 → 0.11.0

package/src/live/validation.ts

@@ -1,5 +1,34 @@
 import { z } from 'zod';
 
+/**
+ * Accept a document whose identity arrives as `_id` and present it as `id`.
+ *
+ * The PostgreSQL migration made `id` REQUIRED on the four schemas below, which is
+ * correct against the ported backend — `_id` left the wire contract there. But the
+ * frontend deploys on its own path (`deploy-frontends.yml`, on `packages/frontend`
+ * and `packages/shared-types`) while the backend deploy is gated, so a merge to
+ * `main` ships the client half ALONE. It did: `GET /rooms` still answers `_id`,
+ * every room failed `ZRoom`, and `validateRooms` DROPS what it cannot parse — so
+ * the Live screen went empty in production with only a `console.warn` to say so.
+ *
+ * Normalising here rather than teaching call sites to read `room.id ?? room._id`
+ * is the architecture this repo already states: parse once at the API boundary and
+ * return typed data. One place, no UI knows, and it is correct against BOTH
+ * backends — so the cutover needs no coordinated client flip, which is the failure
+ * this comment exists because of.
+ *
+ * It can be deleted once no deployed Syra backend serves `_id`. Nothing breaks if
+ * it outlives that: a payload carrying only `id` passes through untouched.
+ */
+function withMongoIdFallback<T extends z.ZodTypeAny>(schema: T) {
+  return z.preprocess((value) => {
+    if (value === null || typeof value !== 'object') return value;
+    const doc = value as Record<string, unknown>;
+    if (typeof doc['id'] === 'string' || typeof doc['_id'] !== 'string') return value;
+    return { ...doc, id: doc['_id'] };
+  }, schema);
+}
+
 // --- Podcast queue ---
 
 /**
@@ -17,9 +46,8 @@ export type PodcastQueueItem = z.infer<typeof ZPodcastQueueItem>;
 
 // --- Room (replaces Space) ---
 
-export const ZRoom = z.object({
-  _id: z.string(),
-  id: z.string().optional(),
+export const ZRoom = withMongoIdFallback(z.object({
+  id: z.string(),
   title: z.string(),
   description: z.string().nullish(),
 
@@ -78,7 +106,7 @@ export const ZRoom = z.object({
   recordingEgressId: z.string().nullish(),
 
   createdAt: z.string(),
-}).passthrough();
+}).passthrough());
 
 export type Room = z.infer<typeof ZRoom>;
 
@@ -117,9 +145,8 @@ export const ZHouseVisibility = z.object({
 
 export type HouseVisibility = z.infer<typeof ZHouseVisibility>;
 
-export const ZHouse = z.object({
-  _id: z.string(),
-  id: z.string().optional(),
+export const ZHouse = withMongoIdFallback(z.object({
+  id: z.string(),
   name: z.string(),
   description: z.string().optional(),
   avatar: z.string().optional().nullable(),
@@ -132,7 +159,7 @@ export const ZHouse = z.object({
   visibility: ZHouseVisibility.default({ discovery: 'listed', rooms: 'anyone', join: 'invite' }),
   tags: z.array(z.string()).optional(),
   createdAt: z.string(),
-}).passthrough();
+}).passthrough());
 
 export type House = z.infer<typeof ZHouse>;
 
@@ -167,9 +194,8 @@ export const ZSeriesEpisode = z.object({
 
 export type SeriesEpisode = z.infer<typeof ZSeriesEpisode>;
 
-export const ZSeries = z.object({
-  _id: z.string(),
-  id: z.string().optional(),
+export const ZSeries = withMongoIdFallback(z.object({
+  id: z.string(),
   title: z.string(),
   description: z.string().optional(),
   coverImage: z.string().optional().nullable(),
@@ -181,14 +207,14 @@ export const ZSeries = z.object({
   nextEpisodeNumber: z.number().default(1),
   isActive: z.boolean().default(true),
   createdAt: z.string(),
-}).passthrough();
+}).passthrough());
 
 export type Series = z.infer<typeof ZSeries>;
 
 // --- Recording ---
 
-export const ZRecording = z.object({
-  _id: z.string(),
+export const ZRecording = withMongoIdFallback(z.object({
+  id: z.string(),
   roomId: z.string(),
   roomTitle: z.string(),
   host: z.string(),
@@ -203,7 +229,7 @@ export const ZRecording = z.object({
   participantIds: z.array(z.string()).default([]),
   expiresAt: z.string(),
   createdAt: z.string(),
-}).passthrough();
+}).passthrough());
 
 export type Recording = z.infer<typeof ZRecording>;
 

package/src/schema.ts

@@ -59,6 +59,9 @@ export type TrackSummary = z.infer<typeof trackSummarySchema>;
  * variant `url` is `/api/images/:id`); `imageSourceUrl` keeps the original
  * external artwork URL as an absolute fallback when re-hosting has not run yet.
  */
+export const podcastVisibilitySchema = z.enum(['private', 'unlisted', 'public']);
+export type PodcastVisibility = z.infer<typeof podcastVisibilitySchema>;
+
 export const podcastSummarySchema = z.object({
   id: z.string(),
   title: z.string(),
@@ -67,6 +70,15 @@ export const podcastSummarySchema = z.object({
   image: z.string().optional(),
   imageSizes: coverArtSizesSchema.optional(),
   imageSourceUrl: z.string().optional(),
+  /**
+   * Who may see this show. OPTIONAL here although the API always sends it: a
+   * published SDK is installed against whatever version of the API a consumer
+   * happens to be pointing at, and requiring a field the previous release did
+   * not send would make this SDK reject every response from it.
+   */
+  visibility: podcastVisibilitySchema.optional(),
+  /** Disclosure: the show's content was machine-generated. Optional, same reason. */
+  aiGenerated: z.boolean().optional(),
 });
 export type PodcastSummary = z.infer<typeof podcastSummarySchema>;
 
@@ -75,12 +87,28 @@ export type PodcastSummary = z.infer<typeof podcastSummarySchema>;
  * (`GET /api/podcasts/:id/episodes`, `GET /api/episodes/:id`) — just enough to
  * list an episode and stream its audio.
  *
- * `enclosureUrl` is the direct audio file URL (e.g.
- * `https://api.fastcast.ai/audio/<guid>.mp3`) and is REQUIRED: an episode with
- * no enclosure is unplayable, so a row missing it is treated as malformed and
- * dropped rather than surfaced as a dead entry. `enclosureType` /
- * `enclosureLength` describe that file (MIME type and byte length); `duration`
- * is the runtime in seconds and `pubDate` the ISO publish timestamp.
+ * ## `enclosureUrl` is OPTIONAL, and that is a bug fix rather than a loosening
+ *
+ * It used to be required, on the reasoning that "an episode with no enclosure is
+ * unplayable, so a row missing it is malformed". That reasoning holds only for
+ * RSS-mirrored episodes. A SYRA-HOSTED episode — everything created through
+ * `createPodcast`/`uploadEpisode`/the ingest ticket — has no enclosure at all:
+ * its audio lives at `audioSource.url`, a path on the Syra API. So the required
+ * field made this SDK silently DROP every Syra-hosted episode from
+ * `getPodcastEpisodes` and throw on one from `getEpisode` — the entire
+ * first-party catalogue, invisible, with no error to notice.
+ *
+ * The two are alternatives, not a required field and an optional one:
+ *
+ *   enclosureUrl      an ABSOLUTE external URL (RSS mirror)
+ *   audioSource.url   a PATH on the Syra API (Syra-hosted)
+ *
+ * `SyraClient.episodeAudioUrl` is the one place that resolves either into
+ * something playable, so no consumer has to know which kind it holds.
+ *
+ * `enclosureType` / `enclosureLength` describe the external file (MIME type and
+ * byte length); `duration` is the runtime in seconds and `pubDate` the ISO
+ * publish timestamp.
  *
  * Artwork mirrors the podcast SHOW: `image` is the re-hosted Syra image id
  * (resolved via `/api/images/:id`); `imageSizes` is the multi-resolution variant
@@ -88,18 +116,73 @@ export type PodcastSummary = z.infer<typeof podcastSummarySchema>;
  * original external artwork URL as an absolute fallback when re-hosting has not
  * run yet.
  */
+/**
+ * Where a Syra-hosted episode's audio actually is.
+ *
+ * `url` is a PATH on the Syra API (`/api/podcasts/episodes/:id/audio`), not an
+ * absolute URL — resolve it with `SyraClient.episodeAudioUrl` rather than
+ * handing it to a player directly.
+ */
+export const episodeAudioSourceSchema = z.object({
+  url: z.string(),
+  format: z.string().optional(),
+  bitrate: z.number().optional(),
+  duration: z.number().optional(),
+});
+export type EpisodeAudioSource = z.infer<typeof episodeAudioSourceSchema>;
+
+/**
+ * An episode's processing state. `ready` is playable; `processing` is an episode
+ * whose audio is still being packaged (including one drafted but not yet
+ * ingested), and only its OWNER is shown those.
+ */
+export const episodeStatusSchema = z.enum(['ready', 'processing', 'failed', 'unavailable']);
+export type EpisodeStatus = z.infer<typeof episodeStatusSchema>;
+
 export const episodeSummarySchema = z.object({
   id: z.string(),
   podcastId: z.string(),
   title: z.string(),
   description: z.string().optional(),
-  enclosureUrl: z.string(),
+  /** ABSOLUTE, and present only for RSS-mirrored episodes — see the note above. */
+  enclosureUrl: z.string().optional(),
   enclosureType: z.string().optional(),
   enclosureLength: z.number().optional(),
+  /** A PATH on the Syra API, present for Syra-hosted episodes. */
+  audioSource: episodeAudioSourceSchema.optional(),
   duration: z.number().optional(),
   pubDate: z.string().optional(),
+  season: z.number().optional(),
+  episodeNumber: z.number().optional(),
+  status: episodeStatusSchema.optional(),
+  /** Disclosure: this episode's content was machine-generated. */
+  aiGenerated: z.boolean().optional(),
   image: z.string().optional(),
   imageSizes: coverArtSizesSchema.optional(),
   imageSourceUrl: z.string().optional(),
 });
 export type EpisodeSummary = z.infer<typeof episodeSummarySchema>;
+
+/** What `createEpisodeDraft` hands back: the episode to fill, and the capability to fill it. */
+export const episodeDraftSchema = z.object({
+  episodeId: z.string(),
+  ingestTicket: z.string(),
+  expiresAt: z.string(),
+});
+export type EpisodeDraft = z.infer<typeof episodeDraftSchema>;
+
+/** What `getEpisodeStream` hands back: a tokenized HLS URL with its own deadline. */
+export const episodeStreamSchema = z.object({
+  url: z.string(),
+  type: z.string(),
+  expiresAt: z.string().optional(),
+});
+export type EpisodeStream = z.infer<typeof episodeStreamSchema>;
+
+/** What the image upload endpoint hands back. */
+export const uploadedImageSchema = z.object({
+  id: z.string(),
+  primaryColor: z.string().optional(),
+  secondaryColor: z.string().optional(),
+});
+export type UploadedImage = z.infer<typeof uploadedImageSchema>;