codai-sdk 0.3.0__tar.gz → 0.5.0__tar.gz

{codai_sdk-0.3.0 → codai_sdk-0.5.0}/CHANGELOG.md

@@ -6,6 +6,34 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-27
+
+### Added
+
+- Resolve job webhooks: `callback_url` on `ResolveIntake`, one-time `callback_secret` on
+  `ResolveQuote` / `ResolveDeclined`, and `ResolveWebhookEvent` / `ResolveWebhookEventName` /
+  `ResolveWebhookJob` TypedDicts (regenerated `_resolve_types.py`).
+- `verify_resolve_webhook(secret, raw_body, signature_header, tolerance_seconds=300, now=None)`
+  — constant-time (`hmac.compare_digest`) check of `x-codai-signature: t=<unix>,v1=<hex>`
+  with a timestamp window. Exported from `codai` and `codai.resources`.
+
+## [0.4.0] - 2026-09-27
+
+### Added
+
+- `client.resolve` — codai Resolve (pay per verified fix, `https://resolve.codai.ro`,
+  override with `resolve_base_url=`): `submit`, `get`, `accept`, `attestation`,
+  `health`, `wait_for`. `ResolveError` / `ResolveInsufficientFundsError` (402 carries
+  `topup_url`, `balance`, `required`). `RESOLVE_OPERATION_METHODS` maps every
+  `resolve.yaml` operationId; `_resolve_types.py` is generated from it.
+
+## [0.3.1] - 2026-09-26
+
+### Changed
+
+- Regenerated `_types.py`: project prebuild pool fields, environment `prebuild`
+  and `prebuild_claimed` on create (CE-0072).
+
 ## [0.3.0] - 2026-09-25
 
 ### Added

