@mybase-dev/sdk 1.0.0

package/dist/cache.js

@@ -0,0 +1,277 @@
+// 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/cache.ts
+function setArgs(key, value, o = {}) {
+  const args = ["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;
+}
+function createCache(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const base = `${options.apiUrl.replace(/\/+$/, "")}/cache/${encodeURIComponent(options.project)}`;
+  const prefix = `${options.project}:`;
+  const k = (key) => key.startsWith(prefix) ? key : prefix + key;
+  async function post(path, body) {
+    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(() => ({}));
+    if (!res.ok)
+      throw new MybaseApiError(data.error ?? `mybase API answered ${res.status}`, res.status);
+    return data;
+  }
+  async function command(args) {
+    const data = await post("", args);
+    if (data.error !== undefined)
+      throw new MybaseApiError(data.error, 400);
+    return data.result;
+  }
+  function pipeline() {
+    const commands = [];
+    const add = (args) => {
+      commands.push(args);
+      return p;
+    };
+    const p = {
+      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) => {
+    const out = {};
+    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(key) {
+      const raw = await command(["GET", k(key)]);
+      return raw === null ? null : JSON.parse(raw);
+    },
+    set: async (key, value, o) => await command(setArgs(k(key), value, o)) === "OK",
+    setJson: async (key, value, o) => await command(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(["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) => {
+      const raw = await command(["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(["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(["ZINCRBY", k(key), by, member])),
+    publish: (channel, message) => command(["PUBLISH", k(channel), message]),
+    pipeline
+  };
+}
+export {
+  MybaseApiError,
+  createCache
+};

package/dist/config.d.ts

@@ -0,0 +1,65 @@
+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 declare function defineConfig<const C extends MybaseConfig>(config: C): C;
+export declare const DEFAULT_CRON_PATH = "/api/cron";

package/dist/config.js

@@ -0,0 +1,9 @@
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+var DEFAULT_CRON_PATH = "/api/cron";
+export {
+  DEFAULT_CRON_PATH,
+  defineConfig
+};

package/dist/cron.d.ts

@@ -0,0 +1,166 @@
+import { type MybaseConfig } from "./config";
+/** `schedule`: a cron tick. `manual`: "Run now". `task`: a one-off task scheduled with `createCronClient`. */
+export type CronTrigger = "schedule" | "manual" | "task";
+/** The body of every cron call. */
+export interface CronRun<Job extends string = string> {
+    job: Job;
+    /** Same across retries of one run, so you can dedupe. */
+    runId: string;
+    /** 1 for the first try, then 2, 3, … on retries. */
+    attempt: number;
+    trigger: CronTrigger;
+    /** When the schedule said to run (ISO). For manual runs, when it was requested. For tasks, the task's run time. */
+    scheduledAt: string;
+    /** When this attempt was sent (ISO). */
+    firedAt: string;
+    payload: unknown;
+    /** Tasks only: the key the task was scheduled with, if any. `runId` is the task id. */
+    key?: string | null;
+}
+export declare const SIGNATURE_HEADER = "X-Mybase-Signature";
+export declare const JOB_HEADER = "X-Mybase-Job";
+export declare const RUN_HEADER = "X-Mybase-Run";
+/** Thrown when a request's signature is missing, malformed, stale, or wrong. */
+export declare class CronVerificationError extends Error {
+    name: string;
+}
+/** The `X-Mybase-Signature` value for `body`. `t` is unix seconds (default: now). */
+export declare function signCronRequest(secret: string, body: string, t?: number): Promise<string>;
+export interface VerifyOptions {
+    /** The raw request body, exactly as received. */
+    body: string;
+    /** The `X-Mybase-Signature` header. */
+    signature: string | null | undefined;
+    /** The project's cron secret. Pass several while rotating (new first). */
+    secret: string | readonly string[];
+    /** Max age of the signature, in seconds. Default 300. */
+    toleranceSec?: number;
+}
+/** Throws CronVerificationError unless `signature` signs `body` with one of the secrets, recently. */
+export declare function verifyCronSignature({ body, signature, secret, toleranceSec }: VerifyOptions): Promise<void>;
+/** Verifies a Fetch API request and returns its parsed body. Consumes the body. */
+export declare function verifyCronRequest(req: Request, secret: string | readonly string[], options?: {
+    toleranceSec?: number;
+}): Promise<CronRun>;
+/** Job names from a config type, or any string without one. */
+type JobName<C extends MybaseConfig> = C extends {
+    cron: {
+        jobs: infer J;
+    };
+} ? Extract<keyof J, string> : string;
+export type CronJobHandler<Job extends string = string> = (run: CronRun<Job>) => unknown | Promise<unknown>;
+export interface CronHandlerOptions<C extends MybaseConfig> {
+    /** The project's cron secret. Pass several while rotating (new first). */
+    secret: string | readonly string[];
+    /** A function per job name. */
+    jobs: {
+        [J in JobName<C>]: CronJobHandler<J>;
+    };
+    /** Called when a job throws, before the 500 goes back (mybase then retries). */
+    onError?: (err: unknown, run: CronRun) => void;
+    toleranceSec?: number;
+}
+/**
+ * A Fetch API handler (Bun.serve, Next.js route handlers, Hono, Deno, Workers) that verifies
+ * the call and runs the named job. 401 bad signature, 404 unknown job, 500 job threw, 200 done.
+ * Pass your config type for typed job names: `cronHandler<typeof config>({ ... })`.
+ */
+export declare function cronHandler<C extends MybaseConfig = MybaseConfig>(options: CronHandlerOptions<C>): (req: Request) => Promise<Response>;
+export type CronTaskStatus = "pending" | "running" | "success" | "failed" | "cancelled";
+/** A one-off call: mybase POSTs a CronRun (trigger `task`) to `url` once, at `runAt`. */
+export interface CronTask {
+    id: string;
+    /** The handler name sent as `run.job`. */
+    job: string;
+    key: string | null;
+    url: string;
+    payload: unknown;
+    runAt: string;
+    timeoutMs: number;
+    retries: number;
+    status: CronTaskStatus;
+    attempts: number;
+    /** Last attempt's status; `null` before the call or when it got no response. */
+    httpStatus: number | null;
+    durationMs: number | null;
+    error: string | null;
+    /** Start of the last response body, truncated. */
+    response: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+/** What the API takes to create a task. Give `runAt` or `delayMs`, or neither to run as soon as possible. */
+export interface CreateCronTaskRequest {
+    job: string;
+    url: string;
+    runAt?: string;
+    delayMs?: number;
+    key?: string;
+    payload?: unknown;
+    timeoutMs?: number;
+    retries?: number;
+}
+export interface CronClientOptions {
+    /** Where the mybase API is reachable from your app, e.g. `https://mybase.example.com`. */
+    apiUrl: string;
+    /** The mybase project. */
+    project: string;
+    /** A mybase API key (`mb_…`) with `cron:write` for this project. Server-side only. */
+    apiKey: string;
+    /** Your app, as reachable from the mybase server. Tasks POST to `baseUrl` + `path` unless they set `url`. */
+    baseUrl?: string;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export interface ScheduleOptions {
+    /** When to run. */
+    at?: Date | string;
+    /** Or how long from now: milliseconds, or `"30s"`, `"15m"`, `"2h"`, `"7d"`. Neither `at` nor `in`: as soon as possible. */
+    in?: number | string;
+    /** JSON sent to your handler as `run.payload` (up to 16 KB). */
+    payload?: unknown;
+    /**
+     * Dedupe key. While a task with this key is pending or running, scheduling the key again
+     * returns that task instead of making a new one. Also lets you `get`/`cancel` by key.
+     */
+    key?: string;
+    /** Appended to the client's `baseUrl`. Default `/api/cron`. */
+    path?: string;
+    /** Full URL to call instead of `baseUrl` + `path`. */
+    url?: string;
+    /** Extra tries after a failed call. 0–5, default 2. */
+    retries?: number;
+    /** 1000–120000, default 30000. */
+    timeoutMs?: number;
+}
+/** A non-2xx answer from the mybase API. */
+export declare class MybaseApiError extends Error {
+    readonly status: number;
+    name: string;
+    constructor(message: string, status: number);
+}
+/** `1500`, `"30s"`, `"15m"`, `"2h"`, `"7d"` → milliseconds. */
+export declare function parseDelay(value: number | string): number;
+export interface CronClient {
+    /** Schedules `job` to be called once. Resolves to the new task (or the pending one with the same `key`). */
+    schedule(job: string, options?: ScheduleOptions): Promise<CronTask>;
+    /** A task by id, or `null` once it's gone (finished tasks are kept 7 days). */
+    get(id: string): Promise<CronTask | null>;
+    /** The newest task with this key, or `null`. */
+    getByKey(key: string): Promise<CronTask | null>;
+    /** Cancels a pending task. Resolves to the task, or `null` when there's no such task. Throws 409 if it already ran. */
+    cancel(id: string): Promise<CronTask | null>;
+    /** Cancels the pending task with this key. */
+    cancelByKey(key: string): Promise<CronTask | null>;
+}
+/**
+ * Schedules one-off calls to your cron handler from app code:
+ *
+ *   const cron = createCronClient({ apiUrl, project: "shop", apiKey: process.env.MYBASE_API_KEY!, baseUrl: "https://shop.example.com" });
+ *   await cron.schedule("send-reminder", { in: "24h", payload: { orderId }, key: `reminder-${orderId}` });
+ *
+ * Keep the API key server-side.
+ */
+export declare function createCronClient(options: CronClientOptions): CronClient;
+export {};