@prismicio/client/dist/WriteClient.d.ts

The official JavaScript + TypeScript client library for Prismic

import type { PrismicMigrationAsset } from "./types/migration/Asset";
import type { PrismicMigrationDocument } from "./types/migration/Document";
import type { PrismicDocument } from "./types/value/document";
import type { FetchParams } from "./BaseClient";
import { Client } from "./Client";
import type { ClientConfig } from "./Client";
import type { Migration } from "./Migration";
/**
 * Utility type to construct events reported by the migration process.
 */
type MigrateReporterEvent<TType extends string, TData = never> = TData extends never ? {
    type: TType;
} : {
    type: TType;
    data: TData;
};
/**
 * A map of event types and their data reported by the migration process.
 */
type MigrateReporterEventMap = {
    start: {
        pending: {
            documents: number;
            assets: number;
        };
    };
    end: {
        migrated: {
            documents: number;
            assets: number;
        };
    };
    "assets:creating": {
        current: number;
        remaining: number;
        total: number;
        asset: PrismicMigrationAsset;
    };
    "assets:created": {
        created: number;
    };
    "documents:masterLocale": {
        masterLocale: string;
    };
    "documents:creating": {
        current: number;
        remaining: number;
        total: number;
        document: PrismicMigrationDocument;
    };
    "documents:created": {
        created: number;
    };
    "documents:updating": {
        current: number;
        remaining: number;
        total: number;
        document: PrismicMigrationDocument;
    };
    "documents:updated": {
        updated: number;
    };
};
/**
 * Available event types reported by the migration process.
 */
type MigrateReporterEventTypes = keyof MigrateReporterEventMap;
/**
 * All events reported by the migration process. Events can be listened to by
 * providing a `reporter` function to the `migrate` method.
 */
export type MigrateReporterEvents = {
    [K in MigrateReporterEventTypes]: MigrateReporterEvent<K, MigrateReporterEventMap[K]>;
}[MigrateReporterEventTypes];
/**
 * Additional parameters for creating an asset in the Prismic media library.
 */
export type CreateAssetParams = {
    /**
     * Asset notes.
     */
    notes?: string;
    /**
     * Asset credits.
     */
    credits?: string;
    /**
     * Asset alt text.
     */
    alt?: string;
    /**
     * Asset tags.
     */
    tags?: string[];
};
/**
 * Configuration for clients that determine how content is queried.
 */
export type WriteClientConfig = {
    /**
     * A Prismic write token that allows writing content to the repository.
     */
    writeToken: string;
    /**
     * The Prismic Asset API endpoint.
     *
     * @defaultValue `"https://asset-api.prismic.io/"`
     *
     * @see Prismic Asset API technical reference: {@link https://prismic.io/docs/asset-api-technical-reference}
     */
    assetAPIEndpoint?: string;
    /**
     * The Prismic Migration API endpoint.
     *
     * @defaultValue `"https://migration.prismic.io/"`
     *
     * @see Prismic Migration API technical reference: {@link https://prismic.io/docs/migration-api-technical-reference}
     */
    migrationAPIEndpoint?: string;
} & ClientConfig;
/**
 * A client that allows querying and writing content to a Prismic repository.
 *
 * If used in an environment where a global `fetch` function is unavailable,
 * such as Node.js, the `fetch` option must be provided as part of the `options`
 * parameter.
 *
 * @typeParam TDocuments - Document types that are registered for the Prismic
 *   repository. Query methods will automatically be typed based on this type.
 */
