@mybase-dev/sdk 1.0.0

package/dist/queue.js

@@ -0,0 +1,358 @@
+// 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/queue.ts
+var QUEUE_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,79}$/;
+var QUEUE_NAME_RULES = "Use 1–80 lowercase letters, digits, `_`, or `-`, starting with a letter or digit.";
+var QUEUE_LIMITS = {
+  batch: 100,
+  batchBytes: 1024 * 1024,
+  maxMessageBytes: { min: 1024, max: 256 * 1024, default: 256 * 1024 },
+  visibilityTimeoutMs: { min: 0, max: 12 * 3600000, default: 30000 },
+  delayMs: { min: 0, max: 15 * 60000, default: 0 },
+  retentionMs: { min: 60000, max: 14 * 86400000, default: 4 * 86400000 },
+  waitMs: { min: 0, max: 20000, default: 0 },
+  maxReceives: { min: 1, max: 1000 },
+  attributes: 10,
+  idLength: 128,
+  dedupWindowMs: 5 * 60000,
+  queuesPerProject: 1000
+};
+var encodeBody = (body) => typeof body === "string" ? body : JSON.stringify(body);
+var ms = (value) => value === undefined ? undefined : parseDelay(value);
+function received(message) {
+  return { ...message, json: () => JSON.parse(message.body) };
+}
+function toEntry(entry, index) {
+  return {
+    id: entry.id ?? String(index),
+    body: encodeBody(entry.body),
+    delayMs: ms(entry.delay),
+    groupId: entry.groupId,
+    dedupId: entry.dedupId,
+    attributes: entry.attributes
+  };
+}
+var sleep = (msToWait, signal) => new Promise((resolve) => {
+  if (signal.aborted || msToWait <= 0)
+    return resolve();
+  const timer = setTimeout(done, msToWait);
+  signal.addEventListener("abort", done, { once: true });
+  function done() {
+    clearTimeout(timer);
+    signal.removeEventListener("abort", done);
+    resolve();
+  }
+});
+function createQueueClient(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const base = `${options.apiUrl.replace(/\/+$/, "")}/queue/${encodeURIComponent(options.project)}/queues`;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const path = (queue, rest = "") => `${base}/${encodeURIComponent(queue)}${rest}`;
+  async function call(method, url, body, signal) {
+    const res = await doFetch(url, {
+      method,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` },
+      signal: 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;
+  }
+  const client = {
+    async send(queue, body, opts = {}) {
+      const result = await client.sendBatch(queue, [{ ...opts, body }]);
+      const failure = result.failed[0];
+      if (failure)
+        throw new MybaseApiError(failure.error, 400);
+      return result.successful[0];
+    },
+    sendBatch: (queue, entries) => call("POST", path(queue, "/messages"), { messages: entries.map(toEntry) }),
+    async receive(queue, opts = {}) {
+      const waitMs = ms(opts.wait);
+      const body = { max: opts.max, waitMs, visibilityTimeoutMs: ms(opts.visibilityTimeout) };
+      const timeout = AbortSignal.timeout((waitMs ?? QUEUE_LIMITS.waitMs.max) + timeoutMs);
+      const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+      const { messages } = await call("POST", path(queue, "/receive"), body, signal);
+      return messages.map(received);
+    },
+    delete: (queue, receipts) => call("POST", path(queue, "/delete"), { receipts: [receipts].flat() }),
+    async changeVisibility(queue, receipt, timeout) {
+      const result = await client.changeVisibilityBatch(queue, [{ receipt, timeout }]);
+      const failure = result.failed[0];
+      if (failure)
+        throw new MybaseApiError(failure.error, 400);
+    },
+    changeVisibilityBatch: (queue, entries) => call("POST", path(queue, "/visibility"), {
+      entries: entries.map((e) => ({ receipt: e.receipt, visibilityTimeoutMs: parseDelay(e.timeout) }))
+    }),
+    consume: (queue, handler, opts) => consume(client, queue, handler, opts),
+    listQueues: () => call("GET", base),
+    getQueue: (queue) => call("GET", path(queue)),
+    createQueue: (queue, settings = {}) => call("POST", base, { ...settings, name: queue }),
+    updateQueue: (queue, settings) => call("PATCH", path(queue), settings),
+    deleteQueue: (queue) => call("DELETE", path(queue)),
+    purge: (queue) => call("POST", path(queue, "/purge")),
+    redrive: (queue, opts = {}) => call("POST", path(queue, "/redrive"), opts)
+  };
+  return client;
+}
+function consume(client, queue, handler, opts = {}) {
+  const batchSize = opts.batchSize ?? 10;
+  const concurrency = Math.max(1, opts.concurrency ?? batchSize);
+  const wait = opts.wait ?? QUEUE_LIMITS.waitMs.max;
+  const retryDelay = ms(opts.retryDelay);
+  const onError = opts.onError ?? ((err) => console.error("[mybase queue]", err));
+  const stopper = new AbortController;
+  const signal = opts.signal ? AbortSignal.any([opts.signal, stopper.signal]) : stopper.signal;
+  async function handle(message) {
+    try {
+      await handler(message);
+      return true;
+    } catch (err) {
+      onError(err, message);
+      if (retryDelay !== undefined)
+        await client.changeVisibility(queue, message.receipt, retryDelay).catch((e) => onError(e, message));
+      return false;
+    }
+  }
+  async function runBatch(messages) {
+    const lanes = new Map;
+    for (const m of messages) {
+      const lane = m.groupId === null ? `m:${m.messageId}` : `g:${m.groupId}`;
+      lanes.set(lane, [...lanes.get(lane) ?? [], m]);
+    }
+    const done = [];
+    const queued = [...lanes.values()];
+    const worker = async () => {
+      for (let lane = queued.shift();lane; lane = queued.shift()) {
+        for (const m of lane) {
+          if (!await handle(m))
+            break;
+          done.push(m.receipt);
+        }
+      }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, queued.length) }, worker));
+    return done;
+  }
+  const done = (async () => {
+    let backoff = 1000;
+    while (!signal.aborted) {
+      let messages;
+      const started = Date.now();
+      try {
+        messages = await client.receive(queue, { max: batchSize, wait, visibilityTimeout: opts.visibilityTimeout, signal });
+        backoff = 1000;
+        if (messages.length === 0)
+          await sleep(1000 - (Date.now() - started), signal);
+      } catch (err) {
+        if (signal.aborted)
+          break;
+        onError(err);
+        await sleep(backoff, signal);
+        backoff = Math.min(backoff * 2, 30000);
+        continue;
+      }
+      if (messages.length === 0)
+        continue;
+      const finished = await runBatch(messages);
+      if (finished.length > 0)
+        await client.delete(queue, finished).catch((err) => onError(err));
+    }
+  })();
+  return {
+    stop() {
+      stopper.abort();
+      return done;
+    },
+    done
+  };
+}
+export {
+  MybaseApiError,
+  QUEUE_LIMITS,
+  QUEUE_NAME_PATTERN,
+  QUEUE_NAME_RULES,
+  createQueueClient,
+  encodeBody
+};

package/dist/ratelimit.d.ts

@@ -0,0 +1,89 @@
+import { MybaseApiError } from "./cron";
+export { MybaseApiError };
+/**
+ * `sliding`: smooth, a weighted count over the current and previous window (default).
+ * `fixed`: a plain counter per window; allows bursts at window edges.
+ * `token`: a bucket of `burst` tokens (default `limit`), refilled at `limit` per `window`.
+ */
+export declare const RATELIMIT_ALGORITHMS: readonly ["sliding", "fixed", "token"];
+export type RateLimitAlgorithm = (typeof RATELIMIT_ALGORITHMS)[number];
+export declare const RATELIMIT_LIMITS: {
+    readonly limit: {
+        readonly min: 1;
+        readonly max: 1000000;
+    };
+    readonly windowMs: {
+        readonly min: 1000;
+        readonly max: number;
+    };
+    readonly idLength: 256;
+    readonly cost: {
+        readonly min: 1;
+        readonly max: 1000000;
+    };
+};
+/** A limit defined inline, per call. Same fields as a rule. */
+export interface InlineLimit {
+    limit: number;
+    /** Milliseconds, or `"10s"`, `"1m"`, `"1h"`, `"1d"`. */
+    window: number | string;
+    algorithm?: RateLimitAlgorithm;
+    /** Token bucket only: capacity. Default `limit`. */
+    burst?: number;
+}
+/** Body of `POST /ratelimit/<project>/limit`. Give `rule` or the inline fields. */
+export interface RateLimitRequest {
+    /** What's being limited: a user id, an IP, an API key. Up to 256 chars. */
+    id: string;
+    rule?: string;
+    limit?: number;
+    /** In ms. */
+    windowMs?: number;
+    algorithm?: RateLimitAlgorithm;
+    burst?: number;
+    /** Units this request uses. Default 1. */
+    cost?: number;
+}
+export interface RateLimitResult {
+    /** Whether the request is within the limit. */
+    success: boolean;
+    limit: number;
+    /** Units left in this window (or tokens left in the bucket). */
+    remaining: number;
+    /** When the limit fully resets, in unix ms. */
+    reset: number;
+    /** Set when mybase couldn't be reached and the limiter failed open or closed. */
+    error?: unknown;
+}
+export interface RateLimiterOptions {
+    /** 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 `ratelimit:write` for this project. Server-side only. */
+    apiKey: string;
+    /**
+     * What to answer when mybase can't be reached or times out. Default `false`: allow the request
+     * (fail open), so an outage doesn't take your app down with it. Set `true` for routes where
+     * letting traffic through is worse (sign-in, password reset).
+     */
+    failClosed?: boolean;
+    /** How long to wait for mybase, in ms. Default 1000. */
+    timeoutMs?: number;
+    /** Called when mybase can't be reached, before failing open or closed. */
+    onError?: (error: unknown) => void;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export interface LimitOptions {
+    /** Units this request uses. Default 1. */
+    cost?: number;
+}
+export interface RateLimiter {
+    /** Counts one request (or `cost` units) for `id` against a named rule or an inline limit. */
+    limit(rule: string | InlineLimit, id: string, options?: LimitOptions): Promise<RateLimitResult>;
+}
+/** `"10s"` / `"1m"` / ms → ms, checked against the allowed window range. */
+export declare function parseWindow(value: number | string): number;
+/** Headers to send with a 429 (or any response): `RateLimit-*` and `Retry-After`. */
+export declare function rateLimitHeaders(result: RateLimitResult, now?: number): Record<string, string>;
+export declare function createRateLimiter(options: RateLimiterOptions): RateLimiter;

package/dist/ratelimit.js

@@ -0,0 +1,244 @@
+// 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/ratelimit.ts
+var RATELIMIT_ALGORITHMS = ["sliding", "fixed", "token"];
+var RATELIMIT_LIMITS = {
+  limit: { min: 1, max: 1e6 },
+  windowMs: { min: 1000, max: 30 * 86400000 },
+  idLength: 256,
+  cost: { min: 1, max: 1e6 }
+};
+function parseWindow(value) {
+  const ms = parseDelay(value);
+  const { min, max } = RATELIMIT_LIMITS.windowMs;
+  if (ms < min || ms > max)
+    throw new RangeError(`window must be from 1s to 30d, got "${value}"`);
+  return ms;
+}
+function rateLimitHeaders(result, now = Date.now()) {
+  const resetSec = Math.max(0, Math.ceil((result.reset - now) / 1000));
+  const headers = {
+    "RateLimit-Limit": String(result.limit),
+    "RateLimit-Remaining": String(result.remaining),
+    "RateLimit-Reset": String(resetSec)
+  };
+  if (!result.success)
+    headers["Retry-After"] = String(resetSec);
+  return headers;
+}
+function createRateLimiter(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const url = `${options.apiUrl.replace(/\/+$/, "")}/ratelimit/${encodeURIComponent(options.project)}/limit`;
+  const timeoutMs = options.timeoutMs ?? 1000;
+  return {
+    async limit(rule, id, { cost } = {}) {
+      const body = typeof rule === "string" ? { id, rule, cost } : { id, limit: rule.limit, windowMs: parseWindow(rule.window), algorithm: rule.algorithm, burst: rule.burst, cost };
+      let res;
+      try {
+        res = await doFetch(url, {
+          method: "POST",
+          body: JSON.stringify(body),
+          headers: { "Content-Type": "application/json", Authorization: `Bearer ${options.apiKey}` },
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+      } catch (error) {
+        return unavailable(error);
+      }
+      const data = await res.json().catch(() => ({}));
+      if (res.ok)
+        return { success: data.success, limit: data.limit, remaining: data.remaining, reset: data.reset };
+      const error = new MybaseApiError(data.error ?? `mybase API answered ${res.status}`, res.status);
+      if (res.status >= 500)
+        return unavailable(error);
+      throw error;
+    }
+  };
+  function unavailable(error) {
+    options.onError?.(error);
+    return { success: !options.failClosed, limit: 0, remaining: 0, reset: Date.now(), error };
+  }
+}
+export {
+  MybaseApiError,
+  RATELIMIT_ALGORITHMS,
+  RATELIMIT_LIMITS,
+  createRateLimiter,
+  parseWindow,
+  rateLimitHeaders
+};