@terreno/mcp 57.2.0 → 57.3.0

package/src/docs/versioned/57.2.0/reference/comms.md

@@ -0,0 +1,213 @@
+# @terreno/comms
+
+Provider-agnostic transactional communications for Terreno backends. The core package defines
+mail, SMS, push, and verification contracts without installing SendGrid, Twilio, or Expo SDKs.
+
+## Install
+
+```bash
+bun add @terreno/comms
+```
+
+Peer dependency: `mongoose ^8.0.0 || ^9.0.0`.
+
+## Register the plugin
+
+```typescript
+import {
+  CommsApp,
+  ConsoleMailProvider,
+  ConsolePushProvider,
+  ConsoleSmsProvider,
+  ConsoleVerificationProvider,
+} from "@terreno/comms";
+import {TerrenoApp} from "@terreno/api";
+
+new TerrenoApp({userModel: User})
+  .register(
+    new CommsApp({
+      defaultFrom: "notifications@example.com",
+      mail: new ConsoleMailProvider(),
+      push: new ConsolePushProvider(),
+      sms: new ConsoleSmsProvider(),
+      verification: new ConsoleVerificationProvider(),
+    })
+  )
+  .start();
+```
+
+Console providers log only non-sensitive metadata such as message lengths and recipient counts.
+They never log message content, recipient identifiers, push tokens, or verification codes.
+
+## Send messages
+
+Use the registered service from routes, jobs, or other plugins:
+
+```typescript
+import {getCommsService} from "@terreno/comms";
+
+await getCommsService().sendMail({
+  subject: "Welcome",
+  text: "Thanks for joining.",
+  to: "person@example.com",
+});
+
+await getCommsService().sendSms({
+  body: "Your appointment is tomorrow.",
+  to: "+15555550100",
+});
+```
+
+`sendPushToUser()` resolves active device tokens and deactivates tokens when
+`errorClass` is `"permanent"` or `isPermanentFailure` is `true`. Provider throws become
+`errorClass: "transient"` with `errorCode: "provider-throw"` and never reject the
+`CommsService` promise. Transient failures retry once (`onRetry` with
+`context.attempt === 2`); push retries only the failed tokens. `checkVerification()` does
+not retry.
+
+`beforeSend` may mutate the message or cancel (`status: "cancelled"`, no provider call).
+A throwing `beforeSend` is logged and treated as no-op (send continues). Adapters later
+call `recordDeliveryEvent()` / `recordOptOut()` to update the log and fire
+`onDeliveryEvent` / `onOptOut`.
+
+Each send stores one `CommsMessage` row with `attempts[]`. Rendered payloads are retained
+for `retainPayloadDays` (default 30, `0` disables) after `redactPayload`. Mail payloads
+keep `to`, `from`, `subject`, `text`, `html`, `replyTo`, `templateId`, and
+`dynamicTemplateData`. SMS payloads keep `to` and `body`. Push payloads omit tokens.
+Verification start stores `{channel}` only; verification checks store no payload.
+`recordDeliveryEvent` writes `status`, `errorCode`, and `errorClass` onto the matching
+row (`opened` does not change status). Expired payloads are unset, not deleted.
+
+## Provider contracts
+
+| Interface | Method |
+|---|---|
+| `MailProvider` | `sendMail(message)` |
+| `SmsProvider` | `sendSms(message)` |
+| `PushProvider` | `sendPush(message)` — one `SendResult` per token |
+| `VerificationProvider` | `startVerification(options)`, `checkVerification(options)` |
+
+Concrete SendGrid, Twilio, and Expo providers are separate adapter packages/subpath exports. Core
+`@terreno/comms` has no concrete provider SDK dependencies.
+
+### SendGrid mail adapter
+
+```bash
+bun add @sendgrid/mail
+```
+
+```typescript
+import {CommsApp} from "@terreno/comms";
+import {SendGridMailProvider} from "@terreno/comms/adapters/sendgrid";
+
+new TerrenoApp({userModel: User})
+  .register(
+    new CommsApp({
+      defaultFrom: "notifications@example.com",
+      mail: new SendGridMailProvider({
+        // apiKey defaults to process.env.SENDGRID_API_KEY (required)
+        fromEmail: "notifications@example.com",
+        fromName: "Terreno",
+        // sandboxMode defaults to true when NODE_ENV === "test"
+      }),
+      onError: async (_context, result) => {
+        console.error("mail failed", result.errorCode, result.errorClass);
+      },
+    })
+  )
+  .start();
+```
+
+`SendGridMailProvider` fails fast at construction when `SENDGRID_API_KEY` (or `apiKey`) is
+missing. Send-time failures never throw through `sendMail`; they return
+`accepted: false` with `errorCode` / `errorClass` (`permanent` | `transient` | `config`).
+Transient failures are retried once by `CommsService`. Accepted sends store the SendGrid
+`x-message-id` and a `metadata.consoleUrl` Email Activity deep link on the `CommsMessage`
+row.
+
+**Sender verification checklist (SendGrid):**
+
+1. Create an API key with Mail Send permission.
+2. Verify the from domain (or single sender) in SendGrid.
+3. Confirm the from address matches a verified identity.
+4. Use sandbox mode in CI/tests so no real mail is delivered.
+
+## Configuration
+
+```typescript
+interface CommsAppOptions {
+  basePath?: string; // default: "/comms"
+  beforeSend?: (context: CommsHookContext) =>
+    Promise<{cancel?: boolean; message?: CommsHookMessage} | undefined>;
+  defaultFrom?: string;
+  logMessages?: boolean; // default: true
+  mail?: MailProvider;
+  onDeliveryEvent?: (event: DeliveryEvent) => Promise<void>;
+  onError?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  onOptOut?: (event: OptOutEvent) => Promise<void>;
+  onRetry?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  onSend?: (context: CommsHookContext, result: SendResult) => Promise<void>;
+  push?: PushProvider;
+  redactPayload?: (context: CommsHookContext, payload: unknown) => unknown;
+  redactRecipients?: boolean; // default: true
+  retainPayloadDays?: number; // default: 30; 0 stores no payload
+  sms?: SmsProvider;
+  verification?: VerificationProvider;
+}
+```
+
+When a channel is unconfigured:
+
+- non-production environments use the matching console provider and emit a warning;
+- production throws a `501` `APIError` titled `Comms channel not configured`.
+
+Delivery attempts are stored in `CommsMessage`. Recipient values are stored as `[redacted]` unless
+`redactRecipients` is explicitly `false`. Rendered payloads are retained for `retainPayloadDays`
+(default 30) after `redactPayload`; expired payloads are unset without deleting the log row.
+Mail payloads keep `to`, `from`, `subject`, `text`, `html`, `replyTo`, `templateId`, and
+`dynamicTemplateData`. SMS payloads keep `to` and `body`. Verification start keeps `{channel}`
+only; verification checks store no payload. `recordDeliveryEvent` writes `status`, `errorCode`,
+and `errorClass` onto the matching row (`opened` does not change status).
+
+`beforeSend` may replace the message or cancel the send (`status: "cancelled"`). `onSend` and
+`onError` fire after every channel outcome. `onRetry` fires once before the inline retry when
+`errorClass` is `"transient"` (`context.attempt === 2`; shipped signature is `(context, result)`).
+Throwing hooks are logged and never change the send outcome. Exception text stays in logs;
+`metadata.hookErrors` records only `hook-threw` per hook name. Adapters should call
+`recordDeliveryEvent()` and `recordOptOut()` rather than invoking those hooks directly.
+
+Provider throws become `{accepted: false, errorClass: "transient", errorCode: "provider-throw"}`.
+Permanent and config failures are not retried. Push retries re-send only the tokens whose first
+result was transient; tokens are deactivated when `errorClass` is `"permanent"` or
+`isPermanentFailure` is true. Each push token gets its own hook context (`attempt`, `isRetry`,
+`messageId`).
+
+## Routes
+
+The default `basePath` is `/comms`.
+
+| Method | Path | Access | Purpose |
+|---|---|---|---|
+| `POST` | `/comms/pushTokens` | Authenticated | Register or refresh a device token |
+| `GET` | `/comms/pushTokens` | Authenticated owner | List the current user's tokens |
+| `GET` | `/comms/pushTokens/:id` | Owner | Read one token |
+| `DELETE` | `/comms/pushTokens/:id` | Owner | Deactivate a token |
+| `GET` | `/comms/messages` | Admin | Filtered, paginated delivery log |
+
+An active token cannot be claimed by another user. After its owner deactivates it, another
+authenticated user on the same device may register it.
+
+## Templates
+
+`renderTemplate()` replaces top-level `{{variable}}` placeholders in `subject`, `text`, and `html`.
+Missing or inherited properties render as empty strings.
+
+```typescript
+const message = renderTemplate({
+  data: {name: "Ada"},
+  template: {
+    subject: "Welcome, {{name}}",
+    text: "Hello {{name}}",
+  },
+});
+```

