Updated March 31, 2026
12 min read
SDK Reference
Complete reference for all Handover SDK methods, types, and error codes.
The Handover SDK provides a type-safe client for interacting with the Handover API. This guide documents all available methods, their parameters, return types, and error handling.
Installation
Install the SDK using your preferred package manager. The SDK has zero runtime dependencies and works in any JavaScript environment with fetch support (Node.js 18+, browsers, edge runtimes).
npm install @handoverhq/sdk
# or
pnpm add @handoverhq/sdk
# or
yarn add @handoverhq/sdkInitialization
Create a Handover client instance with your API URL and project API key. These values are provided when you create a project in the Handover dashboard.
import { Handover } from "@handoverhq/sdk";
const handover = new Handover({
url: process.env.NEXT_PUBLIC_HANDOVER_API_URL!,
apiKey: process.env.NEXT_PUBLIC_HANDOVER_API_KEY!,
timeoutMs: 10000, // optional, defaults to 10s
});Content Methods
getContent() fetches all text and image content for your project. Returns an object with text (key-value pairs) and images (array of image objects).
const content = await handover.getContent();
const title = content.text["hero.title"] as string ?? "Default Title";
const images = content.images; // Array of HandoverImageText Update Methods
updateText() and deleteText() require an admin session token obtained from logging in. Use these methods to modify content from your /admin interface.
const sessionToken = localStorage.getItem("handover_admin_session");
// Update a text field
await handover.updateText("hero.title", "New Title", sessionToken);
// Delete a text field
await handover.deleteText("old.key", sessionToken);Image Upload Methods
uploadImage() handles the complete upload flow: requesting an upload URL, uploading to storage, and saving metadata. Returns the image ID and URL.
deleteImage() removes an image and reclaims storage quota.
const file = event.target.files[0];
const result = await handover.uploadImage(
file,
sessionToken,
"Hero image" // optional alt text
);
console.log(result.imageId, result.url);
// Delete an image
await handover.deleteImage(imageId, sessionToken);Authentication Methods
verifyPassword() validates the client password (legacy method, being phased out in favor of admin sessions).
Admin session methods handle modern authentication with username/password and role-based access.
// Legacy password check
const isValid = await handover.verifyPassword(password);
// Admin login (returns session token)
const { token, user } = await handover.loginAdmin(username, password);
localStorage.setItem("handover_admin_session", token);Error Handling
All SDK methods throw HandoverError with specific error codes. Always catch and handle these errors to provide good UX.
- HANDOVER_LOCKED - Project is locked, show lock screen
- INVALID_PASSWORD - Wrong password entered
- AUTH_RATE_LIMITED - Too many failed attempts
- STORAGE_LIMIT_EXCEEDED - Upgrade needed
- INVALID_IMAGE_TYPE - File is not an image
- NETWORK_ERROR - Connection or timeout issue
try {
const content = await handover.getContent();
} catch (error) {
if (error instanceof HandoverError) {
switch (error.code) {
case "HANDOVER_LOCKED":
showLockScreen();
break;
case "STORAGE_LIMIT_EXCEEDED":
showUpgradePrompt();
break;
default:
showError(error.message);
}
}
}This page maps to packages/sdk/index.ts in the repository.