influship 0.2.0

package/resources/creators.d.mts

@@ -0,0 +1,364 @@
+import { APIResource } from "../core/resource.mjs";
+import * as CreatorsAPI from "./creators.mjs";
+import { APIPromise } from "../core/api-promise.mjs";
+import { RequestOptions } from "../internal/request-options.mjs";
+export declare class Creators extends APIResource {
+    /**
+     * Get creator-level information (person data) for one or multiple creators by
+     * their IDs.
+     *
+     * This endpoint returns basic creator profile data including name, bio, avatar,
+     * and status information. For platform-specific data (follower counts, engagement
+     * rates, etc.), use the `/v1/creators/{id}/profiles` endpoint.
+     *
+     * **Creator vs Profile Data:**
+     *
+     * - **Creator data**: Person-level information (name, bio, avatar, status)
+     * - **Profile data**: Platform-specific data (follower counts, engagement,
+     *   metrics)
+     *
+     * **Pricing**: 0.1 credits per creator profile returned
+     *
+     * @example
+     * ```ts
+     * const creator = await client.creators.retrieve({
+     *   creator_ids: 'creator_ids',
+     * });
+     * ```
+     */
+    retrieve(query: CreatorRetrieveParams, options?: RequestOptions): APIPromise<CreatorRetrieveResponse>;
+    /**
+     * Search creators by partial name or on-platform username for autocomplete
+     * suggestions.
+     *
+     * This endpoint searches across both global creator names and platform-specific
+     * usernames/display names from all platforms. Use the platform parameter to filter
+     * results to only show creators that have profiles on the specified platform.
+     *
+     * Use the scope parameter to control response granularity:
+     *
+     * - `creator_only`: Returns only creator profile data (id, name, avatar)
+     * - `matched_platforms`: Returns creator data + only the social accounts that
+     *   matched the search
+     * - `all_platforms`: Returns creator data + all social accounts (default)
+     *
+     * This endpoint is optimized for fast autocomplete functionality and returns
+     * lightweight results suitable for dropdown suggestions.
+     *
+     * **Pricing**: 0.001 credits per request
+     *
+     * @example
+     * ```ts
+     * const response = await client.creators.autocomplete({
+     *   q: 'fitness',
+     * });
+     * ```
+     */
+    autocomplete(query: CreatorAutocompleteParams, options?: RequestOptions): APIPromise<CreatorAutocompleteResponse>;
+    /**
+     * **EXPLORATION ENDPOINT**: Get all social account data when you know a creator
+     * UUID.
+     *
+     * **🎯 When to use this endpoint:**
+     *
+     * - ✅ You have a creator UUID (from `/v1/creators` or `/v1/profiles` response)
+     * - ✅ You want to see all social accounts for a creator (Instagram, TikTok, etc.)
+     * - ✅ You need comprehensive social account data for a creator
+     * - ✅ You want to explore all platforms a creator is on
+     *
+     * **❌ When NOT to use this endpoint:**
+     *
+     * - ❌ You only have a username and platform (use `/v1/profiles` instead)
+     * - ❌ You don't have a creator UUID (use `/v1/profiles` to discover first)
+     *
+     * **📊 Response Format:** Returns `SocialAccountLite` or `SocialAccountDetailed`
+     * objects with identical structure to `/v1/profiles`. Both endpoints return the
+     * same data structure for consistency.
+     *
+     * **🔗 Data Relationships:**
+     *
+     * - This endpoint requires a creator UUID (not a social account ID)
+     * - Use `creator_profile_id` from `/v1/profiles` response as the `{id}` parameter
+     * - Returns all social accounts associated with that creator
+     * - Filter by platform using the `platforms` query parameter
+     *
+     * **🔄 Typical Workflow:**
+     *
+     * 1. **Discovery**: Call `/v1/profiles` with username+platform → get social
+     *    account data + creator_profile_id
+     * 2. **All Accounts**: Call `/v1/creators/{creator_profile_id}/profiles` → get all
+     *    social accounts for that creator
+     * 3. **Creator Data**: Call `/v1/creators` with creator_profile_id → get
+     *    creator-level data
+     *
+     * **⚙️ Parameters:**
+     *
+     * - `mode`: `lite` (default) or `detailed` - controls response detail level
+     * - `platforms`: Comma-separated list of platforms to filter (e.g.,
+     *   `instagram,tiktok`) **Pricing**: 0.01-0.05 credits per social account
+     *   (lite/detailed mode)
+     *
+     * @example
+     * ```ts
+     * const response = await client.creators.listProfiles(
+     *   '123e4567-e89b-12d3-a456-426614174000',
+     * );
+     * ```
+     */
+    listProfiles(id: string, query?: CreatorListProfilesParams | null | undefined, options?: RequestOptions): APIPromise<CreatorListProfilesResponse>;
+}
+/**
+ * Basic creator information
+ */
+export interface Creator {
+    /**
+     * Unique creator identifier
+     */
+    id?: string;
+    /**
+     * Creator's avatar URL
+     */
+    avatar?: string | null;
+    /**
+     * Creator's bio text
+     */
+    bio?: string | null;
+    /**
+     * Creator's display name
+     */
+    name?: string | null;
+}
+/**
+ * Creator autocomplete result
+ */
+export interface CreatorAutocomplete {
+    /**
+     * Unique creator identifier
+     */
+    id: string;
+    /**
+     * Creator's avatar URL
+     */
+    avatar: string;
+    /**
+     * Creator's display name
+     */
+    name: string;
+    /**
+     * Matching social media platforms
+     */
+    platforms: Array<CreatorAutocomplete.Platform>;
+}
+export declare namespace CreatorAutocomplete {
+    interface Platform {
+        /**
+         * Display name on the platform
+         */
+        display_name: string;
+        /**
+         * Field that matched the search
+         */
+        match_field: string;
+        /**
+         * Type of match found
+         */
+        match_type: 'name' | 'username' | 'display_name';
+        /**
+         * Social media platform
+         */
+        platform: 'instagram' | 'tiktok';
+        /**
+         * Username on the platform
+         */
+        username: string;
+    }
+}
+/**
+ * Extended social account information with detailed metrics
+ */
+export interface SocialAccountDetailed extends SocialAccountLite {
+    /**
+     * Average comments per post from last 12 posts. null if account has <3 posts or is
+     * private.
+     */
+    avg_comments_recent?: number | null;
+    /**
+     * Average views per video post from recent content. null if no video posts or data
+     * unavailable.
+     */
+    avg_video_views_recent?: number | null;
+    /**
+     * Monthly follower growth rate (percentage). Positive = growth, negative =
+     * decline. null if account is <30 days old or insufficient data.
+     */
+    follower_change_rate_monthly_approx?: number | null;
+    /**
+     * Number of accounts this user follows. null if account is private.
+     */
+    following_count?: number | null;
+    /**
+     * Number of Instagram Story highlights. Instagram only. null for other platforms.
+     */
+    highlight_reel_count?: number | null;
+    /**
+     * Total posts published (photos, videos, carousels). null if unavailable.
+     */
+    media_count?: number | null;
+    /**
+     * Platform-assigned category (e.g., "Health & Fitness"). null if not set or
+     * platform doesn't provide categories.
+     */
+    platform_category_name?: string | null;
+}
+/**
+ * Basic social account information returned in lite mode
+ */
+export interface SocialAccountLite {
+    /**
+     * Unique social account identifier
+     */
+    id: string;
+    /**
+     * Account bio
+     */
+    bio: string | null;
+    /**
+     * Creator UUID this social account belongs to. Use with `/v1/creators` for
+     * person-level data (name, bio, avatar) or `/v1/creators/{id}/profiles` for all
+     * social accounts.
+     */
+    creator_profile_id: string;
+    /**
+     * Display name on the platform
+     */
+    display_name: string;
+    /**
+     * Social media platform
+     */
+    platform: 'instagram' | 'tiktok';
+    /**
+     * Username on the platform
+     */
+    username: string;
+    /**
+     * Whether the account has platform verification (blue checkmark).
+     */
+    verified: boolean;
+    /**
+     * Profile picture URL
+     */
+    avatar_url?: string | null;
+    /**
+     * Engagement rate percentage (0-100). Formula: (avg_likes + avg_comments) /
+     * follower_count × 100. Based on last 12 posts. null if account is private or has
+     * <3 posts.
+     */
+    engagement_rate?: number | null;
+    /**
+     * External website URL
+     */
+    external_url?: string | null;
+    /**
+     * Total number of followers on this platform. null if data is unavailable or
+     * account is private.
+     */
+    follower_count?: number | null;
+}
+export interface CreatorRetrieveResponse {
+    creators?: Array<CreatorRetrieveResponse.CreatorWithProfiles | Creator>;
+}
+export declare namespace CreatorRetrieveResponse {
+    /**
+     * Creator with embedded social account profiles
+     */
+    interface CreatorWithProfiles extends CreatorsAPI.Creator {
+        /**
+         * Social account profiles for this creator
+         */
+        profiles: Array<CreatorsAPI.SocialAccountLite | CreatorsAPI.SocialAccountDetailed>;
+    }
+}
+export interface CreatorAutocompleteResponse {
+    count?: number;
+    ok?: boolean;
+    results?: Array<CreatorAutocompleteResponse.Result>;
+}
+export declare namespace CreatorAutocompleteResponse {
+    interface Result {
+        id?: string;
+        avatar?: string;
+        name?: string;
+        platforms?: Array<Result.Platform>;
+    }
+    namespace Result {
+        interface Platform {
+            display_name?: string;
+            match_field?: string;
+            match_type?: 'name' | 'username' | 'display_name';
+            platform?: string;
+            username?: string;
+        }
+    }
+}
+export interface CreatorListProfilesResponse {
+    /**
+     * Array of social account objects. The structure depends on the `mode` parameter:
+     *
+     * - If `mode: "lite"`: Returns SocialAccountLite objects
+     * - If `mode: "detailed"`: Returns SocialAccountDetailed objects with additional
+     *   fields
+     */
+    profiles?: Array<SocialAccountLite | SocialAccountDetailed>;
+}
+export interface CreatorRetrieveParams {
+    /**
+     * Comma-separated list of creator UUIDs
+     */
+    creator_ids: string;
+    /**
+     * Whether to include social account profiles for each creator
+     */
+    include_profiles?: boolean;
+    /**
+     * Detail level for included profiles (only used when include_profiles=true)
+     */
+    profile_mode?: 'lite' | 'detailed';
+    /**
+     * Comma-separated list of platforms to include (instagram, tiktok). Only used when
+     * include_profiles=true
+     */
+    profile_platforms?: string;
+}
+export interface CreatorAutocompleteParams {
+    /**
+     * Search query text (partial name/username)
+     */
+    q: string;
+    /**
+     * Maximum number of results to return
+     */
+    limit?: number;
+    /**
+     * Filter results to only show creators that have profiles on this specific
+     * platform. If not provided, returns creators from all platforms.
+     */
+    platform?: 'instagram' | 'tiktok';
+    /**
+     * Control the granularity of returned data
+     */
+    scope?: 'creator_only' | 'matched_platforms' | 'all_platforms';
+}
+export interface CreatorListProfilesParams {
+    /**
+     * Response detail level
+     */
+    mode?: 'lite' | 'detailed';
+    /**
+     * Comma-separated list of platforms to include (instagram, tiktok)
+     */
+    platforms?: string;
+}
+export declare namespace Creators {
+    export { type Creator as Creator, type CreatorAutocomplete as CreatorAutocomplete, type SocialAccountDetailed as SocialAccountDetailed, type SocialAccountLite as SocialAccountLite, type CreatorRetrieveResponse as CreatorRetrieveResponse, type CreatorAutocompleteResponse as CreatorAutocompleteResponse, type CreatorListProfilesResponse as CreatorListProfilesResponse, type CreatorRetrieveParams as CreatorRetrieveParams, type CreatorAutocompleteParams as CreatorAutocompleteParams, type CreatorListProfilesParams as CreatorListProfilesParams, };
+}
+//# sourceMappingURL=creators.d.mts.map

package/resources/creators.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creators.d.mts","sourceRoot":"","sources":["../src/resources/creators.ts"],"names":[],"mappings":"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"}