package/src/docs/versioned/57.2.0/reference/components/README.mdx

@@ -0,0 +1,70 @@
+---
+title: UI components
+description: Generated reference pages for @terreno/ui components with live demo embeds.
+slug: /reference/components
+---
+
+# UI components
+
+These pages are generated from `demo/ui-types-documentation.json` and `demo/story-config/*.config.tsx` at site build time. Each page embeds the live component demo.
+
+- [Accordion](./accordion)
+- [AddressField](./addressfield)
+- [AI Suggestion Box](./ai-suggestion-box)
+- [Avatar](./avatar)
+- [Badge](./badge)
+- [Banner](./banner)
+- [Boolean field](./boolean-field)
+- [Box](./box)
+- [Button](./button)
+- [Card](./card)
+- [CheckBox](./checkbox)
+- [ConsentFormScreen](./consentformscreen)
+- [Custom Select Field](./custom-select-field)
+- [DataTable](./datatable)
+- [Date & Time field](./date-time-field)
+- [EditableCard](./editablecard)
+- [Email field](./email-field)
+- [Emoji selector](./emoji-selector)
+- [Field](./field)
+- [Filter](./filter)
+- [Height field](./height-field)
+- [Icon](./icon)
+- [IconButton](./iconbutton)
+- [Inner modal content](./inner-modal-content)
+- [Markdown editor field](./markdown-editor-field)
+- [MarkdownView](./markdownview)
+- [Multiselect Field](./multiselect-field)
+- [Number field](./number-field)
+- [Page](./page)
+- [Pagination](./pagination)
+- [Password field](./password-field)
+- [Phone number field](./phone-number-field)
+- [Radio field](./radio-field)
+- [SectionDivider](./sectiondivider)
+- [Segmented control](./segmented-control)
+- [Select field](./select-field)
+- [SelectBadge](./selectbadge)
+- [Side drawer](./side-drawer)
+- [Sidebar navigation (non-expo)](./sidebar-navigation-non-expo)
+- [Signature capture field](./signature-capture-field)
+- [Signature field](./signature-field)
+- [Slider](./slider)
+- [Spinner](./spinner)
+- [Table](./table)
+- [Table badge](./table-badge)
+- [Table boolean](./table-boolean)
+- [Table date](./table-date)
+- [Table icon button](./table-icon-button)
+- [Table number](./table-number)
+- [Table Text](./table-text)
+- [Table title](./table-title)
+- [Tap to edit](./tap-to-edit)
+- [Text area](./text-area)
+- [Text field](./text-field)
+- [Theme](./theme)
+- [ThumbsUpDownFeedback](./thumbsupdownfeedback)
+- [Toast](./toast)
+- [Tooltip](./tooltip)
+- [Typed signature field](./typed-signature-field)
+- [UserInactivity](./userinactivity)

