@mybase-dev/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Landon Harter
+
+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

@@ -0,0 +1,206 @@
+# @mybase-dev/sdk
+
+Helpers for apps that run on [mybase](https://github.com/landonharter/mybase), a self-hosted backend.
+
+```sh
+npm install @mybase-dev/sdk   # or bun add / pnpm add
+```
+
+No runtime dependencies. Uses Web Crypto, so it works in Node 20+, Bun, Deno, Next.js route handlers, Hono, and edge runtimes.
+
+## Analytics (`@mybase-dev/sdk/analytics`)
+
+Page views, custom events, and errors, shown on the project's Analytics page. Turn analytics on for the project (dashboard, or `mybase analytics enable <project>`) to get its public write key, then:
+
+```ts
+import { createAnalytics } from "@mybase-dev/sdk/analytics";
+
+const analytics = createAnalytics({
+  apiUrl: "https://mybase.example.com",
+  project: "shop",
+  key: "mba_…", // public: fine in browser code, it can only add events
+});
+
+analytics.track("signup", { plan: "pro" });
+analytics.captureError(err);
+```
+
+In a browser it records page views (including History API route changes) and uncaught errors on its own, batches events, and sends them with `sendBeacon` when the page is hidden. On a server, call `await analytics.flush()` before exiting. No cookies; visitors are counted with a daily-rotating hash and IPs are never stored.
+
+Plain HTML sites can use the script tag mybase serves instead:
+
+```html
+<script defer src="https://mybase.example.com/analytics.js" data-project="shop" data-key="mba_…"></script>
+<script>mybase.track("signup", { plan: "pro" })</script>
+```
+
+Full guide: [docs/analytics.md](docs/analytics.md). Wire format and admin routes: [docs/analytics-api.md](docs/analytics-api.md).
+
+## Cache (`@mybase-dev/sdk/cache`)
+
+A Redis-compatible cache per project. Turn it on (dashboard, or `mybase cache enable <project>`) to get its password. On the LAN, use any Redis client with `keyPrefix: "<project>:"`. From anywhere else, over HTTP with an API key (`cache:write`):
+
+```ts
+import { createCache } from "@mybase-dev/sdk/cache";
+
+const cache = createCache({ apiUrl: "https://mybase.example.com", project: "shop", apiKey: process.env.MYBASE_API_KEY! });
+await cache.set("session:abc", userId, { ex: 3600 }); // key: shop:session:abc
+```
+
+Full guide: [docs/cache.md](docs/cache.md).
+
+## Rate limits (`@mybase-dev/sdk/ratelimit`)
+
+Limits shared by every instance of your app. Turn them on (dashboard, or `mybase ratelimit enable <project>`), create an API key with `ratelimit:write`, define rules on the dashboard or in `mybase.config.ts`, then:
+
+```ts
+import { createRateLimiter, rateLimitHeaders } from "@mybase-dev/sdk/ratelimit";
+
+const limiter = createRateLimiter({ apiUrl: "https://mybase.example.com", project: "shop", apiKey: process.env.MYBASE_API_KEY! });
+const result = await limiter.limit("login", ip); // or limiter.limit({ limit: 10, window: "1m" }, ip)
+if (!result.success) return new Response("Too many requests", { status: 429, headers: rateLimitHeaders(result) });
+```
+
+If mybase can't be reached, it allows the request (pass `failClosed: true` to deny instead). Full guide: [docs/rate-limits.md](docs/rate-limits.md).
+
+## Queues (`@mybase-dev/sdk/queue`)
+
+SQS-style standard and FIFO queues. Turn them on (dashboard, or `mybase queue enable <project>`), create an API key with `queue:write`, then:
+
+```ts
+import { createQueueClient } from "@mybase-dev/sdk/queue";
+
+const queue = createQueueClient({ apiUrl: "https://mybase.example.com", project: "shop", apiKey: process.env.MYBASE_API_KEY! });
+await queue.send("emails", { to: "ada@example.com" });
+queue.consume("emails", async (message) => sendEmail(message.json()));
+```
+
+Delivery is at least once; failed messages are retried and can go to a dead-letter queue. Full guide: [docs/queues.md](docs/queues.md).
+
+## Cron (`@mybase-dev/sdk/cron`)
+
+A mybase cron job POSTs to a URL in your app on a schedule. Each call is signed with your project's cron secret. You can find it on the project's Cron page, or get it with `mybase cron secret <project>`. Set it as `MYBASE_CRON_SECRET`, then use the handler, which checks the signature and runs the job by name:
+
+```ts
+// app/api/cron/route.ts (Next.js); any framework that takes (Request) => Response works the same
+import { cronHandler } from "@mybase-dev/sdk/cron";
+
+export const POST = cronHandler({
+  secret: process.env.MYBASE_CRON_SECRET!,
+  jobs: {
+    cleanup: async (run) => {
+      // run.payload: the job's JSON payload
+      // run.runId:   same across retries, so you can dedupe
+      // run.attempt: 1, then 2, 3, … on retries
+    },
+  },
+});
+```
+
+Responses: `200` when the job finishes, `401` for a bad or stale signature, `404` for a job with no handler, `500` if the job throws. mybase retries timeouts, `429`, and `5xx` (2 retries by default). It doesn't retry other `4xx` responses.
+
+**Rotating the secret:** pass both secrets, new first, while you deploy: `secret: [process.env.MYBASE_CRON_SECRET!, process.env.MYBASE_CRON_SECRET_OLD!]`.
+
+### Lower level
+
+```ts
+import { verifyCronRequest, verifyCronSignature, CronVerificationError } from "@mybase-dev/sdk/cron";
+
+// Fetch API Request: verifies, then returns the parsed CronRun. Throws CronVerificationError.
+const run = await verifyCronRequest(request, process.env.MYBASE_CRON_SECRET!);
+
+// Raw body + header (e.g. Express with express.text({ type: "application/json" })):
+await verifyCronSignature({ body: req.body, signature: req.get("X-Mybase-Signature"), secret });
+```
+
+### Define jobs in code
+
+Declare jobs next to your app and push them with the mybase CLI. Keep this file free of app code: the CLI imports only this file.
+
+```ts
+// mybase.config.ts
+import { defineConfig } from "@mybase-dev/sdk/config";
+
+export default defineConfig({
+  project: "shop",
+  cron: {
+    baseUrl: "https://shop.example.com", // must be reachable from the mybase server
+    jobs: {
+      cleanup: { schedule: "0 3 * * *" }, // POSTs to baseUrl + /api/cron
+      digest: { schedule: "0 8 * * 1", timezone: "America/Chicago", path: "/api/cron", payload: { kind: "weekly" } },
+    },
+  },
+});
+```
+
+```sh
+mybase cron sync --dry-run   # show what would change
+mybase cron sync             # create, update, and delete code-defined jobs to match
+```
+
+Jobs created in the dashboard are never touched by a sync. For typed job names in the handler, pass the config type: `cronHandler<typeof config>({ ... })`.
+
+Job options: `schedule` (5-field cron, minute precision), `path` (default `/api/cron`), `timezone` (IANA, default `UTC`), `payload` (JSON, up to 16 KB), `retries` (0–5, default 2), `timeoutMs` (1000–120000, default 30000).
+
+### One-off tasks
+
+Schedule a single call to a handler from your app code, e.g. a reminder a day after an order. The task calls the same `cronHandler` as cron jobs: `run.job` is the name you pass, `run.trigger` is `"task"`, and `run.runId` is the task id.
+
+```ts
+import { createCronClient } from "@mybase-dev/sdk/cron";
+
+const cron = createCronClient({
+  apiUrl: process.env.MYBASE_URL!,           // the mybase API, as reachable from your app
+  project: "shop",
+  apiKey: process.env.MYBASE_API_KEY!,       // a mybase API key with cron:write; server-side only
+  baseUrl: "https://shop.example.com",       // your app, as reachable from mybase
+});
+
+const task = await cron.schedule("send-reminder", {
+  in: "24h",                       // or at: new Date("2026-12-01T09:00:00Z"); neither = as soon as possible
+  payload: { orderId: 42 },
+  key: "reminder-42",              // optional dedupe key, see below
+});
+
+await cron.get(task.id);           // CronTask, or null
+await cron.cancelByKey("reminder-42"); // or cron.cancel(task.id); only pending tasks
+```
+
+```ts
+// the handler, next to your cron jobs
+export const POST = cronHandler({
+  secret: process.env.MYBASE_CRON_SECRET!,
+  jobs: {
+    "send-reminder": async (run) => {
+      // run.payload: { orderId: 42 }, run.key: "reminder-42"
+    },
+  },
+});
+```
+
+- **Delays:** milliseconds, or `"30s"`, `"15m"`, `"2h"`, `"7d"`. Up to a year out. Measured by the mybase server's clock.
+- **Keys:** while a task with a key is pending or running, scheduling the same key returns that task instead of a new one. After it finishes, the key is free again.
+- **Durable:** tasks live in Postgres. One that comes due while mybase is down runs when it's back; one interrupted mid-call runs again. Calls are at least once, so dedupe on `run.runId` if it matters.
+- **Retries and timeouts** work like jobs: `retries` (0–5, default 2), `timeoutMs` (1000–120000, default 30000). `path` (default `/api/cron`) is appended to `baseUrl`; `url` overrides both.
+- Finished and cancelled tasks are kept for 7 days. A project can have 10,000 pending tasks.
+- Errors from the API throw `MybaseApiError` (with `status`); `get`/`cancel` resolve to `null` for an unknown task.
+
+The client sends an API key with `cron:write` (not an admin one) as `Authorization: Bearer`.
+
+### Signature format
+
+For verifying in other languages:
+
+```
+X-Mybase-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
+```
+
+Reject the call if `t` is more than 5 minutes from now, then compare `v1` in constant time. The body is JSON:
+
+```json
+{ "job": "cleanup", "runId": "…", "attempt": 1, "trigger": "schedule", "scheduledAt": "…", "firedAt": "…", "payload": null }
+```
+
+`X-Mybase-Job` and `X-Mybase-Run` headers carry the job name and run id too. Task calls add `"key"`, and `trigger` is `"task"`.
+
+Requests from your app to the mybase API (`createCronClient`) carry an API key as `Authorization: Bearer`. Routes: `POST /cron/<project>/tasks`, `GET|DELETE /cron/<project>/tasks/<id>`, `GET|DELETE /cron/<project>/tasks/by-key/<key>`.

package/dist/analytics-script.d.ts

@@ -0,0 +1,11 @@
+import { type Analytics } from "./analytics";
+declare global {
+    interface Window {
+        mybase?: {
+            analytics?: Analytics;
+            track?: Analytics["track"];
+            pageview?: Analytics["pageview"];
+            captureError?: Analytics["captureError"];
+        };
+    }
+}

package/dist/analytics.d.ts

@@ -0,0 +1,89 @@
+export type AnalyticsEventType = "pageview" | "event" | "error";
+/** Custom properties: flat, small, JSON-safe values. */
+export type AnalyticsProps = Record<string, string | number | boolean | null>;
+/** One event on the wire. */
+export interface AnalyticsEvent {
+    type: AnalyticsEventType;
+    /** Custom events: the event name. Errors: the message. Unused for page views. */
+    name?: string;
+    /** The route, e.g. `/pricing`. Query string stripped unless the client keeps it. */
+    path?: string;
+    /** Page views: the page that linked here. mybase keeps only its host. */
+    referrer?: string;
+    props?: AnalyticsProps;
+    /** Errors: the stack trace. */
+    stack?: string;
+    /** The browser's IANA time zone, used to guess the country when the request doesn't say. */
+    tz?: string;
+    /** When it happened (ISO). Defaults to when mybase received it. */
+    ts?: string;
+}
+/** The body of `POST /analytics/<project>/events`. */
+export interface AnalyticsIngestRequest {
+    key: string;
+    events: AnalyticsEvent[];
+}
+/** What the ingest route accepts. Bigger values are rejected (strings are not truncated for you, except by this client). */
+export declare const ANALYTICS_LIMITS: {
+    /** Events per request. */
+    readonly batch: 50;
+    /** Request body, in bytes. */
+    readonly bodyBytes: number;
+    readonly props: 20;
+    readonly propKey: 64;
+    readonly propValue: 256;
+    readonly path: 512;
+    readonly referrer: 512;
+    /** Error messages. */
+    readonly message: 512;
+    readonly stack: 4096;
+};
+/** Custom event names: letters, digits, space, and `_ . : -`, 1–64 chars. */
+export declare const ANALYTICS_EVENT_NAME_PATTERN: RegExp;
+export interface AnalyticsOptions {
+    /** Where the mybase API is reachable from the browser (or server), e.g. `https://mybase.example.com`. */
+    apiUrl: string;
+    project: string;
+    /** The project's public write key (`mba_…`), from the Analytics page. */
+    key: string;
+    /** Browser: record a page view on load and on every client-side route change. Default true. */
+    autoPageviews?: boolean;
+    /** Browser: record uncaught errors and unhandled promise rejections. Default true. */
+    captureErrors?: boolean;
+    /** Keep the query string in paths. Default false (`/search?q=x` is recorded as `/search`). */
+    keepQuery?: boolean;
+    /** Send nothing when the browser's Do Not Track setting is on. Default false. */
+    respectDoNotTrack?: boolean;
+    /** How long to collect events before sending, in ms. Default 5000. */
+    flushIntervalMs?: number;
+    /** Send right away once this many events are queued. Default 20. */
+    batchSize?: number;
+    /** Called when a send fails. Analytics never throws into your app; failed events are dropped. */
+    onError?: (err: unknown) => void;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export interface Analytics {
+    /** Records a page view. `path` defaults to the current location (browser). */
+    pageview(path?: string, props?: AnalyticsProps): void;
+    /** Records a custom event, e.g. `track("signup", { plan: "pro" })`. */
+    track(name: string, props?: AnalyticsProps): void;
+    /** Records an error (an `Error`, or anything else, which is stringified). */
+    captureError(error: unknown, props?: AnalyticsProps): void;
+    /** Sends everything queued now. Call it before a server process exits. */
+    flush(): Promise<void>;
+    /** Sends what's queued and removes every listener this client added. */
+    stop(): void;
+}
+/** `/a/b?x=1#h` → `/a/b` (or `/a/b?x=1` with `keepQuery`). Full URLs are reduced to their path. */
+export declare function normalizePath(input: string, keepQuery?: boolean): string;
+/** `"TypeError: x is undefined"` and its stack, from anything thrown. */
+export declare function describeError(error: unknown): {
+    message: string;
+    stack?: string;
+};
+/**
+ *   const analytics = createAnalytics({ apiUrl: "https://mybase.example.com", project: "shop", key: "mba_…" });
+ *   analytics.track("signup", { plan: "pro" });
+ */
+export declare function createAnalytics(options: AnalyticsOptions): Analytics;

package/dist/analytics.js

@@ -0,0 +1,224 @@
+// src/analytics.ts
+var ANALYTICS_LIMITS = {
+  batch: 50,
+  bodyBytes: 64 * 1024,
+  props: 20,
+  propKey: 64,
+  propValue: 256,
+  path: 512,
+  referrer: 512,
+  message: 512,
+  stack: 4096
+};
+var ANALYTICS_EVENT_NAME_PATTERN = /^[A-Za-z0-9_.:\- ]{1,64}$/;
+function normalizePath(input, keepQuery = false) {
+  let path = input.trim();
+  const scheme = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*/i.exec(path);
+  if (scheme)
+    path = path.slice(scheme[0].length);
+  path = path.split("#", 1)[0];
+  if (!keepQuery)
+    path = path.split("?", 1)[0];
+  if (!path.startsWith("/"))
+    path = `/${path}`;
+  return path.slice(0, ANALYTICS_LIMITS.path);
+}
+function cleanProps(props) {
+  if (!props)
+    return;
+  const out = {};
+  let n = 0;
+  for (const [k, v] of Object.entries(props)) {
+    if (n >= ANALYTICS_LIMITS.props || !k || k.length > ANALYTICS_LIMITS.propKey)
+      continue;
+    if (typeof v === "string")
+      out[k] = v.slice(0, ANALYTICS_LIMITS.propValue);
+    else if (v === null || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v))
+      out[k] = v;
+    else
+      continue;
+    n++;
+  }
+  return n > 0 ? out : undefined;
+}
+function describeError(error) {
+  if (error instanceof Error) {
+    const message = error.message ? `${error.name}: ${error.message}` : error.name;
+    return { message: message.slice(0, ANALYTICS_LIMITS.message), stack: error.stack?.slice(0, ANALYTICS_LIMITS.stack) };
+  }
+  let message;
+  try {
+    message = typeof error === "string" ? error : JSON.stringify(error) ?? String(error);
+  } catch {
+    message = String(error);
+  }
+  return { message: (message || "Unknown error").slice(0, ANALYTICS_LIMITS.message) };
+}
+var NAVIGATE_EVENT = "mybase:navigate";
+var historyPatched = false;
+function patchHistory() {
+  if (historyPatched || typeof history === "undefined")
+    return;
+  historyPatched = true;
+  for (const method of ["pushState", "replaceState"]) {
+    const original = history[method];
+    history[method] = function(...args) {
+      const result = original.apply(this, args);
+      window.dispatchEvent(new Event(NAVIGATE_EVENT));
+      return result;
+    };
+  }
+}
+var MAX_ERRORS_PER_PAGE = 20;
+function createAnalytics(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const url = `${options.apiUrl.replace(/\/+$/, "")}/analytics/${encodeURIComponent(options.project)}/events`;
+  const browser = typeof window !== "undefined" && typeof document !== "undefined";
+  const keepQuery = options.keepQuery ?? false;
+  const interval = options.flushIntervalMs ?? 5000;
+  const batchSize = Math.min(options.batchSize ?? 20, ANALYTICS_LIMITS.batch);
+  const tz = (() => {
+    try {
+      return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+    } catch {
+      return;
+    }
+  })();
+  const dnt = browser && options.respectDoNotTrack && (navigator.doNotTrack === "1" || window.doNotTrack === "1");
+  const queue = [];
+  let timer = null;
+  let stopped = false;
+  const cleanups = [];
+  const reportFailure = (err) => options.onError?.(err);
+  function send(events, beacon) {
+    const body = JSON.stringify({ key: options.key, events });
+    if (beacon && browser && typeof navigator.sendBeacon === "function") {
+      if (navigator.sendBeacon(url, new Blob([body], { type: "text/plain" })))
+        return Promise.resolve();
+    }
+    return doFetch(url, { method: "POST", body, headers: { "Content-Type": "text/plain" }, keepalive: browser, credentials: "omit" }).then(async (res) => {
+      if (!res.ok) {
+        const data = await res.json().catch(() => ({}));
+        reportFailure(new Error(data.error ?? `mybase analytics answered ${res.status}`));
+      }
+    }, reportFailure);
+  }
+  function flushQueued(beacon) {
+    if (timer)
+      clearTimeout(timer);
+    timer = null;
+    const sends = [];
+    while (queue.length > 0)
+      sends.push(send(queue.splice(0, batchSize), beacon));
+    return Promise.all(sends).then(() => {
+      return;
+    });
+  }
+  function enqueue(event) {
+    if (stopped || dnt)
+      return;
+    queue.push({ ...event, tz: event.tz ?? tz, ts: event.ts ?? new Date().toISOString() });
+    if (queue.length >= batchSize)
+      flushQueued(false);
+    else if (!timer)
+      timer = setTimeout(() => void flushQueued(false), interval);
+  }
+  let lastPath = null;
+  let firstView = true;
+  function pageview(path, props) {
+    const raw = path ?? (browser ? location.pathname + location.search : undefined);
+    if (raw === undefined)
+      return;
+    const normalized = normalizePath(raw, keepQuery);
+    const event = { type: "pageview", path: normalized, props: cleanProps(props) };
+    if (firstView && browser && document.referrer) {
+      try {
+        if (new URL(document.referrer).host !== location.host)
+          event.referrer = document.referrer.slice(0, ANALYTICS_LIMITS.referrer);
+      } catch {}
+    }
+    firstView = false;
+    lastPath = normalized;
+    enqueue(event);
+  }
+  if (browser && (options.autoPageviews ?? true)) {
+    const onRoute = () => {
+      const path = normalizePath(location.pathname + location.search, keepQuery);
+      if (path !== lastPath)
+        pageview();
+    };
+    patchHistory();
+    window.addEventListener(NAVIGATE_EVENT, onRoute);
+    window.addEventListener("popstate", onRoute);
+    cleanups.push(() => {
+      window.removeEventListener(NAVIGATE_EVENT, onRoute);
+      window.removeEventListener("popstate", onRoute);
+    });
+    pageview();
+  }
+  const seenErrors = new Set;
+  function captureError(error, props) {
+    const { message, stack } = describeError(error);
+    const id = `${message}
+${stack?.split(`
+`, 2)[1] ?? ""}`;
+    if (seenErrors.has(id) || seenErrors.size >= MAX_ERRORS_PER_PAGE)
+      return;
+    seenErrors.add(id);
+    enqueue({
+      type: "error",
+      name: message,
+      stack,
+      path: browser ? normalizePath(location.pathname + location.search, keepQuery) : undefined,
+      props: cleanProps(props)
+    });
+  }
+  if (browser && (options.captureErrors ?? true)) {
+    const onError = (e) => captureError(e.error ?? e.message);
+    const onRejection = (e) => captureError(e.reason);
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onRejection);
+    cleanups.push(() => {
+      window.removeEventListener("error", onError);
+      window.removeEventListener("unhandledrejection", onRejection);
+    });
+  }
+  if (browser) {
+    const onHide = () => {
+      if (document.visibilityState === "hidden")
+        flushQueued(true);
+    };
+    const onPageHide = () => void flushQueued(true);
+    document.addEventListener("visibilitychange", onHide);
+    window.addEventListener("pagehide", onPageHide);
+    cleanups.push(() => {
+      document.removeEventListener("visibilitychange", onHide);
+      window.removeEventListener("pagehide", onPageHide);
+    });
+  }
+  return {
+    pageview,
+    track(name, props) {
+      if (typeof name !== "string" || !ANALYTICS_EVENT_NAME_PATTERN.test(name)) {
+        reportFailure(new TypeError(`invalid event name "${String(name)}": use 1–64 letters, digits, spaces, or _ . : -`));
+        return;
+      }
+      enqueue({ type: "event", name, path: browser ? normalizePath(location.pathname + location.search, keepQuery) : undefined, props: cleanProps(props) });
+    },
+    captureError,
+    flush: () => flushQueued(false),
+    stop() {
+      flushQueued(false);
+      stopped = true;
+      for (const cleanup of cleanups.splice(0))
+        cleanup();
+    }
+  };
+}
+export {
+  ANALYTICS_EVENT_NAME_PATTERN,
+  ANALYTICS_LIMITS,
+  createAnalytics,
+  describeError,
+  normalizePath
+};

