@bzzsocial/ndk 0.0.0-stage → 3.0.3-bzz.7

package/src/ndk/fetch-event-from-tag.ts

@@ -0,0 +1,156 @@
+import type { NDKEvent, NDKTag } from "../events";
+import { getRelaysForSync } from "../outbox/write";
+import { NDKRelaySet } from "../relay/sets";
+import { calculateRelaySetsFromFilters } from "../relay/sets/calculate";
+import type { NDKSubscriptionOptions } from "../subscription";
+import type { NDK } from ".";
+
+/**
+ * Options on how to handle when a relay hint doesn't respond
+ * with the requested event.
+ *
+ * When a tag includes a relay hint, and the relay hint doesn't come back
+ * with the event, the fallback options are used to try to fetch the event
+ * from somewhere else.
+ */
+export type NDKFetchFallbackOptions = {
+    /**
+     * Relay set to use as a fallback when the hint relay doesn't respond.
+     * If not provided, the normal NDK calculation is used (whether explicit relays or outbox calculation)
+     * Default is `undefined`.
+     */
+    relaySet?: NDKRelaySet;
+
+    /**
+     * Type of fallback to use when the hint relay doesn't respond.
+     * - "timeout" will wait for a timeout before falling back
+     * - "eose" will wait for the EOSE before falling back
+     * - "none" will not fall back
+     * Default is "timeout".
+     */
+    type: "timeout" | "eose" | "none";
+
+    /**
+     * Timeout in milliseconds for the fallback relay.
+     * Default is 1500ms.
+     */
+    timeout?: number;
+};
+
+function isValidHint(hint: string | undefined) {
+    if (!hint || hint === "") return false;
+
+    // Check if the hint is a valid URL
+    try {
+        new URL(hint);
+        return true;
+    } catch (_e) {
+        return false;
+    }
+}
+
+function isRelayHintConnected(ndk: NDK, hint: string | undefined) {
+    if (!isValidHint(hint)) return false;
+
+    return ndk.pool.isRelayConnected(hint!);
+}
+
+/**
+ * @ignore
+ */
+export async function fetchEventFromTag(
+    this: NDK,
+    tag: NDKTag,
+    originalEvent: NDKEvent,
+    subOpts?: NDKSubscriptionOptions,
+    fallback: NDKFetchFallbackOptions = {
+        type: "timeout",
+    },
+) {
+    const d = this.debug.extend("fetch-event-from-tag");
+    const [_, id, hint] = tag;
+
+    // If we are supposed to stick to the cache, just go with that
+    // if (subOpts?.cacheUsage === NDKSubscriptionCacheUsage.ONLY_CACHE) {
+    //     return this.fetchEvent(id, subOpts);
+    // }
+
+    // XXXXX
+    subOpts = {};
+
+    d("fetching event from tag", tag, subOpts, fallback);
+
+    // If we are connected to the relay hint, try exclusively from that relay
+    // if (isRelayHintConnected(this, hint)) {
+    //     d("fetching event from connected relay hint (%s)", normalizeRelayUrl(hint));
+    //     let event = await this.fetchEvent(id, subOpts, this.pool.getRelay(hint));
+    //     if (event) return event;
+    // }
+
+    // Check if we have a relay list for the author of the original event
+    // and prefer to use those relays
+    const authorRelays = getRelaysForSync(this, originalEvent.pubkey);
+    if (authorRelays && authorRelays.size > 0) {
+        d("fetching event from author relays %o", Array.from(authorRelays));
+        const relaySet = NDKRelaySet.fromRelayUrls(Array.from(authorRelays), this);
+        const event = await this.fetchEvent(id, subOpts, relaySet);
+        if (event) return event;
+    } else {
+        d("no author relays found for %s", originalEvent.pubkey, originalEvent);
+    }
+
+    // Attempt without relay hint on whatever NDK calculates
+    const relaySet = calculateRelaySetsFromFilters(this, [{ ids: [id] }], this.pool);
+    d("fetching event without relay hint", relaySet);
+    const event = await this.fetchEvent(id, subOpts);
+    if (event) return event;
+
+    // If we didn't get the event, try to fetch in the relay hint
+    if (hint && hint !== "") {
+        const event = await this.fetchEvent(id, subOpts, this.pool.getRelay(hint, true, true, [{ ids: [id] }]));
+        if (event) return event;
+    }
+
+    let result: NDKEvent | null | undefined;
+
+    const relay = isValidHint(hint) ? this.pool.getRelay(hint, false, true, [{ ids: [id] }]) : undefined;
+
+    const fetchMaybeWithRelayHint = new Promise<NDKEvent | null>((resolve) => {
+        this.fetchEvent(id, subOpts, relay).then(resolve);
+    });
+
+    // if we don't have a relay hint we don't need to setup a fallback
+    if (!isValidHint(hint) || fallback.type === "none") {
+        return fetchMaybeWithRelayHint;
+    }
+
+    /**
+     * Fallback fetch promise.
+     */
+    const fallbackFetchPromise = new Promise<NDKEvent | null>(async (resolve) => {
+        const fallbackRelaySet = fallback.relaySet;
+
+        const timeout = fallback.timeout ?? 1500;
+        const timeoutPromise = new Promise<void>((resolve) => setTimeout(resolve, timeout));
+
+        // if this is a timeout fallback, we need to wait for the timeout to resolve
+        if (fallback.type === "timeout") await timeoutPromise;
+
+        if (result) {
+            resolve(result);
+        } else {
+            d("fallback fetch triggered");
+            const fallbackEvent = await this.fetchEvent(id, subOpts, fallbackRelaySet);
+            resolve(fallbackEvent);
+        }
+    });
+
+    switch (fallback.type) {
+        case "timeout":
+            return Promise.race([fetchMaybeWithRelayHint, fallbackFetchPromise]);
+        case "eose":
+            result = await fetchMaybeWithRelayHint;
+            if (result) return result;
+            return fallbackFetchPromise;
+    }
+}

