influship 0.2.0 → 0.3.1

package/src/resources/creators.ts

@@ -1,58 +1,63 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
-import * as CreatorsAPI from './creators';
+import * as Shared from './shared';
 import { APIPromise } from '../core/api-promise';
+import { BodyCursor, type BodyCursorParams, PagePromise } from '../core/pagination';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
+/**
+ * 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 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> {
-    return this._client.get('/v1/creators', { query, ...options });
+  retrieve(
+    id: string,
+    query: CreatorRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<CreatorRetrieveResponse> {
+    return this._client.get(path`/v1/creators/${id}`, { query, ...options });
   }
 
   /**
-   * 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
@@ -69,382 +74,475 @@ export class Creators extends APIResource {
   }
 
   /**
-   * **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> {
+    return this._client.getAPIList('/v1/creators/lookalike', BodyCursor<CreatorLookalikeResponse>, {
+      body,
+      method: 'post',
+      ...options,
+    });
+  }
+
+  /**
+   * 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> {
-    return this._client.get(path`/v1/creators/${id}/profiles`, { query, ...options });
+  match(body: CreatorMatchParams, options?: RequestOptions): APIPromise<CreatorMatchResponse> {
+    return this._client.post('/v1/creators/match', { body, ...options });
   }
 }
 
-/**
- * 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;
-
+export namespace CreatorRetrieveResponse {
   /**
-   * Creator's display name
+   * Full creator details
    */
-  name: string;
+  export interface Data {
+    /**
+     * Creator unique identifier
+     */
+    id: string;
 
-  /**
-   * Matching social media platforms
-   */
-  platforms: Array<CreatorAutocomplete.Platform>;
-}
+    /**
+     * AI-generated summary of the creator
+     */
+    ai_summary: string | null;
 
