@metalevel/snapix-sdk-core

Typed TypeScript SDK for the Snapix REST API - image upload, on-the-fly conversion, resizing, gallery management, and AI generation for server-side Node.js applications.

• Server-side only (Node.js ≥ 18) - keeps your API key secure
• Zero runtime dependencies - uses native fetch and FormData
• Full TypeScript types for all requests and responses
• Auto-configuration from environment variables

Installation

npm install @metalevel/snapix-sdk-core

or

pnpm add @metalevel/snapix-sdk-core

Quick Start

export SNAPIX_API_KEY=your_api_key_here

import { SnapixClient } from "@metalevel/snapix-sdk-core";

const client = new SnapixClient(); // reads SNAPIX_API_KEY from env

const result = await client.uploadImage({
  imageUrl: "https://example.com/photo.jpg",
  name: "my-photo",
  formatOptions: [{ format: "webp" }],
});

console.log(result.simpleData.variants);
// { webp: "https://cdn.snapix.space/..." }

Configuration

Environment Variables

| Variable | Required | Default | Description | | --- | --- | --- | --- | | SNAPIX_API_KEY | Yes | - | Your Snapix API key | | SNAPIX_BASE_URL | No | https://www.snapix.space | Override API base URL | | SNAPIX_BUCKET_KEY | No | primary bucket | Default storage bucket key | | SNAPIX_LOG_LEVEL | No | warn | debug | info | warn | error | silent |

Manual Configuration

const client = new SnapixClient({
  apiKey: "your_api_key",
  baseUrl: "https://www.snapix.space",
  logLevel: "debug",
});

API Reference

Image Methods

// Upload from URL, file path, or base64
await client.uploadImage(params: UploadImageParams): Promise<UploadImageResponse>

// List with pagination
await client.listImages(params?: ListImagesParams): Promise<ListImagesResponse>

// Get single image
await client.getImage(imageId: string): Promise<GetImageResponse>

// Update metadata
await client.updateImage(imageId: string, params: UpdateImageParams): Promise<UpdateImageResponse>

// Delete
await client.deleteImage(imageId: string): Promise<{ success: true }>

Convert Methods (on-the-fly, not stored)

// Returns binary data
await client.convertImage(params: ConvertImageParams): Promise<Buffer>

// Writes to disk
await client.convertImageToFile(params: ConvertImageParams, outputPath: string): Promise<void>

Generate Method (AI)

await client.generateImage(params: GenerateImageParams): Promise<UploadImageResponse>

Gallery Methods

await client.createGallery(params: CreateGalleryParams): Promise<CreateGalleryResponse>
await client.listGalleries(): Promise<ListGalleriesResponse>
await client.getGallery(galleryId: string): Promise<GetGalleryResponse>
await client.getImagesWithoutGallery(params?: GetImagesWithoutGalleryParams): Promise<GetImagesWithoutGalleryResponse>
await client.updateGallery(galleryId: string, params: UpdateGalleryParams): Promise<GalleryType>
await client.deleteGallery(galleryId: string, deleteImages?: boolean): Promise<{ success: true }>

Next.js Integration

// app/actions/upload.ts
"use server";
import { SnapixClient } from "@metalevel/snapix-sdk-core";

const client = new SnapixClient();

export async function uploadImage(formData: FormData) {
  const file = formData.get("image") as File;
  const base64 = Buffer.from(await file.arrayBuffer()).toString("base64");

  const result = await client.uploadImage({
    imageBase64: base64,
    imageContentType: file.type,
    name: "upload",
    formatOptions: [{ format: "webp" }],
  });

  return result.simpleData.variants["webp"];
}

Error Handling

import { SnapixClient, SnapixApiError, SnapixConfigError } from "@metalevel/snapix-sdk-core";

try {
  const client = new SnapixClient();
  await client.uploadImage({ imageUrl: "https://..." });
} catch (err) {
  if (err instanceof SnapixConfigError) {
    // Missing SNAPIX_API_KEY
  } else if (err instanceof SnapixApiError) {
    console.error(err.status, err.message);
    if (err.isRetryable) { /* 429 - retry after backoff */ }
  }
}

Links

• Full SDK Documentation
• REST API Reference
• MCP Server
• SDK Preview App - interactive Next.js test app for this SDK
• Get API Key

License

MIT