TypeScript SDK for socket.help

What the SDK covers

@socket-help/sdk is a small, dependency-free TypeScript client for the socket.help HTTP API. It works in Node.js and any runtime with fetch. Use it when you want typed methods for utilities and resources instead of building requests by hand.

The SDK is a workspace package, not a published npm install. From the repository, run pnpm build:packages, then pnpm --filter @socket-help/sdk pack to create an installable tarball.

Create a client

All options are optional. baseUrl defaults to https://socket.help and must be an origin; remote origins must use HTTPS. timeoutMs defaults to 25000. You can pass your own fetch implementation.

import { SocketHelp, SocketError } from '@socket-help/sdk';

const socket = new SocketHelp({
  apiKey: process.env.SOCKET_HELP_API_KEY,
});

const result = await socket.run('json', '{"hello":true}', { action: 'format' });
console.log(result.output, result.usage.used);

Methods

Creation methods send visibility: private unless you pass visibility: public. Methods that take a token send it in X-Resource-Token, so they work alongside an API key.

Work with resources

settings accepts ttlSeconds, persistent and visibility; upload also accepts maxDownloads. For endpoints without a dedicated method, such as reading a mock API, use request().

const inbox = await socket.createInbox({ ttlSeconds: 1800 });
// inbox.webhookUrl, inbox.accessToken; manage with your API key

const history = await socket.inspectInbox(inbox.id);

const file = await socket.upload('report.txt', new TextEncoder().encode('hello'), {
  maxDownloads: 1,
});
const bytes = await socket.downloadFile(file.id, file.accessToken);

const mock = await socket.request('GET', '/api/mocks/MOCK_ID');
await socket.remove('inboxes', inbox.id);

Errors

Failed requests throw SocketError with message, status, requestId (from X-Request-Id) and retryAfter (from Retry-After, in seconds). The SDK does not retry requests itself and does not follow redirects.

try {
  await socket.run('json', input);
} catch (error) {
  if (error instanceof SocketError && error.status === 429 && error.retryAfter) {
    // wait error.retryAfter seconds, then try again
  }
  throw error;
}