@zuzjs/flare-admin 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+type AdminConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error';
+type AdminConnectionStateListener = (state: AdminConnectionState) => void;
 interface FlareAdminConfig {
     /**
      * Base URL of your FlareServer instance.
@@ -12,6 +14,12 @@ interface FlareAdminConfig {
      * Keep in an environment variable — NEVER expose to the browser.
      */
     adminKey: string;
+    /** Optional gRPC endpoint, e.g. "127.0.0.1:5051". */
+    grpcUrl?: string;
+    /** Transport preference for supported operations. */
+    transport?: "auto" | "http" | "grpc";
+    /** Optional HTTP base URL override for admin HTTP APIs. */
+    httpBase?: string;
     /** Default token TTL, e.g. "24h" */
     defaultTtl?: string;
     /**
@@ -89,6 +97,322 @@ interface FlareAdminNotifications {
         tokens: AdminPushToken[];
     }>;
 }
+interface AdminStorageServer {
+    id: string;
+    name: string;
+    kind: string;
+    endpoint: string;
+    bucket: string;
+    region: string;
+    prefix?: string;
+    dataDir?: string;
+    forcePathStyle?: boolean;
+    frozen?: boolean;
+    readOnly?: boolean;
+    createdAt?: unknown;
+    updatedAt?: unknown;
+}
+interface AdminStorageServerInput {
+    name: string;
+    kind?: string;
+    endpoint?: string;
+    bucket: string;
+    region?: string;
+    accessKey?: string;
+    secretKey?: string;
+    prefix?: string;
+    dataDir?: string;
+    forcePathStyle?: boolean;
+    frozen?: boolean;
+    readOnly?: boolean;
+}
+interface AdminStorageServerPatchInput {
+    name?: string;
+    endpoint?: string;
+    bucket?: string;
+    region?: string;
+    accessKey?: string;
+    secretKey?: string;
+    prefix?: string;
+    dataDir?: string;
+    forcePathStyle?: boolean;
+    frozen?: boolean;
+    readOnly?: boolean;
+}
+interface AdminStorageUploadInput {
+    serverId: string;
+    path: string;
+    contentBase64: string;
+    contentType?: string;
+    encrypt?: boolean;
+}
+interface AdminStorageDownloadInput {
+    serverId: string;
+    path: string;
+    decrypt?: boolean;
+}
+interface AdminStorageDeleteInput {
+    serverId: string;
+    path: string;
+}
+interface AdminStorageObjectResult {
+    ok: boolean;
+    path: string;
+    key: string;
+    encrypted?: boolean;
+    size?: number;
+    contentBase64?: string;
+    contentType?: string;
+}
+declare enum AdminStorageSignedAction {
+    Upload = "upload",
+    Download = "download",
+    Delete = "delete",
+    Edit = "edit"
+}
+interface AdminStorageSignedUrlInput {
+    bucket: string;
+    key: string;
+    action: AdminStorageSignedAction;
+    expiresInSeconds?: number;
+    sizeBytes?: number;
+    contentType?: string;
+    encrypt?: boolean;
+    decrypt?: boolean;
+    forceDownload?: boolean;
+    allowedOrigins?: string[];
+    embedOnly?: boolean;
+}
+interface AdminStorageSignedUrlResult {
+    ok: boolean;
+    action: AdminStorageSignedAction;
+    method: "PUT" | "PATCH" | "GET" | "DELETE";
+    token: string;
+    urlPath: string;
+    url: string;
+    expiresInSeconds?: number;
+    expiresAt: number;
+    forceDownload?: boolean;
+    allowedOrigins?: string[];
+    embedOnly?: boolean;
+}
+interface AdminGetObjectUrlInput {
+    bucket: string;
+    key: string;
+    decrypt?: boolean;
+    expiresInSeconds?: number;
+    forceDownload?: boolean;
+    allowedOrigins?: string[];
+    embedOnly?: boolean;
+}
+interface AdminDownloadObjectInput extends AdminGetObjectUrlInput {
+    filename?: string;
+    openInNewTab?: boolean;
+}
+interface AdminDownloadObjectResult {
+    ok: boolean;
+    url: string;
+    filename: string;
+    triggered: boolean;
+}
+interface AdminStorageAwsConfig {
+    kind: string;
+    endpoint: string;
+    region: string;
+    bucket: string;
+    prefix?: string;
+    dataDir?: string;
+    forcePathStyle?: boolean;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+interface AdminStorageRulesPolicy {
+    maxEntries?: number;
+    maxAgeDays?: number;
+}
+interface AdminStorageRulesHistoryResult {
+    history: unknown[];
+    policy: AdminStorageRulesPolicy;
+    restoreEvents: unknown[];
+}
+interface FlareAdminStorage {
+    servers(): Promise<AdminStorageServer[]>;
+    createServer(input: AdminStorageServerInput): Promise<{
+        ok: boolean;
+        serverId: string;
+    }>;
+    patchServer(serverId: string, input: AdminStorageServerPatchInput): Promise<{
+        ok: boolean;
+        serverId: string;
+    }>;
+    deleteServer(serverId: string): Promise<{
+        ok: boolean;
+        serverId: string;
+        removedObjects: number;
+    }>;
+    awsConfig(serverId: string): Promise<AdminStorageAwsConfig>;
+    uploadObject(input: AdminStorageUploadInput): Promise<AdminStorageObjectResult>;
+    downloadObject(input: AdminStorageDownloadInput): Promise<AdminStorageObjectResult>;
+    deleteObject(input: AdminStorageDeleteInput | AdminDeleteObjectsInput): Promise<AdminStorageObjectResult | {
+        ok: boolean;
+        deleted: string[];
+        errors: Record<string, string>;
+    }>;
+    createSignedUrl(input: AdminStorageSignedUrlInput): Promise<AdminStorageSignedUrlResult>;
+    setRules(input: {
+        rules?: Record<string, unknown>;
+        rulesDsl?: string;
+        rulesHistoryPolicy?: AdminStorageRulesPolicy;
+    }): Promise<{
+        id: string;
+    }>;
+    validateRules(rulesDsl: string): Promise<{
+        valid: boolean;
+        diagnostics: unknown[];
+        rulesCount: number;
+    }>;
+    rulesHistory(): Promise<AdminStorageRulesHistoryResult>;
+    restoreRules(historyId: string): Promise<{
+        id: string;
+        rulesText: string;
+    }>;
+    createBucket(name: string, options?: AdminStorageBucketInput): Promise<AdminStorageBucket>;
+    listBuckets(): Promise<AdminStorageBucket[]>;
+    deleteBucket(name: string): Promise<{
+        ok: boolean;
+        removedObjects: number;
+    }>;
+    deleteBuckets(names: string[]): Promise<{
+        ok: boolean;
+        deleted: string[];
+        errors: Record<string, string>;
+    }>;
+    getBucketLocation(name: string): Promise<{
+        bucket: string;
+        kind: string;
+        region?: string;
+        endpoint?: string;
+    }>;
+    putObject(input: AdminPutObjectInput): Promise<AdminPutObjectResult>;
+    getObject(input: AdminGetObjectInput): Promise<AdminGetObjectResult>;
+    getObjectUrl(input: AdminGetObjectUrlInput): Promise<string>;
+    downloadObject(input: AdminDownloadObjectInput): Promise<AdminDownloadObjectResult>;
+    headObject(input: AdminHeadObjectInput): Promise<AdminStorageObjectMeta>;
+    headObjects(input: AdminHeadObjectsInput): Promise<AdminStorageObjectMeta[]>;
+    listObjects(input: AdminListObjectsInput): Promise<AdminListObjectsResult>;
+    copyObject(input: AdminCopyObjectInput): Promise<{
+        ok: boolean;
+    }>;
+    copyObjects(inputs: AdminCopyObjectInput[]): Promise<{
+        ok: boolean;
+        errors: Record<string, string>;
+    }>;
+    deleteObjects(input: AdminDeleteObjectsInput): Promise<{
+        ok: boolean;
+        deleted: string[];
+        errors: Record<string, string>;
+    }>;
+}
+interface AdminStorageBucket {
+    id: string;
+    name: string;
+    bucket: string;
+    kind: string;
+    region?: string;
+    endpoint?: string;
+    prefix?: string;
+    frozen?: boolean;
+    readOnly?: boolean;
+    createdAt?: unknown;
+    updatedAt?: unknown;
+}
+interface AdminStorageBucketInput {
+    kind?: string;
+    prefix?: string;
+    region?: string;
+    endpoint?: string;
+    accessKey?: string;
+    secretKey?: string;
+    dataDir?: string;
+    forcePathStyle?: boolean;
+}
+interface AdminStorageObjectMeta {
+    key: string;
+    bucket: string;
+    size: number;
+    contentType: string;
+    encrypted: boolean;
+    createdAt?: unknown;
+    updatedAt?: unknown;
+}
+interface AdminPutObjectInput {
+    bucket: string;
+    key: string;
+    body?: string | Uint8Array | ArrayBuffer | Buffer;
+    /** Pre-encoded base64 body. Mutually exclusive with `body`. Always uses base64 path. */
+    contentBase64?: string;
+    contentType?: string;
+    /** Encrypt at rest with AES-256-GCM. Defaults to true. */
+    encrypt?: boolean;
+    /**
+     * Max payload bytes for the base64-over-JSON upload path.
+     * Payloads larger than this are uploaded via a signed URL (raw binary PUT).
+     * Default: 4 MiB.
+     */
+    base64MaxBytes?: number;
+}
+interface AdminPutObjectResult {
+    ok: boolean;
+    bucket: string;
+    key: string;
+    size: number;
+    encrypted: boolean;
+}
+interface AdminGetObjectInput {
+    bucket: string;
+    key: string;
+    decrypt?: boolean;
+}
+interface AdminGetObjectResult {
+    ok: boolean;
+    bucket: string;
+    key: string;
+    contentBase64: string;
+    contentType: string;
+    size: number;
+    encrypted: boolean;
+}
+interface AdminHeadObjectInput {
+    bucket: string;
+    key: string;
+}
+interface AdminHeadObjectsInput {
+    bucket: string;
+    keys: string[];
+}
+interface AdminListObjectsInput {
+    bucket: string;
+    prefix?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface AdminListObjectsResult {
+    bucket: string;
+    objects: AdminStorageObjectMeta[];
+    count: number;
+    hasMore: boolean;
+    cursor?: string;
+}
+interface AdminCopyObjectInput {
+    sourceBucket: string;
+    sourceKey: string;
+    destBucket: string;
+    destKey: string;
+}
+interface AdminDeleteObjectsInput {
+    bucket: string;
+    keys: string[];
+}
 type QueryOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "array-contains" | "array-contains-any" | "elem-match" | "like" | "not-like" | "contains" | "exists" | "not-exists";
 interface WhereFilter {
     field: string;
@@ -277,6 +601,39 @@ type AdminDocAddedCallback<T = unknown> = (data: T, docId: string) => void;
 type AdminDocUpdatedCallback<T = unknown> = (data: T, docId: string) => void;
 type AdminDocDeletedCallback = (docId: string) => void;
 type AdminDocChangedCallback<T = unknown> = (data: T | null, docId: string, operation: "insert" | "update" | "delete" | "replace") => void;
+type AdminStreamFlushReason = "snapshot" | "change-batch";
+interface AdminCollectionStreamOptions<T = unknown> {
+    flushMs?: number;
+    maxBatchSize?: number;
+    idField?: keyof T & string;
+    getId?: (doc: T) => string | undefined;
+    insertAt?: "start" | "end";
+    maxDocs?: number;
+    sort?: (a: T, b: T) => number;
+}
+interface AdminCollectionStreamMeta {
+    reason: AdminStreamFlushReason;
+    batchSize: number;
+    version: number;
+    ready: boolean;
+}
+type AdminCollectionStreamListener<T = unknown> = (rows: readonly T[], meta: AdminCollectionStreamMeta) => void;
+interface AdminCollectionStream<T = unknown> {
+    subscribe: (listener: AdminCollectionStreamListener<T>, emitCurrent?: boolean) => () => void;
+    getSnapshot: () => readonly T[];
+    isReady: () => boolean;
+    getVersion: () => number;
+    close: () => void;
+    onError: (callback: AdminSubscriptionErrorCallback) => AdminCollectionStream<T>;
+    onPermissionDenied: (callback: AdminSubscriptionErrorCallback) => AdminCollectionStream<T>;
+}
+interface AdminCollectionExternalStore<T = unknown> {
+    subscribe: (onStoreChange: () => void) => () => void;
+    getSnapshot: () => readonly T[];
+    getServerSnapshot: () => readonly T[];
+    stream: AdminCollectionStream<T>;
+    destroy: () => void;
+}
 interface AdminSubscribeOptions {
     skipSnapshot?: boolean;
 }
@@ -454,6 +811,104 @@ declare class FlareAdminNotificationsService implements FlareAdminNotifications
     }>;
 }
 
