{"id":46289776,"url":"https://github.com/khanjal/raptorsheets","last_synced_at":"2026-03-04T08:01:30.906Z","repository":{"id":248299189,"uuid":"744245679","full_name":"khanjal/RaptorSheets","owner":"khanjal","description":"Library for managing and automating Google Sheets via the Google Sheets API. Provides robust support for sheet configuration, data modeling, and formula generation, ensuring seamless integration with .NET applications.","archived":false,"fork":false,"pushed_at":"2025-12-31T21:47:38.000Z","size":1159,"stargazers_count":1,"open_issues_count":12,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-05T19:26:10.927Z","etag":null,"topics":["google","google-sheets","google-sheets-api-v4","sheets"],"latest_commit_sha":null,"homepage":"http://www.raptorsheets.com","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/khanjal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-16T22:45:36.000Z","updated_at":"2025-12-31T15:19:47.000Z","dependencies_parsed_at":"2024-08-07T07:34:29.146Z","dependency_job_id":"6583f69f-cb29-44b5-8319-a98e4c3f431c","html_url":"https://github.com/khanjal/RaptorSheets","commit_stats":null,"previous_names":["khanjal/gigraptorlibrary","khanjal/raptorloggerengine"],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/khanjal/RaptorSheets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanjal%2FRaptorSheets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanjal%2FRaptorSheets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanjal%2FRaptorSheets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanjal%2FRaptorSheets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khanjal","download_url":"https://codeload.github.com/khanjal/RaptorSheets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khanjal%2FRaptorSheets/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30075909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T05:31:57.858Z","status":"ssl_error","status_checked_at":"2026-03-04T05:31:38.462Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google","google-sheets","google-sheets-api-v4","sheets"],"created_at":"2026-03-04T08:01:30.005Z","updated_at":"2026-03-04T08:01:30.898Z","avatar_url":"https://github.com/khanjal.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RaptorSheets.Core\n\nA comprehensive .NET 8 library that simplifies Google Sheets API interactions for developers who need powerful sheet integration without the complexity. Build custom Google Sheets solutions or use our specialized packages for common use cases.\n\n**[📋 Gig Package](RaptorSheets.Gig/README.md)** — Complete gig work tracking guide.\n\n| Badge Name | Status | Site |\n| ---------- | :------------: | :------------: |\n| Latest Build Status | [![build status](https://github.com/khanjal/RaptorSheets/actions/workflows/dotnet.yml/badge.svg)](https://github.com/khanjal/RaptorSheets/actions) | [GitHub Repo](https://github.com/khanjal/RaptorSheets/) |\n| RaptorSheets.Core NuGet | [![Nuget](https://img.shields.io/nuget/v/RaptorSheets.Core)](https://www.nuget.org/packages/RaptorSheets.Core/) | [RaptorSheets.Core](https://www.raptorsheets.com) |\n| RaptorSheets.Gig NuGet | [![Nuget](https://img.shields.io/nuget/v/RaptorSheets.Gig)](https://www.nuget.org/packages/RaptorSheets.Gig/) | [RaptorSheets.Gig](https://www.nuget.org/packages/RaptorSheets.Gig/) |\n| Test Coverage | [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=khanjal_RaptorSheets\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=khanjal_RaptorSheets) | [SonarCloud](https://sonarcloud.io/project/overview?id=khanjal_RaptorSheets) |\n| Code Quality | [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=khanjal_RaptorSheets\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=khanjal_RaptorSheets) | [SonarCloud](https://sonarcloud.io/project/overview?id=khanjal_RaptorSheets) |\n| License | [![License](https://img.shields.io/github/license/khanjal/RaptorSheets)](LICENSE) | - |\n\n## 📦 Installation\n\n```bash\n# Core library for custom implementations\ndotnet add package RaptorSheets.Core\n\n# Or choose a specialized package\ndotnet add package RaptorSheets.Gig    # For gig work tracking\n```\n\n## 🚀 Quick Start\n\n### Basic Google Sheets Operations\n```csharp\nusing RaptorSheets.Core.Services;\nusing RaptorSheets.Core.Models.Google;\n\n// Set up authentication\nvar credentials = new Dictionary\u003cstring, string\u003e\n{\n    [\"type\"] = \"service_account\",\n    [\"client_email\"] = \"service@project.iam.gserviceaccount.com\",\n    [\"private_key\"] = \"-----BEGIN PRIVATE KEY-----\\n...\",\n    // ... other credentials\n};\n\nvar service = new GoogleSheetService(credentials, spreadsheetId);\n\n// Read data from existing sheet\nvar sheetData = await service.GetSheetData(\"MySheet\");\nConsole.WriteLine($\"Found {sheetData.Values.Count} rows\");\n```\n\n### TypedField System with ColumnAttribute\n```csharp\nusing RaptorSheets.Core.Attributes;\nusing RaptorSheets.Core.Enums;\nusing RaptorSheets.Core.Repositories;\n\n// Define entities with automatic type conversion\npublic class ContactEntity\n{\n    public int RowId { get; set; }\n\n    // Basic string field with header mapping\n    [Column(SheetsConfig.HeaderNames.Name, FieldType.String)]\n    public string Name { get; set; } = \"\";\n\n    // Automatic currency formatting with default \"$#,##0.00\" pattern\n    [Column(SheetsConfig.HeaderNames.Salary, FieldType.Currency)]\n    public decimal? Salary { get; set; }\n\n    // Custom format when different from default\n    [Column(SheetsConfig.HeaderNames.Score, FieldType.Percentage, \"0.0%\")]\n    public decimal? Score { get; set; }\n\n    // Override JSON name when needed\n    [Column(SheetsConfig.HeaderNames.EmailAddress, FieldType.Email)]\n    [JsonPropertyName(\"email\")]\n    public string EmailAddress { get; set; } = \"\";\n}\n\n// Repository with automatic CRUD operations\npublic class ContactRepository : BaseEntityRepository\u003cContactEntity\u003e\n{\n    public ContactRepository(IGoogleSheetService sheetService) \n        : base(sheetService, \"Contacts\", hasHeaderRow: true) { }\n\n    // Custom business logic methods\n    public async Task\u003cList\u003cContactEntity\u003e\u003e GetHighScorersAsync()\n    {\n        var allContacts = await GetAllAsync(); // Automatic type conversion\n        return allContacts.Where(c =\u003e c.Score \u003e 0.8m).ToList();\n    }\n}\n\n// Usage\nvar repository = new ContactRepository(service);\n\n// Automatic type conversion: \"$75,000.00\" → decimal 75000\nvar contacts = await repository.GetAllAsync();\n\n// Add new contact with automatic conversion\nvar newContact = new ContactEntity\n{\n    Name = \"John Doe\",\n    Salary = 75000m,      // Automatically formatted as \"$75,000.00\"\n    Score = 0.95m,        // Automatically formatted as \"95.0%\"\n    EmailAddress = \"john@example.com\"\n};\nawait repository.AddAsync(newContact);\n```\n\n### Create Advanced Sheets with Formatting\n```csharp\n// Create custom sheet with formatting\nvar sheetModel = new SheetModel\n{\n    Name = \"CustomSheet\",\n    TabColor = ColorEnum.BLUE,\n    Headers = new List\u003cSheetCellModel\u003e\n    {\n        new() { Name = \"ID\", Format = FormatEnum.NUMBER },\n        new() { Name = \"Name\", Format = FormatEnum.TEXT },\n        new() { Name = \"Amount\", Format = FormatEnum.CURRENCY }\n    }\n};\n\n// Generate and execute requests\nvar requests = sheetModel.GenerateRequests();\nawait service.ExecuteBatchUpdate(requests);\n```\n\n## ✨ Key Features\n\n### TypedField System\n- **ColumnAttribute**: Single attribute for headers, types, and formatting\n- **Automatic Type Conversion**: Currency, dates, percentages, phone numbers, emails\n- **Default Format Patterns**: Specify only when different from sensible defaults\n- **Header-Driven Configuration**: Use header names as primary source of truth\n- **Repository Pattern**: Automatic CRUD operations with type conversion\n\n### Core Infrastructure\n- **📋 Header Management**: Extension methods for column and index assignments with automatic processing\n- **🎨 Column Formatting**: Apply data formatting, configure drop-downs, and set cell protection\n- **🎯 Sheet Styling**: Alternating row colors, full sheet protection, and custom tab colors\n- **⚡ Batch Operations**: Efficient bulk operations for large datasets with automatic batching\n- **🔒 Type Safety**: Strongly typed entities and enums for all operations\n- **✅ Auto Validation**: Automatic header validation with detailed error reporting\n- **🛠️ Error Handling**: Comprehensive message system for operation feedback\n- **🧪 Well Tested**: Extensive unit and integration test coverage\n\n## 🏗️ Architecture\n\n```\nYour Custom Application\n       ↓\nTypedField System\n  ├── ColumnAttribute (Configuration)\n  ├── BaseEntityRepository\u003cT\u003e (CRUD Operations)\n  ├── TypedEntityMapper\u003cT\u003e (Conversion)\n  └── Schema Validation (Type Safety)\n       ↓\nRaptorSheets.Core\n  ├── GoogleSheetService (High-level operations)\n  ├── SheetServiceWrapper (API abstraction)  \n  ├── Models \u0026 Entities (Type safety)\n  └── Extensions \u0026 Helpers (Utilities)\n       ↓\nGoogle Sheets API v4\n```\n\n## 💼 TypedField System Benefits\n\n### Simplified Configuration\n```csharp\n// Single attribute, automated mapping\n[Column(SheetsConfig.HeaderNames.Pay, FieldType.Currency, \"\\\"$\\\"#,##0.00\")]\npublic decimal? Pay { get; set; }\n\n// Automated conversion in mappers\nentity.Pay = MapperHelper.MapField\u003cdecimal?\u003e(\"Pay\", row, headers);\n```\n\n### Supported Field Types with Auto-Conversion\n\n| Field Type | Auto-Converts | Example Input → Output |\n|------------|---------------|------------------------|\n| `Currency` | Dollar amounts | `\"$1,234.56\"` → `decimal 1234.56` |\n| `PhoneNumber` | Phone formats | `\"(555) 123-4567\"` → `long 5551234567` |\n| `DateTime` | Date/time values | Google serial → `DateTime` |\n| `Percentage` | Percentage values | `0.85` → `\"85.00%\"` |\n| `Email` | Email addresses | Validation + text format |\n| `Number` | Numeric values | `\"1,234.56\"` → `decimal 1234.56` |\n| `Integer` | Whole numbers | `\"1,234\"` → `int 1234` |\n| `Boolean` | True/false | `\"TRUE\"` → `bool true` |\n\n## 📚 Specialized Packages\n\nBuilt on RaptorSheets.Core, these packages provide domain-specific functionality:\n\n| Package | Version | Purpose | Documentation |\n|---------|---------|---------|---------------|\n| **[RaptorSheets.Gig](https://www.nuget.org/packages/RaptorSheets.Gig/)** | [![Nuget](https://img.shields.io/nuget/v/RaptorSheets.Gig)](https://www.nuget.org/packages/RaptorSheets.Gig/) | Complete gig work tracking with automated analytics | **[📖 Gig Guide](RaptorSheets.Gig/README.md)** |\n\n\u003e **Looking for gig work tracking?** Check out **[RaptorSheets.Gig](RaptorSheets.Gig/README.md)** - a complete solution for freelancers and gig workers with pre-built sheets for trips, shifts, earnings, and comprehensive analytics.\n\n## 💼 Use Cases\n\n- **Custom Business Solutions**: Build domain-specific Google Sheets integrations for any industry\n- **Data Pipeline Integration**: Automate data sync between your applications and collaborative spreadsheets  \n- **Advanced Report Generation**: Create complex reports with formulas, cross-sheet references, and automated calculations\n- **Workflow Automation**: Streamline business processes that rely on Google Sheets data\n- **Foundation for Specialized Packages**: Use as a base to create domain-specific managers (like RaptorSheets.Gig)\n\n## 🔐 Authentication Quick Start\n\nRaptorSheets supports multiple authentication methods:\n\n### Service Account (Recommended)\n```csharp\nvar credentials = new Dictionary\u003cstring, string\u003e\n{\n    [\"type\"] = \"service_account\",\n    [\"private_key_id\"] = \"your-key-id\",\n    [\"private_key\"] = \"your-private-key\", \n    [\"client_email\"] = \"service@project.iam.gserviceaccount.com\",\n    [\"client_id\"] = \"your-client-id\"\n};\n```\n\n### OAuth2 Access Token\n```csharp\nvar manager = new GoogleSheetManager(accessToken, spreadsheetId);\n```\n\n## 🏗️ Building Custom Packages\n\nRaptorSheets.Core with TypedField system is designed to be the foundation for domain-specific packages:\n\n```csharp\n// 1. Define your domain entities with ColumnAttribute\npublic class ProductEntity\n{\n    public int RowId { get; set; }\n    \n    [Column(SheetsConfig.HeaderNames.ProductName, FieldType.String)]\n    public string Name { get; set; } = \"\";\n    \n    [Column(SheetsConfig.HeaderNames.Price, FieldType.Currency)]\n    public decimal Price { get; set; }\n    \n    [Column(SheetsConfig.HeaderNames.LaunchDate, FieldType.DateTime, \"M/d/yyyy\")]\n    public DateTime? LaunchDate { get; set; }\n}\n\n// 2. Create repository with automatic CRUD\npublic class ProductRepository : BaseEntityRepository\u003cProductEntity\u003e\n{\n    public ProductRepository(IGoogleSheetService service) \n        : base(service, \"Products\", hasHeaderRow: true) { }\n    \n    public async Task\u003cList\u003cProductEntity\u003e\u003e GetExpensiveProductsAsync()\n    {\n        var products = await GetAllAsync(); // Automatic conversion\n        return products.Where(p =\u003e p.Price \u003e 100m).ToList();\n    }\n}\n\n// 3. Domain-specific manager\npublic class ProductManager\n{\n    private readonly ProductRepository _repository;\n    \n    public ProductManager(Dictionary\u003cstring, string\u003e credentials, string spreadsheetId)\n    {\n        var service = new GoogleSheetService(credentials, spreadsheetId);\n        _repository = new ProductRepository(service);\n    }\n    \n    public async Task\u003cList\u003cProductEntity\u003e\u003e GetProductCatalogAsync()\n    {\n        return await _repository.GetAllAsync(); // Full type conversion automatically\n    }\n}\n```\n\n**See [RaptorSheets.Gig](RaptorSheets.Gig/README.md) as a complete example of a specialized package built on the TypedField system.**\n\n## 🛠️ Development Setup\n\n### Prerequisites\n- .NET 8.0 SDK or later\n- Google Cloud Project with Sheets API enabled\n- Service Account credentials (recommended) or OAuth2 setup\n\n### Quick Setup\n```bash\ngit clone https://github.com/khanjal/RaptorSheets.git\ncd RaptorSheets\ndotnet restore\ndotnet build\ndotnet test\n```\n\n## 🧪 Testing\n\n```bash\n# Run all tests\ndotnet test\n\n# Run Core library tests specifically  \ndotnet test RaptorSheets.Core.Tests/\n\n# Run with coverage\ndotnet test --collect:\"XPlat Code Coverage\"\n```\n\n## 🚦 Performance \u0026 API Limits\n\n### Google Sheets API Quotas\n- **Read/Write requests**: 100 requests per 100 seconds per user\n- **Daily requests**: 50,000 requests per day\n\n### Library Optimizations\n- 📦 Automatic request batching\n- ⚡ Efficient data retrieval strategies\n- 🧠 Smart caching mechanisms\n- 🔁 Rate limit handling with retries\n- 🆕 **TypedField Performance**: Cached reflection, efficient type conversion\n\n## 🤝 Contributing\n\nWe welcome contributions to RaptorSheets.Core and the broader ecosystem!\n\n### Development Workflow\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Focus on Core library enhancements or create new specialized packages\n4. Write comprehensive tests\n5. Update relevant documentation\n6. Submit a Pull Request\n\n### Areas for Contribution\n- **TypedField System**: Field types, conversion improvements, validation enhancements\n- **Core Library**: Enhance base functionality, performance, or new Google Sheets features\n- **New Packages**: Create domain-specific packages (Stock, Real Estate, etc.)\n- **Documentation**: Improve guides, examples, and API documentation\n- **Testing**: Add test coverage or performance benchmarks\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 💬 Support \u0026 Resources\n\n- 🐞 [Report Issues](https://github.com/khanjal/RaptorSheets/issues)\n- 💬 [Discussions](https://github.com/khanjal/RaptorSheets/discussions)\n- 📖 [Google Sheets API Reference](https://googleapis.dev/dotnet/Google.Apis.Sheets.v4/latest/api/Google.Apis.Sheets.v4.html)\n- 🌐 [Project Homepage](https://www.raptorsheets.com)\n\n---\n\n**Made with ❤️ by Iron Raptor Digital**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhanjal%2Fraptorsheets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhanjal%2Fraptorsheets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhanjal%2Fraptorsheets/lists"}