@paperhand/typescript

Official TypeScript SDK for Paperhand — provision ephemeral VMs over a simple REST API.

Install

npm install @paperhand/typescript

Requires Node.js 18+ (uses the global fetch).

Quickstart

import { createClient } from "@paperhand/typescript";

const ph = createClient({ apiKey: process.env.PAPERHAND_API_KEY });

// Provision a VM.
const vm = await ph.vms.create({ vcpu: 4, memory: "8GB" });

// Run a command inside it.
const test = await vm.exec({ command: "npm test" });
console.log(test.stdout);

// Tear it down.
await vm.destroy();

Authentication

Every request is authenticated with a workspace API key sent as Authorization: Bearer <apiKey>.

To get a key:

1. Open the Paperhand dashboard.
2. Go to Workspace settings.
3. Open the API keys tab.
4. Click Generate key.

Keys are prefixed with ph_. Store the key in the PAPERHAND_API_KEY environment variable:

export PAPERHAND_API_KEY="ph_..."

If you don't pass apiKey explicitly, the client falls back to process.env.PAPERHAND_API_KEY and throws if it is missing.

API

createClient(options)

• options.apiKey — workspace API key. Defaults to PAPERHAND_API_KEY.
• options.baseUrl — API base URL. Defaults to https://api.paperhand.io.

client.vms.create(options) → Promise<Vm>

Provision a VM.

| Option | Type | Default | Notes | | ------------- | ---------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- | | vcpu | number | — | Required. Sent as vCPU. | | memory | string | — | Required, e.g. "8GB". | | storage | string | "4GB" | | | type | string | "linux/amd64" | | | region | VmRegion | — | One of VmRegion — us-east, us-west, apac, ew-east, eu-central, hong-kong, africa-south, mainland-china. | | idleTimeout | number | — | Seconds of inactivity before stop. | | description | string | — | | | template | string | — | Reserved; not yet sent to the API. |

Vm

• vm.id — the provisioned instanceId.
• vm.exec({ command }) → Promise<{ stdout, stderr, instance }>.
• vm.pause() → Promise<{ instance }>.
• vm.destroy() → Promise<{ instance }>.

client.shelves.create(options) → Promise<Shelf>

Create a shelf in the API key's workspace. The slug is auto-generated from the name (letters, numbers, spaces, and underscores) and is unique within the workspace.

| Option | Type | Default | Notes | | --------- | --------------------------------------- | ----------- | ---------------------------------------------------------------------------------------- | | name | string | — | Required. Letters, numbers, spaces, and underscores. | | privacy | "private" \| "public" \| "restricted" | "private" | private: only you. public: everyone in the workspace. restricted: you + userIds. | | userIds | string[] | — | Workspace user ids granted access. Only used when privacy is restricted. |

const shelf = await ph.shelves.create({
  name: "reports",
  privacy: "restricted",
  userIds: ["user_123", "user_456"],
});
console.log(shelf.id, shelf.slug); // → "…", "reports"

client.shelves.get(idOrSlug) → Promise<ShelfDetails>

Fetch a shelf by its id or slug. Throws PaperhandError (status 404) when the shelf doesn't exist or isn't visible to the key's workspace.

const shelf = await ph.shelves.get("reports"); // by slug
// or: await ph.shelves.get("k17abc...")        // by id
console.log(shelf.name, shelf.privacy, shelf.createdAt);

client.shelves.updatePrivacy(idOrSlug, options) → Promise<void>

Change a shelf's privacy, addressing it by id or slug. Only the shelf's owner may do this. Throws PaperhandError (status 404) when the shelf doesn't exist or isn't visible to the key's workspace.

| Field | Type | Description | | --------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | privacy | "private" \| "public" \| "restricted" | The new visibility. | | userIds | string[] | Workspace user ids granted access. Only used when privacy is restricted (replaces the shelf's members). |

await ph.shelves.updatePrivacy("reports", {
  privacy: "restricted",
  userIds: ["usr_1", "usr_2"],
});

Shelf

• shelf.id — the created shelfId.
• shelf.slug — the auto-generated slug.

ShelfDetails

Returned by shelves.get: { id, name, slug, privacy, createdAt } (createdAt is epoch milliseconds).

Errors

Any non-2xx response throws a PaperhandError with status (HTTP code) and message (the server's error field when present).

import { PaperhandError } from "@paperhand/typescript";

try {
  await ph.vms.create({ vcpu: 4, memory: "8GB" });
} catch (err) {
  if (err instanceof PaperhandError) {
    console.error(err.status, err.message);
  }
}