+declare class FlareAdminStorageService {
+    private readonly cfg;
+    constructor(cfg: Required<FlareAdminConfig>);
+    private base;
+    private get headers();
+    protected jsonRequest<T>(method: string, path: string, body?: unknown): Promise<T>;
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    servers(): Promise<AdminStorageServer[]>;
+    createServer(input: AdminStorageServerInput): Promise<{
+        ok: boolean;
+        serverId: string;
+    }>;
+    patchServer(serverId: string, input: AdminStorageServerPatchInput): Promise<{
+        ok: boolean;
+        serverId: string;
+    }>;
+    deleteServer(serverId: string): Promise<{
+        ok: boolean;
+        serverId: string;
+        removedObjects: number;
+    }>;
+    awsConfig(serverId: string): Promise<AdminStorageAwsConfig>;
+    uploadObject(input: AdminStorageUploadInput): Promise<AdminStorageObjectResult>;
+    downloadObject(input: AdminStorageDownloadInput): Promise<AdminStorageObjectResult>;
+    deleteObject(input: AdminStorageDeleteInput): Promise<AdminStorageObjectResult>;
+    createSignedUrl(input: AdminStorageSignedUrlInput): Promise<AdminStorageSignedUrlResult>;
+    setRules(input: {
+        rules?: Record<string, unknown>;
+        rulesDsl?: string;
+        rulesHistoryPolicy?: AdminStorageRulesPolicy;
+    }): Promise<{
+        id: string;
+    }>;
+    validateRules(rulesDsl: string): Promise<{
+        valid: boolean;
+        diagnostics: unknown[];
+        rulesCount: number;
+    }>;
+    rulesHistory(): Promise<AdminStorageRulesHistoryResult>;
+    restoreRules(historyId: string): Promise<{
+        id: string;
+        rulesText: string;
+    }>;
+}
+/**
+ * S3-compatible admin storage service.
+ * Works with bucket names; resolves server IDs internally.
+ */
+declare class FlareAdminStorageS3 {
+    private readonly _svc;
+    private readonly _bucketCache;
+    private _bucketListLoaded;
+    private _bucketListPromise;
+    constructor(svc: FlareAdminStorageService);
+    private _ensureBuckets;
+    private _loadBuckets;
+    private _invalidateCache;
+    private _resolveBucketId;
+    createBucket(name: string, options?: AdminStorageBucketInput): Promise<AdminStorageBucket>;
+    listBuckets(): Promise<AdminStorageBucket[]>;
+    deleteBucket(name: string): Promise<{
+        ok: boolean;
+        removedObjects: number;
+    }>;
+    deleteBuckets(names: string[]): Promise<{
+        ok: boolean;
+        deleted: string[];
+        errors: Record<string, string>;
+    }>;
+    getBucketLocation(name: string): Promise<{
+        bucket: string;
+        kind: string;
+        region?: string;
+        endpoint?: string;
+    }>;
+    putObject(input: AdminPutObjectInput): Promise<AdminPutObjectResult>;
+    getObject(input: AdminGetObjectInput): Promise<AdminGetObjectResult>;
+    getObjectUrl(input: AdminGetObjectUrlInput): Promise<string>;
+    downloadObject(input: AdminDownloadObjectInput): Promise<AdminDownloadObjectResult>;
+    headObject(input: AdminHeadObjectInput): Promise<AdminStorageObjectMeta>;
+    headObjects(input: AdminHeadObjectsInput): Promise<AdminStorageObjectMeta[]>;
+    listObjects(input: AdminListObjectsInput): Promise<AdminListObjectsResult>;
+    copyObject(input: AdminCopyObjectInput): Promise<{
+        ok: boolean;
+    }>;
+    copyObjects(inputs: AdminCopyObjectInput[]): Promise<{
+        ok: boolean;
+        errors: Record<string, string>;
+    }>;
+    deleteObject(input: AdminStorageDeleteInput): Promise<AdminStorageObjectResult>;
+    deleteObjects(input: AdminDeleteObjectsInput): Promise<{
+        ok: boolean;
+        deleted: string[];
+        errors: Record<string, string>;
+    }>;
+    createSignedUrl(input: AdminStorageSignedUrlInput): Promise<AdminStorageSignedUrlResult>;
+}
+
 type AdminRealtimeSubscriber$1 = {
     subscribe: (collection: string, docId: string | undefined, structuredQuery: StructuredQuery | undefined, callback: AdminSnapshotCallback, options?: AdminSubscribeOptions) => AdminSubscriptionHandle;
 };
