@syra.fm/sdk 0.8.0 → 0.10.0

package/lib/typescript/module/schema.d.ts

@@ -120,6 +120,12 @@ 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 declare const podcastVisibilitySchema: z.ZodEnum<{
+    private: "private";
+    unlisted: "unlisted";
+    public: "public";
+}>;
+export type PodcastVisibility = z.infer<typeof podcastVisibilitySchema>;
 export declare const podcastSummarySchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -165,6 +171,12 @@ export declare const podcastSummarySchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     imageSourceUrl: z.ZodOptional<z.ZodString>;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        private: "private";
+        unlisted: "unlisted";
+        public: "public";
+    }>>;
+    aiGenerated: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type PodcastSummary = z.infer<typeof podcastSummarySchema>;
 /**
@@ -172,12 +184,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
@@ -185,16 +213,57 @@ 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 declare const episodeAudioSourceSchema: z.ZodObject<{
+    url: z.ZodString;
+    format: z.ZodOptional<z.ZodString>;
+    bitrate: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+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 declare const episodeStatusSchema: z.ZodEnum<{
+    ready: "ready";
+    processing: "processing";
+    failed: "failed";
+    unavailable: "unavailable";
+}>;
+export type EpisodeStatus = z.infer<typeof episodeStatusSchema>;
 export declare const episodeSummarySchema: z.ZodObject<{
     id: z.ZodString;
     podcastId: z.ZodString;
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
-    enclosureUrl: z.ZodString;
+    enclosureUrl: z.ZodOptional<z.ZodString>;
     enclosureType: z.ZodOptional<z.ZodString>;
     enclosureLength: z.ZodOptional<z.ZodNumber>;
+    audioSource: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        format: z.ZodOptional<z.ZodString>;
+        bitrate: z.ZodOptional<z.ZodNumber>;
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
     duration: z.ZodOptional<z.ZodNumber>;
     pubDate: z.ZodOptional<z.ZodString>;
+    season: z.ZodOptional<z.ZodNumber>;
+    episodeNumber: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodEnum<{
+        ready: "ready";
+        processing: "processing";
+        failed: "failed";
+        unavailable: "unavailable";
+    }>>;
+    aiGenerated: z.ZodOptional<z.ZodBoolean>;
     image: z.ZodOptional<z.ZodString>;
     imageSizes: z.ZodOptional<z.ZodObject<{
         small: z.ZodOptional<z.ZodObject<{
@@ -237,4 +306,25 @@ export declare const episodeSummarySchema: z.ZodObject<{
     imageSourceUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type EpisodeSummary = z.infer<typeof episodeSummarySchema>;
+/** What `createEpisodeDraft` hands back: the episode to fill, and the capability to fill it. */
+export declare const episodeDraftSchema: z.ZodObject<{
+    episodeId: z.ZodString;
+    ingestTicket: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strip>;
+export type EpisodeDraft = z.infer<typeof episodeDraftSchema>;
+/** What `getEpisodeStream` hands back: a tokenized HLS URL with its own deadline. */
+export declare const episodeStreamSchema: z.ZodObject<{
+    url: z.ZodString;
+    type: z.ZodString;
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EpisodeStream = z.infer<typeof episodeStreamSchema>;
+/** What the image upload endpoint hands back. */
+export declare const uploadedImageSchema: z.ZodObject<{
+    id: z.ZodString;
+    primaryColor: z.ZodOptional<z.ZodString>;
+    secondaryColor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type UploadedImage = z.infer<typeof uploadedImageSchema>;
 //# sourceMappingURL=schema.d.ts.map

package/lib/typescript/module/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH,mFAAmF;AACnF,eAAO,MAAM,qBAAqB;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,yBAAyB;AACzB,MAAM,MAAM,WAAW,GAAG,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQ/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAa/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH,mFAAmF;AACnF,eAAO,MAAM,qBAAqB;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,yBAAyB;AACzB,MAAM,MAAM,WAAW,GAAG,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB;;;;EAA4C,CAAC;AACjF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiB/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;;iBAKnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;EAA2D,CAAC;AAC5F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqB/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,gGAAgG;AAChG,eAAO,MAAM,kBAAkB;;;;iBAI7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,qFAAqF;AACrF,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,iDAAiD;AACjD,eAAO,MAAM,mBAAmB;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syra.fm/sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Syra SDK — headless, isomorphic catalog client (Node/React-free, public reads + 30s previews) that also ships the Syra live-rooms engine (audio rooms over LiveKit) on React Native and web.",
   "source": "src/index.ts",
   "main": "lib/commonjs/index.js",
@@ -34,7 +34,9 @@
   },
   "files": [
     "src",
-    "lib"
+    "lib",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts"
   ],
   "keywords": [
     "syra",
@@ -90,7 +92,7 @@
     "react-native": "^0.85.3",
     "react-native-reanimated": "^4.3.1",
     "react-native-safe-area-context": "^5.7.0",
-    "@oxyhq/services": "^22.1.0",
+    "@oxyhq/services": "^22.13.1 || ^23.0.0 || ^24.0.0 || ^25.0.0 || ^26.0.0 || ^27.0.0",
     "livekit-client": "^2.20.0",
     "@livekit/react-native": "^2.11.1",
     "expo-audio": "~56.0.12",
@@ -151,7 +153,7 @@
     "react-native": "^0.85.3",
     "react-native-reanimated": "^4.3.1",
     "react-native-safe-area-context": "^5.7.0",
-    "@oxyhq/services": "^22.1.0",
+    "@oxyhq/services": "^27.1.1",
     "livekit-client": "^2.20.0",
     "@livekit/react-native": "^2.11.1",
     "expo-audio": "~56.0.12",

package/src/client.ts

@@ -2,9 +2,16 @@ import {
   trackSummarySchema,
   podcastSummarySchema,
   episodeSummarySchema,
+  episodeDraftSchema,
+  episodeStreamSchema,
+  uploadedImageSchema,
   type TrackSummary,
   type PodcastSummary,
   type EpisodeSummary,
+  type EpisodeDraft,
+  type EpisodeStream,
+  type UploadedImage,
+  type PodcastVisibility,
   type CoverArtSizes,
   type ArtworkSize,
 } from './schema';
@@ -28,9 +35,24 @@ export interface SyraClientOptions {
   /**
    * `fetch` implementation. Defaults to the global `fetch` (Node 18+, browsers,
    * React Native). Inject one (e.g. `node-fetch`) when no global is available.
-   * This is the seam where an authenticated transport can be layered in later.
    */
   fetch?: typeof fetch;
+  /**
+   * Supplies the caller's Oxy access token. Called BEFORE EVERY REQUEST, never
+   * cached here, because an access token is short-lived and the host
+   * application is the only thing that knows when it was refreshed — an SDK
+   * holding its own copy is an SDK that starts sending an expired one.
+   *
+   * Returning `null`/`undefined` means "no session right now", which is a normal
+   * state and not an error: every PUBLIC read below still works without a token,
+   * exactly as it did before this existed. Only the authenticated methods refuse,
+   * and they say so by name.
+   *
+   * The token IS sent on public reads when it is available, which is
+   * deliberate — it is what lets an owner see their own private show and their
+   * own unpublished episodes through the same methods everyone else uses.
+   */
+  getAccessToken?: () => string | null | undefined | Promise<string | null | undefined>;
 }
 
 export interface SearchTracksOptions {
@@ -94,6 +116,86 @@ export interface EpisodeArtworkSource {
   imageSourceUrl?: string | null;
 }
 
+/** The fields `createPodcast` accepts. Mirrors `POST /api/podcasts`. */
+export interface CreatePodcastInput {
+  title: string;
+  description?: string;
+  author?: string;
+  /** An image id from {@link SyraClient.uploadPodcastImage}, not a URL. */
+  image?: string;
+  language?: string;
+  categories?: string[];
+  explicit?: boolean;
+  link?: string;
+  type?: 'episodic' | 'serial';
+  visibility?: PodcastVisibility;
+  /** The Alia series this show was generated from; records `provider: 'alia'` provenance. */
+  aliaSeriesId?: string;
+  /** Disclosure. Independent of {@link CreatePodcastInput.aliaSeriesId} — neither implies the other. */
+  aiGenerated?: boolean;
+  /** Hosts & Guests as Oxy user ids. Validated server-side; free text is refused. */
+  hosts?: string[];
+  guests?: string[];
+}
+
+/** The fields `updatePodcast` accepts. Every one is optional; omitted means unchanged. */
+export interface UpdatePodcastInput {
+  title?: string;
+  description?: string;
+  author?: string;
+  image?: string;
+  language?: string;
+  categories?: string[];
+  explicit?: boolean;
+  link?: string;
+  type?: 'episodic' | 'serial';
+  visibility?: PodcastVisibility;
+  aiGenerated?: boolean;
+}
+
+/** The metadata `createEpisodeDraft` accepts — everything except the audio. */
+export interface CreateEpisodeDraftInput {
+  title: string;
+  description?: string;
+  summary?: string;
+  season?: number;
+  episodeNumber?: number;
+  episodeType?: 'full' | 'trailer' | 'bonus';
+  explicit?: boolean;
+  aiGenerated?: boolean;
+  hosts?: string[];
+  guests?: string[];
+}
+
+/**
+ * The metadata the ingest step may set.
+ *
+ * Deliberately SMALLER than {@link CreateEpisodeDraftInput}, and it is not an
+ * oversight: the ticket is redeemed by a process with no user session, so the
+ * server accepts only what such a process can know by having produced the audio.
+ * Title, artwork, `explicit`, `episodeType`, credits and the AI disclosure were
+ * fixed at draft time by the authenticated user and are refused here.
+ */
+export interface IngestEpisodeInput {
+  duration?: number;
+  season?: number;
+  episodeNumber?: number;
+  description?: string;
+  summary?: string;
+}
+
+/**
+ * An audio or image payload, in the shapes the three supported runtimes give you.
+ *
+ * `Blob`/`File` covers browsers and Node 18+. React Native's `FormData` accepts
+ * a `{ uri, name, type }` descriptor instead, which is not a `Blob` at all — it
+ * is named here so an RN caller does not have to cast, and so this SDK never has
+ * to import anything from React Native to support it.
+ */
+export type UploadPayload =
+  | Blob
+  | { uri: string; name?: string; type?: string };
+
 export interface SyraClient {
   /**
    * Search the public catalog for tracks. Returns one paginated page: rows are
@@ -156,6 +258,81 @@ export interface SyraClient {
    * external artwork URL. Returns `undefined` when no artwork can be derived.
    */
   episodeImageUrl(source: EpisodeArtworkSource, size?: ArtworkSize): string | undefined;
+  /**
+   * Resolve an episode's PLAYABLE audio URL, whichever kind of episode it is.
+   *
+   * An RSS-mirrored episode carries an absolute `enclosureUrl`; a Syra-hosted one
+   * carries `audioSource.url`, a path on the API. This is the one place that
+   * knows the difference, so no consumer has to.
+   *
+   * `undefined` when the episode has no audio yet — a drafted episode awaiting
+   * ingest is a real, listable episode with nothing to play, and answering with
+   * a broken URL would be worse than answering with nothing.
+   */
+  episodeAudioUrl(episode: {
+    enclosureUrl?: string | null;
+    audioSource?: { url?: string | null } | null;
+  }): string | undefined;
+
+  // ── Authenticated ──────────────────────────────────────────────────────────
+  //
+  // Every method below needs `getAccessToken` to return a token; without one they
+  // throw `SyraApiError(401)` from the CLIENT rather than making a request that
+  // was never going to be accepted.
+
+  /** `GET /api/podcasts/mine` — every show the caller owns, in every state. */
+  listMyPodcasts(): Promise<PodcastSummary[]>;
+  /** `POST /api/podcasts` — create a Syra-hosted show. */
+  createPodcast(input: CreatePodcastInput): Promise<PodcastSummary>;
+  /** `PATCH /api/podcasts/:id` — edit a Syra-hosted show you own. */
+  updatePodcast(podcastId: string, input: UpdatePodcastInput): Promise<PodcastSummary>;
+  /**
+   * Change who may see a show. A named affordance over
+   * {@link SyraClient.updatePodcast}, because it is the one field with
+   * consequences a caller should not discover by reading a diff: making a show
+   * `private` withdraws it from every listing AND stops its episodes being
+   * transcoded, and publishing it again enqueues the transcodes that were
+   * deferred.
+   */
+  setPodcastVisibility(podcastId: string, visibility: PodcastVisibility): Promise<PodcastSummary>;
+  /**
+   * `POST /api/images/upload` — store cover art and get the image id back.
+   *
+   * The id is what {@link CreatePodcastInput.image} wants; a URL is not accepted
+   * there, because the API re-hosts artwork rather than hotlinking it.
+   */
+  uploadPodcastImage(image: UploadPayload, filename?: string): Promise<UploadedImage>;
+  /**
+   * `POST /api/podcasts/:id/episodes/draft` — reserve an episode now and get a
+   * single-use ticket to attach its audio later, from a process with no session.
+   *
+   * The returned ticket is a bearer capability with a deadline: it is good for
+   * ONE redemption against THIS episode, and it stops working if the show
+   * changes hands. Treat it as a secret.
+   */
+  createEpisodeDraft(podcastId: string, input: CreateEpisodeDraftInput): Promise<EpisodeDraft>;
+  /**
+   * `POST /api/podcasts/episodes/:id/ingest` — redeem a draft's ticket by
+   * attaching the audio.
+   *
+   * Takes the whole {@link EpisodeDraft} rather than a loose id and token, so the
+   * two cannot be paired up wrongly by a caller holding several drafts.
+   *
+   * Authenticated by the TICKET, not by the session — this is the one method here
+   * that works with no `getAccessToken` at all, which is the entire point of it.
+   */
+  ingestEpisode(
+    draft: Pick<EpisodeDraft, 'episodeId' | 'ingestTicket'>,
+    audio: UploadPayload,
+    input?: IngestEpisodeInput,
+    filename?: string,
+  ): Promise<EpisodeSummary>;
+  /**
+   * `GET /api/podcasts/episodes/:id/stream` — a tokenized HLS URL for a
+   * Syra-hosted episode. Requires a session: the URL it returns embeds a stream
+   * token minted for the caller.
+   */
+  getEpisodeStream(episodeId: string): Promise<EpisodeStream>;
 }
 
 /** Order used to pick the best available artwork variant when none is named. */
@@ -232,20 +409,130 @@ export function createSyraClient(options: SyraClientOptions = {}): SyraClient {
     );
   }
 
-  async function getJson(path: string): Promise<unknown> {
-    const doFetch = resolveFetch();
-    const response = await doFetch(`${baseURL}${path}`, {
-      headers: { Accept: 'application/json' },
-    });
-    if (!response.ok) {
+  /**
+   * The caller's token for THIS request, or `undefined`.
+   *
+   * Asked every time rather than once at construction: an access token is
+   * short-lived, and the host application is the only thing that knows when it
+   * was refreshed.
+   */
+  async function currentToken(): Promise<string | undefined> {
+    if (!options.getAccessToken) return undefined;
+    const token = await options.getAccessToken();
+    return typeof token === 'string' && token.length > 0 ? token : undefined;
+  }
+
+  /**
+   * The token, or a refusal — for the methods that cannot work without one.
+   *
+   * Thrown from the CLIENT rather than sent and rejected, so a consumer with no
+   * session gets a message naming the method instead of a bare 401 from a
+   * request that was never going to be accepted.
+   */
+  async function requireToken(method: string): Promise<string> {
+    const token = await currentToken();
+    if (!token) {
       throw new SyraApiError(
-        response.status,
-        `Syra API request failed: ${response.status} ${response.statusText} (${path})`,
+        401,
+        `@syra.fm/sdk: ${method}() needs a signed-in caller. Pass \`getAccessToken\` to ` +
+          'createSyraClient, and make sure it returns a token for the current session.',
       );
     }
+    return token;
+  }
+
+  /** Raise the API's own error, preferring the message it sent over the status text. */
+  async function raiseFor(response: Response, path: string): Promise<never> {
+    let detail = `${response.status} ${response.statusText}`;
+    try {
+      const body: unknown = await response.json();
+      if (body && typeof body === 'object' && 'error' in body && typeof body.error === 'string') {
+        detail = `${response.status} ${body.error}`;
+      }
+    } catch {
+      // A non-JSON error body is not itself an error worth reporting; the status
+      // is what the caller acts on.
+    }
+    throw new SyraApiError(response.status, `Syra API request failed: ${detail} (${path})`);
+  }
+
+  interface RequestInit_ {
+    method?: string;
+    body?: BodyInit;
+    /** Extra headers. `Authorization` is added here, never by a caller. */
+    headers?: Record<string, string>;
+    /** Refuse before sending when there is no session. The value is the method name. */
+    requires?: string;
+    /**
+     * Never attach the session token, even when one is available.
+     *
+     * For a request that carries its OWN credential — the ingest ticket. Sending
+     * both would leave the server's answer ambiguous about which one authorized
+     * the write, and would mean a worker that happens to hold a user token
+     * behaves differently from one that does not. Exactly one credential per
+     * request.
+     */
+    anonymous?: boolean;
+  }
+
+  async function request(path: string, init: RequestInit_ = {}): Promise<unknown> {
+    const doFetch = resolveFetch();
+    const headers: Record<string, string> = { Accept: 'application/json', ...init.headers };
+
+    if (init.requires) {
+      headers.Authorization = `Bearer ${await requireToken(init.requires)}`;
+    } else if (!init.anonymous) {
+      // Sent when available even on public reads — it is what lets an owner see
+      // their own private show through the same method everyone else calls.
+      const token = await currentToken();
+      if (token) headers.Authorization = `Bearer ${token}`;
+    }
+
+    const response = await doFetch(`${baseURL}${path}`, {
+      method: init.method ?? 'GET',
+      headers,
+      ...(init.body === undefined ? {} : { body: init.body }),
+    });
+    if (!response.ok) return raiseFor(response, path);
     return response.json();
   }
 
+  async function getJson(path: string): Promise<unknown> {
+    return request(path);
+  }
+
+  async function postJson(path: string, body: unknown, requires: string): Promise<unknown> {
+    return request(path, {
+      method: 'POST',
+      requires,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Append an upload to a `FormData`, in whichever shape the runtime gave us.
+   *
+   * The RN `{ uri, name, type }` descriptor is not a `Blob` and the DOM
+   * `FormData.append` signature does not admit it, so it goes through one cast
+   * confined to this function — rather than every call site, or a `declare
+   * module` shim that would shadow the real DOM types in every consumer.
+   */
+  function appendUpload(form: FormData, field: string, payload: UploadPayload, filename?: string): void {
+    if (typeof Blob !== 'undefined' && payload instanceof Blob) {
+      form.append(field, payload, filename);
+      return;
+    }
+    const descriptor = payload as { uri: string; name?: string; type?: string };
+    const name = filename ?? descriptor.name ?? field;
+    form.append(field, descriptor as unknown as Blob, name);
+  }
+
+  /** Drop `undefined` fields so a partial input never sends `"key": null`. */
+  function defined(input: Record<string, unknown>): Record<string, unknown> {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+  }
+
   function resolveImageRef(ref: string | null | undefined): string | undefined {
     if (!ref) {
       return undefined;
@@ -418,7 +705,15 @@ export function createSyraClient(options: SyraClientOptions = {}): SyraClient {
 
       const items: EpisodeSummary[] = [];
       for (const raw of rawEpisodes) {
-        // A single malformed episode row must not fail the whole listing.
+        /**
+         * A single malformed episode row must not fail the whole listing — but
+         * "has no enclosure" is no longer malformed. It used to be, and that is
+         * what made every SYRA-HOSTED episode disappear from this method: their
+         * audio is `audioSource.url`, not an enclosure. The schema now validates
+         * IDENTITY and leaves playability to `episodeAudioUrl`, which is also
+         * the only honest answer for a drafted episode whose audio has not
+         * arrived yet.
+         */
         const parsed = episodeSummarySchema.safeParse(raw);
         if (parsed.success) {
           items.push(parsed.data);
@@ -469,5 +764,118 @@ export function createSyraClient(options: SyraClientOptions = {}): SyraClient {
 
       return resolveImageRef(source.imageSourceUrl);
     },
+
+    episodeAudioUrl(episode) {
+      // An RSS mirror's enclosure is already absolute and points at somebody
+      // else's host, so it is returned untouched.
+      if (episode.enclosureUrl && /^https?:\/\//i.test(episode.enclosureUrl)) {
+        return episode.enclosureUrl;
+      }
+      const sourceUrl = episode.audioSource?.url;
+      if (sourceUrl) {
+        return /^https?:\/\//i.test(sourceUrl) ? sourceUrl : `${baseURL}${sourceUrl}`;
+      }
+      // A relative enclosure is unusual but representable; resolve it the same way.
+      if (episode.enclosureUrl) return `${baseURL}${episode.enclosureUrl}`;
+      return undefined;
+    },
+
+    async listMyPodcasts() {
+      const json = (await request('/api/podcasts/mine', {
+        requires: 'listMyPodcasts',
+      })) as PodcastSearchResponseShape;
+      const rows = Array.isArray(json?.data) ? json.data : [];
+
+      const items: PodcastSummary[] = [];
+      for (const raw of rows) {
+        const parsed = podcastSummarySchema.safeParse(raw);
+        if (parsed.success) items.push(parsed.data);
+      }
+      return items;
+    },
+
+    async createPodcast(input) {
+      const json = (await postJson(
+        '/api/podcasts',
+        defined({ ...input }),
+        'createPodcast',
+      )) as { data?: unknown };
+      return podcastSummarySchema.parse(json?.data);
+    },
+
+    async updatePodcast(podcastId, input) {
+      const json = (await request(`/api/podcasts/${encodeURIComponent(podcastId)}`, {
+        method: 'PATCH',
+        requires: 'updatePodcast',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(defined({ ...input })),
+      })) as { data?: unknown };
+      return podcastSummarySchema.parse(json?.data);
+    },
+
+    async setPodcastVisibility(podcastId, visibility) {
+      return this.updatePodcast(podcastId, { visibility });
+    },
+
+    async uploadPodcastImage(image, filename) {
+      const form = new FormData();
+      // `image` is the field name `POST /api/images/upload` reads.
+      appendUpload(form, 'image', image, filename);
+
+      // No `Content-Type`: the runtime sets it, INCLUDING the multipart boundary,
+      // which cannot be written by hand. Setting it here produces a body the
+      // server cannot parse.
+      const json = (await request('/api/images/upload', {
+        method: 'POST',
+        requires: 'uploadPodcastImage',
+        body: form,
+      })) as unknown;
+      return uploadedImageSchema.parse(json);
+    },
+
+    async createEpisodeDraft(podcastId, input) {
+      const json = (await postJson(
+        `/api/podcasts/${encodeURIComponent(podcastId)}/episodes/draft`,
+        defined({ ...input }),
+        'createEpisodeDraft',
+      )) as { data?: unknown };
+      return episodeDraftSchema.parse(json?.data);
+    },
+
+    async ingestEpisode(draft, audio, input = {}, filename) {
+      const form = new FormData();
+      // `audioFile` is the field name the ingest endpoint reads.
+      appendUpload(form, 'audioFile', audio, filename ?? 'episode.mp3');
+      for (const [key, value] of Object.entries(defined({ ...input }))) {
+        form.append(key, String(value));
+      }
+
+      /**
+       * `anonymous`, and it is load-bearing rather than tidy: this request is
+       * authenticated by the TICKET alone, which is the whole reason the
+       * draft/ingest pair exists. Without it a worker that HAPPENS to hold a user
+       * token would send both credentials — behaving differently from one that
+       * does not, and leaving the server's answer ambiguous about which
+       * authorized the write. Caught by a test, not by review.
+       */
+      const json = (await request(
+        `/api/podcasts/episodes/${encodeURIComponent(draft.episodeId)}/ingest`,
+        {
+          method: 'POST',
+          anonymous: true,
+          headers: { 'X-Ingest-Ticket': draft.ingestTicket },
+          body: form,
+        },
+      )) as { data?: unknown };
+      return episodeSummarySchema.parse(json?.data);
+    },
+
+    async getEpisodeStream(episodeId) {
+      const json = await request(
+        `/api/podcasts/episodes/${encodeURIComponent(episodeId)}/stream`,
+        { requires: 'getEpisodeStream' },
+      );
+      return episodeStreamSchema.parse(json);
+    },
   };
 }