> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actioncodes.org/llms.txt
> Use this file to discover all available pages before exploring further.

# ActionCode

The `ActionCode` class represents an action code in the Action Codes Protocol. It encapsulates all the data and logic for a single action code, including its status, metadata, transaction details, and utility methods for validation and display.

***

## Type Definitions

### ActionCodeStatus

```ts theme={null}
type ActionCodeStatus = 'pending' | 'resolved' | 'finalized' | 'expired' | 'error';
```

Represents the status of an action code.

***

### ActionCodeMetadata

```ts theme={null}
interface ActionCodeMetadata {
  description?: string;
  params?: Record<string, any>;
}
```

Metadata for the action code, including an optional description and parameters.

***

### ActionCodeTransaction

```ts theme={null}
interface ActionCodeTransaction {
  transaction?: string; // Solana: base64 string
  txSignature?: string; // Solana signature
  txType?: string; // Transaction type for categorization
  message?: string; // For sign-only mode: the message to be signed
  signedMessage?: string; // For sign-only mode: the signed message or signature
  intentType?: 'transaction' | 'sign-only'; // Explicit intent type
}
```

Represents transaction or message data attached to an action code.

***

### ActionCodeFields

```ts theme={null}
interface ActionCodeFields {
  code: string;
  prefix: string;
  pubkey: string;
  timestamp: number;
  signature: string;
  chain: string; // e.g., 'solana'
  transaction?: ActionCodeTransaction;
  metadata?: ActionCodeMetadata;
  expiresAt: number;
  status: ActionCodeStatus;
}
```

All fields required to construct an ActionCode instance.

***

## ActionCode Class

### Constructor

```ts theme={null}
new ActionCode(fields: ActionCodeFields)
```

Creates a new ActionCode instance from the provided fields.

***

### Static Methods

#### fromPayload

```ts theme={null}
static fromPayload(input: ActionCodeFields): ActionCode
```

Creates an ActionCode from a plain object. Throws if required fields are missing.

#### fromEncoded

```ts theme={null}
static fromEncoded(encoded: string): ActionCode
```

Creates an ActionCode from a base64-encoded string.

***

### Instance Properties & Methods

#### encoded

```ts theme={null}
get encoded: string
```

Returns a base64-encoded string of the action code fields.

#### isValid

```ts theme={null}
isValid(protocol: ActionCodesProtocol): boolean
```

Checks if the action code is valid for the given protocol (signature, code format, not expired).

#### updateStatus

```ts theme={null}
updateStatus(status: ActionCodeStatus): void
```

Updates the status of the action code.

#### json

```ts theme={null}
get json: ActionCodeFields
```

Returns the raw fields as a plain object.

#### remainingTime

```ts theme={null}
get remainingTime: number
```

Milliseconds remaining until expiration (0 if expired).

#### expired

```ts theme={null}
get expired: boolean
```

Returns true if the code is expired.

#### chain

```ts theme={null}
get chain: string
```

Returns the chain identifier (e.g., 'solana').

#### status

```ts theme={null}
get status: ActionCodeStatus
```

Returns the current status of the action code.

#### code

```ts theme={null}
get code: string
```

Returns the 8-character action code string.

#### prefix

```ts theme={null}
get prefix: string
```

Returns the normalized prefix for the code.

#### pubkey

```ts theme={null}
get pubkey: string
```

Returns the user's public key.

#### transaction

```ts theme={null}
get transaction: ActionCodeTransaction | undefined
```

Returns the transaction data, if any.

#### metadata

```ts theme={null}
get metadata: ActionCodeMetadata | undefined
```

Returns the metadata object, if any.

#### description

```ts theme={null}
get description: string | undefined
```

Returns the human-readable description from metadata.

#### params

```ts theme={null}
get params: Record<string, any> | undefined
```

Returns the parameters from metadata.

#### timestamp

```ts theme={null}
get timestamp: number
```

Returns the timestamp when the code was generated.

#### signature

```ts theme={null}
get signature: string
```

Returns the user's signature string.

#### displayString

```ts theme={null}
get displayString: string
```

Returns a formatted string for display (e.g., "PREFIX-XXXXXX (solana, pending)").

#### remainingTimeString

```ts theme={null}
get remainingTimeString: string
```

Returns a human-readable string for remaining time (e.g., "1m 30s remaining" or "Expired").

#### codeHash

```ts theme={null}
get codeHash: string
```

Returns the code hash (used as code ID in protocol meta).

#### intentType

```ts theme={null}
get intentType: 'transaction' | 'sign-only'
```

Returns the intent type for the action code.

***

## Example

```ts theme={null}
import { ActionCode } from "@actioncodes/protocol";

const fields: ActionCodeFields = {
  code: "ABC12345",
  prefix: "DEFAULT",
  pubkey: "...",
  timestamp: Date.now(),
  signature: "...",
  chain: "solana",
  expiresAt: Date.now() + 60000,
  status: "pending",
};

const actionCode = new ActionCode(fields);
console.log(actionCode.displayString); // e.g., "ABC12345 (solana, pending)"
```

***