/** * 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 { 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 { 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 { 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 { 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 { 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 = {}, ) { 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, }) } }