package/src/ndk/fetchEvent-guardrails.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+import { NDK } from "./index.js";
+
+describe("fetchEvent guardrails", () => {
+    it("should warn when fetchEvent is called with a decoded naddr filter", async () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        const naddrFilter = {
+            kinds: [30023],
+            authors: ["fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"],
+            "#d": ["identifier"],
+        };
+
+        try {
+            await ndk.fetchEvent(naddrFilter);
+            throw new Error("Should have thrown a guardrails error");
+        } catch (error: any) {
+            expect(error.message).toContain("For fetching a NIP-33 addressable event");
+            expect(error.message).toContain("use fetchEvent() with the naddr directly");
+            expect(error.message).toContain("nip19.decode(naddr)");
+        }
+    });
+
+    it("should warn when fetchEvent is called with a single ID filter", async () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        const idFilter = {
+            ids: ["abc123"],
+        };
+
+        try {
+            await ndk.fetchEvent(idFilter);
+            throw new Error("Should have thrown a guardrails error");
+        } catch (error: any) {
+            expect(error.message).toContain("For fetching a single event");
+            expect(error.message).toContain("use fetchEvent() instead");
+            expect(error.message).toContain("fetchEvent(eventId)");
+        }
+    });
+
+    it("should NOT warn when fetchEvent is called with a filter that is NOT a single event and ratio threshold not exceeded", async () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        // This is a filter for multiple events - should not trigger warnings
+        // because the ratio threshold hasn't been exceeded yet
+        try {
+            await Promise.race([
+                ndk.fetchEvent(
+                    {
+                        kinds: [1],
+                        limit: 10,
+                    },
+                    { closeOnEose: true },
+                ),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 100)),
+            ]);
+        } catch (error: any) {
+            // Should timeout, not throw a guardrails error
+            if (error.message !== "timeout") {
+                expect(error?.message || "").not.toContain("AI_GUARDRAILS");
+            }
+        }
+    });
+
+    it("should allow skipping the guardrail check", async () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: { skip: new Set(["fetch-events-usage"]) },
+        });
+
+        const naddrFilter = {
+            kinds: [30023],
+            authors: ["fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"],
+            "#d": ["identifier"],
+        };
+
+        // Should not throw because we skipped the check
+        // Race against timeout to avoid network connection
+        try {
+            await Promise.race([
+                ndk.fetchEvent(naddrFilter, { closeOnEose: true }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 100)),
+            ]);
+        } catch (error: any) {
+            if (error.message !== "timeout") {
+                // If it errors, it should NOT be a guardrails error
+                expect(error?.message || "").not.toContain("AI_GUARDRAILS");
+            }
+        }
+    });
+
+    it("should disable all guardrails for one call with guardrailOff()", async () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        const naddrFilter = {
+            kinds: [30023],
+            authors: ["fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"],
+            "#d": ["identifier"],
+        };
+
+        // Test that guardrailOff() suppresses the error
+        let errorThrown = false;
+        try {
+            // This would normally throw immediately due to guardrails
+            // We wrap in a promise race to avoid waiting for network
+            await Promise.race([
+                ndk.guardrailOff().fetchEvent(naddrFilter, { closeOnEose: true }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 100)),
+            ]);
+        } catch (error: any) {
+            if (error.message !== "timeout") {
+                errorThrown = true;
+                // If it errors, it should NOT be a guardrails error
+                expect(error?.message || "").not.toContain("AI_GUARDRAILS");
+            }
+        }
+
+        // Verify that the next call DOES trigger the guardrail
+        try {
+            await ndk.fetchEvent(naddrFilter);
+            throw new Error("Should have thrown a guardrails error");
+        } catch (error: any) {
+            expect(error.message).toContain("AI_GUARDRAILS");
+        }
+    });
+
+    it("should disable specific guardrail for one call with guardrailOff('id')", async () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        const naddrFilter = {
+            kinds: [30023],
+            authors: ["fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"],
+            "#d": ["identifier"],
+        };
+
+        // Test that guardrailOff('id') suppresses the specific error
+        try {
+            await Promise.race([
+                ndk.guardrailOff("fetch-events-usage").fetchEvent(naddrFilter, { closeOnEose: true }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 100)),
+            ]);
+        } catch (error: any) {
+            if (error.message !== "timeout") {
+                // If it errors, it should NOT be a guardrails error
+                expect(error?.message || "").not.toContain("AI_GUARDRAILS");
+            }
+        }
+
+        // Verify that the next call DOES trigger the guardrail
+        try {
+            await ndk.fetchEvent(naddrFilter);
+            throw new Error("Should have thrown a guardrails error");
+        } catch (error: any) {
+            expect(error.message).toContain("AI_GUARDRAILS");
+        }
+    });
+
+    it("should disable multiple guardrails for one call with guardrailOff(['id1', 'id2'])", async () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        const naddrFilter = {
+            kinds: [30023],
+            authors: ["fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"],
+            "#d": ["identifier"],
+        };
+
+        // Test that guardrailOff(['id1', 'id2']) suppresses the errors
+        try {
+            await Promise.race([
+                ndk
+                    .guardrailOff(["fetch-events-usage", "some-other-check"])
+                    .fetchEvent(naddrFilter, { closeOnEose: true }),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 100)),
+            ]);
+        } catch (error: any) {
+            if (error.message !== "timeout") {
+                // If it errors, it should NOT be a guardrails error
+                expect(error?.message || "").not.toContain("AI_GUARDRAILS");
+            }
+        }
+
+        // Verify that the next call DOES trigger the guardrail
+        try {
+            await ndk.fetchEvent(naddrFilter);
+            throw new Error("Should have thrown a guardrails error");
+        } catch (error: any) {
+            expect(error.message).toContain("AI_GUARDRAILS");
+        }
+    });
+});