{codai_sdk-0.3.0 → codai_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codai-sdk
-Version: 0.3.0
+Version: 0.5.0
 Summary: Official Python SDK for the codai AI gateway — chat, messages, responses, streaming, agents, sessions, hosts, tasks, account.
 Project-URL: Homepage, https://codai.ro
 Project-URL: Repository, https://github.com/codai-ro/codai-sdk-python
@@ -147,6 +147,60 @@ Typed request/response shapes live in `codai._types` (generated from the
 OpenAPI spec — `TypedDict`s such as `ChatCompletionRequest`, `Task`,
 `SessionEvent`, `CreateSessionShareResponse`).
 
+## codai Resolve (0.4.0)
+
+Pay per verified fix: submit a public GitHub issue, get a flat quote, accept it
+(held on your wallet), and pay only when the fix passes your tests. First 3 fixes
+are free. Lives on `https://resolve.codai.ro` (same key; `resolve_base_url=` to override).
+
+```python
+from codai import Codai, ResolveInsufficientFundsError
+
+client = Codai(api_key="codai_...")
+job = client.resolve.submit({
+    "repo_url": "https://github.com/owner/repo",
+    "issue_url": "https://github.com/owner/repo/issues/42",
+})
+if job["status"] == "quoted":
+    try:
+        client.resolve.accept(job["id"])
+    except ResolveInsufficientFundsError as e:
+        print("top up first:", e.topup_url)
+        raise
+done = client.resolve.wait_for(job["id"])
+print(done["status"], done.get("attestation_url"))
+```
+
+Failed attempts and infrastructure errors refund the hold in full. Types:
+`codai._resolve_types` (generated from `resolve.yaml`).
+
+### Webhooks instead of polling (0.5.0)
+
+Pass `callback_url` (https, public host) on `submit`; the response carries
+`callback_secret` **once** — store it. Resolve POSTs `job.quoted`, `job.declined`,
+`job.resolved`, `job.failed` and `job.error`, signed with
+`x-codai-signature: t=<unix>,v1=<hex HMAC-SHA256>`. Verify the raw body with
+`verify_resolve_webhook` (constant-time, 300 s tolerance by default). Up to 3
+attempts on 5xx/429/network errors; deduplicate on `x-codai-delivery`; delivery
+never changes job state — `get(id)` stays the source of truth.
+
+```python
+import json
+from codai import verify_resolve_webhook
+
+job = client.resolve.submit({
+    "repo_url": "https://github.com/owner/repo",
+    "issue_url": "https://github.com/owner/repo/issues/42",
+    "callback_url": "https://ci.example.com/hooks/codai-resolve",
+})
+save_secret(job["id"], job["callback_secret"])  # shown once
+
+# in your webhook handler (FastAPI: raw = await request.body())
+if not verify_resolve_webhook(secret, raw, request.headers.get("x-codai-signature")):
+    raise HTTPException(401, "bad signature")
+event = json.loads(raw)  # event["event"], event["job"]["attestation_url"]
+```
+
 ## Development
 
 ```bash

{codai_sdk-0.3.0 → codai_sdk-0.5.0}/README.md

@@ -123,6 +123,60 @@ Typed request/response shapes live in `codai._types` (generated from the
 OpenAPI spec — `TypedDict`s such as `ChatCompletionRequest`, `Task`,
 `SessionEvent`, `CreateSessionShareResponse`).
 
+## codai Resolve (0.4.0)
+
+Pay per verified fix: submit a public GitHub issue, get a flat quote, accept it
+(held on your wallet), and pay only when the fix passes your tests. First 3 fixes
+are free. Lives on `https://resolve.codai.ro` (same key; `resolve_base_url=` to override).
+
+```python
+from codai import Codai, ResolveInsufficientFundsError
+
+client = Codai(api_key="codai_...")
+job = client.resolve.submit({
+    "repo_url": "https://github.com/owner/repo",
+    "issue_url": "https://github.com/owner/repo/issues/42",
+})
+if job["status"] == "quoted":
+    try:
+        client.resolve.accept(job["id"])
+    except ResolveInsufficientFundsError as e:
+        print("top up first:", e.topup_url)
+        raise
+done = client.resolve.wait_for(job["id"])
+print(done["status"], done.get("attestation_url"))
+```
+
+Failed attempts and infrastructure errors refund the hold in full. Types:
+`codai._resolve_types` (generated from `resolve.yaml`).
+
+### Webhooks instead of polling (0.5.0)
+
+Pass `callback_url` (https, public host) on `submit`; the response carries
+`callback_secret` **once** — store it. Resolve POSTs `job.quoted`, `job.declined`,
+`job.resolved`, `job.failed` and `job.error`, signed with
+`x-codai-signature: t=<unix>,v1=<hex HMAC-SHA256>`. Verify the raw body with
+`verify_resolve_webhook` (constant-time, 300 s tolerance by default). Up to 3
+attempts on 5xx/429/network errors; deduplicate on `x-codai-delivery`; delivery
+never changes job state — `get(id)` stays the source of truth.
+
+```python
+import json
+from codai import verify_resolve_webhook
+
+job = client.resolve.submit({
+    "repo_url": "https://github.com/owner/repo",
+    "issue_url": "https://github.com/owner/repo/issues/42",
+    "callback_url": "https://ci.example.com/hooks/codai-resolve",
+})
+save_secret(job["id"], job["callback_secret"])  # shown once
+
+# in your webhook handler (FastAPI: raw = await request.body())
+if not verify_resolve_webhook(secret, raw, request.headers.get("x-codai-signature")):
+    raise HTTPException(401, "bad signature")
+event = json.loads(raw)  # event["event"], event["job"]["attestation_url"]
+```
+
 ## Development
 
 ```bash

{codai_sdk-0.3.0 → codai_sdk-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codai-sdk"
-version = "0.3.0"
+version = "0.5.0"
 description = "Official Python SDK for the codai AI gateway — chat, messages, responses, streaming, agents, sessions, hosts, tasks, account."
 readme = "README.md"
 license = "MIT"

{codai_sdk-0.3.0 → codai_sdk-0.5.0}/scripts/gen-types.py

@@ -1,13 +1,15 @@
 #!/usr/bin/env python3
-"""Generate ``src/codai/_types.py`` from ``apps/docs/openapi/en/gateway.yaml``.
+"""Generate ``src/codai/_types.py`` from ``apps/docs/openapi/en/gateway.yaml``
+(and ``src/codai/_resolve_types.py`` from ``resolve.yaml`` with ``--spec resolve``).
 
 TypedDicts for every ``components.schemas`` entry plus a ``<operationId>Body`` /
 ``<operationId>Response`` alias for each operation's JSON request / 2xx body.
 Deterministic: the same spec always produces byte-identical output, so a second
 run is a no-op (the parity CI step diffs the committed file against a fresh run).
 
-    .\\.venv\\Scripts\\python scripts/gen-types.py          # write
-    .\\.venv\\Scripts\\python scripts/gen-types.py --check  # exit 1 when stale
+    .\\.venv\\Scripts\\python scripts/gen-types.py                   # write
+    .\\.venv\\Scripts\\python scripts/gen-types.py --check           # exit 1 when stale
+    .\\.venv\\Scripts\\python scripts/gen-types.py --spec resolve    # Resolve API types
 
 Dev-only dependency: pyyaml (``pip install -e ".[dev]"``). The runtime SDK stays
 zero-dependency — this script is never imported by the package.
@@ -25,15 +27,24 @@ import yaml
 
 HERE = Path(__file__).resolve().parent
 PKG = HERE.parent
-SPEC = PKG.parents[1] / "apps" / "docs" / "openapi" / "en" / "gateway.yaml"
+OPENAPI = PKG.parents[1] / "apps" / "docs" / "openapi" / "en"
+SPEC = OPENAPI / "gateway.yaml"
 OUT = PKG / "src" / "codai" / "_types.py"
+RESOLVE_SPEC = OPENAPI / "resolve.yaml"
+RESOLVE_OUT = PKG / "src" / "codai" / "_resolve_types.py"
+
+# --spec name → (spec file, output file, API label, regenerate command)
+TARGETS: Dict[str, Tuple[Path, Path, str, str]] = {
+    "gateway": (SPEC, OUT, "gateway", "python scripts/gen-types.py"),
+    "resolve": (RESOLVE_SPEC, RESOLVE_OUT, "Resolve", "python scripts/gen-types.py --spec resolve"),
+}
 
 HTTP_METHODS = ("get", "post", "put", "patch", "delete")
 
-HEADER = '''"""Typed dictionaries for the codai gateway API.
+HEADER = '''"""Typed dictionaries for the codai {api} API.
 
-generated — do not edit. Source: apps/docs/openapi/en/gateway.yaml.
-Regenerate with ``python scripts/gen-types.py`` (see that script's docstring).
+generated — do not edit. Source: apps/docs/openapi/en/{source}.
+Regenerate with ``{regen}`` (see that script's docstring).
 
 Every ``components.schemas`` entry is a ``TypedDict`` (``total=False`` when the
 schema has optional fields; a ``_<Name>Required`` base carries the required
@@ -76,8 +87,15 @@ def union(parts: List[str]) -> str:
 
 
 class Generator:
-    def __init__(self, spec: Dict[str, Any]) -> None:
+    def __init__(
+        self,
+        spec: Dict[str, Any],
+        api: str = "gateway",
+        source: str = "gateway.yaml",
+        regen: str = "python scripts/gen-types.py",
+    ) -> None:
         self.spec = spec
+        self.header = HEADER.format(api=api, source=source, regen=regen)
         self.schemas: Dict[str, Any] = spec["components"]["schemas"]
         self.blocks: List[Tuple[str, str]] = []
         self.emitted: Dict[str, str] = {}
@@ -295,7 +313,7 @@ class Generator:
         for name in self.schemas:  # YAML order
             self.ensure_schema(name)
         self.emit_operations()
-        out = [HEADER]
+        out = [self.header]
         for _, code in self.blocks:
             out.append(code)
             out.append("\n\n")
@@ -307,18 +325,23 @@ class Generator:
 
 
 def main(argv: List[str]) -> int:
-    with SPEC.open("r", encoding="utf-8") as fh:
+    name = argv[argv.index("--spec") + 1] if "--spec" in argv else "gateway"
+    if name not in TARGETS:
+        print(f"unknown --spec {name!r}; one of {', '.join(TARGETS)}", file=sys.stderr)
+        return 2
+    spec_path, out, api, regen = TARGETS[name]
+    with spec_path.open("r", encoding="utf-8") as fh:
         spec = yaml.safe_load(fh)
-    text = Generator(spec).render()
+    text = Generator(spec, api=api, source=spec_path.name, regen=regen).render()
     if "--check" in argv:
-        current = OUT.read_text(encoding="utf-8") if OUT.exists() else ""
+        current = out.read_text(encoding="utf-8") if out.exists() else ""
         if current != text:
-            print(f"STALE: {OUT} differs from a fresh generation", file=sys.stderr)
+            print(f"STALE: {out} differs from a fresh generation", file=sys.stderr)
             return 1
-        print(f"OK: {OUT} is up to date")
+        print(f"OK: {out} is up to date")
         return 0
-    OUT.write_text(text, encoding="utf-8", newline="\n")
-    print(f"wrote {OUT} ({text.count(chr(10))} lines, {len(spec['components']['schemas'])} schemas)")
+    out.write_text(text, encoding="utf-8", newline="\n")
+    print(f"wrote {out} ({text.count(chr(10))} lines, {len(spec['components']['schemas'])} schemas)")
     return 0
 
 

{codai_sdk-0.3.0 → codai_sdk-0.5.0}/src/codai/__init__.py

@@ -32,8 +32,9 @@ from __future__ import annotations
 from typing import Any, Dict, Generator, List, Optional
 
 from ._http import CodaiError, HttpClient, RequestExtensions, SseFrame, extension_headers, frame_json, read_sse
-from ._operations import OPERATION_METHODS, STREAMING_OPERATIONS
+from ._operations import OPERATION_METHODS, RESOLVE_OPERATION_METHODS, STREAMING_OPERATIONS
 from .resources import (
+    RESOLVE_TERMINAL_STATUSES,
     Account,
     AgentRunResult,
     Agents,
@@ -55,6 +56,9 @@ from .resources import (
     PhoneModels,
     Projects,
     Receipts,
+    Resolve,
+    ResolveError,
+    ResolveInsufficientFundsError,
     Responses,
     Sessions,
     SystemOne,
@@ -62,6 +66,7 @@ from .resources import (
     Tokens,
     Tools,
     Triggers,
+    verify_resolve_webhook,
 )
 
 __all__ = [
@@ -75,12 +80,17 @@ __all__ = [
     "RequestExtensions",
     "SseFrame",
     "OPERATION_METHODS",
+    "RESOLVE_OPERATION_METHODS",
+    "RESOLVE_TERMINAL_STATUSES",
+    "ResolveError",
+    "ResolveInsufficientFundsError",
     "STREAMING_OPERATIONS",
     "extension_headers",
     "frame_json",
     "read_sse",
+    "verify_resolve_webhook",
 ]
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 
 class _CallableGroup:
@@ -113,6 +123,7 @@ class Codai:
         client: Optional[str] = None,
         defaults: Optional[RequestExtensions] = None,
         opener: Any = None,
+        resolve_base_url: str = "https://resolve.codai.ro",
     ) -> None:
         if not api_key:
             raise ValueError("Codai: api_key is required")
@@ -156,6 +167,16 @@ class Codai:
         self.phone_models = PhoneModels(http)
         self.triggers = Triggers(http)
         self.notifications = Notifications(http)
+        # codai Resolve lives on its own host; same key, no X-Codai-* defaults.
+        self.resolve = Resolve(
+            HttpClient(
+                api_key=api_key,
+                base_url=resolve_base_url,
+                timeout=timeout,
+                max_retries=max_retries,
+                opener=opener,
+            )
+        )
 
         self.chat: Any = _CallableGroup(Chat(http), self._legacy_chat)
         self.embeddings: Any = _CallableGroup(Embeddings(http), self._legacy_embeddings)

{codai_sdk-0.3.0 → codai_sdk-0.5.0}/src/codai/_operations.py

@@ -123,6 +123,8 @@ OPERATION_METHODS: Dict[str, str] = {
     "receiveTriggerHook": "triggers.fire_hook",
     "listNotifications": "notifications.list",
     "markNotificationsRead": "notifications.mark_read",
+    "deleteNotification": "notifications.delete",
+    "deleteNotifications": "notifications.delete_many",
     # Account
     "getAccount": "account.get",
     "patchAccount": "account.update",
@@ -133,3 +135,12 @@ OPERATION_METHODS: Dict[str, str] = {
 
 # Operations whose SDK method is a generator (SSE-only endpoints).
 STREAMING_OPERATIONS: FrozenSet[str] = frozenset({"streamAgentRun", "streamSession", "streamHost"})
+
+# codai Resolve (``apps/docs/openapi/en/resolve.yaml``) → ``client.resolve.*``.
+RESOLVE_OPERATION_METHODS: Dict[str, str] = {
+    "resolveHealth": "resolve.health",
+    "createResolveJob": "resolve.submit",
+    "getResolveJob": "resolve.get",
+    "acceptResolveJob": "resolve.accept",
+    "getResolveAttestation": "resolve.attestation",
+}

codai_sdk-0.5.0/src/codai/_resolve_types.py

@@ -0,0 +1,212 @@
+"""Typed dictionaries for the codai Resolve API.
+
+generated — do not edit. Source: apps/docs/openapi/en/resolve.yaml.
+Regenerate with ``python scripts/gen-types.py --spec resolve`` (see that script's docstring).
+
+Every ``components.schemas`` entry is a ``TypedDict`` (``total=False`` when the
+schema has optional fields; a ``_<Name>Required`` base carries the required
+keys of mixed schemas). Non-object schemas (enums, unions, arrays) are type
+aliases. ``<operationId>Body`` / ``<operationId>Response`` name each
+operation's JSON request body and first 2xx JSON response.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+class ResolveHealth(TypedDict):
+    ok: bool
+    service: str
+
+
+class ResolveValidationDetails(TypedDict):
+    """Zod `flatten()` output returned when the intake body fails schema validation."""
+    formErrors: List[str]
+    fieldErrors: Dict[str, List[str]]
+
+
+class ResolveError(TypedDict):
+    """Flat error envelope used by every Resolve endpoint. Not the gateway `{ error: { code, message } }` shape."""
+    error: Union[str, ResolveValidationDetails]
+
+
+class _ResolveIntakeRequired(TypedDict):
+    repo_url: str
+
+
+class ResolveIntake(_ResolveIntakeRequired, total=False):
+    """Body of `POST /v1/resolve/jobs`. Provide `issue_url` or `issue_text` (at least one)."""
+    issue_url: str
+    issue_text: str
+    test_command: str
+    callback_url: str
+
+
+# `free` (first 3 resolves per user), `t7` ($7), `t19` ($19), `t49` ($49). Prices are in USD micros on the wire.
+ResolveTier = Literal['free', 't7', 't19', 't49']
+
+
+# Lifecycle: `triage → quoted → accepted → running → resolved | failed`, plus `declined`
+ResolveJobStatus = Literal['triage', 'quoted', 'declined', 'accepted', 'running', 'resolved', 'failed', 'error']
+
+
+class _ResolveQuoteRequired(TypedDict):
+    id: str
+    status: Literal['quoted', 'accepted']
+    tier: ResolveTier
+    quote_micro_usd: int
+    triage_reason: str
+    free_tier_remaining: int
+
+
+class ResolveQuote(_ResolveQuoteRequired, total=False):
+    """`201` body — the job was quoted (`quoted`) or auto-accepted on the free tier (`accepted`)."""
+    callback_secret: str
+
+
+class _ResolveDeclinedRequired(TypedDict):
+    id: str
+    status: str
+    decline_reason: str
+
+
+class ResolveDeclined(_ResolveDeclinedRequired, total=False):
+    """`200` body — triage declined the issue. The job is persisted with `status: declined` and is never billed."""
+    callback_secret: str
+
+
+class ResolveAccepted(TypedDict):
+    """Accepted"""
+    id: str
+    status: str
+
+
+class ResolveInsufficientFunds(TypedDict):
+    """`402` body of `POST /v1/resolve/jobs/{id}/accept` when the wallet cannot hold the quote."""
+    error: str
+    balance: int
+    required: int
+    currency: str
+    topup_url: str
+
+
+class ResolveJob(TypedDict):
+    """Full job view returned by `GET /v1/resolve/jobs/{id}`. Nullable fields are `null` until the corresponding stag…"""
+    id: str
+    status: ResolveJobStatus
+    repo_url: str
+    tier: Optional[ResolveTier]
+    quote_micro_usd: Optional[int]
+    triage_reason: Optional[str]
+    decline_reason: Optional[str]
+    fail_reason: Optional[str]
+    cost_micro_usd: int
+    attestation_id: Optional[str]
+    attestation_url: Optional[str]
+    created_at: str
+    completed_at: Optional[str]
+
+
+class ResolveReproTest(TypedDict):
+    """Repro test written by the agent when you did not supply `test_command`."""
+    path: str
+    content: Optional[str]
+
+
+class ResolveAttestation(TypedDict):
+    """Public execution proof. Everything needed to reproduce the verification locally."""
+    id: str
+    kind: str
+    repo_url: str
+    base_commit: str
+    patch: str
+    repro_test: Optional[ResolveReproTest]
+    test_command: str
+    regression_command: Optional[str]
+    test_output_before: str
+    test_output_after: str
+    regression_output: Optional[str]
+    runner_image_digest: str
+    started_at: str
+    verified_at: str
+
+
+# `job.quoted` (paid quote ready), `job.declined` (triage refused), `job.resolved` (verified fix + attestation),…
+ResolveWebhookEventName = Literal['job.quoted', 'job.declined', 'job.resolved', 'job.failed', 'job.error']
+
+
+class ResolveWebhookJob(TypedDict):
+    """Snapshot of the job at send time. Nullable fields are `null` until the corresponding stage has run."""
+    id: str
+    status: ResolveJobStatus
+    tier: Optional[ResolveTier]
+    quote_micro_usd: Optional[int]
+    repo_url: str
+    decline_reason: Optional[str]
+    fail_reason: Optional[str]
+    cost_micro_usd: int
+    attestation_id: Optional[str]
+    attestation_url: Optional[str]
+    completed_at: Optional[str]
+
+
+class ResolveWebhookEvent(TypedDict):
+    """JSON body POSTed to `callback_url`. Verify `x-codai-signature` over the raw bytes before trusting it."""
+    event: ResolveWebhookEventName
+    job: ResolveWebhookJob
+    sent_at: str
+
+
+# GET /health — 200 response
+ResolveHealthResponse = ResolveHealth
+
+
+# POST /v1/resolve/jobs — request body
+CreateResolveJobBody = ResolveIntake
+
+
+# POST /v1/resolve/jobs — 200 response
+CreateResolveJobResponse = ResolveDeclined
+
+
+# POST /v1/resolve/jobs — 201 response
+CreateResolveJobResponse201 = ResolveQuote
+
+
+# GET /v1/resolve/jobs/{id} — 200 response
+GetResolveJobResponse = ResolveJob
+
+
+# POST /v1/resolve/jobs/{id}/accept — 200 response
+AcceptResolveJobResponse = ResolveAccepted
+
+
+# GET /v1/resolve/attestations/{id} — 200 response
+GetResolveAttestationResponse = ResolveAttestation
+
+
+__all__ = [
+    'AcceptResolveJobResponse',
+    'CreateResolveJobBody',
+    'CreateResolveJobResponse',
+    'CreateResolveJobResponse201',
+    'GetResolveAttestationResponse',
+    'GetResolveJobResponse',
+    'ResolveAccepted',
+    'ResolveAttestation',
+    'ResolveDeclined',
+    'ResolveError',
+    'ResolveHealth',
+    'ResolveHealthResponse',
+    'ResolveInsufficientFunds',
+    'ResolveIntake',
+    'ResolveJob',
+    'ResolveJobStatus',
+    'ResolveQuote',
+    'ResolveReproTest',
+    'ResolveTier',
+    'ResolveValidationDetails',
+    'ResolveWebhookEvent',
+    'ResolveWebhookEventName',
+    'ResolveWebhookJob',
+]