← Public packages
@kody/dropbox
Reusable Dropbox OAuth helpers for account, metadata, search, file transfer, sharing, and generic API requests.
Files
/**
* Low-level Dropbox upload-session helpers (start, append, finish, get-offset)
* for uploads that arrive in pieces across several execute calls or a long
* local run. Each piece goes straight to Dropbox as raw bytes, so a caller can
* resume from any offset. Use the box script `scripts/upload-to-dropbox.mjs`
* for a whole local file; use these helpers when you drive the session yourself.
*
* Writes require `confirm: true`; the entrypoint supports `dryRun: true`.
*
* @example
* import {
* startUploadSession,
* appendUploadSession,
* finishUploadSession,
* } from 'kody:@kody/dropbox/upload-session'
* const { sessionId } = await startUploadSession({ confirm: true })
* const { offset } = await appendUploadSession({ sessionId, offset: 0, bytes, confirm: true })
* const metadata = await finishUploadSession({
* sessionId,
* offset,
* commit: { path: '/Apps/Kody/inbox/file.bin', mode: 'add' },
* confirm: true,
* })
*/
import { createAuthenticatedFetch, credential } from 'kody:runtime'
import { decodeBase64 } from './base64.ts'
import { DROPBOX_CONTENT_ORIGIN, DropboxApiError } from './request.ts'
import type { JsonRecord } from './types.ts'
import {
optionalBoolean,
optionalNumber,
requireDropboxPath,
requireRecord,
requireString,
} from './types.ts'
/** Recommended bytes per append for local execute (16 MiB, a multiple of 4 MiB). */
export const UPLOAD_SESSION_RECOMMENDED_CHUNK_BYTES = 16 * 1024 * 1024
/** Kody gateway ceiling (Dropbox itself allows 150 MiB). */
export const UPLOAD_SESSION_MAX_CHUNK_BYTES = 100 * 1024 * 1024
export type UploadSessionCommit = {
path: string
mode?: 'add' | 'overwrite'
autorename?: boolean
mute?: boolean
strictConflict?: boolean
}
export type UploadSessionCursor = { sessionId: string; offset: number }
type BytesInput = { bytes?: Uint8Array; bytesBase64?: string }
let contentFetch: typeof fetch | null = null
async function getContentFetch(): Promise<typeof fetch> {
if (contentFetch) return contentFetch
try {
const client = await credential('dropbox')
if (client && typeof client.fetch === 'function') {
contentFetch = client.fetch as typeof fetch
return contentFetch
}
} catch {
// Fall back to the integration fetch used by the rest of this package.
}
contentFetch = await createAuthenticatedFetch('dropbox')
return contentFetch
}
/** JSON for the Dropbox-API-Arg header, with non-ASCII escaped as Dropbox requires. */
export function encodeApiArg(apiArg: unknown): string {
return JSON.stringify(apiArg).replace(
/[\u007f-\uffff]/g,
(char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`,
)
}
async function postContent(endpoint: string, apiArg: JsonRecord, bytes: Uint8Array) {
if (bytes.byteLength > UPLOAD_SESSION_MAX_CHUNK_BYTES) throw new Error('Upload body exceeds 100 MiB Kody gateway limit')
const authedFetch = await getContentFetch()
const response = await authedFetch(`${DROPBOX_CONTENT_ORIGIN}/2/${endpoint}`, {
method: 'POST',
headers: {
accept: 'application/json',
'content-type': 'application/octet-stream',
'dropbox-api-arg': encodeApiArg(apiArg),
},
body: bytes as BodyInit,
})
const text = await response.text()
let body: unknown = null
if (text) {
try {
body = JSON.parse(text)
} catch {
body = text
}
}
if (!response.ok) {
throw new DropboxApiError(
`Dropbox API request failed: ${response.status} ${response.statusText} (${endpoint})`,
{
status: response.status,
statusText: response.statusText,
requestId: response.headers.get('x-dropbox-request-id'),
details: body,
retryAfterMs: response.headers.has('retry-after') ? Math.max(0, /^\d+(\.\d+)?$/.test(response.headers.get('retry-after')!) ? Number(response.headers.get('retry-after')) * 1000 : Date.parse(response.headers.get('retry-after')!) - Date.now()) : undefined,
},
)
}
return body
}
function resolveBytes(input: BytesInput, label: string): Uint8Array {
if (input.bytes instanceof Uint8Array) return input.bytes
if (input.bytes !== undefined) throw new Error(`${label}: bytes must be a Uint8Array.`)
if (typeof input.bytesBase64 === 'string') return decodeBase64(input.bytesBase64)
return new Uint8Array(0)
}
function requireConfirm(confirm: unknown, action: string) {
if (confirm !== true) {
throw new Error(
`upload-session ${action} writes to Dropbox. Pass confirm: true only after explicit user approval, or use dryRun: true.`,
)
}
}
function requireOffset(value: unknown): number {
const offset = optionalNumber(value, 'offset') ?? 0
if (!Number.isInteger(offset) || offset < 0) throw new Error('offset must be a non-negative integer.')
return offset
}
function requireSessionId(value: unknown): string {
return requireString(value, 'sessionId')
}
/**
* Read the correct offset from a Dropbox `incorrect_offset` error (409), for
* append (`error.correct_offset`) and finish (`error.lookup_failed.correct_offset`).
* Returns `null` when the error is something else.
*/
export function getCorrectOffsetFromError(error: unknown): number | null {
if (!(error instanceof DropboxApiError) && !(error && typeof error === 'object' && 'details' in error)) {
return null
}
const details = (error as { details?: unknown }).details
const visit = (value: unknown, depth: number): number | null => {
if (!value || typeof value !== 'object' || depth > 4) return null
const record = value as JsonRecord
if (record['.tag'] === 'incorrect_offset' && typeof record.correct_offset === 'number') {
return record.correct_offset
}
for (const key of ['error', 'lookup_failed']) {
const found = visit(record[key], depth + 1)
if (found !== null) return found
}
return null
}
return visit(details, 0)
}
/**
* Start an upload session, optionally with the first bytes.
* @returns `{ sessionId, offset }` where `offset` is the number of bytes sent.
*/
export async function startUploadSession(
input: BytesInput & { close?: boolean; confirm?: boolean } = {},
): Promise<UploadSessionCursor> {
requireConfirm(input.confirm, 'start')
const bytes = resolveBytes(input, 'start')
const close = optionalBoolean(input.close, 'close') ?? false
const body = (await postContent('files/upload_session/start', { close }, bytes)) as JsonRecord
const sessionId = typeof body?.session_id === 'string' ? body.session_id : ''
if (!sessionId) throw new Error('upload_session/start did not return session_id.')
return { sessionId, offset: bytes.byteLength }
}
/**
* Append bytes at `offset`. Throws `DropboxApiError` (409) on a wrong offset;
* read the right one with `getCorrectOffsetFromError(error)` or `getUploadSessionOffset`.
* @returns `{ sessionId, offset }` with the next offset to write.
*/
export async function appendUploadSession(
input: BytesInput & { sessionId: string; offset: number; close?: boolean; confirm?: boolean },
): Promise<UploadSessionCursor> {
requireConfirm(input.confirm, 'append')
const sessionId = requireSessionId(input.sessionId)
let offset = requireOffset(input.offset)
const bytes = resolveBytes(input, 'append')
const close = optionalBoolean(input.close, 'close') ?? false
await postContent('files/upload_session/append_v2', { cursor: { session_id: sessionId, offset }, close }, bytes)
offset += bytes.byteLength
return { sessionId, offset }
}
/**
* Ask Dropbox how many bytes the session holds. Sends an empty append at the
* guessed offset (default 0): success means the guess is right, a 409
* `incorrect_offset` carries the right value. Never changes stored bytes.
*/
export async function getUploadSessionOffset(input: {
sessionId: string
offset?: number
}): Promise<UploadSessionCursor> {
const sessionId = requireSessionId(input.sessionId)
const guess = requireOffset(input.offset ?? 0)
try {
await postContent(
'files/upload_session/append_v2',
{ cursor: { session_id: sessionId, offset: guess }, close: false },
new Uint8Array(0),
)
return { sessionId, offset: guess }
} catch (error) {
const correct = getCorrectOffsetFromError(error)
if (correct === null) throw error
return { sessionId, offset: correct }
}
}
function buildCommit(commit: UploadSessionCommit): JsonRecord {
const record = requireRecord(commit, 'commit')
const path = requireDropboxPath(record.path, 'commit.path')
const mode = record.mode ?? 'add'
if (mode !== 'add' && mode !== 'overwrite') throw new Error('commit.mode must be "add" or "overwrite".')
return {
path,
mode,
autorename: optionalBoolean(record.autorename, 'commit.autorename') ?? false,
mute: optionalBoolean(record.mute, 'commit.mute') ?? false,
strict_conflict: optionalBoolean(record.strictConflict, 'commit.strictConflict') ?? false,
}
}
/**
* Finish the session with optional last bytes and commit it to `commit.path`.
* `offset` is the total bytes already appended (before these last bytes).
* @returns Dropbox file metadata (`size`, `content_hash`, `path_display`, `rev`, ...).
*/
export async function finishUploadSession(
input: BytesInput & {
sessionId: string
offset: number
commit: UploadSessionCommit
confirm?: boolean
},
): Promise<JsonRecord> {
requireConfirm(input.confirm, 'finish')
const sessionId = requireSessionId(input.sessionId)
const offset = requireOffset(input.offset)
const commit = buildCommit(input.commit)
const bytes = resolveBytes(input, 'finish')
const body = await postContent(
'files/upload_session/finish',
{ cursor: { session_id: sessionId, offset }, commit },
bytes,
)
return requireRecord(body, 'upload_session/finish response')
}
type UploadSessionAction = 'start' | 'append' | 'finish' | 'get-offset'
/**
* Drive one upload-session step per call (handy from hosted execute, where a
* request body is capped near 4 MB, so keep each `bytesBase64` under ~2.5 MiB).
*
* @param params.action - `start`, `append`, `finish`, or `get-offset`.
* @param params.sessionId - Session id from `start` (append, finish, get-offset).
* @param params.offset - Bytes already in the session (append, finish; a guess for get-offset).
* @param params.bytesBase64 - Bytes for this step, in params (never in code).
* @param params.commit - `{ path, mode?, autorename?, mute? }` for finish.
* @param params.confirm - Required `true` for start, append, and finish.
* @param params.dryRun - Return the planned step without calling Dropbox.
* @returns start/append/get-offset: `{ sessionId, offset }` (next offset); finish: file metadata.
*
* @example
* import uploadSession from 'kody:@kody/dropbox/upload-session'
* const next = await uploadSession({
* action: 'append',
* sessionId: params.sessionId,
* offset: params.offset,
* bytesBase64: params.bytesBase64,
* confirm: true,
* })
*/
export default async function uploadSessionEntrypoint(
params: Record<string, unknown> = {},
) {
const input = requireRecord(params, 'upload-session')
const action = input.action as UploadSessionAction
if (!['start', 'append', 'finish', 'get-offset'].includes(action)) {
throw new Error('action must be "start", "append", "finish", or "get-offset".')
}
const bytesBase64 =
input.bytesBase64 === undefined
? undefined
: requireString(input.bytesBase64, 'bytesBase64', { allowEmpty: true })
if (input.dryRun === true) {
return {
dryRun: true,
action,
sessionId: input.sessionId ?? null,
offset: input.offset ?? null,
byteLength: bytesBase64 === undefined ? 0 : decodeBase64(bytesBase64).byteLength,
commit: action === 'finish' ? buildCommit(input.commit as UploadSessionCommit) : null,
authorization: '[managed dropbox OAuth integration]',
}
}
switch (action) {
case 'start':
return startUploadSession({ bytesBase64, close: input.close as boolean | undefined, confirm: input.confirm as boolean })
case 'append':
return appendUploadSession({
sessionId: input.sessionId as string,
offset: input.offset as number,
bytesBase64,
close: input.close as boolean | undefined,
confirm: input.confirm as boolean,
})
case 'finish':
return finishUploadSession({
sessionId: input.sessionId as string,
offset: input.offset as number,
bytesBase64,
commit: input.commit as UploadSessionCommit,
confirm: input.confirm as boolean,
})
case 'get-offset':
return getUploadSessionOffset({
sessionId: input.sessionId as string,
offset: input.offset as number | undefined,
})
}
}