openlatch-client-schemas 0.1.4__tar.gz

openlatch_client_schemas-0.1.4/.gitignore

@@ -0,0 +1,52 @@
+# Dependencies
+*.swp
+*.swo
+*.pyc
+__pycache__/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+Thumbs.db
+.DS_Store
+
+# Build outputs
+target/
+dist/
+build/
+
+# Schemas package build staging — canonical source lives in schemas/; CI copies
+# into these paths before publishing @openlatch/client-schemas (npm) and
+# openlatch-client-schemas (PyPI). Not committed to avoid duplicate sources.
+npm/client-schemas/schemas/
+pypi/openlatch-client-schemas/src/openlatch_client_schemas/schemas/
+pypi/openlatch-client-schemas/dist/
+
+# Docker
+*.pid
+*.sock
+
+# Secrets
+*.pem
+*.key
+
+# CI CD
+coverage/
+/target-test
+
+# AI Agents
+CLAUDE.md
+CLAUDE.local.md
+.claude/
+.planning/
+.brainstorming/
+/.brainstorms
+.worktreeinclude

openlatch_client_schemas-0.1.4/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: openlatch-client-schemas
+Version: 0.1.4
+Summary: OpenLatch client wire-format JSON Schemas — canonical contract for events exchanged between openlatch-client and openlatch-platform
+Project-URL: Homepage, https://openlatch.ai
+Project-URL: Repository, https://github.com/OpenLatch/openlatch-client
+Project-URL: Changelog, https://github.com/OpenLatch/openlatch-client/blob/main/CHANGELOG.md
+Author: OpenLatch
+License: Apache-2.0
+Keywords: contract,json-schema,openlatch,schemas
+Classifier: Development Status :: 4 - Beta
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# openlatch-client-schemas
+
+Canonical JSON Schemas for the openlatch-client wire format. This package is the source of truth for the contract between [openlatch-client](https://github.com/OpenLatch/openlatch-client) (Rust) and [openlatch-platform](https://github.com/OpenLatch/openlatch-platform) (Python + React).
+
+## Usage
+
+```python
+from openlatch_client_schemas import schemas_path, load, load_all
+
+schemas_path()                 # pathlib.Path to the bundled schemas/ directory
+load_all()                     # {"enums": {...}, "event-envelope": {...}, ...}
+load("event-envelope")         # parsed schema for one file
+```
+
+## Contents
+
+| File | Purpose |
+|---|---|
+| `enums.schema.json` | `AgentType`, `HookEventType`, `Verdict` |
+| `event-envelope.schema.json` | `EventEnvelope` wire-format |
+| `verdict-response.schema.json` | `VerdictResponse` returned to agent hooks |
+| `cloud-ingestion-request.schema.json` | `CloudIngestionRequest` sent to platform |
+| `cloud-ingestion-response.schema.json` | `CloudIngestionResponse` from platform |
+| `auth-me-response.schema.json` | `AuthMeResponse` for `/api/v1/users/me` |
+
+Version is synchronized with the `openlatch-client` crate — every published version corresponds to the binary release of the same version.
+
+## Breaking Changes
+
+Breaking schema changes require a major version bump. Consumers pinning an exact version will not be silently broken. See the [openlatch-client CHANGELOG](https://github.com/OpenLatch/openlatch-client/blob/main/CHANGELOG.md) for what changed.

openlatch_client_schemas-0.1.4/README.md

@@ -0,0 +1,30 @@
+# openlatch-client-schemas
+
+Canonical JSON Schemas for the openlatch-client wire format. This package is the source of truth for the contract between [openlatch-client](https://github.com/OpenLatch/openlatch-client) (Rust) and [openlatch-platform](https://github.com/OpenLatch/openlatch-platform) (Python + React).
+
+## Usage
+
+```python
+from openlatch_client_schemas import schemas_path, load, load_all
+
+schemas_path()                 # pathlib.Path to the bundled schemas/ directory
+load_all()                     # {"enums": {...}, "event-envelope": {...}, ...}
+load("event-envelope")         # parsed schema for one file
+```
+
+## Contents
+
+| File | Purpose |
+|---|---|
+| `enums.schema.json` | `AgentType`, `HookEventType`, `Verdict` |
+| `event-envelope.schema.json` | `EventEnvelope` wire-format |
+| `verdict-response.schema.json` | `VerdictResponse` returned to agent hooks |
+| `cloud-ingestion-request.schema.json` | `CloudIngestionRequest` sent to platform |
+| `cloud-ingestion-response.schema.json` | `CloudIngestionResponse` from platform |
+| `auth-me-response.schema.json` | `AuthMeResponse` for `/api/v1/users/me` |
+
+Version is synchronized with the `openlatch-client` crate — every published version corresponds to the binary release of the same version.
+
+## Breaking Changes
+
+Breaking schema changes require a major version bump. Consumers pinning an exact version will not be silently broken. See the [openlatch-client CHANGELOG](https://github.com/OpenLatch/openlatch-client/blob/main/CHANGELOG.md) for what changed.

openlatch_client_schemas-0.1.4/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openlatch-client-schemas"
+version = "0.1.4"
+description = "OpenLatch client wire-format JSON Schemas — canonical contract for events exchanged between openlatch-client and openlatch-platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "OpenLatch" }]
+keywords = ["openlatch", "json-schema", "contract", "schemas"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://openlatch.ai"
+Repository = "https://github.com/OpenLatch/openlatch-client"
+Changelog = "https://github.com/OpenLatch/openlatch-client/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openlatch_client_schemas"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/openlatch_client_schemas/**/*.py",
+    "src/openlatch_client_schemas/schemas/*.schema.json",
+    "README.md",
+]

openlatch_client_schemas-0.1.4/src/openlatch_client_schemas/__init__.py

@@ -0,0 +1,35 @@
+"""Canonical JSON Schemas for the openlatch-client wire format.
+
+This package is the source of truth for the contract between openlatch-client
+(Rust) and openlatch-platform (Python + React). Version is synchronized with
+the openlatch-client crate.
+"""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+__all__ = ["schemas_path", "load", "load_all"]
+
+
+def schemas_path() -> Path:
+    """Return the filesystem path to the bundled schemas/ directory."""
+    return Path(str(files(__name__).joinpath("schemas")))
+
+
+def load(name: str) -> dict[str, Any]:
+    """Load a single schema by stem name (e.g. 'event-envelope')."""
+    resource = files(__name__).joinpath("schemas").joinpath(f"{name}.schema.json")
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+def load_all() -> dict[str, dict[str, Any]]:
+    """Load every bundled schema, keyed by stem name."""
+    out: dict[str, dict[str, Any]] = {}
+    root = schemas_path()
+    for p in sorted(root.glob("*.schema.json")):
+        out[p.name.removesuffix(".schema.json")] = json.loads(p.read_text(encoding="utf-8"))
+    return out

openlatch_client_schemas-0.1.4/src/openlatch_client_schemas/schemas/auth-me-response.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.openlatch.ai/client/v1/auth-me-response.schema.json",
+  "title": "AuthMeResponse",
+  "description": "Response from GET /api/v1/users/me for auth status validation (D-19) and PostHog identity stitching (telemetry Phase C). user_db_id, when present, is used as the persistent distinct_id and triggers a one-time $create_alias merging prior agent_id events into the platform person. Mirrors the `id` field on the platform side; both carry the stable better-auth user TEXT primary key.",
+  "type": "object",
+  "additionalProperties": true,
+  "x-postgresql-skip": true,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Stable database identifier for the authenticated user (better-auth user.id). Mirror of user_db_id — either field may be read; prefer user_db_id for telemetry alias semantics."
+    },
+    "user_db_id": {
+      "type": "string",
+      "description": "Stable database identifier for the authenticated user. Used as the PostHog distinct_id post-auth and as the alias target for $create_alias. Optional in this client schema for backwards compatibility — older platforms may not return it; client falls back to agent_id and skips the alias when absent."
+    },
+    "email": {
+      "type": "string",
+      "description": "Email of the authenticated user."
+    },
+    "organization_id": {
+      "type": "string",
+      "description": "Organization id for the user's active organization."
+    },
+    "organization_name": {
+      "type": "string",
+      "description": "Human-readable display name of the user's active organization. Surfaced by the client on re-runs of `openlatch init` so the user can confirm which org their cached credential belongs to. Optional \u2014 when absent, the client displays `Authenticated` without the parenthetical org suffix."
+    }
+  },
+  "examples": [
+    {
+      "id": "usr_019d8af1-f8da-73b3-92eb-79a99e59b10b",
+      "user_db_id": "usr_019d8af1-f8da-73b3-92eb-79a99e59b10b",
+      "email": "alice@example.com",
+      "organization_id": "a1b2c3d4-e5f6-4000-a000-000000000001",
+      "organization_name": "Acme Corp"
+    }
+  ]
+}

openlatch_client_schemas-0.1.4/src/openlatch_client_schemas/schemas/cloud-ingestion-request.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.openlatch.ai/client/v1/cloud-ingestion-request.schema.json",
+  "title": "CloudIngestionRequest",
+  "description": "HTTP request body for POST /api/v1/events/ingest sent by openlatch-client. CloudEvents v1.0.2 batch mode — a bare JSON array of EventEnvelope objects, sent with Content-Type: application/cloudevents-batch+json. Client-wide metadata (schema_version, agent_id) is carried on each CloudEvent via extension attributes rather than a wrapper object.",
+  "type": "array",
+  "x-postgresql-skip": true,
+  "minItems": 1,
+  "maxItems": 100,
+  "items": {
+    "$ref": "event-envelope.schema.json#/$defs/EventEnvelope"
+  },
+  "examples": [
+    [
+      {
+        "specversion": "1.0",
+        "id": "evt_019d8af1-f8da-73b3-92eb-79a99e59b10b",
+        "source": "claude-code",
+        "type": "pre_tool_use",
+        "time": "2026-04-16T12:00:00Z",
+        "datacontenttype": "application/json",
+        "subject": "sess_abc123",
+        "data": {
+          "tool_name": "Bash",
+          "tool_input": {"command": "ls -la"}
+        },
+        "os": "linux",
+        "arch": "x86_64",
+        "clientversion": "0.2.0"
+      }
+    ]
+  ]
+}

