@mybase-dev/sdk 1.0.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "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.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LandonHarter/mybase.git",
+    "directory": "packages/sdk"
+  },
+  "exports": {
+    "./analytics": {
+      "bun": "./src/analytics.ts",
+      "types": "./dist/analytics.d.ts",
+      "default": "./dist/analytics.js"
+    },
+    "./cron": {
+      "bun": "./src/cron.ts",
+      "types": "./dist/cron.d.ts",
+      "default": "./dist/cron.js"
+    },
+    "./config": {
+      "bun": "./src/config.ts",
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./cache": {
+      "bun": "./src/cache.ts",
+      "types": "./dist/cache.d.ts",
+      "default": "./dist/cache.js"
+    },
+    "./ratelimit": {
+      "bun": "./src/ratelimit.ts",
+      "types": "./dist/ratelimit.d.ts",
+      "default": "./dist/ratelimit.js"
+    },
+    "./queue": {
+      "bun": "./src/queue.ts",
+      "types": "./dist/queue.d.ts",
+      "default": "./dist/queue.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/analytics.ts",
+    "src/cron.ts",
+    "src/config.ts",
+    "src/cache.ts",
+    "src/ratelimit.ts",
+    "src/queue.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",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/LandonHarter/mybase#readme"
+}

package/src/analytics.ts

@@ -0,0 +1,311 @@
+// Page views, custom events, and errors, sent to a mybase project's analytics service.
+//
+// In a browser, `createAnalytics` records page views (including client-side route changes)
+// and uncaught errors on its own, batches everything, and sends it with `sendBeacon` when
+// the page is hidden. On a server it only sends what you `track` or `captureError`.
+//
+// The write key is public: it's meant to ship in browser code. It can only add events.
+// No cookies or local storage are used; mybase counts visitors with a daily-rotating hash.
+
+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 const ANALYTICS_LIMITS = {
+  /** Events per request. */
+  batch: 50,
+  /** Request body, in bytes. */
+  bodyBytes: 64 * 1024,
+  props: 20,
+  propKey: 64,
+  propValue: 256,
+  path: 512,
+  referrer: 512,
+  /** Error messages. */
+  message: 512,
+  stack: 4096,
+} as const;
+
+/** Custom event names: letters, digits, space, and `_ . : -`, 1–64 chars. */
+export const ANALYTICS_EVENT_NAME_PATTERN = /^[A-Za-z0-9_.:\- ]{1,64}$/;
+
+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 function normalizePath(input: string, keepQuery = false): string {
+  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);
+}
+
+/** Drops props that would be rejected, rather than losing the whole event. */
+function cleanProps(props: AnalyticsProps | undefined): AnalyticsProps | undefined {
+  if (!props) return undefined;
+  const out: AnalyticsProps = {};
+  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;
+}
+
+/** `"TypeError: x is undefined"` and its stack, from anything thrown. */
+export function describeError(error: unknown): { message: string; stack?: string } {
+  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: string;
+  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) };
+}
+
+// One patch of history.pushState/replaceState per page, shared by every client.
+const NAVIGATE_EVENT = "mybase:navigate";
+let historyPatched = false;
+function patchHistory() {
+  if (historyPatched || typeof history === "undefined") return;
+  historyPatched = true;
+  for (const method of ["pushState", "replaceState"] as const) {
+    const original = history[method];
+    history[method] = function (this: History, ...args: Parameters<History["pushState"]>) {
+      const result = original.apply(this, args);
+      window.dispatchEvent(new Event(NAVIGATE_EVENT));
+      return result;
+    };
+  }
+}
+
+/** Most errors a page reports in one load, so a render loop can't flood the project. */
+const MAX_ERRORS_PER_PAGE = 20;
+
+/**
+ *   const analytics = createAnalytics({ apiUrl: "https://mybase.example.com", project: "shop", key: "mba_…" });
+ *   analytics.track("signup", { plan: "pro" });
+ */
+export function createAnalytics(options: AnalyticsOptions): Analytics {
+  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 undefined;
+    }
+  })();
+  const dnt = browser && options.respectDoNotTrack && (navigator.doNotTrack === "1" || (window as { doNotTrack?: string }).doNotTrack === "1");
+
+  const queue: AnalyticsEvent[] = [];
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = false;
+  const cleanups: (() => void)[] = [];
+  const reportFailure = (err: unknown) => options.onError?.(err);
+
+  function send(events: AnalyticsEvent[], beacon: boolean): Promise<void> {
+    const body = JSON.stringify({ key: options.key, events } satisfies AnalyticsIngestRequest);
+    // text/plain keeps it a "simple" request: no CORS preflight, and sendBeacon accepts it.
+    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(() => ({}))) as { error?: string };
+          reportFailure(new Error(data.error ?? `mybase analytics answered ${res.status}`));
+        }
+      },
+      reportFailure,
+    );
+  }
+
+  function flushQueued(beacon: boolean): Promise<void> {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    const sends: Promise<void>[] = [];
+    while (queue.length > 0) sends.push(send(queue.splice(0, batchSize), beacon));
+    return Promise.all(sends).then(() => undefined);
+  }
+
+  function enqueue(event: AnalyticsEvent) {
+    if (stopped || dnt) return;
+    queue.push({ ...event, tz: event.tz ?? tz, ts: event.ts ?? new Date().toISOString() });
+    if (queue.length >= batchSize) void flushQueued(false);
+    else if (!timer) timer = setTimeout(() => void flushQueued(false), interval);
+  }
+
+  // Page views ------------------------------------------------------------------
+  let lastPath: string | null = null;
+  let firstView = true;
+
+  function pageview(path?: string, props?: AnalyticsProps) {
+    const raw = path ?? (browser ? location.pathname + location.search : undefined);
+    if (raw === undefined) return;
+    const normalized = normalizePath(raw, keepQuery);
+    const event: AnalyticsEvent = { type: "pageview", path: normalized, props: cleanProps(props) };
+    // The referrer only means something for the page the visitor landed on.
+    if (firstView && browser && document.referrer) {
+      try {
+        if (new URL(document.referrer).host !== location.host) event.referrer = document.referrer.slice(0, ANALYTICS_LIMITS.referrer);
+      } catch {
+        // not a URL; skip it
+      }
+    }
+    firstView = false;
+    lastPath = normalized;
+    enqueue(event);
+  }
+
+  if (browser && (options.autoPageviews ?? true)) {
+    const onRoute = () => {
+      const path = normalizePath(location.pathname + location.search, keepQuery);
+      // replaceState is often used for scroll or filter state; only a new path counts.
+      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();
+  }
+
+  // Errors ----------------------------------------------------------------------
+  const seenErrors = new Set<string>();
+
+  function captureError(error: unknown, props?: AnalyticsProps) {
+    const { message, stack } = describeError(error);
+    // The same error over and over is one error; count it once per page load.
+    const id = `${message}\n${stack?.split("\n", 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: ErrorEvent) => captureError(e.error ?? e.message);
+    const onRejection = (e: PromiseRejectionEvent) => captureError(e.reason);
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onRejection);
+    cleanups.push(() => {
+      window.removeEventListener("error", onError);
+      window.removeEventListener("unhandledrejection", onRejection);
+    });
+  }
+
+  // Leaving the page: send what's queued while the browser still lets us.
+  if (browser) {
+    const onHide = () => {
+      if (document.visibilityState === "hidden") void 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() {
+      void flushQueued(false);
+      stopped = true;
+      for (const cleanup of cleanups.splice(0)) cleanup();
+    },
+  };
+}

package/src/cache.ts

@@ -0,0 +1,191 @@
+// A small HTTP client for a project's mybase cache (Valkey, Redis-compatible), for apps that
+// can't open a TCP connection to the mybase machine: serverless hosts, or anything behind the
+// Cloudflare Tunnel. On the LAN or Tailscale, any Redis client works directly:
+//
+//   new Redis("redis://shop:<password>@mybase.local:6379", { keyPrefix: "shop:" })   // ioredis
+//
+// Every key a project can touch starts with `<project>:`. The helpers here add that prefix
+// for you; `command()` sends a raw command and doesn't (prefix keys yourself).
+//
+// The wire format matches Upstash's REST API, so `@upstash/redis` also works against
+// `<apiUrl>/cache/<project>` with a mybase API key as its token (without the auto-prefix).
+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;
+}
+
+function setArgs(key: string, value: CacheArg, o: SetOptions = {}): CacheArg[] {
+  const args: CacheArg[] = ["SET", key, value];
+  if (o.ex !== undefined) args.push("EX", o.ex);
+  if (o.px !== undefined) args.push("PX", o.px);
+  if (o.nx) args.push("NX");
+  if (o.xx) args.push("XX");
+  return args;
+}
+
+/**
+ * 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 function createCache(options: CacheOptions): Cache {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const base = `${options.apiUrl.replace(/\/+$/, "")}/cache/${encodeURIComponent(options.project)}`;
+  const prefix = `${options.project}:`;
+  const k = (key: string) => (key.startsWith(prefix) ? key : prefix + key);
+
+  async function post<T>(path: string, body: unknown): Promise<T> {
+    const res = await doFetch(base + path, {
+      method: "POST",
+      body: JSON.stringify(body),
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` },
+    });
+    const data = (await res.json().catch(() => ({}))) as { error?: string };
+    if (!res.ok) throw new MybaseApiError(data.error ?? `mybase API answered ${res.status}`, res.status);
+    return data as T;
+  }
+
+  async function command<T>(args: CacheArg[]): Promise<T> {
+    const data = await post<{ result?: T; error?: string }>("", args);
+    if (data.error !== undefined) throw new MybaseApiError(data.error, 400);
+    return data.result as T;
+  }
+
+  function pipeline(): CachePipeline {
+    const commands: CacheArg[][] = [];
+    const add = (args: CacheArg[]) => {
+      commands.push(args);
+      return p;
+    };
+    const p: CachePipeline = {
+      command: add,
+      get: (key) => add(["GET", k(key)]),
+      set: (key, value, o) => add(setArgs(k(key), value, o)),
+      del: (...keys) => add(["DEL", ...keys.map(k)]),
+      incr: (key, by = 1) => add(by === 1 ? ["INCR", k(key)] : ["INCRBY", k(key), by]),
+      expire: (key, seconds) => add(["EXPIRE", k(key), seconds]),
+      exec: ({ atomic = false } = {}) => (commands.length === 0 ? Promise.resolve([]) : post(atomic ? "/multi-exec" : "/pipeline", commands)),
+    };
+    return p;
+  }
+
+  const pairs = (flat: string[]) => {
+    const out: Record<string, string> = {};
+    for (let i = 0; i + 1 < flat.length; i += 2) out[flat[i]!] = flat[i + 1]!;
+    return out;
+  };
+
+  return {
+    key: k,
+    command,
+    get: (key) => command(["GET", k(key)]),
+    async getJson<T>(key: string) {
+      const raw = await command<string | null>(["GET", k(key)]);
+      return raw === null ? null : (JSON.parse(raw) as T);
+    },
+    set: async (key, value, o) => (await command<string | null>(setArgs(k(key), value, o))) === "OK",
+    setJson: async (key, value, o) => (await command<string | null>(setArgs(k(key), JSON.stringify(value), o))) === "OK",
+    del: (...keys) => command(["DEL", ...keys.map(k)]),
+    exists: (...keys) => command(["EXISTS", ...keys.map(k)]),
+    incr: (key, by = 1) => command(by === 1 ? ["INCR", k(key)] : ["INCRBY", k(key), by]),
+    expire: async (key, seconds) => (await command<number>(["EXPIRE", k(key), seconds])) === 1,
+    ttl: (key) => command(["TTL", k(key)]),
+    mget: (...keys) => command(["MGET", ...keys.map(k)]),
+    hget: (key, field) => command(["HGET", k(key), field]),
+    hset: (key, fields) => command(["HSET", k(key), ...Object.entries(fields).flat()]),
+    hgetall: async (key) => {
+      // Upstash-style replies keep RESP2's flat array; the API may also answer with an object.
+      const raw = await command<string[] | Record<string, string>>(["HGETALL", k(key)]);
+      return Array.isArray(raw) ? pairs(raw) : raw;
+    },
+    hdel: (key, ...fields) => command(["HDEL", k(key), ...fields]),
+    lpush: (key, ...values) => command(["LPUSH", k(key), ...values]),
+    rpush: (key, ...values) => command(["RPUSH", k(key), ...values]),
+    lrange: (key, start, stop) => command(["LRANGE", k(key), start, stop]),
+    sadd: (key, ...members) => command(["SADD", k(key), ...members]),
+    srem: (key, ...members) => command(["SREM", k(key), ...members]),
+    smembers: (key) => command(["SMEMBERS", k(key)]),
+    sismember: async (key, member) => (await command<number>(["SISMEMBER", k(key), member])) === 1,
+    zadd: (key, ...entries) => command(["ZADD", k(key), ...entries.flatMap((e) => [e.score, e.member])]),
+    zrange: (key, start, stop, o = {}) => command(["ZRANGE", k(key), start, stop, ...(o.rev ? ["REV"] : []), ...(o.withScores ? ["WITHSCORES"] : [])]),
+    zincrby: async (key, by, member) => Number(await command<string | number>(["ZINCRBY", k(key), by, member])),
+    publish: (channel, message) => command(["PUBLISH", k(channel), message]),
+    pipeline,
+  };
+}

