@prismicio/client
Version:
The official JavaScript + TypeScript client library for Prismic
210 lines (209 loc) • 6.38 kB
TypeScript
/**
* An `orderings` parameter that orders the results by the specified field.
*
* {@link https://prismic.io/docs/rest-api-technical-reference#orderings}
*/
export interface Ordering {
field: string;
direction?: "asc" | "desc";
}
/**
* A `routes` parameter that determines how a document's URL field is resolved.
*
* {@link https://prismic.io/docs/route-resolver}
*
* @example With a document's UID field.
*
* ```ts
* {
* "type": "page",
* "path": "/:uid"
* }
* ```
*
* @example With a Content Relationship `parent` field.
*
* ```ts
* {
* "type": "page",
* "path": "/:parent?/:uid",
* "resolvers": {
* "parent": "parent"
* }
* }
* ```
*/
export interface Route {
/**
* The custom type of the document.
*/
type: string;
/**
* A specific UID to which this route definition is scoped. The route is only
* defined for the document whose UID matches the given UID.
*/
uid?: string;
/**
* A specific language to which this route definition is scoped. The route is
* only defined for documents whose language matches the given language.
*/
lang?: string;
/**
* The resolved path of the document with optional placeholders.
*/
path: string;
/**
* An object that lists the API IDs of the Content Relationships in the route.
*/
resolvers?: Record<string, string>;
}
/**
* Parameters for the Prismic REST API V2.
*
* {@link https://prismic.io/docs/api}
*/
export interface QueryParams {
/**
* The secure token for accessing the API (only needed if your repository is
* set to private).
*
* {@link https://prismic.io/docs/access-token}
*/
accessToken?: string;
/**
* The `pageSize` parameter defines the maximum number of documents that the
* API will return for your query.
*
* {@link https://prismic.io/docs/rest-api-technical-reference#pagesize}
*/
pageSize?: number;
/**
* The `page` parameter defines the pagination for the result of your query.
*
* {@link https://prismic.io/docs/rest-api-technical-reference#page}
*/
page?: number;
/**
* The `after` parameter can be used along with the orderings option. It will
* remove all the documents except for those after the specified document in
* the list.
*
* {@link https://prismic.io/docs/rest-api-technical-reference#after}
*/
after?: string;
/**
* The `fetch` parameter is used to make queries faster by only retrieving the
* specified field(s).
*
* {@link https://prismic.io/docs/rest-api-technical-reference#fetch}
*/
fetch?: string | string[];
/**
* The `fetchLinks` parameter allows you to retrieve a specific content field
* from a linked document and add it to the document response object.
*
* {@link https://prismic.io/docs/rest-api-technical-reference#fetchlinks}
*/
fetchLinks?: string | string[];
/**
* The `graphQuery` parameter allows you to specify which fields to retrieve
* and what content to retrieve from Linked Documents / Content
* Relationships.
*
* {@link https://prismic.io/docs/graphquery-rest-api}
*/
graphQuery?: string;
/**
* The `lang` option defines the language code for the results of your query.
*
* {@link https://prismic.io/docs/rest-api-technical-reference#lang}
*/
lang?: string;
/**
* The `orderings` parameter orders the results by the specified field(s). You
* can specify as many fields as you want.
*
* {@link https://prismic.io/docs/rest-api-technical-reference#orderings}
*
* @remarks
* Strings and arrays of strings are deprecated as of
* `@prismicio/client@7.0.0`. Please migrate to the more explicit array of
* objects.
*
* @example
*
* ```typescript
* buildQueryURL(endpoint, {
* orderings: [
* { field: "my.product.price", direction: "desc" },
* { field: "my.product.title" },
* ],
* })
* ```
*/
orderings?: string | Ordering | (string | Ordering)[];
/**
* The `routes` option allows you to define how a document's `url` field is
* resolved.
*
* {@link https://prismic.io/docs/route-resolver}
*/
routes?: Route | string | (Route | string)[];
/**
* The `brokenRoute` option allows you to define the route populated in the
* `url` property for broken link or content relationship fields. A broken
* link is a link or content relationship field whose linked document has been
* unpublished or deleted.
*
* {@link https://prismic.io/docs/route-resolver}
*/
brokenRoute?: string;
}
/**
* Arguments for `buildQueryURL` to construct a Query URL.
*/
type BuildQueryURLParams = {
/**
* Ref used to query documents.
*
* {@link https://prismic.io/docs/api#refs-and-the-entry-api}
*/
ref: string;
/**
* Ref used to populate integration fields with the latest content.
*
* {@link https://prismic.io/docs/integration-fields}
*/
integrationFieldsRef?: string;
/**
* One or more filters to filter documents for the query.
*
* {@link https://prismic.io/docs/rest-api-technical-reference#q}
*/
filters?: string | string[];
/**
* @deprecated Renamed to `filters`. Ensure the value is an array of filters,
* not a single, non-array filter.
*/
predicates?: string | string[];
};
export type BuildQueryURLArgs = QueryParams & BuildQueryURLParams;
/**
* Build a Prismic REST API V2 URL to request documents from a repository. The
* paginated response for this URL includes documents matching the parameters.
*
* A ref is required to make a request. Request the `endpoint` URL to retrieve a
* list of available refs.
*
* Type the JSON response with `Query`.
*
* {@link https://prismic.io/docs/api#refs-and-the-entry-api}
* {@link https://prismic.io/docs/rest-api-technical-reference}
*
* @param endpoint - URL to the repository's REST API V2.
* @param args - Arguments to filter and scope the query.
*
* @returns URL that can be used to request documents from the repository.
*/
export declare const buildQueryURL: (endpoint: string, args: BuildQueryURLArgs) => string;
export {};