Skip to content

Support Proposals

View raw .md

How the support AI records a billing change a customer asked for, such as extending a trial, so that a staff member approves or rejects it in the admin panel.

On this page

Quick Reference#

php
// config/magic-starter.php
'features' => [
    Features::support(),
    Features::billing(),
    Features::supportProposals(),
],
Item Value
Tool propose_billing_change, registered by your code through SupportToolRegistry.
Actions extend_trial, cancel_at_period_end and resume.
Expiry support.proposals.expires_hours, 72 by default.
Trial cap support.proposals.max_trial_extension_days, 14 by default.
Who asks The account owner only.
Who decides Staff the admin panel clears for billing.

Introduction#

A customer who writes "please give me a few more days on my trial" wants a change to their subscription. The support AI must not make that change: a model that can charge, cancel or extend on a customer's word is a model an attacker can talk into it. Support proposals split the work in three:

  1. The AI records the request. propose_billing_change writes a row and changes nothing else.
  2. A staff member approves or rejects it in the admin panel, after reading the customer's own words.
  3. The package executes it on approval, through the same billing contract the operator's panel actions use, with the staff member as the actor.

A proposal is a support tool that writes. Tools never execute: the one write it makes is a row for a person to read, and only that person's approval changes the subscription.

Feature: Features::supportProposals(). It needs Features::support() and the billing features as well, because the billing features supply the owner gate (see Who May Ask and Who May Decide). Listing support-proposals alone turns nothing on.


Enabling#

php
// config/magic-starter.php
'features' => [
    Features::support(),
    Features::billing(),
    Features::supportProposals(),
],

Publish the migration, create_support_proposals_table.php, with the rest of the support migrations and run it:

bash
php artisan magic-starter:install --features=support
php artisan migrate

The table is part of the support migration list, so a host that installed support earlier runs the same command again: a migration already published is skipped and only the new one is added. Proposals point at conversations, messages and users, so when you copy the file by hand, stamp it after theirs.

Two keys bound the feature, under support.proposals:

Key Default Env Meaning
expires_hours 72 MAGIC_STARTER_SUPPORT_PROPOSALS_EXPIRES_HOURS How long a request can be approved after it is recorded
max_trial_extension_days 14 MAGIC_STARTER_SUPPORT_PROPOSALS_MAX_TRIAL_DAYS The most days one request may move a trial end

Registering the Tool#

The package ships the tool and never registers it: the tool registry is empty until your code fills it, and your SDK adapter decides what the model is offered. Register ProposeBillingChangeTool in a service provider's boot():

php
namespace App\Providers;

use AnilcanCakir\MagicStarter\Support\SupportAi\Tools\ProposeBillingChangeTool;
use AnilcanCakir\MagicStarter\Support\SupportAi\Tools\SupportToolRegistry;
use Illuminate\Support\ServiceProvider;

class SupportToolServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        if (config('services.support.proposals')) {
            app(SupportToolRegistry::class)->register(ProposeBillingChangeTool::class);
        }
    }
}

Put the registration behind a switch in your host that defaults to off, as above. A model that can ask for a billing change deserves a staged rollout: turn it on for one environment, read the first proposals in the panel, then widen it. With the switch off the model is never offered the tool, whatever the feature flag says.

The tool is named propose_billing_change and takes three arguments:

Argument Meaning
action extend_trial, cancel_at_period_end or resume
until A calendar day, YYYY-MM-DD, for extend_trial only
reason Why the customer asked, in the model's words, at most 500 characters

The account and the owner check come from the conversation, never from an argument. The model names what to ask for, not for whom.


The Three Actions#

Action Runs on approval Recorded only when
extend_trial AdministersBilling::extendTrial() The subscription is on a trial that is not cancelled, and until is a real day after the current trial end and at most max_trial_extension_days past it
cancel_at_period_end AdministersBilling::cancel() The subscription is active and not already cancelled
resume AdministersBilling::resume() The subscription is cancelled and still inside its period

The tool checks these before it writes, with the predicates the operator's own actions apply, so staff are never shown a request that approval would refuse on sight. Every refusal is a sentence addressed to the model ("The subscription is not on a trial, so there is nothing to extend."), which it relays to the customer. A request is also refused for a visitor without an account, a conversation without a billing account, an account without a Stripe subscription, a malformed date, and one that is already waiting: a conversation holds at most one pending request per action.


Lifecycle#

Status Meaning
draft Written during an AI turn, hidden from staff
pending The turn that wrote it was stored; staff may decide until expires_at
executing An approval claimed it and is calling billing; the outcome is not yet known
approved The change ran, or staff confirmed by hand that it applied
failed The change was refused, or the request no longer held at approval
rejected A staff member declined it
expired The deadline passed with no decision, found by an approval or a rejection

A draft stays hidden because the customer has not read the answer that announces it. When RespondToSupportConversation stores the turn, it promotes that turn's drafts to pending and sends staff a SupportConversationNeedsStaff alert with the reason proposal. A turn that also hands the conversation to staff sends one alert only, the handoff one, because staff open that thread anyway and find the request on it. A turn that fails or is superseded never lands, so its draft stays hidden and never blocks a new request: a retried turn finds its own row by trigger message and action. While that row is still a draft, the retry's parameters and reason replace the earlier ones, so the latest call wins; once it is pending or later, staff may be reading it and it is left as it is. Either way the tool answers with what is stored, such as Recorded: extend the trial to 2026-10-27., so the AI never promises a day staff will not see. A new request for an action is refused while another one for it is pending before its deadline or executing.

