surfercid-client


Namesurfercid-client JSON
Version 0.1.49 PyPI version JSON
download
home_pagehttps://documenter.getpostman.com/view/15842770/2s9YJW55kQt
SummaryA Python client for the SurferCID API
upload_time2025-02-17 23:49:37
maintainerNone
docs_urlNone
authorSurferCID
requires_python>=3.7
licenseNone
keywords surfercid api client token
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # SurferCID API Client

A Python client for interacting with the SurferCID API. This client provides easy access to SurferCID's services including purchasing accounts, creating and refreshing LTokens, checking orders, and managing balance.

## Project Structure

```
surfercid_client/
├── models.py           # Data models and response types
├── surfercid_client.py # Main API client implementation
└── requirements.txt    # Project dependencies
```

## Installation

1. Install via pip:
```bash
pip install surfercid-client
```

## Usage

```python
from surfercid import SurferCIDClient
from surfercid.models import LTokenAccount, Status

# Initialize the client
client = SurferCIDClient(api_key="your_api_key_here")

# Get stock information for a product
stock_info = client.get_stock("Ltoken_create")
print("Stock Info: ", stock_info)

# Check account balance
balance = client.get_balance()
print("Balance: ", balance)

# Create new LTokens
creation_order = client.create_token(quantity=1)
print(f"Order ID: {creation_order.order_id}")

# Wait for token creation to complete
order = client.get_task_status(creation_order.order_id, wait=True)
if order.status == Status.SUCCESS:
    for account in order.accounts:
        if isinstance(account, LTokenAccount):
            print(f"Token created: {account.to_format()}")
            # Outputs: mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|cbits:1536|playerAge:25|token:XXX|vid:XXX

# Example of refreshing tokens
if isinstance(account, LTokenAccount):
    refreshed = client.refresh_token(account)
    print(f"Refreshed token: {refreshed.to_format()}")
```

## Available Methods

### Token Creation and Management
- `create_token(quantity: int = 1) -> OrderResponse`: Create new LTokens
- `get_task_status(order_id: int, wait: bool = False) -> OrderResponse`: Check token creation status
- `refresh_token(token_data: Union[str, LTokenAccount]) -> LTokenAccount`: Refresh an LToken

### Account Management
- `get_stock(product_name: str) -> Dict[str, Any]`: Get stock information for a specific product
- `get_balance() -> float`: Get current account balance
- `purchase(product_name: str, quantity: int) -> OrderResponse`: Purchase products
- `get_order(order_id: int) -> OrderResponse`: Get details of a specific order
- `get_orders(limit: Optional[int] = None) -> List[OrderResponse]`: Get list of orders

## Data Models

### LTokenAccount
```python
@dataclass
class LTokenAccount(Account):
    created_at: str
    mac: str
    name: str
    platform: str
    rid: str
    token: str
    wk: str = "NONE0"
    cbits: int = 1536
    player_age: int = 25
    vid: str = ""

    def to_format(self) -> str:
        """Convert to the new token format"""
        return f"mac:{self.mac}|wk:{self.wk}|platform:{self.platform}|rid:{self.rid}|name:{self.name}|cbits:{self.cbits}|playerAge:{self.player_age}|token:{self.token}|vid:{self.vid}"
```

### OrderResponse
```python
@dataclass
class OrderResponse:
    accounts: List[Account]
    message: str
    success: bool
    cost: float
    order_id: int
    order_date: datetime
    processing: bool = False
    quantity: int = 0
    refund_amount: float = 0
    status: Status = Status.FAILED
```

### Status Enum
```python
class Status(Enum):
    SUCCESS = "success"
    FAILED = "failed"
    PROCESSING = "processing"
```

## Error Handling

The client includes comprehensive error handling for various scenarios:

```python
from requests.exceptions import RequestException

try:
    # Create a new token
    order = client.create_token(quantity=1)
    status = client.get_task_status(order.order_id, wait=True)
    
    if status.status == Status.SUCCESS:
        print("Token created successfully!")
    elif status.status == Status.FAILED:
        print(f"Creation failed: {status.message}")
    
except RequestException as e:
    print(f"API request failed: {e}")
except ValueError as e:
    print(f"Invalid input or response: {e}")
```

