@syra.fm/sdk 0.8.0 → 0.10.0

package/src/index.ts

@@ -18,18 +18,35 @@ export type {
   ArtworkSource,
   PodcastArtworkSource,
   EpisodeArtworkSource,
+  CreatePodcastInput,
+  UpdatePodcastInput,
+  CreateEpisodeDraftInput,
+  IngestEpisodeInput,
+  UploadPayload,
 } from './client';
 export {
   trackSummarySchema,
   podcastSummarySchema,
+  podcastVisibilitySchema,
   episodeSummarySchema,
+  episodeAudioSourceSchema,
+  episodeStatusSchema,
+  episodeDraftSchema,
+  episodeStreamSchema,
+  uploadedImageSchema,
   coverArtSizesSchema,
   coverArtVariantSchema,
 } from './schema';
 export type {
   TrackSummary,
   PodcastSummary,
+  PodcastVisibility,
   EpisodeSummary,
+  EpisodeAudioSource,
+  EpisodeStatus,
+  EpisodeDraft,
+  EpisodeStream,
+  UploadedImage,
   CoverArtSizes,
   CoverArtVariant,
   ArtworkSize,

package/src/live/components/CreateRoomSheet.tsx

@@ -97,7 +97,7 @@ export const CreateRoomSheet = forwardRef<CreateRoomSheetRef, CreateRoomSheetPro
     speakerPermission: isBroadcast ? 'invited' as const : speakerPermission,
     type: roomType,
     ownerType: selectedHouse ? 'house' as const : 'profile' as const,
-    houseId: selectedHouse?._id,
+    houseId: selectedHouse?.id,
     recordingEnabled,
   });
 
@@ -109,10 +109,10 @@ export const CreateRoomSheet = forwardRef<CreateRoomSheetRef, CreateRoomSheetPro
       const room = await roomsService.createRoom(buildCreatePayload());
 
       if (room) {
-        const started = await roomsService.startRoom(room._id);
+        const started = await roomsService.startRoom(room.id);
         onClose();
         if (started) {
-          joinLiveRoom(room._id);
+          joinLiveRoom(room.id);
         } else {
           toast.error('Room created but failed to start');
         }
@@ -317,10 +317,10 @@ export const CreateRoomSheet = forwardRef<CreateRoomSheetRef, CreateRoomSheetPro
               horizontal
               showsHorizontalScrollIndicator={false}
               data={[null, ...houses]}
-              keyExtractor={(item) => item?._id ?? 'personal'}
+              keyExtractor={(item) => item?.id ?? 'personal'}
               contentContainerStyle={styles.chipList}
               renderItem={({ item }) => {
-                const selected = item === null ? !selectedHouse : selectedHouse?._id === item._id;
+                const selected = item === null ? !selectedHouse : selectedHouse?.id === item.id;
                 return (
                   <TouchableOpacity
                     style={[

package/src/live/components/RecordingsPanel.tsx

@@ -49,9 +49,9 @@ export function RecordingsPanel({ roomId, isHost, theme, onClose, onPlay }: Reco
   };
 
   const handlePlay = async (recording: Recording) => {
-    setPlayingId(recording._id);
+    setPlayingId(recording.id);
     try {
-      const result = await roomsService.getRecording(recording._id);
+      const result = await roomsService.getRecording(recording.id);
       if (result?.playbackUrl) {
         onPlay?.(result.playbackUrl, recording);
       } else {
@@ -66,10 +66,10 @@ export function RecordingsPanel({ roomId, isHost, theme, onClose, onPlay }: Reco
 
   const handleToggleAccess = async (recording: Recording) => {
     const newAccess = recording.access === 'public' ? 'participants' as const : 'public' as const;
-    const success = await roomsService.updateRecordingAccess(recording._id, newAccess);
+    const success = await roomsService.updateRecordingAccess(recording.id, newAccess);
     if (success) {
       setRecordings((prev) =>
-        prev.map((r) => r._id === recording._id ? { ...r, access: newAccess } : r)
+        prev.map((r) => r.id === recording.id ? { ...r, access: newAccess } : r)
       );
       toast.success(`Recording is now ${newAccess}`);
     } else {
@@ -78,9 +78,9 @@ export function RecordingsPanel({ roomId, isHost, theme, onClose, onPlay }: Reco
   };
 
   const handleDelete = async (recording: Recording) => {
-    const success = await roomsService.deleteRecording(recording._id);
+    const success = await roomsService.deleteRecording(recording.id);
     if (success) {
-      setRecordings((prev) => prev.filter((r) => r._id !== recording._id));
+      setRecordings((prev) => prev.filter((r) => r.id !== recording.id));
       toast.success('Recording deleted');
     } else {
       toast.error('Failed to delete recording');
@@ -110,7 +110,7 @@ export function RecordingsPanel({ roomId, isHost, theme, onClose, onPlay }: Reco
         ) : (
           recordings.map((recording) => (
             <View
-              key={recording._id}
+              key={recording.id}
               style={[styles.recordingCard, { backgroundColor: `${theme.colors.card}80`, borderColor: theme.colors.border }]}
             >
               <View style={styles.recordingHeader}>
@@ -144,10 +144,10 @@ export function RecordingsPanel({ roomId, isHost, theme, onClose, onPlay }: Reco
 
                 <TouchableOpacity
                   onPress={() => handlePlay(recording)}
-                  disabled={playingId === recording._id}
+                  disabled={playingId === recording.id}
                   style={[styles.playButton, { backgroundColor: theme.colors.primary }]}
                 >
-                  {playingId === recording._id ? (
+                  {playingId === recording.id ? (
                     <ActivityIndicator size="small" color="#FFFFFF" />
                   ) : (
                     <MaterialCommunityIcons name="play" size={22} color="#FFFFFF" />

package/src/live/components/RoomCard.tsx

@@ -80,7 +80,7 @@ const ACTION_HIT_SLOP = { top: 8, bottom: 8, left: 8, right: 8 };
 
 interface RoomCardProps {
   room: {
-    _id: string;
+    id: string;
     title: string;
     status: 'scheduled' | 'live' | 'ended';
     type?: 'talk' | 'stage' | 'broadcast';

package/src/live/services/spaceSocketService.ts

@@ -26,7 +26,7 @@ export class RoomSocketService {
       this.socket = null;
     }
 
-    const baseUrl = this.socketUrl || 'ws://localhost:3000';
+    const baseUrl = this.socketUrl || 'ws://localhost:4120';
 
     this.socket = io(`${baseUrl}/rooms`, {
       transports: ['websocket', 'polling'],

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>;