craterview 0.3.18 → 0.4.0

package/README.md

@@ -136,12 +136,16 @@ the same job.
 
 ## Errors
 
-Everything thrown by this client extends `CraterViewError`, so one `catch` handles the lot.
-`.status` carries the HTTP status where there was one.
+Every answer the API or storage gives that is not a success is thrown as a
+`CraterViewError`. `.status` carries the HTTP status where there was one, and `.traceId` the
+API's `X-Trace-Id` for a request it answered and refused — the id to quote when you ask us
+about it. A request that got
+no answer at all throws the runtime's own error from `fetch`, which is how the retry loop
+above tells the two apart.
 
 | Class | Meaning |
 |---|---|
-| `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. |
+| `RateLimited` | 429 — one of five limits, and the message says which: the key's request rate, the account's upload URLs a minute, the account's new keys an hour, 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, 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. |
 | `CraterViewError` | Everything else, including 4xx and 5xx from the API. |
 
@@ -162,19 +166,19 @@ Every field the API publishes on a job is exposed here.
 | `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. 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 |
+| `community` | True when the job is on the community queue, which runs on shared, free capacity and can wait longer at busy times |
 | `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 |
+| `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; the fields it answers with are its `result_schema` in `cv.models()`.
+`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
@@ -186,11 +190,11 @@ 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 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
-than the right to submit.
+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`
+set. 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.
 `etaSeconds` covers the whole wait, queue time included, so a community job simply reports
 a longer one.
 
@@ -198,13 +202,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 picture the model worked from so a result can be
+`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 result. A model that produces no file has no `thumbUrl`, but still
-has the picture it answered about.
+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
 
@@ -299,10 +303,14 @@ fetched as 200.
 new CraterView({
   apiKey: undefined,
   baseUrl: "https://api.craterview.ai",
+  timeoutMs: 60_000,
 });
 ```
 
-`baseUrl` is what you change to point at a local server.
+`baseUrl` is what you change to point at a local server. `timeoutMs` is how long to wait for
+the API to answer before giving up with the runtime's `TimeoutError` — nothing answered, so
+it is a request to repeat with the same idempotency key. Uploads and downloads go to storage
+and have five minutes.
 
 ## From Claude Code
 

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.3.18";
+export const VERSION = "0.4.0";
 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.
@@ -62,18 +62,25 @@ export function newIdempotencyKey(): string {
   return `idem_${base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")}`;
 }
 
