update actions docs

Author: hzrd149

package.json

@@ -11,7 +11,7 @@
   },
   "dependencies": {
     "@changesets/cli": "^2.28.1",
-    "typedoc": "^0.26.11"
+    "typedoc": "^0.27.9"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "2.1.8",

packages/docs/.vitepress/config.ts

@@ -27,7 +27,7 @@ export default defineConfig({
           { text: "Events", link: "/overview/events" },
           { text: "Queries", link: "/overview/queries" },
           { text: "Helpers", link: "/overview/helpers" },
-          { text: "Event Factory", link: "/overview/factory" },
+          { text: "Factory", link: "/overview/factory" },
           { text: "Loaders", link: "/overview/loaders" },
           { text: "Actions", link: "/overview/actions" },
         ],

packages/docs/overview/actions.md

@@ -1,6 +1,6 @@
 # Actions
 
-Actions are async operations apps can perform using the `EventStore` as the known state, the `EventFactory` to build new events, and a `publish` method to publish or save the resulting events
+Actions are common pre-built async operations apps can perform. they use the `EventStore` as state, the `EventFactory` to build new events, and a `publish` method to publish or save the resulting events
 
 ## Action Hub
 
@@ -21,16 +21,72 @@ const publish = async (label: string, event: NostrEvent, explicitRelays?: string
 
 // create a new action hub with an event store, event factory, and custom publish method
 const hub = new ActionHub(eventStore, eventFactory, publish);
+
+// start using action hub
 ```
 
+:::info
+For performance reasons, its recommended to only create a single `ActionHub` instance for your whole app
+:::
+
 ## What is an action
 
-WIP
+An [Action](https://hzrd149.github.io/applesauce/typedoc/types/applesauce_actions.Action.html) is an async method that reads from the event store and preforms actions by creating events using the event factory and event publisher
+
+You can see the full list of built-in actions in the [reference](https://hzrd149.github.io/applesauce/typedoc/modules/applesauce_actions.Actions.html)
 
 ## Running actions
 
-WIP
+[ActionHub.run](https://hzrd149.github.io/applesauce/typedoc/classes/applesauce_actions.ActionHub.html#run) can be used to run actions once an action hub is created
+
+:::warning
+To avoid overriding replaceable events, actions will throw if an existing replaceable event cant be found
+:::
+
+Here are a few simple examples
+
+```ts
+import { FollowUser } from "applesauce-actions/actions";
+
+// create a new contact list event
+try {
+  await hub.run(NewContacts);
+} catch (err) {
+  // this will throw if a contact list already exists
+}
+
+// follow a user
+await hub.run(
+  FollowUser,
+  "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
+  "wss://pyramid.fiatjaf.com/",
+);
+```
 
 ## Custom actions
 
-WIP
+Custom actions are simply methods that take custom arguments and return an async method
+
+```ts
+import { Action } from "applesauce-actions";
+import { updateProfileContent } from "applesauce-factory/operations/event";
+
+function CustomSetNameAction(newName = "fiatjaf"): Action {
+  return async ({ events, factory, self, publish }) => {
+    // get the profile event
+    const profile = events.getReplaceable(0, self);
+
+    // throw if the profile event cant be found
+    if (!profile) throw new Error("Cant find profile");
+
+    // create a new unsigned profile event with a new name
+    const draft = await factory.modify(profile, updateProfileContent({ name: newName }));
+
+    // request the user to sign the event
+    const signed = await factory.sign(draft);
+
+    // ask the app the publish the app
+    await publish("Set profile name", signed);
+  };
+}
+```

packages/docs/overview/loaders.md

@@ -1,6 +1,6 @@
 # Loaders
 
-The `applesauce-loaders` package contains a bunch of loader classes built on top of [rx-nostr](https://github.com/penpenpng/rx-nostr)
+The `applesauce-loaders` package contains loader classes built on top of [rx-nostr](https://github.com/penpenpng/rx-nostr) that can be used to setup common event loading patterns
 
 ## Event Loader pattern
 

packages/factory/src/operations/event/index.ts

@@ -15,3 +15,4 @@ export * from "./quote.js";
 export * from "./reaction.js";
 export * from "./tags.js";
 export * from "./zap.js";
+export * from "./profile.js";

packages/factory/src/operations/event/profile.ts

@@ -0,0 +1,16 @@
+import { ProfileContent, safeParse } from "applesauce-core/helpers";
+import { EventOperation } from "../../event-factory.js";
+import { setContent } from "./content.js";
+
+/** Sets the content of a kind 0 metadata event */
+export function setProfileContent(content: ProfileContent): EventOperation {
+  return setContent(JSON.stringify(content));
+}
+
+/** Updates the content of a kind 0 metadata event */
+export function updateProfileContent(content: Partial<ProfileContent>): EventOperation {
+  return (draft) => {
+    const existing = safeParse<ProfileContent>(draft.content) || {};
+    return { ...draft, content: JSON.stringify({ ...existing, ...content }) };
+  };
+}