jamframe 0.1.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.
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .pytest_cache/
4
+ .mypy_cache/
5
+ .venv/
6
+ venv/
7
+ dist/
8
+ build/
9
+ *.egg-info/
@@ -0,0 +1,21 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ The first release.
6
+
7
+ - Render templates to PNG, JPEG, WebP, PDF and MP4: carousels, Smart Resize
8
+ (one size or several), translation, link lifetimes (`expires_in`), and the
9
+ experimental PDF options `cmyk` and `compress`.
10
+ - Render jobs: `render_async`, `render_and_wait`, `render_jobs.get` and `wait`.
11
+ - Templates: list, search and get your own and the template library's;
12
+ design new ones with AI (`designs.generate`, `generate_async`, `design_jobs`).
13
+ - The render log, signed render URLs.
14
+ - Workflows: list, get, create, update, delete, run (and wait), runs, cancel,
15
+ a new incoming webhook URL.
16
+ - Social: accounts, posts (create, list, get, cancel, retry) and analytics
17
+ (overview, daily, insights).
18
+ - AI tools: remove a background, transcribe speech into subtitles, AI status.
19
+ - Webhook subscriptions, and signature checks for deliveries
20
+ (`construct_event`, `verify_signature`).
21
+ - Sync and async clients, typed errors, retries for rate limits and safe calls.
jamframe-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Alphacloud Technologies Pte Ltd
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,510 @@
1
+ Metadata-Version: 2.5
2
+ Name: jamframe
3
+ Version: 0.1.0
4
+ Summary: Python client for the JamFrame API: render templates to images, carousels, PDFs and videos, design templates with AI, run workflows and post to social accounts.
5
+ Project-URL: Homepage, https://jamframe.com/
6
+ Project-URL: Documentation, https://app.jamframe.com/docs/api
7
+ Project-URL: Repository, https://github.com/JamFrame-com/jamframe-python
8
+ Project-URL: Issues, https://github.com/JamFrame-com/jamframe-python/issues
9
+ Project-URL: Changelog, https://github.com/JamFrame-com/jamframe-python/blob/main/CHANGELOG.md
10
+ Author-email: Alphacloud Technologies Pte Ltd <hello@jamframe.com>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: api client,carousel,image generation,jamframe,pdf,social media,templates,video
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Programming Language :: Python :: 3.14
25
+ Classifier: Typing :: Typed
26
+ Requires-Python: >=3.9
27
+ Requires-Dist: httpx<1,>=0.24
28
+ Provides-Extra: dev
29
+ Requires-Dist: mypy>=1.5; extra == 'dev'
30
+ Requires-Dist: pytest>=7; extra == 'dev'
31
+ Requires-Dist: pyyaml>=6; extra == 'dev'
32
+ Description-Content-Type: text/markdown
33
+
34
+ # jamframe (Python)
35
+
36
+ The Python client for the [JamFrame](https://jamframe.com) API: render your
37
+ templates to images, carousels, PDFs and MP4 videos, design new templates
38
+ with AI, run workflows, post to social accounts and read their analytics,
39
+ and verify webhooks.
40
+
41
+ - Python 3.9 or later. One dependency: [httpx](https://www.python-httpx.org/).
42
+ - Sync (`Client`) and async (`AsyncClient`) clients with the same methods.
43
+ - Fully typed (`py.typed`, `TypedDict` for every API shape, `mypy --strict` clean).
44
+ - Retries 429s (honouring `Retry-After`) and, for idempotent calls only,
45
+ 5xx answers, connection errors and timeouts.
46
+
47
+ API reference: [app.jamframe.com/docs/api](https://app.jamframe.com/docs/api)
48
+ (the OpenAPI spec is [app.jamframe.com/openapi.yaml](https://app.jamframe.com/openapi.yaml)).
49
+ The [Node.js SDK](https://github.com/JamFrame-com/jamframe-node) has the same surface.
50
+
51
+ ## Install
52
+
53
+ ```sh
54
+ pip install jamframe
55
+ ```
56
+
57
+ ## Quick start
58
+
59
+ Create an API key in the app under **Developers → API Keys** (it starts with
60
+ `jf_live_`), then:
61
+
62
+ ```python
63
+ from jamframe import Client
64
+
65
+ client = Client(api_key="jf_live_...") # or set JAMFRAME_API_KEY
66
+
67
+ result = client.render(
68
+ "clx8m2k3p0001abcd1234efgh", # a template id (yours or a library one)
69
+ {"title": "Summer sale ends Sunday", "title.color": "#FF4D4F"},
70
+ response={"format": "png", "scale": 2},
71
+ )
72
+ print(result["data"]["content"]) # the image URL
73
+ print(result["data"]["credits"]) # 1
74
+ print(result["warnings"]) # e.g. modification keys that matched nothing
75
+ ```
76
+
77
+ `Client()` with no arguments reads `JAMFRAME_API_KEY` and, if set,
78
+ `JAMFRAME_BASE_URL`. `base_url` is the API's origin
79
+ (`https://api.jamframe.com`) or its root (`…/v1`); both work, and so does
80
+ the older `https://app.jamframe.com/api/v1`.
81
+
82
+ Use it as a context manager (or call `close()`) to release connections:
83
+
84
+ ```python
85
+ with Client() as client:
86
+ print(client.whoami()) # {'workspaceId': '…', 'username': 'Jane Doe'}
87
+ ```
88
+
89
+ ## Templates
90
+
91
+ ```python
92
+ # Your workspace's templates, newest first (one page).
93
+ page = client.designs.list(limit=25)
94
+ page["designs"], page["pagination"]["nextCursor"]
95
+
96
+ # Every template, page after page.
97
+ for design in client.designs.iter():
98
+ print(design["id"], design["name"], design["orientation"])
99
+
100
+ # The template library (ready-made templates any workspace can render).
101
+ for design in client.designs.iter(source="library"):
102
+ ...
103
+
104
+ # A picker's search box: names containing the text, ignoring case (either source).
105
+ # Each design has its page count and `animated` (a video template: render it as mp4).
106
+ for design in client.designs.iter(source="library", q="reel"):
107
+ print(design["name"], design["pages"], "video" if design["animated"] else "still")
108
+
109
+ # What a template takes: parameters (keys for `modifications`), page count, saved sizes.
110
+ detail = client.designs.get("clx8m2k3p0002abcd1234efgh")
111
+ for p in detail["parameters"]:
112
+ print(p["key"], p["type"], p["pages"], p["example"])
113
+ ```
114
+
115
+ Modification keys: `title` sets every layer (and `{{title}}` placeholder)
116
+ with that key, `page2@title` only on page 2, `title.color` overrides a style
117
+ property, `page2@title.color` both. See the API reference for the full list
118
+ (`fontSize`, `hidden`, `fill`, `audio`, `audio.volume`, `subtitles`, …).
119
+
120
+ ### Design a template with AI
121
+
122
+ ```python
123
+ # Waits for the design (usually 10–40 s); 15 to 30 AI credits, refunded if it fails.
124
+ job = client.designs.generate(
125
+ "Announce our summer sale, 30% off everything this weekend. Bold and playful.",
126
+ size="instagram-portrait", # or "linkedin-carousel" with pages=5, or "1200x630"
127
+ # brand=False, or {"colors": ["#0b1f4d", "#ff6b5b"], "fonts": ["Poppins"]}; default: your brand library
128
+ )
129
+ job["design"]["id"] # render it like any other template
130
+ job["design"]["parameters"] # [{'key': 'title', …}, {'key': 'photo', …}]
131
+ job["design"]["editorUrl"] # open it in the editor
132
+
133
+ # Or start it and come back later (webhook_url= is called when it ends).
134
+ started = client.designs.generate_async("A teaser video for our app launch", video=True)
135
+ done = client.design_jobs.wait(started["jobId"])
136
+ ```
137
+
138
+ A failed generation raises `DesignJobFailedError` (`.code`, `.message`, `.job`).
139
+
140
+ ## Rendering
141
+
142
+ Credits: 1 per image or PDF page, 1 per second of video (rounded up),
143
+ charged only when a render succeeds.
144
+
145
+ ```python
146
+ # A carousel: one URL per page.
147
+ r = client.render("tpl_id", {"title": "5 ways to brew", "page2@title": "1. Grind fresh"},
148
+ response={"format": "jpeg", "quality": 90})
149
+ r["data"]["content"] # ['https://…-p1.jpg', 'https://…-p2.jpg', …]
150
+
151
+ # A library template by its slug, as a PDF of pages 1 and 2, with links that work for an hour.
152
+ client.render("tool-quote-card-paper", {"quote": "Stay curious"},
153
+ response={"format": "pdf", "includePages": [1, 2]}, expires_in=3600)
154
+
155
+ # Smart Resize: one size …
156
+ client.render("tpl_id", {"title": "Hi"}, response={"format": "png", "size": "story"})
157
+ # … or several in one call (content is one entry per size).
158
+ r = client.render("tpl_id", {"title": "Hi"}, response={"sizes": ["original", "story", "1200x630"]})
159
+ for entry in r["data"]["content"]:
160
+ print(entry["size"], entry["width"], entry["height"], entry.get("url") or entry.get("urls"))
161
+ r["data"]["urls"] # every file's link in one list
162
+
163
+ # Translate every text layer with AI (AI credits; cached per text and language).
164
+ client.render("tpl_id", translate=True, lang="es", ai={"onError": "fallback"})
165
+ ```
166
+
167
+ `jamframe.file_urls(content)` flattens any `content` (a URL, a list of URLs
168
+ or the per-size entries) into a list of URLs. File links work for
169
+ `expires_in` seconds (5 minutes by default, at most 7 days;
170
+ `data["expiresAt"]` says until when).
171
+
172
+ **Experimental, PDF only:** `response={"format": "pdf", "cmyk": True}` (or
173
+ `{"profile": "gracol2013"}`) converts the colours to CMYK for print, and
174
+ `"compress": True` (or `{"preset": "printer"}`) makes the file smaller.
175
+ Their options and output may still change.
176
+
177
+ ### Videos and render jobs
178
+
179
+ MP4 renders, and any render sent as `async`, run as **render jobs**.
180
+
181
+ ```python
182
+ # Simplest: render() waits. The API answers an MP4 within 90 s, or hands
183
+ # back a job, which render() then polls (up to wait_timeout seconds).
184
+ video = client.render("tpl_id", {"title": "New menu"}, response={"format": "mp4"})
185
+ video["data"]["content"], video["data"]["duration"]
186
+
187
+ # Queue it and get the job id at once …
188
+ job = client.render_async("tpl_id", {"title": "New menu"}, response={"format": "mp4"},
189
+ webhook_url="https://example.com/hooks/render-done")
190
+ job["jobId"] # poll it, or wait for the webhook_url callback
191
+
192
+ # … poll it yourself …
193
+ client.render_jobs.get(job["jobId"])["progress"] # 0 to 1
194
+
195
+ # … or wait for it (polls every 1 s, then 1.5x longer each time, at most 5 s).
196
+ done = client.render_jobs.wait(job["jobId"], timeout=600)
197
+ done["result"]["content"]
198
+
199
+ # Queue and wait in one call.
200
+ done = client.render_and_wait("tpl_id", {"title": "New menu"}, response={"format": "mp4"})
201
+ ```
202
+
203
+ A failed job raises `RenderJobFailedError` (`.code`, `.message`, `.job`;
204
+ failed renders cost nothing). Running past the timeout raises
205
+ `WaitTimeoutError` (`.job_id`, `.last_job`); the job keeps running, so you
206
+ can wait again.
207
+
208
+ The `webhook_url` callback is not signed. Treat it as a hint and fetch the
209
+ job with `render_jobs.get()` before trusting it, or subscribe to the signed
210
+ `render.completed` / `render.failed` webhook events instead.
211
+
212
+ ## Render log
213
+
214
+ ```python
215
+ page = client.renders.list(status="failed", limit=10)
216
+ page["totals"]["creditsRemaining"] # this billing period
217
+ for render in client.renders.iter(design_id="tpl_id"):
218
+ print(render["id"], render["status"], [o["url"] for o in render["outputs"]])
219
+
220
+ # One render by id (the `renderId` of a render, or of a job's `result`).
221
+ render = client.renders.get(result["data"]["renderId"])
222
+ render["status"], render["credits"], render["outputs"]
223
+ ```
224
+
225
+ ## Signed URLs
226
+
227
+ A tamper-proof link that renders when opened, for `<img src>`, emails and
228
+ `og:image`. Creating it is free; opening it renders (and caches) the image.
229
+
230
+ ```python
231
+ signed = client.signed_urls.create("tpl_id", {"title": "How we cut render times"},
232
+ response={"format": "png"}, expires_in=30 * 24 * 3600)
233
+ signed["data"]["url"]
234
+
235
+ client.signed_urls.rotate_key() # revoke every signed URL of the workspace
236
+ ```
237
+
238
+ ## Workflows
239
+
240
+ Workflows render a template for each row of a Google Sheet, a CSV or XLSX
241
+ file, an Airtable table or a webhook, and deliver the files. Build them in
242
+ the app (or with `workflows.create()`), then run them from code.
243
+
244
+ ```python
245
+ workflows = client.workflows.list()
246
+
247
+ # Run one and wait for it to end; each row costs render credits.
248
+ run = client.workflows.run_and_wait(workflows[0]["id"], max_rows=2) # a test run
249
+ run["status"] # 'succeeded', 'partial', 'failed' or 'canceled' (check it)
250
+ [row["urls"] for row in run["rows"]] # each row's files
251
+
252
+ # A webhook-payload source: send the rows yourself.
253
+ client.workflows.run("wf_id", payload=[{"Quote": "Stay curious", "Author": "Ada"}])
254
+
255
+ for r in client.workflows.runs.iter("wf_id"):
256
+ print(r["id"], r["status"])
257
+ client.workflows.runs.cancel("wf_id", "run_id")
258
+ client.workflows.update("wf_id", status="active") # turns on its schedule or trigger
259
+ ```
260
+
261
+ ## Social posts
262
+
263
+ Accounts are connected in the app, which shows the networks you can
264
+ connect. Posting costs no credits; a template render costs the usual credits.
265
+
266
+ ```python
267
+ accounts = client.social.accounts.list()
268
+ ids = [a["id"] for a in accounts if a["status"] == "active"]
269
+
270
+ created = client.social.posts.create(
271
+ template_id="tpl_id",
272
+ modifications={"title": "Spring sale"},
273
+ response={"format": "jpeg"},
274
+ accounts=ids,
275
+ caption="Spring sale starts today #sale",
276
+ scheduled_at="2026-11-10T09:00",
277
+ timezone="Europe/Paris",
278
+ # options={"pinterest": {"boardId": "…"}, "tiktok": {"draft": True}, "buffer": {"mode": "next"}},
279
+ )
280
+ post = created["post"] # created["checks"]: per-account warnings
281
+
282
+ client.social.posts.get(post["id"])["targets"] # each account's status and permalink
283
+ client.social.posts.list(status="attention") # failed or partly failed
284
+ client.social.posts.cancel(post["id"])
285
+ client.social.posts.retry(post["id"]) # or target_id="…" for one account
286
+ ```
287
+
288
+ `create()` takes the API body as a dict, as keyword arguments, or both;
289
+ `template_id`, `render_id`, `media_urls` and `scheduled_at` are accepted for
290
+ `templateId`, `renderId`, `mediaUrls` and `scheduledAt`.
291
+
292
+ ### Analytics
293
+
294
+ ```python
295
+ import datetime
296
+
297
+ overview = client.social.analytics.overview(from_=datetime.date(2026, 10, 1), to="2026-10-31",
298
+ platform=["instagram", "linkedin"])
299
+ overview["totals"]["impressions"], overview["change"]["engagement"] # change in % from the period before
300
+ days = client.social.analytics.daily(from_="2026-10-01")["days"]
301
+ insights = client.social.analytics.insights()
302
+ insights["bestTimes"]["bestWeekday"], insights["bestTimes"]["bestHour"]
303
+ ```
304
+
305
+ A metric is `None` when the platforms in scope don't report it. (`from_` has
306
+ an underscore because `from` is a Python keyword.)
307
+
308
+ ## AI tools
309
+
310
+ ```python
311
+ from pathlib import Path
312
+
313
+ # Cut the subject out of a picture (a URL or a file); a transparent PNG in your brand library. 1 AI credit.
314
+ cutout = client.ai.remove_background(file=Path("product.jpg"))
315
+ client.render("tpl_id", {"photo": cutout["url"]})
316
+
317
+ # Subtitles from speech (a URL or a file, up to 100 MB). 1 AI credit per minute of audio.
318
+ subs = client.ai.transcribe(url="https://example.com/voiceover.mp3", style="short")
319
+ client.render("tpl_id", {"subtitles": subs["cues"]}, response={"format": "mp4"})
320
+
321
+ # Whether AI is available, the prices and your AI credits this period. Free.
322
+ client.ai.status()["credits"]["remaining"]
323
+ ```
324
+
325
+ `file=` takes bytes, a `pathlib.Path` or a file opened in binary mode
326
+ (`open("product.jpg", "rb")`).
327
+
328
+ ## Webhooks
329
+
330
+ Subscribe a URL to events (`design.created`, `design.updated`,
331
+ `design.deleted`, `render.completed`, `render.failed`,
332
+ `social.post.published`, `social.post.failed`, `workflow.run.completed`,
333
+ `workflow.run.failed`):
334
+
335
+ ```python
336
+ created = client.webhooks.subscriptions.create(
337
+ "https://example.com/hooks/jamframe", ["render.completed", "render.failed"]
338
+ )
339
+ secret = created["signingSecret"] # shown once: store it
340
+ client.webhooks.subscriptions.test(created["subscription"]["id"], "render.completed")
341
+ client.webhooks.subscriptions.delete(created["subscription"]["id"])
342
+ ```
343
+
344
+ Verify every delivery against the **raw** body:
345
+
346
+ ```python
347
+ # Flask
348
+ from flask import Flask, request, abort
349
+ from jamframe import WebhookSignatureError, construct_event
350
+
351
+ app = Flask(__name__)
352
+
353
+ @app.post("/hooks/jamframe")
354
+ def jamframe_hook():
355
+ try:
356
+ event = construct_event(request.get_data(), request.headers, SECRET)
357
+ except WebhookSignatureError:
358
+ abort(400)
359
+ # Deliveries are at-least-once: deduplicate on request.headers["X-Webhook-Delivery"].
360
+ if event["type"] == "render.completed":
361
+ print(event["data"]["result"]["content"])
362
+ return "", 204
363
+ ```
364
+
365
+ ```python
366
+ # FastAPI
367
+ from fastapi import FastAPI, HTTPException, Request
368
+ from jamframe import verify_signature
369
+
370
+ app = FastAPI()
371
+
372
+ @app.post("/hooks/jamframe")
373
+ async def jamframe_hook(request: Request):
374
+ body = await request.body()
375
+ if not verify_signature(body, request.headers.get("x-webhook-signature", ""), SECRET):
376
+ raise HTTPException(400)
377
+ ...
378
+ ```
379
+
380
+ `verify_signature(payload, header, secret, tolerance=300)` returns a bool;
381
+ `construct_event` raises `WebhookSignatureError` and returns the parsed event.
382
+ `header` is the `X-Webhook-Signature` value or the request's headers;
383
+ `secret` may be a list (old and new while you rotate). Signatures older or
384
+ newer than `tolerance` seconds are refused (replay protection).
385
+
386
+ ## Errors
387
+
388
+ Every error answer raises a subclass of `jamframe.APIError` with `status`,
389
+ `code` (the API's `error`, e.g. `QUOTA_EXCEEDED`), `message` (safe to show
390
+ to users) and `detail`:
391
+
392
+ | Status | Exception | Typical `code` |
393
+ | --- | --- | --- |
394
+ | 400 | `BadRequestError` | `VALIDATION_ERROR`, `INVALID_REQUEST`, `WEBHOOK_URL_INVALID` |
395
+ | 401 | `AuthenticationError` | `MISSING_API_KEY`, `INVALID_API_KEY`, `EXPIRED_API_KEY` |
396
+ | 402 | `PaymentRequiredError` | `QUOTA_EXCEEDED`, `WORKSPACE_QUOTA_EXCEEDED`, `AI_CREDITS_EXCEEDED`, `PLAN_LIMIT_EXCEEDED`, `WEBHOOK_LIMIT_REACHED` |
397
+ | 403 | `PermissionDeniedError` | `ORG_ON_HOLD`, `ORG_SUSPENDED` |
398
+ | 404 | `NotFoundError` | `NOT_FOUND` |
399
+ | 409 | `ConflictError` | `CONFLICT` |
400
+ | 422 | `UnprocessableEntityError` | `VALIDATION_ERROR` (a media URL that won't load), `AI_CONTENT_REFUSED`, `AI_BAD_REQUEST` |
401
+ | 429 | `RateLimitError` (`.retry_after`) | `RATE_LIMITED`, `AI_RATE_LIMITED` |
402
+ | 5xx | `InternalServerError` | `INTERNAL`, `AI_BAD_OUTPUT`, `AI_UPSTREAM_ERROR`, `AI_UNAVAILABLE`, `VIDEO_UNAVAILABLE`, `AI_TIMEOUT` |
403
+
404
+ A body that isn't the API's JSON envelope (a proxy's HTML page) still
405
+ raises the right class, with `code` `HTTP_<status>`. Network failures raise
406
+ `APIConnectionError`, timeouts `APITimeoutError`. A failed render job raises
407
+ `RenderJobFailedError`, a failed AI design `DesignJobFailedError`, a wait
408
+ past its timeout `WaitTimeoutError`. Everything derives from
409
+ `jamframe.SDKError`.
410
+
411
+ ```python
412
+ from jamframe import PaymentRequiredError, BadRequestError
413
+
414
+ try:
415
+ client.render("tpl_id", {"titel": "typo is a warning, not an error"})
416
+ except PaymentRequiredError as e:
417
+ print("Out of credits:", e.detail.get("remaining"))
418
+ except BadRequestError as e:
419
+ print(e.code, e.message, e.detail.get("issues"))
420
+ ```
421
+
422
+ ## Retries and timeouts
423
+
424
+ - **429** is retried for every call (`max_retries`, default 2): the rate
425
+ limiter refuses a request before anything happens. The client waits for
426
+ `Retry-After` (or `detail.retryAfter`); if that's over 60 s it raises
427
+ `RateLimitError` instead.
428
+ - **5xx, connection errors and timeouts** are retried only for idempotent
429
+ calls: reads, deletes, `whoami()`, `signed_urls.create()` and
430
+ `workflows.update()`. A render, an AI call, a social post, a workflow run
431
+ or a subscription isn't retried: it may have happened before the error.
432
+ - Backoff is 0.5 s, 1 s, 2 s … (at most 8 s), with jitter.
433
+ - `timeout` (default 120 s) is per HTTP request. It must cover a synchronous
434
+ MP4, which the API holds for up to 90 s. Waiting for a job has its own
435
+ `timeout` / `wait_timeout` (default 600 s).
436
+
437
+ ```python
438
+ client = Client(timeout=30, max_retries=4, user_agent="my-app/1.2")
439
+ ```
440
+
441
+ `user_agent` is prepended to `jamframe-python/<version>`. Pass
442
+ `http_client=httpx.Client(...)` (or `httpx.AsyncClient` for the async
443
+ client) for proxies, custom TLS or transports; the SDK won't close a client
444
+ you pass in.
445
+
446
+ ## Async
447
+
448
+ ```python
449
+ import asyncio
450
+ from jamframe import AsyncClient
451
+
452
+ async def main():
453
+ async with AsyncClient() as client:
454
+ job = await client.render_and_wait("tpl_id", {"title": "Hi"}, response={"format": "mp4"})
455
+ async for design in client.designs.iter(source="library"):
456
+ print(design["name"])
457
+
458
+ asyncio.run(main())
459
+ ```
460
+
461
+ ## Why httpx
462
+
463
+ One dependency buys a lot here: the same request code drives a sync and an
464
+ async client, timeouts are real (connect, read, write and pool), connections
465
+ are pooled and kept alive across calls, and `httpx.MockTransport` lets the
466
+ tests run the real client code against a fake API with no server. The
467
+ standard library's `urllib` has no async client, no keep-alive pooling and
468
+ coarse timeouts, so it would mean either a sync-only SDK or a second HTTP
469
+ stack for async.
470
+
471
+ ## Development
472
+
473
+ ```sh
474
+ uv sync --extra dev # or: python -m venv .venv && pip install -e ".[dev]"
475
+ uv run pytest # unit tests (no network: httpx.MockTransport)
476
+ uv run mypy # strict type check of src/jamframe
477
+ ```
478
+
479
+ `tests/test_spec.py` checks the SDK against the API spec in
480
+ [`spec/openapi.yaml`](spec/openapi.yaml): every endpoint has a method (or is
481
+ skipped on purpose), the types have exactly the spec's fields and enum
482
+ values, and the async client has the same methods as the sync one.
483
+ `python scripts/update_spec.py` downloads the live spec; CI does that every
484
+ Monday, so a new API feature shows up as a failing check.
485
+
486
+ The live smoke test runs only when `JAMFRAME_SMOKE_API_KEY` is set. It
487
+ renders 2 PNGs of a library template (2 credits), lists designs and
488
+ renders, signs a URL, reads AI status, workflows and analytics, creates and
489
+ deletes a webhook subscription, and posts to an active *sandbox* social
490
+ account if the workspace has one:
491
+
492
+ ```sh
493
+ JAMFRAME_SMOKE_API_KEY=jf_live_... JAMFRAME_SMOKE_BASE_URL=https://api.jamframe.com \
494
+ uv run pytest tests/test_live_smoke.py -s
495
+ ```
496
+
497
+ Use a throwaway key and revoke it afterwards.
498
+
499
+ ## Releasing
500
+
501
+ 1. Update `version` in `pyproject.toml` and `src/jamframe/_version.py` (a
502
+ test checks they match) and add the release to [CHANGELOG.md](CHANGELOG.md).
503
+ 2. Commit, then tag the commit with the bare version (`0.1.1`) and push the tag.
504
+ 3. [`publish.yml`](.github/workflows/publish.yml) runs the checks, builds,
505
+ publishes to TestPyPI, then (after approval in the `pypi` environment)
506
+ to PyPI, through trusted publishing: no token is stored anywhere.
507
+
508
+ ## License
509
+
510
+ [MIT](LICENSE)