firstcash.py 1.0__tar.gz

firstcash_py-1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentLoneStar007
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

firstcash_py-1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: firstcash.py
+Version: 1.0
+Summary: A basic Python library to communicate with FirstCash' mobile app API.
+Author-email: AgentLoneStar007 <contactagent.3gxdf@simplelogin.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AgentLoneStar007/FirstCash.Py
+Project-URL: Documentation, https://github.com/AgentLoneStar007/FirstCash.Py/tree/main/docs
+Project-URL: Issues, https://github.com/AgentLoneStar007/FirstCash.Py/issues
+Keywords: api,web,web api,http,https,http api,https api,rest,restful,restful api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Dynamic: license-file
+
+# FirstCash.py
+
+#### *A basic Python library to communicate with the FirstCash mobile app API.*
+
+This is a super basic library designed for querying the FirstCash mobile app API, which
+allows the developer to search for stores, items, and more. One major advantage of this
+library is it exposes API methods that aren't in use on the FirstCash [inventory website](https://search.cashamerica.com/),
+such as limiting your search to specific stores or multiple categories.
+
+Note: This library does require an API key. While one is very is easy to obtain if you just look
+a little for it, I doubt they're legal to distribute, so you have to attain one on your own.
+
+#### Features:
+- Methods/attributes extensively explained within
+- Use of modern Python built-in typing capabilities
+- Asynchronous functionality
+
+## Installation:
+**This library requires at least Python 3.12 or higher.** <br>
+
+### Pip:
+
+---
+Windows:
+```commandline
+py -3 -m pip install -U firstcash.py
+```
+
+Linux/macOS/Unix:
+```bash
+python3 -m pip install -U firstcash.py
+```
+
+### UV:
+
+---
+Windows/macOS/Linux/Unix:
+```bash
+uv add firstcash.py
+```
+
+## Usage:
+```python
+from firstcash import APIClient, StoreItemResponse
+from asyncio import run
+
+firstcash_client: APIClient = APIClient(api_key="<api key>")
+
+async def main():
+    try:
+        response: StoreItemResponse = await firstcash_client.searchItemsByGeoLocation(
+            category_code=0,  # Zero for all categories
+            search_latitude=39.105,
+            search_longitude=-94.593,
+            search_radius=20  # In miles
+        )
+        
+        for item in response.results:
+            print(item)
+    finally:
+        await firstcash_client.closeAsyncRequestClient()
+
+run(main())
+```
+
+(More examples provided in the [documentation](https://github.com/AgentLoneStar007/FirstCash.Py/tree/main/docs).)
+
+## Contributing:
+To build this library, a normal virtual environment is required (A.K.A. not UV).
+First, install the build requirements:
+```bash
+python -m pip install -r requirements.txt
+```
+Then run the build script for either Linux or Windows:
+```bash
+# Linux
+./scripts/build_and_install.sh
+
+# Windows
+scripts/build_and_install.bat
+```
+This will uninstall any existing versions of the library, build the newest version, and install it
+into the environment.
+
+I'll add more to this in the future!
+
+## TODO:
+- [ ] Add a test suite
+- [ ] Add some documentation and examples
+- [ ] Add more extensive error handling
+- [ ] Add a cache to store recently queried items and store details (possibly)

firstcash_py-1.0/README.md

@@ -0,0 +1,91 @@
+# FirstCash.py
+
+#### *A basic Python library to communicate with the FirstCash mobile app API.*
+
+This is a super basic library designed for querying the FirstCash mobile app API, which
+allows the developer to search for stores, items, and more. One major advantage of this
+library is it exposes API methods that aren't in use on the FirstCash [inventory website](https://search.cashamerica.com/),
+such as limiting your search to specific stores or multiple categories.
+
+Note: This library does require an API key. While one is very is easy to obtain if you just look
+a little for it, I doubt they're legal to distribute, so you have to attain one on your own.
+
+#### Features:
+- Methods/attributes extensively explained within
+- Use of modern Python built-in typing capabilities
+- Asynchronous functionality
+
+## Installation:
+**This library requires at least Python 3.12 or higher.** <br>
+
+### Pip:
+
+---
+Windows:
+```commandline
+py -3 -m pip install -U firstcash.py
+```
+
+Linux/macOS/Unix:
+```bash
+python3 -m pip install -U firstcash.py
+```
+
+### UV:
+
+---
+Windows/macOS/Linux/Unix:
+```bash
+uv add firstcash.py
+```
+
+## Usage:
+```python
+from firstcash import APIClient, StoreItemResponse
+from asyncio import run
+
+firstcash_client: APIClient = APIClient(api_key="<api key>")
+
+async def main():
+    try:
+        response: StoreItemResponse = await firstcash_client.searchItemsByGeoLocation(
+            category_code=0,  # Zero for all categories
+            search_latitude=39.105,
+            search_longitude=-94.593,
+            search_radius=20  # In miles
+        )
+        
+        for item in response.results:
+            print(item)
+    finally:
+        await firstcash_client.closeAsyncRequestClient()
+
+run(main())
+```
+
+(More examples provided in the [documentation](https://github.com/AgentLoneStar007/FirstCash.Py/tree/main/docs).)
+
+## Contributing:
+To build this library, a normal virtual environment is required (A.K.A. not UV).
+First, install the build requirements:
+```bash
+python -m pip install -r requirements.txt
+```
+Then run the build script for either Linux or Windows:
+```bash
+# Linux
+./scripts/build_and_install.sh
+
+# Windows
+scripts/build_and_install.bat
+```
+This will uninstall any existing versions of the library, build the newest version, and install it
+into the environment.
+
+I'll add more to this in the future!
+
+## TODO:
+- [ ] Add a test suite
+- [ ] Add some documentation and examples
+- [ ] Add more extensive error handling
+- [ ] Add a cache to store recently queried items and store details (possibly)

firstcash_py-1.0/firstcash/__init__.py

@@ -0,0 +1,37 @@
+"""
+FirstCash.Py
+------------
+A basic API wrapper for the FirstCash
+mobile app API, which exposes the combined
+functionality of the store and inventory
+management APIs, allowing the user to fetch
+store details as well as search for items across
+the massive FirstCash inventory network.
+
+:copyright: (c) 2026 AgentLoneStar007
+:license: MIT
+"""
+
+__title__: str = "firstcash"
+__author__: str = "AgentLoneStar007"
+__license__: str = "MIT"
+__copyright__: str = "Copyright © 2026-present AgentLoneStar007"
+__version__: str = "1.0"
+
+# Imports from library files, to make everything accessible under the main import of "firstcash"
+
+from .api_client import APIClient
+from .types.category import Category
+from .types.store_address import StoreAddress
+from .types.store_details import StoreDetails
+from .types.store_display_info import StoreDisplayInfo
+from .types.store_hours import StoreHours
+from .types.store_item import StoreItem
+from .types.store_item_response import StoreItemResponse
+from .types.store_license import StoreLicense
+from .types.todays_store_hours import TodaysStoreHours
+from .exceptions import (
+    FirstCashException, APIGeneralError, APIServerError, APIUnauthorizedError, APIResponseTimedOut, APIContentNotFound,
+    APIRateLimited, SearchCoordinateValueError, SearchRadiusValueError, StoreIDValueError, CategoryCodeValueError,
+    PageIndexValueError, PageSizeValueError, PriceValueError
+)

firstcash_py-1.0/firstcash/_utils.py

@@ -0,0 +1,123 @@
+from urllib.parse import urljoin, urlencode
+from .exceptions import (SearchCoordinateValueError, SearchRadiusValueError, StoreIDValueError, CategoryCodeValueError,
+                         PageIndexValueError, PageSizeValueError, PriceValueError)
+
+
+# Function to build a URL to make a request to
+def buildURL(base_api_url: str, api_key: str, endpoint: str = None, params: dict = None) -> str:
+    """
+    A function to build a URL that can be used to make an API request.
+
+    :param base_api_url: The base URL of the API.
+    :param api_key: The API key for the used API.
+    :param endpoint: The endpoint to use. Optional.
+     This will be something like "Categories," or "Items."
+    :param params: The parameters to append to the URL, in a dictionary
+     "key": "value" format.
+
+    :returns: ``str`` - The URL to query with all provided parameters.
+
+    :raises None:
+    """
+
+    # Create the base URL
+    url: str = urljoin(base_api_url, endpoint) if endpoint else base_api_url
+
+    if params:
+        # Join the parameters to the base URL, if provided
+        query_string: str = urlencode(params)
+        if "?" not in url:
+            url += "?" + query_string
+        else:
+            url += "&" + query_string
+
+    # Append the API key to the end, using a & separator if any parameters were
+    # provided, or a ? if none were provided
+    url += f"{"&" if params else "?"}key={api_key}"
+
+    return url
+
+
+class ValueCheckers:
+    @staticmethod
+    def checkLatitude(latitude: float) -> None:
+        """Checks a latitude coordinate to see if it's within bounds."""
+
+        if not (-90 <= latitude <= 90):
+            raise SearchCoordinateValueError(
+                "A latitude value must be greater than or equal to -90, and less than or equal to 90.")
+
+        return
+
+    @staticmethod
+    def checkLongitude(longitude: float) -> None:
+        """Checks a longitude coordinate to see if it's within bounds."""
+
+        if not (-180 <= longitude <= 180):
+            raise SearchCoordinateValueError(
+                "A longitude value must be greater than or equal to -180 and less than or equal to 180.")
+
+        return
+
+    @staticmethod
+    def checkSearchRadius(search_radius: int | float) -> None:
+        """Checks a search radius to see if it's within bounds."""
+
+        if not (0 <= search_radius <= 5000):
+            raise SearchRadiusValueError(
+                "A search radius cannot be negative and must be less than or equal to 5,000 miles.")
+
+        return
+
+    @staticmethod
+    def checkPriceFilters(max_price: float | int, min_price: float | int = None) -> None:
+        """Checks price filters to see if they're within bounds."""
+
+        if max_price < 0:
+            raise PriceValueError("Price filters cannot be negative.")
+
+        if min_price:
+            if min_price < 0:
+                raise PriceValueError("Price filters cannot be negative.")
+
+            if max_price < min_price:
+                raise PriceValueError("The maximum price filter cannot be less than the minimum price filter.")
+        return
+
+    @staticmethod
+    def checkStoreID(store_id: int) -> None:
+        """Checks a store ID to see if it's within bounds."""
+
+        if not (0 <= store_id <= 32767):
+            raise StoreIDValueError("A store ID cannot be negative and must be less than or equal to 32,767.")
+
+        return
+
+    @staticmethod
+    def checkCategoryCode(category_code: int) -> None:
+        """Checks a category code to see if it's within bounds."""
+
+        if not (0 <= category_code <= 9999):
+            raise CategoryCodeValueError("Category codes must be between zero and 9,999.")
+
+        return
+
+    @staticmethod
+    def checkPageIndex(index: int, starting_index: int = 0) -> None:
+        """Checks a page index to see if it's within bounds."""
+
+        if index < 0:
+            raise PageIndexValueError("Page index cannot be negative.")
+
+        ## While this is semi-unnecessary, it adds a bit of prettification to the error.
+        if index < starting_index:
+            raise PageIndexValueError("Page index below starting index.")
+
+        return
+
+    @staticmethod
+    def checkPageSize(page_size: int) -> None:
+        """Checks a page's size to see if it's within bounds."""
+
+        if page_size <= 0:
+            raise PageSizeValueError("The page size must be greater than or equal to one.")