craterview 0.1.5 → 0.3.8

package/README.md

@@ -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** —
@@ -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,7 +150,7 @@ 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 |
+| `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 |
@@ -247,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
 

package/index.ts

@@ -14,7 +14,7 @@
 // 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.5";
+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 the
 // wait you asked for. `run()` clamps to this rather than letting that happen.
@@ -70,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) {
@@ -275,18 +275,13 @@ 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 always takes a share of it, so it never stalls behind paid work. 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. */
@@ -303,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;
 }
 
@@ -317,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";
 
@@ -552,14 +545,14 @@ 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 catalog.

package/package.json

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