@mybase-dev/sdk 1.0.0 → 1.0.2

package/dist/captcha.js

@@ -0,0 +1,239 @@
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+var DEFAULT_CRON_PATH = "/api/cron";
+
+// src/cron.ts
+var SIGNATURE_HEADER = "X-Mybase-Signature";
+var JOB_HEADER = "X-Mybase-Job";
+var RUN_HEADER = "X-Mybase-Run";
+
+class CronVerificationError extends Error {
+  name = "CronVerificationError";
+}
+var encoder = new TextEncoder;
+async function hmacHex(secret, message) {
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(message)));
+  return Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function safeEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let diff = 0;
+  for (let i = 0;i < a.length; i++)
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+async function signCronRequest(secret, body, t = Math.floor(Date.now() / 1000)) {
+  return `t=${t},v1=${await hmacHex(secret, `${t}.${body}`)}`;
+}
+async function verifySigned(signature, secret, toleranceSec, message) {
+  if (!signature)
+    throw new CronVerificationError(`missing ${SIGNATURE_HEADER} header`);
+  let t;
+  const sigs = [];
+  for (const part of signature.split(",")) {
+    const [k, v] = part.trim().split("=", 2);
+    if (k === "t" && v && /^\d+$/.test(v))
+      t = Number(v);
+    else if (k === "v1" && v)
+      sigs.push(v);
+  }
+  if (t === undefined || sigs.length === 0)
+    throw new CronVerificationError(`malformed ${SIGNATURE_HEADER} header`);
+  if (Math.abs(Date.now() / 1000 - t) > toleranceSec)
+    throw new CronVerificationError("signature timestamp outside tolerance");
+  const secrets = typeof secret === "string" ? [secret] : secret;
+  if (secrets.length === 0 || secrets.some((s) => !s))
+    throw new CronVerificationError("no cron secret configured");
+  for (const s of secrets) {
+    const expected = await hmacHex(s, message(t));
+    if (sigs.some((sig) => safeEqual(sig, expected)))
+      return;
+  }
+  throw new CronVerificationError("signature does not match");
+}
+async function verifyCronSignature({ body, signature, secret, toleranceSec = 300 }) {
+  await verifySigned(signature, secret, toleranceSec, (t) => `${t}.${body}`);
+}
+async function verifyCronRequest(req, secret, options = {}) {
+  const body = await req.text();
+  await verifyCronSignature({ body, signature: req.headers.get(SIGNATURE_HEADER), secret, ...options });
+  let run;
+  try {
+    run = JSON.parse(body);
+  } catch {
+    throw new CronVerificationError("body is not JSON");
+  }
+  if (typeof run?.job !== "string" || typeof run.runId !== "string")
+    throw new CronVerificationError("body is not a cron run");
+  return run;
+}
+var reply = (body, status) => new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+function cronHandler(options) {
+  const jobs = options.jobs;
+  return async (req) => {
+    if (req.method !== "POST")
+      return reply({ error: "method not allowed" }, 405);
+    let run;
+    try {
+      run = await verifyCronRequest(req, options.secret, { toleranceSec: options.toleranceSec });
+    } catch (err) {
+      if (err instanceof CronVerificationError)
+        return reply({ error: err.message }, 401);
+      throw err;
+    }
+    const job = Object.hasOwn(jobs, run.job) ? jobs[run.job] : undefined;
+    if (!job)
+      return reply({ error: `no handler for job "${run.job}"` }, 404);
+    try {
+      await job(run);
+    } catch (err) {
+      if (options.onError)
+        options.onError(err, run);
+      else
+        console.error(`mybase cron job "${run.job}" failed`, err);
+      return reply({ error: "job failed" }, 500);
+    }
+    return reply({ ok: true }, 200);
+  };
+}
+
+class MybaseApiError extends Error {
+  status;
+  name = "MybaseApiError";
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+}
+var UNITS = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+function parseDelay(value) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0)
+      throw new RangeError("delay must be a non-negative number of ms");
+    return Math.round(value);
+  }
+  const m = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)\s*$/.exec(value);
+  if (!m)
+    throw new RangeError(`invalid delay "${value}". Use ms, or a number with ms, s, m, h, or d (e.g. "15m")`);
+  return Math.round(Number(m[1]) * UNITS[m[2]]);
+}
+function createCronClient(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const apiUrl = options.apiUrl.replace(/\/+$/, "");
+  const base = `/cron/${encodeURIComponent(options.project)}/tasks`;
+  async function call(method, path, body) {
+    const raw = body === undefined ? "" : JSON.stringify(body);
+    const res = await doFetch(`${apiUrl}${path}`, {
+      method,
+      body: body === undefined ? undefined : raw,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${options.apiKey}`
+      }
+    });
+    if (res.status === 404 && method !== "POST")
+      return null;
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok)
+      throw new MybaseApiError(data.error ?? `mybase API answered ${res.status}`, res.status);
+    return data;
+  }
+  const byId = (id) => `${base}/${encodeURIComponent(id)}`;
+  const byKey = (key) => `${base}/by-key/${encodeURIComponent(key)}`;
+  return {
+    async schedule(job, opts = {}) {
+      if (opts.at !== undefined && opts.in !== undefined)
+        throw new TypeError("give `at` or `in`, not both");
+      let url = opts.url;
+      if (!url) {
+        if (!options.baseUrl)
+          throw new TypeError("set `baseUrl` on the client, or `url` on the task");
+        url = `${options.baseUrl.replace(/\/+$/, "")}/${(opts.path ?? DEFAULT_CRON_PATH).replace(/^\/+/, "")}`;
+      }
+      const at = opts.at === undefined ? undefined : new Date(opts.at);
+      if (at && Number.isNaN(at.getTime()))
+        throw new RangeError(`invalid date "${String(opts.at)}"`);
+      const req = {
+        job,
+        url,
+        runAt: at?.toISOString(),
+        delayMs: opts.in === undefined ? undefined : parseDelay(opts.in),
+        key: opts.key,
+        payload: opts.payload,
+        retries: opts.retries,
+        timeoutMs: opts.timeoutMs
+      };
+      return await call("POST", base, req);
+    },
+    get: (id) => call("GET", byId(id)),
+    getByKey: (key) => call("GET", byKey(key)),
+    cancel: (id) => call("DELETE", byId(id)),
+    cancelByKey: (key) => call("DELETE", byKey(key))
+  };
+}
+
+// src/captcha.ts
+var CAPTCHA_LIMITS = {
+  expiresMs: 5 * 60000,
+  maxNumber: { min: 1000, max: 1e6, default: 50000 },
+  tokenLength: 2000
+};
+var hex = (buf) => Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, "0")).join("");
+async function sha256Hex(text) {
+  return hex(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+}
+function encodeToken(c, number) {
+  const json = JSON.stringify({ algorithm: c.algorithm, challenge: c.challenge, number, salt: c.salt, signature: c.signature });
+  return btoa(json);
+}
+async function solveChallenge(c, { signal } = {}) {
+  if (c.algorithm !== "SHA-256")
+    throw new Error(`mybase captcha: unknown algorithm ${c.algorithm}`);
+  for (let n = 0;n <= c.maxnumber; n++) {
+    if (await sha256Hex(c.salt + n) === c.challenge)
+      return encodeToken(c, n);
+    if (n % 1000 === 0 && signal?.aborted)
+      throw signal.reason ?? new Error("aborted");
+  }
+  throw new Error("mybase captcha: challenge has no solution");
+}
+async function solveCaptcha(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const res = await doFetch(`${options.apiUrl.replace(/\/+$/, "")}/captcha/${encodeURIComponent(options.project)}/challenge`, { signal: options.signal });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok)
+    throw new MybaseApiError(body.error ?? `mybase API answered ${res.status}`, res.status);
+  return solveChallenge(body, { signal: options.signal });
+}
+function createCaptchaClient(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const url = `${options.apiUrl.replace(/\/+$/, "")}/captcha/${encodeURIComponent(options.project)}/verify`;
+  return {
+    async verify(token) {
+      if (typeof token !== "string" || !token || token.length > CAPTCHA_LIMITS.tokenLength)
+        return { success: false, error: "invalid" };
+      const res = await doFetch(url, {
+        method: "POST",
+        body: JSON.stringify({ token }),
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` }
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok)
+        throw new MybaseApiError(body.error ?? `mybase API answered ${res.status}`, res.status);
+      return body;
+    }
+  };
+}
+export {
+  CAPTCHA_LIMITS,
+  MybaseApiError,
+  createCaptchaClient,
+  encodeToken,
+  sha256Hex,
+  solveCaptcha,
+  solveChallenge
+};

