@riloservices/base 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rilo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,256 @@
-# Temporary Holding Version
+# @riloservices/base
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use a [Rilo DB](https://db.services.rilo.studio) Space from your server with one app key. The key works for your databases and for Files.
+
+- **Databases.** `rilo.db('name')` gives you the MongoDB driver's own `Db`. Everything you know about the driver still applies.
+- **Files.** Ask for an upload, send the file from the browser straight to storage, and make links to files.
+- **Mongoose.** One call connects it with the same key.
+- **A `rilodb://` link**, if you only need the database. See [below](#the-rilodb-link-databases-only).
+
+Rilo DB works with MongoDB drivers and tools. MongoDB is a trademark of MongoDB, Inc.; Rilo DB is not affiliated with or endorsed by it.
+
+## Install
+
+```bash
+npm install @riloservices/base
+```
+
+This also installs the official MongoDB driver (`mongodb`, version 6.10 or later): it's a peer dependency, so your app keeps one copy of it, and npm, pnpm and Bun add it for you. With Yarn, add it yourself: `yarn add @riloservices/base mongodb`.
+
+It needs Node 20.19 or later, and works from ES modules and from CommonJS.
+
+## Your app key
+
+Make an app key on the **App keys** page of your Space. It looks like this:
+
+```text
+rilo_in_k3m9x2qz.app.<database secret>.<files secret>
+```
+
+It is shown once, so copy it straight away. Put it in your server's environment as `RILO_KEY`:
+
+```bash
+# .env (on your server, never in git)
+RILO_KEY=rilo_in_k3m9x2qz.app.…
+```
+
+**Keep `RILO_KEY` on your server.** Never put it in browser code, a mobile app or a public repository. The key can read and write your data, so treat it like a password. If it leaks, reset it on the App keys page.
+
+`RILO_KEY` is the main way in, and the only value your app needs: it works for your databases and for Files.
+
+### Allow your app's address
+
+Your Space only accepts database connections from its **Allowed places**. Before your app connects, add the address of the server it runs on (and your own, while you develop): open your Space, then **Settings**, then **Allowed places**. Until then, database calls fail to connect. Files doesn't use Allowed places, so it works from anywhere with the key.
+
+## The `rilodb://` link (databases only)
+
+If a service only needs a database, give it a `rilodb://` link instead of the whole key. `rilo-db env` prints one from your key (see [below](#the-rilo-db-env-command)). It looks like this:
+
+```text
+rilodb://app:<database secret>@k3m9x2qz.in.db.services.rilo.studio/salon-prod
+```
+
+It holds the key's name, the database secret, the address and a database name, using the names you chose. Put it in the environment as `RILODB_URL` and pass it to the same functions:
+
+```js
+const rilo = createClient(process.env.RILODB_URL);
+const bookings = rilo.db().collection('bookings'); // the database the link names
+```
+
+- **Only this package reads it.** MongoDB drivers and tools accept only `mongodb://` or `mongodb+srv://` links, so they can't use a `rilodb://` link. Give them the `mongodb://` link, which is `RILODB_URI` in the output of `rilo-db env`.
+- **Databases only.** The link has no files part. Using `rilo.files` with it throws a `RiloKeyError`: Files needs your app key (`RILO_KEY`).
+- **It brings its own address.** The `spacesDomain` and `port` options are ignored with a link. `tlsCAFile` and `appName` still apply.
+- **The link's database is the default.** `rilo.db()` opens it. A `database` option or a name given to `rilo.db('name')` wins.
+- **It holds a secret.** Treat `RILODB_URL` like `RILO_KEY`: keep it on your server, out of git and logs. If it leaks, reset the key on the App keys page.
+
+## Quick start
+
+```js
+import { createClient } from '@riloservices/base';
+
+const rilo = createClient(process.env.RILO_KEY);
+
+// Databases: use the name you gave the database. The client adds your Space's id for you.
+const bookings = rilo.db('salon-prod').collection('bookings');
+await bookings.insertOne({ client: 'Aroha', at: new Date() });
+console.log(await bookings.find({ client: 'Aroha' }).toArray());
+
+// Close the connections when your app shuts down.
+await rilo.close();
+```
+
+`createClient` checks the key straight away and throws a [`RiloKeyError`](#errors) if it is missing or isn't an app key (or a `rilodb://` link). Nothing connects until you first call `rilo.db()`, and then one connection pool is opened and reused.
+
+### Upload a file from the browser
+
+Files don't pass through your server or through Rilo. Your server asks for a signed upload, the browser sends the file straight to storage with it, and the upload carries no key.
+
+On your server:
+
+```js
+const photos = rilo.files.bucket('photos');
+
+// For example in a route that your page calls before it uploads.
+const ticket = await photos.createUpload({
+  path: 'avatars/user-42.jpg',
+  contentType: 'image/jpeg',
+  size: 204800, // the file's exact size in bytes
+});
+// Send `ticket` to the browser as JSON.
+```
+
+In the browser:
+
+```js
+import { sendUpload } from '@riloservices/base/browser';
+
+await sendUpload(ticket, file); // `file` is a File or Blob
+```
+
+`sendUpload` posts every signed field, then the file last, with no `Authorization` header. If storage refuses the file, it throws a `RiloUploadError` with storage's own status and reason. The upload link lasts 10 minutes. If a person cancels, stop the browser's request first (pass an `AbortSignal` as `{ signal }`), then call `photos.cancelUpload(ticket.uploadId)` on your server.
+
+### Links, lists and deletes
+
+```js
+const photos = rilo.files.bucket('photos');
+
+// A link to view a file. A private bucket's links expire (one hour unless you say).
+const { url, expiresAt } = await photos.link('avatars/user-42.jpg', { expiresInSeconds: 900 });
+
+// Up to 100 links at once, in the order you asked.
+const links = await photos.links(['avatars/user-42.jpg', 'avatars/user-43.jpg']);
+
+// One folder level at a time, a page at a time.
+const page = await photos.list({ prefix: 'avatars/', delimiter: '/', limit: 100 });
+// page.files, page.folders, page.nextCursor (pass it back as `cursor` for the next page)
+
+const file = await photos.get('avatars/user-42.jpg'); // size, contentType, updatedAt
+await photos.delete('avatars/user-42.jpg');
+
+const { buckets, usage } = await rilo.files.buckets();
+```
+
+Uploading and deleting need an app key with **Read and write** access. A **Read only** key can read data, list and get files, and make links.
+
+Paths are sent to Files with each part encoded, so spaces and symbols in names are fine. The slashes between folders stay as they are.
+
+## Mongoose
+
+Mongoose isn't a dependency of this package. Pass the one your app already has:
+
+```js
+import mongoose from 'mongoose';
+import { connectMongoose } from '@riloservices/base/mongoose';
+
+await connectMongoose(mongoose, process.env.RILO_KEY, { database: 'salon-prod' });
+```
+
+It connects with the same link that `createClient` uses, and opens `salon-prod` in your Space. It takes a `rilodb://` link in place of the key too; then `database` is optional, and the link's database is used when you leave it out.
+
+## Options
+
+`createClient(keyOrLink, options)` and `connectMongoose(mongoose, keyOrLink, { database, ...options })` take these. Rilo's own addresses are the defaults, so you don't need any of them in production.
+
+| Option         | What it does                                                                                                                |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `database`     | The database `rilo.db()` opens when you give it no name. (`connectMongoose` needs it, unless a `rilodb://` link names one.) |
+| `appName`      | A name for your app, shown in connection details so you can tell apps apart.                                                |
+| `spacesDomain` | The domain Spaces live under. Default `db.services.rilo.studio`. Ignored with a `rilodb://` link, which has its own.        |
+| `port`         | The database port. Default `27017`. Ignored with a `rilodb://` link, which has its own.                                     |
+| `tlsCAFile`    | A CA file to trust. Only for a local stand-in with its own certificate.                                                     |
+| `filesUrl`     | The Files address. Default `https://files.<region>.<spacesDomain>`, with the region from the key.                           |
+
+## The `rilo-db env` command
+
+Some tools want the plain values instead of the key: Compass, mongosh, a language without this package, or Mongoose set up on its own. Drivers and tools need the `mongodb://` link, which is `RILODB_URI`. With `RILO_KEY` in your environment, or in a `.env` file in the current folder, run:
+
+```bash
+npx @riloservices/base env
+npx @riloservices/base env --database salon-prod
+```
+
+It prints four lines:
+
+```text
+RILODB_URI=mongodb://app_k3m9x2qz:…@k3m9x2qz.in.db.services.rilo.studio:27017/?tls=true&…
+RILODB_URL=rilodb://app:…@k3m9x2qz.in.db.services.rilo.studio/
+RILO_FILES_URL=https://files.in.db.services.rilo.studio
+RILO_FILES_KEY=rdbf_k3m9x2qz_…
+```
+
+- `RILODB_URI` is the `mongodb://` link, for MongoDB drivers and tools.
+- `RILODB_URL` is the `rilodb://` link, for this package only.
+- `RILO_FILES_URL` and `RILO_FILES_KEY` are for the Files API.
+
+With `--database salon-prod`, both links name that database.
+
+It runs on your machine and sends nothing anywhere. The output holds your secrets, so keep it out of chat, tickets, logs and git. If the key is missing or isn't an app key, it says so and exits with status 1.
+
+## Other languages
+
+This package is a convenience for Node. Nothing in Rilo DB depends on it, and the key format is stable, so any language can use `RILO_KEY` with its own MongoDB driver and an HTTP client.
+
+An app key has four parts, separated by dots:
+
+```text
+rilo_<region>_<spaceId>.<name>.<databaseSecret>.<filesSecret>
+```
+
+|                  | How to make it                                                                                                                           |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Database login   | `<name>_<spaceId>`, with `<databaseSecret>` as the password                                                                              |
+| Database address | `<spaceId>.<region>.db.services.rilo.studio`, port `27017`                                                                               |
+| Database name    | `<your database>_<spaceId>`                                                                                                              |
+| Link options     | `tls=true&directConnection=true&retryWrites=false&authSource=admin&maxPoolSize=10`                                                       |
+| Files address    | `https://files.<region>.db.services.rilo.studio`                                                                                         |
+| Files key        | `rdbf_<spaceId>_<filesSecret>`, sent as `Authorization: Bearer …`. **Never send the whole app key to Files:** it answers `app_key_sent`. |
+
+For example, in Python:
+
+```python
+import os
+from pymongo import MongoClient
+
+ident, name, db_secret, files_secret = os.environ["RILO_KEY"].split(".")
+_, region, space = ident.split("_")  # rilo_in_k3m9x2qz
+
+client = MongoClient(
+    f"mongodb://{name}_{space}:{db_secret}@{space}.{region}.db.services.rilo.studio:27017/"
+    "?tls=true&directConnection=true&retryWrites=false&authSource=admin&maxPoolSize=10"
+)
+db = client[f"salon-prod_{space}"]
+files_key = f"rdbf_{space}_{files_secret}"  # the Bearer token for the Files API
+```
+
+## Errors
+
+- **`RiloKeyError`** is thrown when the key or link is missing, isn't an app key or a `rilodb://` link, or when you use `rilo.files` with a `rilodb://` link. Its message says what is wrong, for example that you passed a files key, a `mongodb://` link or a broken `rilodb://` link, and never repeats what you gave it.
+- **`RiloFilesError`** is thrown when a Files call fails. It has the HTTP `status`, a stable `code` such as `read_only_key` or `file_too_large`, a plain `message`, and where the Files API sends them, `details` (extra data, like `maxFileSize`) and `fields` (what to fix, on `validation_failed`). Decide what to do from `status` and `code`, not the message.
+- **`RiloUploadError`** (from `@riloservices/base/browser`) is thrown when storage refuses an upload. It has the `status` and storage's own `code`, such as `AccessDenied` when the link has expired.
+- **Database errors** are the MongoDB driver's own.
+
+```js
+import { RiloFilesError } from '@riloservices/base';
+
+try {
+  await rilo.files
+    .bucket('photos')
+    .createUpload({ path: 'a.jpg', contentType: 'image/jpeg', size });
+} catch (error) {
+  if (error instanceof RiloFilesError && error.code === 'file_too_large') {
+    console.log(`The most allowed is ${String(error.details?.maxFileSize)} bytes.`);
+  } else {
+    throw error;
+  }
+}
+```
+
+Files calls aren't retried for you. Try again after a moment on a `429` or `503`, and give up after a few tries. Any other `4xx` gives the same answer when repeated, so fix the request instead.
+
+## What it never does
+
+- It never logs anything, and never reads `process.env`. You pass the key in. (Only the `rilo-db` command reads `RILO_KEY`, as a command line tool.)
+- It sends Files only the `rdbf_…` part of your key, in the `Authorization` header. The database secret is used only to open the database connection. A `rilodb://` link never reaches Files.
+- It adds no network calls of its own: your data goes through the MongoDB driver, and files through the Files API and storage.
+
+Rilo DB works with MongoDB drivers and tools. MongoDB is a trademark of MongoDB, Inc.; Rilo DB is not affiliated with or endorsed by it.

package/dist/browser.cjs

@@ -0,0 +1,39 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/browser.ts
+/** Storage refused the file. `code` and the message are storage's own, when it sent them. */
+var RiloUploadError = class extends Error {
+	name = "RiloUploadError";
+	/** The HTTP status storage answered with. */
+	status;
+	/** Storage's error code, like `EntityTooLarge` or `AccessDenied`; null when it sent none. */
+	code;
+	constructor(status, code, reason) {
+		super(`Storage refused the upload (status ${status}${code === null ? "" : `, ${code}`})` + (reason === null ? "." : `: ${reason}`));
+		this.status = status;
+		this.code = code;
+	}
+};
+function xmlValue(xml, tag) {
+	const match = new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml);
+	return match?.[1] === void 0 || match[1] === "" ? null : match[1];
+}
+/**
+* Sends a file to storage with the upload your server asked for. Every signed field goes first,
+* then the file, which must be last. There is no key here: the signed fields are the authority.
+* Resolves when storage has the file; throws a `RiloUploadError` when it refuses it.
+*/
+async function sendUpload(ticket, file, options = {}) {
+	const form = new FormData();
+	for (const [name, value] of Object.entries(ticket.fields)) form.append(name, value);
+	form.append("file", file);
+	const response = await fetch(ticket.url, {
+		method: "POST",
+		body: form,
+		signal: options.signal
+	});
+	if (response.ok) return;
+	const xml = await response.text().catch(() => "");
+	throw new RiloUploadError(response.status, xmlValue(xml, "Code"), xmlValue(xml, "Message"));
+}
+exports.RiloUploadError = RiloUploadError;
+exports.sendUpload = sendUpload;

package/dist/browser.d.cts

@@ -0,0 +1,21 @@
+import { d as UploadTicket } from "./types-CD9NBWdA.cjs";
+/** The two parts of an upload ticket that the browser needs. */
+export type UploadForm = Pick<UploadTicket, 'url' | 'fields'>;
+/** Storage refused the file. `code` and the message are storage's own, when it sent them. */
+export declare class RiloUploadError extends Error {
+  readonly name = "RiloUploadError";
+  /** The HTTP status storage answered with. */
+  readonly status: number;
+  /** Storage's error code, like `EntityTooLarge` or `AccessDenied`; null when it sent none. */
+  readonly code: string | null;
+  constructor(status: number, code: string | null, reason: string | null);
+}
+/**
+ * Sends a file to storage with the upload your server asked for. Every signed field goes first,
+ * then the file, which must be last. There is no key here: the signed fields are the authority.
+ * Resolves when storage has the file; throws a `RiloUploadError` when it refuses it.
+ */
+export declare function sendUpload(ticket: UploadForm, file: Blob, options?: {
+  signal?: AbortSignal;
+}): Promise<void>;
+export type { UploadTicket };

package/dist/browser.d.mts

@@ -0,0 +1,21 @@
+import { d as UploadTicket } from "./types-CD9NBWdA.mjs";
+/** The two parts of an upload ticket that the browser needs. */
+export type UploadForm = Pick<UploadTicket, 'url' | 'fields'>;
+/** Storage refused the file. `code` and the message are storage's own, when it sent them. */
+export declare class RiloUploadError extends Error {
+  readonly name = "RiloUploadError";
+  /** The HTTP status storage answered with. */
+  readonly status: number;
+  /** Storage's error code, like `EntityTooLarge` or `AccessDenied`; null when it sent none. */
+  readonly code: string | null;
+  constructor(status: number, code: string | null, reason: string | null);
+}
+/**
+ * Sends a file to storage with the upload your server asked for. Every signed field goes first,
+ * then the file, which must be last. There is no key here: the signed fields are the authority.
+ * Resolves when storage has the file; throws a `RiloUploadError` when it refuses it.
+ */
+export declare function sendUpload(ticket: UploadForm, file: Blob, options?: {
+  signal?: AbortSignal;
+}): Promise<void>;
+export type { UploadTicket };

package/dist/browser.mjs

@@ -0,0 +1,37 @@
+// src/browser.ts
+/** Storage refused the file. `code` and the message are storage's own, when it sent them. */
+var RiloUploadError = class extends Error {
+	name = "RiloUploadError";
+	/** The HTTP status storage answered with. */
+	status;
+	/** Storage's error code, like `EntityTooLarge` or `AccessDenied`; null when it sent none. */
+	code;
+	constructor(status, code, reason) {
+		super(`Storage refused the upload (status ${status}${code === null ? "" : `, ${code}`})` + (reason === null ? "." : `: ${reason}`));
+		this.status = status;
+		this.code = code;
+	}
+};
+function xmlValue(xml, tag) {
+	const match = new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml);
+	return match?.[1] === void 0 || match[1] === "" ? null : match[1];
+}
+/**
+* Sends a file to storage with the upload your server asked for. Every signed field goes first,
+* then the file, which must be last. There is no key here: the signed fields are the authority.
+* Resolves when storage has the file; throws a `RiloUploadError` when it refuses it.
+*/
+async function sendUpload(ticket, file, options = {}) {
+	const form = new FormData();
+	for (const [name, value] of Object.entries(ticket.fields)) form.append(name, value);
+	form.append("file", file);
+	const response = await fetch(ticket.url, {
+		method: "POST",
+		body: form,
+		signal: options.signal
+	});
+	if (response.ok) return;
+	const xml = await response.text().catch(() => "");
+	throw new RiloUploadError(response.status, xmlValue(xml, "Code"), xmlValue(xml, "Message"));
+}
+export { RiloUploadError, sendUpload };