hot-dev 1.2.0__tar.gz → 1.4.0__tar.gz
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.
- hot_dev-1.4.0/PKG-INFO +409 -0
- hot_dev-1.4.0/README.md +378 -0
- hot_dev-1.4.0/pyproject.toml +79 -0
- hot_dev-1.4.0/src/hot/__init__.py +31 -0
- hot_dev-1.4.0/src/hot/_streaming.py +697 -0
- hot_dev-1.4.0/src/hot/_transport.py +439 -0
- hot_dev-1.4.0/src/hot/_version.py +1 -0
- {hot_dev-1.2.0 → hot_dev-1.4.0}/src/hot/client.py +48 -5
- hot_dev-1.4.0/src/hot/errors.py +185 -0
- hot_dev-1.4.0/src/hot/resources.py +2107 -0
- hot_dev-1.4.0/src/hot/sse.py +95 -0
- {hot_dev-1.2.0 → hot_dev-1.4.0}/src/hot/types.py +12 -1
- hot_dev-1.2.0/.github/workflows/ci.yml +0 -65
- hot_dev-1.2.0/.github/workflows/release.yml +0 -37
- hot_dev-1.2.0/AGENTS.md +0 -73
- hot_dev-1.2.0/PKG-INFO +0 -241
- hot_dev-1.2.0/README.md +0 -221
- hot_dev-1.2.0/integration/fixture/.env.example +0 -3
- hot_dev-1.2.0/integration/fixture/.gitignore +0 -5
- hot_dev-1.2.0/integration/fixture/hot/src/fixture/sdk.hot +0 -56
- hot_dev-1.2.0/integration/fixture/hot.hot +0 -22
- hot_dev-1.2.0/integration/mint_key.py +0 -42
- hot_dev-1.2.0/integration/run.sh +0 -44
- hot_dev-1.2.0/pyproject.toml +0 -47
- hot_dev-1.2.0/src/hot/__init__.py +0 -12
- hot_dev-1.2.0/src/hot/_transport.py +0 -200
- hot_dev-1.2.0/src/hot/errors.py +0 -104
- hot_dev-1.2.0/src/hot/resources.py +0 -1647
- hot_dev-1.2.0/src/hot/sse.py +0 -51
- hot_dev-1.2.0/tests/openapi_operations.json +0 -64
- hot_dev-1.2.0/tests/test_client.py +0 -248
- hot_dev-1.2.0/tests/test_integration.py +0 -120
- hot_dev-1.2.0/tests/test_openapi_coverage.py +0 -113
- hot_dev-1.2.0/tests/test_reconnect.py +0 -194
- hot_dev-1.2.0/tests/test_resources.py +0 -94
- hot_dev-1.2.0/tests/test_runs.py +0 -84
- hot_dev-1.2.0/tests/test_tasks.py +0 -79
- {hot_dev-1.2.0 → hot_dev-1.4.0}/.gitignore +0 -0
- {hot_dev-1.2.0 → hot_dev-1.4.0}/LICENSE +0 -0
- {hot_dev-1.2.0 → hot_dev-1.4.0}/NOTICE +0 -0
- {hot_dev-1.2.0 → hot_dev-1.4.0}/src/hot/py.typed +0 -0
hot_dev-1.4.0/PKG-INFO
ADDED
|
@@ -0,0 +1,409 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: hot-dev
|
|
3
|
+
Version: 1.4.0
|
|
4
|
+
Summary: Python SDK for the Hot Dev API
|
|
5
|
+
Project-URL: Homepage, https://hot.dev
|
|
6
|
+
Project-URL: Repository, https://github.com/hot-dev/hot-python
|
|
7
|
+
Project-URL: Issues, https://github.com/hot-dev/hot-python/issues
|
|
8
|
+
Author: Hot Dev, LLC
|
|
9
|
+
License-Expression: Apache-2.0
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
License-File: NOTICE
|
|
12
|
+
Keywords: agents,api,hot,hot-dev,sdk,streaming
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Requires-Dist: httpx<1.0,>=0.28
|
|
25
|
+
Provides-Extra: dev
|
|
26
|
+
Requires-Dist: build==1.6.1; extra == 'dev'
|
|
27
|
+
Requires-Dist: mypy==1.15.0; extra == 'dev'
|
|
28
|
+
Requires-Dist: pytest==9.2.0; extra == 'dev'
|
|
29
|
+
Requires-Dist: ruff==0.17.6; extra == 'dev'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# hot-dev
|
|
33
|
+
|
|
34
|
+
Official Python SDK for the [Hot Dev](https://hot.dev) API.
|
|
35
|
+
|
|
36
|
+
- PyPI distribution: `hot-dev`
|
|
37
|
+
- Import package: `hot`
|
|
38
|
+
- Tested on Python 3.10 through 3.15
|
|
39
|
+
|
|
40
|
+
## Install
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install hot-dev
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Quick Start
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
import os
|
|
50
|
+
|
|
51
|
+
from hot import HotClient
|
|
52
|
+
|
|
53
|
+
hot = HotClient(token=os.environ["HOT_API_KEY"])
|
|
54
|
+
|
|
55
|
+
# base_url defaults to https://api.hot.dev.
|
|
56
|
+
# For local development with `hot dev`, pass base_url="http://localhost:4681".
|
|
57
|
+
|
|
58
|
+
for event in hot.streams.subscribe_with_event(
|
|
59
|
+
{
|
|
60
|
+
"event_type": "team-agent:ask",
|
|
61
|
+
"event_data": {
|
|
62
|
+
"session_id": "web:chat:demo",
|
|
63
|
+
"user_id": "web:user:demo",
|
|
64
|
+
"user_name": "Demo User",
|
|
65
|
+
"question": "what is blocking launch?",
|
|
66
|
+
},
|
|
67
|
+
}
|
|
68
|
+
):
|
|
69
|
+
if event["type"] == "stream:data":
|
|
70
|
+
print(event["data_type"], event.get("payload"))
|
|
71
|
+
|
|
72
|
+
if event["type"] == "run:stop":
|
|
73
|
+
print(event.get("run", {}).get("result"))
|
|
74
|
+
break
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The client closes its underlying HTTP connection cleanly when used as a context
|
|
78
|
+
manager:
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
with HotClient(token=os.environ["HOT_API_KEY"]) as hot:
|
|
82
|
+
event = hot.events.publish(
|
|
83
|
+
{
|
|
84
|
+
"event_type": "team-agent:ask",
|
|
85
|
+
"event_data": {"question": "what changed?"},
|
|
86
|
+
}
|
|
87
|
+
)
|
|
88
|
+
print(event["stream_id"])
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Authenticated clients should run server-side. Browser apps and public notebooks
|
|
92
|
+
should call your own backend route instead of exposing a Hot API key.
|
|
93
|
+
Administrative runtime endpoints require an API key with appropriate grants. Sessions and service keys are
|
|
94
|
+
permission-scoped and are mainly for event publishing and stream reads.
|
|
95
|
+
|
|
96
|
+
When code has a run id but does not need the full stream, wait on its durable
|
|
97
|
+
terminal snapshot. `timeout` bounds the whole wait, including reconnects:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
run = hot.runs.wait(run_id, timeout=300)
|
|
101
|
+
print(run["result"])
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
When a run returns a background task id, wait through the durable task resource:
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
task = hot.tasks.wait(task_id, timeout=300)
|
|
108
|
+
print(task["result"])
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
The task waiter receives the latest persisted state first and reconnects, so it
|
|
112
|
+
cannot miss a task that completed before subscription. A failed, cancelled, or
|
|
113
|
+
timed-out task raises `HotTaskError` with the final task record.
|
|
114
|
+
To coordinate several tasks, wait on each one (`hot.tasks.wait`), for example
|
|
115
|
+
from a thread pool or with `asyncio.gather` on `AsyncHotClient`. The task's
|
|
116
|
+
parent stream also emits durable `task:update` events, but a plain
|
|
117
|
+
`streams.subscribe` ends at the API's 5-minute subscription limit.
|
|
118
|
+
|
|
119
|
+
### Waiters and reconnects
|
|
120
|
+
|
|
121
|
+
`runs.wait`, `tasks.wait`, `streams.wait_for_run_result`, `events.call_hot`
|
|
122
|
+
and `streams.subscribe_with_event` share one reconnect policy:
|
|
123
|
+
|
|
124
|
+
- `timeout` is an absolute deadline over connecting, reading, and backoff. It
|
|
125
|
+
fires even while the server keeps sending keepalives. `subscribe_with_event`
|
|
126
|
+
takes an optional `timeout`; without one it has no deadline.
|
|
127
|
+
- Permanent errors (any 4xx except 408 and 429, including `HotKeyScopeError`)
|
|
128
|
+
raise at once.
|
|
129
|
+
- Transport errors, 408, 429 and 5xx reconnect with jittered exponential
|
|
130
|
+
backoff (0.25 s up to 10 s), honouring `retry_after`. A backoff that would
|
|
131
|
+
cross the deadline raises `TimeoutError` instead.
|
|
132
|
+
- `max_attempts` (default 5) counts consecutive failed connections. The API
|
|
133
|
+
closes every subscription 5 minutes after it opens, with `stream:complete`;
|
|
134
|
+
explicit `stream:complete` rollovers reconnect at once and do not count, so
|
|
135
|
+
long runs can be awaited for as long as `timeout` allows. Unexpected premature
|
|
136
|
+
stream closes without `stream:complete` back off and count against
|
|
137
|
+
`max_attempts`.
|
|
138
|
+
- A run with status `pending_retry` is not final, whatever the event: the
|
|
139
|
+
waiter follows the handler's retry run (linked by `retry_run_id` or
|
|
140
|
+
`origin_run_id`). Hot can replay a retried attempt as `run:fail` with status
|
|
141
|
+
`failed` before the retry run exists; when its `retry_attempt` shows a
|
|
142
|
+
scheduled retry, the waiter holds that failure for 5 seconds (or until
|
|
143
|
+
`timeout`) and raises `HotRunError` (a `RuntimeError` subclass) only if no
|
|
144
|
+
retry run appears. `subscribe_with_event` yields that `run:fail` and ends
|
|
145
|
+
after the same grace.
|
|
146
|
+
- `on_chunk` receives `stream:data` text in order, including chunks the server
|
|
147
|
+
delivers before `run:start`.
|
|
148
|
+
|
|
149
|
+
## Async Usage
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
import os
|
|
153
|
+
|
|
154
|
+
from hot import AsyncHotClient
|
|
155
|
+
|
|
156
|
+
async with AsyncHotClient(token=os.environ["HOT_API_KEY"]) as hot:
|
|
157
|
+
event = await hot.events.publish(
|
|
158
|
+
{
|
|
159
|
+
"event_type": "team-agent:ask",
|
|
160
|
+
"event_data": {"question": "what changed?"},
|
|
161
|
+
}
|
|
162
|
+
)
|
|
163
|
+
print(event["stream_id"])
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Async streaming is supported the same way:
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
async with AsyncHotClient(token=os.environ["HOT_API_KEY"]) as hot:
|
|
170
|
+
async for event in hot.streams.subscribe_with_event(
|
|
171
|
+
{
|
|
172
|
+
"event_type": "team-agent:ask",
|
|
173
|
+
"event_data": {"question": "what changed?"},
|
|
174
|
+
}
|
|
175
|
+
):
|
|
176
|
+
print(event["type"], event)
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
`AsyncHotClient` exposes the same resource namespaces as `HotClient`.
|
|
180
|
+
|
|
181
|
+
## Errors
|
|
182
|
+
|
|
183
|
+
Non-2xx API responses raise `HotApiError` with structured fields:
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
from hot import HotApiError
|
|
187
|
+
|
|
188
|
+
try:
|
|
189
|
+
hot.projects.get("missing-project")
|
|
190
|
+
except HotApiError as error:
|
|
191
|
+
print(error.status_code, error.code, error.request_id, error.retry_after)
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
A call made with the wrong kind of key raises `HotKeyScopeError` (a
|
|
195
|
+
`HotApiError` with status 403 and code `key_scope_mismatch`). Its
|
|
196
|
+
`required_scope` is `"org"` for `hot.orgs` and `hot.api_keys`, and `"env"` for
|
|
197
|
+
every runtime resource.
|
|
198
|
+
|
|
199
|
+
### Retries
|
|
200
|
+
|
|
201
|
+
JSON requests are retried automatically (at most twice, bounded by the client's
|
|
202
|
+
configured read timeout) when the API responds:
|
|
203
|
+
|
|
204
|
+
- `429` with a `retry_after` (including `0`, integer seconds, or HTTP-date),
|
|
205
|
+
- `502`, `503`, or `504` on idempotent requests (`GET`, `HEAD`, `PUT`, `DELETE`),
|
|
206
|
+
- `503` with error code `event_publish_in_progress` on `POST` (for example,
|
|
207
|
+
concurrent retries of `events.publish` with the same client-supplied
|
|
208
|
+
`event_id`).
|
|
209
|
+
|
|
210
|
+
Other errors (including `409 event_id_conflict` when an `event_id` is reused
|
|
211
|
+
with different parameters) are raised as-is. Raw requests (`request_raw`,
|
|
212
|
+
uploads, downloads) are never retried; waiters follow the reconnect policy
|
|
213
|
+
above.
|
|
214
|
+
|
|
215
|
+
## Resources
|
|
216
|
+
|
|
217
|
+
`HotClient` mirrors the Hot API resources:
|
|
218
|
+
|
|
219
|
+
- `hot.status()` — public, unauthenticated server health check (`GET /status`; does not send `Authorization`)
|
|
220
|
+
- `hot.events` — publish (pass an optional `event_id` for idempotent retries; conflicting reuse returns `409 event_id_conflict`), list, get, inspect event runs, and call Hot functions with `call_hot(fn, args)`
|
|
221
|
+
- `hot.streams` — subscribe to run and task updates, wait for run results, and publish events atomically (reconnects automatically across the 5-minute SSE timeout; pass `reconnect=False` to opt out)
|
|
222
|
+
- `hot.runs` — list (filter by `status`, `type`, `time_range`, `project_id`, `stream_id`, `function`, `limit`, `offset`), inspect, subscribe to, and wait for durable runs
|
|
223
|
+
- `hot.tasks` — get, subscribe to, and wait for durable background tasks
|
|
224
|
+
- `hot.files` — upload, download (`download_stream` for large files), list, and delete files (including multipart uploads)
|
|
225
|
+
- `hot.projects` — create, list, update, activate, deactivate, and delete projects
|
|
226
|
+
- `hot.builds` — upload, download (`download_stream`), deploy, and look up live/deployed builds
|
|
227
|
+
- `hot.blobs` — download large payloads spilled to blob storage (`download_stream` streams them); needs an environment API key
|
|
228
|
+
- `hot.context` — manage encrypted project context variables
|
|
229
|
+
- `hot.domains` — register, verify, list, and delete custom domains
|
|
230
|
+
- `hot.sessions` — create and revoke scoped sessions
|
|
231
|
+
- `hot.service_keys` — create and revoke scoped service keys
|
|
232
|
+
- `hot.org` — view the environment's usage and limits
|
|
233
|
+
- `hot.env` — read environment info, subscribe to environment events, and purge call traces
|
|
234
|
+
- `hot.orgs` — with an org API key: sub-organizations, their environments and API keys, account usage, and `orgs.env(org_id, env_id)` for projects, builds and context in an environment
|
|
235
|
+
- `hot.api_keys` — with an org API key: get, narrow, rotate, and revoke API keys it issued (`status` can be `active`, `revoked`, `disabled`, `expired`, `issuer_inactive`, or `suspended`)
|
|
236
|
+
|
|
237
|
+
Use `hot.request(...)` or `hot.request_raw(...)` as an escape hatch for `/v1`
|
|
238
|
+
API endpoints that do not yet have a resource helper. Paths are resolved under
|
|
239
|
+
`/v1` automatically (pass `"/runs"` or `"runs"`, not `"/v1/runs"`); use
|
|
240
|
+
`hot.status()` for the unversioned `GET /status` route.
|
|
241
|
+
|
|
242
|
+
`hot.env.subscribe()` requires API key credentials and a live API pub/sub
|
|
243
|
+
backend; local API servers without pub/sub return a 503. `subscribe_with_event`
|
|
244
|
+
reconnects across the API's 5-minute SSE timeout and stops after the terminal
|
|
245
|
+
run correlated to the event it published. Unrelated runs on the same stream do
|
|
246
|
+
not end the iterator.
|
|
247
|
+
|
|
248
|
+
## Customizing the HTTP Client
|
|
249
|
+
|
|
250
|
+
Without `timeout` or `client`, requests time out after 60 s per read and 10 s
|
|
251
|
+
to connect; pass `timeout=httpx.Timeout(None)` to disable that. Streams and
|
|
252
|
+
waiters set their own timeouts. Note that `timeout=` is ignored when you pass a
|
|
253
|
+
custom `client=` — configure timeouts on your `httpx.Client` /
|
|
254
|
+
`httpx.AsyncClient` instead.
|
|
255
|
+
|
|
256
|
+
`HotClient` and `AsyncHotClient` accept an `httpx.Client` (or
|
|
257
|
+
`httpx.AsyncClient`) via the `client=` argument. Use this to configure retries,
|
|
258
|
+
proxies, or custom transports:
|
|
259
|
+
|
|
260
|
+
```python
|
|
261
|
+
import httpx
|
|
262
|
+
|
|
263
|
+
from hot import HotClient
|
|
264
|
+
|
|
265
|
+
http_client = httpx.Client(
|
|
266
|
+
timeout=httpx.Timeout(connect=5.0, read=60.0, write=30.0, pool=5.0),
|
|
267
|
+
transport=httpx.HTTPTransport(retries=3),
|
|
268
|
+
)
|
|
269
|
+
|
|
270
|
+
hot = HotClient(token=os.environ["HOT_API_KEY"], client=http_client)
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
When you pass your own client, the SDK does not close it on exit.
|
|
274
|
+
|
|
275
|
+
## Downloads
|
|
276
|
+
|
|
277
|
+
`files.download`, `builds.download` and `blobs.download` read the whole body into
|
|
278
|
+
memory. For large files, stream instead:
|
|
279
|
+
|
|
280
|
+
```python
|
|
281
|
+
with hot.files.download_stream(file_id) as response, open("out.bin", "wb") as out:
|
|
282
|
+
for chunk in response.iter_bytes():
|
|
283
|
+
out.write(chunk)
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
`blobs.download_stream(blob_ref_id)` works the same way.
|
|
287
|
+
`AsyncHotClient` offers the same with `async with` and `response.aiter_bytes()`.
|
|
288
|
+
|
|
289
|
+
## Casing Policy
|
|
290
|
+
|
|
291
|
+
Core API request and response payloads use the Hot API wire format:
|
|
292
|
+
`event_type`, `event_data`, `stream_id`, and so on. SDK-only options use Python
|
|
293
|
+
style names such as `base_url` and `timeout`.
|
|
294
|
+
|
|
295
|
+
The SDK never transforms user-owned payloads such as `event_data`.
|
|
296
|
+
|
|
297
|
+
## Type Hints
|
|
298
|
+
|
|
299
|
+
The package ships with `py.typed`, so editors and type checkers will pick up
|
|
300
|
+
the public API. Request and response payloads are currently typed as plain
|
|
301
|
+
`dict[str, Any]` — keys follow the Hot API wire format documented above. Strict
|
|
302
|
+
`TypedDict` shapes generated from the Hot API OpenAPI spec are planned for a
|
|
303
|
+
future release.
|
|
304
|
+
|
|
305
|
+
## Org API
|
|
306
|
+
|
|
307
|
+
Requires Hot 3.0.1 or later. An org API key (created by an administrator of the parent organization in the
|
|
308
|
+
App) provisions sub-organizations, their environments, and environment API
|
|
309
|
+
keys. Org keys only call `hot.orgs` and `hot.api_keys`; environment keys,
|
|
310
|
+
service keys, and sessions only call runtime resources. Either kind of key on
|
|
311
|
+
the wrong routes raises `HotKeyScopeError`.
|
|
312
|
+
|
|
313
|
+
```python
|
|
314
|
+
import os
|
|
315
|
+
import uuid
|
|
316
|
+
|
|
317
|
+
from hot import HotClient
|
|
318
|
+
|
|
319
|
+
with HotClient(token=os.environ["HOT_ORG_API_KEY"]) as org:
|
|
320
|
+
request_id = uuid.uuid4().hex[:24]
|
|
321
|
+
sub_org = org.orgs.create(
|
|
322
|
+
{
|
|
323
|
+
"name": "Customer",
|
|
324
|
+
"slug": f"customer-{request_id}", # 32 characters or fewer
|
|
325
|
+
"external_id": "customer-123",
|
|
326
|
+
"idempotency_key": request_id, # reuse it when retrying this request
|
|
327
|
+
}
|
|
328
|
+
)
|
|
329
|
+
org_id, env_id = sub_org["org"]["org_id"], sub_org["env_id"]
|
|
330
|
+
key = org.orgs.create_env_api_key(
|
|
331
|
+
org_id,
|
|
332
|
+
env_id,
|
|
333
|
+
{"description": "Customer backend", "permissions": {"*:*": ["*"]}},
|
|
334
|
+
)
|
|
335
|
+
# Projects, builds and context in the sub-organization's environment, with the org key.
|
|
336
|
+
org.orgs.env(org_id, env_id).projects.create({"name": "agent"})
|
|
337
|
+
|
|
338
|
+
with HotClient(token=key["token"]) as customer:
|
|
339
|
+
print(customer.env.get())
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
| Method | Route |
|
|
343
|
+
| --- | --- |
|
|
344
|
+
| `orgs.list(limit=, offset=)` | `GET /v1/orgs` (list envelope) |
|
|
345
|
+
| `orgs.create(body)` | `POST /v1/orgs`: returns `org`, `env_id`, `created` |
|
|
346
|
+
| `orgs.get(org_id)` / `orgs.update(org_id, {"state": ...})` | `GET`/`PATCH /v1/orgs/{org_id}` (`active`, `suspended`, `archived`) |
|
|
347
|
+
| `orgs.usage(parent_org_id)` | `GET /v1/orgs/{org_id}/usage` (account usage; parent organization only) |
|
|
348
|
+
| `orgs.purge_calls(org_id, include_sub_orgs=False)` | `DELETE /v1/orgs/{org_id}/calls` |
|
|
349
|
+
| `orgs.list_envs` / `create_env` / `get_env` | `/v1/orgs/{org_id}/envs[/{env_id}]` (create is idempotent by name) |
|
|
350
|
+
| `orgs.list_api_keys` / `create_api_key` | `/v1/orgs/{org_id}/api-keys` (org keys) |
|
|
351
|
+
| `orgs.list_env_api_keys` / `create_env_api_key` | `/v1/orgs/{org_id}/envs/{env_id}/api-keys` |
|
|
352
|
+
| `api_keys.get` / `update` / `revoke` / `rotate(overlap_seconds=)` | `/v1/api-keys/{key_id}[/rotate]` |
|
|
353
|
+
| `orgs.env(org_id, env_id).projects` / `.builds` / `.context` | `/v1/orgs/{org_id}/envs/{env_id}/...` |
|
|
354
|
+
|
|
355
|
+
A minted or rotated key's `token` is returned only once. Minted grants must fit
|
|
356
|
+
inside the org key's own grants for that environment. Revoking or narrowing an
|
|
357
|
+
org key restricts every key, service key, and session issued under it.
|
|
358
|
+
|
|
359
|
+
`hot.org.usage()` (runtime) reports one environment's consumption, with
|
|
360
|
+
`env_id` and `usage_scope: "environment"`; its limits come from the billing
|
|
361
|
+
account. Use `orgs.usage(parent_org_id)` with an org key for the account total.
|
|
362
|
+
|
|
363
|
+
## Local Development
|
|
364
|
+
|
|
365
|
+
```bash
|
|
366
|
+
python -m venv .venv
|
|
367
|
+
source .venv/bin/activate
|
|
368
|
+
python -m pip install -e ".[dev]"
|
|
369
|
+
ruff check .
|
|
370
|
+
pytest
|
|
371
|
+
python -m build
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
## Org API integration tests
|
|
375
|
+
|
|
376
|
+
`integration/suborg_fixture.py` creates an owned disposable database and
|
|
377
|
+
loopback API server, seeds an org API key and a root environment key, checks
|
|
378
|
+
the live OpenAPI operations against `tests/openapi_operations.json`, and runs
|
|
379
|
+
the given test command. It removes only its own resources and never uses
|
|
380
|
+
deployed credentials. It needs Python 3 and a Hot CLI built from the revision
|
|
381
|
+
in `integration/hot-server.ref`. For PostgreSQL, also install Docker and `psql`
|
|
382
|
+
and provide that hot checkout (default: sibling `hot`). Migrations use a
|
|
383
|
+
non-superuser schema owner; the API uses a distinct non-owner
|
|
384
|
+
`NOSUPERUSER NOBYPASSRLS` login with RLS enforcement.
|
|
385
|
+
|
|
386
|
+
```bash
|
|
387
|
+
python3 integration/suborg_fixture.py --hot ../hot/target/debug/hot --backend postgres -- \
|
|
388
|
+
.venv/bin/python -m pytest tests/test_suborg_integration.py -v
|
|
389
|
+
# For SQLite, use --backend sqlite.
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
Coverage includes sub-organization and environment provisioning and idempotency, identical
|
|
393
|
+
project names in siblings, foreign-ID and stream denial, root runtime
|
|
394
|
+
isolation, org/environment key separation (`HotKeyScopeError`), account and
|
|
395
|
+
environment usage, provisioning projects and context through `orgs.env`,
|
|
396
|
+
restricted keys, key rotation, narrowing and revocation, service/session
|
|
397
|
+
issuance and revocation, descendants of a revoked or narrowed org key, and sub-organization
|
|
398
|
+
suspension and resumption. See [the validation record](integration/VALIDATION.md).
|
|
399
|
+
|
|
400
|
+
## Related
|
|
401
|
+
|
|
402
|
+
- [Hot Dev documentation](https://hot.dev/docs)
|
|
403
|
+
- [SDK docs](https://hot.dev/docs/api/sdks)
|
|
404
|
+
- [JavaScript / TypeScript SDK](https://www.npmjs.com/package/@hot-dev/sdk)
|
|
405
|
+
- [Hot Chat demo](https://github.com/hot-dev/hot-demos/tree/main/hot-chat)
|
|
406
|
+
|
|
407
|
+
## License
|
|
408
|
+
|
|
409
|
+
Apache-2.0
|