New Real Estate integration demo 🏠 (#17)

Author: Anto Lepejian

.gitignore

@@ -10,3 +10,9 @@ dist
 openapi-ts-error-*.log
 **/*/db.json
 **/public/exports
+.venv
+.ruff_cache
+.pytest_cache
+__pycache__
+database.db
+.claude

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2025-07-07
+
+### 🧰 Added
+
+- Added a new real estate integration demo in `demos/realty`.
+
+### 🐞 Fixed
+
+- Several typos in the documentation.
+
+### 🔧 Changed
+
+- Upgraded `webpack-dev-server` to version `5.2.2` from `5.2.0`.
+- Updated Brand Template selector components to display Brand Templates download link more prominently.
+
+### 🗑️ Removed
+
+- Removed the `--ngrok` flag which is not required, but could potentially cause issues if certain environment variables are set.
+
 ## 2025-05-15
 
 ### 🐞 Fixed
@@ -12,7 +31,7 @@
 - Refreshed the OpenAPI yml spec `openapi/spec.yml` to be based on the latest Connect API design.
 - Patch and minor version changes to package dependencies in the `ecommerce_shop` and `playground` demos.
 - Moved `webpack.config.cjs` to `webpack.config.ts` for type checking.
-- Updated file name casing to be consistent, and added an elint rule to enforce this
+- Updated file name casing to be consistent, and added an eslint rule to enforce this
 - Updated `eslint`, `eslint-plugin-unicorn`, and `typescript-eslint`.
 
 ## 2024-12-19
@@ -21,7 +40,7 @@
 
 - Both demo projects now take advantage of the CORS support for the Connect API and make most requests directly from the frontend code
 - Updated HeyAPI to version 0.5, and TypeScript to version 5.5
-- Dependencies are now pinned to exact versions to reduce accidental incompatabilities
+- Dependencies are now pinned to exact versions to reduce accidental incompatibilities
 - Refreshed the OpenAPI yml spec `openapi/spec.yml` to be based on the latest Connect API design
 
 ## 2024-09-23

README.md

@@ -15,7 +15,7 @@ This repo contains our openAPI specifications, as well as a demo ecommerce web a
 
 The Canva Connect API doesn't maintain nor publish client SDKs, however, we have made our [OpenAPI spec](./openapi/spec.yml) publicly available, so you can use it with your favorite code generation library, such as [openapi-generator](https://github.com/OpenAPITools/openapi-generator) to generate client SDKs in your language of choice!
 
-To demonstrate this, we're using [openapi-ts](https://www.npmjs.com/package/@hey-api/openapi-ts) to generate TypeScript SDKs in [client/ts](./client//ts/) which is used in our demo app.
+To demonstrate this, we're using [openapi-ts](https://www.npmjs.com/package/@hey-api/openapi-ts) to generate TypeScript SDKs in [client/ts](./client/ts/) which is used in our demo app.
 
 ## Demos: E-commerce Shop
 
@@ -63,7 +63,7 @@ cd demos/ecommerce_shop
 
 2. Add your integration settings to the `demos/ecommerce_shop/.env` file.
 
-- `DATABASE_ENCRYPTION_KEY`: This will encrypt and decrypt the tokens stored in the JSON database. A key is automatically get generated for you after running `npm install`, and will already be set in `.env`. If not, run `npm run generate:db-key` from the `demos/ecommerce_shop` directory.
+- `DATABASE_ENCRYPTION_KEY`: This will encrypt and decrypt the tokens stored in the JSON database. A key is automatically generated for you after running `npm install`, and will already be set in `.env`. If not, run `npm run generate:db-key` from the `demos/ecommerce_shop` directory.
 - `CANVA_CLIENT_ID`: This is the `Client ID` from the prerequisites.
 - `CANVA_CLIENT_SECRET`: This is the `client secret` you generated in the prerequisites.
 
@@ -78,6 +78,75 @@ npm start
 
 4. View your app: [http://127.0.0.1:3000](http://127.0.0.1:3000)
 
+### Brand Templates Setup
+
+To get started with Brand Templates in the e-commerce demo, you can install sample templates from [this Brand Template deck](https://www.canva.com/design/DAGGkcb61HQ/OJhMIQrmz2daIoxo8u3T2g/view).
+
+## Demos: Real-estate demo
+
+### Prerequisites
+
+Before you can run this demo, you'll need to do some setup beforehand.
+
+1. Open the [Developer Portal](https://www.canva.com/developers/integrations/connect-api), and click `Create an integration`.
+
+2. Under `Configuration` → `Configure your integration`.
+
+- `Integration name`: Add a name.
+- `Client ID`: Make a note of this value; you'll need it in a later step.
+- `Generate secret`: Click this and save the secret in a secure location, as you'll need it for a later step.
+
+3. Under `Scopes` → `Set the scopes`, check the following boxes:
+
+- `asset`: Read and Write.
+- `brandtemplate:content`: Read.
+- `brandtemplate:meta`: Read.
+- `design:content`: Read and Write.
+- `design:meta`: Read.
+- `profile`: Read.
+
+4. Under `Authentication` → `Add Authentication`, locate `URL 1` and enter the following value:
+
+```
+http://127.0.0.1:3001/oauth/redirect
+```
+
+5. Under `Return navigation`, toggle on the `Enable return navigation` switch and enter the following as the `Return Url`:
+
+```
+http://127.0.0.1:3001/return-nav
+```
+
+### How to run
+
+1. Install dependencies
+
+```bash
+npm install
+cd demos/realty
+```
+
+2. Add your integration settings to the `demos/realty/.env` file.
+
+- `DATABASE_ENCRYPTION_KEY`: This will encrypt and decrypt the tokens stored in the JSON database. A key is automatically generated for you after running `npm install`, and will already be set in `.env`. If not, run `npm run generate:db-key` from the `demos/realty` directory.
+- `CANVA_CLIENT_ID`: This is the `Client ID` from the prerequisites.
+- `CANVA_CLIENT_SECRET`: This is the `client secret` you generated in the prerequisites.
+
+3. Run the app
+
+```bash
+npm start
+```
+
+> [!WARNING]
+> Accessing the app via `localhost:3000` will throw CORS errors, you must access the app via the below URL.
+
+4. View your app: [http://127.0.0.1:3000](http://127.0.0.1:3000)
+
+### Brand Templates Setup
+
+To get started with Brand Templates in the real estate demo, you can install sample templates from [this Brand Template deck](https://www.canva.com/design/DAGGkcb61HQ/OJhMIQrmz2daIoxo8u3T2g/view).
+
 ## Demos: Connect API Playground
 
 ### Prerequisites
@@ -113,7 +182,7 @@ cd demos/playground
 
 2. Add your integration settings to the `demos/playground/.env` file.
 
-- `DATABASE_ENCRYPTION_KEY`: This will encrypt and decrypt the tokens stored in the JSON database. A key is automatically get generated for you after running `npm install`, and will aready be set in `.env`.
+- `DATABASE_ENCRYPTION_KEY`: This will encrypt and decrypt the tokens stored in the JSON database. A key is automatically generated for you after running `npm install`, and will already be set in `.env`.
 - `CANVA_CLIENT_ID`: This is the `Client ID` from the prerequisites.
 - `CANVA_CLIENT_SECRET`: This is the `client secret` you generated in the prerequisites.
 

demos/common/package.json

@@ -17,23 +17,22 @@
   "type": "commonjs",
   "dependencies": {
     "@canva/connect-api-ts": "file:../../client/ts",
-    "@ngrok/ngrok": "1.4.1",
     "@types/jest": "29.5.14",
     "chalk": "4.1.2",
     "cli-table3": "0.6.5",
     "cookie-parser": "1.4.7",
     "cors": "2.8.5",
     "dotenv": "16.4.7",
-    "jest": "29.7.0",
-    "ts-jest": "29.2.5",
     "envfile": "7.1.0",
     "express": "4.21.2",
+    "jest": "29.7.0",
     "jose": "5.9.6",
     "nodemon": "3.0.1",
     "open": "10.1.0",
     "pug": "3.0.3",
+    "ts-jest": "29.2.5",
     "webpack-cli": "5.1.4",
-    "webpack-dev-server": "5.2.0",
+    "webpack-dev-server": "5.2.2",
     "yargs": "17.7.2"
   },
   "devDependencies": {

demos/common/scripts/app-runner.ts

@@ -1,7 +1,6 @@
 import { Context } from "./context";
 import * as chalk from "chalk";
 import * as Table from "cli-table3";
-import * as ngrok from "@ngrok/ngrok";
 import * as webpack from "webpack";
 import * as WebpackDevServer from "webpack-dev-server";
 import * as nodemon from "nodemon";
@@ -53,31 +52,7 @@ export class AppRunner {
       });
     });
 
-    if (ctx.ngrokEnabled) {
-      console.log(
-        warnChalk("Warning:"),
-        `ngrok exposes a local port via a public URL. Be mindful of what's exposed and shut down the server when it's not in use.\n`,
-      );
-    }
-
-    let url = ctx.backendUrl;
-    if (ctx.ngrokEnabled) {
-      try {
-        const ngrokListener = await ngrok.forward({
-          addr: ctx.backendPort,
-          // requires an `NGROK_AUTHTOKEN` env var to be set
-          authtoken_from_env: true,
-        });
-        url = ngrokListener.url() ?? url;
-      } catch (err) {
-        console.log(
-          errorChalk("Error:"),
-          `Unable to start ngrok server: ${err}`,
-        );
-      }
-    }
-
-    table.push(["Base URL (Backend)", linkChalk(url)]);
+    table.push(["Base URL (Backend)", linkChalk(ctx.backendUrl)]);
   };
 
   private readonly runWebpackDevServer = async (

demos/common/scripts/context.ts

@@ -1,16 +1,8 @@
 import * as fs from "fs";
 import * as path from "path";
 
-type CliArgs = {
-  example?: string;
-  ngrok?: boolean;
-};
-
 export class Context {
-  constructor(
-    private readonly args: CliArgs,
-    private readonly rootDir: string,
-  ) {}
+  constructor(private readonly rootDir: string) {}
 
   get srcDir() {
     const src = path.join(this.rootDir, "frontend", "src");
@@ -32,10 +24,6 @@ export class Context {
     return index;
   }
 
-  get ngrokEnabled() {
-    return !!this.args.ngrok;
-  }
-
   get frontendUrl(): string {
     return process.env.FRONTEND_URL!;
   }

demos/ecommerce_shop/README.md

@@ -10,6 +10,8 @@ A lightweight e-commerce shop demo that showcases how to integrate with the Canv
 - Creating individual designs in custom sizes from existing products.
 - Create multiple designs at once by adding products to your Canva Brand Templates.
 
-For **setup instructions** refer to the steps in the main README:
+## Brand Templates Setup
 
-<https://github.com/canva-sdks/canva-connect-api-starter-kit/blob/main/README.md#demos-e-commerce-shop>
+To get started with Brand Templates, you can install sample templates from [this Brand Template deck](https://www.canva.com/design/DAGGkcb61HQ/OJhMIQrmz2daIoxo8u3T2g/view).
+
+[See the main README for e-commerce shop demo instructions](../../README.md#demos-e-commerce-shop)

demos/ecommerce_shop/frontend/package.json

@@ -43,6 +43,6 @@
     "ts-loader": "9.5.2",
     "typescript": "5.5.4",
     "url-loader": "4.1.1",
-    "webpack-dev-server": "5.2.0"
+    "webpack-dev-server": "5.2.2"
   }
 }

demos/ecommerce_shop/frontend/src/components/marketing/brand-template-selector.tsx

@@ -56,13 +56,31 @@ export const BrandTemplateSelector = ({
         <Grid item={true} xs={12}>
           <Grid container={true} spacing={2}>
             <Grid item={true} xs={12} sm={7} md={9}>
-              <Typography variant="h5">Select brand template</Typography>
+              <Typography variant="h5">Select Brand Template</Typography>
             </Grid>
             <Grid item={true} xs={12} sm={5} md={3}>
-              <DeveloperNote info="Brand templates are only available to Canva Enterprise users." />
+              <DeveloperNote info="Brand Templates are only available to Canva Enterprise users." />
             </Grid>
           </Grid>
         </Grid>
+        <Grid item={true} xs={12}>
+          <Paper
+            variant="outlined"
+            sx={{ padding: 2, bgcolor: "background.default" }}
+          >
+            <Typography variant="body2" color="text.secondary">
+              Need sample Brand Templates? Install them from{" "}
+              <Link
+                href="https://www.canva.com/design/DAGGkcb61HQ/OJhMIQrmz2daIoxo8u3T2g/view"
+                target="_blank"
+                rel="noopener noreferrer"
+              >
+                this Brand Template deck
+              </Link>
+              .
+            </Typography>
+          </Paper>
+        </Grid>
         {!brandTemplates.length ? (
           <EmptyState onClose={onClose} />
         ) : (
@@ -119,17 +137,10 @@ const EmptyState = ({ onClose }: { onClose: () => void }) => (
       gap={3}
     >
       <Stack spacing={2}>
-        <Typography variant="h6">Don’t see any brand templates?</Typography>
+        <Typography variant="h6">Don’t see any Brand Templates?</Typography>
         <Typography variant="body1">
-          Follow the instructions{" "}
-          <Link
-            href="https://www.canva.com/design/DAGGkcb61HQ/OJhMIQrmz2daIoxo8u3T2g/view"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            here
-          </Link>{" "}
-          to install sample templates to your brand folder.
+          Check the help section above for instructions on installing sample
+          templates.
         </Typography>
         <Box>
           <DemoButton

demos/ecommerce_shop/package.json

@@ -32,7 +32,6 @@
   },
   "devDependencies": {
     "@eslint/js": "9.23.0",
-    "@ngrok/ngrok": "1.4.1",
     "@types/cookie-parser": "1.4.8",
     "@types/jest": "29.5.14",
     "@types/node": "20.10.0",
@@ -56,7 +55,7 @@
     "typescript": "5.5.4",
     "typescript-eslint": "8.27.0",
     "webpack-cli": "5.1.4",
-    "webpack-dev-server": "5.2.0",
+    "webpack-dev-server": "5.2.2",
     "yargs": "17.7.2"
   }
 }