onetagai 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OdysseyX LLC
+
+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,74 @@
-# Temporary Holding Version
+# onetagai
 
-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.
+AI for static sites without a backend. Call a model from the browser with a public key: no server, no secret in your code.
+
+```sh
+npm install onetagai
+```
+
+```js
+import { ask } from "onetagai";
+
+const summary = await ask("Summarize this page in two sentences", document.querySelector("article"));
+```
+
+It works on localhost right away, on a shared demo key. Before you deploy, get your own free key (email only, 1,000,000 tokens a month):
+
+```sh
+curl -X POST https://onetagai.com/api/signup -H "Content-Type: application/json" -d '{"email":"you@example.com"}'
+```
+
+```js
+import { configure } from "onetagai";
+
+configure({ key: "ot_..." });
+```
+
+The key is meant to be public, like an analytics ID: it goes in your page source.
+
+## ask(prompt, input?, options?)
+
+Returns a promise of the answer as text.
+
+`input` is what the prompt is about: a string, a DOM element (its text), a form (its fields), an image or `File`, any JSON value, or an array of those.
+
+| Option | What it does |
+| --- | --- |
+| `stream` | A function called with each piece of the answer as it arrives |
+| `json` | `true` parses the answer and returns the value |
+| `system` | Instructions for the model: a persona, limits, a format |
+| `history` | Earlier turns, `[{ role: "user" \| "assistant", content }]` |
+| `maxTokens` | Cap on the answer length (default 500) |
+| `signal` | An `AbortSignal` to cancel the call |
+
+```js
+// Stream into the page
+await ask("Explain this error", log, { stream: (delta) => (output.textContent += delta) });
+
+// Structured output
+const { tags } = await ask("Return {\"tags\": string[]} for this post", post, { json: true });
+
+// An image
+const alt = await ask("Write alt text for this image", fileInput.files[0]);
+```
+
+A failed call rejects with a `OneTagError`. Its `code` is one of `no_key`, `bad_key`, `rate_limited`, `quota_exceeded`, `too_large`, `network`, `aborted` and a few more; its `message` says what to do.
+
+## Without a bundler
+
+The same SDK as one script tag:
+
+```html
+<script src="https://onetagai.com/v1.js" data-key="ot_..."></script>
+<script>
+  onetag.ask("Summarize this page", document.body).then(console.log);
+</script>
+```
+
+## Links
+
+- Docs: https://onetagai.com/docs
+- For AI coding agents: https://onetagai.com/llms.txt
+- Copy-paste blocks built on it: https://aiblock.onetagai.com
+
+MIT

package/core.js

