@lantharos/pult 0.8.0 → 0.10.0

package/README.md

@@ -1,16 +1,18 @@
-# pult
+# @lantharos/pult
 
-The other side of your app. Describe your inboxes, records, actions, pages and flags in code next to your app, and Pult turns them into a console your team runs the product from. Every action runs back inside your app.
+The other side of your app. Describe your inboxes, resources, actions, pages and flags in code next to your app, and Pult turns them into a console your team runs the product from. Every action runs back inside your app.
 
 ```bash
-bun add pult@npm:@lantharos/pult
+bun add @lantharos/pult
 ```
 
-Installing it under the name `pult` keeps your imports as `"pult"`.
+Then run `bunx pult init` to set up a config, a first resource and inbox, and the client. Everything is imported from `"@lantharos/pult"`, and the package also gives you the `pult` command.
+
+Resources are the records your team looks up and acts on, and flags can target them:
 
 ```ts
 // src/users/user.pult.ts
-import { b, resource } from "pult"
+import { b, flag, resource } from "@lantharos/pult"
 import { z } from "zod"
 
 export const user = resource("user", {
@@ -27,28 +29,50 @@ export const user = resource("user", {
     }),
   }),
 })
+
+export const newEditor = flag("new-editor", { target: user })
+```
+
+Inboxes collect what needs a look, each item linked to the record it's about:
+
+```ts
+// src/users/reports.pult.ts
+import { b, inbox } from "@lantharos/pult"
+import { z } from "zod"
+import { user } from "./user.pult"
+
+export const reports = inbox("reports", {
+  resource: user,
+  data: z.object({ reason: z.string(), body: z.string() }),
+  title: (data) => data.reason,
+  render: (item) => [b.markdown(item.data.body), b.actions("ban")],
+})
 ```
 
+Your app sends items as things happen and reads flags where it needs them:
+
 ```ts
 // src/pult.ts
-import { createPult } from "pult"
+import { createPult } from "@lantharos/pult"
 import project from "../.pult"
+import { reports } from "./users/reports.pult"
+import { newEditor } from "./users/user.pult"
 
 export const pult = createPult({ project })
 pult.listen()
-```
 
-```ts
-// src/flags.ts
-import { flag } from "pult"
-
-export const newEditor = flag("new-editor", { target: user })
+export async function report(userId: string, reason: string, body: string) {
+  await pult.send(reports, { record: userId, fingerprint: userId, data: { reason, body } })
+}
 
-if (await pult.flag(newEditor, user.id)) showNewEditor()
+export const editorFor = (userId: string) => pult.flag(newEditor, userId)
 ```
 
-The `pult` command builds your definitions, checks them and deploys them:
+On Cloudflare Workers, set `delivery: { mode: "webhook", path: "/pult" }` in `pult.config.ts` and hand those requests to `pult.handler()` instead of calling `listen()`.
+
+The `pult` command sets up, builds, checks and deploys your definitions:
 
+- `pult init` writes a config, a first resource and inbox, and the client.
 - `pult build` compiles your definitions into `.pult/`. Commit it.
 - `pult check` catches broken references and stale builds. Run it in CI.
 - `pult diff` shows what a deploy would change, including who gains which permission.