protobuf-platform 1.2.619 → 1.2.624

package/AGENTS.md

@@ -0,0 +1,12 @@
+# protobuf-platform: contract repository
+
+- Repository directory: `protobuf`; npm package: `protobuf-platform`. Work on `main`, never `staging`. This is a contract package, not a running service; it owns no database, queues or migrations.
+- Inspect this repository first for every business master task. Reuse existing contracts when sufficient and record `PROTOBUF_CHANGE_NOT_REQUIRED` when no change is needed.
+- A new/material contract decision needs `PROTOBUF_CHANGE_APPROVAL_REQUIRED` and `APPROVE_PROTOBUF_CHANGE` unless the master task already explicitly approved it. Include exact contract, insufficiency, compatibility and affected repositories. Contract work precedes dependent service implementation.
+- Sources are domain `*.proto` files; `update_protobuf.sh` writes colocated `*_pb.js` and `*_grpc_pb.js`; `index.js` exports domain bindings.
+- npm with `package-lock.json`; generated output is CommonJS. Run `npm run proto:build`, inspect generated diff, and review old/new producer-consumer compatibility (field tags/types, optional/default behavior, enum values, RPC methods and exports). Fix Critical/Medium findings before committing.
+- The build script uses `~/node-x64/bin/npm`; `proto:build:x64` uses `~/node-v22.21.1-darwin-x64/bin/npm`. Verify the selected local runtime and grpc-tools binary. `proto:install:x64` deletes node_modules AND the lockfile: it is a recovery script, not ordinary dependency installation.
+- For a contract release, prepare one version bump with `npm version patch --no-git-tag-version` (or the already-approved version), verify package.json and package-lock.json agree, review generated/package contents, and create a local atomic commit including version files. Avoid a second bump if already prepared.
+- Stop with `MANUAL_PROTOBUF_PUBLISH_REQUIRED`; the sole remaining publication command, run by the human in this repository, is `npm publish`. Do not execute it or `npm run publish-update` (which combines bump and publication).
+- Wait for `PROTOBUF_PUBLISHED`, then resume the same master task and verify downstream package/lockfile resolution before dependent implementation. Never publish automatically.
+- package.json has no lint command; its test script is a failing placeholder. For documentation-only edits use diff/link review; generation is required when contracts change, not for editing these instructions.

package/CLAUDE.md

@@ -1,176 +1,3 @@
-# CLAUDE.md
+# Repository instructions
 
