craterview 0.1.3 → 0.3.8

package/README.md

@@ -23,7 +23,7 @@ client installs without dragging a transitive tree behind it.
 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();
 ```
 
@@ -31,12 +31,30 @@ const blob = await job.blob();
 API's shape rather than an accident, but it is not something every caller should have to
 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.
+
+```ts
+const job = await cv.run(file, {
+  // echo is free, for building against. Swap in a paid model when you are ready —
+  // cv-enhance-v3 to enlarge, cv-restore-v1 to repair, cv-headshot-v1 for portraits.
+  model: "echo",
+  scale: 2, wait: 30,
+});
+const blob = await job.blob();
+```
+
+A parameter one model publishes is not 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
 
 Keys begin with `cv_` and are issued from your dashboard.
 
 ```ts
-const cv = new CraterView({ apiKey: process.env.CRATERVIEW_API_KEY });
+const cv = new CraterView({ apiKey: process.env.CV_API_KEY });
 ```
 
 A key carries your whole allowance and does not expire. **Do not ship one to a browser** —
@@ -47,10 +65,10 @@ browser a session instead.
 
 ```ts
 const job = await cv.run(image, {          // Blob | ArrayBuffer | Uint8Array
-  model: "cv-restore-v1",                   // default
+  model: "cv-enhance-v3",                   // default
   wait: 30,                                // seconds to hold the connection open
   timeoutMs: 600_000,                      // total before giving up
-  style: "photo",                          // model parameters pass straight through
+  scale: 4,                                // model parameters pass straight through
 });
 ```
 
@@ -66,7 +84,7 @@ Useful when you want to hold the key, submit later, or fan out.
 
 ```ts
 const inputKey = await cv.upload(file);                        // → "inputs/..."
-let job = await cv.submit(inputKey, { style: "photo" });
+let job = await cv.submit(inputKey, { scale: 4 });
 job = await cv.waitFor(job, 600_000);
 const blob = await job.blob();
 ```
@@ -90,7 +108,7 @@ const key = newIdempotencyKey();           // once, before the first attempt
 let job;
 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) throw e;   // the server answered; do not retry
@@ -102,7 +120,8 @@ for (let attempt = 0; attempt < 3; attempt++) {
 Generating a fresh key per attempt defeats the point entirely — the server has nothing to
 match against and every attempt starts its own job. Reusing a key with a *different* body
 is rejected with 409 rather than quietly handing back the earlier result. Claims are kept
-for 24 hours; past that the same key starts new work.
+for as long as the job's record is, which is not deleted; the same key always returns
+the same job.
 
 ## Errors
 
@@ -111,7 +130,7 @@ Everything thrown by this client extends `CraterViewError`, so one `catch` handl
 
 | Class | Meaning |
 |---|---|
-| `RateLimited` | 429. `.retryAfter` is seconds until the window rolls over. |
+| `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. |
 | `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. |
 
@@ -131,8 +150,8 @@ 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` | The estimate made at submit. Absent once the job has settled |
-| `community` | True when the job is on the community queue: served after priority work, taking a small share of it |
+| `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 |
+| `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 |
@@ -155,9 +174,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, charged and run — it simply waits in the community queue for capacity that paid
-work is not using, and comes back with `community` set. There is no payment error to
-handle: credit buys a place at the front of the queue rather than the right to submit.
+accepted, charged and run — 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.
 `etaSeconds` covers the whole wait, queue time included, so a community job simply reports
 a longer one.
 
@@ -204,7 +225,7 @@ Every copy of a delivery states the same thing, so the first one you accept is t
 answer — later copies of an `id` you have already handled can be dropped rather than
 reconciled.
 
-**Pass the raw body.** Most frameworks parse JSON for you, and re-serialising it changes the
+**Pass the raw body.** Most frameworks parse JSON for you, and re-serializing it changes the
 bytes the signature was computed over — hence `express.raw` above.
 
 `verifyWebhook` is async because it uses WebCrypto, which is what lets it run unchanged in
@@ -245,7 +266,7 @@ old one. You cannot revoke the key you are calling with.
 ## Everything else
 
 ```ts
-await cv.models();                            // models, parameter schemas, queue depth
+await cv.models();                            // models, parameter schemas, which queue you are on
 await cv.job("job_...");                      // one job by id
 await cv.usage();                             // credit balance, spend and job counts
 
@@ -254,6 +275,10 @@ for await (const job of cv.jobs({ limit: 50, status: "succeeded" })) {
 }
 ```
 
+`limit` is how many jobs one request fetches, not how many you get: the loop keeps going
+until your history runs out. 200 is the largest page the API serves, and a bigger number is
+fetched as 200.
+
 ## Configuration
 
 ```ts
@@ -263,7 +288,20 @@ new CraterView({
 });
 ```
 
