Guild api updates

src/src/Constant/ApiParameters.php

@@ -6,10 +6,14 @@ class ApiParameters
 {
     const string ADDRESS = 'address';
 
+    const string AFTER_ID = 'after_id';
+
     const string ALLOCATION_ID = 'allocation_id';
 
     const string ATTRIBUTE_TYPE = 'attribute_type';
 
+    const string BUCKET = 'bucket';
+
     const string CATEGORY = 'category';
 
     const string CODE = 'code';
@@ -38,10 +42,22 @@ class ApiParameters
 
     const string GUILD_ID = 'guild_id';
 
+    const string IDS = 'ids';
+
+    const string INCLUDE_META = 'include_meta';
+
+    const string INCLUDE_TOTAL = 'include_total';
+
     const string IP = 'ip';
 
+    const string IS_DESTROYED = 'is_destroyed';
+
+    const string KIND = 'kind';
+
     const string LABEL = 'label';
 
+    const string LIMIT = 'limit';
+
     const string LOCATION_ID = 'location_id';
 
     const string LOGGED_IN_ADDRESS = 'logged_in_address';
@@ -56,10 +72,16 @@ class ApiParameters
 
     const string OBJECT_KEY = 'object_key';
 
+    const string OBJECT_TYPE = 'object_type';
+
     const string OFFSET = 'offset';
 
+    const string ORDER = 'order';
+
     const string OWNER = 'owner';
 
+    const string OWNER_TYPE = 'owner_type';
+
     const string PAGE = 'page';
 
     const string PERMISSIONS = 'permissions';
@@ -82,14 +104,20 @@ class ApiParameters
 
     const string PUBKEY = 'pubkey';
 
+    const string Q = 'q';
+
     const string SEARCH_STRING = 'search_string';
 
     const string SIGNATURE = 'signature';
 
+    const string SINCE_SEQ = 'since_seq';
+
     const string SOURCE_ID = 'source_id';
 
     const string START_TIME = 'start_time';
 
+    const string STATUS = 'status';
+
     const string STRUCT_ID = 'struct_id';
 
     const string SUBSTATION_ID = 'substation_id';
@@ -98,9 +126,13 @@ class ApiParameters
 
     const string UNIX_TIMESTAMP = 'unix_timestamp';
 
+    const string UPDATED_SINCE = 'updated_since';
+
     const string USER_AGENT = 'user_agent';
 
     const string USERNAME = 'username';
 
     const string VALIDATOR_ADDRESS = 'validator_address';
+
+    const string WINDOW_BLOCKS = 'window_blocks';
 }

src/src/Constant/ObjectTypes.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace App\Constant;
+
+class ObjectTypes
+{
+    /**
+     * Object key prefixes, longest-first so 10 / 11 are matched before 1.
+     *
+     * @var array<string, string>
+     */
+    public const array PREFIXES = [
+        '10' => 'provider',
+        '11' => 'agreement',
+        '0' => 'guild',
+        '1' => 'player',
+        '2' => 'planet',
+        '3' => 'reactor',
+        '4' => 'substation',
+        '5' => 'struct',
+        '6' => 'allocation',
+        '7' => 'infusion',
+        '8' => 'address',
+        '9' => 'fleet',
+    ];
+
+    /**
+     * The values of PREFIXES, as a list. Kept as a literal because attributes need
+     * a constant expression; ObjectTypesTest asserts the two stay in step.
+     */
+    public const array ALL = [
+        'provider',
+        'agreement',
+        'guild',
+        'player',
+        'planet',
+        'reactor',
+        'substation',
+        'struct',
+        'allocation',
+        'infusion',
+        'address',
+        'fleet',
+    ];
+}

src/src/Constant/PaginationLimits.php

@@ -5,4 +5,25 @@
 class PaginationLimits
 {
     const int DEFAULT = 100;
+
+    const int MAX = 1000;
+
+    const int LEADERBOARD_DEFAULT = 50;
+
+    const int BATCH_IDS_MAX = 25;
+
+    const int AGGREGATE_MAX_SECONDS = 2592000;
+
+    /**
+     * Accepts a raw query-string value so callers do not each repeat the
+     * null/empty-string dance before casting.
+     */
+    public static function clamp(int|string|null $limit, int $default = self::DEFAULT): int
+    {
+        if ($limit === null || $limit === '' || (int) $limit < 1) {
+            return $default;
+        }
+
+        return min(self::MAX, (int) $limit);
+    }
 }

src/src/Constant/RegexPattern.php

@@ -17,6 +17,14 @@ class RegexPattern
     /** Composite game object id: type prefix + hyphen + numeric index (e.g. 5-123, 10-1) */
     public const string OBJECT_KEY = '/^\d+-\d+$/';
 
+    /** Comma-separated object keys (batch reads), capped at BATCH_IDS_MAX entries. */
+    public const string IDS = '/^(\d+-\d+)(,(\d+-\d+)){0,'
+        . (PaginationLimits::BATCH_IDS_MAX - 1)
+        . '}$/';
+
+    /** Allowlisted column.direction order specs. */
+    public const string ORDER = '/^[a-z_]+(\.(asc|desc))?$/';
+
     public const string PERMISSIONS = '/^[0-9]{1,8}$/';
 
     public const string PUBKEY = '/^[a-zA-Z0-9]+$/';