@acequants/aegis-contracts 0.1.55 → 0.1.57

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "@acequants/aegis-contracts",
-  "version": "0.1.55",
-  "private": false,
-  "license": "MIT",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist/",
-    "proto/"
-  ],
-  "scripts": {
-    "clean": "rimraf dist src/gen",
-    "gen": "mkdirp ./src/gen && node ./scripts/generate.cjs",
-    "build": "tsc -p tsconfig.build.json",
-    "prepublish": "npm run clean && npm run gen && npm run build"
-  },
-  "peerDependencies": {
-    "@grpc/grpc-js": "^1.10.0",
-    "protobufjs": "^7.2.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.19.11",
-    "mkdirp": "^3.0.1",
-    "rimraf": "^6.0.0",
-    "ts-node": "^10.9.2",
-    "ts-proto": "^1.181.2",
-    "typescript": "^5.5.0"
-  },
-  "dependencies": {
-    "@nestjs/microservices": "^11.1.6",
-    "rxjs": "^7.8.2"
-  }
-}
+{
+  "name": "@acequants/aegis-contracts",
+  "version": "0.1.57",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/",
+    "proto/"
+  ],
+  "scripts": {
+    "clean": "rimraf dist src/gen",
+    "gen": "mkdirp ./src/gen && node ./scripts/generate.cjs",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublish": "npm run clean && npm run gen && npm run build"
+  },
+  "peerDependencies": {
+    "@grpc/grpc-js": "^1.10.0",
+    "protobufjs": "^7.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.11",
+    "mkdirp": "^3.0.1",
+    "rimraf": "^6.0.0",
+    "ts-node": "^10.9.2",
+    "ts-proto": "^1.181.2",
+    "typescript": "^5.5.0"
+  },
+  "dependencies": {
+    "@nestjs/microservices": "^11.1.6",
+    "rxjs": "^7.8.2"
+  }
+}

package/proto/system/v1/system.proto

@@ -7,6 +7,140 @@ option java_multiple_files = true;
 import "google/protobuf/timestamp.proto";
 // import "shared/v1/shared.proto";
 
