influship 0.2.0 → 0.3.1

package/resources/creators.d.mts

@@ -1,51 +1,52 @@
 import { APIResource } from "../core/resource.mjs";
-import * as CreatorsAPI from "./creators.mjs";
+import * as Shared from "./shared.mjs";
 import { APIPromise } from "../core/api-promise.mjs";
+import { BodyCursor, type BodyCursorParams, PagePromise } from "../core/pagination.mjs";
 import { RequestOptions } from "../internal/request-options.mjs";
+/**
+ * Retrieve creator profiles and discover new creators through search, autocomplete, and lookalike matching. Creators are cross-platform entities that may have profiles on multiple social networks.
+ */
 export declare class Creators extends APIResource {
     /**
-     * Get creator-level information (person data) for one or multiple creators by
-     * their IDs.
+     * Retrieve a creator's profile including AI-generated summary, content themes, and
+     * optionally their linked social profiles.
      *
-     * 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.
+     * **What is a Creator?** A creator is a cross-platform entity representing a
+     * person or brand. They may have profiles on multiple social networks (Instagram,
+     * YouTube, TikTok, etc.) that are linked together.
      *
-     * **Creator vs Profile Data:**
+     * **Include options:**
      *
-     * - **Creator data**: Person-level information (name, bio, avatar, status)
-     * - **Profile data**: Platform-specific data (follower counts, engagement,
-     *   metrics)
+     * - `profiles`: Include all linked social profiles with metrics
      *
-     * **Pricing**: 0.1 credits per creator profile returned
+     * **Pricing**: 0.1 credits per request ($0.001)
      *
      * @example
      * ```ts
-     * const creator = await client.creators.retrieve({
-     *   creator_ids: 'creator_ids',
-     * });
+     * const creator = await client.creators.retrieve(
+     *   '123e4567-e89b-12d3-a456-426614174000',
+     *   { include: ['profiles'] },
+     * );
      * ```
      */
-    retrieve(query: CreatorRetrieveParams, options?: RequestOptions): APIPromise<CreatorRetrieveResponse>;
+    retrieve(id: string, query: CreatorRetrieveParams, options?: RequestOptions): APIPromise<CreatorRetrieveResponse>;
     /**
-     * Search creators by partial name or on-platform username for autocomplete
-     * suggestions.
+     * Fast typeahead search for creators by name or username. Optimized for
+     * search-as-you-type UIs with sub-100ms response times.
      *
-     * 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.
+     * **Matching behavior:**
      *
-     * Use the scope parameter to control response granularity:
+     * - Matches against creator name, username, and display name
+     * - Results include which field matched and the matching value
+     * - Prefix matching (e.g., "fit" matches "fitness_coach")
      *
-     * - `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)
+     * **Scope options:**
      *
-     * This endpoint is optimized for fast autocomplete functionality and returns
-     * lightweight results suitable for dropdown suggestions.
+     * - `creator_only`: Return only the creator entity
+     * - `matched_platforms`: Return only profiles that matched the query
+     * - `all_platforms`: Return all linked profiles (default)
      *
-     * **Pricing**: 0.001 credits per request
+     * **Pricing**: 0.05 credits per request ($0.0005)
      *
      * @example
      * ```ts
@@ -56,309 +57,387 @@ export declare class Creators extends APIResource {
      */
     autocomplete(query: CreatorAutocompleteParams, options?: RequestOptions): APIPromise<CreatorAutocompleteResponse>;
     /**
-     * **EXPLORATION ENDPOINT**: Get all social account data when you know a creator
-     * UUID.
+     * Find creators similar to provided seed creators using AI-powered similarity
+     * matching. Analyzes content themes, audience overlap, posting style, and
+     * engagement patterns.
      *
-     * **🎯 When to use this endpoint:**
+     * **Use cases:**
      *
-     * - ✅ 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
+     * - Expand campaigns with creators similar to proven performers
+     * - Find alternatives when preferred creators are unavailable
+     * - Discover emerging creators in the same niche
      *
-     * **❌ When NOT to use this endpoint:**
+     * **How it works:**
      *
-     * - ❌ You only have a username and platform (use `/v1/profiles` instead)
-     * - ❌ You don't have a creator UUID (use `/v1/profiles` to discover first)
+     * 1. Provide 1-10 seed creators (by ID or platform/username)
+     * 2. Optionally weight seeds to prioritize certain creators
+     * 3. Get ranked results with similarity scores and shared traits
      *
-     * **📊 Response Format:** Returns `SocialAccountLite` or `SocialAccountDetailed`
-     * objects with identical structure to `/v1/profiles`. Both endpoints return the
-     * same data structure for consistency.
+     * **Pricing**: 1.5 credits per creator returned ($0.015)
      *
-     * **🔗 Data Relationships:**
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const creatorLookalikeResponse of client.creators.lookalike(
+     *   { seeds: [{}] },
+     * )) {
+     *   // ...
+     * }
+     * ```
+     */
+    lookalike(body: CreatorLookalikeParams, options?: RequestOptions): PagePromise<CreatorLookalikeResponsesBodyCursor, CreatorLookalikeResponse>;
+    /**
+     * Evaluate how well creators match a specific campaign using AI analysis. Returns
+     * a fit score (0-1), decision recommendation (good/neutral/avoid), and
+     * evidence-based explanations.
      *
-     * - 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
+     * **Use cases:**
      *
-     * **🔄 Typical Workflow:**
+     * - Vet shortlisted creators before outreach
+     * - Rank candidates for a specific campaign
+     * - Get AI-generated talking points for why a creator fits
      *
-     * 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
+     * **How it works:**
      *
-     * **⚙️ Parameters:**
+     * 1. Describe your campaign intent and target audience
+     * 2. Provide up to 100 creators to evaluate
+     * 3. Get detailed scores with explanations and evidence
      *
-     * - `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)
+     * **Pricing**: 1 credit per creator scored ($0.01)
      *
      * @example
      * ```ts
-     * const response = await client.creators.listProfiles(
-     *   '123e4567-e89b-12d3-a456-426614174000',
-     * );
+     * const response = await client.creators.match({
+     *   creators: [{}],
+     *   intent: {
+     *     query:
+     *       'Looking for fitness influencers to promote our new protein bar',
+     *   },
+     * });
      * ```
      */
-    listProfiles(id: string, query?: CreatorListProfilesParams | null | undefined, options?: RequestOptions): APIPromise<CreatorListProfilesResponse>;
+    match(body: CreatorMatchParams, options?: RequestOptions): APIPromise<CreatorMatchResponse>;
 }
