{
  "success": true,
  "data": { ... },
  "message": "Operation successful"
}

{
  "success": false,
  "message": "Validation failed",
  "errors": { "email": ["The email field is required."] },
  "error_code": "VALIDATION_ERROR",
  "timestamp": "2026-04-18T12:00:00Z"
}

php artisan reverb:start

php artisan queue:work --queue=default,notifications,webhooks

# Layer 1 — always required
X-API-Key: fsk_live_xxxxxxxxxxxxxxxxxxxx

# Layer 2 — required for user-scoped routes
Authorization: Bearer sanctum_token_here

X-API-Key: fsk_live_xxxxxxxxxxxxxxxxxxxx
Authorization: Bearer your_user_token_here   # required for authenticated routes

curl -X POST https://your-domain.com/api/v1/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -d '{
    "app_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "jane@example.com",
    "password": "secret1234",
    "name": "Jane Doe"
  }'

curl -X POST https://your-domain.com/api/v1/login \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -d '{
    "app_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "jane@example.com",
    "password": "secret1234"
  }'

curl -X POST https://your-domain.com/api/v1/logout \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl https://your-domain.com/api/v1/me \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl -X PUT https://your-domain.com/api/v1/me \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Smith", "phone": "+1234567890" }'

curl -X POST https://your-domain.com/api/v1/auth/devices \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "relay",
    "platform": "android",
    "device_id": "install_01JABC...",
    "device_name": "Pixel 8 Pro",
    "app_uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

curl -X POST https://your-domain.com/api/v1/auth/forgot-password \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com" }'

curl "https://your-domain.com/api/v1/collections?page=1" \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl -X POST https://your-domain.com/api/v1/collections \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Products", "description": "Product catalog" }'

curl -X POST https://your-domain.com/api/v1/collections/products/documents \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Widget Pro",
      "price": 29.99,
      "tags": ["gadget", "sale"]
    }
  }'

/api/v1/collections/products/documents?where[status]=active

/api/v1/collections/products/documents?where[price][op]=lte&where[price][value]=50

curl -G "https://your-domain.com/api/v1/collections/products/documents" \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  --data-urlencode "where[price][op]=lte" \
  --data-urlencode "where[price][value]=50" \
  --data-urlencode "where[status]=active" \
  --data-urlencode "order_by=created_at" \
  --data-urlencode "order_dir=desc" \
  --data-urlencode "per_page=20"

curl -X POST https://your-domain.com/api/v1/documents/abc-123-uuid/collections \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "reviews" }'

curl -X POST https://your-domain.com/api/v1/files \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -F "file=@/path/to/image.png" \
  -F "visibility=public" \
  -F "category=avatar"

curl "https://your-domain.com/api/v1/files?category=avatar&visibility=public" \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl https://your-domain.com/api/v1/files/7 \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl "https://your-domain.com/api/v1/files/7/url?minutes=120" \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl -X DELETE https://your-domain.com/api/v1/files/7 \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl -X POST https://your-domain.com/api/v1/channels \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 1,
    "name": "General",
    "type": "group",
    "member_ids": [2, 3, 4]
  }'

curl -X POST https://your-domain.com/api/v1/channels/direct \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{ "project_id": 1, "user_id": 5 }'

curl -X POST https://your-domain.com/api/v1/channels/1/messages \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "Hello everyone!", "type": "text" }'

curl -X POST https://your-domain.com/api/v1/messages/42/reactions \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

curl -X DELETE "https://your-domain.com/api/v1/messages/42/reactions/%F0%9F%91%8D" \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl "https://your-domain.com/api/v1/channels/1/search?q=hello&per_page=20" \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl "https://your-domain.com/api/v1/notifications" \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl -X PUT https://your-domain.com/api/v1/notifications/uuid-here/read \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl -X POST https://your-domain.com/api/v1/notifications/read-all \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl https://your-domain.com/api/v1/config \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl https://your-domain.com/api/v1/config/min_app_version \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..."

curl -X POST https://your-domain.com/api/v1/events \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "purchase_completed",
    "properties": {
      "product_id": "pro-monthly",
      "amount": 29.00
    },
    "platform": "android",
    "app_version": "2.3.1"
  }'

curl -X POST https://your-domain.com/api/v1/events/batch \
  -H "X-API-Key: fsk_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer 1|AbCdEfGhIjKl..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "event_name": "page_view", "properties": { "page": "home" } },
      { "event_name": "button_click", "properties": { "button": "signup" } }
    ]
  }'

