netgsm

README

go-netgsm

An idiomatic Go client for the NetGSM SMS REST API (v2). Context-aware, typed errors, fully tested, standard-library only.

Why

There is no well-maintained, idiomatic Go client for NetGSM — most projects hand-roll the HTTP call every time. This one targets the modern REST v2 API (https://api.netgsm.com.tr/sms/rest/v2), uses HTTP Basic auth, and turns NetGSM's numeric result codes into typed errors you can match with errors.Is.

Install

go get github.com/YusufDrymz/go-netgsm

Usage

client := netgsm.New(netgsm.Config{
    UserCode: "your-usercode",
    Password: "your-api-password",
    Header:   "YOUR_HEADER", // approved sender name
}, netgsm.WithTimeout(10*time.Second))

res, err := client.Send(ctx, netgsm.SMS{
    To:   []string{"5301112233", "5304445566"},
    Text: "Merhaba dünya",
})
if err != nil {
    if errors.Is(err, netgsm.ErrSystem) {
        // provider-side error, safe to retry
    }
    return
}
fmt.Println("job id:", res.JobID)

Scheduled send and one-time passwords:

client.Send(ctx, netgsm.SMS{To: to, Text: msg,
    StartAt: time.Now().Add(time.Hour)}) // schedule
client.SendOTP(ctx, netgsm.OTP{To: "5301112233", Text: "Kod: 1234"})

Errors

Every NetGSM result code maps to a typed error. Match the family with errors.Is, or read the concrete code with errors.As:

Sentinel	Codes	Meaning
ErrMessageTooLong	20	message text invalid / too long
ErrInvalidCredentials	30	bad credentials or no API permission
ErrInvalidHeader	40, 41	sender header not defined
ErrIYSFilter	50, 51	İYS-controlled sending not allowed
ErrInvalidParams	70	invalid or missing parameters
ErrDuplicateLimit	85	duplicate-send rate limit hit
ErrSystem	100	provider system error (Retryable: true)

var apiErr *netgsm.Error
if errors.As(err, &apiErr) && apiErr.Retryable {
    // back off and retry
}

Options

Option	Default
WithTimeout(d)	30s
WithEncoding(enc)	TR (use ASCII for GSM-7)
WithHTTPClient(h)	http.Client{Timeout: 30s}
WithBaseURL(u)	https://api.netgsm.com.tr

See examples/.

🇹🇷 Türkçe

NetGSM SMS REST API (v2) için idiomatic bir Go istemcisi. Context destekli, typed error'lı, tam test edilmiş, sıfır dış bağımlılık.

Kurulum: go get github.com/YusufDrymz/go-netgsm

client := netgsm.New(netgsm.Config{
    UserCode: "kullanici", Password: "api-sifresi", Header: "BASLIK",
})
res, err := client.Send(ctx, netgsm.SMS{To: []string{"5301112233"}, Text: "Merhaba"})

NetGSM dönüş kodları typed error'a çevrilir: ErrInvalidCredentials (30), ErrInvalidHeader (40/41), ErrIYSFilter (50/51), ErrInvalidParams (70), ErrDuplicateLimit (85), ErrSystem (100, retryable). errors.Is ile aile, errors.As ile ham kod kontrol edilir. Zamanlanmış gönderim (StartAt/StopAt) ve OTP (SendOTP) desteklenir.

License

MIT — see LICENSE.

Documentation

Overview

Package netgsm is an idiomatic Go client for the NetGSM SMS REST API (v2).

It targets https://api.netgsm.com.tr/sms/rest/v2 with HTTP Basic auth, turns NetGSM's numeric result codes into typed errors you can match with errors.Is, and is fully testable through an injectable *http.Client. The only dependency is the standard library (testify is used for tests).

Index

• Variables
• type Client
  • func New(cfg Config, opts ...Option) *Client
  • func (c *Client) Send(ctx context.Context, sms SMS) (Result, error)
  • func (c *Client) SendOTP(ctx context.Context, otp OTP) (Result, error)
• type Config
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Is(target error) bool
• type OTP
• type Option
  • func WithBaseURL(u string) Option
  • func WithEncoding(enc string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithTimeout(d time.Duration) Option
• type Result
• type SMS

Variables

var (
	ErrMessageTooLong     = &Error{kind: kindMessageTooLong, Message: "message text invalid or too long"}
	ErrInvalidCredentials = &Error{kind: kindInvalidCredentials, Message: "invalid credentials or no API permission"}
	ErrInvalidHeader      = &Error{kind: kindInvalidHeader, Message: "sender header is not defined"}
	ErrIYSFilter          = &Error{kind: kindIYSFilter, Message: "IYS-controlled sending not allowed"}
	ErrInvalidParams      = &Error{kind: kindInvalidParams, Message: "invalid or missing parameters"}
	ErrDuplicateLimit     = &Error{kind: kindDuplicateLimit, Message: "duplicate sending limit exceeded"}
	ErrSystem             = &Error{kind: kindSystem, Message: "provider system error", Retryable: true}
)

Sentinel errors for matching with errors.Is.

var (
	ErrNoRecipients = errors.New("netgsm: no recipients")
	ErrEmptyMessage = errors.New("netgsm: empty message")
)

ErrNoRecipients and ErrEmptyMessage are returned for invalid input before any HTTP call is made.

Types

type Client

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

Client talks to the NetGSM SMS REST API. It is safe for concurrent use.

func New

func New(cfg Config, opts ...Option) *Client

New returns a Client configured with cfg and the given options.

func (*Client) Send

func (c *Client) Send(ctx context.Context, sms SMS) (Result, error)

Send delivers Text to every number in sms.To and returns the job id.

func (*Client) SendOTP

func (c *Client) SendOTP(ctx context.Context, otp OTP) (Result, error)

SendOTP sends a one-time-password message through the dedicated OTP endpoint.

type Config

type Config struct {
	UserCode string // NetGSM subscriber number / API sub-user
	Password string // API sub-user password
	Header   string // default approved sender name (msgheader)
}

Config holds the NetGSM API credentials and the default approved sender.

type Error

type Error struct {
	Code      string
	Message   string
	Retryable bool
	// contains filtered or unexported fields
}

Error is a NetGSM API error carrying the raw provider code. Match families with errors.Is (e.g. errors.Is(err, ErrInvalidHeader) covers codes 40 and 41) and inspect the concrete value with errors.As to read Code and Retryable.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

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

Is matches by error family, so a returned code 41 satisfies ErrInvalidHeader.

type OTP

type OTP struct {
	To     string
	Text   string
	Header string // optional; overrides Config.Header
}

OTP is a one-time-password send request to a single number.

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (useful for tests or a proxy).

func WithEncoding

func WithEncoding(enc string) Option

WithEncoding sets the message encoding: "TR" (default, Turkish characters) or "ASCII" (cheaper GSM-7, no Turkish characters).

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient injects a custom *http.Client.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the HTTP client timeout.

type Result

type Result struct {
	JobID string // NetGSM job/bulk id, for later report queries
	Code  string // raw success code ("00")
}

Result is a successful send outcome.

type SMS

type SMS struct {
	To      []string
	Text    string
	Header  string    // optional; overrides Config.Header
	StartAt time.Time // optional; schedule start (zero = send now)
	StopAt  time.Time // optional; schedule stop
}

SMS is a send request: the same Text is delivered to every number in To.