image2ppt 0.5.3 → 0.7.0

package/README.md

@@ -45,6 +45,40 @@ const done = await client.wait(job.jobId, { pollIntervalMs: 5000, timeoutMs: 1_8
 await client.download(done.jobId, "out.pptx");
 ```
 
+Show progress to your own users — `onProgress` is called after every status poll
+(the last one included) with the fresh `Job` and the milliseconds elapsed since
+`wait` started. `convert` and `convertAll` take it too.
+
+```ts
+const done = await client.wait(job.jobId, {
+  onProgress: (job) => {
+    if (job.queueAhead != null) {
+      console.log(`queued, ${job.queueAhead} job(s) ahead`);
+    } else if (job.estimatedRemainingSeconds != null) {
+      console.log(`${job.progress}% — about ${job.estimatedRemainingSeconds}s left`);
+    } else {
+      console.log(`${job.progress ?? 0}% — estimating…`);
+    }
+  },
+});
+```
+
+While a job is running, each snapshot carries:
+
+- `progress` — the whole job, 0–100. It moves within a page, so a one-page job
+  climbs steadily instead of jumping from 0 to 100.
+- `pageProgress` — one `{ pageNumber, progress, stepLabel }` per page.
+  `stepLabel` is a short line about what that page is doing right now, in the
+  language of `acceptLanguage` (English by default), or `null`. Show it as-is and
+  never branch on it: its wording changes as the service changes.
+- `estimatedRemainingSeconds` — the service's estimate of the time left. It can be
+  `null` while the job runs, when no estimate is available yet.
+- `queueAhead` — jobs ahead of this one while it waits to start.
+
+`pageProgress`, `estimatedRemainingSeconds` and `queueAhead` are `null` once
+the job has ended. A returned promise is
+awaited before the next poll, and anything the callback throws ends the wait.
+
 Cancel a job you no longer need:
 
 ```ts
@@ -72,10 +106,195 @@ subclass of `JobFailedError`). `JobAlreadyFinishedError` covers both a job that
 finished on its own and one already past the point where cancelling could change the
 outcome.
 
+## Task names — `name`
+
+```typescript
+const uploaded = await client.submit(["report.pdf"], { name: "Quarterly report" });
+const linked = await client.submitUrls(["https://example.com/report.pdf"], { name: "Quarterly report" });
+const converted = await client.convert(["report.pdf"], "local.pptx", { name: "Quarterly report" });
+console.log(converted.name); // resolved name, possibly "Quarterly report (2)"
+```
+
+`name` is optional on submissions and conversion calls, including `submitAll()` / `convertAll()`.
+Batch calls reuse it for each job; the service resolves each collision. It is the
+task name and the service's download filename, without `.pptx`. After invisible
+characters are removed and whitespace collapsed, it must be non-empty, at most
+60 Unicode characters and 180 UTF-8 bytes. Control characters and `/ \ : * ? " < > |`
+are forbidden, as are leading/trailing dots and Windows reserved names. An invalid
+name raises `InvalidNameError` with code `INVALID_NAME`. The service validates
+and normalizes name contents; the SDK sends the supplied string unchanged.
+
+Names already used by undeleted jobs in the same account get ` (2)`, ` (3)`, etc.
+The resolved name is on `Job.name` in create responses, `getJob()` and job lists;
+completion webhook payloads also include it. A rename on the website appears in
+later snapshots. Older servers that omit it give `null`. Without `name`, one
+input uses its cleaned filename without extension; multiple inputs or an unusable
+filename use `Slides YYYY-MM-DD HHMMSS UTC` at creation time.
+
+`name` participates in the `Idempotency-Key` fingerprint, compared after the
+service's cleanup. Reusing a key with a name that cleans up differently raises
+`IdempotencyKeyMismatchError`, just like changing other submission options; a name
+that differs only in what cleanup removes (extra spaces, invisible characters)
+replays the original job.
+
+`download()` writes to the caller's path and never uses the server name, so a task
+name cannot cause local filename collisions or overwrite other files. Existing
+files at your explicitly chosen path can still be replaced. `convertAll()` keeps
+`part-01.pptx`, `part-02.pptx`, ... naming regardless of task names.
+
+## Convert only some pages — `pages`
+
+```ts
+const job = await client.submit(["report.pdf"], { pages: "1-3, 7" });
+```
+
+Single pages and `start-end` ranges, separated by commas, counting from 1. Page numbers
+run across the **whole submission in order** — an image is one page, a PDF is its page
+count — so with a single PDF they are simply the PDF's own page numbers. Overlaps are
+merged, and the deck keeps the pages in ascending order.
+
+Only the selected pages are charged, and only they count towards the 50-page limit: a
+200-page PDF with `pages: "1-50"` is fine. The spelling is checked locally before
+anything is uploaded (`InvalidPagesError`); a page past the end comes back
+`PagesOutOfRangeError`.
+
+With a selection, `pageResults[i].pageNumber` is the page's place **in the deck**, not
+the number you selected: `pages: "3,7"` gives entries 1 and 2.
+
+## Submit by URL — `submitUrls`
+
+Instead of uploading, hand the service `https` links and it downloads them itself:
+
+```ts
+const job = await client.submitUrls(
+  ["https://example.com/slides/1.png", "https://example.com/report.pdf"],
+  { pages: "1-4" },
+);
+```
+
+Up to 50 links, converted in order into one deck, held to the same limits as uploads
+(35MB per file, 90MB together, 50 pages). File types are judged by content. Links must
+be `https` and resolve to public addresses; a link that is refused throws
+`InvalidUrlError`, a download that fails throws `UrlFetchFailedError` (worth retrying
+later — the other side may have been down), and for both `e.index` says which link,
+counting from 0.
+
+Downloading takes time, so `submitUrls` waits up to 180 seconds for an answer whatever
+the client's `timeoutMs`. One submission by URL per account can be in flight at a time;
+another gets `RateLimitedError`.
+
+## Get told when a job ends — `callbackUrl` and `verifyWebhook`
+
+Pass `callbackUrl` to any submit call and the service `POST`s to it when the job ends,
+instead of you polling:
+
+```ts
+const job = await client.submit(["slide1.png"], {
+  callbackUrl: "https://example.com/hooks/image2ppt",
+});
+```
+
+Every delivery is signed ([Standard Webhooks](https://www.standardwebhooks.com)). Check
+it with the **raw** request body and the signing secret from the Developer / API page:
+
+```ts
+import express from "express";
+import { verifyWebhook, WebhookVerificationError } from "image2ppt";
+
+// express.raw(), not express.json(): the signature is over the exact bytes received.
+app.post("/hooks/image2ppt", express.raw({ type: "application/json" }), (req, res) => {
+  let event;
+  try {
+    event = verifyWebhook(req.body, req.headers, process.env.IMAGE2PPT_WEBHOOK_SECRET!);
+  } catch (e) {
+    if (e instanceof WebhookVerificationError) return res.sendStatus(400);
+    throw e;
+  }
+  if (event.type === "job.completed") {
+    const job = event.job; // same shape as getJob()
+    // ...
+  } else if (event.type === "job.failed") {
+    // ...
+  }
+  // Ignore types you don't recognise — more may be added. Answer 2xx either way.
+  res.sendStatus(204);
+});
+```
+
+- **Pass the body exactly as received** — a `Buffer`, `Uint8Array` or string. Parsing
+  the JSON and serialising it again changes the bytes, and the signature will not match.
+  `headers` can be Node's `req.headers` or a fetch `Headers`.
+- **Answer 2xx within 10 seconds.** Anything else counts as a failure, and the service
+  retries: 6 attempts over about 8.5 hours (right away, then +1 min, +5 min, +30 min,
+  +2 h, +6 h). A retry of one delivery keeps its `event.id`, so use that to skip
+  duplicates.
+- **Timestamps more than 5 minutes off are refused**, either way, as protection against
+  replays (`toleranceSeconds` to change it).
+- A malformed secret, or a body your framework already parsed into an object, throws a
+  `TypeError` — those are mistakes in your receiver, so they are kept apart from a bad
+  delivery.
+- Rotating the secret is safe: for 24 hours the service signs with both the old and the
+  new one, and either verifies.
+
+`getJob()` reports how delivery is going in `job.callback` — `status` is `pending`,
+`delivered` or `failed` (all 6 attempts failed), with `attempts`, `lastResponseStatus`
+and the times of the last and next attempt.
+
+## Resubmitting safely — `idempotencyKey`
+
+Every submission carries an `Idempotency-Key`. If the same key comes back with the same
+request within 24 hours, the service returns the job it already created —
+`job.replayed` is `true` — instead of creating and charging for a second one.
+
+That is what lets this client **resend a submission whose outcome is unknown** — a
+dropped connection, a timeout, a 5xx — without risking a double charge. It does so by
+itself, always under the same key (see *How it works*). By default the key is a random
+UUID per call. Pass your own to extend the protection across calls, processes or
+restarts:
+
+```ts
+const job = await client.submit(paths, { idempotencyKey: `order-${order.id}` });
+```
+
+If a submission still fails, the key it used is on the error:
+
+```ts
+import { APIConnectionError, ServerError } from "image2ppt";
+
+try {
+  job = await client.submit(paths);
+} catch (e) {
+  if (!(e instanceof APIConnectionError || e instanceof ServerError)) throw e;
+  // Later, or from another process: safe for 24 hours, because the same files,
+  // options and key can never create a second job.
+  job = await client.submit(paths, { idempotencyKey: e.idempotencyKey });
+}
+```
+
+"The same request" means the same file bytes in the same order (or the same `urls`), and
+the same `locale`, `aspectRatio`, `pages` and `callbackUrl`. Reusing a key for a
+different request throws `IdempotencyKeyMismatchError`. Keys are 1–255 printable ASCII
+characters, shared by all API keys of the account.
+
+## List your jobs — `listJobs` / `iterJobs`
+
+```ts
+for await (const job of client.iterJobs({ createdFrom: "2026-10-01", createdTo: "2026-10-31" })) {
+  console.log(job.jobId, job.status, job.creditsUsed, job.creditsRefunded);
+}
+```
+
+Jobs submitted through the API, newest first; jobs deleted on the website are not
+listed. Dates are `YYYY-MM-DD` in UTC and both inclusive. `iterJobs` follows the pages
+for you; `listJobs` returns one page (`page.data`, `page.nextCursor`) if you want to page
+yourself — pass `nextCursor` back as `cursor`, `limit` is 1–100 (default 20). Each job
+has `getJob()`'s fields except `pageResults`. For reconciliation, add up `creditsUsed`
+(charged) and `creditsRefunded`.
+
 ## Which pages made it
 
 Once a job is terminal, `job.pageResults` says what happened to each page, in page
-order, one entry per page:
+order, one entry per page of the deck (with `pages`, per *selected* page):
 
 ```ts
 for (const page of done.pageResults ?? []) {
@@ -139,12 +358,12 @@ console.log(email, "credits:", credits);
 - **Async.** `submit` resolves with a job id immediately; conversion runs in the background. A single page typically takes ~2 minutes; 90% of jobs finish within 3.
 - **One job = one PPTX.** All files in a submission are merged into a single deck, in upload order.
 - **Billed per page.** 1 page = 1 credit, reserved at submit and settled on completion. If some pages fail but others succeed, the job still completes with the good pages and the failed pages' credits are refunded (`creditsRefunded`).
-- **Limits.** Each file ≤ 35MB; **the files in one request ≤ 45MB in total**; ≤ 50 pages per job (images count as 1, PDFs as their page count). All three are checked locally before upload — note the per-file limit is the *stricter* one, so a 40MB PDF is refused even though it fits a request. **The sizes counted are the ones that actually go on the wire**: image preparation happens first, then the final payload sizes drive pre-flight and batching. PDFs keep their on-disk size.
-- **The check is never stricter than the documented limit.** 45MB of file content is meant to be usable, so a submission sitting exactly on it goes through. Auto-batching is the one place that is deliberately conservative — it fills a batch only to 40MB, because starting one more batch costs nothing while refusing something the server would have accepted does not.
+- **Limits.** Each file ≤ 35MB; **the files in one request ≤ 90MB in total**; ≤ 50 pages per job (images count as 1, PDFs as their page count — or, with `pages`, the pages selected). All three are checked locally before upload — note the per-file limit is the *stricter* one, so a 40MB PDF is refused even though it fits a request. **The sizes counted are the ones that actually go on the wire**: image preparation happens first, then the final payload sizes drive pre-flight and batching. PDFs keep their on-disk size.
+- **The check is never stricter than the documented limit.** 90MB of file content is meant to be usable, so a submission sitting exactly on it goes through. Auto-batching is the one place that is deliberately conservative — it fills a batch only to 40MB, because starting one more batch costs nothing while refusing something the server would have accepted does not.
 - **Only the formats the API accepts.** `png`, `jpg`/`jpeg`, `webp`, `gif`, `pdf`. Anything else throws `InvalidFileError` locally — the batch calls check every file before submitting the first one, so an unsupported file at the end of the pile cannot leave you paying for the batches ahead of it.
-- **The local page check is a lower bound.** The client does not parse PDFs, so it counts each one as *at least* 1 page. That is enough to refuse combinations that can never work (50 images plus any PDF is already 51 pages), but a submission that passes locally can still come back `TOO_MANY_SLIDES` — a 30-page PDF counts as 1 here and 30 on the server.
+- **The local page check is a lower bound.** The client does not parse PDFs, so it counts each one as *at least* 1 page. That is enough to refuse combinations that can never work (50 images plus any PDF is already 51 pages), but a submission that passes locally can still come back `TOO_MANY_SLIDES` — a 30-page PDF counts as 1 here and 30 on the server. With `pages`, the check counts the pages selected instead, and a PDF longer than 50 pages is fine.
 - **Going over the request limit is not a polite error.** Past that the connection is cut before the API can answer, so the caller sees a write timeout or a broken pipe instead of a status code. The client therefore checks locally *before* uploading and throws `InvalidFileError` (`code: "PAYLOAD_TOO_LARGE"`) without sending a byte.
-- **A failed submission is never retried automatically.** A network error only tells you the exchange broke — not whether the request body arrived. The job may not exist, or it may exist with credits already reserved and only the response lost. Retrying the second case charges you twice, and there is no idempotency key to tell them apart, so the error is thrown as-is. Check `account()` or your job list before resending. (Rate limits *are* retried by `submitAll()` / `convertAll()`: a 429 is the server saying it did not take the submission.)
+- **A submission whose outcome is unknown is resent, under the same `Idempotency-Key`.** A network error only tells you the exchange broke — not whether the request body arrived; the job may exist with credits already reserved and only the response lost. Because every attempt carries the same key, a resend of that case gets the existing job back rather than a second charge. So `submit()` resends after a dropped connection, an idle timeout or a 5xx (up to 2 more attempts, 1s and 2s apart), and waits out `IdempotencyKeyInProgressError` — an earlier attempt the service is still working on — for up to 10 attempts or 3 minutes. Any other error is thrown straight away. Whatever finally escapes carries `e.idempotencyKey`; see *Resubmitting safely*.
 - **Downloads are all-or-nothing.** `download()` writes to a temporary file next to the destination and renames it into place at the end, so a dropped connection cannot leave a truncated `.pptx` behind — or destroy a good deck already sitting at that path.
 - **Every request identifies the client** with a `User-Agent` of `image2ppt-node/<version>`. The service uses this to tell SDK versions apart — it is not part of authentication and never changes a request's outcome.
 - **A deprecated SDK version logs one warning.** If this version is below the lowest the service still supports, the response carries a `Deprecation` header and the client warns once (`console.warn`). Pass `warnOnDeprecated: false` to `Image2PPTClient` to silence it.
@@ -152,7 +371,7 @@ console.log(email, "credits:", credits);
 - **The 60-second request timeout is idle time, not total time.** `timeoutMs` (default 60000) is how long one request may go with **no data moving in either direction** — it is not a cap on how long a request may take. A 40MB upload or a large PPTX download that keeps making progress runs as long as it needs to; only a transfer that actually stalls is given up on, as `APITimeoutError`. A request that never gets a response at all is covered by the same clock. This matches the Python client's read timeout, so the two SDKs behave the same way on a slow link.
 - **Every failure of the request is an `Image2PPTError`.** A refused connection, a reset mid-download, a 2xx that comes back as a proxy's HTML login page, a job body missing its own id — all of them arrive as an SDK error with the original kept on `.cause`, never as a raw `TypeError: fetch failed` or `SyntaxError`. **Your own filesystem is the exception, deliberately:** if `download` cannot write where you asked it to, you get the operating system's error — `ENOSPC`, `EACCES`, `ENOENT` — because that names the thing you have to go and fix, and no error of ours would say it better. The Python client draws the same line.
 
-> Both the Node and Python SDKs pre-compress images that need processing before upload. PNG/JPEG files already at most 1MiB with a longest edge at most 2000px upload byte-for-byte unchanged. Other PNG/JPEG files, and all WebP/GIF files, may be resized, flattened onto white, and sent as JPEG; PDFs are never compressed or decoded and are streamed unchanged.
+> Both the Node and Python SDKs pre-compress images that need processing before upload. PNG/JPEG files already at most 2MiB with a longest edge at most 2000px upload byte-for-byte unchanged. Other PNG/JPEG files, and all WebP/GIF files, may be resized, flattened onto white, and sent as full-colour (4:4:4) JPEG; PDFs are never compressed or decoded and are streamed unchanged.
 
 ## More files than one request can hold
 
@@ -163,7 +382,9 @@ const files = await client.convertAll(imagePaths, "decks/");
 console.log(files); // ['decks/part-01.pptx', 'decks/part-02.pptx']
 ```
 
-Batches hold at most 40MB of file content and at most 50 images; every PDF goes in a batch of its own, because the client does not parse PDFs and only the server knows their page count. `submitAll()` does the same splitting and hands back the jobs if you want to drive polling yourself. To see the plan without uploading anything, use `planBatches()`.
+Batches hold at most 80MB of file content and at most 50 images; every PDF goes in a batch of its own, because the client does not parse PDFs and only the server knows their page count. `submitAll()` does the same splitting and hands back the jobs if you want to drive polling yourself. To see the plan without uploading anything, use `planBatches()`.
+
+Both take `callbackUrl` — each batch's job calls it. They do not take `pages` or `idempotencyKey` (passing either throws a `TypeError`): page numbers run across one submission and a key names one job, so neither can span several batches. Each batch gets its own key, kept across that batch's retries.
 
 **Rate limits are waited out, not thrown.** A pile big enough to need batching will hit the account's per-minute page quota (and its cap on concurrently active jobs). Both arrive as a `429` with a `Retry-After`; both are handled the same way — sleep that long, retry the same batch. Retrying a 429 is free: the server is saying it did *not* take the submission, so nothing was created and nothing was charged. Total waiting is capped by `rateLimitMaxWaitMs` (default 30 min) — and **only waiting counts against it**, not the time the uploads themselves take, so a slow link cannot quietly turn the cap into "do not wait at all". A single batch is also retried at most 10 times, whatever the budget says: every retry re-uploads the whole batch, and a service still refusing after ten tries will not be talked round by more of them.
 
@@ -187,14 +408,15 @@ try {
 
 Per account (all keys share the budget): ≤ 10 concurrent jobs, ≤ 60 pages/minute submitted. Over the limit returns `429` with a `Retry-After` hint. **Only submissions are rate limited — polling job status is not.**
 
-`submitAll()` / `convertAll()` wait these out for you: a pile big enough to need batching is a pile big enough to hit the quota, so a 429 mid-pile is the normal path, not an error. `submit()` and `convert()` do not — they submit exactly once, so catch `RateLimitedError` and honor `retryAfter` (seconds) yourself:
+`submitAll()` / `convertAll()` wait these out for you: a pile big enough to need batching is a pile big enough to hit the quota, so a 429 mid-pile is the normal path, not an error. `submit()`, `submitUrls()` and `convert()` do not, so catch `RateLimitedError` and honor `retryAfter` (seconds) yourself — resending with the same key keeps it safe:
 
 ```ts
 import { RateLimitedError } from "image2ppt";
 
+const idempotencyKey = "order-42";
 for (;;) {
   try {
-    job = await client.submit(paths);
+    job = await client.submit(paths, { idempotencyKey });
     break;
   } catch (e) {
     if (e instanceof RateLimitedError) {
@@ -206,11 +428,11 @@ for (;;) {
 
 ## Errors
 
-Every error this client raises about a *request* subclasses `Image2PPTError` and carries `statusCode`, `code`, and `message`. Branch on `code`, not `message`. The one thing that reaches you unwrapped is a failure of your own disk while `download` is writing — see the note above.
+Every error this client raises about a *request* subclasses `Image2PPTError` and carries `statusCode`, `code`, and `message` — plus `index` (which of `urls` it is about, else `undefined`) and, out of a submit call, `idempotencyKey`. Branch on `code`, not `message`. The one thing that reaches you unwrapped is a failure of your own disk while `download` is writing — see the note above.
 
-Every `Image2PPTError` also carries **`isTransient`** — whether **repeating this exact read** later could plausibly succeed. (A raw filesystem error from `download` has no such field; that is the same exception as above, and it is never transient — free the space or fix the permission first.) It is what `wait()` uses to decide whether a failed status poll should be backed off and retried or should end the wait: `true` for a 5xx, a dropped connection and a stalled request, `false` for a bad key, a job that does not exist, or a response this client cannot parse.
+Every `Image2PPTError` also carries **`isTransient`** — whether **repeating this exact read** later could plausibly succeed. (A raw filesystem error from `download` has no such field; that is the same exception as above, and it is never transient — free the space or fix the permission first.) It is what `wait()` uses to decide whether a failed status poll should be backed off and retried or should end the wait: `true` for a 5xx, a rate limit, `IdempotencyKeyInProgressError`, `UrlFetchFailedError`, a dropped connection and a stalled request, `false` for a bad key, a job that does not exist, or a response this client cannot parse.
 
-**It says nothing about submitting.** `submit()` is never retried on this signal, and neither should your code be: a lost response cannot be told apart from a submission the server accepted, and there is no idempotency key, so resending the same files can create the same job twice and **charge you twice**. Only a `RateLimitedError` is retried on the submit path — a 429 is the service explicitly saying it took nothing.
+**Resubmitting is only safe with the same key.** A lost response cannot be told apart from a submission the server accepted, so resending under a *new* key can create the same job twice and **charge you twice**. Resend with `e.idempotencyKey`, as `submit()` itself does.
 
 | Class | HTTP | code |
 |---|---|---|
@@ -220,7 +442,17 @@ Every `Image2PPTError` also carries **`isTransient`** — whether **repeating th
 | `MalformedUploadError` | 400 | `MALFORMED_UPLOAD` — the body was not valid `multipart/form-data`; **resending identical bytes will not help** |
 | `NoFilesError` | 400 | `NO_FILES` — no files reached the server |
 | `InvalidAspectRatioError` | 400 | `INVALID_ASPECT_RATIO` — use `auto`, `16:9`, or `4:3` |
-| `TooManySlidesError` | 400 | `TOO_MANY_SLIDES` |
+| `TooManySlidesError` | 400 | `TOO_MANY_SLIDES` — also for more than 50 pages selected |
+| `InvalidPagesError` | 400 | `INVALID_PAGES` — `pages` is misspelled (also checked locally) |
+| `PagesOutOfRangeError` | 400 | `PAGES_OUT_OF_RANGE` — page 0, or past the end; subclasses `InvalidPagesError` |
+| `InvalidCallbackUrlError` | 400 | `INVALID_CALLBACK_URL` — not `https`, has credentials, over 2048 characters, or not a public address |
+| `InvalidIdempotencyKeyError` | 400 | `INVALID_IDEMPOTENCY_KEY` — not 1–255 printable ASCII characters (also checked locally) |
+| `IdempotencyKeyMismatchError` | 422 | `IDEMPOTENCY_KEY_MISMATCH` — the key was used for a different request |
+| `IdempotencyKeyInProgressError` | 409 | `IDEMPOTENCY_KEY_IN_PROGRESS` (has `retryAfter`) — an earlier request with this key is still being processed |
+| `InvalidUrlError` | 400 | `INVALID_URL` — a link was refused before downloading (`e.index` says which) |
+| `UrlFetchFailedError` | 400 | `URL_FETCH_FAILED` — downloading a link failed; may be temporary (`e.index` says which) |
+| `InvalidNameError` | 400 | `INVALID_NAME` — invalid task name |
+| `InvalidParameterError` | 400 | `INVALID_PARAMETER`, `INVALID_JSON` — e.g. more than 50 `urls`, or a bad `listJobs` argument |
 | `PageRateExceededError` | 400 | `PAGE_RATE_EXCEEDED` — this one submission has more pages than a minute's quota, so waiting will not help; split it |
 | `InsufficientCreditsError` | 402 | `INSUFFICIENT_CREDITS` |
 | `RateLimitedError` | 429 | `RATE_LIMITED` (has `retryAfter`) |
@@ -235,6 +467,7 @@ Every `Image2PPTError` also carries **`isTransient`** — whether **repeating th
 | `APITimeoutError` | — | `REQUEST_TIMEOUT` — one request went `timeoutMs` with **no data moving**; subclasses `APIConnectionError` |
 | `MalformedResponseError` | — | — (the server answered with something this client cannot read: a 2xx that is not JSON, or a body missing a field the contract guarantees) |
 | `Image2PPTTimeoutError` | — | — (`wait()` exceeded its own `timeoutMs`; job may still be running — **not** a transport failure, and not the same as `APITimeoutError`) |
+| `WebhookVerificationError` | — | — (`verifyWebhook` refused a delivery: missing header, stale timestamp, or no matching signature) |
 
 > **5xx now lands on `ServerError` rather than the base class.** It still subclasses `Image2PPTError`, so `catch (e) { if (e instanceof Image2PPTError) }` is unaffected — only code matching on the exact class or on `e.name` needs updating.
 

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 /** The image2ppt API client. */
-import type { Account, CancellationResult, ClientOptions, ConvertOptions, SubmitOptions, WaitOptions } from "./types.js";
-import { Job } from "./types.js";
+import type { Account, CancellationResult, ClientOptions, ConvertAllOptions, ConvertOptions, ListJobsOptions, SubmitAllOptions, SubmitOptions, WaitOptions } from "./types.js";
+import { Job, JobList } from "./types.js";
 export declare const DEFAULT_BASE_URL = "https://image2ppt.com";
 /**
  * Client for the image2ppt API. Server-side only — keep your key off the browser.
@@ -28,30 +28,67 @@ export declare class Image2PPTClient {
      * Submit a batch of files and create a conversion job.
      *
      * Checked locally before anything is uploaded: the files must add up to at most
-     * 45MB and at most 50 pages. Over either limit this throws without opening a
+     * 90MB and at most 50 pages (the pages *selected*, when `pages` is given), and
+     * `pages` must be spelled correctly. Over a limit this throws without opening a
      * connection — going over the size cap on the wire does not come back as a clean
      * error, it comes back as a dead connection.
      *
-     * **A failed submission is never retried automatically.** A network error does
-     * not tell you whether the request body made it: the job may not exist, or it
-     * may exist with credits already reserved and only the response lost. Retrying
-     * the second case charges twice, and without an idempotency key there is no way
-     * to tell them apart — so the error is thrown as-is. Check `account()` or your
-     * job list before resending.
+     * **Every submission carries an `Idempotency-Key`**, and that is what makes a
+     * failed one safe to resend: if an earlier attempt did create the job, the service
+     * hands that job back (`job.replayed` is true) instead of creating and charging for
+     * a second one. So this call resends by itself, always with the same key, when the
+     * outcome is unknown — a dropped connection, an idle timeout, or a 5xx (up to 2
+     * more attempts, 1s and 2s apart) — and waits out `IDEMPOTENCY_KEY_IN_PROGRESS`, an
+     * earlier attempt the service is still working on (up to 10 attempts / 3 minutes).
+     * A 429 is not retried here; `submitAll` waits those out.
+     *
+     * If it still fails, the key is on the error as `err.idempotencyKey`. Calling
+     * `submit` again with that key and the same files and options is safe for 24
+     * hours; calling it without the key may create a second job.
      *
      * @param paths Local file paths (one or more). png/jpeg/webp/gif/pdf, each ≤ 35MB,
-     *   and ≤ 45MB of file content per request. An image is 1 page, a PDF is its page
+     *   and ≤ 90MB of file content per request. An image is 1 page, a PDF is its page
      *   count; the total must be ≤ 50 pages. For more files than one request can hold,
      *   use `submitAll` / `convertAll`.
-     * @returns A `Job` with status `pending`, plus `slideCount` and `creditsReserved`.
+     * @returns A `Job` with status `pending` (for a replay: the job's current status),
+     *   plus `slideCount` and `creditsReserved`.
      * @throws InvalidFileError Including the local `PAYLOAD_TOO_LARGE` pre-flight failure.
+     * @throws InvalidPagesError / PagesOutOfRangeError / TooManySlidesError A selection
+     *   that is certain to be refused, before anything is sent.
+     * @throws IdempotencyKeyMismatchError The key was used for a different request.
+     * @throws APIConnectionError / ServerError / IdempotencyKeyInProgressError Once the
+     *   retries above run out.
      */
     submit(paths: string[], options?: SubmitOptions): Promise<Job>;
+    /**
+     * Create a conversion job from files the service downloads itself.
+     *
+     * Instead of uploading, hand over `https` links; the service fetches them in order
+     * and converts them as one deck. The downloaded files are held to the same limits
+     * as uploads (35MB each, 90MB together, 50 pages). File types are judged by
+     * content, not by the link or its `Content-Type`.
+     *
+     * Downloading takes time — up to 60 seconds a link and 120 for the request — so
+     * this call waits at least 180 seconds for an answer, whatever the client's
+     * `timeoutMs`. Retries and `idempotencyKey` work exactly as in `submit`. Only one
+     * submission by URL per account can be in flight at a time; another gets a
+     * `RateLimitedError`.
+     *
+     * @param urls 1–50 `https` links. Each must resolve to a public address.
+     * @param options As `submit`. With links the page total is not known here, so
+     *   `pages` is only checked for spelling and for selecting more than 50 pages.
+     * @throws InvalidUrlError A link was refused before downloading.
+     * @throws UrlFetchFailedError A download failed; may be temporary. For these two —
+     *   and `InvalidFileError` about a downloaded file — `err.index` says which link,
+     *   counting from 0.
+     * @throws InvalidParameterError More than 50 links, thrown locally.
+     */
+    submitUrls(urls: string[], options?: SubmitOptions): Promise<Job>;
     /**
      * Split files into submittable batches and create **one job per batch**.
      *
      * For a pile of files too big or too numerous for a single request. Batching
-     * rules live in `planBatches`: at most 40MB of file content and at most 50
+     * rules live in `planBatches`: at most 80MB of file content and at most 50
      * images per batch, and every PDF in a batch of its own (the SDK does not parse
      * PDFs, so only the server knows their page count). Input order is preserved.
      *
@@ -66,8 +103,11 @@ export declare class Image2PPTClient {
      * the same batch again. Waiting is the normal path here. Total waiting is capped
      * by the client's `rateLimitMaxWaitMs`.
      *
-     * **Network errors are not retried** — see `submit`. Only a 429 is, because only
-     * a 429 proves the server did not take the submission.
+     * **Each batch is its own submission with its own `Idempotency-Key`**, and is
+     * retried exactly as `submit` retries — plus the 429s above, with the same key.
+     * There is no `pages` or `idempotencyKey` option here: page numbers run across one
+     * submission and a key names one job, so neither can span several batches. Submit
+     * batches yourself with `submit` if you need them.
      *
      * **If it does give up, the jobs already created are handed back on the error**,
      * in `err.submittedJobs`. Those jobs are running on the server with credits
@@ -79,7 +119,7 @@ export declare class Image2PPTClient {
      *   batching can carry it.
      * @throws RateLimitedError Still rate limited after `rateLimitMaxWaitMs`.
      */
-    submitAll(paths: string[], options?: SubmitOptions): Promise<Job[]>;
+    submitAll(paths: string[], options?: SubmitAllOptions): Promise<Job[]>;
     /** Fetch the current job state as a `Job` snapshot. Throws JobNotFoundError. */
     getJob(jobId: string): Promise<Job>;
     /**
@@ -118,7 +158,7 @@ export declare class Image2PPTClient {
     /**
      * One-shot: submit → wait for completion → download to `destPath`.
      *
-     * One job, one PPTX — the files must fit in a single submission (45MB of file
+     * One job, one PPTX — the files must fit in a single submission (90MB of file
      * content, 50 pages). For more than that, `convertAll` splits the pile and writes
      * one PPTX per batch.
      */
@@ -147,7 +187,30 @@ export declare class Image2PPTClient {
      *   before anything is submitted**, so an unusable destination costs nothing.
      * @returns The written file paths, in batch order.
      */
-    convertAll(paths: string[], destDir: string, options?: ConvertOptions): Promise<string[]>;
+    convertAll(paths: string[], destDir: string, options?: ConvertAllOptions): Promise<string[]>;
+    /**
+     * One page of the jobs this account submitted through the API, newest first.
+     *
+     * Jobs deleted on the website are not listed. Each job has `getJob`'s shape minus
+     * `pageResults`; for reconciliation, add up `creditsUsed` and `creditsRefunded`.
+     * To walk every page, use `iterJobs`.
+     *
+     * @throws InvalidParameterError A parameter is invalid; `message` says which.
+     */
+    listJobs(options?: ListJobsOptions): Promise<JobList>;
+    /**
+     * Every job `listJobs` would list, following `nextCursor` to the end.
+     *
+     * `limit` is the page size, not a cap on how many jobs come back. A 429 is waited
+     * out (`Retry-After`, else 5s), and a page that fails in a way worth repeating
+     * (`isTransient`) is fetched again after a short backoff — at most 10 attempts per
+     * page before the error is thrown.
+     *
+     * ```ts
+     * for await (const job of client.iterJobs({ createdFrom: "2026-10-01" })) { ... }
+     * ```
+     */
+    iterJobs(options?: Omit<ListJobsOptions, "cursor">): AsyncGenerator<Job>;
     /** Return account info: `{ email, credits }` (available credits). */
     account(): Promise<Account>;
 }

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,gCAAgC;AA8BhC,OAAO,KAAK,EACV,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,aAAa,EACb,WAAW,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,GAAG,EAA2B,MAAM,YAAY,CAAC;AAG1D,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAgbxD;;;;;;;GAOG;AACH,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;gBAKrB,OAAO,EAAE,aAAa;IAiBlC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,GAAG,CAAC;IAOxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAmC7E,gFAAgF;IAC1E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAQzC;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAQxD;;;;;;OAMG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,GAAG,CAAC;IAmDlE;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoEhE;;;;;;OAMG;IACG,OAAO,CACX,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,GAAG,CAAC;IAOf;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,EAAE,CAAC;IAyBpB,qEAAqE;IAC/D,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;CAuXlC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAoChC,OAAO,KAAK,EACV,OAAO,EACP,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,WAAW,EACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,GAAG,EAAE,OAAO,EAAwC,MAAM,YAAY,CAAC;AAGhF,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAmhBxD;;;;;;;GAOG;AACH,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;gBAKrB,OAAO,EAAE,aAAa;IAiBlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,GAAG,CAAC;IAgBxE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,GAAG,CAAC;IA+B3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAqChF,gFAAgF;IAC1E,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAQzC;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAQxD;;;;;;OAMG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,GAAG,CAAC;IAqDlE;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoEhE;;;;;;OAMG;IACG,OAAO,CACX,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,GAAG,CAAC;IAsBf;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,EAAE,CAAC;IA4BpB;;;;;;;;OAQG;IACG,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB/D;;;;;;;;;;;OAWG;IACI,QAAQ,CAAC,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAM,GAAG,cAAc,CAAC,GAAG,CAAC;IAUnF,qEAAqE;IAC/D,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;CA2elC"}