zakadi 0.0.1__tar.gz

zakadi-0.0.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/
+.DS_Store

zakadi-0.0.1/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+- Initial release: shared protocol constants of the Zakadi protocol (zakadi.v1) with type annotations. No client yet.

zakadi-0.0.1/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 Moses Gameli. All rights reserved.
+
+This is a pre-release package. The licence under which the Zakadi SDKs and this
+package are distributed has not been finalised; until it is, no rights are
+granted beyond downloading and evaluating the package. See https://zakadi.dev.

zakadi-0.0.1/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: zakadi
+Version: 0.0.1
+Summary: Zakadi face-liveness API client for Python (pre-release): shared protocol constants now, the server-side client for sessions, results and webhook verification next.
+Project-URL: Homepage, https://zakadi.dev
+Project-URL: Documentation, https://docs.zakadi.dev
+Project-URL: Repository, https://github.com/zakadihq/zakadi-python
+Project-URL: Issues, https://github.com/zakadihq/zakadi-python/issues
+Author: Moses Gameli
+License: Copyright (c) 2026 Moses Gameli. All rights reserved.
+        
+        This is a pre-release package. The licence under which the Zakadi SDKs and this
+        package are distributed has not been finalised; until it is, no rights are
+        granted beyond downloading and evaluating the package. See https://zakadi.dev.
+License-File: LICENSE
+Keywords: biometrics,identity-verification,kyc,liveness,zakadi
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# zakadi
+
+Zakadi face-liveness API client for Python. Zakadi is an active face liveness check delivered as a short automated video call; relying parties create sessions and read verdicts server to server.
+
+Pre-release. This version ships the shared protocol constants (session states and statuses, decisions and bands, SDK error codes, terminal states, close codes, challenge kinds, webhook event types) with type annotations. The client for sessions, results, evidence and webhook signature verification follows in a later release; its surface is:
+
+```python
+from zakadi import Zakadi
+client = Zakadi(api_key="zk_live_...", base_url="https://api.zakadi.dev")
+s = client.sessions.create(user_ref="cust-88213", locale="en-NG", channel="android")
+r = client.sessions.result(s.session_id)
+```
+
+Links: https://zakadi.dev (documentation), https://github.com/zakadihq/zakadi-python (source).

zakadi-0.0.1/README.md

@@ -0,0 +1,14 @@
+# zakadi
+
+Zakadi face-liveness API client for Python. Zakadi is an active face liveness check delivered as a short automated video call; relying parties create sessions and read verdicts server to server.
+
+Pre-release. This version ships the shared protocol constants (session states and statuses, decisions and bands, SDK error codes, terminal states, close codes, challenge kinds, webhook event types) with type annotations. The client for sessions, results, evidence and webhook signature verification follows in a later release; its surface is:
+
+```python
+from zakadi import Zakadi
+client = Zakadi(api_key="zk_live_...", base_url="https://api.zakadi.dev")
+s = client.sessions.create(user_ref="cust-88213", locale="en-NG", channel="android")
+r = client.sessions.result(s.session_id)
+```
+
+Links: https://zakadi.dev (documentation), https://github.com/zakadihq/zakadi-python (source).

zakadi-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zakadi"
+version = "0.0.1"
+description = "Zakadi face-liveness API client for Python (pre-release): shared protocol constants now, the server-side client for sessions, results and webhook verification next."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Moses Gameli" }]
+keywords = ["zakadi", "liveness", "biometrics", "identity-verification", "kyc"]
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://zakadi.dev"
+Documentation = "https://docs.zakadi.dev"
+Repository = "https://github.com/zakadihq/zakadi-python"
+Issues = "https://github.com/zakadihq/zakadi-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zakadi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/zakadi", "tests", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]

zakadi-0.0.1/src/zakadi/__init__.py

@@ -0,0 +1,41 @@
+"""Zakadi face-liveness API client for Python.
+
+Pre-release. This version ships the shared protocol constants of the Zakadi
+protocol (``zakadi.v1``); the server-side client (sessions, results, webhook
+verification) follows in a later release. See https://zakadi.dev.
+"""
+
+from zakadi.protocol import (
+    SUBPROTOCOL,
+    Band,
+    ChallengeKind,
+    CloseCode,
+    Decision,
+    EndOutcome,
+    EndReason,
+    ErrorCode,
+    SessionState,
+    SessionStatus,
+    TerminalState,
+    WEBHOOK_EVENTS,
+    terminal_state_for_end,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "__version__",
+    "SUBPROTOCOL",
+    "Band",
+    "ChallengeKind",
+    "CloseCode",
+    "Decision",
+    "EndOutcome",
+    "EndReason",
+    "ErrorCode",
+    "SessionState",
+    "SessionStatus",
+    "TerminalState",
+    "WEBHOOK_EVENTS",
+    "terminal_state_for_end",
+]

