@mybase-dev/sdk 1.0.0 → 1.0.2

package/dist/vector.js

@@ -0,0 +1,331 @@
+// 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/vector.ts
+var VECTOR_INDEX_PATTERN = /^[a-z][a-z0-9_]{0,47}$/;
+var VECTOR_INDEX_RULES = "Use 1–48 lowercase letters, digits, or `_`, starting with a letter.";
+var VECTOR_METRICS = ["cosine", "l2", "ip"];
+var VECTOR_LANGUAGES = [
+  "simple",
+  "arabic",
+  "armenian",
+  "basque",
+  "catalan",
+  "danish",
+  "dutch",
+  "english",
+  "finnish",
+  "french",
+  "german",
+  "greek",
+  "hindi",
+  "hungarian",
+  "indonesian",
+  "irish",
+  "italian",
+  "lithuanian",
+  "nepali",
+  "norwegian",
+  "portuguese",
+  "romanian",
+  "russian",
+  "serbian",
+  "spanish",
+  "swedish",
+  "tamil",
+  "turkish",
+  "yiddish"
+];
+var VECTOR_QUERY_MODES = ["text", "vector", "hybrid"];
+var VECTOR_LIMITS = {
+  batch: 100,
+  batchBytes: 8 * 1024 * 1024,
+  idLength: 256,
+  titleLength: 1000,
+  textLength: 1e5,
+  metadataBytes: 16 * 1024,
+  dimensions: { min: 1, max: 2000 },
+  topK: { min: 1, max: 100, default: 10 },
+  queryLength: 2000,
+  indexesPerProject: 50
+};
+function createVectorClient(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const base = `${options.apiUrl.replace(/\/+$/, "")}/vector/${encodeURIComponent(options.project)}/indexes`;
+  const timeoutMs = options.timeoutMs ?? 30000;
+  const path = (name, rest = "") => `${base}/${encodeURIComponent(name)}${rest}`;
+  async function call(method, url, body) {
+    const res = await doFetch(url, {
+      method,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (res.status === 204)
+      return;
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok)
+      throw new MybaseApiError(data.error ?? `mybase API answered ${res.status}`, res.status);
+    return data;
+  }
+  function index(name) {
+    return {
+      name,
+      upsert: (documents) => call("POST", path(name, "/documents"), { documents: Array.isArray(documents) ? documents : [documents] }),
+      async get(ids, opts = {}) {
+        const params = new URLSearchParams;
+        for (const id of Array.isArray(ids) ? ids : [ids])
+          params.append("id", id);
+        if (opts.includeVectors)
+          params.set("includeVectors", "true");
+        const { documents } = await call("GET", path(name, `/documents?${params}`));
+        return documents;
+      },
+      delete(target) {
+        const body = typeof target === "string" ? { ids: [target] } : Array.isArray(target) ? { ids: target } : { filter: target.filter };
+        return call("POST", path(name, "/documents/delete"), body);
+      },
+      query(query, opts = {}) {
+        const body = typeof query === "string" ? { ...opts, text: query } : { ...opts, ...query };
+        return call("POST", path(name, "/query"), body);
+      },
+      list({ limit, after } = {}) {
+        const params = new URLSearchParams;
+        if (limit !== undefined)
+          params.set("limit", String(limit));
+        if (after !== undefined)
+          params.set("after", after);
+        return call("GET", path(name, `/documents?${params}`));
+      },
+      info: () => call("GET", path(name))
+    };
+  }
+  return {
+    index,
+    listIndexes: () => call("GET", base),
+    getIndex: (name) => call("GET", path(name)),
+    createIndex: (name, settings = {}) => call("POST", base, { name, ...settings }),
+    updateIndex: (name, settings) => call("PATCH", path(name), settings),
+    deleteIndex: (name) => call("DELETE", path(name))
+  };
+}
+function retrievalTool(index, options = {}) {
+  const maxChars = options.maxChars ?? 2000;
+  return {
+    name: options.name ?? "search_documents",
+    description: `Search ${options.about ?? "the knowledge base"} and return the most relevant passages with their ids. ` + "Use specific words from the topic you need.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string", description: "What to look for." } },
+      required: ["query"],
+      additionalProperties: false
+    },
+    async run(input) {
+      const query = typeof input === "object" && input !== null ? input.query : undefined;
+      if (typeof query !== "string" || !query.trim())
+        return "Error: query is required.";
+      try {
+        const { matches } = await index.query(query, { topK: options.topK ?? 5, filter: options.filter, mode: options.mode });
+        if (matches.length === 0)
+          return `Nothing found for "${query}".`;
+        return matches.map((m, i) => {
+          const text = (m.text ?? "").length > maxChars ? `${m.text.slice(0, maxChars)}…` : m.text ?? "";
+          return `${i + 1}. [${m.id}]${m.title ? ` ${m.title}` : ""}
+${text}`;
+        }).join(`
+
+`);
+      } catch (error) {
+        if (error instanceof MybaseApiError && ![401, 403, 404].includes(error.status))
+          return `Error: ${error.message}`;
+        throw error;
+      }
+    }
+  };
+}
+export {
+  MybaseApiError,
+  VECTOR_INDEX_PATTERN,
+  VECTOR_INDEX_RULES,
+  VECTOR_LANGUAGES,
+  VECTOR_LIMITS,
+  VECTOR_METRICS,
+  VECTOR_QUERY_MODES,
+  createVectorClient,
+  retrievalTool
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mybase-dev/sdk",
-  "version": "1.0.0",
-  "description": "Client helpers for apps running on mybase: analytics, cron calls, one-off tasks, cache, rate limits, queues.",
+  "version": "1.0.2",
+  "description": "Client helpers for apps running on mybase: analytics, cron calls, one-off tasks, cache, rate limits, queues, web search, secrets, vector and full-text search, Better Auth, captcha.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -38,6 +38,31 @@
       "bun": "./src/queue.ts",
       "types": "./dist/queue.d.ts",
       "default": "./dist/queue.js"
+    },
+    "./search": {
+      "bun": "./src/search.ts",
+      "types": "./dist/search.d.ts",
+      "default": "./dist/search.js"
+    },
+    "./secrets": {
+      "bun": "./src/secrets.ts",
+      "types": "./dist/secrets.d.ts",
+      "default": "./dist/secrets.js"
+    },
+    "./vector": {
+      "bun": "./src/vector.ts",
+      "types": "./dist/vector.d.ts",
+      "default": "./dist/vector.js"
+    },
+    "./better-auth": {
+      "bun": "./src/better-auth.ts",
+      "types": "./dist/better-auth.d.ts",
+      "default": "./dist/better-auth.js"
+    },
+    "./captcha": {
+      "bun": "./src/captcha.ts",
+      "types": "./dist/captcha.d.ts",
+      "default": "./dist/captcha.js"
     }
   },
   "files": [
@@ -48,13 +73,18 @@
     "src/cache.ts",
     "src/ratelimit.ts",
     "src/queue.ts",
+    "src/search.ts",
+    "src/secrets.ts",
+    "src/vector.ts",
+    "src/better-auth.ts",
+    "src/captcha.ts",
     "README.md"
   ],
   "engines": {
     "node": ">=20"
   },
   "scripts": {
-    "build": "rm -rf dist && bun build src/analytics.ts src/cron.ts src/config.ts src/cache.ts src/ratelimit.ts src/queue.ts --outdir dist --target node --format esm && bun build src/analytics-script.ts --outfile dist/analytics.min.js --target browser --format iife --minify && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/analytics.ts src/cron.ts src/config.ts src/cache.ts src/ratelimit.ts src/queue.ts src/search.ts src/secrets.ts src/vector.ts src/better-auth.ts src/captcha.ts --root src --outdir dist --target node --format esm && bun build src/analytics-script.ts --outfile dist/analytics.min.js --target browser --format iife --minify && bun build src/captcha-widget.ts --outfile dist/captcha.min.js --target browser --format iife --minify && tsc -p tsconfig.build.json",
     "test": "bun test",
     "prepublishOnly": "bun run build"
   },

