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

# 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

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

// 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

// 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.