Installation

npm install @putdotio/sdk

Quick Start

userAccessToken in these examples is an already-issued user token from your app or auth flow.

import { createPutioSdkPromiseClient } from "@putdotio/sdk";

const sdk = createPutioSdkPromiseClient({
  accessToken: userAccessToken,
});

const account = await sdk.account.getInfo({
  download_token: 1,
});

Authentication

The client can be created without a token, for flows that obtain or check one:

const sdk = createPutioSdkPromiseClient();

const validation = await sdk.auth.validateToken(tokenToCheck);
const login = await sdk.auth.login({
  callbackUrl,
  clientId,
  clientSecret,
  password,
  username,
});

Server-side callers can add headers that every API request the SDK sends carries. Per-request headers win, and an authorization entry in config headers is ignored.

const sdk = createPutioSdkPromiseClient({
  headers: { "x-forwarded-for": viewerIp },
});

Long-lived Promise clients can replace or clear their token without recreating the client:

sdk.setAccessToken(nextUserAccessToken);
const account = await sdk.account.getInfo({});

sdk.setAccessToken(undefined);

The token is snapshotted when each Promise-client operation is invoked. Token changes apply to subsequent operations; an operation already in flight keeps the snapshot it started with. Base, upload, and web app URLs remain fixed from client creation.

Authorization-code clients can exchange a code without configuring a default access token:

const sdk = createPutioSdkPromiseClient();

const accessToken = await sdk.auth.exchangeAuthorizationCode({
  clientId,
  clientSecret,
  code,
  redirectUri,
});

The exchange uses a form-encoded POST and never sends a configured bearer token. Known OAuth failures are exposed as OAuthAuthorizationCodeExchangeError; client secrets and codes are not included in validation errors.

App-Specific Passwords

Create and manage passwords for apps that use put.io basic authentication:

const created = await sdk.account.appSpecificPasswords.create({
  note: "Media server",
});

savePasswordSecurely(created.password);

const passwords = await sdk.account.appSpecificPasswords.list();
await sdk.account.appSpecificPasswords.delete(created.id);
await sdk.account.appSpecificPasswords.deleteAll();

The plaintext password is returned only by create. List results contain metadata instead, including a nullable last_used_at timestamp and a null or masked ip_address.

Utilities

Shared formatting, URL, and error-localization helpers are available from the utilities subpath:

import {
  FileUrlProvider,
  secondsToReadableDuration,
  toHumanFileSize,
} from "@putdotio/sdk/utilities";

const urls = new FileUrlProvider({ baseUrl: "https://api.put.io", downloadToken });
const size = toHumanFileSize(1_572_864);
const duration = secondsToReadableDuration(444);

Effect Example

import { Effect } from "effect";
import {
  PutioSdk,
  createPutioSdkEffectClient,
  makePutioSdkLiveClientLayer,
  makePutioSdkLiveLayer,
} from "@putdotio/sdk";

const sdk = createPutioSdkEffectClient();

const program = sdk.files
  .list(0, {
    per_page: 20,
    total: 1,
  })
  .pipe(Effect.provide(makePutioSdkLiveLayer({ accessToken: userAccessToken })));

const result = await Effect.runPromise(program);

Effect workflows can also depend on the SDK as a service:

const serviceProgram = Effect.gen(function* () {
  const sdk = yield* PutioSdk;
  return yield* sdk.files.list(0, { per_page: 20 });
}).pipe(Effect.provide(makePutioSdkLiveClientLayer({ accessToken: userAccessToken })));

makePutioSdkLiveClientLayer(...) provides the SDK service, SDK config, and default fetch-backed transport. makePutioSdkLiveLayer(...) provides both the SDK config and the default fetch-backed transport. Use makePutioSdkLayer(...) with makePutioFetchLayer(...) or your own PutioHttpClient service when you want to supply custom transport.

Client Shapes

Both client styles expose the same domain surface:

promiseClient.files.list(0, { per_page: 20 });
effectClient.files.list(0, { per_page: 20 });