openlatch_client_schemas-0.1.4/src/openlatch_client_schemas/schemas/cloud-ingestion-response.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.openlatch.ai/client/v1/cloud-ingestion-response.schema.json",
+  "title": "CloudIngestionResponse",
+  "description": "HTTP response body for POST /api/v1/events/ingest returned to openlatch-client. The client uses status to determine whether to retry, and event_id to correlate verdicts.",
+  "type": "object",
+  "additionalProperties": false,
+  "x-postgresql-skip": true,
+  "required": [
+    "status"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "description": "Ingestion outcome — accepted means persisted (or duplicate), rejected means permanently invalid.",
+      "enum": ["accepted", "rejected"]
+    },
+    "event_id": {
+      "type": "string",
+      "description": "Server-assigned UUIDv7 event_id for the stored event. Present when status is accepted."
+    },
+    "error": {
+      "type": "string",
+      "description": "Human-readable error description. Present when status is rejected."
+    }
+  },
+  "examples": [
+    {
+      "status": "accepted",
+      "event_id": "019d8af1-f8da-73b3-92eb-79a99e59b10b"
+    },
+    {
+      "status": "rejected",
+      "error": "Envelope failed schema validation: missing required attribute 'specversion'"
+    }
+  ]
+}

openlatch_client_schemas-0.1.4/src/openlatch_client_schemas/schemas/enums.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.openlatch.ai/client/v1/enums.schema.json",
+  "title": "OpenLatch Client Enums",
+  "description": "Shared string types for the openlatch-client wire format. HookEventType and AgentType are OPEN strings — any string is valid. The x-known-values vocabularies are informational hints for tooling and telemetry. Verdict remains a closed enum because it is the cloud→client response surface and the client must branch exhaustively on it.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {},
+  "x-postgresql-skip": true,
+  "$defs": {
+    "AgentType": {
+      "type": "string",
+      "description": "CloudEvents 'source' attribute value — the agent platform identifier that emitted the event. Client forwards any string verbatim; the list below is the canonical set of agent platforms recognised by current OpenLatch tooling. Unknown values are preserved and forwarded unchanged (surfaced in Rust as AgentType::Unknown(String) via the tagged-enum lens).",
+      "examples": [
+        "claude-code",
+        "cursor",
+        "windsurf",
+        "github-copilot",
+        "codex-cli",
+        "gemini-cli",
+        "cline",
+        "openclaw"
+      ],
+      "x-known-values": [
+        "claude-code",
+        "cursor",
+        "windsurf",
+        "github-copilot",
+        "codex-cli",
+        "gemini-cli",
+        "cline",
+        "openclaw"
+      ]
+    },
+    "HookEventType": {
+      "type": "string",
+      "description": "CloudEvents 'type' attribute value — the hook event lifecycle name. Client forwards any string verbatim; the list below is the canonical set recognised by current OpenLatch tooling. Unknown values are preserved and forwarded unchanged (surfaced in Rust as HookEventType::Unknown(String) via the tagged-enum lens). The per-agent x-known-values vocabulary records each agent's native event names; every listed value MUST have a matching Rust variant enforced at compile time by build.rs.",
+      "examples": [
+        "pre_tool_use",
+        "post_tool_use",
+        "user_prompt_submit",
+        "stop",
+        "notification",
+        "pre_compact",
+        "session_start",
+        "session_end",
+        "subagent_stop"
+      ],
+      "x-known-values": [
+        "pre_tool_use",
+        "post_tool_use",
+        "user_prompt_submit",
+        "notification",
+        "stop",
+        "subagent_stop",
+        "pre_compact",
+        "session_start",
+        "session_end"
+      ]
+    },
+    "Verdict": {
+      "type": "string",
+      "description": "Verdict returned to the agent hook. Closed enum — client must handle all three variants exhaustively. allow = proceed normally, approve = user-confirmed allow, deny = blocked.",
+      "enum": [
+        "allow",
+        "approve",
+        "deny"
+      ]
+    }
+  },
+  "examples": [{}]
+}

