Creating Apps

import { createApp } from 'start/app'

export default createApp({
  id: 'my-app',
  name: 'My App',
  description: 'What the app does',
  version: '0.0.1',
  icon: './icon.svg',
  theme: 'blue',

  actions: {
    query: {
      description: 'the generic query action',
      async run({ input, tools, context }) {
        return `you said: ${input.instruction}`
      },
    },
  },
})

export default createApp({
  id: 'my-app',
  // ...
  options: {
    repos: 'string',
    interval: 'number',
    apiKey: 'secret',
  },
  optionsDefaults: {
    interval: 30,
  },
  optionsDescriptions: {
    repos: 'Comma-separated list of owner/repo to sync',
    interval: 'Sync interval in minutes',
  },
  optionsRequired: {
    repos: true,
  },
})

async run({ options, tools }) {
  const repos = options.repos.split(',')
}

export default createApp({
  id: 'my-app',
  // ...
  api: {
    base: 'https://api.example.com/v1',
    auth: 'bearer',
    docs: `
      GET /items - list all items
      GET /items/:id - get a single item
      POST /items - create an item (body: { name, description })
    `,
  },
})

export default createApp({
  id: 'my-app',
  // ...
  helpers: {
    formatCurrency: '(cents) => `$${(cents / 100).toFixed(2)}`',
    toUnixTs: '(dateStr) => Math.floor(new Date(dateStr).getTime() / 1000)',
  },
})

actions: {
  sync: {
    description: 'Sync issues from the configured repos',
    noun: 'issues',
    messageFormat: '[repo]',
    requiresInput: true,
    async run({ input, context, options, tools }) {
      // ...
      return { summary: 'synced 42 issues', count: 42 }
    },
  },
}

actions: {
  // strategy-driven: AI figures out how to query the API
  query: {
    description: 'look up information from the service',
  },

  // imperative: you write the exact logic
  sync: {
    description: 'sync all data from the configured repos',
    async run({ options, tools }) {
      const data = await fetch(`https://api.example.com/repos/${options.repo}`)
      // ...
    },
  },
}

actions: {
  payments: {
    description: 'look up payment and revenue data',
    synonyms: ['revenue', 'transactions', 'charges', 'sales'],
  },
}

type AppActionInput = {
  instruction: string // NLP text after /app action — the user's instruction
  summary: string // previous step's summary output
  data: AppResultDataItem[] // structured pipeline data from previous steps
}

type AppActionContext = {
  serverId: string
  channelId?: string
  threadId?: string
  object: Record<string, unknown> // accumulated cross-step context
}

// simple string
return 'done'

// structured result with data items
return {
  summary: '25 payments totaling $3,420',
  data: [
    {
      type: 'payment',
      key: 'stripe-payment:ch_abc',
      value: { amount: 420, email: 'alice@co.com', status: 'succeeded' },
      title: 'alice@co.com - $420',
      status: 'succeeded',
      url: 'https://dashboard.stripe.com/payments/ch_abc',
    },
  ],
  revenue: 3420, // extra fields passed to next pipeline step
}

actions: {
  query: {
    description: 'generic natural-language entrypoint for this app',
    async run({ input, tools }) {
      return input.instruction
    },
  },
}

// set a value with metadata
await tools.data.public.set('customer:123', JSON.stringify(customer), {
  title: customer.name,
  kind: 'customer',
  status: 'active',
  tags: ['enterprise'],
  url: 'https://example.com/customer/123',
})

// get a single value
const item = await tools.data.public.get('customer:123')
// returns: { key, value, title, kind, status, tags, ... }

// query with filters
const active = await tools.data.public.getAll({
  kind: 'customer',
  status: 'active',
  sort: 'newest',
  limit: 50,
})

// delete
await tools.data.public.delete('customer:123')

await tools.data.public.stat('daily-summary', {
  openIssues: 12,
  closedToday: 3,
})

await tools.data.public.series(
  'response-time',
  { value: 230 },
  {
    period: 'hourly', // 'hourly' | 'daily' | 'weekly' | 'monthly'
  },
)

await tools.message.insert({
  content: 'deployment succeeded',
  channelId: context.channelId,
  serverId: context.serverId,
  threadId: context.threadId, // optional, replies in a thread
})

await tools.message.react({
  messageId: 'msg_abc',
  emoji: 'thumbsup', // emoji keyword or unicode value
})

