api

type Client interface {
	io.Closer

	// ReadUsage returns the current usage counts by the requested subject.
	ReadUsage(ctx context.Context, userId string, subj usage.Subject) (u usage.Usage, err error)

	// ReadUsageLimit returns the usage limit by the requested subject.
	ReadUsageLimit(ctx context.Context, userId string, subj usage.Subject) (l usage.Limit, err error)

	// OpenMessagesWriter opens the batch message writer. A client should close it once done.
	OpenMessagesWriter(ctx context.Context, userId string) (w model.Writer[*pb.CloudEvent], err error)

	// OpenMessagesReader opens batch message reader. A client should close it once done.
	OpenMessagesReader(ctx context.Context, userId, subId string, batchSize uint32) (r model.Reader[[]*pb.CloudEvent], err error)

	// OpenMessagesAckReader opens batch message reader that requires an explicit ack. A client should close it once done.
	OpenMessagesAckReader(ctx context.Context, userId, subId string, batchSize uint32) (r model.AckReader[[]*pb.CloudEvent], err error)

	// CreateSubscription with the specified fields.
	CreateSubscription(ctx context.Context, userId string, subData subscription.Data) (id string, err error)

	// ReadSubscription specified by the id. Returns ErrNotFound if subscription is missing.
	ReadSubscription(ctx context.Context, userId, subId string) (subData subscription.Data, err error)

	// UpdateSubscription replaces the existing subscription.Data fields.
	UpdateSubscription(ctx context.Context, userId, subId string, subData subscription.Data) (err error)

	// DeleteSubscription and all associated conditions those not in use by any other subscription.
	// Returns ErrNotFound if a subscription with the specified id is missing.
	DeleteSubscription(ctx context.Context, userId, subId string) (err error)

	// SearchSubscriptions returns all subscription ids those have the requested user id.
	SearchSubscriptions(ctx context.Context, userId string, limit uint32, cursor string) (ids []string, err error)
}

type ClientBuilder interface {

	// CertAuthority sets the CA to authenticate the Awakari service.
	// Should be used together with ClientKeyPair and ApiUri.
	CertAuthority(caCrt []byte) ClientBuilder

	// ClientKeyPair sets the client certificate key pair to allow Awakari service to authenticate the client.
	// Should be used together with ServerPublicKey and ApiUri.
	ClientKeyPair(clientCrt, clientKey []byte) ClientBuilder

	// ApiUri sets the Awakari public API URI. Should be used together with ServerPublicKey and ClientKeyPair.
	// Useful when a client needs every available public API method.
	// Enables additionally the API methods to read the usage limits and permits.
	ApiUri(apiUri string) ClientBuilder

	// ReaderUri sets the Awakari messages reading API URI. Overrides any value set by ApiUri.
	// Useful when the specific message reading API is needed by the client.
	ReaderUri(readerUri string) ClientBuilder

	// SubscriptionsUri sets the Awakari subscriptions-proxy API URI. Overrides any value set by ApiUri.
	// Useful when the specific subscriptions management API is needed by the client.
	SubscriptionsUri(subsUri string) ClientBuilder

	// WriterUri sets the Awakari messages publishing API URI. Overrides any value set by ApiUri.
	// Useful when the specific message publishing API is needed by the client.
	WriterUri(writerUri string) ClientBuilder

	// Build instantiates the Client instance and returns it.
	Build() (c Client, err error)
}