transynq 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. transynq/__init__.py +57 -0
  2. transynq/_client.py +282 -0
  3. transynq/_core/__init__.py +1 -0
  4. transynq/_core/credentials.py +264 -0
  5. transynq/_core/errors.py +158 -0
  6. transynq/_core/http.py +502 -0
  7. transynq/_core/jsonenc.py +102 -0
  8. transynq/_core/models.py +36 -0
  9. transynq/_core/paging.py +40 -0
  10. transynq/_core/types.py +205 -0
  11. transynq/_generated/__init__.py +3 -0
  12. transynq/_generated/client_services.py +286 -0
  13. transynq/_generated/models.py +6996 -0
  14. transynq/_generated/services/__init__.py +3 -0
  15. transynq/_generated/services/account_invoices.py +80 -0
  16. transynq/_generated/services/accounting_systems.py +222 -0
  17. transynq/_generated/services/admin.py +140 -0
  18. transynq/_generated/services/aged_debtors.py +74 -0
  19. transynq/_generated/services/ai.py +256 -0
  20. transynq/_generated/services/authentication.py +129 -0
  21. transynq/_generated/services/background_jobs.py +61 -0
  22. transynq/_generated/services/bookings.py +265 -0
  23. transynq/_generated/services/check_lists.py +75 -0
  24. transynq/_generated/services/company.py +86 -0
  25. transynq/_generated/services/company_settings.py +121 -0
  26. transynq/_generated/services/compliance.py +132 -0
  27. transynq/_generated/services/costing.py +142 -0
  28. transynq/_generated/services/custom_pages.py +84 -0
  29. transynq/_generated/services/customer_statements.py +100 -0
  30. transynq/_generated/services/customers.py +504 -0
  31. transynq/_generated/services/dashboard.py +72 -0
  32. transynq/_generated/services/delivery_reports.py +39 -0
  33. transynq/_generated/services/dispatch.py +543 -0
  34. transynq/_generated/services/documents.py +75 -0
  35. transynq/_generated/services/driver_app.py +461 -0
  36. transynq/_generated/services/drivers.py +134 -0
  37. transynq/_generated/services/fleet.py +142 -0
  38. transynq/_generated/services/geography.py +484 -0
  39. transynq/_generated/services/grids.py +208 -0
  40. transynq/_generated/services/imports.py +248 -0
  41. transynq/_generated/services/integrations.py +164 -0
  42. transynq/_generated/services/interest.py +76 -0
  43. transynq/_generated/services/invoicing.py +497 -0
  44. transynq/_generated/services/jobs.py +1200 -0
  45. transynq/_generated/services/leg_splits.py +63 -0
  46. transynq/_generated/services/leg_templates.py +87 -0
  47. transynq/_generated/services/long_operations.py +52 -0
  48. transynq/_generated/services/lookups.py +109 -0
  49. transynq/_generated/services/mail.py +37 -0
  50. transynq/_generated/services/meta.py +36 -0
  51. transynq/_generated/services/notifications.py +163 -0
  52. transynq/_generated/services/pallets.py +102 -0
  53. transynq/_generated/services/photo_galleries.py +116 -0
  54. transynq/_generated/services/planning.py +101 -0
  55. transynq/_generated/services/pricing.py +353 -0
  56. transynq/_generated/services/products.py +138 -0
  57. transynq/_generated/services/reference_data.py +252 -0
  58. transynq/_generated/services/report_setup.py +94 -0
  59. transynq/_generated/services/sales_ledger.py +327 -0
  60. transynq/_generated/services/settings.py +286 -0
  61. transynq/_generated/services/spa.py +342 -0
  62. transynq/_generated/services/subcontractors.py +222 -0
  63. transynq/_generated/services/tracking.py +87 -0
  64. transynq/_generated/services/users.py +252 -0
  65. transynq/_generated/services/whats_app.py +211 -0
  66. transynq/_generated/services/yard.py +182 -0
  67. transynq/py.typed +0 -0
  68. transynq-1.0.0.dist-info/METADATA +146 -0
  69. transynq-1.0.0.dist-info/RECORD +71 -0
  70. transynq-1.0.0.dist-info/WHEEL +4 -0
  71. transynq-1.0.0.dist-info/licenses/LICENSE +21 -0
