stophy 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -8,7 +8,7 @@ type ErrorResponse = {
     /**
      * Machine-readable error code.
      */
-    code?: 'UNAUTHORIZED' | 'INSUFFICIENT_CREDITS' | 'BAD_REQUEST' | 'INVALID_INPUT' | 'NOT_FOUND' | 'CONCURRENCY_LIMITED' | 'INTERNAL_ERROR';
+    code?: "UNAUTHORIZED" | "INSUFFICIENT_CREDITS" | "BAD_REQUEST" | "INVALID_INPUT" | "NOT_FOUND" | "CONCURRENCY_LIMITED" | "INTERNAL_ERROR";
     /**
      * Human-readable error message.
      */
@@ -45,7 +45,7 @@ type TranscriptResult = {
 };
 type VideoDetails = {
     id: string;
-    type?: 'video';
+    type?: "video";
     videoUrl: string;
     title: string | null;
     author?: string | null;
@@ -65,7 +65,7 @@ type VideoDetails = {
 };
 type RelatedVideo = {
     id: string;
-    type?: 'video';
+    type?: "video";
     videoUrl: string;
     title?: string | null;
     author?: string | null;
@@ -131,7 +131,7 @@ type LiveChatData = {
  */
 type VideoData = VideoDetailsData | TranscriptResult | CommentsData | LiveChatData;
 type SearchVideo = {
-    type: 'video';
+    type: "video";
     id: string;
     videoUrl: string;
     title: string;
@@ -151,7 +151,7 @@ type SearchVideo = {
     thumbnails: Array<Thumbnail>;
 };
 type SearchShort = {
-    type: 'short';
+    type: "short";
     id: string;
     shortUrl: string;
     title: string;
@@ -168,7 +168,7 @@ type SearchShort = {
     thumbnails: Array<Thumbnail>;
 };
 type SearchPlaylist = {
-    type: 'playlist';
+    type: "playlist";
     id: string;
     playlistUrl: string;
     title: string;
@@ -179,7 +179,7 @@ type SearchPlaylist = {
     thumbnails: Array<Thumbnail>;
 };
 type SearchChannel = {
-    type: 'channel';
+    type: "channel";
     id: string;
     channelUrl: string;
     name: string;
@@ -191,13 +191,13 @@ type SearchChannel = {
     thumbnails: Array<Thumbnail>;
 };
 type SearchItem = ({
-    type?: 'video';
+    type?: "video";
 } & SearchVideo) | ({
-    type?: 'short';
+    type?: "short";
 } & SearchShort) | ({
-    type?: 'playlist';
+    type?: "playlist";
 } & SearchPlaylist) | ({
-    type?: 'channel';
+    type?: "channel";
 } & SearchChannel);
 type SearchData = {
     items: Array<SearchItem>;
@@ -254,7 +254,7 @@ type ChannelData = {
 };
 type PlaylistMeta = {
     id: string;
-    type?: 'playlist';
+    type?: "playlist";
     playlistUrl: string;
     title?: string | null;
     author?: string | null;
@@ -265,7 +265,7 @@ type PlaylistMeta = {
 };
 type PlaylistItem = {
     id: string;
-    type?: 'video';
+    type?: "video";
     videoUrl: string;
     title?: string | null;
     author?: string | null;
@@ -332,7 +332,7 @@ type GetVideoData = {
         /**
          * The type of data to retrieve.
          */
-        type: 'details' | 'transcript' | 'comments' | 'replies' | 'livechat';
+        type: "details" | "transcript" | "comments" | "replies" | "livechat";
         /**
          * Full YouTube video URL. Not required when type is replies.
          */
@@ -340,11 +340,11 @@ type GetVideoData = {
         /**
          * Comment sort order. Only applies when type is comments.
          */
-        sortBy?: 'latest' | 'top';
+        sortBy?: "latest" | "top";
         /**
          * Live chat mode. Only applies when type is livechat: 'top' = Top chat (moderated, default), 'live' = all messages. Applied on the first call; later polls keep the chosen mode.
          */
-        chatType?: 'top' | 'live';
+        chatType?: "top" | "live";
         /**
          * Pagination token. Required when type is replies (use the repliesToken from a comment item); for livechat, pass the continuationToken from a previous livechat response to poll for new messages.
          */
@@ -352,7 +352,7 @@ type GetVideoData = {
     };
     path?: never;
     query?: never;
-    url: '/v1/video';
+    url: "/v1/video";
 };
 type GetVideoErrors = {
     /**
@@ -385,7 +385,7 @@ type GetVideoResponses = {
         success: true;
         requestId: string;
         data: VideoData;
-        cacheState: 'hit' | 'miss';
+        cacheState: "hit" | "miss";
         creditsUsed: number;
         creditsRemaining: number;
     };
@@ -400,23 +400,23 @@ type SearchVideosData = {
         /**
          * Filter by content type.
          */
-        type?: 'video' | 'short' | 'channel' | 'playlist' | 'movie';
+        type?: "video" | "short" | "channel" | "playlist" | "movie";
         /**
          * Sort order. Defaults to relevance.
          */
-        sortBy?: 'relevance' | 'popularity' | 'date' | 'rating';
+        sortBy?: "relevance" | "popularity" | "date" | "rating";
         /**
          * Filter by upload date.
          */
-        uploadDate?: 'today' | 'week' | 'month' | 'year';
+        uploadDate?: "today" | "week" | "month" | "year";
         /**
          * Duration filter. Not applicable when type is short.
          */
-        duration?: 'short' | 'medium' | 'long';
+        duration?: "short" | "medium" | "long";
         /**
          * Filter by video features.
          */
-        features?: Array<'live' | '4k' | 'hd' | 'subtitles' | 'creativeCommons' | '360' | 'vr180' | '3d' | 'hdr' | 'location' | 'purchased'>;
+        features?: Array<"live" | "4k" | "hd" | "subtitles" | "creativeCommons" | "360" | "vr180" | "3d" | "hdr" | "location" | "purchased">;
         /**
          * Token from a previous response to fetch the next page.
          */
@@ -424,7 +424,7 @@ type SearchVideosData = {
     };
     path?: never;
     query?: never;
-    url: '/v1/search';
+    url: "/v1/search";
 };
 type SearchVideosErrors = {
     /**
@@ -457,7 +457,7 @@ type SearchVideosResponses = {
         success: true;
         requestId: string;
         data: SearchData;
-        cacheState: 'hit' | 'miss';
+        cacheState: "hit" | "miss";
         creditsUsed: number;
         creditsRemaining: number;
     };
@@ -472,7 +472,7 @@ type GetChannelData = {
         /**
          * Content tab to fetch. Defaults to video.
          */
-        tab?: 'video' | 'short' | 'playlist' | 'about';
+        tab?: "video" | "short" | "playlist" | "about";
         /**
          * Token from a previous response to fetch the next page.
          */
@@ -480,11 +480,11 @@ type GetChannelData = {
         /**
          * Sort order for the selected tab.
          */
-        sortBy?: 'latest' | 'popular' | 'oldest';
+        sortBy?: "latest" | "popular" | "oldest";
     };
     path?: never;
     query?: never;
-    url: '/v1/channel';
+    url: "/v1/channel";
 };
 type GetChannelErrors = {
     /**
@@ -517,7 +517,7 @@ type GetChannelResponses = {
         success: true;
         requestId: string;
         data: ChannelData;
-        cacheState: 'hit' | 'miss';
+        cacheState: "hit" | "miss";
         creditsUsed: number;
         creditsRemaining: number;
     };
@@ -536,7 +536,7 @@ type GetPlaylistData = {
     };
     path?: never;
     query?: never;
-    url: '/v1/playlist';
+    url: "/v1/playlist";
 };
 type GetPlaylistErrors = {
     /**
@@ -569,7 +569,7 @@ type GetPlaylistResponses = {
         success: true;
         requestId: string;
         data: PlaylistData;
-        cacheState: 'hit' | 'miss';
+        cacheState: "hit" | "miss";
         creditsUsed: number;
         creditsRemaining: number;
     };
@@ -592,7 +592,7 @@ type GetSuggestionsData = {
          */
         gl?: string;
     };
-    url: '/v1/suggest';
+    url: "/v1/suggest";
 };
 type GetSuggestionsErrors = {
     /**
@@ -621,7 +621,7 @@ type GetSuggestionsResponses = {
         success: true;
         requestId: string;
         data: SuggestData;
-        cacheState: 'hit' | 'miss';
+        cacheState: "hit" | "miss";
         creditsUsed: number;
         creditsRemaining: number;
     };
@@ -631,7 +631,7 @@ type GetCreditsData = {
     body?: never;
     path?: never;
     query?: never;
-    url: '/v1/credits';
+    url: "/v1/credits";
 };
 type GetCreditsErrors = {
     /**
@@ -658,7 +658,7 @@ type GetLogsData = {
         /**
          * Time window: 'today', the last 7 days, or the last 30 days.
          */
-        days?: 'today' | '7' | '30';
+        days?: "today" | "7" | "30";
         /**
          * Filter logs to a single endpoint, e.g. /video.
          */
@@ -668,7 +668,7 @@ type GetLogsData = {
          */
         page?: number;
     };
-    url: '/v1/logs';
+    url: "/v1/logs";
 };
 type GetLogsErrors = {
     /**
@@ -695,13 +695,13 @@ type GetUsageData = {
         /**
          * Time window: 'today', the last 7 days, or the last 30 days.
          */
-        days?: 'today' | '7' | '30';
+        days?: "today" | "7" | "30";
         /**
          * Timezone offset in minutes used to bucket activity into days. Defaults to UTC.
          */
         tz?: string;
     };
-    url: '/v1/usage';
+    url: "/v1/usage";
 };
 type GetUsageErrors = {
     /**
@@ -722,57 +722,42 @@ type GetUsageResponses = {
 };
 type GetUsageResponse = GetUsageResponses[keyof GetUsageResponses];
 type ClientOptions = {
-    baseUrl: 'https://api.stophy.dev' | (string & {});
+    baseUrl: "https://api.stophy.dev" | (string & {});
 };
 
-/** A video response with `data` narrowed to the shape for a given request `type`. */
-type VideoResponseFor<D> = Omit<GetVideoResponse, "data"> & {
-    data: D;
+type ChannelBody = GetChannelData["body"];
+type ChannelOptions = Omit<ChannelBody, "channelUrl">;
+
+type PlaylistBody = GetPlaylistData["body"];
+type PlaylistOptions = Omit<PlaylistBody, "playlistUrl">;
+
+type SearchBody = SearchVideosData["body"];
+type SearchOptions = Omit<SearchBody, "q">;
+
+type SuggestQuery = GetSuggestionsData["query"];
+type SuggestOptions = Omit<SuggestQuery, "q">;
+
+type VideoResponseFor<T> = Omit<GetVideoResponse, "data"> & {
+    data: T;
 };
+type CommentsOptions = Pick<GetVideoData["body"], "sortBy" | "continuationToken">;
+type LiveChatOptions = Pick<GetVideoData["body"], "chatType" | "continuationToken">;
 
 interface StophyOptions {
-    /** API key from your dashboard. Sent as `Authorization: Bearer <key>`. */
-    apiKey: string;
-    /** Defaults to `https://api.stophy.dev`. */
+    /** Defaults to `STOPHY_API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `STOPHY_BASE_URL` or `https://api.stophy.dev`. */
     baseUrl?: string;
-    /** Bring your own `fetch` (handy for tests or non-global runtimes). */
     fetch?: typeof globalThis.fetch;
-    /** Sent with every request. */
     headers?: Record<string, string>;
-    /**
-     * Retry attempts for transient failures (network errors and
-     * 429/500/502/503/504). Set to `0` to disable. Defaults to `2`.
-     */
     maxRetries?: number;
-    /** Base delay for backoff, in ms. Defaults to `500`. */
     retryInitialDelayMs?: number;
 }
-/** Thrown when the API responds with a non-2xx status. */
-declare class StophyError extends Error {
-    readonly code?: ErrorResponse["code"];
-    readonly status: number;
-    readonly requestId?: string;
-    readonly details?: unknown;
-    constructor(message: string, opts: {
-        status: number;
-        code?: ErrorResponse["code"];
-        requestId?: string;
-        details?: unknown;
-    });
-}
-/**
- * Stophy API client — YouTube context API for AI agents.
- *
- * ```ts
- * const stophy = new Stophy({ apiKey: process.env.STOPHY_API_KEY! });
- * const { data } = await stophy.video({ type: "transcript", videoUrl });
- * ```
- */
+type StophyClientInput = StophyOptions | string;
+/** Typed client for the Stophy API. */
 declare class Stophy {
-    /** The underlying fetch client, if you need lower-level access. */
     readonly client: Client;
-    constructor(options: StophyOptions);
-    /** Video details, transcript, comments, replies, or live chat — pick with `type`. */
+    constructor(input?: StophyClientInput);
     video(body: GetVideoData["body"] & {
         type: "details";
     }): Promise<VideoResponseFor<VideoDetailsData>>;
@@ -786,20 +771,36 @@ declare class Stophy {
         type: "livechat";
     }): Promise<VideoResponseFor<LiveChatData>>;
     video(body: GetVideoData["body"]): Promise<GetVideoResponse>;
-    /** Search YouTube, optionally filtered by type, sort, date, duration, and features. */
+    videoDetails(videoUrl: string): Promise<VideoResponseFor<VideoDetailsData>>;
+    transcript(videoUrl: string): Promise<VideoResponseFor<TranscriptResult>>;
+    comments(videoUrl: string, options?: CommentsOptions): Promise<VideoResponseFor<CommentsData>>;
+    replies(continuationToken: string): Promise<VideoResponseFor<CommentsData>>;
+    liveChat(videoUrl: string, options?: LiveChatOptions): Promise<VideoResponseFor<LiveChatData>>;
     search(body: SearchVideosData["body"]): Promise<SearchVideosResponse>;
-    /** Channel metadata and content. Switch sections with `tab`. */
+    search(query: string, options?: SearchOptions): Promise<SearchVideosResponse>;
     channel(body: GetChannelData["body"]): Promise<GetChannelResponse>;
-    /** Playlist items. Page through long playlists with `continuationToken`. */
+    channel(channelUrl: string, options?: ChannelOptions): Promise<GetChannelResponse>;
     playlist(body: GetPlaylistData["body"]): Promise<GetPlaylistResponse>;
-    /** Search autocomplete suggestions. */
+    playlist(playlistUrl: string, options?: PlaylistOptions): Promise<GetPlaylistResponse>;
     suggest(query: GetSuggestionsData["query"]): Promise<GetSuggestionsResponse>;
-    /** Your current credit balance. */
+    suggest(query: string, options?: SuggestOptions): Promise<GetSuggestionsResponse>;
     credits(): Promise<GetCreditsResponse>;
-    /** Recent API request logs. */
     logs(query?: GetLogsData["query"]): Promise<GetLogsResponse>;
-    /** Daily credit and request counts. */
     usage(query?: GetUsageData["query"]): Promise<GetUsageResponse>;
 }
 
-export { type ChannelData, type ChannelLink, type ChannelProfile, type ClientOptions, type Comment, type CommentsData, type ContentItem, type CreditsData, type EmptyState, type ErrorResponse, type GetChannelData, type GetChannelError, type GetChannelErrors, type GetChannelResponse, type GetChannelResponses, type GetCreditsData, type GetCreditsError, type GetCreditsErrors, type GetCreditsResponse, type GetCreditsResponses, type GetLogsData, type GetLogsError, type GetLogsErrors, type GetLogsResponse, type GetLogsResponses, type GetPlaylistData, type GetPlaylistError, type GetPlaylistErrors, type GetPlaylistResponse, type GetPlaylistResponses, type GetSuggestionsData, type GetSuggestionsError, type GetSuggestionsErrors, type GetSuggestionsResponse, type GetSuggestionsResponses, type GetUsageData, type GetUsageError, type GetUsageErrors, type GetUsageResponse, type GetUsageResponses, type GetVideoData, type GetVideoError, type GetVideoErrors, type GetVideoResponse, type GetVideoResponses, type LiveChatData, type LiveChatMessage, type LogEntry, type LogsData, type PlaylistData, type PlaylistItem, type PlaylistMeta, type RelatedVideo, type SearchChannel, type SearchData, type SearchItem, type SearchPlaylist, type SearchShort, type SearchVideo, type SearchVideosData, type SearchVideosError, type SearchVideosErrors, type SearchVideosResponse, type SearchVideosResponses, Stophy, StophyError, type StophyOptions, type SuggestData, type Thumbnail, type TranscriptLanguage, type TranscriptResult, type TranscriptSegment, type UsageData, type UsageItem, type VideoData, type VideoDetails, type VideoDetailsData, Stophy as default };
+/** Thrown when the Stophy API responds with a non-success status. */
+declare class StophyError extends Error {
+    readonly code?: ErrorResponse["code"];
+    readonly status: number;
+    readonly requestId?: string;
+    readonly details?: unknown;
+    constructor(message: string, options: {
+        status: number;
+        code?: ErrorResponse["code"];
+        requestId?: string;
+        details?: unknown;
+    });
+}
+
+export { type ChannelData, type ChannelLink, type ChannelOptions, type ChannelProfile, type ClientOptions, type Comment, type CommentsData, type CommentsOptions, type ContentItem, type CreditsData, type EmptyState, type ErrorResponse, type GetChannelData, type GetChannelError, type GetChannelErrors, type GetChannelResponse, type GetChannelResponses, type GetCreditsData, type GetCreditsError, type GetCreditsErrors, type GetCreditsResponse, type GetCreditsResponses, type GetLogsData, type GetLogsError, type GetLogsErrors, type GetLogsResponse, type GetLogsResponses, type GetPlaylistData, type GetPlaylistError, type GetPlaylistErrors, type GetPlaylistResponse, type GetPlaylistResponses, type GetSuggestionsData, type GetSuggestionsError, type GetSuggestionsErrors, type GetSuggestionsResponse, type GetSuggestionsResponses, type GetUsageData, type GetUsageError, type GetUsageErrors, type GetUsageResponse, type GetUsageResponses, type GetVideoData, type GetVideoError, type GetVideoErrors, type GetVideoResponse, type GetVideoResponses, type LiveChatData, type LiveChatMessage, type LiveChatOptions, type LogEntry, type LogsData, type PlaylistData, type PlaylistItem, type PlaylistMeta, type PlaylistOptions, type RelatedVideo, type SearchChannel, type SearchData, type SearchItem, type SearchOptions, type SearchPlaylist, type SearchShort, type SearchVideo, type SearchVideosData, type SearchVideosError, type SearchVideosErrors, type SearchVideosResponse, type SearchVideosResponses, Stophy, type StophyClientInput, StophyError, type StophyOptions, type SuggestData, type SuggestOptions, type Thumbnail, type TranscriptLanguage, type TranscriptResult, type TranscriptSegment, type UsageData, type UsageItem, type VideoData, type VideoDetails, type VideoDetailsData, Stophy as default };