-/**
- * Basic creator information
- */
-export interface Creator {
-    /**
-     * Unique creator identifier
-     */
-    id?: string;
-    /**
-     * Creator's avatar URL
-     */
-    avatar?: string | null;
+export type CreatorLookalikeResponsesBodyCursor = BodyCursor<CreatorLookalikeResponse>;
+export interface CreatorRetrieveResponse {
     /**
-     * Creator's bio text
+     * Full creator details
      */
-    bio?: string | null;
+    data: CreatorRetrieveResponse.Data;
     /**
-     * Creator's display name
+     * Present when partial results were returned because one or more linked profiles
+     * were skipped for data integrity reasons.
      */
-    name?: string | null;
+    warning?: string;
 }
-/**
- * Creator autocomplete result
- */
-export interface CreatorAutocomplete {
-    /**
-     * Unique creator identifier
-     */
-    id: string;
-    /**
-     * Creator's avatar URL
-     */
-    avatar: string;
-    /**
-     * Creator's display name
-     */
-    name: string;
+export declare namespace CreatorRetrieveResponse {
     /**
-     * Matching social media platforms
+     * Full creator details
      */
-    platforms: Array<CreatorAutocomplete.Platform>;
-}
-export declare namespace CreatorAutocomplete {
-    interface Platform {
+    interface Data {
+        /**
+         * Creator unique identifier
+         */
+        id: string;
         /**
-         * Display name on the platform
+         * AI-generated summary of the creator
          */
-        display_name: string;
+        ai_summary: string | null;
         /**
-         * Field that matched the search
+         * Avatar URL
          */
-        match_field: string;
+        avatar_url: string | null;
         /**
-         * Type of match found
+         * Creator bio
          */
-        match_type: 'name' | 'username' | 'display_name';
+        bio: string | null;
         /**
-         * Social media platform
+         * Content themes/topics
          */
-        platform: 'instagram' | 'tiktok';
+        content_themes: Array<string>;
         /**
-         * Username on the platform
+         * Creator display name
          */
-        username: string;
+        name: string;
+        /**
+         * Social profiles (only included when include=profiles)
+         */
+        profiles?: Array<Shared.ProfileSummary>;
     }
 }
-/**
- * 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;
+export interface CreatorAutocompleteResponse {
     /**
-     * Platform-assigned category (e.g., "Health & Fitness"). null if not set or
-     * platform doesn't provide categories.
+     * Autocomplete results
      */
-    platform_category_name?: string | null;
+    data: Array<CreatorAutocompleteResponse.Data>;
 }
-/**
- * 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;
+export declare namespace CreatorAutocompleteResponse {
+    interface Data {
+        /**
+         * Creator ID
+         */
+        id: string;
+        /**
+         * Avatar URL
+         */
+        avatar: string | null;
+        /**
+         * Creator name
+         */
+        name: string;
+        /**
+         * Matching platforms
+         */
+        platforms: Array<Data.Platform>;
+    }
+    namespace Data {
+        interface Platform {
+            display_name: string | null;
+            /**
+             * The field value that matched
+             */
+            match_field: string;
+            /**
+             * How the query matched this profile
+             */
+            match_type: 'name' | 'username' | 'display_name';
+            /**
+             * Social media platform
+             */
+            platform: 'instagram';
+            username: string;
+        }
+    }
+}
+export interface CreatorLookalikeResponse {
     /**
-     * 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.
+     * Basic creator information
      */
-    engagement_rate?: number | null;
+    creator: Shared.CreatorBasic;
     /**
-     * External website URL
+     * Abbreviated profile information
      */
-    external_url?: string | null;
+    primary_profile: Shared.ProfileSummary | null;
     /**
-     * Total number of followers on this platform. null if data is unavailable or
-     * account is private.
+     * Similarity information for lookalike match
      */
-    follower_count?: number | null;
+    similarity: CreatorLookalikeResponse.Similarity;
 }
