@gjermundgaraba/effect-actions 0.16.0 → 0.18.0

package/examples/mcp-tools/src/platform/print-farm.ts

@@ -0,0 +1,118 @@
+import { Config, Effect, Layer, Redacted, Schema } from "effect";
+import {
+  HttpBody,
+  HttpClient,
+  type HttpClientError,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "effect/http";
+import { PrintFarm } from "../printers/farm.js";
+import { Printer, PrintFarmError } from "../printers/Printers.js";
+
+const fail = (message: string) => Effect.fail(new PrintFarmError({ message }));
+
+const unreadable = "The print farm sent an answer this server could not read.";
+
+// The farm answers a request it refuses with a status that is not 2xx and `{ "error": "..." }`.
+// Its reason is passed on to the model, which can act on "The printer is busy with a job".
+const refuseUnlessOk = HttpClientResponse.matchStatus({
+  "2xx": (response) => Effect.succeed(response),
+  orElse: (response) =>
+    HttpClientResponse.schemaBodyJson(Schema.Struct({ error: Schema.String }))(response).pipe(
+      Effect.matchEffect({
+        onFailure: () => fail(`The print farm refused the request (HTTP ${response.status}).`),
+        onSuccess: ({ error }) => fail(`The print farm refused: ${error}`),
+      }),
+    ),
+});
+
+// Every other way a call to the farm fails, as the same declared error: no connection, an
+// answer of another shape than expected, or none in time. Nothing of the HTTP client's own
+// errors leaves this file, so no tool can fail with something its contract does not declare.
+const asPrintFarmError = <A>(
+  effect: Effect.Effect<A, PrintFarmError | HttpClientError.HttpClientError | Schema.SchemaError>,
+) =>
+  effect.pipe(
+    Effect.catchTag("HttpClientError", ({ response }) =>
+      fail(response === undefined ? "The print farm could not be reached." : unreadable),
+    ),
+    Effect.catchTag("SchemaError", () => fail(unreadable)),
+    Effect.timeoutOrElse({
+      duration: "30 seconds",
+      orElse: () => fail("The print farm did not answer in time."),
+    }),
+  );
+
+const asImage = (response: HttpClientResponse.HttpClientResponse) =>
+  Effect.gen(function* () {
+    const mimeType = response.headers["content-type"];
+
+    if (mimeType === undefined || !mimeType.startsWith("image/")) return yield* fail(unreadable);
+
+    return { data: new Uint8Array(yield* response.arrayBuffer), mimeType };
+  });
+
+// Built once, when the process starts. It requires an `HttpClient` and reads its settings
+// from `Config`: the entrypoint decides which client, and the environment says which farm.
+// Not `fetch`: as a service, a test replaces the network alone and opens no port
+// (test/printers/printers.test.ts).
+export const printFarm = Layer.effect(
+  PrintFarm,
+  Effect.gen(function* () {
+    const { url, user, password } = yield* Config.all({
+      url: Config.URL("FARM_URL"),
+      user: Config.NonEmptyString("FARM_USER"),
+      password: Config.Redacted("FARM_PASSWORD"),
+    });
+
+    const http = (yield* HttpClient.HttpClient).pipe(
+      HttpClient.mapRequest(HttpClientRequest.prependUrl(url.href)),
+      HttpClient.transformResponse(Effect.flatMap(refuseUnlessOk)),
+    );
+
+    // Signs in once, here, and every call below reuses the token, kept `Redacted` so no log
+    // prints it. A farm that refuses the sign-in stops the process at startup, with its
+    // reason, before any tool is listed. A real client also signs in again when a call
+    // answers 401, as tokens expire.
+    const session = yield* http
+      .post("/api/login", {
+        body: HttpBody.jsonUnsafe({ user, password: Redacted.value(password) }),
+      })
+      .pipe(
+        Effect.flatMap(
+          HttpClientResponse.schemaBodyJson(
+            Schema.Struct({ token: Schema.RedactedFromValue(Schema.String) }),
+          ),
+        ),
+        asPrintFarmError,
+      );
+
+    yield* Effect.logInfo(`Signed in to the print farm at ${url.host} as ${user}.`);
+
+    const api = HttpClient.mapRequest(http, HttpClientRequest.bearerToken(session.token));
+
+    // An id is written into the path as it is: the contract admits only letters, digits,
+    // `_` and `-`, so it is always one segment. Encoding would not make other text safe:
+    // `encodeURIComponent` leaves `..` alone, and a URL parser then walks up the path.
+    const at = (id: string, rest = "") => `/api/printers/${id}${rest}`;
+
+    const printer = (answer: ReturnType<typeof api.get>) =>
+      answer.pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(Printer)), asPrintFarmError);
+
+    return PrintFarm.of({
+      printers: api.get("/api/printers").pipe(
+        Effect.flatMap(
+          HttpClientResponse.schemaBodyJson(Schema.Struct({ printers: Schema.Array(Printer) })),
+        ),
+        Effect.map(({ printers }) => printers),
+        asPrintFarmError,
+      ),
+      printer: (id) => printer(api.get(at(id))),
+      snapshot: (id) => api.get(at(id, "/camera")).pipe(Effect.flatMap(asImage), asPrintFarmError),
+      start: (id, file) =>
+        printer(api.post(at(id, "/job"), { body: HttpBody.jsonUnsafe({ file }) })),
+      setPaused: (id, paused) => printer(api.post(at(id, paused ? "/pause" : "/resume"))),
+      cancel: (id) => printer(api.del(at(id, "/job"))),
+    });
+  }),
+);

