@jitl/notion-api/src/lib/assets.d.ts

The missing companion library for the official Notion public API.

import { NotionClient, Page, PropertyPointer } from '..';
import { CacheBehavior, NotionObjectIndex } from './cache';
/**
 * An internal, external or emoji asset from the Notion API.
 * @category Asset
 */
export declare type Asset = NonNullable<Page['icon']>;
/**
 * An AssetRequest indicates an asset within a Notion API object,
 * such as a page icon or a image block's image.
 * @category Asset
 * @source
 */
export declare type AssetRequest = {
    object: 'page';
    id: string;
    field: 'icon';
} | {
    object: 'page';
    id: string;
    field: 'cover';
} | {
    object: 'page';
    id: string;
    field: 'properties';
    property: PropertyPointer<any>;
    propertyIndex?: number;
} | {
    object: 'block';
    id: string;
    field: 'image';
} | {
    object: 'block';
    id: string;
    field: 'file';
} | {
    object: 'block';
    id: string;
    field: 'icon';
} | {
    object: 'user';
    id: string;
    field: 'avatar_url';
};
/**
 * Get a unique string key for de-duplicating [[AssetRequest]]s
 * @category Asset
 */
export declare function getAssetRequestKey(assetRequest: AssetRequest): string;
/**
 * Build a URL to GET an asset.
 * @param baseUrl The base URL where the asset request handler is mounted (ending with a /), eg `https://mydomain.com/api/notion-assets/`.
 * @category Asset
 */
export declare function getAssetRequestUrl(assetRequest: AssetRequest, baseUrl: URL, last_edited_time: string | undefined): URL;
/**
 * Get an absolute pathname (eg `/api/notion-assets/...`) for the given asset request.
 * @param assetRequest The asset request.
 * @param basePathOrURL Eg `/api/notion-assets/`. A path or URL ending with a '/'.
 * @param last_edited_time The last_edited_time of the object that contains this asset, for immutable caching.
 * @category Asset
 */
export declare function getAssetRequestPathname(assetRequest: AssetRequest, basePathOrURL: string | URL, last_edited_time: string | undefined): string;
/** @category Asset */
export declare const ASSET_REQUEST_QUERY_PATH_PARAM = "asset_request";
/** @category Asset */
export declare const ASSET_REQUEST_LAST_EDITED_TIME_PARAM = "last_edited_time";
interface NextJSQuery {
    [key: string]: string | string[];
}
/**
 * @category Asset
 */
export interface AssetRequestNextJSQuery extends NextJSQuery {
    [ASSET_REQUEST_QUERY_PATH_PARAM]: [object: string, id: string, field: string];
}
/**
 * The result of parsing an [[AssetRequest]] that was encoded as a URL or
 * partially parsed as a NextJS query object.
 *
 * Encoded AssetRequests optionally contain a `last_edited_time`, which is used
 * for freshness and cache busting.
 *
 * @category Asset
 */
export interface ParsedAssetRequest {
    assetRequest: AssetRequest;
    [ASSET_REQUEST_LAST_EDITED_TIME_PARAM]: string | undefined;
}
/**
 * Parse an AssetRequest from a NextJS-style query object.
 * @category Asset
 */
export declare function parseAssetRequestQuery(query: AssetRequestNextJSQuery | NextJSQuery): ParsedAssetRequest;
/**
 * Inverse of [[getAssetRequestUrl]].
 * @category Asset
 */
export declare function parseAssetRequestUrl(assetUrl: URL | string, baseURL: URL): ParsedAssetRequest;
/**
 * Look up an asset from the Notion API.
 * @category Asset
 */
export declare function performAssetRequest(args: {
    notion: NotionClient;
    cache: NotionObjectIndex;
    request: AssetRequest;
}): Promise<Asset | undefined>;
/**
 * @returns a string key unique for the asset, suitable for use in a hashmap, cache, or filename.
 * @category Asset
 */
export declare function getAssetKey(asset: Asset): string;
/**
 * [[Error.name]] of errors thrown by [[ensureImageDownloaded]] when
 * encountering a permission error, eg if the asset is expired.
 * @category Asset
 */
export declare const DOWNLOAD_PERMISSION_ERROR = "DownloadPermissionError";
/**
 * [[Error.name]] of errors thrown by [[ensureImageDownloaded]] when
 * encountering other HTTP error codes.
 * @category Asset
 */
export declare const DOWNLOAD_HTTP_ERROR = "DownloadHTTPError";
/**
 * Download image at `url` to a path in `directory` starting with
 * `filenamePrefix` if it does not exist, or return the existing path on disk
 * that has that prefix.
 *
 * @returns Promise<string> Relative path from `directory` to image on disk.
 * @category Asset
 */
export declare function ensureImageDownloaded(args: {
    url: string;
    filenamePrefix: string;
    directory: string;
    cacheBehavior?: CacheBehavior;
}): Promise<string | undefined>;
/**
 * Copy an emoji image for `emoji` into `directory`.
 * @returns relative path from `directory` to the image.
 * @category Asset
 */
export declare function ensureEmojiCopied(args: {
    emoji: string;
    directory: string;
    filenamePrefix: string;
    /**
     * Path to directory containing emoji images.
     * The directory should have contents like this:
     * https://github.com/iamcal/emoji-data/tree/1ddc9ca67c1379c372b4ca39824659f71caa2825/img-apple-160
     *
     * If undefined, this path will be looked up using
     * `require.resolve('emoji-datasource-apple')`, or fall back to
     * `${process.cwd()}/node_modules/emoji-datasource-apple/img/apple/64`.
     */
    emojiSourceDirectory?: string;
    cacheBehavior?: CacheBehavior;
}): Promise<string | undefined>;
/**
 * Ensure `asset` is present on disk in `directory`.
 * @returns Relative path from `directory` to the asset on disk, or undefined.
 * @category Asset
 */
export declare function ensureAssetInDirectory(args: {
    asset: Asset;
    directory: string;
    /**
     * See {@link ensureEmojiCopied}
     */
    emojiSourceDirectory?: string;
    cacheBehavior?: CacheBehavior;
}): Promise<string | undefined>;
export {};