influship 0.2.0 → 0.3.2

package/src/resources/search.ts

@@ -1,234 +1,248 @@
 // 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 SearchAPI from './search';
+import * as Shared from './shared';
 import { APIPromise } from '../core/api-promise';
+import { PagePromise, QueryCursor, type QueryCursorParams } from '../core/pagination';
 import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
 
+/**
+ * AI-powered semantic search to find creators using natural language queries. Understands intent and context to match creators based on content themes, audience, and style.
+ */
 export class Search extends APIResource {
   /**
-   * Find influencers using AI-powered search with natural language queries and
-   * optional filters.
+   * Search for creators using natural language queries. The AI understands intent
+   * and context to match creators based on content themes, audience demographics,
+   * and style.
+   *
+   * The response includes a `search_id` that can be used with `GET /v1/search/{id}`
+   * to paginate through results for free.
+   *
+   * **Use cases:**
    *
-   * **Pricing**:
+   * - Find creators in a specific niche ("vegan food bloggers in LA")
+   * - Discover creators with specific audience characteristics ("fitness influencers
+   *   with millennial audience")
+   * - Search by content style ("creators who post cinematic travel videos")
    *
-   * - Base: 2.0 credits per creator returned
-   * - Detailed mode: Additional 0.05 credits per social account profile
-   * - **Example**: 10 creators in lite mode = 20 credits
-   * - **Example**: 10 creators with avg 2 profiles each in detailed mode = 20 + (10
-   *   × 2 × 0.05) = 21 credits
+   * **Pricing**: 25 credits base + 2 credits per creator returned
    *
    * @example
    * ```ts
-   * const response = await client.search.findCreators({
+   * const search = await client.search.create({
    *   query:
-   *     'fitness influencers with 100k+ followers who post workout content',
+   *     'fitness influencers with 100k+ followers who post workout videos',
    * });
    * ```
    */
-  findCreators(
-    params: SearchFindCreatorsParams,
+  create(body: SearchCreateParams, options?: RequestOptions): APIPromise<SearchCreateResponse> {
+    return this._client.post('/v1/search', { body, ...options });
+  }
+
+  /**
+   * Paginate through results from a previous search. Use the `search_id` returned by
+   * `POST /v1/search` to fetch additional pages.
+   *
+   * Search sessions expire after 1 hour. After expiry, a new search must be run.
+   *
+   * **Pricing**: 0 credits (included with initial search)
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const searchRetrieveResponse of client.search.retrieve(
+   *   '123e4567-e89b-12d3-a456-426614174000',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  retrieve(
+    id: string,
+    query: SearchRetrieveParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<SearchFindCreatorsResponse> {
-    const { cursor, limit, ...body } = params;
-    return this._client.post('/v1/search', { query: { cursor, limit }, body, ...options });
+  ): PagePromise<SearchRetrieveResponsesQueryCursor, SearchRetrieveResponse> {
+    return this._client.getAPIList(path`/v1/search/${id}`, QueryCursor<SearchRetrieveResponse>, {
+      query,
+      ...options,
+    });
   }
 }
 
+export type SearchRetrieveResponsesQueryCursor = QueryCursor<SearchRetrieveResponse>;
+
 /**
- * Search result item containing creator information and all social media profiles
+ * Search match information
  */
-export interface SearchItem {
+export interface MatchInfo {
   /**
-   * Unique creator identifier (UUID v4)
+   * Human-readable match reasons
    */
-  id: string;
+  reasons: Array<string>;
 
   /**
-   * AI-powered recommendation analysis explaining why this creator matches your
-   * query
+   * Match relevance score (0-1)
    */
-  ai_recommendation: SearchItem.AIRecommendation;
+  score: number;
+}
+
+export interface SearchCreateResponse {
+  data: Array<SearchCreateResponse.Data>;
 
   /**
-   * Creator's display name or full name
+   * Whether more results are available
    */
-  name: string;
+  has_more: boolean;
 
   /**
-   * Array of ALL social media profiles for this creator
+   * Cursor for the next page
    */
-  profiles: Array<CreatorsAPI.SocialAccountLite | CreatorsAPI.SocialAccountDetailed>;
+  next_cursor: string | null;
 
   /**
-   * Profile picture URL. null if no avatar is available. URLs are typically valid
-   * for 24 hours.
+   * Search ID. Use with GET /v1/search/{id} for free pagination.
    */
-  avatar_url?: string | null;
+  search_id: string;
 
   /**
-   * Creator's biography or description text. May be aggregated from multiple
-   * platforms. null if unavailable.
+   * Total number of results across all pages
    */
-  bio?: string | null;
+  total: number;
 }
 
-export namespace SearchItem {
-  /**
-   * AI-powered recommendation analysis explaining why this creator matches your
-   * query
-   */
-  export interface AIRecommendation {
+export namespace SearchCreateResponse {
+  export interface Data {
     /**
-     * Human-readable explanation of why this creator was recommended. Highlights key
-     * matching factors from the query.
+     * Basic creator information
      */
-    explanation: string;
+    creator: Shared.CreatorBasic;
 
     /**
-     * Relevance score from 0 to 1, where 1 is a perfect match. Scores above 0.7
-     * indicate strong relevance.
+     * Search match information
      */
-    score: number;
+    match: SearchAPI.MatchInfo;
 
     /**
-     * Fact-level evidence from hybrid search explaining why this creator matched. Each
-     * fact represents specific, verifiable information about the creator.
+     * Abbreviated profile information
      */
-    evidence?: Array<AIRecommendation.Evidence>;
-  }
+    primary_profile: Shared.ProfileSummary | null;
 
-  export namespace AIRecommendation {
     /**
-     * Individual fact from hybrid search providing evidence for why a creator matched.
-     * Facts are specific, verifiable pieces of information extracted from creator
-     * data.
+     * Abbreviated profile information
      */
-    export interface Evidence {
-      /**
-       * The actual fact text describing specific information about the creator
-       */
-      fact: string;
-
-      /**
-       * Unique identifier for this fact
-       */
-      factId: string;
-
-      /**
-       * Combined relevance score (similarity × confidence × temporal decay). Higher
-       * scores indicate stronger evidence for the match.
-       */
-      score: number;
-
-      /**
-       * When this fact was created or observed (ISO 8601 format)
-       */
-      created_at?: string;
-
-      /**
-       * Array of source post IDs where this fact originated. A single fact may come from
-       * multiple posts.
-       */
-      source_post_id?: Array<string>;
-    }
+    relevant_profile: Shared.ProfileSummary | null;
   }
 }
 
-export interface SearchFindCreatorsResponse {
+export interface SearchRetrieveResponse {
   /**
-   * Total number of matching results in the database before pagination. Use this
-   * with `has_more` to display "Showing 25 of 1,247 results" in your UI.
+   * Basic creator information
    */
-  filtered_total?: number;
+  creator: Shared.CreatorBasic;
 
   /**
-   * Whether there are more results available for pagination. If true, use the
-   * `next_cursor` value in your next request.
+   * Search match information
    */
-  has_more?: boolean;
+  match: MatchInfo;
 
-  items?: Array<SearchItem>;
+  /**
+   * Abbreviated profile information
+   */
+  primary_profile: Shared.ProfileSummary | null;
 
   /**
-   * Opaque cursor for fetching the next page of results. Pass this value as the
-   * `cursor` query parameter. Only present when `has_more` is true.
+   * Abbreviated profile information
    */
-  next_cursor?: string;
+  relevant_profile: Shared.ProfileSummary | null;
 }
 
-export interface SearchFindCreatorsParams {
+export interface SearchCreateParams {
   /**
-   * Body param: Natural language search query
+   * Natural language search query
    */
   query: string;
 
   /**
-   * Query param: Opaque pagination cursor from previous response's `next_cursor`. Do
-   * not construct manually.
+   * Additional filters
    */
-  cursor?: string;
+  filters?: SearchCreateParams.Filters;
 
   /**
-   * Query param: Maximum number of results to return
+   * Maximum results to return
    */
   limit?: number;
 
   /**
-   * Body param:
-   */
-  filters?: SearchFindCreatorsParams.Filters;
-
-  /**
-   * Body param: Filter social accounts to only these platforms. Reduces payload
-   * size. Does not affect search results or costs.
+   * Filter results to specific platforms
    */
-  include_platforms?: Array<'instagram' | 'tiktok'>;
+  platforms?: Array<'instagram'>;
+}
 
+export namespace SearchCreateParams {
   /**
-   * Body param: Response detail level. `lite` returns basic fields (username,
-   * follower_count, engagement_rate). `detailed` adds avg_comments_recent,
-   * avg_video_views_recent, follower_change_rate, etc. Detailed mode costs 5x more
-   * (0.05 vs 0.01 credits per profile).
+   * Additional filters
    */
-  mode?: 'lite' | 'detailed';
-}
-
-export namespace SearchFindCreatorsParams {
   export interface Filters {
     /**
-     * Per-platform filter definitions
+     * Filter by engagement rate
      */
-    platform_filters?: Array<Filters.PlatformFilter>;
+    engagement_rate?: Filters.EngagementRate;
 
     /**
-     * How to combine platform_filters. `OR` = creator matches ANY platform filter.
-     * `AND` = creator must match ALL platform filters. Default: OR.
+     * Filter by follower count
      */
-    platform_logic?: 'AND' | 'OR';
+    followers?: Filters.Followers;
+
+    /**
+     * Filter by verified status
+     */
+    verified?: boolean;
   }
 
   export namespace Filters {
-    export interface PlatformFilter {
-      platform: 'instagram' | 'tiktok';
-
-      max_engagement_rate?: number;
-
-      max_followers?: number;
+    /**
+     * Filter by engagement rate
+     */
+    export interface EngagementRate {
+      /**
+       * Maximum engagement rate (%)
+       */
+      max?: number;
 
-      min_engagement_rate?: number;
+      /**
+       * Minimum engagement rate (%)
+       */
+      min?: number;
+    }
 
-      min_followers?: number;
+    /**
+     * Filter by follower count
+     */
+    export interface Followers {
+      /**
+       * Maximum follower count
+       */
+      max?: number;
 
-      verified_only?: boolean;
+      /**
+       * Minimum follower count
+       */
+      min?: number;
     }
   }
 }
 
+export interface SearchRetrieveParams extends QueryCursorParams {}
+
 export declare namespace Search {
   export {
-    type SearchItem as SearchItem,
-    type SearchFindCreatorsResponse as SearchFindCreatorsResponse,
-    type SearchFindCreatorsParams as SearchFindCreatorsParams,
+    type MatchInfo as MatchInfo,
+    type SearchCreateResponse as SearchCreateResponse,
+    type SearchRetrieveResponse as SearchRetrieveResponse,
+    type SearchRetrieveResponsesQueryCursor as SearchRetrieveResponsesQueryCursor,
+    type SearchCreateParams as SearchCreateParams,
+    type SearchRetrieveParams as SearchRetrieveParams,
   };
 }

package/src/resources/shared.ts

@@ -0,0 +1,66 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+/**
+ * Basic creator information
+ */
+export interface CreatorBasic {
+  /**
+   * Creator unique identifier
+   */
+  id: string;
+
+  /**
+   * Avatar URL
+   */
+  avatar_url: string | null;
+
+  /**
+   * Creator bio
+   */
+  bio: string | null;
+
+  /**
+   * Creator display name
+   */
+  name: string;
+}
+
+/**
+ * Abbreviated profile information
+ */
+export interface ProfileSummary {
+  /**
+   * Profile unique identifier
+   */
+  id: string;
+
+  /**
+   * Engagement rate as a percentage, null if unknown (e.g. 3.5 means 3.5%)
+   */
+  engagement_rate: number | null;
+
+  /**
+   * Follower count (null if unknown)
+   */
+  followers: number | null;
+
+  /**
+   * Whether the account is verified
+   */
+  is_verified: boolean;
+
+  /**
+   * Social media platform
+   */
+  platform: 'instagram';
+
+  /**
+   * Profile URL
+   */
+  url: string;
+
+  /**
+   * Profile username
+   */
+  username: string;
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.2.0'; // x-release-please-version
+export const VERSION = '0.3.2'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.3.2";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.3.2";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.2.0'; // x-release-please-version
+exports.VERSION = '0.3.2'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.2.0'; // x-release-please-version
+export const VERSION = '0.3.2'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map