@zuzjs/flare-admin 0.1.8 → 0.1.10

package/dist/index.d.cts

@@ -144,6 +144,7 @@ interface AdminStorageUploadInput {
     path: string;
     contentBase64: string;
     contentType?: string;
+    access?: "public" | "private";
     encrypt?: boolean;
 }
 interface AdminStorageDownloadInput {
@@ -159,6 +160,8 @@ interface AdminStorageObjectResult {
     ok: boolean;
     path: string;
     key: string;
+    access?: "public" | "private";
+    url?: string;
     encrypted?: boolean;
     size?: number;
     contentBase64?: string;
@@ -177,6 +180,7 @@ interface AdminStorageSignedUrlInput {
     expiresInSeconds?: number;
     sizeBytes?: number;
     contentType?: string;
+    access?: "public" | "private";
     encrypt?: boolean;
     decrypt?: boolean;
     forceDownload?: boolean;
@@ -341,6 +345,8 @@ interface AdminStorageObjectMeta {
     bucket: string;
     size: number;
     contentType: string;
+    access?: "public" | "private";
+    url?: string;
     encrypted: boolean;
     createdAt?: unknown;
     updatedAt?: unknown;
@@ -352,7 +358,9 @@ interface AdminPutObjectInput {
     /** 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. */
+    /** Public/private object access. Defaults to public. */
+    access?: "public" | "private";
+    /** Encrypt at rest with AES-256-GCM. Defaults to false. */
     encrypt?: boolean;
     /**
      * Max payload bytes for the base64-over-JSON upload path.
@@ -365,6 +373,8 @@ interface AdminPutObjectResult {
     ok: boolean;
     bucket: string;
     key: string;
+    access: "public" | "private";
+    url?: string;
     size: number;
     encrypted: boolean;
 }
@@ -413,6 +423,105 @@ interface AdminDeleteObjectsInput {
     bucket: string;
     keys: string[];
 }
+type AdminFunctionScopeType = "collection" | "document" | "field";
+type AdminFunctionTargetType = "compiled_plan" | "internal" | "webhook" | "isolated_runtime";
+type AdminMutationOperation = "create" | "update" | "delete" | "other";
+type AdminFunctionExecutionStatus = "pending" | "running" | "success" | "failure" | "timeout";
+interface AdminFunctionScope {
+    type?: AdminFunctionScopeType;
+    collection?: string;
+    document_id?: string;
+    fields?: string[];
+}
+interface AdminFunctionTarget {
+    type?: AdminFunctionTargetType;
+    source?: string;
+    handler?: string;
+    url?: string;
+}
+interface AdminCloudFunction {
+    id: string;
+    appId: string;
+    name: string;
+    enabled: boolean;
+    scope: AdminFunctionScope;
+    target: AdminFunctionTarget;
+    timeoutMs?: number;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface AdminCreateFunctionInput {
+    id?: string;
+    name: string;
+    enabled?: boolean;
+    scope: AdminFunctionScope;
+    target: AdminFunctionTarget;
+    timeoutMs?: number;
+}
+interface AdminPatchFunctionInput {
+    name?: string;
+    enabled?: boolean;
+    scope?: AdminFunctionScope;
+    target?: AdminFunctionTarget;
+    timeoutMs?: number;
+}
+interface AdminInvokeFunctionInput {
+    documentId?: string;
+    operation?: AdminMutationOperation;
+    changedFields?: string[];
+    updatedFields?: Record<string, unknown>;
+    removedFields?: string[];
+    fullDocument?: Record<string, unknown>;
+    data?: unknown;
+    auth?: unknown;
+    context?: Record<string, unknown>;
+}
+interface AdminInvokeFunctionResult {
+    ok: boolean;
+    functionId: string;
+    status: AdminFunctionExecutionStatus;
+    output?: unknown;
+    error?: string;
+    durationMs?: number;
+    executionId?: string;
+}
+interface AdminFunctionExecution {
+    id: string;
+    functionId: string;
+    appId: string;
+    status: AdminFunctionExecutionStatus;
+    triggeredBy?: string;
+    durationMs?: number;
+    output?: unknown;
+    error?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface AdminFunctionValidationResult {
+    valid: boolean;
+    diagnostics: unknown[];
+    mode?: "server" | "local_fallback" | "unavailable";
+}
+interface FlareAdminFunctions {
+    list(): Promise<AdminCloudFunction[]>;
+    get(functionId: string): Promise<AdminCloudFunction | null>;
+    create(input: AdminCreateFunctionInput): Promise<AdminCloudFunction>;
+    patch(functionId: string, input: AdminPatchFunctionInput): Promise<AdminCloudFunction>;
+    upsert(functionId: string, input: AdminCreateFunctionInput): Promise<AdminCloudFunction>;
+    delete(functionId: string): Promise<{
+        ok: boolean;
+        id: string;
+    }>;
+    invoke(functionId: string, input?: AdminInvokeFunctionInput): Promise<AdminInvokeFunctionResult>;
+    executions(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        list: AdminFunctionExecution[];
+        total: number;
+    }>;
+    validate(source: string, functionId?: string): Promise<AdminFunctionValidationResult>;
+}
 type QueryOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "array-contains" | "array-contains-any" | "elem-match" | "like" | "not-like" | "contains" | "exists" | "not-exists";
 interface WhereFilter {
     field: string;
@@ -691,32 +800,6 @@ interface AdminSubscriptionHandle {
     catch: (callback: AdminSubscriptionErrorCallback) => AdminSubscriptionHandle;
 }
 
-declare class AdminDocumentReference<T = Record<string, unknown>> {
-    private readonly cfg;
-    readonly collection: string;
-    readonly id: string;
-    constructor(cfg: Required<FlareAdminConfig>, collection: string, id: string);
-    private get baseUrl();
-    private get headers();
-    private request;
-    /** Fetch this document. Returns `null` if it does not exist. */
-    get(): Promise<T | null>;
-    /**
-     * Replace (or create) this document entirely.
-     * All fields not in `data` are removed.
-     */
-    set(data: Partial<T>): Promise<void>;
-    /**
-     * Merge `data` into the existing document (upsert).
-     * Only the provided fields are changed.
-     */
-    update(data: Partial<T>): Promise<void>;
-    /** Delete this document. */
-    delete(): Promise<void>;
-    /** Return the parent collection reference. */
-    parent(): AdminCollectionReference<T>;
-}
-
 declare class AdminCollectionReference<T = Record<string, unknown>> {
     private readonly cfg;
     readonly name: string;
@@ -838,6 +921,32 @@ declare class AdminCollectionReference<T = Record<string, unknown>> {
     doc(id: string): AdminDocumentReference<T>;
 }
 
+declare class AdminDocumentReference<T = Record<string, unknown>> {
+    private readonly cfg;
+    readonly collection: string;
+    readonly id: string;
+    constructor(cfg: Required<FlareAdminConfig>, collection: string, id: string);
+    private get baseUrl();
+    private get headers();
+    private request;
+    /** Fetch this document. Returns `null` if it does not exist. */
+    get(): Promise<T | null>;
+    /**
+     * Replace (or create) this document entirely.
+     * All fields not in `data` are removed.
+     */
+    set(data: Partial<T>): Promise<void>;
+    /**
+     * Merge `data` into the existing document (upsert).
+     * Only the provided fields are changed.
+     */
+    update(data: Partial<T>): Promise<void>;
+    /** Delete this document. */
+    delete(): Promise<void>;
+    /** Return the parent collection reference. */
+    parent(): AdminCollectionReference<T>;
+}
+
 declare class FlareAdminDbService implements FlareAdminDb {
     private readonly cfg;
     constructor(cfg: Required<FlareAdminConfig>);
@@ -1201,6 +1310,38 @@ declare class FlareAdminWsConnection {
     private _handle;
 }
 
+declare class FlareAdminFunctionsService implements FlareAdminFunctions {
+    private readonly cfg;
+    private readonly targetAppId;
+    constructor(cfg: Required<FlareAdminConfig>, targetAppId?: string);
+    private get appId();
+    private get callerAppId();
+    private baseUrl;
+    private get authParams();
+    private get headers();
+    private url;
+    private request;
+    private extractFunction;
+    list(): Promise<AdminCloudFunction[]>;
+    get(functionId: string): Promise<AdminCloudFunction | null>;
+    create(input: AdminCreateFunctionInput): Promise<AdminCloudFunction>;
+    patch(functionId: string, input: AdminPatchFunctionInput): Promise<AdminCloudFunction>;
+    upsert(functionId: string, input: AdminCreateFunctionInput): Promise<AdminCloudFunction>;
+    delete(functionId: string): Promise<{
+        ok: boolean;
+        id: string;
+    }>;
+    invoke(functionId: string, input?: AdminInvokeFunctionInput): Promise<AdminInvokeFunctionResult>;
+    executions(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        list: AdminFunctionExecution[];
+        total: number;
+    }>;
+    validate(source: string, functionId?: string): Promise<AdminFunctionValidationResult>;
+}
+
 /**
  * Sentinel value that asks flare-node to write the current server timestamp.
  *
@@ -1227,6 +1368,7 @@ declare class FlareAdminApp {
     private _notifications?;
     private _storage?;
     private _storageS3?;
+    private _functions?;
     /**
      * Access the auth service.
      *
@@ -1251,6 +1393,29 @@ declare class FlareAdminApp {
      *   await admin.db().collection("users").doc("alice").update({ plan: "pro" });
      */
     db(): FlareAdminDb;
+    /**
+     * Generates a standard 20-character Flare document ID.
+     * UUID v4 without dashes, first 20 chars — matches the Rust server-side format.
+     *
+     * ```ts
+     * const id = admin.generateFlareId();
+     * await admin.db().collection('orders').doc(id).set({ total: 99, id });
+     * ```
+     */
+    generateFlareId(): string;
+    /**
+     * Creates an AdminDocumentReference with a pre-generated Flare ID.
+     * Use `.id` to get the ID before any network call.
+     *
+     * ```ts
+     * const ref = admin.doc('orders');
+     * const id  = ref.id;
+     * await ref.set({ total: 99, id });
+     * ```
+     */
+    doc<T = Record<string, unknown>>(collectionName: string): AdminDocumentReference<T> & {
+        id: string;
+    };
     /**
      * Open (or reuse) a persistent admin WebSocket connection.
      * One socket is shared per app instance — call `.disconnect()` when done.
@@ -1280,6 +1445,25 @@ declare class FlareAdminApp {
      *   admin.live().disconnect();
      */
     live(): FlareAdminConnection;
+    /**
+     * Access cloud functions management APIs.
+     * Requires `adminKey` — operations run as admin, bypassing auth checks.
+     *
+     * @example
+     *   const fns = await admin.functions().list();
+     *   await admin.functions().invoke('my-fn', { data: { userId: 'abc' } });
+     *   await admin.functions().upsert('guard-fn', {
+     *     name: 'guard_fn',
+     *     scope: { type: 'collection', collection: 'orders' },
+     *     target: { type: 'compiled_plan', source: 'if exists(event.invocation.auth.uid) { ... }' },
+     *   });
+     */
+    functions(): FlareAdminFunctions;
+    /**
+     * Access cloud functions for a specific target app.
+     * The caller identity remains this admin app's credentials; only the path target changes.
+     */
+    functionsFor(appId: string): FlareAdminFunctions;
     /**
      * Access push notification management APIs.
      */
@@ -1417,4 +1601,4 @@ declare function live(name?: string): FlareAdminConnection;
 declare function notifications(name?: string): FlareAdminNotifications;
 declare function storage(name?: string): FlareAdminStorageS3;
 
-export { type AdminBulkWriteOperation, type AdminBulkWriteOptions, type AdminBulkWriteProgress, type AdminBulkWriteResult, 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 AdminUpdateManyItem, 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 };
+export { type AdminBulkWriteOperation, type AdminBulkWriteOptions, type AdminBulkWriteProgress, type AdminBulkWriteResult, type AdminCloudFunction, AdminCollectionReference, type AdminConnectionState, type AdminConnectionStateListener, type AdminCopyObjectInput, type AdminCreateFunctionInput, type AdminDeleteObjectsInput, type AdminDocAddedCallback, type AdminDocChangedCallback, type AdminDocDeletedCallback, type AdminDocUpdatedCallback, AdminDocumentReference, type AdminDownloadObjectInput, type AdminDownloadObjectResult, type AdminFunctionExecution, type AdminFunctionExecutionStatus, type AdminFunctionScope, type AdminFunctionScopeType, type AdminFunctionTarget, type AdminFunctionTargetType, type AdminGetObjectInput, type AdminGetObjectResult, type AdminGetObjectUrlInput, type AdminHeadObjectInput, type AdminHeadObjectsInput, type AdminInvokeFunctionInput, type AdminInvokeFunctionResult, type AdminListObjectsInput, type AdminListObjectsResult, AdminLiveCollectionReference, AdminLiveDocumentReference, type AdminMutationOperation, type AdminPatchFunctionInput, 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 AdminUpdateManyItem, type AggregateFunction, type AggregateSpec, type AnyFilter, type CreateCustomTokenOptions, type CursorValue, FlareAdminApp, type FlareAdminAuth, FlareAdminAuthService, type FlareAdminConfig, FlareAdminConnection, type FlareAdminDb, FlareAdminDbService, type FlareAdminFunctions, FlareAdminFunctionsService, 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 };

package/dist/index.d.ts

@@ -40,6 +40,7 @@
  *     .onSnapshot((snap) => console.log(snap));
  */
 export { AdminStorageSignedAction } from "./types";
+export type { AdminCloudFunction, AdminCreateFunctionInput, AdminFunctionExecution, AdminFunctionExecutionStatus, AdminFunctionScope, AdminFunctionScopeType, AdminFunctionTarget, AdminFunctionTargetType, AdminInvokeFunctionInput, AdminInvokeFunctionResult, AdminMutationOperation, AdminPatchFunctionInput, FlareAdminFunctions, } from "./types";
 export type { AdminBulkWriteOperation, AdminBulkWriteOptions, AdminBulkWriteProgress, AdminBulkWriteResult, AdminConnectionState, AdminConnectionStateListener, AdminCopyObjectInput, AdminDeleteObjectsInput, AdminDocAddedCallback, AdminDocChangedCallback, AdminDocDeletedCallback, AdminDocUpdatedCallback, AdminDownloadObjectInput, AdminDownloadObjectResult, AdminGetObjectInput, AdminGetObjectResult, AdminGetObjectUrlInput, AdminHeadObjectInput, AdminHeadObjectsInput, AdminListObjectsInput, AdminListObjectsResult, AdminPushSendInput, AdminPushSendResult, AdminPushToken, AdminPutObjectInput, AdminPutObjectResult, AdminSnapshotCallback, AdminSnapshotData, AdminStorageAwsConfig, AdminStorageBucket, AdminStorageBucketInput, AdminStorageDeleteInput, AdminStorageDownloadInput, AdminStorageObjectMeta, AdminStorageObjectResult, AdminStorageRulesHistoryResult, AdminStorageRulesPolicy, AdminStorageServer, AdminStorageServerInput, AdminStorageServerPatchInput, AdminStorageSignedUrlInput, AdminStorageSignedUrlResult, AdminStorageUploadInput, AdminSubscriptionError, AdminSubscriptionErrorCallback, AdminSubscriptionHandle, AdminUpdateManyItem, AggregateFunction, AggregateSpec, AnyFilter, CreateCustomTokenOptions, CursorValue, FlareAdminAuth, FlareAdminConfig, FlareAdminDb, FlareAdminNotifications, FlareAdminStorage, GroupByClause, HavingClause, JoinClause, OrderByClause, OrFilter, QueryOperator, StructuredQuery, VectorSearchClause, WhereCondition, WhereFilter } from "./types";
 export { AdminCollectionReference } from "./db/Collection";
 export { AdminDocumentReference } from "./db/Document";
@@ -51,9 +52,10 @@ export { FlareAdminConnection } from "./realtime/Connection";
 export { AdminLiveCollectionReference } from "./realtime/LiveCollection";
 export { AdminLiveDocumentReference } from "./realtime/LiveDocument";
 export { FlareAdminWsConnection } from "./realtime/WsConnection";
+export { FlareAdminFunctionsService } from "./lib/functions";
 import { FlareAdminStorageS3 } from "./lib/storage";
 import { FlareAdminConnection } from "./realtime/Connection";
-import { AdminCopyObjectInput, AdminDeleteObjectsInput, AdminDownloadObjectInput, AdminDownloadObjectResult, AdminGetObjectInput, AdminGetObjectResult, AdminGetObjectUrlInput, AdminHeadObjectInput, AdminHeadObjectsInput, AdminListObjectsInput, AdminListObjectsResult, AdminPutObjectInput, AdminPutObjectResult, AdminStorageBucket, AdminStorageBucketInput, AdminStorageObjectMeta, AdminStorageSignedUrlInput, AdminStorageSignedUrlResult, FlareAdminAuth, FlareAdminConfig, FlareAdminDb, FlareAdminNotifications } from "./types";
+import { AdminCopyObjectInput, AdminDeleteObjectsInput, AdminDownloadObjectInput, AdminDownloadObjectResult, AdminGetObjectInput, AdminGetObjectResult, AdminGetObjectUrlInput, AdminHeadObjectInput, AdminHeadObjectsInput, AdminListObjectsInput, AdminListObjectsResult, AdminPutObjectInput, AdminPutObjectResult, AdminStorageBucket, AdminStorageBucketInput, AdminStorageObjectMeta, AdminStorageSignedUrlInput, AdminStorageSignedUrlResult, FlareAdminAuth, FlareAdminConfig, FlareAdminDb, FlareAdminFunctions, FlareAdminNotifications } from "./types";
 /**
  * A FlareAdmin application instance.
  * Create one with `connectApp()` and keep it as a module-level singleton.
@@ -66,6 +68,7 @@ export declare class FlareAdminApp {
     private _notifications?;
     private _storage?;
     private _storageS3?;
+    private _functions?;
     /**
      * Access the auth service.
      *
@@ -90,6 +93,29 @@ export declare class FlareAdminApp {
      *   await admin.db().collection("users").doc("alice").update({ plan: "pro" });
      */
     db(): FlareAdminDb;
+    /**
+     * Generates a standard 20-character Flare document ID.
+     * UUID v4 without dashes, first 20 chars — matches the Rust server-side format.
+     *
+     * ```ts
+     * const id = admin.generateFlareId();
+     * await admin.db().collection('orders').doc(id).set({ total: 99, id });
+     * ```
+     */
+    generateFlareId(): string;
+    /**
+     * Creates an AdminDocumentReference with a pre-generated Flare ID.
+     * Use `.id` to get the ID before any network call.
+     *
+     * ```ts
+     * const ref = admin.doc('orders');
+     * const id  = ref.id;
+     * await ref.set({ total: 99, id });
+     * ```
+     */
+    doc<T = Record<string, unknown>>(collectionName: string): import('./db/Document').AdminDocumentReference<T> & {
+        id: string;
+    };
     /**
      * Open (or reuse) a persistent admin WebSocket connection.
      * One socket is shared per app instance — call `.disconnect()` when done.
@@ -119,6 +145,25 @@ export declare class FlareAdminApp {
      *   admin.live().disconnect();
      */
     live(): FlareAdminConnection;
+    /**
+     * Access cloud functions management APIs.
+     * Requires `adminKey` — operations run as admin, bypassing auth checks.
+     *
+     * @example
+     *   const fns = await admin.functions().list();
+     *   await admin.functions().invoke('my-fn', { data: { userId: 'abc' } });
+     *   await admin.functions().upsert('guard-fn', {
+     *     name: 'guard_fn',
+     *     scope: { type: 'collection', collection: 'orders' },
+     *     target: { type: 'compiled_plan', source: 'if exists(event.invocation.auth.uid) { ... }' },
+     *   });
+     */
+    functions(): FlareAdminFunctions;
+    /**
+     * Access cloud functions for a specific target app.
+     * The caller identity remains this admin app's credentials; only the path target changes.
+     */
+    functionsFor(appId: string): FlareAdminFunctions;
     /**
      * Access push notification management APIs.
      */