basalt / drives/src / Drives
Class: Drives
Defined in: drives/src/drives.ts:171
The application-facing facade.
Every method resolves the tenant the same way @basaltkit/files does, and for the same reason: an ambient tenant in the ALS context always wins, an explicit tenantId is honoured only when it agrees or when there is no context tenant at all (jobs, CLI). A route that forwards ?tenantId= from the client therefore cannot read another tenant's connections — it gets DriveTenantMismatchError.
Constructors
Constructor
> new Drives(options, tenancyActive?): Drives
Defined in: drives/src/drives.ts:184
Parameters
options
tenancyActive?
() => boolean
Whether @basaltkit/tenancy is registered. Wired by drivesPlugin to the container's 'tenancy:active' marker — a signal, not an import, so this package never depends on the tenancy layer.
Returns
Drives
Methods
completeAuthorization()
> completeAuthorization(input): Promise<DriveConnectionView>
Defined in: drives/src/drives.ts:309
Step 2: verify the callback, exchange the code, store the connection.
A tenant may complete this many times for the same provider — each call creates a new connection with its own label, credentials and cursor. That is the "Drive Finance" / "Drive HR" requirement, and it falls out of the model rather than being a special case.
Parameters
input
binding
string | undefined
code
string
label
string
provider
string
redirectUri
string
rootId?
string
state
string | undefined
tenantId?
string
Returns
Promise<DriveConnectionView>
connect()
> connect(input): Promise<DriveConnectionView>
Defined in: drives/src/drives.ts:353
Stores a connection from tokens the app already holds.
Separate from completeAuthorization so a service-account or device-code flow — which some tenants require, and which has no browser redirect at all — can still produce a connection.
Parameters
input
Returns
Promise<DriveConnectionView>
disconnect()
> disconnect(connectionId, options?): Promise<void>
Defined in: drives/src/drives.ts:425
Disconnects: revokes at the provider (best effort, on by default), then deletes the row and its credentials.
The dedup ledger is kept. Files already imported under copy still exist in the app's storage and still need their provenance; dropping the ledger would make a re-connect re-import everything as if it were new. forgetImports is the explicit way to ask for the other behaviour.
Parameters
connectionId
string
options?
DisconnectOptions = {}
Returns
Promise<void>
download()
> download(connectionId, item, options?): Promise<DriveContent>
Defined in: drives/src/drives.ts:665
Opens an item's bytes.
The caller must consume or destroy the returned stream. Nothing is buffered here — the stream goes straight into @basaltkit/files, which streams it on into the storage driver's putStream.
Parameters
connectionId
string
item
options?
signal?
AbortSignal
tenantId?
string
Returns
Promise<DriveContent>
forgetImports()
> forgetImports(connectionId, tenantId?): Promise<number>
Defined in: drives/src/drives.ts:483
Drops the dedup ledger for a connection, so a later sync re-imports everything.
Parameters
connectionId
string
tenantId?
string
Returns
Promise<number>
get()
> get(connectionId, tenantId?): Promise<DriveConnectionView>
Defined in: drives/src/drives.ts:403
One connection, or DriveConnectionNotFoundError.
Parameters
connectionId
string
tenantId?
string
Returns
Promise<DriveConnectionView>
getItem()
> getItem(connectionId, externalId, options?): Promise<DriveItem | null>
Defined in: drives/src/drives.ts:645
Metadata for one item.
Parameters
connectionId
string
externalId
string
options?
signal?
AbortSignal
tenantId?
string
Returns
Promise<DriveItem | null>
list()
> list(filter?): Promise<DriveConnectionView[]>
Defined in: drives/src/drives.ts:393
Connections of the current tenant. Credentials are never part of the result.
Parameters
filter?
DriveConnectionListFilter & object = {}
Returns
Promise<DriveConnectionView[]>
listItems()
> listItems(connectionId, options?): Promise<DrivePage<DriveItem>>
Defined in: drives/src/drives.ts:577
One page of a folder listing.
Parameters
connectionId
string
options?
DriveListOptions & object = {}
Returns
Promise<DrivePage<DriveItem>>
providerNames()
> providerNames(): string[]
Defined in: drives/src/drives.ts:225
Registered provider names.
Returns
string[]
startAuthorization()
> startAuthorization(input): DriveAuthorizationStart
Defined in: drives/src/drives.ts:279
Step 1 of connecting: where to send the browser.
The returned binding must go into an HttpOnly cookie and come back at the callback — see DriveAuthorizationStart.binding.
Parameters
input
provider
string
redirectUri
string
scopes?
readonly string[]
tenantId?
string
Returns
upload()
> upload(connectionId, input, options?): Promise<DriveItem>
Defined in: drives/src/drives.ts:672
Writes a file back to the provider, when the adapter supports it.
Parameters
connectionId
string
input
options?
signal?
AbortSignal
tenantId?
string
Returns
Promise<DriveItem>