// Configure Echo to use your API auth endpoint
const echo = new Echo({
  broadcaster: 'reverb',
  authEndpoint: '/api/v1/broadcasting/auth',
  auth: {
    headers: {
      'X-API-Key': apiKey,
      'Authorization': `Bearer ${token}`
    }
  }
});

echo.private(`channel.${channelId}`)
  .listen('MessageSent', (e) => {
    console.log('New message:', e.message);
  })
  .listen('UserTyping', (e) => {
    console.log(e.user.name, 'is typing...');
  });

dependencies:
  firestack: ^1.2.0

dart pub get

import 'package:firestack/firestack.dart';

void main() async {
  final app = Firestack.initialize(
    apiKey: 'fsk_live_xxxxxxxxxxxx',
    appId: '550e8400-e29b-41d4-a716-446655440000', // REQUIRED: Your app UUID from dashboard
    baseUrl: 'https://your-domain.com', // default: https://firestack.co.za
  );

  // Access services
  final auth = app.auth;
  final Firestack = app.Firestack;
  final storage = app.storage;
  final messaging = app.messaging;
  final notifications = app.notifications;
  final config = app.remoteConfig;
  final analytics = app.analytics;
  final realtime = app.realtime;
}

// Default app
final app = Firestack.initialize(
  apiKey: 'fsk_main',
  appId: '550e8400-e29b-41d4-a716-446655440000',
);

// Named secondary app
final secondary = Firestack.initialize(
  apiKey: 'fsk_other',
  appId: '550e8400-e29b-41d4-a716-446655440001',
  name: 'secondary',
);

// Retrieve later by name
final main = Firestack.instance;
final other = Firestack.instanceFor(name: 'secondary');

final auth = app.auth;

// Listen to auth state changes (like Firebase onAuthStateChanged)
auth.authStateChanges.listen((user) {
  if (user != null) {
    print('Signed in: \${user.name}');
    print('App UUID: \${user.appId}, Project ID: \${user.projectId}');
  } else {
    print('Signed out');
  }
});

// Token persistence (save to secure storage)
auth.setTokenPersistence((token) async {
  await secureStorage.write(key: 'token', value: token);
});

// Register (simplified - no password confirmation)
final user = await auth.signUp(
  email: 'alice@example.com',
  password: 'password',
  name: 'Alice', // Optional
);

// Sign in
await auth.signIn(
  email: 'alice@example.com',
  password: 'password',
);

// Restore existing session
auth.signInWithToken('existing-bearer-token');
final me = await auth.currentUser();

final user = await auth.currentUser();

// Basic fields
print(user.id);         // User ID
print(user.projectId);  // Project ID (multi-tenancy)
print(user.appId);      // App UUID (multi-tenancy)
print(user.name);       // Display name
print(user.email);      // Email
print(user.status);     // 'active', 'pending', 'disabled'

// Status helpers
if (user.isActive) { ... }
if (user.isPending) { ... }
if (user.isDisabled) { ... }

// Custom claims (for role-based access control)
if (user.hasClaim('admin')) {
  print('User is admin');
}
final role = user.getClaim<String>('role');
final isPremium = user.getClaim<bool>('premium');

// Metadata (custom user data)
final onboarded = user.getMetadata<bool>('onboarding_complete');

// Forgot password (sends reset email)
await auth.sendPasswordResetEmail(email: 'alice@example.com');

// Change password (authenticated)
await auth.changePassword(
  currentPassword: 'old',
  newPassword: 'new',
  newPasswordConfirmation: 'new',
);

// Email verification
await auth.sendEmailVerification();

// Refresh token
final newToken = await auth.refreshToken();

// Delete account
await auth.deleteAccount(password: 'password');

// Sign out
await auth.signOut();

final Firestack = app.Firestack;

// Create
final doc = await Firestack.collection('users').add({
  'name': 'Alice',
  'age': 30,
});

// Read
final fetched = await Firestack.collection('users').doc('alice').get();

// Update
await Firestack.collection('users').doc('alice').update({'age': 31});

// Delete
await Firestack.collection('users').doc('alice').delete();

// Check existence
final exists = await Firestack.collection('users').doc('alice').exists();

final results = await Firestack.collection('users').query((q) => q
    .where('age', isGreaterThan: 25)
    .where('status', isEqualTo: 'active')
    .where('tags', arrayContains: 'premium')
    .where('role', whereIn: ['admin', 'editor'])
    .where('deleted_at', isNull: true)
    .orderBy('created_at', descending: true)
    .select(['name', 'email', 'age'])
    .search('alice')
    .limit(10)
    .page(1));