const result = await tools.message.pin({
  messageId: 'msg_abc',
  channelId: context.channelId,
  serverId: context.serverId,
})
// result: { pinned: true } or { pinned: false }

// in-app notification (info by default)
tools.notify('sync completed')
tools.notify('rate limit hit', 'warn')
tools.notify('sync failed', 'error')

// by user ID or @username
await tools.notify.push('user-id-or-@username', 'you have a new assignment')

// with title and body
await tools.notify.push('@alice', {
  title: 'Deploy Complete',
  body: 'v2.1.0 is live on production',
})

// generate text
const summary = await tools.generate.text('md', `Summarize: ${text}`)

// generate structured JSON
const entities = await tools.generate.object(
  'sm',
  `Extract people and places from: ${text}`,
  { people: ['string'], places: ['string'] },
)

const data = await tools.data.private.get('api-key')
if (!data) {
  tools.abort('no API key configured')
}

tools.progress(0)
for (let i = 0; i < items.length; i++) {
  await processItem(items[i])
  tools.progress(Math.round(((i + 1) / items.length) * 100))
}

// create a flow from pipedown syntax
const { id } = await tools.flows.create(`
  every 1 hour
  /github sync
  /notify push sync complete
`)

// delete a flow (only flows created by this app)
await tools.flows.delete(id)

const slug = tools.helpers.slugify('Hello World') // 'hello-world'
const id = tools.helpers.randomId() // random unique string

// sign a JWT (RS256)
const token = await tools.crypto.signJWT(
  { iss: 'my-app', sub: 'user-123' },
  privateKeyPEM,
  { expiresIn: '10m' },
)

// base64url encode
const encoded = tools.crypto.base64url('hello')

// extract a structured object from input
const params = await tools.strategy.object({
  task: 'parse stripe query into a relative period type',
  schema: { period: '"today"|"week"|"month"', n: '?number' },
})
// → { period: "week" }

// extract an array of items
const steps = await tools.strategy.list({
  task: 'break deployment plan into ordered steps',
  schema: { name: 'string', command: 'string' },
})
// → [{ name: "build", command: "npm run build" }, ...]

// map raw API data to standardized data items
const result = await tools.strategy.data({
  data: rawStripeResponse,
  task: 'stripe payments this week',
  fields: ['amount', 'customer_email', 'status'],
})
// → { summary: "Found 25 payments...", items: AppResultDataItem[], count: 25 }
return { summary: result.summary, data: result.items }

// BAD — timestamps get cached, stale on next run
const parsed = await tools.strategy.object({
  task: `Parse: "today"\nCurrent time: ${new Date().toISOString()}`,
  schema: { created: { gte: 'unix_ts', lte: 'unix_ts' } },
})

// GOOD — relative type is cached, resolved at runtime
const parsed = await tools.strategy.object({
  task: `Parse: "today" into a relative period type`,
  schema: { relative: '"today"|"yesterday"|"last-n-days"', n: '?number' },
})
const params = resolveAtRuntime(parsed, new Date())

await tools.files.write('config.json', JSON.stringify(config))
await tools.files.writeJSON('config.json', { key: 'value' })
const content = await tools.files.read('config.json')
const data = await tools.files.readJSON('config.json')
const exists = await tools.files.exists('config.json')
const files = await tools.files.list('/', {
  recursive: true,
  pattern: '*.json',
})
await tools.files.delete('config.json')
const abs = tools.files.resolve('config.json')

export default createApp({
  id: 'my-github-app',
  // ...
  oauth: {
    provider: 'github', // 'github' | 'stripe' | 'linear' | 'google'
    scope: ['user:email', 'public_repo'],
  },

  async onAuthSuccess({ tools, oauthToken }) {
    // runs once after successful OAuth — good for one-time setup
    // like storing initial config or validating the connection
    if (!oauthToken) return

    const res = await fetch('https://api.example.com/me', {
      headers: { Authorization: `Bearer ${oauthToken}` },
    })
    const user = await res.json()
    await tools.data.private.set('account', JSON.stringify(user))
  },
})

async run({ oauthToken, tools }) {
  const res = await fetch('https://api.example.com/me', {
    headers: { Authorization: `Bearer ${oauthToken}` },
  })
}

