# API reference

Every function and type exported by `@hiyorios/kaji`.

```ts
import {
  capability,
  createKaji,
  knownFailure,
  memoryStore,
  type Capability,
  type ClaimResult,
  type ExecutionClaim,
  type ExecutionContext,
  type ExecutionEvidence,
  type ExecutionRequest,
  type ExecutionResult,
  type ExecutionStore,
  type StoredExecution,
} from "@hiyorios/kaji";
```

## `capability()`

Defines one action. See [Capabilities](/docs/concepts/capability).

```ts
function capability<Schema extends StandardSchemaV1, Result>(definition: {
  readonly name: string;
  readonly input: Schema;
  readonly authorize: (request: {
    readonly principalId: string;
    readonly input: SchemaOutput<Schema>;
  }) => boolean | Promise<boolean>;
  readonly approval?: (request: {
    readonly principalId: string;
    readonly input: SchemaOutput<Schema>;
  }) => boolean;
  readonly execute: (
    input: SchemaOutput<Schema>,
    context: ExecutionContext,
  ) => Result | Promise<Result>;
}): Capability<SchemaOutput<Schema>, Result>;
```

`input` is a [Standard Schema](https://standardschema.dev) V1 schema. `capability()` throws right away if `name`, `authorize`, or `input` is missing or invalid. `StandardSchemaV1` and `SchemaOutput` are not exported, so you never import them.

## `createKaji()`

Creates a Kaji instance. See [Stores](/docs/concepts/stores) and [Cancellation](/docs/concepts/cancellation).

```ts
function createKaji(options: {
  readonly store: ExecutionStore;
  readonly approve?: (request: {
    readonly capability: string;
    readonly principalId: string;
    readonly input: unknown;
    readonly idempotencyKey: string;
  }) =>
    | { readonly approved: boolean; readonly evidence?: unknown }
    | Promise<{ readonly approved: boolean; readonly evidence?: unknown }>;
  readonly timeoutMs?: number;
}): {
  execute<Output, Result>(
    capability: Capability<Output, Result>,
    request: ExecutionRequest,
  ): Promise<ExecutionResult<Result>>;
};
```

## `ExecutionRequest`

```ts
type ExecutionRequest = {
  readonly input: unknown;
  readonly principalId: string; // non-empty
  readonly idempotencyKey: string; // non-empty
  readonly signal?: AbortSignal;
};
```

## `ExecutionContext`

Passed to `execute`.

```ts
type ExecutionContext = {
  readonly principalId: string;
  readonly idempotencyKey: string;
  readonly signal: AbortSignal;
};
```

## `ExecutionResult`

```ts
type ExecutionResult<Result> =
  | {
      readonly status: "succeeded";
      readonly result: Result;
      readonly evidence: ExecutionEvidence;
    }
  | {
      readonly status: "denied" | "rejected" | "failed" | "cancelled";
      readonly error: unknown;
      readonly evidence: ExecutionEvidence;
    }
  | {
      readonly status: "unknown";
      readonly error: unknown;
      readonly evidence: ExecutionEvidence;
    };
```

See [Outcomes](/docs/concepts/outcomes).

## `ExecutionEvidence`

```ts
type ExecutionEvidence = {
  readonly executionId: string;
  readonly capability: string;
  readonly principalId: string;
  readonly idempotencyKey: string;
  readonly inputFingerprint: string;
};
```

The IDs Kaji knows about a request, useful for looking it up later. If a request is cancelled before Kaji claims it, `executionId` and `inputFingerprint` are empty. If a call stops waiting for an identical request already in progress, `executionId` is empty.

## `InvalidInputError`

`kaji.execute()` rejects with this error when input fails validation. It is not exported. Check `error.name === "InvalidInputError"`.

```ts
class InvalidInputError extends Error {
  readonly issues: ReadonlyArray<{
    readonly message: string;
    readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>;
  }>;
}
```

`issues` holds the schema's own issues, unchanged.

## `knownFailure()`

```ts
function knownFailure(cause: unknown): Error;
```

Throw it from `execute` when you know the action did not take effect. Kaji returns `failed`.

## Store types

See [Stores](/docs/concepts/stores) for how these fit together.

```ts
type ExecutionStore = {
  claim(claim: ExecutionClaim): Promise<ClaimResult>;
  record(execution: StoredExecution): Promise<void>;
};

type ExecutionClaim = {
  readonly capability: string;
  readonly principalId: string;
  readonly idempotencyKey: string;
  readonly inputFingerprint: string;
};

type ClaimResult =
  | { readonly status: "claimed"; readonly executionId: string }
  | { readonly status: "existing"; readonly outcome: Promise<StoredExecution> }
  | { readonly status: "conflict"; readonly executionId: string };

type StoredExecution = ExecutionResult<unknown>;
```

## `memoryStore()`

```ts
function memoryStore(): ExecutionStore;
```

An in-memory store for development and tests. It works in one process and keeps nothing after restart.

## `Capability`

```ts
type Capability<Output, Result> = { readonly name: string };
```

The returned object only exposes `name`. The type parameters let `kaji.execute()` check your input and result types.