Authoring ingredient packs

Use an ingredient pack when a recipe needs an action on an outside system. You will want to use that action again and again. The action can be an API request or a GraphQL query. It can be a method on a connector you have set up. It can be a local command, or a live subscription. An ingredient is one action a recipe can use. It says how that one action works. The pack is the box around it. The pack handles install, connection, grants, and uninstall.

Is the work only computing? Use a transform. Does it chain actions into a result? Write a recipe. Keep secret keys out of both. They belong in a named connection.

#Start in the Pack editor

Open Kitchen → Ingredient pack. The editor always makes a pack, even for one action. Even a tiny pack gets the same rules as a big one. That means review, grants, and lifecycle.

The editor has five sections:

Save early. A saved draft gets its own Kitchen URL. It shows up in the draft picker. A fresh edit makes the last check result stale until you save again.

#1. Name the capability

Give the draft a human title and a slug. A slug is a short lowercase name that never changes. The slug becomes part of each installed operation id. So use the name of the system, or of what the pack does. Do not use a project name you will drop later. Rename it later, and recipes and grants treat it as something new.

In Publish, give the pack its own slug and description. Also give it a kind, a service kind, and search tags. A good description answers three questions. What result does this add? Which system does it talk to? Does anything run in the background?

#2. Choose how it runs

In Setup, choose the smallest thing that can do the job.

Connection is for HTTP, GraphQL, and connector methods. Say what the base URL or endpoint looks like. Say which connection the pack expects. The draft describes requests. It does not carry an API key, an OAuth token, a cookie, or a password. The server adds the saved secret key only at call time.

CLI delegated is for a command that is already on the server's computer. Name the program and a check that says it is ready. Each operation builds a list of arguments. It never builds a shell command by pasting text together. Keep values that come from users in typed argument slots. Never turn one into code that runs.

You can also say which versions of the program you tested. And you can say how the owner installs it. Recued shows the owner that command. It never runs it. See the composition reference.

#Records: when a pack keeps its own rows

Records is for a pack that needs to keep its own business rows. A job board. A course roster. An order ledger. Not reading someone else's data. The rows live in your server's own encrypted database. The pack offers them as normal actions. So a recipe calls job.search just the way it would call a vendor API. There is no secret key. Nothing leaves the machine.

Records has limits on purpose. The limits are the product, not a first version to grow out of. A pack declares business objects onto a fixed row shape. Each object gets a set number of slots. The slot kinds are text, number, exact decimal, date, true/false, and reference. Each object gets a closed set of actions. They are: create, read one, read many, search, count, update, insert-or-update, and delete. There is no SQL. There is no schema of your own. There is no custom index. Does one object run out of slots? Then declare a second object and link the two. That is just normal data modelling.

#Records: three things to plan for

Plan for these from the start. Every change is checked. An update or a delete must say which row version it expects. So two people editing the same row cannot both quietly win. Searching is bounded. You declare which fields may be filtered and sorted. A query too broad to answer is refused. You get advice instead of a quiet grind. Changing your row shape later is a migration. It is reviewed and run in steps. So it is worth spending a little time on the shape before you publish.

Is the needed vendor connection or program missing? Then preview and install should say so. Do not bake a secret or a path from your own machine into the draft. That would only make it look portable.

#3. Declare operations

Add one card for each action a recipe can call. Group related cards into a family. Then give each one a name that will not change. Add a plain-language description. Recipes refer to the installed operation id. So a name change is a breaking change.

The editor has forms for the common binding kinds:

Webhook, queue, and push-channel bindings use the advanced JSON form. They are special live surfaces. Use them only when the vendor cannot be modeled as a normal request.

For each operation:

• declare each argument the caller supplies, and its type;
• mark an argument as target-affecting when changing it changes the target. The target is the person, record, file, or destination the approval is about;
• choose an honest risk tier: read, write, admin, or destructive;
• choose never, ask, or always for approval;
• mark the card reviewed only after you check it. Check its resolved target, needed scopes, editable arguments, paging, and output mapping.

The Reviewed checkbox is you saying "I checked this". It is not a way around the rules. The server's checks and the live policy gate still decide two things. Can the pack be installed? Can a call run?

#4. Map data on purpose

A pack that only does actions may need no entity schema (the list of fields a kind of record has). A data catalog should use Data fields. That turns vendor-shaped responses into steady fields that recipes can understand.

For each field, declare its entity, vendor path, and type. Also declare its request or response use, and its source operation. Mark it optional when the vendor really does leave it out sometimes. Add a PII label when it holds personal details. That means a name, an email, a phone number, or an address. It also means any other supported privacy class. The review summary points those fields out.

Cross-vendor aliases are promises about meaning. Pick one only when the field really carries that standard meaning. Not just because two vendors use a similar label.

#5. Save and read the review

Save stores the draft and checks it on the server. Then it breaks the draft down into the exact pieces an install would write. Those pieces are the ingredient, catalog, entity-schema, operation-group, and default-grant records. The review sums up:

• operation families and their risk and approval mapping;
• how many entity fields and how many PII fields;
• how many pieces were compiled;
• errors and warnings, each with the path where it was found.

Errors block preview and install. A valid review can still carry warnings. Read them. Do not treat the green status as a stand-in for your own judgement. Any edit makes the review stale until the new body is saved and reviewed.

#6. Preview without testing a write on production

After the review passes, pick an operation in Publish. Enter preview arguments as one JSON object. Choose Preview.

Is it a read behind a connection? Then Recued may run the real request against the saved connection. Then it shows a bounded mapping preview with secrets hidden. A write, admin, or destructive action is never run by preview. Instead you see the resolved request plan, risk, approval, and auth source. Connector and live operations may also return a plan that does not run. That happens when they cannot be sampled safely.

Preview does not last, on purpose. It does not change the draft. It does not keep a sample. It does not write a normal run into the audit diary. Do you need proof of the whole path, policy and audit included? Then run the installed operation through a test recipe.

#7. Install locally before publishing

Fill in the pack details and the list of things it depends on. Is the pack behind a connection? Then choose the local access tier and audience. The install grant picker shows them. Then choose Install.

This installs the reviewed draft on your server. It is not a marketplace publish. That is true even though it sits in the editor's Publish section. Check the installed pack in Discover or Settings. Call each read through a test recipe. Confirm that writes stop at the expected approval. Then test uninstall on a server where no recipe still pins the pack.

#8. Publish the pack

Publishing to everyone is its own cloud step. Reserve a free publisher handle. Set the manifest's publisher to that exact handle. Publish a version-2 pack whose contents carries the reviewed composition. The dashboard accepts three forms. One is a Kitchen handoff, when a build offers one. One is an uploaded JSON file. One is a pasted JSON object.

Packs publish straight away. They do not go into the recipe review queue. But the cloud still runs the pack and composition checks again. That does not mean Recued vouches for the pack. It does not resolve every outside pin. A pin is a fixed version number of something the pack needs. It grants nothing on an installer's server. Read the pack manifest and publishing guides before you submit.

#Before you share it

• The slug and operation ids will not change. They carry your publisher name.
• No secret, token, cookie, local username, or machine path is in the draft.
• Each target field the caller controls is declared and marked the right way.
• Risk and approval describe what each operation really does.
• Reads preview with success. Writes, admin, and destructive actions show a plan without running.
• PII fields and output mappings are correct.
• Local install, a test recipe, the audit diary, and uninstall all behave as you expect.
• The pack version and each dependency pin are on purpose.

For the single-operation fields a pack compiles down to, see the ingredient manifest page. For the bundle envelope and the by-value composition boundary, see the pack manifest page.