-`baseUrl` is what you change to point at a local gateway.
+`baseUrl` is what you change to point at a local server.
+
+## 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-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.
+
+```
+/plugin marketplace add craterviewai/craterview-ts
+/plugin install craterview@craterviewai
+/plugin install craterview-api@craterviewai
+```
 
 ## Versioning
 
@@ -272,7 +310,7 @@ or `ModelInfo`, or changes the type of one, gets a minor bump while this is `0.x
 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
-`result` or a `status` you do not recognise as something to ignore rather than to fail on.
+`result` or a `status` you do not recognize as something to ignore rather than to fail on.
 
 ## License
 

package/index.ts

@@ -9,21 +9,19 @@
  *
  * 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.
- *
- * **This file is published.** It goes to GitHub and npm, and `main` points at the source, so
- * every comment here ships and a doc-comment on an exported member appears in a consumer's
- * editor. Write for someone who can see this package and nothing else: what the client does
- * and what a caller has to know, never how the service behind it is built.
  */
 
 // 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.1.3";
+export const VERSION = "0.3.8";
 const DEFAULT_BASE_URL = "https://api.craterview.ai";
-// The server rejects a longer wait outright, so asking for one costs a 422 rather than a
-// longer wait. Keep in step with MAX_WAIT_SECONDS in the gateway.
+// 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.
 const MAX_SERVER_WAIT = 30;
+// The largest page the job history serves. Same reasoning: a bigger `limit` is refused, so
+// `jobs()` clamps rather than spending a request to be told no.
+const MAX_PAGE = 200;
 
 /**
  * A random key for safely repeating a submission.
@@ -72,11 +70,11 @@ export class CraterViewError extends Error {
  * 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.
  *
- * `retryAfter` is seconds to wait, and how good a number it is depends on which limit you
- * hit: exact for the rate limit, where it is when the window rolls over, and a hint for
- * the in-flight cap, where a slot frees when one of your own jobs finishes and the server
- * can only quote the model's typical duration. `usage()` reports the cap and what you
- * currently hold against it.
+ * `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.
  */
 export class RateLimited extends CraterViewError {
   constructor(message: string, readonly retryAfter?: number) {
@@ -132,7 +130,7 @@ export class InvalidSignature extends CraterViewError {}
  *
  * Throws {@link InvalidSignature} if it does not check out. **Verify before you parse**, and
  * pass the raw body exactly as received — most frameworks parse JSON for you, and
- * re-serialising it changes the bytes the signature was computed over. In Express that means
+ * re-serializing it changes the bytes the signature was computed over. In Express that means
  * `express.raw({ type: "application/json" })` on this route.
  *
  * Async because it uses WebCrypto, which is what makes this work unchanged in Node and in a
@@ -220,8 +218,8 @@ function timingSafeEqual(a: string, b: string): boolean {
 }
 
 /**
- * One entry from the model catalogue, exactly as it arrives. Snake case is the wire's, as
- * with `JobData` — there is no wrapper class here because there is no behaviour to add.
+ * One entry from the model catalog, exactly as it arrives. Snake case is the wire's, as
+ * 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. */
@@ -248,6 +246,11 @@ export interface ModelInfo {
    * look identical in `accepts` alone.
    */
   video_coming_soon?: boolean;
+  /**
+   * How long this model is for. `fixed` is a lasting part of the service; `comet` is a
+   * featured model that may be withdrawn at short notice, so build on it knowing that.
+   */
+  tenure?: "fixed" | "comet";
   max_input_bytes: number;
   /**
    * The ceilings **your key** is held to, not the model's widest. Community work is bounded
@@ -272,22 +275,17 @@ export interface ModelInfo {
   credits_per_video_second?: number | null;
   reference_fps: number;
   params_schema: Record<string, unknown>;
-  /**
-   * Work ahead of you **on the queue your key would use** — not a platform-wide total.
-   * Read it with `community`, which says which queue that is.
-   */
-  queue_depth: number;
   /**
    * Whether your key's work goes to the community queue, which is served after priority
-   * work and takes a small share of it. False once the account holds credit.
+   * 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.
    *
-   * The same field, meaning the same thing, as `Job.community` — these are the two places
-   * the API describes a wait, and they describe it the same way.
+   * 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.
    */
   community: boolean;
   /** Of `params_schema`, the ones that apply to still images only. */
   image_only_params: string[];
-  /** A representative job, for sizing a progress indicator before any eta arrives. */
 }
 
 /** One key on the account. Never the key itself — only the prefix, which identifies it. */
@@ -300,7 +298,11 @@ export interface KeyInfo {
   /** When it stopped working, or null while it still does. */
   revoked_at: string | null;
   rate_limit_per_minute: number;
-  /** Whether this is the key you are calling with. It cannot be revoked while it is. */
+  /**
+   * 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.
+   */
   current: boolean;
 }
 
@@ -314,20 +316,14 @@ export interface NewKey {
   rate_limit_per_minute: number;
 }
 
-/** The body of a callback, once {@link verifyWebhook} has checked it came from us. */
-export interface WebhookEvent {
-  id: string;
-  custom_id: string | null;
-  model: string | null;
-  status: JobStatus;
-  error: string | null;
-  error_code: string | null;
-  community: boolean;
-  credits: number | null;
-  created_at: string | null;
-  finished_at: string | null;
-  result: Record<string, unknown> | null;
-}
+/**
+ * The body of a callback, once {@link verifyWebhook} has checked it came from us.
+ *
+ * A job, delivered rather than fetched: the same fields a read of the job states, under the
+ * same names, every one present and null where it does not apply — so a receiver parses one
+ * shape rather than branching on which keys arrived.
+ */
+export interface WebhookEvent extends Required<JobData> {}
 
 export type JobStatus = "queued" | "running" | "succeeded" | "failed";
 
@@ -400,10 +396,12 @@ export interface JobData {
  * 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 was submitted against a balance of zero and is on the queue
- * served after priority work, which takes a small share of it rather than only what is left.
- * Nothing is refused for want of credit — credit buys a place at the front of the queue, not
- * the right to submit — so an empty balance means a longer wait and never an error.
+ * `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.
  */
 export class Job {
   constructor(private readonly data: JobData) {}
@@ -418,7 +416,7 @@ export class Job {
   get etaSeconds() { return this.data.eta_seconds ?? null; }
   /** Your own name for this job, or null if you did not send one. */
   get customId() { return this.data.custom_id ?? null; }
-  // Defaulted rather than nulled: a gateway too old to send the field is not running a
+  // Defaulted rather than nulled: a server too old to send the field is not running a
   // community queue at all, so its jobs are paid work.
   get community() { return this.data.community ?? false; }
   // Nulled rather than defaulted, unlike `community` above: absent means the image was not
@@ -547,17 +545,17 @@ export class CraterView {
   }
 
   /**
-   * Available models: parameter schemas, prices, limits, and your queue.
+   * Available models: parameter schemas, prices, limits, and which queue you are on.
    *
    * Prices are published here, so the cost of a job is knowable before submitting it.
    *
-   * Needs a key, and not only because the figures are live: `queue_depth` and `community`
-   * are answered **for the queue your key would use**. The API looks up the account's
-   * balance and reports the queue a job from this key would land in — so two keys asking
-   * at the same moment can get different numbers, and buying credit changes yours.
+   * `community` and the limits are answered **for the queue your key would use**. The API
+   * looks up the account's standing and reports the queue a job from this key would land
+   * in — so two keys asking at the same moment can get different answers, and paying —
+   * credit or a subscription — changes yours.
    *
    * A model that is available is not always listed — a model in trial, or being retired,
-   * stays usable by name while absent from this catalogue.
+   * stays usable by name while absent from this catalog.
    */
   async models(): Promise<ModelInfo[]> {
     return await this.request("GET", "/v1/models") as ModelInfo[];
@@ -594,7 +592,7 @@ 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-restore-v1",
+    const { wait = 0, idempotencyKey, webhookUrl, customId, model = "cv-enhance-v3",
             ...params } = options;
     // 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>.
@@ -618,11 +616,17 @@ export class CraterView {
    *
    * Scoped to the account rather than to this key, so a key sees every job the account has
    * run and not only the ones it submitted itself.
+   *
+   * `limit` is how many jobs one request fetches, not how many you get: iteration continues
+   * until the history runs out. 200 is the largest page the API serves, and a bigger number
+   * is fetched as 200 rather than sent and refused.
    */
   async *jobs(options: { limit?: number; status?: JobStatus } = {}): AsyncGenerator<Job> {
     let before: string | undefined;
     for (;;) {
-      const params = new URLSearchParams({ limit: String(options.limit ?? 50) });
+      const params = new URLSearchParams({
+        limit: String(Math.min(options.limit ?? 50, MAX_PAGE)),
+      });
       if (options.status) params.set("status", options.status);
       if (before) params.set("before", before);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craterview",
-  "version": "0.1.3",
+  "version": "0.3.8",
   "dependencies": {},
   "description": "TypeScript client for the CraterView image enhancement API",
   "type": "module",