dimescheduler 0.1.2b0__tar.gz

dimescheduler-0.1.2b0/.gitignore

@@ -0,0 +1,78 @@
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Editor
+.vs/
+.idea/
+*.swp
+*.swo
+*.bak
+*.tmp
+*~
+
+# Secrets / env
+.env
+.env.local
+.env.*.local
+.env.development
+!.env.example
+!.env.sample
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# .NET
+**/bin/
+**/obj/
+TestResults/
+**/*.DotSettings.user
+**/*.user
+src/packages/
+*.suo
+*.userosscache
+*.sln.docstates
+
+# JavaScript / TypeScript
+**/node_modules/
+**/dist/
+*.tgz
+.yarn/cache
+.yarn/build-state.yml
+.yarn/install-state.gz
+.yarn/unplugged
+.pnp.*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg
+*.egg-info/
+.venv/
+venv/
+.env-py/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+
+# Mock server (regenerated on every run)
+scripts/.cache/
+
+# act — local secrets file (template lives at .secrets.example)
+.secrets
+
+# Coverage
+coverage/
+htmlcov/
+.coverage
+.coverage.*
+*.lcov
+lcov.info
+*.cover

dimescheduler-0.1.2b0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Dime Software
+
+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, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dimescheduler-0.1.2b0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: dimescheduler
+Version: 0.1.2b0
+Summary: The official Python SDK for Dime.Scheduler
+Project-URL: Homepage, https://docs.dimescheduler.com
+Project-URL: Repository, https://github.com/dime-scheduler/sdk
+Project-URL: Documentation, https://docs.dimescheduler.com/develop/api
+Author: Dime Software
+License-Expression: MIT
+License-File: LICENSE
+Keywords: business-central,dynamics-365,planning,power-apps,scheduling
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: openapi-python-client>=0.21; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Dime.Scheduler SDK for Python
+
+The official Python SDK for [Dime.Scheduler](https://docs.dimescheduler.com).
+
+> **Status:** alpha. The domain-grouped accessor surface is in place; typed entity models are landing.
+
+## Installation
+
+```bash
+pip install dimescheduler
+# or
+uv add dimescheduler
+```
+
+### Prereleases
+
+Alpha / beta / release-candidate builds (e.g. `0.1.1b0` for `0.1.1-beta.0`) ship as PyPI prereleases. To opt into them:
+
+```bash
+pip install --pre dimescheduler
+```
+
+## Quick start
+
+```python
+from dimescheduler import DimeSchedulerClient, Environment
+
+with DimeSchedulerClient(api_key="MY_API_KEY", environment=Environment.Sandbox) as client:
+    result = client.categories.create({
+        "name": "INSTALL",
+        "displayName": "Install",
+        "color": "#22d3ee",
+    })
+    if not result.ok:
+        raise RuntimeError(result.error)
+```
+
+By default the client targets `Environment.Production`. Switch to `Sandbox` or `Test` for non-prod.
+
+## API surface
+
+Every entity hangs off a typed accessor on the client. CRUD-shaped entities expose `create` / `update` / `delete` / `get_all`:
+
+```python
+client.categories.create(category)
+client.categories.update(category)
+client.categories.delete(category)
+result = client.categories.get_all()
+```
+
+Endpoints with required parameters expose them directly:
+
+```python
+client.appointments.get(start_date, end_date, resources=["R1", "R2"])
+client.notifications.get(page=1, limit=50, sort="createdAt:desc")
+client.geocoding.geocode_text("221B Baker Street", "GB")
+client.optimization.field_service(request)
+```
+
+Every method returns a `Result`:
+
+```python
+result = client.categories.get_all()
+result.ok                 # bool — convenience over response.is_success
+result.data               # parsed JSON body on success, else None
+result.error              # parsed JSON error body on 4xx/5xx, else None
+result.response           # underlying httpx.Response
+```
+
+The accessor names mirror the .NET and JS SDKs 1:1 (with idiomatic `snake_case`), so cross-language code reads the same.
+
+## Development
+
+This package is part of the [`dime-scheduler/sdk`](https://github.com/dime-scheduler/sdk) monorepo. From `packages/python/`:
+
+```bash
+uv sync --extra dev          # install runtime + dev deps
+uv run pytest                # run unit tests
+uv run ruff check             # lint
+./scripts/codegen.sh          # regenerate typed client from ../../spec/openapi.json
+```
+
+## License
+
+[MIT](../../LICENSE)

dimescheduler-0.1.2b0/README.md

@@ -0,0 +1,85 @@
+# Dime.Scheduler SDK for Python
+
+The official Python SDK for [Dime.Scheduler](https://docs.dimescheduler.com).
+
+> **Status:** alpha. The domain-grouped accessor surface is in place; typed entity models are landing.
+
+## Installation
+
+```bash
+pip install dimescheduler
+# or
+uv add dimescheduler
+```
+
+### Prereleases
+
+Alpha / beta / release-candidate builds (e.g. `0.1.1b0` for `0.1.1-beta.0`) ship as PyPI prereleases. To opt into them:
+
+```bash
+pip install --pre dimescheduler
+```
+
+## Quick start
+
+```python
+from dimescheduler import DimeSchedulerClient, Environment
+
+with DimeSchedulerClient(api_key="MY_API_KEY", environment=Environment.Sandbox) as client:
+    result = client.categories.create({
+        "name": "INSTALL",
+        "displayName": "Install",
+        "color": "#22d3ee",
+    })
+    if not result.ok:
+        raise RuntimeError(result.error)
+```
+
+By default the client targets `Environment.Production`. Switch to `Sandbox` or `Test` for non-prod.
+
+## API surface
+
+Every entity hangs off a typed accessor on the client. CRUD-shaped entities expose `create` / `update` / `delete` / `get_all`:
+
+```python
+client.categories.create(category)
+client.categories.update(category)
+client.categories.delete(category)
+result = client.categories.get_all()
+```
+
+Endpoints with required parameters expose them directly:
+
+```python
+client.appointments.get(start_date, end_date, resources=["R1", "R2"])
+client.notifications.get(page=1, limit=50, sort="createdAt:desc")
+client.geocoding.geocode_text("221B Baker Street", "GB")
+client.optimization.field_service(request)
+```
+
+Every method returns a `Result`:
+
+```python
+result = client.categories.get_all()
+result.ok                 # bool — convenience over response.is_success
+result.data               # parsed JSON body on success, else None
+result.error              # parsed JSON error body on 4xx/5xx, else None
+result.response           # underlying httpx.Response
+```
+
+The accessor names mirror the .NET and JS SDKs 1:1 (with idiomatic `snake_case`), so cross-language code reads the same.
+
+## Development
+
+This package is part of the [`dime-scheduler/sdk`](https://github.com/dime-scheduler/sdk) monorepo. From `packages/python/`:
+
+```bash
+uv sync --extra dev          # install runtime + dev deps
+uv run pytest                # run unit tests
+uv run ruff check             # lint
+./scripts/codegen.sh          # regenerate typed client from ../../spec/openapi.json
+```
+
+## License
+
+[MIT](../../LICENSE)

dimescheduler-0.1.2b0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dimescheduler"
+version = "0.1.2b0"
+description = "The official Python SDK for Dime.Scheduler"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Dime Software" }]
+keywords = ["scheduling", "planning", "business-central", "dynamics-365", "power-apps"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "openapi-python-client>=0.21",
+]
+
+[project.urls]
+Homepage = "https://docs.dimescheduler.com"
+Repository = "https://github.com/dime-scheduler/sdk"
+Documentation = "https://docs.dimescheduler.com/develop/api"
+
+[tool.hatch.build.targets.wheel.force-include]
+"src" = "dimescheduler"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/**",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

dimescheduler-0.1.2b0/src/__init__.py

@@ -0,0 +1,68 @@
+from dimescheduler._version import __version__
+from dimescheduler.api import (
+    AppointmentApi,
+    AppointmentDependencyApi,
+    AppointmentFieldApi,
+    CalendarApi,
+    ConnectorApi,
+    CrudApi,
+    GeocodeApi,
+    ImportApi,
+    MessageApi,
+    NotificationApi,
+    OptimizationApi,
+    RecommendationApi,
+    RecurringAppointmentApi,
+    ResourceCapacityApi,
+    ResourceTypeApi,
+    UserApi,
+)
+from dimescheduler.client import DimeSchedulerClient
+from dimescheduler.environment import Environment
+from dimescheduler.errors import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    DimeSchedulerError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from dimescheduler.result import Result
+from dimescheduler.retry import RetryConfig, RetryTransport
+
+__all__ = [
+    "AppointmentApi",
+    "AppointmentDependencyApi",
+    "AppointmentFieldApi",
+    "AuthenticationError",
+    "AuthorizationError",
+    "CalendarApi",
+    "ConflictError",
+    "ConnectorApi",
+    "CrudApi",
+    "DimeSchedulerClient",
+    "DimeSchedulerError",
+    "Environment",
+    "GeocodeApi",
+    "ImportApi",
+    "MessageApi",
+    "NetworkError",
+    "NotFoundError",
+    "NotificationApi",
+    "OptimizationApi",
+    "RateLimitError",
+    "RecommendationApi",
+    "RecurringAppointmentApi",
+    "ResourceCapacityApi",
+    "ResourceTypeApi",
+    "Result",
+    "RetryConfig",
+    "RetryTransport",
+    "ServerError",
+    "UserApi",
+    "ValidationError",
+    "__version__",
+]

dimescheduler-0.1.2b0/src/_version.py

@@ -0,0 +1,3 @@
+# Kept in sync with the [project] version field in pyproject.toml by the manual
+# release workflow (.github/workflows/release.yml). Do not edit by hand.
+__version__ = "0.1.2b0"

dimescheduler-0.1.2b0/src/api/__init__.py

@@ -0,0 +1,37 @@
+from dimescheduler.api.crud import CrudApi
+from dimescheduler.api.specialized import (
+    AppointmentApi,
+    AppointmentDependencyApi,
+    AppointmentFieldApi,
+    CalendarApi,
+    ConnectorApi,
+    GeocodeApi,
+    ImportApi,
+    MessageApi,
+    NotificationApi,
+    OptimizationApi,
+    RecommendationApi,
+    RecurringAppointmentApi,
+    ResourceCapacityApi,
+    ResourceTypeApi,
+    UserApi,
+)
+
+__all__ = [
+    "AppointmentApi",
+    "AppointmentDependencyApi",
+    "AppointmentFieldApi",
+    "CalendarApi",
+    "ConnectorApi",
+    "CrudApi",
+    "GeocodeApi",
+    "ImportApi",
+    "MessageApi",
+    "NotificationApi",
+    "OptimizationApi",
+    "RecommendationApi",
+    "RecurringAppointmentApi",
+    "ResourceCapacityApi",
+    "ResourceTypeApi",
+    "UserApi",
+]

dimescheduler-0.1.2b0/src/api/crud.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Union
+
+from dimescheduler.dispatcher import UNSET, Dispatcher, TimeoutT, timeout_kw
+from dimescheduler.result import Result
+
+Entity = Mapping[str, Any]
+EntityOrList = Union[Entity, Sequence[Entity]]
+
+
+class CrudApi:
+    """Generic CRUD client. Same call surface for every import-shaped entity.
+
+    Mirrors the .NET ``CrudApi<T>`` class: ``create`` / ``update`` / ``delete``
+    accept either a single entity (mapping) or a list of entities; ``get_all``
+    issues a GET against the same route with optional query parameters.
+
+    Every method accepts a kwarg-only ``timeout`` (the per-request cancellation
+    analog): a float in seconds, an ``httpx.Timeout``, or ``None`` to wait
+    indefinitely. Omit it to inherit the client-level timeout.
+    """
+
+    def __init__(self, dispatcher: Dispatcher, route: str) -> None:
+        self._dispatcher = dispatcher
+        self._route = route
+
+    def create(self, entity: EntityOrList, *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", self._route, body=entity, **timeout_kw(timeout))
+
+    def update(self, entity: EntityOrList, *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("PUT", self._route, body=entity, **timeout_kw(timeout))
+
+    def delete(self, entity: EntityOrList, *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("DELETE", self._route, body=entity, **timeout_kw(timeout))
+
+    def get_all(self, query: dict[str, Any] | None = None, *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("GET", self._route, params=query, **timeout_kw(timeout))

dimescheduler-0.1.2b0/src/api/specialized.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime
+from typing import Any
+
+from dimescheduler.api.crud import CrudApi
+from dimescheduler.dispatcher import UNSET, Dispatcher, TimeoutT, timeout_kw
+from dimescheduler.result import Result
+
+
+def _iso(value: datetime | str) -> str:
+    return value if isinstance(value, str) else value.isoformat()
+
+
+class AppointmentApi(CrudApi):
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        super().__init__(dispatcher, "/appointment")
+
+    def get(
+        self,
+        start_date: datetime | str,
+        end_date: datetime | str,
+        resources: list[str] | None = None,
+        *,
+        timeout: TimeoutT = UNSET,
+    ) -> Result:
+        return self._dispatcher.request(
+            "GET",
+            self._route,
+            params={"startDate": _iso(start_date), "endDate": _iso(end_date), "resources": resources},
+            **timeout_kw(timeout),
+        )
+
+
+class ResourceCapacityApi(CrudApi):
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        super().__init__(dispatcher, "/resourceCapacity")
+
+    def get(self, start: datetime | str, end: datetime | str, *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request(
+            "GET",
+            self._route,
+            params={"start": _iso(start), "end": _iso(end)},
+            **timeout_kw(timeout),
+        )
+
+
+class NotificationApi(CrudApi):
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        super().__init__(dispatcher, "/notification")
+
+    def get(
+        self,
+        page: int,
+        limit: int,
+        *,
+        sort: str | None = None,
+        group: str | None = None,
+        filter: str | None = None,
+        timeout: TimeoutT = UNSET,
+    ) -> Result:
+        return self._dispatcher.request(
+            "GET",
+            self._route,
+            params={"page": page, "limit": limit, "sort": sort, "group": group, "filter": filter},
+            **timeout_kw(timeout),
+        )
+
+
+class _ReadOnlyApi:
+    def __init__(self, dispatcher: Dispatcher, route: str) -> None:
+        self._dispatcher = dispatcher
+        self._route = route
+
+    def get_all(self, *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("GET", self._route, **timeout_kw(timeout))
+
+
+class AppointmentDependencyApi(_ReadOnlyApi):
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        super().__init__(dispatcher, "/appointmentDependency")
+
+
+class CalendarApi(_ReadOnlyApi):
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        super().__init__(dispatcher, "/calendar")
+
+
+class ResourceTypeApi(_ReadOnlyApi):
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        super().__init__(dispatcher, "/resourcetype")
+
+
+class AppointmentFieldApi(_ReadOnlyApi):
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        super().__init__(dispatcher, "/appointmentField")
+
+
+class GeocodeApi:
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        self._dispatcher = dispatcher
+
+    def geocode(self, address: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/geocode", body=address, **timeout_kw(timeout))
+
+    def geocode_text(self, address: str, country: str, *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request(
+            "GET", "/geocode", params={"address": address, "country": country}, **timeout_kw(timeout)
+        )
+
+
+class OptimizationApi:
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        self._dispatcher = dispatcher
+
+    def field_service(self, request: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/optimization/fieldService", body=request, **timeout_kw(timeout))
+
+    def professional_services(self, request: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request(
+            "POST", "/optimization/professionalServices", body=request, **timeout_kw(timeout)
+        )
+
+    def daily_route(self, request: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/optimization/dailyRoute", body=request, **timeout_kw(timeout))
+
+
+class RecommendationApi:
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        self._dispatcher = dispatcher
+
+    def get(self, request: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/recommendation", body=request, **timeout_kw(timeout))
+
+    def scorers(self, *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("GET", "/recommendation/scorers", **timeout_kw(timeout))
+
+
+class MessageApi:
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        self._dispatcher = dispatcher
+
+    def send(self, message: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/message", body=message, **timeout_kw(timeout))
+
+
+class ConnectorApi:
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        self._dispatcher = dispatcher
+
+    def create(self, request: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/connector", body=request, **timeout_kw(timeout))
+
+
+class UserApi:
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        self._dispatcher = dispatcher
+
+    def create(self, user: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/user", body=user, **timeout_kw(timeout))
+
+
+class RecurringAppointmentApi:
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        self._dispatcher = dispatcher
+
+    def create(self, request: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/appointmentRecurring", body=request, **timeout_kw(timeout))
+
+    def delete(self, request: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("DELETE", "/appointmentRecurring", body=request, **timeout_kw(timeout))
+
+
+class ImportApi:
+    def __init__(self, dispatcher: Dispatcher) -> None:
+        self._dispatcher = dispatcher
+
+    def run(self, payload: Mapping[str, Any] | list[Mapping[str, Any]], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/import", body=payload, **timeout_kw(timeout))
+
+    def setup(self, payload: Mapping[str, Any], *, timeout: TimeoutT = UNSET) -> Result:
+        return self._dispatcher.request("POST", "/import/setup", body=payload, **timeout_kw(timeout))

dimescheduler-0.1.2b0/src/client.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import httpx
+from dimescheduler._version import __version__
+from dimescheduler.api.crud import CrudApi
+from dimescheduler.api.specialized import (
+    AppointmentApi,
+    AppointmentDependencyApi,
+    AppointmentFieldApi,
+    CalendarApi,
+    ConnectorApi,
+    GeocodeApi,
+    ImportApi,
+    MessageApi,
+    NotificationApi,
+    OptimizationApi,
+    RecommendationApi,
+    RecurringAppointmentApi,
+    ResourceCapacityApi,
+    ResourceTypeApi,
+    UserApi,
+)
+from dimescheduler.dispatcher import Dispatcher
+from dimescheduler.environment import Environment
+from dimescheduler.retry import RetryConfig, RetryTransport
+
+USER_AGENT = f"dimescheduler-python/{__version__}"
+
+
+class DimeSchedulerClient:
+    """Domain-grouped client for the Dime.Scheduler HTTP API.
+
+    Every entity hangs off a typed accessor (``client.categories``,
+    ``client.appointments``, ``client.resources``, …) — the surface mirrors the
+    .NET and JS SDKs 1:1 so cross-language code reads the same. CRUD-shaped
+    entities expose ``create`` / ``update`` / ``delete`` / ``get_all``;
+    specialized endpoints get purpose-built methods.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        environment: Environment = Environment.Production,
+        *,
+        timeout: float = 30.0,
+        headers: dict[str, str] | None = None,
+        retry: RetryConfig | None | Literal[False] = None,
+        transport: httpx.BaseTransport | None = None,
+        **httpx_kwargs: Any,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        merged_headers: dict[str, str] = {
+            "X-API-KEY": api_key,
+            "User-Agent": USER_AGENT,
+        }
+        if headers:
+            # Caller-supplied headers win, including a custom User-Agent.
+            merged_headers.update(headers)
+
+        effective_transport = (
+            transport if retry is False else RetryTransport(config=retry, inner=transport)
+        )
+
+        self._http = httpx.Client(
+            base_url=environment.value,
+            headers=merged_headers,
+            timeout=timeout,
+            transport=effective_transport,
+            **httpx_kwargs,
+        )
+        self._environment = environment
+        d = Dispatcher(self._http)
+
+        self.action_uris = CrudApi(d, "/actionUri")
+        self.appointment_categories = CrudApi(d, "/appointmentCategory")
+        self.appointment_contents = CrudApi(d, "/appointmentcontent")
+        self.appointment_containers = CrudApi(d, "/appointmentContainer")
+        self.appointment_field_values = CrudApi(d, "/appointmentFieldValue")
+        self.appointment_importances = CrudApi(d, "/appointmentImportance")
+        self.appointment_locked = CrudApi(d, "/appointmentLocked")
+        self.appointment_planning_quantities = CrudApi(d, "/appointmentPlanningQuantity")
+        self.appointment_time_markers = CrudApi(d, "/appointmentTimeMarker")
+        self.appointment_uris = CrudApi(d, "/appointmentUri")
+        self.assignments = CrudApi(d, "/assignment")
+        self.captions = CrudApi(d, "/caption")
+        self.categories = CrudApi(d, "/category")
+        self.containers = CrudApi(d, "/container")
+        self.filter_groups = CrudApi(d, "/filterGroup")
+        self.filter_values = CrudApi(d, "/filterValue")
+        self.jobs = CrudApi(d, "/job")
+        self.pins = CrudApi(d, "/pin")
+        self.resources = CrudApi(d, "/resource")
+        self.resource_calendars = CrudApi(d, "/resourceCalendar")
+        self.resource_certificates = CrudApi(d, "/resourceCertificate")
+        self.resource_filter_values = CrudApi(d, "/resourceFilterValue")
+        self.resource_gps_trackings = CrudApi(d, "/resourceGpsTracking")
+        self.resource_uris = CrudApi(d, "/resourceUri")
+        self.tasks = CrudApi(d, "/task")
+        self.task_containers = CrudApi(d, "/taskContainer")
+        self.task_filter_values = CrudApi(d, "/taskFilterValue")
+        self.task_locked = CrudApi(d, "/taskLocked")
+        self.task_uris = CrudApi(d, "/taskUri")
+        self.time_markers = CrudApi(d, "/timeMarker")
+
+        self.appointments = AppointmentApi(d)
+        self.appointment_dependencies = AppointmentDependencyApi(d)
+        self.appointment_fields = AppointmentFieldApi(d)
+        self.notifications = NotificationApi(d)
+        self.resource_capacities = ResourceCapacityApi(d)
+        self.resource_types = ResourceTypeApi(d)
+        self.calendars = CalendarApi(d)
+
+        self.connectors = ConnectorApi(d)
+        self.geocoding = GeocodeApi(d)
+        self.imports = ImportApi(d)
+        self.messages = MessageApi(d)
+        self.optimization = OptimizationApi(d)
+        self.recommendation = RecommendationApi(d)
+        self.recurring_appointments = RecurringAppointmentApi(d)
+        self.users = UserApi(d)
+
+    @property
+    def base_url(self) -> str:
+        return str(self._http.base_url).rstrip("/")
+
+    @property
+    def environment(self) -> Environment:
+        return self._environment
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> DimeSchedulerClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

dimescheduler-0.1.2b0/src/dispatcher.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import Any, Union
+
+import httpx
+from dimescheduler.result import Result
+
+# Sentinel: distinguishes "caller didn't pass a timeout" (inherit the
+# client-level value) from "caller explicitly passed None" (wait indefinitely).
+# Exported so the API accessors can share it instead of defining their own.
+UNSET: Any = object()
+TimeoutT = Union[float, httpx.Timeout, None]
+
+
+def timeout_kw(value: Any) -> dict[str, Any]:
+    """Build a kwargs dict that forwards ``timeout`` only when the caller set it."""
+    return {} if value is UNSET else {"timeout": value}
+
+
+class Dispatcher:
+    """Internal HTTP dispatcher used by every domain accessor.
+
+    Wraps an ``httpx.Client`` and converts each call into a :class:`Result`.
+    Never raises on non-2xx status — the caller inspects ``result.error`` or
+    ``result.response.status_code`` and decides how to react.
+    """
+
+    def __init__(self, http: httpx.Client) -> None:
+        self._http = http
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        params: dict[str, Any] | None = None,
+        timeout: Any = UNSET,
+    ) -> Result:
+        kwargs: dict[str, Any] = {}
+        if body is not None:
+            kwargs["json"] = body
+        if params is not None:
+            kwargs["params"] = _drop_none(params)
+        if timeout is not UNSET:
+            kwargs["timeout"] = timeout
+
+        response = self._http.request(method, path, **kwargs)
+        payload = _parse_json(response)
+
+        if response.is_success:
+            return Result(data=payload, error=None, response=response)
+        return Result(data=None, error=payload, response=response)
+
+
+def _parse_json(response: httpx.Response) -> Any:
+    if not response.content:
+        return None
+    content_type = response.headers.get("content-type", "")
+    if "json" not in content_type:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+def _drop_none(params: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None}

dimescheduler-0.1.2b0/src/environment.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class Environment(str, Enum):
+    Test = "https://test.api.dimescheduler.com"
+    Sandbox = "https://sandbox.api.dimescheduler.com"
+    Production = "https://api.dimescheduler.com"

dimescheduler-0.1.2b0/src/errors.py

@@ -0,0 +1,155 @@
+"""Typed exception hierarchy for Dime.Scheduler API failures.
+
+The dispatcher does not raise these on its own — it surfaces failures via
+:class:`~dimescheduler.result.Result`. Call :meth:`Result.raise_for_error` to
+opt into idiomatic Python exception handling.
+"""
+
+from __future__ import annotations
+
+import email.utils
+from datetime import datetime, timezone
+from typing import Any
+
+import httpx
+
+
+class DimeSchedulerError(Exception):
+    """Base class for every typed error raised by the SDK.
+
+    Pattern-match on the concrete subclass (:class:`RateLimitError`,
+    :class:`NotFoundError`, …) to react to specific failure categories instead
+    of inspecting status codes.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        body: Any = None,
+        response: httpx.Response | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.response = response
+
+
+class ValidationError(DimeSchedulerError):
+    """400 / 422 — request body or query params failed server-side validation."""
+
+
+class AuthenticationError(DimeSchedulerError):
+    """401 — credentials are missing, malformed, or revoked."""
+
+
+class AuthorizationError(DimeSchedulerError):
+    """403 — credentials are valid but lack permission for the resource."""
+
+
+class NotFoundError(DimeSchedulerError):
+    """404 — the requested resource does not exist."""
+
+
+class ConflictError(DimeSchedulerError):
+    """409 — the request conflicts with the current state of the resource."""
+
+
+class RateLimitError(DimeSchedulerError):
+    """429 — rate limit exceeded.
+
+    ``retry_after`` mirrors the server's ``Retry-After`` header (in seconds)
+    when one was sent. Sleeping for that long before retrying is the
+    documented recovery path.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        body: Any = None,
+        response: httpx.Response | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, body=body, response=response)
+        self.retry_after = retry_after
+
+
+class ServerError(DimeSchedulerError):
+    """5xx — server-side failure."""
+
+
+class NetworkError(DimeSchedulerError):
+    """Transport-level failure (DNS, TCP, TLS, timeout, etc.). No HTTP response was received."""
+
+    def __init__(self, message: str, *, cause: BaseException | None = None) -> None:
+        super().__init__(message, status_code=0, body=None, response=None)
+        self.__cause__ = cause
+
+
+def classify(response: httpx.Response, body: Any = None) -> DimeSchedulerError:
+    """Build the most specific :class:`DimeSchedulerError` for ``response``.
+
+    ``body`` is the parsed JSON payload (when present) — passed in by the
+    dispatcher so we don't double-parse.
+    """
+
+    status = response.status_code
+    message = _message_from(body, default=f"HTTP {status}")
+
+    if status in (400, 422):
+        return ValidationError(message, status_code=status, body=body, response=response)
+    if status == 401:
+        return AuthenticationError(message, status_code=status, body=body, response=response)
+    if status == 403:
+        return AuthorizationError(message, status_code=status, body=body, response=response)
+    if status == 404:
+        return NotFoundError(message, status_code=status, body=body, response=response)
+    if status == 409:
+        return ConflictError(message, status_code=status, body=body, response=response)
+    if status == 429:
+        return RateLimitError(
+            message,
+            status_code=status,
+            body=body,
+            response=response,
+            retry_after=parse_retry_after(response.headers.get("retry-after")),
+        )
+    if 500 <= status < 600:
+        return ServerError(message, status_code=status, body=body, response=response)
+    return DimeSchedulerError(message, status_code=status, body=body, response=response)
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    """Parse a ``Retry-After`` header value (seconds or HTTP-date) into seconds."""
+
+    if not value:
+        return None
+    value = value.strip()
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        target = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if target is None:
+        return None
+    if target.tzinfo is None:
+        target = target.replace(tzinfo=timezone.utc)
+    delta = (target - datetime.now(timezone.utc)).total_seconds()
+    return max(0.0, delta)
+
+
+def _message_from(body: Any, *, default: str) -> str:
+    if isinstance(body, dict):
+        for key in ("message", "error", "detail", "title"):
+            value = body.get(key)
+            if isinstance(value, str) and value:
+                return value
+    if isinstance(body, str) and body:
+        return body
+    return default

dimescheduler-0.1.2b0/src/result.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from dimescheduler.errors import DimeSchedulerError, classify
+
+
+@dataclass(frozen=True)
+class Result:
+    """Outcome of a Dime.Scheduler API call.
+
+    Mirrors the openapi-fetch ``{ data, error, response }`` shape used by the
+    JS SDK and the ``Result<T>`` type used by the .NET SDK. ``data`` holds the
+    parsed JSON body on success, ``error`` holds the parsed JSON error body on
+    a 4xx/5xx, and ``response`` is the underlying ``httpx.Response`` for cases
+    where you need headers, status code, or the raw bytes.
+
+    Use :meth:`raise_for_error` if you'd rather opt into typed exceptions than
+    branch on :attr:`ok`.
+    """
+
+    data: Any
+    error: Any
+    response: httpx.Response
+
+    @property
+    def ok(self) -> bool:
+        return self.response.is_success
+
+    def raise_for_error(self) -> None:
+        """Raise a typed :class:`DimeSchedulerError` if the call failed.
+
+        Mirrors :meth:`httpx.Response.raise_for_status` but yields the right
+        :class:`~dimescheduler.errors.DimeSchedulerError` subclass
+        (:class:`~dimescheduler.errors.RateLimitError`,
+        :class:`~dimescheduler.errors.NotFoundError`, …) so callers can write
+        ``except RateLimitError`` instead of inspecting status codes.
+        """
+
+        if self.ok:
+            return
+        raise classify(self.response, self.error)
+
+    def to_error(self) -> DimeSchedulerError | None:
+        """Return the typed error for a failed call, or ``None`` on success.
+
+        Useful when you want to inspect / branch on the error category without
+        actually raising it.
+        """
+
+        if self.ok:
+            return None
+        return classify(self.response, self.error)

dimescheduler-0.1.2b0/src/retry.py

@@ -0,0 +1,149 @@
+"""Retry policy shared by every Dime.Scheduler request.
+
+The wrapped transport retries idempotent transport-level failures and a small
+set of "the server is having a bad time" status codes. Defaults match the JS
+and .NET SDKs so behaviour is identical regardless of runtime.
+"""
+
+from __future__ import annotations
+
+import email.utils
+import random
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable
+
+import httpx
+
+# Status codes that trigger a retry by default.
+DEFAULT_RETRY_STATUS_CODES: tuple[int, ...] = (408, 429, 500, 502, 503, 504)
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Retry policy.
+
+    Set ``max_retries=0`` to effectively disable retrying without removing the
+    transport wrapper.
+    """
+
+    max_retries: int = 3
+    initial_delay_s: float = 0.5
+    max_delay_s: float = 30.0
+    backoff_multiplier: float = 2.0
+    retry_status_codes: tuple[int, ...] = field(default_factory=lambda: DEFAULT_RETRY_STATUS_CODES)
+    respect_retry_after: bool = True
+
+
+class RetryTransport(httpx.BaseTransport):
+    """httpx transport that wraps an inner transport with retry behaviour.
+
+    Retries on:
+      - ``ConnectError``, ``ReadError``, ``WriteError``, ``ConnectTimeout``,
+        ``ReadTimeout``, ``WriteTimeout``, ``PoolTimeout`` (transient I/O).
+      - HTTP responses with status codes in ``config.retry_status_codes``.
+
+    Honours ``Retry-After`` (delta-seconds or HTTP-date) on retryable responses
+    when ``config.respect_retry_after`` is true. The ``Retry-After`` value is
+    capped by ``config.max_delay_s``.
+
+    Backoff is "full jitter": ``random() * min(initial * multiplier**n, cap)``.
+    """
+
+    _RETRYABLE_EXCEPTIONS: tuple[type[BaseException], ...] = (
+        httpx.ConnectError,
+        httpx.ReadError,
+        httpx.WriteError,
+        httpx.ConnectTimeout,
+        httpx.ReadTimeout,
+        httpx.WriteTimeout,
+        httpx.PoolTimeout,
+    )
+
+    def __init__(
+        self,
+        config: RetryConfig | None = None,
+        inner: httpx.BaseTransport | None = None,
+        *,
+        sleep: Callable[[float], None] = time.sleep,
+        rng: Callable[[], float] = random.random,
+        now: Callable[[], datetime] = lambda: datetime.now(timezone.utc),
+    ) -> None:
+        self._config = config or RetryConfig()
+        self._inner = inner or httpx.HTTPTransport()
+        self._sleep = sleep
+        self._rng = rng
+        self._now = now
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        cfg = self._config
+        last_exc: BaseException | None = None
+        last_response: httpx.Response | None = None
+
+        for attempt in range(cfg.max_retries + 1):
+            try:
+                response = self._inner.handle_request(request)
+            except self._RETRYABLE_EXCEPTIONS as exc:
+                last_exc = exc
+                if attempt == cfg.max_retries:
+                    raise
+                self._sleep(self._compute_backoff(attempt))
+                continue
+
+            if attempt == cfg.max_retries or response.status_code not in cfg.retry_status_codes:
+                return response
+
+            # Drain so the connection can be reused.
+            response.read()
+            response.close()
+            last_response = response
+
+            delay = self._delay_for(response, attempt)
+            self._sleep(delay)
+
+        # Loop body always returns or raises on the final attempt, so this is
+        # unreachable. Belt-and-braces guard for static analysers.
+        if last_response is not None:
+            return last_response
+        if last_exc is not None:
+            raise last_exc
+        raise RuntimeError("retry loop exited without a result")
+
+    def close(self) -> None:
+        self._inner.close()
+
+    def _delay_for(self, response: httpx.Response, attempt: int) -> float:
+        if self._config.respect_retry_after:
+            ra = response.headers.get("retry-after")
+            parsed = self._parse_retry_after(ra) if ra else None
+            if parsed is not None:
+                return min(parsed, self._config.max_delay_s)
+        return self._compute_backoff(attempt)
+
+    def _compute_backoff(self, attempt: int) -> float:
+        cfg = self._config
+        exponential = cfg.initial_delay_s * (cfg.backoff_multiplier ** attempt)
+        capped = min(exponential, cfg.max_delay_s)
+        # Full jitter — random in [0, capped].
+        return self._rng() * capped
+
+    def _parse_retry_after(self, value: str) -> float | None:
+        value = value.strip()
+        if not value:
+            return None
+        try:
+            seconds = float(value)
+            return max(0.0, seconds)
+        except ValueError:
+            pass
+        try:
+            target = email.utils.parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+        if target is None:
+            return None
+        if target.tzinfo is None:
+            target = target.replace(tzinfo=timezone.utc)
+        delta = (target - self._now()).total_seconds()
+        return max(0.0, delta)