1/*
2 * Copyright (c) 2026 DataPond D-Library Pty Ltd. ("The Sanctuary")
3 * Non-Profit Public Library — The World Library
4 * 
5 * D-SAFE Certification issued by POND Enterprise.
6 * Published under the D-Open Code Sovereign Licence v1.0 framework
7 * DataPond D-Library All exclusive Right reserved on modifiying the code - CC Attribution to data pond, Non modifiable, Non Commercial.
8 * https://registry.world.bibliotech.com/licence
9 * Source code donated to DataPond D-Library by it's author: data pond.
10 * 
11 * Technical Guardian ("The Shield"): Pond Enterprise Pty Ltd. (ACN 694 747 987)
12 * All liability claims about D-SAFE certification issues coming from the published D-Safe direction must be addressed with Pond Enterprise Pty Ltd.
13 * Code Modification automatically voids the certified liability protection provided by Pond Enterprise.
14 */
15
16// SPDX-License-Identifier: MIT
17pragma solidity ^0.8.24;
18
19interface IBouncerStorage {
20    struct UserAccount {
21        uint32 id;
22        address addr;
23        string username;
24        string language;
25        string country;
26        uint64 registeredAt; // block.timestamp at first registration
27        uint32 referredBy;   // userId of referrer (0 = no referral)
28    }
29
30    // ===== Admin / control =====
31    function getUsernameByAddress(
32        address addr
33    ) external view returns (string memory username);
34
35    // ===== Account reads =====
36    function hasAccount(address addr) external view returns (bool);
37    function userIdOf(address addr) external view returns (uint32);
38    function userAddr(uint32 userId) external view returns (address);
39    function userIdToUsername(
40        uint32 userId
41    ) external view returns (string memory);
42    function usernameToUserId(
43        string calldata username
44    ) external view returns (uint32); // returns 0 if not found
45    function userData(uint32 userId) external view returns (UserAccount memory);
46    function nbAccounts() external view returns (uint32);
47
48    // ===== Location reads =====
49    struct LocationCount {
50        string country;
51        string language;
52        uint32 count;
53    }
54    function getAccountCountByCountryLanguage(
55        string calldata country,
56        string calldata language
57    ) external view returns (uint32);
58    function getAllLocationCounts()
59        external
60        view
61        returns (LocationCount[] memory);
62    function getActiveLocationCount() external view returns (uint256);
63
64    // ===== Account lifecycle =====
65    function userInfos(
66        address addr
67    )
68        external
69        view
70        returns (string memory username, string memory country, string memory language, uint32 userId);
71
72    function newAccount(
73        address caller,
74        string calldata country,
75        string calldata language,
76        uint32 referredBy
77    )
78        external
79        returns (string memory username, string memory countryStr, string memory languageStr, uint32 newUserId);
80
81    function unregister(address caller) external;
82
83    // ===== Admin bulk-import (migration scripts only) =====
84    function importAccount(
85        uint32 userId,
86        address addr,
87        string calldata username,
88        string calldata country,
89        string calldata language,
90        uint64 registeredAt,
91        uint32 referredBy
92    ) external;
93    function setNbAccounts(uint32 count) external;
94
95    // ===== Pure helpers =====
96    function toLowercase(string memory s) external pure returns (string memory);
97    function locationToId(string calldata country, string calldata language) external view returns (uint16);
98
99    // ===== Identity management =====
100    function defineCombinations(
101        string[] calldata adjectives,
102        string[] calldata verbs
103    ) external;
104}
105