craterview 0.3.16 → 0.3.19

package/README.md

@@ -8,10 +8,19 @@ npm install craterview
 ```
 
 **The package ships TypeScript source.** `index.ts` is what npm installs — there is no build
-step and no compiled JavaScript in the tarball — so whatever compiles your own TypeScript
-compiles this too: any bundler, `tsx` or `ts-node`, Bun, Deno, or Node 22.6 and newer with
-type stripping (`--experimental-strip-types`, which recent releases enable by default). A
-plain JavaScript project invoking `node` directly cannot import it.
+step and no compiled JavaScript in the tarball — so it needs a toolchain that compiles
+TypeScript inside `node_modules`. Two that do, and are tested against the published package:
+
+```bash
+npx tsx main.ts                  # run a script directly
+
+npx esbuild main.js --bundle --platform=node --format=esm --outfile=main.bundle.mjs
+node main.bundle.mjs             # or bundle first, for plain JavaScript projects
+```
+
+A front-end bundler works the same way, provided its TypeScript step is not configured to
+skip `node_modules`. **Node on its own cannot import it**, type stripping included: Node
+strips types only from your own files and refuses any `.ts` file under `node_modules`.
 
 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
@@ -132,7 +141,7 @@ Everything thrown by this client extends `CraterViewError`, so one `catch` handl
 
 | Class | Meaning |
 |---|---|
-| `RateLimited` | 429. `.retryAfter` is seconds to wait: until the window rolls over for the request rate, or a short fixed interval to poll on for the in-flight cap. |
+| `RateLimited` | 429 — one of four limits, and the message says which: the key's request rate, the account's upload URLs a minute, the account's jobs in flight, or a full queue. `.retryAfter` is seconds to wait: until the window rolls over for the two per-minute limits, or an interval to poll on for the other two. |
 | `JobFailed` | The job ran and did not succeed. `.message` says what you can do about it; `.errorCode` is the half to branch on. |
 | `CraterViewError` | Everything else, including 4xx and 5xx from the API. |
 
@@ -155,16 +164,17 @@ Every field the API publishes on a job is exposed here.
 | `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 |
-| `inputUrl` | The file you sent. Null once it has expired — inputs go after a day |
+| `thumbnailUrl` | A small JPEG of the job's picture, for listings — the result, or what the model worked from when it produced no file. Null when none was drawn |
+| `inputUrl` | The picture the model worked from — the region, where you named one |
+| `alphaUrl` | Only for a JPEG result of a picture with transparency, which JPEG cannot hold: the transparency as a grayscale JPEG, white where opaque. The result is then the colour alone |
 | `contentType` | The result's media type |
 | `outputBytes` | The result's size in bytes |
 | `blob()`, `arrayBuffer()` | Download the result |
 
-`result` is the whole of what the job produced, and the five rows above it that describe the
-file are getters onto `result.output` rather than separate fields — the API states those links
-once. A model with no file to hand back returns its answer in `result` and leaves every one of
-them null.
+`result` is the whole of what the job produced, and the rows above it that describe the
+result's file are getters onto `result.output` rather than separate fields — the API states
+those links once. A model with no file to hand back returns its answer in `result` and leaves
+every one of them null; the fields it answers with are its `result_schema` in `cv.models()`.
 
 `credits` is the only figure about cost the API states, and the price is fixed and published
 per model, so an invoice reconciles against `credits` alone. For how long a job took, subtract
@@ -176,7 +186,7 @@ accepts exactly that length and nothing else. You do not pass it — it is read
 in hand, which is what makes it impossible to get wrong.
 
 **Running out of credit does not stop you.** A job submitted against a balance of zero is
-accepted, charged and run — it simply waits in the community queue, which is served after
+accepted and run, and charged when it succeeds — it simply waits in the community queue, which is served after
 paid work and always takes a share of it, so it never stalls behind paid work. It comes back
 with `community` set. There is no payment error to handle:
 paying — with credit, or with a subscription — buys a place at the front of the queue rather
@@ -188,11 +198,13 @@ a longer one.
 is signed in, so the second cannot be derived from the first. Both expire, so fetch the
 result rather than storing the link.
 