| Client | Use it for | | ------------------------------------- | ------------------------------------------------- | | createPutioSdkPromiseClient(config) | React apps, scripts, server handlers, React Query | | createPutioSdkEffectClient() | Effect-native workflows and service composition |

Effect is the canonical typed surface; the Promise client adapts it to standard async functions.

• Effect client: keeps errors in the Effect error channel with operation-specific typing.
• Promise client: throws tagged SDK error objects such as PutioOperationError, PutioApiError, and PutioRateLimitError.
• Promise client: owns a managed Effect runtime; call await sdk.dispose() when tearing down a long-lived client.
• Promise client: files.createUploadFormData(...) builds upload FormData without a request.

Interrupting an Effect during fetch or response-body consumption aborts the underlying fetch request, including JSON and binary reads. Successful reads do not abort the request.

Namespaces

Both clients expose the namespaces of sharedOperationTree in src/core/client.ts, such as account, files, transfers, and sharing. Helpers live in the utilities subpath, not on the client.

Runtime Requirements

Host runtimes must provide:

• fetch
• Request, Response, and Headers
• URL and URLSearchParams
• AbortController
• FormData
• btoa for username/password auth flows such as auth.login(...)

Upload flows also need file inputs such as File or Blob. Fill missing APIs with host-level polyfills or adapters instead of patching the SDK surface.

Error Handling

The fetch transport retains HTTP status and rate-limit headers when an error response contains empty or invalid JSON. These errors include a sanitized parsing cause; response contents are not included in that cause. Failures while reading the body remain transport errors, including errors from custom HTTP clients.

Backend error bodies preserve status, status_code, error_type, error_message, error_uri, nullable error_id, and structured extra metadata. The legacy details field is still parsed, but current backend errors use extra.

Promise consumers receive tagged SDK error objects:

import {
  createPutioSdkPromiseClient,
  isPutioOperationError,
  isPutioRateLimitError,
} from "@putdotio/sdk";

const sdk = createPutioSdkPromiseClient({
  accessToken: userAccessToken,
});

try {
  await sdk.files.createFolder({
    name: "",
    parent_id: 0,
  });
} catch (error) {
  if (isPutioOperationError(error)) {
    if (error.operation === "createFolder") {
      console.log(error.body.error_type);
    }
  }

  if (isPutioRateLimitError(error)) {
    console.log(error.retryAfter);
  }
}

A rate limit with error.action === "captcha-needed" can be lifted from the limited visitor's browser with a solved reCAPTCHA token:

if (isPutioRateLimitError(error) && error.action === "captcha-needed" && error.id) {
  await sdk.rateLimits.removeBan({ captchaToken, id: error.id });
}

Effect consumers keep errors in the typed error channel instead of throwing:

import { Effect } from "effect";
import { PutioSdk, makePutioSdkLiveClientLayer } from "@putdotio/sdk";

const handled = Effect.gen(function* () {
  const sdk = yield* PutioSdk;
  return yield* sdk.files.createFolder({
    name: "",
    parent_id: 0,
  });
}).pipe(
  Effect.catchTag("PutioOperationError", (error) => {
    if (error.operation === "createFolder") {
      return Effect.succeed(error.body.error_type);
    }

    return Effect.fail(error);
  }),
  Effect.provide(makePutioSdkLiveClientLayer({ accessToken: userAccessToken })),
);

Direct File Access

files exposes both JSON contracts and direct route helpers. Media URLs leave your app (players, casting receivers, shared links, logs), so sign them with the account download token, which only grants file access, instead of the OAuth token. downloadToken is required; the helpers never fall back to the client's accessToken.

const { download_token: downloadToken } = await sdk.account.getInfo({ download_token: 1 });

const playlistUrl = await sdk.files.getHlsStreamUrl(fileId, {
  downloadToken,
  maxSubtitleCount: 1,
});

const vlcPlaylistUrl = await sdk.files.getXspfPlaylistUrl(fileId, { downloadToken });

