influship 0.2.0 → 0.3.2

package/src/resources/profiles.ts

@@ -1,114 +1,307 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../core/resource';
-import * as CreatorsAPI from './creators';
 import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
 
+/**
+ * Access individual social media profiles with detailed metrics, growth data, and activity information. Profiles are platform-specific accounts linked to creators.
+ */
 export class Profiles extends APIResource {
   /**
-   * **DISCOVERY ENDPOINT**: Look up social account data when you know a username and
-   * platform.
+   * Retrieve detailed profile data including metrics, growth statistics, and
+   * activity information from our database.
    *
-   * **🎯 When to use this endpoint:**
+   * **Response includes:**
    *
-   * - ✅ You have a username and platform (e.g., @fitness_guru on Instagram)
-   * - ✅ You want to discover who a social account belongs to
-   * - ✅ You need to look up specific social accounts by username
-   * - ✅ You want to get social account metrics for known usernames
+   * - Basic info (bio, avatar, verification status)
+   * - Performance metrics (followers, engagement rate, avg likes/comments)
+   * - Growth data (30-day follower growth, monthly rate)
+   * - Activity data (last post date, posting frequency)
    *
-   * **❌ When NOT to use this endpoint:**
+   * **Pricing**: 0.1 credits per request ($0.001)
    *
-   * - ❌ You already have a creator UUID (use `/v1/creators/{id}/profiles` instead)
-   * - ❌ You want to get all accounts for a creator (use
-   *   `/v1/creators/{id}/profiles` instead)
-   *
-   * **📊 Response Format:** Returns `SocialAccountLite` or `SocialAccountDetailed`
-   * objects with identical structure to `/v1/creators/{id}/profiles`. Both endpoints
-   * return the same data structure for consistency.
-   *
-   * **🔗 Data Relationships:**
-   *
-   * - Use the `creator_profile_id` field to fetch creator-level data via
-   *   `/v1/creators`
-   * - Use the `creator_profile_id` to get all social accounts via
-   *   `/v1/creators/{id}/profiles`
-   * - Creator-level data includes: name, bio, avatar, ai_one_line_bio
-   * - Social account data includes: follower_count, engagement_rate, verified,
-   *   platform-specific metrics
-   *
-   * **🔄 Typical Workflow:**
+   * @example
+   * ```ts
+   * const profile = await client.profiles.get(
+   *   'fitness_coach_jane',
+   *   { platform: 'instagram' },
+   * );
+   * ```
+   */
+  get(username: string, params: ProfileGetParams, options?: RequestOptions): APIPromise<ProfileGetResponse> {
+    const { platform } = params;
+    return this._client.get(path`/v1/profiles/${platform}/${username}`, options);
+  }
+
+  /**
+   * Look up multiple profiles in a single request. Efficiently retrieve data for up
+   * to 100 profiles at once.
    *
-   * 1. **Discovery**: Call `/v1/profiles` with username+platform → get social
-   *    account data + creator_profile_id
-   * 2. **Creator Data**: Call `/v1/creators` with creator_profile_id → get
-   *    creator-level data
-   * 3. **All Accounts**: Call `/v1/creators/{id}/profiles` with creator_profile_id →
-   *    get all social accounts for that creator
+   * **Response includes:**
    *
-   * **⚙️ Parameters:**
+   * - `found`: Array of profiles that exist in our database
+   * - `not_found`: Array of profiles that weren't found (consider live scraping
+   *   these)
    *
-   * - `mode`: `lite` (default) or `detailed` - controls response detail level
-   * - `platforms`: Array of platform names to filter results (e.g.,
-   *   `["instagram", "tiktok"]`) **Pricing**: 0.01-0.05 credits per profile
-   *   (lite/detailed mode)
+   * **Pricing**: 0.1 credits per profile ($0.001)
    *
    * @example
    * ```ts
    * const response = await client.profiles.lookup({
    *   profiles: [
-   *     { platform: 'instagram', username: 'fitness_guru' },
-   *     { platform: 'tiktok', username: 'fitness_guru' },
+   *     {
+   *       platform: 'instagram',
+   *       username: 'fitness_coach_jane',
+   *     },
    *   ],
    * });
    * ```
    */
   lookup(body: ProfileLookupParams, options?: RequestOptions): APIPromise<ProfileLookupResponse> {
-    return this._client.post('/v1/profiles', { body, ...options });
+    return this._client.post('/v1/profiles/lookup', { body, ...options });
   }
 }
 