export declare class WriteClient<TDocuments extends PrismicDocument = PrismicDocument> extends Client<TDocuments> {
    writeToken: string;
    assetAPIEndpoint: string;
    migrationAPIEndpoint: string;
    /**
     * Creates a Prismic client that can be used to query and write content to a
     * repository.
     *
     * If used in an environment where a global `fetch` function is unavailable,
     * such as in some Node.js versions, the `fetch` option must be provided as
     * part of the `options` parameter.
     *
     * @param repositoryName - The Prismic repository name for the repository.
     * @param options - Configuration that determines how content will be queried
     *   from and written to the Prismic repository.
     *
     * @returns A client that can query and write content to the repository.
     */
    constructor(repositoryName: string, options: WriteClientConfig);
    /**
     * Creates a migration release on the Prismic repository based on the provided
     * prepared migration.
     *
     * @param migration - A migration prepared with {@link createMigration}.
     * @param params - An event listener and additional fetch parameters.
     *
     * @see Prismic Migration API technical reference: {@link https://prismic.io/docs/migration-api-technical-reference}
     */
    migrate(migration: Migration<TDocuments>, params?: {
        reporter?: (event: MigrateReporterEvents) => void;
    } & FetchParams): Promise<void>;
    /**
     * Creates assets in the Prismic repository's media library.
     *
     * @param migration - A migration prepared with {@link createMigration}.
     * @param params - An event listener and additional fetch parameters.
     *
     * @internal This method is one of the step performed by the {@link migrate} method.
     */
    private migrateCreateAssets;
    /**
     * Creates documents in the Prismic repository's migration release.
     *
     * @param migration - A migration prepared with {@link createMigration}.
     * @param params - An event listener and additional fetch parameters.
     *
     * @internal This method is one of the step performed by the {@link migrate} method.
     */
    private migrateCreateDocuments;
    /**
     * Updates documents in the Prismic repository's migration release with their
     * patched data.
     *
     * @param migration - A migration prepared with {@link createMigration}.
     * @param params - An event listener and additional fetch parameters.
     *
     * @internal This method is one of the step performed by the {@link migrate} method.
     */
    private migrateUpdateDocuments;
    /**
     * Creates an asset in the Prismic media library.
     *
     * @param file - The file to upload as an asset.
     * @param filename - The filename of the asset.
     * @param params - Additional asset data and fetch parameters.
     *
     * @returns The created asset.
     */
    private createAsset;
    /**
     * Updates an asset in the Prismic media library.
     *
     * @param id - The ID of the asset to update.
     * @param params - The asset data to update and additional fetch parameters.
     *
     * @returns The updated asset.
     */
    private updateAsset;
    /**
     * Fetches a foreign asset from a URL.
     *
     * @param url - The URL of the asset to fetch.
     * @param params - Additional fetch parameters.
     *
     * @returns A file representing the fetched asset.
     */
    private fetchForeignAsset;
    /**
     * {@link resolveAssetTagIDs} rate limiter.
     */
    private _resolveAssetTagIDsLimit;
    /**
     * Resolves asset tag IDs from tag names.
     *
     * @param tagNames - An array of tag names to resolve.
     * @param params - Whether or not missing tags should be created and
     *   additional fetch parameters.
     *
     * @returns An array of resolved tag IDs.
     */
    private resolveAssetTagIDs;
    /**
     * Creates a tag in the Asset API.
     *
     * @remarks
     * Tags should be at least 3 characters long and 20 characters at most.
     *
     * @param name - The name of the tag to create.
     * @param params - Additional fetch parameters.
     *
     * @returns The created tag.
     */
    private createAssetTag;
    /**
     * Queries existing tags from the Asset API.
     *
     * @param params - Additional fetch parameters.
     *
     * @returns An array of existing tags.
     */
    private getAssetTags;
    /**
     * Creates a document in the repository's migration release.
     *
     * @typeParam TType - Type of Prismic documents to create.
     *
     * @param document - The document to create.
     * @param documentTitle - The title of the document to create which will be
     *   displayed in the editor.
     * @param params - Document master language document ID and additional fetch
     *   parameters.
     *
     * @returns The ID of the created document.
     *
     * @see Prismic Migration API technical reference: {@link https://prismic.io/docs/migration-api-technical-reference}
     */
    private createDocument;
    /**
     * Updates an existing document in the repository's migration release.
     *
     * @typeParam TType - Type of Prismic documents to update.
     *
     * @param id - The ID of the document to update.
     * @param document - The document content to update.
     * @param params - Additional fetch parameters.
     *
     * @see Prismic Migration API technical reference: {@link https://prismic.io/docs/migration-api-technical-reference}
     */
    private updateDocument;
    /**
     * Builds fetch parameters for the Asset API.
     *
     * @typeParam TBody - Type of the body to send in the fetch request.
     *
     * @param params - Method, body, and additional fetch parameters.
     *
     * @returns An object that can be fetched to interact with the Asset API.
     *
     * @see Prismic Asset API technical reference: {@link https://prismic.io/docs/asset-api-technical-reference}
     */
    private buildAssetAPIQueryParams;
    /**
     * Builds fetch parameters for the Migration API.
     *
     * @typeParam TBody - Type of the body to send in the fetch request.
     *
     * @param params - Method, body, and additional fetch options.
     *
     * @returns An object that can be fetched to interact with the Migration API.
     *
     * @see Prismic Migration API technical reference: {@link https://prismic.io/docs/migration-api-technical-reference}
     */
    private buildMigrationAPIQueryParams;
}
export {};