@@ -569,6 +1024,8 @@ declare class AdminLiveCollectionReference<T = Record<string, unknown>> {
         query: StructuredQuery;
     };
     onSnapshot(callback: AdminSnapshotCallback<T[]>): () => void;
+    stream(options?: AdminCollectionStreamOptions<T>): AdminCollectionStream<T>;
+    asStore(options?: AdminCollectionStreamOptions<T>): AdminCollectionExternalStore<T>;
     onDocAdded(callback: AdminDocAddedCallback<T>): () => void;
     onDocUpdated(callback: AdminDocUpdatedCallback<T>): () => void;
     onDocDeleted(callback: AdminDocDeletedCallback): () => void;
@@ -605,6 +1062,19 @@ declare class FlareAdminConnection {
     collection<T = Record<string, unknown>>(name: string): AdminLiveCollectionReference<T>;
     /** Wait until the WebSocket is open and authenticated. */
     ready(): Promise<void>;
+    /** Current connection state. */
+    get connectionState(): AdminConnectionState;
+    /**
+     * Subscribe to connection state changes.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     *   const unsub = admin.live().onConnectionStateChange((state) => {
+     *     console.log("connection:", state);
+     *   });
+     *   // state: 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error'
+     */
+    onConnectionStateChange(listener: AdminConnectionStateListener): () => void;
     /** Close the WebSocket connection permanently (no reconnect). */
     disconnect(): void;
 }