package/src/config.ts

@@ -0,0 +1,76 @@
+// Cron jobs, rate limit rules, and queues declared in code. `mybase cron sync`, `mybase ratelimit
+// sync`, and `mybase queue sync` import this file (and only this file), so keep app code out of it:
+// handlers live with your routes (see ./cron).
+import type { DeadLetterSettings } from "./queue";
+import type { RateLimitAlgorithm } from "./ratelimit";
+
+/** One job mybase calls on a schedule. */
+export interface CronJobConfig {
+  /** Standard 5-field cron expression (minute precision), e.g. `0 3 * * *`. */
+  schedule: string;
+  /** Appended to `cron.baseUrl`. Default `/api/cron`. */
+  path?: string;
+  /** IANA time zone the schedule runs in. Default `UTC`. */
+  timezone?: string;
+  /** JSON sent to your handler as `run.payload`. */
+  payload?: unknown;
+  /** Extra tries after a failed call (network error, timeout, 429, 5xx). 0–5, default 2. */
+  retries?: number;
+  /** How long to wait for your endpoint, in ms. 1000–120000, default 30000. */
+  timeoutMs?: number;
+}
+
+/** One named rate limit. Apps use it with `limiter.limit("<name>", id)`. */
+export interface RateLimitRuleConfig {
+  /** Default `sliding`. */
+  algorithm?: RateLimitAlgorithm;
+  /** Requests (units) allowed per window. */
+  limit: number;
+  /** Milliseconds, or `"10s"`, `"1m"`, `"1h"`, `"1d"`. 1s–30d. */
+  window: number | string;
+  /** Token bucket only: capacity. Default `limit`. */
+  burst?: number;
+}
+
+/** One queue. Durations are ms or `"30s"`, `"5m"`, `"4d"`. */
+export interface QueueConfig {
+  /** Strict order per message group, deduplicated sends. Can't be changed after creation. Default false. */
+  fifo?: boolean;
+  /** How long a received message stays hidden. 0–12h, default 30s. */
+  visibilityTimeout?: number | string;
+  /** How long new messages wait before they can be received. 0–15m, default 0. */
+  delay?: number | string;
+  /** How long unreceived messages are kept. 1m–14d, default 4d. */
+  retention?: number | string;
+  /** Default long-poll wait for receives. 0–20s, default 0. */
+  receiveWait?: number | string;
+  /** 1024–262144, default 262144. */
+  maxMessageBytes?: number;
+  /** FIFO only: deduplicate by body when a send has no `dedupId`. */
+  contentDedup?: boolean;
+  /** After `maxReceives` failed deliveries, move messages to this queue. */
+  deadLetter?: DeadLetterSettings;
+}
+
+export interface MybaseConfig {
+  /** The mybase project these jobs belong to. */
+  project: string;
+  cron?: {
+    /** Where your app is reachable from the mybase server, e.g. `https://shop.example.com`. */
+    baseUrl: string;
+    jobs: Record<string, CronJobConfig>;
+  };
+  ratelimit?: {
+    rules: Record<string, RateLimitRuleConfig>;
+  };
+  queue?: {
+    queues: Record<string, QueueConfig>;
+  };
+}
+
+/** Identity function that types `mybase.config.ts`. */
+export function defineConfig<const C extends MybaseConfig>(config: C): C {
+  return config;
+}
+
+export const DEFAULT_CRON_PATH = "/api/cron";