clefbase 1.4.1 → 1.5.1

package/dist/functions.d.ts

@@ -0,0 +1,209 @@
+import { HttpClient } from "./http";
+import type { FunctionRuntime, FunctionTrigger, FunctionTriggerType, FunctionDef, FunctionExecution, FunctionsConfig, FunctionStats, DeployFunctionOptions, HttpsCallableResult } from "./types";
+export type { FunctionRuntime, FunctionTrigger, FunctionTriggerType, FunctionDef, FunctionExecution, FunctionsConfig, FunctionStats, DeployFunctionOptions, HttpsCallableResult, };
+/**
+ * Thrown by all Functions SDK methods when the server returns an error
+ * or the function itself errors / times out.
+ *
+ * @example
+ * import { FunctionsError } from "clefbase";
+ *
+ * try {
+ *   const { data } = await fns.call("myFunction", payload);
+ * } catch (err) {
+ *   if (err instanceof FunctionsError) {
+ *     console.error("HTTP status:", err.httpStatus); // e.g. 500
+ *     console.error("Message:",     err.message);
+ *   }
+ * }
+ */
+export declare class FunctionsError extends Error {
+    /** HTTP status code returned by the server, if available */
+    readonly httpStatus?: number | undefined;
+    constructor(message: string, 
+    /** HTTP status code returned by the server, if available */
+    httpStatus?: number | undefined);
+}
+/**
+ * Create a strongly-typed callable reference to an HTTP-triggered function.
+ * Store it once and call it as many times as needed.
+ *
+ * @example
+ * const add = httpsCallable<{ a: number; b: number }, { sum: number }>(fns, "addNumbers");
+ * const { data, durationMs } = await add({ a: 3, b: 4 });
+ * console.log(data.sum);    // 7
+ * console.log(durationMs);  // e.g. 42
+ */
+export declare function httpsCallable<TInput = unknown, TOutput = unknown>(fns: ClefbaseFunctions, name: string): (data?: TInput) => Promise<HttpsCallableResult<TOutput>>;
+/**
+ * Call an HTTP-triggered function in one shot — no need to create a callable ref.
+ * Equivalent to `httpsCallable(fns, name)(data)`.
+ *
+ * @example
+ * const { data } = await callFunction(fns, "resizeImage", { url: "https://..." });
+ */
+export declare function callFunction<TInput = unknown, TOutput = unknown>(fns: ClefbaseFunctions, name: string, data?: TInput): Promise<HttpsCallableResult<TOutput>>;
+/**
+ * Deploy (or redeploy) a function from source code.
+ * Equivalent to `fns.deploy(options)`.
+ *
+ * @example
+ * await deployFunction(fns, {
+ *   name:    "greetUser",
+ *   runtime: "node",
+ *   trigger: { type: "http" },
+ *   source:  `export async function handler(ctx) { return { hi: ctx.data.name }; }`,
+ * });
+ */
+export declare function deployFunction(fns: ClefbaseFunctions, options: DeployFunctionOptions): Promise<FunctionDef>;
+/**
+ * Delete a deployed function by name.
+ * Equivalent to `fns.delete(name)`.
+ */
+export declare function deleteFunction(fns: ClefbaseFunctions, name: string): Promise<{
+    deleted: boolean;
+    name: string;
+}>;
+/**
+ * List all functions deployed to this project.
+ * Equivalent to `fns.list()`.
+ */
+export declare function listFunctions(fns: ClefbaseFunctions): Promise<FunctionDef[]>;
+/**
+ * Fetch execution history for a function.
+ * Equivalent to `fns.executions(name, limit)`.
+ */
+export declare function getFunctionExecutions(fns: ClefbaseFunctions, name: string, limit?: number): Promise<FunctionExecution[]>;
+/**
+ * Attach a user auth token so that HTTP function calls include the caller's
+ * identity in `ctx.auth` inside the function.
+ *
+ * Obtain the token from `auth.signIn()` or `auth.signUp()`.
+ * Pass `null` to remove a previously set token (e.g. after sign-out).
+ *
+ * @example
+ * import { getAuth, getFunctions, setAuthToken, callFunction } from "clefbase";
+ *
+ * const auth = getAuth(app);
+ * const fns  = getFunctions(app);
+ *
+ * const { token } = await auth.signIn("alice@example.com", "password123");
+ * setAuthToken(app, token);
+ *
+ * // ctx.auth.uid / ctx.auth.email are now available inside the function
+ * const { data } = await callFunction(fns, "getUserProfile");
+ *
+ * // On sign-out:
+ * await auth.signOut();
+ * setAuthToken(app, null);
+ */
+export declare function setAuthToken(app: {
+    authToken?: string;
+}, token: string | null): void;
+/**
+ * Deploy a function from a source file on disk. **Node.js / CLI environments only.**
+ *
+ * Reads the file at `filePath` and calls `fns.deploy()` with the source.
+ * Runtime is NOT auto-detected from the file extension — pass it explicitly so
+ * you can deploy `.ts` files as Node.js without a separate transpile step.
+ *
+ * @example
+ * // Deploy a TypeScript file as a Node.js function
+ * await deployFromFile(fns, {
+ *   name:     "processOrder",
+ *   runtime:  "node",
+ *   trigger:  { type: "http" },
+ *   filePath: "./src/functions/processOrder.ts",
+ *   env:      { STRIPE_KEY: process.env.STRIPE_KEY! },
+ * });
+ *
+ * // Deploy a Python file
+ * await deployFromFile(fns, {
+ *   name:      "analyzeSentiment",
+ *   runtime:   "python",
+ *   trigger:   { type: "http" },
+ *   filePath:  "./fns/analyze_sentiment.py",
+ *   timeoutMs: 60_000,
+ * });
+ */
+export declare function deployFromFile(fns: ClefbaseFunctions, options: Omit<DeployFunctionOptions, "source"> & {
+    filePath: string;
+}): Promise<FunctionDef>;
+/**
+ * Clefbase Functions service — obtained via `getFunctions(app)`.
+ *
+ * You can use instance methods directly OR the equivalent top-level
+ * convenience functions (`httpsCallable`, `callFunction`, `deployFunction`,
+ * `deployFromFile`, `setAuthToken`, etc.) — both styles are supported.
+ *
+ * @example
+ * import { initClefbase, getFunctions, httpsCallable, setAuthToken } from "clefbase";
+ *
+ * const app = initClefbase({ serverUrl, projectId, apiKey, adminSecret: "" });
+ * const fns = getFunctions(app);
+ *
+ * // ── Deploy ──────────────────────────────────────────────────────────────
+ * await fns.deploy({
+ *   name:    "greetUser",
+ *   runtime: "node",
+ *   trigger: { type: "http" },
+ *   source:  `export async function handler(ctx) { return { hi: ctx.data.name }; }`,
+ * });
+ *
+ * // ── Typed callable ──────────────────────────────────────────────────────
+ * const greet = httpsCallable<{ name: string }, { hi: string }>(fns, "greetUser");
+ * const { data } = await greet({ name: "Alice" });
+ *
+ * // ── Auth-aware call ─────────────────────────────────────────────────────
+ * const { token } = await getAuth(app).signIn("alice@example.com", "pw");
+ * setAuthToken(app, token);
+ * await fns.call("secureFunction"); // ctx.auth.uid is now set
+ */
+export declare class ClefbaseFunctions {
+    private readonly _http;
+    /** @internal */
+    constructor(_http: HttpClient);
+    /**
+     * Initialise Functions for this project if not already done.
+     * `deploy()` calls this automatically, so you rarely need it directly.
+     */
+    initProject(opts?: {
+        maxConcurrentExecutions?: number;
+        defaultTimeoutMs?: number;
+    }): Promise<FunctionsConfig>;
+    /**
+     * Deploy (or redeploy) a function from source code.
+     *
+     * Redeploying with the same `name` updates the function in-place.
+     * Scheduled functions are re-armed with the new cron expression automatically.
+     */
+    deploy(options: DeployFunctionOptions): Promise<FunctionDef>;
+    /**
+     * List all functions deployed to this project.
+     * Source code is not included in the response.
+     */
+    list(): Promise<FunctionDef[]>;
+    /**
+     * Delete a deployed function by name.
+     * Scheduled functions are de-registered from the cron timer immediately.
+     */
+    delete(name: string): Promise<{
+        deleted: boolean;
+        name: string;
+    }>;
+    /**
+     * Call an HTTP-triggered function and return its result.
+     *
+     * Throws a `FunctionsError` on function error, timeout, or not-found.
+     * For a reusable typed reference, use `httpsCallable()` instead.
+     */
+    call<TInput = unknown, TOutput = unknown>(name: string, data?: TInput): Promise<HttpsCallableResult<TOutput>>;
+    /**
+     * Fetch execution history for a specific function.
+     *
+     * @param name   Function name
+     * @param limit  Max results to return (default: 20, max: 100)
+     */
+    executions(name: string, limit?: number): Promise<FunctionExecution[]>;
+}
+//# sourceMappingURL=functions.d.ts.map

