StorageService
@blobs/sdk / services / StorageService
Defined in: services/StorageService.ts:38
Manages user-owned and organization-owned storage provider configurations (S3, GCS, local FS, OAuth-based providers like Google Drive). The “current” provider returned by getCurrent is what MediaService uses server-side to route file uploads/downloads.
Provider resolution precedence (decided server-side):
- Organization provider (when the user belongs to an org).
- User provider (when
STORAGE_ALLOW_USER_OVERRIDE=true). - System ENV-configured provider.
Example
const sdk = createSDK({ networks: [...] });const res = await sdk.storage.list();Constructors
Constructor
new StorageService(
context):StorageService
Defined in: services/StorageService.ts:46
Constructs a StorageService bound to the given context.
Parameters
context
Shared BlobsContext providing transport and cache.
Returns
StorageService
Methods
create()
create(
input,options?):Promise<Response<StorageProvider>>
Defined in: services/StorageService.ts:78
Creates a new storage provider configuration for the current user (or organization
when the input includes org_id).
Parameters
input
CreateStorageProviderInput describing the provider type and credentials.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<StorageProvider>>
A Response containing the created StorageProvider.
Throws
ValidationError when input is rejected (e.g. invalid credentials shape).
get()
get(
id,options?):Promise<Response<StorageProvider>>
Defined in: services/StorageService.ts:98
Fetches a storage provider configuration by ID, served from cache when available.
Parameters
id
string
The storage provider identifier.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<StorageProvider>>
A Response containing the StorageProvider record.
Throws
NotFoundError when no provider with the given ID exists.
list()
list(
organizationId?,options?):Promise<Response<ListProvidersResponse>>
Defined in: services/StorageService.ts:125
Lists storage provider configurations, scoped to either an organization or the current user.
Parameters
organizationId?
string
When provided, lists organization-owned providers; otherwise lists user-owned providers.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<ListProvidersResponse>>
A Response containing the ListProvidersResponse payload.
getCurrent()
getCurrent(
organizationId?,options?):Promise<Response<StorageProvider>>
Defined in: services/StorageService.ts:149
Returns the storage provider currently active for the user (or organization when organizationId
is provided). The backend resolves precedence in order: organization → user → system ENV.
This is the runtime bridge MediaService uses to route file operations.
Parameters
organizationId?
string
When provided, resolves the organization’s active provider.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<StorageProvider>>
A Response containing the active StorageProvider.
update()
update(
id,input,options?):Promise<Response<StorageProvider>>
Defined in: services/StorageService.ts:174
Updates a storage provider configuration and invalidates its cache entry.
Parameters
id
string
The storage provider identifier.
input
Partial fields to update.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<StorageProvider>>
A Response containing the updated StorageProvider.
Throws
NotFoundError when no provider with the given ID exists.
Throws
PermissionError when the user lacks write access.
delete()
delete(
id,options?):Promise<Response<{message:string; }>>
Defined in: services/StorageService.ts:203
Deletes a storage provider configuration and clears its cache entry.
Parameters
id
string
The storage provider identifier.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<{ message: string; }>>
A Response containing a { message } confirmation payload.
Throws
NotFoundError when no provider with the given ID exists.
Throws
PermissionError when the user lacks delete access.
testConnection()
testConnection(
id,options?):Promise<Response<{success:boolean;message?:string;error?:string; }>>
Defined in: services/StorageService.ts:227
Verifies that a storage provider’s credentials can authenticate against its backend (e.g. a bucket exists and is reachable). Useful for validating provider config after creation.
Parameters
id
string
The storage provider identifier.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<{ success: boolean; message?: string; error?: string; }>>
A Response containing { success, message?, error? } describing the connection result.
getUsage()
getUsage(
id,options?):Promise<Response<StorageUsageInfo>>
Defined in: services/StorageService.ts:253
Returns usage statistics (total bytes, file count, quota) for a storage provider.
Parameters
id
string
The storage provider identifier.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<StorageUsageInfo>>
A Response containing the StorageUsageInfo payload.
initiateOAuth()
initiateOAuth(
providerType,input?,options?):Promise<Response<InitiateOAuthResponse>>
Defined in: services/StorageService.ts:274
Initiates an OAuth authorization flow for an OAuth-based storage provider (e.g. Google Drive, Dropbox, OneDrive). The returned URL should be opened in a popup or redirected to so the user can grant permissions; the server completes the exchange via its callback endpoint.
Parameters
providerType
string
Vendor slug (e.g. google_drive, dropbox, onedrive).
input?
Optional initiation parameters such as a return URL or requested scopes.
options?
Optional network/tenant scoping options.
Returns
Promise<Response<InitiateOAuthResponse>>
A Response containing the InitiateOAuthResponse with oauth_url and state.