package/dist/analytics.min.js

@@ -0,0 +1,3 @@
+(()=>{var p={batch:50,bodyBytes:65536,props:20,propKey:64,propValue:256,path:512,referrer:512,message:512,stack:4096},D=/^[A-Za-z0-9_.:\- ]{1,64}$/;function g(e,i=!1){let n=e.trim(),r=/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*/i.exec(n);if(r)n=n.slice(r[0].length);if(n=n.split("#",1)[0],!i)n=n.split("?",1)[0];if(!n.startsWith("/"))n=`/${n}`;return n.slice(0,p.path)}function b(e){if(!e)return;let i={},n=0;for(let[r,a]of Object.entries(e)){if(n>=p.props||!r||r.length>p.propKey)continue;if(typeof a==="string")i[r]=a.slice(0,p.propValue);else if(a===null||typeof a==="boolean"||typeof a==="number"&&Number.isFinite(a))i[r]=a;else continue;n++}return n>0?i:void 0}function M(e){if(e instanceof Error)return{message:(e.message?`${e.name}: ${e.message}`:e.name).slice(0,p.message),stack:e.stack?.slice(0,p.stack)};let i;try{i=typeof e==="string"?e:JSON.stringify(e)??String(e)}catch{i=String(e)}return{message:(i||"Unknown error").slice(0,p.message)}}var P="mybase:navigate",R=!1;function Q(){if(R||typeof history>"u")return;R=!0;for(let e of["pushState","replaceState"]){let i=history[e];history[e]=function(...n){let r=i.apply(this,n);return window.dispatchEvent(new Event(P)),r}}}var U=20;function x(e){let i=e.fetch??globalThis.fetch,n=`${e.apiUrl.replace(/\/+$/,"")}/analytics/${encodeURIComponent(e.project)}/events`,r=typeof window<"u"&&typeof document<"u",a=e.keepQuery??!1,j=e.flushIntervalMs??5000,T=Math.min(e.batchSize??20,p.batch),I=(()=>{try{return Intl.DateTimeFormat().resolvedOptions().timeZone||void 0}catch{return}})(),_=r&&e.respectDoNotTrack&&(navigator.doNotTrack==="1"||window.doNotTrack==="1"),y=[],f=null,S=!1,h=[],m=(t)=>e.onError?.(t);function O(t,s){let o=JSON.stringify({key:e.key,events:t});if(s&&r&&typeof navigator.sendBeacon==="function"){if(navigator.sendBeacon(n,new Blob([o],{type:"text/plain"})))return Promise.resolve()}return i(n,{method:"POST",body:o,headers:{"Content-Type":"text/plain"},keepalive:r,credentials:"omit"}).then(async(l)=>{if(!l.ok){let u=await l.json().catch(()=>({}));m(Error(u.error??`mybase analytics answered ${l.status}`))}},m)}function d(t){if(f)clearTimeout(f);f=null;let s=[];while(y.length>0)s.push(O(y.splice(0,T),t));return Promise.all(s).then(()=>{return})}function w(t){if(S||_)return;if(y.push({...t,tz:t.tz??I,ts:t.ts??new Date().toISOString()}),y.length>=T)d(!1);else if(!f)f=setTimeout(()=>void d(!1),j)}let L=null,N=!0;function E(t,s){let o=t??(r?location.pathname+location.search:void 0);if(o===void 0)return;let l=g(o,a),u={type:"pageview",path:l,props:b(s)};if(N&&r&&document.referrer)try{if(new URL(document.referrer).host!==location.host)u.referrer=document.referrer.slice(0,p.referrer)}catch{}N=!1,L=l,w(u)}if(r&&(e.autoPageviews??!0)){let t=()=>{if(g(location.pathname+location.search,a)!==L)E()};Q(),window.addEventListener(P,t),window.addEventListener("popstate",t),h.push(()=>{window.removeEventListener(P,t),window.removeEventListener("popstate",t)}),E()}let k=new Set;function A(t,s){let{message:o,stack:l}=M(t),u=`${o}
+${l?.split(`
+`,2)[1]??""}`;if(k.has(u)||k.size>=U)return;k.add(u),w({type:"error",name:o,stack:l,path:r?g(location.pathname+location.search,a):void 0,props:b(s)})}if(r&&(e.captureErrors??!0)){let t=(o)=>A(o.error??o.message),s=(o)=>A(o.reason);window.addEventListener("error",t),window.addEventListener("unhandledrejection",s),h.push(()=>{window.removeEventListener("error",t),window.removeEventListener("unhandledrejection",s)})}if(r){let t=()=>{if(document.visibilityState==="hidden")d(!0)},s=()=>void d(!0);document.addEventListener("visibilitychange",t),window.addEventListener("pagehide",s),h.push(()=>{document.removeEventListener("visibilitychange",t),window.removeEventListener("pagehide",s)})}return{pageview:E,track(t,s){if(typeof t!=="string"||!D.test(t)){m(TypeError(`invalid event name "${String(t)}": use 1–64 letters, digits, spaces, or _ . : -`));return}w({type:"event",name:t,path:r?g(location.pathname+location.search,a):void 0,props:b(s)})},captureError:A,flush:()=>d(!1),stop(){d(!1),S=!0;for(let t of h.splice(0))t()}}}var z=document.currentScript,c=z?.dataset??{},v=(e)=>e==="false"||e==="0";if(!c.project||!c.key)console.warn("mybase analytics: add data-project and data-key to the script tag");else if(!window.mybase?.analytics){let e=x({apiUrl:c.api||new URL(z.src,location.href).origin,project:c.project,key:c.key,autoPageviews:!v(c.pageviews),captureErrors:!v(c.errors),keepQuery:c.keepQuery!==void 0&&!v(c.keepQuery),respectDoNotTrack:c.respectDnt!==void 0&&!v(c.respectDnt)});window.mybase={...window.mybase,analytics:e,track:e.track,pageview:e.pageview,captureError:e.captureError}}})();

