npm - @positronic/template-new-project - Versions diffs - 0.0.63 → 0.0.64 - Mend

@positronic/template-new-project 0.0.63 → 0.0.64

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/index.js +4 -4
package/package.json +1 -1
package/template/CLAUDE.md +10 -0
package/template/_gitignore +1 -0
package/template/docs/brain-dsl-guide.md +82 -5

package/index.js CHANGED Viewed

@@ -53,10 +53,10 @@ module.exports = {
   ],
   setup: async ctx => {
     const devRootPath = process.env.POSITRONIC_LOCAL_PATH;
-    let coreVersion = '^0.0.63';
-    let cloudflareVersion = '^0.0.63';
-    let clientVercelVersion = '^0.0.63';
-    let genUIComponentsVersion = '^0.0.63';
+    let coreVersion = '^0.0.64';
+    let cloudflareVersion = '^0.0.64';
+    let clientVercelVersion = '^0.0.64';
+    let genUIComponentsVersion = '^0.0.64';
     // Map backend selection to package names
     const backendPackageMap = {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@positronic/template-new-project",
-  "version": "0.0.63",
+  "version": "0.0.64",
   "publishConfig": {
     "access": "public"
   },

package/template/CLAUDE.md CHANGED Viewed

@@ -119,6 +119,16 @@ export default brain('approval-workflow')
   }));
 ```
+### CSRF Tokens for Pages with Forms
+If your brain generates a custom HTML page with a form that submits to a webhook, you must include a CSRF token. Without a token, the server will reject the submission.
+1. Generate a token with `generateFormToken()` from `@positronic/core`
+2. Add `<input type="hidden" name="__positronic_token" value="${token}">` to the form
+3. Pass the token when creating the webhook registration: `myWebhook(identifier, token)`
+The `.ui()` step handles this automatically. See `/docs/brain-dsl-guide.md` for full examples.
 ### How Auto-Discovery Works
 - Place webhook files in `/webhooks` directory

package/template/_gitignore CHANGED Viewed

@@ -5,6 +5,7 @@ node_modules/
 # Local development server directory
 .positronic/
+.positronic-auth.json
 .env
 # Cloudflare Wrangler state and temp files

package/template/docs/brain-dsl-guide.md CHANGED Viewed

@@ -867,8 +867,6 @@ brain('Batch Processor')
   }, {
     over: (state) => state.items,  // Array to iterate over
     concurrency: 10,               // Parallel requests (default: 10)
-    stagger: 100,                  // Delay between requests in ms
-    maxRetries: 3,
     error: (item, error) => ({ summary: 'Failed to summarize' })  // Fallback on error
   })
   .step('Process Results', ({ state }) => ({
@@ -884,9 +882,7 @@ brain('Batch Processor')
 ### Batch Options
 - `over: (state) => T[]` - Function returning the array to iterate over
-- `concurrency: number` - Maximum parallel requests (default: 10)
-- `stagger: number` - Milliseconds to wait between starting requests
-- `maxRetries: number` - Maximum number of retries for failed requests (passed to the AI client SDK)
+- `concurrency: number` - Maximum number of items processed in parallel (default: 10)
 - `error: (item, error) => Response` - Fallback function when a request fails
 ### Result Format
@@ -1103,6 +1099,87 @@ The created page object contains:
 - `url: string` - Public URL to access the page
 - `webhook: WebhookConfig` - Webhook configuration for handling form submissions
+### Custom Pages with Forms (CSRF Token)
+When building custom HTML pages with forms, you must include a CSRF token to prevent unauthorized submissions. The `.ui()` step handles this automatically, but custom pages require manual setup. This applies whether you submit to the built-in `ui-form` endpoint or to a custom webhook.
+#### Using a Custom Webhook
+If your page submits to a custom webhook (e.g., `/webhooks/archive`), pass the token as the second argument when creating the webhook registration:
+```typescript
+import { generateFormToken } from '@positronic/core';
+import archiveWebhook from '../webhooks/archive.js';
+brain('Archive Workflow')
+  .step('Create Page', async ({ state, pages, env }) => {
+    const formToken = generateFormToken();
+    const html = `<html>
+      <body>
+        <form method="POST" action="<%= '${env.origin}' %>/webhooks/archive">
+          <input type="hidden" name="__positronic_token" value="<%= '${formToken}' %>">
+          <input type="text" name="name" placeholder="Your name">
+          <button type="submit">Submit</button>
+        </form>
+      </body>
+    </html>`;
+    await pages.create('my-page', html);
+    return { ...state, formToken };
+  })
+  .wait('Wait for submission', ({ state }) => archiveWebhook(state.sessionId, state.formToken))
+  .step('Process', ({ state, response }) => ({
+    ...state,
+    name: response.name,
+  }));
+```
+#### Using the System `ui-form` Endpoint
+If your page submits to the built-in `ui-form` endpoint, include the token in the webhook registration object:
+```typescript
+import { generateFormToken } from '@positronic/core';
+brain('Custom Form')
+  .step('Create Form Page', async ({ state, pages, env }) => {
+    const formToken = generateFormToken();
+    const webhookIdentifier = `custom-form-<%= '${Date.now()}' %>`;
+    const formAction = `<%= '${env.origin}' %>/webhooks/system/ui-form?identifier=<%= '${encodeURIComponent(webhookIdentifier)}' %>`;
+    const page = await pages.create('my-form', `<html>
+      <body>
+        <form method="POST" action="<%= '${formAction}' %>">
+          <input type="hidden" name="__positronic_token" value="<%= '${formToken}' %>">
+          <input type="text" name="name" placeholder="Your name">
+          <button type="submit">Submit</button>
+        </form>
+      </body>
+    </html>`);
+    return {
+      ...state,
+      pageUrl: page.url,
+      webhook: { slug: 'ui-form', identifier: webhookIdentifier, token: formToken },
+    };
+  })
+  .wait('Wait for form', ({ state }) => state.webhook)
+  .step('Process', ({ state, response }) => ({
+    ...state,
+    name: response.name,
+  }));
+```
+#### Summary
+The three required pieces for any custom page with a form:
+1. Call `generateFormToken()` to get a token
+2. Add `<input type="hidden" name="__positronic_token" value="...">` to your form
+3. Include the `token` in your webhook registration — either as the second argument to a custom webhook function (e.g., `myWebhook(identifier, token)`) or in the registration object for `ui-form`
+Without a token, the server will reject the form submission.
 ## UI Steps
 UI steps allow brains to generate dynamic user interfaces using AI. The `.ui()` step generates a page and provides a `page` object to the next step. You then notify users and use `.wait()` to pause until the form is submitted.