Skip to content

Feature/add page context api #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 14 commits into
base: main
Choose a base branch
from
Open

Feature/add page context api #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
136424a
Add page context API with item editor support
JiriLojda Aug 15, 2025
16280ef
Add support for resinzing the custom app popup
JiriLojda Aug 26, 2025
8f39b31
Adjust get page context response shape
JiriLojda Sep 16, 2025
76aa38f
Adjust custom app page schema to the new format
JiriLojda Sep 29, 2025
eeb4317
Document getPageContext in readme
JiriLojda Sep 29, 2025
c5ec869
Formulate better responses in readme
JiriLojda Sep 29, 2025
fccc8b3
Remove projectEnvironmentId from page context
JiriLojda Sep 29, 2025
66ce9b4
Change getPageContext to return predefined objects for each page
JiriLojda Sep 29, 2025
2ab6205
Add support for observerPageContext
JiriLojda Oct 2, 2025
2df75b7
Update biome configuration and fix errors
JiriLojda Oct 2, 2025
38b3884
Merge get-context and get-page-context together into a new version of…
JiriLojda Oct 13, 2025
67b7bca
Mark some context properties as optional
JiriLojda Oct 17, 2025
4077bad
Rename observeContext to observeCustomAppContext for consistency and …
JiriLojda Oct 23, 2025
92ec440
Update API reference in readme
JiriLojda Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 164 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,51 +29,194 @@ npm install @kontent-ai/custom-app-sdk
```typescript
import { getCustomAppContext, CustomAppContext } from "@kontent-ai/custom-app-sdk";

const response: CustomAppContext = await getCustomAppContext();
const response = await getCustomAppContext();

if (response.isError) {
console.error({ errorCode: response.code, description: response.description});
console.error({ errorCode: response.code, description: response.description });
} else {
console.log({ config: response.config, context: response.context });
// TypeScript will narrow the type based on currentPage
if (response.context.currentPage === "itemEditor") {
console.log({
contentItemId: response.context.contentItemId,
languageId: response.context.languageId,
validationErrors: response.context.validationErrors
});
}
}
```

## API Reference

### getCustomAppContext

Use the `getCustomAppContext` function to retrieve the context of the custom app. The function takes no arguments and returns a promise with a value of an object of type `CustomAppContext`.
Retrieves the context of the custom app. The function takes no arguments and automatically detects the current page type, returning the appropriate context with all relevant properties for that page.

#### CustomAppContext
#### Return Type

Returns a promise that resolves to a discriminated union type with two possible states:

##### Success Response (`isError: false`)

| Property | Type | Description |
|---------------|------------------------|------------------------------------------------------------------------------|
| `isError` | `false` | Indicates the request was successful |
| `context` | `CustomAppContext` | A discriminated union of page-specific context objects |

##### Error Response (`isError: true`)

| Property | Type | Description |
|---------------|------------------------|------------------------------------------------------------------------------|
| `isError` | boolean | Determines if there was an error while getting the context of the custom app |
| `code` | ErrorCode enum \| null | The code of the error message |
| `description` | string \| null | The description of the error message |
| `context` | object \| null | Contains data provided by the Kontent.ai application |
| `config` | object \| null | Contains JSON object specified in the custom app configuration |
| `isError` | `true` | Indicates an error occurred |
| `code` | ErrorCode enum | The code of the error message |
| `description` | string | The description of the error message |

#### CustomAppContext

`CustomAppContext` is a discriminated union type based on the `currentPage` property. Each page type includes only the relevant properties for that specific page:

##### Item Editor Page Context

When `currentPage` is `"itemEditor"`, the context includes:

#### Config
The `config` object is a JSON object that can be defined within the Custom App configuration under Environment settings in the Kontent.ai app.
| Property | Type | Description |
|-------------------------|---------------------------------------|----------------------------------------------------------------------|
| `currentPage` | `"itemEditor"` | Identifies this as an item editor page |
| `environmentId` | UUID | The environment's ID |
| `userId` | string | The current user's ID |
| `userEmail` | string | The current user's email |
| `userRoles` | Array of UserRole | An array containing all the roles of the current user in the environment |
| `path` | string | The current path within the Kontent.ai application |
| `pageTitle` | string | The title of the current page |
| `appConfig` | unknown \| undefined | JSON object specified in the custom app configuration |
| `contentItemId` | UUID | The ID of the content item being edited |
| `languageId` | UUID | The ID of the current language |
| `validationErrors` | Record<string, string[]> | A record of validation errors for content item fields |

#### Context
The `context` object contains data provided by the Kontent.ai application that you can leverage in your custom app.
##### Other Page Context

