IBM Cloud Object Storage

IBM Cloud Object Storage via the S3-compatible API. Auth uses IBM Cloud HMAC credentials, not IAM API keys.

Installation

@aws-sdk/client-s3, @aws-sdk/s3-presigned-post, and @aws-sdk/s3-request-presigner are optional peer dependencies of files-sdk - install alongside the SDK so the adapter’s imports resolve at runtime.

npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

pnpm add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

yarn add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

bun add files-sdk @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner

Usage

import { Files } from "files-sdk";
import { ibmCos } from "files-sdk/ibm-cos";

const files = new Files({
  adapter: ibmCos({
    bucket: "uploads",
    region: "us-south", // or "eu-de", "jp-tok", "au-syd", ...
    // accessKeyId / secretAccessKey auto-loaded from
    // IBM_COS_ACCESS_KEY_ID / IBM_COS_SECRET_ACCESS_KEY (HMAC credentials)
  }),
});

IBM Cloud Object Storage via its S3-compatible API. A thin wrapper around the S3 adapter - endpoint derived from the region code (us-south, us-east, eu-de, eu-gb, jp-tok, au-syd, br-sao, ca-tor, …), virtual-hosted-style addressing, errors relabelled. Auth uses IBM Cloud’s HMAC credentials (not IAM API keys) - tick “Include HMAC Credential” under Advanced options when creating the service credential. Auto-loads from IBM_COS_ACCESS_KEY_ID and IBM_COS_SECRET_ACCESS_KEY.

Options

PropType

bucketstring

IBM COS bucket name. The adapter scopes all operations to it.

Typestring

regionstring

IBM Cloud Object Storage region code, e.g. `"us-south"`, `"us-east"`, `"eu-de"`, `"eu-gb"`, `"eu-es"`, `"jp-tok"`, `"jp-osa"`, `"au-syd"`, `"br-sao"`, `"ca-tor"`. Drives the endpoint host (`https://s3.<region>.cloud-object-storage.appdomain.cloud`); there's no env-var fallback. Doubles as the SigV4 region.

Typestring

endpoint?string

Override the IBM COS endpoint. When unset, defaults to the public `https://s3.${region}.cloud-object-storage.appdomain.cloud`. For direct (no-egress) access from inside the same IBM Cloud region, pass `https://s3.direct.${region}.cloud-object-storage.appdomain.cloud` (or the equivalent `private` host). IBM COS routes by Host header.

Typestring

accessKeyId?string

HMAC access key ID. Generate HMAC credentials when creating the IBM COS service credential (Advanced options → "Include HMAC Credential") — separate from IBM Cloud IAM API keys. Falls back to `IBM_COS_ACCESS_KEY_ID`; required if that env var isn't set.

Typestring

secretAccessKey?string

HMAC secret access key. Falls back to `IBM_COS_SECRET_ACCESS_KEY`; required if that env var isn't set.

Typestring

forcePathStyle?boolean

Use path-style addressing (`/<bucket>/<key>`) rather than virtual-hosted style. Defaults to `false` — virtual-hosted is canonical for IBM COS.

Typeboolean

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips signing. For buckets with a public access policy the natural value is `https://${bucket}.s3.${region}.cloud-object-storage.appdomain.cloud`; a custom CNAME fronting the bucket also works. When unset, `url()` falls back to a presigned GetObject (default expiry: 1 hour).

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, for the presigned URLs returned by `url()` when `publicBaseUrl` is not set. Defaults to 3600 (1 hour).

Typenumber

Compatibility

Method	Status	Notes
`upload`	✅
`download`	✅
`delete`	✅
`list`	✅
`search`	✅
`head`	✅
`exists`	✅
`copy`	✅
`url`	✅
`signedUploadUrl`	✅