// Pagination helpers
print('Page \${results.currentPage}/\${results.lastPage}');
print('Has next: \${results.hasNextPage}');
final names = results.map((doc) => doc.get<String>('name'));

await Firestack.collection('users').doc('alice').update({
  'login_count': FieldValue.increment(1),
  'tags': FieldValue.arrayUnion(['vip']),
  'temp': FieldValue.delete(),
  'updated_at': FieldValue.serverTimestamp(),
});

// Batch writes (atomic)
final batch = Firestack.batch();
batch.set(Firestack.collection('users').doc('bob'), {'name': 'Bob'});
batch.update(Firestack.collection('users').doc('alice'), {'role': 'admin'});
batch.delete(Firestack.collection('users').doc('charlie'));
await batch.commit();

// Transactions (read-then-write)
await Firestack.runTransaction((tx) async {
  final doc = await tx.get(Firestack.collection('accounts').doc('alice'));
  final balance = doc.get<int>('balance') ?? 0;
  tx.update(Firestack.collection('accounts').doc('alice'),
      {'balance': balance - 50});
  tx.update(Firestack.collection('accounts').doc('bob'),
      {'balance': FieldValue.increment(50)});
});

// Aggregate queries
final count = await Firestack.collection('users').count();
final totalRevenue = await Firestack.collection('orders').sum('amount');
final avgAge = await Firestack.collection('users').average('age');

// Collection group queries (across all subcollections named 'comments')
final allComments = await Firestack.collectionGroup('comments').getDocs();

// Cache-only read (offline-first)
final cached = await Firestack.collection('users').doc('alice')
    .get(source: CacheSource.cache);

// Clear cache
Firestack.cache.clear();

final storage = app.storage;

// Simple upload with callback
final file = await storage.upload(
  filePath: 'photo.jpg',
  fileBytes: bytes,
  visibility: 'public',
  category: 'images',
  onProgress: (sent, total) => print('\$sent / \$total'),
);

// Stream-based upload (like Firebase UploadTask)
final task = storage.uploadWithProgress(
  filePath: 'video.mp4',
  fileBytes: videoBytes,
);
task.onProgress.listen((snap) {
  print('\${(snap.progress * 100).toStringAsFixed(1)}%');
});
final result = await task.future;

// Signed download URL with expiry
final url = await storage.getDownloadUrl('file-uuid', minutes: 30);
print('URL: \${url.url}');
print('Expired: \${url.isExpired}');

// List files with pagination
final files = await storage.list(
  category: 'images',
  page: 1,
  perPage: 20,
);

// Delete multiple files
await storage.deleteFiles(['uuid1', 'uuid2']);

// Copy a file
final copy = await storage.copyFile('uuid', visibility: 'private');

final messaging = app.messaging;

// List channels
final channels = await messaging.channels(projectId: 1);

// Create group channel
final channel = await messaging.createChannel(
  projectId: 1,
  name: 'general',
  memberIds: [2, 3],
);

// Create or get direct message channel
final dm = await messaging.createDirectChannel(
  projectId: 1,
  userId: 2,
);

// Send message
final msg = await messaging.sendMessage(
  channelId: channel.id,
  body: 'Hello!',
);

// Edit & delete
await messaging.updateMessage(msg.id, body: 'Hello! (edited)');
await messaging.deleteMessage(msg.id);

// Reactions
await messaging.addReaction(messageId: msg.id, emoji: '\u{1F44D}');
await messaging.removeReaction(messageId: msg.id, emoji: '\u{1F44D}');

// Read receipts & typing
await messaging.markAsRead(channel.id);
await messaging.sendTyping(channel.id);

// Search, mute, pin
final results = await messaging.searchMessages(channel.id, query: 'hello');
await messaging.toggleMute(channel.id);
await messaging.togglePin(channel.id);

final notifications = app.notifications;

// 1. Configure platform & app
notifications.configure(platform: 'android', appId: 'com.example.app');

// 2. Set up native permission handler
notifications.setPermissionRequestHandler(() async {
  final status = await Permission.notification.request();
  return NotificationSettings(
    authorizationStatus: status.isGranted
        ? NotificationAuthorizationStatus.authorized
        : NotificationAuthorizationStatus.denied,
  );
});

// 3. Set up device token provider (e.g. from Firebase Messaging)
notifications.setTokenProvider(() async {
  return await FirebaseMessaging.instance.getToken();
});

