feat: update function examples to highlight how to init a cma client within an app function [EXT-6303] (#9630)

* feat: update autotagger example to highlight how to init a cma client within an app function [EXT-6303]

* feat: update comment-bot example to highlight how to init a cma client within an app function [EXT-6303]

* feat: update function-appaction example to highlight how to init a cma client within an app function [EXT-6303]

* feat: update appaction-call template to highlight how to init a cma client within an app function [EXT-6303]

Author: jjolton-contentful

examples/autotagger/functions/autotagger.ts

@@ -3,16 +3,38 @@ import {
   AppActionRequest,
   AppEventEntry,
   AppEventRequest,
+  EntryAutosaveEventPayload,
   FunctionEventContext,
+  FunctionTypeEnum,
 } from '@contentful/node-apps-toolkit/lib/requests/typings';
-import type { EntryProps, PlainClientAPI, Link } from 'contentful-management';
+import {
+  type EntryProps,
+  type PlainClientAPI,
+  type Link,
+  createClient,
+} from 'contentful-management';
 import { buildAutotagPrompts } from './prompts';
 
 const DEFAULT_API_URL = 'https://api.openai.com/v1/chat/completions';
 const DEFAULT_MODEL = 'gpt-4o';
 
+function initContentfulManagementClient(context: FunctionEventContext): PlainClientAPI {
+  if (!context.cmaClientOptions) {
+    throw new Error(
+      'Contentful Management API client options are only provided for certain function types. To learn more about using the CMA within functions, see https://www.contentful.com/developers/docs/extensibility/app-framework/functions/#using-the-cma.'
+    );
+  }
+  return createClient(context.cmaClientOptions, {
+    type: 'plain',
+    defaults: {
+      spaceId: context.spaceId,
+      environmentId: context.environmentId,
+    },
+  });
+}
+
 async function fetchOpenAiResponse(
-  entry: EntryProps,
+  entry: EntryAutosaveEventPayload | EntryProps,
   apiKey: string,
   apiUrl: string,
   model: string
@@ -74,12 +96,12 @@ async function createNewTags(cma: PlainClientAPI, newTags: string[]): Promise<vo
 
 async function updateEntryTags(
   cma: PlainClientAPI,
-  entry: EntryProps,
+  entry: EntryAutosaveEventPayload | EntryProps,
   tags: Link<'Tag'>[]
 ): Promise<void> {
   try {
     await cma.entry.patch(
-      { entryId: entry.sys.id },
+      { entryId: entry.sys.id, version: entry.sys.version },
       [
         {
           op: 'replace',
@@ -98,7 +120,7 @@ async function updateEntryTags(
 }
 
 async function autotag(
-  entry: EntryProps,
+  entry: EntryAutosaveEventPayload | EntryProps,
   cma: PlainClientAPI,
   appInstallationParameters: Record<string, any>
 ) {
@@ -123,45 +145,40 @@ async function autotag(
   }
 }
 
-const appActionHandler: EventHandler<'appaction.call'> = async (
-  event: AppActionRequest<'Custom' | 'Entries.v1.0' | 'Notification.v1.0'>,
+const appActionHandler: EventHandler<FunctionTypeEnum.AppActionCall> = async (
+  event: AppActionRequest<'Custom', { entryId: string }>,
   context: FunctionEventContext
 ) => {
   const {
     body: { entryId },
-  } = event as AppActionRequest<'Custom', { entryId: string }>;
-  const { cma, appInstallationParameters } = context as FunctionEventContext & {
-    cma: PlainClientAPI;
-  };
+  } = event;
   try {
+    const cma = initContentfulManagementClient(context);
     const entry = await cma.entry.get({ entryId });
-    await autotag(entry, cma, appInstallationParameters);
+    await autotag(entry, cma, context.appInstallationParameters);
     return { success: true };
   } catch (error) {
     console.error('Error handling action:', error);
     return { success: false };
   }
 };
 
-const appEventHandler: EventHandler<'appevent.handler'> = async (
+const appEventHandler: EventHandler<FunctionTypeEnum.AppEventHandler> = async (
   event: AppEventRequest,
   context: FunctionEventContext
 ) => {
-  const { cma, appInstallationParameters } = context as FunctionEventContext & {
-    cma: PlainClientAPI;
-  };
   try {
+    const cma = initContentfulManagementClient(context);
     const { body: entry } = event as AppEventEntry;
-    await autotag(entry, cma, appInstallationParameters);
+    await autotag(entry as EntryAutosaveEventPayload, cma, context.appInstallationParameters);
   } catch (error) {
     console.error('Error handling event:', error);
   }
 };
 
-export const handler: EventHandler<'appaction.call' | 'appevent.handler'> = async (
-  event: AppActionRequest | AppEventRequest,
-  context: FunctionEventContext
-) => {
+export const handler: EventHandler<
+  FunctionTypeEnum.AppActionCall | FunctionTypeEnum.AppEventHandler
+> = async (event, context) => {
   if (event.type === 'appaction.call') {
     return appActionHandler(event, context);
   } else if (event.type === 'appevent.handler') {

examples/autotagger/functions/prompts.ts

@@ -1,6 +1,7 @@
+import { EntryAutosaveEventPayload } from '@contentful/node-apps-toolkit';
 import type { EntryProps } from 'contentful-management';
 
-export function buildAutotagPrompts(entry: EntryProps) {
+export function buildAutotagPrompts(entry: EntryAutosaveEventPayload | EntryProps) {
   return [
     {
       role: 'system',

examples/autotagger/package.json

@@ -8,7 +8,7 @@
     "@contentful/f36-tokens": "4.2.0",
     "@contentful/react-apps-toolkit": "1.2.16",
     "@emotion/css": "^11.13.5",
-    "contentful-management": "11.48.0",
+    "contentful-management": "11.50.0",
     "react": "19.0.0",
     "react-dom": "19.0.0"
   },

examples/function-appaction/functions/example.ts

@@ -2,19 +2,36 @@ import { FunctionEventHandler } from '@contentful/node-apps-toolkit';
 import {
   AppActionRequest,
   FunctionEventContext,
+  FunctionTypeEnum,
 } from '@contentful/node-apps-toolkit/lib/requests/typings';
+import { type PlainClientAPI, createClient } from 'contentful-management';
 
 // When using a 'Custom' category App Action, you may define the parameters that the App Action will receive.
 // This should match what you configured in the App Action definition.
 type MyCustomAppActionParameters = {
   foo: string;
 };
 
-export const handler: FunctionEventHandler<'appaction.call'> = async (
+function initContentfulManagementClient(context: FunctionEventContext): PlainClientAPI {
+  if (!context.cmaClientOptions) {
+    throw new Error(
+      'Contentful Management API client options are only provided for certain function types. To learn more about using the CMA within functions, see https://www.contentful.com/developers/docs/extensibility/app-framework/functions/#using-the-cma.'
+    );
+  }
+  return createClient(context.cmaClientOptions, {
+    type: 'plain',
+    defaults: {
+      spaceId: context.spaceId,
+      environmentId: context.environmentId,
+    },
+  });
+}
+
+export const handler: FunctionEventHandler<FunctionTypeEnum.AppActionCall> = async (
   event: AppActionRequest<'Custom', MyCustomAppActionParameters>, // For better typing, specify your App Action category and, if using the 'Custom' category, parameter types here
   context: FunctionEventContext
 ) => {
-  const cma = context.cma!; // App Action Call Functions have access to the authenticated CMA client
+  const cma = initContentfulManagementClient(context); // App Action Call Functions have access to the authenticated CMA client
 
   const { foo } = event.body; // Access the parameters passed to the App Action Call via the event body
 

examples/function-comment-bot/functions/bot-actions/bot-action-base.ts

@@ -1,6 +1,22 @@
-import { PlainClientAPI } from 'contentful-management';
+import { type FunctionEventContext } from '@contentful/node-apps-toolkit';
+import { type PlainClientAPI, createClient } from 'contentful-management';
 
 export class BotActionBase {
+  initContentfulManagementClient(context: FunctionEventContext): PlainClientAPI {
+    if (!context.cmaClientOptions) {
+      throw new Error(
+        'Contentful Management API client options are only provided for certain function types. To learn more about using the CMA within functions, see https://www.contentful.com/developers/docs/extensibility/app-framework/functions/#using-the-cma.'
+      );
+    }
+    return createClient(context.cmaClientOptions, {
+      type: 'plain',
+      defaults: {
+        spaceId: context.spaceId,
+        environmentId: context.environmentId,
+      },
+    });
+  }
+
   async loadContentType(cma: PlainClientAPI, entryId: string) {
     return cma.entry.get({ entryId });
   }

examples/function-comment-bot/functions/bot-actions/publish-button-action.ts

@@ -11,10 +11,8 @@ const publicationWidget = {
 export class PublishButtonAction extends BotActionBase implements BotAction {
   async execute(params: BotActionParams): Promise<void> {
     const { commentBody, context, parentEntityId } = params;
-    if (!isManagementContextInvocation(context)) {
-      throw new Error('This action requires the Contentful Management API client to be available');
-    }
-    const { cma } = context;
+
+    const cma = this.initContentfulManagementClient(context);
 
     const contentType = await this.loadContentType(cma, parentEntityId);
     const contentTypeId = contentType.sys.contentType.sys.id;

function-examples/appaction-call/javascript/appaction-call-template.js

@@ -3,16 +3,35 @@
  *
  * This template provides a starting point for creating an App Action function.
  * You'll need to implement your custom logic in the handler function below.
- *
+ */
+
+import { createClient } from 'contentful-management';
+
+function initContentfulManagementClient(context) {
+  if (!context.cmaClientOptions) {
+    throw new Error(
+      'Contentful Management API client options are only provided for certain function types. To learn more about using the CMA within functions, see https://www.contentful.com/developers/docs/extensibility/app-framework/functions/#using-the-cma.'
+    );
+  }
+  return createClient(context.cmaClientOptions, {
+    type: 'plain',
+    defaults: {
+      spaceId: context.spaceId,
+      environmentId: context.environmentId,
+    },
+  });
+}
+
+/**
  * This handler is invoked when your App Action is called
  *
  * @param {Object} event - Contains the parameters passed to your App Action
  * @param {Object} context - Provides access to the CMA client and other context information
  * @returns {Object} The response from your App Action
  */
 export const handler = async (event, context) => {
-  // Access the authenticated CMA client to interact with Contentful
-  const cma = context.cma;
+  // Instantiate an authenticated CMA client to interact with Contentful
+  const cma = initContentfulManagementClient(context);
 
   // Extract parameters from the event body
   // const { paramName } = event.body;

function-examples/appaction-call/typescript/appaction-call-template.ts

@@ -1,9 +1,10 @@
-import {
+import type {
   FunctionEventContext,
   FunctionEventHandler,
   FunctionTypeEnum,
   AppActionRequest,
 } from '@contentful/node-apps-toolkit';
+import { type PlainClientAPI, createClient } from 'contentful-management';
 
 /**
  * App Action Function Template
@@ -21,6 +22,21 @@ type AppActionParameters = {
   // booleanParam: boolean;
 };
 
+function initContentfulManagementClient(context: FunctionEventContext): PlainClientAPI {
+  if (!context.cmaClientOptions) {
+    throw new Error(
+      'Contentful Management API client options are only provided for certain function types. To learn more about using the CMA within functions, see https://www.contentful.com/developers/docs/extensibility/app-framework/functions/#using-the-cma.'
+    );
+  }
+  return createClient(context.cmaClientOptions, {
+    type: 'plain',
+    defaults: {
+      spaceId: context.spaceId,
+      environmentId: context.environmentId,
+    },
+  });
+}
+
 /**
  * This handler is invoked when your App Action is called
  *
@@ -31,8 +47,8 @@ export const handler: FunctionEventHandler<FunctionTypeEnum.AppActionCall> = asy
   event: AppActionRequest<'Custom', AppActionParameters>,
   context: FunctionEventContext
 ) => {
-  // Access the authenticated CMA client to interact with Contentful
-  const cma = context.cma!;
+  // Instantiate an authenticated CMA client to interact with Contentful
+  const cma = initContentfulManagementClient(context);
 
   // Extract parameters from the event body
   // const { paramName } = event.body;