influship 0.2.0 → 0.3.2

package/src/client.ts

@@ -11,67 +11,55 @@ import type { APIResponseProps } from './internal/parse';
 import { getPlatformHeaders } from './internal/detect-platform';
 import * as Shims from './internal/shims';
 import * as Opts from './internal/request-options';
-import * as qs from './internal/qs';
+import { stringifyQuery } from './internal/utils/query';
 import { VERSION } from './version';
 import * as Errors from './core/error';
+import * as Pagination from './core/pagination';
+import {
+  AbstractPage,
+  type BodyCursorParams,
+  BodyCursorResponse,
+  type QueryCursorParams,
+  QueryCursorResponse,
+} from './core/pagination';
 import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
 import {
-  BrandSafety,
-  BrandSafetyAnalysis,
-  BrandSafetyAnalyzeCreatorsParams,
-  BrandSafetyAnalyzeCreatorsResponse,
-  BrandSafetyAnalyzePostsParams,
-  BrandSafetyAnalyzePostsResponse,
-  BrandSafetyAnalyzeProfilesParams,
-  BrandSafetyAnalyzeProfilesResponse,
-  BrandSafetyFlag,
-  BrandSafetyResult,
-} from './resources/brand-safety';
-import {
-  Creator,
-  CreatorAutocomplete,
   CreatorAutocompleteParams,
   CreatorAutocompleteResponse,
-  CreatorListProfilesParams,
-  CreatorListProfilesResponse,
+  CreatorLookalikeParams,
+  CreatorLookalikeResponse,
+  CreatorLookalikeResponsesBodyCursor,
+  CreatorMatchParams,
+  CreatorMatchResponse,
   CreatorRetrieveParams,
   CreatorRetrieveResponse,
   Creators,
-  SocialAccountDetailed,
-  SocialAccountLite,
 } from './resources/creators';
 import { Health, HealthCheckResponse } from './resources/health';
+import { PostListParams, PostListResponse, PostListResponsesQueryCursor, Posts } from './resources/posts';
 import {
-  Lookalike,
-  LookalikeFindSimilarCreatorsParams,
-  LookalikeFindSimilarCreatorsResponse,
-  LookalikeSeedBase,
-} from './resources/lookalike';
-import {
-  CreatorReferenceByID,
-  Match,
-  MatchAnalyzeParams,
-  MatchAnalyzeResponse,
-  MatchResult,
-} from './resources/match';
-import {
-  AIAnalysis,
-  CursorPagination,
-  PostAnalysis,
-  PostAnalyzeParams,
-  PostListByCreatorParams,
-  PostListByCreatorResponse,
-  Posts,
-} from './resources/posts';
-import {
-  CreatorReferenceByHandle,
+  ProfileActivity,
+  ProfileGetParams,
+  ProfileGetResponse,
+  ProfileGrowth,
   ProfileLookupParams,
   ProfileLookupResponse,
+  ProfileMetrics,
+  ProfileResponseData,
   Profiles,
 } from './resources/profiles';
-import { Search, SearchFindCreatorsParams, SearchFindCreatorsResponse, SearchItem } from './resources/search';
+import {
+  MatchInfo,
+  Search,
+  SearchCreateParams,
+  SearchCreateResponse,
+  SearchRetrieveParams,
+  SearchRetrieveResponse,
+  SearchRetrieveResponsesQueryCursor,
+} from './resources/search';
+import { Raw } from './resources/raw/raw';
 import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