@@ -0,0 +1,242 @@
+/*! OneTag AI SDK v1.2.0 | https://onetagai.com | generated from sdk/v1.js by build.mjs, do not edit */
+const MAX_TEXT = 32000;
+const MAX_SIDE = 1600;
+const CONTROLS = ["HTMLInputElement", "HTMLTextAreaElement", "HTMLSelectElement"];
+const HOME = "https://onetagai.com";
+const script = null;
+const data = (script && script.dataset) || {};
+// The API lives where the SDK came from when that is OneTag AI itself or a local dev
+// server; loaded from a CDN (jsDelivr, unpkg) or a copy on your own site, it is HOME.
+// data-endpoint on the script tag overrides either.
+const origin = (() => {
+  try {
+    return script && script.src ? new URL(script.src) : null;
+  } catch (e) {
+    return null;
+  }
+})();
+const OWN = origin && /^(onetagai\.com|htmlai\.000ooo\.ooo|localhost|127\.0\.0\.1)$/.test(origin.hostname);
+const SITE = OWN ? origin.origin : HOME;
+const config = {
+  key: data.key || "",
+  endpoint: data.endpoint || SITE + "/v1/ask",
+  // A short slug naming the integration that sends the calls (a plugin or package name).
+  via: data.via || "",
+};
+
+class OneTagError extends Error {
+  constructor(code, message, status = 0) {
+    super(message);
+    this.name = "OneTagError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+const isA = (value, type) => typeof globalThis[type] === "function" && value instanceof globalThis[type];
+const textPart = (text) => ({ type: "text", text: String(text) });
+const len = (s) => (typeof s === "string" ? s.length : 0);
+
+// Trim the text parts, in order, to the characters the server has left after the
+// prompt, system and history (it rejects the whole call over MAX_TEXT, counting 7 per
+// separator between parts). A cut never lands between the two halves of a surrogate
+// pair; parts trimmed to nothing are dropped.
+function fit(parts, budget) {
+  const out = [];
+  let sep = 0;
+  for (const part of parts) {
+    if (part.type !== "text") {
+      out.push(part);
+      continue;
+    }
+    let cut = Math.max(0, Math.min(budget - sep, part.text.length));
+    const c = part.text.charCodeAt(cut - 1);
+    if (cut < part.text.length && c >= 0xd800 && c < 0xdc00) cut--;
+    if (!cut) continue;
+    out.push({ type: "text", text: part.text.slice(0, cut) });
+    budget -= sep + cut;
+    sep = 7;
+  }
+  return out;
+}
+
+function configure(options = {}) {
+  if (options.key !== undefined) config.key = options.key;
+  if (options.endpoint !== undefined) config.endpoint = options.endpoint;
+  if (options.via !== undefined) config.via = options.via;
+}
+
+const isSvg = (s) => /^(data:)?image\/svg|\.svg([?#]|$)/i.test(s || "");
+
+// Draw onto a canvas no larger than MAX_SIDE: JPEG on white for photos, PNG for SVG.
+function rasterize(source, width, height, svg) {
+  const scale = Math.min(1, MAX_SIDE / Math.max(width, height));
+  const canvas = document.createElement("canvas");
+  canvas.width = Math.round(width * scale) || 1;
+  canvas.height = Math.round(height * scale) || 1;
+  const g = canvas.getContext("2d");
+  if (!svg) {
+    g.fillStyle = "#fff";
+    g.fillRect(0, 0, canvas.width, canvas.height);
+  }
+  g.drawImage(source, 0, 0, canvas.width, canvas.height);
+  return { type: "image", data_url: svg ? canvas.toDataURL("image/png") : canvas.toDataURL("image/jpeg", 0.85) };
+}
+
+async function fromImg(img, svg) {
+  if (!img.naturalWidth) await img.decode();
+  return rasterize(img, img.naturalWidth, img.naturalHeight, svg);
+}
+
+async function imagePart(input) {
+  try {
+    if (isA(input, "HTMLImageElement")) return await fromImg(input, isSvg(input.currentSrc || input.src));
+    const svg = isSvg(input.type);
+    if (!svg && typeof globalThis.createImageBitmap === "function") {
+      const bitmap = await globalThis.createImageBitmap(input);
+      try {
+        return rasterize(bitmap, bitmap.width, bitmap.height, false);
+      } finally {
+        bitmap.close();
+      }
+    }
+    const url = URL.createObjectURL(input);
+    try {
+      const img = new Image();
+      img.src = url;
+      return await fromImg(img, svg);
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+  } catch (e) {
+    throw new OneTagError("bad_input", e.name === "SecurityError"
+      ? "Cross-origin image without CORS: add crossorigin=\"anonymous\" or pass a File"
+      : "Could not read image: " + e.message);
+  }
+}
+
+// Every field as a "name: value" line, except password fields.
+function formText(form) {
+  const secret = new Set();
+  for (const el of form.elements || []) if (el.type === "password") secret.add(el.name);
+  const lines = [];
+  for (const [name, value] of new FormData(form)) {
+    if (!secret.has(name)) lines.push(name + ": " + (typeof value === "string" ? value : value.name));
+  }
+  return lines.join("\n");
+}
+
+async function normalizeInput(input) {
+  if (input == null) return [];
+  if (Array.isArray(input)) return (await Promise.all(input.map(normalizeInput))).flat();
+  if (typeof input === "string") return [textPart(input)];
+  if (isA(input, "HTMLImageElement") || (isA(input, "Blob") && /^image\//.test(input.type))) return [await imagePart(input)];
+  if (isA(input, "Blob")) return [textPart(await input.text())];
+  if (isA(input, "HTMLFormElement")) return [textPart(formText(input))];
+  if (CONTROLS.some((type) => isA(input, type))) return [textPart(input.value)];
+  if (isA(input, "HTMLElement")) return [textPart(input.innerText || input.textContent || "")];
+  // NodeList, HTMLCollection, Set: read like an array. After the element checks,
+  // because forms and selects are iterable too.
+  if (typeof input[Symbol.iterator] === "function") return normalizeInput(Array.from(input));
+  let json;
+  try {
+    json = JSON.stringify(input, null, 2);
+  } catch (e) {}
+  if (json === undefined) throw new OneTagError("bad_input", "Unsupported input: " + typeof input);
+  return [textPart(json)];
+}
+
+function parseSSE(buffer) {
+  const blocks = buffer.split("\n\n");
+  const rest = blocks.pop();
+  const events = [];
+  for (const block of blocks) {
+    for (const line of block.split("\n")) {
+      if (line.startsWith("data: ")) events.push(JSON.parse(line.slice(6)));
+    }
+  }
+  return { events, rest };
+}
+
+const stripFences = (s) => s.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+
+const networkError = (detail) => new OneTagError("network", "Network error: " + detail, 0);
+// A fired signal rejects fetch with its reason, which is an AbortError unless the caller gave one.
+const isAbort = (e, signal) => !!(signal && signal.aborted) || !!(e && e.name === "AbortError");
+const abortError = () => new OneTagError("aborted", "Request aborted", 0);
+
+async function readStream(response, onDelta, signal) {
+  const reader = response.body.getReader();
+  const decoder = new globalThis.TextDecoder();
+  let buffer = "";
+  let text = "";
+  try {
+    for (;;) {
+      const { done, value } = await reader.read().catch((e) => { throw isAbort(e, signal) ? abortError() : networkError(e.message); });
+      if (done) throw networkError("the stream ended before the answer was complete");
+      const parsed = parseSSE(buffer + decoder.decode(value, { stream: true }));
+      buffer = parsed.rest;
+      for (const event of parsed.events) {
+        if (event.error) throw new OneTagError(event.error.code, event.error.message, response.status);
+        if (event.done) return text;
+        if (event.delta) {
+          text += event.delta;
+          if (typeof onDelta === "function") onDelta(event.delta);
+        }
+      }
+    }
+  } finally {
+    reader.cancel().catch(() => {});
+  }
+}
+
+async function ask(prompt, input, options) {
+  const o = options || {};
+  // options.key and options.via are for packages built on the SDK: they send their own
+  // key and name with each call and leave the page's configuration alone.
+  const key = o.key || config.key;
+  if (!key || /^YOUR_/i.test(key)) {
+    // A placeholder left by a template or an AI coding tool is reported like a missing key, with where to fix it.
+    throw new OneTagError("no_key", (key ? "OneTag AI key is still the placeholder " + key + ". " : "No OneTag AI key. ")
+      + "Get a free key (email only) at " + HOME + "/#get-key and put it in data-key on the script tag (or onetag.configure({key})).", 0);
+  }
+  const history = Array.isArray(o.history) ? o.history : [];
+  // 20 per history message: the server's allowance for its role and framing.
+  const budget = MAX_TEXT - len(prompt) - len(o.system) - history.reduce((n, m) => n + 20 + len(m && m.content), 0);
+  const body = JSON.stringify({
+    key,
+    prompt,
+    input: fit(await normalizeInput(input), budget),
+    system: o.system,
+    json: !!o.json,
+    max_tokens: o.maxTokens,
+    stream: !!o.stream,
+    history: o.history,
+    via: o.via || config.via || undefined,
+  });
+  let response;
+  try {
+    response = await globalThis.fetch(config.endpoint, { method: "POST", headers: { "Content-Type": "application/json" }, body, signal: o.signal });
+  } catch (e) {
+    throw isAbort(e, o.signal) ? abortError() : networkError(e && e.message);
+  }
+  if (!response.ok) {
+    const error = (await response.json().catch(() => null) || {}).error;
+    throw error
+      ? new OneTagError(error.code, error.message, response.status)
+      : new OneTagError("upstream", "OneTag AI returned HTTP " + response.status, response.status);
+  }
+  const text = o.stream
+    ? await readStream(response, o.stream, o.signal)
+    : (await response.json().catch((e) => { throw isAbort(e, o.signal) ? abortError() : e; })).text;
+  if (!o.json) return text;
+  try {
+    return JSON.parse(stripFences(text));
+  } catch (e) {
+    throw new OneTagError("bad_json", "The answer was not valid JSON", 0);
+  }
+}
+
+const version = "1.2.0";
+
+export { ask, configure, OneTagError, version };

package/index.d.ts

@@ -0,0 +1,78 @@
+/** A piece of input: text, a DOM element (its text), a form (its fields), an image or File, any JSON value, or a list of those. */
+export type AskInput = string | Blob | Element | Iterable<unknown> | object | null | undefined;
+
+export interface AskMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+export interface AskOptions {
+  /** Instructions for the model: a persona, limits, a format. */
+  system?: string;
+  /** Called with each piece of the answer as it arrives. The promise still resolves with the whole answer. */
+  stream?: (delta: string) => void;
+  /** Parse the answer as JSON and return the value. */
+  json?: boolean;
+  /** Cap on the answer length in tokens (default 500, at most 10000). */
+  maxTokens?: number;
+  /** Earlier turns of the conversation, oldest first. */
+  history?: AskMessage[];
+  /** Abort the call. */
+  signal?: AbortSignal;
+  /** Use this key for this call instead of the configured one. */
+  key?: string;
+  /** A short slug naming the integration that sends the call. For packages built on this one. */
+  via?: string;
+}
+
+export interface ConfigureOptions {
+  /** Your OneTag AI key. It is designed to be public, like an analytics ID. */
+  key?: string;
+  /** The API endpoint. Default https://onetagai.com/v1/ask */
+  endpoint?: string;
+  /** A short slug naming the integration that sends the calls. */
+  via?: string;
+}
+
+export type OneTagErrorCode =
+  | "no_key"
+  | "bad_input"
+  | "bad_json"
+  | "network"
+  | "aborted"
+  | "bad_request"
+  | "bad_key"
+  | "domain_not_allowed"
+  | "too_large"
+  | "quota_exceeded"
+  | "rate_limited"
+  | "upstream"
+  | "paused"
+  | (string & {});
+
+export class OneTagError extends Error {
+  code: OneTagErrorCode;
+  /** HTTP status, or 0 when the call never reached the server. */
+  status: number;
+  constructor(code: OneTagErrorCode, message: string, status?: number);
+}
+
+/** Set the key once, before the first call. */
+export function configure(options?: ConfigureOptions): void;
+
+/** Ask the model. `input` is what the prompt is about: text, an element, a form, an image, JSON, or a list of those. */
+export function ask<T = unknown>(prompt: string, input: AskInput, options: AskOptions & { json: true }): Promise<T>;
+export function ask(prompt: string, input?: AskInput, options?: AskOptions): Promise<string>;
+
+export const version: string;
+/** The shared demo key this package falls back to on localhost when no key is set. */
+export const DEMO_KEY: string;
+
+declare const onetag: {
+  ask: typeof ask;
+  configure: typeof configure;
+  OneTagError: typeof OneTagError;
+  version: string;
+  DEMO_KEY: string;
+};
+export default onetag;

package/index.js

@@ -0,0 +1,53 @@
+/*! onetag | https://onetagai.com | MIT */
+import { ask as send, configure as set, OneTagError, version } from "./core.js";
+
+// The shared demo key. It answers while you develop on localhost, so a fresh install works
+// before you have a key. Its small daily budget is shared by everyone, so a deployed site
+// needs its own free key.
+const DEMO_KEY = "ot_demo000000000000000000000";
+const GET_KEY =
+  "Get your own free key (email only): curl -X POST https://onetagai.com/api/signup " +
+  `-H "Content-Type: application/json" -d '{"email":"you@example.com"}'`;
+
+let key = "";
+let via = "npm";
+let told = false;
+
+const missing = (value) => !value || /^YOUR_/i.test(value);
+
+// A page on localhost or opened from a file; outside a browser, anything but a production build.
+function isLocal() {
+  const location = globalThis.location;
+  if (location && typeof location.hostname === "string") {
+    return /^(|localhost|127\.0\.0\.1|\[::1\]|.+\.localhost)$/.test(location.hostname);
+  }
+  const env = globalThis.process && globalThis.process.env;
+  return !!env && env.NODE_ENV !== "production";
+}
+
+function configure(options = {}) {
+  if (options.key !== undefined) key = options.key;
+  if (options.via !== undefined) via = options.via;
+  if (options.endpoint !== undefined) set({ endpoint: options.endpoint });
+}
+
+async function ask(prompt, input, options) {
+  const o = options || {};
+  let use = o.key || key;
+  if (missing(use)) {
+    if (!isLocal()) {
+      throw new OneTagError("no_key", "No OneTag AI key: the demo key only answers on localhost. " + GET_KEY + " Then call configure({ key }).", 0);
+    }
+    if (!told) {
+      told = true;
+      console.info("[onetag] No key set: using the shared demo key, which works on localhost only. " + GET_KEY);
+    }
+    use = DEMO_KEY;
+  }
+  return send(prompt, input, { ...o, key: use, via: o.via || via });
+}
+
+const onetag = { ask, configure, OneTagError, version, DEMO_KEY };
+
+export { ask, configure, OneTagError, version, DEMO_KEY };
+export default onetag;

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "onetagai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "AI for static sites without a backend: ask(prompt, input) from the browser with a public key. No server, no secret in your code.",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": ["index.js", "core.js", "index.d.ts", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node build.mjs --check && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": ["ai", "llm", "static-site", "no-backend", "browser", "frontend", "chatbot", "summarize", "translate", "jamstack", "onetag", "onetagai"],
+  "license": "MIT",
+  "author": "OneTag AI (https://onetagai.com)",
+  "homepage": "https://onetagai.com/?ref=npm",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fengyiqicoder/onetagai.git",
+    "directory": "packages/onetag"
+  },
+  "bugs": "https://github.com/fengyiqicoder/onetagai/issues"
+}