-## Service scope
-
-This repository is a standalone Node.js microservice in a B2B iGaming platform.
-It communicates via RPC (gRPC) and RabbitMQ events.
-
----
-
-## Hard stop rules (non-negotiable)
-
-If a request violates any rule in this document, you MUST:
-
-- Refuse to perform the request as stated.
-- Explicitly state which rule(s) would be violated.
-- Propose a compliant alternative that respects all rules.
-
-If a request implies ANY of the following:
-
-- large refactors,
-- rewrites,
-- technology or language changes,
-- introduction or modification of dependencies,
-- new abstractions, base layers, or frameworks,
-- cross-service or repo-wide standardization,
-
-AND this intent is NOT explicitly confirmed by the user in a dedicated request,
-you MUST refuse the request.
-
-You must NOT partially execute, plan, or scaffold such requests.
-
-You must NOT:
-
-- Perform or plan large refactors when minimal diff is required.
-- Introduce, modify, or remove dependencies by default.
-- Add dependencies even if the prompt suggests them.
-- Change the module system or language (CommonJS ↔ ESM ↔ TypeScript).
-- Create new files, base classes, wrappers, or frameworks unless explicitly requested.
-- Reorganize folders or rename modules unless explicitly requested.
-- Execute or suggest commands (npm install, migrations, scaffolding, etc.) unless explicitly requested.
-
----
-
-## Response quality rules (non-negotiable)
-
-- Produce production-grade solutions only.
-- Prefer clarity over cleverness.
-- Minimal but complete: implement only what is strictly required to solve the problem.
-- Avoid speculative code, abstractions, or future-proofing.
-- Keep structure simple and easy to understand.
-- When multiple approaches exist, choose the simplest effective one.
-- Respond with plain code blocks only, unless an explanation is explicitly requested.
-
----
-
-## Non-negotiables
-
-- Do NOT change public contracts (RPC signatures, event payload fields, routing keys) unless explicitly requested.
-- Prefer minimal diffs: the smallest possible change that fixes the issue.
-- Dependencies changes always require explicit confirmation in a separate request.
-- All comments must be concise, in English, and JSDoc-style only when a comment is necessary.
-- Error handling must be deterministic: every consumed message MUST end with ACK or NACK by design.
-- Business logic correctness and data consistency take precedence over code aesthetics.
-
----
-
-## Runtime & module system
-
-- Default module system is CommonJS (`require`, `module.exports`).
-- ESM (`import`) is allowed ONLY in explicitly marked services or files (e.g. `config` service).
-- Do NOT convert files between CJS and ESM unless explicitly requested.
-
----
-
-## Storage
-
-This service may use one or more of the following:
-
-- MySQL (via Sequelize models)
-- MongoDB (via the existing project driver)
-- Redis (used as source of truth for low-latency vendor responses)
-
-You must NOT:
-
-- Change schemas, migrations, or storage models unless explicitly requested.
-- Introduce cross-storage coupling or abstractions.
-
----
-
-## RabbitMQ policy
-
-- Unknown routing keys MUST be ACKed (avoid poison loops).
-- Errors must be classified explicitly:
-  - Permanent errors (invalid payload, missing required fields, not-null violations, business invariants)
-    → ACK + critical log, NO requeue.
-  - Transient errors (network issues, temporary DB/Redis outage)
-    → NACK with requeue=true or existing retry topology.
-- Infinite requeue for permanent errors is strictly forbidden.
-- All publish/consume changes MUST preserve existing exchanges, queues, routing keys, and contracts.
-
----
-
-## Provider callbacks (if applicable)
-
-- Provider responses MUST accurately reflect processing status.
-- On internal inconsistency or unsafe downstream publish:
-  - Return an error to the provider.
-  - Do NOT silently succeed.
-  - Do NOT update Redis/session state if downstream publish cannot be guaranteed.
-- Prevent state divergence between provider responses, Redis, and downstream consumers.
-
----
-
-## Code style & quality gates
-
-- Follow the shared ESLint and Prettier configurations used across services.
-- Keep compatibility with the existing Node.js runtime version.
-- Avoid unnecessary abstractions, base layers, or “framework-style” code.
-- Readability and predictability are more important than DRY or elegance.
-
----
-
-## Output requirements for AI-generated changes
-
-When generating or editing code:
-
-- Output code in plain code blocks only.
-- List changed file paths explicitly.
-- Do NOT include explanations or commentary unless explicitly requested.
-
-## Allowed (Explicit)
-
-Cursor is allowed to execute the following commands without additional confirmation:
-
-npm run proto:build
-npm version patch --no-git-tag-version
-
-Rationale:
-
-npm run proto:build
-Generates protobuf artifacts locally (deterministic, no external side effects).
-
-npm version patch --no-git-tag-version
-Updates the local package version as part of the protobuf contract change workflow.
-
-These commands are considered safe, deterministic, and required for protobuf development.
-
-Forbidden (Always Manual)
-
-Cursor must NOT execute the following commands under any circumstances:
-
-npm publish
-
-Rationale:
-
-Publishes a global contract to npm
-
-Requires explicit human verification and approval
-
-Must always be executed manually
-
-Enforcement Rule
-
-If a task requires publishing the protobuf package:
-
-Cursor must stop after local generation and version bump
-
-Cursor must explicitly instruct the developer to run npm publish manually
-
-## Execution Restrictions
-
-- The assistant MUST NOT execute any build, lint, test or shell commands.
-- The assistant MUST NOT run npm, yarn, pnpm or any other package manager.
-- The assistant MUST NOT run proto:build or any code generation commands.
-- The assistant is allowed to modify files only.
-- Build, lint and test execution is performed manually by the developer.
+Read [AGENTS.md](AGENTS.md) for canonical repository-local guidance. Shared execution policy lives in Codex Project Rules.