package/examples/mcp-tools/src/printers/farm.ts

@@ -1,61 +1,11 @@
-import { Config, Context, Effect, Layer, Redacted, Schema } from "effect";
-import {
-  HttpBody,
-  HttpClient,
-  type HttpClientError,
-  HttpClientRequest,
-  HttpClientResponse,
-} from "effect/http";
+import { Context, type Effect } from "effect";
 import type * as Action from "@gjermundgaraba/effect-actions/Action";
-import { Printer, PrintFarmError } from "./Printers.js";
-
-const fail = (message: string) => Effect.fail(new PrintFarmError({ message }));
-
-const unreadable = "The print farm sent an answer this server could not read.";
-
-// The farm answers a request it refuses with a status that is not 2xx and `{ "error": "..." }`.
-// Its reason is passed on to the model, which can act on "The printer is busy with a job".
-const refuseUnlessOk = HttpClientResponse.matchStatus({
-  "2xx": (response) => Effect.succeed(response),
-  orElse: (response) =>
-    HttpClientResponse.schemaBodyJson(Schema.Struct({ error: Schema.String }))(response).pipe(
-      Effect.matchEffect({
-        onFailure: () => fail(`The print farm refused the request (HTTP ${response.status}).`),
-        onSuccess: ({ error }) => fail(`The print farm refused: ${error}`),
-      }),
-    ),
-});
-
-// Every other way a call to the farm fails, as the same declared error: no connection, an
-// answer of another shape than expected, or none in time. Nothing of the HTTP client's own
-// errors leaves this file, so no tool can fail with something its contract does not declare.
-const asPrintFarmError = <A>(
-  effect: Effect.Effect<A, PrintFarmError | HttpClientError.HttpClientError | Schema.SchemaError>,
-) =>
-  effect.pipe(
-    Effect.catchTag("HttpClientError", ({ response }) =>
-      fail(response === undefined ? "The print farm could not be reached." : unreadable),
-    ),
-    Effect.catchTag("SchemaError", () => fail(unreadable)),
-    Effect.timeoutOrElse({
-      duration: "30 seconds",
-      orElse: () => fail("The print farm did not answer in time."),
-    }),
-  );
-
-const asImage = (response: HttpClientResponse.HttpClientResponse) =>
-  Effect.gen(function* () {
-    const mimeType = response.headers["content-type"];
-
-    if (mimeType === undefined || !mimeType.startsWith("image/")) return yield* fail(unreadable);
-
-    return { data: new Uint8Array(yield* response.arrayBuffer), mimeType };
-  });
+import type { Printer, PrintFarmError } from "./Printers.js";
 
 /**
- * The print farm's HTTP API, the one upstream of this server. Its methods require nothing and
- * fail only with the error the tools declare: the layer has captured the HTTP client, the
- * farm's URL and the session.
+ * The print farm, the one upstream of this server. Its methods require nothing and fail only
+ * with the error the tools declare: its layer, `printFarm` in src/platform/print-farm.ts, has
+ * captured the HTTP client, the farm's URL and the session.
  */
 export class PrintFarm extends Context.Service<
   PrintFarm,
