instagram-graph-api-sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,2225 @@
+import { AxiosRequestConfig } from 'axios';
+
+/**
+ * Common Types for Instagram Graph API SDK
+ */
+/**
+ * SDK Configuration options
+ */
+interface InstagramClientConfig {
+    /** Instagram User access token */
+    accessToken: string;
+    /** API version (default: 'v22.0') */
+    apiVersion?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Pagination cursor for API responses
+ */
+interface PagingCursors {
+    before?: string;
+    after?: string;
+}
+/**
+ * Pagination info for list responses
+ */
+interface Paging {
+    cursors?: PagingCursors;
+    next?: string;
+    previous?: string;
+}
+/**
+ * Generic paginated response
+ */
+interface PaginatedResponse<T> {
+    data: T[];
+    paging?: Paging;
+}
+/**
+ * Generic single item response
+ */
+interface SingleResponse<T> {
+    data: T;
+}
+/**
+ * Success response for mutations
+ */
+interface SuccessResponse {
+    success: boolean;
+}
+/**
+ * ID response for creates
+ */
+interface IdResponse {
+    id: string;
+}
+/**
+ * Fields parameter type (comma-separated list)
+ */
+type FieldsParam = string | string[];
+/**
+ * Convert fields to comma-separated string
+ */
+declare function formatFields(fields?: FieldsParam): string | undefined;
+/**
+ * Base options for list requests
+ */
+interface ListOptions {
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Pagination cursor (after) */
+    after?: string;
+    /** Pagination cursor (before) */
+    before?: string;
+}
+/**
+ * Options with fields selection
+ */
+interface FieldsOptions {
+    /** Fields to include in response */
+    fields?: FieldsParam;
+}
+/**
+ * Combined list options with fields
+ */
+interface ListWithFieldsOptions extends ListOptions, FieldsOptions {
+}
+/**
+ * Time period for insights
+ */
+type InsightsPeriod = 'day' | 'week' | 'days_28' | 'month' | 'lifetime';
+/**
+ * Metric breakdown type
+ */
+type MetricBreakdown = 'age' | 'city' | 'country' | 'gender';
+
+/**
+ * HTTP Client for Instagram Graph API
+ *
+ * Axios-based HTTP client with interceptors for authentication,
+ * error handling, and rate limiting.
+ */
+
+/**
+ * HTTP Client configuration options
+ */
+interface HttpClientConfig {
+    /** Instagram User access token */
+    accessToken: string;
+    /** API version (e.g., 'v22.0') */
+    apiVersion: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Custom headers */
+    headers?: Record<string, string>;
+}
+/**
+ * HTTP Client for making requests to Instagram Graph API
+ */
+declare class HttpClient {
+    private readonly client;
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    /**
+     * Set up request and response interceptors
+     */
+    private setupInterceptors;
+    /**
+     * Update access token
+     */
+    setAccessToken(accessToken: string): void;
+    /**
+     * GET request
+     */
+    get<T>(path: string, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(path: string, data?: Record<string, unknown>, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T>(path: string, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * POST with form data (for file uploads)
+     */
+    postForm<T>(path: string, data: Record<string, unknown>, config?: AxiosRequestConfig): Promise<T>;
+}
+
+/**
+ * Media Types for Instagram Graph API SDK
+ */
+
+/**
+ * Media type
+ */
+type MediaType = 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM';
+/**
+ * Media product type
+ */
+type MediaProductType = 'FEED' | 'REELS' | 'STORY';
+/**
+ * Instagram Media object
+ */
+interface IGMedia {
+    /** The Media's ID */
+    id: string;
+    /** Caption text */
+    caption?: string;
+    /** Media type */
+    media_type?: MediaType;
+    /** Media product type (FEED, REELS, STORY) */
+    media_product_type?: MediaProductType;
+    /** URL to the media */
+    media_url?: string;
+    /** Permalink to the media on Instagram */
+    permalink?: string;
+    /** Thumbnail URL (for videos) */
+    thumbnail_url?: string;
+    /** ISO 8601 timestamp */
+    timestamp?: string;
+    /** Username of the owner */
+    username?: string;
+    /** Like count */
+    like_count?: number;
+    /** Comments count */
+    comments_count?: number;
+    /** Is comments enabled */
+    is_comment_enabled?: boolean;
+    /** Is shared to feed */
+    is_shared_to_feed?: boolean;
+    /** Owner ID */
+    owner?: {
+        id: string;
+    };
+    /** Shortcode */
+    shortcode?: string;
+}
+/**
+ * Available fields for IGMedia
+ */
+declare const IG_MEDIA_FIELDS: readonly ["id", "caption", "media_type", "media_product_type", "media_url", "permalink", "thumbnail_url", "timestamp", "username", "like_count", "comments_count", "is_comment_enabled", "is_shared_to_feed", "owner", "shortcode"];
+type IGMediaField = (typeof IG_MEDIA_FIELDS)[number];
+/**
+ * Carousel child media
+ */
+interface IGMediaChild {
+    id: string;
+    media_type?: MediaType;
+    media_url?: string;
+    timestamp?: string;
+}
+/**
+ * Media collaborator
+ */
+interface MediaCollaborator {
+    id: string;
+    username?: string;
+}
+/**
+ * Product tag on media
+ */
+interface ProductTag {
+    product_id: string;
+    merchant_id?: string;
+    name?: string;
+    image_url?: string;
+    x?: number;
+    y?: number;
+}
+/**
+ * Media children response
+ */
+type MediaChildrenResponse = PaginatedResponse<IGMediaChild>;
+/**
+ * Get media options
+ */
+interface GetMediaOptions {
+    fields?: IGMediaField[];
+}
+/**
+ * Get media children options
+ */
+interface GetMediaChildrenOptions {
+    fields?: string[];
+}
+
+/**
+ * User Types for Instagram Graph API SDK
+ */
+
+/**
+ * Instagram User account type
+ */
+type IGAccountType = 'BUSINESS' | 'MEDIA_CREATOR' | 'PERSONAL';
+/**
+ * Instagram User profile fields
+ */
+interface IGUser {
+    /** The User's ID */
+    id: string;
+    /** The User's account type */
+    account_type?: IGAccountType;
+    /** The User's biography */
+    biography?: string;
+    /** The number of followers */
+    followers_count?: number;
+    /** The number of accounts following */
+    follows_count?: number;
+    /** The number of media objects */
+    media_count?: number;
+    /** The User's username */
+    username?: string;
+    /** The User's name */
+    name?: string;
+    /** The User's profile picture URL */
+    profile_picture_url?: string;
+    /** The User's website */
+    website?: string;
+    /** Instagram user ID */
+    ig_id?: number;
+}
+/**
+ * Available fields for IGUser
+ */
+declare const IG_USER_FIELDS: readonly ["id", "account_type", "biography", "followers_count", "follows_count", "media_count", "username", "name", "profile_picture_url", "website", "ig_id"];
+type IGUserField = (typeof IG_USER_FIELDS)[number];
+/**
+ * Business Discovery response
+ */
+interface BusinessDiscovery {
+    business_discovery: Partial<IGUser> & {
+        media?: PaginatedResponse<IGMedia>;
+    };
+    id: string;
+}
+/**
+ * Content publishing limit
+ */
+interface ContentPublishingLimit {
+    quota_usage: number;
+    config: {
+        quota_total: number;
+        quota_duration: number;
+    };
+}
+/**
+ * User mentions response
+ */
+interface UserMention {
+    id: string;
+    timestamp?: string;
+    caption?: string;
+    media_type?: string;
+    media_url?: string;
+    permalink?: string;
+    username?: string;
+}
+/**
+ * Recently searched hashtag
+ */
+interface RecentlySearchedHashtag {
+    id: string;
+    name?: string;
+}
+/**
+ * Available catalog
+ */
+interface AvailableCatalog {
+    catalog_id: string;
+    catalog_name?: string;
+    shop_name?: string;
+    product_count?: number;
+}
+/**
+ * Catalog product
+ */
+interface CatalogProduct {
+    product_id: string;
+    merchant_id?: string;
+    product_name?: string;
+    image_url?: string;
+    retailer_id?: string;
+    review_status?: string;
+    is_checkout_flow?: boolean;
+}
+/**
+ * User profile request options
+ */
+interface GetUserProfileOptions {
+    fields?: IGUserField[];
+}
+/**
+ * User media request options
+ */
+interface GetUserMediaOptions {
+    fields?: string[];
+    limit?: number;
+    after?: string;
+    before?: string;
+}
+/**
+ * Business discovery options
+ */
+interface BusinessDiscoveryOptions {
+    username: string;
+    fields?: string[];
+}
+
+/**
+ * Auth API Module
+ *
+ * Handles authentication and token operations.
+ */
+
+/**
+ * Token response from Instagram API
+ */
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+}
+/**
+ * Long-lived token response
+ */
+interface LongLivedTokenResponse$1 {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+}
+/**
+ * Auth API class for Instagram authentication operations
+ */
+declare class AuthApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get current user information
+     * @param fields - Fields to retrieve
+     */
+    me(fields?: string): Promise<IGUser>;
+    /**
+     * Refresh a long-lived token (Instagram Login)
+     * Returns a new long-lived token with 60 days expiry
+     */
+    refreshToken(): Promise<LongLivedTokenResponse$1>;
+    /**
+     * Exchange short-lived token for long-lived token (Instagram Login)
+     * @param shortLivedToken - Short-lived access token (1 hour expiry)
+     * @param appSecret - Instagram App Secret
+     */
+    exchangeToken(shortLivedToken: string, appSecret: string): Promise<LongLivedTokenResponse$1>;
+}
+
+/**
+ * OAuth Types
+ *
+ * Types for Instagram Business Login OAuth flow.
+ */
+/**
+ * Available Instagram Business Login scopes
+ */
+type InstagramScope = 'instagram_business_basic' | 'instagram_business_manage_messages' | 'instagram_business_manage_comments' | 'instagram_business_content_publish' | 'instagram_business_manage_insights';
+/**
+ * OAuth configuration for your Instagram app
+ */
+interface OAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+}
+/**
+ * Parameters for building the authorization URL
+ */
+interface AuthorizationUrlParams {
+    /** Your Instagram App ID */
+    clientId: string;
+    /** Must exactly match one of your Valid OAuth Redirect URIs */
+    redirectUri: string;
+    /** List of permissions to request */
+    scopes: InstagramScope[];
+    /** Optional CSRF protection state */
+    state?: string;
+    /** Response type, always 'code' */
+    responseType?: 'code';
+    /** Force re-authentication even if user has active session */
+    forceReauth?: boolean;
+}
+/**
+ * Parameters for exchanging authorization code for tokens
+ */
+interface ExchangeCodeParams {
+    /** Your Instagram App ID */
+    clientId: string;
+    /** Your Instagram App Secret */
+    clientSecret: string;
+    /** Authorization code from callback (will be cleaned of #_ suffix) */
+    code: string;
+    /** Must exactly match the redirect_uri used in authorization */
+    redirectUri: string;
+}
+/**
+ * Short-lived token response from Instagram API
+ * Valid for 1 hour
+ */
+interface ShortLivedTokenResponse {
+    access_token: string;
+    user_id: string;
+    permissions: string;
+}
+/**
+ * Long-lived token response from Instagram API
+ * Valid for 60 days
+ */
+interface LongLivedTokenResponse {
+    access_token: string;
+    token_type: string;
+    /** Token lifetime in seconds (typically ~5184000 for 60 days) */
+    expires_in: number;
+}
+/**
+ * Complete OAuth token response with user info
+ * Returned by exchangeCodeForToken()
+ */
+interface OAuthTokenResponse {
+    /** Long-lived access token (60 days) */
+    access_token: string;
+    token_type: string;
+    /** Token lifetime in seconds */
+    expires_in: number;
+    /** Instagram User ID */
+    user_id: string;
+}
+/**
+ * OAuth error response from Instagram
+ */
+interface OAuthError {
+    error: string;
+    error_reason?: string;
+    error_description?: string;
+}
+/**
+ * OAuth callback parameters (parsed from redirect URL)
+ */
+interface OAuthCallbackParams {
+    /** Authorization code (if successful) */
+    code?: string;
+    /** State parameter (if provided in authorization request) */
+    state?: string;
+    /** Error type (if user denied or error occurred) */
+    error?: string;
+    /** Error reason */
+    error_reason?: string;
+    /** Human-readable error description */
+    error_description?: string;
+}
+
+/**
+ * Instagram OAuth Module
+ *
+ * Static methods for Instagram Business Login OAuth flow.
+ * These methods don't require an access token.
+ *
+ * @example
+ * ```typescript
+ * import { InstagramOAuth } from 'instagram-graph-api-sdk';
+ *
+ * // 1. Build authorization URL
+ * const authUrl = InstagramOAuth.buildAuthorizationUrl({
+ *   clientId: 'your-app-id',
+ *   redirectUri: 'https://your-app.com/callback',
+ *   scopes: ['instagram_business_basic', 'instagram_business_manage_messages'],
+ *   state: 'csrf-token',
+ * });
+ *
+ * // 2. Redirect user to authUrl...
+ *
+ * // 3. In callback, exchange code for token
+ * const tokens = await InstagramOAuth.exchangeCodeForToken({
+ *   clientId: 'your-app-id',
+ *   clientSecret: 'your-app-secret',
+ *   code: 'code-from-callback',
+ *   redirectUri: 'https://your-app.com/callback',
+ * });
+ *
+ * console.log(tokens.access_token); // Long-lived token (60 days)
+ * console.log(tokens.user_id);      // Instagram User ID
+ * ```
+ */
+
+/**
+ * Instagram OAuth - Static methods for authentication flow
+ *
+ * Use these methods for user onboarding (Instagram Business Login).
+ * After obtaining a token, create an InstagramClient instance to make API calls.
+ */
+declare class InstagramOAuth {
+    /**
+     * Build the Instagram authorization URL
+     *
+     * Direct users to this URL to start the OAuth flow.
+     * They will be asked to grant permissions to your app.
+     *
+     * @param params - Authorization URL parameters
+     * @returns Full authorization URL to redirect user to
+     *
+     * @example
+     * ```typescript
+     * const url = InstagramOAuth.buildAuthorizationUrl({
+     *   clientId: process.env.INSTAGRAM_APP_ID,
+     *   redirectUri: `${process.env.APP_URL}/api/instagram/callback`,
+     *   scopes: [
+     *     'instagram_business_basic',
+     *     'instagram_business_manage_messages',
+     *   ],
+     *   state: crypto.randomUUID(), // CSRF protection
+     * });
+     *
+     * // Redirect user to url
+     * ```
+     */
+    static buildAuthorizationUrl(params: AuthorizationUrlParams): string;
+    /**
+     * Parse OAuth callback parameters from URL
+     *
+     * Use this to extract code, state, and error info from the callback URL.
+     *
+     * @param url - The callback URL (or just the search params)
+     * @returns Parsed callback parameters
+     *
+     * @example
+     * ```typescript
+     * const params = InstagramOAuth.parseCallback(request.url);
+     *
+     * if (params.error) {
+     *   // User denied access
+     *   console.log(params.error_description);
+     * } else {
+     *   // Exchange code for token
+     *   const tokens = await InstagramOAuth.exchangeCodeForToken({
+     *     code: params.code!,
+     *     ...
+     *   });
+     * }
+     * ```
+     */
+    static parseCallback(url: string): OAuthCallbackParams;
+    /**
+     * Exchange authorization code for tokens
+     *
+     * This is the recommended method - it handles the full flow:
+     * 1. Exchange code for short-lived token (1 hour)
+     * 2. Exchange short-lived for long-lived token (60 days)
+     *
+     * @param params - Exchange parameters
+     * @returns Long-lived token response with user ID
+     * @throws Error if exchange fails
+     *
+     * @example
+     * ```typescript
+     * const tokens = await InstagramOAuth.exchangeCodeForToken({
+     *   clientId: process.env.INSTAGRAM_APP_ID!,
+     *   clientSecret: process.env.INSTAGRAM_APP_SECRET!,
+     *   code: codeFromCallback,
+     *   redirectUri: `${process.env.APP_URL}/api/instagram/callback`,
+     * });
+     *
+     * // Store tokens.access_token and tokens.user_id in your database
+     * // Token expires in tokens.expires_in seconds (~60 days)
+     * ```
+     */
+    static exchangeCodeForToken(params: ExchangeCodeParams): Promise<OAuthTokenResponse>;
+    /**
+     * Get short-lived token from authorization code
+     *
+     * Use this if you need more control over the token exchange process.
+     * The short-lived token is valid for 1 hour.
+     *
+     * @param params - Exchange parameters
+     * @returns Short-lived token response
+     * @throws Error if exchange fails
+     */
+    static getShortLivedToken(params: ExchangeCodeParams): Promise<ShortLivedTokenResponse>;
+    /**
+     * Exchange short-lived token for long-lived token
+     *
+     * Long-lived tokens are valid for 60 days and can be refreshed.
+     *
+     * @param params - Exchange parameters
+     * @returns Long-lived token response
+     * @throws Error if exchange fails
+     */
+    static getLongLivedToken(params: {
+        clientSecret: string;
+        accessToken: string;
+    }): Promise<LongLivedTokenResponse>;
+    /**
+     * Get the default scopes for Instagram Business Login
+     *
+     * @returns Array of commonly used scopes
+     */
+    static getDefaultScopes(): InstagramScope[];
+    /**
+     * Get all available Instagram Business Login scopes
+     *
+     * @returns Array of all available scopes
+     */
+    static getAllScopes(): InstagramScope[];
+}
+
+/**
+ * Users API Module
+ *
+ * Handles all user-related API operations.
+ */
+
+/**
+ * Users API class for Instagram user operations
+ */
+declare class UsersApi {
+    private readonly http;
+    private readonly userId;
+    constructor(http: HttpClient, userId: string);
+    /**
+     * Get user profile information
+     * @param options - Fields to retrieve
+     */
+    getProfile(options?: GetUserProfileOptions): Promise<IGUser>;
+    /**
+     * Get user's media
+     * @param options - Pagination and fields options
+     */
+    getMedia(options?: GetUserMediaOptions): Promise<PaginatedResponse<IGMedia>>;
+    /**
+     * Get user's stories
+     */
+    getStories(): Promise<PaginatedResponse<IGMedia>>;
+    /**
+     * Get user's live media
+     */
+    getLiveMedia(): Promise<PaginatedResponse<IGMedia>>;
+    /**
+     * Get content publishing limit (quota usage)
+     */
+    getContentPublishingLimit(): Promise<ContentPublishingLimit>;
+    /**
+     * Discover another business account by username
+     * @param options - Username and fields to retrieve
+     */
+    getBusinessDiscovery(options: BusinessDiscoveryOptions): Promise<BusinessDiscovery>;
+    /**
+     * Get media where user is mentioned
+     */
+    getMentionedMedia(): Promise<PaginatedResponse<IGMedia>>;
+    /**
+     * Get comments where user is mentioned
+     */
+    getMentionedComment(): Promise<PaginatedResponse<{
+        id: string;
+        text?: string;
+    }>>;
+    /**
+     * Get media user is tagged in
+     */
+    getTags(): Promise<PaginatedResponse<IGMedia>>;
+    /**
+     * Get recently searched hashtags
+     */
+    getRecentlySearchedHashtags(): Promise<PaginatedResponse<RecentlySearchedHashtag>>;
+    /**
+     * Get available product catalogs
+     */
+    getAvailableCatalogs(): Promise<PaginatedResponse<AvailableCatalog>>;
+    /**
+     * Search products in a catalog
+     * @param catalogId - Catalog ID to search in
+     * @param query - Search query
+     */
+    searchCatalogProducts(catalogId: string, query: string): Promise<PaginatedResponse<CatalogProduct>>;
+}
+
+/**
+ * Comment Types for Instagram Graph API SDK
+ */
+/**
+ * Instagram Comment
+ */
+interface IGComment {
+    /** Comment ID */
+    id: string;
+    /** Comment text */
+    text?: string;
+    /** Username of commenter */
+    username?: string;
+    /** ISO 8601 timestamp */
+    timestamp?: string;
+    /** Like count */
+    like_count?: number;
+    /** Is comment hidden */
+    hidden?: boolean;
+    /** User who posted the comment */
+    from?: {
+        id: string;
+        username?: string;
+    };
+    /** Media this comment is on */
+    media?: {
+        id: string;
+    };
+    /** Parent comment (for replies) */
+    parent_id?: string;
+    /** Replies to this comment */
+    replies?: {
+        data: IGComment[];
+    };
+}
+/**
+ * Available fields for IGComment
+ */
+declare const IG_COMMENT_FIELDS: readonly ["id", "text", "username", "timestamp", "like_count", "hidden", "from", "media", "parent_id", "replies"];
+type IGCommentField = (typeof IG_COMMENT_FIELDS)[number];
+/**
+ * Get comments options
+ */
+interface GetCommentsOptions {
+    fields?: IGCommentField[];
+    limit?: number;
+    after?: string;
+}
+/**
+ * Reply to comment options
+ */
+interface ReplyToCommentOptions {
+    message: string;
+}
+/**
+ * Update comment options (hide/unhide)
+ */
+interface UpdateCommentOptions {
+    hide: boolean;
+}
+
+/**
+ * Insights Types for Instagram Graph API SDK
+ */
+/**
+ * Insight metric value
+ */
+interface InsightValue {
+    value: number | Record<string, number>;
+    end_time?: string;
+}
+/**
+ * Insight data point
+ */
+interface InsightData {
+    id: string;
+    name: string;
+    period: string;
+    values: InsightValue[];
+    title: string;
+    description: string;
+}
+/**
+ * Insights response
+ */
+interface InsightsResponse {
+    data: InsightData[];
+}
+/**
+ * Account insight metrics
+ * Updated to match current Instagram Graph API v22.0
+ */
+type AccountMetric = 'reach' | 'follower_count' | 'website_clicks' | 'profile_views' | 'online_followers' | 'accounts_engaged' | 'total_interactions' | 'likes' | 'comments' | 'shares' | 'saves' | 'replies' | 'engaged_audience_demographics' | 'reached_audience_demographics' | 'follower_demographics' | 'follows_and_unfollows' | 'profile_links_taps' | 'views';
+/**
+ * Media insight metrics
+ */
+type MediaMetric = 'engagement' | 'impressions' | 'reach' | 'saved' | 'video_views' | 'likes' | 'comments' | 'shares' | 'plays' | 'total_interactions';
+/**
+ * Insights period
+ */
+type InsightPeriod = 'day' | 'week' | 'days_28' | 'month' | 'lifetime';
+/**
+ * Get account insights options
+ */
+interface GetAccountInsightsOptions {
+    metric: AccountMetric[];
+    period?: InsightPeriod;
+    since?: number;
+    until?: number;
+    metric_type?: 'total_value' | 'time_series';
+    breakdown?: 'age' | 'city' | 'country' | 'gender';
+}
+/**
+ * Get media insights options
+ */
+interface GetMediaInsightsOptions {
+    metric: MediaMetric[];
+}
+/**
+ * Demographics breakdown
+ */
+interface DemographicsBreakdown {
+    [key: string]: number;
+}
+
+/**
+ * Media API Module
+ *
+ * Handles all media-related API operations.
+ */
+
+/**
+ * Media API class for Instagram media operations
+ */
+declare class MediaApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get media by ID
+     * @param mediaId - Media ID
+     * @param options - Fields to retrieve
+     */
+    get(mediaId: string, options?: GetMediaOptions): Promise<IGMedia>;
+    /**
+     * Get carousel children
+     * @param mediaId - Carousel media ID
+     * @param options - Fields to retrieve
+     */
+    getChildren(mediaId: string, options?: GetMediaChildrenOptions): Promise<PaginatedResponse<IGMediaChild>>;
+    /**
+     * Get comments on media
+     * @param mediaId - Media ID
+     * @param options - Pagination and fields options
+     */
+    getComments(mediaId: string, options?: GetCommentsOptions): Promise<PaginatedResponse<IGComment>>;
+    /**
+     * Get media insights
+     * @param mediaId - Media ID
+     * @param options - Metrics to retrieve
+     */
+    getInsights(mediaId: string, options: GetMediaInsightsOptions): Promise<InsightsResponse>;
+    /**
+     * Get media collaborators
+     * @param mediaId - Media ID
+     */
+    getCollaborators(mediaId: string): Promise<PaginatedResponse<MediaCollaborator>>;
+    /**
+     * Get product tags on media
+     * @param mediaId - Media ID
+     */
+    getProductTags(mediaId: string): Promise<PaginatedResponse<ProductTag>>;
+}
+
+/**
+ * Publishing Types for Instagram Graph API SDK
+ */
+/**
+ * Container media type for publishing
+ */
+type ContainerMediaType = 'IMAGE' | 'VIDEO' | 'REELS' | 'STORIES' | 'CAROUSEL';
+/**
+ * Container status code
+ */
+type ContainerStatusCode = 'EXPIRED' | 'ERROR' | 'FINISHED' | 'IN_PROGRESS' | 'PUBLISHED';
+/**
+ * Base container creation options
+ */
+interface BaseContainerOptions {
+    /** Caption for the media */
+    caption?: string;
+    /** Location tag ID */
+    location_id?: string;
+    /** User tags */
+    user_tags?: UserTag[];
+    /** Collaborators (creator accounts to invite) */
+    collaborators?: string[];
+    /** Alt text for accessibility */
+    alt_text?: string;
+}
+/**
+ * User tag for media
+ */
+interface UserTag {
+    username: string;
+    x?: number;
+    y?: number;
+}
+/**
+ * Image container creation options
+ */
+interface CreateImageContainerOptions extends BaseContainerOptions {
+    /** URL to the image (must be publicly accessible) */
+    image_url: string;
+    /** Whether this is a carousel item */
+    is_carousel_item?: boolean;
+}
+/**
+ * Video container creation options
+ */
+interface CreateVideoContainerOptions extends BaseContainerOptions {
+    /** URL to the video (must be publicly accessible) */
+    video_url: string;
+    /** Media type: VIDEO, REELS, or STORIES */
+    media_type: 'VIDEO' | 'REELS' | 'STORIES';
+    /** Whether to share reel to feed */
+    share_to_feed?: boolean;
+    /** Whether this is a carousel item */
+    is_carousel_item?: boolean;
+    /** Cover URL for video */
+    cover_url?: string;
+    /** Thumb offset for video cover (ms) */
+    thumb_offset?: number;
+    /** Audio name for reels */
+    audio_name?: string;
+}
+/**
+ * Carousel container creation options
+ */
+interface CreateCarouselContainerOptions extends BaseContainerOptions {
+    /** Array of child container IDs */
+    children: string[];
+}
+/**
+ * Resumable upload options
+ */
+interface ResumableUploadOptions extends BaseContainerOptions {
+    /** Media type: VIDEO, REELS, or STORIES */
+    media_type: 'VIDEO' | 'REELS' | 'STORIES';
+    /** Upload type */
+    upload_type: 'resumable';
+}
+/**
+ * Container creation response
+ */
+interface ContainerResponse {
+    id: string;
+}
+/**
+ * Container status response
+ */
+interface ContainerStatus {
+    id: string;
+    status_code?: ContainerStatusCode;
+    status?: string;
+}
+/**
+ * Publish response
+ */
+interface PublishResponse {
+    id: string;
+}
+/**
+ * Trial reel options
+ */
+interface TrialReelOptions {
+    /** Graduation strategy */
+    graduation_strategy: 'MANUAL' | 'SS_PERFORMANCE';
+}
+
+/**
+ * Publishing API Module
+ *
+ * Handles content publishing operations.
+ */
+
+/**
+ * Publishing API class for content publishing operations
+ */
+declare class PublishingApi {
+    private readonly http;
+    private readonly userId;
+    constructor(http: HttpClient, userId: string);
+    /**
+     * Create an image container
+     * @param options - Image URL and optional caption, location, tags
+     */
+    createImageContainer(options: CreateImageContainerOptions): Promise<ContainerResponse>;
+    /**
+     * Create a video/reel/story container
+     * @param options - Video URL, media type, and optional settings
+     */
+    createVideoContainer(options: CreateVideoContainerOptions): Promise<ContainerResponse>;
+    /**
+     * Create a carousel container
+     * @param options - Child container IDs and optional caption
+     */
+    createCarouselContainer(options: CreateCarouselContainerOptions): Promise<ContainerResponse>;
+    /**
+     * Create a resumable upload session
+     * @param options - Media type and settings
+     */
+    createResumableUpload(options: ResumableUploadOptions): Promise<ContainerResponse>;
+    /**
+     * Get container status
+     * @param containerId - Container ID
+     */
+    getContainerStatus(containerId: string): Promise<ContainerStatus>;
+    /**
+     * Publish a container
+     * @param containerId - Container ID to publish
+     */
+    publishContainer(containerId: string): Promise<PublishResponse>;
+    /**
+     * Wait for container to be ready, then publish
+     * @param containerId - Container ID
+     * @param maxAttempts - Maximum number of status checks (default: 30)
+     * @param intervalMs - Interval between checks in ms (default: 2000)
+     */
+    waitAndPublish(containerId: string, maxAttempts?: number, intervalMs?: number): Promise<PublishResponse>;
+}
+
+/**
+ * Messaging Types for Instagram Graph API SDK
+ */
+/**
+ * Message recipient
+ */
+interface MessageRecipient {
+    /** Instagram-scoped user ID */
+    id?: string;
+    /** Comment ID for private replies */
+    comment_id?: string;
+}
+/**
+ * Message attachment type
+ */
+type AttachmentType = 'image' | 'video' | 'audio' | 'file' | 'template' | 'like_heart' | 'MEDIA_SHARE';
+/**
+ * Message attachment payload
+ */
+interface AttachmentPayload {
+    /** URL of the attachment */
+    url?: string;
+    /** Attachment ID (for uploaded assets) */
+    attachment_id?: string;
+    /** Media ID (for MEDIA_SHARE) */
+    id?: string;
+    /** Template type */
+    template_type?: 'generic' | 'button';
+    /** Template elements */
+    elements?: TemplateElement[];
+    /** Button template text */
+    text?: string;
+    /** Buttons */
+    buttons?: TemplateButton[];
+}
+/**
+ * Message attachment
+ */
+interface MessageAttachment {
+    type: AttachmentType;
+    payload?: AttachmentPayload;
+}
+/**
+ * Template element for generic template
+ */
+interface TemplateElement {
+    title: string;
+    subtitle?: string;
+    image_url?: string;
+    default_action?: {
+        type: 'web_url';
+        url: string;
+    };
+    buttons?: TemplateButton[];
+}
+/**
+ * Template button
+ */
+interface TemplateButton {
+    type: 'web_url' | 'postback';
+    title: string;
+    url?: string;
+    payload?: string;
+}
+/**
+ * Quick reply
+ */
+interface QuickReply {
+    content_type: 'text' | 'user_phone_number' | 'user_email';
+    title?: string;
+    payload?: string;
+}
+/**
+ * Message content
+ */
+interface MessageContent {
+    /** Text message */
+    text?: string;
+    /** Attachment */
+    attachment?: MessageAttachment;
+    /** Quick replies */
+    quick_replies?: QuickReply[];
+}
+/**
+ * Send message request
+ */
+interface SendMessageRequest {
+    recipient: MessageRecipient;
+    message?: MessageContent;
+    /** Sender action (react, unreact) */
+    sender_action?: 'react' | 'unreact' | 'typing_on' | 'typing_off' | 'mark_seen';
+    /** Payload for reactions */
+    payload?: {
+        message_id: string;
+        reaction?: 'love' | 'like' | 'laugh' | 'wow' | 'sad' | 'angry';
+    };
+    /** Messaging type */
+    messaging_type?: 'RESPONSE' | 'UPDATE' | 'MESSAGE_TAG';
+    /** Message tag for outside 24hr window */
+    tag?: 'HUMAN_AGENT';
+}
+/**
+ * Send message response
+ */
+interface SendMessageResponse {
+    recipient_id: string;
+    message_id: string;
+}
+/**
+ * Conversation
+ */
+interface Conversation {
+    id: string;
+    updated_time?: string;
+}
+/**
+ * Conversation message
+ */
+interface ConversationMessage {
+    id: string;
+    created_time?: string;
+    from?: {
+        id: string;
+        username?: string;
+    };
+    to?: {
+        data: Array<{
+            id: string;
+            username?: string;
+        }>;
+    };
+    message?: string;
+    is_unsupported?: boolean;
+}
+/**
+ * Get conversations options
+ */
+interface GetConversationsOptions {
+    platform?: 'instagram';
+    user_id?: string;
+    limit?: number;
+    after?: string;
+}
+/**
+ * Send text message options
+ */
+interface SendTextOptions {
+    /** Use HUMAN_AGENT tag (7 day window) */
+    humanAgent?: boolean;
+}
+/**
+ * Send media message options
+ */
+interface SendMediaOptions {
+    /** Media type */
+    type: 'image' | 'video' | 'audio';
+    /** URL to the media */
+    url: string;
+}
+/**
+ * Generic template options
+ */
+interface GenericTemplateOptions {
+    elements: TemplateElement[];
+}
+/**
+ * Button template options
+ */
+interface ButtonTemplateOptions {
+    text: string;
+    buttons: TemplateButton[];
+}
+/**
+ * Quick replies options
+ */
+interface QuickRepliesOptions {
+    text: string;
+    replies: QuickReply[];
+}
+/**
+ * Reaction type
+ */
+type ReactionType = 'love' | 'like' | 'laugh' | 'wow' | 'sad' | 'angry';
+
+/**
+ * Messaging API Module
+ *
+ * Handles all messaging operations (Send API).
+ */
+
+/**
+ * Messaging API class for Instagram messaging operations
+ */
+declare class MessagingApi {
+    private readonly http;
+    private readonly userId;
+    constructor(http: HttpClient, userId: string);
+    /**
+     * Send a text message
+     * @param recipientId - Instagram-scoped user ID (IGSID)
+     * @param text - Message text
+     * @param options - Optional settings (humanAgent for 7-day window)
+     */
+    sendText(recipientId: string, text: string, options?: SendTextOptions): Promise<SendMessageResponse>;
+    /**
+     * Send a media message (image, video, audio)
+     * @param recipientId - Instagram-scoped user ID
+     * @param options - Media type and URL
+     */
+    sendMedia(recipientId: string, options: SendMediaOptions): Promise<SendMessageResponse>;
+    /**
+     * Send a sticker (like_heart)
+     * @param recipientId - Instagram-scoped user ID
+     */
+    sendLikeHeart(recipientId: string): Promise<SendMessageResponse>;
+    /**
+     * Send a generic template
+     * @param recipientId - Instagram-scoped user ID
+     * @param options - Template elements
+     */
+    sendGenericTemplate(recipientId: string, options: GenericTemplateOptions): Promise<SendMessageResponse>;
+    /**
+     * Send a button template
+     * @param recipientId - Instagram-scoped user ID
+     * @param options - Text and buttons
+     */
+    sendButtonTemplate(recipientId: string, options: ButtonTemplateOptions): Promise<SendMessageResponse>;
+    /**
+     * Send quick replies
+     * @param recipientId - Instagram-scoped user ID
+     * @param options - Text and quick reply options
+     */
+    sendQuickReplies(recipientId: string, options: QuickRepliesOptions): Promise<SendMessageResponse>;
+    /**
+     * Send a private reply to a comment
+     * @param commentId - Comment ID to reply to
+     * @param message - Message text
+     */
+    sendPrivateReply(commentId: string, message: string): Promise<SendMessageResponse>;
+    /**
+     * Share a published post via message
+     * @param recipientId - Instagram-scoped user ID
+     * @param mediaId - Media ID of the post to share
+     */
+    sendMediaShare(recipientId: string, mediaId: string): Promise<SendMessageResponse>;
+    /**
+     * React to a message
+     * @param recipientId - Instagram-scoped user ID
+     * @param messageId - Message ID to react to
+     * @param reaction - Reaction type
+     */
+    reactToMessage(recipientId: string, messageId: string, reaction: ReactionType): Promise<SendMessageResponse>;
+    /**
+     * Remove reaction from a message
+     * @param recipientId - Instagram-scoped user ID
+     * @param messageId - Message ID to unreact from
+     */
+    unreactToMessage(recipientId: string, messageId: string): Promise<SendMessageResponse>;
+    /**
+     * Send typing indicator
+     * @param recipientId - Instagram-scoped user ID
+     * @param typing - Whether to show typing (true) or stop (false)
+     */
+    sendTypingIndicator(recipientId: string, typing?: boolean): Promise<SendMessageResponse>;
+}
+
+/**
+ * Conversations API Module
+ *
+ * Handles conversation and message retrieval.
+ */
+
+/**
+ * Conversations API class for Instagram conversation operations
+ */
+declare class ConversationsApi {
+    private readonly http;
+    private readonly userId;
+    constructor(http: HttpClient, userId: string);
+    /**
+     * Get list of conversations
+     * @param options - Pagination and filter options
+     */
+    list(options?: GetConversationsOptions): Promise<PaginatedResponse<Conversation>>;
+    /**
+     * Find conversation with a specific user
+     * @param igsid - Instagram-scoped user ID
+     */
+    findByUser(igsid: string): Promise<PaginatedResponse<Conversation>>;
+    /**
+     * Get messages in a conversation
+     * @param conversationId - Conversation ID
+     * @param fields - Fields to retrieve (default: from,to)
+     */
+    getMessages(conversationId: string, fields?: string): Promise<{
+        messages: PaginatedResponse<ConversationMessage>;
+    }>;
+    /**
+     * Get a specific message
+     * @param messageId - Message ID
+     * @param fields - Fields to retrieve
+     */
+    getMessage(messageId: string, fields?: string): Promise<ConversationMessage>;
+}
+
+/**
+ * Comments API Module
+ *
+ * Handles comment moderation operations.
+ */
+
+/**
+ * Comments API class for Instagram comment operations
+ */
+declare class CommentsApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get comment by ID
+     * @param commentId - Comment ID
+     * @param fields - Fields to retrieve
+     */
+    get(commentId: string, fields?: IGCommentField[]): Promise<IGComment>;
+    /**
+     * Get replies to a comment
+     * @param commentId - Comment ID
+     * @param options - Pagination and fields options
+     */
+    getReplies(commentId: string, options?: GetCommentsOptions): Promise<PaginatedResponse<IGComment>>;
+    /**
+     * Reply to a comment
+     * @param commentId - Comment ID to reply to
+     * @param options - Reply message
+     */
+    reply(commentId: string, options: ReplyToCommentOptions): Promise<IdResponse>;
+    /**
+     * Hide a comment
+     * @param commentId - Comment ID
+     */
+    hide(commentId: string): Promise<SuccessResponse>;
+    /**
+     * Unhide a comment
+     * @param commentId - Comment ID
+     */
+    unhide(commentId: string): Promise<SuccessResponse>;
+    /**
+     * Delete a comment
+     * @param commentId - Comment ID
+     */
+    delete(commentId: string): Promise<SuccessResponse>;
+}
+
+/**
+ * Hashtag Types for Instagram Graph API SDK
+ */
+
+/**
+ * Instagram Hashtag
+ */
+interface IGHashtag {
+    /** Hashtag ID */
+    id: string;
+    /** Hashtag name (without #) */
+    name?: string;
+}
+/**
+ * Hashtag search options
+ */
+interface HashtagSearchOptions {
+    /** User ID for context */
+    user_id: string;
+    /** Search query (hashtag name without #) */
+    q: string;
+}
+/**
+ * Hashtag search response
+ */
+interface HashtagSearchResponse {
+    data: IGHashtag[];
+}
+/**
+ * Get hashtag media options
+ */
+interface GetHashtagMediaOptions {
+    /** User ID for context */
+    user_id: string;
+    /** Fields to return */
+    fields?: string[];
+    /** Maximum results */
+    limit?: number;
+    /** Pagination cursor */
+    after?: string;
+}
+/**
+ * Hashtag media response
+ */
+type HashtagMediaResponse = PaginatedResponse<IGMedia>;
+
+/**
+ * Hashtags API Module
+ *
+ * Handles hashtag search and media retrieval.
+ */
+
+/**
+ * Hashtags API class for Instagram hashtag operations
+ */
+declare class HashtagsApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Search for a hashtag
+     * @param options - User ID and search query
+     */
+    search(options: HashtagSearchOptions): Promise<HashtagSearchResponse>;
+    /**
+     * Get hashtag information
+     * @param hashtagId - Hashtag ID
+     */
+    get(hashtagId: string): Promise<IGHashtag>;
+    /**
+     * Get recent media with hashtag
+     * @param hashtagId - Hashtag ID
+     * @param options - User ID and pagination options
+     */
+    getRecentMedia(hashtagId: string, options: GetHashtagMediaOptions): Promise<HashtagMediaResponse>;
+    /**
+     * Get top media with hashtag
+     * @param hashtagId - Hashtag ID
+     * @param options - User ID and pagination options
+     */
+    getTopMedia(hashtagId: string, options: GetHashtagMediaOptions): Promise<HashtagMediaResponse>;
+}
+
+/**
+ * Insights API Module
+ *
+ * Handles account and media insights.
+ */
+
+/**
+ * Insights API class for Instagram analytics
+ */
+declare class InsightsApi {
+    private readonly http;
+    private readonly userId;
+    constructor(http: HttpClient, userId: string);
+    /**
+     * Get account insights
+     * @param options - Metrics, period, and breakdown options
+     */
+    getAccountInsights(options: GetAccountInsightsOptions): Promise<InsightsResponse>;
+    /**
+     * Get media insights
+     * @param mediaId - Media ID
+     * @param options - Metrics to retrieve
+     */
+    getMediaInsights(mediaId: string, options: GetMediaInsightsOptions): Promise<InsightsResponse>;
+}
+
+/**
+ * Welcome Flow Types for Instagram Graph API SDK
+ */
+/**
+ * Welcome message flow action
+ */
+interface FlowAction {
+    /** Action type */
+    type: 'QUICK_REPLY' | 'ICE_BREAKER' | 'CTA';
+    /** Title shown to user */
+    title?: string;
+    /** Payload sent back on click */
+    payload?: string;
+    /** URL for CTA actions */
+    url?: string;
+}
+/**
+ * Welcome message flow screen
+ */
+interface FlowScreen {
+    /** Screen ID */
+    id?: string;
+    /** Screen title */
+    title?: string;
+    /** Screen body text */
+    body?: string;
+    /** Actions on this screen */
+    actions?: FlowAction[];
+}
+/**
+ * Welcome message flow
+ */
+interface WelcomeMessageFlow {
+    /** Flow ID */
+    flow_id?: string;
+    /** Flow name */
+    name?: string;
+    /** Flow screens */
+    screens?: FlowScreen[];
+    /** Whether flow is active */
+    is_active?: boolean;
+    /** ISO 8601 timestamp */
+    created_time?: string;
+    /** ISO 8601 timestamp */
+    updated_time?: string;
+}
+/**
+ * Create/Update flow options
+ */
+interface WelcomeFlowOptions {
+    name: string;
+    screens: FlowScreen[];
+}
+/**
+ * Get flows response
+ */
+interface WelcomeFlowsResponse {
+    data: WelcomeMessageFlow[];
+}
+
+/**
+ * Welcome Flows API Module
+ *
+ * Handles welcome message flow operations.
+ */
+
+/**
+ * Welcome Flows API class for managing welcome message flows
+ */
+declare class WelcomeFlowsApi {
+    private readonly http;
+    private readonly userId;
+    constructor(http: HttpClient, userId: string);
+    /**
+     * Get all welcome message flows
+     */
+    list(): Promise<WelcomeFlowsResponse>;
+    /**
+     * Get a specific welcome message flow
+     * @param flowId - Flow ID
+     */
+    get(flowId: string): Promise<WelcomeMessageFlow>;
+    /**
+     * Create a new welcome message flow
+     * @param options - Flow name and screens
+     */
+    create(options: WelcomeFlowOptions): Promise<IdResponse>;
+    /**
+     * Update an existing welcome message flow
+     * @param flowId - Flow ID
+     * @param options - Updated flow name and screens
+     */
+    update(flowId: string, options: WelcomeFlowOptions): Promise<SuccessResponse>;
+    /**
+     * Delete a welcome message flow
+     * @param flowId - Flow ID
+     */
+    delete(flowId: string): Promise<SuccessResponse>;
+}
+
+/**
+ * Messenger Profile Types for Instagram Graph API SDK
+ * (Ice Breakers, Persistent Menu, etc.)
+ */
+/**
+ * Ice breaker question
+ */
+interface IceBreakerQuestion {
+    /** Question text shown to user */
+    question: string;
+    /** Payload sent back when clicked */
+    payload: string;
+}
+/**
+ * Ice breaker configuration
+ */
+interface IceBreaker {
+    /** Questions for this locale */
+    call_to_actions: IceBreakerQuestion[];
+    /** Locale code (e.g., 'en_US', 'zh_CN') */
+    locale?: string;
+}
+/**
+ * Set ice breakers options
+ */
+interface SetIceBreakersOptions {
+    /** Platform (always 'instagram') */
+    platform: 'instagram';
+    /** Ice breaker configurations */
+    ice_breakers: IceBreaker[];
+}
+/**
+ * Get ice breakers response
+ */
+interface IceBreakersResponse {
+    data: IceBreaker[];
+}
+/**
+ * Persistent menu button
+ */
+interface PersistentMenuButton {
+    type: 'web_url' | 'postback';
+    title: string;
+    url?: string;
+    payload?: string;
+}
+/**
+ * Persistent menu configuration
+ */
+interface PersistentMenu {
+    /** Locale code */
+    locale?: string;
+    /** Whether to disable user input */
+    composer_input_disabled?: boolean;
+    /** Menu buttons */
+    call_to_actions: PersistentMenuButton[];
+}
+/**
+ * Set persistent menu options
+ */
+interface SetPersistentMenuOptions {
+    /** Platform (always 'instagram') */
+    platform: 'instagram';
+    /** Persistent menu configurations */
+    persistent_menu: PersistentMenu[];
+}
+/**
+ * Sender action type
+ */
+type SenderAction = 'typing_on' | 'typing_off' | 'mark_seen';
+
+/**
+ * Messenger Profile API Module
+ *
+ * Handles Ice Breakers, Persistent Menu, and Sender Actions.
+ */
+
+/**
+ * Messenger Profile API class for managing ice breakers and persistent menu
+ */
+declare class MessengerProfileApi {
+    private readonly http;
+    private readonly userId;
+    constructor(http: HttpClient, userId: string);
+    /**
+     * Get current ice breakers
+     */
+    getIceBreakers(): Promise<IceBreakersResponse>;
+    /**
+     * Set ice breakers (FAQ questions)
+     * @param iceBreakers - Ice breaker configurations (max 4 questions per locale)
+     */
+    setIceBreakers(iceBreakers: IceBreaker[]): Promise<SuccessResponse>;
+    /**
+     * Delete ice breakers
+     */
+    deleteIceBreakers(): Promise<SuccessResponse>;
+    /**
+     * Get persistent menu
+     */
+    getPersistentMenu(): Promise<{
+        data: PersistentMenu[];
+    }>;
+    /**
+     * Set persistent menu
+     * @param menus - Persistent menu configurations
+     */
+    setPersistentMenu(menus: PersistentMenu[]): Promise<SuccessResponse>;
+    /**
+     * Delete persistent menu
+     */
+    deletePersistentMenu(): Promise<SuccessResponse>;
+}
+
+/**
+ * oEmbed Types for Instagram Graph API SDK
+ */
+/**
+ * oEmbed response
+ */
+interface OEmbedResponse {
+    /** oEmbed version */
+    version: string;
+    /** oEmbed type */
+    type: 'rich';
+    /** Title (usually username) */
+    title?: string;
+    /** Author name */
+    author_name?: string;
+    /** Author URL */
+    author_url?: string;
+    /** Provider name */
+    provider_name: 'Instagram';
+    /** Provider URL */
+    provider_url: string;
+    /** HTML embed code */
+    html: string;
+    /** Embed width */
+    width?: number;
+    /** Embed height */
+    height?: number | null;
+    /** Thumbnail URL */
+    thumbnail_url?: string;
+    /** Thumbnail width */
+    thumbnail_width?: number;
+    /** Thumbnail height */
+    thumbnail_height?: number;
+}
+/**
+ * Get oEmbed options
+ */
+interface GetOEmbedOptions {
+    /** Instagram post URL */
+    url: string;
+    /** Maximum width */
+    maxwidth?: number;
+    /** Hide caption */
+    hidecaption?: boolean;
+    /** Omit script */
+    omitscript?: boolean;
+}
+
+/**
+ * oEmbed API Module
+ *
+ * Handles oEmbed operations for embedding Instagram content.
+ */
+
+/**
+ * oEmbed API class for embedding Instagram content
+ */
+declare class OEmbedApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get oEmbed data for an Instagram URL
+     * @param options - URL and optional formatting options
+     */
+    get(options: GetOEmbedOptions): Promise<OEmbedResponse>;
+}
+
+interface WebhookEntry {
+    id: string;
+    time: number;
+    changes?: WebhookChange[];
+    messaging?: WebhookMessagingEvent[];
+}
+interface WebhookChange {
+    field: 'comments' | 'live_comments' | 'mentions' | 'messages' | 'message_reactions' | 'messaging_seen';
+    value: any;
+}
+interface WebhookMessagingEvent {
+    sender: {
+        id: string;
+    };
+    recipient: {
+        id: string;
+    };
+    timestamp: number;
+    message?: {
+        mid: string;
+        text?: string;
+        attachments?: any[];
+        is_deleted?: boolean;
+        is_echo?: boolean;
+        reply_to?: {
+            mid: string;
+        };
+    };
+    reaction?: {
+        mid: string;
+        action: 'react' | 'unreact';
+        reaction: string;
+        emoji: string;
+    };
+    read?: {
+        mid: string;
+    };
+}
+interface WebhookPayload {
+    object: 'instagram';
+    entry: WebhookEntry[];
+}
+interface SubscribedFieldsResponse {
+    data: {
+        link: string;
+        name: string;
+        id: string;
+        category: string;
+        subscribed_fields: string[];
+    }[];
+}
+
+declare class WebhooksApi {
+    private readonly http;
+    private readonly userId;
+    constructor(http: HttpClient, userId: string);
+    /**
+     * Subscribe your app to specific fields for this user/page.
+     *
+     * @param fields List of fields to subscribe to (e.g., ['messages', 'comments'])
+     */
+    subscribe(fields: string[]): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Unsubscribe from specific fields or all fields.
+     *
+     * @param fields Optional list of fields to unsubscribe from. If empty, unsubscribes from all.
+     */
+    unsubscribe(fields?: string[]): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get the list of fields your app is currently subscribed to.
+     */
+    getSubscribedFields(): Promise<SubscribedFieldsResponse>;
+}
+
+/**
+ * Instagram Graph API SDK - Main Client
+ *
+ * Type-safe TypeScript SDK for Instagram Graph API with Instagram Login.
+ *
+ * @example
+ * ```typescript
+ * import { InstagramClient } from 'instagram-graph-api-sdk';
+ *
+ * const client = new InstagramClient({
+ *   accessToken: 'your-access-token',
+ *   apiVersion: 'v22.0', // optional, defaults to 'v22.0'
+ * });
+ *
+ * // Get user profile
+ * const profile = await client.users.getProfile({ fields: ['id', 'username'] });
+ * console.log(profile);
+ * ```
+ */
+
+/**
+ * Instagram Graph API Client
+ *
+ * Main entry point for the SDK. Provides access to all API modules.
+ */
+declare class InstagramClient {
+    private readonly http;
+    private readonly config;
+    private cachedUserId;
+    /** Authentication API - Token management */
+    readonly auth: AuthApi;
+    /** Users API - Profile, media, insights */
+    readonly users: UsersApi;
+    /** Media API - Get media, children, comments */
+    readonly media: MediaApi;
+    /** Publishing API - Publish images, videos, reels */
+    readonly publishing: PublishingApi;
+    /** Messaging API - Send messages, templates */
+    readonly messaging: MessagingApi;
+    /** Conversations API - List conversations, messages */
+    readonly conversations: ConversationsApi;
+    /** Comments API - Moderation */
+    readonly comments: CommentsApi;
+    /** Hashtags API - Search, media */
+    readonly hashtags: HashtagsApi;
+    /** Insights API - Analytics */
+    readonly insights: InsightsApi;
+    /** Welcome Flows API - Welcome message flows */
+    readonly welcomeFlows: WelcomeFlowsApi;
+    /** Messenger Profile API - Ice breakers, menu */
+    readonly messengerProfile: MessengerProfileApi;
+    /** oEmbed API - Embed content */
+    readonly oembed: OEmbedApi;
+    /** Webhooks API - Manage subscriptions */
+    readonly webhooks: WebhooksApi;
+    /**
+     * Create a new Instagram client
+     * @param config - Client configuration
+     */
+    constructor(config: InstagramClientConfig);
+    /**
+     * Get the current user ID
+     * Fetches from API if not cached
+     */
+    getUserId(): Promise<string>;
+    /**
+     * Update the access token
+     * @param accessToken - New access token
+     */
+    setAccessToken(accessToken: string): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): Readonly<Required<InstagramClientConfig>>;
+    /**
+     * Get the API version
+     */
+    getApiVersion(): string;
+}
+
+/**
+ * Instagram API Error Classes
+ *
+ * Custom error classes for handling Instagram Graph API errors.
+ */
+/**
+ * Base error class for Instagram API errors
+ */
+declare class InstagramAPIError extends Error {
+    readonly code: number;
+    readonly type: string;
+    readonly subcode?: number;
+    readonly fbTraceId?: string;
+    constructor(message: string, code: number, type: string, subcode?: number, fbTraceId?: string);
+    /**
+     * Create an InstagramAPIError from an API response
+     */
+    static fromResponse(response: InstagramErrorResponse): InstagramAPIError;
+}
+/**
+ * Authentication error (invalid/expired tokens)
+ */
+declare class AuthenticationError extends InstagramAPIError {
+    constructor(message: string, code?: number, fbTraceId?: string);
+}
+/**
+ * Rate limit exceeded error
+ */
+declare class RateLimitError extends InstagramAPIError {
+    readonly retryAfter?: number;
+    constructor(message: string, code?: number, fbTraceId?: string, retryAfter?: number);
+}
+/**
+ * Validation error (invalid parameters)
+ */
+declare class ValidationError extends InstagramAPIError {
+    constructor(message: string, code?: number, subcode?: number, fbTraceId?: string);
+}
+/**
+ * Network error (connection issues)
+ */
+declare class NetworkError extends Error {
+    readonly originalError?: Error;
+    constructor(message: string, originalError?: Error);
+}
+/**
+ * Instagram API error response structure
+ */
+interface InstagramErrorResponse {
+    error: {
+        message: string;
+        type: string;
+        code: number;
+        error_subcode?: number;
+        fbtrace_id?: string;
+    };
+}
+/**
+ * Check if an error is an Instagram API error
+ */
+declare function isInstagramAPIError(error: unknown): error is InstagramAPIError;
+/**
+ * Check if an error is an authentication error
+ */
+declare function isAuthenticationError(error: unknown): error is AuthenticationError;
+/**
+ * Check if an error is a rate limit error
+ */
+declare function isRateLimitError(error: unknown): error is RateLimitError;
+/**
+ * Check if an error is a validation error
+ */
+declare function isValidationError(error: unknown): error is ValidationError;
+
+/**
+ * Instagram Graph API Endpoints
+ *
+ * Centralized endpoint definitions for easy maintenance.
+ * Update this file when Instagram API documentation changes.
+ *
+ * Base URL: https://graph.instagram.com
+ * API Version: Configurable (default: v22.0)
+ */
+declare const INSTAGRAM_BASE_URL = "https://graph.instagram.com";
+/**
+ * Build a full API URL with version
+ */
+declare function buildUrl(version: string, path: string): string;
+/**
+ * User Endpoints
+ */
+declare const USER_ENDPOINTS: {
+    /** Get user profile: GET /{user-id} */
+    readonly PROFILE: (userId: string) => string;
+    /** Get user media: GET /{user-id}/media */
+    readonly MEDIA: (userId: string) => string;
+    /** Get user stories: GET /{user-id}/stories */
+    readonly STORIES: (userId: string) => string;
+    /** Get user insights: GET /{user-id}/insights */
+    readonly INSIGHTS: (userId: string) => string;
+    /** Get live media: GET /{user-id}/live_media */
+    readonly LIVE_MEDIA: (userId: string) => string;
+    /** Get content publishing limit: GET /{user-id}/content_publishing_limit */
+    readonly CONTENT_PUBLISHING_LIMIT: (userId: string) => string;
+    /** Get business discovery: GET /{user-id}?fields=business_discovery.username(...) */
+    readonly BUSINESS_DISCOVERY: (userId: string) => string;
+    /** Get mentioned media: GET /{user-id}/mentioned_media */
+    readonly MENTIONED_MEDIA: (userId: string) => string;
+    /** Get mentioned comment: GET /{user-id}/mentioned_comment */
+    readonly MENTIONED_COMMENT: (userId: string) => string;
+    /** Get tags: GET /{user-id}/tags */
+    readonly TAGS: (userId: string) => string;
+    /** Get recently searched hashtags: GET /{user-id}/recently_searched_hashtags */
+    readonly RECENTLY_SEARCHED_HASHTAGS: (userId: string) => string;
+    /** Get available catalogs: GET /{user-id}/available_catalogs */
+    readonly AVAILABLE_CATALOGS: (userId: string) => string;
+    /** Search catalog products: GET /{user-id}/catalog_product_search */
+    readonly CATALOG_PRODUCT_SEARCH: (userId: string) => string;
+};
+/**
+ * Media Endpoints
+ */
+declare const MEDIA_ENDPOINTS: {
+    /** Get media by ID: GET /{media-id} */
+    readonly GET: (mediaId: string) => string;
+    /** Get media children (carousel): GET /{media-id}/children */
+    readonly CHILDREN: (mediaId: string) => string;
+    /** Get media comments: GET /{media-id}/comments */
+    readonly COMMENTS: (mediaId: string) => string;
+    /** Get media insights: GET /{media-id}/insights */
+    readonly INSIGHTS: (mediaId: string) => string;
+    /** Get media collaborators: GET /{media-id}/collaborators */
+    readonly COLLABORATORS: (mediaId: string) => string;
+    /** Get product tags: GET /{media-id}/product_tags */
+    readonly PRODUCT_TAGS: (mediaId: string) => string;
+};
+/**
+ * Publishing Endpoints
+ */
+declare const PUBLISHING_ENDPOINTS: {
+    /** Create media container: POST /{user-id}/media */
+    readonly CREATE_CONTAINER: (userId: string) => string;
+    /** Publish media: POST /{user-id}/media_publish */
+    readonly PUBLISH: (userId: string) => string;
+    /** Get container status: GET /{container-id} */
+    readonly CONTAINER_STATUS: (containerId: string) => string;
+};
+/**
+ * Messaging Endpoints
+ */
+declare const MESSAGING_ENDPOINTS: {
+    /** Send message: POST /{user-id}/messages */
+    readonly SEND: (userId: string) => string;
+    /** Get conversations: GET /{user-id}/conversations */
+    readonly CONVERSATIONS: (userId: string) => string;
+    /** Get conversation by ID: GET /{conversation-id} */
+    readonly CONVERSATION: (conversationId: string) => string;
+    /** Get message by ID: GET /{message-id} */
+    readonly MESSAGE: (messageId: string) => string;
+};
+/**
+ * Welcome Message Flow Endpoints
+ */
+declare const WELCOME_FLOW_ENDPOINTS: {
+    /** Get/Create/Update flows: /{user-id}/welcome_message_flows */
+    readonly FLOWS: (userId: string) => string;
+};
+/**
+ * Messenger Profile Endpoints (Ice Breakers, Persistent Menu)
+ */
+declare const MESSENGER_PROFILE_ENDPOINTS: {
+    /** Get/Set/Delete profile: /{user-id}/messenger_profile */
+    readonly PROFILE: (userId: string) => string;
+};
+/**
+ * Comment Endpoints
+ */
+declare const COMMENT_ENDPOINTS: {
+    /** Get comment: GET /{comment-id} */
+    readonly GET: (commentId: string) => string;
+    /** Get replies: GET /{comment-id}/replies */
+    readonly REPLIES: (commentId: string) => string;
+    /** Reply to comment: POST /{comment-id}/replies */
+    readonly REPLY: (commentId: string) => string;
+    /** Hide/Unhide comment: POST /{comment-id} */
+    readonly UPDATE: (commentId: string) => string;
+    /** Delete comment: DELETE /{comment-id} */
+    readonly DELETE: (commentId: string) => string;
+};
+/**
+ * Hashtag Endpoints
+ */
+declare const HASHTAG_ENDPOINTS: {
+    /** Search hashtag: GET /ig_hashtag_search */
+    readonly SEARCH: "/ig_hashtag_search";
+    /** Get hashtag: GET /{hashtag-id} */
+    readonly GET: (hashtagId: string) => string;
+    /** Get recent media: GET /{hashtag-id}/recent_media */
+    readonly RECENT_MEDIA: (hashtagId: string) => string;
+    /** Get top media: GET /{hashtag-id}/top_media */
+    readonly TOP_MEDIA: (hashtagId: string) => string;
+};
+/**
+ * Auth Endpoints (require access token)
+ */
+declare const AUTH_ENDPOINTS: {
+    /** Get current user: GET /me */
+    readonly ME: "/me";
+    /** Refresh token: GET /refresh_access_token */
+    readonly REFRESH_TOKEN: "/refresh_access_token";
+    /** Exchange token: GET /access_token */
+    readonly ACCESS_TOKEN: "/access_token";
+};
+/**
+ * OAuth Endpoints (for Instagram Business Login)
+ * Note: These use different base URLs than the Graph API
+ */
+declare const OAUTH_ENDPOINTS: {
+    /** Authorization URL - redirect users here to start OAuth flow */
+    readonly AUTHORIZE: "https://www.instagram.com/oauth/authorize";
+    /** Short-lived token exchange: POST with form data */
+    readonly TOKEN: "https://api.instagram.com/oauth/access_token";
+    /** Long-lived token exchange: GET with query params */
+    readonly LONG_LIVED_TOKEN: "https://graph.instagram.com/access_token";
+};
+/**
+ * oEmbed Endpoints
+ */
+declare const OEMBED_ENDPOINTS: {
+    /** Get oEmbed: GET /instagram_oembed */
+    readonly GET: "/instagram_oembed";
+};
+
+declare class InstagramWebhooks {
+    /**
+     * Verify that the webhook request came from Meta.
+     * Calculates SHA256 HMAC of the raw body using the App Secret.
+     *
+     * @param body Raw request body as string
+     * @param signature Signature from X-Hub-Signature-256 header (e.g., "sha256=...")
+     * @param appSecret Your Instagram App Secret
+     * @returns true if signature is valid
+     */
+    static verifySignature(body: string, signature: string, appSecret: string): boolean;
+    /**
+     * Type guard and parser for webhook payloads.
+     *
+     * @param body Parsed JSON body
+     * @returns Typed WebhookPayload or throws error
+     */
+    static parsePayload(body: any): WebhookPayload;
+}
+
+export { AUTH_ENDPOINTS, type AccountMetric, type AttachmentPayload, type AttachmentType, AuthApi, AuthenticationError, type AuthorizationUrlParams, type AvailableCatalog, type BaseContainerOptions, type BusinessDiscovery, type BusinessDiscoveryOptions, type ButtonTemplateOptions, COMMENT_ENDPOINTS, type CatalogProduct, CommentsApi, type ContainerMediaType, type ContainerResponse, type ContainerStatus, type ContainerStatusCode, type ContentPublishingLimit, type Conversation, type ConversationMessage, ConversationsApi, type CreateCarouselContainerOptions, type CreateImageContainerOptions, type CreateVideoContainerOptions, type DemographicsBreakdown, type ExchangeCodeParams, type FieldsOptions, type FieldsParam, type FlowAction, type FlowScreen, type GenericTemplateOptions, type GetAccountInsightsOptions, type GetCommentsOptions, type GetConversationsOptions, type GetHashtagMediaOptions, type GetMediaChildrenOptions, type GetMediaInsightsOptions, type GetMediaOptions, type GetOEmbedOptions, type GetUserMediaOptions, type GetUserProfileOptions, HASHTAG_ENDPOINTS, type HashtagMediaResponse, type HashtagSearchOptions, type HashtagSearchResponse, HashtagsApi, HttpClient, type HttpClientConfig, type IGAccountType, type IGComment, type IGCommentField, type IGHashtag, type IGMedia, type IGMediaChild, type IGMediaField, type IGUser, type IGUserField, IG_COMMENT_FIELDS, IG_MEDIA_FIELDS, IG_USER_FIELDS, INSTAGRAM_BASE_URL, type IceBreaker, type IceBreakerQuestion, type IceBreakersResponse, type IdResponse, type InsightData, type InsightPeriod, type InsightValue, InsightsApi, type InsightsPeriod, type InsightsResponse, InstagramAPIError, InstagramClient, type InstagramClientConfig, type InstagramErrorResponse, InstagramOAuth, type InstagramScope, InstagramWebhooks, type ListOptions, type ListWithFieldsOptions, type LongLivedTokenResponse$1 as LongLivedTokenResponse, MEDIA_ENDPOINTS, MESSAGING_ENDPOINTS, MESSENGER_PROFILE_ENDPOINTS, MediaApi, type MediaChildrenResponse, type MediaCollaborator, type MediaMetric, type MediaProductType, type MediaType, type MessageAttachment, type MessageContent, type MessageRecipient, MessagingApi, MessengerProfileApi, type MetricBreakdown, NetworkError, OAUTH_ENDPOINTS, type OAuthCallbackParams, type OAuthConfig, type OAuthError, type ShortLivedTokenResponse as OAuthShortLivedTokenResponse, type OAuthTokenResponse, OEMBED_ENDPOINTS, OEmbedApi, type OEmbedResponse, PUBLISHING_ENDPOINTS, type PaginatedResponse, type Paging, type PagingCursors, type PersistentMenu, type PersistentMenuButton, type ProductTag, type PublishResponse, PublishingApi, type QuickRepliesOptions, type QuickReply, RateLimitError, type ReactionType, type RecentlySearchedHashtag, type ReplyToCommentOptions, type ResumableUploadOptions, type SendMediaOptions, type SendMessageRequest, type SendMessageResponse, type SendTextOptions, type SenderAction, type SetIceBreakersOptions, type SetPersistentMenuOptions, type ShortLivedTokenResponse, type SingleResponse, type SubscribedFieldsResponse, type SuccessResponse, type TemplateButton, type TemplateElement, type TokenResponse, type TrialReelOptions, USER_ENDPOINTS, type UpdateCommentOptions, type UserMention, type UserTag, UsersApi, ValidationError, WELCOME_FLOW_ENDPOINTS, type WebhookChange, type WebhookEntry, type WebhookMessagingEvent, type WebhookPayload, WebhooksApi, type WelcomeFlowOptions, WelcomeFlowsApi, type WelcomeFlowsResponse, type WelcomeMessageFlow, buildUrl, formatFields, isAuthenticationError, isInstagramAPIError, isRateLimitError, isValidationError };