reghelp

package module
v1.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 20, 2026 License: MIT Imports: 11 Imported by: 0

README

REGHelp Go SDK — Push Tokens (APNS, FCM), reCAPTCHA Mobile, Cloudflare Turnstile, Google Play Integrity, iCloud HME & Gmail OAuth

Go Reference Go Report Card

Official Go client for the REGHelp Key API. Automate APNS / FCM push tokens, Google Play Integrity attestation, Cloudflare Turnstile, reCAPTCHA Mobile, iCloud Hide My Email and Gmail OAuth flows from idiomatic Go — context-first, typed errors, zero dependencies (stdlib only), production-tested. Drop-in companion to the Python SDK reghelp_client for teams that need an async/await-style Go API for QA automation, mobile attestation, Telegram bot registration and backend integration tests.

Russian version below / Русская версия ниже.

📑 Table of contents / Содержание

🇬🇧 English

🚀 Features
  • Push Token API — APNS, FCM, Telegram iOS / Android / TG-X / TG-Beta push tokens, VoIP push tokens.
  • CAPTCHA API — Cloudflare Turnstile, reCAPTCHA Mobile, status polling, configurable proxy per request.
  • Device Attestation — Google Play Integrity Classic (MEETS_STRONG_INTEGRITY) and Standard / Express (MEETS_DEVICE_INTEGRITY) flows.
  • Email API — iCloud Hide My Email, Gmail OAuth, verification code polling.
  • Idiomatic Go — context.Context first arg, typed errors via errors.Is / errors.As, no global state, safe for concurrent use.
  • Zero deps — only net/http, encoding/json and friends. Drop into any Go project without dependency surface.
  • Retry & backoff — automatic retry on HTTP 429 and network errors with exponential backoff + jitter.
  • Webhook support — pass a callback URL when creating any task to skip polling.

Built for backend engineers, mobile QA automation teams and Telegram bot developers who need a typed Go SDK for REGHelp services.

📦 Installation
go get github.com/REGHELPNET/reghelp-client-go@latest

Requires Go 1.22 or newer (uses net/http.ServeMux-style ergonomics, but only stdlib).

🔧 Quick start
package main

import (
    "context"
    "log"
    "time"

    "github.com/REGHELPNET/reghelp-client-go"
)

