npm package: @predicate/core
Description: Core utilities for interacting with Predicate API
Author: Predicate Labs
Latest version: 2.2.0

# @predicate/core

[![npm version](https://img.shields.io/npm/v/@predicate/core.svg)](https://www.npmjs.com/package/@predicate/core)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

TypeScript client for interacting with the Predicate API. Handles policy evaluation, authentication, and request validation for any JavaScript/TypeScript environment.

## Installation

```bash
npm install @predicate/core
```

## V1 API Usage

```typescript
import { PredicateClient, PredicateRequest } from '@predicate/core';

const client = new PredicateClient({
    apiUrl: 'https://api.predicate.io/',
    apiKey: process.env.PREDICATE_API_KEY!
});

const request: PredicateRequest = {
    from: '0xSenderAddress',
    to: '0xContractAddress',
    data: '0xEncodedArguments',
    msg_value: '0',
    chain_id: 1 // Optional
};

const result = await client.evaluatePolicy(request);
console.log("Task ID:", result.task_id);
console.log("Signers:", result.signers);
console.log("Signatures:", result.signature);
```

### V1 Response Structure
```typescript
interface PredicateResponse {
  is_compliant: boolean;
  task_id: string;
  expiry_block: number;
  signers: string[];
  signature: string[];
  results?: PredicateSignerResults;
}
```

## V2 API Usage

```typescript
import { PredicateClient, PredicateRequest } from '@predicate/core/v2';

const client = new PredicateClient({
    apiUrl: 'https://api.predicate.io/',
    apiKey: process.env.PREDICATE_API_KEY!
});

const request: PredicateRequest = {
    from: '0xSenderAddress',
    to: '0xContractAddress', 
    data: '0xEncodedArguments',
    msg_value: '0',
    chain: 'ethereum' // Required: 'ethereum' | 'solana' | 'sepolia' | 'holesky' | 'anvil'
};

const result = await client.evaluatePolicy(request);
console.log("Policy ID:", result.policy_id);
console.log("Is Compliant:", result.is_compliant);
console.log("Attestation:", result.attestation);
```

### V2 Response Structure
```typescript
interface PredicateResponse {
  policy_id: string;
  is_compliant: boolean;
  attestation: {
    uuid: string;
    expiration: number;
    attester: string;
    signature: string;
  };
}
```

## Key Differences

| Feature | V1 | V2 |
|---------|----|----|
| **Import** | `@predicate/core` | `@predicate/core/v2` |
| **Endpoint** | `/v1/task` | `/v2/attestation` |
| **Chain Field** | `chain_id?: number \| string` | `chain: SupportedChain` (required) |
| **Response ID** | `task_id` | `attestation.uuid` |
| **Expiry** | `expiry_block` (block number) | `attestation.expiration` (unix seconds) |
| **Signers** | Multiple signers/signatures | Single attester/signature |
| **Policy ID** | Not included | `policy_id` field |

## Migration from V1 to V2

1. **Update import path:**
   ```typescript
   // Before
   import { PredicateClient } from '@predicate/core';
   
   // After  
   import { PredicateClient } from '@predicate/core/v2';
   ```

2. **Add required chain field:**
   ```typescript
   const request = {
     // ... other fields
     chain: 'ethereum' // Now required
   };
   ```

3. **Update response handling:**
   ```typescript
   // V1
   console.log(result.task_id, result.signers);
   
   // V2
   console.log(result.policy_id, result.attestation.uuid, result.attestation.attester);
   ```

## Features

- Policy evaluation and verification
- TypeScript support with full type safety
- Request validation and error handling
- Support for multiple blockchain networks
- Compatible with Node.js, browsers, and edge environments


## Documentation

For detailed documentation, visit [docs.predicate.io](https://docs.predicate.io).

## License

This project is licensed under the MIT License - see the LICENSE file for details.