@inrupt/solid-client/dist/resource/file.d.ts

Make your web apps work with Solid Pods.

/**
 * Copyright 2020 Inrupt Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
 * Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
/// <reference types="node" />
import { File, WithResourceInfo, Url, UrlString, WithServerResourceInfo } from "../interfaces";
/**
 * Options when fetching a file from a Pod.
 *
 * Available options:
 * - `fetch`: A custom `fetch` function with the same signature as
 *   [`window.fetch`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch).
 *   This will be used to execute the actual requests. This option can be used to, for example,
 *   attach credentials to requests that need authentication.
 */
export declare type GetFileOptions = {
    fetch: typeof window.fetch;
};
/**
 * ```{note} This function is still experimental and subject to change, even in a non-major release.
 * ```
 *
 * Retrieves a file from a URL and returns the file as a blob.
 *
 * @param url The URL of the file to return
 * @param options Fetching options: a custom fetcher and/or headers.
 * @returns The file as a blob.
 */
export declare function getFile(input: Url | UrlString, options?: Partial<GetFileOptions>): Promise<File & WithServerResourceInfo>;
/**
 * ```{note} This function is still experimental and subject to change, even in a non-major release.
 * ```
 * Deletes a file at a given URL.
 *
 * @param file The URL of the file to delete
 */
export declare function deleteFile(file: Url | UrlString | WithResourceInfo, options?: Partial<GetFileOptions>): Promise<void>;
/**
 * ```{note} This type is still experimental and subject to change, even in a
 * non-major release.
 * ```
 * Options available when saving a file (extends the options available when
 * writing a file: [[WriteFileOptions]]).
 *
 */
declare type SaveFileOptions = WriteFileOptions & {
    /**
     * This option can be used as a hint to the server in how to name a new file.
     * Note: the server is still free to choose a completely different, unrelated
     * name if it chooses.
     */
    slug?: string;
};
/**
 * ```{note} This function is still experimental and subject to change, even in a non-major release.
 * ```
 *
 * Saves a file in a folder associated with the given URL. The final filename may or may
 * not be the given `slug`.
 *
 * If you know the [media type](https://developer.mozilla.org/en-US/docs/Glossary/MIME_type)
 * of the file you are attempting to save, then you should provide this in the
 * `options` parameter. For example, if you know your file is a JPEG image,
 * then you should provide the media type `image/jpeg`. If you don't know, or
 * don't provide a media type, a default type of `application/octet-stream` will
 * be applied (which indicates that the file should be regarded as pure binary
 * data).
 *
 * The Container at the given URL should already exist; if it does not, the returned Promise will
 * be rejected. You can initialise it first using [[createContainerAt]], or directly save the file
 * at the desired location using [[overwriteFile]].
 *
 * This function is primarily useful if the current user does not have access to change existing files in
 * a Container, but is allowed to add new files; in other words, they have Append, but not Write
 * access to a Container. This is useful in situations where someone wants to allow others to,
 * for example, send notifications to their Pod, but not to view or delete existing notifications.
 * You can pass a suggestion for the new Resource's name, but the server may decide to give it
 * another name — for example, if a Resource with that name already exists inside the given
 * Container.
 * If the user does have access to write directly to a given location, [[overwriteFile]]
 * will do the job just fine, and does not require the parent Container to exist in advance.
 *
 * @param folderUrl The URL of the folder where the new file is saved.
 * @param file The file to be written.
 * @param options Additional parameters for file creation (e.g. a slug).
 * @returns A Promise that resolves to the saved file, if available, or `null` if the current user does not have Read access to the newly-saved file. It rejects if saving fails.
 */
export declare function saveFileInContainer<FileExt extends File | Buffer>(folderUrl: Url | UrlString, file: FileExt, options?: Partial<SaveFileOptions>): Promise<FileExt & WithResourceInfo>;
/**
 * ```{note} This function is still experimental and subject to change, even in a non-major release.
 * ```
 *
 * Options available when writing a file.
 */
export declare type WriteFileOptions = GetFileOptions & {
    /**
     * Allows a file's content type to be provided explicitly, if known. Value is
     * expected to be a valid
     * [media type](https://developer.mozilla.org/en-US/docs/Glossary/MIME_type).
     * For example, if you know your file is a JPEG image, then you should provide
     * the media type `image/jpeg`. If you don't know, or don't provide a media
     * type, a default type of `application/octet-stream` will be applied (which
     * indicates that the file should be regarded as pure binary data).
     */
    contentType: string;
};
/**
 * ```{note} This function is still experimental and subject to change, even in a non-major release.
 * ```
 *
 * Saves a file at a given URL, replacing any previous content.
 *
 * The Solid server will create any intermediary Containers that do not exist yet, so they do not
 * need to be created in advance. For example, if the target URL is
 * https://example.pod/container/resource and https://example.pod/container/ does not exist yet,
 * it will exist after this function resolves successfully.
 *
 * If you know the [media type](https://developer.mozilla.org/en-US/docs/Glossary/MIME_type)
 * of the file you are attempting to write, then you should provide this in the
 * `options` parameter. For example, if you know your file is a JPEG image,
 * then you should provide the media type `image/jpeg`. If you don't know, or
 * don't provide a media type, a default type of `application/octet-stream` will
 * be applied (which indicates that the file should be regarded as pure binary
 * data).
 *
 * @param fileUrl The URL where the file is saved.
 * @param file The file to be written.
 * @param options Additional parameters for file creation (e.g. a slug, or media type).
 */
export declare function overwriteFile<FileExt extends File | Buffer>(fileUrl: Url | UrlString, file: FileExt, options?: Partial<WriteFileOptions>): Promise<FileExt & WithResourceInfo>;
/**
 * @hidden
 * This function feels unnecessarily complicated, but is required in order to
 * have Headers according to type definitions in both Node and browser environments.
 * This might require a fix upstream to be cleaned up.
 *
 * @param headersToFlatten A structure containing headers potentially in several formats
 */
export declare function flattenHeaders(headersToFlatten: Headers | Record<string, string> | string[][] | undefined): Record<string, string>;
export {};