Skip to content
S3 Lens

TypeScript client

@s3lens/client is the first-party TypeScript client. It owns one WebSocket connection, negotiates protocol revision 1, validates requests and responses, and reconnects after ordinary connection failures.

The package is currently consumed inside the S3 Lens workspace. Its public boundary is Effect-based: operations return Effect values with typed S3 Lens failures in the error channel.

Create a client

Section titled “Create a client”
import { Effect } from "effect";
import { createClient } from "@s3lens/client";


const client = createClient({
  url: "ws://127.0.0.1:8085/rpc",
  clientInfo: {
    name: "example-client",
    version: "1.0.0",
  },
});


const program = Effect.gen(function* () {
  const { providers } = yield* client.call("provider/list", {});
  return providers;
});


const providers = await Effect.runPromise(program);
await Effect.runPromise(client.close);

createClient performs no network I/O. The first client.call connects, sends initialize, and waits for the handshake. The client reconnects after ordinary connection failures. Set reconnect: { enabled: false } when the host manages the connection lifecycle itself.

Use initialized() to read the last handshake result and connectionState() to read the current connection state. Register onConnectionStateChange to observe state changes.

Call protocol methods

Section titled “Call protocol methods”

The client exposes one generic typed operation. The method name selects its parameter and result types from the generated registry:

const result = await Effect.runPromise(
  client.call("object/list", {
    providerId: "garage",
    bucketName: "media",
    prefix: "2026/",
    limit: 50,
  }),
);

The available methods cover these areas:

Area Methods
API Keys api-key/create, api-key/list, api-key/rotate, api-key/update-scope, api-key/revoke, and api-key/revoke-all
Providers provider/list
Buckets bucket/list, bucket/get, creation, deletion, and policy methods
Objects listing, search, preview, copy, move, deletion, tags, and versions
Multipart uploads listing, part listing, and abort
Transfers object/transfer/create

All parameter and result types come from @s3lens/contracts/v1. See the revision 1 method catalog for the complete wire-level inventory.

Stream object bytes

Section titled “Stream object bytes”

Large downloads and uploads should use transfer tickets instead of JSON-RPC Object bodies. The client creates the ticket. The host redeems its relative URL over HTTP.

const ticket = await Effect.runPromise(
  client.call("object/transfer/create", {
    providerId: "garage",
    bucketName: "media",
    key: "video.mp4",
    direction: "download",
  }),
);


const response = await fetch(new URL(ticket.url, "http://127.0.0.1:8085"));

@s3lens/client does not provide HTTP transfer helpers, Blob types, or upload progress. Browser and desktop hosts own those details.

Transfer tickets are single-use, expire after 120 seconds when unused, and are consumed when redemption begins. Mint a new ticket after a failed or interrupted attempt.

Browser authentication

Section titled “Browser authentication”

The browser WebSocket automatically carries same-origin cookies. When OIDC is enabled, complete /v1/auth/authorize first and connect from the exact configured public origin. A non-browser host can attach a scoped S3 Lens API Key as a bearer credential when initialize.capabilities.apiKeys is true; key creation and revocation require an interactive session. Identity-provider OAuth access tokens are not S3 Lens API credentials. Electron opens the shared authorization endpoint in the system browser and exchanges a PKCE-bound code at /v1/auth/token; its main process owns the resulting credential and authenticated connection.