nodii-document-cloud-client 0.0.2__tar.gz → 0.2.0__tar.gz

nodii_document_cloud_client-0.2.0/.gitignore

@@ -0,0 +1,89 @@
+node_modules/
+dist/
+build/
+coverage/
+.DS_Store
+*.log
+.env
+.env.local
+.env.*.local
+.turbo/
+.bun/
+
+# AI review loop artifacts (scripts/review/ai-review.ts)
+.claude-pre-review.md
+.claude-pre-review.json
+.claude/pending-patches/
+# Review-tooling scratch. `scripts/review/ai-review.ts` writes a snapshot of
+# the diff under review into .claude/ on every run; a `git add -A` then commits
+# a copy of the PR into the PR. Seven of these were already tracked on main
+# before this rule existed — untracking those is a separate cleanup.
+.claude/claim-audit-diff-*.patch
+.claude/review-diff-*.patch
+.claude/review-claude-last.json
+
+# Agent session state (not committed; per-session)
+.claude/endpoints-snapshot.json
+.agent-todo.md
+
+# Python (uv)
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Go
+*.test
+*.out
+go.work.sum
+
+# Generated proto artifacts (regenerate via `bun proto:gen`)
+ts/_generated/
+python/_generated/
+go/_generated/
+
+# Test-stack volumes (docker-compose persistent data)
+infra/test-stack/data/
+# synthetic consumer go binaries
+synthetic-consumers/telemetry/go/nodii-synthetic-telemetry
+synthetic-consumers/pii/go/nodii-synthetic-pii
+synthetic-consumers/auth-sdk/go/nodii-synthetic-auth-sdk
+.claude-claim-audit.md
+.claude-claim-audit.json
+
+# Compiled synthetic-consumer Go binaries — CLASS RULE, not a name list.
+#
+# `go build` / `go run .` in synthetic-consumers/<lib>/go/ emits a binary named
+# after the directory or the module's last path element, which the `*.test` /
+# `*.out` rules above do not match. The rules here used to name them one at a
+# time (role-catalog, nodii-synthetic-telemetry, nodii-synthetic-pii,
+# nodii-synthetic-auth-sdk, plus a `*/[a-z]*-go` glob) and that is exactly how
+# FOUR of them ended up committed anyway, 77 MB in total:
+#
+#   synthetic-consumers/audit-chain/go/audit-chain                      13 MB
+#   synthetic-consumers/replica-consumer/go/replica-consumer            14 MB
+#   synthetic-consumers/grpc-interceptors/go/nodii-synthetic-grpc-...   22 MB
+#   synthetic-consumers/bean-app-cluster/go/auth-svc/bean-auth-svc-go   26 MB
+#
+# The last of those DID match the old `*/[a-z]*-go` glob — a rule cannot save a
+# file that was already tracked when it landed, which is why they were removed
+# with `git rm --cached` in the same commit as this rule.
+#
+# HOW IT WORKS: every real source file under these directories has an extension
+# (.go, .mod, .sum) — verified, zero tracked extensionless files under
+# synthetic-consumers/*/go/ — so "extensionless file" is a sound proxy for
+# "build artefact". Directories and any dotted filename are re-included, so
+# cmd/, internal/ and friends keep working. Naming a NEW binary can no longer
+# defeat it; that was the whole failure mode.
+synthetic-consumers/**/go/**
+!synthetic-consumers/**/go/**/
+!synthetic-consumers/**/go/**/*.*
+!synthetic-consumers/**/go/*.*

nodii_document_cloud_client-0.2.0/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) Nodii
+
+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.

nodii_document_cloud_client-0.2.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: nodii-document-cloud-client
+Version: 0.2.0
+Summary: Authenticated Document Cloud client with replay-safe direct object-store uploads
+Project-URL: Homepage, https://github.com/cognion-nucleus/nodii-libs
+Project-URL: Repository, https://github.com/cognion-nucleus/nodii-libs
+Author-email: Nodii <ops@nodii.co>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: grpcio-tools>=1.60
+Requires-Dist: grpcio>=1.60
+Requires-Dist: httpx>=0.27
+Requires-Dist: nodii-grpc-auth>=0.16.0
+Requires-Dist: protobuf>=4.25

nodii_document_cloud_client-0.2.0/README.md

@@ -0,0 +1,17 @@
+# nodii-document-cloud-client
+
+The Python twin of `@nodii/document-cloud-client`. It authenticates every RPC,
+streams upload hashing to bounded storage, and sends document bytes directly to
+the signed object-store URL.
+
+```python
+client = create_document_cloud_client(address=DOCUMENT_CLOUD,
+    get_s2s_token=get_token, tenant_id=tenant_id, service_name="hr")
+result = await client.upload_document(folder_path="HR/Payslips/2026",
+    title="October payslip", body=payslip, content_type="application/pdf",
+    idempotency_key=f"payslip:{employee_id}:2026-10", contexts=[{
+        "context_kind": "hr.employee", "context_ref": employee_id,
+        "source_type": "api",
+    }])
+await client.close()
+```

nodii_document_cloud_client-0.2.0/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "nodii-document-cloud-client"
+version = "0.2.0"
+description = "Authenticated Document Cloud client with replay-safe direct object-store uploads"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Nodii", email = "ops@nodii.co" }]
+dependencies = [
+  "grpcio>=1.60",
+  "grpcio-tools>=1.60",
+  "httpx>=0.27",
+  "nodii-grpc-auth>=0.16.0",
+  "protobuf>=4.25",
+]
+
+[tool.uv.sources]
+nodii-grpc-auth = { workspace = true }
+
+[project.urls]
+Homepage = "https://github.com/cognion-nucleus/nodii-libs"
+Repository = "https://github.com/cognion-nucleus/nodii-libs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nodii_document_cloud_client"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.targets.sdist.force-include]
+"../../ts/grpc-interfaces/proto/nodii/document_cloud/v1/document_cloud.proto" = "src/nodii_document_cloud_client/proto/nodii/document_cloud/v1/document_cloud.proto"
+
+[dependency-groups]
+dev = [
+  "boto3>=1.35",
+  "mypy>=1.13",
+  "pytest>=8.3",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.7",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP", "N", "ASYNC", "S", "PT", "RET", "SIM"]
+ignore = ["S101"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "S105", "S106", "B017", "PT011"]
+"tests/test_integration.py" = ["N802"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+
+[[tool.mypy.overrides]]
+module = ["grpc", "grpc.*", "grpc_tools", "grpc_tools.*", "google.protobuf", "google.protobuf.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = ["-ra", "--strict-markers", "--strict-config"]

nodii_document_cloud_client-0.2.0/src/nodii_document_cloud_client/__init__.py

@@ -0,0 +1,45 @@
+from .client import (
+    DocumentCloudClient,
+    UploadResult,
+    create_document_cloud_client,
+    validate_contexts,
+)
+from .errors import (
+    ChecksumMismatchError,
+    ContextRefLooksLikePiiError,
+    DocumentCloudConflictError,
+    DocumentCloudError,
+    DocumentCloudInvalidArgumentError,
+    DocumentCloudNotFoundError,
+    DocumentCloudPermissionDeniedError,
+    DocumentCloudPreconditionError,
+    DocumentCloudUnauthenticatedError,
+    DocumentCloudUnavailableError,
+    S3UnavailableError,
+    SizeMismatchError,
+    UploadAbortedError,
+    UploadHttpError,
+    UploadTimeoutError,
+)
+
+__all__ = [
+    "ChecksumMismatchError",
+    "ContextRefLooksLikePiiError",
+    "DocumentCloudClient",
+    "DocumentCloudConflictError",
+    "DocumentCloudError",
+    "DocumentCloudInvalidArgumentError",
+    "DocumentCloudNotFoundError",
+    "DocumentCloudPermissionDeniedError",
+    "DocumentCloudPreconditionError",
+    "DocumentCloudUnauthenticatedError",
+    "DocumentCloudUnavailableError",
+    "S3UnavailableError",
+    "SizeMismatchError",
+    "UploadAbortedError",
+    "UploadHttpError",
+    "UploadResult",
+    "UploadTimeoutError",
+    "create_document_cloud_client",
+    "validate_contexts",
+]

nodii_document_cloud_client-0.2.0/src/nodii_document_cloud_client/body.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import tempfile
+from collections.abc import AsyncIterable, AsyncIterator, Iterable
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO, TypeAlias
+
+DocumentBody: TypeAlias = (
+    bytes | bytearray | memoryview | BinaryIO | Iterable[bytes] | AsyncIterable[bytes]
+)
+
+
+@dataclass(slots=True)
+class PreparedBody:
+    size_bytes: int
+    checksum_sha256: str
+    _bytes: bytes | None = None
+    _path: Path | None = None
+
+    def open(self) -> BinaryIO:
+        if self._path is not None:
+            return self._path.open("rb")
+        from io import BytesIO
+
+        return BytesIO(self._bytes or b"")
+
+    def cleanup(self) -> None:
+        if self._path is not None:
+            self._path.unlink(missing_ok=True)
+
+
+async def _chunks(body: DocumentBody) -> AsyncIterator[bytes]:
+    if isinstance(body, (bytes, bytearray, memoryview)):
+        yield bytes(body)
+    elif hasattr(body, "__aiter__"):
+        async for chunk in body:
+            yield bytes(chunk)
+    elif hasattr(body, "read"):
+        while chunk := await asyncio.to_thread(body.read, 1024 * 1024):
+            yield bytes(chunk)
+    else:
+        for chunk in body:
+            yield bytes(chunk)
+
+
+async def prepare_body(body: DocumentBody, declared_size: int | None = None) -> PreparedBody:
+    if isinstance(body, (bytes, bytearray, memoryview)):
+        data = bytes(body)
+        if declared_size is not None and declared_size != len(data):
+            raise ValueError(f"size_bytes {declared_size} does not match body size {len(data)}")
+        return PreparedBody(len(data), hashlib.sha256(data).hexdigest(), _bytes=data)
+    fd, name = tempfile.mkstemp(prefix="nodii-document-cloud-")
+    digest = hashlib.sha256()
+    size = 0
+    try:
+        with os.fdopen(fd, "wb") as target:
+            async for chunk in _chunks(body):
+                digest.update(chunk)
+                size += len(chunk)
+                target.write(chunk)
+        if declared_size is not None and declared_size != size:
+            raise ValueError(f"size_bytes {declared_size} does not match body size {size}")
+        return PreparedBody(size, digest.hexdigest(), _path=Path(name))
+    except BaseException:
+        with suppress(FileNotFoundError):
+            os.unlink(name)
+        raise