@acequants/aegis-contracts 0.1.53 → 0.1.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acequants/aegis-contracts",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "private": false,
   "license": "MIT",
   "type": "module",

package/proto/system/v1/system.proto

@@ -31,44 +31,6 @@ 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;
@@ -134,98 +96,122 @@ message GrpcDtoFeaturePermissions {
     repeated GrpcDtoFeaturePermission featurePermissions = 1;
 }
 
-// ---- CLIENT ----
-message GrpcInputClientCreate {
-    string clientTypePublicId=1;
-    string name = 2;
-    optional string managerPublicId=3;
-    optional string description = 4;
+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);
 }
 
-message GrpcInputClientUpdate {
-    string publicId = 1;
-    optional string name = 2;
-    optional string description = 3;
-    optional string clientTypePublicId=4;
-    optional string managerPublicId=5;
-}
+// ============================================================================
+// 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;
 
-message GrpcInputClientFeaturesAdd {
-    string publicId=1;
-    repeated string featureIds=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;
 
-message GrpcInputClientFeaturesRemove {
-    repeated string publicClientFeatureIds=1;
-}
+    string name = 7;
+    string iso2 = 8;
+    string iso3 = 9;
+    string phone_code = 10;
 
-message GrpcInputClient {
-    string publicId = 1;
-}
+    bool is_capital = 11;
+    bool is_active = 12;
 
-message GrpcInputClientFeatures {
-    string clientPublicId = 1;
-}
+    // 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;
+
+    // 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;
+
+    // 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 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;
+    google.protobuf.Timestamp created_at = 18;
+    google.protobuf.Timestamp updated_at = 19;
+    google.protobuf.Timestamp deleted_at = 20;
 }
 
-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;
+message GrpcDtoGeoDivisionsPage {
+    repeated GrpcDtoGeoDivision items = 1;
+    // Empty string when there is no next page.
+    string next_cursor = 2;
 }
 
-message GrpcDtoClients {
-    repeated GrpcDtoClient items = 1;
-    GrpcDtoPagination meta = 2;
+message GrpcDtoGeoDivisions {
+    repeated GrpcDtoGeoDivision items = 1;
 }
 
-message GrpcDtoFeaturesAdd {
-    repeated GrpcDtoFeature features = 1;
+// ---- 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 GrpcDtoClientFeature {
-    string public_id = 1;
-    GrpcDtoFeature feature = 2;
-    optional GrpcDtoClient client = 3;
+message GrpcInputGeoDivisionsGetByPublicIds {
+    repeated string public_ids = 1;
 }
 
-message GrpcDtoClientFeatures {
-    repeated GrpcDtoClientFeature clientFeatures = 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;
 }
 
-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);
+// ---- GEO SERVICE ----
+service GeoService {
+    // Full sync (used on first mirror boot). Paged by public_id cursor.
+    rpc GeoDivisionsListAll (GrpcInputGeoDivisionsListAll) returns (GrpcDtoGeoDivisionsPage);
+
+    // Batch fetch by public_id (used by live Redis event consumers).
+    rpc GeoDivisionsGetByPublicIds (GrpcInputGeoDivisionsGetByPublicIds) returns (GrpcDtoGeoDivisions);
 
-    // --- 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);
+    // Hourly safety-net reconciler. Catches anything the Redis publisher
+    // dropped due to restart races.
+    rpc GeoDivisionsListChangedSince (GrpcInputGeoDivisionsListChangedSince) returns (GrpcDtoGeoDivisionsPage);
 }