/**
 * Create a shared link for a Dropbox file or folder. Pick this instead of
 * `./request` when you already know the path and want the sharing endpoint.
 * Requires `confirm: true`; use `dryRun: true` to preview the request.
 *
 * @param params.path - Dropbox path starting with `/`.
 * @param params.settings - Optional shared-link settings object.
 * @param params.confirm - Required `true` to perform the mutating call.
 * @param params.dryRun - When true, return the planned request without calling Dropbox.
 * @returns Dropbox sharing result, or a dry-run preview.
 *
 * @example
 * import createSharedLink from 'kody:@kentcdodds/dropbox/create-shared-link'
 * const result = await createSharedLink({
 *   path: '/documents/guide.pdf',
 *   confirm: true,
 * })
 */

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

export type CreateSharedLinkInput = {
	path: string
	settings?: JsonRecord
	confirm?: boolean
	dryRun?: boolean
}

/**
 * Create a shared link for a Dropbox file or folder. Pick this instead of
 * `./request` when you already know the path and want the sharing endpoint.
 * Requires `confirm: true`; use `dryRun: true` to preview the request.
 *
 * @param params.path - Dropbox path starting with `/`.
 * @param params.settings - Optional shared-link settings object.
 * @param params.confirm - Required `true` to perform the mutating call.
 * @param params.dryRun - When true, return the planned request without calling Dropbox.
 * @returns Dropbox sharing result, or a dry-run preview.
 *
 * @example
 * import createSharedLink from 'kody:@kentcdodds/dropbox/create-shared-link'
 * const result = await createSharedLink({
 *   path: '/documents/guide.pdf',
 *   confirm: true,
 * })
 */
export async function createSharedLink(
	input: CreateSharedLinkInput,
): Promise<DropboxRequestResult | JsonRecord> {
	const path = requireDropboxPath(input.path)
	if (
		input.settings !== undefined &&
		(!input.settings || typeof input.settings !== 'object' || Array.isArray(input.settings))
	) {
		throw new Error('settings must be an object when provided.')
	}
	return request({
		endpoint: 'sharing/create_shared_link_with_settings',
		body: {
			path,
			...(input.settings ? { settings: input.settings } : {}),
		},
		confirm: input.confirm,
		dryRun: input.dryRun,
	})
}

/**
 * Create a shared link for a Dropbox file or folder.
 * Requires `confirm: true`; use `dryRun: true` to preview the request.
 * @example
 * import createSharedLink from 'kody:@kentcdodds/dropbox/create-shared-link'
 * const result = await createSharedLink({
 *   path: '/documents/guide.pdf',
 *   confirm: true,
 * })
 */
export default async function createSharedLinkEntrypoint(
	params: Partial<CreateSharedLinkInput> & Record<string, unknown> = {},
) {
	const input = requireRecord(params, 'create-shared-link')
	requireDropboxPath(input.path)
	return createSharedLink(input as unknown as CreateSharedLinkInput)
}