-export namespace CreatorAutocomplete {
-  export interface Platform {
     /**
-     * Display name on the platform
+     * Avatar URL
      */
-    display_name: string;
+    avatar_url: string | null;
 
     /**
-     * Field that matched the search
+     * Creator bio
      */
-    match_field: string;
+    bio: string | null;
 
     /**
-     * Type of match found
+     * Content themes/topics
      */
-    match_type: 'name' | 'username' | 'display_name';
+    content_themes: Array<string>;
 
     /**
-     * Social media platform
+     * Creator display name
      */
-    platform: 'instagram' | 'tiktok';
+    name: string;
 
     /**
-     * Username on the platform
+     * Social profiles (only included when include=profiles)
      */
-    username: string;
+    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;
+export namespace CreatorAutocompleteResponse {
+  export interface Data {
+    /**
+     * Creator ID
+     */
+    id: string;
 
-  /**
-   * Account bio
-   */
-  bio: string | null;
+    /**
+     * Avatar URL
+     */
+    avatar: 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;
+    /**
+     * Creator name
+     */
+    name: string;
 
-  /**
-   * Display name on the platform
-   */
-  display_name: string;
+    /**
+     * Matching platforms
+     */
+    platforms: Array<Data.Platform>;
+  }
 
-  /**
-   * Social media platform
-   */
-  platform: 'instagram' | 'tiktok';
+  export namespace Data {
+    export interface Platform {
+      display_name: string | null;
 
-  /**
-   * Username on the platform
-   */
-  username: string;
+      /**
+       * The field value that matched
+       */
+      match_field: string;
 
-  /**
-   * Whether the account has platform verification (blue checkmark).
-   */
-  verified: boolean;
+      /**
+       * How the query matched this profile
+       */
+      match_type: 'name' | 'username' | 'display_name';
 
-  /**
-   * Profile picture URL
-   */
-  avatar_url?: string | null;
+      /**
+       * 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;
-}
-
-export interface CreatorRetrieveResponse {
-  creators?: Array<CreatorRetrieveResponse.CreatorWithProfiles | Creator>;
+  similarity: CreatorLookalikeResponse.Similarity;
 }
 
-export namespace CreatorRetrieveResponse {
+export namespace CreatorLookalikeResponse {
   /**
-   * Creator with embedded social account profiles
+   * Similarity information for lookalike match
    */
-  export interface CreatorWithProfiles extends CreatorsAPI.Creator {
+  export interface Similarity {
     /**
-     * Social account profiles for this creator
+     * Similarity score (0-1)
      */
-    profiles: Array<CreatorsAPI.SocialAccountLite | CreatorsAPI.SocialAccountDetailed>;
+    score: number;
+
+    /**
+     * Shared traits with seed creators
+     */
+    shared_traits: Array<string>;
   }
 }
 
-export interface CreatorAutocompleteResponse {
-  count?: number;
-
-  ok?: boolean;
-
-  results?: Array<CreatorAutocompleteResponse.Result>;
+export interface CreatorMatchResponse {
+  data: Array<CreatorMatchResponse.Data>;
 }
 
-export namespace CreatorAutocompleteResponse {
-  export interface Result {
-    id?: string;
+export namespace CreatorMatchResponse {
+  export interface Data {
+    creator: Data.Creator;
 
-    avatar?: string;
+    input: Data.Input;
 
-    name?: string;
-
-    platforms?: Array<Result.Platform>;
+    match: Data.Match;
   }
 
-  export namespace Result {
-    export interface Platform {
-      display_name?: string;
+  export namespace Data {
+    export interface Creator {
+      id: string;
 
-      match_field?: string;
+      avatar_url: string | null;
 
-      match_type?: 'name' | 'username' | 'display_name';
+      name: string;
+    }
 
-      platform?: string;
+    export interface Input {
+      creator_id?: string;
+
+      /**
+       * Social media platform
+       */
+      platform?: 'instagram';
 
       username?: string;
     }
+
+    export interface Match {
+      /**
+       * Match decision recommendation
+       */
+      decision: 'good' | 'neutral' | 'avoid';
+
+      /**
+       * Structured reasons supporting the decision
+       */
+      reasons: Array<Match.Reason>;
+
+      /**
+       * Match score (0-1)
+       */
+      score: number;
+    }
+
+    export namespace Match {
+      export 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 namespace CreatorLookalikeParams {
+  /**
+   * Seed creator for lookalike search
+   */
+  export 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;
+  }
 
   /**
-   * Filter results to only show creators that have profiles on this specific
-   * platform. If not provided, returns creators from all platforms.
+   * Additional filters
    */
-  platform?: 'instagram' | 'tiktok';
+  export interface Filters {
+    /**
+     * Filter by engagement rate
+     */
+    engagement_rate?: Filters.EngagementRate;
+
+    /**
+     * Filter by follower count
+     */
+    followers?: Filters.Followers;
 
+    /**
+     * Filter by verified status
+     */
+    verified?: boolean;
+  }
+
+  export namespace Filters {
+    /**
+     * Filter by engagement rate
+     */
+    export interface EngagementRate {
+      /**
+       * Maximum engagement rate (%)
+       */
+      max?: number;
+
+      /**
+       * Minimum engagement rate (%)
+       */
+      min?: number;
+    }
+
+    /**
+     * Filter by follower count
+     */
+    export interface Followers {
+      /**
+       * Maximum follower count
+       */
+      max?: number;
+
+      /**
+       * Minimum follower count
+       */
+      min?: number;
+    }
+  }
+}
+
+export interface CreatorMatchParams {
   /**
-   * Control the granularity of returned data
+   * Creators to evaluate
    */
-  scope?: 'creator_only' | 'matched_platforms' | 'all_platforms';
+  creators: Array<CreatorMatchParams.Creator>;
+
+  /**
+   * Campaign intent for creator matching
+   */
+  intent: CreatorMatchParams.Intent;
 }
 
-export interface CreatorListProfilesParams {
+export namespace CreatorMatchParams {
   /**
-   * Response detail level
+   * Creator identifier for match endpoint
    */
-  mode?: 'lite' | 'detailed';
+  export 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;
+  export 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 CreatorLookalikeResponse as CreatorLookalikeResponse,
+    type CreatorMatchResponse as CreatorMatchResponse,
+    type CreatorLookalikeResponsesBodyCursor as CreatorLookalikeResponsesBodyCursor,
     type CreatorRetrieveParams as CreatorRetrieveParams,
     type CreatorAutocompleteParams as CreatorAutocompleteParams,
-    type CreatorListProfilesParams as CreatorListProfilesParams,
+    type CreatorLookalikeParams as CreatorLookalikeParams,
+    type CreatorMatchParams as CreatorMatchParams,
   };
 }