// The master playlist put.io would serve, for inspecting the selected
// variant's CODECS and VIDEO-RANGE. `playOriginal` picks the original
// file over the MP4 conversion.
const masterPlaylist = await sdk.files.getHlsMasterPlaylist(fileId, {
  playOriginal: false,
});

const upload = await sdk.files.upload({
  file: new File(["hello"], "hello.txt"),
  parentId: 0,
});

Upload goes to upload.put.io, because api.put.io/v2/files/upload is only a redirect shim.

Endpoint Coverage

The SDK covers the supported public put.io API surface. It leaves out admin, private, and service-to-service routes, browser page and callback routes, and aliases of routes it already covers.

File Lookup and Mutations

When requesting media_info, stream level values preserve FFmpeg's -99 sentinel for an unknown codec level. Known levels remain nonnegative integers. Stream codec_name can be null when the codec was not identified, including subtitle streams.

Named-child lookup avoids listing an entire folder and preserves the same query-conditioned fields as files.get:

const child = await sdk.files.getChild({
  parentId: folderId,
  name: "movie.mp4",
  query: { stream_url: 1 },
});

await sdk.files.touch({ fileIds: [child.id], updatedAt: new Date() });
const copy = await sdk.files.copy({ fileId: child.id, parentId: 0, name: "movie copy.mp4" });
const writableUserId = await sdk.files.canWrite(copy.id);

canWrite resolves the user ID returned by the backend when the file is writable. A non-writable, missing, or payment-gated file rejects with the corresponding typed SDK error rather than returning false.

Transfer Torrent Operations

Torrent-backed transfers expose their original metainfo bytes and tracker mutation:

const torrent = await sdk.transfers.getTorrent(transferId);

await sdk.transfers.addTrackers({
  transferId,
  trackers: ["udp://tracker.example:80", "https://tracker.example/announce"],
});

getTorrent rejects for magnet-backed or non-torrent transfers. Remove accepts exactly one selector, preventing an ambiguous mix of IDs and filters:

await sdk.transfers.remove({ ids: [transferId] });
await sdk.transfers.remove({ filter: "completed" });

Folder Sort and Podcast Feeds

Folder sort settings persist per folder and apply to subsequent file listings:

await sdk.files.setSort({
  fileId: folderId,
  sortBy: "MODIFIED_DESC",
});

await sdk.files.resetSortSettings();

resetSortSettings() clears the saved sort setting for every folder, including the root folder.

Podcast links can target a folder and an explicit non-empty selection of feed types. Omit types to request the API defaults:

const { links, token } = await sdk.podcast.getLinks({
  parentId: folderId,
  types: ["audio", "mp4"],
});

links is a partial map keyed by all, audio, video, and mp4; check that a requested link is present.

TanStack Query

The Promise client plugs into TanStack Query directly:

import { useQuery } from "@tanstack/react-query";
import { createPutioSdkPromiseClient } from "@putdotio/sdk";

const sdk = createPutioSdkPromiseClient({
  accessToken: token,
});

export const useAccountInfo = () =>
  useQuery({
    queryKey: ["account", "info"],
    queryFn: () => sdk.account.getInfo({ download_token: 1 }),
  });

The Effect client works the same way:

import { useQuery } from "@tanstack/react-query";
import { Effect } from "effect";
import { PutioSdk, makePutioSdkLiveClientLayer } from "@putdotio/sdk";

const sdkLayer = makePutioSdkLiveClientLayer({
  accessToken: token,
});

export const useFiles = (parentId: number) =>
  useQuery({
    queryKey: ["files", parentId],
    queryFn: () =>
      Effect.runPromise(
        Effect.gen(function* () {
          const sdk = yield* PutioSdk;
          return yield* sdk.files.list(parentId, { per_page: 50 });
        }).pipe(Effect.provide(sdkLayer)),
      ),
  });

Docs

• Releases: what changed in each version, breaking changes included
• Contributing: setup, checks, and live tests
• Security policy: private vulnerability reports

License

This project is available under the MIT License.