{"id":29480989,"url":"https://github.com/spounge-ai/spounge-proto","last_synced_at":"2026-05-03T23:36:45.276Z","repository":{"id":303871801,"uuid":"1016927289","full_name":"spounge-ai/spounge-proto","owner":"spounge-ai","description":"Package manager generating typed API packages (Go/TS/Python) from shared protobufs for standardized microservice communication.","archived":false,"fork":false,"pushed_at":"2025-08-23T03:42:56.000Z","size":1977,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-28T16:57:26.904Z","etag":null,"topics":["go","gomodule","npm-package","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@spounge/proto-ts","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spounge-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-07-09T18:38:37.000Z","updated_at":"2025-08-23T03:35:02.000Z","dependencies_parsed_at":"2025-07-29T11:07:57.479Z","dependency_job_id":"ff3aad9a-97fd-4650-9c19-9492e0919cbf","html_url":"https://github.com/spounge-ai/spounge-proto","commit_stats":null,"previous_names":["spoungeai/spounge-protos","spounge-ai/spounge-proto","spoungeai/spounge-proto","spounge-ai/spounge-protos"],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/spounge-ai/spounge-proto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spounge-ai%2Fspounge-proto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spounge-ai%2Fspounge-proto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spounge-ai%2Fspounge-proto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spounge-ai%2Fspounge-proto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spounge-ai","download_url":"https://codeload.github.com/spounge-ai/spounge-proto/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spounge-ai%2Fspounge-proto/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28326198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T22:11:01.104Z","status":"ssl_error","status_checked_at":"2026-01-11T22:10:58.990Z","response_time":60,"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":["go","gomodule","npm-package","typescript"],"created_at":"2025-07-14T23:55:14.198Z","updated_at":"2026-01-11T23:05:24.484Z","avatar_url":"https://github.com/spounge-ai.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"./docs/dark.svg\"\u003e\n  \u003cimg alt=\"spounge-protos-logo\" src=\"./docs/light.svg\" width=\"50%\" height=\"50%\"\u003e \n\u003c/picture\u003e\n\nProtocol Buffer definitions repositoiry powering the [@Spounge](https://github.com/spounge-ai) ecosystem services.\n\n[![Build](https://img.shields.io/github/actions/workflow/status/spoungeai/spounge-proto/build.yml?label=Build\u0026style=flat\u0026color=brightgreen)](https://github.com/spoungeai/spounge-proto/actions/workflows/build.yml)\n[![Go Module](https://img.shields.io/badge/proto--go-v1.2.9-17a2b8?style=flat)](https://github.com/spoungeai/spounge-proto/releases/tag/gen/go/v1.2.1)\n[![TypeScript Package](https://img.shields.io/npm/v/@spounge/proto-ts?label=proto-ts\u0026style=flat\u0026color=blue)](https://www.npmjs.com/package/@spounge/proto-ts)\n[![Python Package](https://img.shields.io/pypi/v/spounge-proto-py?label=proto-py\u0026style=flat\u0026color=DAA520)](https://pypi.org/project/spounge-proto-py/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat)](https://opensource.org/licenses/MIT)\n[![Changelog](https://img.shields.io/badge/Changelog-Available-blue?style=flat)](./docs/CHANGELOG.md)\n\n\u003c/div\u003e\n\u003chr style=\"width: 100%; height: 4px; background-color: #888; border: none; margin: 2em auto 1em;\" /\u003e\n \n \nUniversal schema translator for LLM microservices. Automated code generation for Go, TypeScript, and Python clients.\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Project Structure](#project-structure)\n- [Usage Examples](#usage-examples)\n- [Code Generation](#code-generation)\n- [Design Conventions](#design-conventions)\n- [API Evolution Rules](#api-evolution-rules)\n- [Testing](#testing)\n- [Development Workflow](#development-workflow)\n- [CI/CD Pipeline](#cicd-pipeline)\n- [Prerequisites](#prerequisites)\n- [Contact \u0026 Support](#contact--support)\n- [References](#references)\n\n## Quick Start\n\n```bash\ngit clone https://github.com/spounge-ai/spounge-proto\ncd spounge-proto\nmake docker-setup \n```\n\n## Installation\n\n| Language | Command |\n|----------|---------|\n| Go | `go get github.com/spoungeai/spounge-proto@latest` |\n| TypeScript | `npm install @spounge/proto-ts` |\n| Python | `pip install spounge-proto-py` |\n\n## Project Structure\n\n```\nproto/\n├── \u003cdomain\u003e/\u003cversion\u003e/     # Domain definitions (auth/v1/)\n├── common/v1/              # Shared definitions  \n└── api/v1/                 # API Gateway definitions\n\ngen/                        # Generated code\n├── go/                     # Go protobuf + gRPC/Connect\n├── ts/                     # TypeScript + Connect-Web\n├── py/                     # Python protobuf\n└── openapi/                # OpenAPI specs\n```\n\n## Usage Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGo Client\u003c/strong\u003e\u003c/summary\u003e\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log\"\n    \"time\"\n    \"google.golang.org/grpc\"\n    \"google.golang.org/grpc/credentials/insecure\"\n    \"google.golang.org/grpc/metadata\"\n    apiv1 \"github.com/spounge-ai/spounge-protos/gen/go/api/v1\"\n    authv1 \"github.com/spounge-ai/spounge-protos/gen/go/auth/v1\"\n)\n\nfunc main() {\n    conn, err := grpc.Dial(\"localhost:8080\", \n        grpc.WithTransportCredentials(insecure.NewCredentials()),\n        grpc.WithBlock())\n    if err != nil {\n        log.Fatalf(\"connection failed: %v\", err)\n    }\n    defer conn.Close()\n\n    client := apiv1.NewAuthGatewayServiceClient(conn)\n    \n    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n    defer cancel()\n    \n    ctx = metadata.AppendToOutgoingContext(ctx, \n        \"authorization\", \"Bearer your_token\",\n        \"x-request-id\", \"unique-request-id\")\n\n    req := \u0026apiv1.AuthGatewayServiceLoginRequest{\n        LoginRequest: \u0026authv1.LoginRequest{\n            Email:    \"test@example.com\",\n            Password: \"SecurePassword123\",\n        },\n    }\n\n    res, err := client.Login(ctx, req)\n    if err != nil {\n        log.Fatalf(\"login failed: %v\", err)\n    }\n\n    log.Printf(\"Token: %s\", res.GetLoginResponse().GetToken())\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTypeScript Client\u003c/strong\u003e\u003c/summary\u003e\n\n```typescript\nimport { createConnectTransport } from '@bufbuild/connect-web';\nimport { AuthGatewayServiceClient } from '../gen/ts/api/v1/auth_gateway_service.client';\nimport { AuthGatewayServiceLoginRequest } from '../gen/ts/api/v1/auth_gateway_service';\nimport { LoginRequest } from '../gen/ts/auth/v1/auth_service';\n\nconst transport = createConnectTransport({\n    baseUrl: 'http://localhost:8080',\n    interceptors: [\n        (next) =\u003e async (req) =\u003e {\n            req.header.set('Authorization', 'Bearer YOUR_TOKEN');\n            return next(req);\n        },\n    ],\n});\n\nconst client = new AuthGatewayServiceClient(transport);\n\nasync function login() {\n    try {\n        const request = new AuthGatewayServiceLoginRequest({\n            loginRequest: new LoginRequest({\n                email: 'user@example.com',\n                password: 'SecurePassword!',\n            }),\n        });\n\n        const response = await client.login(request);\n        console.log('Token:', response.loginResponse?.token);\n    } catch (error) {\n        console.error('Login failed:', error);\n    }\n}\n```\n\u003c/details\u003e\n\n## Code Generation\n\n| Command | Purpose |\n|---------|---------|\n| `make gen` | Generate all clients |\n| `make gen-go` | Go only |\n| `make gen-ts` | TypeScript only |\n| `make gen-py` | Python only |\n| `make docker-gen` | Docker-based generation |\n\n## Design Conventions\n\n### Naming Standards\n\n| Element | Convention | Example |\n|---------|------------|---------|\n| Packages | `lower.snake.case` | `api.v1` |\n| Services | `PascalCase` + `Service` | `AuthGatewayService` |\n| RPC Methods | `PascalCase` | `Login`, `GetUserProfile` |\n| Messages | `ServiceMethodRequest/Response` | `AuthGatewayServiceLoginRequest` |\n| Fields | `lower_snake_case` | `workflow_id` |\n| Enums | `PascalCase` | `ExecutionStatus` |\n| Enum Values | `PREFIX_VALUE_NAME` | `EXECUTION_STATUS_PENDING` |\n\n### Field Modifiers\n\n- `repeated` - Arrays/lists\n- `optional` - Nullable scalars (recommended for new fields)\n- `oneof` - Mutually exclusive field groups\n\n## API Evolution Rules\n\n| ✅ Allowed | ❌ Breaking Changes |\n|------------|-------------------|\n| Add new fields, services, methods | Remove/rename fields, services, methods |\n| Add `optional` fields | Change field types or numbers |\n| Add enum values (append only) | Reorder enum values |\n\n## Testing\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003egRPC Testing\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# List services\ngrpcurl localhost:8080 list\n\n# Test RPC\ngrpcurl -plaintext -d '{\n    \"loginRequest\": {\n        \"email\": \"test@example.com\", \n        \"password\": \"password\"\n    }\n}' localhost:8080 api.v1.AuthGatewayService/Login\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHTTP/REST Testing\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\ncurl -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"loginRequest\": {\"email\": \"test@example.com\", \"password\": \"password\"}}' \\\n  http://localhost:8080/v1/auth/login\n```\n\u003c/details\u003e\n\n| Command | Purpose |\n|---------|---------|\n| `make test-go` | Go integration tests |\n| `make test-ts` | TypeScript client tests |\n| `make test-py` | Python client tests |\n\n## Development Workflow\n\n1. Edit `.proto` files following conventions\n2. `buf format -w proto/` - Format\n3. `make lint` - Lint\n4. `make gen` - Generate\n5. `make test` - Test\n6. Commit (include generated code)\n\n## CI/CD Pipeline\n\n- Protobuf linting (`buf lint`)\n- Breaking change detection (`buf breaking --against origin/main`)\n- Code generation verification\n- Client library testing\n\n## Prerequisites\n\n| Tool | Version | Installation |\n|------|---------|-------------|\n| Go | 1.24+ | [go.dev/doc/install](https://go.dev/doc/install) |\n| Node.js | LTS | [nodejs.org](https://nodejs.org/en/download/) |\n| protoc | v30+ | [protobuf.dev/installation/](https://protobuf.dev/installation/) |\n| buf | v2.x.x+ | [docs.buf.build/installation](https://docs.buf.build/installation) |\n| Docker | Latest | [docs.docker.com/get-docker](https://docs.docker.com/get-docker/) |\n\n## Contact \u0026 Support\n\n- **Issues**: GitHub Issues\n- **Support**: dev@spounge.com\n- **License**: MIT\n\n## References\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDocumentation Links\u003c/strong\u003e\u003c/summary\u003e\n\n**Protocol Buffers \u0026 gRPC**\n- [Protocol Buffers Documentation](https://protobuf.dev/)\n- [Proto3 Language Guide](https://protobuf.dev/programming-guides/proto3/)\n- [gRPC Documentation](https://grpc.io/docs/)\n\n**Buf Ecosystem**\n- [Buf Documentation](https://buf.build/docs)\n- [Buf Style Guide](https://buf.build/docs/style-guide)\n- [Buf Lint Rules](https://buf.build/docs/lint-overview)\n\n**Connect \u0026 Gateway**\n- [ConnectRPC Documentation](https://connectrpc.com/docs)\n- [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway)\n\n**API Design**\n- [Google API Design Guide](https://cloud.google.com/apis/design)\n\u003c/details\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspounge-ai%2Fspounge-proto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspounge-ai%2Fspounge-proto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspounge-ai%2Fspounge-proto/lists"}