+/**
+ * `status` is the HTTP status where there was one. `traceId` is the API's `X-Trace-Id` for a
+ * request it answered and refused — the id to quote when asking about it. Absent when the
+ * refusal came from storage rather than the API.
+ */
 export class CraterViewError extends Error {
-  constructor(message: string, readonly status?: number) {
+  constructor(message: string, readonly status?: number, readonly traceId?: string) {
     super(message);
     this.name = "CraterViewError";
   }
 }
 
 /**
- * 429 — too fast, or too much at once. Four different limits answer with this, and the
+ * 429 — too fast, or too much at once. Five different limits answer with this, and the
  * message says which:
  *
  * - the key's request rate, per minute;
+ * - 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;
  * - 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
@@ -82,12 +89,13 @@ export class CraterViewError extends Error {
  *   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 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.
+ * the two per-minute limits it is when the window rolls over; for new keys, when the account
+ * may be given another; 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) {
-    super(message, 429);
+  constructor(message: string, readonly retryAfter?: number, traceId?: string) {
+    super(message, 429, traceId);
     this.name = "RateLimited";
   }
 }
@@ -308,9 +316,9 @@ export interface ModelInfo {
    */
   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
-   * the account is paying — holding credit, or on a subscription.
+   * Whether your key's work goes to the community queue, which runs on shared, free capacity
+   * and can wait longer at busy times. False while the account is paying — holding credit, or
+   * on a subscription — which puts its work on paid compute that scales with demand.
    *
    * The same field, meaning the same thing, as `Job.community`. How long a wait will be
    * is answered on the job, once you have one — `Job.eta_seconds` — and nowhere else.
@@ -328,7 +336,7 @@ export interface KeyInfo {
   name: string;
   created_at: string | null;
   /** When it stopped working, or null while it still does. */
-  revoked_at: string | null;
+  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;
@@ -395,6 +403,12 @@ export interface JobData {
    * read them out of `result.output`.
    */
   result?: Record<string, unknown> | 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;
@@ -423,28 +437,30 @@ 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 picture the model worked from, so a result
- * can be shown against what it was made from. Both expire with the result. `alphaUrl` is
- * there only when you asked for a JPEG of a picture with transparency: the transparency, as
- * a file of its own.
+ * `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
  * a promise — read it as guidance, not a deadline. Absent once a job has settled.
  *
- * `community` says the job is on the queue served after priority work, which always takes
- * a share of it rather than only what is left over — so it waits longer at busy times and
- * never stalls behind paid work. That is where an account goes when it has not
- * paid for priority — by holding credit or by subscribing. Nothing is refused for want of
- * either: paying buys a place at the front of the queue, not the right to submit, so an
- * account that has not paid means a longer wait and never an error.
+ * `community` says the job is on the community queue, which runs on shared, free capacity —
+ * so it waits longer at busy times, and never stops. That is where an account's work goes
+ * when it is not paying, by holding credit or by subscribing. An empty balance is never itself
+ * a reason to refuse a job — paying moves work onto paid compute that scales with demand, not
+ * the right to submit — but on some models the community queue takes smaller files.
+ * `models()` lists each model's limits for your key, and a file over them is refused with
+ * the limit named.
  */
 export class Job {
   constructor(private readonly data: JobData) {}
@@ -468,6 +484,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; }
+  /** 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. */
@@ -491,7 +509,6 @@ 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; }
   /**
    * 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
@@ -543,8 +560,10 @@ export class Job {
     if (!url) {
       throw new CraterViewError(`job ${this.id} has no result (status ${this.status})`);
     }
-    const resp = await fetch(url);
-    if (!resp.ok) throw new CraterViewError(`downloading result failed: ${resp.status}`);
+    const resp = await fetch(url, { signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS) });
+    if (!resp.ok) {
+      throw new CraterViewError(`downloading result failed: ${resp.status}`, resp.status);
+    }
     return await resp.blob();
   }
 
@@ -556,8 +575,18 @@ export class Job {
 export interface CraterViewOptions {
   apiKey?: string;
   baseUrl?: string;
+  /**
+   * Milliseconds to wait for the API to answer a request before giving up, 60 000 by default.
+   * A request that times out throws the runtime's `TimeoutError`, not a `CraterViewError`:
+   * nothing answered, so it is one to repeat with the same idempotency key. Uploads and
+   * downloads go to storage and are given five minutes whatever this says.
+   */
+  timeoutMs?: number;
 }
 
+/** How long a transfer to or from storage may take, however large the picture. */
+const TRANSFER_TIMEOUT_MS = 300_000;
+
 /**
  * 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
@@ -605,6 +634,7 @@ export interface SubmitOptions {
 export class CraterView {
   private readonly baseUrl: string;
   private readonly headers: Record<string, string>;
+  private readonly timeoutMs: number;
   // 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.
@@ -612,6 +642,7 @@ export class CraterView {
 
   constructor(options: CraterViewOptions = {}) {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = options.timeoutMs ?? 60_000;
     this.headers = { "User-Agent": `craterview-ts/${VERSION}` };
     if (options.apiKey) this.headers["Authorization"] = `Bearer ${options.apiKey}`;
   }
@@ -619,6 +650,7 @@ export class CraterView {
   private async request<T>(method: string, path: string, body?: unknown,
                            extraHeaders: Record<string, string> = {}): Promise<T> {
     const resp = await fetch(`${this.baseUrl}${path}`, {
+      signal: AbortSignal.timeout(this.timeoutMs),
       method,
       headers: { ...this.headers, ...extraHeaders,
                  ...(body ? { "Content-Type": "application/json" } : {}) },
@@ -627,10 +659,11 @@ export class CraterView {
 
     if (!resp.ok) {
       const detail = await this.detail(resp);
+      const traceId = resp.headers.get("X-Trace-Id") ?? undefined;
       if (resp.status === 429) {
-        throw new RateLimited(detail, Number(resp.headers.get("Retry-After") ?? 0));
+        throw new RateLimited(detail, Number(resp.headers.get("Retry-After") ?? 0), traceId);
       }
-      throw new CraterViewError(detail, resp.status);
+      throw new CraterViewError(detail, resp.status, traceId);
     }
     // A 204 carries no body, so asking for JSON throws on a call that succeeded.
     if (resp.status === 204) return undefined as T;
@@ -685,9 +718,10 @@ export class CraterView {
       "POST", "/v1/uploads", { content_type: type, content_length: blob.size });
 
     const put = await fetch(slot.upload_url, {
+      signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS),
       method: "PUT", body: blob, headers: { "Content-Type": type },
     });
-    if (!put.ok) throw new CraterViewError(`upload failed: ${put.status}`);
+    if (!put.ok) throw new CraterViewError(`upload failed: ${put.status}`, put.status);
     const megapixels = await megapixelsOf(blob);
     if (megapixels) {
       if (this.sizes.size >= 512) this.sizes.delete(this.sizes.keys().next().value!);
@@ -795,9 +829,24 @@ export class CraterView {
     return body.secret;
   }
 
-  /** Every key on the account, including revoked ones, by prefix rather than value. */
+  /**
+   * Every key on the account, including revoked ones, by prefix rather than value, newest
+   * first. The API serves the list a page at a time; this fetches every page and returns them
+   * together.
+   */
   async keys(): Promise<KeyInfo[]> {
-    return await this.request("GET", "/v1/keys") as KeyInfo[];
+    const found: KeyInfo[] = [];
+    let before: string | undefined;
+    for (;;) {
+      const params = new URLSearchParams({ limit: String(MAX_PAGE) });
+      if (before) params.set("before", before);
+      const page = await this.request<{ data: KeyInfo[]; has_more: boolean; next_before?: string }>(
+        "GET", `/v1/keys?${params}`);
+      found.push(...page.data);
+      // As in `jobs`: a missing or non-advancing cursor stops rather than spinning.
+      if (!page.has_more || !page.next_before || page.next_before === before) return found;
+      before = page.next_before;
+    }
   }
 
   /**
@@ -807,6 +856,9 @@ export class CraterView {
    * Several keys on an account is the ordinary arrangement, one per service or environment.
    * They share the account's credits and history. This is also how you rotate without
    * downtime: create the new key, move your clients onto it, then revoke the old one.
+   *
+   * An account is given a limited number of new keys an hour, whichever of its keys asks:
+   * past it this throws `RateLimited`, whose `retryAfter` says when to ask again.
    */
   async createKey(name = "api"): Promise<NewKey> {
     return await this.request("POST", "/v1/keys", { name }) as NewKey;
@@ -815,8 +867,9 @@ export class CraterView {
   /**
    * Stop a key working. Immediate, and not reversible.
    *
-   * You cannot revoke the key this client is authenticating with — the call would succeed
-   * and leave you unable to make another.
+   * You cannot revoke the key this client is authenticating with: it is refused with status
+   * 409, because it would leave you unable to make another. Create a replacement, move onto
+   * it, then revoke this one.
    */
   async revokeKey(keyId: string): Promise<void> {
     await this.request("DELETE", `/v1/keys/${encodeURIComponent(keyId)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craterview",
-  "version": "0.3.18",
+  "version": "0.4.0",
   "dependencies": {
     "image-size": "^2.0.4"
   },
@@ -25,10 +25,10 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
-    "esbuild": "^0.25.0",
+    "@types/node": "^26.6.3",
+    "esbuild": "^0.28.2",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.2"
   }
 }