@riloservices/base 0.0.0-stage → 0.1.0

package/dist/cli.mjs

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+// ../shared/src/connect.ts
+/**
+* The fixed options of every link, in this order. `directConnection` keeps the driver talking only
+* to the Gateway; DocumentDB has no retryable writes; logins live in `admin`; `maxPoolSize=10`
+* fits 4 app instances in the Seed limit of 50, with 2 monitoring connections each (decision Q3).
+*/
+const CONNECT_OPTIONS = {
+	tls: true,
+	directConnection: true,
+	retryWrites: false,
+	authSource: "admin",
+	maxPoolSize: 10
+};
+// ../shared/src/logins.ts
+/**
+* The rule for a password the person chooses (step 11): 16 to 64 letters, digits, `-` and `_`.
+* These are the characters a `mongodb://` link carries without encoding. Rilo's own suggestion is
+* 24 random bytes in base64url (32 characters), which always passes.
+*/
+const LOGIN_PASSWORD = {
+	min: 16,
+	max: 64,
+	pattern: /^[A-Za-z0-9_-]+$/
+};
+// ../shared/src/regions.ts
+const REGION_CODES = ["in", "au"];
+const SPACE_ID_PATTERN = new RegExp(`^[bcdfghjkmnpqrstvwxz23456789]{8}$`);
+function isSpaceId(value) {
+	return SPACE_ID_PATTERN.test(value);
+}
+// ../shared/src/app-keys.ts
+/** Every app key starts with this, so people, scanners and the Files service recognise one. */
+const APP_KEY_PREFIX = "rilo_";
+/** The environment variable an app keeps its key in. */
+const APP_KEY_ENV_VAR = "RILO_KEY";
+/**
+* An app key's name is also its login's and its files key's name, so it follows both rules:
+* lowercase letters, digits and single hyphens, starting with a letter, 3 to 32 characters.
+*/
+const APP_KEY_NAME = {
+	min: 3,
+	max: 32,
+	pattern: /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/
+};
+/** The files secret: 32 random bytes in base64url, 43 characters. */
+const FILES_SECRET = /^[A-Za-z0-9_-]{43}$/;
+const IDENTITY = /^rilo_([a-z]+)_([a-z0-9]+)$/;
+/** What is wrong with an app key name, in plain words, or null. Nothing is trimmed or lowered. */
+function appKeyNameProblem(name) {
+	if (name === "") return "Enter a name for the key.";
+	if (name.trim() !== name) return "Remove the spaces at the start or end of the name.";
+	if (/\s/.test(name)) return "Use hyphens instead of spaces, like web-app.";
+	if (/[A-Z]/.test(name)) return "Use lowercase letters only, like web-app.";
+	if (!/^[a-z0-9-]+$/.test(name)) return "Use only lowercase letters, digits and hyphens.";
+	if (!/^[a-z]/.test(name)) return "Start the name with a letter.";
+	if (name.includes("--")) return "Use single hyphens, never two in a row.";
+	if (name.endsWith("-")) return "End the name with a letter or digit, not a hyphen.";
+	if (name.length < APP_KEY_NAME.min) return `Use at least ${APP_KEY_NAME.min} characters.`;
+	if (name.length > APP_KEY_NAME.max) return `Use ${APP_KEY_NAME.max} characters or fewer.`;
+	return null;
+}
+function isDatabaseSecret(value) {
+	return LOGIN_PASSWORD.pattern.test(value) && value.length >= LOGIN_PASSWORD.min && value.length <= LOGIN_PASSWORD.max;
+}
+function isRegion(value) {
+	return REGION_CODES.includes(value);
+}
+/**
+* The parts of an app key, or null when the text isn't exactly one. Strict: anything else, even
+* with the right prefix, is refused. It says nothing about whether the key is real.
+*/
+function parseAppKey(key) {
+	if (!key.startsWith("rilo_")) return null;
+	const pieces = key.split(".");
+	if (pieces.length !== 4) return null;
+	const [identity = "", name = "", databaseSecret = "", filesSecret = ""] = pieces;
+	const match = IDENTITY.exec(identity);
+	const region = match?.[1];
+	const spaceId = match?.[2];
+	if (region === void 0 || spaceId === void 0) return null;
+	if (!isRegion(region) || !isSpaceId(spaceId)) return null;
+	if (appKeyNameProblem(name) !== null) return null;
+	if (!isDatabaseSecret(databaseSecret) || !FILES_SECRET.test(filesSecret)) return null;
+	return {
+		region,
+		spaceId,
+		name,
+		databaseSecret,
+		filesSecret
+	};
+}
+/** The `mongodb://` link MongoDB drivers and tools need, with the password in it. */
+function mongoLink(link) {
+	const options = Object.entries(CONNECT_OPTIONS).map(([key, value]) => `${key}=${value}`);
+	if (link.tlsCAFile) options.push(`tlsCAFile=${encodeURIComponent(link.tlsCAFile)}`);
+	const path = link.databaseRealName ? encodeURIComponent(link.databaseRealName) : "";
+	return `mongodb://${`${encodeURIComponent(link.loginRealName)}:${encodeURIComponent(link.password)}`}@${link.host}:${link.port}/${path}?${options.join("&")}`;
+}
+/** Everything an app needs from its key: the same values the Connect card shows. */
+function appKeyValues(parts, addresses, database) {
+	const loginRealName = `${parts.name}_${parts.spaceId}`;
+	const host = `${parts.spaceId}.${parts.region}.${addresses.spacesDomain}`;
+	return {
+		loginRealName,
+		filesKey: `rdbf_${parts.spaceId}_${parts.filesSecret}`,
+		host,
+		filesUrl: addresses.filesUrl,
+		connectLink: mongoLink({
+			loginRealName,
+			password: parts.databaseSecret,
+			host,
+			port: addresses.port,
+			databaseRealName: database ? `${database}_${parts.spaceId}` : null,
+			tlsCAFile: addresses.tlsCAFile
+		}),
+		rilodbLink: formatRilodbLink(parts, addresses, database)
+	};
+}
+/** The environment variable for a `rilodb://` link. */
+const RILODB_LINK_ENV_VAR = "RILODB_URL";
+/** The `rilodb://` link of a key, naming `database` when one is given. */
+function formatRilodbLink(parts, addresses, database) {
+	const port = addresses.port === 27017 ? "" : `:${addresses.port}`;
+	const host = `${parts.spaceId}.${parts.region}.${addresses.spacesDomain}${port}`;
+	const path = database ? encodeURIComponent(database) : "";
+	return `rilodb://${parts.name}:${parts.databaseSecret}@${host}/${path}`;
+}
+// src/errors.ts
+/** The key or link is missing or isn't an app key or a `rilodb://` link. The message never repeats it. */
+var RiloKeyError = class extends Error {
+	name = "RiloKeyError";
+};
+const MISSING = `No app key was given. Set ${APP_KEY_ENV_VAR} to your app key from the App keys page of your Space, on your server, and pass it in.`;
+const MISSING_EITHER = `${MISSING} A rilodb:// link works too, for databases only.`;
+const FILES_KEY = `That is a files key (it starts with rdbf_), not an app key. Use the app key, which starts with ${APP_KEY_PREFIX}. It works for databases and Files.`;
+const MONGO_LINK = `That is a mongodb:// connect link, not an app key. Use the app key, which starts with ${APP_KEY_PREFIX}. It works for databases and Files. MongoDB drivers and tools use the mongodb:// link; this client reads the app key.`;
+const MONGO_LINK_EITHER = `That is a mongodb:// connect link, not an app key or a rilodb:// link. Use the app key, which starts with ${APP_KEY_PREFIX}, or the rilodb:// link. MongoDB drivers and tools use the mongodb:// link; this client reads the app key or the rilodb:// link.`;
+const RILODB_LINK = `That is a rilodb:// link, not an app key. This needs the app key (${APP_KEY_ENV_VAR}), which starts with ${APP_KEY_PREFIX}. A rilodb:// link holds only the database part.`;
+const MALFORMED = `That is not a valid app key. An app key starts with ${APP_KEY_PREFIX} and has four parts separated by dots. Copy the whole key again from the App keys page. A lost key can't be shown again, so reset it there.`;
+const MALFORMED_EITHER = `That is not a valid app key or rilodb:// link. An app key starts with ${APP_KEY_PREFIX} and has four parts separated by dots. Copy the whole key again from the App keys page. A lost key can't be shown again, so reset it there.`;
+const isRilodbLink = (text) => /^rilodb:\/\//i.test(text);
+const isMongoLink = (text) => /^mongodb(\+srv)?:\/\//i.test(text);
+/**
+* The text of a key, trimmed, or a `RiloKeyError` that says what was given instead. `orLink` words
+* the refusals for a place that takes a `rilodb://` link too. No message repeats any of the input.
+*/
+function keyText(key, orLink) {
+	if (key === void 0 || key === null || typeof key === "string" && key.trim() === "") throw new RiloKeyError(orLink ? MISSING_EITHER : MISSING);
+	if (typeof key !== "string") throw new RiloKeyError(orLink ? MALFORMED_EITHER : MALFORMED);
+	const text = key.trim();
+	if (text.startsWith("rdbf_")) throw new RiloKeyError(FILES_KEY);
+	if (isMongoLink(text)) throw new RiloKeyError(orLink ? MONGO_LINK_EITHER : MONGO_LINK);
+	if (isRilodbLink(text)) throw new RiloKeyError(RILODB_LINK);
+	return text;
+}
+function resolveAppKey(text, orLink, options, database) {
+	const parts = parseAppKey(text);
+	if (parts === null) throw new RiloKeyError(orLink ? MALFORMED_EITHER : MALFORMED);
+	const spacesDomain = options.spacesDomain ?? "db.services.rilo.studio";
+	const filesUrl = (options.filesUrl ?? `https://files.${parts.region}.${spacesDomain}`).replace(/\/+$/, "");
+	return {
+		parts,
+		values: appKeyValues(parts, {
+			spacesDomain,
+			port: options.port ?? 27017,
+			filesUrl,
+			tlsCAFile: options.tlsCAFile
+		}, database)
+	};
+}
+/**
+* The app key's parts and the values built from them, or a `RiloKeyError`. The error says what is
+* wrong and never contains any part of the key. A `rilodb://` link is refused: this is for what
+* needs the whole key.
+*/
+function resolveKey(key, options = {}, database) {
+	return resolveAppKey(keyText(key, false), false, options, database);
+}
+// src/env-command.ts
+const KEY_VAR = "RILO_KEY";
+const HELP = `rilo-db: tools for your Rilo DB app key
+
+Usage:
+  rilo-db env [--database <name>]   Print RILODB_URI, RILODB_URL, RILO_FILES_URL and RILO_FILES_KEY
+  rilo-db --help                    Show this help
+
+Use "env" when a tool or language needs the plain values: Compass, mongosh, Python, Go or Mongoose
+set up on its own. It reads ${KEY_VAR} from the environment, or from a .env file in this folder. It
+runs on your machine and sends nothing anywhere.
+
+What it prints:
+  RILODB_URI       The mongodb:// link, for MongoDB drivers and tools
+  RILODB_URL       The rilodb:// link, for the Rilo client (databases only; drivers can't read it)
+  RILO_FILES_URL   The Files address
+  RILO_FILES_KEY   The files key
+
+The output holds your secrets. Keep it out of chat, tickets, logs and git.
+
+Options:
+  --database <name>   Put this database in both links, by the name you gave it, like salon-prod
+  -h, --help          Show this help
+`;
+/**
+* The value of `name` in the text of a `.env` file, or undefined. Handles `export`, comments, quotes
+* and Windows line endings; it expands nothing. The last line that sets it wins.
+*/
+function readDotenvValue(text, name) {
+	const body = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+	let found;
+	for (const raw of body.split(/\r?\n/)) {
+		const line = raw.trim().replace(/^export\s+/, "");
+		if (line === "" || line.startsWith("#")) continue;
+		const equals = line.indexOf("=");
+		if (equals === -1 || line.slice(0, equals).trim() !== name) continue;
+		const value = line.slice(equals + 1).trim();
+		const quote = value[0];
+		if ((quote === "\"" || quote === "'") && value.indexOf(quote, 1) > 0) found = value.slice(1, value.indexOf(quote, 1));
+		else found = value.replace(/\s+#.*$/, "");
+	}
+	return found;
+}
+function readKey(context) {
+	const fromEnv = context.env[KEY_VAR];
+	if (fromEnv !== void 0 && fromEnv.trim() !== "") return fromEnv;
+	try {
+		const fromFile = readDotenvValue(readFileSync(join(context.cwd, ".env"), "utf8"), KEY_VAR);
+		return fromFile === void 0 || fromFile.trim() === "" ? void 0 : fromFile;
+	} catch {
+		return;
+	}
+}
+/** Reads `--database <name>` or `--database=<name>`; a string when something is wrong. */
+function readOptions(args) {
+	let database;
+	let help = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index] ?? "";
+		if (arg === "-h" || arg === "--help") help = true;
+		else if (arg === "--database") {
+			index += 1;
+			database = args[index];
+			if (database === void 0 || database.startsWith("-")) return "--database needs a name.";
+		} else if (arg.startsWith("--database=")) database = arg.slice(11);
+		else return `Unknown option ${arg}.`;
+	}
+	if (database === "") return "--database needs a name.";
+	return {
+		database,
+		help
+	};
+}
+/** Runs the `rilo-db` command and returns its exit code. It never prints the key. */
+function runCli(argv, context) {
+	const [command, ...rest] = argv;
+	if (command === void 0 || command === "-h" || command === "--help" || command === "help") {
+		if (command === void 0) {
+			context.stderr(HELP);
+			return 1;
+		}
+		context.stdout(HELP);
+		return 0;
+	}
+	if (command !== "env") {
+		context.stderr(`rilo-db: Unknown command ${command}. Run rilo-db --help.\n`);
+		return 1;
+	}
+	const options = readOptions(rest);
+	if (typeof options === "string") {
+		context.stderr(`rilo-db: ${options} Run rilo-db --help.\n`);
+		return 1;
+	}
+	if (options.help) {
+		context.stdout(HELP);
+		return 0;
+	}
+	const key = readKey(context);
+	if (key === void 0) {
+		context.stderr(`rilo-db: ${KEY_VAR} is not set. Put it in your environment or in a .env file in this folder.\n`);
+		return 1;
+	}
+	try {
+		const { values } = resolveKey(key, {}, options.database);
+		context.stdout([
+			`RILODB_URI=${values.connectLink}`,
+			`${RILODB_LINK_ENV_VAR}=${values.rilodbLink}`,
+			`RILO_FILES_URL=${values.filesUrl}`,
+			`RILO_FILES_KEY=${values.filesKey}`,
+			""
+		].join("\n"));
+		return 0;
+	} catch (error) {
+		if (!(error instanceof RiloKeyError)) throw error;
+		context.stderr(`rilo-db: ${error.message}\n`);
+		return 1;
+	}
+}
+// src/cli.ts
+process.exitCode = runCli(process.argv.slice(2), {
+	env: process.env,
+	cwd: process.cwd(),
+	stdout: (text) => process.stdout.write(text),
+	stderr: (text) => process.stderr.write(text)
+});
+export {};

