plansom-sdk 0.0.1__tar.gz

plansom_sdk-0.0.1/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

plansom_sdk-0.0.1/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: plansom-sdk
+Version: 0.0.1
+Summary: Python client SDK for Plansom's be3 v3 API.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Plansom/plansom-sdk/tree/main/python
+Project-URL: Repository, https://github.com/Plansom/plansom-sdk
+Project-URL: Issues, https://github.com/Plansom/plansom-sdk/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.11.2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.15.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: respx>=0.21.0; extra == "dev"
+Requires-Dist: PyYAML>=6.0.1; extra == "dev"
+Dynamic: license-file
+
+# Plansom SDK — Python
+
+Python client for Plansom's `be3` v3 API. Ships both a sync and an async client from one package.
+Every request-building, response-parsing, and transport function is written directly against
+[`openapi/v3.yaml`](https://github.com/Plansom/plansom-sdk/blob/main/openapi/v3.yaml).
+
+> **Status: OAuth is live, API Key is still pending.** `OAuthTokenAuth` does the authorization-code
+> exchange and transparent refresh for real. API Key issuance hasn't shipped on be3 yet, so
+> `APIKeyAuth` still raises `NotImplementedError`. See
+> [`plansom_sdk/auth.py`](https://github.com/Plansom/plansom-sdk/blob/main/python/plansom_sdk/auth.py).
+
+## Layout
+
+```
+plansom_sdk/
+  client.py, async_client.py   the public Plansom / PlansomAsync classes
+  auth.py                       API Key (PENDING) / OAuth (live) strategies, see file docstring
+  exceptions.py                  typed exception hierarchy
+  models.py                       pydantic response models
+  pagination.py                    page-iteration helper for list endpoints (sync + async)
+  _version.py                       single source of truth for __version__ (also used for the User-Agent header)
+  py.typed                           PEP 561 marker — this package's type hints are checked, not decorative
+  transport/
+    http.py                         SyncTransport / AsyncTransport — request building, retry, error translation
+    retry.py                         retry configuration
+  resources/
+    goals.py, tasks.py, users.py, teams.py, organizations.py, search.py
+                                       one resource class (+ async twin) per file, 34 operations
+tests/
+```
+
+`transport/` groups the two files responsible for actually talking HTTP; `resources/` groups the
+six per-resource method sets. Everything else (`client.py`, `auth.py`, `exceptions.py`,
+`models.py`, `pagination.py`) is a single cross-cutting concern used by both the sync and async
+client, so it stays at the package root rather than nested.
+
+## Resource scope (v1)
+
+Read-only: `goals`, `tasks`, `users`, `teams`, `organizations`, `search` — list / retrieve / search only.
+Write operations and AI Plan integration are deferred to a later phase. 34 operations are implemented
+as SDK methods, each with its response model fields and path/query parameters read directly from
+[`openapi/v3.yaml`](https://github.com/Plansom/plansom-sdk/blob/main/openapi/v3.yaml).
+
+## Usage
+
+OAuth (live today — third-party app acting on behalf of its own end-user):
+
+```python
+from plansom_sdk import Plansom
+from plansom_sdk.auth import OAuthTokenAuth
+
+# Right after your redirect handler receives `?code=...`:
+auth = OAuthTokenAuth.from_authorization_code(
+    code=request.GET["code"],
+    client_id="...",
+    client_secret="...",
+    redirect_uri="https://myapp.example/oauth/callback",
+)
+client = Plansom(auth=auth)
+page = client.goals.list(organization=org_id)  # refreshes transparently once the token nears expiry
+
+# async
+from plansom_sdk import PlansomAsync
+client = PlansomAsync(auth=auth)
+page = await client.goals.list(organization=org_id)
+```
+
+`OAuthTokenAuth` only reaches the `read:goals_tasks`-scoped `goals`/`tasks` endpoints — be3 doesn't
+authenticate OAuth tokens anywhere else (see "OAuth" below). Restoring a token you already have and
+holding a refresh token without going through the exchange are both supported too — see
+[`plansom_sdk/auth.py`](https://github.com/Plansom/plansom-sdk/blob/main/python/plansom_sdk/auth.py)'s docstring for both shapes.
+
+API Key (once be3 ships issuance):
+
+```python
+from plansom_sdk.auth import APIKeyAuth
+
+client = Plansom(auth=APIKeyAuth(api_key="pk_live_..."))
+page = client.goals.list()
+```
+
+## Design notes worth knowing before extending this
+
+- **List-endpoint filters**: be3's list endpoints each expose ~15-18 near-identical DRF filter
+  query params. Rather than naming all of them on every method, the common ones (`page`,
+  `page_size`, `search`, `ordering`) are explicit and typed; the rest pass through a loose
+  `**filters` kwarg straight into the query string. See `resources/goals.py`'s module docstring for
+  the tradeoff (no autocomplete/typo-catching on the long tail of filter names).
+- **String IDs and timestamps**: UUID and datetime fields stay as `str` rather than being parsed
+  into `uuid.UUID`/`datetime` objects, to keep every model a flat, direct field list. See
+  `models.py`'s module docstring.
+- **One generic `Paginated[T]`**: instead of a distinct wrapper class per list response, `models.Paginated`
+  is one pydantic generic model parameterized by item type — `Paginated[Goal].model_validate(data)`.
+  Some sub-list endpoints (shared-members, shared-teams, attachments, acceptance-tests) don't
+  paginate at all and return plain `List[Model]` instead — see the relevant resource file.
+- **Every model field is `Optional` except `id`**: regardless of what the schema marks "required."
+  A DRF read serializer's "required" is a weaker guarantee than it looks — see `goal_type`'s write-
+  side validation gap below — so parsing must not hard-fail on a missing key. `id` is the one
+  exception, since it's about as close to guaranteed-present as any field gets. Stated once in
+  `models.py`'s module docstring rather than justified per field.
+- **`goal_type`/`task_type` are plain `str`, not `Literal`** — verified directly against be3 source:
+  `task_type`'s write-side serializer uses a bare `CharField`, not a `ChoiceField`, so arbitrary
+  strings can be written today with zero validation. A strict `Literal` would make a real, reachable
+  API response fail to parse. The right fix is on the backend, not papered over here — but the SDK
+  stays lenient regardless, since even a backend fix wouldn't retroactively clean up existing data.
+- **OAuth**: OAuth-authenticated requests are served by the same `/api/v3/goals/` and
+  `/api/v3/tasks/` endpoints as any other authenticated caller, gated by a `read:goals_tasks` scope
+  check — there's no OAuth-only endpoint surface. That's why `Goals`/`Tasks` need no OAuth-specific
+  routing: an `OAuthTokenAuth`-authenticated client calls the same resource methods as an
+  `APIKeyAuth`-authenticated one. `client.users`/`teams`/`organizations`/`search` aren't reachable
+  under OAuth auth (be3 doesn't authenticate OAuth tokens on those endpoints) — not guarded against
+  client-side, since letting be3's own error surface is simpler than duplicating that policy here
+  and risking drift; the resulting `401` surfaces as `PlansomAuthError`, same as any other auth
+  failure.
+
+  `AuthStrategy` exposes both `get_token()` (sync) and `async_get_token()` (defaults to the sync
+  path — correct for anything with no I/O). `OAuthTokenAuth` overrides both independently (sync
+  `httpx.Client` / async `httpx.AsyncClient`) so the async client's refresh never blocks the event
+  loop with a sync HTTP call — see `transport/http.py`'s `AsyncTransport.get`, which `await`s the
+  token callable. Refresh is proactive — checked and done inside `get_token`/`async_get_token`, 60s
+  before `expires_at` — rather than reactive-on-401, so `transport/http.py` stays completely
+  unaware refresh exists at all.
+
+## Reliability and typing
+
+- Every request has a bounded timeout (`DEFAULT_TIMEOUT_SECONDS = 30.0` in `transport/http.py`)
+  unless a caller passes `timeout_ms` explicitly.
+- The retry loop (exponential backoff, `transport/retry.py`) covers both retryable HTTP status
+  codes and transport-level failures (timeouts, connection resets, DNS) with the same attempt
+  budget — the latter surface as `PlansomConnectionError`, never a raw `httpx` exception, so callers
+  only ever need to catch this package's own exception hierarchy.
+- PEP 561 typed (`py.typed` ships in the built package) and `mypy`-clean.
+- `pagination.paginate`/`async_paginate` walk every page of a list endpoint for both clients.
+- Every request sends `User-Agent: plansom-sdk-python/<version>` (`_version.py`).
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+Covers client construction and auth behavior (`test_client.py`/`test_async_client.py`), the OAuth
+exchange/refresh flow respx-mocked against `/o/token/` (`test_auth.py`), sync/async pagination
+(`test_pagination.py`), pydantic model parsing (`test_models.py`), the HTTP transport layer —
+successful requests, error-status mapping, retries, connection failures — respx-mocked without a
+real network call (`test_transport.py`), and that every field a resource method's return type
+relies on still exists in `openapi/v3.yaml`'s current schema (`test_schema_conformance.py`).
+
+```
+mypy plansom_sdk/
+```

plansom_sdk-0.0.1/README.md

@@ -0,0 +1,152 @@
+# Plansom SDK — Python
+
+Python client for Plansom's `be3` v3 API. Ships both a sync and an async client from one package.
+Every request-building, response-parsing, and transport function is written directly against
+[`openapi/v3.yaml`](https://github.com/Plansom/plansom-sdk/blob/main/openapi/v3.yaml).
+
+> **Status: OAuth is live, API Key is still pending.** `OAuthTokenAuth` does the authorization-code
+> exchange and transparent refresh for real. API Key issuance hasn't shipped on be3 yet, so
+> `APIKeyAuth` still raises `NotImplementedError`. See
+> [`plansom_sdk/auth.py`](https://github.com/Plansom/plansom-sdk/blob/main/python/plansom_sdk/auth.py).
+
+## Layout
+
+```
+plansom_sdk/
+  client.py, async_client.py   the public Plansom / PlansomAsync classes
+  auth.py                       API Key (PENDING) / OAuth (live) strategies, see file docstring
+  exceptions.py                  typed exception hierarchy
+  models.py                       pydantic response models
+  pagination.py                    page-iteration helper for list endpoints (sync + async)
+  _version.py                       single source of truth for __version__ (also used for the User-Agent header)
+  py.typed                           PEP 561 marker — this package's type hints are checked, not decorative
+  transport/
+    http.py                         SyncTransport / AsyncTransport — request building, retry, error translation
+    retry.py                         retry configuration
+  resources/
+    goals.py, tasks.py, users.py, teams.py, organizations.py, search.py
+                                       one resource class (+ async twin) per file, 34 operations
+tests/
+```
+
+`transport/` groups the two files responsible for actually talking HTTP; `resources/` groups the
+six per-resource method sets. Everything else (`client.py`, `auth.py`, `exceptions.py`,
+`models.py`, `pagination.py`) is a single cross-cutting concern used by both the sync and async
+client, so it stays at the package root rather than nested.
+
+## Resource scope (v1)
+
+Read-only: `goals`, `tasks`, `users`, `teams`, `organizations`, `search` — list / retrieve / search only.
+Write operations and AI Plan integration are deferred to a later phase. 34 operations are implemented
+as SDK methods, each with its response model fields and path/query parameters read directly from
+[`openapi/v3.yaml`](https://github.com/Plansom/plansom-sdk/blob/main/openapi/v3.yaml).
+
+## Usage
+
+OAuth (live today — third-party app acting on behalf of its own end-user):
+
+```python
+from plansom_sdk import Plansom
+from plansom_sdk.auth import OAuthTokenAuth
+
+# Right after your redirect handler receives `?code=...`:
+auth = OAuthTokenAuth.from_authorization_code(
+    code=request.GET["code"],
+    client_id="...",
+    client_secret="...",
+    redirect_uri="https://myapp.example/oauth/callback",
+)
+client = Plansom(auth=auth)
+page = client.goals.list(organization=org_id)  # refreshes transparently once the token nears expiry
+
+# async
+from plansom_sdk import PlansomAsync
+client = PlansomAsync(auth=auth)
+page = await client.goals.list(organization=org_id)
+```
+
+`OAuthTokenAuth` only reaches the `read:goals_tasks`-scoped `goals`/`tasks` endpoints — be3 doesn't
+authenticate OAuth tokens anywhere else (see "OAuth" below). Restoring a token you already have and
+holding a refresh token without going through the exchange are both supported too — see
+[`plansom_sdk/auth.py`](https://github.com/Plansom/plansom-sdk/blob/main/python/plansom_sdk/auth.py)'s docstring for both shapes.
+
+API Key (once be3 ships issuance):
+
+```python
+from plansom_sdk.auth import APIKeyAuth
+
+client = Plansom(auth=APIKeyAuth(api_key="pk_live_..."))
+page = client.goals.list()
+```
+
+## Design notes worth knowing before extending this
+
+- **List-endpoint filters**: be3's list endpoints each expose ~15-18 near-identical DRF filter
+  query params. Rather than naming all of them on every method, the common ones (`page`,
+  `page_size`, `search`, `ordering`) are explicit and typed; the rest pass through a loose
+  `**filters` kwarg straight into the query string. See `resources/goals.py`'s module docstring for
+  the tradeoff (no autocomplete/typo-catching on the long tail of filter names).
+- **String IDs and timestamps**: UUID and datetime fields stay as `str` rather than being parsed
+  into `uuid.UUID`/`datetime` objects, to keep every model a flat, direct field list. See
+  `models.py`'s module docstring.
+- **One generic `Paginated[T]`**: instead of a distinct wrapper class per list response, `models.Paginated`
+  is one pydantic generic model parameterized by item type — `Paginated[Goal].model_validate(data)`.
+  Some sub-list endpoints (shared-members, shared-teams, attachments, acceptance-tests) don't
+  paginate at all and return plain `List[Model]` instead — see the relevant resource file.
+- **Every model field is `Optional` except `id`**: regardless of what the schema marks "required."
+  A DRF read serializer's "required" is a weaker guarantee than it looks — see `goal_type`'s write-
+  side validation gap below — so parsing must not hard-fail on a missing key. `id` is the one
+  exception, since it's about as close to guaranteed-present as any field gets. Stated once in
+  `models.py`'s module docstring rather than justified per field.
+- **`goal_type`/`task_type` are plain `str`, not `Literal`** — verified directly against be3 source:
+  `task_type`'s write-side serializer uses a bare `CharField`, not a `ChoiceField`, so arbitrary
+  strings can be written today with zero validation. A strict `Literal` would make a real, reachable
+  API response fail to parse. The right fix is on the backend, not papered over here — but the SDK
+  stays lenient regardless, since even a backend fix wouldn't retroactively clean up existing data.
+- **OAuth**: OAuth-authenticated requests are served by the same `/api/v3/goals/` and
+  `/api/v3/tasks/` endpoints as any other authenticated caller, gated by a `read:goals_tasks` scope
+  check — there's no OAuth-only endpoint surface. That's why `Goals`/`Tasks` need no OAuth-specific
+  routing: an `OAuthTokenAuth`-authenticated client calls the same resource methods as an
+  `APIKeyAuth`-authenticated one. `client.users`/`teams`/`organizations`/`search` aren't reachable
+  under OAuth auth (be3 doesn't authenticate OAuth tokens on those endpoints) — not guarded against
+  client-side, since letting be3's own error surface is simpler than duplicating that policy here
+  and risking drift; the resulting `401` surfaces as `PlansomAuthError`, same as any other auth
+  failure.
+
+  `AuthStrategy` exposes both `get_token()` (sync) and `async_get_token()` (defaults to the sync
+  path — correct for anything with no I/O). `OAuthTokenAuth` overrides both independently (sync
+  `httpx.Client` / async `httpx.AsyncClient`) so the async client's refresh never blocks the event
+  loop with a sync HTTP call — see `transport/http.py`'s `AsyncTransport.get`, which `await`s the
+  token callable. Refresh is proactive — checked and done inside `get_token`/`async_get_token`, 60s
+  before `expires_at` — rather than reactive-on-401, so `transport/http.py` stays completely
+  unaware refresh exists at all.
+
+## Reliability and typing
+
+- Every request has a bounded timeout (`DEFAULT_TIMEOUT_SECONDS = 30.0` in `transport/http.py`)
+  unless a caller passes `timeout_ms` explicitly.
+- The retry loop (exponential backoff, `transport/retry.py`) covers both retryable HTTP status
+  codes and transport-level failures (timeouts, connection resets, DNS) with the same attempt
+  budget — the latter surface as `PlansomConnectionError`, never a raw `httpx` exception, so callers
+  only ever need to catch this package's own exception hierarchy.
+- PEP 561 typed (`py.typed` ships in the built package) and `mypy`-clean.
+- `pagination.paginate`/`async_paginate` walk every page of a list endpoint for both clients.
+- Every request sends `User-Agent: plansom-sdk-python/<version>` (`_version.py`).
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+Covers client construction and auth behavior (`test_client.py`/`test_async_client.py`), the OAuth
+exchange/refresh flow respx-mocked against `/o/token/` (`test_auth.py`), sync/async pagination
+(`test_pagination.py`), pydantic model parsing (`test_models.py`), the HTTP transport layer —
+successful requests, error-status mapping, retries, connection failures — respx-mocked without a
+real network call (`test_transport.py`), and that every field a resource method's return type
+relies on still exists in `openapi/v3.yaml`'s current schema (`test_schema_conformance.py`).
+
+```
+mypy plansom_sdk/
+```

plansom_sdk-0.0.1/plansom_sdk/__init__.py

@@ -0,0 +1,21 @@
+"""Plansom SDK — Python client for be3's v3 API."""
+
+from ._version import __version__
+from .client import Plansom
+from .async_client import PlansomAsync
+from .exceptions import (
+    PlansomError,
+    PlansomAPIError,
+    PlansomAuthError,
+    PlansomConnectionError,
+)
+
+__all__ = [
+    "Plansom",
+    "PlansomAsync",
+    "PlansomError",
+    "PlansomAPIError",
+    "PlansomAuthError",
+    "PlansomConnectionError",
+    "__version__",
+]

plansom_sdk-0.0.1/plansom_sdk/_version.py

@@ -0,0 +1,6 @@
+"""Single source of truth for the package version, kept separate from
+__init__.py so leaf modules (e.g. transport/http.py, for the User-Agent
+header) can import it without risking a circular import through the
+package's own __init__.py."""
+
+__version__ = "0.0.1"

plansom_sdk-0.0.1/plansom_sdk/async_client.py

@@ -0,0 +1,67 @@
+"""Plansom SDK — asynchronous client. Mirrors client.py."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .auth import AuthStrategy, OAuthTokenAuth
+from .resources.goals import AsyncGoals
+from .resources.organizations import AsyncOrganizations
+from .resources.search import AsyncSearch
+from .resources.tasks import AsyncTasks
+from .resources.teams import AsyncTeams
+from .resources.users import AsyncUsers
+from .transport.http import DEFAULT_BASE_URL, AsyncTransport
+from .transport.retry import RetryConfig
+
+
+def _require_auth(auth: Optional[AuthStrategy]):
+    async def get_token() -> str:
+        if auth is None:
+            raise RuntimeError("PlansomAsync(auth=...) is required to make API calls.")
+        return await auth.async_get_token()
+
+    return get_token
+
+
+class PlansomAsync:
+    """Asynchronous Plansom API client.
+
+    Usage:
+        from plansom_sdk import PlansomAsync
+        from plansom_sdk.auth import OAuthTokenAuth
+
+        client = PlansomAsync(auth=await OAuthTokenAuth.from_authorization_code_async(...))
+        page = await client.goals.list(organization=org_id)
+    """
+
+    def __init__(
+        self,
+        auth: Optional[AuthStrategy] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        retry_config: Optional[RetryConfig] = None,
+    ) -> None:
+        resolved_base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        if isinstance(auth, OAuthTokenAuth) and auth.base_url != resolved_base_url:
+            raise ValueError(
+                f"PlansomAsync is configured for {resolved_base_url!r} but its OAuthTokenAuth is "
+                f"configured for {auth.base_url!r} — resource calls and token refresh would "
+                f"silently hit different environments."
+            )
+        self._transport = AsyncTransport(
+            _require_auth(auth), base_url=base_url, timeout_ms=timeout_ms, retry_config=retry_config
+        )
+        self.goals = AsyncGoals(self._transport)
+        self.tasks = AsyncTasks(self._transport)
+        self.users = AsyncUsers(self._transport)
+        self.teams = AsyncTeams(self._transport)
+        self.organizations = AsyncOrganizations(self._transport)
+        self.search = AsyncSearch(self._transport)
+
+    async def __aenter__(self) -> "PlansomAsync":
+        return self
+
+    async def __aexit__(self, *exc_info) -> None:
+        await self._transport.aclose()