@kentcdodds/dropbox

/**
 * Return metadata for a Dropbox file or folder path. Pick this for a cheap
 * existence/size/rev check without listing or downloading.
 *
 * @param params.path - Dropbox path starting with `/`.
 * @param params.includeDeleted - Include deleted items.
 * @param params.includeMediaInfo - Include media info when Dropbox has it.
 * @param params.includeHasExplicitSharedMembers - Include explicit sharing flag.
 * @returns Dropbox metadata JSON for the path.
 *
 * @example
 * import getMetadata from 'kody:@kentcdodds/dropbox/get-metadata'
 * const metadata = await getMetadata({ path: '/notes/todo.txt' })
 */

import { dropboxRpc } from './request.ts'
import type { JsonRecord } from './types.ts'
import { optionalBoolean, requireDropboxPath, requireRecord } from './types.ts'

export type GetMetadataInput = {
	path: string
	includeDeleted?: boolean
	includeMediaInfo?: boolean
	includeHasExplicitSharedMembers?: boolean
}

/**
 * Return metadata for a Dropbox file or folder path. Pick this for a cheap
 * existence/size/rev check without listing or downloading.
 *
 * @param params.path - Dropbox path starting with `/`.
 * @param params.includeDeleted - Include deleted items.
 * @param params.includeMediaInfo - Include media info when Dropbox has it.
 * @param params.includeHasExplicitSharedMembers - Include explicit sharing flag.
 * @returns Dropbox metadata JSON for the path.
 *
 * @example
 * import getMetadata from 'kody:@kentcdodds/dropbox/get-metadata'
 * const metadata = await getMetadata({ path: '/notes/todo.txt' })
 */
export async function getMetadata(input: GetMetadataInput): Promise<JsonRecord> {
	const path = requireDropboxPath(input.path)
	return dropboxRpc<JsonRecord>('files/get_metadata', {
		path,
		include_deleted: optionalBoolean(input.includeDeleted, 'includeDeleted') ?? false,
		include_media_info: optionalBoolean(input.includeMediaInfo, 'includeMediaInfo') ?? false,
		include_has_explicit_shared_members:
			optionalBoolean(
				input.includeHasExplicitSharedMembers,
				'includeHasExplicitSharedMembers',
			) ?? false,
	})
}

/**
 * Return metadata for a Dropbox file or folder path.
 * @example
 * import getMetadata from 'kody:@kentcdodds/dropbox/get-metadata'
 * const metadata = await getMetadata({ path: '/notes/todo.txt' })
 */
export default async function getMetadataEntrypoint(
	params: Partial<GetMetadataInput> & Record<string, unknown> = {},
) {
	const input = requireRecord(params, 'get-metadata')
	requireDropboxPath(input.path)
	return getMetadata(input as unknown as GetMetadataInput)
}