# Endorser Types

**Created:** 2023-06-30  
**Last Updated:** 2023-06-30  
**Version:** 1.0.0

A shared TypeScript declaration file project that maintains typing structures external to individual applications, enabling type safety and consistency between backend and frontend implementations.

## Overview

This project contains TypeScript declaration files (`.d.ts`) that define shared interfaces and types used across multiple applications in the endorser ecosystem. By maintaining these types externally, we ensure:

- **Type Safety**: Consistent typing between backend and frontend
- **Code Reusability**: Single source of truth for shared data structures
- **Maintainability**: Centralized type definitions that can be updated once
- **Developer Experience**: Better IntelliSense and compile-time error checking

## Structure

### Core Interfaces

The `endorser.d.ts` file contains the following key interfaces:

#### Verifiable Credentials
- **`AgreeVerifiableCredential`**: Represents an agreement on a verifiable credential
- **`GiveVerifiableCredential`**: Represents a "give" action in the endorser system
- **`RegisterVerifiableCredential`**: Represents registration of a verifiable credential

#### Data Structures
- **`GiveServerRecord`**: Server-side record for give operations
- **`GenericClaim`**: Generic claim structure with flexible content
- **`ClaimResult`**: Result structure for claim operations

#### Error Handling
- **`InternalError`**: Standardized error structure for internal operations

## Usage

### Installation

```bash
# If published as an npm package
npm install @your-org/endorser-types

# Or include directly in your project
# Copy endorser.d.ts to your project's types directory
```

### Import and Use

```typescript
import type { 
  GiveVerifiableCredential, 
  GiveServerRecord,
  InternalError 
} from 'endorser-types';

// Use in your application
const giveCredential: GiveVerifiableCredential = {
  "@type": "GiveVerifiableCredential",
  recipient: { identifier: "did:example:123" },
  object: { amountOfThisGood: 100, unitCode: "USD" }
};
```

### Backend Integration

```typescript
// Express.js example
import type { GiveServerRecord, InternalError } from 'endorser-types';

app.post('/give', (req, res) => {
  try {
    const record: GiveServerRecord = {
      agentDid: req.body.agentDid,
      amount: req.body.amount,
      // ... other fields
    };
    // Process the record
  } catch (error) {
    const internalError: InternalError = {
      error: error.message,
      userMessage: "An error occurred processing your request"
    };
    res.status(500).json(internalError);
  }
});
```

### Frontend Integration

```typescript
// React example
import type { GiveVerifiableCredential } from 'endorser-types';

interface GiveFormProps {
  onSubmit: (credential: GiveVerifiableCredential) => void;
}

const GiveForm: React.FC<GiveFormProps> = ({ onSubmit }) => {
  // Form implementation using the shared types
};
```

## Development

### Adding New Types

1. Add new interfaces to `endorser.d.ts`
2. Follow the existing naming conventions
3. Include JSDoc comments for complex types
4. Update this README with new type descriptions

### Type Guidelines

- Use descriptive interface names that clearly indicate their purpose
- Include optional properties where appropriate (marked with `?`)
- Use `Record<string, any>` for flexible object structures
- Maintain backward compatibility when possible
- Follow TypeScript best practices for declaration files

### Versioning

When making breaking changes:
1. Increment the major version number
2. Document migration steps
3. Consider maintaining deprecated types for a transition period

## Security Considerations

- All types are for compile-time checking only
- Runtime validation should still be implemented in consuming applications
- Sensitive data structures should be carefully designed to avoid exposing internal details
- Consider using branded types for sensitive identifiers (DIDs, etc.)

## Contributing

1. Ensure all new types are properly documented
2. Test type compatibility with both backend and frontend projects
3. Update this README when adding new interfaces
4. Follow the existing code style and conventions

## License

[Add your license information here]

## Author

**Matthew Raymer**  
*Initial Development:* 2023-06-30

## File History

| Date | Commit | Description |
|------|--------|-------------|
| 2023-06-30 | db51253 | Initial commit - Core type definitions for endorser system |

---

*This project serves as a foundational type system for the endorser ecosystem, ensuring consistency and type safety across all applications.*