Inbox API

import { User } from 'lua-cli';

const receipt = await User.Inbox.push({
  title: 'Approve the Q3 renewal quote',
  body: 'Northstar Ltd renewal is ready to send at $48,000.',
  actions: ['approve'],
  key: 'northstar-q3-renewal',
});

// { outcome: 'deposited', kind: 'input_request', key: 'northstar-q3-renewal' }

const receipt = await User.Inbox.push(input);

// Monday — file the card
await User.Inbox.push({
  key: 'weekly-pipeline-review',
  title: 'Pipeline review ready',
  body: '12 deals need a status update.',
});

// Tuesday — same key, new numbers: the existing card updates
await User.Inbox.push({
  key: 'weekly-pipeline-review',
  title: 'Pipeline review ready',
  body: '9 deals need a status update.',
});
// → { outcome: 'updated', kind: 'agent_notice', key: 'weekly-pipeline-review' }

try {
  await User.Inbox.push({ title, body, actions: ['fix'], connection });
} catch (error: any) {
  if (error.code === 'invalid_input') {
    // Fix the payload — retrying unchanged will fail the same way
  }
  throw error;
}

import { LuaTool, User } from 'lua-cli';
import { z } from 'zod';

export class RequestRefundApproval implements LuaTool {
  name = 'request_refund_approval';
  description = 'Ask the account owner to approve a refund above the auto-approve threshold';

  inputSchema = z.object({
    orderId: z.string(),
    amount: z.number(),
  });

  async execute({ orderId, amount }: z.infer<typeof this.inputSchema>) {
    const receipt = await User.Inbox.push({
      title: `Approve a $${amount} refund`,
      body: `Order ${orderId} is above the auto-approve limit and needs a decision.`,
      detail: 'Approving issues the refund immediately and emails the customer.',
      options: [
        { label: 'Approve refund', description: 'Issue it now' },
        { label: 'Decline', description: 'Keep the order as is' },
      ],
      key: `refund-approval:${orderId}`,
      priority: 'high',
    });

    if (receipt.outcome === 'capped') {
      return 'Could not file the approval today — the daily inbox limit was reached.';
    }

    return `Approval requested. You'll be asked in your inbox.`;
  }
}

import { Jobs, User } from 'lua-cli';

await Jobs.create({
  name: 'nightly-digest',
  schedule: { type: 'cron', expression: '0 6 * * *' },
  execute: async () => {
    const summary = await buildDigest();

    await User.Inbox.push({
      title: 'Nightly digest ready',
      body: `${summary.count} items processed overnight.`,
      detail: summary.text,
      deeplink: summary.url,
      key: 'nightly-digest',
    });
  },
});

const receipt = await User.Inbox.push({
  title: 'Reconnect Google Calendar',
  body: "I can't read your availability — the calendar connection expired.",
  actions: ['fix'],
  connection: { type: 'google-calendar', name: 'Google Calendar' },
  key: 'calendar-reconnect',
});
// → { outcome: 'deposited', kind: 'connection_fix', key: 'calendar-reconnect' }

import { User } from 'lua-cli';

type InboxPushInput = Parameters<typeof User.Inbox.push>[0];
type InboxPushReceipt = Awaited<ReturnType<typeof User.Inbox.push>>;

async function notify(input: InboxPushInput): Promise<InboxPushReceipt> {
  return User.Inbox.push(input);
}