-export interface CreatorRetrieveResponse {
-    creators?: Array<CreatorRetrieveResponse.CreatorWithProfiles | Creator>;
-}
-export declare namespace CreatorRetrieveResponse {
+export declare namespace CreatorLookalikeResponse {
     /**
-     * Creator with embedded social account profiles
+     * Similarity information for lookalike match
      */
-    interface CreatorWithProfiles extends CreatorsAPI.Creator {
+    interface Similarity {
+        /**
+         * Similarity score (0-1)
+         */
+        score: number;
         /**
-         * Social account profiles for this creator
+         * Shared traits with seed creators
          */
-        profiles: Array<CreatorsAPI.SocialAccountLite | CreatorsAPI.SocialAccountDetailed>;
+        shared_traits: Array<string>;
     }
 }
-export interface CreatorAutocompleteResponse {
-    count?: number;
-    ok?: boolean;
-    results?: Array<CreatorAutocompleteResponse.Result>;
+export interface CreatorMatchResponse {
+    data: Array<CreatorMatchResponse.Data>;
 }
-export declare namespace CreatorAutocompleteResponse {
-    interface Result {
-        id?: string;
-        avatar?: string;
-        name?: string;
-        platforms?: Array<Result.Platform>;
+export declare namespace CreatorMatchResponse {
+    interface Data {
+        creator: Data.Creator;
+        input: Data.Input;
+        match: Data.Match;
     }
-    namespace Result {
-        interface Platform {
-            display_name?: string;
-            match_field?: string;
-            match_type?: 'name' | 'username' | 'display_name';
-            platform?: string;
+    namespace Data {
+        interface Creator {
+            id: string;
+            avatar_url: string | null;
+            name: string;
+        }
+        interface Input {
+            creator_id?: string;
+            /**
+             * Social media platform
+             */
+            platform?: 'instagram';
             username?: string;
         }
+        interface Match {
+            /**
+             * Match decision recommendation
+             */
+            decision: 'good' | 'neutral' | 'avoid';
+            /**
+             * Structured reasons supporting the decision
+             */
+            reasons: Array<Match.Reason>;
+            /**
+             * Match score (0-1)
+             */
+            score: number;
+        }
+        namespace Match {
+            interface Reason {
+                /**
+                 * Human-readable reason for the match
+                 */
+                text: string;
+                /**
+                 * ID of the supporting fact, if applicable
+                 */
+                fact_id?: string;
+                /**
+                 * ID of the source post, if applicable
+                 */
+                source_post_id?: string;
+            }
+        }
     }
 }
-export interface CreatorListProfilesResponse {
+export interface CreatorRetrieveParams {
     /**
-     * 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
+     * Additional data to include in response
      */
-    profiles?: Array<SocialAccountLite | SocialAccountDetailed>;
+    include: Array<'profiles'>;
 }
-export interface CreatorRetrieveParams {
+export interface CreatorAutocompleteParams {
     /**
-     * Comma-separated list of creator UUIDs
+     * Search query (min 2 characters)
      */
-    creator_ids: string;
+    q: string;
     /**
-     * Whether to include social account profiles for each creator
+     * Maximum results to return
      */
-    include_profiles?: boolean;
+    limit?: number;
     /**
-     * Detail level for included profiles (only used when include_profiles=true)
+     * Filter by platform
      */
-    profile_mode?: 'lite' | 'detailed';
+    platform?: 'instagram';
     /**
-     * Comma-separated list of platforms to include (instagram, tiktok). Only used when
-     * include_profiles=true
+     * Which platforms to include in results
      */
-    profile_platforms?: string;
+    scope?: 'creator_only' | 'matched_platforms' | 'all_platforms';
 }
-export interface CreatorAutocompleteParams {
+export interface CreatorLookalikeParams extends BodyCursorParams {
     /**
-     * Search query text (partial name/username)
+     * Seed creators to find similar creators for
      */
-    q: string;
+    seeds: Array<CreatorLookalikeParams.Seed>;
     /**
-     * Maximum number of results to return
+     * Additional filters
      */
-    limit?: number;
+    filters?: CreatorLookalikeParams.Filters;
+}
+export declare namespace CreatorLookalikeParams {
+    /**
+     * Seed creator for lookalike search
+     */
+    interface Seed {
+        /**
+         * Creator ID (use this OR platform+username)
+         */
+        creator_id?: string;
+        /**
+         * Platform (required with username)
+         */
+        platform?: 'instagram';
+        /**
+         * Username (required with platform)
+         */
+        username?: string;
+        /**
+         * Weight for this seed (0-1)
+         */
+        weight?: number;
+    }
+    /**
+     * Additional filters
+     */
+    interface Filters {
+        /**
+         * Filter by engagement rate
+         */
+        engagement_rate?: Filters.EngagementRate;
+        /**
+         * Filter by follower count
+         */
+        followers?: Filters.Followers;
+        /**
+         * Filter by verified status
+         */
+        verified?: boolean;
+    }
+    namespace Filters {
+        /**
+         * Filter by engagement rate
+         */
+        interface EngagementRate {
+            /**
+             * Maximum engagement rate (%)
+             */
+            max?: number;
+            /**
+             * Minimum engagement rate (%)
+             */
+            min?: number;
+        }
+        /**
+         * Filter by follower count
+         */
+        interface Followers {
+            /**
+             * Maximum follower count
+             */
+            max?: number;
+            /**
+             * Minimum follower count
+             */
+            min?: number;
+        }
+    }
+}
+export interface CreatorMatchParams {
     /**
-     * Filter results to only show creators that have profiles on this specific
-     * platform. If not provided, returns creators from all platforms.
+     * Creators to evaluate
      */
-    platform?: 'instagram' | 'tiktok';
+    creators: Array<CreatorMatchParams.Creator>;
     /**
-     * Control the granularity of returned data
+     * Campaign intent for creator matching
      */
-    scope?: 'creator_only' | 'matched_platforms' | 'all_platforms';
+    intent: CreatorMatchParams.Intent;
 }
-export interface CreatorListProfilesParams {
+export declare namespace CreatorMatchParams {
     /**
-     * Response detail level
+     * Creator identifier for match endpoint
      */
-    mode?: 'lite' | 'detailed';
+    interface Creator {
+        /**
+         * Creator ID (use this OR platform+username)
+         */
+        creator_id?: string;
+        /**
+         * Platform (required with username)
+         */
+        platform?: 'instagram';
+        /**
+         * Username (required with platform)
+         */
+        username?: string;
+    }
     /**
-     * Comma-separated list of platforms to include (instagram, tiktok)
+     * Campaign intent for creator matching
      */
-    platforms?: string;
+    interface Intent {
+        /**
+         * Campaign description
+         */
+        query: string;
+        /**
+         * Additional context about the campaign
+         */
+        context?: 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, };
+    export { type CreatorRetrieveResponse as CreatorRetrieveResponse, type CreatorAutocompleteResponse as CreatorAutocompleteResponse, type CreatorLookalikeResponse as CreatorLookalikeResponse, type CreatorMatchResponse as CreatorMatchResponse, type CreatorLookalikeResponsesBodyCursor as CreatorLookalikeResponsesBodyCursor, type CreatorRetrieveParams as CreatorRetrieveParams, type CreatorAutocompleteParams as CreatorAutocompleteParams, type CreatorLookalikeParams as CreatorLookalikeParams, type CreatorMatchParams as CreatorMatchParams, };
 }
 //# sourceMappingURL=creators.d.mts.map