func main() {
    cli := reghelp.New("your_api_key")
    ctx := context.Background()

    // Check balance.
    bal, err := cli.GetBalance(ctx)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("balance: %.4f %s", bal.Balance, bal.Currency)

    // Get a Telegram iOS push token.
    task, err := cli.GetPushToken(ctx, reghelp.PushTokenRequest{
        AppName:   "tgiOS",
        AppDevice: reghelp.AppDeviceIOS,
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("task created: %s", task.ID)

    // Wait for the result.
    status, err := cli.WaitForResult(ctx, task.ID, reghelp.ServicePush,
        180*time.Second, 2*time.Second)
    if err != nil {
        log.Fatal(err)
    }
    push := status.(*reghelp.PushStatusResponse)
    log.Printf("push token: %s", push.Token)
}
📚 API reference
Client construction
cli := reghelp.New("api_key",
    reghelp.WithBaseURL("https://api.reghelp.net"),    // default
    reghelp.WithTimeout(45*time.Second),               // default 30s
    reghelp.WithMaxRetries(5),                         // default 3
    reghelp.WithRetryDelay(2*time.Second),             // default 1s
    reghelp.WithUserAgent("my-bot/1.0"),
    reghelp.WithHTTPClient(custom),                    // optional
)
📱 Push tokens (APNS, FCM)
task, _ := cli.GetPushToken(ctx, reghelp.PushTokenRequest{
    AppName:    "tgiOS",                  // tgiOS / tg / tg_beta / tg_x …
    AppDevice:  reghelp.AppDeviceIOS,     // or AppDeviceAndroid
    AppVersion: "12.7",                   // optional
    AppBuild:   "32933",                  // optional
    Ref:        "promo",                  // optional referral tag
})

st, _ := cli.GetPushStatus(ctx, task.ID)
// st.Status == reghelp.TaskStatusDone → st.Token is the push token (hex APNS / FCM string)
Supported AppName values
App AppName AppDevice
Telegram iOS Official tgiOS AppDeviceIOS
Telegram Android Official (Google Play) tg AppDeviceAndroid
Telegram Android Official (Beta) tg_beta AppDeviceAndroid
Telegram X (Challegram) tg_x AppDeviceAndroid
Marking a failed push for refund
_, err := cli.SetPushStatus(ctx, task.ID, "+15551234567", reghelp.PushStatusTypeNoSMS)
// PushStatusTypeNoSMS / PushStatusTypeFlood / PushStatusTypeBanned / PushStatusType2FA
📞 VoIP push token (iOS — required alongside APNS)
voip, _ := cli.GetVoIPToken(ctx, reghelp.VoIPTokenRequest{AppName: "tgiOS"})
st, _ := cli.GetVoIPStatus(ctx, voip.ID)
📧 Email (iCloud HME, Gmail OAuth)
em, _ := cli.GetEmail(ctx, reghelp.EmailRequest{
    AppName:   "tg",
    AppDevice: reghelp.AppDeviceAndroid,
    Phone:     "+15551234567",            // E.164
    Type:      reghelp.EmailTypeICloud,   // or EmailTypeGmail
})

// em.Email is allocated immediately; the verification code arrives later.
res, _ := cli.WaitForResult(ctx, em.ID, reghelp.ServiceEmail, 3*time.Minute, 2*time.Second)
code := res.(*reghelp.EmailStatusResponse).Code
🔒 Play Integrity (Classic / Standard)
task, _ := cli.GetIntegrityToken(ctx, reghelp.IntegrityTokenRequest{
    AppName:        "tg",
    AppDevice:      reghelp.AppDeviceAndroid,
    Nonce:          nonceFromTGServer,    // 16..500 URL-safe base64 chars
    AppVersionCode: 31948,                // mandatory since Key API v2026-05
    TokenType:      reghelp.IntegrityTokenTypeClassic, // or IntegrityTokenTypeStd
})
res, _ := cli.WaitForResult(ctx, task.ID, reghelp.ServiceIntegrity, 30*time.Second, 1*time.Second)
token := res.(*reghelp.IntegrityStatusResponse).Token
Flow Latency TG flag Result
Classic (IntegrityTokenTypeClassic, default) ~1-3 s MEETS_STRONG_INTEGRITY long-lived
Standard/Express (IntegrityTokenTypeStd) ~200-600 ms MEETS_DEVICE_INTEGRITY shorter-lived
🤖 reCAPTCHA Mobile
task, _ := cli.GetRecaptchaMobileToken(ctx, reghelp.RecaptchaMobileRequest{
    AppName:   "org.telegram.messenger",
    AppDevice: reghelp.AppDeviceAndroid,
    AppKey:    "6Lc-recaptcha-site-key",
    AppAction: "login",
    Proxy: &reghelp.ProxyConfig{
        Type:    reghelp.ProxyTypeHTTP,
        Address: "p.example.com", Port: 8080,
        Login: "user", Password: "pass",
    },
})
res, _ := cli.WaitForResult(ctx, task.ID, reghelp.ServiceRecaptcha, 2*time.Minute, 2*time.Second)
token := res.(*reghelp.RecaptchaMobileStatusResponse).Token
🔐 Cloudflare Turnstile
task, _ := cli.GetTurnstileToken(ctx, reghelp.TurnstileRequest{
    URL:     "https://example.com/page",
    SiteKey: "0x4AAAA...",
    Action:  "login",
})
res, _ := cli.WaitForResult(ctx, task.ID, reghelp.ServiceTurnstile, 2*time.Minute, 2*time.Second)
token := res.(*reghelp.TurnstileStatusResponse).Token
🔄 Polling
status, err := cli.WaitForResult(ctx, task.ID,
    reghelp.ServicePush,                  // push / email / integrity / recaptcha / turnstile / voip
    180*time.Second,                      // total timeout
    2*time.Second,                        // poll interval
)

Returns when the task reaches a terminal state (done / error), the deadline elapses (reghelp.ErrTimeout) or ctx is cancelled.

🪝 Webhooks

Pass a Webhook URL on any Get…Token / GetEmail call to receive a POST when the task completes, instead of polling.

🚨 Error handling

All errors are wrapped in *reghelp.Error. Compare with sentinel errors via errors.Is:

_, err := cli.GetPushToken(ctx, req)
switch {
case errors.Is(err, reghelp.ErrUnauthorized):
    // invalid API key
case errors.Is(err, reghelp.ErrRateLimit):
    // back off
case errors.Is(err, reghelp.ErrTaskNotFound):
    // task ID mismatch
case errors.Is(err, reghelp.ErrTimeout):
    // WaitForResult deadline
case err != nil:
    var apiErr *reghelp.Error
    if errors.As(err, &apiErr) {
        log.Printf("[%d %s] %s", apiErr.Status, apiErr.Code, apiErr.Message)
    }
}

Sentinel errors:

Sentinel Trigger
ErrUnauthorized HTTP 401 / id=UNAUTHORIZED
ErrRateLimit HTTP 429 / id=RATE_LIMIT
ErrServiceDisabled id=SERVICE_DISABLED
ErrMaintenance id=MAINTENANCE_MODE
ErrTaskNotFound HTTP 404 / id=TASK_NOT_FOUND
ErrInvalidParameter HTTP 400 / id=INVALID_PARAM
ErrExternalService HTTP 502 / id=EXTERNAL_ERROR
ErrTimeout WaitForResult deadline reached
ErrNetwork transport-level failure
ErrInvalidJSONResult non-JSON response body
⚙️ Configuration
Option Default
WithBaseURL(string) https://api.reghelp.net
WithHTTPClient(*http.Client) &http.Client{Timeout: 30s}
WithTimeout(time.Duration) 30s
WithMaxRetries(int) 3
WithRetryDelay(time.Duration) 1s (base for exponential back-off)
WithUserAgent(string) reghelp-client-go/<version>
🧪 Examples

End-to-end demo: examples/basic.

REGHELP_API_KEY=your_key go run ./examples/basic

🇷🇺 Русская версия

Официальный Go SDK для REGHelp Key API — push-токены (APNS / FCM), Cloudflare Turnstile, reCAPTCHA Mobile, Google Play Integrity, iCloud Hide My Email и Gmail OAuth. Типизированные ошибки, контекст-первый API, нулевые внешние зависимости (только стандартная библиотека). Подходит для автоматизации регистраций Telegram-аккаунтов на iOS / Android / TG-X / TG-Beta, мобильной аттестации устройств и backend-интеграционных тестов. Пара к Python SDK reghelp_client.

🚀 Возможности
  • Push-токены: APNS, FCM, Telegram iOS / Android Official / TG-X / TG-Beta, VoIP push (iOS).
  • CAPTCHA: Cloudflare Turnstile и reCAPTCHA Mobile с опциональным прокси на каждую задачу.
  • Play Integrity: Classic (MEETS_STRONG_INTEGRITY) и Standard / Express (MEETS_DEVICE_INTEGRITY).
  • Email: iCloud Hide My Email и Gmail OAuth с автоматическим ожиданием кода.
  • Идиоматический Go: context.Context-first, типизированные ошибки через errors.Is / errors.As, безопасность для конкурентного использования.
  • Нулевые зависимости: только стандартная библиотека Go (net/http, encoding/json …).
  • Автоматический ретрай на HTTP 429 и сетевых ошибках с экспоненциальной задержкой и джиттером.
  • Поддержка webhook вместо polling — указать Webhook: "https://…" в любом Get…Token запросе.
📦 Установка
go get github.com/REGHELPNET/reghelp-client-go@latest

Требуется Go 1.22+.

🔧 Быстрый старт
package main

import (
    "context"
    "log"
    "time"

    "github.com/REGHELPNET/reghelp-client-go"
)

func main() {
    cli := reghelp.New("your_api_key")
    ctx := context.Background()

    bal, _ := cli.GetBalance(ctx)
    log.Printf("Баланс: %.4f %s", bal.Balance, bal.Currency)

    task, _ := cli.GetPushToken(ctx, reghelp.PushTokenRequest{
        AppName:   "tgiOS",
        AppDevice: reghelp.AppDeviceIOS,
    })
    status, _ := cli.WaitForResult(ctx, task.ID, reghelp.ServicePush,
        180*time.Second, 2*time.Second)
    log.Printf("Push токен: %s", status.(*reghelp.PushStatusResponse).Token)
}
📚 Документация

Полная справка по API — раздел API reference выше (примеры и сигнатуры совпадают с Go-версией). Соответствие методов Python SDK один-в-один:

Python Go
RegHelpClient(api_key, ...) reghelp.New(apiKey, opts...)
await client.get_balance() cli.GetBalance(ctx)
await client.get_push_token(...) cli.GetPushToken(ctx, req)
await client.get_voip_token(...) cli.GetVoIPToken(ctx, req)
await client.get_email(...) cli.GetEmail(ctx, req)
await client.get_integrity_token(...) cli.GetIntegrityToken(ctx, req)
await client.get_recaptcha_mobile_token(...) cli.GetRecaptchaMobileToken(ctx, req)
await client.get_turnstile_token(...) cli.GetTurnstileToken(ctx, req)
await client.wait_for_result(id, service, ...) cli.WaitForResult(ctx, id, service, ...)
🚨 Обработка ошибок
_, err := cli.GetBalance(ctx)
if errors.Is(err, reghelp.ErrUnauthorized) { /* неверный API-ключ */ }
if errors.Is(err, reghelp.ErrRateLimit)    { /* лимит, ретрай позже */ }

Полный список sentinel-ошибок — таблица в English-разделе.

❓ FAQ

Q: Почему ноль зависимостей? Хочется красивый http-клиент. A: Передайте свой *http.Client через reghelp.WithHTTPClient(...). SDK не лезет в выбор клиента, чтобы не тащить транзитивные зависимости.

Q: Подходит ли SDK для concurrent-использования? A: Да. Один *reghelp.Client безопасен для конкурентных вызовов из любого числа горутин — состояние только read-after-construct.

Q: Где взять api_key? A: На дашборде reghelp.net. Тот же ключ, что у Python SDK.

Q: Чем отличается Classic Integrity от Standard? A: Classic (default) делает полный запрос Play Integrity, занимает 1-3 с, токен живёт долго (MEETS_STRONG_INTEGRITY). Standard / Express использует кэшированный device token (MEETS_DEVICE_INTEGRITY), 200-600 мс, короче живёт.

Q: Нужно ли вызывать client.Close() или defer? A: Нет — SDK не держит долгоживущих ресурсов сверх http.Client.Timeout. Если передан кастомный клиент, его lifecycle на вас.

📄 License

MIT — see LICENSE.

Copyright (c) 2026 REGHelp Team.

Documentation

Overview

Package reghelp is the official Go SDK for the REGHelp Key API — push tokens (APNS, FCM), Cloudflare Turnstile, reCAPTCHA Mobile, Google Play Integrity, iCloud Hide My Email, Gmail OAuth and VoIP push, with typed errors, configurable retries and zero external dependencies.

It mirrors the Python SDK (github.com/REGHELPNET/reghelp_client) in feature coverage and method naming while following Go idioms: context-first APIs, typed errors via errors.As / errors.Is, and stdlib-only HTTP transport.

Quick start 

cli := reghelp.New("your_api_key")

ctx := context.Background()
bal, err := cli.GetBalance(ctx)
if err != nil {
    log.Fatal(err)
}
log.Printf("balance: %.4f %s", bal.Balance, bal.Currency)

task, err := cli.GetPushToken(ctx, reghelp.PushTokenRequest{
    AppName:   "tgiOS",
    AppDevice: reghelp.AppDeviceIOS,
})
if err != nil {
    log.Fatal(err)
}
status, err := cli.WaitForResult(ctx, task.ID, reghelp.ServicePush, 180*time.Second, 2*time.Second)
if err != nil {
    log.Fatal(err)
}
log.Printf("push token: %s", status.(*reghelp.PushStatusResponse).Token)

All services (Push, VoIP, Email, Integrity, Turnstile, RecaptchaMobile) are supported. See examples/basic for an end-to-end demo.

Index

Constants

View Source 
const DefaultBaseURL = "https://api.reghelp.net"

DefaultBaseURL is the production REGHelp Key API endpoint.

Variables

View Source 
var (
	ErrUnauthorized      = errors.New("reghelp: invalid api key")
	ErrRateLimit         = errors.New("reghelp: rate limit exceeded")
	ErrServiceDisabled   = errors.New("reghelp: service temporarily disabled")
	ErrMaintenance       = errors.New("reghelp: api in maintenance mode")
	ErrTaskNotFound      = errors.New("reghelp: task not found")
	ErrInvalidParameter  = errors.New("reghelp: invalid parameter")
	ErrExternalService   = errors.New("reghelp: external service error")
	ErrUnknown           = errors.New("reghelp: unknown error")
	ErrNetwork           = errors.New("reghelp: network error")
	ErrTimeout           = errors.New("reghelp: timeout waiting for task result")
	ErrInvalidJSONResult = errors.New("reghelp: invalid JSON in response")
)

Sentinel error codes. Compare with errors.Is(err, reghelp.ErrUnauthorized).

Functions

This section is empty.

Types

type AnyStatus 

type AnyStatus interface {
	// contains filtered or unexported methods
}

AnyStatus is the return type of WaitForResult — one of *PushStatusResponse, *VoipStatusResponse, *EmailStatusResponse, *IntegrityStatusResponse, *RecaptchaMobileStatusResponse, *TurnstileStatusResponse, *AttestationStatusResponse.

type AppDevice 

type AppDevice string

AppDevice identifies the target mobile platform of a request. 

const (
	AppDeviceIOS     AppDevice = "iOS"
	AppDeviceAndroid AppDevice = "Android"
)

type AttestationStatusResponse added in v1.1.0 

type AttestationStatusResponse struct {
	StatusResponse
	Authorization     string `json:"authorization,omitempty"`
	Sign              string `json:"sign,omitempty"`
	LeafPrivateKeyB64 string `json:"leafPrivateKeyB64,omitempty"`
	KeyboxDeviceID    string `json:"keyboxDeviceId,omitempty"`
}

AttestationStatusResponse is the attestation.getStatus result.

On TaskStatusDone the full SignResponse payload is returned: an X.509 certificate chain (base64-encoded DER concatenation), the optional ECDSA signature over the request's enc field, the leaf private key (PKCS#8 / base64), and the keybox device id used for debugging which keybox served the request.

type AttestationTokenRequest added in v1.1.0 

type AttestationTokenRequest struct {
	// AuthKey is the Google-issued challenge nonce.
	// Hex or base64 (std/url-safe), 4..512 characters.
	AuthKey string

	// Optional 32-byte hex overrides. Empty values fall back to the
	// server's zero-array placeholder (C3/C4 normalisation rule in
	// attestation-server).
	VerifiedBootKey  string
	VerifiedBootHash string

	// Optional embedded APK metadata overrides. Leave zero/empty to
	// use the attestation-server defaults.
	APKVersionCode     int
	PackageName        string
	APKSignatureSha256 string

	// Optional base64 payload to ECDSA-sign with the leaf key. The
	// signature comes back as `Sign` in the status response.
	Enc string

	// Ref is an optional referral tag.
	Ref string
	// Webhook is an optional URL to receive completion notifications.
	Webhook string
}

AttestationTokenRequest contains the parameters for Client.GetAttestationToken.

AuthKey is the only mandatory field — every other knob has a sensible default on the attestation-server side. The flow is generic Android Key Attestation: wraps a TEE-bound keybox from the server-side pool and returns an X.509 chain with the KeyMint attestation extension (OID 1.3.6.1.4.1.11129.2.1.17). Override package name, APK version and signature to target any Google-issued challenge.

type BalanceResponse 

type BalanceResponse struct {
	Status   string  `json:"status"`
	Balance  float64 `json:"balance"`
	Currency string  `json:"currency"`
}

BalanceResponse is the result of GetBalance.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client talks to the REGHelp Key API. Construct with New; all methods are safe for concurrent use.

func New 

func New(apiKey string, opts ...Option) *Client

New returns a Client bound to apiKey. Options are applied in order.

func (*Client) BaseURL 

func (c *Client) BaseURL() string

BaseURL reports the URL the client targets.

func (*Client) GetAttestationStatus added in v1.1.0 

func (c *Client) GetAttestationStatus(ctx context.Context, taskID string) (*AttestationStatusResponse, error)

GetAttestationStatus polls an Android Key Attestation task.

func (*Client) GetAttestationToken added in v1.1.0 

func (c *Client) GetAttestationToken(ctx context.Context, req AttestationTokenRequest) (*TokenResponse, error)

GetAttestationToken creates an Android Key Attestation task.

The result is asynchronous: the returned TokenResponse carries the task ID; poll GetAttestationStatus (or WaitForResult with service="attestation") until Status == TaskStatusDone.

func (*Client) GetBalance 

func (c *Client) GetBalance(ctx context.Context) (*BalanceResponse, error)

GetBalance returns the current account balance.

func (*Client) GetEmail 

func (c *Client) GetEmail(ctx context.Context, req EmailRequest) (*EmailGetResponse, error)

GetEmail allocates a temporary email address (iCloud HME or Gmail OAuth) for the given phone. The verification code is delivered asynchronously — poll via Client.WaitForResult / Client.GetEmailStatus.

func (*Client) GetEmailStatus 

func (c *Client) GetEmailStatus(ctx context.Context, taskID string) (*EmailStatusResponse, error)

GetEmailStatus polls an email-task for the verification code.

func (*Client) GetIntegrityStatus 

func (c *Client) GetIntegrityStatus(ctx context.Context, taskID string) (*IntegrityStatusResponse, error)

GetIntegrityStatus polls a Play Integrity task.

func (*Client) GetIntegrityToken 

func (c *Client) GetIntegrityToken(ctx context.Context, req IntegrityTokenRequest) (*TokenResponse, error)

GetIntegrityToken creates a Play Integrity attestation task.

func (*Client) GetPushStatus 

func (c *Client) GetPushStatus(ctx context.Context, taskID string) (*PushStatusResponse, error)

GetPushStatus polls a push-token task.

func (*Client) GetPushToken 

func (c *Client) GetPushToken(ctx context.Context, req PushTokenRequest) (*TokenResponse, error)

GetPushToken creates an asynchronous task for an APNS / FCM push token.

func (*Client) GetRecaptchaMobileStatus 

func (c *Client) GetRecaptchaMobileStatus(ctx context.Context, taskID string) (*RecaptchaMobileStatusResponse, error)

GetRecaptchaMobileStatus polls a mobile reCAPTCHA task.

func (*Client) GetRecaptchaMobileToken 

func (c *Client) GetRecaptchaMobileToken(ctx context.Context, req RecaptchaMobileRequest) (*TokenResponse, error)

GetRecaptchaMobileToken creates an asynchronous mobile reCAPTCHA task.

func (*Client) GetTurnstileStatus 

func (c *Client) GetTurnstileStatus(ctx context.Context, taskID string) (*TurnstileStatusResponse, error)

GetTurnstileStatus polls a Turnstile task.

func (*Client) GetTurnstileToken 

func (c *Client) GetTurnstileToken(ctx context.Context, req TurnstileRequest) (*TokenResponse, error)

GetTurnstileToken solves a Cloudflare Turnstile challenge.

func (*Client) GetVoIPStatus 

func (c *Client) GetVoIPStatus(ctx context.Context, taskID string) (*VoipStatusResponse, error)

GetVoIPStatus polls a VoIP token task.

func (*Client) GetVoIPToken 

func (c *Client) GetVoIPToken(ctx context.Context, req VoIPTokenRequest) (*TokenResponse, error)

GetVoIPToken creates an asynchronous task for an iOS VoIP push token. On iOS both push (APNS) and VoIP tokens are required for registerDevice.

func (*Client) HealthCheck 

func (c *Client) HealthCheck(ctx context.Context) (bool, error)

HealthCheck pings GET /health. Returns true iff the API answers 200. Does not require an API key.

func (*Client) SetPushStatus 

func (c *Client) SetPushStatus(ctx context.Context, taskID, phoneNumber string, status PushStatusType) (*SetPushStatusResult, error)

SetPushStatus reports a failed push-token task to enable refund. Status is one of PushStatusType values (NOSMS, FLOOD, BANNED, 2FA). PhoneNumber must be in E.164 format.

func (*Client) WaitForResult 

func (c *Client) WaitForResult(
	ctx context.Context,
	taskID string,
	service Service,
	timeout time.Duration,
	pollInterval time.Duration,
) (AnyStatus, error)

WaitForResult polls the matching getStatus endpoint until the task reaches a terminal state (done or error), the deadline elapses, or ctx is canceled.

timeout 0 → 180s (matches Python SDK default). pollInterval 0 → 2s (matches Python SDK default).

Returns the concrete *XxxStatusResponse (use AnyStatus for the interface boundary). On timeout returns ErrTimeout; on ctx cancel returns ctx.Err().

type EmailGetResponse 

type EmailGetResponse struct {
	Status  string  `json:"status"`
	ID      string  `json:"id"`
	Email   string  `json:"email"`
	Service string  `json:"service"`
	Product string  `json:"product"`
	Price   float64 `json:"price"`
	Balance float64 `json:"balance"`
}

EmailGetResponse is the result of GetEmail (the email is allocated immediately; the verification code is retrieved later via WaitForResult / GetEmailStatus).

type EmailRequest 

type EmailRequest struct {
	AppName   string
	AppDevice AppDevice
	Phone     string // E.164
	Type      EmailType
	Ref       string // optional
	Webhook   string // optional
}

EmailRequest contains the parameters for Client.GetEmail.

type EmailStatusResponse 

type EmailStatusResponse struct {
	StatusResponse
	Email string `json:"email,omitempty"`
	Code  string `json:"code,omitempty"`
}

EmailStatusResponse is the email.getStatus result.

type EmailType 

type EmailType string

EmailType selects the temporary email provider. 

const (
	EmailTypeICloud EmailType = "icloud"
	EmailTypeGmail  EmailType = "gmail"
)

type Error 

type Error struct {
	Status  int
	Code    string
	Message string
	Raw     map[string]any
	// Unwrapped underlying error, if any (e.g. network/timeout).
	Cause error
}

Error is the base error type returned by the SDK.

Status is the HTTP status code (or 0 for transport errors). Code mirrors the `id` field from the REGHelp error envelope when present (RATE_LIMIT, SERVICE_DISABLED, MAINTENANCE_MODE, TASK_NOT_FOUND, INVALID_PARAM, EXTERNAL_ERROR …). Raw holds the decoded error envelope for callers that need the original fields (e.g. balance on push.setStatus error).

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Is 

func (e *Error) Is(target error) bool

Is reports whether err equals one of the sentinel errors above. Implements errors.Is for chained Error values.

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type IntegrityStatusResponse 

type IntegrityStatusResponse struct {
	StatusResponse
	Token string `json:"token,omitempty"`
}

IntegrityStatusResponse is the integrity.getStatus result.

type IntegrityTokenRequest 

type IntegrityTokenRequest struct {
	AppName        string
	AppDevice      AppDevice
	Nonce          string // URL-safe Base64, 16..500 chars
	AppVersionCode int    // 1..2_147_483_647 (mandatory)
	TokenType      IntegrityTokenType
	Ref            string
	Webhook        string
}

IntegrityTokenRequest contains the parameters for Client.GetIntegrityToken.

AppVersionCode is mandatory since Key API v2026-05 — it must match the APK versionCode of the target app at signing time. Valid range: 1..2_147_483_647.

TokenType selects the Play Integrity flow:

type IntegrityTokenType 

type IntegrityTokenType string

IntegrityTokenType selects the Play Integrity flow.

CLASSIC is the default and is sent on the wire by omitting the `type` parameter (returns a long-lived strong-integrity token, ~1-3s). STD opts into the Standard/Express flow with `type=std` (returns a device-integrity token, ~200-600ms). 

const (
	IntegrityTokenTypeClassic IntegrityTokenType = "classic"
	IntegrityTokenTypeStd     IntegrityTokenType = "std"
)

type Option 

type Option func(*Client)

Option customizes the Client returned by New.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (default DefaultBaseURL).

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies a custom *http.Client. The client must honor context cancellation — i.e., its Transport should propagate ctx deadlines.

func WithMaxRetries 

func WithMaxRetries(n int) Option

WithMaxRetries sets the maximum number of retry attempts on transient failures (429, network errors). Default 3.

func WithRetryDelay 

func WithRetryDelay(d time.Duration) Option

WithRetryDelay sets the base back-off delay between retries (default 1s). Effective delay scales as base * 2^attempt.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets the HTTP client's per-request timeout (default 30s). Ignored if WithHTTPClient is also passed.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent overrides the User-Agent header sent on every request.

type ProxyConfig 

type ProxyConfig struct {
	Type     ProxyType
	Address  string
	Port     int
	Login    string // optional
	Password string // optional
}

ProxyConfig describes an upstream proxy for services that support it (currently only RecaptchaMobile via proxyType/proxyAddress/...).

Address up to 255 chars, Login up to 128, Password up to 256 (limits enforced by the REGHelp API since v1.2.1).

func (ProxyConfig) Validate 

func (p ProxyConfig) Validate() error

Validate reports whether p is structurally valid for an outgoing request.

type ProxyType 

type ProxyType string

ProxyType identifies a proxy scheme accepted by ProxyConfig. 

const (
	ProxyTypeHTTP   ProxyType = "http"
	ProxyTypeHTTPS  ProxyType = "https"
	ProxyTypeSOCKS4 ProxyType = "socks4"
	ProxyTypeSOCKS5 ProxyType = "socks5"
)

type PushStatusResponse 

type PushStatusResponse struct {
	StatusResponse
	Token string `json:"token,omitempty"`
}

PushStatusResponse is the push.getStatus result.

type PushStatusType 

type PushStatusType string

PushStatusType is the failure reason for SetPushStatus refund flow. 

const (
	PushStatusTypeNoSMS  PushStatusType = "NOSMS"
	PushStatusTypeFlood  PushStatusType = "FLOOD"
	PushStatusTypeBanned PushStatusType = "BANNED"
	PushStatusType2FA    PushStatusType = "2FA"
)

type PushTokenRequest 

type PushTokenRequest struct {
	AppName    string    // e.g. "tgiOS", "tg", "tg_beta", "tg_x"
	AppDevice  AppDevice // AppDeviceIOS / AppDeviceAndroid
	AppVersion string    // optional
	AppBuild   string    // optional
	Ref        string    // optional referral tag
	Webhook    string    // optional notification URL
}

PushTokenRequest contains the parameters for Client.GetPushToken.

type RecaptchaMobileRequest 

type RecaptchaMobileRequest struct {
	AppName   string    // e.g. "org.telegram.messenger"
	AppDevice AppDevice // iOS / Android
	AppKey    string    // reCAPTCHA site key
	AppAction string    // e.g. "login"
	Proxy     *ProxyConfig
	Ref       string
	Webhook   string
}

RecaptchaMobileRequest contains the parameters for Client.GetRecaptchaMobileToken.

type RecaptchaMobileStatusResponse 

type RecaptchaMobileStatusResponse struct {
	StatusResponse
	Token string `json:"token,omitempty"`
}

RecaptchaMobileStatusResponse is the RecaptchaMobile.getStatus result.

type Service 

type Service string

Service identifies a polled service for WaitForResult. 

const (
	ServicePush        Service = "push"
	ServiceEmail       Service = "email"
	ServiceIntegrity   Service = "integrity"
	ServiceRecaptcha   Service = "recaptcha"
	ServiceTurnstile   Service = "turnstile"
	ServiceVoIP        Service = "voip"
	ServiceAttestation Service = "attestation"
)

type SetPushStatusResult 

type SetPushStatusResult struct {
	Success bool
	// Balance is set when the server returned an updated balance on either
	// "success" or recoverable "error" envelopes (e.g. refund flow).
	Balance *float64
	// Raw is the original decoded JSON envelope, in case the caller needs more.
	Raw map[string]any
}

SetPushStatusResult is the parsed envelope returned by SetPushStatus.

type StatusResponse 

type StatusResponse struct {
	ID      string     `json:"id"`
	Status  TaskStatus `json:"status"`
	Message string     `json:"message,omitempty"`
}

StatusResponse is the common shape of all *getStatus endpoints. Concrete token / code fields are populated only when Status == TaskStatusDone.

type TaskStatus 

type TaskStatus string

TaskStatus is the lifecycle state of an asynchronous REGHelp task. 

const (
	TaskStatusWait       TaskStatus = "wait"
	TaskStatusPending    TaskStatus = "pending"
	TaskStatusSubmitted  TaskStatus = "submitted"
	TaskStatusRunning    TaskStatus = "running"
	TaskStatusProcessing TaskStatus = "processing"
	TaskStatusDone       TaskStatus = "done"
	TaskStatusError      TaskStatus = "error"
)

func (TaskStatus) IsTerminal 

func (s TaskStatus) IsTerminal() bool

IsTerminal reports whether the task has reached a final state.

type TokenResponse 

type TokenResponse struct {
	Status  string  `json:"status"`
	ID      string  `json:"id"`
	Service string  `json:"service"`
	Product string  `json:"product"`
	Price   float64 `json:"price"`
	Balance float64 `json:"balance"`
}

TokenResponse is the create-task response shared by Push / VoIP / Email / Integrity / Recaptcha / Turnstile getToken endpoints.

type TurnstileRequest 

type TurnstileRequest struct {
	URL     string // page URL with the widget
	SiteKey string // Turnstile site key
	Action  string // optional expected action
	CData   string // optional custom data
	Proxy   string // optional, "scheme://host:port"
	Actor   string // optional
	Scope   string // optional
	Ref     string
	Webhook string
}

TurnstileRequest contains the parameters for Client.GetTurnstileToken.

type TurnstileStatusResponse 

type TurnstileStatusResponse struct {
	StatusResponse
	Token string `json:"token,omitempty"`
}

TurnstileStatusResponse is the turnstile.getStatus result.

type VoIPTokenRequest 

type VoIPTokenRequest struct {
	AppName string
	Ref     string // optional
	Webhook string // optional
}

VoIPTokenRequest contains the parameters for Client.GetVoIPToken (iOS).

type VoipStatusResponse 

type VoipStatusResponse struct {
	StatusResponse
	Token string `json:"token,omitempty"`
}

VoipStatusResponse is the pushVoip.getStatus result.

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
Basic usage example for the reghelp-client-go SDK.
 Basic usage example for the reghelp-client-go SDK.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.