Skip to content

API.md

Latest commit

 

History

History
117 lines (79 loc) · 3.86 KB

API.md

File metadata and controls

117 lines (79 loc) · 3.86 KB
Raw

Internal API Reference

The project is a desktop application rather than a network service. This document covers its stable internal interfaces and the configured license-validation contract.

Safety helpers

validate_test_send_limit(value) -> int

Parses a value as an integer and accepts only 1 <= value <= 500. Invalid values raise TypeError or ValueError.

safe_test_send_limit(value) -> int

Normalizes untrusted persisted or runtime values. Invalid values fail closed to the default of 50.

_strict_server_boolean(value) -> bool

Accepts only True, integer 1, or the case-insensitive strings true, 1, and yes. Non-empty strings such as false do not become truthy accidentally.

_license_url_is_allowed(url) -> bool

Requires HTTPS with a host. Non-frozen development may use HTTP only for localhost or 127.0.0.1.

Managers

SettingsManager(path)

  • load() merges persisted values with defaults and sanitizes the Send limit.
  • save() writes UTF-8 JSON.
  • reset() restores defaults.
  • get(key, default) and set(key, value) provide persistence access.

LicenseManager(settings)

  • validate(license_key, email) -> (bool, str) performs local format checks and remote validation.
  • is_activated() -> bool requires a recoverable key, matching hash, and valid expiry.
  • logout() clears memory and removes the cache file.
  • device_id() -> str returns a truncated SHA-256 device binding derived from local machine/user identifiers.

License endpoint contract

Request

Method: POST
Content type: application/json
Production transport: HTTPS

{
  "license_key": "user-provided-key",
  "email": "optional-user-email",
  "device_hash": "24-character-device-hash",
  "device_id": "24-character-device-hash",
  "app_id": "Razorpay (Vib.Tools)",
  "app_name": "Razorpay (Vib.Tools)",
  "app_version": "1.0.6",
  "version": "1.0.6",
  "api_key": "deployment-api-key"
}

The API key is also sent in X-API-Key and Bearer Authorization headers for compatibility with the existing endpoint.

Accepted response

HTTP status must be 200. The JSON object must contain a strictly true valid or success field. Expiry can be returned as:

  • activated_until
  • expires_at
  • license.expires
  • license.expires_at

Expiry must begin with YYYY-MM-DD and must not be earlier than the current local date.

Rejected response

Non-200 status, non-object JSON, false/ambiguous boolean values, invalid expiry, expired license, transport failure, or disallowed URL returns (False, message) and does not activate the session.

Task model

TaskItem

Fields: email, name, status, attempts, message, result.

TaskState

Fields include slot ID, target URL, items, current index, success/failed counters, status, and creation time. Computed properties: total, remaining, and progress.

Worker control API

Commands

  • request_start(settings, target_url)
  • request_focus()
  • request_close()

UI events

Event Purpose
log Structured task log message
progress Counts/index/progress update
status Task lifecycle state
item Report row
security Manual security-challenge warning
browser Open/closed state
login Verified/not-verified state and message
send_limit Used and configured Send clicks
done Processing/browser lifecycle completion
license_invalid Force session close and login UI

Exceptions

  • SecurityChallenge: a challenge requires manual completion and resume.
  • SessionVerificationError: authenticated Test Mode Share page cannot be verified.
  • TestModeRequired: Test Mode banner is missing before Send.
  • TestSendLimitReached: current Start-run cap is exhausted.
  • InviteRejected: target UI displayed an explicit invite error that can be safely retried under configured policy.