package/dist/functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../src/functions.ts"],"names":[],"mappings":"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"}

package/dist/functions.js

@@ -0,0 +1,307 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClefbaseFunctions = exports.FunctionsError = void 0;
+exports.httpsCallable = httpsCallable;
+exports.callFunction = callFunction;
+exports.deployFunction = deployFunction;
+exports.deleteFunction = deleteFunction;
+exports.listFunctions = listFunctions;
+exports.getFunctionExecutions = getFunctionExecutions;
+exports.setAuthToken = setAuthToken;
+exports.deployFromFile = deployFromFile;
+const types_1 = require("./types");
+// ─── FunctionsError ───────────────────────────────────────────────────────────
+/**
+ * Thrown by all Functions SDK methods when the server returns an error
+ * or the function itself errors / times out.
+ *
+ * @example
+ * import { FunctionsError } from "clefbase";
+ *
+ * try {
+ *   const { data } = await fns.call("myFunction", payload);
+ * } catch (err) {
+ *   if (err instanceof FunctionsError) {
+ *     console.error("HTTP status:", err.httpStatus); // e.g. 500
+ *     console.error("Message:",     err.message);
+ *   }
+ * }
+ */
+class FunctionsError extends Error {
+    constructor(message, 
+    /** HTTP status code returned by the server, if available */
+    httpStatus) {
+        super(message);
+        this.httpStatus = httpStatus;
+        this.name = "FunctionsError";
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, FunctionsError);
+        }
+    }
+}
+exports.FunctionsError = FunctionsError;
+// ─── httpsCallable (top-level factory) ───────────────────────────────────────
+/**
+ * Create a strongly-typed callable reference to an HTTP-triggered function.
+ * Store it once and call it as many times as needed.
+ *
+ * @example
+ * const add = httpsCallable<{ a: number; b: number }, { sum: number }>(fns, "addNumbers");
+ * const { data, durationMs } = await add({ a: 3, b: 4 });
+ * console.log(data.sum);    // 7
+ * console.log(durationMs);  // e.g. 42
+ */
+function httpsCallable(fns, name) {
+    return (data) => fns.call(name, data);
+}
+// ─── callFunction ─────────────────────────────────────────────────────────────
+/**
+ * Call an HTTP-triggered function in one shot — no need to create a callable ref.
+ * Equivalent to `httpsCallable(fns, name)(data)`.
+ *
+ * @example
+ * const { data } = await callFunction(fns, "resizeImage", { url: "https://..." });
+ */
+async function callFunction(fns, name, data) {
+    return fns.call(name, data);
+}
+// ─── deployFunction ───────────────────────────────────────────────────────────
+/**
+ * Deploy (or redeploy) a function from source code.
+ * Equivalent to `fns.deploy(options)`.
+ *
+ * @example
+ * await deployFunction(fns, {
+ *   name:    "greetUser",
+ *   runtime: "node",
+ *   trigger: { type: "http" },
+ *   source:  `export async function handler(ctx) { return { hi: ctx.data.name }; }`,
+ * });
+ */
+async function deployFunction(fns, options) {
+    return fns.deploy(options);
+}
+// ─── deleteFunction ───────────────────────────────────────────────────────────
+/**
+ * Delete a deployed function by name.
+ * Equivalent to `fns.delete(name)`.
+ */
+async function deleteFunction(fns, name) {
+    return fns.delete(name);
+}
+// ─── listFunctions ────────────────────────────────────────────────────────────
+/**
+ * List all functions deployed to this project.
+ * Equivalent to `fns.list()`.
+ */
+async function listFunctions(fns) {
+    return fns.list();
+}
+// ─── getFunctionExecutions ────────────────────────────────────────────────────
+/**
+ * Fetch execution history for a function.
+ * Equivalent to `fns.executions(name, limit)`.
+ */
+async function getFunctionExecutions(fns, name, limit = 20) {
+    return fns.executions(name, limit);
+}
+// ─── setAuthToken ─────────────────────────────────────────────────────────────
+/**
+ * Attach a user auth token so that HTTP function calls include the caller's
+ * identity in `ctx.auth` inside the function.
+ *
+ * Obtain the token from `auth.signIn()` or `auth.signUp()`.
+ * Pass `null` to remove a previously set token (e.g. after sign-out).
+ *
+ * @example
+ * import { getAuth, getFunctions, setAuthToken, callFunction } from "clefbase";
+ *
+ * const auth = getAuth(app);
+ * const fns  = getFunctions(app);
+ *
+ * const { token } = await auth.signIn("alice@example.com", "password123");
+ * setAuthToken(app, token);
+ *
+ * // ctx.auth.uid / ctx.auth.email are now available inside the function
+ * const { data } = await callFunction(fns, "getUserProfile");
+ *
+ * // On sign-out:
+ * await auth.signOut();
+ * setAuthToken(app, null);
+ */
+function setAuthToken(app, token) {
+    app.authToken = token ?? undefined;
+}
+// ─── deployFromFile ───────────────────────────────────────────────────────────
+/**
+ * Deploy a function from a source file on disk. **Node.js / CLI environments only.**
+ *
+ * Reads the file at `filePath` and calls `fns.deploy()` with the source.
+ * Runtime is NOT auto-detected from the file extension — pass it explicitly so
+ * you can deploy `.ts` files as Node.js without a separate transpile step.
+ *
+ * @example
+ * // Deploy a TypeScript file as a Node.js function
+ * await deployFromFile(fns, {
+ *   name:     "processOrder",
+ *   runtime:  "node",
+ *   trigger:  { type: "http" },
+ *   filePath: "./src/functions/processOrder.ts",
+ *   env:      { STRIPE_KEY: process.env.STRIPE_KEY! },
+ * });
+ *
+ * // Deploy a Python file
+ * await deployFromFile(fns, {
+ *   name:      "analyzeSentiment",
+ *   runtime:   "python",
+ *   trigger:   { type: "http" },
+ *   filePath:  "./fns/analyze_sentiment.py",
+ *   timeoutMs: 60_000,
+ * });
+ */
+async function deployFromFile(fns, options) {
+    let readFileSync;
+    try {
+        ({ readFileSync } = await Promise.resolve().then(() => __importStar(require("fs"))));
+    }
+    catch {
+        throw new FunctionsError("deployFromFile() requires Node.js — it cannot be called in a browser environment.");
+    }
+    const { filePath, ...rest } = options;
+    const source = readFileSync(filePath, "utf8");
+    return fns.deploy({ ...rest, source });
+}
+// ─── ClefbaseFunctions ────────────────────────────────────────────────────────
+/**
+ * Clefbase Functions service — obtained via `getFunctions(app)`.
+ *
+ * You can use instance methods directly OR the equivalent top-level
+ * convenience functions (`httpsCallable`, `callFunction`, `deployFunction`,
+ * `deployFromFile`, `setAuthToken`, etc.) — both styles are supported.
+ *
+ * @example
+ * import { initClefbase, getFunctions, httpsCallable, setAuthToken } from "clefbase";
+ *
+ * const app = initClefbase({ serverUrl, projectId, apiKey, adminSecret: "" });
+ * const fns = getFunctions(app);
+ *
+ * // ── Deploy ──────────────────────────────────────────────────────────────
+ * await fns.deploy({
+ *   name:    "greetUser",
+ *   runtime: "node",
+ *   trigger: { type: "http" },
+ *   source:  `export async function handler(ctx) { return { hi: ctx.data.name }; }`,
+ * });
+ *
+ * // ── Typed callable ──────────────────────────────────────────────────────
+ * const greet = httpsCallable<{ name: string }, { hi: string }>(fns, "greetUser");
+ * const { data } = await greet({ name: "Alice" });
+ *
+ * // ── Auth-aware call ─────────────────────────────────────────────────────
+ * const { token } = await getAuth(app).signIn("alice@example.com", "pw");
+ * setAuthToken(app, token);
+ * await fns.call("secureFunction"); // ctx.auth.uid is now set
+ */
+class ClefbaseFunctions {
+    /** @internal */
+    constructor(_http) {
+        this._http = _http;
+    }
+    // ─── initProject ──────────────────────────────────────────────────────────
+    /**
+     * Initialise Functions for this project if not already done.
+     * `deploy()` calls this automatically, so you rarely need it directly.
+     */
+    async initProject(opts) {
+        return this._http.post("/", opts ?? {});
+    }
+    // ─── deploy ───────────────────────────────────────────────────────────────
+    /**
+     * Deploy (or redeploy) a function from source code.
+     *
+     * Redeploying with the same `name` updates the function in-place.
+     * Scheduled functions are re-armed with the new cron expression automatically.
+     */
+    async deploy(options) {
+        return this._http.post("/deploy", options);
+    }
+    // ─── list ─────────────────────────────────────────────────────────────────
+    /**
+     * List all functions deployed to this project.
+     * Source code is not included in the response.
+     */
+    async list() {
+        return this._http.get("/");
+    }
+    // ─── delete ───────────────────────────────────────────────────────────────
+    /**
+     * Delete a deployed function by name.
+     * Scheduled functions are de-registered from the cron timer immediately.
+     */
+    async delete(name) {
+        return this._http.delete(`/${encodeURIComponent(name)}`);
+    }
+    // ─── call ─────────────────────────────────────────────────────────────────
+    /**
+     * Call an HTTP-triggered function and return its result.
+     *
+     * Throws a `FunctionsError` on function error, timeout, or not-found.
+     * For a reusable typed reference, use `httpsCallable()` instead.
+     */
+    async call(name, data) {
+        try {
+            return await this._http.post(`/call/${encodeURIComponent(name)}`, { data: data ?? null });
+        }
+        catch (err) {
+            if (err instanceof types_1.ClefbaseError) {
+                throw new FunctionsError(err.message, err.status);
+            }
+            throw err;
+        }
+    }
+    // ─── executions ───────────────────────────────────────────────────────────
+    /**
+     * Fetch execution history for a specific function.
+     *
+     * @param name   Function name
+     * @param limit  Max results to return (default: 20, max: 100)
+     */
+    async executions(name, limit = 20) {
+        return this._http.get(`/${encodeURIComponent(name)}/executions?limit=${Math.min(limit, 100)}`);
+    }
+}
+exports.ClefbaseFunctions = ClefbaseFunctions;
+//# sourceMappingURL=functions.js.map

