@mybase-dev/sdk 1.0.0 → 1.0.2

package/dist/search.js

@@ -0,0 +1,315 @@
+// 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/search.ts
+var SEARCH_CATEGORIES = ["general", "news", "it"];
+var SEARCH_TIME_RANGES = ["day", "week", "month", "year"];
+var SEARCH_LIMITS = {
+  queryLength: 400,
+  results: { default: 10, max: 20 },
+  page: { max: 10 },
+  urlLength: 2048,
+  maxChars: { default: 20000, min: 500, max: 1e5 }
+};
+var SEARCH_LANGUAGE_PATTERN = /^[a-z]{2}(-[A-Z]{2})?$/;
+function createSearchClient(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const base = `${options.apiUrl.replace(/\/+$/, "")}/search/${encodeURIComponent(options.project)}`;
+  const timeoutMs = options.timeoutMs ?? 20000;
+  async function get(url) {
+    const res = await doFetch(url, {
+      headers: { Authorization: `Bearer ${options.apiKey}` },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok)
+      throw new MybaseApiError(data.error ?? `mybase API answered ${res.status}`, res.status);
+    return data;
+  }
+  return {
+    search(query, { limit, category, timeRange, language, page } = {}) {
+      const params = new URLSearchParams({ q: query });
+      if (limit !== undefined)
+        params.set("limit", String(limit));
+      if (category)
+        params.set("category", category);
+      if (timeRange)
+        params.set("timeRange", timeRange);
+      if (language)
+        params.set("language", language);
+      if (page !== undefined)
+        params.set("page", String(page));
+      return get(`${base}?${params}`);
+    },
+    fetch(url, { maxChars } = {}) {
+      const params = new URLSearchParams({ url });
+      if (maxChars !== undefined)
+        params.set("maxChars", String(maxChars));
+      return get(`${base}/fetch?${params}`);
+    }
+  };
+}
+function searchTools(client, options = {}) {
+  const maxChars = options.maxChars ?? SEARCH_LIMITS.maxChars.default;
+  const limit = options.limit ?? 8;
+  return [
+    {
+      name: "web_search",
+      description: "Search the web. Returns titles, URLs, and snippets. Use web_fetch to read a result in full. " + "Write queries like a search engine query (keywords), not a question to a person.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "The search query." },
+          category: {
+            type: "string",
+            enum: [...SEARCH_CATEGORIES],
+            description: "general (default): the web. news: recent articles. it: GitHub and Stack Overflow."
+          },
+          timeRange: { type: "string", enum: [...SEARCH_TIME_RANGES], description: "Only results from this recent period." }
+        },
+        required: ["query"],
+        additionalProperties: false
+      },
+      run: (input) => attempt(async () => {
+        const { query, category, timeRange } = object(input);
+        if (typeof query !== "string" || !query.trim())
+          return "Error: query is required.";
+        const { results } = await client.search(query, {
+          limit,
+          category: oneOf(category, SEARCH_CATEGORIES),
+          timeRange: oneOf(timeRange, SEARCH_TIME_RANGES)
+        });
+        if (results.length === 0)
+          return `No results for "${query}".`;
+        return results.map((r, i) => {
+          const date = r.publishedAt ? ` (${r.publishedAt.slice(0, 10)})` : "";
+          return `${i + 1}. ${r.title}${date}
+   ${r.url}${r.snippet ? `
+   ${r.snippet}` : ""}`;
+        }).join(`
+
+`);
+      })
+    },
+    {
+      name: "web_fetch",
+      description: "Read a public web page and return its main content as markdown. Use it on URLs from web_search " + "or ones the user gave. Long pages are cut off.",
+      inputSchema: {
+        type: "object",
+        properties: { url: { type: "string", description: "The http(s) URL to read." } },
+        required: ["url"],
+        additionalProperties: false
+      },
+      run: (input) => attempt(async () => {
+        const { url } = object(input);
+        if (typeof url !== "string" || !url.trim())
+          return "Error: url is required.";
+        const page = await client.fetch(url, { maxChars });
+        const head = `# ${page.title ?? page.url}
+URL: ${page.url}
+
+`;
+        return head + page.markdown + (page.truncated ? `
+
+[Cut off at ${maxChars} characters.]` : "");
+      })
+    }
+  ];
+}
+var object = (input) => typeof input === "object" && input !== null && !Array.isArray(input) ? input : {};
+function oneOf(value, allowed) {
+  return allowed.includes(value) ? value : undefined;
+}
+async function attempt(run) {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof MybaseApiError && ![401, 403, 404].includes(error.status))
+      return `Error: ${error.message}`;
+    throw error;
+  }
+}
+export {
+  MybaseApiError,
+  SEARCH_CATEGORIES,
+  SEARCH_LANGUAGE_PATTERN,
+  SEARCH_LIMITS,
+  SEARCH_TIME_RANGES,
+  createSearchClient,
+  searchTools
+};

package/dist/secrets.d.ts

