Merge branch 'master' of github.com:prismicio/prismic-client into lg/…

…text-in-links

# Conflicts:
#	CHANGELOG.md
#	package-lock.json
#	package.json

.eslintignore

@@ -3,6 +3,7 @@ CHANGELOG.md
 # .gitignore copy
 
 # custom
+*.tgz
 dist
 examples/**/package-lock.json
 

.gitignore

@@ -1,4 +1,5 @@
 # custom
+*.tgz
 dist
 examples/**/package-lock.json
 

.prettierignore

@@ -4,6 +4,7 @@ CHANGELOG.md
 # .gitignore copy
 
 # custom
+*.tgz
 dist
 examples/**/package-lock.json
 

CHANGELOG.md

@@ -2,49 +2,19 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-## [7.10.0-alpha.0](https://github.com/prismicio/prismic-client/compare/v7.9.0...v7.10.0-alpha.0) (2024-09-20)
+### [7.10.1](https://github.com/prismicio/prismic-client/compare/v7.10.0...v7.10.1) (2024-09-23)
 
-## [7.9.0-alpha.3](https://github.com/prismicio/prismic-client/compare/v7.8.1...v7.9.0-alpha.3) (2024-09-10)
 
+### Bug Fixes
 
-### Chore
-
-* **release:** 7.9.0-alpha.3 ([0d3fb98](https://github.com/prismicio/prismic-client/commit/0d3fb98743b79d3fc2a41dcb2fc6edfc67857478))
-
-## [7.9.0-alpha.2](https://github.com/prismicio/prismic-client/compare/v7.9.0-alpha.1...v7.9.0-alpha.2) (2024-08-27)
-
-
-### Chore
-
-* **release:** 7.9.0-alpha.2 ([000f146](https://github.com/prismicio/prismic-client/commit/000f146d25b84b2937c3accaffa54ab936a78de8))
-* revert previous changes ([c53de86](https://github.com/prismicio/prismic-client/commit/c53de86a7ed749f0f9d8999b9e58564d9a8efe35))
-
-## [7.9.0-alpha.1](https://github.com/prismicio/prismic-client/compare/v7.9.0-alpha.0...v7.9.0-alpha.1) (2024-08-27)
-
-
-### Features
-
-* use KeyTextField for link text value definition ([1a4c51a](https://github.com/prismicio/prismic-client/commit/1a4c51a389ed4d06cf69c3edcb215559ba91fe99))
-
-
-### Chore
-
-* **release:** 7.9.0-alpha.1 ([d940fcd](https://github.com/prismicio/prismic-client/commit/d940fcdb023de34765006607f7f34481de00a6ef))
-* remove changelog for alpha ([50fc797](https://github.com/prismicio/prismic-client/commit/50fc797372726c0abc575b9f1b0a56d5db939bb1))
+* ensure correct content type is attached to asset's blob ([80fe887](https://github.com/prismicio/prismic-client/commit/80fe887235e2eda594876f08db54cdb544e20b9f))
 
-## [7.9.0-alpha.0](https://github.com/prismicio/prismic-client/compare/v7.8.0...v7.9.0-alpha.0) (2024-08-14)
+## [7.10.0](https://github.com/prismicio/prismic-client/compare/v7.9.0...v7.10.0) (2024-09-23)
 
 
 ### Features
 
-* add text property to link models ([40d0e0b](https://github.com/prismicio/prismic-client/commit/40d0e0be3ce8038cd36e8cdf3350ffa9893ada98))
-* add text to link value models ([8459d75](https://github.com/prismicio/prismic-client/commit/8459d75608c1af8319adafd2b3bf73555569a434))
-
-
-### Chore
-
-* **release:** 7.9.0-alpha.0 ([f2021c0](https://github.com/prismicio/prismic-client/commit/f2021c053b9aac1c17b7bbd1845c91eab7b0d176))
-* update package version ([c06b383](https://github.com/prismicio/prismic-client/commit/c06b383ff41f01e253641c7852a4e9701725bdba))
+* add `createMigration` and `createWriteClient` ([#350](https://github.com/prismicio/prismic-client/issues/350)) ([7dc2950](https://github.com/prismicio/prismic-client/commit/7dc2950e25e7f8db706522175974b8aee36d170e))
 
 ## [7.9.0](https://github.com/prismicio/prismic-client/compare/v7.8.1...v7.9.0) (2024-09-17)
 
@@ -65,13 +35,6 @@ All notable changes to this project will be documented in this file. See [standa
 
 * add missing `is_master` property on repository type ([0289698](https://github.com/prismicio/prismic-client/commit/0289698cc9ca7ed5b264f71f2a9f8d39e3710058))
 
-## [7.9.0-alpha.2](https://github.com/prismicio/prismic-client/compare/v7.9.0-alpha.1...v7.9.0-alpha.2) (2024-08-27)
-
-
-### Chore
-
-* revert previous changes ([c53de86](https://github.com/prismicio/prismic-client/commit/c53de86a7ed749f0f9d8999b9e58564d9a8efe35))
-
 ## [7.8.0](https://github.com/prismicio/prismic-client/compare/v7.7.4...v7.8.0) (2024-08-01)
 
 

examples/migrate/README.md

@@ -0,0 +1,26 @@
+# Migrate
+
+This example shows a migration script leveraging `@prismicio/client`'s write client
+and the migration helper to migrate existing content to Prismic. `migrate.ts` is the
+TypeScript exact equivalent of `migrate.mjs`.
+
+Learn more about migrating to Prismic on the [migration documentation](https://prismic.io/docs/migration).
+
+## How to run the example
+
+> Scripts in this example uses an hypothetical WordPress client, therefore, they are not runnable as-is.
+
+```sh
+# Clone the repository to your computer
+git clone https://github.com/prismicio/prismic-client.git
+cd prismic-client/examples/migrate
+
+# Install the dependencies
+npm install
+
+# Run the example (TypeScript)
+npx tsx migrate.ts
+
+# Run the example (JavaScript)
+node migrate.mjs
+```

examples/migrate/migrate.mjs

@@ -0,0 +1,101 @@
+import * as prismic from "@prismicio/client"
+import { htmlAsRichText } from "@prismicio/migrate"
+import "dotenv/config"
+// An hypothetical WordPress client
+import { createWordPressClient } from "wordpress"
+
+import { repositoryName } from "./slicemachine.config.json"
+
+// Prismic setup
+const writeClient = prismic.createWriteClient(repositoryName, {
+	writeToken: process.env.PRISMIC_WRITE_TOKEN,
+})
+
+const migration = prismic.createMigration()
+
+// Custom migration script logic
+
+const convertWPDocument = (wpDocument) => {
+	switch (wpDocument.type) {
+		case "page":
+			return convertWPPage(wpDocument)
+		case "settings":
+			return convertWPSettings(wpDocument)
+	}
+
+	throw new Error(`Unsupported document type: ${wpDocument.type}`)
+}
+
+const convertWPPage = (wpPage) => {
+	return migration.createDocument(
+		{
+			type: "page",
+			lang: wpPage.lang,
+			uid: wpPage.slug,
+			tags: ["wordpress"],
+			data: {
+				meta_title: wpPage.meta_title,
+				meta_description: wpPage.meta_description,
+				meta_image: migration.createAsset(
+					wpPage.meta_image.url,
+					wpPage.meta_image.name,
+				),
+				title: wpHTMLAsRichText(wpPage.title),
+				body: wpHTMLAsRichText(wpPage.content),
+			},
+		},
+		wpPage.name,
+		{
+			masterLanguageDocument: () =>
+				migration.getByUID(
+					wpPage.masterLanguageDocument.type,
+					wpPage.masterLanguageDocument.uid,
+				),
+		},
+	)
+}
+
+const convertWPSettings = (wpSettings) => {
+	return migration.createDocument(
+		{
+			type: "settings",
+			lang: wpSettings.lang,
+			tags: ["wordpress"],
+			data: {
+				title: wpHTMLAsRichText(wpSettings.name),
+			},
+		},
+		"Settings",
+	)
+}
+
+const wpHTMLAsRichText = (html) => {
+	return htmlAsRichText(html, {
+		serializer: {
+			img: ({ node }) => {
+				const src = node.properties.src
+				const filename = src.split("/").pop()
+				const alt = node.properties.alt
+
+				return {
+					type: "image",
+					id: migration.createAsset(src, filename, { alt }),
+				}
+			},
+		},
+	}).result
+}
+
+// Fetching and converting WordPress documents
+const wpClient = createWordPressClient("https://example.com/wp-json")
+
+const wpDocuments = await wpClient.dangerouslyGetAllDocuments()
+
+for (const wpDocument of wpDocuments) {
+	convertWPDocument(wpDocument)
+}
+
+// Execute the prepared migration at the very end of the script
+await writeClient.migrate(migration, {
+	reporter: (event) => console.info(event),
+})

examples/migrate/migrate.ts

@@ -0,0 +1,102 @@
+import * as prismic from "@prismicio/client"
+import { htmlAsRichText } from "@prismicio/migrate"
+import "dotenv/config"
+// An hypothetical WordPress client
+// @ts-expect-error - This is an hypothetical WordPress client
+import { type WPDocument, createWordPressClient } from "wordpress"
+
+import { repositoryName } from "./slicemachine.config.json"
+
+// Prismic setup
+const writeClient = prismic.createWriteClient(repositoryName, {
+	writeToken: process.env.PRISMIC_WRITE_TOKEN!,
+})
+
+const migration = prismic.createMigration()
+
+// Custom migration script logic
+
+const convertWPDocument = (wpDocument: WPDocument) => {
+	switch (wpDocument.type) {
+		case "page":
+			return convertWPPage(wpDocument)
+		case "settings":
+			return convertWPSettings(wpDocument)
+	}
+
+	throw new Error(`Unsupported document type: ${wpDocument.type}`)
+}
+
+const convertWPPage = (wpPage: WPDocument) => {
+	return migration.createDocument(
+		{
+			type: "page",
+			lang: wpPage.lang,
+			uid: wpPage.slug,
+			tags: ["wordpress"],
+			data: {
+				meta_title: wpPage.meta_title,
+				meta_description: wpPage.meta_description,
+				meta_image: migration.createAsset(
+					wpPage.meta_image.url,
+					wpPage.meta_image.name,
+				),
+				title: wpHTMLAsRichText(wpPage.title),
+				body: wpHTMLAsRichText(wpPage.content),
+			},
+		},
+		wpPage.name,
+		{
+			masterLanguageDocument: () =>
+				migration.getByUID(
+					wpPage.masterLanguageDocument.type,
+					wpPage.masterLanguageDocument.uid,
+				),
+		},
+	)
+}
+
+const convertWPSettings = (wpSettings: WPDocument) => {
+	return migration.createDocument(
+		{
+			type: "settings",
+			lang: wpSettings.lang,
+			tags: ["wordpress"],
+			data: {
+				title: wpHTMLAsRichText(wpSettings.name),
+			},
+		},
+		"Settings",
+	)
+}
+
+const wpHTMLAsRichText = (html: string) => {
+	return htmlAsRichText(html, {
+		serializer: {
+			img: ({ node }) => {
+				const src = node.properties.src as string
+				const filename = src.split("/").pop()!
+				const alt = node.properties.alt as string
+
+				return {
+					type: "image",
+					id: migration.createAsset(src, filename, { alt }),
+				}
+			},
+		},
+	}).result
+}
+
+// Fetching and converting WordPress documents
+const wpClient = createWordPressClient("https://example.com/wp-json")
+
+const wpDocuments = await wpClient.dangerouslyGetAllDocuments()
+
+for (const wpDocument of wpDocuments) {
+	convertWPDocument(wpDocument)
+}
+
+// Execute the prepared migration at the very end of the script
+await writeClient.migrate(migration, {
+	reporter: (event) => console.info(event),
+})

examples/migrate/package.json

@@ -0,0 +1,11 @@
+{
+	"type": "module",
+	"dependencies": {
+		"@prismicio/client": "latest",
+		"@prismicio/migrate": "latest"
+	},
+	"devDependencies": {
+		"tsx": "^4.19.1",
+		"typescript": "^5.6.2"
+	}
+}

examples/migrate/slicemachine.config.json

@@ -0,0 +1,6 @@
+{
+	"libraries": ["./slices"],
+	"adapter": "@slicemachine/adapter-next",
+	"repositoryName": "qwerty",
+	"localSliceSimulatorURL": "http://localhost:3000/slice-simulator"
+}

examples/migrate/tsconfig.json

@@ -0,0 +1,14 @@
+{
+	"compilerOptions": {
+		"target": "esnext",
+		"lib": ["esnext"],
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"resolveJsonModule": true,
+		"strict": true,
+		"strictNullChecks": true,
+		"esModuleInterop": true,
+		"skipDefaultLibCheck": true,
+		"skipLibCheck": true
+	}
+}

messages/avoid-write-client-in-browser.md

@@ -0,0 +1,23 @@
+# Avoid write client in browser
+
+`@prismicio/client`'s write client uses credentials to authenticate write queries to a Prismic repository.
+
+The repository write token and Migration API key must be provided when creating a `@prismicio/client` write client like the following:
+
+```typescript
+import * as prismic from "@prismicio/client";
+
+const writeClient = prismic.createWriteClient("example-prismic-repo", {
+	writeToken: "xxx"
+})
+```
+
+If the write client is exposed to the browser, so are its tokens. Malicious actors will have write access to your repository.
+
+Use the non-write client when write actions are not needed. The non-write client only has read access to the repository and can safely be used in the browser. Be aware the client's access token, if used, will be exposed in the browser.
+
+```typescript
+import * as prismic from "@prismicio/client";
+
+const client = prismic.createClient("example-prismic-repo")
+```