@@ -626,12 +1096,21 @@ declare class FlareAdminWsConnection {
     private connected;
     private shouldReconnect;
     private reconnectDelay;
+    private _state;
+    private _stateListeners;
     private readonly wsUrl;
     private _readyResolve;
     private _readyPromise;
     constructor(cfg: Required<FlareAdminConfig>);
     /** Resolves once the WS is open and AUTH_OK is received from the server. */
     ready(): Promise<void>;
+    /** Current connection state. */
+    get connectionState(): AdminConnectionState;
+    /**
+     * Subscribe to connection state changes.
+     * Returns an unsubscribe function.
+     */
+    onConnectionStateChange(listener: AdminConnectionStateListener): () => void;
     /** Close the connection permanently (no reconnect). */
     disconnect(): void;
     /**
@@ -648,51 +1127,24 @@ declare class FlareAdminWsConnection {
     private replayActiveSubscriptions;
     private toSubscriptionError;
     private emitSubscriptionError;
+    private _setState;
     private _connect;
     private _handle;
 }
 
 /**
- * @zuzjs/flare-admin
- *
- * Server-side admin SDK for FlareServer.
- * Runs only on your backend, never in a browser.
- *
- * ─── Quick start ──────────────────────────────────────────────────────────────
- *
- *   import { connectApp } from "@zuzjs/flare-admin";
+ * Sentinel value that asks flare-node to write the current server timestamp.
  *
- *   const admin = connectApp({
- *     serverUrl: process.env.FLARE_URL!,
- *     appId:     process.env.FLARE_APP_ID!,
- *     adminKey:  process.env.FLARE_ADMIN_KEY!,
- *   });
- *
- *   // Mint a custom auth token (for use by the browser client)
- *   const token = await admin.auth().createCustomToken(String(user.id), {
- *     role:   user.isAdmin ? "admin" : "user",
- *     claims: { email: user.email, plan: user.plan },
- *   });
- *
- *   // One-shot DB queries (bypasses security rules)
- *   const users = await admin.db().collection("users").get();
- *   await admin.db().collection("users").doc("alice").set({ name: "Alice" });
- *
- *   // Rich queries
- *   const seniors = await admin.db()
- *     .collection("users")
- *     .where({ age: ">= 60" })
- *     .orderBy("name")
- *     .limit(10)
- *     .get();
- *
- *   // Real-time subscriptions over WebSocket
- *   const unsub = admin.connection()
- *     .collection("orders")
- *     .where({ status: "pending" })
- *     .orderBy("createdAt", "desc")
- *     .onSnapshot((snap) => console.log(snap));
+ * Usage:
+ *   await admin.db().collection("posts").doc(id).update({ updatedAt: ServerTimeStamp })
  */
+declare const ServerTimeStamp: "ServerTimeStamp";
+/**
+ * Object form of the same sentinel for payloads that prefer structured values.
+ */
+declare const ServerTimeStampField: {
+    readonly $serverTimestamp: true;
+};
 
 /**
  * A FlareAdmin application instance.
@@ -704,6 +1156,8 @@ declare class FlareAdminApp {
     private _db?;
     private _conn?;
     private _notifications?;
+    private _storage?;
+    private _storageS3?;
     /**
      * Access the auth service.
      *
@@ -738,7 +1192,7 @@ declare class FlareAdminApp {
     * `groupBy`, `having`, `Join`, `select`, `distinctField`, `vectorSearch`.
      *
      * @example
-     *   const unsub = admin.connection()
+     *   const unsub = admin.live()
      *     .collection("orders")
      *     .where({ status: "pending" })
      *     .orderBy("createdAt", "desc")
@@ -748,19 +1202,86 @@ declare class FlareAdminApp {
      *       else console.log(snap.operation, snap.data);
      *     });
      *
-     *   const unsub2 = admin.connection()
+     *   const unsub2 = admin.live()
      *     .collection("users").doc("alice")
      *     .onSnapshot((snap) => console.log(snap.data));
      *
      *   unsub();
      *   unsub2();
-     *   admin.connection().disconnect();
+     *   admin.live().disconnect();
      */
-    connection(): FlareAdminConnection;
+    live(): FlareAdminConnection;
     /**
      * Access push notification management APIs.
      */
     notifications(): FlareAdminNotifications;
+    private storageService;
+    storage(): FlareAdminStorageS3;
+    /**
+     * S3-compatible storage service. Works with bucket names; no server IDs needed.
+     * Bucket is auto-created on putObject() if it doesn't exist.
+     *
+     * @example
+     *   await admin.s3().putObject({ bucket: 'avatars', key: 'alice.png', body: buffer });
+     *   const { contentBase64 } = await admin.s3().getObject({ bucket: 'avatars', key: 'alice.png' });
+     */
+    s3(): FlareAdminStorageS3;
+    createSignedUrl(input: AdminStorageSignedUrlInput): Promise<AdminStorageSignedUrlResult>;
+    createBucket(name: string, options?: AdminStorageBucketInput): Promise<AdminStorageBucket>;
+    listBuckets(): Promise<AdminStorageBucket[]>;
+    deleteBucket(name: string): Promise<{
+        ok: boolean;
+        removedObjects: number;
+    }>;
+    deleteBuckets(names: string[]): Promise<{
+        ok: boolean;
+        deleted: string[];
+        errors: Record<string, string>;
+    }>;
+    getBucketLocation(name: string): Promise<{
+        bucket: string;
+        kind: string;
+        region?: string;
+        endpoint?: string;
+    }>;
+    putObject(input: AdminPutObjectInput): Promise<AdminPutObjectResult>;
+    getObject(input: AdminGetObjectInput): Promise<AdminGetObjectResult>;
+    getObjectUrl(input: AdminGetObjectUrlInput): Promise<string>;
+    downloadObject(input: AdminDownloadObjectInput): Promise<AdminDownloadObjectResult>;
+    headObject(input: AdminHeadObjectInput): Promise<AdminStorageObjectMeta>;
+    headObjects(input: AdminHeadObjectsInput): Promise<AdminStorageObjectMeta[]>;
+    listObjects(input: AdminListObjectsInput): Promise<AdminListObjectsResult>;
+    copyObject(input: AdminCopyObjectInput): Promise<{
+        ok: boolean;
+    }>;
+    copyObjects(inputs: AdminCopyObjectInput[]): Promise<{
+        ok: boolean;
+        errors: Record<string, string>;
+    }>;
+    deleteObjects(input: AdminDeleteObjectsInput): Promise<{
+        ok: boolean;
+        deleted: string[];
+        errors: Record<string, string>;
+    }>;
+    /**
+     * Subscribe to WebSocket connection state changes.
+     * Initializes the live connection if not already open.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     *   const unsub = admin.onConnectionStateChange((state) => {
+     *     console.log("connection:", state);
+     *     // state: 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error'
+     *   });
+     *   // Later:
+     *   unsub();
+     */
+    onConnectionStateChange(listener: (state: AdminConnectionState) => void): () => void;
+    /**
+     * Disconnect realtime resources tied to this app instance.
+     * Safe to call multiple times.
+     */
+    disconnect(): void;
 }
 /**
  * Initialize a FlareAdmin app instance.
@@ -782,6 +1303,15 @@ declare function connectApp(config: FlareAdminConfig, name?: string): FlareAdmin
  * @throws If the app has not been initialized yet.
  */
 declare function getApp(name?: string): FlareAdminApp;
