Skip to main content

​
Quickstart Guide

Get up and running with the Inspatial Cloud Client SDK in minutes. This guide shows you how to initialize clients, fetch data, and listen to real-time updates.

​
Prerequisites

  • Node.js 16+ or Deno 1.30+
  • An Inspatial Cloud backend instance
  • API endpoint URL

​
Initialize the REST Client

Create an instance of InCloudClient to interact with your backend APIs: 
import { InCloudClient } from '@inspatial/cloud-client';

// Initialize with your API endpoint
const client = new InCloudClient('/api');

// Or with a full URL for remote servers
const remoteClient = new InCloudClient('https://your-domain.com/api');

​
Custom Notifications and Redirects

Handle API notifications and redirects with custom callbacks: 
const client = new InCloudClient('/api', {
  onNotify: (info) => {
    // Custom notification handler
    console.log(`[${info.type}] ${info.title}: ${info.message}`);
    // Integrate with your UI toast/notification system
  },
  onRedirect: (url, response) => {
    // Custom redirect handler
    window.location.href = url;
  }
});

​
Fetch and Create Entries

Work with entries using the entry group methods:
1

Fetch a Single Entry

const product = await client.entry.getEntry('Product', '123');
console.log(product.id, product.createdAt);
2

Fetch a List of Entries

const response = await client.entry.getEntryList('Product', {
  limit: 10,
  offset: 0,
  filter: {
    status: 'active'
  }
});

console.log(`Found ${response.total} products`);
response.list.forEach(product => {
  console.log(product.id);
});
3

Create a New Entry

const newProduct = await client.entry.createEntry('Product', {
  name: 'Gaming Laptop',
  price: 1299.99,
  status: 'active'
});

console.log('Created product:', newProduct.id);
4

Update an Entry

const updated = await client.entry.updateEntry(
  'Product',
  '123',
  { price: 1199.99 }
);

​
Upload Files

Upload files with progress tracking: 
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

client.uploadFile({
  fileName: file.name,
  file: file,
  publicFile: true,
  optimize: {
    width: 1200,
    height: 800
  },
  progressCallback: (progress) => {
    const percent = (progress.loaded / progress.total) * 100;
    console.log(`Upload progress: ${percent.toFixed(0)}%`);
  },
  completeCallback: (uploadedFile) => {
    console.log('File uploaded:', uploadedFile.id);
    // Access file URL: client.filesEndpoint + uploadedFile.id
  },
  errorCallback: (error) => {
    console.error('Upload failed:', error);
  }
});

​
Real-time Updates with InLiveClient

Listen to live changes using WebSocket connections:
1

Initialize and Connect

import { InLiveClient } from '@inspatial/cloud-client';

const liveClient = new InLiveClient('wss://your-domain.com');

// Start the connection
liveClient.start();
2

Monitor Connection Status

liveClient.onConnectionStatus((status) => {
  console.log('Connection status:', status);
  // status: 'connected' | 'disconnected' | 'connecting'
});
3

Listen to Entry Changes

// Subscribe to a specific entry
liveClient.onEntry('Product', '123', {
  name: 'product-listener',
  callback: (event, data) => {
    console.log(`Product ${event}:`, data);
    // Events: 'updated', 'deleted', 'field_changed'
  }
});
4

Listen to Entry Type Events

// Subscribe to all products
liveClient.onEntryType('Product', {
  name: 'all-products',
  callback: (event, data) => {
    if (event === 'created') {
      console.log('New product created:', data);
    }
  }
});
5

Clean Up

// Remove specific listener
liveClient.removeEntryListener('Product', '123', 'product-listener');

// Leave all listeners for an entry
liveClient.leaveEntry('Product', '123');

// Disconnect when done
liveClient.stop();

​
Query and Aggregate Data

Perform advanced queries with filtering and aggregation: 
// Count entries with grouping
const stats = await client.entry.count('Order', {
  groupBy: ['status'],
  filter: {
    createdAt: { $gte: Date.now() - 86400000 } // Last 24 hours
  }
});

// [{ status: 'pending', count: 15 }, { status: 'completed', count: 42 }]

// Sum numeric fields
const revenue = await client.entry.sum('Order', {
  fields: ['total', 'tax'],
  filter: { status: 'completed' }
});

console.log(`Total revenue: $${revenue.total}`);

​
Check Server Connection

Verify your backend is reachable: 
const isOnline = await client.ping();
if (isOnline) {
  console.log('Connected to Inspatial Cloud');
} else {
  console.error('Unable to reach backend');
}

​
Using MIME Type Utilities

The SDK includes built-in MIME type detection: 
import { MimeTypes } from '@inspatial/cloud-client';

// Get MIME type from file name
const mimeType = MimeTypes.getMimeTypeByFileName('document.pdf');
// 'application/pdf'

// Get by extension
const type = MimeTypes.getMimeTypeByExtension('png');
// 'image/png'

// Get category
const category = MimeTypes.getCategory('mp4');
// 'video'

// Get all extensions in a category
const imageExts = MimeTypes.getExtensionsByCategory('image');

​
Complete Example

Here’s a complete working example combining REST and real-time clients: 
import { InCloudClient, InLiveClient } from '@inspatial/cloud-client';

// Initialize clients
const client = new InCloudClient('/api');
const liveClient = new InLiveClient('ws://localhost:8080');

// Start live connection
liveClient.start();

// Fetch initial data
const products = await client.entry.getEntryList('Product', {
  limit: 20,
  filter: { status: 'active' }
});

console.log(`Loaded ${products.list.length} products`);

// Listen for new products
liveClient.onEntryType('Product', {
  name: 'product-updates',
  callback: (event, data) => {
    if (event === 'created') {
      console.log('New product added:', data);
      // Update your UI with the new product
    }
  }
});

// Create a new product
const newProduct = await client.entry.createEntry('Product', {
  name: 'Wireless Mouse',
  price: 29.99,
  status: 'active'
});

// The live listener above will be triggered automatically
The real-time client automatically manages room subscriptions. When you add listeners, it joins the appropriate rooms, and when all listeners are removed, it leaves the room to optimize bandwidth.

​
Next Steps

API Reference

Explore the complete API documentation

Entry Management

Learn more about working with entries

Real-time Events

Deep dive into real-time event handling

File Uploads

Advanced file upload techniques

Build docs developers (and LLMs) love

Get started for freeTalk to us