+//----------------------
+// --- GEOSYCN START ---
+//----------------------
+//
+// Geo* delta-sync surface.
+//
+// aegis owns every Geo* table; gtms holds a read-only mirror refreshed
+// hourly via the RPCs below. Each request carries a server-defined
+// cursor (last seen `updated_at` for watermark-friendly tables; last
+// seen `id` for the 3 bridge tables that have no `updated_at`/
+// `deleted_at` column). Responses are stable-ordered pages with
+// `next_cursor` + `has_more` so the consumer can stream until idle.
+//
+// All timestamp fields carry the source-of-truth (aegis) value; the
+// consumer is free to store its own local audit dates separately.
+
+message GrpcInputGeoSync {
+    // Opaque cursor — for delta tables this is an ISO8601 string of
+    // the last seen `updated_at`; for bridge tables it is the last
+    // seen integer `id` rendered as decimal. Empty string = from start.
+    string cursor = 1;
+    // Server clamps to [100, 2000]; 0 / unset → 500.
+    int32 page_size = 2;
+}
+
+// ---- Geo DTOs (1:1 with aegis schema scalars + FK publicIds) ----
+
+message GrpcDtoGeoTimezone {
+    string public_id = 1;
+    string iana = 2;
+    google.protobuf.Timestamp updated_at = 3;
+    google.protobuf.Timestamp deleted_at = 4; // nullable
+}
+
+message GrpcDtoGeoCurrency {
+    string public_id = 1;
+    string code = 2;
+    string name = 3;
+    string symbol = 4;                        // nullable, empty = unset
+    bool is_base = 5;
+    bool is_active = 6;
+    string exchange_rate = 7;                 // Decimal serialised as string
+    google.protobuf.Timestamp updated_at = 8;
+    google.protobuf.Timestamp deleted_at = 9; // nullable
+}
+
+message GrpcDtoGeoLanguage {
+    string public_id = 1;
+    string iso639_1 = 2;                      // LANGUAGE enum as string
+    string iso639_2 = 3;                      // nullable
+    string name = 4;
+    bool is_active = 5;
+    google.protobuf.Timestamp updated_at = 6;
+    google.protobuf.Timestamp deleted_at = 7; // nullable
+}
+
+message GrpcDtoGeoLocale {
+    string public_id = 1;
+    string language_public_id = 2;
+    string code = 3;
+    string name = 4;
+    google.protobuf.Timestamp updated_at = 5;
+    // GeoLocale has no deletedAt in aegis schema.
+}
+
+message GrpcDtoGeoDivision {
+    string public_id = 1;
+    string timezone_public_id = 2;            // nullable
+    string currency_public_id = 3;            // nullable
+    string parent_public_id = 4;              // nullable
+    string type = 5;                          // GEO_DIVISION enum as string
+    int32 level = 6;
+    string code = 7;                          // nullable
+    string path = 8;
+    string iso2 = 9;                          // nullable
+    string iso3 = 10;                         // nullable
+    string name = 11;
+    string phone_code = 12;                   // nullable
+    bool is_capital = 13;
+    bool is_active = 14;
+    double lat = 15;                          // nullable -> 0 when unset
+    double lng = 16;                          // nullable -> 0 when unset
+    bool has_lat = 17;
+    bool has_lng = 18;
+    string geo_json = 19;                     // JSON.stringify(geoJson) or empty
+    google.protobuf.Timestamp updated_at = 20;
+    google.protobuf.Timestamp deleted_at = 21;// nullable
+}
+
+message GrpcDtoGeoCountryMeta {
+    string public_id = 1;
+    string division_public_id = 2;
+    google.protobuf.Timestamp updated_at = 3;
+    // GeoCountryMeta has no deletedAt in aegis schema.
+}
+
+message GrpcDtoGeoCountryTimezone {
+    string public_id = 1;
+    string country_meta_public_id = 2;
+    string timezone_public_id = 3;
+    bool is_primary = 4;
+}
+
+message GrpcDtoGeoCountryCurrency {
+    string public_id = 1;
+    string country_meta_public_id = 2;
+    string currency_public_id = 3;
+    bool is_primary = 4;
+}
+
+message GrpcDtoGeoCountryLanguage {
+    string public_id = 1;
+    string country_meta_public_id = 2;
+    string language_public_id = 3;
+    bool is_official = 4;
+    bool is_national = 5;
+}
+
+// ---- Per-table sync responses ----
+
+message GrpcDtoGeoTimezonesSync       { repeated GrpcDtoGeoTimezone        items = 1; string next_cursor = 2; bool has_more = 3; }
+message GrpcDtoGeoCurrenciesSync      { repeated GrpcDtoGeoCurrency        items = 1; string next_cursor = 2; bool has_more = 3; }
+message GrpcDtoGeoLanguagesSync       { repeated GrpcDtoGeoLanguage        items = 1; string next_cursor = 2; bool has_more = 3; }
+message GrpcDtoGeoLocalesSync         { repeated GrpcDtoGeoLocale          items = 1; string next_cursor = 2; bool has_more = 3; }
+message GrpcDtoGeoDivisionsSync       { repeated GrpcDtoGeoDivision        items = 1; string next_cursor = 2; bool has_more = 3; }
+message GrpcDtoGeoCountryMetasSync    { repeated GrpcDtoGeoCountryMeta     items = 1; string next_cursor = 2; bool has_more = 3; }
+message GrpcDtoGeoCountryTimezonesSync{ repeated GrpcDtoGeoCountryTimezone items = 1; string next_cursor = 2; bool has_more = 3; }
+message GrpcDtoGeoCountryCurrenciesSync{repeated GrpcDtoGeoCountryCurrency items = 1; string next_cursor = 2; bool has_more = 3; }
+message GrpcDtoGeoCountryLanguagesSync{ repeated GrpcDtoGeoCountryLanguage items = 1; string next_cursor = 2; bool has_more = 3; }
+
+//----------------------
+// --- GEOSYCN END -----
+//----------------------
+
 message GrpcDtoPagination {
     int32 total_items = 1;
     int32 total_pages = 2;
@@ -31,6 +165,44 @@ message GrpcDtoPermissionsAdd {
     repeated GrpcDtoPermission permissions = 1;
 }
 
+// ---- CLIENT TYPE ----
+message GrpcInputClientTypeSeed {
+    string name = 1;
+}
+
+message GrpcInputClientTypesSeed {
+    repeated GrpcInputClientTypeSeed client_types = 1;
+}
+
+message GrpcInputClientType {
+    string publicId = 1;
+}
+
+message GrpcInputClientTypes {
+    optional string search = 1;
+    optional int32 page = 2;
+    optional int32 page_size = 3;
+    optional string sort_by = 4;
+    optional string sort_order = 5;
+}
+
+message GrpcDtoClientType {
+    string public_id = 1;
+    string name = 2;
+    google.protobuf.Timestamp created_at = 3;
+    google.protobuf.Timestamp updated_at = 4;
+    google.protobuf.Timestamp deleted_at = 5;
+}
+
+message GrpcDtoClientTypesSeed {
+    repeated GrpcDtoClientType client_types = 1;
+}
+
+message GrpcDtoClientTypes {
+    repeated GrpcDtoClientType items = 1;
+    GrpcDtoPagination meta = 2;
+}
+
 // ---- FEATURES ----
 message GrpcInputFeatureSeed {
     string name = 1;
@@ -96,122 +268,109 @@ message GrpcDtoFeaturePermissions {
     repeated GrpcDtoFeaturePermission featurePermissions = 1;
 }
 
-service SystemService {
-    // --- Features ---
-    rpc FeaturesSeed (GrpcInputFeaturesSeed) returns (GrpcDtoFeaturesSeed);
-    rpc Features (GrpcInputFeatures) returns (GrpcDtoFeatures);
-    rpc Feature (GrpcInputFeature) returns (GrpcDtoFeature);
-    rpc FeaturePermissions (GrpcInputFeaturePermissions) returns (GrpcDtoFeaturePermissions);
-    rpc FeaturePermissionsAdd (GrpcInputFeaturePermissionsAdd) returns (GrpcDtoPermissionsAdd);
-    rpc FeaturePermissionsRemove (GrpcInputFeaturePermissionsRemove) returns (GrpcDtoMessage);
+// ---- CLIENT ----
+message GrpcInputClientCreate {
+    string clientTypePublicId=1;
+    string name = 2;
+    optional string managerPublicId=3;
+    optional string description = 4;
 }
 
-// ============================================================================
-// GEO REPLICATION CONTRACT
-// ============================================================================
-//
-// Used by aegis (authoritative) to ship GeoDivision rows to subscriber
-// services (today: gtms) so they can maintain a local read-only mirror.
-//
-// RULES
-// - Keyed by public_id only. NEVER add internal numeric ids.
-// - Soft-deleted rows ARE returned so subscribers can mark them deleted.
-// - Ordering is part of the contract: level ASC, public_id ASC. Parents
-//   arrive before children so the subscriber can satisfy its self-FK.
-//
-// DO
-// - Add new fields at the END of a message with a new field number.
-// - Bump to a v2 file for removals/renames or breaking semantics.
-//
-// DON'T
-// - Don't reuse field numbers. Ever.
-// - Don't add user/auth context to these payloads — geo is public data.
-// ============================================================================
-
-// ---- GEO MESSAGES ----
-message GrpcDtoGeoDivision {
-    string public_id = 1;
-    // Parent's public_id; empty string when this is a root division (level 0).
-    string parent_public_id = 2;
-
-    // Enum name as string (e.g. "COUNTRY", "REGION") — matches Prisma enum
-    // GEO_DIVISION. Kept as string so adding new levels doesn't require a
-    // proto bump on the subscriber.
-    string type = 3;
-    int32 level = 4;
-    string code = 5;
-    // Immutable hierarchy path (e.g. "KE", "KE.47", "KE.47.001").
-    string path = 6;
-
-    string name = 7;
-    string iso2 = 8;
-    string iso3 = 9;
-    string phone_code = 10;
-
-    bool is_capital = 11;
-    bool is_active = 12;
+message GrpcInputClientUpdate {
+    string publicId = 1;
+    optional string name = 2;
+    optional string description = 3;
+    optional string clientTypePublicId=4;
+    optional string managerPublicId=5;
+}
 
-    // Optional centroid. Sent as wrapped/optional so 0,0 stays distinguishable
-    // from "no value". Using `optional` keyword (proto3 field presence).
-    optional double lat = 13;
-    optional double lng = 14;
+message GrpcInputClientFeaturesAdd {
+    string publicId=1;
+    repeated string featureIds=2;
+}
 
-    // JSON-encoded geometry (GeoJSON). Empty string when not set.
-    // Kept as string to avoid pulling in google.protobuf.Struct here and to
-    // stay lossless for arbitrary GeoJSON shapes.
-    string geo_json = 15;
+message GrpcInputClientFeaturesRemove {
+    repeated string publicClientFeatureIds=1;
+}
 
-    // Relation references by public_id. Mirrors the structure of aegis
-    // `GeoDivision.timezone` / `.currency` — subscribers can hold either
-    // an opaque string ref or layer their own mirror table on top. We
-    // ship public_ids (not internal ids) so the contract stays portable.
-    string timezone_public_id = 16;
-    string currency_public_id = 17;
+message GrpcInputClient {
+    string publicId = 1;
+}
 
-    google.protobuf.Timestamp created_at = 18;
-    google.protobuf.Timestamp updated_at = 19;
-    google.protobuf.Timestamp deleted_at = 20;
+message GrpcInputClientFeatures {
+    string clientPublicId = 1;
 }
 
-message GrpcDtoGeoDivisionsPage {
-    repeated GrpcDtoGeoDivision items = 1;
-    // Empty string when there is no next page.
-    string next_cursor = 2;
+message GrpcInputClients {
+    optional string clientTypePublicId=1;
+    optional string managerPublicId=2;
+    optional string search = 3;
+    optional int32 page = 4;
+    optional int32 pageSize = 5;
+    optional string sortBy = 6;
+    optional string sortOrder = 7;
 }
 
-message GrpcDtoGeoDivisions {
-    repeated GrpcDtoGeoDivision items = 1;
+message GrpcDtoClient {
+    string publicId = 1;
+    string name = 2;
+    optional string description = 3;
+    optional GrpcDtoClientType clientType = 4;
+    google.protobuf.Timestamp createdAt = 5;
+    google.protobuf.Timestamp updatedAt = 6;
+    google.protobuf.Timestamp deletedAt = 7;
 }
 
-// ---- GEO INPUTS ----
-message GrpcInputGeoDivisionsListAll {
-    // Empty string means "from the beginning".
-    string cursor = 1;
-    // 0 means "use server default". Server clamps to its max.
-    int32 limit = 2;
+message GrpcDtoClients {
+    repeated GrpcDtoClient items = 1;
+    GrpcDtoPagination meta = 2;
 }
 
-message GrpcInputGeoDivisionsGetByPublicIds {
-    repeated string public_ids = 1;
+message GrpcDtoFeaturesAdd {
+    repeated GrpcDtoFeature features = 1;
 }
 
-message GrpcInputGeoDivisionsListChangedSince {
-    // Strict `>` comparison server-side. Subscriber should record its
-    // "last seen updated_at" and pass it back here unchanged.
-    google.protobuf.Timestamp since = 1;
-    string cursor = 2;
-    int32 limit = 3;
+message GrpcDtoClientFeature {
+    string public_id = 1;
+    GrpcDtoFeature feature = 2;
+    optional GrpcDtoClient client = 3;
 }
 
-// ---- GEO SERVICE ----
-service GeoService {
-    // Full sync (used on first mirror boot). Paged by public_id cursor.
-    rpc GeoDivisionsListAll (GrpcInputGeoDivisionsListAll) returns (GrpcDtoGeoDivisionsPage);
+message GrpcDtoClientFeatures {
+    repeated GrpcDtoClientFeature clientFeatures = 1;
+}
 
-    // Batch fetch by public_id (used by live Redis event consumers).
-    rpc GeoDivisionsGetByPublicIds (GrpcInputGeoDivisionsGetByPublicIds) returns (GrpcDtoGeoDivisions);
+service SystemService {
+    // --- Client Types ---
+    rpc ClientTypesSeed (GrpcInputClientTypesSeed) returns (GrpcDtoClientTypesSeed);
+    rpc ClientTypes (GrpcInputClientTypes) returns (GrpcDtoClientTypes);
+    rpc ClientType (GrpcInputClientType) returns (GrpcDtoClientType);
+    
+    // --- Features ---
+    rpc FeaturesSeed (GrpcInputFeaturesSeed) returns (GrpcDtoFeaturesSeed);
+    rpc Features (GrpcInputFeatures) returns (GrpcDtoFeatures);
+    rpc Feature (GrpcInputFeature) returns (GrpcDtoFeature);
+    rpc FeaturePermissions (GrpcInputFeaturePermissions) returns (GrpcDtoFeaturePermissions);
+    rpc FeaturePermissionsAdd (GrpcInputFeaturePermissionsAdd) returns (GrpcDtoPermissionsAdd);
+    rpc FeaturePermissionsRemove (GrpcInputFeaturePermissionsRemove) returns (GrpcDtoMessage);
 
-    // Hourly safety-net reconciler. Catches anything the Redis publisher
-    // dropped due to restart races.
-    rpc GeoDivisionsListChangedSince (GrpcInputGeoDivisionsListChangedSince) returns (GrpcDtoGeoDivisionsPage);
+    // --- Clients ---
+    rpc ClientCreate (GrpcInputClientCreate) returns (GrpcDtoClient);
+    rpc ClientUpdate (GrpcInputClientUpdate) returns (GrpcDtoClient);
+    rpc Clients (GrpcInputClients) returns (GrpcDtoClients);
+    rpc Client (GrpcInputClient) returns (GrpcDtoClient);
+    rpc ClientFeaturesAdd (GrpcInputClientFeaturesAdd) returns (GrpcDtoFeaturesAdd);
+    rpc ClientFeaturesRemove (GrpcInputClientFeaturesRemove) returns (GrpcDtoMessage);
+    rpc ClientFeatures (GrpcInputClientFeatures) returns (GrpcDtoClientFeatures);
+
+    // --- Geo delta sync (hourly pull from gtms mirror) ---
+    rpc GeoTimezonesSync        (GrpcInputGeoSync) returns (GrpcDtoGeoTimezonesSync);
+    rpc GeoCurrenciesSync       (GrpcInputGeoSync) returns (GrpcDtoGeoCurrenciesSync);
+    rpc GeoLanguagesSync        (GrpcInputGeoSync) returns (GrpcDtoGeoLanguagesSync);
+    rpc GeoLocalesSync          (GrpcInputGeoSync) returns (GrpcDtoGeoLocalesSync);
+    rpc GeoDivisionsSync        (GrpcInputGeoSync) returns (GrpcDtoGeoDivisionsSync);
+    rpc GeoCountryMetasSync     (GrpcInputGeoSync) returns (GrpcDtoGeoCountryMetasSync);
+    rpc GeoCountryTimezonesSync (GrpcInputGeoSync) returns (GrpcDtoGeoCountryTimezonesSync);
+    rpc GeoCountryCurrenciesSync(GrpcInputGeoSync) returns (GrpcDtoGeoCountryCurrenciesSync);
+    rpc GeoCountryLanguagesSync (GrpcInputGeoSync) returns (GrpcDtoGeoCountryLanguagesSync);
 }