@bisibility/sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,793 @@
+export type Device = "desktop" | "mobile";
+export type RankCheckFrequency = "paused" | "manual" | "daily" | "weekly" | "custom_cron";
+export type JsonObject = Record<string, unknown>;
+export type RequestHeaders = HeadersInit;
+export interface ProblemDetails {
+    detail?: string;
+    docs_url?: string;
+    errors?: unknown;
+    instance?: string;
+    status?: number;
+    title?: string;
+    type?: string;
+}
+export interface ListMeta {
+    next_cursor: string | null;
+    [key: string]: unknown;
+}
+export interface ListResponse<T> {
+    data: T[];
+    meta: ListMeta;
+}
+export interface DataResponse<T> {
+    data: T;
+    meta?: JsonObject;
+}
+export interface PaginationOptions {
+    cursor?: string;
+    limit?: number;
+}
+export type ProjectWriteMode = "active" | "migration_hold";
+export interface Project {
+    created_at: string;
+    domain: string;
+    id: string;
+    name: string;
+    updated_at: string;
+    write_mode: ProjectWriteMode;
+}
+export interface UpdateProjectInput {
+    domain?: string;
+    name?: string;
+}
+export interface ProjectDefaults {
+    auto_schedule: boolean;
+    city: string | null;
+    country: string;
+    cron_expression: string | null;
+    device: Device;
+    frequency: RankCheckFrequency;
+    jitter_minutes: number;
+    last_checked_at: string | null;
+    location_key: string;
+    next_check_at: string | null;
+    project_id: string;
+    timezone: string;
+    updated_at: string | null;
+}
+export interface ProjectDefaultsPatch {
+    auto_schedule?: boolean;
+    city?: string | null;
+    country?: string;
+    cron_expression?: string | null;
+    device?: Device;
+    frequency?: RankCheckFrequency;
+    jitter_minutes?: number;
+    location_key?: string;
+    timezone?: string;
+}
+export type TrackingScope = "city" | "country";
+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;
+}
+export interface ApiKey {
+    created_at: string;
+    id: string;
+    last_used_at: string | null;
+    name: string;
+    prefix: string;
+    revoked_at: string | null;
+}
+export interface CreatedApiKey extends ApiKey {
+    masked_value: string;
+    token: string;
+}
+export type MembershipRole = "admin" | "auditor" | "member" | "owner" | "viewer";
+export interface MeProject {
+    domain: string;
+    id: string;
+    name: string;
+    role: MembershipRole;
+}
+export interface Me {
+    email: string;
+    id: string;
+    name: string;
+    projects: MeProject[];
+}
+export interface UpdateMeInput {
+    name: string;
+}
+export type PersonalAccessTokenScope = "admin" | "read" | "write";
+export interface PersonalAccessToken {
+    created_at: string;
+    expires_at: string | null;
+    id: string;
+    last_used_at: string | null;
+    name: string;
+    prefix: string;
+    revoked_at: string | null;
+    scope: PersonalAccessTokenScope;
+}
+export interface CreatedPersonalAccessToken extends PersonalAccessToken {
+    masked_value: string;
+    token: string;
+}
+export interface CreateMyTokenInput {
+    /** Days until the token expires, or null for no expiry. Defaults to null. */
+    expiresInDays?: 30 | 90 | 365 | null;
+    name: string;
+    /** Token scope. Defaults to "read" on the server. */
+    scope?: PersonalAccessTokenScope;
+}
+export interface Webhook {
+    created_at: string;
+    description: string | null;
+    enabled: boolean;
+    id: string;
+    last_delivery_at: string | null;
+    updated_at: string;
+    url: string;
+}
+export interface CreateWebhookInput {
+    description?: string | null;
+    enabled?: boolean;
+    /** HMAC signing secret (minimum 16 characters). Write-only; never returned by the API. */
+    hmac_secret: string;
+    url: string;
+}
+export interface UpdateWebhookInput {
+    description?: string | null;
+    enabled?: boolean;
+    /** HMAC signing secret (minimum 16 characters). Write-only; never returned by the API. */
+    hmac_secret?: string;
+    url?: string;
+}
+export interface KeywordSchedule {
+    auto_schedule: boolean;
+    cron_expression: string | null;
+    frequency: RankCheckFrequency;
+    jitter_minutes: number;
+    last_checked_at: string | null;
+    next_check_at: string | null;
+    timezone: string;
+}
+export interface Keyword {
+    country: string;
+    created_at: string;
+    device: Device;
+    id: string;
+    intent: string | null;
+    latest_position: number | null;
+    location: string;
+    previous_position: number | null;
+    project_id: string;
+    ranking_url: string | null;
+    schedule: KeywordSchedule | null;
+    tags: string[];
+    target_url: string | null;
+    text: string;
+    topic: string | null;
+    updated_at: string;
+}
+export interface KeywordScheduleInput {
+    autoSchedule?: boolean;
+    cronExpression: string | null;
+    frequency: RankCheckFrequency;
+    jitterMinutes?: number;
+    timezone?: string;
+}
+export interface CreateKeywordInput {
+    city?: string | null;
+    country?: string;
+    device?: Device;
+    intent?: string | null;
+    keyword: string;
+    location?: string;
+    location_key?: string;
+    schedule?: KeywordScheduleInput;
+    tags?: readonly string[];
+    target_url?: string | null;
+    topic?: string | null;
+}
+export type CreateKeywordItem = string | CreateKeywordInput;
+export type CreateKeywordsInput = CreateKeywordInput | readonly CreateKeywordInput[] | {
+    keywords: readonly CreateKeywordItem[];
+};
+type OpenString<T extends string> = T | (string & Record<never, never>);
+export interface CreateKeywordResult {
+    keyword: Keyword;
+    status: OpenString<"created" | "skipped">;
+    warning?: string;
+}
+export interface CreateKeywordsResponse {
+    created: number;
+    results: CreateKeywordResult[];
+    skipped: number;
+    warnings?: string[];
+}
+export interface UpdateKeywordInput {
+    city?: string | null;
+    country?: string;
+    device?: Device;
+    frequency?: RankCheckFrequency;
+    intent?: string | null;
+    keyword?: string;
+    location?: string;
+    location_key?: string;
+    schedule?: KeywordScheduleInput;
+    tags?: readonly string[];
+    target_url?: string | null;
+    topic?: string | null;
+}
+export type KeywordBulkOperation = "add_tags" | "delete" | "remove_tags" | "set_frequency" | "set_target_url";
+export type KeywordBulkInput = {
+    keyword_ids: readonly string[];
+    operation: "add_tags" | "remove_tags";
+    tags: readonly string[];
+} | {
+    keyword_ids: readonly string[];
+    operation: "delete";
+} | {
+    keyword_ids: readonly string[];
+    operation: "set_frequency";
+    frequency?: RankCheckFrequency;
+    schedule?: KeywordScheduleInput;
+} | {
+    keyword_ids: readonly string[];
+    operation: "set_target_url";
+    target_url?: string | null;
+};
+export interface KeywordBulkItemResult {
+    keyword_id: string;
+    status: OpenString<"deleted" | "not_found" | "updated">;
+}
+export interface KeywordBulkResponse {
+    operation: KeywordBulkOperation;
+    results: KeywordBulkItemResult[];
+}
+export interface ListKeywordsOptions extends PaginationOptions {
+    country?: string;
+    device?: Device;
+    intent?: string;
+    positionGt?: number;
+    positionLt?: number;
+    search?: string;
+    sort?: "created_at" | "-created_at" | "keyword" | "-keyword" | "text" | "-text" | "updated_at" | "-updated_at";
+    tag?: string;
+    topic?: string;
+}
+export type RankCheckStatus = "completed" | "failed" | "running";
+export interface RankCheckAttempt {
+    message: string;
+    provider: string;
+}
+export interface RankCheck {
+    attempts: RankCheckAttempt[] | null;
+    checked_at: string;
+    cost_cents: number | null;
+    error: string | null;
+    id: string;
+    keyword_id: string;
+    position: number | null;
+    previous_position: number | null;
+    provider: string;
+    ranking_url: string | null;
+    status: RankCheckStatus;
+}
+export interface ListRankChecksOptions extends PaginationOptions {
+    since?: Date | string;
+    status?: RankCheckStatus;
+    until?: Date | string;
+}
+export interface RunRankCheckInput {
+    provider_id?: ProviderId;
+}
+export interface RunRankCheckOptions extends RequestOptions {
+    async?: boolean;
+}
+export type AlertConditionType = "change_pct" | "competitor_overtake" | "enters_top_n" | "exits_top_n" | "serp_feature" | "threshold";
+export type AlertChannel = "email" | "slack" | "webhook";
+export type AlertTargetType = "all" | "keyword" | "tag";
+export type AlertSeverity = "info" | "urgent" | "warning";
+export interface AlertRuleTarget {
+    created_at?: string;
+    id: string;
+    keyword_id?: string | null;
+    rule_id?: string;
+    tag_id?: string | null;
+    updated_at?: string;
+}
+export interface AlertRule {
+    change_pct?: number | string | null;
+    channel?: string;
+    channels: AlertChannel[];
+    condition?: string;
+    condition_type: AlertConditionType;
+    competitor_domain?: string | null;
+    created_at?: string;
+    created_by_id?: string | null;
+    enabled: boolean;
+    fires?: string;
+    id: string;
+    name: string;
+    period?: string;
+    project_id?: string;
+    scope?: string;
+    serp_feature?: string | null;
+    severity?: AlertSeverity;
+    status?: OpenString<"active" | "paused">;
+    target_ids?: string[];
+    target_type: AlertTargetType;
+    targets?: AlertRuleTarget[];
+    threshold_position?: number | null;
+    top_n?: number | null;
+    updated_at?: string;
+}
+export interface AlertRuleInput {
+    change_pct?: number | null;
+    channels?: readonly AlertChannel[];
+    condition_type: AlertConditionType;
+    competitor_domain?: string | null;
+    enabled?: boolean;
+    name: string;
+    serp_feature?: string | null;
+    target_ids?: readonly string[];
+    target_type?: AlertTargetType;
+    threshold_position?: number | null;
+    top_n?: number | null;
+}
+export type CreateAlertRuleInput = AlertRuleInput;
+export type UpdateAlertRuleInput = AlertRuleInput;
+export interface DeleteAlertRuleResponse {
+    deleted: boolean;
+}
+export interface TriggeredAlert {
+    action: string;
+    ctas: string[];
+    current: string;
+    headline: string;
+    id: string;
+    keyword: string;
+    previous: string;
+    rule: string;
+    severity: AlertSeverity;
+    unread: boolean;
+    when: string;
+}
+export type TeamRole = "admin" | "member" | "owner" | "viewer";
+export type TeamRoleLabel = "Admin" | "Editor" | "Owner" | "Viewer";
+export interface TeamMember {
+    color: OpenString<"accent" | "blue" | "purple">;
+    email: string;
+    id: string;
+    initials: string;
+    name: string;
+    role: TeamRoleLabel;
+    role_value: TeamRole;
+}
+export interface TeamInvite {
+    email: string;
+    expires_label: string;
+    id: string;
+    invited_label: string;
+    role: TeamRoleLabel;
+    role_value: Exclude<TeamRole, "owner">;
+}
+export interface CreateTeamInviteInput {
+    email: string;
+    role: Exclude<TeamRole, "owner">;
+}
+export interface CreatedTeamInvite {
+    expires_at: string;
+    id: string;
+    invite_link: string;
+}
+export interface RevokedTeamInvite {
+    id: string;
+}
+export type ProviderId = "dataforseo" | "ga4" | "gsc" | "plausible" | "serpapi";
+export type ProviderKind = "analytics" | "enrichment" | "serp";
+export type ProviderStatus = OpenString<"connected" | "optional" | "planned" | "ready">;
+export type ProviderIconName = "chart" | "database" | "globe" | "link" | "magnifier" | "table" | "trend";
+export interface ProviderMetaRow {
+    label: string;
+    value: string;
+}
+export interface ProviderCredentialField {
+    label: string;
+    name: OpenString<"login" | "secret">;
+    placeholder: string;
+    type?: OpenString<"password" | "text">;
+}
+export interface ProviderDrawerDefaults {
+    cost_per_check: number;
+    depth: string;
+    device: string;
+    enabled?: boolean;
+    language: string;
+    location: string;
+    login: string;
+    primary: boolean;
+    priority?: number;
+    secret: string;
+}
+export interface ProviderDrawer {
+    activities: ProviderMetaRow[];
+    cost_help: string;
+    credential_fields: ProviderCredentialField[];
+    defaults: ProviderDrawerDefaults;
+    env_hint: string;
+    primary_toggle_label: string;
+}
+export interface Provider {
+    category_id: string;
+    category_title: string;
+    description: string;
+    drawer: ProviderDrawer;
+    enabled?: boolean;
+    icon: ProviderIconName;
+    id: OpenString<ProviderId>;
+    logo_domain?: string;
+    meta: ProviderMetaRow[];
+    name: string;
+    primary?: boolean;
+    priority?: number;
+    secondary_action?: string;
+    status: ProviderStatus;
+    tint: string;
+}
+export interface ProviderCredentialsInput {
+    api_key?: string;
+    endpoint?: string;
+    login?: string;
+    secret?: string;
+}
+export interface ConnectProviderInput {
+    cost_per_check?: number;
+    credentials?: ProviderCredentialsInput;
+    enabled?: boolean;
+    login?: string;
+    primary?: boolean;
+    priority?: number;
+    secret?: string;
+}
+export interface TestProviderConnectionInput {
+    credentials?: ProviderCredentialsInput;
+    login?: string;
+    secret?: string;
+}
+export interface ProviderSettingsInput {
+    enabled?: boolean;
+    primary?: boolean;
+    priority?: number;
+}
+export interface ProviderConnection {
+    cost_per_check_cents: number | string | null;
+    created_at: string;
+    credentials_hash?: string | null;
+    enabled: boolean;
+    id: string;
+    is_primary: boolean;
+    kind: ProviderKind;
+    last_used_at: string | null;
+    priority: number;
+    project_id: string;
+    provider: OpenString<ProviderId>;
+    status: ProviderStatus;
+    updated_at: string;
+}
+export interface ProviderTestResult {
+    balance?: number;
+    message: string;
+    ok: boolean;
+}
+export interface ProviderDisconnectResponse {
+    ok: boolean;
+}
+export type SavedViewFilterChange = "any" | "down" | "lost" | "new" | "up";
+export type SavedViewFilterCountry = "all" | "de" | "gb" | "pl" | "us";
+export type SavedViewFilterDevice = "all" | Device;
+export type SavedViewPositionFilter = "11-50" | "51-100" | "top10" | "top3";
+export type SavedViewSerpFilter = "ai" | "featured" | "image" | "paa" | "sitelinks" | "video";
+export interface SavedViewFilters {
+    change: SavedViewFilterChange;
+    contains: string;
+    country: SavedViewFilterCountry;
+    device: SavedViewFilterDevice;
+    position: SavedViewPositionFilter[];
+    serp: SavedViewSerpFilter[];
+    tags: string[];
+    vol_max: number;
+    vol_min: number;
+    wrong_url: boolean;
+}
+export interface SavedViewConfig {
+    filters: SavedViewFilters;
+    search: string;
+}
+export interface CreateSavedViewInput {
+    config: SavedViewConfig;
+    name: string;
+}
+export interface SavedView {
+    config: SavedViewConfig;
+    created_at: string;
+    created_by_id: string | null;
+    id: string;
+    name: string;
+}
+export interface DeleteSavedViewResponse {
+    deleted: boolean;
+}
+export interface Competitor {
+    domain: string;
+    id: string;
+    initials?: string;
+    label: string | null;
+}
+export interface AddCompetitorInput {
+    domain: string;
+    label?: string;
+}
+export interface RemoveCompetitorResponse {
+    removed: boolean;
+}
+export type CompetitorKind = "Managed" | "You";
+export interface CompetitorColumn {
+    domain: string;
+    id?: string;
+    kind: CompetitorKind;
+    label: string;
+}
+export interface CompetitorShare {
+    color: string;
+    domain: string;
+    id?: string;
+    initials: string;
+    kind: CompetitorKind;
+    label: string;
+    share_of_voice: number;
+    shared_keywords: number;
+}
+export interface HeadToHeadRow {
+    gap: number | null;
+    keyword: string;
+    ranks: Record<string, number | null>;
+}
+export interface CompetitorMarket {
+    checked_keyword_count: number;
+    columns: CompetitorColumn[];
+    competitor_count: number;
+    country: string;
+    device: string;
+    engine: string;
+    has_rank_data: boolean;
+    key: string;
+    rows: HeadToHeadRow[];
+    shares: CompetitorShare[];
+    shared_keyword_count: number;
+    tracked_keyword_count: number;
+}
+export interface SuggestedCompetitor {
+    domain: string;
+    initials: string;
+    overlap: number;
+}
+export interface CompetitorListMeta extends ListMeta {
+    markets: CompetitorMarket[];
+    suggestions: SuggestedCompetitor[];
+}
+export interface CompetitorListResponse extends ListResponse<Competitor> {
+    meta: CompetitorListMeta;
+}
+export interface NotificationPreferences {
+    alert_email: boolean;
+    alert_in_app: boolean;
+    alert_slack: boolean;
+    alert_webhook: boolean;
+    check_email: boolean;
+    check_in_app: boolean;
+    email?: string;
+    email_verification?: "unverified" | "verified";
+    import_email: boolean;
+    import_in_app: boolean;
+    invite_email: boolean;
+    invite_in_app: boolean;
+    project_id: string;
+    slack_available?: boolean;
+    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 type MigrationScope = "full" | "keywords";
+export type CloudImportState = "done" | "failed" | "idle" | "importing" | "receiving";
+export interface CloudImportJob {
+    counts: unknown;
+    created_at: string | null;
+    error: string | null;
+    finished_at: string | null;
+    id: string | null;
+    progress: number;
+    started_at: string | null;
+    state: CloudImportState;
+}
+export interface ActiveMigrationToken {
+    created_at: string;
+    created_by?: {
+        email: string;
+        name: string;
+    };
+    expires_at: string;
+    id: string;
+    scope: MigrationScope;
+    single_use: boolean;
+}
+export interface IssuedMigrationToken extends ActiveMigrationToken {
+    import_job: CloudImportJob;
+    token: string;
+}
+export interface MintMigrationTokenInput {
+    scope?: MigrationScope;
+}
+export interface RevokedMigrationToken {
+    id: string;
+    revoked_at: string;
+}
+export interface MigrationTokenListMeta extends ListMeta {
+    import_job: CloudImportJob;
+}
+export interface MigrationTokenListResponse extends ListResponse<ActiveMigrationToken> {
+    meta: MigrationTokenListMeta;
+}
+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";
+export interface Signal {
+    created_at: string;
+    happened_at: string;
+    id: string;
+    keyword_id: string | null;
+    payload: JsonObject | null;
+    project_id: string;
+    public_id: string;
+    severity: SignalSeverity;
+    source: SignalSource;
+    type: string;
+    url: string | null;
+}
+export interface CreateSignalInput {
+    /** ISO-8601 date-time when the signal happened. Defaults to now on the server. */
+    happened_at?: string;
+    keyword_id?: string;
+    /** JSON object payload. Ingestion rejects serialized payloads above 8KB. */
+    payload?: JsonObject;
+    severity?: SignalSeverity;
+    source: CreateSignalSource;
+    /** Dot-separated signal type such as "deploy.completed" (`^[a-z_]+\.[a-z_]+$`). */
+    type: string;
+    url?: string;
+}
+export interface ListSignalsOptions extends PaginationOptions {
+    from?: Date | string;
+    source?: SignalSource;
+    to?: Date | string;
+    type?: string;
+}
+export type CostEstimateFrequency = "daily" | "monthly" | "weekly";
+export type PricingModel = "flat" | "plan";
+export interface GetCostEstimateOptions {
+    /** Device count per keyword (1 or 2). Defaults to 1. */
+    devices?: number;
+    /** Rank-check frequency used to estimate monthly checks. Defaults to "daily". */
+    frequency?: CostEstimateFrequency;
+    /** Keyword count. Required; integer between 0 and 100000. */
+    keywords: number;
+    /** Location count per keyword. Defaults to 1; maximum 100. */
+    locations?: number;
+    /** Flat-rate provider option key, for example "standard", "priority", or "live". */
+    option?: string;
+    /** Plan-model provider plan key; unknown values use auto selection. */
+    plan?: string;
+    /** Provider rate card to use. Defaults to "dataforseo". */
+    provider?: string;
+}
+export interface ProviderRateOption {
+    key: string;
+    label: string;
+    short_label: string;
+    turnaround: string;
+    unit_cost_cents: number;
+    unit_cost_usd: number;
+}
+export interface ProviderRatePlan {
+    included_checks: number;
+    label: string;
+    monthly_price_cents: number;
+    monthly_price_usd: number;
+    plan_key: string;
+}
+export interface ProviderRateBase {
+    checked_at: string;
+    label: string;
+    notes?: string;
+    provider_id: string;
+    source_url: string;
+}
+export interface FlatProviderRate extends ProviderRateBase {
+    options: ProviderRateOption[];
+    pricing_model: "flat";
+}
+export interface PlanProviderRate extends ProviderRateBase {
+    plans: ProviderRatePlan[];
+    pricing_model: "plan";
+}
+export type ProviderRate = FlatProviderRate | PlanProviderRate;
+export interface CostEstimateBase {
+    checks_per_run: number;
+    effective_cost_per_check_cents: number;
+    exceeds_largest_plan: boolean;
+    exceeds_selected_plan: boolean;
+    monthly_checks: number;
+    monthly_cost_cents: number;
+    monthly_cost_usd: number;
+    provider_id: string;
+    rate_checked_at: string;
+    rate_source_url: string;
+}
+export interface FlatCostEstimate extends CostEstimateBase {
+    pricing_model: "flat";
+    selected_option: ProviderRateOption;
+}
+export interface PlanCostEstimate extends CostEstimateBase {
+    pricing_model: "plan";
+    selected_plan: ProviderRatePlan;
+}
+export type CostEstimate = FlatCostEstimate | PlanCostEstimate;
+export interface HealthResponse {
+    checked_at: string;
+    providers: {
+        serp: string[];
+    };
+    services: {
+        app: string;
+        database: OpenString<"degraded" | "ok">;
+    };
+    status: OpenString<"degraded" | "ok">;
+}
+export interface Capability {
+    description: string;
+    input_schema: JsonObject;
+    name: string;
+    operationId: string;
+}
+export interface OpenApiDocument extends JsonObject {
+    info: JsonObject;
+    openapi: string;
+    paths: JsonObject;
+}
+export interface RequestOptions {
+    headers?: RequestHeaders;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+    /** Milliseconds before the request is aborted. Composed with any user-provided signal. */
+    timeout?: number;
+}
+export interface BisibilityClientConfig {
+    apiKey?: string;
+    baseUrl?: string | URL;
+    fetch?: FetchLike;
+    headers?: RequestHeaders;
+    /**
+     * 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;
+}
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export {};
+//# sourceMappingURL=types.d.ts.map