client

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jan 14, 2021 License: BSD-3-Clause Imports: 23 Imported by: 0

Documentation

Overview

This package provides a client for sending messages via Threema.Gateway.

Index

Constants

View Source 
const (
	DefaultThreemaGatewayURL = "https://msgapi.threema.ch"
	MaxTextMessageBytes      = 3500
)
View Source 
const (
	TypeTextMessage     MessageType = 0x01 // Content: UTF-8 encoded string
	TypeImageMessage                = 0x02 // Unsupported, TODO
	TypeFileMessage                 = 0x17 // Unsupported, TODO
	TypeDeliveryReceipt             = 0x80 // Unsupported, TODO

	Received     DeliveryReceiptType = 0x01
	Read                             = 0x02
	Acknowledged                     = 0x03
	Declined                         = 0x04
)

Variables

View Source 
var (
	// Caller errors
	ErrInvalidPhoneNumber = errors.New("invalid phone number, must consist of at most 15 digits")
	ErrIDLength           = errors.New("id must be exactly 8 bytes long")

	ErrImageTooLarge = errors.New("image too large")

	// API errors
	ErrInvalidRequest = errors.New("invalid recipient or identity not set up for chosen mode (simple/e2e)")
	ErrMissingBlob    = errors.New("missing parameters or blob is empty")
	ErrCredentials    = errors.New("wrong id or secret for API")
	ErrOutOfCredits   = errors.New("out of credits")
	ErrNotFound       = errors.New("id not found")
	ErrMessageTooLong = errors.New("message too long")
	ErrBlobTooLarge   = errors.New("blob too large")
	ErrTemporary      = errors.New("temporary API failure")
	ErrUnknown        = errors.New("unknown API error")
)
View Source 
var (
	ErrUnknownMessageType = errors.New("unknown message type")
	ErrInvalidPadding     = errors.New("invalid padding")
	ErrInvalidBlobID      = errors.New("invalid blob ID")
)

Functions

func PackMessage added in v0.2.0 

func PackMessage(msg Message) ([]byte, error)

Packs the specified message, including random padding

Types

type BlobID added in v0.2.0 

type BlobID = [16]byte

type Client 

type Client interface {
	ID() string

	// Fetches the remaining credits for the ID associated with the Client.
	GetRemainingCredits() (int, error)

	LookupIDByPhoneHash(phoneNumber string) (ThreemaID, error)
	LookupIDByEmailHash(address string) (ThreemaID, error)

	SendTextMessage(id ThreemaID, apiSecret string) error
	SendTextMessageToPhone(phone string, apiSecret string) error
	SendTextMessageToEmail(address string, apiSecret string) error
}

type DeliveryReceipt 

type DeliveryReceipt struct {
	Type       DeliveryReceiptType
	MessageIDs [][8]byte
}

type DeliveryReceiptType added in v0.2.0 

type DeliveryReceiptType byte

type E2EClient 

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

An E2EClient has a private key to sign and encrypt messages with.

It automatically caches ID->PubKey lookups as adivsed in the Threema.Gateway documentation.

func NewE2EClient 

func NewE2EClient(id ThreemaID, apiSecret string, privateKey PrivateKey) (*E2EClient, error)

func (*E2EClient) GetCapabilities 

func (c *E2EClient) GetCapabilities(id ThreemaID) ([]string, error)

Returns the capabilities of the given ID. As of 01/2021, there are five supported capabilities:

  • text
  • image
  • video
  • audio
  • file

func (*E2EClient) GetRemainingCredits 

func (c *E2EClient) GetRemainingCredits() (int, error)

func (*E2EClient) ID added in v0.1.1 

func (c *E2EClient) ID() string

Returns the client's ID

func (*E2EClient) LookupIDByEmailHash 

func (c *E2EClient) LookupIDByEmailHash(address string) (ThreemaID, error)

Looks up the Threema ID of the given e-mail address by its hash. The e-mail must be passed in plaintext, it will be normalized and hashed as necessary.

Returns ErrNotFound if the given address is unknown.

func (*E2EClient) LookupIDByPhoneHash 

func (c *E2EClient) LookupIDByPhoneHash(phoneNumber string) (ThreemaID, error)

Looks up the Threema ID of the given phone number by hash. Phone number must be passed in E.164 format. It will be normalized and hashed as neceassary

Returns ErrNotFound if the given phone number is unknown.

func (*E2EClient) LookupPublicKeyByID 

func (c *E2EClient) LookupPublicKeyByID(requestedID ThreemaID) (PublicKey, error)

Looks up the public key associated with the corresponding ID.

Updates the client's cache on successful lookup.

func (*E2EClient) PublicKey added in v0.1.1 

func (c *E2EClient) PublicKey() PublicKey

Returns the client's hex-encoded public key.

func (*E2EClient) SendImage added in v0.2.0 

func (c *E2EClient) SendImage(to ThreemaID, image io.Reader) error

Send an image to the given Threema ID.