@@ -67,70 +17,4 @@ export class PrintFarm extends Context.Service<
     readonly setPaused: (id: string, paused: boolean) => Effect.Effect<Printer, PrintFarmError>;
     readonly cancel: (id: string) => Effect.Effect<Printer, PrintFarmError>;
   }
->()("mcp-tools/PrintFarm") {
-  // Built once, when the process starts. It requires an `HttpClient` and reads its settings
-  // from `Config`: the entrypoint decides which client, and the environment says which farm.
-  // Not `fetch`: as a service, a test replaces the network alone and opens no port
-  // (test/printers/printers.test.ts).
-  static readonly layer = Layer.effect(
-    PrintFarm,
-    Effect.gen(function* () {
-      const { url, user, password } = yield* Config.all({
-        url: Config.URL("FARM_URL"),
-        user: Config.NonEmptyString("FARM_USER"),
-        password: Config.Redacted("FARM_PASSWORD"),
-      });
-
-      const http = (yield* HttpClient.HttpClient).pipe(
-        HttpClient.mapRequest(HttpClientRequest.prependUrl(url.href)),
-        HttpClient.transformResponse(Effect.flatMap(refuseUnlessOk)),
-      );
-
-      // Signs in once, here, and every call below reuses the token, kept `Redacted` so no log
-      // prints it. A farm that refuses the sign-in stops the process at startup, with its
-      // reason, before any tool is listed. A real client also signs in again when a call
-      // answers 401, as tokens expire.
-      const session = yield* http
-        .post("/api/login", {
-          body: HttpBody.jsonUnsafe({ user, password: Redacted.value(password) }),
-        })
-        .pipe(
-          Effect.flatMap(
-            HttpClientResponse.schemaBodyJson(
-              Schema.Struct({ token: Schema.RedactedFromValue(Schema.String) }),
-            ),
-          ),
-          asPrintFarmError,
-        );
-
-      yield* Effect.logInfo(`Signed in to the print farm at ${url.host} as ${user}.`);
-
-      const api = HttpClient.mapRequest(http, HttpClientRequest.bearerToken(session.token));
-
-      // An id is written into the path as it is: the contract admits only letters, digits,
-      // `_` and `-`, so it is always one segment. Encoding would not make other text safe:
-      // `encodeURIComponent` leaves `..` alone, and a URL parser then walks up the path.
-      const at = (id: string, rest = "") => `/api/printers/${id}${rest}`;
-
-      const printer = (answer: ReturnType<typeof api.get>) =>
-        answer.pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(Printer)), asPrintFarmError);
-
-      return PrintFarm.of({
-        printers: api.get("/api/printers").pipe(
-          Effect.flatMap(
-            HttpClientResponse.schemaBodyJson(Schema.Struct({ printers: Schema.Array(Printer) })),
-          ),
-          Effect.map(({ printers }) => printers),
-          asPrintFarmError,
-        ),
-        printer: (id) => printer(api.get(at(id))),
-        snapshot: (id) =>
-          api.get(at(id, "/camera")).pipe(Effect.flatMap(asImage), asPrintFarmError),
-        start: (id, file) =>
-          printer(api.post(at(id, "/job"), { body: HttpBody.jsonUnsafe({ file }) })),
-        setPaused: (id, paused) => printer(api.post(at(id, paused ? "/pause" : "/resume"))),
-        cancel: (id) => printer(api.del(at(id, "/job"))),
-      });
-    }),
-  );
-}
+>()("mcp-tools/PrintFarm") {}

