Metadata-Version: 2.4
Name: globio
Version: 0.1.0
Summary: Official Python SDK for Globio
Project-URL: Homepage, https://globio.stanlink.online
Project-URL: Repository, https://github.com/Globio-Technologies/globio-app
Author: Globio Technologies
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-httpx; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# Globio Python SDK

The official Python SDK for [Globio](https://globio.stanlink.online) — game backend infrastructure built on Cloudflare.

[![PyPI version](https://img.shields.io/pypi/v/globio)](https://pypi.org/project/globio)
[![Python Version](https://img.shields.io/pypi/pyversions/globio)](https://pypi.org/project/globio)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## What is Globio?

Globio is a backend-as-a-service platform built specifically for game developers. Instead of stitching together Firebase, Supabase, PlayFab, and a handful of other services, you get everything in one SDK at one URL.

| Module | Service | What it does |
|---|---|---|
| `GlobioId` | Globio ID | Authentication — email, OAuth, SMS, WhatsApp, anonymous |
| `GlobioDoc` | GlobalDoc | Document database — NoSQL, JSON documents |
| `GlobioVault` | GlobalVault | File storage — assets, avatars, replays, saves |
| `GlobioPulse` | GlobalPulse | Live config and feature flags |
| `GlobioSync` | GlobalSync | Real-time multiplayer rooms over WebSocket |
| `GlobioSignal` | GlobalSignal | Real-time notifications over WebSocket |
| `GlobioMart` | GlobalMart | Virtual economy — currencies, items, IAP |
| `GlobioBrain` | GlobalBrain | AI inference and content moderation |
| `GlobioCode` | GlobalCode | Serverless edge functions and hooks |
| `GlobioScope` | GlobalScope | Game analytics — events, funnels, retention |

---

## Installation

```bash
pip install globio
```

*Requires Python 3.9 or higher.*

---

## Quick Start

The Python SDK is fully asynchronous, built on top of `httpx` and `asyncio`.

```python
import asyncio
from globio.types import GlobioConfig
from globio.client import GlobioClient
from globio.modules.id import GlobioId

async def main():
    config = GlobioConfig(api_key="glo_client_your_key_here")
    client = GlobioClient(config)
    
    # Initialize the modules you need
    auth = GlobioId(client)
    
    # Use the services
    if not auth.is_signed_in():
        await auth.sign_in_anonymously()
        
    await client.close()

if __name__ == "__main__":
    asyncio.run(main())
```

Get your API key from the [Globio Console](https://console.globio.stanlink.online).

---

## Authentication — `GlobioId`

```python
from globio.modules.id import GlobioId

auth = GlobioId(client)

# Sign up
result = await auth.sign_up(
    email="player@example.com", 
    password="securepassword"
)

# Sign in
result = await auth.sign_in("player@example.com", "securepassword")

# Get current user
user = await auth.get_user()

# Check if signed in
if auth.is_signed_in():
    print(f"Logged in as {user.display_name}")

# Update profile
await auth.update_profile({
    "display_name": "New Name",
    "avatar_url": "https://...",
    "metadata": {"level": 5, "clan": "dragons"}
})

# Sign out
await auth.sign_out()
```

Sessions are stored automatically and tokens are refreshed transparently in memory.

---

## Documents — `GlobioDoc`

```python
from globio.modules.doc import GlobioDoc

doc_db = GlobioDoc(client)

# Write a document
await doc_db.set("scores", user_id, {
    "score": 1500,
    "level": 12
})

# Read a document
result = await doc_db.get("scores", user_id)
print(result["data"]["score"]) # 1500

# Add a document (auto-generated ID)
await doc_db.add("game_sessions", {
    "player_id": user_id,
    "duration_seconds": 300,
    "map": "desert_storm"
})

# Query documents
results = await doc_db.query("scores", {
    "where": [{"field": "level", "op": ">=", "value": 10}],
    "orderBy": {"field": "score", "direction": "desc"},
    "limit": 10
})

# Delete a document
await doc_db.delete("scores", document_id)
```

---

## File Storage — `GlobioVault`

```python
from globio.modules.vault import GlobioVault

vault = GlobioVault(client)

# Upload a file
with open("avatar.png", "rb") as f:
    await vault.upload_file(f"avatars/{user_id}.png", f)

# List files in a path
files = await vault.list_files("avatars/")

# Get a public download URL
url = await vault.get_download_url("avatars/player.png")

# Delete a file
await vault.delete_file("avatars/old-avatar.png")
```

---

## Live Config & Feature Flags — `GlobioPulse`

```python
from globio.modules.pulse import GlobioPulse

pulse = GlobioPulse(client)

# Get all configs and flags at once
result = await pulse.get_all("production")
configs = result["data"]["configs"]
flags = result["data"]["flags"]

# Get a specific config value
max_players = await pulse.get_config("max_players")

# Check a feature flag
is_new_map_enabled = await pulse.evaluate_flag("new_map_feature")

if is_new_map_enabled:
    load_new_map()
```

---

## Analytics — `GlobioScope`

```python
from globio.modules.scope import GlobioScope

scope = GlobioScope(client)

# Track an event
await scope.track("level_completed", {
    "level": 5,
    "time_seconds": 120,
    "deaths": 2
})

await scope.track("item_purchased", {
    "sku": "sword_of_fire",
    "currency": "GEMS",
    "amount": 50
})

# Force-flush pending events immediately
await scope.flush()
```

---

## Virtual Economy — `GlobioMart`

```python
from globio.modules.mart import GlobioMart

mart = GlobioMart(client)

# Get player wallet (all currency balances)
wallet = await mart.get_wallet()
# -> [{"currency_code": "COINS", "balance": 500}, ...]

# Purchase an item
result = await mart.purchase("sword_of_fire", "GEMS")

# Get player inventory
inventory = await mart.get_inventory()
```

---

## GlobioBrain — AI Agents and Moderation

GlobioBrain provides named AI agents with persistent conversation history and content moderation.

### Chat with an Agent

```python
from globio.modules.brain import GlobioBrain

brain = GlobioBrain(client)

# Simple chat — server manages conversation history
result = await brain.chat("support-agent", "How do I reset my password?")
print(result["data"]["response"])
```

### Content Moderation

```python
result = await brain.moderate(
    content="user submitted content here",
    content_type="chat_message"
)

if result["data"]["result"] == "rejected":
    # Block the content
    pass
```

---

## GlobalCode — Serverless Functions

Invoke serverless HTTP functions directly from your Python backend.

```python
from globio.modules.code import GlobioCode

code = GlobioCode(client)

# Invoke from server/client
result = await code.invoke("matchmaking", {
    "userId": "user_123",
    "rating": 1450,
    "region": "africa"
})

print(result["data"]["roomId"])
```

---

## Error Handling

Every API call returns standard exceptions for different failure types.

```python
from globio.exceptions import GlobioAuthError, GlobioValidationError

try:
    await auth.sign_in(email, password)
except GlobioAuthError as e:
    print(e.code)    # e.g., 'INVALID_CREDENTIALS'
    print(e.message) # e.g., 'Email or password is incorrect'
except GlobioValidationError as e:
    print("Invalid input format")
```

---

## Type Hinting

The SDK is strictly typed and ships with full type annotations. All methods return strongly typed objects (defined in `globio.types`).

---

## License

MIT © [Globio Technologies](https://github.com/globio-technologies)