## Token Format

The new token format includes additional fields for enhanced functionality:
```
mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|cbits:1536|playerAge:25|token:XXX|vid:XXX
```

Where:
- `mac`: MAC address
- `wk`: World key (default: NONE0)
- `platform`: Platform identifier
- `rid`: Resource identifier
- `name`: Account name
- `cbits`: Client bits (default: 1536)
- `playerAge`: Player age (default: 25)
- `token`: Authentication token
- `vid`: Version identifier

## Token Refresh Examples

### Single Token Refresh
```python
from surfercid import SurferCIDClient
from surfercid.models import LTokenAccount

# Initialize client
client = SurferCIDClient(api_key="your_api_key")

# Create token account from formatted string
token_str = "mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|token:XXX"
token = LTokenAccount.from_format(token_str)

# Refresh token
refreshed = client.refresh_token(token)
print(f"New token: {refreshed.to_format()}")
```

### Multiple Tokens Refresh
```python
from surfercid import SurferCIDClient
from surfercid.models import LTokenAccount

def refresh_tokens(api_key: str, tokens_str: str) -> None:
    client = SurferCIDClient(api_key=api_key)
    
    # Parse and refresh each token
    for line in tokens_str.strip().split('\n'):
        if not line.strip():
            continue
            
        try:
            token = LTokenAccount.from_format(line)
            refreshed = client.refresh_token(token)
            print(f"✓ Refreshed {token.name}: {refreshed.to_format()}")
        except Exception as e:
            print(f"✗ Failed to refresh: {e}")

# Example usage
tokens = """
mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:Token1|token:XXX
mac:YY:YY:YY:YY:YY:YY|wk:NONE0|platform:1|rid:YYY|name:Token2|token:YYY
"""

refresh_tokens("your_api_key", tokens)
```

The examples above demonstrate:
1. Refreshing a single token using a formatted string
2. Batch refreshing multiple tokens from a multi-line string
3. Error handling for failed refreshes
4. Using the key:value format for token strings

            

