@olastudio/social-media-sdk 0.1.0

package/dist/insights.types-5z7HJnbt.d.mts

@@ -0,0 +1,351 @@
+import { R as RequestOptions } from './auth.types-DTXCyA56.mjs';
+
+/**
+ * API Types - Interfaces for API clients
+ */
+
+/**
+ * Interface that each API client must implement
+ */
+interface APIClient {
+    /**
+     * Generic request
+     */
+    request<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+    /**
+     * GET request
+     */
+    get<T>(endpoint: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(endpoint: string, body?: any): Promise<T>;
+    /**
+     * PUT request
+     */
+    put<T>(endpoint: string, body?: any): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T>(endpoint: string): Promise<T>;
+}
+/**
+ * HTTP client configuration
+ */
+interface HttpClientConfig {
+    baseURL: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    accessToken?: string;
+}
+
+/**
+ * Insights Constants - Metrics available for Facebook/Instagram APIs
+ * Updated for Graph API v24.0 (includes Nov 2025 changes)
+ *
+ * @see https://developers.facebook.com/docs/insights/guides
+ */
+/**
+ * Facebook Page metrics (lifetime)
+ * Note: 'page_fans' deprecated Nov 2025, use 'followers_count' field instead
+ */
+declare const PAGE_METRICS_LIFETIME: readonly ["page_fans_country", "page_fans_city", "page_fans_gender_age"];
+/**
+ * Facebook Page metrics (day/week/days_28)
+ * Note: 'page_impressions' deprecated Nov 2025, use 'page_views' instead
+ */
+declare const PAGE_METRICS_PERIODIC: readonly ["page_views_total", "page_views", "page_post_engagements", "page_fans_online", "page_fans_online_per_day", "page_video_views", "page_daily_follows", "page_daily_unfollows"];
+/**
+ * Post metrics (lifetime only)
+ * Note: 'post_impressions' deprecated, use 'post_views' equivalents
+ */
+declare const POST_METRICS: readonly ["post_engaged_users", "post_negative_feedback", "post_engaged_fan", "post_clicks", "post_clicks_unique", "post_reactions_by_type_total"];
+/**
+ * Video metrics (lifetime)
+ * Note: 'video_views' deprecated Apr 2024, use 'total_video_views'
+ */
+declare const VIDEO_METRICS: readonly ["total_video_views", "total_video_views_unique", "total_video_views_autoplayed", "total_video_views_clicked_to_play", "total_video_views_organic", "total_video_views_organic_unique", "total_video_views_paid", "total_video_views_paid_unique", "total_video_avg_time_watched", "total_video_view_total_time", "total_video_complete_views", "total_video_complete_views_unique", "total_video_complete_views_organic", "total_video_complete_views_organic_unique", "total_video_complete_views_paid", "total_video_complete_views_paid_unique"];
+/**
+ * Facebook Reels metrics (added Dec 2024)
+ * Available via Video Insights API
+ */
+declare const REELS_METRICS: readonly ["blue_reels_play_count", "post_video_avg_time_watched", "post_video_views", "post_video_social_actions"];
+/**
+ * Extended Reels metrics for detailed analysis
+ */
+declare const REELS_METRICS_EXTENDED: readonly ["plays", "comments", "likes", "shares", "reach", "total_plays", "average_minutes_viewed", "minutes_viewed"];
+/**
+ * Photo metrics (lifetime only)
+ */
+declare const PHOTO_METRICS: readonly ["photo_views", "photo_reach", "engaged_users"];
+/**
+ * Instagram account metrics (day/week/days_28)
+ * Note: 'impressions' deprecated Apr 2025, use 'views'
+ */
+declare const INSTAGRAM_ACCOUNT_METRICS: readonly ["views", "reach", "accounts_engaged", "total_interactions", "likes", "comments", "shares", "saves", "follows_and_unfollows", "profile_links_taps", "profile_views"];
+/**
+ * Instagram account metrics - Demographics
+ */
+declare const INSTAGRAM_DEMOGRAPHICS_METRICS: readonly ["follower_demographics", "reached_audience_demographics", "engaged_audience_demographics"];
+/**
+ * Instagram media metrics (all types)
+ */
+declare const INSTAGRAM_MEDIA_METRICS_COMMON: readonly ["views", "reach", "likes", "comments", "shares", "saved", "total_interactions"];
+/**
+ * Instagram Reels specific metrics
+ */
+declare const INSTAGRAM_REELS_METRICS: readonly ["plays", "reach", "likes", "comments", "shares", "saved", "total_interactions"];
+/**
+ * Instagram Stories specific metrics
+ */
+declare const INSTAGRAM_STORIES_METRICS: readonly ["exits", "replies", "taps_forward", "taps_back", "views", "reach"];
+declare const INSIGHTS_PERIODS: {
+    readonly DAY: "day";
+    readonly WEEK: "week";
+    readonly DAYS_28: "days_28";
+    readonly MONTH: "month";
+    readonly LIFETIME: "lifetime";
+};
+type InsightsPeriod = typeof INSIGHTS_PERIODS[keyof typeof INSIGHTS_PERIODS];
+/**
+ * Common metric presets for quick access
+ */
+declare const METRIC_PRESETS: {
+    readonly PAGE_OVERVIEW: readonly ["page_views_total", "page_post_engagements", "page_video_views"];
+    readonly VIDEO_PERFORMANCE: readonly ["total_video_views", "total_video_avg_time_watched", "total_video_complete_views"];
+    readonly REELS_PERFORMANCE: readonly ["blue_reels_play_count", "post_video_avg_time_watched", "post_video_social_actions"];
+    readonly INSTAGRAM_OVERVIEW: readonly ["views", "reach", "accounts_engaged", "total_interactions"];
+    readonly INSTAGRAM_ENGAGEMENT: readonly ["likes", "comments", "shares", "saves"];
+};
+
+/**
+ * Insights Types - Types for Facebook/Instagram Insights APIs
+ */
+
+/**
+ * Base insight value structure
+ */
+interface InsightValue {
+    value: number | Record<string, number>;
+    end_time?: string;
+}
+/**
+ * Base insight data item
+ */
+interface InsightDataItem {
+    id?: string;
+    name: string;
+    period: string;
+    values?: InsightValue[];
+    total_value?: {
+        value: number;
+        breakdowns?: InsightBreakdown[];
+    };
+    title?: string;
+    description?: string;
+}
+/**
+ * Insight breakdown structure
+ */
+interface InsightBreakdown {
+    dimension_keys: string[];
+    results: Array<{
+        dimension_values: string[];
+        value: number;
+        end_time?: string;
+    }>;
+}
+/**
+ * Generic insights response
+ */
+interface InsightsResponse {
+    data: InsightDataItem[];
+    paging?: {
+        previous?: string;
+        next?: string;
+    };
+}
+/**
+ * Page insights request params
+ */
+interface PageInsightsParams {
+    metric: string[];
+    period?: InsightsPeriod;
+    since?: number;
+    until?: number;
+    date_preset?: 'today' | 'yesterday' | 'this_week' | 'last_week' | 'this_month' | 'last_month';
+}
+/**
+ * Page overview data
+ */
+interface PageOverview {
+    id: string;
+    name: string;
+    followers_count: number;
+    fan_count?: number;
+    views_total?: number;
+    engagement?: number;
+}
+/**
+ * Post insights request params
+ */
+interface PostInsightsParams {
+    postId: string;
+    metric?: string[];
+}
+/**
+ * Post insights data
+ */
+interface PostInsights {
+    id: string;
+    views?: number;
+    reach?: number;
+    engaged_users?: number;
+    clicks?: number;
+    reactions_by_type?: Record<string, number>;
+    negative_feedback?: number;
+}
+/**
+ * Video insights request params
+ */
+interface VideoInsightsParams {
+    videoId: string;
+    metric?: string[];
+}
+/**
+ * Video insights data
+ */
+interface VideoInsights {
+    id: string;
+    total_views?: number;
+    unique_views?: number;
+    avg_time_watched?: number;
+    complete_views?: number;
+    organic_views?: number;
+    paid_views?: number;
+    total_time_watched?: number;
+}
+/**
+ * Video basic info with insights
+ */
+interface VideoWithInsights {
+    id: string;
+    title?: string;
+    description?: string;
+    created_time: string;
+    length?: number;
+    views?: number;
+    insights?: VideoInsights;
+}
+/**
+ * Reels insights request params
+ */
+interface ReelsInsightsParams {
+    reelId: string;
+    metric?: string[];
+}
+/**
+ * Reels insights data
+ */
+interface ReelsInsights {
+    id: string;
+    plays?: number;
+    total_plays?: number;
+    avg_time_watched?: number;
+    reach?: number;
+    likes?: number;
+    comments?: number;
+    shares?: number;
+    saves?: number;
+}
+/**
+ * Photo insights request params
+ */
+interface PhotoInsightsParams {
+    photoId: string;
+    metric?: string[];
+}
+/**
+ * Photo insights data
+ */
+interface PhotoInsights {
+    id: string;
+    views?: number;
+    reach?: number;
+    engaged_users?: number;
+}
+/**
+ * Instagram account insights params
+ */
+interface InstagramAccountInsightsParams {
+    metric: string[];
+    period?: InsightsPeriod;
+    metric_type?: 'time_series' | 'total_value';
+    since?: number;
+    until?: number;
+    breakdown?: 'city' | 'country' | 'age' | 'gender';
+}
+/**
+ * Instagram media insights params
+ */
+interface InstagramMediaInsightsParams {
+    mediaId: string;
+    metric?: string[];
+}
+/**
+ * Instagram account summary
+ */
+interface InstagramAccountSummary {
+    id: string;
+    username: string;
+    followers_count: number;
+    views?: number;
+    reach?: number;
+    accounts_engaged?: number;
+    total_interactions?: number;
+}
+/**
+ * Instagram media insights data
+ */
+interface InstagramMediaInsights {
+    id: string;
+    media_type: 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM' | 'REELS';
+    views?: number;
+    reach?: number;
+    likes?: number;
+    comments?: number;
+    shares?: number;
+    saves?: number;
+    plays?: number;
+    total_interactions?: number;
+}
+/**
+ * Aggregated insights for a time period
+ */
+interface AggregatedInsights {
+    period: {
+        since: string;
+        until: string;
+    };
+    totals: {
+        views?: number;
+        reach?: number;
+        engagement?: number;
+        followers_gained?: number;
+        followers_lost?: number;
+    };
+    breakdown?: {
+        byDay?: Record<string, number>;
+        byContentType?: Record<string, number>;
+    };
+}
+/**
+ * Insights-specific error
+ */
+interface InsightsError {
+    metric: string;
+    error_code: number;
+    error_message: string;
+}
+
+export { type APIClient as A, INSTAGRAM_MEDIA_METRICS_COMMON as B, INSTAGRAM_REELS_METRICS as C, INSTAGRAM_STORIES_METRICS as D, INSIGHTS_PERIODS as E, type InsightsPeriod as F, type HttpClientConfig as H, type InsightValue as I, METRIC_PRESETS as M, type PageInsightsParams as P, type ReelsInsightsParams as R, type VideoInsightsParams as V, type InsightDataItem as a, type InsightBreakdown as b, type InsightsResponse as c, type PageOverview as d, type PostInsightsParams as e, type PostInsights as f, type VideoInsights as g, type VideoWithInsights as h, type ReelsInsights as i, type PhotoInsightsParams as j, type PhotoInsights as k, type InstagramAccountInsightsParams as l, type InstagramMediaInsightsParams as m, type InstagramAccountSummary as n, type InstagramMediaInsights as o, type AggregatedInsights as p, type InsightsError as q, PAGE_METRICS_LIFETIME as r, PAGE_METRICS_PERIODIC as s, POST_METRICS as t, VIDEO_METRICS as u, REELS_METRICS as v, REELS_METRICS_EXTENDED as w, PHOTO_METRICS as x, INSTAGRAM_ACCOUNT_METRICS as y, INSTAGRAM_DEMOGRAPHICS_METRICS as z };

package/dist/insights.types-DF2_r0L1.d.ts

@@ -0,0 +1,351 @@
+import { R as RequestOptions } from './auth.types-DTXCyA56.js';
+
+/**
+ * API Types - Interfaces for API clients
+ */
+
+/**
+ * Interface that each API client must implement
+ */
+interface APIClient {
+    /**
+     * Generic request
+     */
+    request<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+    /**
+     * GET request
+     */
+    get<T>(endpoint: string, params?: Record<string, any>): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(endpoint: string, body?: any): Promise<T>;
+    /**
+     * PUT request
+     */
+    put<T>(endpoint: string, body?: any): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T>(endpoint: string): Promise<T>;
+}
+/**
+ * HTTP client configuration
+ */
+interface HttpClientConfig {
+    baseURL: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    accessToken?: string;
+}
+
+/**
+ * Insights Constants - Metrics available for Facebook/Instagram APIs
+ * Updated for Graph API v24.0 (includes Nov 2025 changes)
+ *
+ * @see https://developers.facebook.com/docs/insights/guides
+ */
+/**
+ * Facebook Page metrics (lifetime)
+ * Note: 'page_fans' deprecated Nov 2025, use 'followers_count' field instead
+ */
+declare const PAGE_METRICS_LIFETIME: readonly ["page_fans_country", "page_fans_city", "page_fans_gender_age"];
+/**
+ * Facebook Page metrics (day/week/days_28)
+ * Note: 'page_impressions' deprecated Nov 2025, use 'page_views' instead
+ */
+declare const PAGE_METRICS_PERIODIC: readonly ["page_views_total", "page_views", "page_post_engagements", "page_fans_online", "page_fans_online_per_day", "page_video_views", "page_daily_follows", "page_daily_unfollows"];
+/**
+ * Post metrics (lifetime only)
+ * Note: 'post_impressions' deprecated, use 'post_views' equivalents
+ */
+declare const POST_METRICS: readonly ["post_engaged_users", "post_negative_feedback", "post_engaged_fan", "post_clicks", "post_clicks_unique", "post_reactions_by_type_total"];
+/**
+ * Video metrics (lifetime)
+ * Note: 'video_views' deprecated Apr 2024, use 'total_video_views'
+ */
+declare const VIDEO_METRICS: readonly ["total_video_views", "total_video_views_unique", "total_video_views_autoplayed", "total_video_views_clicked_to_play", "total_video_views_organic", "total_video_views_organic_unique", "total_video_views_paid", "total_video_views_paid_unique", "total_video_avg_time_watched", "total_video_view_total_time", "total_video_complete_views", "total_video_complete_views_unique", "total_video_complete_views_organic", "total_video_complete_views_organic_unique", "total_video_complete_views_paid", "total_video_complete_views_paid_unique"];
+/**
+ * Facebook Reels metrics (added Dec 2024)
+ * Available via Video Insights API
+ */
+declare const REELS_METRICS: readonly ["blue_reels_play_count", "post_video_avg_time_watched", "post_video_views", "post_video_social_actions"];
+/**
+ * Extended Reels metrics for detailed analysis
+ */
+declare const REELS_METRICS_EXTENDED: readonly ["plays", "comments", "likes", "shares", "reach", "total_plays", "average_minutes_viewed", "minutes_viewed"];
+/**
+ * Photo metrics (lifetime only)
+ */
+declare const PHOTO_METRICS: readonly ["photo_views", "photo_reach", "engaged_users"];
+/**
+ * Instagram account metrics (day/week/days_28)
+ * Note: 'impressions' deprecated Apr 2025, use 'views'
+ */
+declare const INSTAGRAM_ACCOUNT_METRICS: readonly ["views", "reach", "accounts_engaged", "total_interactions", "likes", "comments", "shares", "saves", "follows_and_unfollows", "profile_links_taps", "profile_views"];
+/**
+ * Instagram account metrics - Demographics
+ */
+declare const INSTAGRAM_DEMOGRAPHICS_METRICS: readonly ["follower_demographics", "reached_audience_demographics", "engaged_audience_demographics"];
+/**
+ * Instagram media metrics (all types)
+ */
+declare const INSTAGRAM_MEDIA_METRICS_COMMON: readonly ["views", "reach", "likes", "comments", "shares", "saved", "total_interactions"];
+/**
+ * Instagram Reels specific metrics
+ */
+declare const INSTAGRAM_REELS_METRICS: readonly ["plays", "reach", "likes", "comments", "shares", "saved", "total_interactions"];
+/**
+ * Instagram Stories specific metrics
+ */
+declare const INSTAGRAM_STORIES_METRICS: readonly ["exits", "replies", "taps_forward", "taps_back", "views", "reach"];
+declare const INSIGHTS_PERIODS: {
+    readonly DAY: "day";
+    readonly WEEK: "week";
+    readonly DAYS_28: "days_28";
+    readonly MONTH: "month";
+    readonly LIFETIME: "lifetime";
+};
+type InsightsPeriod = typeof INSIGHTS_PERIODS[keyof typeof INSIGHTS_PERIODS];
+/**
+ * Common metric presets for quick access
+ */
+declare const METRIC_PRESETS: {
+    readonly PAGE_OVERVIEW: readonly ["page_views_total", "page_post_engagements", "page_video_views"];
+    readonly VIDEO_PERFORMANCE: readonly ["total_video_views", "total_video_avg_time_watched", "total_video_complete_views"];
+    readonly REELS_PERFORMANCE: readonly ["blue_reels_play_count", "post_video_avg_time_watched", "post_video_social_actions"];
+    readonly INSTAGRAM_OVERVIEW: readonly ["views", "reach", "accounts_engaged", "total_interactions"];
+    readonly INSTAGRAM_ENGAGEMENT: readonly ["likes", "comments", "shares", "saves"];
+};
+
+/**
+ * Insights Types - Types for Facebook/Instagram Insights APIs
+ */
+
+/**
+ * Base insight value structure
+ */
+interface InsightValue {
+    value: number | Record<string, number>;
+    end_time?: string;
+}
+/**
+ * Base insight data item
+ */
+interface InsightDataItem {
+    id?: string;
+    name: string;
+    period: string;
+    values?: InsightValue[];
+    total_value?: {
+        value: number;
+        breakdowns?: InsightBreakdown[];
+    };
+    title?: string;
+    description?: string;
+}
+/**
+ * Insight breakdown structure
+ */
+interface InsightBreakdown {
+    dimension_keys: string[];
+    results: Array<{
+        dimension_values: string[];
+        value: number;
+        end_time?: string;
+    }>;
+}
+/**
+ * Generic insights response
+ */
+interface InsightsResponse {
+    data: InsightDataItem[];
+    paging?: {
+        previous?: string;
+        next?: string;
+    };
+}
+/**
+ * Page insights request params
+ */
+interface PageInsightsParams {
+    metric: string[];
+    period?: InsightsPeriod;
+    since?: number;
+    until?: number;
+    date_preset?: 'today' | 'yesterday' | 'this_week' | 'last_week' | 'this_month' | 'last_month';
+}
+/**
+ * Page overview data
+ */
+interface PageOverview {
+    id: string;
+    name: string;
+    followers_count: number;
+    fan_count?: number;
+    views_total?: number;
+    engagement?: number;
+}
+/**
+ * Post insights request params
+ */
+interface PostInsightsParams {
+    postId: string;
+    metric?: string[];
+}
+/**
+ * Post insights data
+ */
+interface PostInsights {
+    id: string;
+    views?: number;
+    reach?: number;
+    engaged_users?: number;
+    clicks?: number;
+    reactions_by_type?: Record<string, number>;
+    negative_feedback?: number;
+}
+/**
+ * Video insights request params
+ */
+interface VideoInsightsParams {
+    videoId: string;
+    metric?: string[];
+}
+/**
+ * Video insights data
+ */
+interface VideoInsights {
+    id: string;
+    total_views?: number;
+    unique_views?: number;
+    avg_time_watched?: number;
+    complete_views?: number;
+    organic_views?: number;
+    paid_views?: number;
+    total_time_watched?: number;
+}
+/**
+ * Video basic info with insights
+ */
+interface VideoWithInsights {
+    id: string;
+    title?: string;
+    description?: string;
+    created_time: string;
+    length?: number;
+    views?: number;
+    insights?: VideoInsights;
+}
+/**
+ * Reels insights request params
+ */
+interface ReelsInsightsParams {
+    reelId: string;
+    metric?: string[];
+}
+/**
+ * Reels insights data
+ */
+interface ReelsInsights {
+    id: string;
+    plays?: number;
+    total_plays?: number;
+    avg_time_watched?: number;
+    reach?: number;
+    likes?: number;
+    comments?: number;
+    shares?: number;
+    saves?: number;
+}
+/**
+ * Photo insights request params
+ */
+interface PhotoInsightsParams {
+    photoId: string;
+    metric?: string[];
+}
+/**
+ * Photo insights data
+ */
+interface PhotoInsights {
+    id: string;
+    views?: number;
+    reach?: number;
+    engaged_users?: number;
+}
+/**
+ * Instagram account insights params
+ */
+interface InstagramAccountInsightsParams {
+    metric: string[];
+    period?: InsightsPeriod;
+    metric_type?: 'time_series' | 'total_value';
+    since?: number;
+    until?: number;
+    breakdown?: 'city' | 'country' | 'age' | 'gender';
+}
+/**
+ * Instagram media insights params
+ */
+interface InstagramMediaInsightsParams {
+    mediaId: string;
+    metric?: string[];
+}
+/**
+ * Instagram account summary
+ */
+interface InstagramAccountSummary {
+    id: string;
+    username: string;
+    followers_count: number;
+    views?: number;
+    reach?: number;
+    accounts_engaged?: number;
+    total_interactions?: number;
+}
+/**
+ * Instagram media insights data
+ */
+interface InstagramMediaInsights {
+    id: string;
+    media_type: 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM' | 'REELS';
+    views?: number;
+    reach?: number;
+    likes?: number;
+    comments?: number;
+    shares?: number;
+    saves?: number;
+    plays?: number;
+    total_interactions?: number;
+}
+/**
+ * Aggregated insights for a time period
+ */
+interface AggregatedInsights {
+    period: {
+        since: string;
+        until: string;
+    };
+    totals: {
+        views?: number;
+        reach?: number;
+        engagement?: number;
+        followers_gained?: number;
+        followers_lost?: number;
+    };
+    breakdown?: {
+        byDay?: Record<string, number>;
+        byContentType?: Record<string, number>;
+    };
+}
+/**
+ * Insights-specific error
+ */
+interface InsightsError {
+    metric: string;
+    error_code: number;
+    error_message: string;
+}
+
+export { type APIClient as A, INSTAGRAM_MEDIA_METRICS_COMMON as B, INSTAGRAM_REELS_METRICS as C, INSTAGRAM_STORIES_METRICS as D, INSIGHTS_PERIODS as E, type InsightsPeriod as F, type HttpClientConfig as H, type InsightValue as I, METRIC_PRESETS as M, type PageInsightsParams as P, type ReelsInsightsParams as R, type VideoInsightsParams as V, type InsightDataItem as a, type InsightBreakdown as b, type InsightsResponse as c, type PageOverview as d, type PostInsightsParams as e, type PostInsights as f, type VideoInsights as g, type VideoWithInsights as h, type ReelsInsights as i, type PhotoInsightsParams as j, type PhotoInsights as k, type InstagramAccountInsightsParams as l, type InstagramMediaInsightsParams as m, type InstagramAccountSummary as n, type InstagramMediaInsights as o, type AggregatedInsights as p, type InsightsError as q, PAGE_METRICS_LIFETIME as r, PAGE_METRICS_PERIODIC as s, POST_METRICS as t, VIDEO_METRICS as u, REELS_METRICS as v, REELS_METRICS_EXTENDED as w, PHOTO_METRICS as x, INSTAGRAM_ACCOUNT_METRICS as y, INSTAGRAM_DEMOGRAPHICS_METRICS as z };