Add actions

An action is anything that changes the world outside Tappify. Every one of them creates a run that starts pending, shows the owner a card, and only reaches your server after they approve.

tappify extension add action send-push --scope messaging:send

The push-notification extension

The example that runs end to end is an extension that sends a push notification through the owner’s own Firebase project. The owner supplies their Firebase credentials at install, the action asks them before every send, and their credentials reach your server and nowhere else.

{
  "id": "push-lab",
  "name": "Push Lab",
  "description": "Send a push notification to a segment of your users.",
  "scopes": [
    { "key": "ui:render" },
    {
      "key": "ai:actions",
      "justification": "Sending a notification is a change to the owner's users, so it goes behind an approval card."
    },
    {
      "key": "messaging:send",
      "justification": "Sends the notification through the Firebase project the owner connects at install."
    }
  ],
  "contributes": {
    "connector": {
      "auth": {
        "method": "api_key",
        "fields": [
          {
            "name": "firebase_project_id",
            "label": "Firebase project ID",
            "type": "text",
            "required": true
          },
          {
            "name": "service_account",
            "label": "Service account JSON",
            "type": "file",
            "required": true,
            "help": "Firebase console → Project settings → Service accounts → Generate new private key"
          }
        ]
      }
    },
    "ai": {
      "actions": [
        {
          "id": "send-push",
          "description": "Sends one push notification to the audience you pick.",
          "input": {
            "type": "object",
            "properties": {
              "audience": { "type": "string", "enum": ["all", "lapsed", "new"] },
              "title": { "type": "string" },
              "body": { "type": "string" }
            },
            "required": ["audience", "title", "body"]
          },
          "approval": true,
          "reversible": false,
          "scope": "messaging:send",
          "estimatesCost": true
        }
      ]
    }
  },
  "server": { "baseUrl": "https://push-lab.dev" }
}

The command writes this entry. You can hand-edit tappify.extension.json instead — the $schema line gives your editor completion and validation, and tappify extension doctor checks the result. An action id is lowercase letters, digits and dashes, and it is the key your handler registers under. approval is always true; there is no action that runs without one. reversible and scope are what the card tells the owner, and the scope has to be one you also declare under scopes. estimatesCost is declared only: the manifest accepts it and publish validates it, and there is no way to supply an estimate, so no run carries a cost and the card shows none. At most 10 actions. input is bounded like a tool’s: at most 16 KB serialised, and the title and description strings inside it are read by the assistant, scanned at publish, and cut to 400 characters before it sees them.

Asking for a run

From your own UI, tap.actions.run creates the run and returns it. Tappify draws the card; you never do.

import { TapForm, useTap } from "@tappify/extension-sdk";

export default function SendPush() {
  const tap = useTap();

  return (
    <TapForm
      schema={sendPushSchema}
      submitLabel="Ask to send"
      onSubmit={async (values) => {
        const run = await tap.actions.run("send-push", values);
        tap.ui.toast(
          run.status === "pending" ? "Waiting for approval." : "Sent.",
        );
      }}
    />
  );
}

The promise resolves as soon as the run exists. A run Tappify refuses to create rejects instead: with a TapError coded TAP_SCOPE_MISSING when the install was never granted the action’s scope, and otherwise with a TapServerError carrying Tappify’s own code — ACTION_INPUT_INVALID when the input fails your schema, RATE_LIMIT_EXCEEDED when the project has spent its runs for the day. status is pending whenever the owner still has to approve. An owner can only stop being asked for an extension whose granted scopes all sit outside security review, and ai:actions — which every action needs — is one that does not, so an action asks every time.

Handling the run

Your handler is called once, after approval, with the validated input and the owner’s credentials.

import { createTappifyHandler } from "@tappify/extension-sdk/server";

export default createTappifyHandler({
  extensionId: "push-lab",
  actions: {
    "send-push": async (request) => {
      const { firebase_project_id, service_account } = request.credentials;
      const { audience, title, body } = request.input;

      const sent = await sendThroughFirebase({
        projectId: firebase_project_id,
        serviceAccount: JSON.parse(service_account),
        audience,
        notification: { title, body },
      });

      return { sent };
    },
  },
});

A 2xx answer marks the run succeeded and whatever object you returned is stored on it. Anything else marks the run failed and records the status code you answered with, so throw a TapServerError for a failure you want a code and a sentence in your own logs for.

What the card says

Line	Where it comes from
Title and vendor tile	Your action’s id, and your extension’s name
What it does, and where	Your action’s `description` verbatim, then a sentence Tappify writes naming the project and the credentials the owner gave you
The input	One row per field of the input your schema validated
What it needs	The label of the scope your action declares
Whether it can be undone	`Can be undone` or `Cannot be undone`, from your `reversible`

The card has a slot for an Estimated cost line, and it is never drawn: a run’s estimate is always empty, whatever estimatesCost says. Your description is the only line you write. Write it as a sentence an owner can act on: Sends one push notification to the audience you pick., not Executes the send-push operation.

Where a run can start

tap.actions.run, called from your own UI, is what creates a run. Tappify posts it, draws the card, and calls POST /tappify/actions/send-push only once the owner has approved. The extension never sees the decision — it reads the status of the run it asked for and nothing else. The assistant is the other way in, and it stops at the same place. When an owner’s question leads it to one of your actions, it creates the run and the run stays pending: the owner reads the card, and your server is called on their approval, not on the assistant’s request. Nothing the assistant decides reaches you without an owner’s yes in between.

Limits and the record

Two hundred runs a day per project, counted when the run is created, so a run the owner rejects spends one too. Every run is kept with who asked, who approved, the input it was created with and what came back, and owners read their extension’s runs on its page in their workspace. The share of runs owners approve over 90 days is one of the four numbers on your listing: under 60 % the listing is flagged, with the share spelled out as the reason.

Start

Build

Test

Publish

Reference

The push-notification extension

Asking for a run

Handling the run

What the card says

Where a run can start

Limits and the record

​The push-notification extension

​Asking for a run

​Handling the run

​What the card says

​Where a run can start

​Limits and the record

The push-notification extension

Asking for a run

Handling the run

What the card says

Where a run can start

Limits and the record