> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snackbase.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Type Reference

> TypeScript type definitions for the SDK

This is a reference for the main TypeScript types exported by the SnackBase JavaScript SDK.

## Core Types

### SnackBaseClient

The main SDK client class.

```ts theme={null}
class SnackBaseClient {
  constructor(config: SnackBaseConfig)

  // Auth state
  readonly user: User | null
  readonly account: Account | null
  readonly isAuthenticated: boolean

  // Services
  readonly auth: AuthService
  readonly accounts: AccountService
  readonly users: UserService
  readonly collections: CollectionService
  readonly records: RecordService
  readonly groups: GroupsService
  readonly invitations: InvitationService
  readonly apiKeys: ApiKeyService
  readonly auditLogs: AuditLogService
  readonly roles: RoleService
  readonly collectionRules: CollectionRuleService
  readonly macros: MacroService
  readonly dashboard: DashboardService
  readonly admin: AdminService
  readonly emailTemplates: EmailTemplateService
  readonly files: FileService
  readonly realtime: RealTimeService
  readonly migrations: MigrationService

  // Methods
  getConfig(): Required<SnackBaseConfig>
  on<K extends keyof AuthEvents>(event: K, listener: AuthEvents[K]): () => void
  login(credentials: LoginCredentials): Promise<AuthResponse>
  logout(): Promise<void>
  // ... (see Client Reference for full method list)
}
```

***

### SnackBaseConfig

Client configuration options.

```ts theme={null}
interface SnackBaseConfig {
  // Required
  baseUrl: string;

  // Optional - Authentication
  apiKey?: string;
  defaultAccount?: string;

  // Optional - Request settings
  timeout?: number;
  maxRetries?: number;
  retryDelay?: number;

  // Optional - Token management
  enableAutoRefresh?: boolean;
  refreshBeforeExpiry?: number;
  storageBackend?: StorageBackend;

  // Optional - Realtime
  maxRealTimeRetries?: number;
  realTimeReconnectionDelay?: number;

  // Optional - Logging
  enableLogging?: boolean;
  logLevel?: LogLevel;

  // Optional - Error callbacks
  onAuthError?: (error: any) => void;
  onNetworkError?: (error: any) => void;
  onRateLimitError?: (error: any) => void;
}
```

***

## Authentication Types

### User

User account information.

```ts theme={null}
interface User {
  id: string;
  email: string;
  fullName?: string;
  avatarUrl?: string;
  isActive: boolean;
  isEmailVerified: boolean;
  roleIds: string[];
  account: {
    id: string;
    name: string;
    slug: string;
  };
  createdAt: string;
  updatedAt: string;
}
```

***

### Account

Account information.

```ts theme={null}
interface Account {
  id: string;
  name: string;
  slug: string;
  description?: string;
  settings?: Record<string, any>;
  createdAt: string;
  updatedAt: string;
}
```

***

### AuthState

Authentication state.

```ts theme={null}
interface AuthState {
  user: User | null;
  account: Account | null;
  token: string | null;
  refreshToken: string | null;
  isAuthenticated: boolean;
  expiresAt: string | null;
}
```

***

### AuthEvents

Authentication event types.

```ts theme={null}
interface AuthEvents {
  "auth:login": (state: AuthState) => void;
  "auth:logout": () => void;
  "auth:refresh": (state: AuthState) => void;
  "auth:error": (error: Error) => void;
}
```

***

### LoginCredentials

Email/password login credentials.

```ts theme={null}
interface LoginCredentials {
  account: string;
  email: string;
  password: string;
}
```

***

### RegisterData

User registration data.

```ts theme={null}
interface RegisterData {
  email: string;
  password: string;
  accountName: string;
  accountSlug?: string;
}
```

***

## Collection Types

### Collection

Collection definition.

```ts theme={null}
interface Collection {
  id: string;
  name: string;
  description?: string;
  fields: Field[];
  accountId: string;
  createdAt: string;
  updatedAt: string;
}
```

***

### Field

Collection field definition.

```ts theme={null}
interface Field {
  name: string;
  type: FieldType;
  required?: boolean;
  unique?: boolean;
  options?: FieldOptions;
}

type FieldType =
  | "text"
  | "number"
  | "boolean"
  | "date"
  | "select"
  | "multiselect"
  | "file"
  | "json"
  | "relation";

interface FieldOptions {
  // Text options
  multiline?: boolean;
  minLength?: number;
  maxLength?: number;
  pattern?: string;

  // Number options
  min?: number;
  max?: number;
  default?: number;

  // Select options
  choices?: string[];

  // Relation options
  relatedCollection?: string;
}
```

***

## Record Types

### BaseRecord

Base properties for all records.

```ts theme={null}
interface BaseRecord {
  id: string;
  createdAt: string;
  updatedAt: string;
}
```

***

### RecordListParams

Query parameters for listing records.

```ts theme={null}
interface RecordListParams {
  filter?: string | Record<string, any>;
  sort?: string;
  skip?: number;
  limit?: number;
  fields?: string[] | string;
  expand?: string[] | string;
}
```

***

### RecordListResponse

Response from listing records.

```ts theme={null}
interface RecordListResponse<T> {
  items: (T & BaseRecord)[];
  total: number;
  skip: number;
  limit: number;
}
```

***

## Query Types

### FilterOperator

Filter operators for queries.

