TypeScript SDK

npm install gumnut-sdk
# or
yarn add gumnut-sdk
# or
pnpm add gumnut-sdk

import Gumnut from 'gumnut-sdk';

const client = new Gumnut({
  apiKey: process.env.GUMNUT_API_KEY
});

// Upload an asset
const asset = await client.assets.create({
  asset_data: fs.createReadStream('photo.jpg'),
  device_asset_id: 'photo_001',
  device_id: 'my_device',
  file_created_at: new Date().toISOString(),
  file_modified_at: new Date().toISOString()
});

// Create an album
const album = await client.albums.create({
  album_name: 'Vacation 2024',
  description: 'Summer vacation photos'
});

// Add asset to album
await client.albums.addAssets(album.id, {
  asset_ids: [asset.id]
});

const viewport = '-77.1,38.9,-77.0,39.0';

// List the individual assets inside a bounding box.
const page = await client.assets.list({
  bbox: viewport,
  limit: 100,
});

// Or search around a single point instead of a rectangle.
const nearby = await client.assets.list({
  center: '-77.05,38.95',
  radius: 1000,
  limit: 100,
});

// Summarize the viewport into map-friendly clusters.
const clusters = await client.assets.clusterByGeo({
  bbox: viewport,
  cell_size: 0.01,
});

for (const cluster of clusters.data) {
  console.log(cluster.count, cluster.latitude, cluster.longitude);
}

// File stream (Node.js)
import fs from 'fs';
const asset = await client.assets.create({
  asset_data: fs.createReadStream('photo.jpg'),
  device_asset_id: 'unique_id',
  device_id: 'my_device'
});

// Buffer with helper
import { toFile } from 'gumnut-sdk';
const asset = await client.assets.create({
  asset_data: await toFile(buffer, 'photo.jpg'),
  device_asset_id: 'unique_id', 
  device_id: 'my_device'
});

// Fetch response
const asset = await client.assets.create({
  asset_data: await fetch('https://example.com/photo.jpg'),
  device_asset_id: 'unique_id',
  device_id: 'my_device'
});

// Web File API (browser)
const asset = await client.assets.create({
  asset_data: new File([bytes], 'photo.jpg'),
  device_asset_id: 'unique_id',
  device_id: 'my_device'
});

const client = new Gumnut({
  apiKey: process.env.GUMNUT_API_KEY,
  maxRetries: 3, // Default retry count
  timeout: 60000 // Request timeout in milliseconds
});

import { APIError } from 'gumnut-sdk';

try {
  const asset = await client.assets.get('invalid_id');
} catch (error) {
  if (error instanceof APIError) {
    console.log(`API Error: ${error.status} - ${error.message}`);
    if (error.status === 429) {
      console.log(`Rate limited. Retry after: ${error.retryAfter}s`);
    }
  }
}

import Gumnut from 'gumnut-sdk';

// Use OAuth token, not API key in browser
const client = new Gumnut({
  apiKey: oauthToken // Get from your OAuth flow
});

// Upload from file input
const fileInput = document.getElementById('file');
const file = fileInput.files[0];

const asset = await client.assets.create({
  asset_data: file,
  device_asset_id: `browser_${Date.now()}`,
  device_id: 'web_client'
});