diff --git a/README.md b/README.md index ae76eef..b8c4d20 100644 --- a/README.md +++ b/README.md @@ -1 +1,160 @@ -# endorser-types \ No newline at end of file +# 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 = ({ 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` 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.* \ No newline at end of file diff --git a/endorser.d.ts b/endorser.d.ts index 24b167f..4bf790b 100644 --- a/endorser.d.ts +++ b/endorser.d.ts @@ -1,57 +1,218 @@ +/** + * @fileoverview Endorser Type Definitions + * + * This file contains TypeScript declaration interfaces for the endorser system, + * providing shared type definitions for verifiable credentials, claims, and + * server operations. These types are designed to be used across both backend + * and frontend applications to ensure type safety and consistency. + * + * @author Matthew Raymer + * @created 2023-06-30 + * @version 1.0.0 + * + * @see {@link https://www.w3.org/TR/vc-data-model/ Verifiable Credentials Data Model} + */ +/** + * Represents an agreement on a verifiable credential within the endorser system. + * This interface defines the structure for expressing agreement with a specific + * verifiable credential, allowing for flexible object content. + * + * @interface AgreeVerifiableCredential + * @since 1.0.0 + */ export interface AgreeVerifiableCredential { + /** The JSON-LD context for the verifiable credential */ "@context": string; + /** The type identifier for the agreement credential */ "@type": string; + /** + * The object being agreed upon. Uses Record to allow for + * arbitrary objects as the subject of agreement. + * + * @example + * ```typescript + * object: { + * "@type": "GiveVerifiableCredential", + * recipient: { identifier: "did:example:123" }, + * object: { amountOfThisGood: 100, unitCode: "USD" } + * } + * ``` + */ // "any" because arbitrary objects can be subject of agreement // eslint-disable-next-line @typescript-eslint/no-explicit-any object: Record; } +/** + * Represents the result of a claim operation, either successful or failed. + * This interface provides a standardized way to handle claim operation outcomes. + * + * @interface ClaimResult + * @since 1.0.0 + */ export interface ClaimResult { - success: { claimId: string; handleId: string }; - error: { code: string; message: string }; + /** Success result containing claim and handle identifiers */ + success: { + /** Unique identifier for the claim */ + claimId: string; + /** Unique identifier for the handle associated with the claim */ + handleId: string; + }; + /** Error result containing error code and message */ + error: { + /** Error code for programmatic handling */ + code: string; + /** Human-readable error message */ + message: string; + }; } +/** + * Represents a generic claim structure with flexible content. + * This interface provides a base structure for various types of claims + * within the endorser system. + * + * @interface GenericClaim + * @since 1.0.0 + */ export interface GenericClaim { + /** The JSON-LD context for the claim */ "@context": string; + /** The type identifier for the claim */ "@type": string; + /** ISO 8601 timestamp when the claim was issued */ issuedAt: string; + /** + * The actual claim content. Uses Record to allow for + * flexible claim structures. + * + * @example + * ```typescript + * claim: { + * amount: 100, + * currency: "USD", + * description: "Payment for services" + * } + * ``` + */ // "any" because arbitrary objects can be subject of agreement // eslint-disable-next-line @typescript-eslint/no-explicit-any claim: Record; } +/** + * Represents a server-side record for give operations. + * This interface defines the complete structure for tracking give + * operations on the server, including confirmation status. + * + * @interface GiveServerRecord + * @since 1.0.0 + */ export interface GiveServerRecord { + /** DID (Decentralized Identifier) of the agent performing the give operation */ agentDid: string; + /** The amount being given */ amount: number; + /** The amount that has been confirmed/processed */ amountConfirmed: number; + /** Human-readable description of the give operation */ description: string; + /** The complete verifiable credential for the give operation */ fullClaim: GiveVerifiableCredential; + /** Unique identifier for the handle associated with this operation */ handleId: string; + /** ISO 8601 timestamp when the record was created */ issuedAt: string; + /** DID (Decentralized Identifier) of the recipient */ recipientDid: string; + /** Unit of measurement for the amount (e.g., "USD", "BTC") */ unit: string; } +/** + * Represents a verifiable credential for give operations. + * This interface defines the structure for expressing "give" actions + * within the endorser system, following W3C Verifiable Credentials standards. + * + * @interface GiveVerifiableCredential + * @since 1.0.0 + */ export interface GiveVerifiableCredential { - "@context"?: string; // optional when embedded, eg. in an Agree + /** + * The JSON-LD context for the verifiable credential. + * Optional when embedded in other structures (e.g., in an Agree credential). + */ + "@context"?: string; + /** The type identifier for the give credential */ "@type": string; - agent?: { identifier: string }; + /** Information about the agent performing the give operation */ + agent?: { + /** DID or other identifier for the agent */ + identifier: string; + }; + /** Human-readable description of the give operation */ description?: string; + /** Unique identifier for this credential */ identifier?: string; - object?: { amountOfThisGood: number; unitCode: string }; - recipient: { identifier: string }; + /** The object being given, including amount and unit */ + object?: { + /** The quantity being given */ + amountOfThisGood: number; + /** The unit code for the amount (e.g., "USD", "BTC") */ + unitCode: string; + }; + /** Information about the recipient of the give operation */ + recipient: { + /** DID or other identifier for the recipient */ + identifier: string; + }; } +/** + * Represents a verifiable credential for registration operations. + * This interface defines the structure for expressing registration + * actions within the endorser system. + * + * @interface RegisterVerifiableCredential + * @since 1.0.0 + */ export interface RegisterVerifiableCredential { + /** The JSON-LD context for the verifiable credential */ "@context": string; + /** The type identifier for the registration credential */ "@type": string; - agent: { identifier: string }; + /** Information about the agent performing the registration */ + agent: { + /** DID or other identifier for the agent */ + identifier: string; + }; + /** The object being registered (typically a string identifier) */ object: string; - recipient: { identifier: string }; + /** Information about the recipient of the registration */ + recipient: { + /** DID or other identifier for the recipient */ + identifier: string; + }; } +/** + * Represents an internal error structure for standardized error handling. + * This interface provides a consistent way to represent errors across + * the endorser system, separating system logging from user-facing messages. + * + * @interface InternalError + * @since 1.0.0 + */ export interface InternalError { - error: string; // for system logging - userMessage?: string; // for user display + /** + * Internal error message for system logging and debugging. + * This should contain technical details useful for developers. + */ + error: string; + /** + * User-friendly error message for display to end users. + * Optional - if not provided, a generic message should be shown. + */ + userMessage?: string; }