applesauce-actions 0.0.0-next-20250313155042 → 0.0.0-next-20250314133024

package/README.md

@@ -1 +1,5 @@
 # Applesauce Actions
+
+A collection of pre-built actions nostr clients can use. built on top of `applesauce-core` and `applesauce-factory`
+
+[Documentation](https://hzrd149.github.io/applesauce/typedoc/modules/applesauce_actions.html)

package/dist/__tests__/action-hub.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/action-hub.test.js

@@ -0,0 +1,67 @@
+import { from, Subject } from "rxjs";
+import { describe, expect, it, vi } from "vitest";
+import { subscribeSpyTo } from "@hirez_io/observer-spy";
+import { EventFactory } from "applesauce-factory";
+import { EventStore } from "applesauce-core";
+import { FakeUser } from "./fake-user.js";
+import { ActionHub } from "../action-hub.js";
+import { CreateProfile } from "../actions/profile.js";
+const user = new FakeUser();
+const events = new EventStore();
+const factory = new EventFactory({ signer: user });
+describe("runAction", () => {
+    it("should handle action that return observables", async () => {
+        const e = [user.note(), user.profile({ name: "testing" })];
+        const action = () => from(e);
+        const spy = subscribeSpyTo(ActionHub.runAction({ events, factory, self: await user.getPublicKey() }, action));
+        await spy.onComplete();
+        expect(spy.getValues()).toEqual(e);
+    });
+    it("should handle action that return AsyncIterable", async () => {
+        const e = [user.note(), user.profile({ name: "testing" })];
+        async function* action() {
+            for (const event of e)
+                yield event;
+        }
+        const spy = subscribeSpyTo(ActionHub.runAction({ events, factory, self: await user.getPublicKey() }, action));
+        await spy.onComplete();
+        expect(spy.getValues()).toEqual(e);
+    });
+    it("should handle action that return Iterable", async () => {
+        const e = [user.note(), user.profile({ name: "testing" })];
+        function* action() {
+            for (const event of e)
+                yield event;
+        }
+        const spy = subscribeSpyTo(ActionHub.runAction({ events, factory, self: await user.getPublicKey() }, action));
+        await spy.onComplete();
+        expect(spy.getValues()).toEqual(e);
+    });
+});
+describe("run", () => {
+    it("should throw if publish is not set", async () => {
+        const hub = new ActionHub(events, factory);
+        await expect(async () => hub.run(CreateProfile, { name: "fiatjaf" })).rejects.toThrow();
+    });
+    it("should call publish with all events", async () => {
+        const publish = vi.fn().mockResolvedValue(undefined);
+        const hub = new ActionHub(events, factory, publish);
+        await hub.run(CreateProfile, { name: "fiatjaf" });
+        expect(publish).toHaveBeenCalledWith(expect.objectContaining({ content: JSON.stringify({ name: "fiatjaf" }) }));
+    });
+});
+describe("exec", () => {
+    it("should support forEach to stream to publish", async () => {
+        const publish = vi.fn().mockResolvedValue(undefined);
+        const hub = new ActionHub(events, factory);
+        await hub.exec(CreateProfile, { name: "fiatjaf" }).forEach(publish);
+        expect(publish).toHaveBeenCalledWith(expect.objectContaining({ content: JSON.stringify({ name: "fiatjaf" }) }));
+    });
+    it("should support streaming to a publish subject", async () => {
+        const publish = new Subject();
+        const spy = subscribeSpyTo(publish);
+        const hub = new ActionHub(events, factory);
+        await hub.exec(CreateProfile, { name: "fiatjaf" }).forEach((v) => publish.next(v));
+        expect(spy.getValues()).toEqual([expect.objectContaining({ content: JSON.stringify({ name: "fiatjaf" }) })]);
+    });
+});

package/dist/action-hub.d.ts

@@ -1,11 +1,12 @@
+import { Observable } from "rxjs";
+import { NostrEvent } from "nostr-tools";
 import { IEventStore } from "applesauce-core/event-store";
 import { EventFactory } from "applesauce-factory";
-import { NostrEvent } from "nostr-tools";
 /**
  * A callback used to tell the upstream app to publish an event
  * @param label a label describing what
  */
-export type PublishMethod = (label: string, event: NostrEvent, explicitRelays?: string[]) => Promise<void>;
+export type PublishMethod = (event: NostrEvent) => void | Promise<void>;
 /** The context that is passed to actions for them to use to preform actions */
 export type ActionContext = {
     /** The event store to load events from */
@@ -14,21 +15,22 @@ export type ActionContext = {
     self: string;
     /** The event factory used to build and modify events */
     factory: EventFactory;
-    /** A method used to publish final events to relays */
-    publish: PublishMethod;
 };
 /** An action that can be run in a context to preform an action */
-export type Action<T extends unknown = unknown> = (ctx: ActionContext) => Promise<T>;
-export type ActionConstructor<Args extends Array<any>, T extends unknown = unknown> = (...args: Args) => Action<T>;
+export type Action = (ctx: ActionContext) => Observable<NostrEvent> | AsyncGenerator<NostrEvent> | Generator<NostrEvent>;
+export type ActionConstructor<Args extends Array<any>> = (...args: Args) => Action;
 /** The main class that runs actions */
 export declare class ActionHub {
     events: IEventStore;
     factory: EventFactory;
-    publish: PublishMethod;
-    constructor(events: IEventStore, factory: EventFactory, publish: PublishMethod);
+    publish?: PublishMethod | undefined;
+    constructor(events: IEventStore, factory: EventFactory, publish?: PublishMethod | undefined);
     protected context: ActionContext | undefined;
-    getContext(): Promise<ActionContext>;
-    run<Args extends Array<any>, T extends unknown = unknown>(Action: ActionConstructor<Args, T>, ...args: Args): Promise<T>;
-    follow(pubkey: string): Promise<unknown>;
-    unfollow(pubkey: string): Promise<unknown>;
+    protected getContext(): Promise<ActionContext>;
+    /** Runs an action in a ActionContext and converts the result to an Observable */
+    static runAction(ctx: ActionContext, action: Action): Observable<NostrEvent>;
+    /** Run an action and publish events using the publish method */
+    run<Args extends Array<any>>(Action: ActionConstructor<Args>, ...args: Args): Promise<void>;
+    /** Run an action without publishing the events */
+    exec<Args extends Array<any>>(Action: ActionConstructor<Args>, ...args: Args): Observable<NostrEvent>;
 }

package/dist/action-hub.js

@@ -1,4 +1,4 @@
-import { FollowUser } from "./actions/contacts.js";
+import { from, isObservable, lastValueFrom, switchMap, toArray } from "rxjs";
 /** The main class that runs actions */
 export class ActionHub {
     events;
@@ -17,20 +17,33 @@ export class ActionHub {
             if (!this.factory.context.signer)
                 throw new Error("Missing signer");
             const self = await this.factory.context.signer.getPublicKey();
-            this.context = { self, events: this.events, factory: this.factory, publish: this.publish };
+            this.context = { self, events: this.events, factory: this.factory };
             return this.context;
         }
     }
-    async run(Action, ...args) {
-        const action = Action(...args);
-        const ctx = await this.getContext();
-        return await action(ctx);
+    /** Runs an action in a ActionContext and converts the result to an Observable */
+    static runAction(ctx, action) {
+        const result = action(ctx);
+        if (isObservable(result))
+            return result;
+        else
+            return from(result);
     }
-    // helper methods
-    follow(pubkey) {
-        return this.run(FollowUser, pubkey);
+    /** Run an action and publish events using the publish method */
+    async run(Action, ...args) {
+        if (!this.publish)
+            throw new Error("Missing publish method, use ActionHub.exec");
+        // wait for action to complete and group events
+        const events = await lastValueFrom(this.exec(Action, ...args).pipe(toArray()));
+        // publish events
+        for (const event of events)
+            await this.publish(event);
     }
-    unfollow(pubkey) {
-        return this.run(FollowUser, pubkey);
+    /** Run an action without publishing the events */
+    exec(Action, ...args) {
+        return from(this.getContext()).pipe(switchMap((ctx) => {
+            const action = Action(...args);
+            return ActionHub.runAction(ctx, action);
+        }));
     }
 }

package/dist/actions/__tests__/bookmarks.test.js

@@ -19,6 +19,6 @@ beforeEach(() => {
 describe("CreateBookmarkList", () => {
     it("should publish a kind 10003 bookmark list", async () => {
         await hub.run(CreateBookmarkList);
-        expect(publish).toBeCalledWith(expect.any(String), expect.objectContaining({ kind: kinds.BookmarkList }));
+        expect(publish).toBeCalledWith(expect.objectContaining({ kind: kinds.BookmarkList }));
     });
 });

package/dist/actions/__tests__/contacts.test.js

@@ -24,7 +24,7 @@ describe("FollowUser", () => {
     it('should publish an event with a new "p" tag', async () => {
         events.add(user.contacts());
         await hub.run(FollowUser, user.pubkey);
-        expect(publish).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ tags: expect.arrayContaining([["p", user.pubkey]]) }));
+        expect(publish).toHaveBeenCalledWith(expect.objectContaining({ tags: expect.arrayContaining([["p", user.pubkey]]) }));
     });
 });
 describe("UnfollowUser", () => {
@@ -36,7 +36,7 @@ describe("UnfollowUser", () => {
     it('should publish an event with a new "p" tag', async () => {
         events.add(user.contacts([user.pubkey]));
         await hub.run(UnfollowUser, user.pubkey);
-        expect(publish).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ kind: 3, tags: [] }));
+        expect(publish).toHaveBeenCalledWith(expect.objectContaining({ kind: 3, tags: [] }));
     });
 });
 describe("NewContacts", () => {
@@ -48,6 +48,6 @@ describe("NewContacts", () => {
     it("should publish a new contact event with pubkeys", async () => {
         await hub.run(NewContacts, [user.pubkey]);
         expect(publish).toHaveBeenCalled();
-        expect(publish).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ kind: 3, tags: expect.arrayContaining([["p", user.pubkey]]) }));
+        expect(publish).toHaveBeenCalledWith(expect.objectContaining({ kind: 3, tags: expect.arrayContaining([["p", user.pubkey]]) }));
     });
 });

package/dist/actions/bookmarks.js

@@ -1,5 +1,4 @@
 import { kinds } from "nostr-tools";
-import { isReplaceable } from "applesauce-core/helpers";
 import { addEventBookmarkTag, removeEventBookmarkTag } from "applesauce-factory/operations/tag";
 import { modifyHiddenTags, modifyPublicTags, setListDescription, setListImage, setListTitle, } from "applesauce-factory/operations/event";
 function getBookmarkEvent(events, self, identifier) {
@@ -12,13 +11,13 @@ function getBookmarkEvent(events, self, identifier) {
  * @param hidden set to true to add to hidden bookmarks
  */
 export function BookmarkEvent(event, identifier, hidden = false) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const bookmarks = getBookmarkEvent(events, self, identifier);
         if (!bookmarks)
             throw new Error("Cant find bookmarks");
         const operation = addEventBookmarkTag(event);
         const draft = await factory.modifyTags(bookmarks, hidden ? { hidden: operation } : operation);
-        await publish(`Bookmark ${isReplaceable(event.kind) ? "note" : "article"}`, await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }
 /**
@@ -28,32 +27,32 @@ export function BookmarkEvent(event, identifier, hidden = false) {
  * @param hidden set to true to remove from hidden bookmarks
  */
 export function UnbookmarkEvent(event, identifier, hidden = false) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const bookmarks = getBookmarkEvent(events, self, identifier);
         if (!bookmarks)
             throw new Error("Cant find bookmarks");
         const operation = removeEventBookmarkTag(event);
         const draft = await factory.modifyTags(bookmarks, hidden ? { hidden: operation } : operation);
-        await publish("Remove bookmark", await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }
 /** An action that creates a new bookmark list for a user */
 export function CreateBookmarkList(bookmarks) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const existing = getBookmarkEvent(events, self);
         if (existing)
             throw new Error("Bookmark list already exists");
-        const draft = await factory.process({ kind: kinds.BookmarkList }, bookmarks ? modifyPublicTags(...bookmarks.map(addEventBookmarkTag)) : undefined);
-        await publish("Create bookmark list", await factory.sign(draft));
+        const draft = await factory.build({ kind: kinds.BookmarkList }, bookmarks ? modifyPublicTags(...bookmarks.map(addEventBookmarkTag)) : undefined);
+        yield await factory.sign(draft);
     };
 }
 /** An action that creates a new bookmark set for a user */
 export function CreateBookmarkSet(title, description, additional) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const existing = getBookmarkEvent(events, self);
         if (existing)
             throw new Error("Bookmark list already exists");
         const draft = await factory.process({ kind: kinds.BookmarkList }, setListTitle(title), setListDescription(description), additional.image ? setListImage(additional.image) : undefined, additional.public ? modifyPublicTags(...additional.public.map(addEventBookmarkTag)) : undefined, additional.hidden ? modifyHiddenTags(...additional.hidden.map(addEventBookmarkTag)) : undefined);
-        await publish("Create bookmark set", await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }

package/dist/actions/contacts.js

@@ -2,34 +2,34 @@ import { kinds } from "nostr-tools";
 import { addPubkeyTag, removePubkeyTag } from "applesauce-factory/operations/tag";
 /** An action that adds a pubkey to a users contacts event */
 export function FollowUser(pubkey, relay, hidden = false) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const contacts = events.getReplaceable(kinds.Contacts, self);
         if (!contacts)
             throw new Error("Missing contacts event");
         const pointer = { pubkey, relays: relay ? [relay] : undefined };
         const operation = addPubkeyTag(pointer);
         const draft = await factory.modifyTags(contacts, hidden ? { hidden: operation } : operation);
-        await publish("Update contacts", await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }
 /** An action that removes a pubkey from a users contacts event */
 export function UnfollowUser(pubkey, hidden = false) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const contacts = events.getReplaceable(kinds.Contacts, self);
         if (!contacts)
             throw new Error("Missing contacts event");
         const operation = removePubkeyTag(pubkey);
         const draft = await factory.modifyTags(contacts, hidden ? { hidden: operation } : operation);
-        await publish("Update contacts", await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }
 /** An action that creates a new kind 3 contacts lists, throws if a contact list already exists */
 export function NewContacts(pubkeys) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const contacts = events.getReplaceable(kinds.Contacts, self);
         if (contacts)
             throw new Error("Contact list already exists");
         const draft = await factory.process({ kind: kinds.Contacts, tags: pubkeys?.map((p) => ["p", p]) });
-        await publish("New contact list", await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }

package/dist/actions/pins.js

@@ -3,31 +3,31 @@ import { addEventTag, removeEventTag } from "applesauce-factory/operations/tag";
 import { modifyPublicTags } from "applesauce-factory/operations/event";
 /** An action that pins a note to the users pin list */
 export function PinNote(note) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const pins = events.getReplaceable(kinds.Pinlist, self);
         if (!pins)
             throw new Error("Missing pin list");
         const draft = await factory.modifyTags(pins, addEventTag(note.id));
-        await publish("Pin note", await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }
 /** An action that removes an event from the users pin list */
 export function UnpinNote(note) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const pins = events.getReplaceable(kinds.Pinlist, self);
         if (!pins)
             throw new Error("Missing pin list");
         const draft = await factory.modifyTags(pins, removeEventTag(note.id));
-        await publish("Pin note", await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }
 /** An action that creates a new pin list for a user */
 export function CreatePinList(pins = []) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const existing = events.getReplaceable(kinds.Pinlist, self);
         if (existing)
             throw new Error("Pin list already exists");
         const draft = await factory.process({ kind: kinds.Pinlist }, modifyPublicTags(...pins.map((event) => addEventTag(event.id))));
-        await publish("Create pin list", await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }

package/dist/actions/profile.js

@@ -2,21 +2,21 @@ import { kinds } from "nostr-tools";
 import { setProfileContent, updateProfileContent } from "applesauce-factory/operations/event";
 /** An action that creates a new kind 0 profile event for a user */
 export function CreateProfile(content) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const metadata = events.getReplaceable(kinds.Metadata, self);
         if (metadata)
             throw new Error("Profile already exists");
-        const draft = await factory.process({ kind: kinds.Metadata }, setProfileContent(content));
-        await publish("Create profile", await factory.sign(draft));
+        const draft = await factory.build({ kind: kinds.Metadata }, setProfileContent(content));
+        yield await factory.sign(draft);
     };
 }
 /** An action that updates a kind 0 profile evnet for a user */
 export function UpdateProfile(content) {
-    return async ({ events, factory, self, publish }) => {
+    return async function* ({ events, factory, self }) {
         const metadata = events.getReplaceable(kinds.Metadata, self);
         if (!metadata)
             throw new Error("Profile does not exists");
         const draft = await factory.modify(metadata, updateProfileContent(content));
-        await publish("Update profile", await factory.sign(draft));
+        yield await factory.sign(draft);
     };
 }

package/dist/helpers/observable.d.ts

@@ -0,0 +1,3 @@
+import { Observable } from "rxjs";
+/** Subscribes to an observable, send all the values to a method and unsubscribes when complete */
+export declare function play<T extends unknown = unknown>(stream: Observable<T>, method: (value: T) => void): Promise<void>;

package/dist/helpers/observable.js

@@ -0,0 +1,20 @@
+/** Subscribes to an observable, send all the values to a method and unsubscribes when complete */
+export function play(stream, method) {
+    return new Promise((resolve, reject) => {
+        const sub = stream.subscribe({
+            next: (v) => {
+                try {
+                    method(v);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            },
+            error: (error) => reject(error),
+            complete: () => {
+                sub.unsubscribe();
+                resolve();
+            },
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "applesauce-actions",
-  "version": "0.0.0-next-20250313155042",
+  "version": "0.0.0-next-20250314133024",
   "description": "A package for performing common nostr actions",
   "type": "module",
   "main": "dist/index.js",
@@ -32,13 +32,15 @@
     }
   },
   "dependencies": {
-    "applesauce-core": "0.0.0-next-20250313155042",
-    "applesauce-factory": "0.0.0-next-20250313155042",
-    "nostr-tools": "^2.10.4"
+    "applesauce-core": "0.0.0-next-20250314133024",
+    "applesauce-factory": "0.0.0-next-20250314133024",
+    "nostr-tools": "^2.10.4",
+    "rxjs": "^7.8.1"
   },
   "devDependencies": {
+    "@hirez_io/observer-spy": "^2.2.0",
     "@types/debug": "^4.1.12",
-    "applesauce-signers": "0.0.0-next-20250313155042",
+    "applesauce-signers": "0.0.0-next-20250314133024",
     "nanoid": "^5.0.9",
     "typescript": "^5.7.3",
     "vitest": "^3.0.5"