Costs 2 credits (1 to upload image, 1 to send message)

Allowed file types (list not exhaustive)

  • JPEG
  • PNG

func (*E2EClient) SendTextMessage 

func (c *E2EClient) SendTextMessage(to ThreemaID, msg string) error

Send a text message to the given Threema ID.

The public key of the recipient is cached for up to `maxCacheEntryAge`, so multiple invocations of SendTextMessage re-use existing public keys.

The message is encrypted before sending.

func (*E2EClient) SendTextMessageToEmail 

func (c *E2EClient) SendTextMessageToEmail(address string, msg string) error

Send a text message to account associated with the given email address.

E-Mail->ID translations are not cached, so specifying recipients by Threema ID is preferred.

The message is encrypted before sending.

func (*E2EClient) SendTextMessageToPhone 

func (c *E2EClient) SendTextMessageToPhone(phone string, msg string) error

Send a text message to the account associated with the given phone number, passed in E.164 format.

Phone->ID translations are not cached, so specifying recipients by Threema ID is preferred.

The message is encrypted before sending.

func (*E2EClient) SetGatewayURL added in v0.1.1 

func (c *E2EClient) SetGatewayURL(url string)

Set the base URL for the Threema.Gateway server

func (*E2EClient) SetHTTPClient added in v0.1.1 

func (c *E2EClient) SetHTTPClient(httpClient *http.Client)

Set the http.Client to be used

type FileMessage 

type FileMessage struct {
	BlobID          *BlobID
	ThumbnailBlobID *BlobID
	EncryptionKey   *SharedKey
	MimeType        string
	Filename        string
	Size            uint64
	Description     string
}

type ImageMessage 

type ImageMessage struct {
	BlobID BlobID
	Size   uint32
	Nonce  Nonce
}

type Message added in v0.2.0 

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

Abstract interface for messages

func UnpackMessage added in v0.2.0 

func UnpackMessage(in []byte) (Message, error)

Tries to unpack in into a valid message type.

type MessageID added in v0.2.0 

type MessageID = [8]byte

type MessageType 

type MessageType byte

type Nonce 

type Nonce = [24]byte

type PrivateKey 

type PrivateKey = [32]byte

type PublicKey 

type PublicKey = [32]byte

type SharedKey added in v0.2.0 

type SharedKey = [32]byte

type SimpleClient 

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

A simple client has no private key. It can only send text messages, which are encrypted using a key held by Threema.

func NewSimpleClient 

func NewSimpleClient(id ThreemaID, apiSecret string) (*SimpleClient, error)

func (*SimpleClient) GetCapabilities 

func (c *SimpleClient) GetCapabilities(id ThreemaID) ([]string, error)

Returns the capabilities of the given ID. As of 01/2021, there are five supported capabilities:

  • text
  • image
  • video
  • audio
  • file

func (*SimpleClient) GetRemainingCredits 

func (c *SimpleClient) GetRemainingCredits() (int, error)

func (*SimpleClient) ID added in v0.1.1 

func (c *SimpleClient) ID() string

Returns the client's ID

func (*SimpleClient) LookupIDByEmailHash 

func (c *SimpleClient) LookupIDByEmailHash(address string) (ThreemaID, error)

Looks up the Threema ID of the given e-mail address by its hash. The e-mail must be passed in plaintext, it will be normalized and hashed as necessary.

Returns ErrNotFound if the given address is unknown.

func (*SimpleClient) LookupIDByPhoneHash 

func (c *SimpleClient) LookupIDByPhoneHash(phoneNumber string) (ThreemaID, error)

Looks up the Threema ID of the given phone number by hash. Phone number must be passed in E.164 format. It will be normalized and hashed as neceassary

Returns ErrNotFound if the given phone number is unknown.

func (*SimpleClient) SendTextMessage 

func (c *SimpleClient) SendTextMessage(to ThreemaID, msg string) error

Send a message to the given Threema ID.

The message is sent in plaintext and encrypted at the Threema servers.

func (*SimpleClient) SendTextMessageToEmail 

func (c *SimpleClient) SendTextMessageToEmail(address string, msg string) error

Send a message to account associated with the given email address.

The message is sent in plaintext and encrypted at the Threema servers.

func (*SimpleClient) SendTextMessageToPhone 

func (c *SimpleClient) SendTextMessageToPhone(phone string, msg string) error

Send a message to the given phone number, passed in E.164 format.

The message is sent in plaintext and encrypted at the Threema servers.

func (*SimpleClient) SetGatewayURL added in v0.1.1 

func (c *SimpleClient) SetGatewayURL(url string)

Set the base URL for the Threema.Gateway server

func (*SimpleClient) SetHTTPClient added in v0.1.1 

func (c *SimpleClient) SetHTTPClient(httpClient *http.Client)

Set the http.Client to be used

type TextMessage 

type TextMessage struct {
	Content string
}

type ThreemaID 

type ThreemaID = string

Source Files

View all Source files

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.