craterview 0.4.26 → 0.4.29

package/README.md

@@ -1,6 +1,6 @@
 # craterview
 
-TypeScript client for the [CraterView](https://craterview.ai) image enhancement and
+TypeScript client for the [CraterView.ai](https://craterview.ai) image enhancement and
 restoration API.
 
 ```bash
@@ -45,7 +45,7 @@ reimplement.
 Build against `echo` first. It costs no credits, needs no GPU and returns a real result — a
 plain upscale — so the request, the parameters and the response are the ones a paid model
 gives, and your integration needs no change when you switch. When you are ready, swap the
-model name for the one you want.
+model id for the one you want.
 
 ```ts
 const job = await cv.run(file, {
@@ -57,7 +57,7 @@ const job = await cv.run(file, {
 const blob = await job.blob();
 ```
 
-A parameter one model publishes is not one another accepts — `cv.models()` says which — and
+A parameter one model publishes is not necessarily one another accepts — `cv.models()` says which — and
 a value a model does not publish is refused at submit rather than ignored.
 
 ## An API key
@@ -109,7 +109,7 @@ a presigned URL and `blob()` GETs the result the same way; the API moves keys, n
 
 ## Retries are yours to write
 
-**Outside `run()` and `waitFor()`, this client does not retry.** `run()` asks its submission
+**Outside `run()` and `waitFor()`, this client does not retry.** `run()` sends its submission
 once more, under one idempotency key, when the first got no answer or a failure on the
 platform's side, and `waitFor()` reads on through the same until its timeout; neither can make a
 second job. Every other call is sent once. That is deliberate: only the caller knows where one
@@ -152,7 +152,7 @@ above tells the two apart.
 
 | Class | Meaning |
 |---|---|
-| `RateLimited` | 429 — one of five limits, and `.code` says which: `rate_limited` (the key's request rate), `too_many_uploads`, `too_many_keys`, `too_many_jobs` or `queue_full`. `.retryAfter` is seconds to wait: until the window rolls over for the two per-minute limits, until a new key can be made for the hourly one, or an interval to poll on for the other two. |
+| `RateLimited` | 429 — one of five limits, and `.code` says which: `rate_limited` (the account's request rate), `too_many_uploads`, `too_many_keys`, `too_many_jobs` or `queue_full`. `.retryAfter` is seconds to wait: until the window rolls over for the two per-minute limits, until a new key can be made for the hourly one, 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; `.jobId` is the job. |
 | `InvalidSignature` | A webhook delivery did not verify. Do not act on its body. |
 | `CraterViewError` | Everything else, including 4xx and 5xx from the API, and storage refusing an upload or a download. |
@@ -187,8 +187,9 @@ result's file are getters onto `result.output` rather than separate fields — t
 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
+`credits` is the only figure about cost the API states, and each model publishes its price in
+`cv.models()` — `credits_per_image`, and `credit_steps` where a smaller image costs less — so
+an invoice reconciles against `credits` alone. For how long a job took, subtract
 `createdAt` from `finishedAt` — that is the wait you had, queue included.
 
 **Uploads declare their size.** `upload()` and `run()` take the length from the `Blob`
@@ -197,8 +198,8 @@ 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 and run, and charged when it succeeds — it goes to the community queue, which runs
-on shared, free capacity and can wait longer at busy times. It comes back with `community`
+accepted, and unless a subscription has work left this period it runs free on the community
+queue, which runs on shared, free capacity and can wait longer at busy times. It comes back with `community`
 set, and `usage()` reports the same flag for your next job before you send it. There is no
 payment error to handle: paying — with credit, or with a subscription — moves work onto paid
 compute that scales with demand, rather than buying the right to submit.
@@ -327,7 +328,7 @@ to storage and have five minutes.
 ## From Claude Code
 
 This repository is also a Claude Code marketplace. Two plugins: `craterview` connects
-CraterView's hosted tools so the assistant enhances images in the conversation, and
+CraterView.ai's hosted tools so the assistant enhances images in the conversation, and
 `craterview-api` teaches an agent to call the API from code with this client. See
 [`plugins/`](plugins/) for what each does and how it finds a key.
 
@@ -340,7 +341,7 @@ CraterView's hosted tools so the assistant enhances images in the conversation,
 ## Versioning
 
 Semver, from `0.1.0` on. A release that removes an exported member, renames a field on `Job`
-or `ModelInfo`, or changes the type of one, gets a minor bump while this is `0.x` and a major
+or `ModelInfo`, or changes the type of one gets a minor bump while this is `0.x` and a major
 bump after `1.0.0`; anything purely additive gets a patch. Pin what you depend on.
 
 The API this wraps adds fields to its responses without warning, so treat an unfamiliar key in

package/index.ts

@@ -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.4.26";
+export const VERSION = "0.4.29";
 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.
@@ -154,7 +154,8 @@ export class CraterViewError extends Error {
  * says which — `rate_limited`, `too_many_keys`, `too_many_uploads`, `too_many_jobs` or
  * `queue_full`, in this order:
  *
- * - the key's request rate, per minute;
+ * - the account's request rate, per minute — counted across all its keys, for submitting
+ *   jobs, creating keys and gallery calls. No other call counts;
  * - the account's new keys, per hour — counted across all its keys, and only from
  *   `createKey`;
  * - the account's upload URLs, per minute — counted across all its keys;
@@ -336,11 +337,19 @@ function timingSafeEqual(a: string, b: string): boolean {
  * with `JobData` — there is no wrapper class here because there is no behavior to add.
  */
 export interface ModelInfo {
-  /** The public name, and what you pass as `model` when submitting. */
-  name: string;
-  version: string;
+  /** What you pass as `model` when submitting. Not for showing to a person; that is `title`. */
+  id: string;
+  /**
+   * Which revision of this model is in service. It changes when the same input gives a
+   * different result, while the id stays the same; record it to explain an old result later.
+   */
+  revision: string;
+  /** What to call this model when talking to a person. */
   title: string;
+  /** What this model is for and when to choose it over another; for a program or an agent. */
   description: string;
+  /** What this model does, in one short line for a person choosing it in an app. */
+  help: string;
   accepts: string[];
   /**
    * The media type a result usually comes back as, and advisory: a model that keeps the
@@ -365,6 +374,12 @@ export interface ModelInfo {
    * utility or fun experiment.
    */
   tenure?: "fixed" | "comet";
+  /**
+   * Whether this is a model for testing an integration rather than for use: free, and it
+   * returns a result of the right size without improving the picture. `echo` is one.
+   * CraterView's apps do not offer it; an app built on this catalog should leave it out too.
+   */
+  test_model?: boolean;
   max_input_bytes: number;
   /**
    * The ceilings **your key** is held to, not the model's widest. Community work is bounded
@@ -372,16 +387,16 @@ export interface ModelInfo {
    * before uploading rather than learning them from a rejected job.
    *
    * `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.
+   * still is one frame. `max_frames` bounds how many frames one job may carry. Null means
+   * nothing bounds that axis for you; a limit is never 0.
    *
    * 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
    * is one that can disagree with itself, and frames are what the platform counts, enforces
    * and bills on.
    */
-  max_frame_megapixels: number;
-  max_frames: number;
+  max_frame_megapixels: number | null;
+  max_frames: number | null;
   /**
    * 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
@@ -392,44 +407,53 @@ export interface ModelInfo {
    *
    * ```ts
    * const result = megapixels * scale ** 2;
-   * if (model.max_output_megapixels && result > model.max_output_megapixels) {
+   * if (model.max_output_megapixels !== null && 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.
+   * enlargement keeps the whole picture. Null means nothing bounds it for you.
    */
-  max_output_megapixels: number;
+  max_output_megapixels: number | null;
   /**
-   * The most of a picture this model works on in one job, in megapixels: the region you
+   * The most of a picture one job may work on for you, in megapixels: the region you
    * name with `roi`, or the whole image. Where it is set it binds at every enlargement, so
    * the largest frame you may send is the smaller of this and `max_output_megapixels`
    * divided by the square of the enlargement — and asking for less enlargement does not
-   * help with it, where a smaller region does. Zero means this axis is unbounded for you.
+   * help with it, where a smaller region does. Null means nothing bounds it for you.
    */
-  max_input_megapixels: number;
+  max_input_megapixels: number | null;
   /**
-   * The most of a picture this model works on in one job with `denoise` sent as true, in
-   * megapixels; `max_input_megapixels` applies otherwise. Null for a model that takes no
-   * `denoise`. Zero means this axis is unbounded for you.
+   * The most of a picture one job may work on for you at each `binning` value, in megapixels,
+   * keyed by the value ("2x2", "3x3", ...); `max_input_megapixels` applies with binning off.
+   * Each is `max_output_megapixels` divided by the square of the largest scale that binning
+   * allows. Null for a model that takes no `binning`, or when nothing bounds it for you.
    */
-  max_denoise_input_megapixels?: number | null;
+  max_input_megapixels_by_binning?: Record<string, number> | null;
   /**
-   * The most of a picture this model works on in one job with `tiled` sent as true, in
-   * megapixels: the region you name with `roi`, or the whole image, worked on at its own
-   * resolution and returned at its own size. Without `tiled`, a larger picture is reduced
-   * rather than refused: see `working_megapixels`. Null for a model that takes no `tiled`.
+   * The shortest side, in pixels, of the part of a picture this model works on: the region
+   * you name with `roi`, or the whole image. A job with a shorter one fails before the model
+   * runs, as `input_too_small`, and is not charged. The same for every key.
    */
-  max_tiled_input_megapixels?: number | null;
+  min_input_side: number;
   /**
-   * The most this model works on at a picture's own resolution, in megapixels: a larger
-   * picture or region is reduced to about this area first and comes back at about this size,
-   * unless `tiled` is sent as true. Null for a model that works at the size it is given.
+   * Whole credits: what one still image costs, or the most one costs where `credit_steps`
+   * charges less for a smaller one. Knowable before you send anything.
    */
-  working_megapixels?: number | null;
-  /** Whole credits. The price is flat and knowable before you send anything. */
   credits_per_image: number;
+  /**
+   * A lower price for a smaller still image, or null where every one costs
+   * `credits_per_image`. `by` is `megapixels` — the part of the image a job works on, the
+   * region you name with `roi` or the whole image, in millions of pixels, divided by 4 at
+   * `binning` 2x2, 9 at 3x3 and 16 at 4x4 — or `faces`, the faces the model redraws, counted
+   * when the job finishes. A still costs the first step its measure is at or under, and
+   * `credits_per_image` past the last.
+   */
+  credit_steps?: {
+    by: "megapixels" | "faces";
+    steps: { up_to: number; credits: number }[];
+  } | null;
   /** Whole credits. Null means this model takes stills only. */
   credits_per_video_second?: number | null;
   reference_fps: number;
@@ -439,6 +463,12 @@ export interface ModelInfo {
    * not order an object's keys, so a form drawn from the schema reads its order from here.
    */
   params_order: string[];
+  /**
+   * A short line for a person choosing each setting in a form, keyed by parameter name: every
+   * parameter in `params_schema` that one control can set. Show it under the control. For what
+   * a value may be and what may be sent together, read `params_schema`.
+   */
+  params_help: Record<string, string>;
   /**
    * 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.
@@ -466,7 +496,6 @@ export interface KeyInfo {
   created_at: string | null;
   /** When it stopped working, or null while it still does. */
   revoked_at?: string;
-  rate_limit_per_minute: number;
   /**
    * Whether this is the key you are calling with. It cannot be revoked by id while it is;
    * `DELETE /v1/keys/current` ends it on request, unless it is the account's only way
@@ -482,7 +511,6 @@ export interface NewKey {
   key: string;
   prefix: string;
   name: string;
-  rate_limit_per_minute: number;
 }
 
 /**
@@ -1023,7 +1051,9 @@ export class CraterView {
    * 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. A balance of zero never stops a
+   * The balance is `credits_remaining`; `credits_spent` is what the account has spent, all
+   * time, and `credits_granted` what it has been given. `credits_remaining` is always a
+   * number, floored at zero. A balance of zero never stops a
    * submission: `community` says whether your next job runs on the community queue, which is
    * free and can wait longer at busy times, or on paid compute. `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,10 +1,10 @@
 {
   "name": "craterview",
-  "version": "0.4.26",
+  "version": "0.4.29",
   "dependencies": {
     "image-size": "^2.0.4"
   },
-  "description": "TypeScript client for the CraterView image enhancement API",
+  "description": "TypeScript client for the CraterView.ai image enhancement API",
   "type": "module",
   "main": "index.ts",
   "types": "index.ts",
@@ -25,10 +25,10 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.6",
     "esbuild": "^0.28.2",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.5"
   }
 }