pocketcasts-api 0.1.0

package/src/index.ts

@@ -0,0 +1,14 @@
+export { PocketCasts, type PocketCastsOptions } from './client.js';
+export {
+  PocketCastsError,
+  PocketCastsAuthError,
+  PocketCastsAPIError,
+} from './errors.js';
+export type {
+  Podcast,
+  Episode,
+  SearchResult,
+  ListeningStats,
+  PlayingStatus,
+} from './types.js';
+export { PLAYING_STATUS_TO_API } from './types.js';

package/src/types.ts

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+
+// --- Playing Status ---
+// The API returns playing status as either:
+//   - a number: 0=unplayed, 1=not played (same as unplayed), 2=playing, 3=played
+//   - a string: "unplayed", "playing", "played"
+
+const PLAYING_STATUS_NUM_MAP: Record<number, PlayingStatus> = {
+  0: 'unplayed',
+  1: 'unplayed', // value 1 appears in the wild, treat as unplayed
+  2: 'playing',
+  3: 'played',
+};
+
+const PLAYING_STATUS_STRINGS = ['unplayed', 'playing', 'played'] as const;
+
+export const PlayingStatusSchema = z.union([
+  z.number().transform((n) => PLAYING_STATUS_NUM_MAP[n] ?? 'unplayed'),
+  z.enum(PLAYING_STATUS_STRINGS),
+]);
+
+export type PlayingStatus = 'unplayed' | 'playing' | 'played';
+
+export const PLAYING_STATUS_TO_API: Record<PlayingStatus, number> = {
+  unplayed: 0,
+  playing: 2,
+  played: 3,
+};
+
+// --- Podcast ---
+
+export const PodcastSchema = z
+  .looseObject({
+    uuid: z.string(),
+    title: z.string(),
+    author: z.string(),
+    description: z.string().default(''),
+    url: z.string(),
+    thumbnail_url: z.string().optional(),
+    language: z.string().optional(),
+    categories: z.array(z.string()).optional(),
+    media_type: z.string().optional(),
+    sort_order: z.number().optional(),
+  })
+  .transform(({ thumbnail_url, media_type, sort_order, ...rest }) => ({
+    ...rest,
+    thumbnailUrl: thumbnail_url,
+    mediaType: media_type,
+    sortOrder: sort_order,
+  }));
+
+export type Podcast = z.output<typeof PodcastSchema>;
+
+// --- Episode ---
+// The real API returns camelCase fields (podcastUuid, playingStatus, etc.)
+// We accept both camelCase and snake_case for flexibility.
+
+const boolOrNum = z
+  .union([z.boolean(), z.number().transform((n) => n === 1)])
+  .default(false);
+const stringOrNum = z
+  .union([z.number(), z.string().transform((s) => parseInt(s, 10) || 0)])
+  .optional();
+
+export const EpisodeSchema = z
+  .looseObject({
+    uuid: z.string(),
+    title: z.string(),
+    url: z.string().default(''),
+    // Accept both camelCase (real API) and snake_case
+    podcastUuid: z.string().optional(),
+    podcast_uuid: z.string().optional(),
+    podcastTitle: z.string().optional(),
+    podcast_title: z.string().optional(),
+    duration: z.number().default(0),
+    published: z.string().optional(),
+    publishedAt: z.string().optional(),
+    published_at: z.string().optional(),
+    fileType: z.string().optional(),
+    file_type: z.string().optional(),
+    size: stringOrNum,
+    playingStatus: PlayingStatusSchema.optional(),
+    playing_status: PlayingStatusSchema.optional(),
+    playedUpTo: z.number().optional(),
+    played_up_to: z.number().optional(),
+    starred: boolOrNum,
+    isDeleted: boolOrNum,
+    is_deleted: boolOrNum,
+    isVideo: boolOrNum,
+    is_video: boolOrNum,
+  })
+  .transform((e) => ({
+    ...e,
+    podcastUuid: e.podcastUuid ?? e.podcast_uuid ?? '',
+    podcastTitle: e.podcastTitle ?? e.podcast_title,
+    publishedAt: e.publishedAt || e.published_at || e.published || '',
+    fileType: e.fileType ?? e.file_type,
+    playingStatus: e.playingStatus ?? e.playing_status ?? ('unplayed' as const),
+    playedUpTo: e.playedUpTo ?? e.played_up_to ?? 0,
+    isDeleted: e.isDeleted || e.is_deleted || false,
+    isVideo: e.isVideo || e.is_video || false,
+  }));
+
+export type Episode = z.output<typeof EpisodeSchema>;
+
+// --- Search Result ---
+
+export const SearchResultSchema = z
+  .looseObject({
+    uuid: z.string(),
+    title: z.string(),
+    author: z.string().default(''),
+    description: z.string().optional(),
+    thumbnail_url: z.string().optional(),
+  })
+  .transform(({ thumbnail_url, ...rest }) => ({
+    ...rest,
+    thumbnailUrl: thumbnail_url,
+  }));
+
+export type SearchResult = z.output<typeof SearchResultSchema>;
+
+// --- Listening Stats ---
+// Real API returns camelCase with some values as strings (not numbers).
+
+const numOrStr = z
+  .union([z.number(), z.string().transform((s) => parseFloat(s) || 0)])
+  .default(0);
+
+export const ListeningStatsSchema = z
+  .looseObject({
+    // camelCase (real API)
+    timeSilenceRemoval: numOrStr,
+    timeListened: numOrStr,
+    timeSkipping: numOrStr,
+    timeIntroSkipping: numOrStr,
+    timeVariableSpeed: numOrStr,
+    totalPodcasts: numOrStr,
+    totalEpisodes: numOrStr,
+    timesStartedAt: z.string().optional(),
+    startedAt: z.string().optional(),
+    // snake_case fallback
+    time_silence_removal: numOrStr,
+    time_listened: numOrStr,
+    time_skipping: numOrStr,
+    time_intro_skipping: numOrStr,
+    time_variable_speed: numOrStr,
+    total_podcasts: numOrStr,
+    total_episodes: numOrStr,
+    started_at: z.string().optional(),
+  })
+  .transform((s) => ({
+    ...s,
+    timeSilenceRemoval: s.timeSilenceRemoval || s.time_silence_removal || 0,
+    timeListened: s.timeListened || s.time_listened || 0,
+    timeSkipping: s.timeSkipping || s.time_skipping || 0,
+    timeIntroSkipping: s.timeIntroSkipping || s.time_intro_skipping || 0,
+    timeVariableSpeed: s.timeVariableSpeed || s.time_variable_speed || 0,
+    totalPodcasts: s.totalPodcasts || s.total_podcasts || 0,
+    totalEpisodes: s.totalEpisodes || s.total_episodes || 0,
+    startedAt: s.timesStartedAt ?? s.startedAt ?? s.started_at ?? '',
+  }));
+
+export type ListeningStats = z.output<typeof ListeningStatsSchema>;
+
+// --- Login Response ---
+
+export const LoginResponseSchema = z.object({
+  token: z.string(),
+  uuid: z.string(),
+});