feat: support providing a repository name to createClient() in place of an API endpoint

README.md

@@ -18,8 +18,7 @@ The official JavaScript + TypeScript client library for [Prismic][prismic].
 import * as prismic from "@prismicio/client";
 
 // Create a client
-const endpoint = prismic.getRepositoryEndpoint("my-repository");
-const client = prismic.createClient(endpoint);
+const client = prismic.createClient("my-repository");
 
 // Then query for your content
 const blogPosts = await client.getAllByType("blog_post");

examples/custom-caching/index.js

@@ -2,12 +2,11 @@ import * as prismic from "@prismicio/client";
 import fetch from "node-fetch";
 import QuickLRU from "quick-lru";
 
-const endpoint = prismic.getRepositoryEndpoint("qwerty");
 const cache = new QuickLRU({
 	maxSize: 1000, // 1000 entries
 });
 
-const client = prismic.createClient(endpoint, {
+const client = prismic.createClient("qwerty", {
 	fetch: async (url, options) => {
 		// The cache key contains the requested URL and headers
 		const key = JSON.stringify({ url, options });

examples/custom-timeout/index.js

@@ -5,11 +5,9 @@ import fetch, { AbortError } from "node-fetch";
 // version >=14.17.0, or are not in a node environment, remove this line.
 import { AbortController } from "abort-controller";
 
-const endpoint = prismic.getRepositoryEndpoint("qwerty");
-
 // A global timeout can be implemented like the following. This timeout will
 // apply to all network requests made by the client.
-const client = prismic.createClient(endpoint, {
+const client = prismic.createClient("qwerty", {
 	fetch: async (url, options) => {
 		// Create an AbortController. This will be used to cancel the
 		// `fetch()` request if it does not resolve within the given

examples/multiple-languages/index.js

@@ -1,8 +1,7 @@
 import * as prismic from "@prismicio/client";
 import fetch from "node-fetch";
 
-const endpoint = prismic.getRepositoryEndpoint("qwerty");
-const client = prismic.createClient(endpoint, {
+const client = prismic.createClient("qwerty", {
 	fetch,
 	// A default language can be set here. If a `lang` option is not set, your
 	// repository's default language will be used.

examples/releases/index.js

@@ -1,8 +1,7 @@
 import * as prismic from "@prismicio/client";
 import fetch from "node-fetch";
 
-const endpoint = prismic.getRepositoryEndpoint("qwerty");
-const client = prismic.createClient(endpoint, {
+const client = prismic.createClient("qwerty", {
 	fetch,
 });
 

examples/server-usage/index.js

@@ -1,8 +1,7 @@
 import * as prismic from "@prismicio/client";
 import fetch from "node-fetch";
 
-const endpoint = prismic.getRepositoryEndpoint("qwerty");
-const client = prismic.createClient(endpoint, {
+const client = prismic.createClient("qwerty", {
 	// Here, we provide a way for the client to make network requests.
 	// `node-fetch` is a Node.js fetch-compatible package.
 	fetch,

examples/using-refs/index.js

@@ -1,8 +1,7 @@
 import * as prismic from "@prismicio/client";
 import fetch from "node-fetch";
 
-const endpoint = prismic.getRepositoryEndpoint("qwerty");
-const client = prismic.createClient(endpoint, {
+const client = prismic.createClient("qwerty", {
 	fetch,
 });
 

examples/with-express/index.js

@@ -4,12 +4,11 @@ import fetch from "node-fetch";
 import express from "express";
 import QuickLRU from "quick-lru";
 
-const endpoint = prismic.getRepositoryEndpoint("qwerty");
 const cache = new QuickLRU({
 	maxSize: 1000, // 1000 entries
 });
 
-const client = prismic.createClient(endpoint, {
+const client = prismic.createClient("qwerty", {
 	fetch: async (url, options) => {
 		// The cache key contains the requested URL and headers
 		const key = JSON.stringify({ url, options });

examples/with-typescript/index.ts

@@ -54,8 +54,7 @@ type PrismicDocumentBlogPost = prismicT.PrismicDocument<
 >;
 
 const main = async () => {
-	const endpoint = prismic.getRepositoryEndpoint("qwerty");
-	const client = prismic.createClient(endpoint, { fetch });
+	const client = prismic.createClient("qwerty", { fetch });
 
 	// We can pass a type to client methods that return documents.
 	// Here, we tell `client.getByUID` that the document type will be a `PrismicDocumentPage`.

src/client.ts

@@ -17,6 +17,8 @@ import { NotFoundError } from "./NotFoundError";
 import { ParsingError } from "./ParsingError";
 import { PrismicError } from "./PrismicError";
 import { buildQueryURL, BuildQueryURLArgs } from "./buildQueryURL";
+import { getRepositoryEndpoint } from "./getRepositoryEndpoint";
+import { isRepositoryEndpoint } from "./isRepositoryEndpoint";
 import { predicate } from "./predicate";
 
 /**
@@ -237,8 +239,18 @@ const someTagsPredicate = (tags: string | string[]): string =>
 /**
  * Creates a Prismic client that can be used to query a repository.
  *
- * @param endpoint - The Prismic REST API V2 endpoint for the repository (use
- *   `prismic.getRepositoryEndpoint` for the default endpoint).
+ * @example
+ *
+ * ```ts
+ * // With a repository name.
+ * createClient("qwerty");
+ *
+ * // Or with a full Prismic Rest API V2 endpoint.
+ * createClient("https://qwerty.cdn.prismic.io/api/v2");
+ * ```
+ *
+ * @param repositoryNameOrEndpoint - The Prismic repository name or full Rest
+ *   API V2 endpoint for the repository.
  * @param options - Configuration that determines how content will be queried
  *   from the Prismic repository.
  *
@@ -319,26 +331,31 @@ export class Client {
 	 * such as Node.js, the `fetch` option must be provided as part of the
 	 * `options` parameter.
 	 *
-	 * @param endpoint - The Prismic REST API V2 endpoint for the repository (use
-	 *   `prismic.getRepositoryEndpoint` to get the default endpoint).
+	 * @param repositoryNameOrEndpoint - The Prismic repository name or full Rest
+	 *   API V2 endpoint for the repository.
 	 * @param options - Configuration that determines how content will be queried
 	 *   from the Prismic repository.
 	 *
 	 * @returns A client that can query content from the repository.
 	 */
-	constructor(endpoint: string, options: ClientConfig = {}) {
-		if (
-			process.env.NODE_ENV === "development" &&
-			/\.prismic\.io\/(?!api\/v2\/?)/.test(endpoint)
-		) {
-			throw new PrismicError(
-				"@prismicio/client only supports Prismic Rest API V2. Please use the getRepositoryEndpoint helper to generate a valid Rest API V2 endpoint URL.",
-				undefined,
-				undefined,
-			);
+	constructor(repositoryNameOrEndpoint: string, options: ClientConfig = {}) {
+		if (isRepositoryEndpoint(repositoryNameOrEndpoint)) {
+			if (
+				process.env.NODE_ENV === "development" &&
+				/\.prismic\.io\/(?!api\/v2\/?)/.test(repositoryNameOrEndpoint)
+			) {
+				throw new PrismicError(
+					"@prismicio/client only supports Prismic Rest API V2. Please provide only the repository name to the first createClient() parameter or use the getRepositoryEndpoint() helper to generate a valid Rest API V2 endpoint URL.",
+					undefined,
+					undefined,
+				);
+			}
+
+			this.endpoint = repositoryNameOrEndpoint;
+		} else {
+			this.endpoint = getRepositoryEndpoint(repositoryNameOrEndpoint);
 		}
 
-		this.endpoint = endpoint;
 		this.accessToken = options.accessToken;
 		this.routes = options.routes;
 		this.defaultParams = options.defaultParams;

test/client.test.ts

@@ -21,12 +21,29 @@ test.before(() => server.listen({ onUnhandledRequest: "error" }));
 test.after(() => server.close());
 
 test.serial("createClient creates a Client", (t) => {
+	const client = prismic.createClient("qwerty", {
+		fetch: sinon.stub(),
+	});
+
+	t.true(client instanceof prismic.Client);
+});
+
+test.serial("creates a client with a repository name", (t) => {
+	const repositoryName = "qwerty";
+	const client = prismic.createClient(repositoryName, {
+		fetch: sinon.stub(),
+	});
+
+	t.is(client.endpoint, prismic.getRepositoryEndpoint(repositoryName));
+});
+
+test.serial("creates a client with a Rest API V2 endpoint", (t) => {
 	const endpoint = prismic.getRepositoryEndpoint("qwerty");
 	const client = prismic.createClient(endpoint, {
 		fetch: sinon.stub(),
 	});
 
-	t.true(client instanceof prismic.Client);
+	t.is(client.endpoint, endpoint);
 });
 
 test.serial("client has correct default state", (t) => {
@@ -47,6 +64,40 @@ test.serial("client has correct default state", (t) => {
 	t.is(client.defaultParams, options.defaultParams);
 });
 
+test.serial(
+	"constructor throws if an invalid repository name is provided",
+	(t) => {
+		t.throws(
+			() => {
+				prismic.createClient("invalid repository name", {
+					fetch: sinon.stub(),
+				});
+			},
+			{
+				instanceOf: prismic.PrismicError,
+				message: /an invalid Prismic repository name was given/i,
+			},
+		);
+	},
+);
+
+test.serial(
+	"constructor throws if an invalid repository endpoint is provided",
+	(t) => {
+		t.throws(
+			() => {
+				prismic.createClient("https://invalid url.cdn.prismic.io/api/v2", {
+					fetch: sinon.stub(),
+				});
+			},
+			{
+				instanceOf: prismic.PrismicError,
+				message: /an invalid Prismic repository name was given/i,
+			},
+		);
+	},
+);
+
 test.serial("constructor throws if fetch is unavailable", (t) => {
 	const endpoint = prismic.getRepositoryEndpoint("qwerty");