Skip to main content

API Reference

Complete reference for all exported classes, methods, and type definitions in @liorans3/driver.

1. Class: BastionClient​

Constructor​

new BastionClient(uriOrOptions: string | BastionClientOptions)

Properties​

  • uri: BastionUri: Parsed connection URI.
  • safeUri: string: Connection URI with credentials masked.
  • buckets: BucketsClient: Bucket management client.
  • users: UsersClient: User management client.
  • accessKeys: AccessKeysClient: Access key client.
  • videos: VideosClient: Video operations client.

Methods​

bucket(name: string): BucketHandle​

Returns a scoped handle for interacting with objects and configuration in the specified bucket.

health(): Promise<HealthStatus>​

Checks server health status (GET /health). Returns { name: string, status: string, version: string }.

systemInfo(): Promise<SystemInfo>​

Retrieves diagnostic system information (GET /api/v1/system/info).

systemPerformance(): Promise<PutPerformanceSnapshot>​

Retrieves server PUT latency breakdown and throughput statistics (GET /api/v1/system/performance).

metrics(): Promise<string>​

Retrieves raw Prometheus exposition metrics in plain text format (GET /api/v1/metrics).

uploadMultipart(source: MultipartUploadSource, options: UploadMultipartOptions): Promise<ObjectMetadata>​

High-level automated chunked multipart upload for large files.

2. Class: BucketHandle​

Properties​

  • name: string: Target bucket name.

Methods​

info(): Promise<BucketMetadata>​

Fetches bucket metadata and configuration.

update(options: UpdateBucketOptions): Promise<BucketMetadata>​

Updates bucket quotas, versioning state, and tags.

deleteBucket(force?: boolean): Promise<boolean>​

Deletes the bucket from the server.

put(key: string, data: PutData, options?: PutObjectOptions): Promise<ObjectMetadata>​

Uploads an object with bounded-memory streaming.

  • data: ReadableStream, Node Readable, Buffer, Uint8Array, Blob, or string.

get(key: string, options?: GetObjectOptions): Promise<BastionObject>​

Downloads an object with bounded-memory streaming.

getRange(key: string, range: ByteRangeSpec | string, options?: GetObjectOptions): Promise<BastionObject>​

Downloads a specific byte range of an object.

head(key: string, options?: ObjectOptions): Promise<ObjectHeaderInfo>​

Queries object headers without downloading the body (HTTP HEAD).

delete(key: string): Promise<boolean>​

Deletes an object from the bucket.

listPage(options?: ListObjectsOptions): Promise<ListObjectsResponse>​

Queries a single paginated batch of object metadata.

list(options?: ListObjectsOptions): Promise<ObjectMetadata[]>​

Returns all matching objects, automatically traversing all pages.

presign(key: string, method?: "GET" | "PUT" | "HEAD", options?: PresignOptions): Promise<PresignedUrlResult>​

Generates an expiring cryptographically signed URL.

presignGet(key: string, options?: PresignOptions): Promise<string>​

Generates an expiring presigned GET URL string.

presignPut(key: string, options?: PresignOptions): Promise<string>​

Generates an expiring presigned PUT URL string.

presignHead(key: string, options?: PresignOptions): Promise<string>​

Generates an expiring presigned HEAD URL string.

optimize(key: string, options?: OptimizeImageOptions): Promise<OptimizedImageResult>​

Performs server-side image transformation (resizing, format conversion, quality tuning).

createMultipartUpload(key: string, options?: CreateMultipartUploadOptions): Promise<MultipartUploadHandle>​

Initiates a generic resumable multipart upload session.

uploadMultipart(key: string, source: MultipartUploadSource, options?: UploadMultipartOptions): Promise<ObjectMetadata>​

High-level automated chunked multipart upload.

3. Class: BastionObject​

Handle returned by bucket.get() and bucket.getRange().

Properties​

  • bucket: string: Bucket name.
  • key: string: Object key.
  • status: number: HTTP status (200 or 206).
  • metadata: ObjectHeaderInfo: Parsed object headers (contentLength, contentType, etag, sha256, lastModified, acceptRanges, contentRange).

Methods​

  • stream(): NodeJS.ReadableStream: Returns stream for Node.js pipelines.
  • text(): Promise<string>: Decodes body as UTF-8 string.
  • json<T>(): Promise<T>: Parses body as JSON object.
  • buffer(): Promise<Buffer>: Reads body into Node.js Buffer.
  • arrayBuffer(): Promise<ArrayBuffer>: Reads body into ArrayBuffer.
  • writeToFile(filePath: string): Promise<void>: Streams body directly to disk file.
  • pipeTo(destination: NodeJS.WritableStream): Promise<void>: Pipes body to writable stream.

4. Class: MultipartUploadHandle​

Properties​

  • uploadId: string: Unique upload session identifier.
  • bucket: string: Destination bucket name.
  • key: string: Destination object key.
  • recommendedPartSize: number: Recommended chunk size in bytes.
  • maxParallelParts: number: Recommended concurrency limit.
  • expiresAt: string: Session expiration timestamp.

Methods​

  • uploadPart(partNumber: number, data: PutData, options?: { contentLength?: number }): Promise<MultipartUploadPartResponse>
  • status(): Promise<MultipartUploadSession>
  • complete(options?: MultipartUploadCompleteRequest): Promise<ObjectMetadata>
  • abort(): Promise<boolean>

5. Type Definitions​

BucketMetadata​

interface BucketMetadata {
  name: string;
  owner: string;
  quota_bytes: number | null;
  versioning_enabled: boolean;
  tags?: Record<string, string>;
  created_at?: string;
  updated_at?: string;
}

ObjectMetadata​

interface ObjectMetadata {
  bucket: string;
  key: string;
  size_bytes: number;
  content_type?: string;
  etag?: string;
  sha256_checksum?: string;
  version_id?: string;
  custom_metadata?: Record<string, string>;
  created_at: string;
  updated_at: string;
}

PutObjectOptions​

interface PutObjectOptions {
  contentType?: string;
  contentLength?: number;
  signal?: AbortSignal;
}

ByteRangeSpec​

interface ByteRangeSpec {
  start?: number;
  end?: number;
  suffix?: number;
}

ListObjectsOptions​

interface ListObjectsOptions {
  prefix?: string;
  limit?: number; // 1..1000
  cursor?: string;
  signal?: AbortSignal;
}

PresignOptions​

interface PresignOptions {
  expiresIn?: number; // Duration in seconds (default: 3600)
  signal?: AbortSignal;
}