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

1. 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');
}