rasket 0.4.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.
rasket/__init__.py ADDED
@@ -0,0 +1,55 @@
1
+ """`rasket` -- the Rasket Python client.
2
+
3
+ ```python
4
+ import os
5
+ from rasket import Rasket
6
+
7
+ rasket = Rasket(api_key=os.environ["RASKET_API_KEY"], user_agent="acme-billing/1.0")
8
+ result = rasket.emails.send({...}, idempotency_key="receipt-1042")
9
+ ```
10
+
11
+ Request and response types live in `rasket.types`, generated from the API's own document.
12
+ """
13
+
14
+ from . import _types as types
15
+ from . import webhooks
16
+ from ._client import Rasket
17
+ from ._errors import (
18
+ ChecksRefusal,
19
+ EmailCheckResult,
20
+ ErrorDetails,
21
+ NextStepRefusal,
22
+ RasketApiError,
23
+ RasketConnectionError,
24
+ RateLimit,
25
+ SandboxRefusal,
26
+ ValidationIssue,
27
+ )
28
+ from ._http import DEFAULT_BASE_URL, RasketResponse, RetryOptions
29
+ from ._replay import ReplayManyResult
30
+ from ._version import SDK_VERSION
31
+ from .webhooks import WebhookVerificationError
32
+
33
+ __version__ = SDK_VERSION
34
+
35
+ __all__ = [
36
+ "DEFAULT_BASE_URL",
37
+ "SDK_VERSION",
38
+ "ChecksRefusal",
39
+ "EmailCheckResult",
40
+ "ErrorDetails",
41
+ "NextStepRefusal",
42
+ "Rasket",
43
+ "RasketApiError",
44
+ "RasketConnectionError",
45
+ "RasketResponse",
46
+ "RateLimit",
47
+ "ReplayManyResult",
48
+ "RetryOptions",
49
+ "SandboxRefusal",
50
+ "ValidationIssue",
51
+ "WebhookVerificationError",
52
+ "__version__",
53
+ "types",
54
+ "webhooks",
55
+ ]
rasket/_client.py ADDED
@@ -0,0 +1,55 @@
1
+ """The client a customer constructs. The resources it carries are generated (`resources/`)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from types import TracebackType
6
+
7
+ import httpx
8
+
9
+ from ._http import DEFAULT_TIMEOUT, HttpClient, RetryOptions
10
+ from .resources import Resources
11
+
12
+
13
+ class Rasket(Resources):
14
+ """A Rasket API client.
15
+
16
+ `api_key` is an `rk_…` key or an OAuth access token; both are sent as `Authorization: Bearer`.
17
+ `base_url` defaults to the documented origin; a deployment host takes the prefix,
18
+ `https://<deployment-host>/api/v1`. `user_agent` is appended to the client's own agent, never
19
+ substituted. `timeout` is seconds per attempt. Pass `http_client` to reuse your own
20
+ `httpx.Client` (proxies, transports); the client then leaves closing it to you.
21
+ """
22
+
23
+ def __init__(
24
+ self,
25
+ api_key: str,
26
+ *,
27
+ base_url: str | None = None,
28
+ user_agent: str | None = None,
29
+ timeout: float = DEFAULT_TIMEOUT,
30
+ retry: RetryOptions | None = None,
31
+ http_client: httpx.Client | None = None,
32
+ ) -> None:
33
+ self._client = HttpClient(
34
+ api_key,
35
+ base_url=base_url,
36
+ user_agent=user_agent,
37
+ timeout=timeout,
38
+ retry=retry,
39
+ http_client=http_client,
40
+ )
41
+ super().__init__(self._client)
42
+
43
+ def close(self) -> None:
44
+ self._client.close()
45
+
46
+ def __enter__(self) -> Rasket:
47
+ return self
48
+
49
+ def __exit__(
50
+ self,
51
+ exc_type: type[BaseException] | None,
52
+ exc: BaseException | None,
53
+ traceback: TracebackType | None,
54
+ ) -> None:
55
+ self.close()
rasket/_errors.py ADDED
@@ -0,0 +1,151 @@
1
+ """The two ways a call can fail: the API refused it, or no answer arrived.
2
+
3
+ `packages/sdk/src/errors.ts` is the specification; the attribute names are its fields in
4
+ snake_case.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass
10
+ from typing import Literal
11
+
12
+ UNKNOWN_ERROR_NAME = "unknown_error"
13
+
14
+ ErrorSource = Literal["server", "client"]
15
+ ConnectionFailure = Literal["network", "timeout"]
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class RateLimit:
20
+ """The three rate-limit headers the API sets on every response (14 §1), plus `retry-after`."""
21
+
22
+ limit: int
23
+ """`ratelimit-limit`: the documented 10 requests per second, per team."""
24
+ remaining: int
25
+ """`ratelimit-remaining`: tokens left in the bucket after this request."""
26
+ reset_seconds: int
27
+ """`ratelimit-reset`: seconds until the bucket is full again."""
28
+ retry_after_seconds: int | None = None
29
+ """`retry-after`: whole seconds, present only on a 429."""
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class ValidationIssue:
34
+ """One entry of the `errors[]` array a validation error may carry."""
35
+
36
+ path: str
37
+ message: str
38
+
39
+
40
+ @dataclass(frozen=True)
41
+ class SandboxRefusal:
42
+ """`details` on the 403 a send gets while its region is still in our sending sandbox.
43
+
44
+ It names the refused recipient and the region. `allowed` says who the sandbox delivers to:
45
+ `verified_identity`, `verified_domain`, `simulator`. `GET /team` lists sandboxed regions in
46
+ `sending.sandbox_regions`.
47
+ """
48
+
49
+ recipient: str
50
+ region: str
51
+ allowed: tuple[str, ...]
52
+
53
+
54
+ @dataclass(frozen=True)
55
+ class NextStepRefusal:
56
+ """`details` on a refusal whose answer is a different surface.
57
+
58
+ `next == "checkout"` is `POST /billing/addons` saying the team has no subscription to put an
59
+ add-on on, and that `POST /billing/checkout` will make one -- for `inbox_storage_100gb` it can
60
+ buy the add-on on its own. The `message` says the same thing in a sentence.
61
+ """
62
+
63
+ next: Literal["checkout"]
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class EmailCheckResult:
68
+ """One pre-send check's verdict, as `broadcasts.checks()` lists it."""
69
+
70
+ code: str
71
+ status: str
72
+ title: str
73
+ message: str
74
+ block_id: str | None = None
75
+
76
+
77
+ @dataclass(frozen=True)
78
+ class ChecksRefusal:
79
+ """`details` on the 422 a broadcast send gets when its content fails a pre-send check.
80
+
81
+ `checks` are the failing checks. Send again with `acknowledge_checks: True` to send anyway.
82
+ """
83
+
84
+ checks: tuple[EmailCheckResult, ...]
85
+
86
+
87
+ #: Everything `details` may be. Narrow it with `isinstance`; the API sets exactly one shape per
88
+ #: refusal, and a future one is a new member rather than a change to an existing one.
89
+ ErrorDetails = SandboxRefusal | NextStepRefusal | ChecksRefusal
90
+
91
+
92
+ class RasketApiError(Exception):
93
+ """The API refused the request, or answered with something that was not a Rasket response.
94
+
95
+ `name` is the stable vocabulary value from 14 §1.1 -- `validation_error`, `not_found`,
96
+ `rate_limit_exceeded` -- which is what a caller branches on. A name newer than this copy of
97
+ the client is passed through rather than hidden. `unknown_error` means the body was not ours.
98
+
99
+ `source` is `"client"` for the one refusal this package makes on its own: an
100
+ `Idempotency-Key` outside 1-256 characters, raised before any request is spent, with the
101
+ same `status_code` and `name` the API would have used.
102
+ """
103
+
104
+ kind: Literal["api_error"] = "api_error"
105
+
106
+ def __init__(
107
+ self,
108
+ *,
109
+ status_code: int,
110
+ name: str,
111
+ message: str,
112
+ source: ErrorSource,
113
+ errors: tuple[ValidationIssue, ...] | None = None,
114
+ code: int | None = None,
115
+ claimable: bool | None = None,
116
+ details: ErrorDetails | None = None,
117
+ request_id: str | None = None,
118
+ rate_limit: RateLimit | None = None,
119
+ ) -> None:
120
+ super().__init__(message)
121
+ self.status_code = status_code
122
+ self.name = name
123
+ self.message = message
124
+ self.source: ErrorSource = source
125
+ self.errors = errors
126
+ self.code = code
127
+ self.claimable = claimable
128
+ self.details = details
129
+ self.request_id = request_id
130
+ self.rate_limit = rate_limit
131
+
132
+ def __repr__(self) -> str:
133
+ return (
134
+ f"RasketApiError(status_code={self.status_code}, name={self.name!r}, "
135
+ f"message={self.message!r})"
136
+ )
137
+
138
+
139
+ class RasketConnectionError(Exception):
140
+ """The request never got an answer: the connection failed, or the per-attempt timeout elapsed.
141
+
142
+ For a request that was safe to repeat the client has already retried before raising this; for
143
+ a send without an `Idempotency-Key` it has not, and whether the email was accepted is unknown.
144
+ """
145
+
146
+ kind: Literal["connection_error"] = "connection_error"
147
+
148
+ def __init__(self, reason: ConnectionFailure, message: str) -> None:
149
+ super().__init__(message)
150
+ self.reason: ConnectionFailure = reason
151
+ self.message = message