@@ -87,14 +75,14 @@ import { isEmptyObj } from './internal/utils/values';
 
 export interface ClientOptions {
   /**
-   * API key for authentication
+   * Defaults to process.env['INFLUSHIP_API_KEY'].
    */
   apiKey?: string | undefined;
 
   /**
    * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
    *
-   * Defaults to process.env['INFLUSHIP_API_BASE_URL'].
+   * Defaults to process.env['INFLUSHIP_BASE_URL'].
    */
   baseURL?: string | null | undefined;
 
@@ -148,7 +136,7 @@ export interface ClientOptions {
   /**
    * Set the log level.
    *
-   * Defaults to process.env['INFLUSHIP_API_LOG'] or 'warn' if it isn't set.
+   * Defaults to process.env['INFLUSHIP_LOG'] or 'warn' if it isn't set.
    */
   logLevel?: LogLevel | undefined;
 
@@ -161,9 +149,9 @@ export interface ClientOptions {
 }
 
 /**
- * API Client for interfacing with the Influship API API.
+ * API Client for interfacing with the Influship API.
  */
-export class InflushipAPI {
+export class Influship {
   apiKey: string;
 
   baseURL: string;
@@ -179,10 +167,10 @@ export class InflushipAPI {
   private _options: ClientOptions;
 
   /**
-   * API Client for interfacing with the Influship API API.
+   * API Client for interfacing with the Influship API.
    *
    * @param {string | undefined} [opts.apiKey=process.env['INFLUSHIP_API_KEY'] ?? undefined]
-   * @param {string} [opts.baseURL=process.env['INFLUSHIP_API_BASE_URL'] ?? https://api.influship.com] - Override the default base URL for the API.
+   * @param {string} [opts.baseURL=process.env['INFLUSHIP_BASE_URL'] ?? https://api.influship.com] - Override the default base URL for the API.
    * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
    * @param {Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
@@ -191,13 +179,13 @@ export class InflushipAPI {
    * @param {Record<string, string | undefined>} opts.defaultQuery - Default query parameters to include with every request to the API.
    */
   constructor({
-    baseURL = readEnv('INFLUSHIP_API_BASE_URL'),
+    baseURL = readEnv('INFLUSHIP_BASE_URL'),
     apiKey = readEnv('INFLUSHIP_API_KEY'),
     ...opts
   }: ClientOptions = {}) {
     if (apiKey === undefined) {
-      throw new Errors.InflushipAPIError(
-        "The INFLUSHIP_API_KEY environment variable is missing or empty; either provide it, or instantiate the InflushipAPI client with an apiKey option, like new InflushipAPI({ apiKey: 'My API Key' }).",
+      throw new Errors.InflushipError(
+        "The INFLUSHIP_API_KEY environment variable is missing or empty; either provide it, or instantiate the Influship client with an apiKey option, like new Influship({ apiKey: 'My API Key' }).",
       );
     }
 
@@ -208,14 +196,14 @@ export class InflushipAPI {
     };
 
     this.baseURL = options.baseURL!;
-    this.timeout = options.timeout ?? InflushipAPI.DEFAULT_TIMEOUT /* 1 minute */;
+    this.timeout = options.timeout ?? Influship.DEFAULT_TIMEOUT /* 1 minute */;
     this.logger = options.logger ?? console;
     const defaultLogLevel = 'warn';
     // Set default logLevel early so that we can log a warning in parseLogLevel.
     this.logLevel = defaultLogLevel;
     this.logLevel =
       parseLogLevel(options.logLevel, 'ClientOptions.logLevel', this) ??
-      parseLogLevel(readEnv('INFLUSHIP_API_LOG'), "process.env['INFLUSHIP_API_LOG']", this) ??
+      parseLogLevel(readEnv('INFLUSHIP_LOG'), "process.env['INFLUSHIP_LOG']", this) ??
       defaultLogLevel;
     this.fetchOptions = options.fetchOptions;
     this.maxRetries = options.maxRetries ?? 2;
@@ -265,8 +253,8 @@ export class InflushipAPI {
     return buildHeaders([{ 'X-API-Key': this.apiKey }]);
   }
 
-  protected stringifyQuery(query: Record<string, unknown>): string {
-    return qs.stringify(query, { arrayFormat: 'comma' });
+  protected stringifyQuery(query: object | Record<string, unknown>): string {
+    return stringifyQuery(query);
   }
 
   private getUserAgent(): string {
@@ -298,12 +286,13 @@ export class InflushipAPI {
       : new URL(baseURL + (baseURL.endsWith('/') && path.startsWith('/') ? path.slice(1) : path));
 
     const defaultQuery = this.defaultQuery();
-    if (!isEmptyObj(defaultQuery)) {
-      query = { ...defaultQuery, ...query };
+    const pathQuery = Object.fromEntries(url.searchParams);
+    if (!isEmptyObj(defaultQuery) || !isEmptyObj(pathQuery)) {
+      query = { ...pathQuery, ...defaultQuery, ...query };
     }
 
     if (typeof query === 'object' && query && !Array.isArray(query)) {
-      url.search = this.stringifyQuery(query as Record<string, unknown>);
+      url.search = this.stringifyQuery(query);
     }
 
     return url.toString();
@@ -487,7 +476,7 @@ export class InflushipAPI {
       loggerFor(this).info(`${responseInfo} - ${retryMessage}`);
 
       const errText = await response.text().catch((err: any) => castToError(err).message);
-      const errJSON = safeJSON(errText);
+      const errJSON = safeJSON(errText) as any;
       const errMessage = errJSON ? undefined : errText;
 
       loggerFor(this).debug(
@@ -521,6 +510,30 @@ export class InflushipAPI {
     return { response, options, controller, requestLogID, retryOfRequestLogID, startTime };
   }
 
+  getAPIList<Item, PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>>(
+    path: string,
+    Page: new (...args: any[]) => PageClass,
+    opts?: PromiseOrValue<RequestOptions>,
+  ): Pagination.PagePromise<PageClass, Item> {
+    return this.requestAPIList(
+      Page,
+      opts && 'then' in opts ?
+        opts.then((opts) => ({ method: 'get', path, ...opts }))
+      : { method: 'get', path, ...opts },
+    );
+  }
+
+  requestAPIList<
+    Item = unknown,
+    PageClass extends Pagination.AbstractPage<Item> = Pagination.AbstractPage<Item>,
+  >(
+    Page: new (...args: ConstructorParameters<typeof Pagination.AbstractPage>) => PageClass,
+    options: PromiseOrValue<FinalRequestOptions>,
+  ): Pagination.PagePromise<PageClass, Item> {
+    const request = this.makeRequest(options, null, undefined);
+    return new Pagination.PagePromise<PageClass, Item>(this as any as Influship, request, Page);
+  }
+
   async fetchWithTimeout(
     url: RequestInfo,
     init: RequestInit | undefined,
@@ -528,9 +541,10 @@ export class InflushipAPI {
     controller: AbortController,
   ): Promise<Response> {
     const { signal, method, ...options } = init || {};
-    if (signal) signal.addEventListener('abort', () => controller.abort());
+    const abort = this._makeAbort(controller);
+    if (signal) signal.addEventListener('abort', abort, { once: true });
 
-    const timeout = setTimeout(() => controller.abort(), ms);
+    const timeout = setTimeout(abort, ms);
 
     const isReadableBody =
       ((globalThis as any).ReadableStream && options.body instanceof (globalThis as any).ReadableStream) ||
@@ -607,9 +621,9 @@ export class InflushipAPI {
       }
     }
 
-    // If the API asks us to wait a certain amount of time (and it's a reasonable amount),
-    // just do what it says, but otherwise calculate a default
-    if (!(timeoutMillis && 0 <= timeoutMillis && timeoutMillis < 60 * 1000)) {
+    // If the API asks us to wait a certain amount of time, just do what it
+    // says, but otherwise calculate a default
+    if (timeoutMillis === undefined) {
       const maxRetries = options.maxRetries ?? this.maxRetries;
       timeoutMillis = this.calculateDefaultRetryTimeoutMillis(retriesRemaining, maxRetries);
     }
@@ -697,6 +711,12 @@ export class InflushipAPI {
     return headers.values;
   }
 
+  private _makeAbort(controller: AbortController) {
+    // note: we can't just inline this method inside `fetchWithTimeout()` because then the closure
+    //       would capture all request options, and cause a memory leak.
+    return () => controller.abort();
+  }
+
   private buildBody({ options: { body, headers: rawHeaders } }: { options: FinalRequestOptions }): {
     bodyHeaders: HeadersLike;
     body: BodyInit | undefined;
@@ -729,15 +749,23 @@ export class InflushipAPI {
         (Symbol.iterator in body && 'next' in body && typeof body.next === 'function'))
     ) {
       return { bodyHeaders: undefined, body: Shims.ReadableStreamFrom(body as AsyncIterable<Uint8Array>) };
+    } else if (
+      typeof body === 'object' &&
+      headers.values.get('content-type') === 'application/x-www-form-urlencoded'
+    ) {
+      return {
+        bodyHeaders: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: this.stringifyQuery(body),
+      };
     } else {
       return this.#encoder({ body, headers });
     }
   }
 
-  static InflushipAPI = this;
+  static Influship = this;
   static DEFAULT_TIMEOUT = 60000; // 1 minute
 
-  static InflushipAPIError = Errors.InflushipAPIError;
+  static InflushipError = Errors.InflushipError;
   static APIError = Errors.APIError;
   static APIConnectionError = Errors.APIConnectionError;
   static APIConnectionTimeoutError = Errors.APIConnectionTimeoutError;
@@ -753,93 +781,91 @@ export class InflushipAPI {
 
   static toFile = Uploads.toFile;
 
+  /**
+   * API health and status endpoints
+   */
   health: API.Health = new API.Health(this);
-  search: API.Search = new API.Search(this);
+  /**
+   * 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.
+   */
   creators: API.Creators = new API.Creators(this);
+  /**
+   * 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.
+   */
+  search: API.Search = new API.Search(this);
+  /**
+   * Access individual social media profiles with detailed metrics, growth data, and activity information. Profiles are platform-specific accounts linked to creators.
+   */
   profiles: API.Profiles = new API.Profiles(this);
-  lookalike: API.Lookalike = new API.Lookalike(this);
+  /**
+   * Retrieve and analyze social media posts with engagement metrics, media content, and performance data.
+   */
   posts: API.Posts = new API.Posts(this);
-  match: API.Match = new API.Match(this);
-  brandSafety: API.BrandSafety = new API.BrandSafety(this);
+  raw: API.Raw = new API.Raw(this);
 }
 
-InflushipAPI.Health = Health;
-InflushipAPI.Search = Search;
-InflushipAPI.Creators = Creators;
-InflushipAPI.Profiles = Profiles;
-InflushipAPI.Lookalike = Lookalike;
-InflushipAPI.Posts = Posts;
-InflushipAPI.Match = Match;
-InflushipAPI.BrandSafety = BrandSafety;
+Influship.Health = Health;
+Influship.Creators = Creators;
+Influship.Search = Search;
+Influship.Profiles = Profiles;
+Influship.Posts = Posts;
+Influship.Raw = Raw;
 
-export declare namespace InflushipAPI {
+export declare namespace Influship {
   export type RequestOptions = Opts.RequestOptions;
 
-  export { Health as Health, type HealthCheckResponse as HealthCheckResponse };
+  export import QueryCursor = Pagination.QueryCursor;
+  export { type QueryCursorParams as QueryCursorParams, type QueryCursorResponse as QueryCursorResponse };
 
-  export {
-    Search as Search,
-    type SearchItem as SearchItem,
-    type SearchFindCreatorsResponse as SearchFindCreatorsResponse,
-    type SearchFindCreatorsParams as SearchFindCreatorsParams,
-  };
+  export import BodyCursor = Pagination.BodyCursor;
+  export { type BodyCursorParams as BodyCursorParams, type BodyCursorResponse as BodyCursorResponse };
+
+  export { Health as Health, type HealthCheckResponse as HealthCheckResponse };
 
   export {
     Creators as Creators,
-    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,
   };
 
   export {
-    Profiles as Profiles,
-    type CreatorReferenceByHandle as CreatorReferenceByHandle,
-    type ProfileLookupResponse as ProfileLookupResponse,
-    type ProfileLookupParams as ProfileLookupParams,
+    Search as Search,
+    type MatchInfo as MatchInfo,
+    type SearchCreateResponse as SearchCreateResponse,
+    type SearchRetrieveResponse as SearchRetrieveResponse,
+    type SearchRetrieveResponsesQueryCursor as SearchRetrieveResponsesQueryCursor,
+    type SearchCreateParams as SearchCreateParams,
+    type SearchRetrieveParams as SearchRetrieveParams,
   };
 
   export {
-    Lookalike as Lookalike,
-    type LookalikeSeedBase as LookalikeSeedBase,
-    type LookalikeFindSimilarCreatorsResponse as LookalikeFindSimilarCreatorsResponse,
-    type LookalikeFindSimilarCreatorsParams as LookalikeFindSimilarCreatorsParams,
+    Profiles as Profiles,
+    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,
   };
 
   export {
     Posts as Posts,
-    type AIAnalysis as AIAnalysis,
-    type CursorPagination as CursorPagination,
-    type PostAnalysis as PostAnalysis,
-    type PostListByCreatorResponse as PostListByCreatorResponse,
-    type PostAnalyzeParams as PostAnalyzeParams,
-    type PostListByCreatorParams as PostListByCreatorParams,
+    type PostListResponse as PostListResponse,
+    type PostListResponsesQueryCursor as PostListResponsesQueryCursor,
+    type PostListParams as PostListParams,
   };
 
-  export {
-    Match as Match,
-    type CreatorReferenceByID as CreatorReferenceByID,
-    type MatchResult as MatchResult,
-    type MatchAnalyzeResponse as MatchAnalyzeResponse,
-    type MatchAnalyzeParams as MatchAnalyzeParams,
-  };
+  export { Raw as Raw };
 
-  export {
-    BrandSafety as BrandSafety,
-    type BrandSafetyAnalysis as BrandSafetyAnalysis,
-    type BrandSafetyFlag as BrandSafetyFlag,
-    type BrandSafetyResult as BrandSafetyResult,
-    type BrandSafetyAnalyzeCreatorsResponse as BrandSafetyAnalyzeCreatorsResponse,
-    type BrandSafetyAnalyzePostsResponse as BrandSafetyAnalyzePostsResponse,
-    type BrandSafetyAnalyzeProfilesResponse as BrandSafetyAnalyzeProfilesResponse,
-    type BrandSafetyAnalyzeCreatorsParams as BrandSafetyAnalyzeCreatorsParams,
-    type BrandSafetyAnalyzePostsParams as BrandSafetyAnalyzePostsParams,
-    type BrandSafetyAnalyzeProfilesParams as BrandSafetyAnalyzeProfilesParams,
-  };
+  export type CreatorBasic = API.CreatorBasic;
+  export type ProfileSummary = API.ProfileSummary;
 }

package/src/core/api-promise.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { type InflushipAPI } from '../client';
+import { type Influship } from '../client';
 
 import { type PromiseOrValue } from '../internal/types';
 import { APIResponseProps, defaultParseResponse } from '../internal/parse';
@@ -11,13 +11,13 @@ import { APIResponseProps, defaultParseResponse } from '../internal/parse';
  */
 export class APIPromise<T> extends Promise<T> {
   private parsedPromise: Promise<T> | undefined;
-  #client: InflushipAPI;
+  #client: Influship;
 
   constructor(
-    client: InflushipAPI,
+    client: Influship,
     private responsePromise: Promise<APIResponseProps>,
     private parseResponse: (
-      client: InflushipAPI,
+      client: Influship,
       props: APIResponseProps,
     ) => PromiseOrValue<T> = defaultParseResponse,
   ) {

package/src/core/error.ts

@@ -2,13 +2,13 @@
 
 import { castToError } from '../internal/errors';
 
-export class InflushipAPIError extends Error {}
+export class InflushipError extends Error {}
 
 export class APIError<
   TStatus extends number | undefined = number | undefined,
   THeaders extends Headers | undefined = Headers | undefined,
   TError extends Object | undefined = Object | undefined,
-> extends InflushipAPIError {
+> extends InflushipError {
   /** HTTP status for the response that caused the error */
   readonly status: TStatus;
   /** HTTP headers for the response that caused the error */