openlatch_client_schemas-0.1.4/src/openlatch_client_schemas/schemas/event-envelope.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.openlatch.ai/client/v1/event-envelope.schema.json",
+  "title": "EventEnvelope",
+  "description": "CloudEvents v1.0.2 structured-mode envelope for agent hook events. Content-Type is application/cloudevents+json (single) or application/cloudevents-batch+json (batch). The 'data' field contains the raw agent payload untouched; all OpenLatch metadata lives in CloudEvents extension attributes. Extension attribute names MUST match ^[a-z0-9]+$ per the CloudEvents spec. verdict and latency_ms are NOT on the wire — they are produced by the daemon after processing and attached to stored events as the olverdict and ollatencyms extension attributes.",
+  "type": "object",
+  "additionalProperties": true,
+  "x-postgresql-skip": true,
+  "required": [
+    "specversion",
+    "id",
+    "source",
+    "type",
+    "time"
+  ],
+  "properties": {
+    "specversion": {
+      "type": "string",
+      "const": "1.0",
+      "description": "CloudEvents spec version. MUST be '1.0' for CloudEvents v1.0.2."
+    },
+    "id": {
+      "type": "string",
+      "description": "Unique event identifier — UUIDv7 with 'evt_' prefix. CloudEvents core attribute."
+    },
+    "source": {
+      "$ref": "enums.schema.json#/$defs/AgentType",
+      "description": "Agent platform identifier (was 'agent_platform'). CloudEvents core attribute. Bare string per OpenLatch convention; any string is valid. See x-known-values in enums.schema.json#/$defs/AgentType for the canonical set."
+    },
+    "type": {
+      "$ref": "enums.schema.json#/$defs/HookEventType",
+      "description": "Hook event lifecycle name (was 'event_type'). CloudEvents core attribute. Any string is valid. See x-known-values in enums.schema.json#/$defs/HookEventType for the canonical set."
+    },
+    "time": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Event creation timestamp (was 'timestamp'). RFC 3339 UTC with Z suffix. CloudEvents core attribute."
+    },
+    "datacontenttype": {
+      "type": "string",
+      "const": "application/json",
+      "description": "Media type of the 'data' field. CloudEvents core optional attribute. Fixed to application/json for all OpenLatch events."
+    },
+    "subject": {
+      "type": "string",
+      "description": "CloudEvents 'subject' attribute. OpenLatch uses this for the agent session identifier (was 'session_id'). Consumers can group events by subject for per-session analytics."
+    },
+    "data": {
+      "description": "Raw agent payload, forwarded verbatim. Shape is agent-specific (e.g. Claude Code PreToolUse emits { tool_name, tool_input, … }; Cursor beforeShellExecution emits { command, … }). OpenLatch does NOT normalise this field."
+    },
+    "os": {
+      "type": "string",
+      "description": "OpenLatch extension. Operating system ('linux', 'macos', 'windows'). CloudEvents extension — lowercase alphanumeric attribute name."
+    },
+    "arch": {
+      "type": "string",
+      "description": "OpenLatch extension. CPU architecture ('x86_64', 'aarch64')."
+    },
+    "localipv4": {
+      "type": "string",
+      "format": "ipv4",
+      "description": "OpenLatch extension (was 'local_ipv4'). Machine's local IPv4 address. Detected once at daemon startup, cached for the process lifetime. Omitted when no non-loopback interface is available."
+    },
+    "localipv6": {
+      "type": "string",
+      "format": "ipv6",
+      "description": "OpenLatch extension (was 'local_ipv6'). Machine's local IPv6 address."
+    },
+    "publicipv4": {
+      "type": "string",
+      "format": "ipv4",
+      "description": "OpenLatch extension (was 'public_ipv4'). Machine's public IPv4 address."
+    },
+    "publicipv6": {
+      "type": "string",
+      "format": "ipv6",
+      "description": "OpenLatch extension (was 'public_ipv6'). Machine's public IPv6 address."
+    },
+    "clientversion": {
+      "type": "string",
+      "description": "OpenLatch extension (was 'client_version'). Semver of the openlatch-client that emitted the envelope."
+    },
+    "agentversion": {
+      "type": "string",
+      "description": "OpenLatch extension (was 'agent_version'). Agent software version, if reported by the hook."
+    },
+    "agentid": {
+      "type": "string",
+      "description": "OpenLatch extension. Stamped by the daemon on outbound events — identifies the AI agent install (one openlatch-client installation) that emitted this event (agt_<uuid>)."
+    }
+  },
+  "examples": [
+    {
+      "specversion": "1.0",
+      "id": "evt_019d8af1-f8da-73b3-92eb-79a99e59b10b",
+      "source": "claude-code",
+      "type": "pre_tool_use",
+      "time": "2026-04-16T12:00:00Z",
+      "datacontenttype": "application/json",
+      "subject": "sess_abc123",
+      "data": {
+        "tool_name": "Bash",
+        "tool_input": {"command": "ls -la"}
+      },
+      "os": "linux",
+      "arch": "x86_64",
+      "localipv4": "192.168.1.42",
+      "publicipv4": "203.0.113.7",
+      "clientversion": "0.2.0",
+      "agentversion": "1.2.0"
+    }
+  ]
+}