// 4. Request permission (auto-registers device)
final settings = await notifications.requestPermission();
if (settings.isAuthorized) print('Push enabled!');

// Foreground message handling
notifications.onMessage((notification) {
  print('Received: \${notification.title}');
});

// Topic subscriptions
await notifications.subscribeToTopic('promotions');
await notifications.unsubscribeFromTopic('promotions');

// List (optionally filter to unread)
final notifs = await notifications.list(unreadOnly: true);
final unread = await notifications.unreadCount();

// Mark read
await notifications.markAsRead('notification-id');
await notifications.markAllAsRead();

// Delete
await notifications.delete('notification-id');
await notifications.deleteAll();

final config = app.remoteConfig;

// Set defaults (used before first fetch)
config.setDefaults({
  'dark_mode': false,
  'max_items': 50,
  'welcome_msg': 'Hello!',
});

// Set minimum fetch interval (throttling)
config.minimumFetchInterval = Duration(minutes: 5);

// Fetch and activate in one call
final updated = await config.fetchAndActivate();

// Type-safe cached getters
final darkMode = config.getBool('dark_mode');
final limit = config.getInt('max_items', defaultValue: 50);
final ratio = config.getDouble('ratio', defaultValue: 1.0);
final name = config.getString('app_name', defaultValue: 'My App');

// Feature flags
if (config.isFeatureEnabled('new_ui')) {
  // show new UI
}

// Fetch status
print(config.lastFetchStatus); // success, failure, throttled
print(config.lastFetchTime);

final analytics = app.analytics;

// Set user identity (like Firebase setUserId)
analytics.setUserId('user-123');

// Set user properties (auto-merged into all events)
analytics.setUserProperty(name: 'subscription', value: 'premium');

// Set defaults for all events
analytics.setDefaults(platform: 'android', appVersion: '2.0.0');

// Screen tracking
await analytics.logScreenView(
  screenName: 'Home',
  screenClass: 'HomePage',
);

// Convenience events
await analytics.logLogin(method: 'email');
await analytics.logSignUp(method: 'google');

// Custom events
await analytics.logEvent(
  name: 'purchase',
  properties: {'item_id': '42', 'price': '9.99'},
);

// Batch events (max 100)
await analytics.logBatch([
  AnalyticsEvent(name: 'item_view', properties: {'item_id': '42'}),
  AnalyticsEvent(name: 'add_to_cart', properties: {'qty': '1'}),
]);

final realtime = app.realtime;

realtime.configure(
  host: 'your-domain.com',
  port: 8080,
  scheme: 'ws', // or 'wss' for SSL
  appKey: 'reverb-app-key',
  appSecret: 'reverb-app-secret',
);

await realtime.connect();

// Monitor connection state
realtime.stateStream.listen((state) => print('\$state'));

// Listen for document changes
await realtime.onDocumentCreated(projectId, (data) {
  print('New document: \$data');
});
await realtime.onDocumentUpdated(projectId, (data) => print(data));

// Listen for messaging events
await realtime.onMessageReceived(channelId, (data) => print(data));
await realtime.onTyping(channelId, (data) => print(data));

// Collection snapshots (like Firebase onSnapshot)
Firestack.collection('users').snapshots(projectId: 1).listen((docs) {
  print('\${docs.length} users');
});

// Single document snapshots
Firestack.collection('users').doc('alice').snapshots(projectId: 1).listen((doc) {
  print('Alice: \${doc?.data}');
});

// Raw streams
realtime.snapshotStream(projectId: 1, event: 'document.created').listen(print);
realtime.messageStream(channelId).listen(print);

try {
  await app.auth.signIn(
    email: 'wrong@email.com',
    password: 'wrong',
  );
} on FirestackException catch (e) {
  print('\${e.statusCode}: \${e.message}');

  if (e.isUnauthorized) print('Bad credentials');
  if (e.isRateLimited) print('Too many requests — retry after \${e.statusCode}');
  if (e.isValidationError) print('Errors: \${e.errors}');
  if (e.isNotFound) print('Resource not found');
  if (e.isServerError) print('Server error');
}

# Install from source
cd firestack_cli
dart pub get

# Run directly
dart run bin/firestack.dart

# Or compile to native binary
dart compile exe bin/firestack.dart -o firestack
./firestack

# Initialize project (creates firestack.json)
firestack init --api-key fsk_live_xxx --url https://your-domain.com

# Sign in
firestack auth login --email alice@example.com --password secret

# Check connection
firestack status