@in-human-resources/backend-proto 0.1.2 → 0.1.4

package/README.md

@@ -1,82 +1,85 @@
-# `@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.
-
-## 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).
+# `@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`, `HiringService`, shared types) |
+| `auth/v1/service.proto` | Internal auth service (`auth.v1.AuthService`) |
+| `hiring/v1/service.proto` | Private hiring service (`hiring.v1.HiringService`) |
+| `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 the repository root:
+
+```bash
+(cd proto && npm ci) # first time or after dependency changes
+make proto-gen
+```
+
+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/`, `hiring/`, `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/auth.proto

@@ -4,10 +4,19 @@ package api.v1;
 
 option go_package = "github.com/InHuman-Resources/Backend/Go/proto/gen/api/v1;apiv1";
 
+// api.v1 versioning: prefer additive field/RPC changes; never renumber fields. A future
+// api.v2 would be a breaking, coordinated release. See proto/AGENTS.md and ROADMAP.md.
+
 import "api/v1/common.proto";
 
-// AuthService is the client-facing authentication service.
-// Mobile and web clients call these RPCs directly.
+// AuthService — public identity and session edge for product clients.
+//
+// Business context: registration and login (credentials + OAuth), email verification,
+// password lifecycle, session listing/revocation, and basic profile reads/updates on the
+// gateway. Permission and role truth beyond the token remains in auth-service; hiring
+// and other domains enforce their own authorization.
+//
+// Clients call only through the API gateway with Bearer tokens on protected RPCs.
 service AuthService {
   // Core authentication
   rpc Register(RegisterRequest) returns (RegisterResponse);

package/api/v1/candidate.proto

@@ -4,9 +4,16 @@ package api.v1;
 
 option go_package = "github.com/InHuman-Resources/Backend/Go/proto/gen/api/v1;apiv1";
 
+// api.v1 versioning: prefer additive field/RPC changes; never renumber fields.
+
 import "api/v1/common.proto";
 
-// CandidateService is the client-facing candidate profile service.
+// CandidateService — candidate profile, skills, experience, and onboarding.
+//
+// Business context: profile CRUD, application-readiness hints, and step-based candidate
+// onboarding. Canonical hiring applications and stages live under HiringService, not here.
+// Next upgrades: richer profile or assessment-prep fields should be additive; hiring
+// artifacts (applications) stay on HiringService.
 service CandidateService {
   // Profile management
   rpc GetCandidateProfile(GetCandidateProfileRequest) returns (CandidateProfileResponse);

package/api/v1/common.proto

@@ -4,6 +4,9 @@ package api.v1;
 
 option go_package = "github.com/InHuman-Resources/Backend/Go/proto/gen/api/v1;apiv1";
 
+// Shared api.v1 types. Versioning: add fields with new tags only; do not rename or
+// repurpose existing fields without a breaking-change process.
+
 // RequestContext contains metadata about the client request.
 // This is optional and can be used for idempotency, tracing, etc.
 message RequestContext {

package/api/v1/company.proto

@@ -4,9 +4,16 @@ package api.v1;
 
 option go_package = "github.com/InHuman-Resources/Backend/Go/proto/gen/api/v1;apiv1";
 
+// api.v1 versioning: prefer additive field/RPC changes; never renumber fields.
+
 import "api/v1/common.proto";
 
-// CompanyService is the client-facing company management service.
+// CompanyService — company profile, membership, and onboarding for company users.
+//
+// Business context: company record updates, member invites and roles, and step-based
+// company onboarding aligned with auth-owned onboarding state. Not hiring pipeline data.
+// Next upgrades: new onboarding steps or compliance fields should be added as optional
+// fields or new RPCs; avoid breaking existing mobile/web clients without a version bump plan.
 service CompanyService {
   // Company CRUD
   rpc GetCompany(GetCompanyRequest) returns (GetCompanyResponse);

package/api/v1/hiring.proto

@@ -0,0 +1,326 @@
+syntax = "proto3";
+
+package api.v1;
+
+option go_package = "github.com/InHuman-Resources/Backend/Go/proto/gen/api/v1;apiv1";
+
+// =============================================================================
+// api.v1 public contract — versioning and evolution (HiringService)
+// =============================================================================
+// Clients (web, mobile) MUST call only this package via the API gateway. Do not
+// import or call private hiring.v1 from product apps.
+//
+// Evolution policy until a deliberate major bump:
+// - Prefer additive changes only: new optional fields, new RPCs. Never renumber or
+//   recycle field tags; reserve deprecated fields if you must stop using them.
+// - Run `make proto-gen` and buf breaking change checks before releases that alter
+//   protos (see proto/AGENTS.md).
+// - Next upgrades (roadmap): workflow orchestration may cause the gateway to perform
+//   additional side effects (e.g. signal Temporal) on some RPCs while keeping the
+//   same api.v1 signatures; auth-sensitive operations may gain stricter permission
+//   errors from the hiring service without contract changes.
+// - A future api.v2 would only be introduced for incompatible reshapes (new service
+//   splits, renamed RPCs); until then, extend api.v1 additively.
+
+// HiringService — public hiring surface for the product.
+//
+// Business context: companies create and publish jobs; candidates discover open
+// roles and apply; recruiters manage the pipeline (stages, decisions, screening
+// outcomes, interviews, assessment links, offers). Authoritative state lives in the
+// hiring service; the gateway authenticates and forwards; authorization is enforced
+// downstream (company tenant vs candidate).
+service HiringService {
+  // Recruiter: create an internal draft job for the authenticated company.
+  rpc CreateJob(CreateJobRequest) returns (CreateJobResponse);
+  // Recruiter: make a draft job visible to candidates (requires public_slug set server-side).
+  rpc PublishJob(PublishJobRequest) returns (PublishJobResponse);
+  // Candidate: submit an application to a published job (idempotent per candidate+job server-side).
+  rpc ApplyToJob(ApplyToJobRequest) returns (ApplyToJobResponse);
+
+  // Read job details. Published jobs are visible broadly; drafts only to owning company.
+  rpc GetJob(GetJobRequest) returns (GetJobResponse);
+  // Read application — candidate sees own; company sees applications for their jobs.
+  rpc GetApplication(GetApplicationRequest) returns (GetApplicationResponse);
+
+  // Recruiter: paginated jobs for the current company (optional status filter).
+  rpc ListJobs(ListJobsRequest) returns (ListJobsResponse);
+  // Published job search (e.g. job board). Authenticated; filter by query string.
+  rpc SearchJobs(SearchJobsRequest) returns (SearchJobsResponse);
+  // Recruiter: update editable fields on a company-owned job.
+  rpc UpdateJob(UpdateJobRequest) returns (UpdateJobResponse);
+  // Recruiter: stop accepting new applications for a job.
+  rpc CloseJob(CloseJobRequest) returns (CloseJobResponse);
+
+  // Candidate: all applications for the token user (pagination).
+  rpc ListMyApplications(ListMyApplicationsRequest) returns (ListMyApplicationsResponse);
+  // Recruiter: company-wide application inbox across jobs (filters optional).
+  rpc ListApplications(ListApplicationsRequest) returns (ListApplicationsResponse);
+  // Recruiter: applications for one job (must own the job).
+  rpc ListApplicationsForJob(ListApplicationsForJobRequest) returns (ListApplicationsForJobResponse);
+
+  // Recruiter: move pipeline stage following the server’s allowed transition graph; append-only audit.
+  // Future: gateway may also trigger workflow signals; hiring remains source of truth for stage.
+  rpc TransitionApplicationStage(TransitionApplicationStageRequest) returns (TransitionApplicationStageResponse);
+  // Recruiter: record a structured human decision (approve/reject/etc.) with reasoning.
+  rpc RecordRecruiterDecision(RecordRecruiterDecisionRequest) returns (RecordRecruiterDecisionResponse);
+  // Recruiter: store hiring-owned screening summary (scores/explanation/skills); not the AI model.
+  rpc RecordScreeningResult(RecordScreeningResultRequest) returns (RecordScreeningResultResponse);
+  // Recruiter: attach interview facts (times, notes, transcript ref, structured scores JSON).
+  rpc RecordInterview(RecordInterviewRequest) returns (RecordInterviewResponse);
+  // Recruiter: link an external assessment id and status/score summary; assessment content lives elsewhere.
+  rpc LinkAssessment(LinkAssessmentRequest) returns (LinkAssessmentResponse);
+  // Recruiter: create/update offer terms and status for an application.
+  rpc RecordOffer(RecordOfferRequest) returns (RecordOfferResponse);
+
+  // Audit/history timeline for one application (candidate or owning company).
+  rpc ListApplicationEvents(ListApplicationEventsRequest) returns (ListApplicationEventsResponse);
+}
+
+message PageRequest {
+  int32 page_size = 1;
+  string page_token = 2;
+}
+
+message PageResponse {
+  string next_page_token = 1;
+}
+
+message CreateJobRequest {
+  string title = 1;
+  string description = 2;
+  string public_slug = 3;
+}
+
+message CreateJobResponse {
+  string job_id = 1;
+}
+
+message PublishJobRequest {
+  string job_id = 1;
+}
+
+message PublishJobResponse {
+  string status = 1;
+}
+
+message ApplyToJobRequest {
+  string job_id = 1;
+}
+
+message ApplyToJobResponse {
+  string application_id = 1;
+}
+
+message GetJobRequest {
+  string job_id = 1;
+}
+
+message Job {
+  string job_id = 1;
+  string company_id = 2;
+  string title = 3;
+  string description = 4;
+  string status = 5;
+  string public_slug = 6;
+  string requirements = 7;
+  string team_metadata_json = 8;
+  string created_at = 9;
+  string updated_at = 10;
+}
+
+message GetJobResponse {
+  string job_id = 1;
+  string company_id = 2;
+  string title = 3;
+  string description = 4;
+  string status = 5;
+  string public_slug = 6;
+  string requirements = 7;
+  string team_metadata_json = 8;
+  string created_at = 9;
+  string updated_at = 10;
+}
+
+message ListJobsRequest {
+  string status_filter = 1;
+  PageRequest page = 2;
+}
+
+message ListJobsResponse {
+  repeated Job jobs = 1;
+  PageResponse page = 2;
+}
+
+message SearchJobsRequest {
+  string query = 1;
+  PageRequest page = 2;
+}
+
+message SearchJobsResponse {
+  repeated Job jobs = 1;
+  PageResponse page = 2;
+}
+
+message UpdateJobRequest {
+  string job_id = 1;
+  string title = 2;
+  string description = 3;
+  string public_slug = 4;
+  string requirements = 5;
+  string team_metadata_json = 6;
+}
+
+message UpdateJobResponse {
+  Job job = 1;
+}
+
+message CloseJobRequest {
+  string job_id = 1;
+}
+
+message CloseJobResponse {
+  string status = 1;
+}
+
+message Application {
+  string application_id = 1;
+  string job_id = 2;
+  string candidate_user_id = 3;
+  string current_stage = 4;
+  string applied_at = 5;
+  string job_title = 6;
+  string company_id = 7;
+}
+
+message GetApplicationRequest {
+  string application_id = 1;
+}
+
+message GetApplicationResponse {
+  string application_id = 1;
+  string job_id = 2;
+  string candidate_user_id = 3;
+  string current_stage = 4;
+  string applied_at = 5;
+  string requirements = 6;
+  string team_metadata_json = 7;
+}
+
+message ListMyApplicationsRequest {
+  PageRequest page = 1;
+}
+
+message ListMyApplicationsResponse {
+  repeated Application applications = 1;
+  PageResponse page = 2;
+}
+
+message ListApplicationsRequest {
+  string status_filter = 1;
+  string stage_filter = 2;
+  PageRequest page = 3;
+}
+
+message ListApplicationsResponse {
+  repeated Application applications = 1;
+  PageResponse page = 2;
+}
+
+message ListApplicationsForJobRequest {
+  string job_id = 1;
+  PageRequest page = 2;
+}
+
+message ListApplicationsForJobResponse {
+  repeated Application applications = 1;
+  PageResponse page = 2;
+}
+
+message TransitionApplicationStageRequest {
+  string application_id = 1;
+  string target_stage = 2;
+  string reason = 3;
+}
+
+message TransitionApplicationStageResponse {
+  string current_stage = 1;
+}
+
+message RecordRecruiterDecisionRequest {
+  string application_id = 1;
+  string stage_context = 2;
+  string outcome = 3;
+  string reasoning = 4;
+}
+
+message RecordRecruiterDecisionResponse {
+  string decision_id = 1;
+}
+
+message RecordScreeningResultRequest {
+  string application_id = 1;
+  double score = 2;
+  string explanation = 3;
+  string skill_extractions_json = 4;
+  string source_model_id = 5;
+  string raw_output_ref = 6;
+}
+
+message RecordScreeningResultResponse {
+  string screening_result_id = 1;
+}
+
+message RecordInterviewRequest {
+  string application_id = 1;
+  string scheduled_at = 2;
+  string actual_at = 3;
+  string notes = 4;
+  string transcript_ref = 5;
+  string structured_scores_json = 6;
+}
+
+message RecordInterviewResponse {
+  string interview_record_id = 1;
+}
+
+message LinkAssessmentRequest {
+  string application_id = 1;
+  string external_assessment_id = 2;
+  string status = 3;
+  string score_summary = 4;
+}
+
+message LinkAssessmentResponse {
+  string assessment_link_id = 1;
+}
+
+message RecordOfferRequest {
+  string application_id = 1;
+  string terms = 2;
+  string status = 3;
+}
+
+message RecordOfferResponse {
+  string offer_id = 1;
+}
+
+message ApplicationEvent {
+  string event_id = 1;
+  string application_id = 2;
+  string from_stage = 3;
+  string to_stage = 4;
+  string actor_type = 5;
+  string actor_user_id = 6;
+  string metadata_json = 7;
+  string created_at = 8;
+}
+
+message ListApplicationEventsRequest {
+  string application_id = 1;
+  PageRequest page = 2;
+}
+
+message ListApplicationEventsResponse {
+  repeated ApplicationEvent events = 1;
+  PageResponse page = 2;
+}