Raw data

            {
    "_id": null,
    "home_page": "https://documenter.getpostman.com/view/15842770/2s9YJW55kQt",
    "name": "surfercid-client",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "keywords": "surfercid, api, client, token",
    "author": "SurferCID",
    "author_email": "HeySurfers@protonmail.com",
    "download_url": "https://files.pythonhosted.org/packages/4c/84/78d964191244041bea3b7cf714eaffa1db7474327e65ab402a1050de6433/surfercid_client-0.1.49.tar.gz",
    "platform": null,
    "description": "# SurferCID API Client\r\n\r\nA Python client for interacting with the SurferCID API. This client provides easy access to SurferCID's services including purchasing accounts, creating and refreshing LTokens, checking orders, and managing balance.\r\n\r\n## Project Structure\r\n\r\n```\r\nsurfercid_client/\r\n\u251c\u2500\u2500 models.py           # Data models and response types\r\n\u251c\u2500\u2500 surfercid_client.py # Main API client implementation\r\n\u2514\u2500\u2500 requirements.txt    # Project dependencies\r\n```\r\n\r\n## Installation\r\n\r\n1. Install via pip:\r\n```bash\r\npip install surfercid-client\r\n```\r\n\r\n## Usage\r\n\r\n```python\r\nfrom surfercid import SurferCIDClient\r\nfrom surfercid.models import LTokenAccount, Status\r\n\r\n# Initialize the client\r\nclient = SurferCIDClient(api_key=\"your_api_key_here\")\r\n\r\n# Get stock information for a product\r\nstock_info = client.get_stock(\"Ltoken_create\")\r\nprint(\"Stock Info: \", stock_info)\r\n\r\n# Check account balance\r\nbalance = client.get_balance()\r\nprint(\"Balance: \", balance)\r\n\r\n# Create new LTokens\r\ncreation_order = client.create_token(quantity=1)\r\nprint(f\"Order ID: {creation_order.order_id}\")\r\n\r\n# Wait for token creation to complete\r\norder = client.get_task_status(creation_order.order_id, wait=True)\r\nif order.status == Status.SUCCESS:\r\n    for account in order.accounts:\r\n        if isinstance(account, LTokenAccount):\r\n            print(f\"Token created: {account.to_format()}\")\r\n            # Outputs: mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|cbits:1536|playerAge:25|token:XXX|vid:XXX\r\n\r\n# Example of refreshing tokens\r\nif isinstance(account, LTokenAccount):\r\n    refreshed = client.refresh_token(account)\r\n    print(f\"Refreshed token: {refreshed.to_format()}\")\r\n```\r\n\r\n## Available Methods\r\n\r\n### Token Creation and Management\r\n- `create_token(quantity: int = 1) -> OrderResponse`: Create new LTokens\r\n- `get_task_status(order_id: int, wait: bool = False) -> OrderResponse`: Check token creation status\r\n- `refresh_token(token_data: Union[str, LTokenAccount]) -> LTokenAccount`: Refresh an LToken\r\n\r\n### Account Management\r\n- `get_stock(product_name: str) -> Dict[str, Any]`: Get stock information for a specific product\r\n- `get_balance() -> float`: Get current account balance\r\n- `purchase(product_name: str, quantity: int) -> OrderResponse`: Purchase products\r\n- `get_order(order_id: int) -> OrderResponse`: Get details of a specific order\r\n- `get_orders(limit: Optional[int] = None) -> List[OrderResponse]`: Get list of orders\r\n\r\n## Data Models\r\n\r\n### LTokenAccount\r\n```python\r\n@dataclass\r\nclass LTokenAccount(Account):\r\n    created_at: str\r\n    mac: str\r\n    name: str\r\n    platform: str\r\n    rid: str\r\n    token: str\r\n    wk: str = \"NONE0\"\r\n    cbits: int = 1536\r\n    player_age: int = 25\r\n    vid: str = \"\"\r\n\r\n    def to_format(self) -> str:\r\n        \"\"\"Convert to the new token format\"\"\"\r\n        return f\"mac:{self.mac}|wk:{self.wk}|platform:{self.platform}|rid:{self.rid}|name:{self.name}|cbits:{self.cbits}|playerAge:{self.player_age}|token:{self.token}|vid:{self.vid}\"\r\n```\r\n\r\n### OrderResponse\r\n```python\r\n@dataclass\r\nclass OrderResponse:\r\n    accounts: List[Account]\r\n    message: str\r\n    success: bool\r\n    cost: float\r\n    order_id: int\r\n    order_date: datetime\r\n    processing: bool = False\r\n    quantity: int = 0\r\n    refund_amount: float = 0\r\n    status: Status = Status.FAILED\r\n```\r\n\r\n### Status Enum\r\n```python\r\nclass Status(Enum):\r\n    SUCCESS = \"success\"\r\n    FAILED = \"failed\"\r\n    PROCESSING = \"processing\"\r\n```\r\n\r\n## Error Handling\r\n\r\nThe client includes comprehensive error handling for various scenarios:\r\n\r\n```python\r\nfrom requests.exceptions import RequestException\r\n\r\ntry:\r\n    # Create a new token\r\n    order = client.create_token(quantity=1)\r\n    status = client.get_task_status(order.order_id, wait=True)\r\n    \r\n    if status.status == Status.SUCCESS:\r\n        print(\"Token created successfully!\")\r\n    elif status.status == Status.FAILED:\r\n        print(f\"Creation failed: {status.message}\")\r\n    \r\nexcept RequestException as e:\r\n    print(f\"API request failed: {e}\")\r\nexcept ValueError as e:\r\n    print(f\"Invalid input or response: {e}\")\r\n```\r\n\r\n## Token Format\r\n\r\nThe new token format includes additional fields for enhanced functionality:\r\n```\r\nmac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|cbits:1536|playerAge:25|token:XXX|vid:XXX\r\n```\r\n\r\nWhere:\r\n- `mac`: MAC address\r\n- `wk`: World key (default: NONE0)\r\n- `platform`: Platform identifier\r\n- `rid`: Resource identifier\r\n- `name`: Account name\r\n- `cbits`: Client bits (default: 1536)\r\n- `playerAge`: Player age (default: 25)\r\n- `token`: Authentication token\r\n- `vid`: Version identifier\r\n\r\n## Token Refresh Examples\r\n\r\n### Single Token Refresh\r\n```python\r\nfrom surfercid import SurferCIDClient\r\nfrom surfercid.models import LTokenAccount\r\n\r\n# Initialize client\r\nclient = SurferCIDClient(api_key=\"your_api_key\")\r\n\r\n# Create token account from formatted string\r\ntoken_str = \"mac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:XXX|token:XXX\"\r\ntoken = LTokenAccount.from_format(token_str)\r\n\r\n# Refresh token\r\nrefreshed = client.refresh_token(token)\r\nprint(f\"New token: {refreshed.to_format()}\")\r\n```\r\n\r\n### Multiple Tokens Refresh\r\n```python\r\nfrom surfercid import SurferCIDClient\r\nfrom surfercid.models import LTokenAccount\r\n\r\ndef refresh_tokens(api_key: str, tokens_str: str) -> None:\r\n    client = SurferCIDClient(api_key=api_key)\r\n    \r\n    # Parse and refresh each token\r\n    for line in tokens_str.strip().split('\\n'):\r\n        if not line.strip():\r\n            continue\r\n            \r\n        try:\r\n            token = LTokenAccount.from_format(line)\r\n            refreshed = client.refresh_token(token)\r\n            print(f\"\u2713 Refreshed {token.name}: {refreshed.to_format()}\")\r\n        except Exception as e:\r\n            print(f\"\u2717 Failed to refresh: {e}\")\r\n\r\n# Example usage\r\ntokens = \"\"\"\r\nmac:XX:XX:XX:XX:XX:XX|wk:NONE0|platform:1|rid:XXX|name:Token1|token:XXX\r\nmac:YY:YY:YY:YY:YY:YY|wk:NONE0|platform:1|rid:YYY|name:Token2|token:YYY\r\n\"\"\"\r\n\r\nrefresh_tokens(\"your_api_key\", tokens)\r\n```\r\n\r\nThe examples above demonstrate:\r\n1. Refreshing a single token using a formatted string\r\n2. Batch refreshing multiple tokens from a multi-line string\r\n3. Error handling for failed refreshes\r\n4. Using the key:value format for token strings\r\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A Python client for the SurferCID API",
    "version": "0.1.49",
    "project_urls": {
        "Homepage": "https://documenter.getpostman.com/view/15842770/2s9YJW55kQt"
    },
    "split_keywords": [
        "surfercid",
        " api",
        " client",
        " token"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "5b6388b57ba6430586591214e393b0ef76e7f566d892a43161afed71f6beb4a4",
                "md5": "71230b7a2b052ab2ebf4b3ede143d72f",
                "sha256": "bca2ca58ae3d612651bf39a1b80b4bc42ba98f6b7d3426c0f70a2d64b13b5631"
            },
            "downloads": -1,
            "filename": "surfercid_client-0.1.49-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "71230b7a2b052ab2ebf4b3ede143d72f",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 10652,
            "upload_time": "2025-02-17T23:49:36",
            "upload_time_iso_8601": "2025-02-17T23:49:36.162576Z",
            "url": "https://files.pythonhosted.org/packages/5b/63/88b57ba6430586591214e393b0ef76e7f566d892a43161afed71f6beb4a4/surfercid_client-0.1.49-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "4c8478d964191244041bea3b7cf714eaffa1db7474327e65ab402a1050de6433",
                "md5": "07b7be981c8db0e586d1a133b9846a28",
                "sha256": "15ee94ab7aabd98f5388382c4367a9d1ed8df06caa363f63bd0bb69dfa5f3bb7"
            },
            "downloads": -1,
            "filename": "surfercid_client-0.1.49.tar.gz",
            "has_sig": false,
            "md5_digest": "07b7be981c8db0e586d1a133b9846a28",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 11479,
            "upload_time": "2025-02-17T23:49:37",
            "upload_time_iso_8601": "2025-02-17T23:49:37.739882Z",
            "url": "https://files.pythonhosted.org/packages/4c/84/78d964191244041bea3b7cf714eaffa1db7474327e65ab402a1050de6433/surfercid_client-0.1.49.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-17 23:49:37",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "surfercid-client"
}
        
Elapsed time: 0.78288s