Capabilities
Define an action with its input, permission check, optional approval, and function.
A capability describes one action your app can perform.
const refundPayment = capability({
name: "payments.refund",
input: RefundInput,
authorize: ({ principalId, input }) => canRefund(principalId, input),
approval: ({ input }) => input.amount >= 1_000,
execute: (input, context) => refundThroughProvider(input, context),
});
Call order
kaji.execute() always runs these steps in order:
- Validate the input.
- Check whether this request was already made (see Idempotency).
- Run
authorize. - Ask for approval, if the capability needs it.
- Run
execute. - Save the result.
If a step stops the request, the later steps do not run.
Name
A non-empty string that identifies the action, such as "payments.refund". Keep it stable: it is part of how Kaji recognizes repeat requests, so renaming it means old retries no longer match.
Input
A Standard Schema V1 schema: Zod, Valibot, ArkType, or an object with a ~standard property that has version: 1 and a validate function. authorize, approval, and execute receive the validated result, never the raw input.
If validation fails, kaji.execute() rejects with an InvalidInputError whose issues property holds the schema’s issues. Nothing else runs.
Authorize
Required. Receives principalId and the validated input, and returns true or false (or a promise of either). Only true lets the request continue. Anything else gives a denied result and execute does not run: false, a thrown error, or any other value, such as undefined from a missing return.
Kaji does not log users in. Set principalId from your own session or auth check, and never from untrusted request data.
await kaji.execute(deleteProject, {
input: { projectId: "project_123" },
principalId: session.userId,
idempotencyKey: request.idempotencyKey,
});
Approval
Optional. A function that returns true when this request needs approval and false when it does not. It receives the same principalId and input as authorize, and must return synchronously.
Approval is skipped only when the function returns exactly false. Any other value, including a promise from an async function, requires approval. If the function throws, Kaji returns rejected.
When it returns true, Kaji calls the approve function you passed to createKaji():
const kaji = createKaji({
store,
approve: async ({ capability, principalId, input, idempotencyKey }) => {
return approvalService.request({ capability, principalId, input, idempotencyKey });
},
});
approve returns { approved: boolean, evidence?: unknown }. Only { approved: true } lets the action run. Anything else gives a rejected result: no approve function, an invalid return value, approved: false, or a thrown error. Kaji does not save evidence, so keep any approval record in your own system.
authorize runs first, so an unauthorized request never reaches approve.
Execute
Receives the validated input and a context:
type ExecutionContext = {
readonly principalId: string;
readonly idempotencyKey: string;
readonly signal: AbortSignal;
};
Pass context.idempotencyKey to your provider if it supports one, and pass context.signal to anything that can be cancelled.
Returning gives succeeded. Throwing gives unknown, because the side effect may already have happened. Throw knownFailure(cause) only when you know it did not (see Outcomes).