```ts theme={null}
type FilterOperator =
  | "="   // Equals
  | "!="  // Not equals
  | ">"   // Greater than
  | ">="  // Greater than or equal
  | "<"   // Less than
  | "<="  // Less than or equal
  | "~"   // Contains
  | "!~"  // Does not contain
  | "?="  // Is empty
  | "?!"; // Is not empty
```

***

### SortDirection

Sort direction.

```ts theme={null}
type SortDirection = "asc" | "desc";
```

***

### QueryBuilder

Query builder class.

```ts theme={null}
class QueryBuilder<T = any> {
  select(fields: string | string[]): this;
  expand(relations: string | string[]): this;
  filter(field: string, operator: FilterOperator, value?: any): this;
  filter(filterString: string): this;
  sort(field: string, direction?: SortDirection): this;
  limit(count: number): this;
  skip(count: number): this;
  page(pageNum: number, perPage?: number): this;
  get(): Promise<RecordListResponse<T>>;
  first(): Promise<(T & BaseRecord) | null>;
}
```

***

## Realtime Types

### RealTimeState

Realtime connection state.

```ts theme={null}
type RealTimeState = "disconnected" | "connecting" | "connected" | "error";
```

***

### ServerMessage

Realtime server message format.

```ts theme={null}
interface ServerMessage {
  type: string;
  collection?: string;
  data?: any;
}
```

***

### RealTimeEvents

Realtime event types.

```ts theme={null}
interface RealTimeEvents {
  "connecting": () => void;
  "connected": () => void;
  "disconnected": () => void;
  "error": (error: Error) => void;
  "auth_error": (error: Error) => void;
  "message": (message: ServerMessage) => void;
  [event: string]: (data: any) => void;
}
```

***

## Error Types

### SnackBaseError

Base error class.

```ts theme={null}
class SnackBaseError extends Error {
  readonly code: string;
  readonly status?: number;
  readonly details?: any;
  readonly field?: string;
  readonly retryable: boolean;
}
```

***

### Error Classes

```ts theme={null}
class AuthenticationError extends SnackBaseError { }
class AuthorizationError extends SnackBaseError { }
class NotFoundError extends SnackBaseError { }
class ConflictError extends SnackBaseError { }
class ValidationError extends SnackBaseError {
  readonly fields?: Record<string, string[]>;
}
class RateLimitError extends SnackBaseError {
  readonly retryAfter?: number;
}
class NetworkError extends SnackBaseError { }
class TimeoutError extends SnackBaseError { }
class ServerError extends SnackBaseError { }
```

***

## React Types

### SnackBaseProviderProps

React provider props.

```ts theme={null}
interface SnackBaseProviderProps {
  children: React.ReactNode;
  baseUrl: string;
  apiKey?: string;
  defaultAccount?: string;
  timeout?: number;
  maxRetries?: number;
  storageBackend?: StorageBackend;
  enableLogging?: boolean;
  logLevel?: LogLevel;
}
```

***

### UseAuthResult

Return type of useAuth hook.

```ts theme={null}
interface UseAuthResult extends AuthState {
  login: (credentials: LoginCredentials) => Promise<any>;
  logout: () => Promise<void>;
  register: (data: RegisterData) => Promise<any>;
  forgotPassword: (data: PasswordResetRequest) => Promise<any>;
  resetPassword: (data: PasswordResetConfirm) => Promise<any>;
  isLoading: boolean;
}
```

***

### UseRecordResult

Return type of useRecord hook.

```ts theme={null}
interface UseRecordResult<T> {
  data: (T & BaseRecord) | null;
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}
```

***

### UseQueryResult

Return type of useQuery hook.

```ts theme={null}
interface UseQueryResult<T> {
  data: RecordListResponse<T> | null;
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}
```

***

### UseMutationResult

Return type of useMutation hook.

```ts theme={null}
interface UseMutationResult<T> {
  mutate: (idOrData: string | Partial<T>, data?: Partial<T>) => Promise<T & BaseRecord>;
  isLoading: boolean;
  error: Error | null;
  reset: () => void;
}
```

***

## Utility Types

### StorageBackend

Storage backend options.

```ts theme={null}
type StorageBackend = "localStorage" | "sessionStorage" | "memory" | "asyncStorage";
```

***

### LogLevel

Logging levels.

```ts theme={null}
type LogLevel = "debug" | "info" | "warn" | "error";
```

***

## Complete Import Example

```ts theme={null}
import {
  // Classes
  SnackBaseClient,
  QueryBuilder,

  // Types - Config
  SnackBaseConfig,
  StorageBackend,
  LogLevel,

  // Types - Auth
  User,
  Account,
  AuthState,
  AuthEvents,
  LoginCredentials,
  RegisterData,

  // Types - Collections
  Collection,
  Field,
  FieldType,

  // Types - Records
  BaseRecord,
  RecordListParams,
  RecordListResponse,

  // Types - Query
  FilterOperator,
  SortDirection,

  // Types - Realtime
  RealTimeState,
  ServerMessage,
  RealTimeEvents,

  // Types - Errors
  SnackBaseError,
  AuthenticationError,
  AuthorizationError,
  NotFoundError,
  ConflictError,
  ValidationError,
  RateLimitError,
  NetworkError,
  TimeoutError,
  ServerError,
} from "@snackbase/sdk";
```

## Next Steps

* **[Client Reference](/sdk/js/reference/client)** - Client class reference
* **[Services](/sdk/js/services/records)** - Service references
* **[React Hooks](/sdk/js/react/setup)** - React integration types