package/dist/captcha.min.js

@@ -0,0 +1 @@
+(()=>{class u extends Error{status;name="MybaseApiError";constructor(e,r){super(e);this.status=r}}var p=(e)=>Array.from(new Uint8Array(e),(r)=>r.toString(16).padStart(2,"0")).join("");async function f(e){return p(await crypto.subtle.digest("SHA-256",new TextEncoder().encode(e)))}function h(e,r){let t=JSON.stringify({algorithm:e.algorithm,challenge:e.challenge,number:r,salt:e.salt,signature:e.signature});return btoa(t)}async function y(e,{signal:r}={}){if(e.algorithm!=="SHA-256")throw Error(`mybase captcha: unknown algorithm ${e.algorithm}`);for(let t=0;t<=e.maxnumber;t++){if(await f(e.salt+t)===e.challenge)return h(e,t);if(t%1000===0&&r?.aborted)throw r.reason??Error("aborted")}throw Error("mybase captcha: challenge has no solution")}async function g(e){let t=await(e.fetch??globalThis.fetch)(`${e.apiUrl.replace(/\/+$/,"")}/captcha/${encodeURIComponent(e.project)}/challenge`,{signal:e.signal}),o=await t.json().catch(()=>({}));if(!t.ok)throw new u(o.error??`mybase API answered ${t.status}`,t.status);return y(o,{signal:e.signal})}var m=document.currentScript,l=m?.dataset??{},d="mybase-captcha";if(!l.project)console.warn("mybase captcha: add data-project to the script tag");else{let e=l.api||new URL(m.src,location.href).origin,r=l.project,t=()=>g({apiUrl:e,project:r});window.mybase={...window.mybase,captcha:{solve:t}};let o=(a,n)=>{let i=a.querySelector(".mybase-captcha-status");if(i)i.textContent=n};document.addEventListener("submit",(a)=>{let n=a.target;if(!(n instanceof HTMLFormElement)||!n.hasAttribute("data-mybase-captcha"))return;if(n.dataset.mybaseCaptchaReady==="1"){delete n.dataset.mybaseCaptchaReady;return}a.preventDefault(),a.stopImmediatePropagation();let i=a.submitter;o(n,"Checking you're not a bot…"),t().then((c)=>{let s=n.querySelector(`input[name="${d}"]`);if(!s)s=document.createElement("input"),s.type="hidden",s.name=d,n.append(s);s.value=c,o(n,""),n.dataset.mybaseCaptchaReady="1",n.requestSubmit(i instanceof HTMLElement?i:void 0)}).catch((c)=>{console.warn("mybase captcha:",c),o(n,"Couldn't check this form. Try again.")})},!0)}})();

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { DeadLetterSettings } from "./queue";
 import type { RateLimitAlgorithm } from "./ratelimit";