package/src/better-auth.ts

@@ -0,0 +1,189 @@
+// Sign-in for your app's users with Better Auth (https://better-auth.com), backed by mybase.
+// Better Auth runs in your app and does the auth work; these helpers plug mybase in:
+//
+//   import { betterAuth } from "better-auth";
+//   import { captcha } from "better-auth/plugins";
+//   import { Pool } from "pg";
+//   import { createCache } from "@mybase-dev/sdk/cache";
+//   import { authDatabaseUrl, mybaseAuth, mybaseCaptcha, mybaseSecondaryStorage } from "@mybase-dev/sdk/better-auth";
+//
+//   const mybase = { apiUrl: process.env.MYBASE_URL!, project: "shop", apiKey: process.env.MYBASE_API_KEY! };
+//   export const auth = betterAuth({
+//     database: new Pool({ connectionString: authDatabaseUrl(process.env.DATABASE_URL!) }),
+//     secondaryStorage: mybaseSecondaryStorage(createCache(mybase)),
+//     session: { storeSessionInDatabase: true },
+//     emailAndPassword: { enabled: true },
+//     plugins: [mybaseAuth(mybase), captcha(mybaseCaptcha({ ...mybase, secretKey: process.env.MYBASE_CAPTCHA_SECRET! }))],
+//   });
+//
+// Nothing here imports better-auth, so this module adds no dependencies; the shapes below
+// match Better Auth's `SecondaryStorage`, plugin, and captcha options (checked against 1.7).
+import type { Cache } from "./cache";
+
+/** Better Auth's tables live in this schema of the project's database (the `users` service creates it). */
+export const AUTH_SCHEMA = "auth";
+
+/**
+ * The project's connection string with `search_path` set to the auth schema, so Better Auth's
+ * tables (and its migrations) land there instead of next to your app's tables in `public`.
+ * Pass `extra` schemas to also see them unqualified (e.g. `["public"]`).
+ */
+export function authDatabaseUrl(url: string, extra: string[] = []): string {
+  const u = new URL(url);
+  const path = [AUTH_SCHEMA, ...extra].join(",");
+  u.searchParams.set("options", `-c search_path=${path}`);
+  return u.toString();
+}
+
+/** What Better Auth's `secondaryStorage` option takes. TTLs are in seconds. */
+export interface SecondaryStorage {
+  get(key: string): Promise<string | null>;
+  getAndDelete(key: string): Promise<string | null>;
+  increment(key: string, ttl: number): Promise<number>;
+  set(key: string, value: string, ttl?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * Better Auth's `secondaryStorage` on the project's mybase cache (Valkey): sessions and rate
+ * limit counters stay in memory instead of hitting Postgres (and the SD card) on every request.
+ * Keys go under `<project>:auth:`, inside the project's cache ACL. Needs the cache service and an
+ * API key with `cache:write`. The dashboard's Users page revokes sessions here too.
+ */
+export function mybaseSecondaryStorage(cache: Cache, { prefix = "auth:" }: { prefix?: string } = {}): SecondaryStorage {
+  const k = (key: string) => cache.key(prefix + key);
+  return {
+    get: (key) => cache.command<string | null>(["GET", k(key)]),
+    getAndDelete: (key) => cache.command<string | null>(["GETDEL", k(key)]),
+    async increment(key, ttl) {
+      // Created at 0 with the TTL (only if absent), then incremented: the window starts at the first hit.
+      const [, incr] = await cache
+        .pipeline()
+        .command(["SET", k(key), 0, "EX", Math.max(1, Math.ceil(ttl)), "NX"])
+        .command(["INCR", k(key)])
+        .exec({ atomic: true });
+      if (!incr || "error" in incr) throw new Error(`mybase cache: ${incr && "error" in incr ? incr.error : "no reply"}`);
+      return Number(incr.result);
+    },
+    async set(key, value, ttl) {
+      await cache.command(ttl && ttl > 0 ? ["SET", k(key), value, "EX", Math.ceil(ttl)] : ["SET", k(key), value]);
+    },
+    async delete(key) {
+      await cache.command(["DEL", k(key)]);
+    },
+  };
+}
+
+export interface MybaseAuthOptions {
+  /** Where the mybase API is reachable from your app. */
+  apiUrl: string;
+  project: string;
+  /** A mybase API key with `users:write` for this project. Server-side only. */
+  apiKey: string;
+  /** Default `globalThis.fetch`. */
+  fetch?: typeof fetch;
+  /** Called when an event can't be sent (it's dropped, never retried). Default: console.warn. */
+  onError?: (err: unknown) => void;
+}
+
+/** What the app reports to mybase's audit log (`POST /users/:project/events`). */
+export type UserEventType = "user.created" | "user.deleted" | "session.created" | "session.revoked";
+
+export interface UserEvent {
+  type: UserEventType;
+  userId: string;
+  /** The end user's IP and user agent, as Better Auth saw them. */
+  ip?: string | null;
+  userAgent?: string | null;
+}
+
+interface SessionLike {
+  userId: string;
+  ipAddress?: string | null;
+  userAgent?: string | null;
+}
+
+/**
+ * A Better Auth plugin that reports sign-ups, sign-ins, sign-outs, and deleted users to the
+ * project's mybase audit log, where they show up next to everything else (and on the
+ * dashboard's Users page). No passwords, emails, or tokens are sent: user ids, IPs, user agents.
+ * Sending never blocks or fails a sign-in.
+ */
+export function mybaseAuth(options: MybaseAuthOptions) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const url = `${options.apiUrl.replace(/\/+$/, "")}/users/${encodeURIComponent(options.project)}/events`;
+  const onError = options.onError ?? ((err: unknown) => console.warn("mybase: auth event not sent:", err));
+
+  const send = (event: UserEvent) => {
+    void doFetch(url, {
+      method: "POST",
+      body: JSON.stringify({ events: [event] }),
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` },
+    })
+      .then(async (res) => {
+        if (!res.ok) onError(new Error(`mybase API answered ${res.status}: ${await res.text().catch(() => "")}`));
+      })
+      .catch(onError);
+  };
+  const fromSession = (type: UserEventType, s: SessionLike) => send({ type, userId: s.userId, ip: s.ipAddress ?? null, userAgent: s.userAgent ?? null });
+
+  return {
+    id: "mybase" as const,
+    init() {
+      return {
+        options: {
+          databaseHooks: {
+            user: {
+              create: { after: async (user: { id: string }) => send({ type: "user.created", userId: user.id }) },
+              delete: { after: async (user: { id: string }) => send({ type: "user.deleted", userId: user.id }) },
+            },
+            session: {
+              create: { after: async (session: SessionLike) => fromSession("session.created", session) },
+              delete: { after: async (session: SessionLike) => fromSession("session.revoked", session) },
+            },
+          },
+        },
+      };
+    },
+  };
+}
+
+export interface MybaseCaptchaOptions {
+  apiUrl: string;
+  project: string;
+  /** The project's captcha secret (dashboard → Captcha, or `mybase captcha key`). Server-side only. */
+  secretKey: string;
+  /** Better Auth routes that need a solved captcha. Default: sign-up, sign-in, and password reset. */
+  endpoints?: string[];
+}
+
+/**
+ * Options for Better Auth's `captcha()` plugin that check tokens with mybase's self-hosted
+ * captcha instead of Cloudflare's: mybase answers in Turnstile's siteverify format. Put the
+ * widget (`<script src="<mybase>/captcha.js">`) on your forms and send its token in the
+ * `x-captcha-response` header, as Better Auth expects.
+ */
+export function mybaseCaptcha(options: MybaseCaptchaOptions) {
+  return {
+    provider: "cloudflare-turnstile" as const,
+    secretKey: options.secretKey,
+    siteVerifyURLOverride: `${options.apiUrl.replace(/\/+$/, "")}/captcha/${encodeURIComponent(options.project)}/siteverify`,
+    ...(options.endpoints ? { endpoints: options.endpoints } : {}),
+  };
+}
+
+/**
+ * The statement that tells Postgres who the signed-in user is, for row-level security policies
+ * on `mybase_auth.uid()`. Run it inside the same transaction as your queries:
+ *
+ *   await sql.begin(async (tx) => {
+ *     const q = userContextQuery(session.user.id);
+ *     await tx.unsafe(q.text, q.values);
+ *     return tx`select * from orders`; // policy: using (user_id = mybase_auth.uid())
+ *   });
+ *
+ * Policies only apply to the table owner (your app's role) with `force row level security`.
+ */
+export function userContextQuery(userId: string): { text: string; values: [string] } {
+  return { text: "select set_config('mybase.user_id', $1, true)", values: [userId] };
+}