Agent doc: Storage JS SDK

Package

• Name: @spectra-platform/storage-sdk
• Version: 0.1.3
• Registry: GitHub Packages

Purpose

Storage JS SDK performs app-user scoped file/object operations against Storage Platform.

API tree

Storage JS SDK
├─ setup
│  ├─ new SpectraStorageClient(config)
│  └─ createSpectraStorageClient(config)
└─ files
   ├─ listFiles(options?)
   ├─ uploadFile(input)
   ├─ uploadImage(input)
   ├─ uploadFile(fileOrBlob, options)   # legacy compatible
   ├─ uploadImage(file, options?)       # legacy compatible
   ├─ getDownloadUrl(path)
   ├─ downloadBlob(path)
   └─ deleteFile(path)

Public setup inputs

• projectId
• auth, usually an Auth SDK instance
• optional API baseUrl
• optional fetch
• optional crypto

Required auth object and token boundary

• Pass the Auth JS SDK object as auth.
• Storage SDK obtains Storage-scoped authorization through auth.getAccessToken({ service: "storage" }) or an equivalent Auth SDK boundary.
• Storage operations are app-user scoped under the user's root path.
• Browser/mobile code must not hold admin bucket credentials, S3/MinIO root keys, or provider secrets. Secret Key exposure requires an explicit consuming-project architecture decision, and the raw value must not be logged. Project Secret Keys are environment-bound and have no expiration date.

Agent integration order

1. Verify Auth SDK login/session/token first.

2. Create SpectraStorageClient with projectId and auth.

3. If upload fails before Storage API response, verify auth.getSession() and a single auth.getAccessToken({ service: "storage" }) call. Do not put forceRefresh: true in an upload loop unless Platform CS explicitly asks for a one-off diagnostic.

4. Implement uploadFile({ file, path, context?, fileInfo?, metadata? }) for generic files or videos.

5. Implement uploadImage({ file, path? | directory?, context?, fileInfo?, metadata? }) where the UI accepts only image blobs.

6. Persist the returned object reference in Chat/community/review domain records instead of copying binary data into those systems.

7. Implement listFiles().

8. Implement getDownloadUrl() or downloadBlob() depending on the UI need.

9. Implement deleteFile() for user-owned objects only.

Public operations

• listFiles({ prefix?, cursor?, limit? }): list user-root files and prefixes.
• uploadFile({ file, path, contentType?, context?, fileInfo?, metadata?, checksumSha256?, onProgress? }): upload generic file/blob.
• uploadImage({ file, path?, directory?, context?, fileInfo?, metadata?, checksumSha256?, onProgress? }): upload image-only blob.
• uploadFile(fileOrBlob, options) and uploadImage(file, options?): legacy compatible forms. Prefer object input for new apps.
• getDownloadUrl(path): create temporary download URL.
• downloadBlob(path): fetch bytes as Blob.
• deleteFile(path): delete user-root object.

Consumer example

import { SpectraStorageClient } from "@spectra-platform/storage-sdk";

const storage = new SpectraStorageClient({
  projectId,
  auth,
});

const object = await storage.uploadFile({
  file,
  path: "/reviews/photo.jpg",
  visibility: "private",
  context: "review",
  fileInfo: {
    originalName: file.name,
    fingerprint: `${file.name}|${file.size}|${file.type}|${file.lastModified}`,
    lastModified: file.lastModified,
  },
});

const listed = await storage.listFiles({ prefix: "/reviews/" });
const url = await storage.getDownloadUrl(object.objectKey);

Current caveats

• Browser SDK owns user-file operations, not admin bucket policy or quota administration. Server-side Storage management uses a backend-held environment-bound Project ID + Secret Key, and requires the Storage service toggle to be enabled.
• Chat/community/review attachments should store Storage object references.
• fileInfo.originalName may contain non-ASCII names. The SDK sends it as JSON metadata, and Storage API owns signed PUT header-safe encoding.

Unsupported or separate gates

• Admin bucket policy, quota administration, lifecycle policy, and migration jobs are server/Console scope.
• Media transcoding, HLS packaging, and CDN policy are not implied by uploadFile().
• Storage service E2E and provider/object-store health must be verified separately from SDK package API existence.

Escalate to Platform CS when

• The SDK asks for raw S3/MinIO credentials, or asks for a Secret Key in browser/mobile code without an explicit consuming-project architecture decision.
• auth.getSession() is non-null but Storage token issuance returns APP_SESSION_UNAUTHORIZED; include the SDK error requestId.
• Browser upload fails with Failed to construct 'Headers': String contains non ISO-8859-1 code point; include Storage API deploy status and the upload intent response shape.
• Upload succeeds but the returned object reference is unusable by Chat/community/review attachment flows.
• getDownloadUrl() or downloadBlob() requires undocumented internal API calls.
• User-root path behavior differs from this document.