@sovaria/sdk 0.0.0-stage → 0.5.0

package/dist/collections.js

@@ -0,0 +1,569 @@
+/**
+ * Firestore-style document collections: field queries, cursors, live listeners, batches,
+ * transactions and field transforms.
+ *
+ * ```ts
+ * const posts = sov.collection('posts')
+ * const page = await posts.where('published', '==', true).orderBy('likes', 'desc').limit(20).get()
+ * const next = await posts.where('published', '==', true).orderBy('likes', 'desc').limit(20).startAfter(page.docs.at(-1)!).get()
+ *
+ * await sov.doc('posts/p1').update({ likes: FieldValue.increment(1), tags: FieldValue.arrayUnion('new') })
+ *
+ * await sov.runTransaction(async (tx) => {
+ *   const a = await tx.get(sov.doc('accounts/a'))
+ *   tx.update(sov.doc('accounts/a'), { balance: (a.data?.balance as number) - 10 })
+ *   tx.update(sov.doc('accounts/b'), { balance: FieldValue.increment(10) })
+ * })
+ *
+ * const stop = await posts.where('room', '==', 'r1').onSnapshot((snap) => render(snap.docs))
+ * stop()
+ * ```
+ *
+ * Every call goes through the gateway with the caller's credentials, so collection rules (Guard)
+ * and the project's row policies decide what a query returns and what a write may change.
+ */
+import { SovariaError } from './errors.js';
+const BASE = '/api/v1/data/doc';
+function quotePath(path) {
+    return path.split('/').filter(Boolean).map(encodeURIComponent).join('/');
+}
+export function filter(field, op, value) {
+    return [field, op, value];
+}
+/** Matches documents that match any of `filters` (Firestore `or()`; at most 30 OR terms after expansion). */
+export function or(...filters) {
+    return { or: filters };
+}
+/** Matches documents that match all of `filters` (Firestore `and()`), for nesting inside `or`. */
+export function and(...filters) {
+    return { and: filters };
+}
+export const count = () => ({ op: 'count' });
+export const sum = (field) => ({ op: 'sum', field });
+export const average = (field) => ({ op: 'avg', field });
+// ── field values ──────────────────────────────────────────────────────────────
+const TRANSFORM = Symbol('sovaria.fieldValue');
+function transform(op, value) {
+    return { [TRANSFORM]: true, op, value };
+}
+function isTransform(value) {
+    return typeof value === 'object' && value !== null && value[TRANSFORM] === true;
+}
+/** Atomic field updates, applied by the server inside the commit. */
+export const FieldValue = {
+    increment: (n) => transform('increment', n),
+    maximum: (n) => transform('maximum', n),
+    minimum: (n) => transform('minimum', n),
+    arrayUnion: (...elements) => transform('array_union', elements),
+    arrayRemove: (...elements) => transform('array_remove', elements),
+    serverTimestamp: () => transform('server_timestamp'),
+    delete: () => transform('delete'),
+};
+function fieldPath(parts) {
+    return parts.map((p) => (/^[A-Za-z_][A-Za-z0-9_]*$/.test(p) ? p : '`' + p.replace(/\\/g, '\\\\').replace(/`/g, '\\`') + '`')).join('.');
+}
+/** Pull FieldValue sentinels out of nested data into the API's `transforms` list. */
+export function splitTransforms(data, prefix = []) {
+    const clean = {};
+    const transforms = [];
+    for (const [key, value] of Object.entries(data)) {
+        const path = [...prefix, key];
+        if (isTransform(value)) {
+            transforms.push({ field: fieldPath(path), op: value.op, value: (value.value ?? null) });
+        }
+        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            const inner = splitTransforms(value, path);
+            transforms.push(...inner.transforms);
+            if (Object.keys(inner.data).length || !inner.transforms.length)
+                clean[key] = inner.data;
+        }
+        else {
+            clean[key] = value;
+        }
+    }
+    return { data: clean, transforms };
+}
+function setWrite(path, data, opts = {}) {
+    const split = splitTransforms(data);
+    const write = { op: opts.op ?? 'set', path, data: split.data, transforms: split.transforms };
+    if (opts.merge)
+        write.merge = true;
+    if (opts.mergeFields?.length)
+        write.merge_fields = opts.mergeFields;
+    return write;
+}
+function updateWrite(path, fields) {
+    const data = {};
+    const transforms = [];
+    for (const [key, value] of Object.entries(fields)) {
+        if (isTransform(value))
+            transforms.push({ field: key, op: value.op, value: (value.value ?? null) });
+        else
+            data[key] = value;
+    }
+    return { op: 'update', path, data, transforms };
+}
+function toSnapshot(raw) {
+    const exists = raw.exists !== false && raw.data !== null && raw.data !== undefined;
+    const path = String(raw.path ?? '');
+    return {
+        id: String(raw.id ?? path.split('/').pop() ?? ''),
+        path,
+        exists,
+        data: exists ? raw.data : null,
+        version: Number(raw.version ?? 0),
+        updateTime: raw.update_time ? String(raw.update_time) : undefined,
+        createTime: raw.create_time ? String(raw.create_time) : undefined,
+        ...(raw.from_cache ? { fromCache: true } : {}),
+        ...(raw.pending ? { hasPendingWrites: true } : {}),
+        ...(typeof raw.distance === 'number' ? { distance: raw.distance } : {}),
+    };
+}
+/** A `findNearest` query: `await query.findNearest({...}).get()`. */
+export class VectorQuery {
+    sdk;
+    path;
+    body;
+    constructor(sdk, path, body) {
+        this.sdk = sdk;
+        this.path = path;
+        this.body = body;
+    }
+    toJSON() {
+        return JSON.parse(JSON.stringify(this.body));
+    }
+    async get() {
+        const raw = await this.sdk.request('POST', `${BASE}/_nearest/${quotePath(this.path)}`, { body: this.toJSON() });
+        return querySnapshot((raw.documents ?? []).map((d) => toSnapshot(d)));
+    }
+}
+function querySnapshot(docs, changes = [], extra = {}) {
+    return { docs, changes, hasMore: false, nextCursor: null, ...extra, empty: docs.length === 0, size: docs.length };
+}
+export class DocumentReference {
+    sdk;
+    path;
+    id;
+    constructor(sdk, path) {
+        this.sdk = sdk;
+        const parts = path.split('/').filter(Boolean);
+        if (parts.length < 2 || parts.length % 2)
+            throw SovariaError.config('A document path is collection/id (or collection/id/sub/id)');
+        this.path = parts.join('/');
+        this.id = parts[parts.length - 1];
+    }
+    get parent() {
+        return new Query(this.sdk, this.path.split('/').slice(0, -1).join('/'));
+    }
+    collection(name) {
+        return new Query(this.sdk, `${this.path}/${name}`);
+    }
+    async get() {
+        try {
+            const raw = await this.sdk.request('GET', `${BASE}/${quotePath(this.path)}`);
+            return toSnapshot({ ...raw, id: this.id, path: this.path });
+        }
+        catch (error) {
+            if (error instanceof SovariaError && error.statusCode === 404) {
+                return { id: this.id, path: this.path, exists: false, data: null, version: 0 };
+            }
+            throw error;
+        }
+    }
+    async commitOne(write) {
+        const out = await commitWrites(this.sdk, [write]);
+        return out.results[0];
+    }
+    /** Replace the document (or merge into it with `{ merge: true }`). */
+    set(data, opts = {}) {
+        return this.commitOne(setWrite(this.path, data, opts));
+    }
+    /** Create it; fails with 409 ALREADY_EXISTS when it exists. */
+    create(data) {
+        return this.commitOne(setWrite(this.path, data, { op: 'create' }));
+    }
+    /** Change fields (dotted paths allowed); fails with 404 when the document doesn't exist. */
+    update(fields, opts = {}) {
+        const write = updateWrite(this.path, fields);
+        if (opts.version !== undefined)
+            write.precondition = { version: opts.version };
+        return this.commitOne(write);
+    }
+    async delete(opts = {}) {
+        const write = { op: 'delete', path: this.path };
+        if (opts.version !== undefined)
+            write.precondition = { version: opts.version };
+        await commitWrites(this.sdk, [write]);
+    }
+    /** Live document: `callback` runs now and after every change. Returns a function that stops it. */
+    onSnapshot(callback, onError) {
+        return this.parent.where('__key__', '==', this.id).onSnapshot((snap) => {
+            callback(snap.docs[0] ?? { id: this.id, path: this.path, exists: false, data: null, version: 0 });
+        }, onError);
+    }
+}
+export class Query {
+    sdk;
+    body;
+    isGroup;
+    path;
+    id;
+    /**
+     * A collection, or with `isGroup` (`sov.collectionGroup('comments')`) every collection with that id at any
+     * depth; in a group, document cursors and `__key__` are full document paths.
+     */
+    constructor(sdk, path, body = {}, isGroup = false) {
+        this.sdk = sdk;
+        this.body = body;
+        this.isGroup = isGroup;
+        const parts = path.split('/').filter(Boolean);
+        if (isGroup && parts.length !== 1)
+            throw SovariaError.config("A collection group is one collection id, like 'comments'");
+        if (!parts.length || parts.length % 2 === 0)
+            throw SovariaError.config('A collection path is collection or collection/id/subcollection');
+        this.path = parts.join('/');
+        this.id = parts[parts.length - 1];
+    }
+    with(changes) {
+        const body = { ...this.body };
+        for (const [k, v] of Object.entries(changes)) {
+            if (v === undefined)
+                delete body[k];
+            else
+                body[k] = v;
+        }
+        return new Query(this.sdk, this.path, body, this.isGroup);
+    }
+    where(fieldOrFilter, op, value) {
+        const item = typeof fieldOrFilter === 'string' ? [fieldOrFilter, op, value] : fieldOrFilter;
+        return this.with({ where: [...(this.body.where ?? []), item] });
+    }
+    orderBy(field, direction = 'asc') {
+        return this.with({ order_by: [...(this.body.order_by ?? []), [field, direction]] });
+    }
+    limit(n) {
+        return this.with({ limit: n, limit_to_last: undefined });
+    }
+    limitToLast(n) {
+        return this.with({ limit_to_last: n, limit: undefined });
+    }
+    cursor(args) {
+        const [first] = args;
+        if (args.length === 1 && first && typeof first === 'object' && !Array.isArray(first)) {
+            const obj = first;
+            // A DocumentSnapshot: its id, or its full path in a collection group.
+            if ('exists' in obj && typeof obj.id === 'string')
+                return { key: this.isGroup && obj.path ? obj.path : obj.id };
+            if (obj.values || obj.key)
+                return { values: obj.values, key: obj.key };
+        }
+        return { values: args };
+    }
+    startAt(...values) { return this.with({ start_at: this.cursor(values), start_after: undefined }); }
+    startAfter(...values) { return this.with({ start_after: this.cursor(values), start_at: undefined }); }
+    endAt(...values) { return this.with({ end_at: this.cursor(values), end_before: undefined }); }
+    endBefore(...values) { return this.with({ end_before: this.cursor(values), end_at: undefined }); }
+    doc(id) {
+        if (this.isGroup)
+            throw SovariaError.config("A collection group has no documents of its own; use sov.doc('posts/p1/comments/c1')");
+        return new DocumentReference(this.sdk, `${this.path}/${id ?? newDocumentId()}`);
+    }
+    async add(data) {
+        const ref = this.doc();
+        await ref.create(data);
+        return ref;
+    }
+    toJSON() {
+        const body = JSON.parse(JSON.stringify(this.body));
+        if (this.isGroup)
+            body.collection_group = true;
+        return body;
+    }
+    /**
+     * Vector search like Firestore's `findNearest`: this query's `where` filters run first, then the `limit`
+     * documents whose `vectorField` is closest to `queryVector` come back closest first, each with `distance`.
+     */
+    findNearest(opts) {
+        const body = {
+            where: this.body.where ?? [],
+            field: opts.vectorField,
+            vector: opts.queryVector.map(Number),
+            limit: opts.limit,
+            distance: String(opts.distanceMeasure ?? 'cosine').toLowerCase(),
+        };
+        if (opts.distanceResultField)
+            body.distance_field = opts.distanceResultField;
+        if (opts.distanceThreshold !== undefined)
+            body.distance_threshold = opts.distanceThreshold;
+        if (this.isGroup)
+            body.collection_group = true;
+        return new VectorQuery(this.sdk, this.path, body);
+    }
+    async get() {
+        const raw = await this.sdk.request('POST', `${BASE}/_query/${quotePath(this.path)}`, { body: this.toJSON() });
+        const docs = (raw.documents ?? []).map((d) => toSnapshot(raw.from_cache ? { ...d, from_cache: true } : d));
+        return querySnapshot(docs, [], {
+            hasMore: Boolean(raw.has_more),
+            nextCursor: raw.next_cursor ?? null,
+            indexHint: raw.index_hint,
+        });
+    }
+    async count() {
+        const body = this.toJSON();
+        delete body.limit;
+        delete body.limit_to_last;
+        const raw = await this.sdk.request('POST', `${BASE}/_count/${quotePath(this.path)}`, { body });
+        return Number(raw.count ?? 0);
+    }
+    /**
+     * count / sum / average on the server, like Firestore's `getAggregateFromServer`:
+     * `await orders.where('paid', '==', true).aggregate({ n: count(), revenue: sum('total'), avg: average('total') })`.
+     * sum and average only use numeric values; average is null when there are none. With `limit`, they cover
+     * the first `limit` results; without, every match.
+     */
+    async aggregate(spec) {
+        const body = this.toJSON();
+        body.aggregations = Object.entries(spec).map(([alias, a]) => ({ ...a, alias }));
+        const raw = await this.sdk.request('POST', `${BASE}/_aggregate/${quotePath(this.path)}`, { body });
+        return (raw.aggregations ?? {});
+    }
+    /** Every matching document, one request per page. */
+    async *pages(pageSize = 100) {
+        let query = this.limit(pageSize);
+        for (;;) {
+            const snap = await query.get();
+            yield* snap.docs;
+            if (!snap.hasMore || !snap.nextCursor)
+                return;
+            query = query.with({ start_after: snap.nextCursor, start_at: undefined });
+        }
+    }
+    /** Live results: `callback` runs with the first snapshot and after every change. Await it for the stop function. */
+    async onSnapshot(callback, onError) {
+        const listener = new LiveQuery(this.sdk, this, callback, onError);
+        await listener.start();
+        return () => listener.close();
+    }
+}
+export function newDocumentId() {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    const bytes = new Uint8Array(20);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => alphabet[b % alphabet.length]).join('');
+}
+export class LiveQuery {
+    sdk;
+    query;
+    callback;
+    onError;
+    id = '';
+    channel = '';
+    docs = new Map();
+    order = [];
+    seq = 0;
+    pending = [];
+    renewTimer;
+    socket;
+    pollTimer;
+    closed = false;
+    /** A server without collection-group listeners (older): the group query is re-run this often (ms). */
+    static groupPollMs = 5000;
+    constructor(sdk, query, callback, onError) {
+        this.sdk = sdk;
+        this.query = query;
+        this.callback = callback;
+        this.onError = onError;
+    }
+    async start() {
+        let raw;
+        try {
+            raw = await this.sdk.request('POST', `${BASE}/_listen/${quotePath(this.query.path)}`, { body: this.query.toJSON() });
+        }
+        catch (error) {
+            // A server from before collection-group listeners answers 400 UNSUPPORTED: poll the group query instead.
+            if (this.query.isGroup && error instanceof SovariaError && error.statusCode === 400 && error.serverCode === 'UNSUPPORTED') {
+                this.applyFull((await this.query.get()).docs, true);
+                this.pollTimer = setInterval(() => void this.resync(), LiveQuery.groupPollMs);
+                return;
+            }
+            throw error;
+        }
+        this.id = String(raw.id);
+        this.channel = String(raw.channel);
+        this.applyFull((raw.documents ?? []).map((d) => toSnapshot(d)), true);
+        const ttl = Number(raw.ttl_seconds ?? 600);
+        this.renewTimer = setInterval(() => {
+            this.sdk.request('POST', `${BASE}/_listeners/${this.id}/renew`).catch((error) => this.onError?.(error));
+        }, Math.max(30, ttl / 2) * 1000);
+        this.socket = this.sdk.openChannel(this.channel, {
+            onMessage: (payload) => void this.applyMessage(payload),
+            onStatus: (status) => {
+                // Changes published while the socket was (re)connecting: catch up with one query.
+                if (status === 'live')
+                    void this.resync();
+            },
+            onError: (error) => this.onError?.(error),
+        });
+    }
+    emit(changes) {
+        try {
+            this.callback(querySnapshot(this.order.map((id) => this.docs.get(id)), changes));
+        }
+        catch (error) {
+            this.onError?.(error);
+        }
+    }
+    applyFull(docs, initial = false) {
+        // In a collection group the same id can appear under two parents: key by path there.
+        const key = (d) => (this.query.isGroup ? d.path : d.id);
+        const oldIndex = new Map(this.order.map((id, i) => [id, i]));
+        const changes = [];
+        const ids = new Set(docs.map(key));
+        for (const [id, i] of oldIndex)
+            if (!ids.has(id))
+                changes.push({ type: 'removed', doc: this.docs.get(id), oldIndex: i, newIndex: -1 });
+        docs.forEach((d, i) => {
+            const prev = this.docs.get(key(d));
+            if (!prev)
+                changes.push({ type: 'added', doc: d, oldIndex: -1, newIndex: i });
+            else if (prev.version !== d.version)
+                changes.push({ type: 'modified', doc: d, oldIndex: oldIndex.get(key(d)) ?? -1, newIndex: i });
+        });
+        this.docs = new Map(docs.map((d) => [key(d), d]));
+        this.order = docs.map(key);
+        if (changes.length || initial)
+            this.emit(changes);
+    }
+    async resync() {
+        if (this.closed)
+            return;
+        try {
+            this.applyFull((await this.query.get()).docs);
+        }
+        catch (error) {
+            this.onError?.(error);
+        }
+    }
+    async applyMessage(msg) {
+        // Offline mode: a local write or a sync asks the listener to re-read (served from the cache offline).
+        if (msg.type === 'local_resync' && (!msg.listener_id || msg.listener_id === this.id))
+            return this.resync();
+        if (msg.type !== 'doc_changes' || msg.listener_id !== this.id)
+            return;
+        const seq = Number(msg.seq ?? 0);
+        if (seq <= this.seq && (msg.part ?? 1) === 1)
+            return;
+        if (seq > this.seq + 1 || msg.resync || (msg.changes ?? []).some((c) => c.data_omitted)) {
+            this.seq = seq;
+            await this.resync();
+            return;
+        }
+        // In a collection group the same id can live under two parents: documents are keyed by path there.
+        const keyOf = (c) => String(this.query.isGroup ? c.path ?? c.id : c.id);
+        for (const c of msg.changes ?? []) {
+            if (c.type === 'removed') {
+                const gone = this.docs.get(keyOf(c));
+                if (gone) {
+                    this.docs.delete(keyOf(c));
+                    this.pending.push({ type: 'removed', doc: gone, oldIndex: Number(c.old_index ?? -1), newIndex: -1 });
+                }
+            }
+            else {
+                const snap = toSnapshot(c);
+                this.docs.set(this.query.isGroup ? snap.path : snap.id, snap);
+                this.pending.push({ type: c.type, doc: snap, oldIndex: Number(c.old_index ?? -1), newIndex: Number(c.new_index ?? -1) });
+            }
+        }
+        if ((msg.part ?? 1) < (msg.parts ?? 1))
+            return;
+        this.seq = seq;
+        if (msg.ids)
+            this.order = msg.ids.filter((id) => this.docs.has(id));
+        else
+            this.order = this.order.filter((id) => this.docs.has(id)).concat([...this.docs.keys()].filter((id) => !this.order.includes(id)));
+        for (const id of [...this.docs.keys()])
+            if (!this.order.includes(id))
+                this.docs.delete(id);
+        const changes = this.pending;
+        this.pending = [];
+        this.emit(changes);
+    }
+    close() {
+        this.closed = true;
+        if (this.renewTimer)
+            clearInterval(this.renewTimer);
+        if (this.pollTimer)
+            clearInterval(this.pollTimer);
+        this.socket?.close();
+        if (this.id)
+            this.sdk.request('DELETE', `${BASE}/_listeners/${this.id}`).catch(() => undefined);
+    }
+}
+// ── batches and transactions ──────────────────────────────────────────────────
+export function commitWrites(sdk, writes, reads = []) {
+    return sdk.request('POST', `${BASE}/_commit`, { body: { writes, reads } });
+}
+/** Writes committed together: every one or none (up to the plan's docs.max_transaction_writes). */
+export class WriteBatch {
+    sdk;
+    writes = [];
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    set(ref, data, opts = {}) {
+        this.writes.push(setWrite(ref.path, data, opts));
+        return this;
+    }
+    create(ref, data) {
+        this.writes.push(setWrite(ref.path, data, { op: 'create' }));
+        return this;
+    }
+    update(ref, fields) {
+        this.writes.push(updateWrite(ref.path, fields));
+        return this;
+    }
+    delete(ref) {
+        this.writes.push({ op: 'delete', path: ref.path });
+        return this;
+    }
+    commit() {
+        return commitWrites(this.sdk, this.writes);
+    }
+}
+export class Transaction extends WriteBatch {
+    reads = new Map();
+    async get(ref) {
+        if (this.writes.length)
+            throw SovariaError.config('Read every document before the first write in a transaction');
+        const raw = await this.sdk.request('POST', `${BASE}/_get`, { body: { paths: [ref.path] } });
+        const snap = toSnapshot(raw.documents[0]);
+        this.reads.set(ref.path, snap.version);
+        return snap;
+    }
+    get hasWrites() {
+        return this.writes.length > 0;
+    }
+    commit() {
+        return commitWrites(this.sdk, this.writes, [...this.reads].map(([path, version]) => ({ path, version })));
+    }
+}
+/** Run `fn` and commit its writes atomically; retried when a document it read changed meanwhile. */
+export async function runTransaction(sdk, fn, maxAttempts = 5) {
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const tx = new Transaction(sdk);
+        const result = await fn(tx);
+        if (!tx.hasWrites)
+            return result;
+        try {
+            await tx.commit();
+            return result;
+        }
+        catch (error) {
+            // Contention only; ALREADY_EXISTS / NOT_FOUND / FAILED_PRECONDITION are final.
+            if (!(error instanceof SovariaError) || error.statusCode !== 409 || error.serverCode !== 'ABORTED')
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(2000, 50 * 2 ** attempt) * (0.5 + Math.random())));
+        }
+    }
+    throw new SovariaError(409, { code: 'ABORTED', message: `Transaction still conflicting after ${maxAttempts} attempts` });
+}

package/dist/complete-api.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Complete API namespace factories for SovariaSDK parity with console endpoints.
+ */
+import type { JsonObject, JsonValue, RequestOptions } from './index.js';
+type RequestFn = <T = JsonValue>(method: string, path: string, options?: RequestOptions) => Promise<T>;
+export declare function createKeysApi(request: RequestFn): {
+    list: () => Promise<JsonValue>;
+    create: (payload: JsonObject) => Promise<JsonObject>;
+    ensureDefaults: () => Promise<JsonObject>;
+    revoke: (keyId: string) => Promise<JsonObject>;
+};
+export declare function createGovernanceApi(request: RequestFn): {
+    listRegions: () => Promise<JsonValue>;
+    listAvailableRegions: (query?: {
+        size?: string;
+        plan?: string;
+    }) => Promise<JsonValue>;
+    patchRegion: (regionId: string, body: JsonObject) => Promise<JsonObject>;
+    listTenants: () => Promise<JsonValue>;
+    getTenant: (orgId: string) => Promise<JsonObject>;
+    setTenantStatus: (orgId: string, body: JsonObject) => Promise<JsonObject>;
+    listTenantDatabases: (orgId: string) => Promise<JsonValue>;
+    provisionDatabase: (orgId: string, body: JsonObject) => Promise<JsonObject>;
+    getDatabaseConnection: (orgId: string, projectId: string) => Promise<JsonObject>;
+    /** Staff only: the connection string, with the active access grant that allows revealing it. */
+    revealDatabaseConnection: (orgId: string, projectId: string, grantId: string) => Promise<JsonObject>;
+    pauseDatabase: (orgId: string, projectId: string) => Promise<JsonObject>;
+    resumeDatabase: (orgId: string, projectId: string) => Promise<JsonObject>;
+    resizeDatabase: (orgId: string, projectId: string, body: JsonObject) => Promise<JsonObject>;
+    deleteDatabase: (orgId: string, projectId: string, snapshot?: boolean) => Promise<JsonObject>;
+    listDatabaseBackups: (orgId: string, projectId: string, limit?: number) => Promise<JsonValue>;
+    triggerDatabaseBackup: (orgId: string, projectId: string) => Promise<JsonObject>;
+    /**
+     * Download a completed backup (plain SQL, gzip) as a Blob — the whole database, so owners, admins and
+     * developers only (`database.backup.read`). Restore it anywhere with `gunzip -c file | psql`.
+     */
+    downloadDatabaseBackup: (orgId: string, projectId: string, backupId: number | string) => Promise<Blob>;
+    /** Download a portable export bundle (tar.gz: Postgres dump + migration metadata) as a Blob. */
+    downloadProjectExport: (orgId: string, projectId: string, exportId: string) => Promise<Blob>;
+    adminListDatabases: () => Promise<JsonValue>;
+    listHosts: (regionId?: string) => Promise<JsonValue>;
+    patchHost: (hostId: string, body: JsonObject) => Promise<JsonObject>;
+    metricsOverview: () => Promise<JsonObject>;
+    projectMetrics: (projectId: string, since?: string, limit?: number) => Promise<JsonObject>;
+};
+export declare function createAdminApi(request: RequestFn): {
+    listErrorTraces: (query?: Record<string, string | number | boolean | null | undefined>) => Promise<JsonValue>;
+    getErrorTrace: (traceId: string) => Promise<JsonObject>;
+    resolveErrorTrace: (traceId: string, body?: JsonObject) => Promise<JsonObject>;
+    usageOverview: (period?: string, limit?: number) => Promise<JsonObject>;
+    listAccessTransparency: (query: Record<string, string | number | boolean | null | undefined>) => Promise<JsonValue>;
+    gatewayHealth: () => Promise<JsonValue>;
+};
+export {};