image2ppt 0.5.3

package/dist/errors.js

@@ -0,0 +1,293 @@
+/**
+ * Exception hierarchy for the image2ppt client.
+ *
+ * Every error carries the HTTP `statusCode`, the server error `code` (from the
+ * `{ error: { code, message } }` envelope), and a human-readable `message`.
+ * Branch on `code`, not `message` — messages may be reworded.
+ */
+/** Base class for all client errors. */
+export class Image2PPTError extends Error {
+    statusCode;
+    code;
+    /**
+     * Jobs already created when this error was thrown out of `submitAll` /
+     * `convertAll`. They are **running on the server with credits already
+     * reserved** — not lost, not refunded by the failure. Wait on them
+     * (`wait`/`download`) or come back to them later. Empty for any error not
+     * thrown out of a batch call.
+     */
+    submittedJobs = [];
+    constructor(message, init = {}) {
+        super(message, "cause" in init ? { cause: init.cause } : undefined);
+        // new.target gives the concrete subclass, so subclasses get the right name
+        // without each redefining it.
+        this.name = new.target.name;
+        this.statusCode = init.statusCode;
+        this.code = init.code;
+    }
+    /**
+     * Whether retrying the same call later could plausibly succeed.
+     *
+     * `wait()` polls a job for as long as half an hour, and this is the flag it
+     * consults to decide whether one failed poll should be backed off and retried
+     * or should end the wait. It used to ask a different question — "did this error
+     * come out of this SDK?" — and got both halves wrong: an unexpected bug in this
+     * client was retried for the whole deadline, while a single slow status poll
+     * (which this SDK reports as its own error) aborted the wait outright.
+     *
+     * The default is the HTTP rule: a 5xx is the server's own problem and may clear
+     * on its own, everything else — a bad key, a job that does not exist, a
+     * rejected file — will still be wrong in fifteen seconds. Subclasses that know
+     * better override it.
+     */
+    get isTransient() {
+        return this.statusCode != null && this.statusCode >= 500;
+    }
+}
+/**
+ * The request never completed at the transport level.
+ *
+ * A connection refused or reset, a DNS or TLS failure, a response body that
+ * stopped arriving. The underlying error is kept as `cause`.
+ *
+ * **This does not tell you whether the server acted on the request.** For a
+ * submission it is genuinely ambiguous — the job may not exist, or it may exist
+ * with credits reserved and only the reply lost — which is why `submit` never
+ * retries one for you. Polling a job's status has no such cost, so `wait()` does
+ * back these off and retry (`isTransient` is true).
+ */
+export class APIConnectionError extends Image2PPTError {
+    get isTransient() {
+        return true;
+    }
+}
+/**
+ * A single HTTP request went `timeoutMs` with no data moving in either
+ * direction (`code: "REQUEST_TIMEOUT"`).
+ *
+ * `timeoutMs` is an **idle** timeout, not a cap on how long a request may take:
+ * a large upload or download that keeps making progress is never cut off by it,
+ * however long it runs in total.
+ *
+ * **Not the same as `Image2PPTTimeoutError`**, and the two are deliberately kept
+ * apart. This one is a transport failure — one request stalled — so it is
+ * transient and `wait()` retries it. `Image2PPTTimeoutError` means `wait()` ran
+ * out of its own overall deadline while the job was still running perfectly
+ * well; nothing failed, and there is nothing to retry.
+ */
+export class APITimeoutError extends APIConnectionError {
+    /**
+     * `code` defaults here rather than at each `throw`, the way the Python class
+     * does it. Every construction site meant the same thing by it, and one that
+     * forgot would have produced an `APITimeoutError` with no code at all for a
+     * caller branching on codes.
+     */
+    constructor(message, init = {}) {
+        super(message, { code: "REQUEST_TIMEOUT", ...init });
+    }
+}
+/**
+ * The server answered, but this client cannot make sense of the answer.
+ *
+ * Either a 2xx body that is not JSON at all — a captive-portal login page, a CDN
+ * error page, a proxy that replaced the response — or a JSON body missing a
+ * field the API contract guarantees.
+ *
+ * **Never transient**, on purpose. A response that cannot be parsed is a sign
+ * that something between this client and the API is rewriting traffic, and no
+ * amount of waiting fixes it. Retrying would mean `wait()` silently swallowing
+ * the evidence for half an hour and then reporting a timeout instead.
+ */
+export class MalformedResponseError extends Image2PPTError {
+    get isTransient() {
+        return false;
+    }
+}
+/**
+ * The service failed on its own side (any 5xx).
+ *
+ * The contract's advice for these is to retry later, so `isTransient` is true and
+ * `wait()` backs off and polls again rather than giving up. Subclasses
+ * `Image2PPTError` like every other error here, so existing
+ * `catch (e) { if (e instanceof Image2PPTError) ... }` code is unaffected.
+ */
+export class ServerError extends Image2PPTError {
+}
+/** API key is missing, invalid, or the account is gone (401 / 403). */
+export class AuthenticationError extends Image2PPTError {
+}
+/**
+ * A file was rejected (400), or the request carried too much file content.
+ *
+ * Raised for an unsupported format, a single file over the 35MB per-file limit, or
+ * a request whose files add up to more than the 45MB per-request limit
+ * (413 `PAYLOAD_TOO_LARGE`). The client raises the `PAYLOAD_TOO_LARGE` case
+ * locally, before uploading anything.
+ */
+export class InvalidFileError extends Image2PPTError {
+}
+/**
+ * The upload was cut off before the body finished arriving (400 `UPLOAD_ABORTED`).
+ *
+ * The server is telling you it did **not** take the submission — no job was created
+ * and no credits were reserved — so **resending the same files is safe**. That makes
+ * this different from a transport-level fetch failure, which cannot rule out that the
+ * job was created and only the response was lost; the client never retries that one
+ * for you.
+ *
+ * If it keeps happening the submission is probably too large for the link. Send fewer
+ * files per request, or use `submitAll` / `convertAll` to split.
+ */
+export class UploadAbortedError extends Image2PPTError {
+}
+/**
+ * The body was not valid `multipart/form-data` (400 `MALFORMED_UPLOAD`). A
+ * client-side framing problem: **retrying the identical payload will not help**.
+ * Using this SDK unmodified you should never see it; if you do, please report it.
+ */
+export class MalformedUploadError extends Image2PPTError {
+}
+/**
+ * The request carried no files at all (400 `NO_FILES`). Using this SDK you should
+ * never see it — `submit` refuses an empty `paths` before opening a connection.
+ */
+export class NoFilesError extends Image2PPTError {
+}
+/**
+ * `aspectRatio` was not one of the accepted values (400 `INVALID_ASPECT_RATIO`).
+ * Accepted: `auto` (default), `16:9`, `4:3`. Nothing was created and nothing was
+ * charged — fix the value and submit again.
+ */
+export class InvalidAspectRatioError extends Image2PPTError {
+}
+/**
+ * One submission holds more pages than the per-minute quota allows (400
+ * `PAGE_RATE_EXCEEDED`).
+ *
+ * Distinct from `RateLimitedError`: a 429 means "not right now, try again in N
+ * seconds" and the same submission will eventually go through. `PAGE_RATE_EXCEEDED`
+ * means this submission can *never* fit the window whole, so waiting does not help —
+ * split it, e.g. with `submitAll` / `convertAll`.
+ */
+export class PageRateExceededError extends Image2PPTError {
+}
+/** The submission exceeds the 50-page-per-job limit (400 TOO_MANY_SLIDES). */
+export class TooManySlidesError extends Image2PPTError {
+}
+/** Not enough available credits to cover the submission (402). */
+export class InsufficientCreditsError extends Image2PPTError {
+}
+/** The job id doesn't exist, or isn't owned by this key's account (404). */
+export class JobNotFoundError extends Image2PPTError {
+}
+/** The job finished naturally before a cancellation request was accepted (409). */
+export class JobAlreadyFinishedError extends Image2PPTError {
+}
+/** The job hasn't finished yet, so the deliverable can't be downloaded (409). */
+export class NotReadyError extends Image2PPTError {
+}
+/** The job finished, but its PPTX passed the retention window and was reaped (410). */
+export class OutputExpiredError extends Image2PPTError {
+}
+/**
+ * Rate limited (429 RATE_LIMITED). `retryAfter` is the server-suggested wait in
+ * seconds (from the `Retry-After` header); retry after that long.
+ *
+ * Both kinds of 429 land here — the per-minute page quota and the cap on
+ * concurrently active jobs — and both are handled the same way: wait, then try the
+ * same submission again. `submitAll` / `convertAll` do that for you; if one of
+ * them gives up, `submittedJobs` holds the jobs already created.
+ */
+export class RateLimitedError extends Image2PPTError {
+    retryAfter;
+    constructor(message, init = {}) {
+        super(message, init);
+        this.retryAfter = init.retryAfter;
+    }
+    /** "Not right now" is the one server answer that says to come back and ask again. */
+    get isTransient() {
+        return true;
+    }
+}
+/**
+ * The job ended in failure (raised by `wait` when it polls status=failed). `job`
+ * is the failure snapshot; `code` / `message` come from its `error` field.
+ */
+export class JobFailedError extends Image2PPTError {
+    job;
+    constructor(message, init = {}) {
+        super(message, { code: init.code });
+        this.job = init.job;
+    }
+}
+/** A graceful cancellation settled without any deliverable pages. */
+export class JobCancelledError extends JobFailedError {
+}
+/**
+ * `wait` exceeded its `timeout` before the job reached a terminal state. This does
+ * not mean the job failed — it may still be running. Re-`wait` on the `jobId` later.
+ *
+ * **Not the same as `APITimeoutError`**, which means one HTTP request stalled with
+ * no data moving for `timeoutMs`. That one is a transport failure and `wait()`
+ * retries it internally; this one is `wait()` itself running out of the deadline
+ * the caller gave it, with nothing having gone wrong at all.
+ */
+export class Image2PPTTimeoutError extends Image2PPTError {
+    jobId;
+    constructor(message, jobId) {
+        super(message);
+        this.jobId = jobId;
+    }
+}
+// Server error code -> exception class. Unlisted codes fall back to the status-code
+// map, then to `ServerError` for any 5xx, then to the base class.
+const CODE_TO_CLASS = {
+    INVALID_API_KEY: AuthenticationError,
+    API_KEY_REQUIRED: AuthenticationError,
+    ACCOUNT_DELETED: AuthenticationError,
+    INVALID_FILE: InvalidFileError,
+    INVALID_PDF: InvalidFileError,
+    PAYLOAD_TOO_LARGE: InvalidFileError,
+    UPLOAD_ABORTED: UploadAbortedError,
+    MALFORMED_UPLOAD: MalformedUploadError,
+    NO_FILES: NoFilesError,
+    INVALID_ASPECT_RATIO: InvalidAspectRatioError,
+    PAGE_RATE_EXCEEDED: PageRateExceededError,
+    TOO_MANY_SLIDES: TooManySlidesError,
+    INSUFFICIENT_CREDITS: InsufficientCreditsError,
+    RATE_LIMITED: RateLimitedError,
+    JOB_NOT_FOUND: JobNotFoundError,
+    JOB_ALREADY_FINISHED: JobAlreadyFinishedError,
+    NOT_READY: NotReadyError,
+    OUTPUT_EXPIRED: OutputExpiredError,
+};
+const STATUS_TO_CLASS = {
+    401: AuthenticationError,
+    403: AuthenticationError, // API_KEY_REQUIRED / ACCOUNT_DELETED (fallback if code absent)
+    402: InsufficientCreditsError,
+    404: JobNotFoundError,
+    409: NotReadyError,
+    410: OutputExpiredError,
+    413: InvalidFileError,
+    429: RateLimitedError,
+};
+/** Build the mapped exception for an error envelope. */
+export function exceptionFor(args) {
+    const { statusCode, code, message, retryAfter } = args;
+    if (statusCode === 429) {
+        return new RateLimitedError(message, {
+            statusCode: 429,
+            code: code ?? "RATE_LIMITED",
+            retryAfter,
+        });
+    }
+    // A 5xx the maps do not claim is the service's own failure: retrying later is
+    // the contract's advice, so it gets a class that says so. Codes that already map
+    // to a specific class keep doing so, whatever status they arrive with — callers
+    // branch on `code`, and that must not change with the status line.
+    const cls = (code && CODE_TO_CLASS[code]) ||
+        STATUS_TO_CLASS[statusCode] ||
+        (statusCode >= 500 ? ServerError : Image2PPTError);
+    return new cls(message, { statusCode, code });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Official Node.js / TypeScript client for the image2ppt API.
+ * Convert images and PDFs into editable PowerPoint (.pptx) decks.
+ *
+ * ```ts
+ * import { Image2PPTClient } from "image2ppt";
+ *
+ * const client = new Image2PPTClient({ apiKey: "i2p_live_..." });
+ * const job = await client.convert(["slide.png", "report.pdf"], "out.pptx");
+ * console.log("credits used:", job.creditsUsed);
+ * ```
+ *
+ * Server-side only — keep your API key off the browser.
+ * See https://github.com/image2ppt/image2ppt-sdk for docs and examples.
+ */
+export { DEFAULT_BASE_URL, Image2PPTClient } from "./client.js";
+export { VERSION } from "./version.js";
+export { APIConnectionError, APITimeoutError, AuthenticationError, Image2PPTError, Image2PPTTimeoutError, InsufficientCreditsError, InvalidAspectRatioError, InvalidFileError, JobAlreadyFinishedError, JobCancelledError, JobFailedError, JobNotFoundError, MalformedResponseError, MalformedUploadError, NoFilesError, NotReadyError, OutputExpiredError, PageRateExceededError, RateLimitedError, ServerError, TooManySlidesError, UploadAbortedError, } from "./errors.js";
+export type { ErrorInit } from "./errors.js";
+export { BATCH_TARGET_BYTES, MAX_FILE_BYTES, MAX_PAGES_PER_JOB, MAX_UPLOAD_BYTES, checkFileSize, checkSubmission, planBatches, } from "./limits.js";
+export type { UploadItem } from "./limits.js";
+export { Job, PageError, PageResult } from "./types.js";
+export type { Account, AspectRatio, CancellationResult, ClientOptions, ConvertOptions, JobError, JobStatus, Locale, PageStatus, SubmitOptions, WaitOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EACV,OAAO,EACP,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,QAAQ,EACR,SAAS,EACT,MAAM,EACN,UAAU,EACV,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+/**
+ * Official Node.js / TypeScript client for the image2ppt API.
+ * Convert images and PDFs into editable PowerPoint (.pptx) decks.
+ *
+ * ```ts
+ * import { Image2PPTClient } from "image2ppt";
+ *
+ * const client = new Image2PPTClient({ apiKey: "i2p_live_..." });
+ * const job = await client.convert(["slide.png", "report.pdf"], "out.pptx");
+ * console.log("credits used:", job.creditsUsed);
+ * ```
+ *
+ * Server-side only — keep your API key off the browser.
+ * See https://github.com/image2ppt/image2ppt-sdk for docs and examples.
+ */
+export { DEFAULT_BASE_URL, Image2PPTClient } from "./client.js";
+export { VERSION } from "./version.js";
+export { APIConnectionError, APITimeoutError, AuthenticationError, Image2PPTError, Image2PPTTimeoutError, InsufficientCreditsError, InvalidAspectRatioError, InvalidFileError, JobAlreadyFinishedError, JobCancelledError, JobFailedError, JobNotFoundError, MalformedResponseError, MalformedUploadError, NoFilesError, NotReadyError, OutputExpiredError, PageRateExceededError, RateLimitedError, ServerError, TooManySlidesError, UploadAbortedError, } from "./errors.js";
+export { BATCH_TARGET_BYTES, MAX_FILE_BYTES, MAX_PAGES_PER_JOB, MAX_UPLOAD_BYTES, checkFileSize, checkSubmission, planBatches, } from "./limits.js";
+export { Job, PageError, PageResult } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/limits.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Upload size limits and batch planning.
+ *
+ * The API caps the **file content of a single request** at 45MB. Going over that
+ * is not a friendly failure: the check can only run after the whole body has been
+ * received, and the network layer in front of the API gives up on an oversized
+ * request before it ever gets there — so a client that sends too much sees the
+ * connection die (a write timeout on a slow uplink, a broken pipe on a fast one)
+ * with no error code and no explanation.
+ *
+ * The fix is to never send too much. These limits, the pre-flight checks, and
+ * `planBatches` let a client know a submission is too big *before* opening a
+ * connection, and split a large pile of files into submittable batches.
+ *
+ * There are three separate caps, and they fail in different ways: one file
+ * (`MAX_FILE_BYTES`), the file content of one request (`MAX_UPLOAD_BYTES`), and
+ * pages per job (`MAX_PAGES_PER_JOB`). `BATCH_TARGET_BYTES` is not a fourth cap — it
+ * is how much `planBatches` puts in one batch, deliberately under the real one.
+ */
+/**
+ * Server cap on **one** file. A file over this is rejected with `INVALID_FILE`
+ * however it is submitted, so no amount of batching helps. Keep in sync with the
+ * documented API contract.
+ */
+export declare const MAX_FILE_BYTES: number;
+/**
+ * Server cap on the **file content** of one request — boundaries, per-part headers
+ * and filenames do not count towards it. Over this, the request is rejected
+ * (413 `PAYLOAD_TOO_LARGE`) — or, further up, cut off outright before the server can
+ * answer at all. Keep in sync with the documented API contract.
+ */
+export declare const MAX_UPLOAD_BYTES: number;
+/**
+ * Byte budget for one auto-planned batch. **A splitting budget, not a cap** — the cap
+ * is `MAX_UPLOAD_BYTES`, and `checkSubmission` compares against that exactly.
+ *
+ * Deliberately below the cap, and the asymmetry is the point: starting one more batch
+ * costs nothing, while refusing a submission the server would have accepted is a bug in
+ * the guard. Nothing here needs the headroom — the planner measures the exact bytes it
+ * will send — so this is margin, not correction. **Do not turn it into a cap.**
+ * `MAX_UPLOAD_BYTES` is file content only; the multipart framing around it does not
+ * count against the published limit, and a pre-flight that "leaves room" for framing
+ * just makes the documented maximum unreachable.
+ */
+export declare const BATCH_TARGET_BYTES: number;
+/**
+ * Server cap on pages per job. An image is 1 page; a PDF counts as its own page
+ * count. Keep in sync with the documented API contract.
+ */
+export declare const MAX_PAGES_PER_JOB = 50;
+/**
+ * One file to upload, with the size it will occupy in the request.
+ *
+ * `size` is the final file-content byte count on the wire. Images may have been
+ * client-compressed already; PDFs retain their on-disk size.
+ *
+ * `isPdf` marks a file whose page count is unknown to the client — the SDK does
+ * not parse PDFs. Such a file is never mixed into a batch with others.
+ */
+export interface UploadItem {
+    path: string;
+    size: number;
+    isPdf: boolean;
+}
+/** Format a byte count as MB, for human-readable error messages. */
+export declare function formatBytes(size: number): string;
+/**
+ * Throw if one file is over the per-file cap, whatever else it travels with.
+ *
+ * Separate from `checkSubmission` because it is a property of the file, not of
+ * the request: a 40MB PDF fits under the 45MB request cap and would sail through
+ * batch planning, then be rejected by the server every single time. Fail on it
+ * locally instead of building a batch that can never succeed.
+ *
+ * @param path The file, named in the error so the caller knows which one.
+ * @param size Its size as it will be uploaded.
+ * @throws InvalidFileError Over `MAX_FILE_BYTES` (`code: "INVALID_FILE"`, the same
+ *   code the server would answer with).
+ */
+export declare function checkFileSize(path: string, size: number): void;
+/**
+ * Throw if a submission cannot succeed, before any bytes go on the wire.
+ *
+ * **The page check is a lower bound, not the server's verdict.** An image is
+ * exactly 1 page, but a PDF is however many pages it holds and the SDK does not
+ * parse PDFs (zero dependencies), so each one can only be counted as *at least* 1.
+ * That is enough to catch the combinations that are certain to fail — 50 images
+ * plus any PDF is at least 51 pages, so it never had a chance — but a submission
+ * that passes here can still come back `TOO_MANY_SLIDES` from the server, because
+ * a 30-page PDF counted as 1 here and as 30 there. Passing this check means "not
+ * obviously doomed", not "will be accepted".
+ *
+ * @param totalBytes Sum of the file sizes that will be sent in this request.
+ * @param imagePages Number of image files. Each is exactly 1 page.
+ * @param pdfFiles Number of PDFs (or other files whose page count is unknown to
+ *   the client). Each counts as at least 1 page.
+ * @throws TooManySlidesError The minimum page count already exceeds what one job
+ *   can hold.
+ * @throws InvalidFileError File content over the per-request cap
+ *   (`code = "PAYLOAD_TOO_LARGE"`).
+ */
+export declare function checkSubmission(totalBytes: number, imagePages: number, pdfFiles?: number): void;
+/**
+ * Split files into batches that each fit in one submission.
+ *
+ * Pure function: no file system, no network. Same input, same output.
+ *
+ * Rules:
+ * - a batch holds at most `BATCH_TARGET_BYTES` of file content;
+ * - a batch holds at most `MAX_PAGES_PER_JOB` images. That count is exact, not a
+ *   lower bound like `checkSubmission`'s: a PDF always flushes the current batch
+ *   and takes one of its own, so a batch being filled here only ever holds images,
+ *   and an image is always exactly 1 page;
+ * - **every PDF gets a batch to itself.** The SDK does not parse PDFs (zero
+ *   dependencies), so the client cannot know how many pages one holds. Mixed into
+ *   a batch, an unknown page count could push the job over the page limit with no
+ *   way to predict it. Alone, the job is exactly that one PDF and the server's own
+ *   count decides;
+ * - input order is preserved, so the same files always plan the same way.
+ *
+ * @throws InvalidFileError A single file is over `MAX_FILE_BYTES`. No batching can
+ *   help — the server rejects that file however it is submitted.
+ */
+export declare function planBatches(items: Iterable<UploadItem>): UploadItem[][];
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAmB,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAmB,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,QAAmB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAS9D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,SAAI,GACX,IAAI,CAuBN;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,EAAE,EAAE,CAsCvE"}

package/dist/limits.js

@@ -0,0 +1,177 @@
+/**
+ * Upload size limits and batch planning.
+ *
+ * The API caps the **file content of a single request** at 45MB. Going over that
+ * is not a friendly failure: the check can only run after the whole body has been
+ * received, and the network layer in front of the API gives up on an oversized
+ * request before it ever gets there — so a client that sends too much sees the
+ * connection die (a write timeout on a slow uplink, a broken pipe on a fast one)
+ * with no error code and no explanation.
+ *
+ * The fix is to never send too much. These limits, the pre-flight checks, and
+ * `planBatches` let a client know a submission is too big *before* opening a
+ * connection, and split a large pile of files into submittable batches.
+ *
+ * There are three separate caps, and they fail in different ways: one file
+ * (`MAX_FILE_BYTES`), the file content of one request (`MAX_UPLOAD_BYTES`), and
+ * pages per job (`MAX_PAGES_PER_JOB`). `BATCH_TARGET_BYTES` is not a fourth cap — it
+ * is how much `planBatches` puts in one batch, deliberately under the real one.
+ */
+import { InvalidFileError, TooManySlidesError } from "./errors.js";
+/**
+ * Server cap on **one** file. A file over this is rejected with `INVALID_FILE`
+ * however it is submitted, so no amount of batching helps. Keep in sync with the
+ * documented API contract.
+ */
+export const MAX_FILE_BYTES = 35 * 1024 * 1024;
+/**
+ * Server cap on the **file content** of one request — boundaries, per-part headers
+ * and filenames do not count towards it. Over this, the request is rejected
+ * (413 `PAYLOAD_TOO_LARGE`) — or, further up, cut off outright before the server can
+ * answer at all. Keep in sync with the documented API contract.
+ */
+export const MAX_UPLOAD_BYTES = 45 * 1024 * 1024;
+/**
+ * Byte budget for one auto-planned batch. **A splitting budget, not a cap** — the cap
+ * is `MAX_UPLOAD_BYTES`, and `checkSubmission` compares against that exactly.
+ *
+ * Deliberately below the cap, and the asymmetry is the point: starting one more batch
+ * costs nothing, while refusing a submission the server would have accepted is a bug in
+ * the guard. Nothing here needs the headroom — the planner measures the exact bytes it
+ * will send — so this is margin, not correction. **Do not turn it into a cap.**
+ * `MAX_UPLOAD_BYTES` is file content only; the multipart framing around it does not
+ * count against the published limit, and a pre-flight that "leaves room" for framing
+ * just makes the documented maximum unreachable.
+ */
+export const BATCH_TARGET_BYTES = 40 * 1024 * 1024;
+/**
+ * Server cap on pages per job. An image is 1 page; a PDF counts as its own page
+ * count. Keep in sync with the documented API contract.
+ */
+export const MAX_PAGES_PER_JOB = 50;
+/** Format a byte count as MB, for human-readable error messages. */
+export function formatBytes(size) {
+    // Stays honest below a megabyte. Rounding everything to MB makes a submission one
+    // byte over the cap read as "45.0MB, over the 45.0MB limit (0.0MB too much)" — a
+    // message that contradicts itself and looks like the check is broken.
+    if (size < 1024)
+        return `${size}B`;
+    if (size < 1024 * 1024)
+        return `${(size / 1024).toFixed(1)}KB`;
+    return `${(size / (1024 * 1024)).toFixed(1)}MB`;
+}
+/**
+ * Throw if one file is over the per-file cap, whatever else it travels with.
+ *
+ * Separate from `checkSubmission` because it is a property of the file, not of
+ * the request: a 40MB PDF fits under the 45MB request cap and would sail through
+ * batch planning, then be rejected by the server every single time. Fail on it
+ * locally instead of building a batch that can never succeed.
+ *
+ * @param path The file, named in the error so the caller knows which one.
+ * @param size Its size as it will be uploaded.
+ * @throws InvalidFileError Over `MAX_FILE_BYTES` (`code: "INVALID_FILE"`, the same
+ *   code the server would answer with).
+ */
+export function checkFileSize(path, size) {
+    if (size > MAX_FILE_BYTES) {
+        throw new InvalidFileError(`"${path}" is ${formatBytes(size)}, over the ${formatBytes(MAX_FILE_BYTES)} ` +
+            "per-file limit; the server rejects it however it is submitted, so " +
+            "splitting into batches will not help", { code: "INVALID_FILE" });
+    }
+}
+/**
+ * Throw if a submission cannot succeed, before any bytes go on the wire.
+ *
+ * **The page check is a lower bound, not the server's verdict.** An image is
+ * exactly 1 page, but a PDF is however many pages it holds and the SDK does not
+ * parse PDFs (zero dependencies), so each one can only be counted as *at least* 1.
+ * That is enough to catch the combinations that are certain to fail — 50 images
+ * plus any PDF is at least 51 pages, so it never had a chance — but a submission
+ * that passes here can still come back `TOO_MANY_SLIDES` from the server, because
+ * a 30-page PDF counted as 1 here and as 30 there. Passing this check means "not
+ * obviously doomed", not "will be accepted".
+ *
+ * @param totalBytes Sum of the file sizes that will be sent in this request.
+ * @param imagePages Number of image files. Each is exactly 1 page.
+ * @param pdfFiles Number of PDFs (or other files whose page count is unknown to
+ *   the client). Each counts as at least 1 page.
+ * @throws TooManySlidesError The minimum page count already exceeds what one job
+ *   can hold.
+ * @throws InvalidFileError File content over the per-request cap
+ *   (`code = "PAYLOAD_TOO_LARGE"`).
+ */
+export function checkSubmission(totalBytes, imagePages, pdfFiles = 0) {
+    const minPages = imagePages + pdfFiles;
+    if (minPages > MAX_PAGES_PER_JOB) {
+        const counted = pdfFiles
+            ? `${imagePages} images plus ${pdfFiles} ${pdfFiles === 1 ? "PDF" : "PDFs"} ` +
+                `(at least 1 page each) is at least ${minPages} pages`
+            : `${imagePages} images is ${minPages} pages`;
+        throw new TooManySlidesError(`${counted} in one submission, over the ${MAX_PAGES_PER_JOB}-page-per-job ` +
+            "limit; use submitAll() or convertAll() to split them into jobs automatically", { code: "TOO_MANY_SLIDES" });
+    }
+    if (totalBytes > MAX_UPLOAD_BYTES) {
+        throw new InvalidFileError(`these files add up to ${formatBytes(totalBytes)}, over the ` +
+            `${formatBytes(MAX_UPLOAD_BYTES)} of file content one request may carry ` +
+            `(${formatBytes(totalBytes - MAX_UPLOAD_BYTES)} too much). ` +
+            "Send fewer files per call, or use submitAll() / convertAll() to split them " +
+            "into batches automatically", { code: "PAYLOAD_TOO_LARGE" });
+    }
+}
+/**
+ * Split files into batches that each fit in one submission.
+ *
+ * Pure function: no file system, no network. Same input, same output.
+ *
+ * Rules:
+ * - a batch holds at most `BATCH_TARGET_BYTES` of file content;
+ * - a batch holds at most `MAX_PAGES_PER_JOB` images. That count is exact, not a
+ *   lower bound like `checkSubmission`'s: a PDF always flushes the current batch
+ *   and takes one of its own, so a batch being filled here only ever holds images,
+ *   and an image is always exactly 1 page;
+ * - **every PDF gets a batch to itself.** The SDK does not parse PDFs (zero
+ *   dependencies), so the client cannot know how many pages one holds. Mixed into
+ *   a batch, an unknown page count could push the job over the page limit with no
+ *   way to predict it. Alone, the job is exactly that one PDF and the server's own
+ *   count decides;
+ * - input order is preserved, so the same files always plan the same way.
+ *
+ * @throws InvalidFileError A single file is over `MAX_FILE_BYTES`. No batching can
+ *   help — the server rejects that file however it is submitted.
+ */
+export function planBatches(items) {
+    const batches = [];
+    let current = [];
+    let currentBytes = 0;
+    const flush = () => {
+        if (current.length) {
+            batches.push(current);
+            current = [];
+            currentBytes = 0;
+        }
+    };
+    for (const item of items) {
+        // Stricter than the request cap and checked first: a file over the per-file
+        // limit is unsubmittable, not merely unbatchable.
+        checkFileSize(item.path, item.size);
+        if (item.isPdf) {
+            flush();
+            batches.push([item]);
+            continue;
+        }
+        // A file bigger than the batch target still gets uploaded — alone. The
+        // `current.length` guard means we only start a new batch to make room, never
+        // refuse to place an item.
+        if (current.length &&
+            (currentBytes + item.size > BATCH_TARGET_BYTES ||
+                current.length + 1 > MAX_PAGES_PER_JOB)) {
+            flush();
+        }
+        current.push(item);
+        currentBytes += item.size;
+    }
+    flush();
+    return batches;
+}
+//# sourceMappingURL=limits.js.map