zakadi-0.0.1/src/zakadi/protocol.py

@@ -0,0 +1,195 @@
+"""Constants shared by every Zakadi client and server (protocol ``zakadi.v1``)."""
+
+from __future__ import annotations
+
+from enum import Enum, IntEnum
+
+#: The WebSocket subprotocol every Zakadi client requests.
+SUBPROTOCOL = "zakadi.v1"
+
+
+class SessionState(str, Enum):
+    """Client-side session states, in lifecycle order."""
+
+    IDLE = "idle"
+    CONSENT = "consent"
+    PERMISSION = "permission"
+    CONNECTING = "connecting"
+    ACTIVE = "active"
+    ENDED = "ended"
+    ERROR = "error"
+
+
+class SessionStatus(str, Enum):
+    """Server-side session status as returned by the Zakadi API."""
+
+    CREATED = "created"
+    CONNECTED = "connected"
+    IN_PROGRESS = "in_progress"
+    VERIFYING = "verifying"
+    PASSED = "passed"
+    FAILED = "failed"
+    INCONCLUSIVE = "inconclusive"
+    EXPIRED = "expired"
+    ABORTED = "aborted"
+
+
+class Decision(str, Enum):
+    """Verdict decision in a result."""
+
+    PASS = "pass"
+    FAIL = "fail"
+    INCONCLUSIVE = "inconclusive"
+
+
+class Band(str, Enum):
+    """Assurance band of a session."""
+
+    A = "A"
+    B = "B"
+    C = "C"
+
+
+class ErrorCode(str, Enum):
+    """SDK error codes. Runtime conditions only; API misuse raises a usage error."""
+
+    CONSENT_DECLINED = "consent_declined"
+    CANCELLED = "cancelled"
+    PERMISSION_DENIED = "permission_denied"
+    UNSUPPORTED_DEVICE = "unsupported_device"
+    SDK_DISABLED = "sdk_disabled"
+    PACK_UNAVAILABLE = "pack_unavailable"
+    NETWORK_UNAVAILABLE = "network_unavailable"
+    AUTH_ERROR = "auth_error"
+    SESSION_EXPIRED = "session_expired"
+    SESSION_USED = "session_used"
+    MAX_DURATION = "max_duration"
+    ADMISSION_REJECTED = "admission_rejected"
+    NETWORK_FLOOR = "network_floor"
+    PROTOCOL_ERROR = "protocol_error"
+    INTERRUPTED = "interrupted"
+    CAPTURE_ERROR = "capture_error"
+    ENCODER_ERROR = "encoder_error"
+    INTERNAL = "internal"
+
+
+class TerminalState(str, Enum):
+    """Terminal UI states of a session on the client."""
+
+    COMPLETED = "completed"
+    INCOMPLETE = "incomplete"
+    DISCONNECTED = "disconnected"
+    NETWORK_FLOOR = "network_floor"
+    CANCELLED = "cancelled"
+    ERROR = "error"
+    UNSUPPORTED_DEVICE = "unsupported_device"
+    PERMISSION_DENIED = "permission_denied"
+    INTERRUPTED = "interrupted"
+    SDK_DISABLED = "sdk_disabled"
+
+    @property
+    def cue(self) -> str:
+        """The prompt-pack cue the SDK may play locally for this state."""
+        return _TERMINAL_CUES[self]
+
+    @property
+    def offers_redial(self) -> bool:
+        """Whether the SDK offers a redial action in this state."""
+        return self in _REDIAL_STATES
+
+
+_TERMINAL_CUES: dict[TerminalState, str] = {
+    TerminalState.COMPLETED: "done.thanks",
+    TerminalState.INCOMPLETE: "fail.one_more_step",
+    TerminalState.DISCONNECTED: "net.dropped",
+    TerminalState.NETWORK_FLOOR: "net.slow",
+    TerminalState.CANCELLED: "end.cancelled",
+    TerminalState.ERROR: "end.error",
+    TerminalState.UNSUPPORTED_DEVICE: "end.unsupported",
+    TerminalState.PERMISSION_DENIED: "end.permission",
+    TerminalState.INTERRUPTED: "end.interrupted",
+    TerminalState.SDK_DISABLED: "end.disabled",
+}
+
+_REDIAL_STATES = frozenset(
+    {
+        TerminalState.INCOMPLETE,
+        TerminalState.DISCONNECTED,
+        TerminalState.NETWORK_FLOOR,
+        TerminalState.ERROR,
+        TerminalState.INTERRUPTED,
+    }
+)
+
+
+class EndOutcome(str, Enum):
+    """Outcome carried by the server's ``end`` message."""
+
+    COMPLETED = "completed"
+    ABORTED = "aborted"
+
+
+class EndReason(str, Enum):
+    """Reason carried by the server's ``end`` message."""
+
+    OK = "ok"
+    FLOOR_BREACHED = "floor_breached"
+    MAX_DURATION = "max_duration"
+    USER_CANCEL = "user_cancel"
+    ATTEMPTS_EXHAUSTED = "attempts_exhausted"
+    SERVER_ERROR = "server_error"
+    ADMISSION = "admission"
+
+
+def terminal_state_for_end(reason: EndReason) -> TerminalState:
+    """Map an ``end`` reason to the terminal UI state the SDK shows."""
+    return _END_TO_TERMINAL[reason]
+
+
+_END_TO_TERMINAL: dict[EndReason, TerminalState] = {
+    EndReason.OK: TerminalState.COMPLETED,
+    EndReason.ATTEMPTS_EXHAUSTED: TerminalState.INCOMPLETE,
+    EndReason.MAX_DURATION: TerminalState.INCOMPLETE,
+    EndReason.FLOOR_BREACHED: TerminalState.NETWORK_FLOOR,
+    EndReason.USER_CANCEL: TerminalState.CANCELLED,
+    EndReason.SERVER_ERROR: TerminalState.ERROR,
+    EndReason.ADMISSION: TerminalState.ERROR,
+}
+
+
+class CloseCode(IntEnum):
+    """Application-level WebSocket close codes."""
+
+    NORMAL = 1000
+    TOKEN_INVALID = 4001
+    TOKEN_EXPIRED = 4002
+    SESSION_NOT_FOUND = 4003
+    SESSION_USED = 4004
+    UNSUPPORTED_CAPABILITIES = 4005
+    PROTOCOL_VIOLATION = 4006
+    MEDIA_FLOOR_BREACHED = 4007
+    ADMISSION_REJECTED = 4008
+    MAX_DURATION_EXCEEDED = 4009
+    CANCELLED_BY_USER = 4010
+    INTERNAL_ERROR = 4011
+
+
+class ChallengeKind(str, Enum):
+    """Challenge kinds the server may issue."""
+
+    HEAD_TURN = "head_turn"
+    DISTANCE = "distance"
+    FINGERS = "fingers"
+    DIGITS = "digits"
+    BLINK = "blink"
+    EXPRESSION = "expression"
+    HAND_OVER_FACE = "hand_over_face"
+    LOOK_PROFILE = "look_profile"
+
+
+#: Webhook event types delivered to relying parties.
+WEBHOOK_EVENTS: tuple[str, ...] = (
+    "zakadi.session.completed",
+    "zakadi.session.aborted",
+    "zakadi.session.expired",
+)

