@kavel/kavel 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kavel (https://www.kavel.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @kavel/kavel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate **and edit** images from TypeScript with no API key, no account and no card. Runs in Deno,
+Node 18+ and Bun — anything with `fetch`, zero dependencies.
+
+```bash
+npm install @kavel/kavel      # Deno: deno add jsr:@kavel/kavel
+```
+
+```ts
+import { generate, edit, KavelError } from "@kavel/kavel";
+
+const img = await generate(
+  "matte black ceramic mug on pale oak, soft window light from the left, shallow depth of field",
+  { aspectRatio: "16:9" },
+);
+console.log(img.url); // https://cdn.kavel.ai/uploads/kie/image/....webp
+
+const edited = await edit(img.url, "place the mug on a white marble surface");
+```
+
+Every other image client wants a key from OpenAI, fal or Replicate before it runs once. This one talks
+to the free tier of [Kavel](https://www.kavel.ai/?utm_source=npm&utm_medium=package) — a client id
+the module invents rather than an account you register — so a script works on a machine with nothing
+configured, including CI and edge functions.
+
+## Why it is shaped this way
+
+- **Zero dependencies, fully typed.** Just `fetch` and Web Crypto.
+- **An edit lane.** `edit` takes a photo you already have and one sentence describing the change.
+- **One error class with a `kind`.** `quota` means wait or sign in, `rejected` means reword,
+  `sign_in` means the request is off the free shelf.
+- **`AbortSignal` support and a deadline.** Pass `signal` to cancel from a UI.
+- **It keeps polling through a dropped connection.** A free run waits in a queue and only reaches the
+  model at the end of it; giving up on one failed poll would throw away a job about to run.
+
+## Limits, measured against the running service
+
+- The free grant is **15 credits**. An image costs **5**, an edit costs **15**. The crate mints a new
+  client id per call, so a loop is not capped at three.
+- **30 credits per IP per day** sits on top — about six images from one machine — and surfaces as
+  a `quota` error.
+- Free output is **1K and watermarked**; `img.watermarked` tells you instead of leaving you to guess.
+- Free runs queue **25–80 seconds** before the model is called, which is why the default deadline is
+  six minutes.
+- **Video does not run anonymously** — the cheapest clip costs more than the grant. The
+  [AI video generator](https://www.kavel.ai/video?utm_source=npm&utm_medium=package) has a browser
+  lane for that.
+
+Signing in removes the watermark and opens the full shelf:
+[Nano Banana 2](https://www.kavel.ai/image/nano-banana-2?utm_source=npm&utm_medium=package) for up to
+14 reference photos, [GPT Image 2](https://www.kavel.ai/image/gpt-image-2?utm_source=npm&utm_medium=package)
+for 4K output, [Qwen Image 3](https://www.kavel.ai/image/qwen-image-3?utm_source=npm&utm_medium=package)
+when the picture has to contain correctly spelled text, and
+[Seedream 5.0 Pro](https://www.kavel.ai/image/seedream-5-pro?utm_source=npm&utm_medium=package) for
+photoreal people. [Pricing](https://www.kavel.ai/pricing?utm_source=npm&utm_medium=package) has every tier.
+
+## Past the free tier: an API key
+
+When the free allowance runs out, the error tells you where to go next. Create a key at
+[kavel.ai/settings/apikeys](https://www.kavel.ai/settings/apikeys?utm_source=npm&utm_medium=package) — the same account
+you use on the site — and pass it (or set `KAVEL_API_KEY`):
+
+```ts
+const img = await generate(prompt, { apiKey: process.env.KAVEL_API_KEY, model: "gpt-image-2" });
+```
+
+With a key every call runs on your account, exactly as it would on the site: your
+[credits and plan](https://www.kavel.ai/pricing?utm_source=npm&utm_medium=package), no per-IP ceiling, no watermark on a
+paid plan, and any image model your plan includes. A `KavelError` with `kind === "auth"` means the key is wrong; `"quota"` with a key means the account is out of credits.
+
+## Prompts that work
+
+Name the light, the material and the composition — that moves the result more than adjectives do.
+For edits, say what changes and the model keeps the rest; it is the same
+[Nano Banana 2 Lite](https://www.kavel.ai/image/nano-banana-2-lite?utm_source=npm&utm_medium=package)
+lane behind the [AI hairstyle changer](https://www.kavel.ai/image/ai-hairstyle-changer?utm_source=npm&utm_medium=package)
+and the [AI outfit generator](https://www.kavel.ai/image/ai-outfit-generator?utm_source=npm&utm_medium=package).
+The [free AI image generator](https://www.kavel.ai/image?utm_source=npm&utm_medium=package) runs the
+same engines in a browser, and the [showcase](https://www.kavel.ai/showcases?utm_source=npm&utm_medium=package)
+has finished output.
+
+## Tests
+
+```bash
+deno test   # from the repository
+```
+
+Offline: argument validation, client id uniqueness, the quota wall (an HTTP 200 recognised only by a
+field), the sign-in refusal, and polling through a dropped connection.
+
+MIT

package/dist/mod.d.ts

@@ -0,0 +1,76 @@
+/** The service this module talks to. */
+export declare const BASE_URL = "https://www.kavel.ai";
+/** Credit balance a signed-out caller starts with. */
+export declare const ANON_GRANT = 15;
+/** What one generated image costs, so the grant pays for three. */
+export declare const COST_TEXT_TO_IMAGE = 5;
+/** What one edit costs: the whole grant. */
+export declare const COST_EDIT = 15;
+/** Credits one machine may spend per day regardless of client ids. */
+export declare const IP_DAILY_CEILING = 30;
+/** The free text-to-image engine. */
+export declare const MODEL_GENERATE = "kavel-image-v1";
+/** The free image-to-image engine. */
+export declare const MODEL_EDIT = "nano-banana-2-lite";
+/** One finished picture. */
+export interface Image {
+    /** A permanent, cacheable CDN link. */
+    url: string;
+    /** Whether a mark was actually drawn on it. Signing in removes it. */
+    watermarked: boolean;
+}
+/** Tunes a single call. Every field is optional. */
+export interface Options {
+    /** "1:1" (default), "16:9", "9:16", "4:3" or "3:4". Ignored by {@link edit}. */
+    aspectRatio?: string;
+    /** Poll interval in milliseconds. Default 5000. */
+    pollEveryMs?: number;
+    /** Deadline for the whole call in milliseconds. Default 360000. */
+    timeoutMs?: number;
+    /** Aborts the call. */
+    signal?: AbortSignal;
+    /**
+     * An API key from https://www.kavel.ai/settings/apikeys. With a key the call
+     * runs on your account — your credits, your plan's models, no watermark on a
+     * paid plan. Without one it runs on the free anonymous tier. Defaults to the
+     * `KAVEL_API_KEY` environment variable when it can be read.
+     */
+    apiKey?: string;
+    /** Model to run. Only honoured with an API key; the free tier has one model per lane. */
+    model?: string;
+    /** Override for tests or a proxy. */
+    baseUrl?: string;
+    /** Override for tests. */
+    fetch?: typeof fetch;
+}
+/** Why a call failed, split by what the caller should do next. */
+export type KavelErrorKind = "invalid" | "quota" | "rejected" | "sign_in" | "auth" | "timeout" | "service";
+/** The only error this module throws on purpose. Branch on `kind`. */
+export declare class KavelError extends Error {
+    /** What went wrong. */
+    readonly kind: KavelErrorKind;
+    /** Creates an error of a given kind. */
+    constructor(kind: KavelErrorKind, message: string);
+}
+interface Envelope {
+    code: number;
+    message?: string;
+    data?: Record<string, unknown> | null;
+}
+/** A fresh client id. A reused id walls partway through a loop. */
+export declare function anonId(): string;
+/**
+ * Interpret the submit response. The quota wall answers HTTP 200 with code 0,
+ * so it can only be recognised by a field.
+ */
+export declare function parseSubmit(env: Envelope): string;
+/** Turn a prompt into a new image. Name the light, the material and the composition. */
+export declare function generate(prompt: string, opts?: Options): Promise<Image>;
+/** Rewrite an existing image. `sourceUrl` must be a public http(s) url. */
+export declare function edit(sourceUrl: string, instruction: string, opts?: Options): Promise<Image>;
+/** What a client id has left. Costs nothing. Omit `clientId` to ask about a fresh one. */
+export declare function credits(clientId?: string): Promise<{
+    remaining: number;
+    grant: number;
+}>;
+export {};

package/dist/mod.js

@@ -0,0 +1,170 @@
+// Generate and edit images with no API key and no account. See README.md.
+/** The service this module talks to. */
+export const BASE_URL = "https://www.kavel.ai";
+/** Credit balance a signed-out caller starts with. */
+export const ANON_GRANT = 15;
+/** What one generated image costs, so the grant pays for three. */
+export const COST_TEXT_TO_IMAGE = 5;
+/** What one edit costs: the whole grant. */
+export const COST_EDIT = 15;
+/** Credits one machine may spend per day regardless of client ids. */
+export const IP_DAILY_CEILING = 30;
+/** The free text-to-image engine. */
+export const MODEL_GENERATE = "kavel-image-v1";
+/** The free image-to-image engine. */
+export const MODEL_EDIT = "nano-banana-2-lite";
+/** The only error this module throws on purpose. Branch on `kind`. */
+export class KavelError extends Error {
+    /** What went wrong. */
+    kind;
+    /** Creates an error of a given kind. */
+    constructor(kind, message) {
+        super(`kavel: ${message}`);
+        this.name = "KavelError";
+        this.kind = kind;
+    }
+}
+/** A fresh client id. A reused id walls partway through a loop. */
+export function anonId() {
+    const b = new Uint8Array(8);
+    crypto.getRandomValues(b);
+    return "ts-" + Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Interpret the submit response. The quota wall answers HTTP 200 with code 0,
+ * so it can only be recognised by a field.
+ */
+export function parseSubmit(env) {
+    if (env.code !== 0) {
+        const m = env.message ?? "request refused";
+        const lower = m.toLowerCase();
+        if (lower.includes("invalid api key"))
+            throw new KavelError("auth", m);
+        if (lower.includes("insufficient credits"))
+            throw new KavelError("quota", m);
+        if (lower.includes("sign in") || lower.includes("subscription"))
+            throw new KavelError("sign_in", m);
+        throw new KavelError("service", m);
+    }
+    const d = env.data ?? {};
+    if (d.wall === true) {
+        if (d.reason === "anon_ip_daily") {
+            throw new KavelError("quota", `this machine has used its ${IP_DAILY_CEILING} free credits for today — pass an apiKey from ${BASE_URL}/settings/apikeys to keep going`);
+        }
+        if (d.reason === "anon_unmetered_video")
+            throw new KavelError("sign_in", "video");
+        throw new KavelError("quota", `free allowance spent — pass an apiKey from ${BASE_URL}/settings/apikeys to keep going`);
+    }
+    if (typeof d.id !== "string" || d.id === "") {
+        throw new KavelError("service", "the service returned no task id");
+    }
+    return d.id;
+}
+/** Turn a prompt into a new image. Name the light, the material and the composition. */
+export function generate(prompt, opts = {}) {
+    if (!prompt?.trim())
+        return Promise.reject(new KavelError("invalid", "prompt is required"));
+    return run(opts, {
+        provider: "kie",
+        mediaType: "image",
+        model: keyFor(opts) && opts.model ? opts.model : MODEL_GENERATE,
+        scene: "text-to-image",
+        prompt,
+        options: { aspect_ratio: opts.aspectRatio || "1:1" },
+    });
+}
+/** Rewrite an existing image. `sourceUrl` must be a public http(s) url. */
+export function edit(sourceUrl, instruction, opts = {}) {
+    if (!/^https?:\/\//.test(sourceUrl ?? "")) {
+        return Promise.reject(new KavelError("invalid", "sourceUrl must be a public http(s) url"));
+    }
+    if (!instruction?.trim())
+        return Promise.reject(new KavelError("invalid", "instruction is required"));
+    return run(opts, {
+        provider: "kie",
+        mediaType: "image",
+        model: keyFor(opts) && opts.model ? opts.model : MODEL_EDIT,
+        scene: "image-to-image",
+        prompt: instruction,
+        options: { image_input: [sourceUrl] },
+    });
+}
+const wait = (ms, signal) => new Promise((resolve, reject) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(t);
+        reject(signal.reason);
+    }, { once: true });
+});
+function keyFor(opts) {
+    if (opts.apiKey)
+        return opts.apiKey;
+    try {
+        return globalThis.Deno?.env.get("KAVEL_API_KEY") ??
+            globalThis.process?.env.KAVEL_API_KEY;
+    }
+    catch {
+        return undefined; // Deno without --allow-env
+    }
+}
+async function run(opts, payload) {
+    const f = opts.fetch ?? fetch;
+    const base = opts.baseUrl ?? BASE_URL;
+    const deadline = Date.now() + (opts.timeoutMs ?? 360_000);
+    const key = keyFor(opts);
+    // With a key the account is the identity; without one, a fresh anonymous id.
+    const auth = key ? { authorization: `Bearer ${key}` } : { "x-anon-id": anonId() };
+    const res = await f(`${base}/api/ai/generate`, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...auth },
+        body: JSON.stringify(payload),
+        signal: opts.signal,
+    });
+    const task = parseSubmit(await res.json());
+    // Queued runs only reach the model on the poll that crosses the end of the
+    // wait, so polling is what starts the work.
+    const poll = () => key
+        ? f(`${base}/api/ai/query`, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...auth },
+            body: JSON.stringify({ taskId: task }),
+            signal: opts.signal,
+        })
+        : f(`${base}/api/ai/anon-query?taskId=${encodeURIComponent(task)}&provider=kie&mediaType=image`, {
+            headers: auth,
+            signal: opts.signal,
+        });
+    while (Date.now() < deadline) {
+        await wait(opts.pollEveryMs ?? 5000, opts.signal);
+        let env;
+        try {
+            env = await (await poll()).json();
+        }
+        catch (e) {
+            if (opts.signal?.aborted)
+                throw e;
+            continue; // a dropped poll is not a failed generation
+        }
+        if (env.code !== 0)
+            continue;
+        const d = env.data ?? {};
+        const clean = d.cleanImages;
+        if (clean?.length)
+            return { url: clean[0], watermarked: false };
+        const images = d.images;
+        if (images?.length) {
+            return { url: images[0], watermarked: Boolean(d.watermarked?.[0]) };
+        }
+        if (d.status === "failed" || d.status === "error")
+            throw new KavelError("rejected", "prompt refused");
+    }
+    throw new KavelError("timeout", "deadline passed");
+}
+/** What a client id has left. Costs nothing. Omit `clientId` to ask about a fresh one. */
+export async function credits(clientId = anonId()) {
+    const env = await (await fetch(`${BASE_URL}/api/ai/anon-credits`, { headers: { "x-anon-id": clientId } }))
+        .json();
+    if (env.code !== 0)
+        throw new KavelError("service", env.message ?? "failed");
+    return { remaining: Number(env.data?.remaining ?? 0), grant: Number(env.data?.grant ?? 0) };
+}

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@kavel/kavel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Generate and edit images from JavaScript and TypeScript with no API key, no account and no card. Zero dependencies; Node 18+, Bun, Deno and edge runtimes.",
+  "license": "MIT",
+  "author": "Kavel (https://www.kavel.ai)",
+  "homepage": "https://www.kavel.ai",
+  "repository": { "type": "git", "url": "git+https://github.com/hanshs474/kavel-ts.git" },
+  "bugs": { "url": "https://github.com/hanshs474/kavel-ts/issues" },
+  "keywords": ["kavel", "ai", "image-generation", "text-to-image", "image-to-image", "image-editing", "no-api-key", "sdk"],
+  "type": "module",
+  "main": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": { ".": { "types": "./dist/mod.d.ts", "import": "./dist/mod.js" } },
+  "files": ["dist", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.npm.json",
+    "prepack": "npm run build && node scripts/npm-readme.mjs to-npm",
+    "postpack": "node scripts/npm-readme.mjs restore"
+  },
+  "devDependencies": { "typescript": "^5.6.0" },
+  "engines": { "node": ">=18" }
+}