@prismicio/client
Version:
The official JavaScript + TypeScript client library for Prismic
704 lines (702 loc) • 23.5 kB
text/typescript
import { PrismicDocument } from "./types/value/document.cjs";
import { LinkResolverFunction } from "./helpers/asLink.cjs";
import { AbortSignalLike, FetchLike, RequestInitLike } from "./lib/request.cjs";
import { Query } from "./types/api/query.cjs";
import { Ref } from "./types/api/ref.cjs";
import { Repository } from "./types/api/repository.cjs";
import { BuildQueryURLArgs } from "./buildQueryURL.cjs";
//#region src/Client.d.ts
/**
* Extracts a document type with a matching `type` property from a union of
* document types.
*/
type ExtractDocumentType<TDocuments extends PrismicDocument, TDocumentType extends TDocuments["type"]> = Extract<TDocuments, {
type: TDocumentType;
}> extends never ? TDocuments : Extract<TDocuments, {
type: TDocumentType;
}>;
/**
* The minimum required properties to treat as an HTTP Request for automatic
* Prismic preview support.
*/
type HttpRequestLike =
// Web API Request
{
headers?: {
get(name: string): string | null;
};
url?: string;
} | {
headers?: {
cookie?: string;
};
query?: Record<string, unknown>;
};
/**
* A function that returns a ref string. Used to configure which ref the client
* queries content from.
*/
type GetRef = (params?: Pick<BuildQueryURLArgs, "accessToken"> & FetchParams) => string | undefined | Promise<string | undefined>;
/** Parameters for client methods that use `fetch()`. */
type FetchParams = {
/**
* Options provided to the client's `fetch()` on all network requests. These
* options will be merged with internally required options. They can also be
* overriden on a per-query basis using the query's `fetchOptions` parameter.
*/
fetchOptions?: RequestInitLike;
/** @deprecated Move to `fetchOptions.signal`: */
signal?: AbortSignalLike;
};
/** Prismic client configuration. */
type ClientConfig = {
/**
* The client's Content API endpoint.
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
documentAPIEndpoint?: string;
/**
* The secure token used for the Content API.
*
* @see {@link https://prismic.io/docs/fetch-content#content-visibility}
*/
accessToken?: string;
/**
* The version of the repository's content. It can optionally be a function
* that returns a ref.
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
ref?: string | GetRef;
/**
* A list of route resolver objects that define how a document's `url`
* property is resolved.
*
* @see {@link https://prismic.io/docs/routes}
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
routes?: NonNullable<BuildQueryURLArgs["routes"]>;
/**
* The URL used for link or content relationship fields that point to an
* archived or deleted page.
*
* @see {@link https://prismic.io/docs/routes}
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
brokenRoute?: NonNullable<BuildQueryURLArgs["brokenRoute"]>;
/**
* Default parameters sent with each Content API request. These parameters can
* be overridden on each method.
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
defaultParams?: Omit<BuildQueryURLArgs, "ref" | "integrationFieldsRef" | "accessToken" | "routes" | "brokenRoute">;
/**
* The `fetch` function used to make network requests.
*
* @default The global `fetch` function.
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
fetch?: FetchLike;
/**
* The default `fetch` options sent with each Content API request. These
* parameters can be overriden on each method.
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
fetchOptions?: RequestInitLike;
};
/**
* Parameters specific to client methods that fetch all documents. These methods
* start with `getAll` (e.g. `getAllByType`).
*/
type GetAllParams = {
/**
* Limit the number of documents queried.
*
* @default No limit.
*/
limit?: number;
};
/**
* A client for fetching content from a Prismic repository.
*
* @see {@link https://prismic.io/docs/fetch-content}
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client}
*/
declare class Client<TDocuments extends PrismicDocument = PrismicDocument> {
#private;
/**
* The client's Content API endpoint.
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
documentAPIEndpoint: string;
/**
* The secure token used for the Content API.
*
* @see {@link https://prismic.io/docs/fetch-content#content-visibility}
*/
accessToken?: string;
/**
* A list of route resolver objects that define how a document's `url`
* property is resolved.
*
* @see {@link https://prismic.io/docs/routes}
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
routes?: NonNullable<BuildQueryURLArgs["routes"]>;
/**
* The URL used for link or content relationship fields that point to an
* archived or deleted page.
*
* @see {@link https://prismic.io/docs/routes}
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
brokenRoute?: NonNullable<BuildQueryURLArgs["brokenRoute"]>;
/**
* Default parameters sent with each Content API request. These parameters can
* be overridden on each method.
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
defaultParams?: Omit<BuildQueryURLArgs, "ref" | "integrationFieldsRef" | "accessToken" | "routes">;
/**
* The `fetch` function used to make network requests.
*
* @default The global `fetch` function.
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
fetchFn: FetchLike;
/**
* The default `fetch` options sent with each Content API request. These
* parameters can be overriden on each method.
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#config-options}
*/
fetchOptions: RequestInitLike;
/**
* @param repositoryNameOrEndpoint - The Prismic repository name or full
* Content API endpoint for the repository.
* @param config - Client configuration.
*/
constructor(repositoryNameOrEndpoint: string, config?: ClientConfig);
/** The Prismic repository's name. */
set repositoryName(value: string);
/** The Prismic repository's name. */
get repositoryName(): string;
/** @deprecated Replace with `documentAPIEndpoint`. */
set endpoint(value: string);
/** @deprecated Replace with `documentAPIEndpoint`. */
get endpoint(): string;
/**
* Enables the client to automatically query content from a preview session.
*
* @example
*
* ```ts
* client.enableAutoPreviews()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#enableautopreviews}
*/
enableAutoPreviews(): void;
/**
* Enables the client to automatically query content from a preview session
* using an HTTP request object.
*
* @example
*
* ```ts
* client.enableAutoPreviewsFromReq(req)
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#enableautopreviewsfromreq}
*/
enableAutoPreviewsFromReq(request: HttpRequestLike): void;
/**
* Disables the client from automatically querying content from a preview
* session.
*
* @example
*
* ```ts
* client.disableAutoPreviews()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#disableautopreviews}
*/
disableAutoPreviews(): void;
/**
* Fetches pages based on the `params` argument. Results are paginated.
*
* @example
*
* ```ts
* const response = await client.get({ pageSize: 10 })
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#get}
*/
get<TDocument extends TDocuments>(params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<Query<TDocument>>;
/**
* Fetches the first page returned based on the `params` argument.
*
* @example
*
* ```ts
* const page = await client.getFirst()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getfirst}
*/
getFirst<TDocument extends TDocuments>(params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<TDocument>;
/**
* Fetches all pages based on the `params` argument. This method may make
* multiple network requests to fetch all matching pages.
*
* @example
*
* ```ts
* const pages = await client.dangerouslyGetAll()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#dangerouslygetall}
*/
dangerouslyGetAll<TDocument extends TDocuments>(params?: Partial<Omit<BuildQueryURLArgs, "page">> & GetAllParams & FetchParams): Promise<TDocument[]>;
/**
* Fetches a page with a specific ID.
*
* @example
*
* ```ts
* const page = await client.getByID("WW4bKScAAMAqmluX")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getbyid}
*/
getByID<TDocument extends TDocuments>(id: string, params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<TDocument>;
/**
* Fetches pages with specific IDs. Results are paginated.
*
* @example
*
* ```ts
* const response = await client.getByIDs([
* "WW4bKScAAMAqmluX",
* "U1kTRgEAAC8A5ldS",
* ])
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getbyids}
*/
getByIDs<TDocument extends TDocuments>(ids: string[], params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<Query<TDocument>>;
/**
* Fetches pages with specific IDs. This method may make multiple network
* requests to fetch all matching pages.
*
* @example
*
* ```ts
* const pages = await client.getAllByIDs([
* "WW4bKScAAMAqmluX",
* "U1kTRgEAAC8A5ldS",
* ])
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getallbyids}
*/
getAllByIDs<TDocument extends TDocuments>(ids: string[], params?: Partial<Omit<BuildQueryURLArgs, "page">> & GetAllParams & FetchParams): Promise<TDocument[]>;
/**
* Fetches a page with a specific UID and type.
*
* @example
*
* ```ts
* const page = await client.getByUID("blog_post", "my-first-post")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getbyuid}
*/
getByUID<TDocument extends TDocuments, TDocumentType extends TDocument["type"] = TDocument["type"]>(documentType: TDocumentType, uid: string, params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<ExtractDocumentType<TDocument, TDocumentType>>;
/**
* Fetches pages with specific UIDs and a specific type. Results are
* paginated.
*
* @example
*
* ```ts
* const response = await client.getByUIDs("blog_post", [
* "my-first-post",
* "my-second-post",
* ])
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getbyuids}
*/
getByUIDs<TDocument extends TDocuments, TDocumentType extends TDocument["type"] = TDocument["type"]>(documentType: TDocumentType, uids: string[], params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<Query<ExtractDocumentType<TDocument, TDocumentType>>>;
/**
* Fetches pages with specific UIDs and a specific type. This method may make
* multiple network requests to fetch all matching pages.
*
* @example
*
* ```ts
* const pages = await client.getAllByUIDs("blog_post", [
* "my-first-post",
* "my-second-post",
* ])
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getallbyuids}
*/
getAllByUIDs<TDocument extends TDocuments, TDocumentType extends TDocument["type"] = TDocument["type"]>(documentType: TDocumentType, uids: string[], params?: Partial<Omit<BuildQueryURLArgs, "page">> & GetAllParams & FetchParams): Promise<ExtractDocumentType<TDocument, TDocumentType>[]>;
/**
* Fetches a specific single type page.
*
* @example
*
* ```ts
* const page = await client.getSingle("settings")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getsingle}
*/
getSingle<TDocument extends TDocuments, TDocumentType extends TDocument["type"] = TDocument["type"]>(documentType: TDocumentType, params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<ExtractDocumentType<TDocument, TDocumentType>>;
/**
* Fetches pages with a specific type. Results are paginated.
*
* @example
*
* ```ts
* const response = await client.getByType("blog_post")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getbytype}
*/
getByType<TDocument extends TDocuments, TDocumentType extends TDocument["type"] = TDocument["type"]>(documentType: TDocumentType, params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<Query<ExtractDocumentType<TDocument, TDocumentType>>>;
/**
* Fetches pages with a specific type. This method may make multiple network
* requests to fetch all matching documents.
*
* @example
*
* ```ts
* const pages = await client.getAllByType("blog_post")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getallbytype}
*/
getAllByType<TDocument extends TDocuments, TDocumentType extends TDocument["type"] = TDocument["type"]>(documentType: TDocumentType, params?: Partial<Omit<BuildQueryURLArgs, "page">> & GetAllParams & FetchParams): Promise<ExtractDocumentType<TDocument, TDocumentType>[]>;
/**
* Fetches pages with a specific tag. Results are paginated.
*
* @example
*
* ```ts
* const response = await client.getByTag("featured")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getbytag}
*/
getByTag<TDocument extends TDocuments>(tag: string, params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<Query<TDocument>>;
/**
* Fetches pages with a specific tag. This method may make multiple network
* requests to fetch all matching documents.
*
* @example
*
* ```ts
* const pages = await client.getAllByTag("featured")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getallbytag}
*/
getAllByTag<TDocument extends TDocuments>(tag: string, params?: Partial<Omit<BuildQueryURLArgs, "page">> & GetAllParams & FetchParams): Promise<TDocument[]>;
/**
* Fetches pages with every tag from a list of tags. Results are paginated.
*
* @example
*
* ```ts
* const response = await client.getByEveryTag(["featured", "homepage"])
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getbyeverytag}
*/
getByEveryTag<TDocument extends TDocuments>(tags: string[], params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<Query<TDocument>>;
/**
* Fetches pages with every tag from a list of tags. This method may make
* multiple network requests to fetch all matching pages.
*
* @example
*
* ```ts
* const pages = await client.getAllByEveryTag(["featured", "homepage"])
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getallbyeverytag}
*/
getAllByEveryTag<TDocument extends TDocuments>(tags: string[], params?: Partial<Omit<BuildQueryURLArgs, "page">> & GetAllParams & FetchParams): Promise<TDocument[]>;
/**
* Fetches pages with at least one tag from a list of tags. Results are
* paginated.
*
* @example
*
* ```ts
* const response = await client.getBySomeTags(["featured", "homepage"])
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getbysometags}
*/
getBySomeTags<TDocument extends TDocuments>(tags: string[], params?: Partial<BuildQueryURLArgs> & FetchParams): Promise<Query<TDocument>>;
/**
* Fetches pages with at least one tag from a list of tags. This method may
* make multiple network requests to fetch all matching documents.
*
* @example
*
* ```ts
* const pages = await client.getAllBySomeTags(["featured", "homepage"])
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getallbysometags}
*/
getAllBySomeTags<TDocument extends TDocuments>(tags: string[], params?: Partial<Omit<BuildQueryURLArgs, "page">> & GetAllParams & FetchParams): Promise<TDocument[]>;
/**
* Fetches metadata about the client's Prismic repository.
*
* @example
*
* ```ts
* const repository = await client.getRepository()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getrepository}
*/
getRepository(params?: Pick<BuildQueryURLArgs, "accessToken"> & FetchParams): Promise<Repository>;
/**
* Fetches the repository's active refs.
*
* @example
*
* ```ts
* const refs = await client.getRefs()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getrefs}
*/
getRefs(params?: FetchParams): Promise<Ref[]>;
/**
* Fetches a ref by its ID.
*
* @example
*
* ```ts
* const ref = await client.getRefByID("YhE3YhEAACIA4321")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getrefbyid}
*/
getRefByID(id: string, params?: FetchParams): Promise<Ref>;
/**
* Fetches a ref by its label. A release ref's label is its name shown in the
* Page Builder.
*
* @example
*
* ```ts
* const ref = await client.getRefByLabel("My Release")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getrefbylabel}
*/
getRefByLabel(label: string, params?: FetchParams): Promise<Ref>;
/**
* Fetches the repository's master ref.
*
* @example
*
* ```ts
* const masterRef = await client.getMasterRef()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getmasterref}
*/
getMasterRef(params?: FetchParams): Promise<Ref>;
/**
* Fetches the repository's active releases.
*
* @example
*
* ```ts
* const releases = await client.getReleases()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getreleases}
*/
getReleases(params?: FetchParams): Promise<Ref[]>;
/**
* Fetches a release with a specific ID.
*
* @example
*
* ```ts
* const release = await client.getReleaseByID("YhE3YhEAACIA4321")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getreleasebyid}
*/
getReleaseByID(id: string, params?: FetchParams): Promise<Ref>;
/**
* Fetches a release by its label. A release ref's label is its name shown in
* the Page Builder.
*
* @example
*
* ```ts
* const release = await client.getReleaseByLabel("My Release")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#getreleasebylabel}
*/
getReleaseByLabel(label: string, params?: FetchParams): Promise<Ref>;
/**
* Fetches the repository's page tags.
*
* @example
*
* ```ts
* const tags = await client.getTags()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#gettags}
*/
getTags(params?: FetchParams): Promise<string[]>;
/**
* Builds a Content API query URL with a set of parameters.
*
* @example
*
* ```ts
* const url = await client.buildQueryURL({
* filters: [filter.at("document.type", "blog_post")],
* })
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#buildqueryurl}
*/
buildQueryURL({
signal,
fetchOptions,
...params
}?: Partial<BuildQueryURLArgs> & FetchParams): Promise<string>;
/**
* Fetches a previewed page's URL using a preview token and page ID.
*
* @example
*
* ```ts
* const url = await client.resolvePreviewURL({
* linkResolver,
* defaultURL: "/",
* })
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#resolvepreviewurl}
*/
resolvePreviewURL<LinkResolverReturnType>(args: {
/** A function converts a document to a URL in your website. */
linkResolver?: LinkResolverFunction<LinkResolverReturnType>;
/** A fallback URL used when the document does not have a URL. */
defaultURL: string;
/** The preview token for the preview session. */
previewToken?: string;
/** The previewed document's ID. */
documentID?: string;
} & FetchParams): Promise<string>;
/**
* Configures the client to query the latest published content. This is the
* client's default mode.
*
* @example
*
* ```ts
* client.queryLatestContent()
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#querylatestcontent}
*/
queryLatestContent(): void;
/**
* Configures the client to query content from a release with a specific ID.
*
* @example
*
* ```ts
* client.queryContentFromReleaseByID("YhE3YhEAACIA4321")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#querycontentfromreleasebyid}
*/
queryContentFromReleaseByID(id: string): void;
/**
* Configures the client to query content from a release with a specific
* label.
*
* @example
*
* ```ts
* client.queryContentFromReleaseByLabel("My Release")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#querycontentfromreleasebylabel}
*/
queryContentFromReleaseByLabel(label: string): void;
/**
* Configures the client to query content from a specific ref.
*
* @example
*
* ```ts
* client.queryContentFromRef("my-ref")
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#querycontentfromref}
*/
queryContentFromRef(ref: string | GetRef): void;
/**
* A preconfigured `fetch()` function for Prismic's GraphQL API that can be
* provided to GraphQL clients.
*
* @example
*
* ```ts
* import { createClient, getGraphQLEndpoint } from "@prismicio/client"
*
* const client = createClient("example-prismic-repo")
* const graphQLClient = new ApolloClient({
* link: new HttpLink({
* uri: getGraphQLEndpoint(client.repositoryName),
* // Provide `client.graphQLFetch` as the fetch implementation.
* fetch: client.graphQLFetch,
* // Using GET is required.
* useGETForQueries: true,
* }),
* cache: new InMemoryCache(),
* })
* ```
*
* @see {@link https://prismic.io/docs/technical-reference/prismicio-client/v7#graphqlfetch}
*/
graphQLFetch(input: RequestInfo, init?: Omit<RequestInit, "signal"> & {
signal?: AbortSignalLike;
}): Promise<Response>;
}
//#endregion
export { Client, ClientConfig, FetchParams, HttpRequestLike };
//# sourceMappingURL=Client.d.cts.map