| Property | Type | Description |
|-----------------|-------------------|--------------------------------------------------------------------------|
| `environmentId` | UUID | The environment's ID |
| `userId` | string | The current user's ID |
| `userEmail` | string | The current user's email |
| `userRoles` | Array of UserRole | An array containing all the roles of the current user in the environment |
When `currentPage` is `"other"`, the context includes:

#### UserRole
| Property | Type | Description |
|-------------------------|---------------------------------------|----------------------------------------------------------------------|
| `currentPage` | `"other"` | Identifies this as any other page type |
| `environmentId` | UUID | The environment's ID |
| `userId` | string | The current user's ID |
| `userEmail` | string | The current user's email |
| `userRoles` | Array of UserRole | An array containing all the roles of the current user in the environment |
| `path` | string | The current path within the Kontent.ai application |
| `pageTitle` | string | The title of the current page |
| `appConfig` | unknown \| undefined | JSON object specified in the custom app configuration |

#### UserRole

| Property | Type | Description |
|------------|--------|----------------------------------------------------------------------|
| `id` | UUID | The role's ID |
| `codename` | string | The role's codename - applicable only for the _Project manager_ role |

### observeCustomAppContext

Subscribes to context changes and receives notifications when the context is updated. The function takes a callback that will be invoked whenever the context changes.

#### Parameters

| Parameter | Type | Description |
|------------|-----------------------------|-------------------------------------------------------|
| `callback` | `(context: CustomAppContext) => void` | Function to be called when the context changes |

#### Return Type

Returns a promise that resolves to a discriminated union type with two possible states:

##### Success Response (`isError: false`)

| Property | Type | Description |
|---------------|------------------------|------------------------------------------------------------------------------|
| `isError` | `false` | Indicates the request was successful |
| `context` | `CustomAppContext` | The initial context value |
| `unsubscribe` | `() => Promise<void>` | Function to call to stop receiving context updates |

##### Error Response (`isError: true`)

| Property | Type | Description |
|---------------|------------------------|------------------------------------------------------------------------------|
| `isError` | `true` | Indicates an error occurred |
| `code` | ErrorCode enum | The code of the error message |
| `description` | string | The description of the error message |

#### Usage Example

```typescript
import { observeCustomAppContext } from "@kontent-ai/custom-app-sdk";

const response = await observeCustomAppContext((context) => {
console.log("Context updated:", context);
});

if (response.isError) {
console.error({ errorCode: response.code, description: response.description });
} else {
console.log("Initial context:", response.context);

// Later, when you want to stop observing
await response.unsubscribe();
}
```

### setPopupSize

Sets the size of the popup window when the custom app is displayed in a popup.

#### Parameters

| Parameter | Type | Description |
|-----------|----------------------|--------------------------------------------------|
| `width` | `PopupSizeDimension` | The desired width of the popup |
| `height` | `PopupSizeDimension` | The desired height of the popup |

#### PopupSizeDimension

A discriminated union type for specifying dimensions in either pixels or percentages:

```typescript
type PopupSizeDimension =
| { unit: "px"; value: number }
| { unit: "%"; value: number };
```

#### Return Type

Returns a promise that resolves to a discriminated union type with two possible states:

##### Success Response (`isError: false`)

| Property | Type | Description |
|---------------|------------------------|------------------------------------------------------------------------------|
| `isError` | `false` | Indicates the request was successful |

##### Error Response (`isError: true`)

| Property | Type | Description |
|---------------|------------------------|------------------------------------------------------------------------------|
| `isError` | `true` | Indicates an error occurred |
| `code` | ErrorCode enum | The code of the error message |
| `description` | string | The description of the error message |

#### Usage Example

```typescript
import { setPopupSize } from "@kontent-ai/custom-app-sdk";

const response = await setPopupSize(
{ unit: "px", value: 800 },
{ unit: "%", value: 90 }
);

if (response.isError) {
console.error({ errorCode: response.code, description: response.description });
}
```

## Contributing

For Contributing please see <a href="./CONTRIBUTING.md">`CONTRIBUTING.md`</a> for more information.
Expand Down
14 changes: 3 additions & 11 deletions biome.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,5 @@
{
"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
"organizeImports": {
"enabled": true
},
"$schema": "https://biomejs.dev/schemas/2.2.4/schema.json",
"formatter": {
"indentStyle": "space",
"lineWidth": 100
Expand All @@ -20,13 +17,8 @@
}
},
"files": {
"ignore": [
"**/*-lock.json",
"**/.DS_Store",
".idea/**",
".vscode/**",
".history/**",
"node_modules/**"
"includes": [
"src/**/*"
]
}
}
Loading