-export interface CreatorReferenceByHandle {
+/**
+ * Profile activity information
+ */
+export interface ProfileActivity {
+  /**
+   * Timestamp of last post
+   */
+  last_post_at: string | null;
+}
+
+/**
+ * Profile growth statistics
+ */
+export interface ProfileGrowth {
+  /**
+   * Follower growth percentage over 30 days (e.g. 2.5 means +2.5%)
+   */
+  followers_30d_pct: number;
+}
+
+/**
+ * Profile performance metrics
+ */
+export interface ProfileMetrics {
+  /**
+   * Average comments on recent posts
+   */
+  avg_comments_recent: number;
+
+  /**
+   * Average likes on recent posts
+   */
+  avg_likes_recent: number;
+
+  /**
+   * Average views on recent posts (for video content)
+   */
+  avg_views_recent: number | null;
+
+  /**
+   * Engagement rate as a percentage (e.g. 3.5 means 3.5%)
+   */
+  engagement_rate: number;
+
+  /**
+   * Follower count
+   */
+  followers: number;
+
+  /**
+   * Following count
+   */
+  following: number;
+
+  /**
+   * Total post count
+   */
+  posts: number;
+
+  /**
+   * Posts in the last 30 days
+   */
+  posts_last_30d: number;
+
+  /**
+   * Average posts per week
+   */
+  posts_per_week: number;
+}
+
+/**
+ * Full profile details
+ */
+export interface ProfileResponseData {
+  /**
+   * Profile unique identifier
+   */
+  id: string;
+
+  /**
+   * Profile activity information
+   */
+  activity: ProfileActivity;
+
+  /**
+   * Avatar URL
+   */
+  avatar_url: string | null;
+
+  /**
+   * Profile bio
+   */
+  bio: string | null;
+
+  /**
+   * Account category
+   */
+  category: string | null;
+
+  /**
+   * Creator unique identifier
+   */
+  creator_id: string;
+
+  /**
+   * Last data refresh timestamp
+   */
+  data_updated_at: string | null;
+
+  /**
+   * Display name
+   */
+  display_name: string | null;
+
+  /**
+   * External website URL from bio
+   */
+  external_url: string | null;
+
+  /**
+   * Profile growth statistics
+   */
+  growth: ProfileGrowth;
+
+  /**
+   * Whether this is a business account
+   */
+  is_business: boolean;
+
+  /**
+   * Whether the account is private
+   */
+  is_private: boolean;
+
+  /**
+   * Whether the account is verified
+   */
+  is_verified: boolean;
+
+  /**
+   * Profile performance metrics
+   */
+  metrics: ProfileMetrics;
+
+  /**
+   * Social media platform
+   */
+  platform: 'instagram';
+
+  /**
+   * Listed pronouns
+   */
+  pronouns: Array<string> | null;
+
   /**
-   * Social platform where the creator exists
+   * Profile URL
    */
-  platform: 'instagram' | 'tiktok';
+  url: string;
 
   /**
-   * Username on the platform
+   * Profile username
    */
   username: string;
 }
 
+export interface ProfileGetResponse {
+  /**
+   * Full profile details
+   */
+  data: ProfileResponseData;
+
+  /**
+   * Present when partial results were returned because profile metrics/data were
+   * skipped due to integrity issues.
+   */
+  warning?: string;
+}
+
 export interface ProfileLookupResponse {
   /**
-   * 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 that were found
+   */
+  data: Array<ProfileResponseData>;
+
+  /**
+   * Profiles that were not found
    */
-  profiles?: Array<CreatorsAPI.SocialAccountLite | CreatorsAPI.SocialAccountDetailed>;
+  not_found: Array<ProfileLookupResponse.NotFound>;
 }
 
-export interface ProfileLookupParams {
-  profiles: Array<CreatorReferenceByHandle>;
+export namespace ProfileLookupResponse {
+  export interface NotFound {
+    /**
+     * Social media platform
+     */
+    platform: 'instagram';
+
+    username: string;
+  }
+}
 
+export interface ProfileGetParams {
   /**
-   * Response detail level - lite for basic fields, detailed for additional metrics
+   * Platform name
    */
-  mode?: 'lite' | 'detailed';
+  platform: string;
+}
 
+export interface ProfileLookupParams {
   /**
-   * Filter results to only include these platforms
+   * Profiles to lookup
    */
-  platforms?: Array<'instagram' | 'tiktok'>;
+  profiles: Array<ProfileLookupParams.Profile>;
+}
+
+export namespace ProfileLookupParams {
+  export interface Profile {
+    /**
+     * Social media platform
+     */
+    platform: 'instagram';
+
+    /**
+     * Username to lookup
+     */
+    username: string;
+  }
 }
 
 export declare namespace Profiles {
   export {
-    type CreatorReferenceByHandle as CreatorReferenceByHandle,
+    type ProfileActivity as ProfileActivity,
+    type ProfileGrowth as ProfileGrowth,
+    type ProfileMetrics as ProfileMetrics,
+    type ProfileResponseData as ProfileResponseData,
+    type ProfileGetResponse as ProfileGetResponse,
     type ProfileLookupResponse as ProfileLookupResponse,
+    type ProfileGetParams as ProfileGetParams,
     type ProfileLookupParams as ProfileLookupParams,
   };
 }

package/src/resources/raw/index.ts

@@ -0,0 +1,16 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Instagram, type InstagramGetProfileResponse, type InstagramGetProfileParams } from './instagram';
+export { Raw } from './raw';
+export {
+  Youtube,
+  type TranscriptSegment,
+  type YoutubeGetChannelResponse,
+  type YoutubeGetChannelTranscriptsResponse,
+  type YoutubeGetTranscriptResponse,
+  type YoutubeSearchResponse,
+  type YoutubeGetChannelParams,
+  type YoutubeGetChannelTranscriptsParams,
+  type YoutubeGetTranscriptParams,
+  type YoutubeSearchParams,
+} from './youtube';

package/src/resources/raw/instagram.ts

@@ -0,0 +1,271 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Fetch fresh data directly from social platforms in real-time. Use when you need the most current information or data for profiles not yet in our database.
+ */
+export class Instagram extends APIResource {
+  /**
+   * Fetch fresh Instagram profile data directly from Instagram in real-time. Use
+   * this when you need the most current follower counts, bio, or recent activity.
+   *
+   * **When to use live scraping:**
+   *
+   * - Profile not found in our database
+   * - Need real-time follower/engagement data
+   * - Verifying current profile status before campaign
+   *
+   * **Note:** Live scraping is slower than cached data (2-5 seconds) and costs more.
+   * Use cached endpoints when freshness isn't critical.
+   *
+   * **Pricing**: 0.5 credits per profile scraped ($0.005)
+   */
+  getProfile(
+    username: string,
+    query: InstagramGetProfileParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<InstagramGetProfileResponse> {
+    return this._client.get(path`/v1/raw/instagram/profile/${username}`, { query, ...options });
+  }
+}
+
+export interface InstagramGetProfileResponse {
+  /**
+   * Live scraped profile data
+   */
+  data: InstagramGetProfileResponse.Data;
+}
+
+export namespace InstagramGetProfileResponse {
+  /**
+   * Live scraped profile data
+   */
+  export interface Data {
+    /**
+     * Profile unique identifier
+     */
+    id: string;
+
+    activity: Data.Activity;
+
+    /**
+     * Avatar URL
+     */
+    avatar_url: string | null;
+
+    /**
+     * Profile bio
+     */
+    bio: string | null;
+
+    /**
+     * Account category
+     */
+    category: string | null;
+
+    /**
+     * Creator unique identifier
+     */
+    creator_id: string;
+
+    /**
+     * Last data refresh timestamp
+     */
+    data_updated_at: string | null;
+
+    /**
+     * Display name
+     */
+    display_name: string | null;
+
+    /**
+     * External website URL
+     */
+    external_url: string | null;
+
+    growth: Data.Growth;
+
+    /**
+     * Whether this is a business account
+     */
+    is_business: boolean;
+
+    /**
+     * Whether the account is private
+     */
+    is_private: boolean;
+
+    /**
+     * Whether the account is verified
+     */
+    is_verified: boolean;
+
+    metrics: Data.Metrics;
+
+    /**
+     * Social media platform
+     */
+    platform: 'instagram';
+
+    /**
+     * Listed pronouns
+     */
+    pronouns: Array<string> | null;
+
+    /**
+     * When this data was scraped
+     */
+    scraped_at: string;
+
+    /**
+     * Profile URL
+     */
+    url: string;
+
+    /**
+     * Profile username
+     */
+    username: string;
+
+    /**
+     * Recent posts (only included when include_posts=true)
+     */
+    posts?: Array<Data.Post>;
+  }
+
+  export namespace Data {
+    export interface Activity {
+      /**
+       * Timestamp of last post
+       */
+      last_post_at: string | null;
+    }
+
+    export interface Growth {
+      /**
+       * Follower growth percentage over 30 days (e.g. 2.5 means +2.5%)
+       */
+      followers_30d_pct: number;
+    }
+
+    export interface Metrics {
+      /**
+       * Average comments on recent posts
+       */
+      avg_comments_recent: number;
+
+      /**
+       * Average likes on recent posts
+       */
+      avg_likes_recent: number;
+
+      /**
+       * Average views on recent posts
+       */
+      avg_views_recent: number | null;
+
+      /**
+       * Engagement rate as a percentage (e.g. 3.5 means 3.5%)
+       */
+      engagement_rate: number;
+
+      /**
+       * Follower count
+       */
+      followers: number;
+
+      /**
+       * Following count
+       */
+      following: number;
+
+      /**
+       * Total post count
+       */
+      posts: number;
+
+      /**
+       * Posts in the last 30 days
+       */
+      posts_last_30d: number;
+
+      /**
+       * Average posts per week
+       */
+      posts_per_week: number;
+    }
+
+    /**
+     * Simplified post from live scrape
+     */
+    export interface Post {
+      /**
+       * Post unique identifier
+       */
+      id: string;
+
+      /**
+       * Post caption
+       */
+      caption: string | null;
+
+      /**
+       * Comment count
+       */
+      comments_count: number | null;
+
+      /**
+       * Like count
+       */
+      likes_count: number | null;
+
+      /**
+       * Primary media URL
+       */
+      media_url: string | null;
+
+      /**
+       * Platform-specific post ID
+       */
+      platform_id: string;
+
+      /**
+       * Post timestamp
+       */
+      posted_at: string;
+
+      /**
+       * Type of post
+       */
+      type: 'image' | 'video' | 'carousel' | 'reel' | 'story';
+
+      /**
+       * Post URL
+       */
+      url: string;
+    }
+  }
+}
+
+export interface InstagramGetProfileParams {
+  /**
+   * Include recent posts in response
+   */
+  include_posts?: boolean;
+
+  /**
+   * Number of posts to include
+   */
+  post_limit?: number;
+}
+
+export declare namespace Instagram {
+  export {
+    type InstagramGetProfileResponse as InstagramGetProfileResponse,
+    type InstagramGetProfileParams as InstagramGetProfileParams,
+  };
+}

package/src/resources/raw/raw.ts

@@ -0,0 +1,47 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as InstagramAPI from './instagram';
+import { Instagram, InstagramGetProfileParams, InstagramGetProfileResponse } from './instagram';
+import * as YoutubeAPI from './youtube';
+import {
+  TranscriptSegment,
+  Youtube,
+  YoutubeGetChannelParams,
+  YoutubeGetChannelResponse,
+  YoutubeGetChannelTranscriptsParams,
+  YoutubeGetChannelTranscriptsResponse,
+  YoutubeGetTranscriptParams,
+  YoutubeGetTranscriptResponse,
+  YoutubeSearchParams,
+  YoutubeSearchResponse,
+} from './youtube';
+
+export class Raw extends APIResource {
+  instagram: InstagramAPI.Instagram = new InstagramAPI.Instagram(this._client);
+  youtube: YoutubeAPI.Youtube = new YoutubeAPI.Youtube(this._client);
+}
+
+Raw.Instagram = Instagram;
+Raw.Youtube = Youtube;
+
+export declare namespace Raw {
+  export {
+    Instagram as Instagram,
+    type InstagramGetProfileResponse as InstagramGetProfileResponse,
+    type InstagramGetProfileParams as InstagramGetProfileParams,
+  };
+
+  export {
+    Youtube as Youtube,
+    type TranscriptSegment as TranscriptSegment,
+    type YoutubeGetChannelResponse as YoutubeGetChannelResponse,
+    type YoutubeGetChannelTranscriptsResponse as YoutubeGetChannelTranscriptsResponse,
+    type YoutubeGetTranscriptResponse as YoutubeGetTranscriptResponse,
+    type YoutubeSearchResponse as YoutubeSearchResponse,
+    type YoutubeGetChannelParams as YoutubeGetChannelParams,
+    type YoutubeGetChannelTranscriptsParams as YoutubeGetChannelTranscriptsParams,
+    type YoutubeGetTranscriptParams as YoutubeGetTranscriptParams,
+    type YoutubeSearchParams as YoutubeSearchParams,
+  };
+}