synapseone-sdk 0.7.0__py3-none-any.whl

synapsedx_sdk/__init__.py

@@ -0,0 +1,11 @@
+# Copyright 2026 SynapseOne Contributors
+# Licensed under the Apache License, Version 2.0 (the "License");
+"""Compatibility shim for the SynapseDX -> SynapseOne rebrand.
+
+``synapsedx_sdk`` is deprecated; import ``synapseone_sdk`` instead. Everything
+here is re-exported from the canonical package, including the legacy
+``SynapseDXClient`` / ``SynapseDXError`` aliases.
+"""
+
+from synapseone_sdk import *  # noqa: F401,F403
+from synapseone_sdk import __all__ as __all__  # noqa: F401

synapseone_sdk/__init__.py

@@ -0,0 +1,291 @@
+# Copyright 2026 SynapseOne Contributors
+# Licensed under the Apache License, Version 2.0 (the "License");
+"""synapseone Python SDK — gateway client for the SynapseOne platform.
+
+The SDK is split per service; use the namespace that matches the service you
+talk to:
+
+======================  =============================================
+``client.iam``          auth, orgs/accounts/users, roles, policies,
+                        API keys, credentials, service accounts
+``client.workflow``     workflow templates, CRUD/lifecycle, executions,
+                        test runs
+``client.lds``          LDS datasources, attributes, records, NGSI-LD
+                        entities, licenses
+``client.base``         SynapseBase collections/documents, queries,
+                        batches, counters, change feed, object mapping
+``client.faststore``    Synapse Faststore cache/KV, hashes, lists, sets,
+                        sorted sets, locks
+``client.queue``        SynapseQueue publish/consume/ack, dead letters
+======================  =============================================
+
+The old flat methods on :class:`SynapseOneClient` still work but are deprecated:
+each one emits a ``DeprecationWarning`` and forwards to the namespaced call
+(e.g. ``client.list_templates()`` -> ``client.workflow.list_templates()``).
+
+Example::
+
+    from synapseone_sdk import SynapseOneClient
+
+    client = SynapseOneClient("http://localhost:8080", token=jwt)
+    parks = client.base.collection("parks", model=Park, mapping={"name": "profile.name"})
+    parks.create(Park(name="Central"))
+    result = client.queue.publish("emails", {"to": "a@b.c"})
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+from ._http import UNSET, HttpClient, SynapseOneError
+from .ai import AiService
+from .base import (
+    BaseCollection,
+    BaseService,
+    QueryResult,
+    VectorSearchResult,
+    data_to_object,
+    normalize_mapping,
+    object_to_data,
+)
+from .faststore import FaststoreService
+from .iam import IamService
+from .inference import InferenceService
+from .lds import LdsService
+from .queue import QueueService
+from .stream import StreamService
+from .workflow import WorkflowService, trigger_webhook, unwrap_executions
+
+__all__ = [
+    "UNSET",
+    "AiService",
+    "BaseCollection",
+    "BaseService",
+    "FaststoreService",
+    "IamService",
+    "InferenceService",
+    "LdsService",
+    "QueryResult",
+    "VectorSearchResult",
+    "QueueService",
+    "StreamService",
+    "SynapseDXClient",
+    "SynapseDXError",
+    "SynapseOneClient",
+    "SynapseOneError",
+    "WorkflowService",
+    "data_to_object",
+    "normalize_mapping",
+    "object_to_data",
+    "trigger_webhook",
+    "unwrap_executions",
+]
+
+
+class SynapseOneClient:
+    """One client, one HTTP layer, seven service namespaces.
+
+    ``base_url`` points at the gateway (``http://localhost:8080``) or a single
+    service origin. ``tenant`` is sent as ``x-synapseone-tenant`` and is only
+    required by platform callers of faststore/queue.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        api_key: str | None = None,
+        timeout: int = 15,
+        tenant: str | None = None,
+    ) -> None:
+        self._http = HttpClient(
+            base_url, token=token, api_key=api_key, tenant=tenant, timeout=timeout
+        )
+        self.iam = IamService(self._http)
+        self.workflow = WorkflowService(self._http)
+        self.ai = AiService(self._http)
+        self.lds = LdsService(self._http)
+        self.base = BaseService(self._http)
+        self.faststore = FaststoreService(self._http)
+        self.queue = QueueService(self._http)
+        self.stream = StreamService(self._http)
+        self.inference = InferenceService(self._http)
+
+    # ---- transport knobs (also mirrored by JS setToken/setApiKey and Go) ----
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url
+
+    @base_url.setter
+    def base_url(self, value: str) -> None:
+        self._http.base_url = value.rstrip("/")
+
+    @property
+    def token(self) -> str | None:
+        return self._http.token
+
+    @token.setter
+    def token(self, value: str | None) -> None:
+        self._http.token = value
+
+    @property
+    def api_key(self) -> str | None:
+        return self._http.api_key
+
+    @api_key.setter
+    def api_key(self, value: str | None) -> None:
+        self._http.api_key = value
+
+    @property
+    def tenant(self) -> str | None:
+        return self._http.tenant
+
+    @tenant.setter
+    def tenant(self, value: str | None) -> None:
+        self._http.tenant = value
+
+    @property
+    def timeout(self) -> int:
+        return self._http.timeout
+
+    @timeout.setter
+    def timeout(self, value: int) -> None:
+        self._http.timeout = value
+
+    def set_token(self, token: str) -> None:
+        """Set/replace the Bearer JWT (mirrors JS setToken / Go SetToken)."""
+        self.token = token
+
+    def set_api_key(self, api_key: str) -> None:
+        """Set/replace the X-API-Key (mirrors JS setApiKey / Go SetAPIKey)."""
+        self.api_key = api_key
+
+    def call(self, method: str, path: str, body: Any | None = None) -> Any:
+        """Generic escape hatch (forward-compat with endpoints added after this SDK).
+
+        method is e.g. 'GET'/'POST'/'PUT'/'DELETE'; path must start with '/'.
+        """
+        verb = (method or "GET").upper()
+        if not path.startswith("/"):
+            path = "/" + path
+        if verb in ("GET", "HEAD"):
+            return self._http.request(verb, path)
+        return self._http.request(verb, path, body)
+
+
+# ---------------------------------------------------------------------------
+# deprecated flat wrappers (legacy merged API)
+# ---------------------------------------------------------------------------
+
+_IAM_METHODS = (
+    "login",
+    "refresh",
+    "logout",
+    "logout_all",
+    "verify",
+    "me",
+    "oidc_config",
+    "oidc_start",
+    "oidc_callback",
+    "list_orgs",
+    "create_org",
+    "create_account",
+    "list_accounts",
+    "create_user",
+    "list_users",
+    "user_policies",
+    "authorize",
+    "attach_policy",
+    "detach_policy",
+    "role_policies",
+    "assign_role",
+    "unassign_role",
+    "user_roles",
+    "simulate",
+    "list_audit",
+    "create_api_key",
+    "revoke_api_key",
+    "list_api_keys",
+    "verify_api_key",
+    "create_service_account",
+    "list_service_accounts",
+    "list_roles",
+    "create_role",
+    "delete_role",
+    "list_policies",
+    "create_policy",
+    "delete_policy",
+    "service_account_token",
+)
+
+_WORKFLOW_METHODS = (
+    "list_templates",
+    "get_template",
+    "get_workflow",
+    "activate_workflow",
+    "deactivate_workflow",
+    "execute_workflow",
+    "list_workflows",
+    "create_workflow_from_template",
+    "create_workflow",
+    "update_workflow",
+    "delete_workflow",
+    "list_executions",
+    "get_execution",
+    "test_run",
+    "create_credential",
+    "list_credentials",
+    "get_credential",
+    "delete_credential",
+    "rotate_credential",
+)
+
+_LDS_METHODS = {
+    "list_lds_licenses": "list_licenses",
+    "list_lds_datasources": "list_datasources",
+    "create_lds_datasource": "create_datasource",
+    "get_lds_datasource": "get_datasource",
+    "update_lds_datasource": "update_datasource",
+    "delete_lds_datasource": "delete_datasource",
+    "get_lds_datasource_attributes": "get_datasource_attributes",
+    "set_lds_datasource_attributes": "set_datasource_attributes",
+    "ingest_lds_records": "ingest_records",
+    "list_lds_entities": "list_entities",
+    "get_lds_entity": "get_entity",
+    "get_lds_datasource_stats": "get_datasource_stats",
+}
+
+
+def _deprecated(service: str, legacy: str, target: str):
+    replacement = f"client.{service}.{target}()"
+
+    def wrapper(self: SynapseOneClient, *args: Any, **kwargs: Any) -> Any:
+        warnings.warn(
+            f"SynapseOneClient.{legacy}() is deprecated; use {replacement} instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(getattr(self, service), target)(*args, **kwargs)
+
+    wrapper.__name__ = legacy
+    wrapper.__qualname__ = f"SynapseOneClient.{legacy}"
+    wrapper.__doc__ = f"Deprecated alias for ``{replacement}``."
+    return wrapper
+
+
+for _name in _IAM_METHODS:
+    setattr(SynapseOneClient, _name, _deprecated("iam", _name, _name))
+for _name in _WORKFLOW_METHODS:
+    setattr(SynapseOneClient, _name, _deprecated("workflow", _name, _name))
+for _legacy, _target in _LDS_METHODS.items():
+    setattr(SynapseOneClient, _legacy, _deprecated("lds", _legacy, _target))
+setattr(SynapseOneClient, "ai_agent", _deprecated("ai", "ai_agent", "agent"))
+
+
+# ---------------------------------------------------------------------------
+# SynapseDX aliases (rebrand window: same classes, old import names keep working)
+# ---------------------------------------------------------------------------
+
+SynapseDXClient = SynapseOneClient
+SynapseDXError = SynapseOneError

synapseone_sdk/_http.py

@@ -0,0 +1,105 @@
+# Copyright 2026 SynapseOne Contributors
+# Licensed under the Apache License, Version 2.0 (the "License");
+"""Shared HTTP plumbing for the synapseone SDK.
+
+Every service module (iam, workflow, lds, base, faststore, queue) talks to the
+platform through one :class:`HttpClient`, which adds auth headers, the optional
+platform tenant header and maps every failure (network or HTTP) to
+:class:`SynapseOneError`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+# Sentinel for "argument was not provided", distinct from None (an explicit
+# null must be distinguishable from "leave untouched" in partial updates).
+UNSET = object()
+
+
+class SynapseOneError(Exception):
+    """All SDK errors surface as SynapseOneError (network or HTTP).
+
+    ``status`` carries the HTTP status code when the failure came from a JSON
+    response (None for network errors) and ``body`` carries the parsed error
+    body when one was returned, so callers can branch on codes such as
+    ``not_found`` or ``version_conflict``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        body: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class HttpClient:
+    """Thin request layer shared by all SynapseOne services.
+
+    ``base_url`` points at the gateway (``http://localhost:8080``) or directly
+    at a service origin. ``tenant`` is only needed by platform callers of the
+    tenant-scoped services (faststore/queue) and is sent as
+    ``x-synapseone-tenant``.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        api_key: str | None = None,
+        tenant: str | None = None,
+        timeout: int = 15,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.api_key = api_key
+        self.tenant = tenant
+        self.timeout = timeout
+
+    def headers(self) -> dict[str, str]:
+        h = {"Content-Type": "application/json"}
+        if self.token:
+            h["Authorization"] = f"Bearer {self.token}"
+        if self.api_key:
+            h["X-API-Key"] = self.api_key
+        if self.tenant:
+            h["x-synapseone-tenant"] = self.tenant
+        return h
+
+    def request(self, method: str, path: str, body: Any | None = None) -> Any:
+        try:
+            r = requests.request(
+                (method or "GET").upper(),
+                self.base_url + path,
+                json=body,
+                headers=self.headers(),
+                timeout=self.timeout,
+            )
+        except Exception as e:  # network, DNS, timeout...
+            raise SynapseOneError(f"synapseone network {path}: {e}") from e
+        if r.status_code >= 400:
+            raise SynapseOneError(
+                f"synapseone {r.status_code} {path}: {r.text[:500]}",
+                status=r.status_code,
+                body=_try_json(r),
+            )
+        if not r.text:
+            return None
+        try:
+            return r.json()
+        except ValueError:
+            return r.text  # non-JSON body (parity with JS SDK text fallback)
+
+
+def _try_json(r: Any) -> Any:
+    try:
+        return r.json()
+    except ValueError:
+        return None

synapseone_sdk/ai.py

@@ -0,0 +1,44 @@
+# Copyright 2026 SynapseOne Contributors
+# Licensed under the Apache License, Version 2.0 (the "License");
+"""Synapse AI client: the guidance-only API assistant (``POST /v1/ai/agent``).
+
+The agent maps a natural-language question to one catalogued SynapseOne
+endpoint and returns the method/path plus a ready-to-try body. It never
+executes the call itself — callers decide whether to run it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._http import HttpClient
+
+
+class AiService:
+    """Methods for the SynapseOne AI Assistant service (``/v1/ai``)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def agent(
+        self, question: str, history: list[dict[str, Any]] | None = None
+    ) -> dict[str, Any]:
+        """Ask the API assistant a question (1..2000 chars).
+
+        Parameters
+        ----------
+        question:
+            Natural language question about SynapseOne APIs.
+        history:
+            Optional list of prior turns (``[{"role": "user"|"ai", "text": "..."}]``).
+
+        Returns
+        -------
+        dict
+            Result containing ``ok``, ``method``, ``path``, ``auth``, ``pathValues``,
+            ``body``, ``explanation``, ``reason``, and optional ``guidance``.
+        """
+        body: dict[str, Any] = {"question": question}
+        if history:
+            body["history"] = history
+        return self._http.request("POST", "/v1/ai/agent", body)