Setup scripts for managing spaces and app defns [INTEG-2837] (#9950)

* space setup scripts

* separate appDef for staging and production apps

* feat: pull variables from .env file

* refactor: converting files to ts

* fix: .npmrc file

* feat: merge complete

* fix: linting

* fix: unused import, backticks instead of concatenation

* refactor: improve team space membership checks

* feat: add teardown functionality for cleanup after setup

* feat: add example environment variables

* refactor: moving dependencies to scripts folder

* docs: update README with environment variable setup

* feat: add TypeScript support

* docs: update README with teardown function instructions and testing details

---------

Co-authored-by: ryunsong-contentful <ryun.song@contentful.com>

Author: harikakondur

.npmrc

@@ -1 +1,2 @@
 engine-strict = true
+@contentful:registry=https://registry.npmjs.org

package-lock.json

@@ -1,12 +1,14 @@
 {
   "name": "@contentful/apps",
   "private": true,
+  "type": "module",
   "engines": {
     "node": ">=16.0.0",
     "npm": ">=8.0.0"
   },
   "devDependencies": {
     "@sentry/cli": "^2.14.4",
+    "@types/node": "^24.0.13",
     "eslint": "^7.32.0",
     "husky": "^8.0.0",
     "lint-staged": "^13.0.0",

package.json

@@ -0,0 +1,4 @@
+CONTENTFUL_ACCESS_TOKEN =
+CONTENTFUL_ORGANIZATION_ID  = 
+CONTENTFUL_TEAM_ID =
+CONTENTFUL_APP_NAME = 

scripts/.env-example

@@ -0,0 +1,124 @@
+# Contentful Space Setup Script
+
+This script automates the complete setup of Contentful spaces for your app, including app definition creation, space creation, team assignments, and app installations.
+
+## What This Script Does
+
+1. **Creates App Definitions** (staging and production) in your Contentful organization
+2. **Creates Two Spaces**: Production and Staging environments
+3. **Assigns Teams** to both spaces with admin privileges
+4. **Installs the App** in both spaces
+5. **Provides Configuration Links** to finish app setup
+
+## ⚙️ Configuration
+
+### Environment Variables Setup
+
+1. **Copy the example environment file:**
+
+   ```bash
+   cp .env-example .env
+   ```
+
+2. **Fill in your Contentful credentials in `.env`:**
+   ```bash
+   CONTENTFUL_ACCESS_TOKEN=your_access_token_here
+   CONTENTFUL_ORGANIZATION_ID=your_org_id_here
+   CONTENTFUL_TEAM_ID=your_team_id_here
+   CONTENTFUL_APP_NAME=Your App Name
+   CONTENTFUL_ENVIRONMENT=master
+   ```
+
+### 🔑 How to Get Required IDs
+
+#### Access Token (Content Management API)
+
+1. Go to [Contentful Web App](https://app.contentful.com)
+2. Navigate to Settings → API keys → Content management tokens
+3. Generate a new personal access token
+4. Copy the token to `CONTENTFUL_ACCESS_TOKEN` in your `.env` file
+
+#### Organization ID
+
+1. In Contentful, go to your organization settings
+2. The organization ID is in the URL: `app.contentful.com/account/organizations/{ORGANIZATION_ID}`
+3. Copy this ID to `CONTENTFUL_ORGANIZATION_ID` in your `.env` file
+
+#### Team ID
+
+1. Go to Settings → Teams
+2. Click on the team you want to assign
+3. The team ID is in the URL: `app.contentful.com/account/organizations/{ORG_ID}/teams/{TEAM_ID}`
+4. Copy this ID to `CONTENTFUL_TEAM_ID` in your `.env` file
+
+## Testing
+
+### Teardown Function
+
+For testing purposes, the script includes a teardown function that completely removes all created resources.
+
+#### How to Enable Teardown
+
+1. **Uncomment the teardown section** at the bottom of the file `scripts/setup.ts`:
+
+   ```typescript
+   // FOR TESTING - uncomment to undo setup
+   await teardown({
+     client,
+     organizationId,
+     spaceIdStaging: stagingSpace.sys.id,
+     spaceIdProduction: productionSpace.sys.id,
+     appDefinitionIdStaging: appDefinitionStaging.sys.id,
+     appDefinitionIdProduction: appDefinitionProduction.sys.id,
+   });
+   ```
+
+2. **Run the setup script** as normal:
+   ```bash
+   npm run setup
+   ```
+
+## How to Run
+
+1. **Navigate to the scripts directory:**
+
+   ```bash
+   cd scripts
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   npm install
+   ```
+
+3. **Configure your `.env` file** (see Configuration section above)
+
+4. **Run the setup script:**
+   ```bash
+   npm run setup
+   ```
+
+## What Gets Created
+
+### App Definitions
+
+- **Staging**: `{appName} (staging)`
+- **Production**: `{appName} (production)`
+- **Location**: Your Contentful organization
+- **Status**: Created but needs configuration
+
+### Spaces
+
+- **Production**: `{appName} (production)`
+- **Staging**: `{appName} (staging)`
+- **Team Access**: Admin privileges for all members in specified team
+- **App Installation**: Your app installed in both spaces
+
+## 📝 Next Steps
+
+After running the script successfully:
+
+1. **Configure your app definitions** using the provided links
+2. **Set up app locations** (entry field, page, etc.)
+3. **Configure app parameters** if needed

scripts/README.md

@@ -0,0 +1,41 @@
+import { createCMAClient } from './createCMAClient.ts';
+
+interface AddTeamToSpaceProps {
+  client?: any;
+  spaceId: string;
+  teamId: string;
+}
+
+export async function addTeamToSpace({ client, spaceId, teamId }: AddTeamToSpaceProps) {
+  try {
+    if (!client) {
+      client = await createCMAClient();
+    }
+    const space = await client.getSpace(spaceId);
+
+    // Check if team already has access
+    const existingMemberships = await space.getTeamSpaceMemberships();
+    const teamHasSpaceAccess = existingMemberships.items.some(
+      (membership) => membership.sys.team.sys.id === teamId
+    );
+
+    if (teamHasSpaceAccess) {
+      console.log(`👥 Team already has access to space - no action taken.`);
+      return;
+    }
+
+    // Create team space membership with admin privileges
+    const teamSpaceMembership = await space.createTeamSpaceMembership(teamId, {
+      admin: true,
+      roles: [],
+    });
+
+    console.log(
+      `\n👥 Team assigned to space ${space.name} (${space.sys.id}) successfully: ${teamSpaceMembership.sys.id}`
+    );
+    return teamSpaceMembership;
+  } catch (error) {
+    console.error(`❌ Failed to assign team to space: ${error.message}`);
+    throw error;
+  }
+}

scripts/actions/addTeamToSpace.ts

@@ -0,0 +1,27 @@
+import { createCMAClient } from './createCMAClient.ts';
+interface CreateAppDefinitionProps {
+  client?: any;
+  organizationId: string;
+  appName: string;
+}
+
+export async function createAppDefinition({
+  client,
+  organizationId,
+  appName,
+}: CreateAppDefinitionProps) {
+  if (!client) {
+    client = await createCMAClient();
+  }
+
+  const organization = await client.getOrganization(organizationId);
+  const appDefinition = await organization.createAppDefinition({
+    name: appName,
+  });
+
+  console.log(
+    `\n🚀 App definition created: ${appDefinition.name} (${appDefinition.sys.id}) in organization: ${organization.name} (${organization.sys.id})`
+  );
+
+  return appDefinition;
+}

scripts/actions/createAppDefinition.ts

@@ -0,0 +1,13 @@
+import contentful from 'contentful-management';
+
+export async function createCMAClient() {
+  if (!process.env.CONTENTFUL_ACCESS_TOKEN) {
+    throw new Error('Cannot find CMA token');
+  }
+
+  const client = contentful.createClient({
+    accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
+  });
+
+  return client;
+}

scripts/actions/createCMAClient.ts

@@ -0,0 +1,19 @@
+import { createCMAClient } from './createCMAClient.ts';
+
+interface CreateSpaceOptions {
+  client?: any;
+  organizationId: string;
+  spaceName: string;
+}
+
+export async function createSpace({ client, organizationId, spaceName }: CreateSpaceOptions) {
+  if (!client) {
+    client = await createCMAClient();
+  }
+
+  const space = await client.createSpace({ name: spaceName }, organizationId);
+
+  console.log(`\n🌐 Space created! Name: ${space.name}, ID: ${space.sys.id}`);
+
+  return space;
+}

scripts/actions/createSpace.ts

@@ -0,0 +1,24 @@
+import { createCMAClient } from './createCMAClient.ts';
+
+interface DeleteAppDefinitionProps {
+  client?: any;
+  organizationId: string;
+  appDefinitionId: string;
+}
+
+export async function deleteAppDefinition({
+  client,
+  organizationId,
+  appDefinitionId,
+}: DeleteAppDefinitionProps) {
+  if (!client) {
+    client = await createCMAClient();
+  }
+
+  const org = await client.getOrganization(organizationId);
+  const appDefinition = await org.getAppDefinition(appDefinitionId);
+
+  await appDefinition.delete();
+
+  console.log(`\n🗑️  AppDefinition '${appDefinitionId}' deleted successfully!`);
+}