package/dist/functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.js","sourceRoot":"","sources":["../src/functions.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,43 +2,60 @@
  * clefbase — Firebase-style SDK for Clefbase / Cleforyx
  *
  * @example
- * import { initClefbase, getDatabase, getAuth, getStorage, getHosting, FieldValue } from "clefbase";
+ * import {
+ *   initClefbase, getDatabase, getAuth, getStorage, getHosting,
+ *   getFunctions, httpsCallable, callFunction, deployFunction, deployFromFile,
+ *   setAuthToken, FunctionsError, FieldValue,
+ * } from "clefbase";
  *
- * const app = initClefbase({
- *   serverUrl:   "https://api.cleforyx.com",
- *   projectId:   "my_project_abc",
- *   apiKey:      "cfx_...",
- *   adminSecret: "...",  // only needed for hosting
- * });
+ * const app  = initClefbase({ serverUrl, projectId, apiKey, adminSecret: "" });
+ * const fns  = getFunctions(app);
+ * const auth = getAuth(app);
  *
- * const db = getDatabase(app);
+ * // ── Auth-aware function call ───────────────────────────────────────────────
+ * const { token } = await auth.signIn("alice@example.com", "password123");
+ * setAuthToken(app, token);    // ctx.auth.uid / email now available in function
  *
