https://github.com/focusreactive/contentful-ai-sdk
https://github.com/focusreactive/contentful-ai-sdk
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/focusreactive/contentful-ai-sdk
- Owner: focusreactive
- Created: 2025-02-17T09:49:25.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-03-19T14:35:40.000Z (about 1 year ago)
- Last Synced: 2025-03-19T15:35:42.133Z (about 1 year ago)
- Language: TypeScript
- Size: 62.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Contentful AI SDK
## Installation
To add the SDK to your project, run the following command:
```sh
yarn add @focus-reactive/contentful-ai-sdk
```
## Usage
### Initialization
Before using the SDK, you must initialize it with the Contentful client and a valid OpenAI token.
In React apps, you can use the `useSDK` hook from the `@contentful/react-apps-toolkit` package:
```typescript
import type { SidebarAppSDK } from '@contentful/app-sdk'
import { useSDK } from '@contentful/react-apps-toolkit'
import { initSDK } from '@focus-reactive/contentful-ai-sdk'
import { useEffect } from 'react'
const LocationComponent = () => {
const sdk = useSDK()
useEffect(() => {
initSDK({ client: sdk.cma, openAiKey: process.env.REACT_APP_OPENAI_TOKEN! })
}, [])
return ...;
}
export default LocationComponent
```
Alternatively, you can directly initialize the client via `createClient` with your access token and pass it to the `initSDK` function.
### Using the SDK
```typescript
import type { SidebarAppSDK } from '@contentful/app-sdk'\
import { useSDK } from '@contentful/react-apps-toolkit'
import { Form } from '@contentful/f36-components'
import { localize } from '@focus-reactive/contentful-ai-sdk'
import { useForm } from 'react-hook-form'
import { useMutation } from '@tanstack/react-query'
export default function Translate() {
const sdk = useSDK()
const { handleSubmit } = useForm()
const { mutate } = useMutation({
mutationFn: localize,
})
const onSubmit = (values) => {
mutate({
targetLanguage: values.targetLanguage,
translationLevel: values.translationLevel,
entryId: sdk.entry.getSys().id,
localEntryId: values.local,
globalEntryId: values.global,
})
}
return (
...
)
}
```
## API
### **localize**
Translate the fields of an entry to the target language. The field values in the default locale will be used as the source. It can be used for both field-level and entry-level localizations.
#### **Parameters**
```typescript
type LocalizeFieldsProps = {
translationLevel: 'field';
targetLanguage: string;
entryId: string;
};
type LocalizeEntryProps = {
translationLevel: 'entry';
targetLanguage: string;
localEntryId: string;
globalEntryId: string;
};
type LocalizeProps = LocalizeFieldsProps | LocalizeEntryProps;
```
- `targetLanguage` - language (or locale) to which you want to translate your entry. **Available locales must be configured in space settings.**
- `translationLevel` - which localization level to use.
- `field` - add target localization to the current entry
- `entryId` - ID of the entry that you want to translate.
- `entry` - create a new entry with translated values stored in the default locale and link the global entry (container) with the newly created entry
- `localEntryId` - ID of the entry that will be used as a data source.
- `globalEntryId` - ID of the entry that will be used as a container for the newly created entry.
#### **Return**
`Promise`
### **resolveEntries**
Identify global and local entries based on whether a given entry refers to any other entries or is being referenced.
#### **Parameters**
- `entryId` - ID of the entry
#### **Return**
`{ global: RecognizedEntry; local: RecognizedEntry }`, where `RecognizedEntry` is an object with the following structure:
```typescript
type RecognizedEntry = {
id: string;
name: string;
contentType: { id: string; name: string };
} | null
```
If entry is isolated (no references), `{ global: null, local: entry }` will be returned.
### **findTags**
Find the most relevant tags for the entry's content from the space's configured tags.
#### **Parameters**
- `entryId` - ID of the entry
- `contentTitle` - content title for more context
#### **Return**
An array of tags, where each tag is an object with the following structure:
```typescript
type Tag = {
id: string
title: string
}
```
### **applyTags**
Apply tags (with overwrite) to the given entry
#### **Parameters**
- `entryId` - ID of the entry
- `tags` - Array of objects with `id` property, where `id` is the ID of the tag
#### **Return**
`Promise`