transynq/__init__.py ADDED
@@ -0,0 +1,57 @@
1
+ """Official Python client for the Transynq TMS API."""
2
+ from __future__ import annotations
3
+
4
+ from ._client import (
5
+ FAILED,
6
+ QUEUED,
7
+ RUNNING,
8
+ SUCCEEDED,
9
+ AsyncLongOperationPoller,
10
+ AsyncTransynqClient,
11
+ LongOperationPoller,
12
+ TransynqClient,
13
+ new_id,
14
+ new_idempotency_key,
15
+ read_modify_write,
16
+ read_modify_write_async,
17
+ )
18
+ from ._core.credentials import (
19
+ ApiKeyCredential,
20
+ Credential,
21
+ DriverLoginCredential,
22
+ DriverTokenCredential,
23
+ SessionCredential,
24
+ )
25
+ from ._core.errors import (
26
+ ApiError,
27
+ AuthenticationError,
28
+ BusinessRuleError,
29
+ ConflictError,
30
+ ConnectionError,
31
+ LongOperationFailedError,
32
+ NotFoundError,
33
+ PermissionDeniedError,
34
+ RateLimitError,
35
+ ServerError,
36
+ StaleVersionError,
37
+ TimeoutError,
38
+ TransynqError,
39
+ ValidationError,
40
+ )
41
+ from ._core.http import SDK_VERSION, ClientOptions
42
+ from ._core.models import PagedResponse, TransynqModel
43
+ from ._core.types import ApiResponse, FileDownload, FileUpload, RequestOptions, ResponseBody
44
+ from ._generated import models
45
+ from ._generated.client_services import API_VERSION, OPERATION_COUNT, SPEC_SHA256
46
+
47
+ __version__ = SDK_VERSION
48
+
49
+ __all__ = [
50
+ "API_VERSION", "FAILED", "OPERATION_COUNT", "QUEUED", "RUNNING", "SDK_VERSION", "SPEC_SHA256", "SUCCEEDED",
51
+ "ApiError", "ApiKeyCredential", "ApiResponse", "AsyncLongOperationPoller", "AsyncTransynqClient", "AuthenticationError",
52
+ "BusinessRuleError", "ClientOptions", "ConflictError", "ConnectionError", "Credential", "DriverLoginCredential",
53
+ "DriverTokenCredential", "FileDownload", "FileUpload", "LongOperationFailedError", "LongOperationPoller", "NotFoundError",
54
+ "PagedResponse", "PermissionDeniedError", "RateLimitError", "RequestOptions", "ResponseBody", "ServerError",
55
+ "SessionCredential", "StaleVersionError", "TimeoutError", "TransynqClient", "TransynqError", "TransynqModel",
56
+ "ValidationError", "models", "new_id", "new_idempotency_key", "read_modify_write", "read_modify_write_async",
57
+ ]
transynq/_client.py ADDED
@@ -0,0 +1,282 @@
1
+ """The entry clients."""
2
+ from __future__ import annotations
3
+
4
+ import uuid
5
+ from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Iterator, Optional, TypeVar, Union
6
+
7
+ import httpx
8
+
9
+ from ._core.credentials import Credential, DriverLoginCredential, SessionCredential
10
+ from ._core.errors import LongOperationFailedError, StaleVersionError
11
+ from ._core.http import AsyncTransport, ClientOptions, SyncTransport
12
+ from ._core.types import ApiResponse, FileDownload, RequestOptions, ResponseBody
13
+ from ._generated import models as m
14
+ from ._generated.client_services import AsyncServices, SyncServices
15
+
16
+ T = TypeVar("T")
17
+ R = TypeVar("R")
18
+
19
+ QUEUED, RUNNING, SUCCEEDED, FAILED = "Queued", "Running", "Succeeded", "Failed"
20
+ """Long operation states (an open set: compare as strings)."""
21
+
22
+
23
+ def _options(
24
+ base_url: str, credential: Optional[Credential], timeout: float, max_retries: int, user_agent_suffix: Optional[str], **extra: Any
25
+ ) -> ClientOptions:
26
+ return ClientOptions(base_url=base_url, credential=credential, timeout=timeout, max_retries=max_retries,
27
+ user_agent_suffix=user_agent_suffix, **extra)
28
+
29
+
30
+ def operation_id_from(response: "ApiResponse[ResponseBody]") -> uuid.UUID:
31
+ """The long operation a 202 answer started (its ``Location``, else its body's ``id``)."""
32
+ location = response.location
33
+ if location and "/long-operations/" in location.lower():
34
+ try:
35
+ return uuid.UUID(location.split("?", 1)[0].rstrip("/").rsplit("/", 1)[-1])
36
+ except ValueError:
37
+ pass
38
+ body = response.data.json() if isinstance(response.data, ResponseBody) else None
39
+ if isinstance(body, dict) and isinstance(body.get("id"), str):
40
+ return uuid.UUID(body["id"])
41
+ raise ValueError("the response is not a long-operation answer (no Location and no id)")
42
+
43
+
44
+ def _check(op: m.LongOperationResponse, operation_id: uuid.UUID) -> bool:
45
+ if op.status.lower() == SUCCEEDED.lower():
46
+ return True
47
+ if op.status.lower() == FAILED.lower():
48
+ raise LongOperationFailedError(f"Long operation {operation_id} ({op.kind}) failed: {op.error or 'no reason given'}.", op)
49
+ return False
50
+
51
+
52
+ class LongOperationPoller:
53
+ """Follows a long-running operation (``GET /api/v1/long-operations/{id}``) to its end."""
54
+
55
+ def __init__(self, client: "TransynqClient", operation_id: uuid.UUID) -> None:
56
+ self._client = client
57
+ self.id = operation_id
58
+ self.last: Optional[m.LongOperationResponse] = None
59
+
60
+ def status(self) -> m.LongOperationResponse:
61
+ self.last = self._client.long_operations.get_long_operation(self.id).data
62
+ return self.last
63
+
64
+ def wait(self, poll_interval: float = 2.0, timeout: float = 1800.0,
65
+ on_progress: Optional[Callable[[m.LongOperationResponse], None]] = None) -> m.LongOperationResponse:
66
+ """Polls until ``Succeeded`` (returns it) or ``Failed`` (raises :class:`LongOperationFailedError`)."""
67
+ waited = 0.0
68
+ while True:
69
+ op = self.status()
70
+ if on_progress:
71
+ on_progress(op)
72
+ if _check(op, self.id):
73
+ return op
74
+ if waited >= timeout:
75
+ raise TimeoutError(f"long operation {self.id} did not finish within {timeout} s")
76
+ self._client._transport._sleep(poll_interval)
77
+ waited += poll_interval
78
+
79
+ def download_result(self) -> FileDownload:
80
+ """The operation's result file (a workbook or PDF). Close it after reading."""
81
+ return self._client.long_operations.get_long_operation_file(self.id).data
82
+
83
+
84
+ class AsyncLongOperationPoller:
85
+ """Async version of :class:`LongOperationPoller`."""
86
+
87
+ def __init__(self, client: "AsyncTransynqClient", operation_id: uuid.UUID) -> None:
88
+ self._client = client
89
+ self.id = operation_id
90
+ self.last: Optional[m.LongOperationResponse] = None
91
+
92
+ async def status(self) -> m.LongOperationResponse:
93
+ self.last = (await self._client.long_operations.get_long_operation(self.id)).data
94
+ return self.last
95
+
96
+ async def wait(self, poll_interval: float = 2.0, timeout: float = 1800.0,
97
+ on_progress: Optional[Callable[[m.LongOperationResponse], None]] = None) -> m.LongOperationResponse:
98
+ waited = 0.0
99
+ while True:
100
+ op = await self.status()
101
+ if on_progress:
102
+ on_progress(op)
103
+ if _check(op, self.id):
104
+ return op
105
+ if waited >= timeout:
106
+ raise TimeoutError(f"long operation {self.id} did not finish within {timeout} s")
107
+ await self._client._transport._sleep(poll_interval)
108
+ waited += poll_interval
109
+
110
+ async def download_result(self) -> FileDownload:
111
+ return (await self._client.long_operations.get_long_operation_file(self.id)).data
112
+
113
+
114
+ class TransynqClient(SyncServices):
115
+ """
116
+ The Transynq TMS API client (blocking). One attribute per API area (``client.jobs``, ``client.customers``...),
117
+ one method per operation. Thread-safe; create one and reuse it. Use as a context manager or call :meth:`close`.
118
+ """
119
+
120
+ def __init__(
121
+ self,
122
+ base_url: str,
123
+ *,
124
+ credential: Optional[Credential] = None,
125
+ timeout: float = 60.0,
126
+ max_retries: int = 2,
127
+ user_agent_suffix: Optional[str] = None,
128
+ http_client: Optional[httpx.Client] = None,
129
+ **options: Any,
130
+ ) -> None:
131
+ self.options = _options(base_url, credential, timeout, max_retries, user_agent_suffix, **options)
132
+ self._transport = SyncTransport(self.options, http_client)
133
+ self._init_services(self._transport)
134
+
135
+ @property
136
+ def user_agent(self) -> str:
137
+ return self._transport.user_agent
138
+
139
+ def poll_long_operation(self, accepted: Union["ApiResponse[ResponseBody]", uuid.UUID]) -> LongOperationPoller:
140
+ """A poller for the long operation a 202 answer started, or for an operation id."""
141
+ return LongOperationPoller(self, accepted if isinstance(accepted, uuid.UUID) else operation_id_from(accepted))
142
+
143
+ def iter_grid_rows(self, grid_id: str, request: m.GridQueryRequest, options: Optional[RequestOptions] = None) -> Iterator[Dict[str, Any]]:
144
+ """Every row of ``POST /api/v1/grids/{grid_id}/query``, page by page (page size default 500, the maximum)."""
145
+ page, size = request.page or 1, request.page_size or 500
146
+ while True:
147
+ data = self.grids.query_grid(grid_id, request.model_copy(update={"page": page, "page_size": size}), options=options).data
148
+ if not data.rows:
149
+ return
150
+ yield from data.rows
151
+ if data.page * data.page_size >= data.total:
152
+ return
153
+ page += 1
154
+
155
+ def sign_out(self) -> None:
156
+ """Ends a session or driver sign-in on the server and forgets it locally."""
157
+ credential = self.options.credential
158
+ if isinstance(credential, SessionCredential) and credential.state is not None:
159
+ self.authentication.logout()
160
+ credential.reset()
161
+ elif isinstance(credential, DriverLoginCredential) and credential.state is not None:
162
+ self.driver_app.driver_logout()
163
+ credential.reset()
164
+
165
+ def close(self) -> None:
166
+ self._transport.close()
167
+
168
+ def __enter__(self) -> "TransynqClient":
169
+ return self
170
+
171
+ def __exit__(self, *exc: object) -> None:
172
+ self.close()
173
+
174
+
175
+ class AsyncTransynqClient(AsyncServices):
176
+ """The Transynq TMS API client (asyncio). Same surface as :class:`TransynqClient`, every method awaitable."""
177
+
178
+ def __init__(
179
+ self,
180
+ base_url: str,
181
+ *,
182
+ credential: Optional[Credential] = None,
183
+ timeout: float = 60.0,
184
+ max_retries: int = 2,
185
+ user_agent_suffix: Optional[str] = None,
186
+ http_client: Optional[httpx.AsyncClient] = None,
187
+ **options: Any,
188
+ ) -> None:
189
+ self.options = _options(base_url, credential, timeout, max_retries, user_agent_suffix, **options)
190
+ self._transport = AsyncTransport(self.options, http_client)
191
+ self._init_services(self._transport)
192
+
193
+ @property
194
+ def user_agent(self) -> str:
195
+ return self._transport.user_agent
196
+
197
+ def poll_long_operation(self, accepted: Union["ApiResponse[ResponseBody]", uuid.UUID]) -> AsyncLongOperationPoller:
198
+ return AsyncLongOperationPoller(self, accepted if isinstance(accepted, uuid.UUID) else operation_id_from(accepted))
199
+
200
+ async def iter_grid_rows(self, grid_id: str, request: m.GridQueryRequest,
201
+ options: Optional[RequestOptions] = None) -> AsyncIterator[Dict[str, Any]]:
202
+ page, size = request.page or 1, request.page_size or 500
203
+ while True:
204
+ data = (await self.grids.query_grid(grid_id, request.model_copy(update={"page": page, "page_size": size}), options=options)).data
205
+ if not data.rows:
206
+ return
207
+ for row in data.rows:
208
+ yield row
209
+ if data.page * data.page_size >= data.total:
210
+ return
211
+ page += 1
212
+
213
+ async def sign_out(self) -> None:
214
+ credential = self.options.credential
215
+ if isinstance(credential, SessionCredential) and credential.state is not None:
216
+ await self.authentication.logout()
217
+ credential.reset()
218
+ elif isinstance(credential, DriverLoginCredential) and credential.state is not None:
219
+ await self.driver_app.driver_logout()
220
+ credential.reset()
221
+
222
+ async def aclose(self) -> None:
223
+ await self._transport.aclose()
224
+
225
+ async def __aenter__(self) -> "AsyncTransynqClient":
226
+ return self
227
+
228
+ async def __aexit__(self, *exc: object) -> None:
229
+ await self.aclose()
230
+
231
+
232
+ def read_modify_write(
233
+ load: Callable[[], "ApiResponse[T]"],
234
+ save: Callable[[T, RequestOptions], "ApiResponse[R]"],
235
+ max_attempts: int = 3,
236
+ ) -> "ApiResponse[R]":
237
+ """Loads (with its ETag), saves with ``If-Match``; on :class:`StaleVersionError` reloads and repeats."""
238
+ if max_attempts < 1:
239
+ raise ValueError("max_attempts must be at least 1")
240
+ attempt = 0
241
+ while True:
242
+ attempt += 1
243
+ current = load()
244
+ if not current.etag:
245
+ raise ValueError("the loaded record has no ETag")
246
+ try:
247
+ return save(current.data, RequestOptions.with_if_match(current.etag))
248
+ except StaleVersionError:
249
+ if attempt >= max_attempts:
250
+ raise
251
+
252
+
253
+ async def read_modify_write_async(
254
+ load: Callable[[], Awaitable["ApiResponse[T]"]],
255
+ save: Callable[[T, RequestOptions], Awaitable["ApiResponse[R]"]],
256
+ max_attempts: int = 3,
257
+ ) -> "ApiResponse[R]":
258
+ """Async version of :func:`read_modify_write`."""
259
+ if max_attempts < 1:
260
+ raise ValueError("max_attempts must be at least 1")
261
+ attempt = 0
262
+ while True:
263
+ attempt += 1
264
+ current = await load()
265
+ if not current.etag:
266
+ raise ValueError("the loaded record has no ETag")
267
+ try:
268
+ return await save(current.data, RequestOptions.with_if_match(current.etag))
269
+ except StaleVersionError:
270
+ if attempt >= max_attempts:
271
+ raise
272
+
273
+
274
+ def new_id() -> uuid.UUID:
275
+ """A new client id for an idempotent create (``POST`` with ``id`` in the body)."""
276
+ return uuid.uuid4()
277
+
278
+
279
+ def new_idempotency_key() -> str:
280
+ return uuid.uuid4().hex
281
+
282
+
@@ -0,0 +1 @@
1
+ """Hand-written core of the Transynq SDK (transport, auth, errors, types)."""
@@ -0,0 +1,264 @@
1
+ """Credentials matching the API's real mechanisms (docs/design.md section 3)."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import datetime as _dt
6
+ import json
7
+ import threading
8
+ from abc import ABC, abstractmethod
9
+ from typing import Any, Callable, Generic, Iterable, Optional, TypeVar
10
+
11
+ from .errors import AuthenticationError
12
+ from .http import API_KEY_HEADER, CSRF_HEADER, CredentialRequest, SignInResponse
13
+
14
+ S = TypeVar("S")
15
+
16
+
17
+ class Credential(ABC):
18
+ """How requests authenticate. Implementations must be safe to share between threads (sync) or tasks (async)."""
19
+
20
+ @abstractmethod
21
+ def apply(self, request: CredentialRequest) -> None:
22
+ """Adds headers before a request is sent (sync clients), signing in first when needed."""
23
+
24
+ async def apply_async(self, request: CredentialRequest) -> None:
25
+ """Adds headers before a request is sent (async clients)."""
26
+ self.apply(request)
27
+
28
+ def refresh_after_unauthorized(self, request: CredentialRequest) -> bool:
29
+ """Called on a 401; True when one retry with fresh credentials is worthwhile."""
30
+ return False
31
+
32
+ async def refresh_after_unauthorized_async(self, request: CredentialRequest) -> bool:
33
+ return self.refresh_after_unauthorized(request)
34
+
35
+
36
+ class ApiKeyCredential(Credential):
37
+ """An API client key, sent as ``X-Transynq-APIKey``. The key's company is the tenant; no cookie, no CSRF."""
38
+
39
+ def __init__(self, api_key: str) -> None:
40
+ if not api_key or not api_key.strip():
41
+ raise ValueError("api_key is required")
42
+ self._key = api_key
43
+
44
+ def apply(self, request: CredentialRequest) -> None:
45
+ request.set_header(API_KEY_HEADER, self._key)
46
+
47
+ def __repr__(self) -> str:
48
+ return "ApiKeyCredential([redacted])"
49
+
50
+
51
+ class DriverTokenCredential(Credential):
52
+ """An existing driver-app token (``Authorization: Bearer <token>``), valid for ``/api/v1/driver/*``."""
53
+
54
+ def __init__(self, token: str) -> None:
55
+ if not token or not token.strip():
56
+ raise ValueError("token is required")
57
+ self._token = token
58
+
59
+ def apply(self, request: CredentialRequest) -> None:
60
+ request.set_header("Authorization", "Bearer " + self._token)
61
+
62
+ def __repr__(self) -> str:
63
+ return "DriverTokenCredential([redacted])"
64
+
65
+
66
+ def _parse_instant(value: Any) -> Optional[_dt.datetime]:
67
+ if not isinstance(value, str):
68
+ return None
69
+ try:
70
+ parsed = _dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
71
+ except ValueError:
72
+ return None
73
+ return parsed if parsed.tzinfo else parsed.replace(tzinfo=_dt.timezone.utc)
74
+
75
+
76
+ class SignInCredential(Credential, Generic[S]):
77
+ """Base of credentials that sign in: single-flight sign-in, refresh before expiry and once after a 401."""
78
+
79
+ refresh_margin = _dt.timedelta(seconds=60)
80
+
81
+ def __init__(self) -> None:
82
+ self._state: Optional[S] = None
83
+ self._lock = threading.Lock()
84
+ self._async_lock: Optional[asyncio.Lock] = None
85
+ self.sign_in_count = 0
86
+ self.clock: Callable[[], _dt.datetime] = lambda: _dt.datetime.now(_dt.timezone.utc)
87
+
88
+ @property
89
+ def state(self) -> Optional[S]:
90
+ return self._state
91
+
92
+ def reset(self) -> None:
93
+ """Forgets the signed-in state (after a sign-out); the next request signs in again."""
94
+ self._state = None
95
+
96
+ def _fresh(self, state: Optional[S]) -> bool:
97
+ if state is None:
98
+ return False
99
+ expires = self._expires(state)
100
+ return expires is None or expires - self.refresh_margin > self.clock()
101
+
102
+ def apply(self, request: CredentialRequest) -> None:
103
+ state = self._state
104
+ if not self._fresh(state):
105
+ with self._lock:
106
+ state = self._state
107
+ if not self._fresh(state):
108
+ state = self._from_answer(self._sign_in_call(request.transport.post_json))
109
+ self.sign_in_count += 1
110
+ self._state = state
111
+ assert state is not None
112
+ request.applied_state = state
113
+ self._apply(request, state)
114
+
115
+ async def apply_async(self, request: CredentialRequest) -> None:
116
+ state = self._state
117
+ if not self._fresh(state):
118
+ if self._async_lock is None:
119
+ self._async_lock = asyncio.Lock()
120
+ async with self._async_lock:
121
+ state = self._state
122
+ if not self._fresh(state):
123
+ state = self._from_answer(await self._sign_in_call(request.transport.post_json))
124
+ self.sign_in_count += 1
125
+ self._state = state
126
+ assert state is not None
127
+ request.applied_state = state
128
+ self._apply(request, state)
129
+
130
+ def refresh_after_unauthorized(self, request: CredentialRequest) -> bool:
131
+ with self._lock:
132
+ # only drop the state the failed request used; another caller may already have signed in again
133
+ if self._state is request.applied_state:
134
+ self._state = None
135
+ return True
136
+
137
+ async def refresh_after_unauthorized_async(self, request: CredentialRequest) -> bool:
138
+ if self._state is request.applied_state:
139
+ self._state = None
140
+ return True
141
+
142
+ @abstractmethod
143
+ def _sign_in_call(self, post_json: Callable[..., Any]) -> Any:
144
+ """Calls ``post_json(path, body, headers, operation_id)`` (returns its result or awaitable)."""
145
+
146
+ @abstractmethod
147
+ def _from_answer(self, answer: SignInResponse) -> S: ...
148
+
149
+ @abstractmethod
150
+ def _expires(self, state: S) -> Optional[_dt.datetime]: ...
151
+
152
+ @abstractmethod
153
+ def _apply(self, request: CredentialRequest, state: S) -> None: ...
154
+
155
+
156
+ class Session:
157
+ """A signed-in session (the cookie and CSRF token are never printed)."""
158
+
159
+ def __init__(self, cookie: str, csrf_token: str, expires_utc: Optional[_dt.datetime], me: Any) -> None:
160
+ self.cookie = cookie
161
+ self.csrf_token = csrf_token
162
+ self.expires_utc = expires_utc
163
+ self.me = me
164
+
165
+ def __repr__(self) -> str:
166
+ return f"Session(expires_utc={self.expires_utc!r}, [redacted])"
167
+
168
+
169
+ def session_cookie(set_cookies: Iterable[str]) -> Optional[str]:
170
+ """The ``name=value`` of the session cookie (``tq_session`` or ``__Host-tq_session``)."""
171
+ for header in set_cookies:
172
+ pair = header.split(";", 1)[0].strip()
173
+ name, sep, value = pair.partition("=")
174
+ if sep and value and name.endswith("tq_session"):
175
+ return pair
176
+ return None
177
+
178
+
179
+ class SessionCredential(SignInCredential[Session]):
180
+ """
181
+ A user session: ``POST /api/v1/auth/login`` with user name and password, then the session cookie on every request
182
+ and ``X-CSRF-Token`` on every unsafe one. Signs in again before the session expires and once after a 401.
183
+ """
184
+
185
+ def __init__(self, user_name: str, password: str) -> None:
186
+ super().__init__()
187
+ if not user_name or not password:
188
+ raise ValueError("user_name and password are required")
189
+ self._user_name = user_name
190
+ self._password = password
191
+
192
+ @property
193
+ def me(self) -> Any:
194
+ """The login answer (``MeResponse`` as a dict), or ``None`` before the first request."""
195
+ return self._state.me if self._state else None
196
+
197
+ def _sign_in_call(self, post_json: Callable[..., Any]) -> Any:
198
+ body = json.dumps({"userName": self._user_name, "password": self._password}).encode("utf-8")
199
+ # without a session the CSRF check only needs a non-empty value
200
+ return post_json("/api/v1/auth/login", body, {CSRF_HEADER: "transynq-sdk"}, "Login")
201
+
202
+ def _from_answer(self, answer: SignInResponse) -> Session:
203
+ cookie = session_cookie(answer.set_cookies)
204
+ if cookie is None:
205
+ raise AuthenticationError("Login answered without a session cookie.", status=answer.status_code, operation_id="Login")
206
+ me = json.loads(answer.body) if answer.body else {}
207
+ csrf = me.get("csrfToken") if isinstance(me, dict) else None
208
+ if not csrf:
209
+ raise AuthenticationError("Login answered without a csrfToken.", status=answer.status_code, operation_id="Login")
210
+ return Session(cookie, csrf, _parse_instant(me.get("sessionExpiresUtc")), me)
211
+
212
+ def _expires(self, state: Session) -> Optional[_dt.datetime]:
213
+ return state.expires_utc
214
+
215
+ def _apply(self, request: CredentialRequest, state: Session) -> None:
216
+ request.set_header("Cookie", state.cookie)
217
+ if request.is_unsafe:
218
+ request.set_header(CSRF_HEADER, state.csrf_token)
219
+
220
+ def __repr__(self) -> str:
221
+ return f"SessionCredential({self._user_name!r}, [redacted])"
222
+
223
+
224
+ class DriverToken:
225
+ def __init__(self, token: str, expires_utc: Optional[_dt.datetime], session: Any) -> None:
226
+ self.token = token
227
+ self.expires_utc = expires_utc
228
+ self.session = session
229
+
230
+ def __repr__(self) -> str:
231
+ return f"DriverToken(expires_utc={self.expires_utc!r}, [redacted])"
232
+
233
+
234
+ class DriverLoginCredential(SignInCredential[DriverToken]):
235
+ """Driver-app sign-in (``POST /api/v1/driver/login``), then ``Authorization: Bearer <token>``."""
236
+
237
+ def __init__(self, company_code: str, pin: str, device_id: str, push_token: str, app_version: str, platform: str) -> None:
238
+ super().__init__()
239
+ self._login = {"companyCode": company_code, "pin": pin, "deviceId": device_id, "pushToken": push_token,
240
+ "appVersion": app_version, "platform": platform}
241
+
242
+ @property
243
+ def session(self) -> Any:
244
+ """The last ``DriverSession`` (as a dict), or ``None``."""
245
+ return self._state.session if self._state else None
246
+
247
+ def _sign_in_call(self, post_json: Callable[..., Any]) -> Any:
248
+ return post_json("/api/v1/driver/login", json.dumps(self._login).encode("utf-8"), {}, "DriverLogin")
249
+
250
+ def _from_answer(self, answer: SignInResponse) -> DriverToken:
251
+ session = json.loads(answer.body) if answer.body else {}
252
+ token = session.get("token") if isinstance(session, dict) else None
253
+ if not token:
254
+ raise AuthenticationError("DriverLogin answered without a token.", status=answer.status_code, operation_id="DriverLogin")
255
+ return DriverToken(token, _parse_instant(session.get("expiresUtc")), session)
256
+
257
+ def _expires(self, state: DriverToken) -> Optional[_dt.datetime]:
258
+ return state.expires_utc
259
+
260
+ def _apply(self, request: CredentialRequest, state: DriverToken) -> None:
261
+ request.set_header("Authorization", "Bearer " + state.token)
262
+
263
+ def __repr__(self) -> str:
264
+ return "DriverLoginCredential([redacted])"