@@ -0,0 +1,138 @@
+import { MybaseApiError } from "./cron";
+export { MybaseApiError };
+/** `dev`, `staging`, `prod`, `prod_eu`, … */
+export declare const SECRETS_ENV_PATTERN: RegExp;
+export declare const SECRETS_ENV_RULES = "1\u201340 characters: lowercase letters, digits, _ or -, starting with a letter";
+/** Env var names: `STRIPE_KEY`, `databaseUrl`, … */
+export declare const SECRET_KEY_PATTERN: RegExp;
+export declare const SECRET_KEY_RULES = "1\u2013128 characters: letters, digits, or _, not starting with a digit";
+export declare const SECRETS_LIMITS: {
+    /** Per value, UTF-8. */
+    readonly valueBytes: number;
+    readonly keysPerEnv: 1000;
+    readonly envsPerProject: 50;
+    /** Older revisions are pruned. */
+    readonly revisionsKept: 200;
+    readonly messageLength: 200;
+};
+/** Every project starts with these (they can be renamed or deleted). */
+export declare const DEFAULT_SECRETS_ENVS: readonly ["dev", "staging", "prod"];
+/**
+ * Keys `mybase secrets link` writes and keeps up to date. Read-only elsewhere: running link
+ * again rotates them.
+ */
+export declare const MANAGED_SECRET_KEYS: readonly ["DATABASE_URL", "S3_ENDPOINT", "S3_REGION", "S3_BUCKET", "S3_ACCESS_KEY_ID", "S3_SECRET_ACCESS_KEY", "REDIS_URL", "MYBASE_URL", "MYBASE_PROJECT"];
+export interface SecretsEnv {
+    name: string;
+    /** Branch envs inherit every key of their parent (a root env) and override some. */
+    parent: string | null;
+    /** Bumped on every change. */
+    revision: number;
+    /** Own keys, not counting inherited ones. */
+    keys: number;
+    /** Holds the project's credentials (`mybase secrets link`). */
+    linked: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `GET /projects/<project>/secrets`. Only envs the caller's key may read are listed. */
+export interface SecretsOverview {
+    envs: SecretsEnv[];
+    apiUrl: string;
+    enabledAt: string;
+}
+export interface SecretEntry {
+    key: string;
+    /** Only when values were asked for. */
+    value?: string;
+    /** Written by `mybase secrets link`. */
+    managed: boolean;
+    /** From the parent env (a branch env hasn't overridden it). */
+    inherited: boolean;
+    updatedAt: string;
+}
+export interface SecretsEnvDetail {
+    env: SecretsEnv;
+    secrets: SecretEntry[];
+}
+export interface CreateSecretsEnvRequest {
+    name: string;
+    /** Makes a branch env of this root env. */
+    parent?: string | null;
+}
+export interface UpdateSecretsRequest {
+    set?: Record<string, string>;
+    unset?: string[];
+    /** Shown in the history. */
+    message?: string;
+}
+export interface UpdateSecretsResponse {
+    /** The env's revision after the change (unchanged when nothing changed). */
+    revision: number;
+    changed: number;
+}
+export type SecretChangeAction = "added" | "changed" | "removed";
+export interface SecretChange {
+    key: string;
+    action: SecretChangeAction;
+    managed: boolean;
+    /** Only when values were asked for. */
+    oldValue?: string | null;
+    newValue?: string | null;
+}
+export interface SecretsRevision {
+    revision: number;
+    /** `admin`, `key:<name>`, or `link`. */
+    actor: string;
+    message: string | null;
+    createdAt: string;
+    changes: SecretChange[];
+}
+/** `GET /secrets/<project>/<env>`: every key resolved, branch overrides applied. */
+export interface SecretsResponse {
+    env: string;
+    /** Changes whenever any value (own or inherited) may have changed. Also sent as the ETag. */
+    version: string;
+    secrets: Record<string, string>;
+}
+export interface LinkCredentialsRequest {
+    envs: string[];
+}
+export interface LinkCredentialsResponse {
+    /** Every env now holding the credentials (earlier links included). */
+    envs: string[];
+    keys: string[];
+}
+export interface SecretsClientOptions {
+    /** Where the mybase API is reachable from your app, e.g. `https://mybase.example.com`. */
+    apiUrl: string;
+    project: string;
+    /** `dev`, `prod`, a branch env, … */
+    env: string;
+    /** A mybase API key (`mb_…`) with `secrets:read` for this project (and env, if it's env-scoped). Server-side only. */
+    apiKey: string;
+    /** Reuse fetched secrets this long without asking mybase, in ms. Default 0: every read revalidates (a 304 when nothing changed). */
+    maxAgeMs?: number;
+    /** Default 10000. */
+    timeoutMs?: number;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export interface SecretsClient {
+    /** Every key in the env, inherited ones included. */
+    all(): Promise<Record<string, string>>;
+    /** One value, or undefined when the key isn't set. */
+    get(key: string): Promise<string | undefined>;
+    /** Copies the secrets into `process.env`. Existing vars win unless `override`. Returns the keys set. */
+    load(options?: {
+        override?: boolean;
+    }): Promise<string[]>;
+    /** Needs `secrets:write`. One revision in the history. */
+    set(values: Record<string, string>, options?: {
+        message?: string;
+    }): Promise<UpdateSecretsResponse>;
+    unset(keys: string | string[], options?: {
+        message?: string;
+    }): Promise<UpdateSecretsResponse>;
+}
+export declare function createSecretsClient(options: SecretsClientOptions): SecretsClient;