package/dist/errors-DwVg5fNj.d.cts

@@ -0,0 +1,24 @@
+/** The key or link is missing or isn't an app key or a `rilodb://` link. The message never repeats it. */
+declare class RiloKeyError extends Error {
+  readonly name = "RiloKeyError";
+}
+/** What the Files API answers when a call fails: its `error` body, plus the HTTP status. */
+declare class RiloFilesError extends Error {
+  readonly name = "RiloFilesError";
+  /** The HTTP status. */
+  readonly status: number;
+  /** A stable name for the error, like `read_only_key`. Decide what to do from this. */
+  readonly code: string;
+  /** Extra data for some codes, like `maxFileSize` on `file_too_large`. */
+  readonly details: Record<string, unknown> | null;
+  /** On `validation_failed`: each field that needs fixing, with what to fix. */
+  readonly fields: Record<string, string> | null;
+  constructor(init: {
+    status: number;
+    code: string;
+    message: string;
+    details?: Record<string, unknown> | null;
+    fields?: Record<string, string> | null;
+  });
+}
+export { RiloKeyError as n, RiloFilesError as t };

package/dist/errors-DwVg5fNj.d.mts

@@ -0,0 +1,24 @@
+/** The key or link is missing or isn't an app key or a `rilodb://` link. The message never repeats it. */
+declare class RiloKeyError extends Error {
+  readonly name = "RiloKeyError";
+}
+/** What the Files API answers when a call fails: its `error` body, plus the HTTP status. */
+declare class RiloFilesError extends Error {
+  readonly name = "RiloFilesError";
+  /** The HTTP status. */
+  readonly status: number;
+  /** A stable name for the error, like `read_only_key`. Decide what to do from this. */
+  readonly code: string;
+  /** Extra data for some codes, like `maxFileSize` on `file_too_large`. */
+  readonly details: Record<string, unknown> | null;
+  /** On `validation_failed`: each field that needs fixing, with what to fix. */
+  readonly fields: Record<string, string> | null;
+  constructor(init: {
+    status: number;
+    code: string;
+    message: string;
+    details?: Record<string, unknown> | null;
+    fields?: Record<string, string> | null;
+  });
+}
+export { RiloKeyError as n, RiloFilesError as t };

