👁 Image
SaaS-Factory.AppBlueprint.Contracts 1.0.6

AppBlueprint.Contracts

👁 NuGet Version
👁 License: MIT

Overview

The AppBlueprint.Contracts package provides a shared library of Data Transfer Objects (DTOs) for client-server communication. This package contains request and response models that define the contract between the API and its clients, following Clean Architecture principles.

Features

Request/Response DTOs

• Baseline Module - Core user, profile, authentication, and authorization contracts
• B2B Module - Business-to-Business specific contracts (teams, tenants, subscriptions)
• B2C Module - Business-to-Consumer specific contracts (placeholder for future features)
• Admin Module - Administrative operation contracts (placeholder for future features)

Contract Categories

• Authentication & Authorization - Login, logout, token management
• User Management - Profile creation, updates, user queries
• Team Management - Team creation, member management, invitations
• Tenant Management - Tenant operations and settings
• Payment & Billing - Subscription and payment processing

Design Principles

• API-first design with clear request/response contracts
• Immutable DTOs for thread-safety
• Validation-ready properties with appropriate nullability
• Serialization-friendly for JSON, XML, and other formats
• Framework-agnostic - can be used with any .NET application
• Strongly-typed with proper C# typing

Installation

dotnet add package SaaS-Factory.AppBlueprint.Contracts

Dependencies

This package has minimal dependencies:

• AppBlueprint.SharedKernel - For shared types and base classes

Usage

Authentication Requests/Responses

using AppBlueprint.Contracts.Baseline.Authentication;

// Login request
var loginRequest = new LoginRequest
{
 Email = "user@example.com",
 Password = "SecurePassword123!"
};

// Login response
public class LoginResponse
{
 public string AccessToken { get; set; }
 public string RefreshToken { get; set; }
 public DateTime ExpiresAt { get; set; }
}

Profile Management

using AppBlueprint.Contracts.Baseline.Profile;

// Create profile request
var createProfileRequest = new CreateProfileRequest
{
 FirstName = "John",
 LastName = "Doe",
 DateOfBirth = new DateTime(1990, 1, 1),
 Gender = "Male",
 UserName = "johndoe",
 IsActive = true,
 Language = "en-US",
 Timezone = DateTime.UtcNow,
 Avatar = "https://example.com/avatar.jpg",
 Slug = "john-doe"
};

// Profile response
public class ProfileResponse
{
 public string? FirstName { get; set; }
 public string? LastName { get; set; }
 public DateTime DateOfBirth { get; set; }
 public string? Gender { get; set; }
 public string? UserName { get; set; }
 public bool IsActive { get; set; }
 public DateTimeOffset CreatedAt { get; set; }
 public DateTimeOffset LastLogin { get; set; }
 public string? Language { get; set; }
 public DateTime Timezone { get; set; }
 public string? Avatar { get; set; }
 public string? Slug { get; set; }
}

Team Management (B2B)

using AppBlueprint.Contracts.B2B.Team;

// Create team request
var createTeamRequest = new CreateTeamRequest
{
 Name = "Development Team",
 Description = "Our awesome dev team",
 TenantId = tenantId
};

// Team member invitation
var inviteRequest = new InviteTeamMemberRequest
{
 Email = "newmember@example.com",
 Role = "Developer"
};

Contract Structure

AppBlueprint.Contracts/
├── Baseline/
│ ├── Authentication/
│ │ ├── Requests/
│ │ │ ├── LoginRequest.cs
│ │ │ └── RegisterRequest.cs
│ │ └── Responses/
│ │ └── LoginResponse.cs
│ ├── Profile/
│ │ ├── Requests/
│ │ │ ├── CreateProfileRequest.cs
│ │ │ └── UpdateProfileRequest.cs
│ │ └── Responses/
│ │ └── ProfileResponse.cs
│ └── Payment/
│ └── Requests/
│ └── ProfileRequest.cs
├── B2B/
│ ├── Team/
│ ├── Tenant/
│ └── Subscription/
├── B2C/
│ └── (Future B2C-specific contracts)
└── Admin/
 └── (Future admin-specific contracts)

Best Practices

Request Objects

• Use required keyword for mandatory properties
• Provide clear, descriptive property names
• Include data annotations for validation when needed
• Keep requests focused and single-purpose

Response Objects

• Make properties nullable where appropriate
• Include all relevant data for the client
• Use proper types (DateTimeOffset for timestamps, etc.)
• Keep responses lean and focused

Naming Conventions

• Requests: {Action}{Entity}Request (e.g., CreateUserRequest)
• Responses: {Entity}Response or {Action}{Entity}Response
• Use PascalCase for all public members
• Prefix interfaces with I

Validation

While this package doesn't include validation logic, it's designed to work with:

• FluentValidation for complex validation rules
• Data Annotations for simple validation
• Custom validators in the Application layer

// Example with FluentValidation (in Application layer)
public class CreateProfileRequestValidator : AbstractValidator<CreateProfileRequest>
{
 public CreateProfileRequestValidator()
 {
 RuleFor(x => x.FirstName).NotEmpty().MaximumLength(50);
 RuleFor(x => x.LastName).NotEmpty().MaximumLength(50);
 RuleFor(x => x.UserName).NotEmpty().MaximumLength(30);
 RuleFor(x => x.Email).EmailAddress();
 }
}

Versioning

This package follows semantic versioning:

• Major: Breaking changes to existing contracts
• Minor: New contracts or non-breaking additions
• Patch: Bug fixes and documentation updates

⚠️ Breaking Changes: Adding required properties or removing properties are breaking changes.

Migration Guide

When contracts change:

Adding New Properties (Non-Breaking)

// Before
public class UserResponse
{
 public string Name { get; set; }
}

// After - Add nullable property (non-breaking)
public class UserResponse
{
 public string Name { get; set; }
 public string? Email { get; set; } // New optional property
}

Removing Properties (Breaking)

// This requires a major version bump
// Deprecate first, remove in next major version
[Obsolete("Use NewProperty instead")]
public string OldProperty { get; set; }

Related Packages

This package is part of the AppBlueprint ecosystem:

• AppBlueprint.SharedKernel - Base types and shared utilities
• AppBlueprint.Api.Client.Sdk - Type-safe API client using these contracts
• AppBlueprint.Application - Application services that use these contracts
• AppBlueprint.Presentation.ApiModule - API endpoints that implement these contracts

Contributing

This package is part of the SaaS Factory Labs AppBlueprint template. Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

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

Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions

Links

• Source Code
• SaaS Factory Labs
• NuGet Package