openlatch_client_schemas-0.1.4/src/openlatch_client_schemas/schemas/verdict-response.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.openlatch.ai/client/v1/verdict-response.schema.json",
+  "title": "VerdictResponse",
+  "description": "Verdict response returned to the agent hook after processing. The client passes this through to the agent hook without interpreting the verdict itself. Mirrors the cloud response schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "x-postgresql-skip": true,
+  "required": [
+    "schema_version",
+    "verdict",
+    "event_id",
+    "latency_ms"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Schema version for forward compatibility. Currently '1.0'."
+    },
+    "verdict": {
+      "$ref": "enums.schema.json#/$defs/Verdict",
+      "description": "The verdict: allow = proceed, approve = user-confirmed allow, deny = blocked."
+    },
+    "event_id": {
+      "type": "string",
+      "description": "Server-assigned or client-generated ID of the event this verdict responds to."
+    },
+    "latency_ms": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Total end-to-end processing latency in milliseconds, including cloud round-trip when applicable."
+    },
+    "reason": {
+      "type": "string",
+      "description": "Human-readable explanation for the verdict. Omitted for allow verdicts."
+    },
+    "severity": {
+      "type": "string",
+      "description": "Threat severity level (e.g., 'critical', 'high', 'medium', 'low'). Omitted when no threat was detected."
+    },
+    "threat_category": {
+      "type": "string",
+      "description": "Category of detected threat (e.g., 'credential_exfiltration', 'command_injection'). Omitted when no threat detected."
+    },
+    "rule_id": {
+      "type": "string",
+      "description": "Identifier of the detection rule that triggered this verdict. Omitted when no rule matched."
+    },
+    "details_url": {
+      "type": "string",
+      "description": "URL to the OpenLatch dashboard with detailed event analysis. Omitted when not available."
+    }
+  },
+  "examples": [
+    {
+      "schema_version": "1.0",
+      "verdict": "allow",
+      "event_id": "019d8af1-f8da-73b3-92eb-79a99e59b10b",
+      "latency_ms": 42
+    },
+    {
+      "schema_version": "1.0",
+      "verdict": "deny",
+      "event_id": "019d8af1-f8da-73b3-92eb-000000000002",
+      "latency_ms": 88,
+      "reason": "Credential detected in tool output",
+      "severity": "critical",
+      "threat_category": "credential_detection",
+      "rule_id": "rule_cred_001",
+      "details_url": "https://app.openlatch.ai/events/019d8af1-f8da-73b3-92eb-000000000002"
+    }
+  ]
+}