craterview 0.1.0 → 0.1.5

package/README.md

@@ -7,9 +7,15 @@ restoration API.
 npm install craterview
 ```
 
-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 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.
+
+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.
 
 ## Quickstart
 
@@ -17,7 +23,7 @@ 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();
 ```
 
@@ -41,10 +47,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
 });
 ```
 
@@ -60,7 +66,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();
 ```
@@ -84,7 +90,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
@@ -126,7 +132,7 @@ 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` | 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 |
+| `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 |
@@ -149,9 +155,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.
 
@@ -198,7 +206,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
@@ -248,6 +256,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
@@ -257,7 +269,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
 
@@ -266,7 +291,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.0";
+export const VERSION = "0.1.5";
 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.
@@ -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
@@ -279,7 +282,8 @@ export interface ModelInfo {
   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 once
+   * the account holds credit.
    *
    * 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.
@@ -287,7 +291,6 @@ export interface ModelInfo {
   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. */
@@ -400,10 +403,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 +423,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
@@ -557,7 +562,7 @@ export class CraterView {
    * at the same moment can get different numbers, and buying credit 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 +599,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 +623,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.0",
+  "version": "0.1.5",
   "dependencies": {},
   "description": "TypeScript client for the CraterView image enhancement API",
   "type": "module",