-`thumbUrl` and `inputUrl` are for building a job listing: a few-hundred-pixel preview so a
-page of results costs kilobytes, and the original so a result can be shown against what made
-it. They keep very different company on expiry — the preview lives as long as the result,
-while inputs are deleted a day in — so treat a missing `inputUrl` as normal rather than as an
-error.
+`thumbnailUrl` and `inputUrl` are for building a job listing: a few-hundred-pixel preview so a
+page of jobs costs kilobytes, and the picture the model worked from so a result can be
+shown against it. Where you named a region, `inputUrl` is that region — so a before-and-after
+is a true pair, and what was used is something you can look at rather than something to take
+on trust. It is not the file you uploaded: yours stays yours and is removed on its own
+schedule. Both expire with the job's other pictures. A model that produces no file has no
+result to preview, so `thumbnailUrl` is a preview of the picture it answered about.
 
 ## Webhooks
 
@@ -268,7 +280,7 @@ old one. You cannot revoke the key you are calling with.
 ## Everything else
 
 ```ts
-await cv.models();                            // models, parameter schemas, which queue you are on
+await cv.models();                            // models, what each takes and answers with, which queue you are on
 await cv.job("job_...");                      // one job by id
 await cv.usage();                             // credit balance, spend and job counts
 

package/index.ts

@@ -4,7 +4,7 @@
  *   import { CraterView } from "craterview";
  *
  *   const cv = new CraterView({ apiKey: "cv_..." });
- *   const job = await cv.run(file, { style: "photo" });
+ *   const job = await cv.run(file, { scale: 4 });
  *   const blob = await job.blob();
  *
  * One dependency: `image-size`, which reads an image's dimensions from its header — no
@@ -18,7 +18,7 @@ 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.16";
+export const VERSION = "0.3.19";
 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.
@@ -35,7 +35,7 @@ const MAX_PAGE = 200;
  *   const key = newIdempotencyKey();          // once, before the first attempt
  *   for (let attempt = 0; attempt < 3; attempt++) {
  *     try {
- *       job = await cv.submit(inputKey, { idempotencyKey: key, style: "photo" });
+ *       job = await cv.submit(inputKey, { idempotencyKey: key, scale: 4 });
  *       break;
  *     } catch (e) {
  *       if (!(e instanceof CraterViewError)) continue;  // same key, at most one job
@@ -70,15 +70,20 @@ export class CraterViewError extends Error {
 }
 
 /**
- * 429 — too fast, or too much at once. Two different limits answer with this: the key's
- * request rate, and the account's cap on jobs queued or running at the same time, which
- * exists so one caller cannot occupy the whole fleet.
+ * 429 — too fast, or too much at once. Four different limits answer with this, and the
+ * message says which:
+ *
+ * - the key's request rate, per minute;
+ * - the account's upload URLs, per minute — counted across all its keys;
+ * - the account's cap on jobs queued or running at the same time, which exists so one
+ *   caller cannot occupy the whole fleet. `usage()` reports the cap and what you currently
+ *   hold against it;
+ * - the queue itself, when it is full and taking no more work. Nothing you sent is wrong;
+ *   an account with credit or a subscription submits on a queue that fills separately.
  *
  * `retryAfter` is seconds to wait, and what it means depends on which limit you hit: for
- * the rate limit it is when the window rolls over; for the in-flight cap it is a fixed
- * short interval to poll on, since a slot frees when one of your own jobs finishes and
- * nothing here predicts that. `usage()` reports the cap and what you currently hold
- * against it.
+ * the two per-minute limits it is when the window rolls over; for the in-flight cap and the
+ * full queue it is an interval to poll on, since nothing here predicts when a slot frees.
  */
 export class RateLimited extends CraterViewError {
   constructor(message: string, readonly retryAfter?: number) {
@@ -92,7 +97,7 @@ export class RateLimited extends CraterViewError {
  *
  * `message` says what you can do about it and `errorCode` is the half to branch on, because
  * the prose is written for a person and gets reworded. `inference_failed` means the fault was
- * ours, the credits were refunded, and the same call is worth making again.
+ * ours, nothing was charged, and the same call is worth making again.
  *
  * An unfamiliar code is a failure with no special handling, not an error in itself: new ones
  * appear as new things become worth telling apart.
@@ -261,10 +266,9 @@ export interface ModelInfo {
    * more tightly than paid work, so these move when `community` below does — check them
    * before uploading rather than learning them from a rejected job.
    *
-   * Two axes, and they are the two a job is made of. `max_frame_megapixels` bounds one
-   * frame, which is what a GPU actually holds, and applies to images too since a still is one
-   * frame. `max_frames` bounds how many frames one job may carry. Zero means that axis is
-   * unbounded for you.
+   * `max_frame_megapixels` bounds one frame you send, and applies to images too since a
+   * still is one frame. `max_frames` bounds how many frames one job may carry. Zero means
+   * that axis is unbounded for you.
    *
    * For a duration, divide: `max_frames / reference_fps` is the longest clip you may send, in
    * seconds. It is not published as its own field on purpose — one limit with two spellings
@@ -273,12 +277,36 @@ export interface ModelInfo {
    */
   max_frame_megapixels: number;
   max_frames: number;
+  /**
+   * The largest frame you may get **back**, in megapixels, and for a model that enlarges it
+   * is the ceiling that decides whether a job runs: what returns is the frame you send
+   * multiplied by the enlargement in each direction, so a modest photograph at a large
+   * enlargement is refused where the same photograph unenlarged is not.
+   *
+   * Check it before uploading:
+   *
+   * ```ts
+   * const result = megapixels * scale ** 2;
+   * if (model.max_output_megapixels && result > model.max_output_megapixels) {
+   *   // send a smaller region of the image, or ask for less enlargement
+   * }
+   * ```
+   *
+   * Sending a smaller region keeps every pixel of what it covers; asking for less
+   * enlargement keeps the whole picture. Zero means this axis is unbounded for you.
+   */
+  max_output_megapixels: number;
   /** Whole credits. The price is flat and knowable before you send anything. */
   credits_per_image: number;
   /** Whole credits. Null means this model takes stills only. */
   credits_per_video_second?: number | null;
   reference_fps: number;
   params_schema: Record<string, unknown>;
+  /**
+   * JSON Schema for the fields a finished job of this model states under `result`, beside
+   * any files it links. Empty for a model whose whole answer is its file.
+   */
+  result_schema: Record<string, unknown>;
   /**
    * Whether your key's work goes to the community queue, which is served after priority
    * work and always takes a share of it, so it never stalls behind paid work. False while
@@ -304,8 +332,8 @@ export interface KeyInfo {
   rate_limit_per_minute: number;
   /**
    * Whether this is the key you are calling with. It cannot be revoked by id while it is;
-   * `endCurrentKey()` (`DELETE /v1/keys/current`) ends it on request, unless it is the
-   * account's only way back in.
+   * `DELETE /v1/keys/current` ends it on request, unless it is the account's only way
+   * back in. This client has no method for that call.
    */
   current: boolean;
 }
@@ -367,18 +395,17 @@ export interface JobData {
    * read them out of `result.output`.
    */
   result?: Record<string, unknown> | null;
-  input_url?: string | null;
+  /**
+   * A small JPEG of the job's picture, for a listing: the result, or the image the model
+   * worked from when it produced no file. Absent until the job succeeds, where none could be
+   * drawn, and once the job's pictures are deleted.
+   */
+  thumbnail_url?: string | null;
   /** Whole credits. TypeScript cannot say integer, but the API only ever sends one. */
   credits?: number | null;
   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
@@ -402,18 +429,18 @@ export interface JobData {
  * by the same names.
  *
  * `result` is the whole of what the job produced. Where the model wrote a file,
- * `result.output` carries its links, and `outputUrl` / `downloadUrl` / `thumbUrl` /
+ * `result.output` carries its links, and `outputUrl` / `downloadUrl` /
  * `contentType` / `outputBytes` read out of it. `outputUrl` and `downloadUrl` are the same
  * object signed two ways: one to display, one to hand a person as a file. The disposition
  * is signed in, so the second cannot be derived from the first without the storage
  * credential. Both are presigned and expire — fetch the result rather than storing the link.
  *
- * `thumbUrl` is a small JPEG of the result, for showing a page of jobs without downloading
- * a page of full-size outputs. `inputUrl` is the file you sent, so a result can be shown
- * against what it was made from. The two expire on very different clocks: the preview goes
- * with the result, while inputs are deleted after a day — much sooner than the output — so
- * `inputUrl` is null for most of a job's life and code that reads it should expect nothing
- * there.
+ * `thumbnailUrl` is a small JPEG of the job's picture — the result, or the image the model
+ * worked from when it produced no file — for showing a page of jobs without downloading a
+ * page of full-size pictures. `inputUrl` is the picture the model worked from, so a result
+ * can be shown against what it was made from. Both expire with the job's other pictures.
+ * `alphaUrl` is there only when you asked for a JPEG of a picture with transparency: the
+ * transparency, as a file of its own.
  *
  * `etaSeconds` is the whole of what is reported about waiting: how long until the result,
  * counting time spent waiting for a GPU as well as time spent on one. An estimate and never
@@ -448,8 +475,8 @@ export class Job {
   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; }
+  /** A small JPEG of the job's picture, for a listing. Null where there is none. */
+  get thumbnailUrl() { return this.data.thumbnail_url ?? null; }
   /** 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. */
@@ -473,8 +500,33 @@ export class Job {
    * the disposition is signed in, so re-signing needs the storage credential.
    */
   get downloadUrl() { return (this.output["download_url"] as string) ?? null; }
-  get thumbUrl() { return (this.output["thumbnail_url"] as string) ?? null; }
-  get inputUrl() { return this.data.input_url ?? null; }
+  /**
+   * A link to the picture the model worked from. Where you named a region, this is that
+   * region — so what was used is something you can look at rather than something to take on
+   * trust. It is not the file you uploaded: yours stays yours and is removed on its own
+   * schedule.
+   *
+   * Null for a job that has not finished. A model that answers about a picture rather than
+   * producing one has it too: it is the picture that answer is about.
+   */
+  get inputUrl() {
+    const given = (this.data.result ?? {})["input"];
+    return (given && typeof given === "object")
+      ? ((given as Record<string, unknown>)["url"] as string) ?? null
+      : null;
+  }
+  /**
+   * The transparency of a result you asked for as JPEG, which cannot hold it: a grayscale
+   * JPEG the size of the result, white where it is opaque and black where it is transparent.
+   * The result is then the colour alone, not placed on any background, so the two together
+   * are the picture. Null for every other result.
+   */
+  get alphaUrl() {
+    const mask = (this.data.result ?? {})["alpha"];
+    return (mask && typeof mask === "object")
+      ? ((mask as Record<string, unknown>)["url"] as string) ?? null
+      : null;
+  }
   get contentType() { return (this.output["content_type"] as string) ?? null; }
   get outputBytes() { return (this.output["bytes"] as number) ?? null; }
 
@@ -714,9 +766,9 @@ export class CraterView {
   /**
    * The account's credit balance, what it has spent, and what is in flight.
    *
-   * All-time, not monthly: credits are granted and deplete rather than renewing. Counts
-   * committed work rather than completed, so a queued job is already in the figures —
-   * otherwise this and the balance a submission is checked against would disagree.
+   * All-time, not monthly: credits are granted and deplete rather than renewing. A job is
+   * charged when it succeeds, so queued and running work is not in the figures yet, and a
+   * failed job costs nothing.
    *
    * `credits_remaining` is always a number, floored at zero. `jobs_in_flight` and
    * `max_jobs_in_flight` are the state of the queue and are what a 429 on submit is about.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craterview",
-  "version": "0.3.16",
+  "version": "0.3.19",
   "dependencies": {
     "image-size": "^2.0.4"
   },
@@ -27,6 +27,7 @@
   "devDependencies": {
     "@types/node": "^26.2.0",
     "esbuild": "^0.25.0",
+    "tsx": "^4.23.15",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"
   }