Skip to main content

​
TypeScript SDK

The official Gumnut TypeScript SDK provides full type safety and works seamlessly in both Node.js and browser environments.

​
Installation

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

​
Quick Start

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]
});

​
Key Features

  • Full TypeScript Support: Complete type definitions for all API endpoints
  • Universal Compatibility: Works in Node.js 16+ and modern browsers
  • Automatic Retries: Built-in exponential backoff for failed requests
  • File Upload Helpers: Support for various file formats (File, Buffer, Stream)
  • Streaming Support: Handle large responses efficiently
  • Tree-shakeable: Optimized bundle size for frontend applications

​
File Upload Options

Multiple ways to upload files: 
// 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'
});

​
Configuration

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

​
Error Handling

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`);
    }
  }
}

​
Repository & Documentation

GitHub Repository: github.com/gumnut-ai/photos-sdk-typescript For complete API documentation, examples, and advanced usage:

​
Browser Usage

The SDK works in browsers with proper bundling: 
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'
});

​
Next Steps

⌘I