@mybase-dev/sdk 1.0.0 → 1.0.2

package/dist/secrets.js

@@ -0,0 +1,274 @@
+// 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/secrets.ts
+var SECRETS_ENV_PATTERN = /^[a-z][a-z0-9_-]{0,39}$/;
+var SECRETS_ENV_RULES = "1–40 characters: lowercase letters, digits, _ or -, starting with a letter";
+var SECRET_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+var SECRET_KEY_RULES = "1–128 characters: letters, digits, or _, not starting with a digit";
+var SECRETS_LIMITS = {
+  valueBytes: 64 * 1024,
+  keysPerEnv: 1000,
+  envsPerProject: 50,
+  revisionsKept: 200,
+  messageLength: 200
+};
+var DEFAULT_SECRETS_ENVS = ["dev", "staging", "prod"];
+var MANAGED_SECRET_KEYS = [
+  "DATABASE_URL",
+  "S3_ENDPOINT",
+  "S3_REGION",
+  "S3_BUCKET",
+  "S3_ACCESS_KEY_ID",
+  "S3_SECRET_ACCESS_KEY",
+  "REDIS_URL",
+  "MYBASE_URL",
+  "MYBASE_PROJECT"
+];
+function createSecretsClient(options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const url = `${options.apiUrl.replace(/\/+$/, "")}/secrets/${encodeURIComponent(options.project)}/${encodeURIComponent(options.env)}`;
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const maxAgeMs = options.maxAgeMs ?? 0;
+  const headers = { Authorization: `Bearer ${options.apiKey}` };
+  let cached;
+  async function fail(res) {
+    const data = await res.json().catch(() => ({}));
+    throw new MybaseApiError(data.error ?? `mybase API answered ${res.status}`, res.status);
+  }
+  async function all() {
+    if (cached && Date.now() - cached.at < maxAgeMs)
+      return { ...cached.secrets };
+    const res = await doFetch(url, {
+      headers: cached?.etag ? { ...headers, "If-None-Match": cached.etag } : headers,
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (res.status === 304 && cached) {
+      cached.at = Date.now();
+      return { ...cached.secrets };
+    }
+    if (!res.ok)
+      return fail(res);
+    const data = await res.json();
+    cached = { etag: res.headers.get("ETag"), secrets: data.secrets, at: Date.now() };
+    return { ...data.secrets };
+  }
+  async function update(body) {
+    const res = await doFetch(url, {
+      method: "PATCH",
+      body: JSON.stringify(body),
+      headers: { ...headers, "Content-Type": "application/json" },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!res.ok)
+      return fail(res);
+    cached = undefined;
+    return await res.json();
+  }
+  return {
+    all,
+    get: async (key) => (await all())[key],
+    async load({ override = false } = {}) {
+      const secrets = await all();
+      const env = globalThis.process?.env;
+      if (!env)
+        throw new Error("load() needs process.env (Node, Bun, Deno); use all() elsewhere");
+      const set = [];
+      for (const [key, value] of Object.entries(secrets)) {
+        if (!override && env[key] !== undefined)
+          continue;
+        env[key] = value;
+        set.push(key);
+      }
+      return set;
+    },
+    set: (values, opts = {}) => update({ set: values, message: opts.message }),
+    unset: (keys, opts = {}) => update({ unset: [keys].flat(), message: opts.message })
+  };
+}
+export {
+  DEFAULT_SECRETS_ENVS,
+  MANAGED_SECRET_KEYS,
+  MybaseApiError,
+  SECRETS_ENV_PATTERN,
+  SECRETS_ENV_RULES,
+  SECRETS_LIMITS,
+  SECRET_KEY_PATTERN,
+  SECRET_KEY_RULES,
+  createSecretsClient
+};

package/dist/vector.d.ts

@@ -0,0 +1,234 @@
+import { MybaseApiError } from "./cron";
+import type { ToolInputSchema } from "./search";
+export { MybaseApiError };
+export type { ToolInputSchema };
+/** Index names: they become table names, so lowercase letters, digits, and `_`. */
+export declare const VECTOR_INDEX_PATTERN: RegExp;
+export declare const VECTOR_INDEX_RULES = "Use 1\u201348 lowercase letters, digits, or `_`, starting with a letter.";
+/** How vectors are compared. `cosine` suits most embedding models. */
+export declare const VECTOR_METRICS: readonly ["cosine", "l2", "ip"];
+export type VectorMetric = (typeof VECTOR_METRICS)[number];
+/** Postgres text search configurations: stemming and stop words. `simple` does neither. */
+export declare const VECTOR_LANGUAGES: readonly ["simple", "arabic", "armenian", "basque", "catalan", "danish", "dutch", "english", "finnish", "french", "german", "greek", "hindi", "hungarian", "indonesian", "irish", "italian", "lithuanian", "nepali", "norwegian", "portuguese", "romanian", "russian", "serbian", "spanish", "swedish", "tamil", "turkish", "yiddish"];
+export type VectorLanguage = (typeof VECTOR_LANGUAGES)[number];
+export declare const VECTOR_QUERY_MODES: readonly ["text", "vector", "hybrid"];
+export type VectorQueryMode = (typeof VECTOR_QUERY_MODES)[number];
+export declare const VECTOR_LIMITS: {
+    /** Documents per upsert, get, or delete. */
+    readonly batch: 100;
+    /** One upsert's JSON body. */
+    readonly batchBytes: number;
+    readonly idLength: 256;
+    readonly titleLength: 1000;
+    readonly textLength: 100000;
+    /** A document's metadata, as JSON. */
+    readonly metadataBytes: number;
+    /** Vector dimensions (pgvector's HNSW index takes up to 2000). */
+    readonly dimensions: {
+        readonly min: 1;
+        readonly max: 2000;
+    };
+    readonly topK: {
+        readonly min: 1;
+        readonly max: 100;
+        readonly default: 10;
+    };
+    /** Query text. */
+    readonly queryLength: 2000;
+    readonly indexesPerProject: 50;
+};
+/** Where an index is defined: dashboard/CLI, mybase.config.ts (`mybase vector sync`), or app code. */
+export type VectorIndexSource = "dashboard" | "code" | "api";
+export type VectorMetadata = Record<string, unknown>;
+/** An index's settings. Dimensions, metric, and language are fixed at creation. */
+export interface VectorIndexSettings {
+    /** Vector length; null = a text-only index (no vectors). */
+    dimensions: number | null;
+    metric: VectorMetric;
+    language: VectorLanguage;
+    /** mybase embeds `text` with the project's embedding provider when a document or query has no vector. */
+    embed: boolean;
+}
+export interface VectorIndexInput {
+    /** Omit with `embed: true` to use the provider's dimensions. */
+    dimensions?: number | null;
+    /** Default `cosine`. */
+    metric?: VectorMetric;
+    /** Default `english`. */
+    language?: VectorLanguage;
+    /** Default false. Needs an embedding provider in the project's vector settings. */
+    embed?: boolean;
+}
+export interface VectorIndex extends VectorIndexSettings {
+    name: string;
+    source: VectorIndexSource;
+    /** Approximate document count (Postgres statistics, exact for small tables). */
+    documents: number;
+    createdAt: string;
+}
+/** A document to upsert. Documents with the same id are replaced. */
+export interface VectorDocument<M extends VectorMetadata = VectorMetadata> {
+    id: string;
+    /** Searched by keyword, weighted above `text`. */
+    title?: string | null;
+    /** Searched by keyword, and embedded when the index has `embed` on and no `vector` is given. */
+    text?: string;
+    /** Free-form JSON, matched by `filter`. */
+    metadata?: M;
+    vector?: number[];
+}
+export interface StoredDocument<M extends VectorMetadata = VectorMetadata> {
+    id: string;
+    title: string | null;
+    text: string;
+    metadata: M;
+    /** Only when asked for (`includeVectors`). */
+    vector?: number[] | null;
+    updatedAt: string;
+}
+export interface UpsertDocumentsRequest {
+    documents: VectorDocument[];
+}
+export interface UpsertDocumentsResponse {
+    upserted: number;
+    /** How many of them mybase embedded. */
+    embedded: number;
+}
+export interface DeleteDocumentsRequest {
+    ids?: string[];
+    /** Deletes every document whose metadata contains this object. */
+    filter?: VectorMetadata;
+}
+export interface DeleteDocumentsResponse {
+    deleted: number;
+}
+export interface ListDocumentsResponse<M extends VectorMetadata = VectorMetadata> {
+    documents: StoredDocument<M>[];
+    /** Pass as `after` for the next page; null at the end. */
+    next: string | null;
+}
+export interface VectorQueryRequest {
+    /** Keywords for text search, and embedded for vector search when no `vector` is given. */
+    text?: string;
+    vector?: number[];
+    /** Default: `hybrid` when both a vector (given or embedded) and text are available, else whichever is. */
+    mode?: VectorQueryMode;
+    /** 1–100, default 10. */
+    topK?: number;
+    /** Only documents whose metadata contains this object, e.g. `{ lang: "en" }`. */
+    filter?: VectorMetadata;
+    /** Hybrid only: weight of the vector ranking, 0–1 (text gets the rest). Default 0.5. */
+    alpha?: number;
+    /** Return each match's text. Default true. */
+    includeText?: boolean;
+    includeVectors?: boolean;
+    /** Text and hybrid: a snippet with matched words wrapped in `<b>…</b>`. */
+    highlight?: boolean;
+}
+export interface VectorMatch<M extends VectorMetadata = VectorMetadata> {
+    id: string;
+    /**
+     * Higher is better. text: ts_rank_cd. vector: cosine similarity (cosine), negative distance (l2),
+     * or inner product (ip). hybrid: reciprocal rank fusion.
+     */
+    score: number;
+    title: string | null;
+    text?: string;
+    metadata: M;
+    vector?: number[] | null;
+    highlight?: string;
+}
+export interface VectorQueryResponse<M extends VectorMetadata = VectorMetadata> {
+    mode: VectorQueryMode;
+    matches: VectorMatch<M>[];
+}
+/** The project's embedding provider: any OpenAI-compatible `POST <url>/embeddings`. */
+export interface EmbeddingSettings {
+    /** e.g. `https://api.openai.com/v1` or `http://ollama.lan:11434/v1`. */
+    url: string;
+    model: string;
+    /** Vector length the model returns. */
+    dimensions: number;
+    /** Whether an API key is stored (it's never returned). */
+    hasKey: boolean;
+}
+export interface VectorServiceSettings {
+    /** The API's public URL, for `createVectorClient({ apiUrl })`. */
+    apiUrl: string;
+    embedding: EmbeddingSettings | null;
+    enabledAt: string;
+}
+export interface VectorClientOptions {
+    /** 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 `vector:write` for this project (`vector:read` is enough to query). Server-side only. */
+    apiKey: string;
+    /** How long to wait for mybase, in ms. Default 30000 (embedding can take a while). */
+    timeoutMs?: number;
+    /** Default `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export type QueryOptions = Omit<VectorQueryRequest, "text">;
+export interface VectorIndexClient<M extends VectorMetadata = VectorMetadata> {
+    readonly name: string;
+    /** Inserts or replaces documents by id, up to 100 per call. */
+    upsert(documents: VectorDocument<M> | VectorDocument<M>[]): Promise<UpsertDocumentsResponse>;
+    /** Documents by id; missing ones are left out. */
+    get(ids: string | string[], options?: {
+        includeVectors?: boolean;
+    }): Promise<StoredDocument<M>[]>;
+    /** By ids, or by `{ filter }`. */
+    delete(target: string | string[] | {
+        filter: Partial<M> & VectorMetadata;
+    }): Promise<DeleteDocumentsResponse>;
+    /** Search by text (`query("…")`), or pass a full request (`query({ vector, filter })`). */
+    query(query: string | VectorQueryRequest, options?: QueryOptions): Promise<VectorQueryResponse<M>>;
+    /** Pages through documents in id order. */
+    list(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<ListDocumentsResponse<M>>;
+    info(): Promise<VectorIndex>;
+}
+export interface VectorClient {
+    index<M extends VectorMetadata = VectorMetadata>(name: string): VectorIndexClient<M>;
+    listIndexes(): Promise<VectorIndex[]>;
+    getIndex(name: string): Promise<VectorIndex>;
+    /** Idempotent: an existing index with the same settings is returned as is. */
+    createIndex(name: string, settings?: VectorIndexInput): Promise<VectorIndex>;
+    /** Only `embed` can change. */
+    updateIndex(name: string, settings: {
+        embed: boolean;
+    }): Promise<VectorIndex>;
+    /** Deletes the index and all its documents. */
+    deleteIndex(name: string): Promise<void>;
+}
+export declare function createVectorClient(options: VectorClientOptions): VectorClient;
+/**
+ * A tool for an LLM agent, independent of the provider. Map it to yours:
+ * Anthropic `{ name, description, input_schema: inputSchema }`,
+ * OpenAI `{ type: "function", function: { name, description, parameters: inputSchema } }`.
+ */
+export interface RetrievalTool {
+    name: string;
+    description: string;
+    inputSchema: ToolInputSchema;
+    /** Runs the search and returns text for the tool result. Fixable problems come back as `Error: …`. */
+    run(input: unknown): Promise<string>;
+}
+export interface RetrievalToolOptions {
+    /** Default `search_documents`. */
+    name?: string;
+    /** What the index holds, for the model, e.g. "the product documentation". */
+    about?: string;
+    /** Matches returned. Default 5. */
+    topK?: number;
+    /** Applied to every search (e.g. the signed-in user's tenant). */
+    filter?: VectorMetadata;
+    mode?: VectorQueryMode;
+    /** Most characters of each match's text. Default 2000. */
+    maxChars?: number;
+}
+/** A retrieval tool over one index, ready for an LLM tool-use loop (RAG). */
+export declare function retrievalTool(index: VectorIndexClient, options?: RetrievalToolOptions): RetrievalTool;