zakadi-0.0.1/tests/test_protocol.py

@@ -0,0 +1,37 @@
+import unittest
+
+from zakadi import (
+    SUBPROTOCOL,
+    CloseCode,
+    EndReason,
+    ErrorCode,
+    TerminalState,
+    __version__,
+    terminal_state_for_end,
+)
+
+
+class ProtocolTests(unittest.TestCase):
+    def test_subprotocol(self) -> None:
+        self.assertEqual(SUBPROTOCOL, "zakadi.v1")
+        self.assertEqual(__version__, "0.0.1")
+
+    def test_error_codes(self) -> None:
+        self.assertEqual(len(ErrorCode), 18)
+        self.assertEqual(ErrorCode("interrupted"), ErrorCode.INTERRUPTED)
+        with self.assertRaises(ValueError):
+            ErrorCode("not_a_code")
+
+    def test_redial(self) -> None:
+        self.assertTrue(TerminalState.INCOMPLETE.offers_redial)
+        self.assertFalse(TerminalState.COMPLETED.offers_redial)
+        self.assertEqual(TerminalState.INCOMPLETE.cue, "fail.one_more_step")
+
+    def test_end_mapping(self) -> None:
+        self.assertEqual(terminal_state_for_end(EndReason.OK), TerminalState.COMPLETED)
+        self.assertEqual(terminal_state_for_end(EndReason.MAX_DURATION), TerminalState.INCOMPLETE)
+        self.assertEqual(CloseCode.CANCELLED_BY_USER, 4010)
+
+
+if __name__ == "__main__":
+    unittest.main()