Creators Data Structures

type AccountPlatform = "tiktok" | "instagram" | "youtube";

type AccountStatus = "active" | "inactive" | "error";

interface CreateCreatorRequest {
  /** Creator name */
  name: string;
  /** Array of accounts to associate with this creator */
  accounts: NewCreatorAccountPayload[];
}

interface CreateCreatorResponse {
  /** Whether the creator was created successfully */
  ok: boolean;
  /** The slug (numeric identifier) of the created creator */
  creatorSlug: number;
  /** Array of warning messages if some accounts failed to be added (optional) */
  warnings?: string[];
}

interface Creator {
  /** Unique creator identifier */
  id: string;
  /** Workspace identifier */
  workspaceId: string;
  /** Creator slug (numeric identifier) */
  slug: number;
  /** Creator name */
  name: string;
  /** ISO 8601 timestamp when the creator was created */
  createdAt: string;
  /** ISO 8601 timestamp when the creator was last updated */
  updatedAt: string;
  /** Array of creator accounts */
  accounts: CreatorAccount[];
  /** Total number of accounts */
  accountsCount: number;
  /** Total followers across all accounts */
  followersTotal?: number;
  /** Total following across all accounts */
  followingTotal?: number;
  /** Total number of posts */
  postsCount?: number;
  /** Minimum time gap between posts (in seconds) */
  minGap?: number;
  /** Total likes */
  likes?: number;
  /** Total comments */
  comments?: number;
  /** Total shares */
  shares?: number;
  /** Total saves */
  saves?: number;
  /** Total views */
  views?: number;
  /** Top views count */
  topViews?: number;
  /** Total cost */
  cost?: number;
  /** Cost per mille (cost per 1000 views) */
  cpm?: number;
  /** Payment cost summary breakdown */
  costSummary?: object[];
  /** Minimum profit estimate */
  profitMin?: number;
  /** Maximum profit estimate */
  profitMax?: number;
  /** Minimum revenue estimate */
  revenueMin?: number;
  /** Maximum revenue estimate */
  revenueMax?: number;
  /** Minimum revenue per mille (revenue per 1000 views) */
  rpmMin?: number;
  /** Maximum revenue per mille (revenue per 1000 views) */
  rpmMax?: number;
  /** ISO 8601 timestamp of the earliest post */
  earliestPostedAt?: string;
  /** ISO 8601 timestamp of the latest post */
  latestPostedAt?: string;
  /** ISO 8601 timestamp of the most recent post */
  lastPostedAt?: string;
  /** ISO 8601 timestamp when tracking started */
  trackingStartedAt?: string;
  /** ISO 8601 timestamp of the last stats update */
  lastStatsAt?: string;
  /** Engagement rate percentage */
  engagementRate?: number;
  /** Amount owed to creator */
  owed?: number;
  /** Whether the creator has limited data available */
  limitedData: boolean;
}

interface CreatorAccount {
  /** Unique account identifier */
  id: string;
  /** Workspace identifier */
  workspaceId: string;
  /** Creator identifier */
  creatorId: string;
  /** Account URL */
  accountUrl: string;
  platform: AccountPlatform;
  /** Account username */
  username: string;
  /** Account display name */
  displayName?: string;
  /** Account avatar URL */
  avatarUrl?: string;
  /** Account bio */
  bio?: string;
  /** Account bio link */
  bioLink?: string;
  /** Whether the account is verified */
  verified?: boolean;
  /** ISO 8601 timestamp when the account was created */
  createdAt: string;
  /** ISO 8601 timestamp when the account was last updated */
  updatedAt: string;
  status: AccountStatus;
  /** Platform user ID */
  platformUserId?: string;
  /** Number of posts to track */
  postsToTrack?: number;
  /** Array of hashtags to track */
  hashtagsToTrack: string[];
  /** Array of mentions to track */
  mentionsToTrack: string[];
  /** Array of payment rules for this account */
  paymentRules: object[];
  /** Array of account statistics */
  accountStats: object[];
  /** Payment cost summary */
  costSummary?: object[];
  /** Total followers */
  followersTotal?: number;
  /** Total following */
  followingTotal?: number;
  /** Total number of posts */
  postsCount?: number;
  /** Total likes */
  likes?: number;
  /** Total comments */
  comments?: number;
  /** Total shares */
  shares?: number;
  /** Total saves */
  saves?: number;
  /** Total views */
  views?: number;
  /** Top views count */
  topViews?: number;
  /** Minimum revenue estimate */
  revenueMin?: number;
  /** Maximum revenue estimate */
  revenueMax?: number;
  /** Minimum revenue per mille */
  rpmMin?: number;
  /** Maximum revenue per mille */
  rpmMax?: number;
  /** Total cost */
  cost?: number;
  /** Cost per mille */
  cpm?: number;
  /** ISO 8601 timestamp of the earliest post */
  earliestPostedAt?: string;
  /** ISO 8601 timestamp of the latest post */
  latestPostedAt?: string;
  /** ISO 8601 timestamp of the most recent post */
  lastPostedAt?: string;
  /** ISO 8601 timestamp of the last stats update */
  lastStatsAt?: string;
  /** ISO 8601 timestamp when tracking started */
  trackingStartedAt?: string;
  /** Engagement rate percentage */
  engagementRate?: number;
}

interface CreatorAccountPaymentRuleInput {
  rule: PaymentRule;
  /** Fixed amount in USD (for flat rate rules) */
  amountUsd?: number;
  /** Percentage (for revenue share rules) */
  percent?: number;
  /** Minimum views threshold */
  minViews?: number;
  /** Maximum views threshold */
  maxViews?: number;
}

interface DeleteCreatorResponse {
  /** Whether the creator was deleted successfully */
  ok: boolean;
}

interface NewCreatorAccountPayload {
  platform: AccountPlatform;
  /** Account username (with @ prefix recommended) */
  username: string;
  /** Full URL to the account profile */
  accountUrl: string;
  /** Array of hashtags to track (optional) */
  hashtagsToTrack?: string[];
  /** Array of mentions to track (optional) */
  mentionsToTrack?: string[];
  /** Payment rules for this account (optional) */
  paymentRules?: CreatorAccountPaymentRuleInput[];
  /** Account status (optional, defaults to active) */
  accountStatus?: AccountStatus;
  /** Number of posts to track for this account. Must be one of: 10, 20, 40, 60, 80, 100. Maximum is 100. (optional, defaults to 20) */
  postsToTrack?: "10" | "20" | "40" | "60" | "80" | "100";
}

interface PaginatedCreators {
  /** Array of creators */
  items: Creator[];
  /** Current page number (1-indexed) */
  page: number;
  /** Number of items per page */
  limit: number;
  /** Total number of items across all pages */
  total: number;
  /** Total number of pages */
  totalPages: number;
  /** Whether there is a next page */
  hasNext: boolean;
  /** Whether there is a previous page */
  hasPrev: boolean;
}

type PaymentRule = "per_post_flat" | "cpm" | "monthly_flat" | "post_bonus_views" | "revenue_share";

interface UpdateCreatorRequest {
  /** Creator ID (UUID) to update */
  id: string;
  /** Creator name */
  name: string;
  /** Array of accounts to associate with this creator */
  accounts: NewCreatorAccountPayload[];
}

interface UpdateCreatorResponse {
  /** Whether the creator was updated successfully */
  ok: boolean;
  /** The slug (numeric identifier) of the updated creator (if returned) */
  creatorSlug?: number;
  /** Array of warning messages if some account updates failed (optional) */
  warnings?: string[];
}