bisibility 0.2.1__tar.gz

bisibility-0.2.1/.gitignore

@@ -0,0 +1,22 @@
+.venv/
+__pycache__/
+*.py[cod]
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+coverage/*
+!coverage/operations.json
+htmlcov/
+
+build/
+dist/
+*.egg-info/
+
+.env
+.env.*
+!.env.example
+
+.DS_Store

bisibility-0.2.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

bisibility-0.2.1/NOTICE

@@ -0,0 +1,5 @@
+Bisibility SDK for Python
+Copyright (c) 2026 CorgiCorner
+
+This product is licensed under the Apache License, Version 2.0 (Apache-2.0).
+See the LICENSE file for the full license text.

bisibility-0.2.1/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: bisibility
+Version: 0.2.1
+Summary: Python SDK for the Bisibility REST API.
+Project-URL: Homepage, https://bisibility.com
+Project-URL: Documentation, https://bisibility.com/docs/api
+Project-URL: Source, https://github.com/CorgiCorner/bisibility-sdk-python
+Author: Bisibility
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: api,bisibility,rank-tracking,sdk,seo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: hatchling>=1.25; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bisibility
+
+> Part of [bisibility](https://github.com/CorgiCorner/bisibility) - open-source keyword
+> rank tracking you can self-host and automate. This repository contains the Python SDK
+> for the Bisibility REST API.
+>
+> [Docs](https://bisibility.com/docs) ·
+> [API reference](https://bisibility.com/docs/api/overview) ·
+> [Roadmap](https://bisibility.com/roadmap)
+>
+> **Status:** In development; not yet published to PyPI.
+
+Python SDK for the Bisibility REST API.
+
+## Install
+
+```sh
+pip install bisibility
+```
+
+For local development:
+
+```sh
+pip install -e .[dev]
+```
+
+## Quickstart
+
+```python
+import os
+
+from bisibility import BisibilityClient
+
+bisibility = BisibilityClient(api_key=os.environ["BISIBILITY_API_KEY"])
+
+projects = bisibility.list_projects()
+project_id = projects.data[0].id if projects.data else None
+
+if project_id:
+    created = bisibility.create_keywords(
+        project_id,
+        {
+            "keywords": [
+                {
+                    "keyword": "rank tracker api",
+                    "target_url": "https://example.com/rank-tracker",
+                    "tags": ["api"],
+                }
+            ]
+        },
+    )
+
+    keyword_id = created.results[0].keyword.id if created.results else None
+    if keyword_id:
+        check = bisibility.run_rank_check(keyword_id)
+        print(check.position, check.ranking_url)
+```
+
+## Configuration
+
+```python
+from bisibility import BisibilityClient
+
+bisibility = BisibilityClient(
+    api_key="bsk_live_...",
+    base_url="https://bisibility.com/api/v1",
+    timeout=30.0,
+)
+```
+
+`base_url` should point at the API v1 root. Protected methods send
+`Authorization: Bearer <api_key>`. Write methods accept `RequestOptions` with an
+`idempotency_key`, which maps to the server `Idempotency-Key` header.
+
+The client accepts project API keys (`bsk_live_...`) and personal access tokens
+(`bsp_live_...`). For a PAT with multiple project memberships, pass
+`project_id="prj_abc123"` to send `X-Bisibility-Project` on project-implicit
+routes. PAT methods include `get_me`, `create_project`, personal-token
+self-management, project API-key minting, and webhook CRUD.
+
+The default timeout is 30 seconds per attempt. Pass `timeout=None` to the client
+to opt out globally, or `RequestOptions(timeout=None)` for one request. The SDK
+sends `User-Agent: bisibility-sdk-python/<version>` unless you supplied a user
+agent, and always sends the matching `X-Bisibility-Client` header.
+
+### Retries
+
+Failed requests are retried automatically up to `max_retries` times (default 2)
+when the failure is an `httpx` transport error or a `429`/`503` response. Only
+requests that are safe to replay are retried: idempotent
+`GET`/`HEAD`/`PUT`/`DELETE` requests are always eligible, while non-idempotent
+`POST`/`PATCH` requests are retried only when an `Idempotency-Key` header is present (set via
+`RequestOptions(idempotency_key=...)`). When
+the server sends a `Retry-After` header in seconds or HTTP-date form, the client
+waits that long (capped at 60 seconds); otherwise it uses capped exponential
+backoff (0.5s, 1s, 2s, ... up to 8s). Set `max_retries=0` to disable retries.
+
+```python
+bisibility = BisibilityClient(api_key="bsk_live_...", max_retries=3)
+```
+
+```python
+from bisibility import RequestOptions
+
+bisibility.create_api_key(
+    {"name": "CI"},
+    request_options=RequestOptions(idempotency_key="request-123"),
+)
+```
+
+## Methods
+
+- Discovery: `get_health`, `get_open_api`, `get_capabilities`, `get_llms_text`
+- Public cost (no auth): `get_provider_rates`, `get_cost_estimate`
+- Projects: `list_projects`, `get_project`, `update_project`, `delete_project`,
+  `update_project_defaults`
+- API keys: `list_api_keys`, `create_api_key`, `revoke_api_key`
+- Keywords: `list_keywords`, `create_keywords`, `add_keywords`, `get_keyword`,
+  `update_keyword`, `set_keyword_target_url`, `delete_keyword`, `bulk_update_keywords`
+- Keyword research: `research_keywords` for one seed and `get_keyword_metrics` for
+  batches of up to 700 keywords. Both require API write scope because a cache miss can
+  spend provider budget. Pass `estimate_only=True` for a free cache-aware dry run and
+  `max_cost_cents` for a best-effort request guard. Research source diagnostics report
+  `ok`, `failed`, or `skipped`, including a machine-readable reason when applicable.
+  Both methods expose nullable provider metrics, cache metadata, and paid BYO-key cost.
+- Rank checks: `list_rank_checks`, `run_rank_check`, `get_rank_check_result`
+- Signals: `create_signal`, `list_project_signals`
+- Alert rules: `list_alert_rules`, `create_alert_rule`, `update_alert_rule`,
+  `delete_alert_rule`, `list_triggered_alerts`, `mute_triggered_alert`,
+  `mark_project_alerts_read`
+- Rank-history export: `export_rank_history` for typed cursor-paginated JSON or raw CSV text
+- Sitemap monitors: `list_sitemap_monitors`, `update_sitemap_monitor`
+- Team: `list_team_members`, `list_team_invites`, `create_team_invite`,
+  `revoke_project_team_invite`, `revoke_team_invite`
+- Providers: `list_providers`, `connect_provider`, `test_provider_connection`,
+  `update_provider_settings`, `set_provider_enabled`, `set_provider_priority`,
+  `set_primary_provider`, `disconnect_provider`
+- Saved views: `list_saved_views`, `create_saved_view`, `delete_project_saved_view`,
+  `delete_saved_view`
+- Competitors: `list_competitors`, `add_competitor`, `remove_project_competitor`,
+  `remove_competitor`
+- Notification preferences: `get_notification_preferences`, `update_notification_preferences`
+- Migration tokens: `list_migration_tokens`, `mint_migration_token`,
+  `revoke_project_migration_token`, `revoke_migration_token`
+
+List methods return `ListResponse[T]` with `data` and `meta.next_cursor`. Resource
+methods return pydantic models matching the Bisibility API response shape.
+
+Keyword research uses a single seed and a result limit of 100, 300, or 500. Metrics
+requests accept at most 700 keywords per call, matching the REST contract. Split larger
+batches explicitly so each response retains its own cache counts and provider cost.
+
+Cursor-paginated resources also expose lazy `iter_*` generators. They preserve
+the supplied filters, request pages only as needed, and stop when
+`meta.next_cursor` is `None`:
+
+```python
+from bisibility import ListKeywordsOptions
+
+for keyword in bisibility.iter_keywords(
+    "prj_123",
+    ListKeywordsOptions(tag="Product", limit=100),
+):
+    print(keyword.text)
+```
+
+Iterators are available for keywords, rank checks, signals, API keys (including
+project API keys), webhooks, alert rules, triggered alerts, team members, team
+invites, providers, saved views, competitors, and migration tokens.
+
+### Webhook secret rotation
+
+To rotate a webhook secret, set `hmac_secret` on `WebhookUpdateInput` to a
+non-empty string. Sending a null, empty, or whitespace-only secret is rejected.
+Omit `hmac_secret` entirely to leave the existing secret unchanged; omitted
+fields are not included in the PATCH request.
+
+All SDK-defined exceptions derive from `BisibilityError`. `BisibilityApiError`
+also exposes `is_rate_limit`, `is_not_found`, and `retry_after_seconds` helpers.
+Problem responses follow RFC 9457 and preserve extension members; sensitive
+response headers are removed before an API error is exposed.
+
+There is intentionally no `create_project` method: the API returns
+`403 Forbidden` for `POST /projects` because project-scoped API keys cannot
+create projects. Create projects from the Bisibility app instead.
+
+`list_keywords` supports `country`, `device`, `tag`, `topic`, `intent`,
+`position_gt`/`position_lt`, `search` and `sort` filters via
+`ListKeywordsOptions` (or a plain dict); `topic` and `intent` match the keyword
+classification fields, case-insensitively.
+
+### Signals
+
+Ingest deploy/CMS/API events as signals and read them back per project.
+`create_signal` requires `source` (`"deploy"`, `"cms"`, or `"api"`) and `type`
+(shaped like `category.event`, e.g. `"deploy.completed"`); `payload` must
+serialize to 8KB or less. `list_project_signals` returns signals newest first
+and accepts `source`, `type` and a `from`/`to` time range (use the `from_`
+field name, or the `"from"` key in a dict).
+
+```python
+from bisibility import CreateSignalInput, ListSignalsOptions
+
+emitted = bisibility.create_signal(
+    CreateSignalInput(
+        source="deploy",
+        type="deploy.completed",
+        payload={"version": "1.2.3"},
+        url="https://example.com/releases/1",
+    )
+)
+
+signals = bisibility.list_project_signals(
+    "prj_123",
+    ListSignalsOptions(source="deploy", from_="2026-07-01T00:00:00Z"),
+)
+```
+
+### Public cost estimates
+
+`get_provider_rates` and `get_cost_estimate` are public discovery endpoints and
+work without an API key. `get_cost_estimate` requires `keywords` and accepts
+`locations`, `devices` (1-2), `frequency` (`"daily"`, `"weekly"`,
+`"monthly"`), `provider`, and a flat-rate `option` or plan `plan` selector.
+Both return a `DataResponse` whose `data` is typed (`list[ProviderRate]` and
+`CostEstimate`).
+
+```python
+from bisibility import BisibilityClient, CostEstimateOptions
+
+anonymous = BisibilityClient()  # no api_key needed for these calls
+
+rates = anonymous.get_provider_rates()
+estimate = anonymous.get_cost_estimate(
+    CostEstimateOptions(keywords=248, frequency="daily", provider="dataforseo")
+)
+print(estimate.data.monthly_cost_usd)
+```
+
+### Async rank checks
+
+`run_rank_check` blocks until the check completes by default. Pass
+`async_mode=True` to queue the check instead: the server responds with
+`202 Accepted` and a rank check in status `"running"`; poll
+`get_rank_check_result` until the status becomes `"completed"` or `"failed"`.
+
+```python
+queued = bisibility.run_rank_check("kw_123", async_mode=True)
+assert queued.status == "running"
+
+result = bisibility.get_rank_check_result(queued.id)
+```
+
+## Typed Inputs
+
+Plain dictionaries are supported for request bodies, and pydantic input models are
+available when you want validation and editor completion.
+
+```python
+from bisibility import CreateKeywordInput, CreateKeywordsBatch, KeywordScheduleInput
+
+created = bisibility.create_keywords(
+    "prj_123",
+    CreateKeywordsBatch(
+        keywords=[
+            CreateKeywordInput(
+                keyword="rank tracker",
+                target_url="https://example.com/rank-tracker",
+                tags=["api"],
+                schedule=KeywordScheduleInput(
+                    frequency="daily",
+                    cron_expression=None,
+                ),
+            )
+        ]
+    ),
+)
+```
+
+New app-surface endpoints also have typed request models. Plain dictionaries remain supported.
+
+```python
+from bisibility import (
+    AlertRuleInput,
+    ApiKeyCreateInput,
+    ConnectProviderInput,
+    ProjectDefaultsPatch,
+    ProviderCredentialsInput,
+    UpdateProjectInput,
+)
+
+project = bisibility.update_project("prj_123", UpdateProjectInput(name="Marketing site"))
+
+defaults = bisibility.update_project_defaults(
+    "prj_123",
+    ProjectDefaultsPatch(frequency="daily", location_key="US/Texas/Austin"),
+)
+
+api_key = bisibility.create_api_key(ApiKeyCreateInput(name="CI"))
+
+rule = bisibility.create_alert_rule(
+    "prj_123",
+    AlertRuleInput(
+        channels=["email"],
+        condition_type="threshold",
+        name="Ranking drop",
+        target_type="all",
+        threshold_position=10,
+    ),
+)
+
+provider = bisibility.connect_provider(
+    "prj_123",
+    "serpapi",
+    ConnectProviderInput(
+        credentials=ProviderCredentialsInput(api_key="serpapi-secret"),
+        primary=True,
+    ),
+)
+
+# Self-hosted analytics providers (e.g. "plausible") accept an optional
+# endpoint credential pointing at the instance API.
+analytics = bisibility.connect_provider(
+    "prj_123",
+    "plausible",
+    ConnectProviderInput(
+        credentials=ProviderCredentialsInput(
+            api_key="plausible-secret",
+            endpoint="https://plausible.example.com/api",
+        ),
+    ),
+)
+```
+
+## Errors
+
+Non-2xx API responses raise `BisibilityApiError`. The RFC problem details body is
+available on `error.problem` when the server returns one.
+
+```python
+from bisibility import BisibilityApiError
+
+try:
+    bisibility.get_keyword("kw_missing")
+except BisibilityApiError as error:
+    print(error.status, error.problem.detail if error.problem else error.body)
+```
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).