package/src/ndk/fetchEvent-invalid-filter.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from "vitest";
+import { NDK } from "./index.js";
+
+describe("fetchEvent with invalid filter (issue #357)", () => {
+    it("should not crash with ReferenceError when subscribe throws", async () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.example.com"],
+        });
+
+        // Mock subscribe to throw, simulating the scenario where
+        // an invalid filter causes subscribe to fail before assignment.
+        // The timeout callback must use optional chaining (s?.stop())
+        // to avoid crashing on the unassigned variable.
+        const subscribeSpy = vi.spyOn(ndk, "subscribe").mockImplementation(() => {
+            throw new Error("Invalid filter caused subscribe to fail");
+        });
+
+        try {
+            await ndk.fetchEvent({ authors: ["not-a-valid-hex"] });
+        } catch (error: any) {
+            // Should get the subscribe error, NOT a ReferenceError about 's'
+            expect(error).not.toBeInstanceOf(ReferenceError);
+            expect(error.message).not.toContain("Cannot access");
+            expect(error.message).toContain("Invalid filter caused subscribe to fail");
+        }
+
+        subscribeSpy.mockRestore();
+    });
+
+    it("should not crash when fetchEvent is called with a malformed hex ID string", async () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.example.com"],
+        });
+
+        // fetchEvent with a bad string should not throw a ReferenceError.
+        // It may timeout or fail for other reasons, but the 's' variable
+        // must be safely handled via optional chaining.
+        let caughtError: Error | undefined;
+        try {
+            await Promise.race([
+                ndk.fetchEvent("zzz-invalid-id"),
+                new Promise((_, reject) =>
+                    setTimeout(() => reject(new Error("timeout")), 200),
+                ),
+            ]);
+        } catch (error: any) {
+            caughtError = error;
+        }
+
+        // Must not be a ReferenceError about 's'
+        if (caughtError) {
+            expect(caughtError).not.toBeInstanceOf(ReferenceError);
+            expect(caughtError.message).not.toContain("Cannot access");
+        }
+    });
+
+    it("should resolve null when subscribe throws and timeout fires", async () => {
+        vi.useFakeTimers();
+
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.example.com"],
+        });
+
+        const subscribeSpy = vi.spyOn(ndk, "subscribe").mockImplementation(() => {
+            throw new Error("subscribe failed");
+        });
+
+        const promise = ndk.fetchEvent({ ids: ["abc"] });
+
+        // The promise should have been rejected immediately by the thrown error
+        // (Promise constructor catches synchronous throws)
+        await expect(promise).rejects.toThrow("subscribe failed");
+
+        // Advance past the 10-second timeout to ensure it doesn't crash
+        vi.advanceTimersByTime(11000);
+
+        subscribeSpy.mockRestore();
+        vi.useRealTimers();
+    });
+});

