stophy 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,805 @@
+import { Client } from '@hey-api/client-fetch';
+
+type ErrorResponse = {
+    /**
+     * Always false for error responses.
+     */
+    success: false;
+    /**
+     * Machine-readable error code.
+     */
+    code?: 'UNAUTHORIZED' | 'INSUFFICIENT_CREDITS' | 'BAD_REQUEST' | 'INVALID_INPUT' | 'NOT_FOUND' | 'CONCURRENCY_LIMITED' | 'INTERNAL_ERROR';
+    /**
+     * Human-readable error message.
+     */
+    error: string;
+    /**
+     * Optional additional context, present on validation errors.
+     */
+    details?: unknown;
+};
+type Thumbnail = {
+    url: string;
+    width: number;
+    height: number;
+};
+type EmptyState = {
+    code: string;
+    message: string;
+};
+type TranscriptLanguage = {
+    code: string | null;
+    name: string | null;
+    isAutoGenerated: boolean;
+};
+type TranscriptSegment = {
+    start: number;
+    duration: number;
+    text: string;
+};
+type TranscriptResult = {
+    language: TranscriptLanguage;
+    segments: Array<TranscriptSegment>;
+    text: string;
+    empty?: EmptyState;
+};
+type VideoDetails = {
+    id: string;
+    type?: 'video';
+    videoUrl: string;
+    title: string | null;
+    author?: string | null;
+    authorId?: string | null;
+    category?: string | null;
+    description?: string | null;
+    durationSec?: number | null;
+    durationText?: string | null;
+    isLive?: boolean;
+    likeCount?: number | null;
+    likeCountText?: string | null;
+    publishedAt?: string | null;
+    tags?: Array<string>;
+    viewCount?: number | null;
+    viewCountText?: string | null;
+    thumbnails: Array<Thumbnail>;
+};
+type RelatedVideo = {
+    id: string;
+    type?: 'video';
+    videoUrl: string;
+    title?: string | null;
+    author?: string | null;
+    authorId?: string | null;
+    durationSec?: number | null;
+    durationText?: string | null;
+    publishedAt?: string | null;
+    publishedAtText?: string | null;
+    viewCount?: number | null;
+    viewCountText?: string | null;
+    thumbnails: Array<Thumbnail>;
+};
+type VideoDetailsData = {
+    video: VideoDetails;
+    related: Array<RelatedVideo>;
+};
+type Comment = {
+    id: string | null;
+    text: string | null;
+    author: string | null;
+    authorId: string | null;
+    authorThumbnail?: string | null;
+    hasChannelOwnerReplied: boolean;
+    isChannelOwner: boolean;
+    isHearted: boolean;
+    isPinned: boolean;
+    isVerified: boolean;
+    publishedAt?: string | null;
+    publishedAtText?: string | null;
+    likeCount?: number | null;
+    likeCountText?: string | null;
+    replyCount?: number | null;
+    replyCountText?: string | null;
+    repliesToken?: string | null;
+};
+type CommentsData = {
+    items: Array<Comment>;
+    continuationToken: string | null;
+    empty?: EmptyState;
+};
+type LiveChatMessage = {
+    id: string;
+    text: string;
+    author?: string | null;
+    authorId?: string | null;
+    timestampUsec?: string | null;
+    isOwner: boolean;
+    isModerator: boolean;
+    isVerified: boolean;
+    superChatAmount?: string | null;
+    superChatCurrency?: string | null;
+};
+type LiveChatData = {
+    status: string;
+    isLive: boolean;
+    concurrentViewers?: number | null;
+    pollIntervalMs?: number | null;
+    messages: Array<LiveChatMessage>;
+    continuationToken: string | null;
+};
+/**
+ * Shape depends on the request `type`: details, transcript, comments/replies, or livechat.
+ */
+type VideoData = VideoDetailsData | TranscriptResult | CommentsData | LiveChatData;
+type SearchVideo = {
+    type: 'video';
+    id: string;
+    videoUrl: string;
+    title: string;
+    author?: string | null;
+    authorId?: string | null;
+    description?: string | null;
+    duration?: string | null;
+    durationSec?: number | null;
+    durationText?: string | null;
+    isLive?: boolean;
+    isUpcoming?: boolean;
+    isVerified?: boolean;
+    viewCount?: number | null;
+    viewCountText?: string | null;
+    publishedAt?: string | null;
+    publishedAtText?: string | null;
+    thumbnails: Array<Thumbnail>;
+};
+type SearchShort = {
+    type: 'short';
+    id: string;
+    shortUrl: string;
+    title: string;
+    author?: string | null;
+    authorId?: string | null;
+    description?: string | null;
+    duration?: string | null;
+    durationSec?: number | null;
+    durationText?: string | null;
+    viewCount?: number | null;
+    viewCountText?: string | null;
+    publishedAt?: string | null;
+    publishedAtText?: string | null;
+    thumbnails: Array<Thumbnail>;
+};
+type SearchPlaylist = {
+    type: 'playlist';
+    id: string;
+    playlistUrl: string;
+    title: string;
+    author?: string | null;
+    authorId?: string | null;
+    videoCount?: number | null;
+    videoCountText?: string | null;
+    thumbnails: Array<Thumbnail>;
+};
+type SearchChannel = {
+    type: 'channel';
+    id: string;
+    channelUrl: string;
+    name: string;
+    handle?: string | null;
+    description?: string | null;
+    subscriberCount?: number | null;
+    subscriberCountText?: string | null;
+    isVerified?: boolean;
+    thumbnails: Array<Thumbnail>;
+};
+type SearchItem = ({
+    type?: 'video';
+} & SearchVideo) | ({
+    type?: 'short';
+} & SearchShort) | ({
+    type?: 'playlist';
+} & SearchPlaylist) | ({
+    type?: 'channel';
+} & SearchChannel);
+type SearchData = {
+    items: Array<SearchItem>;
+    continuationToken: string | null;
+    estimatedResults?: number;
+    empty?: EmptyState;
+};
+type ChannelLink = {
+    title: string;
+    url: string;
+};
+type ChannelProfile = {
+    id: string | null;
+    name: string | null;
+    handle: string | null;
+    channelUrl: string | null;
+    description?: string | null;
+    subscriberCount?: number | null;
+    subscriberCountText?: string | null;
+    videoCount?: number | null;
+    videoCountText?: string | null;
+    viewCount?: number | null;
+    viewCountText?: string | null;
+    isVerified: boolean;
+    country?: string | null;
+    joinedDate?: string | null;
+    thumbnails: Array<Thumbnail>;
+    banners: Array<Thumbnail>;
+    links?: Array<ChannelLink> | null;
+};
+type ContentItem = {
+    id: string;
+    type?: string;
+    title?: string | null;
+    videoUrl?: string;
+    shortUrl?: string;
+    playlistUrl?: string;
+    author?: string | null;
+    authorId?: string | null;
+    durationSec?: number | null;
+    durationText?: string | null;
+    viewCount?: number | null;
+    viewCountText?: string | null;
+    publishedAt?: string | null;
+    publishedAtText?: string | null;
+    thumbnails: Array<Thumbnail>;
+};
+type ChannelData = {
+    channel: ChannelProfile | null;
+    tab?: string | null;
+    items?: Array<ContentItem>;
+    continuationToken?: string | null;
+    empty?: EmptyState;
+};
+type PlaylistMeta = {
+    id: string;
+    type?: 'playlist';
+    playlistUrl: string;
+    title?: string | null;
+    author?: string | null;
+    authorId?: string | null;
+    description?: string | null;
+    videoCount?: string | null;
+    thumbnails: Array<Thumbnail>;
+};
+type PlaylistItem = {
+    id: string;
+    type?: 'video';
+    videoUrl: string;
+    title?: string | null;
+    author?: string | null;
+    authorId?: string | null;
+    durationSec?: number | null;
+    durationText?: string | null;
+    index?: number | null;
+    isLive?: boolean;
+    isPlayable?: boolean;
+    isUpcoming?: boolean;
+    upcomingAt?: string | null;
+    viewCount?: number | null;
+    viewCountText?: string | null;
+    publishedAt?: string | null;
+    publishedAtText?: string | null;
+    thumbnails: Array<Thumbnail>;
+};
+type PlaylistData = {
+    playlist: PlaylistMeta | null;
+    items: Array<PlaylistItem>;
+    continuationToken: string | null;
+    empty?: EmptyState;
+};
+type SuggestData = {
+    q: string;
+    hl: string;
+    gl: string;
+    suggestions: Array<string>;
+};
+type CreditsData = {
+    credits: number;
+};
+type LogEntry = {
+    id: string;
+    userId?: string;
+    apiKeyId?: string | null;
+    apiKeyName?: string | null;
+    endpoint: string;
+    method: string;
+    status: number;
+    credits: number;
+    durationMs?: number | null;
+    response?: string | null;
+    createdAt: string;
+};
+type LogsData = {
+    logs: Array<LogEntry>;
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    endpoints: Array<string>;
+};
+type UsageItem = {
+    date: string;
+    credits: number;
+    requests: number;
+};
+type UsageData = {
+    items: Array<UsageItem>;
+};
+type GetVideoData = {
+    body: {
+        /**
+         * The type of data to retrieve.
+         */
+        type: 'details' | 'transcript' | 'comments' | 'replies' | 'livechat';
+        /**
+         * Full YouTube video URL. Not required when type is replies.
+         */
+        videoUrl: string;
+        /**
+         * Comment sort order. Only applies when type is comments.
+         */
+        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';
+        /**
+         * 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.
+         */
+        continuationToken?: string;
+    };
+    path?: never;
+    query?: never;
+    url: '/v1/video';
+};
+type GetVideoErrors = {
+    /**
+     * Validation error
+     */
+    400: ErrorResponse;
+    /**
+     * Invalid or missing API key
+     */
+    401: ErrorResponse;
+    /**
+     * Insufficient credits
+     */
+    402: ErrorResponse;
+    /**
+     * Rate limited
+     */
+    429: ErrorResponse;
+    /**
+     * Internal error
+     */
+    500: ErrorResponse;
+};
+type GetVideoError = GetVideoErrors[keyof GetVideoErrors];
+type GetVideoResponses = {
+    /**
+     * Successful response
+     */
+    200: {
+        success: true;
+        requestId: string;
+        data: VideoData;
+        cacheState: 'hit' | 'miss';
+        creditsUsed: number;
+        creditsRemaining: number;
+    };
+};
+type GetVideoResponse = GetVideoResponses[keyof GetVideoResponses];
+type SearchVideosData = {
+    body: {
+        /**
+         * Search query.
+         */
+        q: string;
+        /**
+         * Filter by content type.
+         */
+        type?: 'video' | 'short' | 'channel' | 'playlist' | 'movie';
+        /**
+         * Sort order. Defaults to relevance.
+         */
+        sortBy?: 'relevance' | 'popularity' | 'date' | 'rating';
+        /**
+         * Filter by upload date.
+         */
+        uploadDate?: 'today' | 'week' | 'month' | 'year';
+        /**
+         * Duration filter. Not applicable when type is short.
+         */
+        duration?: 'short' | 'medium' | 'long';
+        /**
+         * Filter by video features.
+         */
+        features?: Array<'live' | '4k' | 'hd' | 'subtitles' | 'creativeCommons' | '360' | 'vr180' | '3d' | 'hdr' | 'location' | 'purchased'>;
+        /**
+         * Token from a previous response to fetch the next page.
+         */
+        continuationToken?: string;
+    };
+    path?: never;
+    query?: never;
+    url: '/v1/search';
+};
+type SearchVideosErrors = {
+    /**
+     * Validation error
+     */
+    400: ErrorResponse;
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+    /**
+     * Insufficient credits
+     */
+    402: ErrorResponse;
+    /**
+     * Rate limited
+     */
+    429: ErrorResponse;
+    /**
+     * Internal error
+     */
+    500: ErrorResponse;
+};
+type SearchVideosError = SearchVideosErrors[keyof SearchVideosErrors];
+type SearchVideosResponses = {
+    /**
+     * Search results
+     */
+    200: {
+        success: true;
+        requestId: string;
+        data: SearchData;
+        cacheState: 'hit' | 'miss';
+        creditsUsed: number;
+        creditsRemaining: number;
+    };
+};
+type SearchVideosResponse = SearchVideosResponses[keyof SearchVideosResponses];
+type GetChannelData = {
+    body: {
+        /**
+         * Full YouTube channel URL, e.g. https://www.youtube.com/@mkbhd.
+         */
+        channelUrl: string;
+        /**
+         * Content tab to fetch. Defaults to video.
+         */
+        tab?: 'video' | 'short' | 'playlist' | 'about';
+        /**
+         * Token from a previous response to fetch the next page.
+         */
+        continuationToken?: string;
+        /**
+         * Sort order for the selected tab.
+         */
+        sortBy?: 'latest' | 'popular' | 'oldest';
+    };
+    path?: never;
+    query?: never;
+    url: '/v1/channel';
+};
+type GetChannelErrors = {
+    /**
+     * Validation error
+     */
+    400: ErrorResponse;
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+    /**
+     * Insufficient credits
+     */
+    402: ErrorResponse;
+    /**
+     * Rate limited
+     */
+    429: ErrorResponse;
+    /**
+     * Internal error
+     */
+    500: ErrorResponse;
+};
+type GetChannelError = GetChannelErrors[keyof GetChannelErrors];
+type GetChannelResponses = {
+    /**
+     * Channel data
+     */
+    200: {
+        success: true;
+        requestId: string;
+        data: ChannelData;
+        cacheState: 'hit' | 'miss';
+        creditsUsed: number;
+        creditsRemaining: number;
+    };
+};
+type GetChannelResponse = GetChannelResponses[keyof GetChannelResponses];
+type GetPlaylistData = {
+    body: {
+        /**
+         * Full YouTube playlist URL.
+         */
+        playlistUrl: string;
+        /**
+         * Token from a previous response to fetch the next page.
+         */
+        continuationToken?: string;
+    };
+    path?: never;
+    query?: never;
+    url: '/v1/playlist';
+};
+type GetPlaylistErrors = {
+    /**
+     * Validation error
+     */
+    400: ErrorResponse;
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+    /**
+     * Insufficient credits
+     */
+    402: ErrorResponse;
+    /**
+     * Rate limited
+     */
+    429: ErrorResponse;
+    /**
+     * Internal error
+     */
+    500: ErrorResponse;
+};
+type GetPlaylistError = GetPlaylistErrors[keyof GetPlaylistErrors];
+type GetPlaylistResponses = {
+    /**
+     * Playlist items
+     */
+    200: {
+        success: true;
+        requestId: string;
+        data: PlaylistData;
+        cacheState: 'hit' | 'miss';
+        creditsUsed: number;
+        creditsRemaining: number;
+    };
+};
+type GetPlaylistResponse = GetPlaylistResponses[keyof GetPlaylistResponses];
+type GetSuggestionsData = {
+    body?: never;
+    path?: never;
+    query: {
+        /**
+         * Search query.
+         */
+        q: string;
+        /**
+         * Language code, e.g. en, fr, de. Defaults to en.
+         */
+        hl?: string;
+        /**
+         * Country code, e.g. US, GB, DE. Defaults to US.
+         */
+        gl?: string;
+    };
+    url: '/v1/suggest';
+};
+type GetSuggestionsErrors = {
+    /**
+     * Validation error
+     */
+    400: ErrorResponse;
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+    /**
+     * Rate limited
+     */
+    429: ErrorResponse;
+    /**
+     * Internal error
+     */
+    500: ErrorResponse;
+};
+type GetSuggestionsError = GetSuggestionsErrors[keyof GetSuggestionsErrors];
+type GetSuggestionsResponses = {
+    /**
+     * Autocomplete suggestions
+     */
+    200: {
+        success: true;
+        requestId: string;
+        data: SuggestData;
+        cacheState: 'hit' | 'miss';
+        creditsUsed: number;
+        creditsRemaining: number;
+    };
+};
+type GetSuggestionsResponse = GetSuggestionsResponses[keyof GetSuggestionsResponses];
+type GetCreditsData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/v1/credits';
+};
+type GetCreditsErrors = {
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+};
+type GetCreditsError = GetCreditsErrors[keyof GetCreditsErrors];
+type GetCreditsResponses = {
+    /**
+     * Credit balance
+     */
+    200: {
+        success: true;
+        requestId: string;
+        data: CreditsData;
+    };
+};
+type GetCreditsResponse = GetCreditsResponses[keyof GetCreditsResponses];
+type GetLogsData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Time window: 'today', the last 7 days, or the last 30 days.
+         */
+        days?: 'today' | '7' | '30';
+        /**
+         * Filter logs to a single endpoint, e.g. /video.
+         */
+        endpoint?: string;
+        /**
+         * Zero-based page index. Page size is fixed at 50 entries.
+         */
+        page?: number;
+    };
+    url: '/v1/logs';
+};
+type GetLogsErrors = {
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+};
+type GetLogsError = GetLogsErrors[keyof GetLogsErrors];
+type GetLogsResponses = {
+    /**
+     * Request logs
+     */
+    200: {
+        success: true;
+        requestId: string;
+        data: LogsData;
+    };
+};
+type GetLogsResponse = GetLogsResponses[keyof GetLogsResponses];
+type GetUsageData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Time window: 'today', the last 7 days, or the last 30 days.
+         */
+        days?: 'today' | '7' | '30';
+        /**
+         * Timezone offset in minutes used to bucket activity into days. Defaults to UTC.
+         */
+        tz?: string;
+    };
+    url: '/v1/usage';
+};
+type GetUsageErrors = {
+    /**
+     * Unauthorized
+     */
+    401: ErrorResponse;
+};
+type GetUsageError = GetUsageErrors[keyof GetUsageErrors];
+type GetUsageResponses = {
+    /**
+     * Daily usage
+     */
+    200: {
+        success: true;
+        requestId: string;
+        data: UsageData;
+    };
+};
+type GetUsageResponse = GetUsageResponses[keyof GetUsageResponses];
+type ClientOptions = {
+    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;
+};
+
+interface StophyOptions {
+    /** API key from your dashboard. Sent as `Authorization: Bearer <key>`. */
+    apiKey: string;
+    /** Defaults to `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 });
+ * ```
+ */
+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`. */
+    video(body: GetVideoData["body"] & {
+        type: "details";
+    }): Promise<VideoResponseFor<VideoDetailsData>>;
+    video(body: GetVideoData["body"] & {
+        type: "transcript";
+    }): Promise<VideoResponseFor<TranscriptResult>>;
+    video(body: GetVideoData["body"] & {
+        type: "comments" | "replies";
+    }): Promise<VideoResponseFor<CommentsData>>;
+    video(body: GetVideoData["body"] & {
+        type: "livechat";
+    }): Promise<VideoResponseFor<LiveChatData>>;
+    video(body: GetVideoData["body"]): Promise<GetVideoResponse>;
+    /** Search YouTube, optionally filtered by type, sort, date, duration, and features. */
+    search(body: SearchVideosData["body"]): Promise<SearchVideosResponse>;
+    /** Channel metadata and content. Switch sections with `tab`. */
+    channel(body: GetChannelData["body"]): Promise<GetChannelResponse>;
+    /** Playlist items. Page through long playlists with `continuationToken`. */
+    playlist(body: GetPlaylistData["body"]): Promise<GetPlaylistResponse>;
+    /** Search autocomplete suggestions. */
+    suggest(query: GetSuggestionsData["query"]): Promise<GetSuggestionsResponse>;
+    /** Your current credit balance. */
+    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 };