Skip to content

Commit fcee225

Browse files
committed
Merge origin/main (d1e329e) into claude/issue-25742-liveness-flows-screens-anchor
2 parents 54ba753 + d1e329e commit fcee225

8 files changed

Lines changed: 773 additions & 13 deletions

File tree

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
'@objectstack/service-automation': minor
3+
---
4+
5+
feat(service-automation)!: a `notify` node mails the address in an email field of the trigger record, and refuses a computed address no user holds
6+
7+
Clause-②: no (narrowing: a recipient that the value expression of a `notify` node whose `channels` include `email` evaluates to an email address no user holds now fails the node at run time instead of being mailed)
8+
Metadata-protocol: narrowed
9+
10+
A `notify` node can now reach a person who is not a user, such as an applicant who came in through a public form. `recipients: { emailField: 'applicant_email' }` with `channels: 'email'` (the form `@objectstack/spec` declared earlier in this release, which until now failed the run at the node) mails the address held in that `email`-typed field of the record that triggered the flow.
11+
12+
- **The address.** It is read from the stored record by id when the node runs, never from the record snapshot the run carries. It must be exactly one plain ASCII mailbox, `name@example.com`. A list, a display name, a separator, a line break or an audience prefix such as `role:` fails the node and nothing is sent, and so does an address the `email` field type accepts but this node does not: a non-ASCII character, a quoted local part or an IP-literal domain. So do an empty field, a record that is not stored and a run with no trigger record. The failure names the field and the record, never the value.
13+
- **The send.** The title and message render as for any notify, the email goes through the deployment's outbound mail, and it is recorded like every notification: a `sys_notification` event and a `sys_notification_delivery` row whose recipient is the address.
14+
- **Per-address limit.** One address receives at most 5 email-field sends per hour (`EMAIL_FIELD_SENDS_PER_WINDOW`, `EMAIL_FIELD_SEND_WINDOW_SECONDS`), across every flow, counted case-insensitively in the kernel `cache` service (per process when none is registered, said once). A sixth fails the node before anything is written. The limit is best-effort: when the counter faults, the send is admitted and a warning is logged once.
15+
- **BREAKING (narrowed): a computed address the node mails must be a user's.** In a `notify` node whose `channels` include `email`, a recipient that a value expression (a CEL envelope) evaluates to and that reads as an email address, bare or as `user:ADDRESS`, now resolves to the user who holds it, and fails the node when no user holds it (or when no user directory can be read), with a message that points to `{ emailField }`. Before, such an address was mailed as it stood, so an expression over record text let whoever typed that text choose who the flow mailed. A node that does not name `email` (`inbox` alone, the messaging default) mails nobody and is unchanged. An address written out in the flow (`recipients: ['ops@example.com']`) is the author's constant and is sent as written, as before.
16+
- **Who moves.** A flow that mails (`channels` include `email`) a recipient its expression evaluates to an address no user holds. Measured over `examples/**` at `47af3dd`: no `notify` node names the `email` channel, so no in-repo flow changes. (Of the 17 `recipients` envelopes, the app-showcase ones over `record.owner` / `ownerId` do evaluate to addresses, since that field holds the owner's email, but those nodes are `inbox` only.) Fix: give the address its own `notify` node with `recipients: { emailField: 'FIELD' }` and `channels: 'email'`, or give the person a user.
17+
- **Dependency.** `@objectstack/plugin-auth` moves from a dev dependency to a dependency of `@objectstack/service-automation`: the limit counts through its `rate-limit-storage` fixed-window counter, the repository's one counter, as `@objectstack/service-sms` does. This is a new workspace edge, `service-automation` → `plugin-auth`, and no cycle: neither `plugin-auth` nor what it depends on (`service-messaging`, `rest`) depends on `service-automation`.
18+
19+
<!-- adr-0087: not-required (no-migration-prescription) a run-time refusal in a `notify` node that mails (`channels` include `email`) of a recipient that a value expression evaluates to an email address no user holds: no authorable key, spelling or stored shape moves, the parse is unchanged, and no stored flow is read, rewritten or converted. The repair is the author's choice between an email-field recipient naming a field of the trigger record and giving the person a user, which no ledger entry can derive, and no in-repo flow mails a computed address (no `notify` node in `examples/**` at `47af3dd` names the `email` channel). The other categories are closed on facts: the package publishes (not unpublished); no ADR-0087 id covers this verdict (not already-registered); and nothing exported is removed or narrowed (not runtime-interface-only, type-surface-only or runtime-export-retired). -->

‎content/docs/automation/flows.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -356,6 +356,51 @@ there — write the value itself (`sourceObject: 'crm_case'`). A `{…}` token
356356
there is refused, since it would reach the messaging service with its braces,
357357
and so is an envelope. The node's `actionUrl` is a text slot (below).
358358

359+
**A `notify` node mails a person who is not a user through an email field.**
360+
An applicant who came in through a public form has no account, so no user id
361+
reaches them. Write `recipients: { emailField: 'applicant_email' }` — the whole
362+
value, never a list entry — naming an `email`-typed field of the record that
363+
triggered the flow, with `channels: 'email'`:
364+
365+
```ts
366+
{
367+
id: 'tell_applicant', type: 'notify', label: 'Tell the applicant',
368+
config: {
369+
recipients: { emailField: 'applicant_email' },
370+
channels: 'email',
371+
title: 'We received your application, {{ record.company_name }}',
372+
message: 'We will reply within five working days.',
373+
},
374+
}
375+
```
376+
377+
The address is read from the **stored** record when the node runs, and it
378+
must be exactly one plain ASCII mailbox (`name@example.com`): a list, a
379+
display name, a separator or a line break fails the node and nothing is sent,
380+
and so do an address the `email` field type accepts but this node does not (a
381+
non-ASCII character, a quoted local part, an IP-literal domain), an empty field
382+
and a run with no trigger record. The title and message are
383+
rendered as for any notify, the send goes through the deployment's outbound
384+
mail, and it is recorded like every notification: a `sys_notification` event
385+
and a `sys_notification_delivery` row whose recipient is the address. One
386+
address receives at most 5 such emails per hour, across every flow; a sixth
387+
fails the node, so a form a visitor fills in cannot mail one inbox without
388+
end. The limit is best-effort: when its counter in the kernel `cache` service
389+
faults, the send is admitted and a warning is logged once. `objectstack validate` refuses a field the object does not have, a field
390+
that is not `email`-typed, another channel, and a flow with no triggering
391+
record.
392+
393+
In a node whose `channels` include `email`, an address a **value expression
394+
computes** must belong to a user, written bare or as `user:ADDRESS`: an
395+
envelope that evaluates to a user's address reaches that user, and one that
396+
evaluates to an address no user holds
397+
fails the node, pointing to `{ emailField }` — an expression over record text
398+
would otherwise let whoever typed that text choose who the flow mails. A node
399+
that does not name `email` (`inbox` alone, the default) mails nobody, so its
400+
computed recipients resolve as before. An address **written out** in the flow
401+
(`recipients: ['ops@example.com']`) is the author's constant and is sent as
402+
written.
403+
359404
**A CRUD node's filter: each operand computes before the query, and the query
360405
placeholders stay.** In a `get_record`, `update_record` or `delete_record`
361406
`filter`, each **operand** — a field's value, an operator's comparand, each

‎packages/services/service-automation/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
"@objectstack/metadata-core": "workspace:*",
3131
"@objectstack/metadata-protocol": "workspace:*",
3232
"@objectstack/platform-objects": "workspace:*",
33+
"@objectstack/plugin-auth": "workspace:*",
3334
"@objectstack/spec": "workspace:*",
3435
"@objectstack/types": "workspace:*"
3536
},
@@ -38,7 +39,6 @@
3839
"@objectstack/metadata-core": "workspace:*",
3940
"@objectstack/objectql": "workspace:*",
4041
"@objectstack/plugin-audit": "workspace:*",
41-
"@objectstack/plugin-auth": "workspace:*",
4242
"@objectstack/plugin-security": "workspace:*",
4343
"@objectstack/plugin-sharing": "workspace:*",
4444
"@objectstack/refd-timer-testkit": "workspace:*",

0 commit comments

Comments
 (0)