+/**
+ * Disconnect and remove an initialized app by name.
+ * Returns true when an app existed and was removed.
+ */
+declare function disconnectApp(name?: string): boolean;
+/**
+ * Disconnect and clear all initialized apps.
+ */
+declare function disconnectAllApps(): void;
 /**
  * Get the auth service from the default app.
  * Equivalent to `getApp().auth()`.
@@ -802,19 +1332,20 @@ declare function auth(name?: string): FlareAdminAuth;
 declare function db(name?: string): FlareAdminDb;
 /**
  * Get the real-time WebSocket connection from the default app.
- * Equivalent to `getApp().connection()`.
+ * Equivalent to `getApp().live()`.
  *
  * @example
- *   import { connection } from "@zuzjs/flare-admin";
- *   const unsub = connection().collection("users")
+ *   import { live } from "@zuzjs/flare-admin";
+ *   const unsub = live().collection("users")
  *     .where({ role: "admin" })
  *     .onSnapshot((snap) => console.log(snap));
  */
-declare function connection(name?: string): FlareAdminConnection;
+declare function live(name?: string): FlareAdminConnection;
 /**
  * Get the notifications service from the default app.
  * Equivalent to `getApp().notifications()`.
  */
 declare function notifications(name?: string): FlareAdminNotifications;
