API Reference

Complete API reference for the Cocobase Go SDK.

Client
Configuration
Document Operations
Query Builder
Authentication
Real-time
Types

Client

NewClient

Creates a new Cocobase client instance.

func NewClient(config Config) *Client

Parameters:

config (Config): Client configuration

Returns:

*Client: New client instance

Example:

client := cocobase.NewClient(cocobase.Config{
    APIKey: "your-api-key",
})

Configuration Methods

SetToken

Manually set the authentication token.

func (c *Client) SetToken(token string) error

Parameters:

token (string): JWT authentication token

Returns:

error: Error if storage fails

Example:

err := client.SetToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")

GetToken

Get the current authentication token.

func (c *Client) GetToken() string

Returns:

string: Current authentication token

Example:

token := client.GetToken()

IsAuthenticated

Check if client is authenticated.

func (c *Client) IsAuthenticated() bool

Returns:

bool: true if authenticated, false otherwise

Example:

if client.IsAuthenticated() {
    // User is logged in
}

HasRole

Check if current user has a specific role.

func (c *Client) HasRole(role string) bool

Parameters:

role (string): Role name to check

Returns:

bool: true if user has role, false otherwise

Example:

if client.HasRole("admin") {
    // User is an admin
}

Configuration

Config

Client configuration structure.

type Config struct {
    APIKey     string        // Required: API key
    BaseURL    string        // Optional: Base URL (default: http://localhost:3000)
    HTTPClient *http.Client  // Optional: Custom HTTP client
    Storage    Storage       // Optional: Token storage
}

Example:

config := cocobase.Config{
    APIKey:  "your-api-key",
    BaseURL: "https://api.cocobase.io",
    HTTPClient: &http.Client{
        Timeout: 30 * time.Second,
    },
    Storage: storage.NewMemoryStorage(),
}

Storage Interface

type Storage interface {
    Get(key string) (string, error)
    Set(key string, value string) error
    Delete(key string) error
}

Document Operations

CreateDocument

Create a new document in a collection.

func (c *Client) CreateDocument(ctx context.Context, collection string, data map[string]interface{}) (*Document, error)

Parameters:

ctx (context.Context): Request context
collection (string): Collection name
data (map[string]interface): Document data

Returns:

*Document: Created document
error: Error if operation fails

Example:

doc, err := client.CreateDocument(ctx, "users", map[string]interface{}{
    "name":  "Alice",
    "email": "alice@example.com",
})

GetDocument

Retrieve a document by ID.

func (c *Client) GetDocument(ctx context.Context, collection, docID string) (*Document, error)

Parameters:

ctx (context.Context): Request context
collection (string): Collection name
docID (string): Document ID

Returns:

*Document: Retrieved document
error: Error if operation fails (404 if not found)

Example:

doc, err := client.GetDocument(ctx, "users", "doc-id-123")

UpdateDocument

Update an existing document.

func (c *Client) UpdateDocument(ctx context.Context, collection, docID string, data map[string]interface{}) (*Document, error)

Parameters:

ctx (context.Context): Request context
collection (string): Collection name
docID (string): Document ID
data (map[string]interface): Updated data (merged with existing)

Returns:

*Document: Updated document
error: Error if operation fails

Example:

doc, err := client.UpdateDocument(ctx, "users", "doc-id-123", map[string]interface{}{
    "age": 30,
})

DeleteDocument

Delete a document.

func (c *Client) DeleteDocument(ctx context.Context, collection, docID string) error

Parameters:

ctx (context.Context): Request context
collection (string): Collection name
docID (string): Document ID

Returns:

error: Error if operation fails

Example:

err := client.DeleteDocument(ctx, "users", "doc-id-123")

ListDocuments

List documents with optional query.

func (c *Client) ListDocuments(ctx context.Context, collection string, query *QueryBuilder) ([]Document, error)

Parameters:

ctx (context.Context): Request context
collection (string): Collection name
query (*QueryBuilder): Optional query (nil for all documents)

Returns:

[]Document: Array of documents
error: Error if operation fails

Example:

query := cocobase.NewQuery().
    Where("status", "active").
    Limit(50)

docs, err := client.ListDocuments(ctx, "users", query)

QueryDocuments

List documents with raw query string.

func (c *Client) QueryDocuments(ctx context.Context, collection, rawQuery string) ([]Document, error)

Parameters:

ctx (context.Context): Request context
collection (string): Collection name
rawQuery (string): URL-encoded query string

Returns:

[]Document: Array of documents
error: Error if operation fails

Example:

docs, err := client.QueryDocuments(ctx, "users", "status=active&age_gte=18")

Query Builder

NewQuery

Create a new query builder.

func NewQuery() *QueryBuilder

Returns:

*QueryBuilder: New query builder instance

Example:

query := cocobase.NewQuery()

Comparison Operators

func (qb *QueryBuilder) Where(field string, value interface{}) *QueryBuilder
func (qb *QueryBuilder) Equals(field string, value interface{}) *QueryBuilder
func (qb *QueryBuilder) NotEquals(field string, value interface{}) *QueryBuilder
func (qb *QueryBuilder) GreaterThan(field string, value interface{}) *QueryBuilder
func (qb *QueryBuilder) GreaterThanOrEqual(field string, value interface{}) *QueryBuilder
func (qb *QueryBuilder) LessThan(field string, value interface{}) *QueryBuilder
func (qb *QueryBuilder) LessThanOrEqual(field string, value interface{}) *QueryBuilder
func (qb *QueryBuilder) Between(field string, min, max interface{}) *QueryBuilder

String Operators

func (qb *QueryBuilder) Contains(field, substring string) *QueryBuilder
func (qb *QueryBuilder) StartsWith(field, prefix string) *QueryBuilder
func (qb *QueryBuilder) EndsWith(field, suffix string) *QueryBuilder
func (qb *QueryBuilder) Search(searchTerm string, fields ...string) *QueryBuilder

List Operators

func (qb *QueryBuilder) In(field string, values ...interface{}) *QueryBuilder
func (qb *QueryBuilder) NotIn(field string, values ...interface{}) *QueryBuilder

Null Checks

func (qb *QueryBuilder) IsNull(field string) *QueryBuilder
func (qb *QueryBuilder) IsNotNull(field string) *QueryBuilder

Boolean Logic

func (qb *QueryBuilder) Or() *OrBuilder
func (qb *QueryBuilder) OrGroup(groupName string) *OrBuilder

Pagination

func (qb *QueryBuilder) Limit(limit int) *QueryBuilder
func (qb *QueryBuilder) Offset(offset int) *QueryBuilder
func (qb *QueryBuilder) Page(page, perPage int) *QueryBuilder

Sorting

func (qb *QueryBuilder) OrderBy(field string) *QueryBuilder
func (qb *QueryBuilder) OrderByAsc(field string) *QueryBuilder
func (qb *QueryBuilder) OrderByDesc(field string) *QueryBuilder
func (qb *QueryBuilder) Asc() *QueryBuilder
func (qb *QueryBuilder) Desc() *QueryBuilder

Helper Methods

func (qb *QueryBuilder) Active() *QueryBuilder
func (qb *QueryBuilder) Deleted() *QueryBuilder
func (qb *QueryBuilder) Recent() *QueryBuilder
func (qb *QueryBuilder) Oldest() *QueryBuilder

Build

func (qb *QueryBuilder) Build() string

Returns:

string: URL-encoded query string

Example:

query := cocobase.NewQuery().
    Where("status", "active").
    Limit(10)

queryString := query.Build()
// Output: "status=active&limit=10"

Authentication

Register

func (c *Client) Register(ctx context.Context, email, password string, data map[string]interface{}) error

Parameters:

ctx (context.Context): Request context
email (string): User email
password (string): User password
data (map[string]interface): Optional additional user data

Returns:

error: Error if registration fails

Example:

err := client.Register(ctx, "user@example.com", "password123", map[string]interface{}{
    "firstName": "Alice",
    "lastName":  "Smith",
})

Authenticate a user.

func (c *Client) Login(ctx context.Context, email, password string) error

Parameters:

ctx (context.Context): Request context
email (string): User email
password (string): User password

Returns:

error: Error if login fails

Example:

err := client.Login(ctx, "user@example.com", "password123")

Logout

Logout current user.

func (c *Client) Logout() error

Returns:

error: Error if logout fails

Example:

err := client.Logout()

InitAuth

Initialize authentication from stored token.

func (c *Client) InitAuth(ctx context.Context) error

Parameters:

ctx (context.Context): Request context

Returns:

error: Error if initialization fails

Example:

err := client.InitAuth(ctx)
if err != nil {
    // No existing session
}

GetCurrentUser

Get current authenticated user.

func (c *Client) GetCurrentUser(ctx context.Context) (*AppUser, error)

Parameters:

ctx (context.Context): Request context

Returns:

*AppUser: Current user
error: Error if not authenticated or request fails

Example:

user, err := client.GetCurrentUser(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("User: %s\n", user.Email)

UpdateUser

Update current user.

func (c *Client) UpdateUser(ctx context.Context, data map[string]interface{}, email, password *string) (*AppUser, error)

Parameters:

ctx (context.Context): Request context
data (map[string]interface): Updated user data (optional, can be nil)
email (*string): New email (optional, can be nil)
password (*string): New password (optional, can be nil)

Returns:

*AppUser: Updated user
error: Error if update fails

Example:

newEmail := "newemail@example.com"
user, err := client.UpdateUser(ctx, map[string]interface{}{
    "phone": "+1234567890",
}, &newEmail, nil)

Real-time

WatchCollection

Watch a collection for real-time updates.

func (c *Client) WatchCollection(ctx context.Context, collection string, callback func(Event), name string) (*Connection, error)

Parameters:

ctx (context.Context): Request context
collection (string): Collection name to watch
callback (func(Event)): Event handler function
name (string): Connection name (empty for auto-generated)

Returns:

*Connection: WebSocket connection
error: Error if connection fails

Example:

conn, err := client.WatchCollection(ctx, "users", func(event cocobase.Event) {
    fmt.Printf("Event: %s\n", event.Event)
}, "users-watcher")
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

Connection Methods

Close

Close the WebSocket connection.

func (conn *Connection) Close() error

Returns:

error: Error if closing fails

Example:

err := conn.Close()

IsClosed

Check if connection is closed.

func (conn *Connection) IsClosed() bool

Returns:

bool: true if closed, false otherwise

Example:

if conn.IsClosed() {
    fmt.Println("Connection is closed")
}

Types

Document

type Document struct {
    ID         string                 `json:"id"`
    Collection string                 `json:"collection"`
    Data       map[string]interface{} `json:"data"`
    CreatedAt  time.Time              `json:"created_at"`
    UpdatedAt  time.Time              `json:"updated_at"`
}

AppUser

type AppUser struct {
    ID        string                 `json:"id"`
    Email     string                 `json:"email"`
    Roles     []string               `json:"roles"`
    Data      map[string]interface{} `json:"data"`
    CreatedAt time.Time              `json:"created_at"`
    UpdatedAt time.Time              `json:"updated_at"`
}

Event

type Event struct {
    Event string   `json:"event"`  // "create", "update", or "delete"
    Data  Document `json:"data"`
}

APIError

type APIError struct {
    StatusCode int
    Method     string
    URL        string
    Body       string
    Suggestion string
}

func (e *APIError) Error() string

Connection

type Connection struct {
    // Internal fields (not exported)
}

Constants

const (
    DefaultBaseURL      = "http://localhost:3000"
    DefaultTimeout      = 30 * time.Second
    ContentTypeJSON     = "application/json"
    HeaderAPIKey        = "x-api-key"
    HeaderAuthorization = "Authorization"
)

Previous: Error Handling | Next: Best Practices →

Table of Contents​

Client​

NewClient​

Configuration Methods​

SetToken​

GetToken​

IsAuthenticated​

HasRole​

Configuration​

Config​

Storage Interface​

Document Operations​

CreateDocument​

GetDocument​

UpdateDocument​

DeleteDocument​

ListDocuments​

QueryDocuments​

Query Builder​

NewQuery​

Comparison Operators​

String Operators​

List Operators​

Null Checks​

Boolean Logic​

Pagination​

Sorting​

Helper Methods​

Build​

Authentication​

Register​

Login​

Logout​

InitAuth​

GetCurrentUser​

UpdateUser​

Real-time​

WatchCollection​

Connection Methods​

Close​

IsClosed​

Types​

Document​

AppUser​

Event​

APIError​

Connection​

Constants​

Table of Contents

Client

NewClient

Configuration Methods

SetToken

GetToken

IsAuthenticated

HasRole

Configuration

Config

Storage Interface

Document Operations

CreateDocument

GetDocument

UpdateDocument

DeleteDocument

ListDocuments

QueryDocuments

Query Builder

NewQuery

Comparison Operators

String Operators

List Operators

Null Checks

Boolean Logic

Pagination

Sorting

Helper Methods

Build

Authentication

Register

Login

Logout

InitAuth

GetCurrentUser

UpdateUser

Real-time

WatchCollection

Connection Methods

Close

IsClosed

Types

Document

AppUser

Event

APIError

Connection

Constants