surquest-utils-poscore-client 0.0.5

Python client for POS Media Data Core APIs with credential handling and convenience helpers.

POS Media Data Core Python Client

Lightweight helper package for authenticating against POS Media Data Core and calling its Campaigns API from Python. The library exposes two primary objects:

• Credentials: exchanges a username/password for a short-lived Bearer token.
• Client: wraps Data Core endpoints (e.g., list campaigns, fetch campaign installations) using an injected Credentials instance.

Installation

pip install surquest-utils-poscore-client

Quickstart

from surquest.utils.poscore.credentials import Credentials
from surquest.utils.poscore.client import Client
import uuid

# Create token provider
creds = Credentials(
    username="your_username",
    password="your_password",
    # Optional: base_url="https://pos-core.pos-media.eu/gate/api/v1"
)

# Wire the authenticated client
client = Client(credentials=creds)

# 1) List campaigns
campaigns = client.get_campaigns(
    size=50,
    orderby="created desc",
    fetch_all=False # Set to True to auto-paginate through all results
)
for campaign in campaigns:
    print(f"Campaign: {campaign.name} with id: `{campaign.id}`

# 2) Get campaign installations
installations = client.get_campaign_installations(
    campaign_id=12345,
    locations=[], # Optional filters
    cm_carriers=[],
    components=[],
    task_types=[]
)
print(installations)

# 3) Fetch a document
doc_id = uuid.UUID("dc85d712-dc49-4e07-bb6c-876a6aa97ec6")
blob = client.fetch_document(document_id=doc_id, thumbnail=False)
print(f"Downloaded {blob.file_name} ({blob.content_type})")

# 4) Export all photos
blob = client.export_photos(
    campaign_id=12345
)

Concepts

• Token handling: Credentials handles authentication and attaches the Bearer token to each request. Refresh logic is encapsulated so callers do not manually manage tokens.
• Thin HTTP wrapper: Client keeps endpoints small and explicit; it accepts request parameters and returns parsed JSON (or content for documents).

Common Usage Patterns

• Pagination: get_campaigns supports fetch_all=True to automatically retrieve all pages. If fetch_all=False, use page and size to paginate manually.
• Filtering: get_campaign_installations allows filtering by locations, carriers, components, and task types.
• Document Retrieval: fetch_document retrieves the binary content of a document along with its filename and content type.

Error Handling

• Authentication errors: raised when credentials are invalid or tokens expire unexpectedly.
• HTTP errors: surfaced with status codes and response bodies to aid debugging; wrap calls in try/except as needed.

Development

Development of this package is realized via Dev Containers. This ensures a consistent environment for all developers.

Using Dev Containers (Recommended)

1. Open the project in VS Code.
2. When prompted, click Reopen in Container (or run the command Dev Containers: Reopen in Container).
3. The environment will be automatically configured with all dependencies.
4. Run tests using:

   pytest
   

Support

In case you have any questions or suggestions please contact us: [e-mail]