+import type { VectorIndexInput } from "./vector";
 /** One job mybase calls on a schedule. */
 export interface CronJobConfig {
     /** Standard 5-field cron expression (minute precision), e.g. `0 3 * * *`. */
@@ -45,6 +46,8 @@ export interface QueueConfig {
     /** After `maxReceives` failed deliveries, move messages to this queue. */
     deadLetter?: DeadLetterSettings;
 }
+/** One vector/full-text index. Dimensions, metric, and language can't change after creation. */
+export type VectorIndexConfig = VectorIndexInput;
 export interface MybaseConfig {
     /** The mybase project these jobs belong to. */
     project: string;
@@ -59,6 +62,9 @@ export interface MybaseConfig {
     queue?: {
         queues: Record<string, QueueConfig>;
     };
+    vector?: {
+        indexes: Record<string, VectorIndexConfig>;
+    };
 }
 /** Identity function that types `mybase.config.ts`. */
 export declare function defineConfig<const C extends MybaseConfig>(config: C): C;

package/dist/search.d.ts

@@ -0,0 +1,120 @@
+import { MybaseApiError } from "./cron";
+export { MybaseApiError };
+/** `general`: the web. `news`: recent articles. `it`: GitHub and Stack Overflow. */
+export declare const SEARCH_CATEGORIES: readonly ["general", "news", "it"];
+export type SearchCategory = (typeof SEARCH_CATEGORIES)[number];
+export declare const SEARCH_TIME_RANGES: readonly ["day", "week", "month", "year"];
+export type SearchTimeRange = (typeof SEARCH_TIME_RANGES)[number];
+export declare const SEARCH_LIMITS: {
+    readonly queryLength: 400;
+    readonly results: {
+        readonly default: 10;
+        readonly max: 20;
+    };
+    readonly page: {
+        readonly max: 10;
+    };
+    readonly urlLength: 2048;
+    readonly maxChars: {
+        readonly default: 20000;
+        readonly min: 500;
+        readonly max: 100000;
+    };
+};
+/** `en`, `de`, `en-US`, …: what language results should be in. */
+export declare const SEARCH_LANGUAGE_PATTERN: RegExp;
+export interface SearchOptions {
+    /** Results to return, 1–20. Default 10. */
+    limit?: number;
+    /** Default `general`. */
+    category?: SearchCategory;
+    /** Only results from the last day/week/month/year. Not every engine supports it. */
+    timeRange?: SearchTimeRange;
+    /** `en`, `en-US`, …. Default: any language. */
+    language?: string;
+    /** Results page, 1–10. Default 1. */
+    page?: number;
+}
+export interface SearchResult {
+    title: string;
+    url: string;
+    /** The text the engines showed under the link. May be empty. */
+    snippet: string;
+    /** Which engines returned it; more engines usually means more relevant. */
+    engines: string[];
+    /** ISO date, when the engine knows it (mostly news). */
+    publishedAt: string | null;
+}
+/** Answer of `GET /search/<project>?q=…`. */
+export interface SearchResponse {
+    query: string;
+    results: SearchResult[];
+    /** True when this answer came from mybase's cache (searches are kept 1 hour). */
+    cached: boolean;
+}
+export interface FetchOptions {
+    /** Cut the markdown at this many characters, 500–100000. Default 20000. */
+    maxChars?: number;
+}
+/** Answer of `GET /search/<project>/fetch?url=…`. */
+export interface FetchResponse {
+    /** Where the page ended up, after redirects. */
+    url: string;
+    title: string | null;
+    /** The page's main content as markdown (navigation, ads, and scripts left out). */
+    markdown: string;
+    /** True when the markdown was cut at `maxChars`. */
+    truncated: boolean;
+    contentType: string;
+    /** True when this answer came from mybase's cache (pages are kept 1 day). */
+    cached: boolean;
+}
+export interface SearchClientOptions {
+    /** Where the mybase API is reachable from your app, e.g. `https://mybase.example.com`. */
+    apiUrl: string;
+    project: string;
+    /** A mybase API key (`mb_…`) with `search:read` for this project. Server-side only. */
+    apiKey: string;
+    /** How long to wait for mybase, in ms. Default 20000 (searches and page reads take seconds). */
+    timeoutMs?: number;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export interface SearchClient {
+    /** Searches the web. Throws `MybaseApiError` when mybase answers with an error. */
+    search(query: string, options?: SearchOptions): Promise<SearchResponse>;
+    /** Reads a public web page as markdown. Throws `MybaseApiError` when it can't (blocked address, not HTML, …). */
+    fetch(url: string, options?: FetchOptions): Promise<FetchResponse>;
+}
+export declare function createSearchClient(options: SearchClientOptions): SearchClient;
+/** JSON Schema for a tool's input (the subset these tools use). */
+export interface ToolInputSchema {
+    type: "object";
+    properties: Record<string, Record<string, unknown>>;
+    required: string[];
+    additionalProperties: false;
+}
+/**
+ * A tool for an LLM agent, independent of the provider. Map it to yours:
+ * Anthropic `{ name, description, input_schema: inputSchema }`,
+ * OpenAI `{ type: "function", function: { name, description, parameters: inputSchema } }`.
+ */
+export interface SearchTool {
+    name: "web_search" | "web_fetch";
+    description: string;
+    inputSchema: ToolInputSchema;
+    /**
+     * Runs the tool with the model's input and returns text for the tool result. Problems the
+     * model can work around (a blocked or unreadable page, no results, bad input, rate limits) come
+     * back as text starting with `Error:`; a wrong key or a disabled service throws.
+     */
+    run(input: unknown): Promise<string>;
+}
+export interface SearchToolsOptions {
+    /** Most characters `web_fetch` returns per page. Default 20000. Keeps tool results inside your context budget. */
+    maxChars?: number;
+    /** Results `web_search` returns. Default 8. */
+    limit?: number;
+}
+/** `web_search` and `web_fetch`, ready for an LLM tool-use loop. */
+export declare function searchTools(client: SearchClient, options?: SearchToolsOptions): SearchTool[];