package/dist/index.cjs

@@ -0,0 +1,124 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_key = require("./key-DPXUxbGX.cjs");
+let mongodb = require("mongodb");
+// src/files.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One part of a path through `encodeURIComponent`, plus the `!'()*` it leaves as they are. */
+function encodeSegment(segment) {
+	return encodeURIComponent(segment).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/** A file path as it goes in a URL: each part encoded, the slashes between them kept. */
+function encodePath(path) {
+	return path.split("/").map(encodeSegment).join("/");
+}
+/** The Files API's `error` body, as a `RiloFilesError`. Anything that isn't one still gets a status. */
+async function toError(response) {
+	let error = {};
+	try {
+		const body = await response.json();
+		if (isRecord(body) && isRecord(body.error)) error = body.error;
+	} catch {}
+	const { code, message, details, fields } = error;
+	return new require_key.RiloFilesError({
+		status: response.status,
+		code: typeof code === "string" ? code : `http_${response.status}`,
+		message: typeof message === "string" ? message : `The Files API answered with status ${response.status}.`,
+		details: isRecord(details) ? details : null,
+		fields: isRecord(fields) ? fields : null
+	});
+}
+/**
+* The Files API client. `filesKey` is the `rdbf_…` part of the app key: it is the only secret that
+* is ever sent, and only in the `Authorization` header.
+*/
+function createFiles(baseUrl, filesKey) {
+	async function call(method, path, body) {
+		const headers = {
+			authorization: `Bearer ${filesKey}`,
+			accept: "application/json"
+		};
+		if (body !== void 0) headers["content-type"] = "application/json";
+		const response = await fetch(`${baseUrl}${path}`, {
+			method,
+			headers,
+			body: body === void 0 ? void 0 : JSON.stringify(body)
+		});
+		if (!response.ok) throw await toError(response);
+		if (response.status === 204) return void 0;
+		return response.json();
+	}
+	function bucket(name) {
+		const root = `/v1/buckets/${encodeURIComponent(name)}`;
+		async function makeLinks(target, options) {
+			const body = options?.expiresInSeconds === void 0 ? target : {
+				...target,
+				expiresInSeconds: options.expiresInSeconds
+			};
+			return (await call("POST", `${root}/links`, body)).links;
+		}
+		return {
+			createUpload: async (body) => await call("POST", `${root}/uploads`, body),
+			cancelUpload: async (uploadId) => {
+				await call("DELETE", `/v1/uploads/${encodeURIComponent(uploadId)}`);
+			},
+			link: async (path, options) => {
+				const [link] = await makeLinks({ path }, options);
+				if (link === void 0) throw new Error("The Files API answered without a link.");
+				return link;
+			},
+			links: (paths, options) => makeLinks({ paths }, options),
+			list: async (query = {}) => {
+				const params = new URLSearchParams();
+				if (query.prefix !== void 0) params.set("prefix", query.prefix);
+				if (query.delimiter !== void 0) params.set("delimiter", query.delimiter);
+				if (query.cursor !== void 0) params.set("cursor", query.cursor);
+				if (query.limit !== void 0) params.set("limit", String(query.limit));
+				const search = params.size === 0 ? "" : `?${params.toString()}`;
+				return await call("GET", `${root}/files${search}`);
+			},
+			get: async (path) => await call("GET", `${root}/files/${encodePath(path)}`),
+			delete: async (path) => {
+				await call("DELETE", `${root}/files/${encodePath(path)}`);
+			}
+		};
+	}
+	return {
+		buckets: async () => await call("GET", "/v1/buckets"),
+		bucket
+	};
+}
+// src/index.ts
+const FILES_NEED_KEY = "Files needs your app key (RILO_KEY). A rilodb:// link holds only the database part.";
+/**
+* Turns an app key, or a `rilodb://` link, into everything an app needs. The app key (`rilo_…`)
+* works for databases and Files. A `rilodb://` link works for databases only, and brings its own
+* address and default database. Throws a `RiloKeyError` when the input is missing or is neither;
+* the message says what was given and never repeats it. Nothing connects until `db()` is first used.
+*/
+function createClient(keyOrLink, options = {}) {
+	const target = require_key.resolveTarget(keyOrLink, options);
+	const files = target.files === null ? null : createFiles(target.files.url, target.files.key);
+	let mongo;
+	return {
+		db(name) {
+			const database = name ?? options.database ?? target.database ?? void 0;
+			if (database === void 0 || database === "") throw new TypeError("Say which database to open: db(\"name\"), or give createClient a `database` option.");
+			mongo ??= new mongodb.MongoClient(target.connectLink, options.appName === void 0 ? void 0 : { appName: options.appName });
+			return mongo.db(`${database}_${target.spaceId}`);
+		},
+		get files() {
+			if (files === null) throw new require_key.RiloKeyError(FILES_NEED_KEY);
+			return files;
+		},
+		async close() {
+			const open = mongo;
+			mongo = void 0;
+			await open?.close();
+		}
+	};
+}
+exports.RiloFilesError = require_key.RiloFilesError;
+exports.RiloKeyError = require_key.RiloKeyError;
+exports.createClient = createClient;

package/dist/index.d.cts

@@ -0,0 +1,57 @@
+import { a as FileList, c as LinkOptions, d as UploadTicket, i as FileLink, l as ListFilesQuery, n as FileEntry, o as FilesBucketView, r as FileInfo, s as FilesBuckets, t as AddressOptions, u as UploadBody } from "./types-CD9NBWdA.cjs";
+import { n as RiloKeyError, t as RiloFilesError } from "./errors-DwVg5fNj.cjs";
+import { Db } from "mongodb";
+/** What an app does with one bucket. */
+interface RiloBucket {
+  /**
+   * Asks for a signed upload for one file. Send it to the browser, which posts the file straight
+   * to storage with `sendUpload` from `@riloservices/base/browser`. Needs a Read and write key.
+   */
+  createUpload(body: UploadBody): Promise<UploadTicket>;
+  /** Releases an upload's hold on storage at once. Stop the browser's request first. */
+  cancelUpload(uploadId: string): Promise<void>;
+  /** A link to one file. A private bucket's link expires, one hour later unless you say. */
+  link(path: string, options?: LinkOptions): Promise<FileLink>;
+  /** Links to up to 100 files, in the order asked. */
+  links(paths: string[], options?: LinkOptions): Promise<FileLink[]>;
+  list(query?: ListFilesQuery): Promise<FileList>;
+  get(path: string): Promise<FileInfo>;
+  /** Needs a Read and write key. */
+  delete(path: string): Promise<void>;
+}
+/** The Files API, called with the files part of the app key. */
+interface RiloFiles {
+  buckets(): Promise<FilesBuckets>;
+  bucket(name: string): RiloBucket;
+}
+export interface ClientOptions extends AddressOptions {
+  /**
+   * The database `db()` opens when you give it no name. With a `rilodb://` link, the link's own
+   * database is the default when this isn't given.
+   */
+  database?: string;
+  /** Shown in the Gateway's connection details, to tell apps apart. */
+  appName?: string;
+}
+export interface RiloClient {
+  /**
+   * The MongoDB driver's own `Db`. Use the name you gave the database, like `salon-prod`: the
+   * client adds the Space's id. With no name, it opens `options.database`.
+   */
+  db(name?: string): Db;
+  /**
+   * The Files API, with the files part of your app key. A `rilodb://` link has no files part, so
+   * with one, using `files` throws a `RiloKeyError`.
+   */
+  readonly files: RiloFiles;
+  /** Closes the database connections. Call it when your app shuts down. */
+  close(): Promise<void>;
+}
+/**
+ * Turns an app key, or a `rilodb://` link, into everything an app needs. The app key (`rilo_…`)
+ * works for databases and Files. A `rilodb://` link works for databases only, and brings its own
+ * address and default database. Throws a `RiloKeyError` when the input is missing or is neither;
+ * the message says what was given and never repeats it. Nothing connects until `db()` is first used.
+ */
+export declare function createClient(keyOrLink: string | null | undefined, options?: ClientOptions): RiloClient;
+export { type AddressOptions, type FileEntry, type FileInfo, type FileLink, type FileList, type FilesBucketView, type FilesBuckets, type LinkOptions, type ListFilesQuery, type RiloBucket, type RiloFiles, RiloFilesError, RiloKeyError, type UploadBody, type UploadTicket };

package/dist/index.d.mts

@@ -0,0 +1,57 @@
+import { a as FileList, c as LinkOptions, d as UploadTicket, i as FileLink, l as ListFilesQuery, n as FileEntry, o as FilesBucketView, r as FileInfo, s as FilesBuckets, t as AddressOptions, u as UploadBody } from "./types-CD9NBWdA.mjs";
+import { n as RiloKeyError, t as RiloFilesError } from "./errors-DwVg5fNj.mjs";
+import { Db } from "mongodb";
+/** What an app does with one bucket. */
+interface RiloBucket {
+  /**
+   * Asks for a signed upload for one file. Send it to the browser, which posts the file straight
+   * to storage with `sendUpload` from `@riloservices/base/browser`. Needs a Read and write key.
+   */
+  createUpload(body: UploadBody): Promise<UploadTicket>;
+  /** Releases an upload's hold on storage at once. Stop the browser's request first. */
+  cancelUpload(uploadId: string): Promise<void>;
+  /** A link to one file. A private bucket's link expires, one hour later unless you say. */
+  link(path: string, options?: LinkOptions): Promise<FileLink>;
+  /** Links to up to 100 files, in the order asked. */
+  links(paths: string[], options?: LinkOptions): Promise<FileLink[]>;
+  list(query?: ListFilesQuery): Promise<FileList>;
+  get(path: string): Promise<FileInfo>;
+  /** Needs a Read and write key. */
+  delete(path: string): Promise<void>;
+}
+/** The Files API, called with the files part of the app key. */
+interface RiloFiles {
+  buckets(): Promise<FilesBuckets>;
+  bucket(name: string): RiloBucket;
+}
+export interface ClientOptions extends AddressOptions {
+  /**
+   * The database `db()` opens when you give it no name. With a `rilodb://` link, the link's own
+   * database is the default when this isn't given.
+   */
+  database?: string;
+  /** Shown in the Gateway's connection details, to tell apps apart. */
+  appName?: string;
+}
+export interface RiloClient {
+  /**
+   * The MongoDB driver's own `Db`. Use the name you gave the database, like `salon-prod`: the
+   * client adds the Space's id. With no name, it opens `options.database`.
+   */
+  db(name?: string): Db;
+  /**
+   * The Files API, with the files part of your app key. A `rilodb://` link has no files part, so
+   * with one, using `files` throws a `RiloKeyError`.
+   */
+  readonly files: RiloFiles;
+  /** Closes the database connections. Call it when your app shuts down. */
+  close(): Promise<void>;
+}
+/**
+ * Turns an app key, or a `rilodb://` link, into everything an app needs. The app key (`rilo_…`)
+ * works for databases and Files. A `rilodb://` link works for databases only, and brings its own
+ * address and default database. Throws a `RiloKeyError` when the input is missing or is neither;
+ * the message says what was given and never repeats it. Nothing connects until `db()` is first used.
+ */
+export declare function createClient(keyOrLink: string | null | undefined, options?: ClientOptions): RiloClient;
+export { type AddressOptions, type FileEntry, type FileInfo, type FileLink, type FileList, type FilesBucketView, type FilesBuckets, type LinkOptions, type ListFilesQuery, type RiloBucket, type RiloFiles, RiloFilesError, RiloKeyError, type UploadBody, type UploadTicket };