craterview 0.3.12 → 0.3.16

package/README.md

@@ -13,9 +13,11 @@ compiles this too: any bundler, `tsx` or `ts-node`, Bun, Deno, or Node 22.6 and
 type stripping (`--experimental-strip-types`, which recent releases enable by default). A
 plain JavaScript project invoking `node` directly cannot import it.
 
-The code itself needs Node 18 or newer, or any modern browser. **Zero runtime
-dependencies** — `fetch`, `Blob` and `crypto.getRandomValues` are standard in both, so the
-client installs without dragging a transitive tree behind it.
+The code itself needs Node 18 or newer, or any modern browser. **One runtime dependency**,
+[`image-size`](https://www.npmjs.com/package/image-size), pure JavaScript that runs in
+both: it reads an image's dimensions from its header — nothing is decoded — so `upload()`
+can tell the API how big your file is and `etaSeconds` is estimated for that file rather
+than for a typical one. `fetch`, `Blob` and `crypto.getRandomValues` are standard in both.
 
 ## Quickstart
 
@@ -150,7 +152,7 @@ Every field the API publishes on a job is exposed here.
 | `error` | Set when the job failed. Safe to show a user |
 | `errorCode` | The same fact, as a stable identifier. Branch on this, show the other |
 | `credits` | **What you were billed** |
-| `etaSeconds` | Seconds until the job is expected to finish, recomputed on every read — it counts down while the job runs. Absent once the job has settled |
+| `etaSeconds` | Seconds until the job is expected to finish, recomputed on every read — it counts down while the job runs. Absent once the job has settled. Estimated for your image's size when `upload()` could read it (or when you pass `inputMegapixels` to `submit()`), for a typical image otherwise |
 | `community` | True when the job is on the community queue: served after priority work, always taking a share of it, so it never stalls behind paid work |
 | `outputUrl`, `downloadUrl` | The result, presigned. One to display, one to save |
 | `thumbUrl` | A small JPEG of the result, for listings. Null when none was drawn |

package/index.ts

@@ -7,14 +7,18 @@
  *   const job = await cv.run(file, { style: "photo" });
  *   const blob = await job.blob();
  *
- * Zero dependencies: fetch and Blob are standard in Node 18+ and every browser, so the
- * client stays installable anywhere without dragging a transitive tree behind it.
+ * One dependency: `image-size`, which reads an image's dimensions from its header — no
+ * decoding — so the client can tell the API how big the file you sent is and get a wait
+ * estimated for that file rather than a typical one. fetch and Blob are standard in Node 18+
+ * and every browser, and `image-size` runs in both, so the client stays installable anywhere.
  */
 
+import { imageSize } from "image-size";
+
 // Mirrored from package.json, which is the number a release bumps. It cannot be imported
 // from there — this ships as TypeScript, so the import would have to resolve in the
 // consumer's toolchain — so test/version.test.ts asserts the two agree.
-export const VERSION = "0.3.12";
+export const VERSION = "0.3.16";
 const DEFAULT_BASE_URL = "https://api.craterview.ai";
 // The server rejects a longer wait outright, so asking for one costs a 422 rather than the
 // wait you asked for. `run()` clamps to this rather than letting that happen.
@@ -327,6 +331,13 @@ export interface WebhookEvent extends Required<JobData> {}
 
 export type JobStatus = "queued" | "running" | "succeeded" | "failed";
 
+/** A job's standing with the public gallery: `pending` under review, `approved` once shown. */
+export interface GalleryState {
+  status: "pending" | "approved";
+  /** The submission's id, which is what withdrawing it takes. */
+  post_id: string;
+}
+
 /** The API's job representation, exactly as it arrives. Snake case is the wire's. */
 export interface JobData {
   id: string;
@@ -362,6 +373,18 @@ export interface JobData {
   eta_seconds?: number | null;
   /** Retained past the ordinary expiry because its owner asked, links and all. */
   kept?: boolean;
+  /**
+   * Whether the kept copy includes the image you sent as well as the result. It does when
+   * you kept the job while the original was still there; false when only the result is
+   * kept, and when nothing is.
+   */
+  kept_original?: boolean;
+  /**
+   * Where this job stands with the public gallery, when you have offered it: present while
+   * it is being reviewed or shown, absent or null when it is not offered — including after
+   * you withdraw it.
+   */
+  gallery?: GalleryState | null;
   community?: boolean;
   /**
    * Whether an automated check thought this image may fall outside what the service
@@ -423,6 +446,12 @@ export class Job {
   // checked, and `false` would say it was checked and cleared. The two are different
   // answers and only one of them is true.
   get flagged() { return this.data.flagged ?? null; }
+  /** Retained past the ordinary expiry because you asked. */
+  get kept() { return this.data.kept ?? false; }
+  /** Whether the kept copy holds the image you sent as well as the result. */
+  get keptOriginal() { return this.data.kept_original ?? false; }
+  /** Where this job stands with the public gallery, or null when it is not offered. */
+  get gallery() { return this.data.gallery ?? null; }
   /** The whole answer, including where the file is when there is one. */
   get result() { return this.data.result ?? null; }
   /**
@@ -485,6 +514,23 @@ export interface CraterViewOptions {
   baseUrl?: string;
 }
 
+/**
+ * Width × height ÷ 10⁶ from the file's header, or `undefined` for a file the reader does not
+ * know. Reads the first megabyte only — every format's dimensions sit near the front, and a
+ * Blob of any size costs one bounded copy — and never throws: a size the client cannot read
+ * is simply not declared.
+ */
+async function megapixelsOf(blob: Blob): Promise<number | undefined> {
+  try {
+    const head = new Uint8Array(await blob.slice(0, 1 << 20).arrayBuffer());
+    const { width, height } = imageSize(head);
+    if (!width || !height) return undefined;
+    return Math.round((width * height) / 1e6 * 1e4) / 1e4 || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export interface SubmitOptions {
   wait?: number;
   idempotencyKey?: string;
@@ -500,6 +546,14 @@ export interface SubmitOptions {
    * becomes a model parameter, is checked against the model's schema, and would be refused.
    */
   customId?: string;
+  /**
+   * The size of the file you uploaded, in megapixels (width × height ÷ 1,000,000). Used
+   * only to estimate `eta_seconds` for your image rather than for a typical one — it does
+   * not affect the price, the queue or whether the job is accepted, all of which read the
+   * file itself. Left unset, the size `upload()` read from the file is sent for a key this
+   * client uploaded; set it to override or to supply one for a key uploaded elsewhere.
+   */
+  inputMegapixels?: number;
   model?: string;
   [param: string]: unknown;
 }
@@ -507,6 +561,10 @@ export interface SubmitOptions {
 export class CraterView {
   private readonly baseUrl: string;
   private readonly headers: Record<string, string>;
+  // What `upload()` read from each file's header, by the key it came back with, so a later
+  // `submit()` of that key declares the size without the caller carrying it. Bounded: a
+  // long-lived client uploading thousands of files keeps the most recent few hundred.
+  private readonly sizes = new Map<string, number>();
 
   constructor(options: CraterViewOptions = {}) {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
@@ -564,6 +622,11 @@ export class CraterView {
   /**
    * Put an image in storage and return its key. Bytes go straight to object storage on a
    * presigned URL, never through the API.
+   *
+   * The image's size is read from its header on the way past and remembered against the
+   * key, so `submit()` can tell the API what you sent and `eta_seconds` is estimated for
+   * your image rather than a typical one. A file the reader does not know is uploaded just
+   * the same; only the estimate is less specific.
    */
   async upload(image: Blob | ArrayBuffer | Uint8Array, contentType?: string): Promise<string> {
     const blob = image instanceof Blob
@@ -581,6 +644,11 @@ export class CraterView {
       method: "PUT", body: blob, headers: { "Content-Type": type },
     });
     if (!put.ok) throw new CraterViewError(`upload failed: ${put.status}`);
+    const megapixels = await megapixelsOf(blob);
+    if (megapixels) {
+      if (this.sizes.size >= 512) this.sizes.delete(this.sizes.keys().next().value!);
+      this.sizes.set(slot.input_key, megapixels);
+    }
     return slot.input_key;
   }
 
@@ -592,8 +660,9 @@ export class CraterView {
    * job and is billed for both.
    */
   async submit(inputKey: string, options: SubmitOptions = {}): Promise<Job> {
-    const { wait = 0, idempotencyKey, webhookUrl, customId, model = "cv-enhance-v3",
-            ...params } = options;
+    const { wait = 0, idempotencyKey, webhookUrl, customId, inputMegapixels,
+            model = "cv-enhance-v3", ...params } = options;
+    const declared = inputMegapixels ?? this.sizes.get(inputKey);
     // Annotated, not inferred: without this the two branches unify to a type whose key
     // may be `undefined`, which is not assignable to Record<string, string>.
     const headers: Record<string, string> = idempotencyKey
@@ -603,6 +672,7 @@ export class CraterView {
       model, input_key: inputKey, params,
       ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
       ...(customId ? { custom_id: customId } : {}),
+      ...(declared && declared > 0 ? { input_megapixels: declared } : {}),
     }, headers);
     return new Job(data);
   }

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "craterview",
-  "version": "0.3.12",
-  "dependencies": {},
+  "version": "0.3.16",
+  "dependencies": {
+    "image-size": "^2.0.4"
+  },
   "description": "TypeScript client for the CraterView image enhancement API",
   "type": "module",
   "main": "index.ts",
@@ -24,6 +26,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
+    "esbuild": "^0.25.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"
   }