nika:notify
Network
Tool family from the canonical registry.
invoke
Call this builtin through the invoke verb.
Read this contract
This reference preserves the specification at the revision linked below. Source examples are fragments: their surrounding tasks, inputs and permissions are not supplied here. Consult engine status andnika catalog --tools --json for the installed implementation; a registry declaration is not a runtime qualification.
Usage and behavior
illustration
channel: enum (webhook/slack/email/discord/sms · one builtin not 5). The 1.0 engine MUST support webhook · others MAY be feature-gated. data: (OPTIONAL · any JSON value) carries structured context alongside the human message: the webhook payload is { message, severity, data? } (the key is absent when not given · receivers branch on machine fields, never parse the message). Returns null on accepted delivery. Throws · NIKA-BUILTIN-NOTIFY-001 (channel unconfigured · validation_error) · -002 (delivery failed · network_error · transient engine-assessed).
Chat webhooks (normative · webhook) · a chat service’s incoming webhook reads its own text field and refuses the payload above (a Slack incoming webhook answers HTTP 400 no_text). The engine MUST shape the webhook body for the receivers it recognizes from target: and MUST keep { message, severity, data? } for every other target:
The text a person reads is the
message, prefixed [<severity>] when severity is not info, then the data: context on its own line (a string as written, any other value as compact JSON). For Slack, & < > become & < >. For Discord, every character that opens markdown, a masked link or a mention (\ * _ ~ ` | [ ] < >, and a line’s opening # or -) is backslash-escaped outside a bare http:///https:// URL, and content is bounded to 2,000 UTF-16 units, ending … when cut, without splitting an escape. A refused delivery (-002) names the receiver’s answer as one bounded line, with control and invisible characters removed and every part of target: withheld (a webhook URL carries its credential in its path or query), and carries details.status_code.
Injection defense (normative) · the webhook payload is JSON-encoded, so the message cannot break its transport (serde escaping neutralizes "/newlines). A channel that renders the message into a DIFFERENT medium MUST neutralize that medium’s injection surface when implemented · email MUST reject/strip CR/LF in any header-bound field (target:/subject) against RFC 5322 header injection · slack/discord MUST treat the message as text, never a trusted mrkdwn/mention control string · sms MUST bound length to the carrier segment limit. The webhook target: rides the same SSRF boundary as nika:fetch (private-network / cloud-metadata rejected). Same discipline as the nika:fetch SSRF requirement · an output channel that reaches an interpreter neutralizes that interpreter’s control surface.
Related concepts
Arguments
Pass the values required by the tool contract.
Permissions
Understand authority before granting effects.
Errors and recovery
Read diagnostics and choose a recovery policy.
Workflow templates
Put the fragment inside a complete workflow.
Contract provenance
Read the pinned specification · Canonical registry. Tool identity:nika:notify. Specification revision: 5cd95cd25c0f.
Documentation
Guides, reference contracts and working examples.
Language spec
the nine-key envelope, Apache-2.0. The contract these docs explain.
Engine source
Rust, AGPL-3.0-or-later. Every commit public.
TypeScript SDK
Use one typed lifecycle locally or against authenticated nika serve HTTP.
Editor extension
The editor extension, frozen at 0.120 and not qualified with 0.124: use
nika lsp and the JSON Schema.Homebrew tap
brew install supernovae-st/tap/nika for the latest tagged CLI release.SuperNovae
The Paris studio crafting Nika. 🦋