package/examples/mcp-tools/src/server.ts

@@ -2,8 +2,8 @@ import { createServer } from "node:http";
 import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
 import { ByteSize, Config, Effect, Layer } from "effect";
 import { HttpRouter, HttpServerRequest } from "effect/http";
-import { fakeFarm } from "./printers/fake.js";
-import { PrintFarm } from "./printers/farm.js";
+import { fakeFarm } from "./platform/fake-farm.js";
+import { printFarm } from "./platform/print-farm.js";
 import { routes } from "./routes.js";
 
 // Entrypoint: `node --import tsx examples/mcp-tools/src/server.ts`, with FARM_URL, FARM_USER
@@ -22,8 +22,8 @@ const server = Layer.unwrap(
       // short fields, so anything larger is not one.
       Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.kibibytes(64))),
       // DEMO ONLY: `fakeFarm` answers the farm's API in memory. A real server provides
-      // `FetchHttpClient.layer` in its place, and `PrintFarm.layer` calls the farm at FARM_URL.
-      Layer.provide(PrintFarm.layer.pipe(Layer.provide(fakeFarm))),
+      // `FetchHttpClient.layer` in its place, and `printFarm` calls the farm at FARM_URL.
+      Layer.provide(printFarm.pipe(Layer.provide(fakeFarm))),
     );
   }),
 );

package/examples/mcp-tools/src/stdio.ts

@@ -3,8 +3,8 @@ import { Effect, Layer } from "effect";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import { serverInfo } from "./instructions.js";
-import { fakeFarm } from "./printers/fake.js";
-import { PrintFarm } from "./printers/farm.js";
+import { fakeFarm } from "./platform/fake-farm.js";
+import { printFarm } from "./platform/print-farm.js";
 import { printers } from "./printers/handlers.js";
 
 // Entrypoint: an MCP server a local agent starts as a subprocess, with FARM_URL, FARM_USER and
@@ -17,10 +17,10 @@ ActionMcp.runStdio(printers, serverInfo).pipe(
     NodeStdio.layer,
     // DEMO ONLY: `fakeFarm` answers the farm's API in memory. A real server provides
     // `FetchHttpClient.layer` in its place.
-    PrintFarm.layer.pipe(Layer.provide(fakeFarm)),
+    printFarm.pipe(Layer.provide(fakeFarm)),
   ]),
   // stdout carries the protocol alone. Applied last, this sends every log to stderr, the
-  // sign-in line `PrintFarm.layer` logs included, and a startup failure too.
+  // sign-in line `printFarm` logs included, and a startup failure too.
   ActionCli.logToStderr,
   NodeRuntime.runMain,
 );

package/examples/mcp-tools/test/printers/printers.test.ts

@@ -8,8 +8,8 @@ import {
 } from "effect/http";
 import { TestClock } from "effect/testing";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
-import { fakeFarm } from "../../src/printers/fake.js";
-import { PrintFarm } from "../../src/printers/farm.js";
+import { fakeFarm } from "../../src/platform/fake-farm.js";
+import { printFarm } from "../../src/platform/print-farm.js";
 import { printers } from "../../src/printers/handlers.js";
 import { PrintFarmError } from "../../src/printers/Printers.js";
 
@@ -19,7 +19,7 @@ import { PrintFarmError } from "../../src/printers/Printers.js";
 // The real `PrintFarm` over an upstream of the test's: its requests, its sign-in and its error
 // mapping all run, and only the network is replaced. Its settings come from a Layer too.
 const farmOver = (upstream: Layer.Layer<HttpClient.HttpClient>) =>
