@progressive-development/pd-provider-firebase-functions 0.3.5 → 0.4.1

package/dist/auth-trash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-trash.d.ts","sourceRoot":"","sources":["../src/auth-trash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAgE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAQvG,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAEtC,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAkCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EACnD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAmCvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CA6Bf"}
+{"version":3,"file":"auth-trash.d.ts","sourceRoot":"","sources":["../src/auth-trash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,SAAS,CAAC;AAQjB,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAEtC,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EACnD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CA0CvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/auth-trash.js

@@ -1,5 +1,5 @@
 import { getAuth } from 'firebase-admin/auth';
-import { moveToTrash, getTrashItem, restoreFromTrash, permanentDelete } from './trash.js';
+import { moveToTrash, getTrashItem, permanentDelete, restoreFromTrash } from './trash.js';
 import { NotFoundError } from './errors.js';
 import { logger } from './logger.js';
 
@@ -11,20 +11,28 @@ function getAuthUidFromTrashItem(trashItem, options) {
   const data = trashItem.data;
   const uid = data[source];
   if (typeof uid !== "string" || !uid) {
-    throw new Error(`Auth UID field '${source}' not found or empty in trash item data`);
+    throw new Error(
+      `Auth UID field '${source}' not found or empty in trash item data`
+    );
   }
   return uid;
 }
 async function moveToTrashWithAuth(collection, documentId, deletedBy, objectType, options) {
   const authUid = options?.authUidSource === "documentId" || !options?.authUidSource ? documentId : documentId;
-  logger.info("Disabling Auth user before trash", { authUid, collection, documentId });
+  logger.info("Disabling Auth user before trash", {
+    authUid,
+    collection,
+    documentId
+  });
   try {
     await getAuth().updateUser(authUid, { disabled: true });
     logger.info("Auth user disabled", { authUid });
   } catch (error) {
     const authError = error;
     if (authError.code === "auth/user-not-found") {
-      logger.info("Auth user not found, continuing with trash operation", { authUid });
+      logger.info("Auth user not found, continuing with trash operation", {
+        authUid
+      });
     } else {
       throw error;
     }
@@ -56,14 +64,20 @@ async function restoreFromTrashWithAuth(trashItemId, options) {
   await restoreFromTrash(trashItemId, options?.databaseId);
   try {
     await getAuth().updateUser(authUid, { disabled: false });
-    logger.info("Document restored and Auth user re-enabled", { trashItemId, authUid });
+    logger.info("Document restored and Auth user re-enabled", {
+      trashItemId,
+      authUid
+    });
   } catch (error) {
     const authError = error;
     if (authError.code === "auth/user-not-found") {
-      logger.warn("Document restored but Auth user not found - manual Auth user creation required", {
-        trashItemId,
-        authUid
-      });
+      logger.warn(
+        "Document restored but Auth user not found - manual Auth user creation required",
+        {
+          trashItemId,
+          authUid
+        }
+      );
     } else {
       throw error;
     }
@@ -82,11 +96,17 @@ async function permanentDeleteWithAuth(trashItemId, options) {
   await permanentDelete(trashItemId, options?.databaseId);
   try {
     await getAuth().deleteUser(authUid);
-    logger.info("Trash item and Auth user permanently deleted", { trashItemId, authUid });
+    logger.info("Trash item and Auth user permanently deleted", {
+      trashItemId,
+      authUid
+    });
   } catch (error) {
     const authError = error;
     if (authError.code === "auth/user-not-found") {
-      logger.info("Auth user not found, trash item deleted", { trashItemId, authUid });
+      logger.info("Auth user not found, trash item deleted", {
+        trashItemId,
+        authUid
+      });
     } else {
       throw error;
     }

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,CASjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EAAE,GACrB,WAAW,CAUb;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,CAMjF"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,CASjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EAAE,GACrB,WAAW,CAUb;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,eAAe,EAAE,MAAM,GACtB,IAAI,CAMN"}

package/dist/counter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"counter.d.ts","sourceRoot":"","sources":["../src/counter.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAWjB"}
+{"version":3,"file":"counter.d.ts","sourceRoot":"","sources":["../src/counter.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/dist/counter.js

@@ -8,7 +8,11 @@ async function getNextCounter(counterName, databaseId) {
     const doc = await transaction.get(counterRef);
     const current = doc.exists ? doc.data()?.value ?? 0 : 0;
     const next = current + 1;
-    transaction.set(counterRef, { value: next, updatedAt: /* @__PURE__ */ new Date() }, { merge: true });
+    transaction.set(
+      counterRef,
+      { value: next, updatedAt: /* @__PURE__ */ new Date() },
+      { merge: true }
+    );
     return next;
   });
 }

package/dist/import-templates.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Reusable Mail Templates Import
+ *
+ * Imports mail templates from a templates directory into Firestore.
+ * Each template consists of three files:
+ *   - {name}.json          — metadata (name, subject)
+ *   - {name}.html.hbs      — HTML template
+ *   - {name}.txt.hbs       — Text template
+ */
+export interface ImportTemplatesConfig {
+    /** Path to the mail-templates/ directory */
+    templatesDir: string;
+    /** Path to the serviceAccountKey.json */
+    serviceAccountPath: string;
+    /** Optional Firestore named database */
+    databaseId?: string;
+    /** Optional collection name (default: "emailTemplates") */
+    collection?: string;
+    /** Optional single template name to import */
+    templateFilter?: string;
+    /** If true, no writes are performed (default: false) */
+    dryRun?: boolean;
+}
+/**
+ * Import mail templates into Firestore.
+ */
+export declare function runImportTemplates(config: ImportTemplatesConfig): Promise<void>;
+//# sourceMappingURL=import-templates.d.ts.map

package/dist/import-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-templates.d.ts","sourceRoot":"","sources":["../src/import-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAiDD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA2Ff"}

package/dist/import-templates.js

@@ -0,0 +1,113 @@
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { scriptLog, createScriptContext } from './script-helpers.js';
+
+function findTemplates(templatesDir) {
+  const files = readdirSync(templatesDir);
+  const jsonFiles = files.filter(
+    (f) => f.endsWith(".json") && f !== "serviceAccountKey.json"
+  );
+  return jsonFiles.map((f) => f.replace(".json", ""));
+}
+function loadTemplate(templatesDir, name) {
+  const jsonPath = `${templatesDir}/${name}.json`;
+  const htmlPath = `${templatesDir}/${name}.html.hbs`;
+  const textPath = `${templatesDir}/${name}.txt.hbs`;
+  if (!existsSync(jsonPath)) {
+    scriptLog(`Metadata not found: ${jsonPath}`, "error");
+    return null;
+  }
+  if (!existsSync(htmlPath)) {
+    scriptLog(`HTML template not found: ${htmlPath}`, "error");
+    return null;
+  }
+  if (!existsSync(textPath)) {
+    scriptLog(`Text template not found: ${textPath}`, "error");
+    return null;
+  }
+  const metadata = JSON.parse(
+    readFileSync(jsonPath, "utf-8")
+  );
+  const html = readFileSync(htmlPath, "utf-8");
+  const text = readFileSync(textPath, "utf-8");
+  return { ...metadata, html, text };
+}
+async function runImportTemplates(config) {
+  const {
+    templatesDir,
+    serviceAccountPath,
+    databaseId,
+    collection = "emailTemplates",
+    templateFilter,
+    dryRun = false
+  } = config;
+  if (!existsSync(templatesDir)) {
+    scriptLog(`Templates directory not found: ${templatesDir}`, "error");
+    process.exit(1);
+  }
+  const { db } = createScriptContext({
+    title: "Mail Templates Import",
+    serviceAccountPath,
+    databaseId,
+    dryRun
+  });
+  scriptLog(`Templates dir: ${templatesDir}`);
+  scriptLog(`Target collection: ${collection}`);
+  let templates = findTemplates(templatesDir);
+  if (templateFilter) {
+    templates = templates.filter((t) => t === templateFilter);
+    if (templates.length === 0) {
+      scriptLog(`Template not found: ${templateFilter}`, "error");
+      process.exit(1);
+    }
+  }
+  scriptLog(`Found ${templates.length} template(s): ${templates.join(", ")}`);
+  console.log("");
+  let successCount = 0;
+  let errorCount = 0;
+  for (const templateName of templates) {
+    const template = loadTemplate(templatesDir, templateName);
+    if (!template) {
+      errorCount++;
+      continue;
+    }
+    const docId = `${templateName}Id`;
+    console.log(`
+  ${templateName}`);
+    console.log(`   Document ID: ${docId}`);
+    console.log(`   Subject: ${template.subject}`);
+    console.log(`   HTML: ${template.html.length} chars`);
+    console.log(`   Text: ${template.text.length} chars`);
+    if (!dryRun) {
+      try {
+        await db.collection(collection).doc(docId).set({
+          name: template.name,
+          subject: template.subject,
+          html: template.html,
+          text: template.text,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        scriptLog(`Imported: ${templateName} -> ${docId}`, "success");
+        successCount++;
+      } catch (error) {
+        scriptLog(`Failed to import ${templateName}: ${error}`, "error");
+        errorCount++;
+      }
+    } else {
+      scriptLog(`Would import: ${templateName} -> ${docId}`, "info");
+      successCount++;
+    }
+  }
+  console.log("\n" + "-".repeat(50));
+  console.log(`
+Summary:`);
+  console.log(`   Success: ${successCount}`);
+  console.log(`   Errors:  ${errorCount}`);
+  if (dryRun) {
+    console.log(`
+   Run without --dry-run to apply changes.
+`);
+  }
+  process.exit(errorCount > 0 ? 1 : 0);
+}
+
+export { runImportTemplates };

package/dist/index.d.ts

@@ -1,13 +1,17 @@
 export type { ApiResponse, AuthContext } from './types';
 export { StatusCode } from './types';
-export { AppError, ValidationError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, EmailAlreadyUsedError, SC_EMAIL_ALREADY_USED } from './errors';
+export { AppError, ValidationError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, EmailAlreadyUsedError, SC_EMAIL_ALREADY_USED, } from './errors';
 export { requireAuth, requireClaims, requireOwnership } from './auth';
 export { success, created, handleError } from './response';
 export { getDb } from './firestore';
 export { getNextCounter } from './counter';
 export type { TrashItem } from './trash';
-export { moveToTrash, restoreFromTrash, permanentDelete, listTrash, getTrashItem } from './trash';
+export { moveToTrash, restoreFromTrash, permanentDelete, listTrash, getTrashItem, } from './trash';
 export type { AuthTrashOptions } from './auth-trash';
-export { moveToTrashWithAuth, restoreFromTrashWithAuth, permanentDeleteWithAuth } from './auth-trash';
+export { moveToTrashWithAuth, restoreFromTrashWithAuth, permanentDeleteWithAuth, } from './auth-trash';
 export { logger } from './logger';
+export type { LogType, ScriptContextConfig, ScriptContext, } from './script-helpers';
+export { scriptLog, initFirebaseAdmin, createScriptContext, } from './script-helpers';
+export type { ImportTemplatesConfig } from './import-templates';
+export { runImportTemplates } from './import-templates';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGpK,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGtE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG3D,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGlG,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAGtG,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,OAAO,EACL,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGtE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG3D,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,YAAY,EACV,OAAO,EACP,mBAAmB,EACnB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -7,3 +7,5 @@ export { getNextCounter } from './counter.js';
 export { getTrashItem, listTrash, moveToTrash, permanentDelete, restoreFromTrash } from './trash.js';
 export { moveToTrashWithAuth, permanentDeleteWithAuth, restoreFromTrashWithAuth } from './auth-trash.js';
 export { logger } from './logger.js';
+export { createScriptContext, initFirebaseAdmin, scriptLog } from './script-helpers.js';
+export { runImportTemplates } from './import-templates.js';

package/dist/response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AAIlD,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAmBxF"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AAIlD,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,GACb,WAAW,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB9C"}

package/dist/response.js

@@ -13,7 +13,10 @@ function handleError(error) {
     if (error.statusCode >= 500) {
       logger.error("App error", error);
     } else {
-      logger.warn("Request error", { code: error.code, message: error.message });
+      logger.warn("Request error", {
+        code: error.code,
+        message: error.message
+      });
     }
     return {
       statusCode: error.statusCode,

package/dist/script-helpers.d.ts

@@ -0,0 +1,35 @@
+import { Firestore } from 'firebase-admin/firestore';
+export type LogType = "info" | "success" | "error" | "warn";
+/**
+ * Print a prefixed log message to console.
+ */
+export declare function scriptLog(message: string, type?: LogType): void;
+/**
+ * Initialize Firebase Admin SDK if not already initialized.
+ */
+export declare function initFirebaseAdmin(serviceAccountPath: string): void;
+export interface ScriptContextConfig {
+    /** Script title shown in console header */
+    title: string;
+    /** Path to serviceAccountKey.json */
+    serviceAccountPath: string;
+    /** Optional Firestore named database */
+    databaseId?: string;
+    /** Dry-run mode (default: false) */
+    dryRun?: boolean;
+}
+export interface ScriptContext {
+    /** Firestore instance (cached via getDb) */
+    db: Firestore;
+    /** Whether dry-run mode is active */
+    dryRun: boolean;
+}
+/**
+ * Set up a script context: validates paths, initializes Firebase,
+ * returns a ready-to-use Firestore instance.
+ *
+ * Prints title, connection info, and dry-run banner.
+ * Calls `process.exit(1)` if the service account key is missing.
+ */
+export declare function createScriptContext(config: ScriptContextConfig): ScriptContext;
+//# sourceMappingURL=script-helpers.d.ts.map

package/dist/script-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-helpers.d.ts","sourceRoot":"","sources":["../src/script-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAQ1D,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAS5D;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,OAAgB,GAAG,IAAI,CAEvE;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAWlE;AAMD,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,EAAE,EAAE,SAAS,CAAC;IACd,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,mBAAmB,GAC1B,aAAa,CA+Bf"}

package/dist/script-helpers.js

@@ -0,0 +1,52 @@
+import { getApps, initializeApp, cert } from 'firebase-admin/app';
+import { existsSync, readFileSync } from 'fs';
+import { getDb } from './firestore.js';
+
+const LOG_PREFIX = {
+  info: "i ",
+  success: "OK",
+  error: "X ",
+  warn: "! "
+};
+function scriptLog(message, type = "info") {
+  console.log(`${LOG_PREFIX[type]} ${message}`);
+}
+function initFirebaseAdmin(serviceAccountPath) {
+  if (getApps().length > 0) return;
+  const serviceAccount = JSON.parse(
+    readFileSync(serviceAccountPath, "utf-8")
+  );
+  initializeApp({
+    credential: cert(serviceAccount),
+    databaseURL: `https://${serviceAccount.projectId}.firebaseio.com`
+  });
+}
+function createScriptContext(config) {
+  const { title, serviceAccountPath, databaseId, dryRun = false } = config;
+  console.log(`
+${title}
+`);
+  console.log("-".repeat(50));
+  if (!existsSync(serviceAccountPath)) {
+    scriptLog("Service Account Key not found!", "error");
+    console.log(`
+   Expected: ${serviceAccountPath}`);
+    console.log(`
+   Download from Firebase Console:`);
+    console.log(
+      `   Project Settings > Service Accounts > Generate new private key
+`
+    );
+    process.exit(1);
+  }
+  initFirebaseAdmin(serviceAccountPath);
+  const db = getDb(databaseId);
+  scriptLog(`Firestore: ${databaseId ?? "(default)"}`);
+  if (dryRun) {
+    scriptLog("DRY RUN - No changes will be made", "warn");
+  }
+  console.log("-".repeat(50));
+  return { db, dryRun };
+}
+
+export { createScriptContext, initFirebaseAdmin, scriptLog };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progressive-development/pd-provider-firebase-functions",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Firebase Functions v2 utilities for pd-spa-helper backend",
   "author": "PD Progressive Development",
   "license": "SEE LICENSE IN LICENSE",