BetaRecipes / Authoring a FlurryPORT recipe

Authoring a FlurryPORT recipe

A recipe is a small declarative document: what an agent may send (the intent schema), how it becomes a provider call (the transformation and target template), and what the human sets up once (install parameters and secrets). Agents install recipes by copying them, so the document is the product: write every field as if it will be pasted unchanged into a live pipe, because it will be.

The prime rule: your recipe will be copied verbatim

An installing agent pattern-matches from whatever is in front of it. A vague field becomes a guess, a placeholder left in prose becomes a live value, and an undeclared convention simply does not exist. Structured facts beat paragraphs every time: one canonical example teaches more than a page of description.

The authoring loop

  1. Draft the content document (start from the exemplar below).
  2. Lint it: the lint_recipe tool, or POST /api/v1/catalog/recipes/lint. Every error is exactly what publishing would refuse.
  3. Fix errors, act on warnings, lint again until clean.
  4. Prove it: fire the pipe at the real destination once. Publishing requires that receipt, no exemptions.
  5. Publish. A moderation review with your functional receipt rides every version.

The content document

Recipes are published as one JSON content document. These are its fields; the exemplar below shows every one of them in a shipped, receipt-proven recipe.

Install parameters are structured facts

$install.NAME means: inline a literal here at install time. The engine has no runtime $install binding, so every placeholder must be a declared parameter the installer can resolve before the pipe goes live. Each entry carries four facts:

Install parameters are non-secret by definition: they are inlined visibly into the transformation. Credential-shaped parameter names are refused at publish. Anything sensitive is $secrets.NAME, declared under secrets.

Secrets: the shape and the custody rule

Each secrets entry is exactly { logicalName, walkthrough }. logicalName is the SCREAMING_SNAKE name that $secrets.NAME references and the secret page labels its box with; other keys are not read. The walkthrough is the service-side steps you actually took proving the recipe: the agent relays them, and the human enters the value on the FlurryPORT secret page. Values never transit the model.

When the destination host varies per user (self-hosted chat servers, per-tenant webhook URLs), the whole URL is the secret: targetTemplate.url is just $secrets.NAME. A hardcoded host makes the recipe single-tenant, and lint cannot know a host is a placeholder; only the receipt gate catches it. Token-in-path, like the exemplar's bot URL, fits when the host is fixed and only the credential varies.

Every lint finding, and what it means

Errors refuse publish, fail closed. Warnings are install-success advice and never block. The lint_recipe tool and the publish gate run the same checks, so nothing here is learn-by-rejection-only.

The exemplar: telegram-send, field by field

This is the shipped flurryport:telegram-send content document, receipt-proven at its real destination. It lints clean against every rule on this page. Start your draft from this shape.

{
  "displayName": "Send a Telegram message",
  "description": "Deliver a message via a Telegram bot to a chat. The bot token rides the request URL path, which is exactly why it must never transit the model - FlurryPORT resolves $secrets in the URL server-side at delivery.",
  "intentSchema": {
    "type": "object",
    "required": ["text"],
    "properties": {
      "text": { "type": "string", "maxLength": 4096 },
      "chatId": { "type": "string", "description": "Override the installed default chat." }
    }
  },
  "parameters": [
    {
      "name": "chatId",
      "binding": "install-time",
      "type": "string",
      "required": true,
      "example": "8123456789",
      "howToFind": "Send your bot a message, then open your bot's getUpdates page in a browser; the chat id is the numeric message.chat.id value. For a group, add the bot to the group first; group ids are negative numbers.",
      "description": "Default chat id for this install; runtime intent.chatId overrides."
    }
  ],
  "transformation": "{ \"chat_id\": $body.chatId ? $body.chatId : $install.chatId, \"text\": $body.text }",
  "targetTemplate": {
    "url": "https://api.telegram.org/bot$secrets.TELEGRAM_BOT_TOKEN/sendMessage",
    "method": "POST",
    "headers": { "Content-Type": "application/json" }
  },
  "secrets": [
    {
      "logicalName": "TELEGRAM_BOT_TOKEN",
      "walkthrough": "Message @BotFather, run /newbot, copy the token. Start a chat with your bot (or add it to a group) and get the chat id from getUpdates. Paste the token in the FlurryPORT secret page."
    }
  ],
  "tools": [
    {
      "name": "flry_telegram_send",
      "description": "Send a message via the configured Telegram bot. Input: text (required), chatId (optional override).",
      "inputSchema": {
        "type": "object",
        "required": ["text"],
        "properties": { "text": { "type": "string" }, "chatId": { "type": "string" } }
      }
    }
  ],
  "gotchas": "Token-in-path means URL logs are sensitive on the Telegram side; text over 4096 chars is rejected by the API."
}

A proven pipe gets published

The receipt gate has no exemptions: a delivery recipe publishes with a receipt from firing this exact content at its real destination, first-party included. Write the walkthrough from that run; anything you did not need, the user does not either. Every published version carries a moderation review with the functional receipt attached, and human approval stays in the loop.

Lint from anywhere

Agents: run npx -y flurryport mcp (no account needed) and call lint_recipe with your draft. Anything else: POST the document as {"ContentJson": "..."} to /api/v1/catalog/recipes/lint. Same checks, structured findings, nothing stored.

Securing an endpoint

The capture URL is a write capability, reading always needs a token, and signed intake can close an inbox to everyone but trusted writers. The full model, including key custody and what your recipe should declare about integrity, lives at /recipes/security. Intake recipes whose value depends on message integrity should teach it in their own content.

Back to all recipes