@simpleplatform/sdk 2.4.0 → 2.4.1

package/README.md

@@ -308,6 +308,63 @@ yet; attach its handle through the workflow that owns the record.
 
 ## API Documentation
 
+### Describing an Action
+
+What an action is, and when to reach for it, is written where the code is — in
+the JSDoc comment above the handler, the same comment that carries its
+description:
+
+```typescript
+/**
+ * Close a duplicate lead and point it at the record that survives.
+ *
+ * The surviving lead keeps its activity; the duplicate is marked closed and
+ * linked to it, so a later report still reaches both records.
+ *
+ * @tool
+ * @shortdesc Close a duplicate lead, pointing it at the surviving record.
+ * @usewhen A lead is a duplicate of one already in the system.
+ * @usewhen Two leads share a contact and one should be retired.
+ */
+simple.Handle(async (request) => {
+  // ...
+})
+```
+
+| Tag             | Shape                                           | What it says                                                                                                                              |
+| --------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tool`         | bare, no value                                  | This action can be reached as a tool                                                                                                      |
+| `@shortdesc`    | one line, up to 300 characters, written once    | What this is, read in a listing of tools                                                                                                  |
+| `@usewhen`      | one line, up to 100 characters, up to ten times | One occasion for reaching for this rather than something else                                                                             |
+| `@parallelsafe` | bare, no value, only alongside `@tool`          | This tool changes no stored data and sends nothing, so it may run at the same time as the other parallel-safe calls next to it in a batch |
+
+`@parallelsafe` is a claim you make about your own action; the platform does
+not verify it. It changes only which calls of a batch may overlap — consecutive
+parallel-safe calls may run at the same time, and every other call still runs
+alone, in the order asked. It never changes whether a failed call is retried,
+nor the platform's assumption that a failed call may have changed stored data.
+The build refuses it without `@tool`, with a value, or written twice. Write it
+only when the action is read-only:
+
+```typescript
+/**
+ * Look up a lead's open activity.
+ *
+ * @tool
+ * @shortdesc Look up a lead's open activity.
+ * @usewhen A caller wants a lead's current open activity.
+ * @parallelsafe
+ */
+simple.Handle(async (request) => {
+  // reads only — no writes, no outbound calls
+})
+```
+
+The prose above the tags is the full description, and stays exactly as
+written. Each tag is declared in `tsdoc.json` (`{"tagName": "@parallelsafe",
+"syntaxKind": "modifier"}` alongside `@tool`, `@shortdesc` and `@usewhen`), so
+an editor with TSDoc support recognizes it instead of flagging it as unknown.
+
 ### AI Module
 
 The AI module provides powerful capabilities for working with unstructured data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleplatform/sdk",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Simple Platform Typescript SDK",
   "license": "Apache-2.0",
   "homepage": "https://docs.simple.dev",