-  PrintFarm.layer.pipe(
+  printFarm.pipe(
     Layer.provide(upstream),
     Layer.provide(
       ConfigProvider.layer(

package/examples/mcp-tools/test/routes.test.ts

@@ -3,8 +3,8 @@ import { ConfigProvider, Effect, Layer, Schema } from "effect";
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
-import { fakeFarm, picture } from "../src/printers/fake.js";
-import { PrintFarm } from "../src/printers/farm.js";
+import { fakeFarm, picture } from "../src/platform/fake-farm.js";
+import { printFarm } from "../src/platform/print-farm.js";
 import { PrintFarmError, Printers } from "../src/printers/Printers.js";
 import { routes } from "../src/routes.js";
 
@@ -15,10 +15,10 @@ import { routes } from "../src/routes.js";
 const farm = { FARM_URL: "https://farm.example.test", FARM_USER: "agent", FARM_PASSWORD: "secret" };
 
 // `Testing.layer` gives the test an `HttpClient` of its own, which reaches the routes. The
-// fake farm is another `HttpClient`, provided to `PrintFarm.layer` alone.
+// fake farm is another `HttpClient`, provided to `printFarm` alone.
 const servedWith = (environment: Record<string, string>) =>
   Testing.layer(routes).pipe(
-    Layer.provide(PrintFarm.layer.pipe(Layer.provide(fakeFarm))),
+    Layer.provide(printFarm.pipe(Layer.provide(fakeFarm))),
     Layer.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord(environment))),
   );
 

package/examples/notes-service/README.md

@@ -50,6 +50,37 @@ prints one message on stderr saying to set it, and exits 1. `--help` needs none.
 
 The tokens are fixed names and the store is memory: replace both before deploying anything.
 
+## Retry a creation
+
+`createNote({ title, body })` creates a new note on every call. To retry safely, add an optional
+`requestId`. Generate it once for a new creation, for example with `crypto.randomUUID()`, and
+keep it with the pending operation outside any retry loop. After a lost response, send the
+same key and content again. For the CLI, pass `--request-id` and keep it when repeating the
+command:
+
+```sh
+echo "First draft" | node --import tsx examples/notes-service/src/cli.ts create-note --request-id plan-1 --title Plan
+```
+
+The key belongs to the signed-in caller and the `createNote` operation. Another caller can use
+it independently. The same caller repeating the key and content gets the original result;
+different content fails with `RequestConflict`. A new key creates a new note, even when its
+content is identical. Every attempt still runs authorization.
+
+The replay result is a snapshot of the creation. Updating or deleting the note leaves that
+snapshot intact: replay neither changes the note back nor recreates it. `importNotes` has no
+request key; each import creates new notes. Calls without a key are not idempotent, so the
+creation tool does not advertise `idempotentHint: true`.
+
+[src/notes/store.ts](src/notes/store.ts) owns creation and replay recording.
+
+**DEMO ONLY:** notes and replay records live in this process's memory, without eviction. They
+do not survive a restart or coordinate separate server instances. A deployed store must commit
+the mutation and replay record in one transaction, enforce uniqueness of caller, operation and
+key, and define a retention window. An expired key no longer protects a retry. External side
+effects need the upstream system's cooperation: a local record cannot make a separate network
+call atomic. The library supplies neither replay storage nor automatic retries.
+
 ## Layout
 
 ```text
@@ -73,7 +104,7 @@ src/
 ├── worker.ts          entrypoint: a fetch handler for a serverless host
 ├── stdio.ts           entrypoint: MCP for a local agent
 ├── commands.ts        the commands calling the server, one written by hand, and their connection
-├── cli.ts             entrypoint: the commands, given that connection
+├── cli.ts             entrypoint: the commands
 └── browser.ts         client module: promises for a web page
 test/
 ├── notes/             in process, with Action.client
@@ -102,6 +133,7 @@ test/
 | A contract with declared errors and their statuses            | `src/notes/Notes.ts`             |
 | Input fields described, for `--help` and a tool's schema      | `src/notes/Notes.ts`             |
 | Handlers getting a service once and the caller per call       | `src/notes/handlers.ts`          |
+| A write safe to retry with the same caller and request key    | `src/notes/store.ts`             |
 | A public action beside protected ones                         | `src/status/`                    |
 | Authorization from `readOnly`, refusing with a scope          | `src/identity/authorize.ts`      |
 | A token verifier and OAuth discovery read from config         | `src/identity/verifier.ts`       |
@@ -112,7 +144,7 @@ test/
 | A CLI derived from the binding: an argument, a field on stdin | `src/commands.ts`                |
 | A command written by hand beside the derived ones             | `src/commands.ts`                |
 | A bulk import as one action, its command reading a file       | `src/notes/`, `src/commands.ts`  |
-| The CLI's connection, read from config when a command runs    | `src/commands.ts`, `src/cli.ts`  |
+| The CLI's connection, read from config when a command runs    | `src/commands.ts`                |
 | A missing token as one message, not a `ConfigError` report    | `src/commands.ts`                |
 | A promise client handling each declared error by its tag      | `src/browser.ts`                 |
 | Testing handlers and authorization with no transport          | `test/notes/notes.test.ts`       |

package/examples/notes-service/src/cli.ts

@@ -1,21 +1,15 @@
 import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node";
 import { Effect } from "effect";
 import { Command } from "effect/cli";
-import { HttpClient } from "effect/http";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import { commands, connection } from "./commands.js";
+import { commands } from "./commands.js";
 
 // Entrypoint: `node --import tsx examples/notes-service/src/cli.ts list-notes`.
-// The commands of commands.ts, connected to a server.
-const notes = commands.pipe(
-  // Provided on the command, never around `Command.run`: the URL and the token are then read
-  // when a command runs, so `--help` and a mistyped flag need neither.
-  Command.provideEffect(HttpClient.HttpClient, connection),
-);
+// The commands of commands.ts, which read where the server is and the token when one runs.
 
 // A result is printed on stdout. A failure goes to stderr, under an `ERROR` heading, as the JSON
 // HTTP sends, such as `{"_tag":"NoteNotFound","id":"9"}`, and the command exits 1.
-Command.run(notes, { version: "1.0.0" }).pipe(
+Command.run(commands, { version: "1.0.0" }).pipe(
   Effect.provide([NodeHttpClient.layerUndici, NodeServices.layer]),
   ActionCli.logToStderr,
   NodeRuntime.runMain,

package/examples/notes-service/src/commands.ts

@@ -1,10 +1,44 @@
-import { Config, Console, Effect, FileSystem, flow } from "effect";
+import { Config, Console, Effect, FileSystem, Schema } from "effect";
 import { Argument, CliError, Command } from "effect/cli";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { Http } from "./Api.js";
 
+// What a command fails with when no token is configured: a tagged error of the CLI's own, printed
+// on stderr as `MissingToken: <message>` under an `ERROR` heading, and exit 1.
+class MissingToken extends Schema.TaggedError<MissingToken>()("MissingToken", {
+  message: Schema.String,
+}) {}
+
+// The binding's typed client, connected to where the server is and as who is calling, both read
+// from config. It is an Effect, not a client: every command here, the derived ones and your own,
+// runs it when it runs, so `--help` and a mistyped flag read nothing. It reaches these commands'
+// requests and no others.
+const api = Effect.gen(function* () {
+  const baseUrl = yield* Config.String("NOTES_URL").pipe(
+    Config.withDefault("http://127.0.0.1:3000"),
+  );
+
+  // Required, since every command but `get-status` is refused without one. Left as it is, a
+  // missing token prints as `ConfigError: …`; mapped, it prints the message, which says what to
+  // do. A CLI whose public commands must answer signed out reads the token with `Config.option`
+  // instead and adds the header when it is there.
+  const token = yield* Config.Redacted("NOTES_TOKEN").pipe(
+    Effect.mapError(
+      () =>
+        new MissingToken({
+          message: "NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
+        }),
+    ),
+  );
+
+  return yield* ActionHttp.client(Http, {
+    baseUrl,
+    transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+  });
+});
+
 // The file's format: each note a `# ` title line, a blank line and its body, the notes apart by
 // a blank line. A body line that starts as a title would is written with a backslash before it,
 // as Markdown escapes one, and `import` takes it off, so every note reads back as it was.
@@ -15,14 +49,14 @@ const unescape = (body: string) => body.replaceAll(/^\\(?=\\*# )/gmu, "");
 // A command of your own, for what no single action does: this one calls two and writes a file.
 // It is a native Effect CLI command, so its syntax and its output are what you write: `notes
 // export notes.md` takes its argument from `Argument`, as a flag would come from `Flag`. It
-// calls the server through the binding's typed client, on the `HttpClient` the derived commands
-// use, and writes with the `FileSystem` every Effect CLI command has.
+// calls the server through `api`, the client the derived commands call, and writes with the
+// `FileSystem` every Effect CLI command has.
 const exportNotes = Command.make(
   "export",
   { file: Argument.String("file").pipe(Argument.withDescription("The Markdown file to write.")) },
   ({ file }) =>
     Effect.gen(function* () {
-      const client = yield* ActionHttp.client(Http);
+      const client = yield* api;
       const files = yield* FileSystem.FileSystem;
       const { notes } = yield* client.listNotes();
       const whole = yield* Effect.forEach(notes, ({ id }) => client.getNote({ id }));
@@ -63,7 +97,7 @@ const importNotes = Command.make(
   },
   ({ text }) =>
     Effect.gen(function* () {
-      const client = yield* ActionHttp.client(Http);
+      const client = yield* api;
 
       if (text === "") return yield* Console.log("Created 0 notes");
 
@@ -93,6 +127,7 @@ const importNotes = Command.make(
 // it: test/commands.test.ts.
 export const commands = ActionCli.remote(Http, {
   name: "notes",
+  client: api,
   commands: {
     // `notes create-note --title Draft < draft.md`: the body is piped in, not a flag.
     createNote: { stdin: "body" },
@@ -104,34 +139,3 @@ export const commands = ActionCli.remote(Http, {
   // go here.
   subcommands: [exportNotes, importNotes],
 });
-
-// Where the server is and who is calling, read from config: the `HttpClient` every command
-// above calls with. It is an Effect, not a value, so that cli.ts provides it on the commands
-// and it runs when one of them does.
-export const connection = Effect.gen(function* () {
-  const url = yield* Config.String("NOTES_URL").pipe(Config.withDefault("http://127.0.0.1:3000"));
-
-  // Required, since every command but `get-status` is refused without one. A failure of what a
-  // command is provided is no action's error: left as it is, a missing token is reported as a
-  // crash, the log line `ERROR (#n): ConfigError: SchemaError(Expected string at
-  // ["NOTES_TOKEN"])`. Mapped to a `UserError`, it is printed as any failure of a command is:
-  // the message under an `ERROR` heading on stderr, and exit 1. `userMessage` is all that is
-  // printed, never `cause`: what the user needs from the cause goes into the message. A CLI
-  // whose public commands must answer signed out reads the token with `Config.option` instead
-  // and adds the header when it is there.
-  const token = yield* Config.Redacted("NOTES_TOKEN").pipe(
-    Effect.mapError(
-      (cause) =>
-        new CliError.UserError({
-          cause,
-          userMessage:
-            "NOTES_TOKEN is not set. Set it to your token: export NOTES_TOKEN=<your token>",
-        }),
-    ),
-  );
-
-  return HttpClient.mapRequest(
-    yield* HttpClient.HttpClient,
-    flow(HttpClientRequest.prependUrl(url), HttpClientRequest.bearerToken(token)),
-  );
-});

package/examples/notes-service/src/identity/authorize.ts

@@ -8,6 +8,7 @@ import { CurrentUser, scopes } from "./Identity.js";
 // answered a challenge, which only a server publishing discovery (verifier.ts) can follow up.
 // Where tokens are fixed, such as API keys, name no scope: the refusal is then a plain one.
 // So `scopes` below goes when `protectedResource` in verifier.ts does: copy both or neither.
+// This named span measures authorization within the action's span, including a refusal.
 export const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
   const scope = action.readOnly ? scopes.read : scopes.write;
   const user = yield* CurrentUser;

package/examples/notes-service/src/notes/Notes.ts

@@ -25,6 +25,12 @@ export class NoteChanged extends Schema.TaggedError<NoteChanged>()(
   { httpApiStatus: 409 },
 ) {}
 
+export class RequestConflict extends Schema.TaggedError<RequestConflict>()(
+  "RequestConflict",
+  { requestId: Schema.String },
+  { httpApiStatus: 409 },
+) {}
+
 // A description on an input field is that field's help on every surface: beside its flag or
 // argument in a command's `--help`, and in the input schema a model reads from the MCP tool
 // listing and the OpenAPI document. A field without one has a flag with no help.
@@ -43,6 +49,8 @@ const Title = Schema.String.check(
 
 const Body = Schema.String.annotate({ description: "The note's whole text." });
 
+const Content = Schema.Struct({ title: Title, body: Body });
+
 export const ListNotes = Action.make("listNotes", {
   description: "List your notes, without their bodies.",
   success: { notes: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String })) },
@@ -60,9 +68,17 @@ export const GetNote = Action.make("getNote", {
 });
 
 export const CreateNote = Action.make("createNote", {
-  description: "Create a note.",
-  input: { title: Title, body: Body },
+  description:
+    "Create a note. To retry safely, supply a requestId and reuse it with the same content.",
+  input: {
+    requestId: Schema.optionalKey(Schema.NonEmptyString).annotate({
+      description:
+        "An optional key for this creation. Keep it for retries; without one, every call creates a note.",
+    }),
+    ...Content.fields,
+  },
   success: Note,
+  error: RequestConflict,
   readOnly: false,
   caller: CurrentUser,
   mcp: { destructiveHint: false },
@@ -98,14 +114,15 @@ export const DeleteNote = Action.make("deleteNote", {
 // Work every surface should offer is an action, a bulk import included: the HTTP API, the MCP
 // tools and the CLI then all have it, and the whole list is decoded, so checked, before the
 // handler writes any of it. A command of your own only reads the file and calls this once
-// (commands.ts). `importNotes` adds and removes nothing, so `destructiveHint` is `false`.
-// Each note is `createNote`'s input: an action's `input` is a schema already, used as it is.
+// (commands.ts). `importNotes` only adds notes, so `destructiveHint` is `false`.
+// Imports share note content with `createNote`, but exclude request keys because bulk creation
+// does not deduplicate.
 export const ImportNotes = Action.make("importNotes", {
   description:
     "Create several notes at once, such as those `notes export` wrote. Every note is checked " +
     "before any is written: an import holding one that is not valid writes none.",
   input: {
-    notes: Schema.Array(CreateNote.input)
+    notes: Schema.Array(Content)
       .check(
         Schema.isMinLength(1, { message: "An import holds at least one note." }),
         Schema.isMaxLength(100, { message: "An import holds at most 100 notes." }),

package/examples/notes-service/src/notes/handlers.ts

@@ -23,8 +23,8 @@ export const notes = Action.implement(
           return { notes: owned.map(({ id, title }) => ({ id, title })) };
         }),
       getNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.get(user.id, id)),
-      createNote: ({ title, body }) =>
-        Effect.flatMap(CurrentUser, (user) => store.create(user.id, title, body)),
+      createNote: ({ requestId, title, body }) =>
+        Effect.flatMap(CurrentUser, (user) => store.create(user.id, title, body, requestId)),
       updateNote: ({ id, body, revision }) =>
         Effect.flatMap(CurrentUser, (user) => store.update(user.id, id, body, revision)),
       deleteNote: ({ id }) => Effect.flatMap(CurrentUser, (user) => store.remove(user.id, id)),