{"id":28651818,"url":"https://github.com/Nyarum/zigtgshka","last_synced_at":"2025-06-13T06:05:39.205Z","repository":{"id":295796682,"uuid":"988974136","full_name":"Nyarum/zigtgshka","owner":"Nyarum","description":"🤖 Memory-safe, high-performance Telegram Bot API library for Zig with zero-cost abstractions and comprehensive examples","archived":false,"fork":false,"pushed_at":"2025-05-27T11:09:13.000Z","size":162,"stargazers_count":11,"open_issues_count":14,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-05-27T12:21:18.072Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Zig","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/Nyarum.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}},"created_at":"2025-05-23T11:08:27.000Z","updated_at":"2025-05-27T11:09:19.000Z","dependencies_parsed_at":"2025-05-27T12:21:25.530Z","dependency_job_id":"3e7ad0f6-1c29-4b79-92f9-168a8fdbcbd2","html_url":"https://github.com/Nyarum/zigtgshka","commit_stats":null,"previous_names":["nyarum/zigtgshka"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Nyarum/zigtgshka","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nyarum%2Fzigtgshka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nyarum%2Fzigtgshka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nyarum%2Fzigtgshka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nyarum%2Fzigtgshka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nyarum","download_url":"https://codeload.github.com/Nyarum/zigtgshka/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nyarum%2Fzigtgshka/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259592260,"owners_count":22881265,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-06-13T06:01:38.591Z","updated_at":"2025-06-13T06:05:39.196Z","avatar_url":"https://github.com/Nyarum.png","language":"Zig","funding_links":[],"categories":["Network \u0026 Web"],"sub_categories":["Network"],"readme":"# 🤖 Telegram Bot API for Zig\n\n\u003cdiv align=\"center\"\u003e\n\n[![Zig](https://img.shields.io/badge/Zig-0.14.0+-F7A41D?style=for-the-badge\u0026logo=zig\u0026logoColor=white)](https://ziglang.org/)\n[![Telegram Bot API](https://img.shields.io/badge/Bot%20API-7.0+-2AABEE?style=for-the-badge\u0026logo=telegram\u0026logoColor=white)](https://core.telegram.org/bots/api)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)\n\n\n**A memory-safe, high-performance Telegram Bot API implementation in Zig**\n\n*Build powerful bots with zero allocations in hot paths and compile-time guarantees*\n\n[![API Coverage](https://img.shields.io/badge/API%20Coverage-85%25-brightgreen?style=for-the-badge)](API_METHODS_IMPLEMENTED.md)\n\n[🚀 Quick Start](#-quick-start) • [📚 Examples](#-examples) • [🎯 Features](#-features) • [📖 DeepWiki](https://deepwiki.com/Nyarum/zigtgshka/1-overview)\n\n\u003c/div\u003e\n\n🤖 **Complete Bot API Support**\n- 📨 **Message Handling**: Send, receive, edit, and delete messages\n- 📁 **File Operations**: Upload and download files with streaming support\n- 🎯 **Inline Queries**: Full inline mode support\n- 🔗 **Webhooks**: Secure webhook management\n- 🎮 **Interactive Elements**: Keyboards, buttons, and callbacks\n- 📊 **Rich Media**: Photos, videos, documents, and more\n\n## 🚀 Quick Start\n\n### Prerequisites\n- **Zig 0.14.0+** ([Download here](https://ziglang.org/download/))\n- **Telegram Bot Token** ([Get from @BotFather](https://t.me/botfather))\n\n### 📦 Installation\n\n**Option 1: Using Zig Package Manager (Recommended)**\n```bash\n# Add to your build.zig.zon\nzig fetch --save git+https://github.com/Nyarum/zigtgshka.git\n```\n\n**Your build.zig.zon should look like:**\n```zig\n.{\n    .name = \"my_bot\",\n    .version = \"0.0.0\",\n    .minimum_zig_version = \"0.14.0\",\n    .dependencies = .{\n        .zigtgshka = .{\n            .url = \"git+https://github.com/Nyarum/zigtgshka.git\",\n            .hash = \"1220...\", // This will be auto-generated by zig fetch\n        },\n    },\n    .paths = .{\n        \"build.zig\",\n        \"build.zig.zon\",\n        \"src\",\n    },\n}\n```\n\n**Complete build.zig example:**\n```zig\nconst std = @import(\"std\");\n\npub fn build(b: *std.Build) void {\n    const target = b.standardTargetOptions(.{});\n    const optimize = b.standardOptimizeOption(.{});\n\n    // Add zigtgshka dependency\n    const telegram_dependency = b.dependency(\"zigtgshka\", .{\n        .target = target,\n        .optimize = optimize,\n    });\n\n    // Create your executable\n    const exe = b.addExecutable(.{\n        .name = \"my_bot\",\n        .root_source_file = b.path(\"src/main.zig\"),\n        .target = target,\n        .optimize = optimize,\n    });\n\n    // Import the telegram module\n    exe.root_module.addImport(\"telegram\", telegram_dependency.module(\"telegram\"));\n    exe.linkLibC(); // Required for HTTP client\n    \n    b.installArtifact(exe);\n\n    // Run step\n    const run_cmd = b.addRunArtifact(exe);\n    run_cmd.step.dependOn(b.getInstallStep());\n    \n    if (b.args) |args| {\n        run_cmd.addArgs(args);\n    }\n\n    const run_step = b.step(\"run\", \"Run the app\");\n    run_step.dependOn(\u0026run_cmd.step);\n}\n```\n\n**Option 2: Git Submodule**\n```bash\ngit submodule add https://github.com/Nyarum/zigtgshka.git libs/telegram\n\nconst telegram_mod = b.addModule(\"telegram\", .{\n    .root_source_file = b.path(\"libs/telegram/src/telegram.zig\"),\n    .target = target,\n    .optimize = optimize,\n});\nexe.root_module.addImport(\"telegram\", telegram_mod);\nexe.linkLibC(); // Required for HTTP client\n```\n\n**Option 3: Direct Download**\n```bash\ngit clone https://github.com/Nyarum/zigtgshka.git\ncd zigtgshka\n```\n\n### ⚡ Your First Bot (60 seconds)\n\nCreate `src/main.zig`:\n\n```zig\nconst std = @import(\"std\");\nconst telegram = @import(\"telegram\");\n\npub fn main() !void {\n    // 🏗️ Setup with explicit allocator (Zig best practice)\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // 🌐 Initialize HTTP client\n    var client = try telegram.HTTPClient.init(allocator);\n    defer client.deinit();\n\n    // 🤖 Create your bot\n    var bot = try telegram.Bot.init(allocator, \"YOUR_BOT_TOKEN\", \u0026client);\n    defer bot.deinit();\n\n    // 🎉 Get bot info and start polling\n    const me = try telegram.methods.getMe(\u0026bot);\n    defer me.deinit(allocator);\n    \n    std.debug.print(\"🚀 Bot @{s} is online!\\n\", .{me.username orelse me.first_name});\n\n    // 🔄 Simple polling loop\n    var offset: i32 = 0;\n    while (true) {\n        const updates = try telegram.methods.getUpdates(\u0026bot, offset, 100, 30);\n        defer {\n            for (updates) |*update| update.deinit(allocator);\n            allocator.free(updates);\n        }\n\n        for (updates) |update| {\n            offset = update.update_id + 1;\n            \n            if (update.message) |message| {\n                if (message.text) |text| {\n                    // 💬 Echo messages back\n                    const reply = try telegram.methods.sendMessage(\u0026bot, message.chat.id, text);\n                    defer reply.deinit(allocator);\n                    \n                    std.debug.print(\"📨 Echoed: {s}\\n\", .{text});\n                }\n            }\n        }\n    }\n}\n```\n\n**Run it:**\n```bash\n# Using zig build (recommended)\nzig build run\n\n# Or build and run manually\nzig build\n./zig-out/bin/my_bot\n```\n\n## 📚 Examples\n\nWe provide comprehensive examples from beginner to advanced use cases:\n\n\u003e 📖 **For detailed documentation of all examples, see [examples/README.md](examples/README.md)**\n\n### 🎯 Available Examples\n\n| Example | Description | Complexity | Key Features |\n|---------|-------------|------------|--------------|\n| [**echo_bot**](examples/echo_bot.zig) | Simple echo bot | 🟢 Beginner | Basic message handling |\n| [**bot_info**](examples/bot_info.zig) | Get bot information | 🟢 Beginner | API calls, error handling |\n| [**simple_sender**](examples/simple_sender.zig) | Send targeted messages | 🟡 Intermediate | Direct messaging |\n| [**polling_bot**](examples/polling_bot.zig) | Command-based bot | 🟡 Intermediate | Command parsing, help system |\n| [**advanced_bot**](examples/advanced_bot.zig) | Full-featured bot | 🔴 Advanced | State management, analytics |\n| [**webhook_manager**](examples/webhook_manager.zig) | Webhook setup | 🟡 Intermediate | Webhook configuration |\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### 🔧 Development Setup\n```bash\n# Clone the repository\ngit clone https://github.com/Nyarum/zigtgshka.git\ncd zigtgshka\n\n# Run tests to verify setup\nzig build test\n\n# Run examples to test functionality\nmake run-info API_KEY=your_test_token\n```\n\n### 📝 Contribution Guidelines\n- **Code Style**: Follow Zig's standard formatting (`zig fmt`)\n- **Memory Safety**: Always pair `init()` with `deinit()`\n- **Error Handling**: Use explicit error types and handling\n- **Documentation**: Update docs for any API changes\n- **Tests**: Add tests for new functionality\n\n### 🐛 Reporting Issues\n- Use the issue template\n- Include Zig version (`zig version`)\n- Provide minimal reproduction code\n- Include relevant log output\n\n## 📊 Performance\n\n### 🚀 Benchmarks\n- **Memory Usage**: \u003c 10MB for typical bots\n- **Latency**: \u003c 50ms average response time\n- **Throughput**: 1000+ messages/second\n- **Binary Size**: \u003c 2MB (release builds)\n\n### 📈 Optimization Features\n- Zero-allocation hot paths\n- Compile-time parameter validation\n- Efficient JSON parsing with `std.json`\n- Connection pooling for HTTP requests\n\n## 🔗 Resources\n\n### 📚 Learning Zig\n- [Official Zig Documentation](https://ziglang.org/documentation/master/)\n- [Zig Learn](https://ziglearn.org/)\n- [Zig News](https://zig.news/)\n\n### 🤖 Telegram Bot API\n- [Official Bot API Documentation](https://core.telegram.org/bots/api)\n- [BotFather](https://t.me/botfather) - Create and manage bots\n- [Telegram Bot Examples](https://core.telegram.org/bots/samples)\n\n## 📜 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ and Zig**\n\n*Star ⭐ this repo if you find it useful!*\n\n[🐛 Report Bug](https://github.com/Nyarum/zigtgshka/issues) • [✨ Request Feature](https://github.com/Nyarum/zigtgshka/issues) • [💬 Discussions](https://github.com/Nyarum/zigtgshka/discussions)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNyarum%2Fzigtgshka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNyarum%2Fzigtgshka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNyarum%2Fzigtgshka/lists"}