tutorflow-content 0.1.0__tar.gz

tutorflow_content-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: tutorflow-content
+Version: 0.1.0
+Summary: Python client for the TutorFlow Content API: generated routes and models, retries, pagination, run polling and webhook verification.
+License: Proprietary
+Project-URL: Homepage, https://tutorflow.io/resources/integrations/content-api-sdks
+Project-URL: Documentation, https://tutorflow.io/resources/integrations/content-api-sdks
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: attrs>=22.2
+Requires-Dist: python-dateutil>=2.8
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: openapi-python-client==0.29.1; extra == "dev"
+
+# tutorflow-content
+
+A Python client for the TutorFlow Content API (`/v1/content`). Routes and models are generated from the published OpenAPI document with [openapi-python-client](https://github.com/openapi-generators/openapi-python-client), and the package adds what an integration otherwise writes by hand: retries, pagination, waiting for runs, typed errors, and webhook verification. It is built on httpx.
+
+## Install
+
+Requires Python 3.11 or later.
+
+```bash
+pip install tutorflow-content
+```
+
+Documentation is at [tutorflow.io/resources/integrations/content-api-sdks](https://tutorflow.io/resources/integrations/content-api-sdks).
+
+## Create a client
+
+Keep the key on your server.
+
+```python
+import os
+
+from tutorflow_content import create_client, unwrap
+from tutorflow_content.generated.api.content_classrooms import (
+    content_integration_classroom_controller_list_classrooms as list_classrooms,
+)
+
+client = create_client(os.environ["TUTORFLOW_CONTENT_API_KEY"])
+
+for classroom in unwrap(list_classrooms.sync_detailed(client=client)):
+    print(classroom.id, classroom.name, classroom.is_sandbox)
+```
+
+Every route is a module under `tutorflow_content.generated.api.<tag>` with `sync`, `sync_detailed`, `asyncio` and `asyncio_detailed`. `unwrap()` takes a `*_detailed` response and returns the parsed model, or raises `ContentApiError` with `code`, `status`, `request_id`, `retry_after_seconds`, `current_etag` and `details` from the error envelope. A 412 raises its subclass `ContentPreconditionFailedError`.
+
+A test key (`tf_content_test_...`) works the same way against the sandbox classroom; `is_test_key(api_key)` tells them apart.
+
+## Retries and idempotency
+
+`create_client()` installs `RetryTransport` (and `AsyncRetryTransport` for the async calls):
+
+- `429`: always retried, after `Retry-After` (up to 60 seconds; a longer wait comes back to you as the 429).
+- `500`, `502`, `503`, `504` and connection failures: retried only for `GET`, `PUT`, `DELETE` and requests that carry an `Idempotency-Key`, so a change is never applied twice.
+
+Backoff starts at 0.5 s and doubles with jitter, two retries by default. Tune it with `create_client(key, retry=RetryConfig(max_retries=4))` or turn it off with `retry=None`.
+
+Routes that accept an `Idempotency-Key` take it as the `idempotency_key=` argument. Every retry sends the same key, and the API replays the first answer:
+
+```python
+from tutorflow_content import new_idempotency_key
+from tutorflow_content.generated.api.content_generation import content_generation_controller_generate_course as generate_course
+from tutorflow_content.generated.models import ContentGenerateCourseRequest
+
+accepted = unwrap(
+    generate_course.sync_detailed(
+        classroom_id,
+        client=client,
+        body=ContentGenerateCourseRequest(topic="Fractions for Grade 5", lesson_count=6, language="en"),
+        idempotency_key=new_idempotency_key(),
+    )
+)
+```
+
+## Pagination
+
+`paginate()` yields every item of a list and reads both envelopes: page-numbered lists get the next `page=`, cursor lists get `cursor=` from `meta.nextCursor`. Pass a function that takes those keyword arguments:
+
+```python
+from tutorflow_content import paginate
+from tutorflow_content.generated.api.content_courses import content_resource_course_controller_list as list_courses
+
+for course in paginate(lambda **next: list_courses.sync_detailed(classroom_id, client=client, limit=100, **next)):
+    print(course.id, course.title)
+```
+
+## Waiting for runs
+
+These poll until the run settles and return its final status. They do not raise when the run failed; check the status.
+
+```python
+from tutorflow_content import wait_for_build, wait_for_render, wait_for_run
+
+run = wait_for_run(client, classroom_id=classroom_id, run_id=accepted.run_id)  # tests, modules, courses, slides
+if str(run.status) == "failed":
+    raise RuntimeError(run.error)
+
+build = wait_for_build(client, kind="game", classroom_id=classroom_id, resource_id=game_id, run_id=run_id)
+render = wait_for_render(client, classroom_id=classroom_id, video_id=video_id)
+```
+
+Options: `interval` (default 3 s), `timeout` (default 30 minutes), `on_poll`. The build status route only knows runs of the server that answers since its last deploy; a run it no longer tracks raises `ContentWaitError` with `reason == "run_not_tracked"`, and the run's webhook is the signal to rely on.
+
+## Webhooks
+
+`verify_webhook()` checks the `X-Content-Integration-Signature-V2` header against the raw body and returns the event as a dict, with `livemode` always present:
+
+```python
+from flask import Flask, abort, request
+
+from tutorflow_content import WebhookVerificationError, verify_webhook
+
+app = Flask(__name__)
+SECRETS = [s for s in (os.environ.get("TUTORFLOW_WEBHOOK_SECRET"), os.environ.get("TUTORFLOW_WEBHOOK_SECRET_PREVIOUS")) if s]
+
+
+@app.post("/tutorflow/webhooks")
+def tutorflow_webhook():
+    try:
+        event = verify_webhook(request.get_data(), request.headers.get("X-Content-Integration-Signature-V2"), SECRETS)
+    except WebhookVerificationError as error:
+        abort(400, error.reason)
+
+    if event["event"]["type"] == "course.generation.completed" and event["livemode"]:
+        queue_course_import(event["event"]["id"], event["resourceId"])
+    return "", 204
+```
+
+It accepts the request when `t` is within `tolerance_seconds` (default 300) of now and any `v1=` signature matches any secret you pass. During TutorFlow's secret rotation grace period the header carries a signature for the new and the previous secret. Deliveries are signed again on every retry.
+
+## Development
+
+```bash
+cd sdks/python
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest                               # httpx.MockTransport, no network
+python scripts/generate.py           # rewrite tutorflow_content/generated
+python scripts/generate.py --check   # exit 1 when it is stale against openapi.json
+```
+
+`tutorflow_content/generated` comes from `apps/frontend-admin/public/resources/integrations/openapi.json`, which the backend writes (`pnpm run openapi:content -- <path>` in tutorflow-backend). Regenerate after that file changes and commit both. Do not edit the generated code by hand.

tutorflow_content-0.1.0/README.md

@@ -0,0 +1,130 @@
+# tutorflow-content
+
+A Python client for the TutorFlow Content API (`/v1/content`). Routes and models are generated from the published OpenAPI document with [openapi-python-client](https://github.com/openapi-generators/openapi-python-client), and the package adds what an integration otherwise writes by hand: retries, pagination, waiting for runs, typed errors, and webhook verification. It is built on httpx.
+
+## Install
+
+Requires Python 3.11 or later.
+
+```bash
+pip install tutorflow-content
+```
+
+Documentation is at [tutorflow.io/resources/integrations/content-api-sdks](https://tutorflow.io/resources/integrations/content-api-sdks).
+
+## Create a client
+
+Keep the key on your server.
+
+```python
+import os
+
+from tutorflow_content import create_client, unwrap
+from tutorflow_content.generated.api.content_classrooms import (
+    content_integration_classroom_controller_list_classrooms as list_classrooms,
+)
+
+client = create_client(os.environ["TUTORFLOW_CONTENT_API_KEY"])
+
+for classroom in unwrap(list_classrooms.sync_detailed(client=client)):
+    print(classroom.id, classroom.name, classroom.is_sandbox)
+```
+
+Every route is a module under `tutorflow_content.generated.api.<tag>` with `sync`, `sync_detailed`, `asyncio` and `asyncio_detailed`. `unwrap()` takes a `*_detailed` response and returns the parsed model, or raises `ContentApiError` with `code`, `status`, `request_id`, `retry_after_seconds`, `current_etag` and `details` from the error envelope. A 412 raises its subclass `ContentPreconditionFailedError`.
+
+A test key (`tf_content_test_...`) works the same way against the sandbox classroom; `is_test_key(api_key)` tells them apart.
+
+## Retries and idempotency
+
+`create_client()` installs `RetryTransport` (and `AsyncRetryTransport` for the async calls):
+
+- `429`: always retried, after `Retry-After` (up to 60 seconds; a longer wait comes back to you as the 429).
+- `500`, `502`, `503`, `504` and connection failures: retried only for `GET`, `PUT`, `DELETE` and requests that carry an `Idempotency-Key`, so a change is never applied twice.
+
+Backoff starts at 0.5 s and doubles with jitter, two retries by default. Tune it with `create_client(key, retry=RetryConfig(max_retries=4))` or turn it off with `retry=None`.
+
+Routes that accept an `Idempotency-Key` take it as the `idempotency_key=` argument. Every retry sends the same key, and the API replays the first answer:
+
+```python
+from tutorflow_content import new_idempotency_key
+from tutorflow_content.generated.api.content_generation import content_generation_controller_generate_course as generate_course
+from tutorflow_content.generated.models import ContentGenerateCourseRequest
+
+accepted = unwrap(
+    generate_course.sync_detailed(
+        classroom_id,
+        client=client,
+        body=ContentGenerateCourseRequest(topic="Fractions for Grade 5", lesson_count=6, language="en"),
+        idempotency_key=new_idempotency_key(),
+    )
+)
+```
+
+## Pagination
+
+`paginate()` yields every item of a list and reads both envelopes: page-numbered lists get the next `page=`, cursor lists get `cursor=` from `meta.nextCursor`. Pass a function that takes those keyword arguments:
+
+```python
+from tutorflow_content import paginate
+from tutorflow_content.generated.api.content_courses import content_resource_course_controller_list as list_courses
+
+for course in paginate(lambda **next: list_courses.sync_detailed(classroom_id, client=client, limit=100, **next)):
+    print(course.id, course.title)
+```
+
+## Waiting for runs
+
+These poll until the run settles and return its final status. They do not raise when the run failed; check the status.
+
+```python
+from tutorflow_content import wait_for_build, wait_for_render, wait_for_run
+
+run = wait_for_run(client, classroom_id=classroom_id, run_id=accepted.run_id)  # tests, modules, courses, slides
+if str(run.status) == "failed":
+    raise RuntimeError(run.error)
+
+build = wait_for_build(client, kind="game", classroom_id=classroom_id, resource_id=game_id, run_id=run_id)
+render = wait_for_render(client, classroom_id=classroom_id, video_id=video_id)
+```
+
+Options: `interval` (default 3 s), `timeout` (default 30 minutes), `on_poll`. The build status route only knows runs of the server that answers since its last deploy; a run it no longer tracks raises `ContentWaitError` with `reason == "run_not_tracked"`, and the run's webhook is the signal to rely on.
+
+## Webhooks
+
+`verify_webhook()` checks the `X-Content-Integration-Signature-V2` header against the raw body and returns the event as a dict, with `livemode` always present:
+
+```python
+from flask import Flask, abort, request
+
+from tutorflow_content import WebhookVerificationError, verify_webhook
+
+app = Flask(__name__)
+SECRETS = [s for s in (os.environ.get("TUTORFLOW_WEBHOOK_SECRET"), os.environ.get("TUTORFLOW_WEBHOOK_SECRET_PREVIOUS")) if s]
+
+
+@app.post("/tutorflow/webhooks")
+def tutorflow_webhook():
+    try:
+        event = verify_webhook(request.get_data(), request.headers.get("X-Content-Integration-Signature-V2"), SECRETS)
+    except WebhookVerificationError as error:
+        abort(400, error.reason)
+
+    if event["event"]["type"] == "course.generation.completed" and event["livemode"]:
+        queue_course_import(event["event"]["id"], event["resourceId"])
+    return "", 204
+```
+
+It accepts the request when `t` is within `tolerance_seconds` (default 300) of now and any `v1=` signature matches any secret you pass. During TutorFlow's secret rotation grace period the header carries a signature for the new and the previous secret. Deliveries are signed again on every retry.
+
+## Development
+
+```bash
+cd sdks/python
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest                               # httpx.MockTransport, no network
+python scripts/generate.py           # rewrite tutorflow_content/generated
+python scripts/generate.py --check   # exit 1 when it is stale against openapi.json
+```
+
+`tutorflow_content/generated` comes from `apps/frontend-admin/public/resources/integrations/openapi.json`, which the backend writes (`pnpm run openapi:content -- <path>` in tutorflow-backend). Regenerate after that file changes and commit both. Do not edit the generated code by hand.

tutorflow_content-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tutorflow-content"
+version = "0.1.0"
+description = "Python client for the TutorFlow Content API: generated routes and models, retries, pagination, run polling and webhook verification."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Proprietary" }
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "attrs>=22.2",
+  "python-dateutil>=2.8",
+]
+
+[project.urls]
+Homepage = "https://tutorflow.io/resources/integrations/content-api-sdks"
+Documentation = "https://tutorflow.io/resources/integrations/content-api-sdks"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "openapi-python-client==0.29.1",
+]
+
+[tool.setuptools.packages.find]
+include = ["tutorflow_content*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tutorflow_content-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tutorflow_content-0.1.0/tests/test_errors.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import pytest
+
+from tutorflow_content import ContentApiError, ContentPreconditionFailedError, error_from_response
+
+from .conftest import error_response, json_response
+
+
+def test_reads_every_field_of_the_error_envelope():
+    # Arrange
+    response = error_response(429, "content_rate_limit_exceeded", {"retryAfterSeconds": 30}, {"Retry-After": "30"})
+
+    # Act
+    error = error_from_response(response)
+
+    # Assert
+    assert isinstance(error, ContentApiError)
+    assert (error.code, error.status, error.request_id, error.retry_after_seconds) == ("content_rate_limit_exceeded", 429, "req-err", 30.0)
+    assert str(error) == "content_rate_limit_exceeded happened"
+
+
+def test_a_412_is_a_precondition_failure_with_the_current_etag():
+    # Act
+    error = error_from_response(error_response(412, "content_precondition_failed", {"currentETag": '"v13"'}))
+
+    # Assert
+    assert isinstance(error, ContentPreconditionFailedError)
+    assert error.current_etag == '"v13"'
+
+
+def test_falls_back_to_status_and_headers_without_an_envelope():
+    # Arrange
+    response = json_response(502, "<html>Bad gateway</html>", {"Request-Id": "edge-9"})
+
+    # Act
+    error = error_from_response(response)
+
+    # Assert
+    assert (error.code, error.status, error.request_id) == ("content_http_error", 502, "edge-9")
+
+
+def test_unwrap_raises_for_a_generated_error_response():
+    # Arrange
+    from tutorflow_content import unwrap
+
+    class Detailed:
+        status_code = 404
+        content = b'{"error":{"code":"content_not_found","message":"Not found","status":404,"requestId":"r"}}'
+        headers = {}
+        parsed = None
+
+    # Act and Assert
+    with pytest.raises(ContentApiError) as raised:
+        unwrap(Detailed())
+    assert raised.value.code == "content_not_found"

tutorflow_content-0.1.0/tests/test_pagination.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from urllib.parse import parse_qs
+
+from tutorflow_content import create_client, paginate
+from tutorflow_content.generated.api.content_courses import content_resource_course_controller_list as list_courses
+from tutorflow_content.generated.api.content_generation import content_generation_controller_list_runs as list_runs
+
+from .conftest import API_KEY, BASE_URL, CLASSROOM_ID, ScriptedTransport, json_response
+
+COURSE = {
+    "classroomId": CLASSROOM_ID,
+    "title": "Fractions",
+    "description": None,
+    "thumbnail": None,
+    "slug": "fractions",
+    "level": None,
+    "visibility": "PRIVATE",
+    "createdAt": "2026-09-01T09:00:00.000Z",
+    "updatedAt": "2026-09-02T14:30:00.000Z",
+}
+
+
+def numbered_page(page: int, ids: list[str], has_next: bool) -> dict:
+    data = [{**COURSE, "id": course_id} for course_id in ids]
+    meta = {"page": page, "take": 2, "itemCount": 3, "pageCount": 2, "hasPreviousPage": page > 1, "hasNextPage": has_next}
+    return {"data": data, "meta": meta, "items": data, "totalCount": 3}
+
+
+def run(run_id: str) -> dict:
+    return {
+        "runId": run_id,
+        "kind": "course",
+        "classroomId": CLASSROOM_ID,
+        "status": "completed",
+        "stage": None,
+        "progress": {"completed": 1, "total": 1, "unit": "lesson"},
+        "resourceId": None,
+        "creditsCharged": 3,
+        "estimatedCredits": 3,
+        "error": None,
+        "resumedFromRunId": None,
+        "createdAt": "2026-09-01T09:00:00.000Z",
+        "finishedAt": None,
+    }
+
+
+def query(request) -> dict:
+    return {key: values[0] for key, values in parse_qs(request.url.query.decode()).items()}
+
+
+def test_walks_a_page_numbered_list_with_the_next_page_number():
+    # Arrange
+    ids = ["3f6c2a1e-7b4d-4c8e-9a10-00000000000" + str(index) for index in range(1, 4)]
+    scripted = ScriptedTransport(
+        [json_response(200, numbered_page(1, ids[:2], True)), json_response(200, numbered_page(2, ids[2:], False))]
+    )
+    client = create_client(API_KEY, base_url=BASE_URL, transport=scripted.transport)
+
+    # Act
+    courses = list(
+        paginate(lambda **next: list_courses.sync_detailed(CLASSROOM_ID, client=client, limit=2, **next))
+    )
+
+    # Assert
+    assert [str(course.id) for course in courses] == ids
+    assert [query(request).get("page") for request in scripted.requests] == ["1", "2"]
+
+
+def test_walks_a_cursor_list_by_sending_next_cursor_back():
+    # Arrange
+    first = {"data": [run("3f6c2a1e-7b4d-4c8e-9a10-000000000001")], "meta": {"limit": 1, "hasNextPage": True, "nextCursor": "opaque-1"}}
+    last = {"data": [run("3f6c2a1e-7b4d-4c8e-9a10-000000000002")], "meta": {"limit": 1, "hasNextPage": False, "nextCursor": None}}
+    scripted = ScriptedTransport([json_response(200, first), json_response(200, last)])
+    client = create_client(API_KEY, base_url=BASE_URL, transport=scripted.transport)
+
+    # Act
+    runs = list(paginate(lambda **next: list_runs.sync_detailed(CLASSROOM_ID, client=client, limit=1, **next)))
+
+    # Assert
+    assert len(runs) == 2
+    assert "cursor" not in query(scripted.requests[0])
+    assert query(scripted.requests[1])["cursor"] == "opaque-1"
+
+
+def test_reads_plain_dict_pages_too():
+    # Arrange
+    pages = iter([{"data": [1, 2], "meta": {"hasNextPage": True, "nextCursor": "c"}}, {"data": [3], "meta": {"hasNextPage": False, "nextCursor": None}}])
+    seen: list[dict] = []
+
+    def fetch(**next):
+        seen.append(next)
+        return next_page()
+
+    next_page = lambda: next(pages)  # noqa: E731
+
+    # Act
+    items = list(paginate(fetch))
+
+    # Assert
+    assert items == [1, 2, 3]
+    assert seen == [{}, {"cursor": "c"}]

tutorflow_content-0.1.0/tests/test_retry.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from tutorflow_content import RetryConfig, RetryTransport, create_client, new_idempotency_key, unwrap
+from tutorflow_content.generated.api.content_classrooms import content_integration_classroom_controller_list_classrooms as list_classrooms
+
+from .conftest import API_KEY, BASE_URL, ScriptedTransport, error_response, json_response
+
+
+def client_with(scripted: ScriptedTransport, sleep, **config):
+    transport = RetryTransport(scripted.transport, RetryConfig(random=lambda: 0.5, **config), sleep=sleep)
+    return httpx.Client(base_url=BASE_URL, transport=transport)
+
+
+def test_waits_out_retry_after_on_429_and_sends_again(sleep):
+    # Arrange
+    scripted = ScriptedTransport([error_response(429, "content_rate_limit_exceeded", headers={"Retry-After": "2"}), json_response(200, [])])
+    client = client_with(scripted, sleep)
+
+    # Act
+    response = client.get("/v1/content/classrooms")
+
+    # Assert
+    assert response.status_code == 200
+    assert sleep.delays == [2.0]
+    assert len(scripted.requests) == 2
+
+
+def test_reuses_the_idempotency_key_and_body_after_a_503(sleep):
+    # Arrange
+    scripted = ScriptedTransport([error_response(503, "content_internal_error"), json_response(202, {"runId": "r1"})])
+    client = client_with(scripted, sleep)
+
+    # Act
+    response = client.post("/v1/content/x", json={"topic": "Fractions"}, headers={"Idempotency-Key": "key-1"})
+
+    # Assert
+    assert response.status_code == 202
+    assert [request.headers["Idempotency-Key"] for request in scripted.requests] == ["key-1", "key-1"]
+    assert scripted.requests[1].content == b'{"topic":"Fractions"}'
+    assert sleep.delays == [0.25]
+
+
+def test_does_not_repeat_a_post_without_a_key_after_a_500(sleep):
+    # Arrange
+    scripted = ScriptedTransport([error_response(500, "content_internal_error")])
+    client = client_with(scripted, sleep)
+
+    # Act
+    response = client.post("/v1/content/x", json={})
+
+    # Assert
+    assert response.status_code == 500
+    assert len(scripted.requests) == 1
+
+
+def test_retries_a_get_after_a_network_failure_then_gives_up(sleep):
+    # Arrange
+    failure = httpx.ConnectError("refused")
+    scripted = ScriptedTransport([failure, failure, failure])
+    client = client_with(scripted, sleep, max_retries=2)
+
+    # Act and Assert
+    with pytest.raises(httpx.ConnectError):
+        client.get("/v1/content/classrooms")
+    assert len(scripted.requests) == 3
+
+
+def test_hands_back_a_429_that_asks_for_too_long_a_wait(sleep):
+    # Arrange
+    scripted = ScriptedTransport([error_response(429, "content_rate_limit_exceeded", headers={"Retry-After": "120"})])
+    client = client_with(scripted, sleep)
+
+    # Act
+    response = client.get("/v1/content/classrooms")
+
+    # Assert
+    assert response.status_code == 429
+    assert sleep.delays == []
+
+
+def test_create_client_sends_the_bearer_key_through_the_generated_calls():
+    # Arrange
+    scripted = ScriptedTransport([json_response(200, [{"id": "3f6c2a1e-7b4d-4c8e-9a10-0000000c0001", "name": "Grade 5 maths", "slug": "grade-5-maths", "locale": "en", "isSandbox": True}])])
+    client = create_client(API_KEY, base_url=f"{BASE_URL}/", transport=scripted.transport, retry=None)
+
+    # Act
+    classrooms = unwrap(list_classrooms.sync_detailed(client=client))
+
+    # Assert
+    assert classrooms[0].name == "Grade 5 maths"
+    assert scripted.requests[0].headers["Authorization"] == f"Bearer {API_KEY}"
+    assert str(scripted.requests[0].url) == f"{BASE_URL}/v1/content/classrooms"
+
+
+def test_create_client_refuses_a_value_that_is_not_a_content_api_key():
+    # Act and Assert
+    with pytest.raises(ValueError):
+        create_client("sk_live_wrong")
+
+
+def test_new_idempotency_key_is_a_fresh_uuid():
+    # Act
+    first, second = new_idempotency_key(), new_idempotency_key()
+
+    # Assert
+    assert first != second
+    assert len(first) == 36