package/src/docs/versioned/57.2.0/reference/components/badge.mdx

@@ -0,0 +1,39 @@
+---
+title: "Badge"
+description: "Badge is a label that indicates status or importance. Badges should provide quick recognition.\\n"
+sidebar_label: "Badge"
+slug: /reference/components/badge
+---
+
+import ComponentDemo from '@site/src/components/ComponentDemo';
+
+# Badge
+
+Badge is a label that indicates status or importance. Badges should provide quick recognition.\n
+
+**Package:** `@terreno/ui`  
+**Categories:** Component  
+**Props interface:** `BadgeProps`  
+**Story source:** [`demo/stories/Badge.stories.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/stories/Badge.stories.tsx)
+
+## Live demo
+
+<ComponentDemo name="Badge" />
+
+## Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `color` | `union` |  | For the "status" variant, whether the dot uses the bold (saturated) or subtle (light) tone. |
+| `customBackgroundColor` | `string` |  | When status is "custom", determines the badge's background color. |
+| `customBorderColor` | `string` |  | When status is "custom", determines the badge's border color. |
+| `customIconColor` | `keyof TextTheme` |  | When status is "custom", determines the badge's icon color |
+| `customIconName` | `IconName` |  | When status is "custom", determines the badge's icon |
+| `customTextColor` | `string` |  | When status is "custom", determines the badge's text color. |
+| `iconName` | `IconName` |  | The name of the icon to display in the badge. |
+| `maxValue` | `number` |  | The maximum value to display. Used for "numberOnly" variant to display "$\{maxValue\}+" when value is greater than max. |
+| `secondary` | `boolean` |  | If true, the badge will have a secondary style. |
+| `status` | `union` |  | The status of the badge. Determines its color and appearance. |
+| `testID` | `string` |  | Root test id for the primary interactive element or container. |
+| `value` | `union` |  | The text or number to display inside the badge. |
+| `variant` | `union` |  | The variant of the badge. "status" renders a small colored dot (no text) used to indicate an active/modified state. |

package/src/docs/versioned/57.2.0/reference/components/card.mdx

@@ -0,0 +1,26 @@
+---
+title: "Card"
+description: "A card serves as a surface for information. It helps organize and highlight information while providing visual hierarchy."
+sidebar_label: "Card"
+slug: /reference/components/card
+---
+
+import ComponentDemo from '@site/src/components/ComponentDemo';
+
+# Card
+
+A card serves as a surface for information. It helps organize and highlight information while providing visual hierarchy. Card renders the container and display surfaces; see EditableCard for a card that summarizes saved information the user can edit.
+
+**Package:** `@terreno/ui`  
+**Categories:** Component  
+**Props interface:** `CardProps`  
+**Story source:** [`demo/stories/Card.stories.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/stories/Card.stories.tsx)
+
+## Live demo
+
+<ComponentDemo name="Card" />
+
+## Props
+
+_No documented props were extracted from TypeDoc._
+

