kroger-api 0.3.0__tar.gz → 0.4.0__tar.gz

{kroger_api-0.3.0/kroger_api.egg-info → kroger_api-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kroger-api
-Version: 0.3.0
+Version: 0.4.0
 Summary: A Python client library for the Kroger Public API
 Author-email: Stephen Thoemmes <thoemmes.stephen@gmail.com>
 License: MIT License
@@ -54,6 +54,7 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
 Requires-Dist: requests-mock>=1.9.0; extra == "dev"
+Requires-Dist: cryptography; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
@@ -65,6 +66,8 @@ Dynamic: license-file
 
 A comprehensive Python client library for the Kroger Public API, featuring robust token management, comprehensive examples, and easy-to-use interfaces for all available endpoints.
 
+📚 **Docs:** https://cupofowls.github.io/kroger-api/ — tutorials, how-to guides, concepts, and the full reference.
+
 ## 📺 Demo
 
 Adding an item to your cart via an interactive Python script, and checking that it appears in your account:
@@ -157,20 +160,21 @@ This library implements robust, automatic token management:
 ### ✨ Features
 - **Automatic token refresh** - No manual token handling required
 - **Persistent storage** - Tokens saved securely to avoid repeated logins  
-- **Proactive validation** - Tests tokens before use
+- **Expiry tracking** - Checks a token's expiry time before use, with no API call
 - **Reactive recovery** - Automatically refreshes expired tokens during API calls
 - **PKCE Support** - Enhanced OAuth security with Proof Key for Code Exchange
+- **Shared sign-ins** - Processes and threads that share a token file renew it one at a time, so they never sign each other out
 
 ### 🔧 How it Works
 
 **Proactive Approach:**
-1. Loads saved tokens and tests them with a lightweight API request
-2. Automatically refreshes if token is expired and refresh token is available
+1. Loads saved tokens and checks their expiry time (no API request)
+2. Automatically refreshes if token is expired and refresh token is available, while it holds a lock on the token file (`<token file>.lock`). A process that waited for the lock uses the token that another process renewed meanwhile, so a refresh token is never sent twice. A new sign-in and `clear_token` wait for the same lock, and a token whose file `clear_token` deleted is not renewed.
 
 **Reactive Approach:**
 1. Makes API requests with current token
-2. On 401 Unauthorized errors, attempts token refresh
-3. Retries original request with new token
+2. On 401 Unauthorized errors, refreshes the user token, or requests a new client-credentials token
+3. Retries the original request once with the new token
 
 Token files (automatically managed):
 - `.kroger_token_client_product.compact.json` - Client credentials tokens
@@ -184,7 +188,7 @@ The directory is shared with the [kroger-mcp](https://github.com/CupOfOwls/kroge
 
 ### 🔒 Enhanced Security with PKCE
 
-This library supports PKCE (Proof Key for Code Exchange) for enhanced security in the OAuth flow:
+This library supports PKCE (Proof Key for Code Exchange) for enhanced security in the OAuth flow. `authenticate_user` uses it automatically; if you build the flow yourself, pass the parameters as shown:
 
 ```python
 from kroger_api import KrogerAPI
@@ -213,6 +217,40 @@ token_info = kroger.authorization.get_token_with_authorization_code(
 
 PKCE helps protect against authorization code interception attacks, particularly important for public clients or those using external tools to manage OAuth flows.
 
+## ⚠️ Error Handling
+
+Every exception the library raises derives from `KrogerAPIError`. Invalid arguments are rejected before any request is sent, and every non-2xx response raises an exception that carries Kroger's own error code and message:
+
+```python
+from kroger_api import KrogerAPI, KrogerAPIError, InvalidParameterError, NotFoundError
+
+try:
+    kroger.location.get_location("99999999")
+except NotFoundError as e:
+    print(e)
+    # Kroger API error 404 Not Found: (no error message in the response body)
+    #   request: GET /v1/locations/99999999
+    #   correlation id: akam_1792606007_ba10cee2-f276-444a-aeac-082b98ac9ca3
+    #   hint: No store has this locationId. Find valid IDs with a location search.
+except KrogerAPIError as e:
+    print(e.to_dict())  # the same details as JSON-safe data
+```
+
+| Exception | When |
+|-----------|------|
+| `InvalidParameterError` | An argument breaks a documented API constraint, such as `fulfillment="delivery"` (valid: `ais`, `csp`, `dth`, `sth`). No request is sent. |
+| `ConfigurationError` | Credentials or the redirect URI are missing |
+| `NotAuthenticatedError` | A call was made before any token was obtained |
+| `BadRequestError` (400) | The API rejected a parameter; `kroger_message` names it |
+| `AuthenticationError` (401) | The token, or at the token endpoint the client credentials, were rejected after one automatic refresh-and-retry |
+| `PermissionDeniedError` (403) | The token type or scope cannot use this endpoint, such as a client-credentials token on the cart |
+| `NotFoundError` (404) | The location, chain, or department does not exist |
+| `RateLimitError` (429) | The endpoint's daily rate limit is used up |
+| `InternalServerError` (5xx) | Kroger's server failed |
+| `APIConnectionError`, `APITimeoutError` | No response arrived (requests time out after 30 seconds by default; set `KrogerAPI(timeout=...)`) |
+
+HTTP and network errors also subclass the matching `requests` exceptions, so existing `except requests.exceptions.HTTPError` code still catches every error response from the API. An argument that fails a parameter check raises `InvalidParameterError` (a `ValueError`) without sending a request, so catch `KrogerAPIError` to handle both. A failed cart add whose `outcome_unknown` is `True` may have gone through: check the cart before sending it again. See the [error handling reference](https://cupofowls.github.io/kroger-api/reference/errors) for every attribute.
+
 ## 📚 Example Scripts
 
 The `examples/` directory contains comprehensive demonstrations:
@@ -274,6 +312,8 @@ When requesting user authorization, you can specify these scopes:
 - `cart.basic:write` - Add items to cart  
 - `profile.compact` - Read user profile information
 
+Request only the scopes of the API products your app is registered for (`cart.basic:write` needs the Cart API, `profile.compact` the Identity API). Kroger refuses the whole sign-in with `invalid_scope` when one is missing.
+
 ## 📖 API Documentation
 
 For complete API documentation, visit:

{kroger_api-0.3.0 → kroger_api-0.4.0}/README.md

@@ -2,6 +2,8 @@
 
 A comprehensive Python client library for the Kroger Public API, featuring robust token management, comprehensive examples, and easy-to-use interfaces for all available endpoints.
 
+📚 **Docs:** https://cupofowls.github.io/kroger-api/ — tutorials, how-to guides, concepts, and the full reference.
+
 ## 📺 Demo
 
 Adding an item to your cart via an interactive Python script, and checking that it appears in your account:
@@ -94,20 +96,21 @@ This library implements robust, automatic token management:
 ### ✨ Features
 - **Automatic token refresh** - No manual token handling required
 - **Persistent storage** - Tokens saved securely to avoid repeated logins  
-- **Proactive validation** - Tests tokens before use
+- **Expiry tracking** - Checks a token's expiry time before use, with no API call
 - **Reactive recovery** - Automatically refreshes expired tokens during API calls
 - **PKCE Support** - Enhanced OAuth security with Proof Key for Code Exchange
+- **Shared sign-ins** - Processes and threads that share a token file renew it one at a time, so they never sign each other out
 
 ### 🔧 How it Works
 
 **Proactive Approach:**
-1. Loads saved tokens and tests them with a lightweight API request
-2. Automatically refreshes if token is expired and refresh token is available
+1. Loads saved tokens and checks their expiry time (no API request)
+2. Automatically refreshes if token is expired and refresh token is available, while it holds a lock on the token file (`<token file>.lock`). A process that waited for the lock uses the token that another process renewed meanwhile, so a refresh token is never sent twice. A new sign-in and `clear_token` wait for the same lock, and a token whose file `clear_token` deleted is not renewed.
 
 **Reactive Approach:**
 1. Makes API requests with current token
-2. On 401 Unauthorized errors, attempts token refresh
-3. Retries original request with new token
+2. On 401 Unauthorized errors, refreshes the user token, or requests a new client-credentials token
+3. Retries the original request once with the new token
 
 Token files (automatically managed):
 - `.kroger_token_client_product.compact.json` - Client credentials tokens
@@ -121,7 +124,7 @@ The directory is shared with the [kroger-mcp](https://github.com/CupOfOwls/kroge
 
 ### 🔒 Enhanced Security with PKCE
 
-This library supports PKCE (Proof Key for Code Exchange) for enhanced security in the OAuth flow:
+This library supports PKCE (Proof Key for Code Exchange) for enhanced security in the OAuth flow. `authenticate_user` uses it automatically; if you build the flow yourself, pass the parameters as shown:
 
 ```python
 from kroger_api import KrogerAPI
@@ -150,6 +153,40 @@ token_info = kroger.authorization.get_token_with_authorization_code(
 
 PKCE helps protect against authorization code interception attacks, particularly important for public clients or those using external tools to manage OAuth flows.
 
+## ⚠️ Error Handling
+
+Every exception the library raises derives from `KrogerAPIError`. Invalid arguments are rejected before any request is sent, and every non-2xx response raises an exception that carries Kroger's own error code and message:
+
+```python
+from kroger_api import KrogerAPI, KrogerAPIError, InvalidParameterError, NotFoundError
+
+try:
+    kroger.location.get_location("99999999")
+except NotFoundError as e:
+    print(e)
+    # Kroger API error 404 Not Found: (no error message in the response body)
+    #   request: GET /v1/locations/99999999
+    #   correlation id: akam_1792606007_ba10cee2-f276-444a-aeac-082b98ac9ca3
+    #   hint: No store has this locationId. Find valid IDs with a location search.
+except KrogerAPIError as e:
+    print(e.to_dict())  # the same details as JSON-safe data
+```
+
+| Exception | When |
+|-----------|------|
+| `InvalidParameterError` | An argument breaks a documented API constraint, such as `fulfillment="delivery"` (valid: `ais`, `csp`, `dth`, `sth`). No request is sent. |
+| `ConfigurationError` | Credentials or the redirect URI are missing |
+| `NotAuthenticatedError` | A call was made before any token was obtained |
+| `BadRequestError` (400) | The API rejected a parameter; `kroger_message` names it |
+| `AuthenticationError` (401) | The token, or at the token endpoint the client credentials, were rejected after one automatic refresh-and-retry |
+| `PermissionDeniedError` (403) | The token type or scope cannot use this endpoint, such as a client-credentials token on the cart |
+| `NotFoundError` (404) | The location, chain, or department does not exist |
+| `RateLimitError` (429) | The endpoint's daily rate limit is used up |
+| `InternalServerError` (5xx) | Kroger's server failed |
+| `APIConnectionError`, `APITimeoutError` | No response arrived (requests time out after 30 seconds by default; set `KrogerAPI(timeout=...)`) |
+
+HTTP and network errors also subclass the matching `requests` exceptions, so existing `except requests.exceptions.HTTPError` code still catches every error response from the API. An argument that fails a parameter check raises `InvalidParameterError` (a `ValueError`) without sending a request, so catch `KrogerAPIError` to handle both. A failed cart add whose `outcome_unknown` is `True` may have gone through: check the cart before sending it again. See the [error handling reference](https://cupofowls.github.io/kroger-api/reference/errors) for every attribute.
+
 ## 📚 Example Scripts
 
 The `examples/` directory contains comprehensive demonstrations:
@@ -211,6 +248,8 @@ When requesting user authorization, you can specify these scopes:
 - `cart.basic:write` - Add items to cart  
 - `profile.compact` - Read user profile information
 
+Request only the scopes of the API products your app is registered for (`cart.basic:write` needs the Cart API, `profile.compact` the Identity API). Kroger refuses the whole sign-in with `invalid_scope` when one is missing.
+
 ## 📖 API Documentation
 
 For complete API documentation, visit:

kroger_api-0.4.0/kroger_api/__init__.py

@@ -0,0 +1,30 @@
+# Make the KrogerAPI class available at the package level
+from kroger_api.kroger_api import KrogerAPI
+from . import auth
+from . import utils
+from . import validation
+from .client import KrogerClient
+from .errors import (
+    KrogerAPIError,
+    ConfigurationError,
+    InvalidParameterError,
+    NotAuthenticatedError,
+    APIConnectionError,
+    APITimeoutError,
+    APIStatusError,
+    BadRequestError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    RateLimitError,
+    InternalServerError,
+    InvalidResponseError,
+)
+
+__all__ = [
+    'KrogerAPI', 'auth', 'utils', 'validation', 'KrogerClient',
+    'KrogerAPIError', 'ConfigurationError', 'InvalidParameterError', 'NotAuthenticatedError',
+    'APIConnectionError', 'APITimeoutError', 'APIStatusError', 'BadRequestError',
+    'AuthenticationError', 'PermissionDeniedError', 'NotFoundError', 'RateLimitError',
+    'InternalServerError', 'InvalidResponseError',
+]

kroger_api-0.4.0/kroger_api/api/authorization.py

@@ -0,0 +1,148 @@
+import logging
+from typing import Dict, Optional, Any
+
+from kroger_api.client import KrogerClient
+from kroger_api.errors import BadRequestError, NotAuthenticatedError
+from kroger_api.token_storage import USER_TOKEN_FILE, get_token_file_path, load_token
+
+logger = logging.getLogger(__name__)
+
+
+class AuthorizationAPI:
+    """
+    Provides access to the Kroger Authorization API endpoints.
+    """ 
+    
+    def __init__(self, client: KrogerClient):
+        """
+        Initialize the Authorization API
+        
+        Args:
+            client: The KrogerClient instance
+        """
+        self.client = client
+    
+    def get_authorization_url(self, scope: str, state: Optional[str] = None, banner: Optional[str] = None, code_challenge: Optional[str] = None, code_challenge_method: Optional[str] = None) -> str:
+        """
+        Get the URL to redirect the user to for authorization
+        
+        Args:
+            scope: The level of access your application is requesting
+            state: A random string to verify that the response belongs to the initiated request
+            banner: Sets the chain specific branding displayed on the authorization consent screen
+            code_challenge: PKCE code challenge for enhanced security (recommended)
+            code_challenge_method: Method used to generate the code challenge (S256 is recommended)
+            
+        Returns:
+            The authorization URL
+        """
+        return self.client.get_authorization_url(scope, state, banner, code_challenge, code_challenge_method)
+    
+    def get_token_with_client_credentials(self, scope: str) -> Dict[str, Any]:
+        """
+        Get an access token using client credentials
+        
+        Args:
+            scope: The level of access your application is requesting
+            
+        Returns:
+            The token information
+        """
+        return self.client.get_token_with_client_credentials(scope)
+    
+    def get_token_with_authorization_code(self, code: str, code_verifier: Optional[str] = None,
+                                          token_file: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Get an access token using an authorization code
+        
+        Args:
+            code: The authorization code received from the redirect
+            code_verifier: PKCE code verifier used during authorization (if PKCE was used)
+            token_file: The file to save the user token to (default USER_TOKEN_FILE)
+            
+        Returns:
+            The token information
+        """
+        return self.client.get_token_with_authorization_code(code, code_verifier, token_file)
+    
+    def refresh_token(self, refresh_token: str) -> Dict[str, Any]:
+        """
+        Refresh an access token using a refresh token
+        
+        Args:
+            refresh_token: The refresh token received from a previous token request
+            
+        Returns:
+            The token information
+        """
+        return self.client.refresh_token(refresh_token)
+    
+    def load_saved_token(self, token_file: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Load a saved user token into the client, renewing it first if it has expired
+
+        An expired token is renewed with the token file locked, so threads
+        and processes that share the file renew it one at a time. One that
+        waited for the lock uses the token that another renewed meanwhile,
+        instead of sending a refresh token that was already used.
+
+        Args:
+            token_file: The file to load the token from (default the client's
+                token file, else USER_TOKEN_FILE). A renewed token is saved
+                back to it, and it becomes the client's token file.
+
+        Returns:
+            The token information, now in the client
+
+        Raises:
+            NotAuthenticatedError: If there is no saved token, or it has
+                expired and has no refresh token, or it was deleted while
+                this call waited to renew it
+            BadRequestError: If Kroger rejected the refresh token, so the
+                user has to sign in again
+            KrogerAPIError: If renewing fails for another reason, such as a
+                network error
+        """
+        token_file = token_file or self.client.token_file or USER_TOKEN_FILE
+        token_info = load_token(token_file)
+        if not isinstance(token_info, dict) or not token_info.get("access_token"):
+            raise NotAuthenticatedError(f"There is no saved token in {get_token_file_path(token_file)}.")
+
+        # The client's token file changes only when its token comes from this
+        # file, so a token that cannot be used never redirects later saves.
+        if not self.client.is_token_expired(token_info):
+            self.client.token_info = token_info
+            self.client.token_file = token_file
+            return token_info
+        if not token_info.get("refresh_token"):
+            raise NotAuthenticatedError(
+                f"The saved token in {get_token_file_path(token_file)} has expired and has no refresh token."
+            )
+
+        # token_info has a refresh token, so this renews it or raises
+        renewed = self.client._renew_user_token(token_file, token_info)
+        self.client.token_file = token_file
+        return renewed
+
+    def refresh_token_if_needed(self, token_file: Optional[str] = None) -> Optional[Dict[str, Any]]:
+        """
+        Load a saved token into the client, refreshing it first if it has expired
+
+        Like load_saved_token, but returns None where that raises
+        NotAuthenticatedError or BadRequestError.
+
+        Args:
+            token_file: The file path to load the token from
+
+        Returns:
+            The token information (either existing or refreshed), or None if
+            there is no saved token, or it has expired and cannot be refreshed
+
+        Raises:
+            KrogerAPIError: If refreshing fails for another reason than a
+                rejected refresh token, such as a network error
+        """
+        try:
+            return self.load_saved_token(token_file)
+        except (NotAuthenticatedError, BadRequestError):
+            return None

{kroger_api-0.3.0 → kroger_api-0.4.0}/kroger_api/api/cart.py

@@ -1,5 +1,6 @@
 from typing import Dict, List, Any
 
+from kroger_api import validation
 from kroger_api.client import KrogerClient
 
 
@@ -23,15 +24,22 @@ class CartAPI:
         
         Args:
             items: A list of items to add to the cart. Each item should be a dictionary with keys:
-                  - upc: The UPC of the item
-                  - quantity: The quantity of the item
+                  - upc: The UPC of the item (13 digits)
+                  - quantity: The quantity of the item (an integer of 1 or more)
                   - modality: (Optional) The modality including: DELIVERY, PICKUP
                   
         Returns:
             None if successful
+
+        Raises:
+            InvalidParameterError: If an item is malformed; no request is sent
+            PermissionDeniedError: If the token is not a user token with cart.basic:write
+            BadRequestError: If the API rejects an item
         """
         data = {
-            "items": items
+            "items": validation.cart_items(items)
         }
         
-        return self.client._make_request('PUT', '/v1/cart/add', data=data)
+        # The 2xx status is the result: an unreadable body must not report a
+        # completed add as a failure, which a caller might resend
+        self.client._make_request('PUT', '/v1/cart/add', data=data, read_body=False)

kroger_api-0.4.0/kroger_api/api/location.py

@@ -0,0 +1,210 @@
+from typing import Dict, Optional, Any
+from urllib.parse import quote
+
+from kroger_api import validation
+from kroger_api.client import KrogerClient
+from kroger_api.errors import NotFoundError
+
+
+class LocationAPI:
+    """
+    Provides access to the Kroger Location API endpoints.
+    """
+    
+    def __init__(self, client: KrogerClient):
+        """
+        Initialize the Location API
+        
+        Args:
+            client: The KrogerClient instance
+        """
+        self.client = client
+    
+    def search_locations(self, 
+                         zip_code: Optional[str] = None,
+                         lat_long: Optional[str] = None,
+                         lat: Optional[str] = None,
+                         lon: Optional[str] = None,
+                         radius_in_miles: Optional[int] = None,
+                         limit: Optional[int] = None,
+                         chain: Optional[str] = None,
+                         department: Optional[str] = None,
+                         location_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Search for locations
+        
+        Args:
+            zip_code: The zip code to use as a starting point for results (5 digits)
+            lat_long: The latitude and longitude to use as a starting point for results (comma separated)
+            lat: The latitude to use as a starting point for results
+            lon: The longitude to use as a starting point for results
+            radius_in_miles: The mile radius of results (1-100)
+            limit: The number of results to return (1-200)
+            chain: The chain name
+            department: The departmentId of the department (2 characters each, comma separated)
+            location_id: Comma-separated list of locationIds (8 characters each)
+            
+        Returns:
+            The locations matching the search criteria
+
+        Raises:
+            InvalidParameterError: If a parameter is invalid; no request is sent
+            APIStatusError: If the API rejects the request
+        """
+        params = {}
+        
+        if zip_code is not None:
+            params['filter.zipCode.near'] = validation.zip_code(zip_code)
+        
+        if lat_long is not None:
+            params['filter.latLong.near'] = validation.lat_long(lat_long)
+        
+        if lat is not None:
+            params['filter.lat.near'] = validation.coordinate(lat, "lat", 90)
+        
+        if lon is not None:
+            params['filter.lon.near'] = validation.coordinate(lon, "lon", 180)
+        
+        if radius_in_miles is not None:
+            params['filter.radiusInMiles'] = validation.check_int(
+                "radius_in_miles", radius_in_miles, validation.LOCATION_RADIUS_MIN, validation.LOCATION_RADIUS_MAX)
+        
+        if limit is not None:
+            params['filter.limit'] = validation.check_int(
+                "limit", limit, validation.LOCATION_LIMIT_MIN, validation.LOCATION_LIMIT_MAX)
+        
+        if chain is not None:
+            params['filter.chain'] = validation.check_non_empty("chain", chain)
+        
+        if department is not None:
+            params['filter.department'] = validation.department_id_list(department)
+        
+        if location_id is not None:
+            params['filter.locationId'] = validation.location_id_list(location_id)
+        
+        return self.client._make_request('GET', '/v1/locations', params=params)
+    
+    def get_location(self, location_id: str) -> Dict[str, Any]:
+        """
+        Get details for a specific location
+        
+        Args:
+            location_id: The locationId of the store (8 characters)
+            
+        Returns:
+            The location details
+
+        Raises:
+            InvalidParameterError: If location_id is malformed; no request is sent
+            NotFoundError: If no store has this locationId
+        """
+        location_id = validation.location_id(location_id)
+        return self.client._make_request('GET', f'/v1/locations/{quote(location_id, safe="")}')
+    
+    def location_exists(self, location_id: str) -> bool:
+        """
+        Check if a location exists
+        
+        Args:
+            location_id: The locationId of the store (8 characters)
+            
+        Returns:
+            True if the location exists, False otherwise
+
+        Raises:
+            InvalidParameterError: If location_id is malformed; no request is sent
+        """
+        location_id = validation.location_id(location_id)
+        return self._exists(f'/v1/locations/{quote(location_id, safe="")}')
+    
+    def list_chains(self) -> Dict[str, Any]:
+        """
+        Get a list of all chains
+        
+        Returns:
+            A list of all chains
+        """
+        return self.client._make_request('GET', '/v1/chains')
+    
+    def get_chain(self, name: str) -> Dict[str, Any]:
+        """
+        Get details for a specific chain
+        
+        Args:
+            name: The name of the chain (case-insensitive; may contain spaces, such as "FRED MEYER STORES")
+            
+        Returns:
+            The chain details
+
+        Raises:
+            InvalidParameterError: If name is empty; no request is sent
+            NotFoundError: If no chain has this name
+        """
+        name = validation.check_non_empty("name", name)
+        return self.client._make_request('GET', f'/v1/chains/{quote(name, safe="")}')
+    
+    def chain_exists(self, name: str) -> bool:
+        """
+        Check if a chain exists
+        
+        Args:
+            name: The name of the chain
+            
+        Returns:
+            True if the chain exists, False otherwise
+
+        Raises:
+            InvalidParameterError: If name is empty; no request is sent
+        """
+        name = validation.check_non_empty("name", name)
+        return self._exists(f'/v1/chains/{quote(name, safe="")}')
+    
+    def list_departments(self) -> Dict[str, Any]:
+        """
+        Get a list of all departments
+        
+        Returns:
+            A list of all departments
+        """
+        return self.client._make_request('GET', '/v1/departments')
+    
+    def get_department(self, department_id: str) -> Dict[str, Any]:
+        """
+        Get details for a specific department
+        
+        Args:
+            department_id: The departmentId of the department (2 characters)
+            
+        Returns:
+            The department details
+
+        Raises:
+            InvalidParameterError: If department_id is malformed; no request is sent
+            NotFoundError: If no department has this ID
+        """
+        department_id = validation.department_id(department_id)
+        return self.client._make_request('GET', f'/v1/departments/{quote(department_id, safe="")}')
+    
+    def department_exists(self, department_id: str) -> bool:
+        """
+        Check if a department exists
+        
+        Args:
+            department_id: The departmentId of the department (2 characters)
+            
+        Returns:
+            True if the department exists, False otherwise
+
+        Raises:
+            InvalidParameterError: If department_id is malformed; no request is sent
+        """
+        department_id = validation.department_id(department_id)
+        return self._exists(f'/v1/departments/{quote(department_id, safe="")}')
+
+    def _exists(self, path: str) -> bool:
+        """True if a HEAD request for path succeeds, False if it gets a 404"""
+        try:
+            self.client._make_request('HEAD', path)
+            return True
+        except NotFoundError:
+            return False