@in-human-resources/backend-proto 0.1.0 → 0.1.3

package/README.md

@@ -1,63 +1,84 @@
-# `@in-human-resources/backend-proto`
-
-Published npm package: **Protobuf-ES** message types and **Connect-ES** service stubs for `api.v1`, `auth.v1`, and `common.v1`.
-
-## Install
-
-```bash
-npm install @in-human-resources/backend-proto
-```
-
-Peer dependencies (install in your app):
-
-```bash
-npm install @bufbuild/protobuf @connectrpc/connect
-```
-
-For browsers you may also use `@connectrpc/connect-web`.
-
-## Usage
-
-Import Connect service definitions and create a client (example: gateway `api.v1`):
-
-```typescript
-import { createClient } from '@connectrpc/connect';
-import { createGrpcTransport } from '@connectrpc/connect-node';
-import { AuthService } from '@in-human-resources/backend-proto/gen/ts/api/v1/auth_connect.js';
-
-const transport = createGrpcTransport({ baseUrl: 'http://localhost:8082', httpVersion: '2' });
-export const authClient = createClient(AuthService, transport);
-```
-
-Use the same pattern for `company_connect.js`, `candidate_connect.js`, or internal `auth/v1/service_connect.js` as needed.
-
-## Regenerate (maintainers)
-
-From this directory:
-
-```bash
-npm install
-npx buf generate
-```
-
-This refreshes **Go** output under `gen/` and **TypeScript** under `gen/ts/`. Commit both when APIs change.
-
-## Publish
-
-1. Bump `"version"` in `package.json`.
-2. `npm login` (npmjs.com account with permission to publish the `@in-human-resources` scope).
-3. **npm requires 2FA to publish** (or a [granular access token](https://docs.npmjs.com/about-access-tokens) with publish rights). Enable 2FA on [npm account settings](https://www.npmjs.com/settings/~/auth) (Authorization and publishing), or create a token with “Bypass two-factor authentication” if your org allows it.
-4. From `proto/`:
-
-   ```bash
-   npm publish
-   ```
-
-   `publishConfig.access` is set to `public` in `package.json` for this scoped package.
-
-## Layout
-
-| Path        | Contents                                      |
-|------------|-----------------------------------------------|
-| `gen/`     | Go protobuf + gRPC (`paths=source_relative`) |
-| `gen/ts/`  | `*_pb.ts` (messages) and `*_connect.ts` (Connect services) |
+# `@in-human-resources/backend-proto`
+
+Published npm package: **Protobuf-ES** message types and **Connect-ES** service stubs for `api.v1`, `auth.v1`, and `common.v1`.
+
+## Install
+
+```bash
+npm install @in-human-resources/backend-proto
+```
+
+Peer dependencies (install in your app):
+
+```bash
+npm install @bufbuild/protobuf @connectrpc/connect
+```
+
+For browsers you may also use `@connectrpc/connect-web`.
+
+## Usage
+
+Import Connect service definitions and create a client (example: gateway `api.v1`):
+
+```typescript
+import { createClient } from '@connectrpc/connect';
+import { createGrpcTransport } from '@connectrpc/connect-node';
+import { AuthService } from '@in-human-resources/backend-proto/gen/ts/api/v1/auth_connect';
+
+const transport = createGrpcTransport({ baseUrl: 'http://localhost:8082', httpVersion: '2' });
+export const authClient = createClient(AuthService, transport);
+```
+
+Use the same pattern for `company_connect`, `candidate_connect`, or internal `auth/v1/service_connect` (extensionless so Next/Turbopack can resolve the published `.ts` files).
+
+> **Note:** Code is generated with `import_extension=none` so local imports inside `gen/ts` omit `.js`. The package only publishes TypeScript under `gen/ts` (not precompiled `.js`); a `.js` suffix in import specifiers is incorrect for that layout.
+
+## Source `.proto` files (contract reference)
+
+The package ships the **original Protobuf schemas** next to generated code so you can read RPCs and messages without leaving `node_modules`:
+
+| Location in the package | Contents |
+|-------------------------|----------|
+| `api/v1/*.proto` | Public gateway API (`AuthService`, `CompanyService`, `CandidateService`, shared types) |
+| `auth/v1/service.proto` | Internal auth service (`auth.v1.AuthService`) |
+| `common/v1/common.proto` | Shared `common.v1` messages |
+
+Example path after install:
+
+`node_modules/@in-human-resources/backend-proto/api/v1/auth.proto`
+
+`buf.yaml` / `buf.gen.yaml` are included for Buf-based tooling if you point at this folder as a module.
+
+## Regenerate (maintainers)
+
+From this directory:
+
+```bash
+npm install
+npx buf generate
+```
+
+This refreshes **Go** output under `gen/` and **TypeScript** under `gen/ts/`. Commit both when APIs change.
+
+## Publish
+
+1. Bump `"version"` in `package.json`.
+2. `npm login` (npmjs.com account with permission to publish the `@in-human-resources` scope).
+3. **npm requires 2FA to publish** (or a [granular access token](https://docs.npmjs.com/about-access-tokens) with publish rights). Enable 2FA on [npm account settings](https://www.npmjs.com/settings/~/auth) (Authorization and publishing), or create a token with “Bypass two-factor authentication” if your org allows it.
+4. From `proto/`:
+
+   ```bash
+   npm publish
+   ```
+
+   `publishConfig.access` is set to `public` in `package.json` for this scoped package.
+
+## What ships on npm
+
+| Path | Contents |
+|------|----------|
+| `gen/ts/` | Generated TypeScript (`*_pb.ts`, `*_connect.ts`) |
+| `api/`, `auth/`, `common/` | **Source `.proto` files** (API contract) |
+| `buf.yaml`, `buf.gen.yaml` | Buf module + codegen config |
+
+Go stubs under `gen/*.go` are **not** published (they stay in the git repo for the backend workspace only).

package/api/v1/README.md

@@ -0,0 +1,282 @@
+# API Gateway - Client-Facing gRPC Services
+
+This directory contains the **client-facing gRPC service definitions** that mobile and web applications use to communicate with the backend.
+
+## Architecture Overview
+
+The API gateway follows a **two-layer proto pattern**:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Mobile/Web Clients (gRPC)                              │
+│  - Type-safe generated stubs                            │
+│  - Kotlin, Swift, TypeScript                            │
+└───────────────────────┬─────────────────────────────────┘
+                        │
+                        │ gRPC (proto/api/v1/*.proto)
+                        │ Port: 8082
+                        ▼
+┌─────────────────────────────────────────────────────────┐
+│  API Gateway (BFF)                                      │
+│  - Authentication/validation                            │
+│  - Rate limiting                                        │
+│  - Request logging                                      │
+│  - Metrics collection                                   │
+└───────────────────────┬─────────────────────────────────┘
+                        │
+                        │ gRPC (proto/auth/v1/service.proto)
+                        │
+                        ▼
+┌─────────────────────────────────────────────────────────┐
+│  Backend Services                                       │
+│  - Auth Service (port 9091)                             │
+│  - Future: Jobs, Workflows, etc.                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Why Two Proto Layers?
+
+### Layer 1: Client-Facing API (`proto/api/v1/`)
+- **Purpose**: Public contract for mobile/web clients
+- **Location**: This directory
+- **Features**:
+  - Simplified, client-friendly message formats
+  - Versioned (`/api/v1`, `/api/v2`)
+  - Can aggregate multiple backend calls
+  - Stable interface that doesn't change with backend refactors
+
+### Layer 2: Internal Backend (`proto/auth/v1/service.proto`)
+- **Purpose**: Internal service-to-service communication
+- **Location**: `proto/<service>/v1/`
+- **Features**:
+  - Domain-specific logic
+  - Can evolve independently
+  - Optimized for backend needs
+
+## Services
+
+### AuthService (`auth.proto`)
+Handles all authentication and user management operations:
+- Registration & Login
+- Token refresh & logout
+- Email verification
+- Password management
+- Profile management
+- Session management
+- OAuth integration
+
+**Public methods** (no auth required):
+- `Register`, `Login`, `RefreshToken`
+- `VerifyEmail`, `ResendVerificationEmail`
+- `RequestPasswordReset`, `ResetPassword`
+- `OAuthLogin`, `OAuthCallback`
+
+**Protected methods** (require auth token in metadata):
+- All other methods
+
+### CompanyService (`company.proto`)
+Manages company profiles and team members:
+- Company CRUD operations
+- Team member management
+- Company onboarding flow
+
+### CandidateService (`candidate.proto`)
+Manages candidate profiles and job applications:
+- Profile management
+- Skills & experience
+- Job preferences
+- Application readiness checks
+- Candidate onboarding flow
+
+## Client Integration
+
+### Mobile (Kotlin)
+
+```kotlin
+import io.grpc.ManagedChannelBuilder
+import com.inhuman.backend.apiv1.AuthServiceGrpc
+import com.inhuman.backend.apiv1.RegisterRequest
+
+// Create channel
+val channel = ManagedChannelBuilder
+    .forAddress("api.example.com", 8082)
+    .useTransportSecurity()
+    .build()
+
+// Create client stub
+val authClient = AuthServiceGrpc.newBlockingStub(channel)
+
+// Make request
+val response = authClient.register(
+    RegisterRequest.newBuilder()
+        .setEmail("user@example.com")
+        .setPassword("secret")
+        .setName("John Doe")
+        .setUserType("candidate")
+        .build()
+)
+
+println("Access token: ${response.accessToken}")
+```
+
+### Web (TypeScript with grpc-web)
+
+```typescript
+import { AuthServiceClient } from './proto/api/v1/auth_grpc_web_pb';
+import { RegisterRequest } from './proto/api/v1/auth_pb';
+
+// Create client
+const client = new AuthServiceClient('https://api.example.com:8082');
+
+// Make request
+const request = new RegisterRequest();
+request.setEmail('user@example.com');
+request.setPassword('secret');
+request.setName('John Doe');
+request.setUserType('candidate');
+
+client.register(request, {}, (err, response) => {
+  if (err) {
+    console.error(err);
+  } else {
+    console.log('Access token:', response.getAccessToken());
+  }
+});
+```
+
+## Authentication
+
+Protected RPCs require a bearer token in the gRPC metadata:
+
+```kotlin
+// Kotlin
+val metadata = Metadata()
+metadata.put(
+    Metadata.Key.of("authorization", Metadata.ASCII_STRING_MARSHALLER),
+    "Bearer $accessToken"
+)
+val stub = authClient.withInterceptors(MetadataUtils.newAttachHeadersInterceptor(metadata))
+```
+
+```typescript
+// TypeScript
+const metadata = {
+  'authorization': `Bearer ${accessToken}`
+};
+client.getProfile(request, metadata, callback);
+```
+
+## Error Handling
+
+The gateway returns standard gRPC status codes:
+
+| Code | Meaning | Common Causes |
+|------|---------|---------------|
+| `OK` (0) | Success | Request completed successfully |
+| `INVALID_ARGUMENT` (3) | Bad request | Missing required fields, invalid format |
+| `UNAUTHENTICATED` (16) | Auth required | Missing or invalid token |
+| `PERMISSION_DENIED` (7) | Forbidden | User lacks permission |
+| `NOT_FOUND` (5) | Not found | Resource doesn't exist |
+| `ALREADY_EXISTS` (6) | Conflict | Duplicate email, etc. |
+| `RESOURCE_EXHAUSTED` (8) | Rate limited | Too many requests |
+| `INTERNAL` (13) | Server error | Unexpected backend error |
+
+## Rate Limiting
+
+The gateway enforces rate limits per client IP:
+- **Default**: 100 requests/second per IP
+- **Burst**: 20 additional requests allowed
+- **Response**: `RESOURCE_EXHAUSTED` (code 8) when exceeded
+
+## Monitoring
+
+### Health Checks (HTTP)
+- `GET http://api.example.com:8083/health` - Liveness probe
+- `GET http://api.example.com:8083/readyz` - Readiness probe (checks Redis)
+
+### Metrics (Prometheus)
+- `GET http://api.example.com:8083/metrics`
+
+Metrics exposed:
+- `grpc_requests_total{method, code}` - Total requests
+- `grpc_request_duration_seconds{method}` - Request latency
+- `grpc_requests_in_flight` - Current concurrent requests
+
+## Development
+
+### Generating Client Code
+
+**Go** (server):
+```bash
+make proto-gen
+```
+
+**Kotlin** (Android):
+```bash
+protoc --kotlin_out=app/src/main/java \
+       --grpc-kotlin_out=app/src/main/java \
+       proto/api/v1/*.proto
+```
+
+**Swift** (iOS):
+```bash
+protoc --swift_out=Sources \
+       --grpc-swift_out=Sources \
+       proto/api/v1/*.proto
+```
+
+**TypeScript** (Web):
+```bash
+protoc --js_out=import_style=commonjs:src \
+       --grpc-web_out=import_style=typescript,mode=grpcwebtext:src \
+       proto/api/v1/*.proto
+```
+
+### Testing
+
+Use `grpcurl` to test endpoints:
+
+```bash
+# Public endpoint (no auth)
+grpcurl -plaintext \
+  -d '{"email":"test@example.com","password":"secret","name":"Test","user_type":"candidate"}' \
+  localhost:8082 \
+  api.v1.AuthService/Register
+
+# Protected endpoint (with auth)
+grpcurl -plaintext \
+  -H "authorization: Bearer $TOKEN" \
+  localhost:8082 \
+  api.v1.AuthService/GetProfile
+```
+
+## Versioning Strategy
+
+- **Current**: `api.v1` (stable)
+- **Future**: `api.v2` (when breaking changes needed)
+
+Breaking changes require a new version. Non-breaking changes can be added to v1:
+- ✅ Adding new RPCs
+- ✅ Adding optional fields
+- ✅ Adding new enum values (with default handling)
+- ❌ Removing RPCs
+- ❌ Removing fields
+- ❌ Changing field types
+
+## Benefits of gRPC
+
+Compared to REST/JSON:
+
+1. **Type Safety**: Generated stubs catch errors at compile time
+2. **Performance**: Binary protobuf is 3-10x smaller than JSON
+3. **Streaming**: Supports bidirectional streaming (future use)
+4. **Auto-completion**: IDEs provide full method/field completion
+5. **Consistency**: Same types across all platforms
+6. **Versioning**: Explicit version in package name
+
+## Next Steps
+
+- [ ] Add streaming support for real-time features
+- [ ] Implement gRPC reflection for dynamic discovery
+- [ ] Add OpenTelemetry tracing
+- [ ] Create client SDKs for each platform

package/api/v1/auth.proto

@@ -0,0 +1,228 @@
+syntax = "proto3";
+
+package api.v1;
+
+option go_package = "github.com/InHuman-Resources/Backend/Go/proto/gen/api/v1;apiv1";
+
+import "api/v1/common.proto";
+
+// AuthService is the client-facing authentication service.
+// Mobile and web clients call these RPCs directly.
+service AuthService {
+  // Core authentication
+  rpc Register(RegisterRequest) returns (RegisterResponse);
+  rpc Login(LoginRequest) returns (LoginResponse);
+  rpc RefreshToken(RefreshTokenRequest) returns (RefreshTokenResponse);
+  rpc Logout(LogoutRequest) returns (Empty);
+  
+  // Email verification
+  rpc VerifyEmail(VerifyEmailRequest) returns (Empty);
+  rpc ResendVerificationEmail(ResendVerificationEmailRequest) returns (Empty);
+  rpc SendEmailVerificationOtp(SendEmailVerificationOtpRequest) returns (Empty);
+  rpc VerifyEmailWithOtp(VerifyEmailWithOtpRequest) returns (Empty);
+  
+  // Password management
+  rpc RequestPasswordReset(RequestPasswordResetRequest) returns (Empty);
+  rpc ResetPassword(ResetPasswordRequest) returns (Empty);
+  rpc ChangePassword(ChangePasswordRequest) returns (Empty);
+  
+  // Profile
+  rpc GetProfile(GetProfileRequest) returns (GetProfileResponse);
+  rpc UpdateProfile(UpdateProfileRequest) returns (Empty);
+  
+  // Sessions
+  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse);
+  rpc RevokeSession(RevokeSessionRequest) returns (Empty);
+  rpc RevokeAllSessions(RevokeAllSessionsRequest) returns (Empty);
+  
+  // OAuth
+  rpc OAuthLogin(OAuthLoginRequest) returns (OAuthLoginResponse);
+  rpc OAuthCallback(OAuthCallbackRequest) returns (OAuthCallbackResponse);
+  rpc LinkOAuthAccount(LinkOAuthAccountRequest) returns (Empty);
+  rpc UnlinkOAuthAccount(UnlinkOAuthAccountRequest) returns (Empty);
+}
+
+// ==================== Core Authentication ====================
+
+message RegisterRequest {
+  string email = 1;
+  string password = 2;
+  string name = 3;
+  string user_type = 4;  // "company" or "candidate"
+  string professional_headline = 5;  // Required for candidates
+  string company_invite_token = 6; // optional; company invites when user_type=company
+  RequestContext context = 10;
+}
+
+message RegisterResponse {
+  string user_id = 1;
+  string access_token = 2;
+  string refresh_token = 3;
+  string user_type = 4;
+  bool email_verified = 5;
+  ProfileCompletion profile_completion = 6;
+  string onboarding_step = 7;
+  bool onboarding_complete = 8;
+}
+
+message LoginRequest {
+  string email = 1;
+  string password = 2;
+  RequestContext context = 10;
+}
+
+message LoginResponse {
+  string user_id = 1;
+  string access_token = 2;
+  string refresh_token = 3;
+  string user_type = 4;
+  string company_id = 5;
+  string hierarchy_level = 6;
+  string department = 7;
+  bool email_verified = 8;
+  string onboarding_status = 9;
+  string onboarding_step = 10;
+  bool onboarding_complete = 11;
+}
+
+message RefreshTokenRequest {
+  string refresh_token = 1;
+}
+
+message RefreshTokenResponse {
+  string user_id = 1;
+  string access_token = 2;
+  string refresh_token = 3;
+  string user_type = 4;
+  string company_id = 5;
+  string hierarchy_level = 6;
+  string department = 7;
+  bool email_verified = 8;
+  string onboarding_status = 9;
+  string onboarding_step = 10;
+  bool onboarding_complete = 11;
+}
+
+message LogoutRequest {
+  // Session ID is extracted from auth token in interceptor
+}
+
+// ==================== Email Verification ====================
+
+message VerifyEmailRequest {
+  string token = 1;
+}
+
+message ResendVerificationEmailRequest {
+  string email = 1;
+}
+
+message SendEmailVerificationOtpRequest {
+  string email = 1;
+}
+
+message VerifyEmailWithOtpRequest {
+  string email = 1;
+  string code = 2;
+}
+
+// ==================== Password Management ====================
+
+message RequestPasswordResetRequest {
+  string email = 1;
+}
+
+message ResetPasswordRequest {
+  string token = 1;
+  string new_password = 2;
+}
+
+message ChangePasswordRequest {
+  string old_password = 1;
+  string new_password = 2;
+  // User ID is extracted from auth token in interceptor
+}
+
+// ==================== Profile ====================
+
+message GetProfileRequest {
+  // User ID is extracted from auth token in interceptor
+}
+
+message GetProfileResponse {
+  string user_id = 1;
+  string email = 2;
+  string name = 3;
+  string user_type = 4;
+  string company_id = 5;
+  string company_name = 6;
+  string hierarchy_level = 7;
+  string department = 8;
+  bool email_verified = 9;
+  string created_at = 10;
+}
+
+message UpdateProfileRequest {
+  string name = 1;
+  // User ID is extracted from auth token in interceptor
+}
+
+// ==================== Sessions ====================
+
+message ListSessionsRequest {
+  // User ID is extracted from auth token in interceptor
+}
+
+message ListSessionsResponse {
+  repeated SessionInfo sessions = 1;
+}
+
+message RevokeSessionRequest {
+  string session_id = 1;
+  // User ID is extracted from auth token in interceptor
+}
+
+message RevokeAllSessionsRequest {
+  // User ID is extracted from auth token in interceptor
+}
+
+// ==================== OAuth ====================
+
+message OAuthLoginRequest {
+  string provider = 1;  // "google", "github", "linkedin", etc.
+}
+
+message OAuthLoginResponse {
+  string redirect_url = 1;
+}
+
+message OAuthCallbackRequest {
+  string provider = 1;
+  string code = 2;
+  string state = 3;
+}
+
+message OAuthCallbackResponse {
+  string user_id = 1;
+  string access_token = 2;
+  string refresh_token = 3;
+  string user_type = 4;
+  string company_id = 5;
+  string hierarchy_level = 6;
+  string department = 7;
+  bool email_verified = 8;
+  string onboarding_status = 9;
+  string onboarding_step = 10;
+  bool onboarding_complete = 11;
+}
+
+message LinkOAuthAccountRequest {
+  string provider = 1;
+  string code = 2;
+  // User ID is extracted from auth token in interceptor
+}
+
+message UnlinkOAuthAccountRequest {
+  string provider = 1;
+  // User ID is extracted from auth token in interceptor
+}