package/src/docs/versioned/57.2.0/reference/components/editablecard.mdx

@@ -0,0 +1,26 @@
+---
+title: "EditableCard"
+description: "A compact card summarizing saved information the user can edit, with an optional icon, badge, and helper text."
+sidebar_label: "EditableCard"
+slug: /reference/components/editablecard
+---
+
+import ComponentDemo from '@site/src/components/ComponentDemo';
+
+# EditableCard
+
+An editable card summarizes saved information in a compact row and gives the user a way to edit it. It wraps a Card, which provides the card surface, and adds an optional leading icon, a title with an optional badge, a description, helper text, and an edit button.
+
+**Package:** `@terreno/ui`  
+**Categories:** Component  
+**Props interface:** `EditableCardProps`  
+**Story source:** [`demo/stories/EditableCard.stories.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/stories/EditableCard.stories.tsx)
+
+## Live demo
+
+<ComponentDemo name="EditableCard" />
+
+## Props
+
+_No documented props were extracted from TypeDoc._
+

package/src/docs/versioned/57.2.0/reference/components/filter.mdx

@@ -0,0 +1,45 @@
+---
+title: "Filter"
+description: "A compositional filter dropdown for data-heavy views. Combine the select menu, boolean, and accordion sub-components inside the parent, with an optional Apply/Clear/Cancel footer. Desktop web only."
+sidebar_label: "Filter"
+slug: /reference/components/filter
+---
+
+import ComponentDemo from '@site/src/components/ComponentDemo';
+
+# Filter
+
+A compositional filter dropdown for data-heavy views. Combine the select menu, boolean, and accordion sub-components inside the parent, with an optional Apply/Clear/Cancel footer. Desktop web only.
+
+**Package:** `@terreno/ui`  
+**Categories:** Component  
+**Props interface:** `FilterProps`  
+**Story source:** [`demo/stories/Filter.stories.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/stories/Filter.stories.tsx)
+
+## Live demo
+
+<ComponentDemo name="Filter" />
+
+## Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | Yes | Composed filter controls rendered inside the dropdown panel. |
+| `applyButtonText` | `string` |  |  |
+| `cancelButtonText` | `string` |  |  |
+| `clearButtonText` | `string` |  |  |
+| `defaultOpen` | `boolean` |  | Initial open state when uncontrolled. |
+| `iconName` | `IconName` |  | Trigger button icon. Defaults to the built-in  |
+| `isOpen` | `boolean` |  | Controlled open state. Omit to use  |
+| `label` | `string` |  | Trigger button label. |
+| `onApply` | `reflection` |  | Called when Apply is pressed. The dropdown then closes. |
+| `onCancel` | `reflection` |  | Called when Cancel or a click-outside closes the dropdown. |
+| `onClear` | `reflection` |  | Called when Clear is pressed. The dropdown then closes. |
+| `onOpenChange` | `reflection` |  | Called whenever the dropdown opens or closes. |
+| `showActionButtons` | `boolean` |  | Master toggle for the Apply/Clear/Cancel footer. |
+| `showApplyButton` | `boolean` |  | Show the Apply button in the footer. |
+| `showCancelButton` | `boolean` |  | Show the Cancel button in the footer. |
+| `showClearButton` | `boolean` |  | Show the Clear hyperlink in the footer. |
+| `testID` | `string` |  | Root test id for the primary interactive element or container. |
+| `variant` | `union` |  | Primary theming for the trigger and Apply button. |
+| `width` | `number` |  | Panel width in pixels. Defaults to 320 per the design spec. |

