akeyless-server-commons 1.0.204 → 1.0.206

package/dist/helpers/postponed_actions.js

@@ -0,0 +1,358 @@
+import { FieldValue, Timestamp } from "firebase-admin/firestore";
+import { db } from "./firebase_helpers";
+import { logger } from "../managers";
+const POSTPONED_ACTIONS_COLLECTION = "nx-postponed-actions";
+export var PostponedActionStatus;
+(function (PostponedActionStatus) {
+    PostponedActionStatus["pending"] = "pending";
+    PostponedActionStatus["processing"] = "processing";
+    PostponedActionStatus["completed"] = "completed";
+    PostponedActionStatus["cancelled"] = "cancelled";
+    PostponedActionStatus["failed"] = "failed";
+})(PostponedActionStatus || (PostponedActionStatus = {}));
+const get_ref = (key) => {
+    if (!key.trim()) {
+        throw new Error("postponed action key must not be empty");
+    }
+    if (key.includes("/")) {
+        throw new Error("postponed action key must not contain '/'");
+    }
+    return db.collection(POSTPONED_ACTIONS_COLLECTION).doc(key);
+};
+export const resolve_postponed_action_time = (value, now = new Date()) => {
+    if (value instanceof Date || typeof value === "string") {
+        const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+        if (!Number.isFinite(date.getTime())) {
+            throw new Error("execute_at must be a valid date");
+        }
+        return date;
+    }
+    const { minutes = 0, hours = 0 } = value;
+    if (!Number.isFinite(minutes) || !Number.isFinite(hours) || minutes < 0 || hours < 0 || minutes + hours <= 0) {
+        throw new Error("relative execute_at must contain positive finite minutes or hours");
+    }
+    return new Date(now.getTime() + (minutes + hours * 60) * 60_000);
+};
+const validate_text = (value, field_name) => {
+    if (!value.trim()) {
+        throw new Error(`postponed action ${field_name} must not be empty`);
+    }
+};
+const validate_details = (details) => {
+    if (!details || Array.isArray(details) || typeof details !== "object") {
+        throw new Error("postponed action details must be a JSON object");
+    }
+    try {
+        JSON.stringify(details, (_key, value) => {
+            if (value === undefined || typeof value === "bigint" || typeof value === "function" || typeof value === "symbol") {
+                throw new Error("unsupported JSON value");
+            }
+            if (typeof value === "number" && !Number.isFinite(value)) {
+                throw new Error("JSON numbers must be finite");
+            }
+            return value;
+        });
+    }
+    catch (error) {
+        throw new Error("postponed action details must be JSON serializable", { cause: error });
+    }
+};
+const timestamp_to_date = (value, field_name) => {
+    if (value instanceof Timestamp)
+        return value.toDate();
+    if (value instanceof Date)
+        return value;
+    throw new Error(`postponed action has invalid ${field_name}`);
+};
+const optional_timestamp_to_date = (value, field_name) => {
+    return value === undefined ? undefined : timestamp_to_date(value, field_name);
+};
+const to_postponed_action = (snapshot) => {
+    const value = snapshot.data();
+    if (!snapshot.exists || !value) {
+        throw new Error(`postponed action '${snapshot.id}' does not exist`);
+    }
+    return {
+        key: snapshot.id,
+        details: value.details,
+        action_type: value.action_type,
+        description: value.description,
+        execute_at: timestamp_to_date(value.execute_at, "execute_at"),
+        status: value.status,
+        attempt_count: typeof value.attempt_count === "number" ? value.attempt_count : 0,
+        created_at: timestamp_to_date(value.created_at, "created_at"),
+        updated_at: timestamp_to_date(value.updated_at, "updated_at"),
+        started_at: optional_timestamp_to_date(value.started_at, "started_at"),
+        completed_at: optional_timestamp_to_date(value.completed_at, "completed_at"),
+        cancelled_at: optional_timestamp_to_date(value.cancelled_at, "cancelled_at"),
+        failed_at: optional_timestamp_to_date(value.failed_at, "failed_at"),
+        error: typeof value.error === "string" ? value.error : undefined,
+    };
+};
+const assert_status = (key, actual, allowed) => {
+    if (!allowed.includes(actual)) {
+        throw new Error(`postponed action '${key}' has status '${String(actual)}'; expected ${allowed.join(" or ")}`);
+    }
+};
+const get_postponed_action_core = async (key) => {
+    const snapshot = await get_ref(key).get();
+    return snapshot.exists ? to_postponed_action(snapshot) : null;
+};
+const add_postponed_action_core = async (input) => {
+    validate_details(input.details);
+    validate_text(input.action_type, "action_type");
+    validate_text(input.description, "description");
+    const ref = get_ref(input.key);
+    const execute_at = resolve_postponed_action_time(input.execute_at);
+    const now = new Date();
+    return db.runTransaction(async (transaction) => {
+        const snapshot = await transaction.get(ref);
+        if (snapshot.exists) {
+            assert_status(input.key, snapshot.get("status"), [PostponedActionStatus.pending]);
+            transaction.update(ref, {
+                details: input.details,
+                action_type: input.action_type,
+                description: input.description,
+                execute_at,
+                updated_at: now,
+            });
+            return {
+                ...to_postponed_action(snapshot),
+                details: input.details,
+                action_type: input.action_type,
+                description: input.description,
+                execute_at,
+                updated_at: now,
+            };
+        }
+        const action = {
+            key: input.key,
+            details: input.details,
+            action_type: input.action_type,
+            description: input.description,
+            execute_at,
+            status: PostponedActionStatus.pending,
+            attempt_count: 0,
+            created_at: now,
+            updated_at: now,
+        };
+        transaction.create(ref, action);
+        return action;
+    });
+};
+const update_postponed_action_core = async (key, input) => {
+    if (input.details === undefined && input.action_type === undefined && input.description === undefined && input.execute_at === undefined) {
+        throw new Error("postponed action update must contain details, action_type, description or execute_at");
+    }
+    if (input.details !== undefined)
+        validate_details(input.details);
+    if (input.action_type !== undefined)
+        validate_text(input.action_type, "action_type");
+    if (input.description !== undefined)
+        validate_text(input.description, "description");
+    const ref = get_ref(key);
+    await db.runTransaction(async (transaction) => {
+        const snapshot = await transaction.get(ref);
+        if (!snapshot.exists)
+            throw new Error(`postponed action '${key}' does not exist`);
+        assert_status(key, snapshot.get("status"), [PostponedActionStatus.pending]);
+        transaction.update(ref, {
+            ...(input.details === undefined ? {} : { details: input.details }),
+            ...(input.action_type === undefined ? {} : { action_type: input.action_type }),
+            ...(input.description === undefined ? {} : { description: input.description }),
+            ...(input.execute_at === undefined ? {} : { execute_at: resolve_postponed_action_time(input.execute_at) }),
+            updated_at: new Date(),
+        });
+    });
+};
+const repostpone_postponed_action_core = async (key, execute_at) => {
+    const ref = get_ref(key);
+    await db.runTransaction(async (transaction) => {
+        const snapshot = await transaction.get(ref);
+        if (!snapshot.exists)
+            throw new Error(`postponed action '${key}' does not exist`);
+        assert_status(key, snapshot.get("status"), [
+            PostponedActionStatus.pending,
+            PostponedActionStatus.completed,
+            PostponedActionStatus.cancelled,
+            PostponedActionStatus.failed,
+        ]);
+        transaction.update(ref, {
+            execute_at: resolve_postponed_action_time(execute_at),
+            status: PostponedActionStatus.pending,
+            updated_at: new Date(),
+            started_at: FieldValue.delete(),
+            completed_at: FieldValue.delete(),
+            cancelled_at: FieldValue.delete(),
+            failed_at: FieldValue.delete(),
+            error: FieldValue.delete(),
+        });
+    });
+};
+const cancel_postponed_action_core = async (key) => {
+    const ref = get_ref(key);
+    await db.runTransaction(async (transaction) => {
+        const snapshot = await transaction.get(ref);
+        if (!snapshot.exists)
+            throw new Error(`postponed action '${key}' does not exist`);
+        assert_status(key, snapshot.get("status"), [PostponedActionStatus.pending]);
+        const now = new Date();
+        transaction.update(ref, { status: PostponedActionStatus.cancelled, cancelled_at: now, updated_at: now });
+    });
+};
+const complete_postponed_action_core = async (key) => {
+    const ref = get_ref(key);
+    await db.runTransaction(async (transaction) => {
+        const snapshot = await transaction.get(ref);
+        if (!snapshot.exists)
+            throw new Error(`postponed action '${key}' does not exist`);
+        assert_status(key, snapshot.get("status"), [PostponedActionStatus.processing]);
+        const now = new Date();
+        transaction.update(ref, { status: PostponedActionStatus.completed, completed_at: now, updated_at: now });
+    });
+};
+const fail_postponed_action_core = async (key, error) => {
+    const ref = get_ref(key);
+    await db.runTransaction(async (transaction) => {
+        const snapshot = await transaction.get(ref);
+        if (!snapshot.exists)
+            throw new Error(`postponed action '${key}' does not exist`);
+        assert_status(key, snapshot.get("status"), [PostponedActionStatus.processing]);
+        const now = new Date();
+        transaction.update(ref, {
+            status: PostponedActionStatus.failed,
+            failed_at: now,
+            updated_at: now,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    });
+    logger.error(`[PostponedActions] action '${key}' failed`, error);
+};
+const delete_postponed_action_core = async (key) => {
+    await get_ref(key).delete();
+};
+const claim_postponed_action_core = async (key, action_type, now = new Date()) => {
+    validate_text(action_type, "action_type");
+    const ref = get_ref(key);
+    return db.runTransaction(async (transaction) => {
+        const snapshot = await transaction.get(ref);
+        if (!snapshot.exists || snapshot.get("status") !== PostponedActionStatus.pending || snapshot.get("action_type") !== action_type) {
+            return null;
+        }
+        const action = to_postponed_action(snapshot);
+        if (action.execute_at.getTime() > now.getTime())
+            return null;
+        const claimed = {
+            ...action,
+            status: PostponedActionStatus.processing,
+            attempt_count: action.attempt_count + 1,
+            started_at: now,
+            updated_at: now,
+        };
+        transaction.update(ref, {
+            status: claimed.status,
+            attempt_count: claimed.attempt_count,
+            started_at: now,
+            updated_at: now,
+        });
+        return claimed;
+    });
+};
+const claim_due_postponed_actions_core = async (action_type, limit = 100, now = new Date()) => {
+    validate_text(action_type, "action_type");
+    if (!Number.isInteger(limit) || limit <= 0) {
+        throw new Error("limit must be a positive integer");
+    }
+    const snapshot = await db
+        .collection(POSTPONED_ACTIONS_COLLECTION)
+        .where("action_type", "==", action_type)
+        .where("status", "==", PostponedActionStatus.pending)
+        .where("execute_at", "<=", now)
+        .orderBy("execute_at")
+        .limit(limit)
+        .get();
+    const claimed = await Promise.all(snapshot.docs.map((document) => claim_postponed_action_core(document.id, action_type, now)));
+    return claimed.filter((action) => action !== null);
+};
+const with_error_logging = (operation, action, get_key) => {
+    return async (...args) => {
+        try {
+            return await action(...args);
+        }
+        catch (error) {
+            const key = get_key?.(...args);
+            logger.error(`[PostponedActions] ${operation} failed${key ? ` for '${key}'` : ""}`, error);
+            throw error;
+        }
+    };
+};
+export const get_postponed_action = with_error_logging("get", get_postponed_action_core, (key) => key);
+export const add_postponed_action = with_error_logging("add", add_postponed_action_core, (input) => input.key);
+export const update_postponed_action = with_error_logging("update", update_postponed_action_core, (key) => key);
+export const repostpone_postponed_action = with_error_logging("repostpone", repostpone_postponed_action_core, (key) => key);
+export const cancel_postponed_action = with_error_logging("cancel", cancel_postponed_action_core, (key) => key);
+export const complete_postponed_action = with_error_logging("complete", complete_postponed_action_core, (key) => key);
+export const fail_postponed_action = with_error_logging("mark as failed", fail_postponed_action_core, (key) => key);
+export const delete_postponed_action = with_error_logging("delete", delete_postponed_action_core, (key) => key);
+export const claim_postponed_action = with_error_logging("claim", claim_postponed_action_core, (key) => key);
+export const claim_due_postponed_actions = with_error_logging("claim due", claim_due_postponed_actions_core);
+/**
+ * @example Add an action for a specific date and time.
+ * ```ts
+ * await postponed_actions.add({
+ *     key: "subscription:123:expire",
+ *     action_type: "subscription_expiration",
+ *     description: "Expire subscription 123",
+ *     details: { subscription_id: "123", notify_customer: true },
+ *     execute_at: new Date("2026-08-01T12:00:00Z"),
+ * });
+ * ```
+ *
+ * @example Add an action relative to the current time. Adding the same key
+ * updates the pending action.
+ * ```ts
+ * await postponed_actions.add({
+ *     key: "invoice:456:reminder",
+ *     action_type: "invoice_reminder",
+ *     description: "Send invoice 456 reminder",
+ *     details: { invoice_id: "456" },
+ *     execute_at: { hours: 2, minutes: 30 },
+ * });
+ * ```
+ *
+ * @example Update, repostpone, or cancel a pending action.
+ * ```ts
+ * await postponed_actions.update("invoice:456:reminder", {
+ *     description: "Send the final invoice reminder",
+ *     execute_at: { minutes: 15 },
+ * });
+ * await postponed_actions.repostpone("invoice:456:reminder", { hours: 1 });
+ * await postponed_actions.cancel("invoice:456:reminder");
+ * ```
+ *
+ * @example Claim and execute due actions. Claiming is atomic, so concurrent
+ * workers cannot claim the same action.
+ * ```ts
+ * const actions = await postponed_actions.claim_due("invoice_reminder", 25);
+ * for (const action of actions) {
+ *     try {
+ *         await execute_action(action.details);
+ *         await postponed_actions.complete(action.key);
+ *     } catch (error) {
+ *         await postponed_actions.fail(action.key, error);
+ *     }
+ * }
+ * ```
+ */
+export const postponed_actions = {
+    get: get_postponed_action,
+    add: add_postponed_action,
+    update: update_postponed_action,
+    repostpone: repostpone_postponed_action,
+    cancel: cancel_postponed_action,
+    complete: complete_postponed_action,
+    fail: fail_postponed_action,
+    delete: delete_postponed_action,
+    claim: claim_postponed_action,
+    claim_due: claim_due_postponed_actions,
+};

package/dist/managers/rabbitmq_manager.js

@@ -111,6 +111,9 @@ export class RabbitManager {
         return event;
     }
     async open_connection() {
+        if (!(process.env.RABBITMQ_URL ?? "")) {
+            return;
+        }
         const connection_url = new URL(process.env.RABBITMQ_URL);
         if (!connection_url.searchParams.has("heartbeat")) {
             connection_url.searchParams.set("heartbeat", "30");

package/dist/types/helpers/index.d.ts

@@ -7,6 +7,7 @@ export * from "./notification_helpers";
 export * from "./email_helpers";
 export * from "./phone_number_helpers";
 export * from "./tasks_helpers";
+export * from "./postponed_actions";
 export * from "./boards_helpers";
 export * from "./redis";
 export * from "./location_helpers";

package/dist/types/helpers/postponed_actions.d.ts

@@ -0,0 +1,113 @@
+import { TObject } from "akeyless-types-commons";
+export declare enum PostponedActionStatus {
+    pending = "pending",
+    processing = "processing",
+    completed = "completed",
+    cancelled = "cancelled",
+    failed = "failed"
+}
+export type PostponedActionTime = Date | string | {
+    minutes?: number;
+    hours?: number;
+};
+export type JsonPayload = TObject<any>;
+export interface PostponedAction {
+    key: string;
+    details: JsonPayload;
+    action_type: string;
+    description: string;
+    execute_at: Date;
+    status: PostponedActionStatus;
+    attempt_count: number;
+    created_at: Date;
+    updated_at: Date;
+    started_at?: Date;
+    completed_at?: Date;
+    cancelled_at?: Date;
+    failed_at?: Date;
+    error?: string;
+}
+export interface AddPostponedAction {
+    key: string;
+    details: JsonPayload;
+    action_type: string;
+    description: string;
+    execute_at: PostponedActionTime;
+}
+export interface UpdatePostponedAction {
+    details?: JsonPayload;
+    action_type?: string;
+    description?: string;
+    execute_at?: PostponedActionTime;
+}
+export declare const resolve_postponed_action_time: (value: PostponedActionTime, now?: Date) => Date;
+export declare const get_postponed_action: (key: string) => Promise<PostponedAction | null>;
+export declare const add_postponed_action: (input: AddPostponedAction) => Promise<PostponedAction>;
+export declare const update_postponed_action: (key: string, input: UpdatePostponedAction) => Promise<void>;
+export declare const repostpone_postponed_action: (key: string, execute_at: PostponedActionTime) => Promise<void>;
+export declare const cancel_postponed_action: (key: string) => Promise<void>;
+export declare const complete_postponed_action: (key: string) => Promise<void>;
+export declare const fail_postponed_action: (key: string, error: unknown) => Promise<void>;
+export declare const delete_postponed_action: (key: string) => Promise<void>;
+export declare const claim_postponed_action: (key: string, action_type: string, now?: Date | undefined) => Promise<PostponedAction | null>;
+export declare const claim_due_postponed_actions: (action_type: string, limit?: number | undefined, now?: Date | undefined) => Promise<PostponedAction[]>;
+/**
+ * @example Add an action for a specific date and time.
+ * ```ts
+ * await postponed_actions.add({
+ *     key: "subscription:123:expire",
+ *     action_type: "subscription_expiration",
+ *     description: "Expire subscription 123",
+ *     details: { subscription_id: "123", notify_customer: true },
+ *     execute_at: new Date("2026-08-01T12:00:00Z"),
+ * });
+ * ```
+ *
+ * @example Add an action relative to the current time. Adding the same key
+ * updates the pending action.
+ * ```ts
+ * await postponed_actions.add({
+ *     key: "invoice:456:reminder",
+ *     action_type: "invoice_reminder",
+ *     description: "Send invoice 456 reminder",
+ *     details: { invoice_id: "456" },
+ *     execute_at: { hours: 2, minutes: 30 },
+ * });
+ * ```
+ *
+ * @example Update, repostpone, or cancel a pending action.
+ * ```ts
+ * await postponed_actions.update("invoice:456:reminder", {
+ *     description: "Send the final invoice reminder",
+ *     execute_at: { minutes: 15 },
+ * });
+ * await postponed_actions.repostpone("invoice:456:reminder", { hours: 1 });
+ * await postponed_actions.cancel("invoice:456:reminder");
+ * ```
+ *
+ * @example Claim and execute due actions. Claiming is atomic, so concurrent
+ * workers cannot claim the same action.
+ * ```ts
+ * const actions = await postponed_actions.claim_due("invoice_reminder", 25);
+ * for (const action of actions) {
+ *     try {
+ *         await execute_action(action.details);
+ *         await postponed_actions.complete(action.key);
+ *     } catch (error) {
+ *         await postponed_actions.fail(action.key, error);
+ *     }
+ * }
+ * ```
+ */
+export declare const postponed_actions: {
+    get: (key: string) => Promise<PostponedAction | null>;
+    add: (input: AddPostponedAction) => Promise<PostponedAction>;
+    update: (key: string, input: UpdatePostponedAction) => Promise<void>;
+    repostpone: (key: string, execute_at: PostponedActionTime) => Promise<void>;
+    cancel: (key: string) => Promise<void>;
+    complete: (key: string) => Promise<void>;
+    fail: (key: string, error: unknown) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    claim: (key: string, action_type: string, now?: Date | undefined) => Promise<PostponedAction | null>;
+    claim_due: (action_type: string, limit?: number | undefined, now?: Date | undefined) => Promise<PostponedAction[]>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "akeyless-server-commons",
-    "version": "1.0.204",
+    "version": "1.0.206",
     "scripts": {
         "build:cjs": "tsc --project tsconfig.cjs.json",
         "build:esm": "tsc --project tsconfig.esm.json",