@mybase-dev/sdk 1.0.0

package/dist/cron.js

@@ -0,0 +1,190 @@
+// 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))
+  };
+}
+export {
+  CronVerificationError,
+  JOB_HEADER,
+  MybaseApiError,
+  RUN_HEADER,
+  SIGNATURE_HEADER,
+  createCronClient,
+  cronHandler,
+  parseDelay,
+  signCronRequest,
+  verifyCronRequest,
+  verifyCronSignature
+};

package/dist/queue.d.ts

@@ -0,0 +1,279 @@
+import { MybaseApiError } from "./cron";
+export { MybaseApiError };
+/** Queue names: unique per project, safe in URLs. */
+export declare const QUEUE_NAME_PATTERN: RegExp;
+export declare const QUEUE_NAME_RULES = "Use 1\u201380 lowercase letters, digits, `_`, or `-`, starting with a letter or digit.";
+export declare const QUEUE_LIMITS: {
+    /** Messages per send, receive, delete, or visibility batch. */
+    readonly batch: 100;
+    /** All bodies and attributes of one send together. */
+    readonly batchBytes: number;
+    readonly maxMessageBytes: {
+        readonly min: 1024;
+        readonly max: number;
+        readonly default: number;
+    };
+    readonly visibilityTimeoutMs: {
+        readonly min: 0;
+        readonly max: number;
+        readonly default: 30000;
+    };
+    readonly delayMs: {
+        readonly min: 0;
+        readonly max: number;
+        readonly default: 0;
+    };
+    readonly retentionMs: {
+        readonly min: 60000;
+        readonly max: number;
+        readonly default: number;
+    };
+    /** Long polling: how long a receive waits for a message to arrive. */
+    readonly waitMs: {
+        readonly min: 0;
+        readonly max: 20000;
+        readonly default: 0;
+    };
+    readonly maxReceives: {
+        readonly min: 1;
+        readonly max: 1000;
+    };
+    readonly attributes: 10;
+    /** FIFO group and deduplication ids: printable ASCII. */
+    readonly idLength: 128;
+    /** A FIFO send with a deduplication id seen this recently is accepted but not enqueued. */
+    readonly dedupWindowMs: number;
+    readonly queuesPerProject: 1000;
+};
+export type QueueAttributes = Record<string, string | number | boolean>;
+/** Where a queue is defined: dashboard/CLI, mybase.config.ts (`mybase queue sync`), or app code. */
+export type QueueSource = "dashboard" | "code" | "api";
+export interface DeadLetterSettings {
+    /** Another queue in the project, of the same kind (standard or FIFO). */
+    queue: string;
+    /** Receives after which a message moves there instead of being delivered again. */
+    maxReceives: number;
+}
+/** A queue's settings, as the API returns them. */
+export interface QueueSettings {
+    /** FIFO: strict order within each message group, exactly-once enqueue (deduplication). Fixed at creation. */
+    fifo: boolean;
+    /** How long a received message stays hidden from other consumers. */
+    visibilityTimeoutMs: number;
+    /** How long new messages wait before they can be received. */
+    delayMs: number;
+    /** How long a message is kept before it's deleted unreceived. */
+    retentionMs: number;
+    maxMessageBytes: number;
+    /** Default long-poll wait for receives that don't set one. */
+    receiveWaitMs: number;
+    /** FIFO only: deduplicate by a SHA-256 of the body when a send has no `dedupId`. */
+    contentDedup: boolean;
+    deadLetter: DeadLetterSettings | null;
+}
+export interface QueueCounts {
+    /** Ready to receive. */
+    visible: number;
+    /** Received, not yet deleted, still within the visibility timeout. */
+    inFlight: number;
+    /** Waiting out a delay. */
+    delayed: number;
+}
+export interface Queue extends QueueSettings {
+    name: string;
+    source: QueueSource;
+    /** Approximate. */
+    counts: QueueCounts;
+    /** Sent time of the oldest message, or null when empty. */
+    oldestMessageAt: string | null;
+    /** Queues that send their dead letters here. */
+    deadLetterFor: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Create or change a queue. Durations are ms or `"30s"`, `"5m"`, `"4d"`; `…Ms` fields take ms.
+ * Absent fields keep their current value (or the default, on create).
+ */
+export interface QueueSettingsInput {
+    fifo?: boolean;
+    visibilityTimeout?: number | string;
+    delay?: number | string;
+    retention?: number | string;
+    receiveWait?: number | string;
+    maxMessageBytes?: number;
+    contentDedup?: boolean;
+    deadLetter?: DeadLetterSettings | null;
+}
+export interface CreateQueueRequest extends QueueSettingsInput {
+    name: string;
+}
+/** One message in a send. */
+export interface SendMessageEntry {
+    /** Yours, echoed in the result to match entries up. Default: the entry's index. */
+    id?: string;
+    body: string;
+    /** Standard queues only; FIFO queues use the queue's delay. */
+    delayMs?: number;
+    /** FIFO: required. Messages with the same group are delivered in order, one batch at a time. */
+    groupId?: string;
+    /** FIFO: a repeat within 5 minutes is accepted but not enqueued again. Required unless the queue has `contentDedup`. */
+    dedupId?: string;
+    attributes?: QueueAttributes;
+}
+export interface SendMessagesRequest {
+    messages: SendMessageEntry[];
+}
+export interface SentMessage {
+    id: string;
+    messageId: string;
+    /** FIFO: position in the queue, increasing. Null for standard queues. */
+    sequence: string | null;
+    /** FIFO: the dedup id was seen in the last 5 minutes; `messageId` is the original's. */
+    duplicate: boolean;
+}
+export interface BatchFailure {
+    /** The entry's `id`, or its receipt for deletes and visibility changes. */
+    id: string;
+    error: string;
+}
+export interface SendMessagesResponse {
+    successful: SentMessage[];
+    failed: BatchFailure[];
+}
+export interface ReceiveMessagesRequest {
+    /** 1–100. Default 1. */
+    max?: number;
+    /** Long polling: wait up to this long (0–20000 ms) for a message. Default: the queue's `receiveWaitMs`. */
+    waitMs?: number;
+    /** Overrides the queue's visibility timeout for these messages. */
+    visibilityTimeoutMs?: number;
+}
+/** A received message. Delete it with `receipt` once handled, or it's delivered again. */
+export interface QueueMessage {
+    messageId: string;
+    /** Proves this receive; changes on every delivery. Only the latest one works. */
+    receipt: string;
+    body: string;
+    attributes: QueueAttributes;
+    groupId: string | null;
+    dedupId: string | null;
+    sequence: string | null;
+    /** Times this message has been received, this time included. */
+    receiveCount: number;
+    sentAt: string;
+    firstReceivedAt: string;
+}
+export interface ReceiveMessagesResponse {
+    messages: QueueMessage[];
+}
+export interface DeleteMessagesRequest {
+    receipts: string[];
+}
+export interface VisibilityEntry {
+    receipt: string;
+    visibilityTimeoutMs: number;
+}
+export interface ChangeVisibilityRequest {
+    entries: VisibilityEntry[];
+}
+/** Deletes and visibility changes: how many applied, and which receipts didn't (stale, or the message is gone). */
+export interface BatchResult {
+    done: number;
+    failed: BatchFailure[];
+}
+/** Moves a dead-letter queue's messages back. Without `to`, each goes back to the queue it came from. */
+export interface RedriveRequest {
+    to?: string;
+}
+export interface RedriveResponse {
+    moved: number;
+}
+export interface QueueClientOptions {
+    /** 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 `queue:write` for this project (`queue:read` is enough to list and get queues). Server-side only. */
+    apiKey: string;
+    /** How long to wait for mybase on calls other than long polls, in ms. Default 10000. */
+    timeoutMs?: number;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export interface SendOptions {
+    /** Standard queues: hide the message this long first (ms or `"30s"`, up to 15 minutes). */
+    delay?: number | string;
+    groupId?: string;
+    dedupId?: string;
+    attributes?: QueueAttributes;
+}
+export interface SendBatchEntry extends SendOptions {
+    id?: string;
+    /** Strings are sent as is; anything else as JSON. */
+    body: unknown;
+}
+export interface ReceiveOptions {
+    max?: number;
+    /** Long poll: ms or `"20s"`, up to 20 seconds. */
+    wait?: number | string;
+    visibilityTimeout?: number | string;
+    signal?: AbortSignal;
+}
+/** A received message, with its body parsed on demand. */
+export interface ReceivedMessage extends QueueMessage {
+    /** `JSON.parse(body)`. */
+    json<T = unknown>(): T;
+}
+export interface ConsumeOptions {
+    /** Messages per receive, 1–100. Default 10. */
+    batchSize?: number;
+    /** Handlers running at once. Default `batchSize`. FIFO groups always run one message at a time, in order. */
+    concurrency?: number;
+    /** Long poll per receive. Default 20s. */
+    wait?: number | string;
+    /** Default: the queue's. Set it longer than your slowest handler. */
+    visibilityTimeout?: number | string;
+    /**
+     * After a handler throws: make the message visible again after this long. Default: leave it
+     * hidden until its visibility timeout runs out.
+     */
+    retryDelay?: number | string;
+    /** Called when a handler throws or mybase can't be reached. Default `console.error`. */
+    onError?: (error: unknown, message?: ReceivedMessage) => void;
+    /** Stops the consumer, like `stop()`. */
+    signal?: AbortSignal;
+}
+export interface Consumer {
+    /** Stops receiving, waits for running handlers, and deletes what they finished. */
+    stop(): Promise<void>;
+    /** Settles when the consumer has stopped. */
+    done: Promise<void>;
+}
+export interface QueueClient {
+    send(queue: string, body: unknown, options?: SendOptions): Promise<SentMessage>;
+    /** Up to 100 messages. Entries fail one by one: check `failed`. */
+    sendBatch(queue: string, entries: SendBatchEntry[]): Promise<SendMessagesResponse>;
+    receive(queue: string, options?: ReceiveOptions): Promise<ReceivedMessage[]>;
+    /** Deletes received messages by receipt. Resolves to how many were deleted. */
+    delete(queue: string, receipts: string | string[]): Promise<BatchResult>;
+    /** Extends (or ends, with 0) the visibility timeout of a received message. */
+    changeVisibility(queue: string, receipt: string, timeout: number | string): Promise<void>;
+    changeVisibilityBatch(queue: string, entries: {
+        receipt: string;
+        timeout: number | string;
+    }[]): Promise<BatchResult>;
+    /** Calls `handler` for each message, deleting it when the handler resolves. */
+    consume(queue: string, handler: (message: ReceivedMessage) => unknown, options?: ConsumeOptions): Consumer;
+    listQueues(): Promise<Queue[]>;
+    getQueue(queue: string): Promise<Queue>;
+    createQueue(queue: string, settings?: QueueSettingsInput): Promise<Queue>;
+    updateQueue(queue: string, settings: QueueSettingsInput): Promise<Queue>;
+    deleteQueue(queue: string): Promise<void>;
+    /** Deletes every message in the queue. */
+    purge(queue: string): Promise<void>;
+    /** Moves a dead-letter queue's messages back to their source queues (or `to`). */
+    redrive(queue: string, options?: RedriveRequest): Promise<RedriveResponse>;
+}
+/** Strings as is, everything else as JSON. */
+export declare const encodeBody: (body: unknown) => string;
+export declare function createQueueClient(options: QueueClientOptions): QueueClient;