package/src/docs/versioned/57.2.0/reference/components/signature-capture-field.mdx

@@ -0,0 +1,41 @@
+---
+title: "Signature capture field"
+description: "Lets a user sign by drawing or by typing their name and choosing a font, chosen via a"
+sidebar_label: "Signature capture field"
+slug: /reference/components/signature-capture-field
+---
+
+import ComponentDemo from '@site/src/components/ComponentDemo';
+
+# Signature capture field
+
+Lets a user sign by drawing or by typing their name and choosing a font, chosen via a
+
+**Package:** `@terreno/ui`  
+**Categories:** Component  
+**Props interface:** `SignatureCaptureFieldProps`  
+**Story source:** [`demo/stories/Signaturecapturefield.stories.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/stories/Signaturecapturefield.stories.tsx)
+
+## Live demo
+
+<ComponentDemo name="Signature capture field" />
+
+## Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `onChange` | `reflection` | Yes |  |
+| `defaultMode` | `SignatureMode` |  | Which capture method is shown first when the field is empty. Ignored once  |
+| `disabled` | `boolean` |  |  |
+| `errorText` | `string` |  |  |
+| `fonts` | `array` |  | Fonts offered in "type" mode. Defaults to the library's bundled signature fonts. When supplying a custom list, the consumer must load those font families themselves. |
+| `fullWidth` | `boolean` |  | Stretches the draw pad to the full available width. |
+| `helperText` | `string` |  |  |
+| `nameLabel` | `string` |  | Label for the typed name input. Defaults to "Full name". |
+| `onEnd` | `reflection` |  | Fired when the signer stops drawing — use to re-enable a parent ScrollView. |
+| `onStart` | `reflection` |  | Fired when the signer starts drawing — use to disable a parent ScrollView. |
+| `placeholder` | `string` |  | Placeholder for the typed name input. Defaults to "Type your full name". |
+| `testID` | `string` |  | Root test id for the primary interactive element or container. |
+| `testIDs` | `FieldTestIDs` |  |  |
+| `title` | `string` |  | Section title rendered above the field. Defaults to "Signature". |
+| `value` | `SignatureCaptureValue` |  | Controlled value. When omitted the field starts empty in  |

package/src/docs/versioned/57.2.0/reference/components/thumbsupdownfeedback.mdx

@@ -0,0 +1,32 @@
+---
+title: "ThumbsUpDownFeedback"
+description: "ThumbsUpDownFeedback is a thumbs up / thumbs down pair for collecting a single positive or negative reaction, e.g. on an AI generated response. Pressing the selected option again clears the selection."
+sidebar_label: "ThumbsUpDownFeedback"
+slug: /reference/components/thumbsupdownfeedback
+---
+
+import ComponentDemo from '@site/src/components/ComponentDemo';
+
+# ThumbsUpDownFeedback
+
+ThumbsUpDownFeedback is a thumbs up / thumbs down pair for collecting a single positive or negative reaction, e.g. on an AI generated response. Pressing the selected option again clears the selection.
+
+**Package:** `@terreno/ui`  
+**Categories:** Component  
+**Props interface:** `ThumbsUpDownFeedbackProps`  
+**Story source:** [`demo/stories/ThumbsUpDownFeedback.stories.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/stories/ThumbsUpDownFeedback.stories.tsx)
+
+## Live demo
+
+<ComponentDemo name="ThumbsUpDownFeedback" />
+
+## Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `onChange` | `reflection` | Yes | Called with the newly selected value, or undefined when the current value is deselected. |
+| `disabled` | `boolean` |  | If true, both options are non-interactive and rendered in a muted color. |
+| `negativeAccessibilityLabel` | `string` |  | Accessibility label for the negative (thumbs down) option. |
+| `positiveAccessibilityLabel` | `string` |  | Accessibility label for the positive (thumbs up) option. |
+| `testID` | `string` |  | Root test id for the primary interactive element or container. |
+| `value` | `ThumbsUpDownFeedbackValue` |  | The currently selected feedback. Leave undefined for no selection. |