package/dist/cache.d.ts

@@ -0,0 +1,91 @@
+import { MybaseApiError } from "./cron";
+export { MybaseApiError };
+export type CacheArg = string | number;
+/** One reply per command: Valkey errors don't fail the whole pipeline. */
+export type PipelineResult = {
+    result: unknown;
+} | {
+    error: string;
+};
+export interface CacheOptions {
+    /** 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 `cache:write` for this project. Server-side only. */
+    apiKey: string;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export interface SetOptions {
+    /** Expire after this many seconds. */
+    ex?: number;
+    /** Expire after this many milliseconds. */
+    px?: number;
+    /** Only set if the key doesn't exist. */
+    nx?: boolean;
+    /** Only set if the key exists. */
+    xx?: boolean;
+}
+/** Builds a batch of commands sent in one request. Keys get the project prefix. */
+export interface CachePipeline {
+    command(args: CacheArg[]): CachePipeline;
+    get(key: string): CachePipeline;
+    set(key: string, value: CacheArg, options?: SetOptions): CachePipeline;
+    del(...keys: string[]): CachePipeline;
+    incr(key: string, by?: number): CachePipeline;
+    expire(key: string, seconds: number): CachePipeline;
+    /** Sends the batch. `atomic: true` wraps it in MULTI/EXEC. */
+    exec(options?: {
+        atomic?: boolean;
+    }): Promise<PipelineResult[]>;
+}
+export interface Cache {
+    /** `key` with the project prefix, for raw commands. */
+    key(key: string): string;
+    /** A raw command, e.g. `["ZADD", cache.key("board"), 10, "ana"]`. Keys aren't prefixed. */
+    command<T = unknown>(args: CacheArg[]): Promise<T>;
+    get(key: string): Promise<string | null>;
+    /** JSON.parse of `get`, or null. */
+    getJson<T = unknown>(key: string): Promise<T | null>;
+    /** `true` when set, `false` when `nx`/`xx` stopped it. */
+    set(key: string, value: CacheArg, options?: SetOptions): Promise<boolean>;
+    setJson(key: string, value: unknown, options?: SetOptions): Promise<boolean>;
+    /** How many keys were deleted. */
+    del(...keys: string[]): Promise<number>;
+    exists(...keys: string[]): Promise<number>;
+    incr(key: string, by?: number): Promise<number>;
+    expire(key: string, seconds: number): Promise<boolean>;
+    /** Seconds left; -1 with no expiry, -2 when the key doesn't exist. */
+    ttl(key: string): Promise<number>;
+    mget(...keys: string[]): Promise<(string | null)[]>;
+    hget(key: string, field: string): Promise<string | null>;
+    hset(key: string, fields: Record<string, CacheArg>): Promise<number>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hdel(key: string, ...fields: string[]): Promise<number>;
+    lpush(key: string, ...values: CacheArg[]): Promise<number>;
+    rpush(key: string, ...values: CacheArg[]): Promise<number>;
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    sadd(key: string, ...members: CacheArg[]): Promise<number>;
+    srem(key: string, ...members: CacheArg[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    sismember(key: string, member: CacheArg): Promise<boolean>;
+    zadd(key: string, ...entries: {
+        score: number;
+        member: string;
+    }[]): Promise<number>;
+    /** Members by rank, lowest score first. `withScores` adds the scores. */
+    zrange(key: string, start: number, stop: number, options?: {
+        withScores?: boolean;
+        rev?: boolean;
+    }): Promise<string[]>;
+    zincrby(key: string, by: number, member: string): Promise<number>;
+    publish(channel: string, message: string): Promise<number>;
+    pipeline(): CachePipeline;
+}
+/**
+ * A cache client over HTTP. Each call is one request; batch with `pipeline()`.
+ *
+ *   const cache = createCache({ apiUrl, project: "shop", apiKey: process.env.MYBASE_API_KEY! });
+ *   await cache.set("session:abc", userId, { ex: 3600 });   // key is shop:session:abc
+ */
+export declare function createCache(options: CacheOptions): Cache;