@bisibility/sdk 0.1.0 → 0.1.2

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 export type Device = "desktop" | "mobile";
-export type RankCheckFrequency = "paused" | "manual" | "daily" | "weekly" | "custom_cron";
+export type RankCheckFrequency = "paused" | "manual" | "daily" | "weekly" | "monthly" | "custom_cron";
 export type JsonObject = Record<string, unknown>;
 export type RequestHeaders = HeadersInit;
 export interface ProblemDetails {
@@ -27,7 +27,7 @@ export interface PaginationOptions {
     cursor?: string;
     limit?: number;
 }
-export type ProjectWriteMode = "active" | "migration_hold";
+export type ProjectWriteMode = "active" | "migration_hold" | "migrated";
 export interface Project {
     created_at: string;
     domain: string;
@@ -67,13 +67,32 @@ export interface ProjectDefaultsPatch {
     timezone?: string;
 }
 export type TrackingScope = "city" | "country";
+export type LocationKind = "city" | "country" | "region";
+export interface LocationSuggestion {
+    city_name: string | null;
+    country_code: string;
+    display_name: string;
+    hl: string;
+    id: string;
+    kind: LocationKind;
+    language_label: string;
+    location_key: string;
+    region_code: string | null;
+    region_name: string | null;
+}
+export type LocationSuggestionsResponse = ListResponse<LocationSuggestion>;
+export interface SearchLocationsOptions {
+    country?: string;
+    limit?: number;
+    q: string;
+}
 export interface CreateProjectInput {
     /** Initial rank-check schedule defaults for the project. */
     defaults?: ProjectDefaultsPatch;
     domain: string;
     name: string;
     /** Location granularity for rank tracking. Defaults to "country" on the server. */
-    trackingScope?: TrackingScope;
+    tracking_scope?: TrackingScope;
 }
 export interface ApiKey {
     created_at: string;
@@ -120,7 +139,7 @@ export interface CreatedPersonalAccessToken extends PersonalAccessToken {
 }
 export interface CreateMyTokenInput {
     /** Days until the token expires, or null for no expiry. Defaults to null. */
-    expiresInDays?: 30 | 90 | 365 | null;
+    expires_in_days?: 30 | 90 | 365 | null;
     name: string;
     /** Token scope. Defaults to "read" on the server. */
     scope?: PersonalAccessTokenScope;
@@ -176,10 +195,10 @@ export interface Keyword {
     updated_at: string;
 }
 export interface KeywordScheduleInput {
-    autoSchedule?: boolean;
-    cronExpression: string | null;
+    auto_schedule?: boolean;
+    cron_expression: string | null;
     frequency: RankCheckFrequency;
-    jitterMinutes?: number;
+    jitter_minutes?: number;
     timezone?: string;
 }
 export interface CreateKeywordInput {
@@ -262,6 +281,157 @@ export interface ListKeywordsOptions extends PaginationOptions {
     tag?: string;
     topic?: string;
 }
+export interface RankedKeywordSuggestion {
+    already_tracked: boolean;
+    estimated_traffic: number | null;
+    keyword: string;
+    position: number | null;
+    search_volume: number | null;
+}
+export interface RankedKeywordConnection {
+    id: string;
+    label: string;
+    provider: "dataforseo";
+}
+export interface RankedKeywordSuggestionsResponse {
+    cached: boolean;
+    connections: RankedKeywordConnection[];
+    cost_cents: number;
+    fetched_at: string;
+    offset: number;
+    rows: RankedKeywordSuggestion[];
+    total_count: number | null;
+}
+export interface ListRankedKeywordSuggestionsOptions {
+    connectionId?: string;
+    fresh?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export type KeywordMetricsIntent = "informational" | "commercial" | "transactional" | "navigational" | "unknown";
+export interface KeywordMonthlyTrend {
+    month: number;
+    search_volume: number | null;
+    year: number;
+}
+export interface KeywordMetrics {
+    competition: number | null;
+    cpc_cents: number | null;
+    difficulty: number | null;
+    intent: KeywordMetricsIntent | null;
+    monthly_trend: KeywordMonthlyTrend[];
+    search_volume: number | null;
+}
+export interface KeywordMetricsRow extends KeywordMetrics {
+    keyword: string;
+}
+export interface KeywordResearchConnection {
+    id: string;
+    label: string;
+    provider: string;
+}
+export type KeywordResearchMode = "auto" | "related" | "suggestions" | "ideas";
+export type KeywordResearchResultLimit = 100 | 300 | 500;
+export type KeywordResearchSource = "related" | "suggestion" | "idea";
+export type KeywordResearchSourceReason = "budget_exhausted" | "cost_limit" | "in_progress" | "needs_reauth" | "no_source" | "previous_source_failed" | "provider_error" | "rate_limited" | "result_limit" | "unsupported_location";
+export type KeywordResearchSourceStatus = "ok" | "failed" | "skipped";
+export interface KeywordResearchRow extends KeywordMetricsRow {
+    already_tracked: boolean;
+    source: KeywordResearchSource;
+}
+export interface KeywordResearchSourceDiagnostic {
+    cached: boolean;
+    cost_cents: number;
+    reason?: KeywordResearchSourceReason;
+    returned: number;
+    source: KeywordResearchSource;
+    status: KeywordResearchSourceStatus;
+}
+export interface KeywordResearchResponse {
+    cached: boolean;
+    connections: KeywordResearchConnection[];
+    cost_cents: number;
+    estimate?: boolean;
+    fetched_at: string;
+    provider: string;
+    rows: KeywordResearchRow[];
+    sources: KeywordResearchSourceDiagnostic[];
+    total_count: number;
+}
+export interface ResearchKeywordsOptions {
+    connectionId?: string;
+    estimateOnly?: boolean;
+    fresh?: boolean;
+    includeClickstream?: boolean;
+    maxCostCents?: number;
+    mode?: KeywordResearchMode;
+    resultLimit?: KeywordResearchResultLimit;
+    seed: string;
+}
+export interface GetKeywordMetricsInput {
+    connection_id?: string;
+    estimate_only?: boolean;
+    fresh?: boolean;
+    include_clickstream?: boolean;
+    /** One to 700 keyword strings. */
+    keywords: readonly string[];
+    max_cost_cents?: number;
+}
+export interface KeywordMetricsResponse {
+    cached_count: number;
+    connections: KeywordResearchConnection[];
+    cost_cents: number;
+    estimate?: boolean;
+    estimated_cost_cents?: number;
+    fetched_at: string;
+    fetched_count: number;
+    fetched_count_estimate?: number;
+    provider: string;
+    rows: KeywordMetricsRow[];
+    total_count: number;
+}
+export type RankHistoryExportRange = "30" | "90" | "all";
+export type RankHistoryExportGranularity = "daily" | "weekly";
+export interface RankHistoryExportRow {
+    checked_at: string;
+    id: string;
+    keyword: string;
+    keyword_id: string;
+    position: number | null;
+    previous_position: number | null;
+    ranking_url: string | null;
+}
+export type RankHistoryExportResponse = ListResponse<RankHistoryExportRow>;
+interface RankHistoryExportOptions {
+    granularity?: RankHistoryExportGranularity;
+    keywordIds?: readonly string[];
+    range?: RankHistoryExportRange;
+}
+export interface ExportRankHistoryJsonOptions extends PaginationOptions, RankHistoryExportOptions {
+    format?: "json";
+}
+export interface ExportRankHistoryCsvOptions extends RankHistoryExportOptions {
+    format: "csv";
+}
+export type SitemapMonitorStatus = "active" | "disabled" | "pending";
+export interface SitemapMonitorSnapshot {
+    fetched_at: string;
+    id: string;
+    sitemap_url: string;
+    url_count: number;
+}
+export interface SitemapMonitor {
+    enabled: boolean;
+    id: string;
+    latest_snapshot: SitemapMonitorSnapshot | null;
+    project_id: string;
+    sitemap_url: string | null;
+    status: SitemapMonitorStatus;
+}
+export type SitemapMonitorListResponse = ListResponse<SitemapMonitor>;
+export interface UpdateSitemapMonitorInput {
+    enabled: boolean;
+}
 export type RankCheckStatus = "completed" | "failed" | "running";
 export interface RankCheckAttempt {
     message: string;
@@ -360,6 +530,13 @@ export interface TriggeredAlert {
     unread: boolean;
     when: string;
 }
+export interface TriggeredAlertMuteResult {
+    muted: true;
+    snoozed_until: string | null;
+}
+export interface TriggeredAlertsReadResult {
+    updated: number;
+}
 export type TeamRole = "admin" | "member" | "owner" | "viewer";
 export type TeamRoleLabel = "Admin" | "Editor" | "Owner" | "Viewer";
 export interface TeamMember {
@@ -391,6 +568,22 @@ export interface CreatedTeamInvite {
 export interface RevokedTeamInvite {
     id: string;
 }
+export type AssignableTeamRole = Exclude<TeamRole, "owner">;
+export interface UpdateTeamMemberRoleInput {
+    role: AssignableTeamRole;
+}
+export interface TeamMemberRoleResult {
+    id: string;
+    role: AssignableTeamRole;
+}
+export interface TeamMemberMutationResult {
+    id: string;
+}
+export interface TeamInviteResendResult {
+    expires_at: string;
+    id: string;
+    invite_link: string;
+}
 export type ProviderId = "dataforseo" | "ga4" | "gsc" | "plausible" | "serpapi";
 export type ProviderKind = "analytics" | "enrichment" | "serp";
 export type ProviderStatus = OpenString<"connected" | "optional" | "planned" | "ready">;
@@ -604,6 +797,84 @@ export interface NotificationPreferences {
     webhook_available?: boolean;
 }
 export type UpdateNotificationPreferencesInput = Partial<Pick<NotificationPreferences, "alert_email" | "alert_in_app" | "alert_slack" | "alert_webhook" | "check_email" | "check_in_app" | "import_email" | "import_in_app" | "invite_email" | "invite_in_app">>;
+export interface ListTrafficSnapshotsOptions {
+    endDate: Date | string;
+    limit?: number;
+    offset?: number;
+    paths?: readonly string[];
+    startDate: Date | string;
+}
+export interface PageTrafficSnapshot {
+    bounce_rate: number | null;
+    created_at: string;
+    date: string;
+    engagement_rate: number | null;
+    id: string;
+    key_events: number | null;
+    path: string;
+    project_id: string;
+    provider: string;
+    scroll_depth: number | null;
+    sessions: number;
+    updated_at: string;
+    visit_duration_seconds: number | null;
+    visitors: number | null;
+    window_days: number;
+}
+export interface PageTrafficSnapshotsResponse {
+    offset: number;
+    rows: PageTrafficSnapshot[];
+    total_count: number;
+}
+export interface ListSearchPerformanceQueryStatsOptions {
+    connectionId?: string;
+    endDate: Date | string;
+    limit?: number;
+    query?: string;
+    startDate: Date | string;
+}
+export interface AnalyticsConnection {
+    id: string;
+    label: string;
+    provider: string;
+}
+export interface SearchPerformanceQueryStat {
+    clicks: number;
+    ctr: number;
+    impressions: number;
+    page?: string | null;
+    position: number;
+    query: string;
+}
+export interface SearchPerformanceQueryStatsResponse {
+    connection: AnalyticsConnection;
+    rows: SearchPerformanceQueryStat[];
+}
+export type TrafficSyncRunStatus = "succeeded_with_data" | "succeeded_empty" | "deferred_rate_limit" | "failed" | "not_applicable";
+export interface TrafficSyncRun {
+    connection_id: string;
+    error?: string;
+    error_class?: string;
+    provider: string;
+    rows_fetched: number;
+    rows_matched: number;
+    rows_upserted: number;
+    status: TrafficSyncRunStatus;
+    truncated: boolean;
+}
+export type TrafficSyncSkippedReason = "no_capability" | "rate_limited";
+export interface TrafficSyncSkippedConnection {
+    provider: string;
+    reason: TrafficSyncSkippedReason;
+}
+export interface TrafficSyncSummary {
+    connections: number;
+    keyword_snapshots: number;
+    page_snapshots: number;
+    project_id: string;
+    runs: TrafficSyncRun[];
+    skipped: TrafficSyncSkippedConnection[];
+}
 export type MigrationScope = "full" | "keywords";
 export type CloudImportState = "done" | "failed" | "idle" | "importing" | "receiving";
 export interface CloudImportJob {
@@ -644,6 +915,182 @@ export interface MigrationTokenListMeta extends ListMeta {
 export interface MigrationTokenListResponse extends ListResponse<ActiveMigrationToken> {
     meta: MigrationTokenListMeta;
 }
+export type CloudImportSchemaVersion = 1 | 2 | 3;
+export type CloudImportLocation = "Australia" | "Austria" | "Belgium" | "Brazil" | "Canada" | "Denmark" | "Finland" | "France" | "Germany" | "India" | "Ireland" | "Italy" | "Japan" | "Mexico" | "Netherlands" | "New Zealand" | "Norway" | "Poland" | "Portugal" | "Singapore" | "South Africa" | "Spain" | "Sweden" | "Switzerland" | "United Arab Emirates" | "United Kingdom" | "United States";
+export interface CloudImportCompatibility {
+    app_version: string;
+    latest_migration: string | null;
+    schema_versions_supported: CloudImportSchemaVersion[];
+}
+export interface CloudImportRankingHistory {
+    checkedAt: string;
+    position?: number | null;
+    previousPosition?: number | null;
+    rankingUrl?: string | null;
+}
+export interface CloudImportKeyword {
+    country?: CloudImportLocation;
+    device?: Device;
+    id?: string;
+    keyword?: string;
+    location?: CloudImportLocation;
+    rankingHistory?: CloudImportRankingHistory[];
+    tags?: string[];
+    target_url?: string | null;
+    targetUrl?: string | null;
+    text?: string;
+}
+export interface CloudImportCompetitor {
+    domain: string;
+    label?: string | null;
+}
+export interface CloudImportSavedView {
+    config?: unknown;
+    name: string;
+    surface?: "competitors" | "keywords";
+}
+export type CloudImportAlertChannel = "email" | "slack" | "webhook";
+export type CloudImportAlertConditionType = "change_pct" | "competitor_overtake" | "enters_top_n" | "exits_top_n" | "serp_feature" | "threshold";
+export type CloudImportAlertTargetType = "all" | "keyword" | "tag";
+export interface CloudImportAlertRuleTarget {
+    device?: Device;
+    keyword?: string;
+    keyword_id?: string;
+    keywordId?: string;
+    location?: CloudImportLocation;
+    tag?: string;
+    tag_id?: string;
+    tagId?: string;
+    type?: "keyword" | "tag";
+}
+export interface CloudImportAlertRule {
+    change_pct?: number | null;
+    changePct?: number | null;
+    channels?: CloudImportAlertChannel[];
+    competitor_domain?: string | null;
+    competitorDomain?: string | null;
+    condition_type?: CloudImportAlertConditionType;
+    conditionType?: CloudImportAlertConditionType;
+    enabled?: boolean;
+    name: string;
+    serp_feature?: string | null;
+    serpFeature?: string | null;
+    target_type?: CloudImportAlertTargetType;
+    targets?: CloudImportAlertRuleTarget[];
+    targetType?: CloudImportAlertTargetType;
+    threshold_position?: number | null;
+    thresholdPosition?: number | null;
+    top_n?: number | null;
+    topN?: number | null;
+}
+export interface CloudImportNotificationPreference {
+    alert_email?: boolean;
+    alert_in_app?: boolean;
+    alertEmail?: boolean;
+    alertInApp?: boolean;
+    check_email?: boolean;
+    check_in_app?: boolean;
+    checkEmail?: boolean;
+    checkInApp?: boolean;
+    import_email?: boolean;
+    import_in_app?: boolean;
+    importEmail?: boolean;
+    importInApp?: boolean;
+    invite_email?: boolean;
+    invite_in_app?: boolean;
+    inviteEmail?: boolean;
+    inviteInApp?: boolean;
+}
+export interface CloudImportTopLevelRankCheck {
+    checked_at?: string;
+    checkedAt?: string;
+    keyword?: string;
+    keyword_id?: string;
+    keywordId?: string;
+    position?: number | null;
+    previous_position?: number | null;
+    previousPosition?: number | null;
+    ranking_url?: string | null;
+    rankingUrl?: string | null;
+    text?: string;
+}
+export type CloudImportScope = "current" | "history";
+export interface CloudImportPackage {
+    alert_rules?: CloudImportAlertRule[];
+    alertRules?: CloudImportAlertRule[];
+    competitors?: CloudImportCompetitor[];
+    exportedAt?: string;
+    keywords?: CloudImportKeyword[];
+    notification_preferences?: CloudImportNotificationPreference[];
+    notificationPreferences?: CloudImportNotificationPreference[];
+    projectId?: string;
+    rank_checks?: CloudImportTopLevelRankCheck[];
+    saved_views?: CloudImportSavedView[];
+    savedViews?: CloudImportSavedView[];
+    scope?: CloudImportScope;
+    version?: number;
+    [key: string]: unknown;
+}
+export type CloudImportCounts = Record<string, number>;
+export interface CloudImportFinalizeResponse {
+    counts: CloudImportCounts;
+    job_id: string;
+    state: "done";
+}
+export interface CloudImportSessionCreate {
+    chunk_count: number;
+    totals?: {
+        keywords?: number;
+        rank_checks?: number;
+    };
+    version: 3;
+}
+export interface CloudImportSessionCreateResponse {
+    chunk_limits: {
+        max_body_bytes: number;
+        max_history_rows: number;
+        max_keywords: number;
+    };
+    session_id: string;
+    state: "receiving";
+}
+export interface CloudImportSourceKeyword {
+    device: Device;
+    location: CloudImportLocation;
+    text: string;
+}
+export interface CloudImportSessionSections {
+    alert_rules?: CloudImportAlertRule[];
+    alertRules?: CloudImportAlertRule[];
+    competitors?: CloudImportCompetitor[];
+    notification_preferences?: CloudImportNotificationPreference[];
+    notificationPreferences?: CloudImportNotificationPreference[];
+    saved_views?: CloudImportSavedView[];
+    savedViews?: CloudImportSavedView[];
+    source_keyword_ids?: Record<string, CloudImportSourceKeyword>;
+    sourceKeywordIds?: Record<string, CloudImportSourceKeyword>;
+    [key: string]: unknown;
+}
+export interface CloudImportKeywordsChunk {
+    checksum: string;
+    keywords: CloudImportKeyword[];
+    kind: "keywords";
+}
+export interface CloudImportSectionsChunk {
+    checksum: string;
+    kind: "sections";
+    sections: CloudImportSessionSections;
+}
+export type CloudImportUploadChunk = CloudImportKeywordsChunk | CloudImportSectionsChunk;
+export interface UploadCloudImportChunkOptions extends RequestOptions {
+    /** Set to "gzip" when the JSON chunk body is gzip compressed. */
+    contentEncoding?: "gzip";
+}
+export interface CloudImportChunkResponse {
+    chunk_count: number;
+    chunks_received: number;
+    state: "receiving";
+}
 export type SignalSource = "api" | "cms" | "deploy" | "manual" | "rank_tracker" | "search_analytics" | "search_engine_status" | "sitemap" | "url_inspection";
 export type CreateSignalSource = "api" | "cms" | "deploy";
 export type SignalSeverity = "critical" | "info" | "warning";
@@ -774,19 +1221,23 @@ export interface RequestOptions {
     headers?: RequestHeaders;
     idempotencyKey?: string;
     signal?: AbortSignal;
-    /** Milliseconds before the request is aborted. Composed with any user-provided signal. */
-    timeout?: number;
+    /** Milliseconds before the request is aborted. Null disables the timeout. */
+    timeout?: number | null;
 }
 export interface BisibilityClientConfig {
     apiKey?: string;
     baseUrl?: string | URL;
     fetch?: FetchLike;
     headers?: RequestHeaders;
+    /** Number of retries after the initial attempt. Defaults to 2; 0 disables retries. */
+    maxRetries?: number;
     /**
      * Project id or public id sent as the X-Bisibility-Project header on every request.
      * Targets personal access token requests at a project on routes without one in the path.
      */
     projectId?: string;
+    /** Per-attempt timeout in milliseconds. Defaults to 30 seconds; null disables it. */
+    timeout?: number | null;
 }
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 export {};