package/src/docs/versioned/57.2.0/reference/components/typed-signature-field.mdx

@@ -0,0 +1,37 @@
+---
+title: "Typed signature field"
+description: "Lets a user type their name and choose a signature font with a live preview. Works the"
+sidebar_label: "Typed signature field"
+slug: /reference/components/typed-signature-field
+---
+
+import ComponentDemo from '@site/src/components/ComponentDemo';
+
+# Typed signature field
+
+Lets a user type their name and choose a signature font with a live preview. Works the
+
+**Package:** `@terreno/ui`  
+**Categories:** Component  
+**Props interface:** `TypedSignatureFieldProps`  
+**Story source:** [`demo/stories/Typedsignaturefield.stories.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/stories/Typedsignaturefield.stories.tsx)
+
+## Live demo
+
+<ComponentDemo name="Typed signature field" />
+
+## Props
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `onChange` | `reflection` | Yes |  |
+| `disabled` | `boolean` |  |  |
+| `errorText` | `string` |  |  |
+| `fonts` | `array` |  | Selectable fonts. Defaults to the library's bundled signature fonts. When supplying a custom list, the consumer is responsible for loading those font families (e.g. via expo-font) so the preview renders correctly. |
+| `helperText` | `string` |  |  |
+| `nameLabel` | `string` |  | Label for the name input. Defaults to "Full name". |
+| `placeholder` | `string` |  | Placeholder for the name input. Defaults to "Type your full name". |
+| `testID` | `string` |  | Root test id for the primary interactive element or container. |
+| `testIDs` | `FieldTestIDs` |  |  |
+| `title` | `string` |  | Section title rendered above the field. Defaults to "Signature". |
+| `value` | `TypedSignatureValue` |  | Controlled value. When omitted the field starts empty with the first font selected. |