package/bet/bet.proto

@@ -41,6 +41,15 @@ service Bet {
     rpc getWinRates(PaginationRequest) returns (WinRatesResponse);
     rpc getLastWins(PaginationRequest) returns (WinRatesResponse);
     rpc getTopWinByMultiplier(TopWinByMultiplierRequest) returns (WinRateItem);
+
+    // Simulated promotional cards only. The requesting UI must visibly disclose this mode.
+    // Uses limit and zero-based page offset only; never reads or creates real player activity.
+    rpc getPromotionalBigWins(PaginationRequest) returns (WinRatesResponse);
+
+    // Internal configuration management, exposed only through authenticated BackOffice routes.
+    rpc readListPromotionalBigWins(PaginationRequest) returns (PromotionalBigWinItemsResponse);
+    rpc setPromotionalBigWin(PromotionalBigWinRequest) returns (PromotionalBigWinItem);
+    rpc deletePromotionalBigWin(PromotionalBigWinKey) returns (PromotionalBigWinStatusResponse);
 }
 
 message PingRequest { string ping = 1; }
@@ -295,6 +304,41 @@ message WinRatesResponse {
     optional int32 total_pages = 2;
     optional int32 total_items = 3;
 }
+
+// One configuration per canonical game-service game ID; no cross-service DB foreign key.
+message PromotionalBigWinKey {
+    int32 game_id = 1;
+}
+
+// Full create-or-replace configuration, not a partial patch. All values must be supplied.
+// game_id must resolve through game-service before saving. No user or financial identity.
+message PromotionalBigWinRequest {
+    int32 game_id = 1;
+    int32 frequency = 2; // Positive integer selection weight, never a quota or duplicate count.
+    string min_win = 3; // Exact non-negative decimal amount in runtime BaseCurrency.
+    string max_win = 4; // Exact decimal amount >= min_win, using the platform currency scale.
+    optional bool is_active = 5; // Presence required by the service, including explicit false.
+}
+
+message PromotionalBigWinItem {
+    int32 game_id = 1;
+    int32 frequency = 2;
+    string min_win = 3;
+    string max_win = 4;
+    bool is_active = 5;
+    string created_at = 6;
+    string updated_at = 7;
+}
+
+message PromotionalBigWinItemsResponse {
+    repeated PromotionalBigWinItem items = 1;
+    int32 total_pages = 2;
+    int32 total_items = 3;
+}
+
+message PromotionalBigWinStatusResponse {
+    bool success = 1; // Idempotent delete succeeds even when the configuration is already absent.
+}
 // Sport event human-readable info (cached/stored in bet-service DB).
 message SportEventInfo {
     string event_id = 1;

package/bet/bet_grpc_pb.js

@@ -191,6 +191,61 @@ function deserialize_bet_PongResponse(buffer_arg) {
   return bet_pb.PongResponse.deserializeBinary(new Uint8Array(buffer_arg));
 }
 
+function serialize_bet_PromotionalBigWinItem(arg) {
+  if (!(arg instanceof bet_pb.PromotionalBigWinItem)) {
+    throw new Error('Expected argument of type bet.PromotionalBigWinItem');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_bet_PromotionalBigWinItem(buffer_arg) {
+  return bet_pb.PromotionalBigWinItem.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
+function serialize_bet_PromotionalBigWinItemsResponse(arg) {
+  if (!(arg instanceof bet_pb.PromotionalBigWinItemsResponse)) {
+    throw new Error('Expected argument of type bet.PromotionalBigWinItemsResponse');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_bet_PromotionalBigWinItemsResponse(buffer_arg) {
+  return bet_pb.PromotionalBigWinItemsResponse.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
+function serialize_bet_PromotionalBigWinKey(arg) {
+  if (!(arg instanceof bet_pb.PromotionalBigWinKey)) {
+    throw new Error('Expected argument of type bet.PromotionalBigWinKey');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_bet_PromotionalBigWinKey(buffer_arg) {
+  return bet_pb.PromotionalBigWinKey.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
+function serialize_bet_PromotionalBigWinRequest(arg) {
+  if (!(arg instanceof bet_pb.PromotionalBigWinRequest)) {
+    throw new Error('Expected argument of type bet.PromotionalBigWinRequest');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_bet_PromotionalBigWinRequest(buffer_arg) {
+  return bet_pb.PromotionalBigWinRequest.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
+function serialize_bet_PromotionalBigWinStatusResponse(arg) {
+  if (!(arg instanceof bet_pb.PromotionalBigWinStatusResponse)) {
+    throw new Error('Expected argument of type bet.PromotionalBigWinStatusResponse');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_bet_PromotionalBigWinStatusResponse(buffer_arg) {
+  return bet_pb.PromotionalBigWinStatusResponse.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
 function serialize_bet_SegmentedUserRequest(arg) {
   if (!(arg instanceof bet_pb.SegmentedUserRequest)) {
     throw new Error('Expected argument of type bet.SegmentedUserRequest');
@@ -533,6 +588,53 @@ getWinRates: {
     responseSerialize: serialize_bet_WinRateItem,
     responseDeserialize: deserialize_bet_WinRateItem,
   },
+  // Simulated promotional cards only. The requesting UI must visibly disclose this mode.
+// Uses limit and zero-based page offset only; never reads or creates real player activity.
+getPromotionalBigWins: {
+    path: '/bet.Bet/getPromotionalBigWins',
+    requestStream: false,
+    responseStream: false,
+    requestType: bet_pb.PaginationRequest,
+    responseType: bet_pb.WinRatesResponse,
+    requestSerialize: serialize_bet_PaginationRequest,
+    requestDeserialize: deserialize_bet_PaginationRequest,
+    responseSerialize: serialize_bet_WinRatesResponse,
+    responseDeserialize: deserialize_bet_WinRatesResponse,
+  },
+  // Internal configuration management, exposed only through authenticated BackOffice routes.
+readListPromotionalBigWins: {
+    path: '/bet.Bet/readListPromotionalBigWins',
+    requestStream: false,
+    responseStream: false,
+    requestType: bet_pb.PaginationRequest,
+    responseType: bet_pb.PromotionalBigWinItemsResponse,
+    requestSerialize: serialize_bet_PaginationRequest,
+    requestDeserialize: deserialize_bet_PaginationRequest,
+    responseSerialize: serialize_bet_PromotionalBigWinItemsResponse,
+    responseDeserialize: deserialize_bet_PromotionalBigWinItemsResponse,
+  },
+  setPromotionalBigWin: {
+    path: '/bet.Bet/setPromotionalBigWin',
+    requestStream: false,
+    responseStream: false,
+    requestType: bet_pb.PromotionalBigWinRequest,
+    responseType: bet_pb.PromotionalBigWinItem,
+    requestSerialize: serialize_bet_PromotionalBigWinRequest,
+    requestDeserialize: deserialize_bet_PromotionalBigWinRequest,
+    responseSerialize: serialize_bet_PromotionalBigWinItem,
+    responseDeserialize: deserialize_bet_PromotionalBigWinItem,
+  },
+  deletePromotionalBigWin: {
+    path: '/bet.Bet/deletePromotionalBigWin',
+    requestStream: false,
+    responseStream: false,
+    requestType: bet_pb.PromotionalBigWinKey,
+    responseType: bet_pb.PromotionalBigWinStatusResponse,
+    requestSerialize: serialize_bet_PromotionalBigWinKey,
+    requestDeserialize: deserialize_bet_PromotionalBigWinKey,
+    responseSerialize: serialize_bet_PromotionalBigWinStatusResponse,
+    responseDeserialize: deserialize_bet_PromotionalBigWinStatusResponse,
+  },
 };
 
 exports.BetClient = grpc.makeGenericClientConstructor(BetService, 'Bet');