src: add and delete file webhooks when designs are attached or removed (#260)

* Add file webhook repository and types

* install figma rest api spec

* Create file webhooks for a design when it's linked

* delete file webhooks on disassociate or app uninstall

* update tests

* fix integration test request

* don't throw errors if creating file webhook fails from user perms

* add tests for disassociated use case

* simplify FigmaFileWebhook class into a type

* split webhook creation into two to avoid dangling webhooks

Author: Isaiah-Turner

package-lock.json

@@ -33,6 +33,7 @@
 		"test:unit": "DOTENV_CONFIG_PATH=.env.test jest -c jest.config.unit.ts"
 	},
 	"dependencies": {
+		"@figma/rest-api-spec": "^0.33.0",
 		"@prisma/client": "^5.1.1",
 		"ajv": "^8.12.0",
 		"atlassian-jwt": "^2.0.2",

package.json

@@ -0,0 +1,27 @@
+export enum FigmaFileWebhookEventType {
+	FILE_UPDATE = 'FILE_UPDATE',
+	DEV_MODE_STATUS_UPDATE = 'DEV_MODE_STATUS_UPDATE',
+}
+
+export type FigmaFileWebhook = {
+	readonly id: string;
+	readonly webhookId: string;
+	readonly webhookPasscode: string;
+	readonly fileKey: string;
+	readonly eventType: FigmaFileWebhookEventType;
+	readonly createdBy: {
+		readonly atlassianUserId: string;
+		readonly connectInstallationId: string;
+	};
+};
+
+export type FigmaFileWebhookCreateParams = {
+	readonly webhookId: string;
+	readonly webhookPasscode: string;
+	readonly fileKey: string;
+	readonly eventType: FigmaFileWebhookEventType;
+	readonly createdBy: {
+		readonly atlassianUserId: string;
+		readonly connectInstallationId: string;
+	};
+};

src/domain/entities/figma-file-webhook.ts

@@ -7,3 +7,4 @@ export * from './figma-oauth2-user-credentials';
 export * from './figma-team';
 export * from './figma-user';
 export * from './jira-issue';
+export * from './figma-file-webhook';

src/domain/entities/index.ts

@@ -7,6 +7,7 @@ import type {
 	ConnectInstallation,
 	ConnectInstallationCreateParams,
 	ConnectUserInfo,
+	FigmaFileWebhook,
 	FigmaOAuth2UserCredentialsCreateParams,
 	FigmaTeamCreateParams,
 	FigmaTeamSummary,
@@ -16,6 +17,7 @@ import {
 	AtlassianDesignStatus,
 	AtlassianDesignType,
 	FigmaDesignIdentifier,
+	FigmaFileWebhookEventType,
 	FigmaOAuth2UserCredentials,
 	FigmaTeam,
 	FigmaTeamAuthStatus,
@@ -271,3 +273,24 @@ export const generateFigmaTeamSummary = ({
 	teamName,
 	authStatus: status,
 });
+
+export const generateFigmaFileWebhook = ({
+	id = generateNumericStringId(),
+	webhookId = uuidv4(),
+	webhookPasscode = uuidv4(),
+	fileKey = generateFigmaFileKey(),
+	eventType = FigmaFileWebhookEventType.FILE_UPDATE,
+	createdBy = {
+		atlassianUserId: uuidv4(),
+		connectInstallationId: generateNumericStringId(),
+	},
+}: Partial<FigmaFileWebhook> = {}): FigmaFileWebhook => {
+	return {
+		id,
+		webhookId,
+		webhookPasscode,
+		fileKey,
+		eventType,
+		createdBy,
+	};
+};

src/domain/entities/testing/mocks.ts

@@ -1,3 +1,7 @@
+import type {
+	PostWebhookRequestBody,
+	PostWebhookResponse,
+} from '@figma/rest-api-spec';
 import axios from 'axios';
 import { withParser } from 'stream-json/filters/Filter';
 import { streamValues } from 'stream-json/streamers/StreamValues';
@@ -6,20 +10,18 @@ import type { Stream } from 'stream';
 
 import {
 	CREATE_DEV_RESOURCE_RESPONSE_SCHEMA,
-	CREATE_WEBHOOK_RESPONSE,
 	GET_DEV_RESOURCE_RESPONSE_SCHEMA,
 	GET_FILE_META_RESPONSE_SCHEMA,
 	GET_FILE_RESPONSE_SCHEMA,
 	GET_ME_RESPONSE_SCHEMA,
 	GET_OAUTH2_TOKEN_RESPONSE_SCHEMA,
 	GET_TEAM_PROJECTS_RESPONSE_SCHEMA,
+	POST_WEBHOOK_RESPONSE_SCHEMA,
 	REFRESH_OAUTH2_TOKEN_RESPONSE_SCHEMA,
 } from './schemas';
 import type {
 	CreateDevResourcesRequest,
 	CreateDevResourcesResponse,
-	CreateWebhookRequest,
-	CreateWebhookResponse,
 	DeleteDevResourceRequest,
 	GetDevResourcesRequest,
 	GetDevResourcesResponse,
@@ -377,9 +379,9 @@ export class FigmaClient {
 	 * @throws {HttpClientError} An error associated with specific HTTP response status codes.
 	 */
 	createWebhook = async (
-		request: CreateWebhookRequest,
+		request: PostWebhookRequestBody,
 		accessToken: string,
-	): Promise<CreateWebhookResponse> =>
+	): Promise<PostWebhookResponse> =>
 		withAxiosErrorTranslation(async () => {
 			const url = new URL(`v2/webhooks`, getConfig().figma.apiBaseUrl);
 
@@ -389,7 +391,7 @@ export class FigmaClient {
 				},
 			});
 
-			assertSchema(response.data, CREATE_WEBHOOK_RESPONSE);
+			assertSchema(response.data, POST_WEBHOOK_RESPONSE_SCHEMA);
 
 			return response.data;
 		});

src/infrastructure/figma/figma-client/figma-client.ts

@@ -2,9 +2,10 @@
  * Contains JSON schema definitions for Figma API responses. Used for validating the types of incoming data on the entry
  * points to the application.
  */
+import type { PostWebhookResponse } from '@figma/rest-api-spec';
+
 import type {
 	CreateDevResourcesResponse,
-	CreateWebhookResponse,
 	DevResource,
 	ErrorResponse,
 	GetDevResourcesResponse,
@@ -166,30 +167,34 @@ export const GET_DEV_RESOURCE_RESPONSE_SCHEMA: JSONSchemaTypeWithId<GetDevResour
 		required: ['dev_resources'],
 	};
 
-export const CREATE_WEBHOOK_RESPONSE: JSONSchemaTypeWithId<CreateWebhookResponse> =
+export const POST_WEBHOOK_RESPONSE_SCHEMA: JSONSchemaTypeWithId<PostWebhookResponse> =
 	{
 		$id: 'figma-api:post:v2/webhooks:response',
 		type: 'object',
 		properties: {
 			id: { type: 'string' },
 			team_id: { type: 'string' },
-			event_type: { type: 'string' },
+			event_type: { type: 'string' }, // This should match WebhookV2Event type
+			context: { type: 'string' },
+			context_id: { type: 'string' },
+			plan_api_id: { type: 'string' },
 			client_id: { type: 'string' },
 			endpoint: { type: 'string' },
 			passcode: { type: 'string' },
 			status: { type: 'string' },
 			description: { type: 'string' },
-			protocol_version: { type: 'string' },
 		},
 		required: [
 			'id',
 			'team_id',
+			'context',
+			'context_id',
+			'plan_api_id',
 			'event_type',
 			'client_id',
 			'endpoint',
 			'passcode',
 			'status',
-			'protocol_version',
 		],
 	};
 

src/infrastructure/figma/figma-client/schemas.ts

@@ -1,10 +1,14 @@
+import type {
+	PostWebhookResponse,
+	WebhookV2Event,
+	WebhookV2Status,
+} from '@figma/rest-api-spec';
 import { v4 as uuidv4 } from 'uuid';
 
 import type {
 	CreateDevResourceError,
 	CreateDevResourcesRequest,
 	CreateDevResourcesResponse,
-	CreateWebhookResponse,
 	GetDevResourcesResponse,
 	GetFileMetaResponse,
 	GetFileResponse,
@@ -215,23 +219,26 @@ export const generateEmptyDevResourcesResponse =
 export const generateCreateWebhookResponse = ({
 	id = uuidv4(),
 	teamId = uuidv4(),
-	eventType = 'FILE_UPDATE',
+	planApiId = `organization:${uuidv4()}`,
+	context = 'team',
+	eventType = 'FILE_UPDATE' as WebhookV2Event,
 	clientId = uuidv4(),
 	endpoint = `https://figma-for-jira.atlassian.com/figma/webhooks`,
 	passcode = uuidv4(),
-	status = 'ACTIVE',
+	status = 'ACTIVE' as WebhookV2Status,
 	description = 'Figma for Jira',
-	protocolVersion = '2',
-} = {}): CreateWebhookResponse => ({
+} = {}): PostWebhookResponse => ({
 	id: id,
 	team_id: teamId,
+	context: context,
+	context_id: teamId,
 	event_type: eventType,
 	client_id: clientId,
 	endpoint,
 	passcode,
 	status,
 	description,
-	protocol_version: protocolVersion,
+	plan_api_id: planApiId,
 });
 
 export const generateGetTeamProjectsResponse = ({

src/infrastructure/figma/figma-client/testing/mocks.ts

@@ -102,27 +102,6 @@ export type DeleteDevResourceRequest = {
 	readonly accessToken: string;
 };
 
-export type CreateWebhookRequest = {
-	readonly event_type: string;
-	readonly team_id: string;
-	readonly endpoint: string;
-	readonly passcode: string;
-	readonly status?: string;
-	readonly description?: string;
-};
-
-export type CreateWebhookResponse = {
-	readonly id: string;
-	readonly team_id: string;
-	readonly event_type: string;
-	readonly client_id: string;
-	readonly endpoint: string;
-	readonly passcode: string;
-	readonly status: string;
-	readonly description: string | null;
-	readonly protocol_version: string;
-};
-
 export type GetTeamProjectsResponse = {
 	readonly name: string;
 	readonly projects: {