Journey functions

Journey: Functions

Stage 3e of the guided journey. Implement and deploy each function in the plan.

When to use

• Dispatched by journey when current_stage: functions.
• Directly via /butterbase-skills:journey-functions.
• Skipped (annotated (n/a)) if the plan lists no functions.

Preflight

If docs/butterbase/03-preflight.md is missing, older than 24 hours, or 00-state.md has app_id: null, invoke butterbase-skills:journey-preflight first. Wait for it to return successfully before proceeding.

Inputs

• docs/butterbase/02-plan.md — the Functions section.
• docs/butterbase/00-state.md — for app_id.

Procedure

0. Refresh docs. Call butterbase_docs with topic: "functions". For trigger types and ctx shape, also WebFetch https://docs.butterbase.ai/functions. Skip if cache is fresh.

0.5. Check built-in integrations first. Before writing function code that calls an external SaaS for email / messaging / calendar / CRM / payments:

• Email / Slack / etc. → invoke butterbase-skills:integrations. The function should call manage_integrations execute_action rather than installing a third-party SDK.
• Payments → invoke butterbase-skills:payments. The function should use Stripe Connect via manage_billing unless the plan has explicitly chosen a regional gateway.

@butterbase/sdk works server-side too

Inside a function, prefer ctx.db / ctx.storage / ctx.user for the common cases — those are pre-wired and authenticated against the calling user. But for cross-app calls, scripts, or scheduled jobs that operate on multiple apps, instantiate @butterbase/sdk with a service key (bb_sk_) and use the same client surface as the frontend.

Example for a cron function that aggregates from another app:

import { createClient } from '@butterbase/sdk';

export async function handler(_request: Request, ctx: { env: Record<string,string> }) {
  const other = createClient({
    apiUrl: ctx.env.OTHER_APP_API_URL,
    apiKey: ctx.env.OTHER_APP_SERVICE_KEY,
  });
  const { data } = await other.db.from('events').select('*').gte('created_at', ...);
  // ...
  return new Response('ok');
}

For server-side patterns, butterbase_docs topic: "sdk".

Build each function

For each function in the plan, in order:

1. Print: "About to build function: <name> (trigger=<trigger>). Proceed?". Wait for yes.
2. Invoke butterbase-skills:function-dev via the Skill tool with the function spec (name, trigger, behaviour, dependencies) and app_id. The wrapped skill scaffolds the handler, writes tests where appropriate, and calls deploy_function. Reminder it must enforce: handler signature (request, { db, env, user }) and must return new Response(...).
3. Smoke: call invoke_function for HTTP/cron functions and confirm a 2xx + expected body. For WebSocket, defer the smoke to frontend integration.
4. Append one line per function to docs/butterbase/04-build-log.md: <ISO timestamp> functions deploy_function <fn-name> ok
5. After all functions are done, tick - [x] functions in 00-state.md, set current_stage: to the next unchecked stage.
6. Return to journey orchestrator (or ask "Continue to the next stage? (yes/no)").

Outputs

• Deployed functions in the Butterbase app.
• One line per function in 04-build-log.md.

Anti-patterns

• ❌ Letting a handler return a plain object — must be new Response(...).
• ❌ Skipping the smoke invocation. Cron functions in particular are easy to deploy and forget.
• ❌ Forgetting per-function env vars — use manage_function action: update_env.