Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// The shared classifier that decides what a failed recurring charge means.
//
// Before api/_lib/recurring.js existed, both crons treated every failure the
// same way: pause the schedule, write the raw error string, and offer no way
// back. A one-off RPC blip therefore ended a schedule as permanently as a
// revoked delegation. These tests pin the four behaviours that replaced it,
// because each one is a different promise to the person paying:
//
// fatal pause now, the owner has to fix something
// retryable keep the schedule, try again next tick, pause after a bound
// ambiguous never retry, because a retry here can double-charge
// skipped give up this period only, do not hold it against the schedule
//
// plus the platform-outage carve-out, where the fault is ours and no owner
// should have to resume by hand once we fix it.
import { describe, it, expect } from 'vitest';
import {
MAX_CONSECUTIVE_FAILURES,
OUTCOME,
applyChargeFailure,
chargeStatusFor,
classifyChargeFailure,
describePeriod,
formatUnits,
planStatusChange,
sumUnits,
} from '../api/_lib/recurring.js';
const classify = (code, message = '') => classifyChargeFailure({ code, message });
describe('classifyChargeFailure: revoked and expired authority', () => {
it('treats a revoked delegation as fatal, with an actionable reason', () => {
const r = classify('delegation_revoked', 'delegation has been revoked');
expect(r.outcome).toBe(OUTCOME.FATAL);
expect(r.code).toBe('delegation_revoked');
expect(r.reason).toMatch(/revoked/i);
expect(r.reason).toMatch(/grant a new one/i);
});
it('pauses immediately on a fatal failure rather than burning the retry budget', () => {
const applied = applyChargeFailure({ outcome: OUTCOME.FATAL, consecutiveFailures: 0 });
expect(applied).toEqual({ pause: true, retry: false, consecutiveFailures: 1 });
});
it.each(['delegation_expired', 'delegation_not_found', 'delegation_gone'])(
'treats %s as fatal too',
(code) => {
expect(classify(code).outcome).toBe(OUTCOME.FATAL);
},
);
it('treats a scope that no longer covers the charge as fatal, not a retry', () => {
// Retrying a scope_exceeded every hour would just hammer the relayer for
// a period cap that cannot change until the owner signs a wider grant.
const r = classify('scope_exceeded', 'token spend would exceed scope.maxAmount');
expect(r.outcome).toBe(OUTCOME.FATAL);
expect(r.reason).toMatch(/larger than the permission/i);
});
});
describe('classifyChargeFailure: an underfunded wallet', () => {
it('names the insufficient balance behind a generic on-chain revert', () => {
// The relayer reports every revert as rpc_error. A wallet short of USDC
// is the one cause the owner can fix themselves, so it gets its own code.
const r = classify('rpc_error', 'execution reverted: ERC20: transfer amount exceeds balance');
expect(r.code).toBe('insufficient_balance');
expect(r.outcome).toBe(OUTCOME.RETRYABLE);
expect(r.reason).toMatch(/top it up/i);
});
it.each([
'insufficient funds for gas * price + value',
'ERC20InsufficientBalance(0xabc, 0, 5000000)',
'transfer amount exceeds balance',
])('recognises %s', (message) => {
expect(classify('rpc_error', message).code).toBe('insufficient_balance');
});
it('keeps the schedule alive across a top-up window, then pauses', () => {
const outcome = OUTCOME.RETRYABLE;
const first = applyChargeFailure({ outcome, consecutiveFailures: 0 });
expect(first).toEqual({ pause: false, retry: true, consecutiveFailures: 1 });
const last = applyChargeFailure({
outcome,
consecutiveFailures: MAX_CONSECUTIVE_FAILURES - 1,
});
expect(last.pause).toBe(true);
expect(last.retry).toBe(false);
expect(last.consecutiveFailures).toBe(MAX_CONSECUTIVE_FAILURES);
});
});
describe('classifyChargeFailure: a timeout is never retried', () => {
it('classifies a timeout as ambiguous and pauses without retrying', () => {
// The one failure where a retry can charge twice: the request may have
// landed on-chain even though we never saw the response.
const r = classify('timeout', 'onPeriod exceeded 25000ms');
expect(r.outcome).toBe(OUTCOME.AMBIGUOUS);
const applied = applyChargeFailure({ outcome: r.outcome, consecutiveFailures: 0 });
expect(applied.retry).toBe(false);
expect(applied.pause).toBe(true);
expect(chargeStatusFor(r.outcome)).toBe('unknown');
});
it('catches a timeout that only announced itself in the message', () => {
expect(classify('unknown', 'timeout: onPeriod exceeded 25000ms').outcome).toBe(
OUTCOME.AMBIGUOUS,
);
});
});
describe('classifyChargeFailure: a diverged DCA quote skips one period', () => {
it('does not count a skipped period against the schedule', () => {
const r = classify('quote_divergence', 'Quote divergence 91bps exceeds 50bps limit');
expect(r.outcome).toBe(OUTCOME.SKIPPED);
const applied = applyChargeFailure({ outcome: r.outcome, consecutiveFailures: 2 });
expect(applied).toEqual({ pause: false, retry: false, consecutiveFailures: 2 });
});
});
describe('classifyChargeFailure: a platform outage is never the owner problem', () => {
it.each(['feature_disabled', 'unauthorized'])(
'%s retries forever without counting toward the pause bound',
(code) => {
const r = classify(code, 'relayer not enabled on this deployment');
expect(r.platform).toBe(true);
const applied = applyChargeFailure({
outcome: r.outcome,
platform: r.platform,
consecutiveFailures: MAX_CONSECUTIVE_FAILURES + 5,
});
// Mass-pausing every schedule over one operator config gap would be a
// worse outage than the gap, and each would then need a manual resume.
expect(applied.pause).toBe(false);
expect(applied.retry).toBe(true);
expect(applied.consecutiveFailures).toBe(MAX_CONSECUTIVE_FAILURES + 5);
},
);
});
describe('classifyChargeFailure: HTTP statuses and unknown codes', () => {
it('treats a 5xx from the relayer as retryable and a 4xx as our bug', () => {
expect(classify('http_503').outcome).toBe(OUTCOME.RETRYABLE);
expect(classify('http_503').code).toBe('relayer_error');
expect(classify('http_400').outcome).toBe(OUTCOME.FATAL);
expect(classify('http_400').code).toBe('validation_error');
});
it('defaults an unrecognised code to retryable so the bound stops it', () => {
// Unknown-transient recovers on its own; unknown-permanent still stops
// after MAX_CONSECUTIVE_FAILURES instead of retrying forever.
const r = classify('something_new', 'a code nobody has seen');
expect(r.outcome).toBe(OUTCOME.RETRYABLE);
expect(r.code).toBe('something_new');
expect(r.reason).toContain('a code nobody has seen');
});
it('never returns an empty code, even for an empty failure', () => {
expect(classifyChargeFailure({}).code).toBe('unknown');
expect(classifyChargeFailure().code).toBe('unknown');
});
});
describe('chargeStatusFor', () => {
it('maps every outcome to a status the ledger constraint accepts', () => {
const allowed = new Set(['success', 'failed', 'aborted', 'unknown']);
for (const outcome of Object.values(OUTCOME)) {
expect(allowed.has(chargeStatusFor(outcome))).toBe(true);
}
expect(chargeStatusFor(OUTCOME.CHARGED)).toBe('success');
});
});
describe('planStatusChange', () => {
it('allows the two transitions an owner controls', () => {
expect(planStatusChange('pause', 'active')).toEqual({ ok: true, status: 'paused' });
expect(planStatusChange('resume', 'paused')).toEqual({ ok: true, status: 'active' });
});
it('reports a no-op as a conflict rather than pretending it worked', () => {
expect(planStatusChange('pause', 'paused')).toMatchObject({ ok: false, code: 'conflict' });
expect(planStatusChange('resume', 'active')).toMatchObject({ ok: false, code: 'conflict' });
});
it('refuses to reanimate a terminal schedule', () => {
// Cancel is terminal on purpose: restarting means a new schedule, so the
// charge ledger of the old one stays honest.
for (const terminal of ['canceled', 'cancelled', 'expired']) {
expect(planStatusChange('resume', terminal).ok).toBe(false);
expect(planStatusChange('pause', terminal).ok).toBe(false);
}
});
it('rejects an unknown action', () => {
expect(planStatusChange('destroy', 'active')).toMatchObject({
ok: false,
code: 'validation_error',
});
});
});
describe('presentation helpers', () => {
it('names the periods a schedule can run on', () => {
expect(describePeriod(86400)).toBe('daily');
expect(describePeriod(604800)).toBe('weekly');
expect(describePeriod(2592000)).toBe('monthly');
expect(describePeriod(1209600)).toBe('every 2 weeks');
expect(describePeriod(7200)).toBe('every 2 hours');
expect(describePeriod(0)).toBe('unknown');
});
it('renders USDC base units without floating-point drift', () => {
expect(formatUnits('5000000')).toBe('5');
expect(formatUnits('1234567')).toBe('1.234567');
expect(formatUnits('1')).toBe('0.000001');
expect(formatUnits('0')).toBe('0');
expect(formatUnits(null)).toBe('0');
expect(formatUnits('not-a-number')).toBe('0');
});
it('sums base units as integers, so a big ledger cannot lose a cent', () => {
expect(sumUnits(['5000000', '1234567'])).toBe('6234567');
expect(sumUnits(['9007199254740993', '1'])).toBe('9007199254740994');
expect(sumUnits([null, undefined, 'x', '10'])).toBe('10');
expect(sumUnits([])).toBe('0');
});
});