- * // FieldValue sentinels
- * await db.collection("posts").doc("p1").update({
- *   views:      FieldValue.increment(1),
- *   score:      FieldValue.decrement(0.5),
- *   publishedAt: FieldValue.serverTimestamp(),
- *   draft:      FieldValue.deleteField(),
- *   tags:       FieldValue.arrayUnion("featured"),
- *   oldTags:    FieldValue.arrayRemove("wip"),
- * });
+ * // ── Typed callable ────────────────────────────────────────────────────────
+ * const greet = httpsCallable<{ name: string }, { message: string }>(fns, "greetUser");
+ * const { data } = await greet({ name: "Alice" });
+ *
+ * // ── One-shot call ─────────────────────────────────────────────────────────
+ * const { data } = await callFunction(fns, "greetUser", { name: "Bob" });
  *
- * // Batch writes
- * const batch = db.batch();
- * batch.update(db.collection("counters").doc("hits"), { n: FieldValue.increment(1) });
- * batch.delete(db.collection("sessions").doc("expired"));
- * await batch.commit();
+ * // ── Deploy from source ────────────────────────────────────────────────────
+ * await deployFunction(fns, {
+ *   name:    "greetUser",
+ *   runtime: "node",
+ *   trigger: { type: "http" },
+ *   source:  `export async function handler(ctx) { return { message: "Hi " + ctx.data.name }; }`,
+ * });
  *
