Primitives
The parts an app uses instead of writing its own, each with its rules built in.
Every primitive finds your app from the file that called it. No function takes a slug, so one app cannot act as another. The kit page lists every function with its signature. Inside a namespace the examples call the kit with a leading backslash, which is how the lint reads it.
Secrets
\respira_secret( 'RESEND_KEY' ) returns a value the owner set, or null. Declare each one in secrets as an object with a name matching ^[A-Z][A-Z0-9_]{2,63}$, a label and required.
- Only the owner sets, rotates or deletes a secret, on the Respira Code Secrets screen. No REST route or MCP tool writes one, and every credential gets a 403.
- A constant
RESPIRA_CODE_SECRET_<APP>__<NAME>inwp-config.phpwins over the stored value. - Values are encrypted at rest. A rotated value stays readable as
\respira_secret_previous()for 7 days. - A secret's value is replaced with
[secret:NAME]in every response, log and audit row. A deploy is refused while a required secret is unset.
Declare each kind in emails as one or many. A one kind answers the recipient's own action: a confirmation, a verify link, a delete link. A many kind is a batch.
function send_invites( array $recipients ) {
$plan = \respira_app_send_batch( 'invite', $recipients, array( 'dry_run' => true ) );
$test = \respira_app_send( 'invite', array( 'vars' => array( 'first_name' => 'Test' ) ), array( 'test_to' => \get_option( 'admin_email' ) ) );
return \respira_app_send_batch(
'invite',
$recipients,
array(
'receipt' => $test['receipt'],
'expect_plan' => $plan['plan_sha256'],
)
);
} - Send once. A ledger keyed on app, kind and a hash of the normalised address stops a second send.
once_keyallows one per key.allow_repeatneeds a stated reason. - Limits. A
manykind may reach 10 distinct people an hour per app without a test receipt. A bigger batch is refused whole, withrespira_code_mail_receipt_required, and nothing is sent. Aonekind sent in the recipient's own request is never held for the owner and is limited to 5 an hour and 20 a day per address and 200 an hour per kind, then skipped with the limit named. Aoneletter that an agent key or a job sends counts against the same 10 people an hour as a batch, and past it the letter is held for the owner. - Test receipt. A send with
test_toto an admin address returns a receipt. It lasts 60 minutes, covers the tested languages, and a batch spends it once. Passtest_totorespira_app_send(), for a kind of either audience.respira_app_send_batch()takes onlydry_run,receiptandexpect_plan, and refuses another option. - Dry run. It sends nothing and returns a plan hash.
expect_planrefuses a list that drifted. - Providers.
wp_mail, Resend or Postmark, chosen by the owner. Webhooks arrive at/mail/webhook/{provider}/{slug}.
Templates
Write emails/<kind>/<lang>.html. The respira CLI compiles each to JSON at deploy. {{var}} is escaped. {{var|url}} accepts https on the site's host, and http only when the site itself is http. {{respira.delete_link}} and {{respira.unsubscribe_link}} are built in. A many kind without an unsubscribe link fails the lint. POST /apps/<slug>/templates/preview renders one.
Jobs
List a job in cron with a hook, a schedule, a timeout and an optional offset_minutes, then call \respira_app_on_job( $hook, $handler ). Respira keeps WP-Cron equal to the manifest. A lock lets one instance run, and a long job calls \respira_app_job_alive() every few minutes to keep it. A thrown error fails the run only. Three fatals quarantine that job. The site brief warns when cron runs late or has no loopback. respira app job run <hook> runs one now, snapshots its tables and is audited.
Erasure
\respira_app_delete_link( $email ) returns a link for one person. A GET shows a confirmation page. Only a POST erases, because mail scanners open links. Erasure deletes the declared rows and their children, cancels queued mail, suppresses the address hash and keeps no copy. People without a link can ask at POST /privacy/request, which uses WordPress's own request flow. The app is also registered as a core eraser and exporter.
Retention
Retention is a list of rules inside personal_data. Child tables go on the entry, each with the column that points at the parent: children with fk. Erasure and every retention rule of the entry delete those rows first.
{
"manifest_version": 1,
"slug": "demo",
"version": "1.0.0",
"entry": "entry.php",
"tables": [ { "name": "demo_people" }, { "name": "demo_mail" } ],
"personal_data": [
{
"table": "demo_people",
"email_column": "email",
"columns": ["email"],
"basis": "consent",
"children": [ { "table": "demo_mail", "fk": "person_id" } ],
"retention": [
{ "table": "demo_people", "after": { "column": "created", "days": 30 }, "where": { "status": "unconfirmed" }, "chunk": 500 }
]
}
]
} A rule needs a where when the table has a status column, and * is never allowed. The runner deletes rows matching both after and where, children first, in chunks of 500 rows by default. A rule may set its own chunk, and the runner caps it at 1,000. The owner approves each rule with its hash and a dry-run count, and a changed rule needs a new approval. Your own job can call the runner. It never runs its own DELETE.
A rule may carry its own children, written { "table", "key" }. When it does, that list replaces the entry's for that rule. Most apps leave it out.
Rate limit
\respira_app_rate_limit( $key, $limit, $window_seconds ) returns true while the call is allowed. It is scoped to your app and counts atomically, and a window is at most 7 days. Call it before the first write in any public route, and write the leading backslash, or import it with use function.
Logs
\respira_app_log( $level, $code, $message, $context ) writes to the channel app. The levels are debug, info, notice, warning and error. The other channels are php, mail, job, i18n, compliance and secret. respira app logs pen-pals -f follows them; --channel and --level filter. Values are redacted and addresses masked.
Translations
Put strings in i18n/<lang>.json and declare i18n with a default and a language list. \respira_app_t( $key, $vars ) picks the language from Polylang, then WPML, then the locale. The lint refuses a key missing from any language. A missing key at runtime falls back to the default, then to [[key]], so put [[ in each contract's must_not.
Consent check
POST /apps/<slug>/compliance/consent-check reads the home page and each contract page, and finds tracking tags, the consent default and the consent tool. It warns and blocks only if the owner opts in. It reads one server response, so a cookie that JavaScript sets later is not seen. Say what is allowed in consent: allow_hosts, allow_cookies, cmp_markers.