+declare function storage(name?: string): FlareAdminStorageS3;
 
-export { AdminCollectionReference, type AdminDocAddedCallback, type AdminDocChangedCallback, type AdminDocDeletedCallback, type AdminDocUpdatedCallback, AdminDocumentReference, AdminLiveCollectionReference, AdminLiveDocumentReference, type AdminPushSendInput, type AdminPushSendResult, type AdminPushToken, type AdminSnapshotCallback, type AdminSnapshotData, type AdminSubscriptionError, type AdminSubscriptionErrorCallback, type AdminSubscriptionHandle, type AggregateFunction, type AggregateSpec, type AnyFilter, type CreateCustomTokenOptions, type CursorValue, FlareAdminApp, type FlareAdminAuth, FlareAdminAuthService, type FlareAdminConfig, FlareAdminConnection, type FlareAdminDb, FlareAdminDbService, type FlareAdminNotifications, FlareAdminNotificationsService, FlareAdminWsConnection, type GroupByClause, type HavingClause, type JoinClause, type OrFilter, type OrderByClause, type QueryOperator, type StructuredQuery, type VectorSearchClause, type WhereCondition, type WhereFilter, auth, connectApp, connection, db, getApp, notifications };
+export { AdminCollectionReference, type AdminConnectionState, type AdminConnectionStateListener, type AdminCopyObjectInput, type AdminDeleteObjectsInput, type AdminDocAddedCallback, type AdminDocChangedCallback, type AdminDocDeletedCallback, type AdminDocUpdatedCallback, AdminDocumentReference, type AdminDownloadObjectInput, type AdminDownloadObjectResult, type AdminGetObjectInput, type AdminGetObjectResult, type AdminGetObjectUrlInput, type AdminHeadObjectInput, type AdminHeadObjectsInput, type AdminListObjectsInput, type AdminListObjectsResult, AdminLiveCollectionReference, AdminLiveDocumentReference, type AdminPushSendInput, type AdminPushSendResult, type AdminPushToken, type AdminPutObjectInput, type AdminPutObjectResult, type AdminSnapshotCallback, type AdminSnapshotData, type AdminStorageAwsConfig, type AdminStorageBucket, type AdminStorageBucketInput, type AdminStorageDeleteInput, type AdminStorageDownloadInput, type AdminStorageObjectMeta, type AdminStorageObjectResult, type AdminStorageRulesHistoryResult, type AdminStorageRulesPolicy, type AdminStorageServer, type AdminStorageServerInput, type AdminStorageServerPatchInput, AdminStorageSignedAction, type AdminStorageSignedUrlInput, type AdminStorageSignedUrlResult, type AdminStorageUploadInput, type AdminSubscriptionError, type AdminSubscriptionErrorCallback, type AdminSubscriptionHandle, type AggregateFunction, type AggregateSpec, type AnyFilter, type CreateCustomTokenOptions, type CursorValue, FlareAdminApp, type FlareAdminAuth, FlareAdminAuthService, type FlareAdminConfig, FlareAdminConnection, type FlareAdminDb, FlareAdminDbService, type FlareAdminNotifications, FlareAdminNotificationsService, type FlareAdminStorage, FlareAdminStorageS3, FlareAdminWsConnection, type GroupByClause, type HavingClause, type JoinClause, type OrFilter, type OrderByClause, type QueryOperator, ServerTimeStamp, ServerTimeStampField, type StructuredQuery, type VectorSearchClause, type WhereCondition, type WhereFilter, auth, connectApp, db, disconnectAllApps, disconnectApp, getApp, live, notifications, storage };