package/src/ndk/fetchUser.test.ts

@@ -0,0 +1,149 @@
+import { nip19 } from "nostr-tools";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { NDKUser } from "../user/index.js";
+import * as nip05Module from "../user/nip05.js";
+import { NDK } from "./index.js";
+
+describe("ndk.fetchUser()", () => {
+    let ndk: NDK;
+    const testPubkey = "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d";
+    const testNpub = nip19.npubEncode(testPubkey);
+    const testNprofile = nip19.nprofileEncode({
+        pubkey: testPubkey,
+        relays: ["wss://relay1.example.com", "wss://relay2.example.com"],
+    });
+
+    beforeEach(() => {
+        ndk = new NDK();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe("with npub string", () => {
+        it("should decode npub and create user with correct pubkey", async () => {
+            const user = await ndk.fetchUser(testNpub);
+            expect(user).toBeInstanceOf(NDKUser);
+            expect(user?.pubkey).toBe(testPubkey);
+            expect(user?.ndk).toBe(ndk);
+        });
+
+        it("should throw error for invalid npub", async () => {
+            await expect(ndk.fetchUser("npub1invalid")).rejects.toThrow();
+        });
+    });
+
+    describe("with nprofile string", () => {
+        it("should decode nprofile and create user with pubkey and relay hints", async () => {
+            const user = await ndk.fetchUser(testNprofile);
+            expect(user).toBeInstanceOf(NDKUser);
+            expect(user?.pubkey).toBe(testPubkey);
+            expect(user?.relayUrls).toEqual(["wss://relay1.example.com", "wss://relay2.example.com"]);
+            expect(user?.ndk).toBe(ndk);
+        });
+
+        it("should handle nprofile without relays", async () => {
+            const nprofileNoRelays = nip19.nprofileEncode({
+                pubkey: testPubkey,
+                relays: [],
+            });
+            const user = await ndk.fetchUser(nprofileNoRelays);
+            expect(user).toBeInstanceOf(NDKUser);
+            expect(user?.pubkey).toBe(testPubkey);
+            expect(user?.relayUrls).toEqual([]);
+        });
+    });
+
+    describe("with hex pubkey string", () => {
+        it("should accept hex pubkey directly", async () => {
+            const user = await ndk.fetchUser(testPubkey);
+            expect(user).toBeInstanceOf(NDKUser);
+            expect(user?.pubkey).toBe(testPubkey);
+            expect(user?.ndk).toBe(ndk);
+        });
+
+        it("should handle various hex pubkey formats", async () => {
+            const shortHex = "deadbeef";
+            const user = await ndk.fetchUser(shortHex);
+            expect(user).toBeInstanceOf(NDKUser);
+            expect(user?.pubkey).toBe(shortHex);
+        });
+    });
+
+    describe("with NIP-05 identifier", () => {
+        it("should resolve NIP-05 with @ symbol", async () => {
+            const mockUser = new NDKUser({ pubkey: testPubkey });
+            mockUser.ndk = ndk;
+
+            vi.spyOn(NDKUser, "fromNip05").mockResolvedValue(mockUser);
+
+            const user = await ndk.fetchUser("pablo@test.com");
+            expect(NDKUser.fromNip05).toHaveBeenCalledWith("pablo@test.com", ndk, false);
+            expect(user).toBe(mockUser);
+        });
+
+        it("should resolve NIP-05 without @ symbol (domain only)", async () => {
+            const mockUser = new NDKUser({ pubkey: testPubkey });
+            mockUser.ndk = ndk;
+
+            vi.spyOn(NDKUser, "fromNip05").mockResolvedValue(mockUser);
+
+            const user = await ndk.fetchUser("test.com");
+            expect(NDKUser.fromNip05).toHaveBeenCalledWith("test.com", ndk, false);
+            expect(user).toBe(mockUser);
+        });
+
+        it("should handle NIP-05 resolution failure", async () => {
+            vi.spyOn(NDKUser, "fromNip05").mockResolvedValue(undefined);
+
+            const user = await ndk.fetchUser("nonexistent@test.com");
+            expect(NDKUser.fromNip05).toHaveBeenCalledWith("nonexistent@test.com", ndk, false);
+            expect(user).toBeUndefined();
+        });
+
+        it("should pass skipCache parameter for NIP-05", async () => {
+            const mockUser = new NDKUser({ pubkey: testPubkey });
+            mockUser.ndk = ndk;
+
+            vi.spyOn(NDKUser, "fromNip05").mockResolvedValue(mockUser);
+
+            await ndk.fetchUser("pablo@test.com", true);
+            expect(NDKUser.fromNip05).toHaveBeenCalledWith("pablo@test.com", ndk, true);
+        });
+
+        it("should distinguish between NIP-05 and nprofile with dots", async () => {
+            // nprofile should not be mistaken for NIP-05 even if it contains dots somehow
+            const user = await ndk.fetchUser(testNprofile);
+            expect(user).toBeInstanceOf(NDKUser);
+            expect(user?.pubkey).toBe(testPubkey);
+        });
+    });
+
+    describe("edge cases", () => {
+        it("should handle empty string", async () => {
+            const user = await ndk.fetchUser("");
+            expect(user).toBeInstanceOf(NDKUser);
+            // Empty string is not a valid pubkey, so accessing pubkey should throw
+            expect(() => user?.pubkey).toThrow("npub not set");
+        });
+
+        it("should handle strings starting with 'n' but not valid NIP-19", async () => {
+            const invalidString = "notanip19string";
+            const user = await ndk.fetchUser(invalidString);
+            expect(user).toBeInstanceOf(NDKUser);
+            expect(user?.pubkey).toBe(invalidString);
+        });
+
+        it("should handle domain with multiple dots", async () => {
+            const mockUser = new NDKUser({ pubkey: testPubkey });
+            mockUser.ndk = ndk;
+
+            vi.spyOn(NDKUser, "fromNip05").mockResolvedValue(mockUser);
+
+            const user = await ndk.fetchUser("sub.domain.test.com");
+            expect(NDKUser.fromNip05).toHaveBeenCalledWith("sub.domain.test.com", ndk, false);
+            expect(user).toBe(mockUser);
+        });
+    });
+});

package/src/ndk/guardrailOff.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import { NDK } from "./index.js";
+
+describe("guardrailOff()", () => {
+    it("should disable all guardrails for one call", () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        const naddrFilter = {
+            kinds: [30023],
+            authors: ["fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"],
+            "#d": ["identifier"],
+        };
+
+        // Set the flag
+        ndk.guardrailOff();
+
+        // Verify the flag was set to 'all'
+        expect(ndk.aiGuardrails["_nextCallDisabled"]).toBe("all");
+
+        // Verify shouldCheck returns false for any ID when 'all' is set
+        expect(ndk.aiGuardrails.shouldCheck("fetch-events-usage")).toBe(false);
+        expect(ndk.aiGuardrails.shouldCheck("any-other-check")).toBe(false);
+    });
+
+    it("should disable specific guardrail for one call", () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        // Set the flag for a specific guardrail
+        ndk.guardrailOff("fetch-events-usage");
+
+        // Verify the flag was set correctly
+        expect(ndk.aiGuardrails["_nextCallDisabled"]).toBeInstanceOf(Set);
+        expect(ndk.aiGuardrails["_nextCallDisabled"]).toContain("fetch-events-usage");
+
+        // Verify shouldCheck returns false only for the specified ID
+        expect(ndk.aiGuardrails.shouldCheck("fetch-events-usage")).toBe(false);
+        expect(ndk.aiGuardrails.shouldCheck("other-check")).toBe(true);
+    });
+
+    it("should disable multiple guardrails for one call", () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        // Set the flag for multiple guardrails
+        ndk.guardrailOff(["fetch-events-usage", "filter-large-limit"]);
+
+        // Verify the flag was set correctly
+        expect(ndk.aiGuardrails["_nextCallDisabled"]).toBeInstanceOf(Set);
+        expect(ndk.aiGuardrails["_nextCallDisabled"]).toContain("fetch-events-usage");
+        expect(ndk.aiGuardrails["_nextCallDisabled"]).toContain("filter-large-limit");
+
+        // Verify shouldCheck returns false for specified IDs
+        expect(ndk.aiGuardrails.shouldCheck("fetch-events-usage")).toBe(false);
+        expect(ndk.aiGuardrails.shouldCheck("filter-large-limit")).toBe(false);
+        expect(ndk.aiGuardrails.shouldCheck("other-check")).toBe(true);
+    });
+
+    it("should return this for method chaining", () => {
+        const ndk = new NDK({
+            explicitRelayUrls: ["wss://relay.primal.net"],
+            aiGuardrails: true,
+        });
+
+        const result = ndk.guardrailOff("fetch-events-usage");
+        expect(result).toBe(ndk);
+    });
+});