Approval reads the world again under a row lock instead of trusting the snapshot taken at recording. It moves a proposal to failed, with the reason on the row, when:

  • the conversation has no billing account any more (no_billable), or the account is another one than the request named (billable_changed);
  • the customer who asked is no longer the account owner (owner_changed);
  • an extend_trial day no longer fits the trial as it stands (params_stale).

A proposal found past expires_at is set to expired and not run. A rejection of such a proposal does the same: it is set to expired and the customer is not told it was declined.


Who May Ask and Who May Decide#

The owner gate. Only the account owner asks. The tool resolves the billing account from the conversation, then asks Gate::forUser($opener)->allows('manageBilling', $billable), the gate the billing endpoints apply. That gate belongs to the billing features, which is why support-proposals needs them. A member of a team who is not its owner gets a sentence telling them to write in from the owner's account. Approval asks the gate again, so an owner who was replaced between the request and the decision fails the proposal.

The billing staff gate. Only a staff member the admin panel clears for billing decides. DecidesSupportProposals requires a FilamentUser that can access the panel it is given and passes BillingAuthorization::allows($staff, $panel) for that same panel, so the plugin rule of the panel the decision is made in applies even when no panel is current, as in a queued job or a test: an empty magic-starter.admin.billing_emails lets every panel admin through, a non-empty one admits only the addresses it lists, and an authorizeBillingUsing() callback on the plugin replaces both. The decision buttons are hidden from everyone else, and the contract re-checks on its own, so a crafted Livewire call is refused.

DecidesSupportProposals is bound only where Filament is installed.


Ordering Guarantee#

Stripe has no rollback. A charge or a trial change that already happened stays, whatever the database does afterwards. So approval is ordered to keep the database from lying about it:

  1. In one short transaction, under a row lock, it re-checks the request and claims the row as executing. A second approval finds the row no longer pending and stops.
  2. With no database transaction open, it calls AdministersBilling. The Stripe call and the billing_events rows it writes commit on their own.
  3. In a second short transaction it re-reads the row under its lock and, only while it is still executing, writes approved and posts the customer's line. If another staff member marked it applied or failed while billing ran, that decision stands and no second line is posted.

Two outcomes follow:

  • A BillingAdministrationRefused (the subscription is no longer on a trial, Stripe rejected the call) leaves the row failed with the refusal's reason.
  • A rail_error refusal caused by a Stripe connection failure (Stripe\Exception\ApiConnectionException: a timeout, a dropped connection) is the exception: the request may have reached Stripe and applied, so the row stays executing, the customer is told nothing, and the refusal still reaches the panel.
  • Any other fault, such as a process killed mid-call, leaves the row executing. That status means the outcome is unknown. Open the account's billing events and check whether the change applied: use Mark applied with a reason if it did, which sets approved and tells the customer, or Mark failed with a reason if it did not, which tells the customer nothing. Either one records you as the final decider. Never approve twice by other means: the claim exists so that a second approval cannot charge again, and neither mark calls billing.

What Staff See#

A "Billing requests" tab on the support conversation page, shown only while the feature is on. It lists every proposal that is not a draft: the action, its parameters, the status, the requester, and when it was created and expires. Below the lg breakpoint only the action and the status stay, and the status notes a request whose deadline passed; the rest is in the request's details.

The details of a request carry what a staff member needs to decide:

  • the customer's own words, from the message that triggered it;
  • the AI's rationale;
  • for a trial extension, the current trial end and how many times the account's trial was already extended;
  • how many customer messages arrived since the request, which may have changed or withdrawn it.

The customer's words and the rationale are untrusted text. They are shown as escaped plain text, never HTML or Markdown, and labelled unverified: the rationale is the model's reading of the customer, not a fact.

Each row's actions sit in one menu, so they are reached without scrolling the table sideways. The menu offers Details on every row, Approve and Reject (with a reason) on a pending request before its deadline, and Mark applied and Mark failed (each with a reason) on an executing one. Each decision is audited as support.proposal_approved, support.proposal_rejected, support.proposal_marked_applied or support.proposal_marked_failed.


What the Customer Sees#

The customer never sees a proposal row. The AI tells them in its answer that a person will review the request, and the thread then gets a system activity line in the conversation's language, not the staff member's:

Outcome Line
Approved, or marked applied A teammate approved your request: Extend the trial.
Rejected A teammate declined your request: Extend the trial.
Billing refused the change We could not apply your request (Extend the trial). A teammate will follow up here.

The thread refreshes through SupportConversationUpdated. A request that fails the re-check at approval, an expired request, an approval left executing and a Mark failed post no line, because nothing was decided that the customer can act on; staff follow up in the thread.

Gotchas#

Mistake Fix
Listing support-proposals alone It needs support and the billing features as well; listed alone it turns nothing on.
Expecting the package to register the tool It never does. Register ProposeBillingChangeTool yourself, behind a switch that defaults to off.
Reading an executing row as in progress After a crash it means the outcome is unknown. Check the account's billing events, then use Mark applied or Mark failed with a reason.
Calling DecidesSupportProposals::approve() inside a database transaction It refuses, because a rollback would hide a billing call that already happened.
Waiting for a customer's "cancel" to reach the model The handoff classifier hands billing words to staff first, so such a message never reaches the model.
Letting a team member who is not the owner ask Only the account owner may ask; others get a sentence pointing them to the owner.
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.