gatsby-attainlabs-cms 1.0.0 → 1.0.1

package/README.md

@@ -1,4 +1,4 @@
-# gatsby-attain-labs-cms
+# gatsby-attainlabs-cms
 
 A Gatsby plugin that downloads and syncs `index.tsx` components from the **Attain Labs CMS** hosted in Azure Repos into your Gatsby project at build time.
 
@@ -6,24 +6,111 @@ This is especially useful for keeping brand-specific and global CMS blocks up to
 
 ---
 
-## Install
+## Installation
 
 ```bash
-npm install gatsby-attain-labs-cms
+npm install gatsby-attainlabs-cms
 ```
 
 ---
 
-## Usage
+## Setup
 
-In your gatsby-config.js, configure the plugin with the brand you want to sync:
+### 1. Add environment variable
 
-```javascript
-{
-      resolve: "gatsby-attain-labs-cms",
+At the root of your Gatsby site, create a `.env.development` and/or `.env.production` file if it doesn’t already exist:
+
+```bash
+touch .env.development
+```
+
+Inside the file, add your Azure DevOps Personal Access Token (PAT):
+
+```
+PERSONAL_ACCESS_TOKEN=xxxxxxxxxxxxxxxx
+```
+
+⚠️ **Do not** prefix this with `GATSBY_`.  
+That prefix exposes variables to the browser bundle, which is not safe for secrets.
+
+---
+
+### 2. Load `.env` in Gatsby
+
+At the top of your `gatsby-config.js`, load dotenv:
+
+```js
+require("dotenv").config({
+  path: `.env.${process.env.NODE_ENV}`,
+});
+```
+
+---
+
+### 3. Configure the plugin in `gatsby-config.js`
+
+```js
+module.exports = {
+  plugins: [
+    {
+      resolve: "gatsby-plugin-your-plugin",
       options: {
-        // Select one: 'LendDirect', 'Cash Money', or 'Heights Finance'
-        brand: "LendDirect",
+        brand: "Cash Money", // LendDirect | Cash Money | Heights Finance adding-puck-for-visual-code-editing
+        // personalAccessToken: "optional-fallback", // not recommended, but supported
       },
     },
+  ],
+};
+```
+
+---
+
+## Behavior
+
+- Downloads brand-specific `index.tsx` components into:
+  - `src/cms/components/brand/`
+  - `src/cms/components/global/`
+
+- Requires an Azure DevOps Personal Access Token (PAT) to authenticate requests.
+
+- If the PAT is missing, the plugin will **warn and skip execution** instead of failing the build.
+
+- If the `brand` option is missing or invalid, the plugin will **throw an error** and stop the build.  
+  Valid values are:
+  - `LendDirect`
+  - `Cash Money`
+  - `Heights Finance`
+
+---
+
+## Troubleshooting
+
+### PAT missing warning
+
+If you see:
+
 ```
+⚠️ [gatsby-plugin-your-plugin] No PERSONAL_ACCESS_TOKEN found...
+```
+
+➡️ Double-check that `.env.development` or `.env.production` exists and is loaded in `gatsby-config.js`.
+
+---
+
+### Invalid brand option
+
+If you see:
+
+```
+[gatsby-plugin-your-plugin] Invalid or missing "brand" option.
+You must specify one of: LendDirect, Cash Money, Heights Finance
+```
+
+➡️ Make sure you pass a valid brand in `gatsby-config.js`.
+
+---
+
+### Token in client code
+
+Don’t use `GATSBY_PERSONAL_ACCESS_TOKEN`. That will leak your secret into the browser bundle.  
+Always use `PERSONAL_ACCESS_TOKEN`.

package/gatsby-node.js

@@ -5,9 +5,20 @@ import "dotenv/config";
 // Load PAT from env instead of hardcoding (fallback to old const for now but warn)
 
 export const onPreInit = async (_, pluginOptions) => {
-  const { brand, azureBranch } = pluginOptions;
-
-  const pat = process.env.GATSBY_PERSONAL_ACCESS_TOKEN;
+  const { brand, azureBranch, personalAccessToken: patOption } = pluginOptions;
+
+  // Try env first, then plugin option fallback
+  const pat = process.env.PERSONAL_ACCESS_TOKEN || patOption;
+
+  if (!pat) {
+    console.warn(
+      "⚠️ [gatsby-plugin-your-plugin] No PERSONAL_ACCESS_TOKEN found. " +
+        "Set it in your project's .env file (recommended) or pass via plugin options.\n" +
+        "Example .env:\n" +
+        "PERSONAL_ACCESS_TOKEN=xxxxxxx\n"
+    );
+    return; // stop execution early
+  }
 
   const brands = {
     LendDirect: "lenddirect",
@@ -15,6 +26,19 @@ export const onPreInit = async (_, pluginOptions) => {
     "Heights Finance": "heightsfinance",
   };
 
+  // 🚨 Validate brand option
+  if (!brand || !brands[brand]) {
+    throw new Error(
+      `[gatsby-plugin-your-plugin] Invalid or missing "brand" option.\n` +
+        `You must specify one of: ${Object.keys(brands).join(", ")}\n` +
+        `Example:\n` +
+        `{\n` +
+        `  resolve: "gatsby-plugin-your-plugin",\n` +
+        `  options: { brand: "Cash Money" }\n` +
+        `}`
+    );
+  }
+
   const org = "CuroFinTech";
   const project = "Marketing";
   const repo = "Attain Labs";
@@ -144,5 +168,3 @@ export const onPreInit = async (_, pluginOptions) => {
     doRequest(fileUrl);
   }
 };
-
-onPreInit({}, { brand: "LendDirect" }); // For testing purposes, remove when done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gatsby-attainlabs-cms",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "gatsby-node.js",
   "type": "module",
   "scripts": {