applesauce-actions 0.0.0-next-20250428164231 → 0.0.0-next-20250429163257

package/README.md

@@ -1,5 +1,42 @@
 # Applesauce Actions
 
-A collection of pre-built actions nostr clients can use. built on top of `applesauce-core` and `applesauce-factory`
+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)
+
+## Installation
+
+```bash
+npm install applesauce-actions
+```
+
+## Overview
+
+Actions are common pre-built async operations that apps can perform. They use:
+
+- `EventStore` for access to known nostr events
+- `EventFactory` to build and sign new nostr events
+- A `publish` method to publish or save the resulting events
+
+The package provides an `ActionHub` class that combines these components into a single manager for easier action execution.
+
+## Basic Usage
+
+```typescript
+import { ActionHub } from "applesauce-actions";
+import { FollowUser } from "applesauce-actions/actions";
+
+async function publishEvent(event: NostrEvent) {
+  await relayPool.publish(event, ["wss://relay.example.com"]);
+}
+
+// Create an action hub with your event store, factory and publish method
+const hub = new ActionHub(eventStore, eventFactory, publishEvent);
+
+// Example: Follow a user
+await hub
+  .exec(FollowUser, "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d")
+  .forEach((event) => publishEvent(event));
+```
+
+For more detailed documentation and examples, visit the [full documentation](https://hzrd149.github.io/applesauce/overview/actions.html).

package/dist/actions/__tests__/blossom.test.d.ts

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

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

@@ -0,0 +1,93 @@
+import { EventStore } from "applesauce-core";
+import { BLOSSOM_SERVER_LIST_KIND } from "applesauce-core/helpers/blossom";
+import { EventFactory } from "applesauce-factory";
+import { firstValueFrom, lastValueFrom } from "rxjs";
+import { toArray } from "rxjs/operators";
+import { beforeEach, describe, expect, it } from "vitest";
+import { FakeUser } from "../../__tests__/fake-user.js";
+import { ActionHub } from "../../action-hub.js";
+import { AddBlossomServer, NewBlossomServers, RemoveBlossomServer, SetDefaultBlossomServer } from "../blossom.js";
+const user = new FakeUser();
+let events;
+let factory;
+let hub;
+beforeEach(() => {
+    events = new EventStore();
+    factory = new EventFactory({ signer: user });
+    hub = new ActionHub(events, factory);
+});
+describe("NewBlossomServers", () => {
+    it("should publish a kind 10063 blossom server list", async () => {
+        const result = await lastValueFrom(hub.exec(NewBlossomServers, ["https://cdn.example.com/"]).pipe(toArray()));
+        expect(result[0]).toMatchObject({ kind: BLOSSOM_SERVER_LIST_KIND, tags: [["server", "https://cdn.example.com/"]] });
+    });
+    it("should throw if a blossom servers event already exists", async () => {
+        // Create the initial event
+        await hub.exec(NewBlossomServers, ["https://cdn.example.com/"]).forEach((e) => events.add(e));
+        // Attempt to create another one
+        await expect(lastValueFrom(hub.exec(NewBlossomServers, ["https://other.example.com/"]).pipe(toArray()))).rejects.toThrow("Blossom servers event already exists");
+    });
+});
+describe("AddBlossomServer", () => {
+    beforeEach(async () => {
+        // Create an initial empty server list
+        await hub.exec(NewBlossomServers, ["https://cdn.example.com/"]).forEach((e) => events.add(e));
+    });
+    it("should add a single server to the list", async () => {
+        const result = await firstValueFrom(hub.exec(AddBlossomServer, "https://other.example.com/"));
+        expect(result).toMatchObject({
+            kind: BLOSSOM_SERVER_LIST_KIND,
+            tags: expect.arrayContaining([["server", expect.stringContaining("other.example.com")]]),
+        });
+    });
+    it("should add multiple servers to the list", async () => {
+        const result = await firstValueFrom(hub.exec(AddBlossomServer, ["https://other.example.com/", "https://other2.example.com/"]));
+        expect(result).toMatchObject({
+            kind: BLOSSOM_SERVER_LIST_KIND,
+            tags: expect.arrayContaining([
+                ["server", expect.stringContaining("other.example.com")],
+                ["server", expect.stringContaining("other2.example.com")],
+            ]),
+        });
+    });
+});
+describe("RemoveBlossomServer", () => {
+    beforeEach(async () => {
+        // Create an initial server list with two servers
+        await hub
+            .exec(NewBlossomServers, ["https://cdn.example.com/", "https://other.example.com/"])
+            .forEach((e) => events.add(e));
+    });
+    it("should remove a server from the list", async () => {
+        const result = await firstValueFrom(hub.exec(RemoveBlossomServer, "https://cdn.example.com/"));
+        expect(result).toMatchObject({
+            kind: BLOSSOM_SERVER_LIST_KIND,
+            tags: expect.arrayContaining([["server", expect.stringContaining("other.example.com")]]),
+        });
+    });
+    it("should remove multiple servers from the list", async () => {
+        const result = await firstValueFrom(hub.exec(RemoveBlossomServer, ["https://cdn.example.com/", "https://other.example.com/"]));
+        expect(result).toMatchObject({
+            kind: BLOSSOM_SERVER_LIST_KIND,
+            tags: [],
+        });
+    });
+});
+describe("SetDefaultBlossomServer", () => {
+    beforeEach(async () => {
+        // Create an initial server list with two servers
+        await hub
+            .exec(NewBlossomServers, ["https://cdn.example.com/", "https://other.example.com/"])
+            .forEach((e) => events.add(e));
+    });
+    it("should move the specified server to the top of the list", async () => {
+        const result = await firstValueFrom(hub.exec(SetDefaultBlossomServer, "https://other.example.com/"));
+        expect(result).toMatchObject({
+            kind: BLOSSOM_SERVER_LIST_KIND,
+            tags: expect.arrayContaining([
+                ["server", expect.stringContaining("other.example.com")],
+                ["server", expect.stringContaining("cdn.example.com")],
+            ]),
+        });
+    });
+});

package/dist/actions/blocked-relays.js

@@ -1,5 +1,5 @@
-import { addRelayTag, removeRelayTag } from "applesauce-factory/operations/tag";
-import { modifyHiddenTags, modifyPublicTags } from "applesauce-factory/operations/tag/list";
+import { modifyHiddenTags, modifyPublicTags } from "applesauce-factory/operations/event";
+import { addRelayTag, removeRelayTag } from "applesauce-factory/operations/tag/relay";
 import { kinds } from "nostr-tools";
 function getBlockedRelaysEvent(events, self) {
     const event = events.getReplaceable(kinds.BlockedRelaysList, self);

package/dist/actions/blossom.d.ts

@@ -0,0 +1,9 @@
+import { Action } from "../action-hub.js";
+/** An action that adds a server to the Blossom servers event */
+export declare function AddBlossomServer(server: string | URL | (string | URL)[]): Action;
+/** An action that removes a server from the Blossom servers event */
+export declare function RemoveBlossomServer(server: string | URL | (string | URL)[]): Action;
+/** Makes a specific Blossom server the default server (move it to the top of the list) */
+export declare function SetDefaultBlossomServer(server: string | URL): Action;
+/** Creates a new Blossom servers event */
+export declare function NewBlossomServers(servers?: (string | URL)[]): Action;

package/dist/actions/blossom.js

@@ -0,0 +1,52 @@
+import { BLOSSOM_SERVER_LIST_KIND } from "applesauce-core/helpers/blossom";
+import { modifyPublicTags } from "applesauce-factory/operations/event";
+import { addBlossomServerTag, removeBlossomServerTag } from "applesauce-factory/operations/tag/blossom";
+function getBlossomServersEvent(events, self) {
+    const event = events.getReplaceable(BLOSSOM_SERVER_LIST_KIND, self);
+    if (!event)
+        throw new Error("Can't find Blossom servers event");
+    return event;
+}
+/** An action that adds a server to the Blossom servers event */
+export function AddBlossomServer(server) {
+    return async function* ({ events, factory, self }) {
+        const servers = getBlossomServersEvent(events, self);
+        const operation = Array.isArray(server) ? server.map((s) => addBlossomServerTag(s)) : addBlossomServerTag(server);
+        const draft = await factory.modifyTags(servers, operation);
+        yield await factory.sign(draft);
+    };
+}
+/** An action that removes a server from the Blossom servers event */
+export function RemoveBlossomServer(server) {
+    return async function* ({ events, factory, self }) {
+        const servers = getBlossomServersEvent(events, self);
+        const operation = Array.isArray(server)
+            ? server.map((s) => removeBlossomServerTag(s))
+            : removeBlossomServerTag(server);
+        const draft = await factory.modifyTags(servers, operation);
+        yield await factory.sign(draft);
+    };
+}
+/** Makes a specific Blossom server the default server (move it to the top of the list) */
+export function SetDefaultBlossomServer(server) {
+    return async function* ({ events, factory, self }) {
+        const servers = getBlossomServersEvent(events, self);
+        const prependTag = (tag) => (tags) => [tag, ...tags];
+        const draft = await factory.modifyTags(servers, [
+            removeBlossomServerTag(server),
+            prependTag(["server", String(server)]),
+        ]);
+        yield await factory.sign(draft);
+    };
+}
+/** Creates a new Blossom servers event */
+export function NewBlossomServers(servers) {
+    return async function* ({ events, factory, self }) {
+        const existing = events.getReplaceable(BLOSSOM_SERVER_LIST_KIND, self);
+        if (existing)
+            throw new Error("Blossom servers event already exists");
+        const operations = servers ? servers.map((s) => addBlossomServerTag(s)) : [];
+        const draft = await factory.build({ kind: BLOSSOM_SERVER_LIST_KIND }, modifyPublicTags(...operations));
+        yield await factory.sign(draft);
+    };
+}

package/dist/actions/dm-relays.js

@@ -1,5 +1,5 @@
-import { addRelayTag, removeRelayTag } from "applesauce-factory/operations/tag";
-import { modifyPublicTags } from "applesauce-factory/operations/tag/list";
+import { modifyPublicTags } from "applesauce-factory/operations/event";
+import { addRelayTag, removeRelayTag } from "applesauce-factory/operations/tag/relay";
 import { kinds } from "nostr-tools";
 function getDMRelaysEvent(events, self) {
     const event = events.getReplaceable(kinds.DirectMessageRelaysList, self);

package/dist/actions/favorite-relays.js

@@ -1,6 +1,6 @@
 import { FAVORITE_RELAYS_KIND } from "applesauce-core/helpers/lists";
+import { modifyHiddenTags, modifyPublicTags } from "applesauce-factory/operations/event";
 import { addCoordinateTag, addRelayTag, removeCoordinateTag, removeRelayTag } from "applesauce-factory/operations/tag";
-import { modifyHiddenTags, modifyPublicTags } from "applesauce-factory/operations/tag/list";
 function getFavoriteRelaysEvent(events, self) {
     const event = events.getReplaceable(FAVORITE_RELAYS_KIND, self);
     if (!event)

package/dist/actions/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./blocked-relays.js";
+export * from "./blossom.js";
 export * from "./bookmarks.js";
 export * from "./contacts.js";
 export * from "./dm-relays.js";

package/dist/actions/index.js

@@ -1,4 +1,5 @@
 export * from "./blocked-relays.js";
+export * from "./blossom.js";
 export * from "./bookmarks.js";
 export * from "./contacts.js";
 export * from "./dm-relays.js";

package/dist/actions/search-relays.js

@@ -1,5 +1,5 @@
-import { addRelayTag, removeRelayTag } from "applesauce-factory/operations/tag";
-import { modifyHiddenTags, modifyPublicTags } from "applesauce-factory/operations/tag/list";
+import { modifyHiddenTags, modifyPublicTags } from "applesauce-factory/operations/event";
+import { addRelayTag, removeRelayTag } from "applesauce-factory/operations/tag/relay";
 import { kinds } from "nostr-tools";
 function getSearchRelaysEvent(events, self) {
     const event = events.getReplaceable(kinds.SearchRelaysList, self);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "applesauce-actions",
-  "version": "0.0.0-next-20250428164231",
+  "version": "0.0.0-next-20250429163257",
   "description": "A package for performing common nostr actions",
   "type": "module",
   "main": "dist/index.js",
@@ -32,15 +32,15 @@
     }
   },
   "dependencies": {
-    "applesauce-core": "0.0.0-next-20250428164231",
-    "applesauce-factory": "0.0.0-next-20250428164231",
+    "applesauce-core": "0.0.0-next-20250429163257",
+    "applesauce-factory": "0.0.0-next-20250429163257",
     "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-20250428164231",
+    "applesauce-signers": "0.0.0-next-20250429163257",
     "nanoid": "^5.1.5",
     "typescript": "^5.8.3",
     "vitest": "^3.1.1"