export default createApp({
  id: 'my-app',
  // ...
  events: {
    deploy: {
      description: 'deployment completed',
      payload: {
        status: 'success | failure',
        environment: 'string',
        url: '?string',
      },
      entity: 'deployment',
    },
  },

  async onWebhook({ context, payload, tools, options }) {
    const { headers, ...body } = payload

    await tools.message.insert({
      content: `deploy to ${body.environment}: ${body.status}`,
      channelId: context.channelId,
      serverId: context.serverId,
    })

    return {
      event: 'deploy', // matches a key in events
      summary: 'deployment received', // displayed as message
      data: [
        {
          type: 'deployment',
          key: `deploy:${body.environment}`,
          value: body,
          title: `${body.environment} deploy`,
          status: body.status,
        },
      ],
    }
  },
})

outputs: {
  issue: {
    title: 'string',
    number: 'number',
    state: 'string',
    assignee: '?string',
  },
  deployment: {
    url: 'string',
    status: 'string',
    environment: 'string',
  },
},

suggestedFlowsAndBlocks: [
  {
    explanation: 'Keeps issue data fresh every hour.',
    flow: `
# Sync Issues
Sync issues into app data every hour.

every hour

/github sync
    `.trim(),
  },
],

suggestedFlowsAndBlocks: [
  {
    explanation: 'Shows open issue count in a dedicated thread.',
    block:
      '<Number query="app:github category:issue state:open" extract="value" label="Open Issues" />',
  },
],

export default createApp({
  id: 'my-app',
  // ...
  frontend({ options, tools }) {
    return (
      <YStack p="$4" gap="$2">
        <SizableText>Configured repos: {options.repos}</SizableText>
      </YStack>
    )
  },
})

frontend(props: { options?: ParsedOptions; tools: AppTools }): ReactNode

import { createApp } from 'start/app'

export default createApp({
  id: 'uptime',
  name: 'Uptime',
  description: 'Monitor endpoint health and alert on downtime',
  version: '0.0.1',
  icon: 'Activity',
  theme: 'green',

  options: {
    urls: 'string',
  },
  optionsDescriptions: {
    urls: 'Comma-separated URLs to monitor',
  },
  optionsRequired: {
    urls: true,
  },

  events: {
    down: {
      description: 'an endpoint went down',
      payload: { url: 'string', status: 'number', error: '?string' },
    },
  },

  outputs: {
    health: {
      url: 'string',
      status: 'number',
      latency: 'number',
      ok: 'boolean',
    },
  },

  actions: {
    check: {
      description: 'Check health of all configured endpoints',
      noun: 'health report',
      async run({ options, tools, context }) {
        const urls = options.urls.split(',').map((u) => u.trim())
        const results = []

        for (const url of urls) {
          const start = Date.now()
          try {
            const res = await fetch(url, { method: 'HEAD' })
            const latency = Date.now() - start
            results.push({ url, status: res.status, latency, ok: res.ok })

            await tools.data.public.set(
              `health:${url}`,
              JSON.stringify({
                url,
                status: res.status,
                latency,
                ok: res.ok,
              }),
              {
                title: url,
                kind: 'health',
                status: res.ok ? 'up' : 'down',
              },
            )

            if (!res.ok) {
              await tools.notify.push('@admin', {
                title: 'Endpoint Down',
                body: `${url} returned ${res.status}`,
              })
            }
          } catch (err) {
            results.push({
              url,
              status: 0,
              latency: 0,
              ok: false,
              error: err.message,
            })
            await tools.data.public.set(
              `health:${url}`,
              JSON.stringify({
                url,
                status: 0,
                latency: 0,
                ok: false,
              }),
              {
                title: url,
                kind: 'health',
                status: 'down',
              },
            )
          }
        }

        const down = results.filter((r) => !r.ok)
        return {
          summary: down.length
            ? `${down.length} endpoint(s) down: ${down.map((d) => d.url).join(', ')}`
            : `all ${results.length} endpoints healthy`,
          data: results.map((r) => ({
            type: 'health',
            key: `health:${r.url}`,
            value: r,
            title: r.url,
            status: r.ok ? 'up' : 'down',
          })),
        }
      },
    },
  },

  suggestedFlowsAndBlocks: [
    {
      explanation: 'Runs health checks every 5 minutes.',
      flow: `
# Health Check
Check configured endpoints every 5 minutes.

every 5 minutes

/uptime check
      `.trim(),
    },
  ],
})

start app init my-app        # create the project
cd my-app
# edit app.tsx...
start app build               # compile to .app.json

start app publish             # build + publish to npm + register

start app submit my-app       # submit for review