- * // Transactions
- * await db.runTransaction(async (tx) => {
- *   const wallet = await tx.get(db.collection("wallets").doc(uid));
- *   tx.update(db.collection("wallets").doc(uid), { balance: (wallet?.balance as number ?? 0) + 10 });
+ * // ── Deploy from file (Node.js) ────────────────────────────────────────────
+ * await deployFromFile(fns, {
+ *   name:     "processOrder",
+ *   runtime:  "node",
+ *   trigger:  { type: "http" },
+ *   filePath: "./src/functions/processOrder.ts",
  * });
  *
- * // Collection-group queries
- * const allComments = await db.collectionGroup("comments").where({ approved: true }).getDocs();
+ * // ── Error handling ────────────────────────────────────────────────────────
+ * try {
+ *   await callFunction(fns, "mayFail");
+ * } catch (err) {
+ *   if (err instanceof FunctionsError) {
+ *     console.error(err.httpStatus, err.message);
+ *   }
+ * }
+ *
+ * // ── Database ──────────────────────────────────────────────────────────────
+ * const db = getDatabase(app);
+ * await db.collection("posts").doc("p1").update({
+ *   views:       FieldValue.increment(1),
+ *   publishedAt: FieldValue.serverTimestamp(),
+ * });
  */
-export { ClefbaseApp, initClefbase, getApp, getDatabase, getAuth, getStorage, getHosting, } from "./app";
+export { ClefbaseApp, initClefbase, getApp, getDatabase, getAuth, getStorage, getHosting, getFunctions, } from "./app";
 export { Database, CollectionReference, CollectionGroup, DocumentReference, Query, WriteBatch, Transaction, runTransaction, } from "./db";
 export { Auth } from "./auth";
 export type { GoogleButtonOptions } from "./auth";
@@ -48,6 +65,8 @@ export type { StorageImageStatus } from "./react/StorageImage";
 export { EmailVerificationCard } from "./react/EmailVerificationCard";
 export { ClefbaseHosting, SiteReference } from "./hosting";
 export type { HostingSite, HostingDeploy, HostingFile, DeployResult, DeployOptions, HostingStatus, DeployStatus, } from "./hosting";
+export { ClefbaseFunctions, FunctionsError, httpsCallable, callFunction, deployFunction, deleteFunction, listFunctions, getFunctionExecutions, setAuthToken, deployFromFile, } from "./functions";
+export type { FunctionRuntime, FunctionTrigger, FunctionTriggerType, FunctionDef, FunctionExecution, FunctionsConfig, FunctionStats, DeployFunctionOptions, HttpsCallableResult, } from "./functions";
 export { FieldValue, FieldValueSentinel } from "./field_value";
 export type { FieldValueType } from "./field_value";
 export type { ClefbaseConfig, ClefbaseDocument, QueryOptions, QueryResult, FilterOperator, WhereClause, WhereValue, AuthUser, AuthSession, AuthResult, } from "./types";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EACL,WAAW,EACX,YAAY,EACZ,MAAM,EACN,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,GACX,MAAM,OAAO,CAAC;AAGf,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,KAAK,EACL,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,MAAM,CAAC;AAGd,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,YAAY,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAGlD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC/E,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAQ7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3D,YAAY,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,GACb,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGpD,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAGH,OAAO,EACL,WAAW,EACX,YAAY,EACZ,MAAM,EACN,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,YAAY,GACb,MAAM,OAAO,CAAC;AAGf,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,KAAK,EACL,UAAU,EACV,WAAW,EACX,cAAc,GACf,MAAM,MAAM,CAAC;AAGd,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,YAAY,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAGlD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC/E,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3D,YAAY,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,GACb,MAAM,WAAW,CAAC;AAGnB,OAAO,EAEL,iBAAiB,EAEjB,cAAc,EAEd,aAAa,EACb,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGpD,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,UAAU,EACV,QAAQ,EACR,WAAW,EACX,UAAU,GACX,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}