seekgist 1.0.0__tar.gz

seekgist-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

seekgist-1.0.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 — 2026-10-19
+
+First public release.

seekgist-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SeekGist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seekgist-1.0.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: seekgist
+Version: 1.0.0
+Summary: SeekGist API client for Python: Arabic-first e-commerce search, suggest, catalog sync and webhooks.
+Project-URL: Homepage, https://seekgist.com/docs/sdk/python
+Project-URL: Documentation, https://seekgist.com/docs
+Project-URL: Repository, https://github.com/seekgist/seekgist-python
+Project-URL: Issues, https://github.com/seekgist/seekgist-python/issues
+Project-URL: Changelog, https://github.com/seekgist/seekgist-python/blob/main/CHANGELOG.md
+Author-email: SeekGist <support@seekgist.com>
+Maintainer-email: SeekGist <support@seekgist.com>
+License: MIT
+License-File: LICENSE
+Keywords: arabic,autocomplete,ecommerce,sdk,search,seekgist
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# seekgist: SeekGist for Python
+
+The official Python client for the [SeekGist](https://seekgist.com) API: Arabic-first e-commerce
+search, suggest, catalog sync and webhooks. Python 3.12+, sync (`SeekGist`) and asyncio
+(`AsyncSeekGist`) clients on httpx, fully typed (`py.typed`, TypedDicts for every request and
+response).
+
+```bash
+pip install seekgist
+```
+
+Documentation: https://seekgist.com/docs. Support: support@seekgist.com.
+
+## Quick start
+
+```python
+from seekgist import SeekGist
+
+with SeekGist(api_key="sg_sec_...") as client:  # or set SEEKGIST_API_KEY
+    products = [{"id": "42", "name": {"en": "Desk lamp", "ar": "مصباح مكتب"}, "price": "12.500", "currency": "JOD"}]
+    summary = client.upsert_products(products)  # batches, retries, one Idempotency-Key per batch
+    print(summary.upserted, summary.errors)
+
+    res = client.find("مصباح", lang="ar", per_page=12)
+    print(res.data["ids"])  # product ids in rank order; res.data["hits"] has the product cards
+    print(res.usage, res.request_id)  # searches used this period; quote the request id to support
+```
+
+```python
+from seekgist import AsyncSeekGist
+
+async with AsyncSeekGist() as client:
+    res = await client.find("white sneakers", lang="en")
+```
+
+Keys: a **public** key (`sg_pub_...`) can search, suggest, recommend and send events.
+A **secret** key (`sg_sec_...`) can do everything an API key may; keep it on your server.
+Options: `base_url` (default `https://api.seekgist.com`, or `SEEKGIST_BASE_URL`), `timeout`
+(10 s per attempt), `max_retries` (2), `headers`, `http_client`.
+
+## All API methods
+
+One namespace per API area, one method per operation, keyword arguments only:
+`client.search`, `events`, `catalog`, `imports`, `connectors`, `jobs`, `synonyms`, `rules`,
+`experiments`, `translation`, `analytics`, `webhooks`, `account`, `billing`, `health`, `files`.
+
+Catalog translation works: `translation.backfill`, `status`, `review_*`, `glossary_*`, `export`,
+`approved` and `ack`. Not available on this platform: the chat methods. They answer
+`404 feature_unavailable`.
+
+```python
+client.synonyms.create(body={"kind": "equivalent", "terms": ["sneakers", "trainers", "سنيكرز"]})
+client.catalog.products_get(product_id="42")
+client.analytics.stats(report="top_queries", from_="2026-10-01")  # `from` is a keyword: from_
+client.search.search_get(q="sneakers", options={"query": {"filter[brand]": ["Nike", "Adidas"]}})
+r = client.request("search_post", body={"q": "dress"})  # any operation, with headers
+```
+
+Every method takes `options={"timeout", "max_retries", "idempotency_key", "headers", "query"}`.
+Dashboard sign-in, admin and store-app callback endpoints are not in the SDK on purpose.
+
+## Helpers
+
+| Helper | What it does |
+|---|---|
+| `client.find(q, **fields)` | POST /v1/search; returns `ApiResponse` with `.usage` |
+| `client.upsert_products(products, batch_size=500, delete_ids=..., replace_all=False, key_prefix=None, on_batch=None)` | Batches of up to 1,000 with one `Idempotency-Key` per batch (`<key_prefix>-<n>`) and 5 retries; the same `key_prefix` again = safe resume; `replace_all=True` = full sync. Returns `UpsertSummary` |
+| `client.wait_for_job(job_id)` | Polls `GET /v1/jobs/{id}` until done |
+| `client.pages(lambda c: client.synonyms.list(cursor=c))` | Every item of a cursor list |
+| `AsyncSeekGist.suggester(debounce=0.12, lang=..., products=...)` | `await s.input(text)`: debounced, drops out-of-date answers, caches; `None` for short or stale text. Suggest is never billed |
+| `verify_webhook(secret, headers, raw_body)` | Standard Webhooks signature + 5-minute time check; returns the event |
+| `parse_usage(header)` | Reads `X-SeekGist-Usage` |
+
+Debounce matters where people type: in a browser use the JS SDK (`@seekgist/sdk`) or the
+widget. In Python the suggester is for asyncio code such as a chat bot or a server-side proxy.
+
+## Errors, retries and idempotency
+
+- `ApiError` (`status`, `code`, `request_id`, `field_errors`, `retry_after_s`): use `code` in
+  your program. `TimeoutError`, `ConnectionError`: no answer. `WebhookVerificationError`: bad webhook.
+  All are `SeekGistError`.
+- Retries (default 2, backoff 0.5 s, 1 s, 2 s ... with jitter; `Retry-After` wins): GET calls,
+  search, and writes that take an `Idempotency-Key` (the SDK adds one and keeps it across
+  retries). Other writes (click, event) are never retried after a network error
+  or a 5xx; a 429 is retried for every call.
+- Store search pages: `SeekGist(timeout=0.3, max_retries=0)` and fall back to the store's own
+  search on any `SeekGistError`.
+
+## Examples
+
+`examples/search.py`, `examples/sync_catalog.py`, `examples/webhook_receiver.py` (standard
+library server), `examples/async_suggest.py`.
+
+## Development
+
+From a clone of https://github.com/seekgist/seekgist-python:
+
+```bash
+pip install -e . pytest pytest-asyncio
+pytest
+```
+
+Bugs and questions: https://github.com/seekgist/seekgist-python/issues or support@seekgist.com.
+
+## License
+
+MIT. See `LICENSE`.

seekgist-1.0.0/README.md

@@ -0,0 +1,107 @@
+# seekgist: SeekGist for Python
+
+The official Python client for the [SeekGist](https://seekgist.com) API: Arabic-first e-commerce
+search, suggest, catalog sync and webhooks. Python 3.12+, sync (`SeekGist`) and asyncio
+(`AsyncSeekGist`) clients on httpx, fully typed (`py.typed`, TypedDicts for every request and
+response).
+
+```bash
+pip install seekgist
+```
+
+Documentation: https://seekgist.com/docs. Support: support@seekgist.com.
+
+## Quick start
+
+```python
+from seekgist import SeekGist
+
+with SeekGist(api_key="sg_sec_...") as client:  # or set SEEKGIST_API_KEY
+    products = [{"id": "42", "name": {"en": "Desk lamp", "ar": "مصباح مكتب"}, "price": "12.500", "currency": "JOD"}]
+    summary = client.upsert_products(products)  # batches, retries, one Idempotency-Key per batch
+    print(summary.upserted, summary.errors)
+
+    res = client.find("مصباح", lang="ar", per_page=12)
+    print(res.data["ids"])  # product ids in rank order; res.data["hits"] has the product cards
+    print(res.usage, res.request_id)  # searches used this period; quote the request id to support
+```
+
+```python
+from seekgist import AsyncSeekGist
+
+async with AsyncSeekGist() as client:
+    res = await client.find("white sneakers", lang="en")
+```
+
+Keys: a **public** key (`sg_pub_...`) can search, suggest, recommend and send events.
+A **secret** key (`sg_sec_...`) can do everything an API key may; keep it on your server.
+Options: `base_url` (default `https://api.seekgist.com`, or `SEEKGIST_BASE_URL`), `timeout`
+(10 s per attempt), `max_retries` (2), `headers`, `http_client`.
+
+## All API methods
+
+One namespace per API area, one method per operation, keyword arguments only:
+`client.search`, `events`, `catalog`, `imports`, `connectors`, `jobs`, `synonyms`, `rules`,
+`experiments`, `translation`, `analytics`, `webhooks`, `account`, `billing`, `health`, `files`.
+
+Catalog translation works: `translation.backfill`, `status`, `review_*`, `glossary_*`, `export`,
+`approved` and `ack`. Not available on this platform: the chat methods. They answer
+`404 feature_unavailable`.
+
+```python
+client.synonyms.create(body={"kind": "equivalent", "terms": ["sneakers", "trainers", "سنيكرز"]})
+client.catalog.products_get(product_id="42")
+client.analytics.stats(report="top_queries", from_="2026-10-01")  # `from` is a keyword: from_
+client.search.search_get(q="sneakers", options={"query": {"filter[brand]": ["Nike", "Adidas"]}})
+r = client.request("search_post", body={"q": "dress"})  # any operation, with headers
+```
+
+Every method takes `options={"timeout", "max_retries", "idempotency_key", "headers", "query"}`.
+Dashboard sign-in, admin and store-app callback endpoints are not in the SDK on purpose.
+
+## Helpers
+
+| Helper | What it does |
+|---|---|
+| `client.find(q, **fields)` | POST /v1/search; returns `ApiResponse` with `.usage` |
+| `client.upsert_products(products, batch_size=500, delete_ids=..., replace_all=False, key_prefix=None, on_batch=None)` | Batches of up to 1,000 with one `Idempotency-Key` per batch (`<key_prefix>-<n>`) and 5 retries; the same `key_prefix` again = safe resume; `replace_all=True` = full sync. Returns `UpsertSummary` |
+| `client.wait_for_job(job_id)` | Polls `GET /v1/jobs/{id}` until done |
+| `client.pages(lambda c: client.synonyms.list(cursor=c))` | Every item of a cursor list |
+| `AsyncSeekGist.suggester(debounce=0.12, lang=..., products=...)` | `await s.input(text)`: debounced, drops out-of-date answers, caches; `None` for short or stale text. Suggest is never billed |
+| `verify_webhook(secret, headers, raw_body)` | Standard Webhooks signature + 5-minute time check; returns the event |
+| `parse_usage(header)` | Reads `X-SeekGist-Usage` |
+
+Debounce matters where people type: in a browser use the JS SDK (`@seekgist/sdk`) or the
+widget. In Python the suggester is for asyncio code such as a chat bot or a server-side proxy.
+
+## Errors, retries and idempotency
+
+- `ApiError` (`status`, `code`, `request_id`, `field_errors`, `retry_after_s`): use `code` in
+  your program. `TimeoutError`, `ConnectionError`: no answer. `WebhookVerificationError`: bad webhook.
+  All are `SeekGistError`.
+- Retries (default 2, backoff 0.5 s, 1 s, 2 s ... with jitter; `Retry-After` wins): GET calls,
+  search, and writes that take an `Idempotency-Key` (the SDK adds one and keeps it across
+  retries). Other writes (click, event) are never retried after a network error
+  or a 5xx; a 429 is retried for every call.
+- Store search pages: `SeekGist(timeout=0.3, max_retries=0)` and fall back to the store's own
+  search on any `SeekGistError`.
+
+## Examples
+
+`examples/search.py`, `examples/sync_catalog.py`, `examples/webhook_receiver.py` (standard
+library server), `examples/async_suggest.py`.
+
+## Development
+
+From a clone of https://github.com/seekgist/seekgist-python:
+
+```bash
+pip install -e . pytest pytest-asyncio
+pytest
+```
+
+Bugs and questions: https://github.com/seekgist/seekgist-python/issues or support@seekgist.com.
+
+## License
+
+MIT. See `LICENSE`.

seekgist-1.0.0/examples/async_suggest.py

@@ -0,0 +1,24 @@
+"""Debounced suggestions in asyncio code (a chat bot, a terminal UI, a server-side proxy).
+
+SEEKGIST_API_KEY=sg_pub_... python examples/async_suggest.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from seekgist import AsyncSeekGist
+
+
+async def main() -> None:
+    async with AsyncSeekGist() as client:
+        suggester = client.suggester(debounce=0.12, lang="auto", products=3)
+        typed = ["d", "dr", "dre", "dres", "dress"]
+        tasks = [asyncio.ensure_future(suggester.input(text)) for text in typed]  # fast typing
+        results = await asyncio.gather(*tasks)
+        for text, res in zip(typed, results, strict=True):
+            print(f"{text!r}: {'(skipped)' if res is None else [s['text'] for s in res['suggestions']]}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

seekgist-1.0.0/examples/search.py

@@ -0,0 +1,33 @@
+"""Search from Python with a PUBLIC or SECRET key.
+
+SEEKGIST_API_KEY=sg_pub_... SEEKGIST_BASE_URL=http://localhost:58000 python examples/search.py "فستان"
+"""
+
+from __future__ import annotations
+
+import sys
+
+from seekgist import ApiError, SeekGist
+
+
+def main() -> int:
+    query = sys.argv[1] if len(sys.argv) > 1 else "dress"
+    with SeekGist() as client:  # reads SEEKGIST_API_KEY and SEEKGIST_BASE_URL
+        try:
+            res = client.find(query, per_page=5)
+        except ApiError as e:
+            print(f"API error {e.status} {e.code} (request {e.request_id})", file=sys.stderr)
+            return 1
+        print(f"{res.data['total']} results for {query!r} ({res.data['took_ms']} ms)")
+        for hit in res.data["hits"]:
+            p = hit["product"]
+            print(f"- {p['name'].get('ar') or p['name'].get('en')} | {p['price']} {p['currency']}")
+        if res.usage:
+            print(f"usage: {res.usage.searches} searches in {res.usage.period} (limit {res.usage.limit})")
+        sug = client.search.suggest(q=query[:3])
+        print("suggestions:", ", ".join(s["text"] for s in sug["suggestions"]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

seekgist-1.0.0/examples/sync_catalog.py

@@ -0,0 +1,31 @@
+"""Push products with a SECRET key: batches of 500, one Idempotency-Key per batch, retries.
+Run it again with the same KEY_PREFIX to resume a stopped run safely.
+
+    SEEKGIST_API_KEY=sg_sec_... KEY_PREFIX=nightly-2026-10-13 python examples/sync_catalog.py
+"""
+
+from __future__ import annotations
+
+import os
+
+from seekgist import SeekGist
+
+products = [
+    {
+        "id": f"demo-{i}",
+        "name": {"en": f"Demo product {i}", "ar": f"منتج تجريبي {i}"},
+        "price": f"{5 + i % 50:.3f}",
+        "currency": "USD",
+        "in_stock": i % 7 != 0,
+    }
+    for i in range(1200)
+]
+
+with SeekGist() as client:
+    summary = client.upsert_products(
+        products,
+        batch_size=500,
+        key_prefix=os.environ.get("KEY_PREFIX"),
+        on_batch=lambda b: print(f"batch {b.index + 1}: {b.count} items{' (already done)' if b.replayed else ''}"),
+    )
+    print(summary)

seekgist-1.0.0/examples/webhook_receiver.py

@@ -0,0 +1,35 @@
+"""Receive SeekGist webhooks with the standard library and check the signature.
+
+SEEKGIST_WEBHOOK_SECRET=whsec_... python examples/webhook_receiver.py   (listens on :3001)
+"""
+
+from __future__ import annotations
+
+import os
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from seekgist import WebhookVerificationError, verify_webhook
+
+SECRET = os.environ.get("SEEKGIST_WEBHOOK_SECRET", "")
+seen: set[str] = set()  # drop repeated deliveries (use your database in production)
+
+
+class Handler(BaseHTTPRequestHandler):
+    def do_POST(self) -> None:
+        body = self.rfile.read(int(self.headers.get("Content-Length", "0")))  # the RAW body
+        try:
+            event = verify_webhook(SECRET, dict(self.headers), body)
+        except WebhookVerificationError as e:
+            self.send_response(400)
+            self.end_headers()
+            self.wfile.write(str(e).encode())
+            return
+        if event["id"] not in seen:
+            seen.add(event["id"])
+            print(event["type"], event["data"])
+        self.send_response(204)
+        self.end_headers()
+
+
+if __name__ == "__main__":
+    HTTPServer(("127.0.0.1", 3001), Handler).serve_forever()

seekgist-1.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seekgist"
+version = "1.0.0"
+description = "SeekGist API client for Python: Arabic-first e-commerce search, suggest, catalog sync and webhooks."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "SeekGist", email = "support@seekgist.com" }]
+maintainers = [{ name = "SeekGist", email = "support@seekgist.com" }]
+keywords = ["seekgist", "search", "arabic", "ecommerce", "autocomplete", "sdk"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27,<1",
+]
+
+[project.urls]
+Homepage = "https://seekgist.com/docs/sdk/python"
+Documentation = "https://seekgist.com/docs"
+Repository = "https://github.com/seekgist/seekgist-python"
+Issues = "https://github.com/seekgist/seekgist-python/issues"
+Changelog = "https://github.com/seekgist/seekgist-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/seekgist"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/seekgist", "README.md", "LICENSE", "CHANGELOG.md", "examples"]
+
+# Ruff: the same rules as the SeekGist API code, plus room for generated code (long docstrings
+# and operation lines). Kept here in full so the package also lints on its own.
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "S", "ASYNC", "RUF", "SIM", "PL"]
+ignore = ["PLR0913", "PLR2004", "PLR0911", "PLR0912", "PLR0915", "PLR0917", "S101", "RUF001", "RUF002", "RUF003", "B008", "PLC0415"]
+
+[tool.ruff.lint.isort]
+# seekgist_api: the API app, used only by the live tests that run next to the API code.
+known-first-party = ["seekgist", "seekgist_api"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S", "PLR", "B017", "E501", "ASYNC"]
+"src/seekgist/_generated/**" = ["E501", "I001", "RUF022"]
+
+[tool.ruff.format]
+exclude = ["src/seekgist/_generated/**"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

seekgist-1.0.0/src/seekgist/__init__.py

@@ -0,0 +1,48 @@
+"""SeekGist Python SDK: Arabic-first e-commerce search (search, suggest, catalog sync, webhooks).
+
+from seekgist import SeekGist
+client = SeekGist(api_key="sg_sec_...")          # or set SEEKGIST_API_KEY
+res = client.find("فستان سهرة تحت 100")
+print(res.data["ids"], res.usage)
+"""
+
+from ._async_client import AsyncSeekGist
+from ._client import DEFAULT_BASE_URL, SeekGist, __version__
+from ._generated.api import GENERATOR_VERSION, OPS, SPEC_SHA256
+from ._spec import ApiResponse, FileInput, OperationSpec, RateLimit, RequestOptions, Usage
+from ._transport import new_idempotency_key, parse_usage
+from ._upsert import MAX_BATCH, BatchInfo, UpsertSummary
+from .errors import ApiError, ConnectionError, SeekGistError, TimeoutError, WebhookVerificationError
+from .suggest import AsyncSuggester
+from .webhooks import TOLERANCE_S, WebhookEvent, sign_webhook, verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "GENERATOR_VERSION",
+    "MAX_BATCH",
+    "OPS",
+    "SPEC_SHA256",
+    "TOLERANCE_S",
+    "ApiError",
+    "ApiResponse",
+    "AsyncSeekGist",
+    "AsyncSuggester",
+    "BatchInfo",
+    "ConnectionError",
+    "FileInput",
+    "OperationSpec",
+    "RateLimit",
+    "RequestOptions",
+    "SeekGist",
+    "SeekGistError",
+    "TimeoutError",
+    "UpsertSummary",
+    "Usage",
+    "WebhookEvent",
+    "WebhookVerificationError",
+    "__version__",
+    "new_idempotency_key",
+    "parse_usage",
+    "sign_webhook",
+    "verify_webhook",
+]