buildfree 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# BuildFree SDK
+
+BuildFree is a simple Node.js SDK that lets you connect your application to the BuildFree CMS API and use your CMS data anywhere.
+
+[buildfree.dev](https://buildfree.dev)
+
+---
+
+## Installation
+
+```bash
+npm install buildfree
+```
+
+## Quick Start
+
+```javascript
+const { BuildFree } = require("buildfree");
+
+const buildfree = new BuildFree({
+  apiKey: "cms_live_your_api_key"
+});
+```
+
+---
+
+## Records
+
+### Get all records
+
+```javascript
+const products = await buildfree.getRecords({
+  projectSlug: "my-project",
+  collectionSlug: "products"
+});
+```
+
+### Get one record
+
+```javascript
+const product = await buildfree.getRecord({
+  projectSlug: "my-project",
+  collectionSlug: "products",
+  recordId: "record-id"
+});
+```
+
+---
+
+## Forms
+
+### Get a form
+
+```javascript
+const form = await buildfree.getForm({
+  projectSlug: "my-project",
+  formSlug: "contact-form"
+});
+```
+
+### Submit a form
+
+```javascript
+const result = await buildfree.submitForm({
+  projectSlug: "my-project",
+  formSlug: "contact-form",
+  data: {
+    name: "John",
+    email: "john@example.com",
+    message: "Hello!"
+  }
+});
+```
+
+---
+
+## File Upload
+
+Forms also support file uploads:
+
+```javascript
+const result = await buildfree.submitForm({
+  projectSlug: "my-project",
+  formSlug: "application-form",
+
+  data: {
+    name: "John"
+  },
+
+  files: [
+    {
+      fieldname: "resume",
+      path: "./resume.pdf"
+    }
+  ]
+});
+```
+
+---
+
+## API Key
+
+Your API key must start with:
+
+```text
+cms_live_
+```
+
+> Keep your API key secure and use environment variables in production.
+
+---
+
+## Available Methods
+
+```text
+buildfree.getRecords()
+buildfree.getRecord()
+
+buildfree.getForm()
+buildfree.submitForm()
+```
+
+---
+
+**BuildFree** — Build your API. Use it anywhere.
+
+[buildfree.dev](https://buildfree.dev)

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "buildfree",
+  "version": "1.0.0",
+  "description": "Official JavaScript SDK for buildfree",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node src/index.js",
+    "dev": ""
+  },
+  "keywords": [],
+  "author": "BuildFree",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.20.0",
+    "nodemon": "^3.1.14"
+  }
+}

package/src/forms.js

@@ -0,0 +1,327 @@
+const axios = require("axios");
+const FormData = require("form-data");
+const fs = require("fs");
+
+class Forms {
+
+  constructor({
+    apiKey,
+    baseURL
+  }) {
+
+    this.client = axios.create({
+
+      baseURL,
+
+      timeout: 10000,
+
+      headers: {
+        "x-api-key": apiKey,
+        "Accept": "application/json"
+      }
+
+    });
+
+  }
+
+
+  // ==========================================================
+  // GET FORM
+  // ==========================================================
+
+  async getOne({
+    projectSlug,
+    formSlug
+  } = {}) {
+
+    // ==========================================
+    // VALIDATION
+    // ==========================================
+
+    if (!projectSlug) {
+      throw new Error("projectSlug is required");
+    }
+
+    if (!formSlug) {
+      throw new Error("formSlug is required");
+    }
+
+
+    // ==========================================
+    // REQUEST
+    // ==========================================
+
+    try {
+
+      const response = await this.client.get(
+
+        `/public/${encodeURIComponent(projectSlug)}/forms/${encodeURIComponent(formSlug)}`
+
+      );
+
+      return response.data;
+
+    } catch (error) {
+
+      this.handleError(error);
+
+    }
+
+  }
+
+
+  // ==========================================================
+  // SUBMIT FORM
+  // ==========================================================
+
+  async submit({
+    projectSlug,
+    formSlug,
+    data = {},
+    files = []
+  } = {}) {
+
+    // ==========================================
+    // VALIDATION
+    // ==========================================
+
+    if (!projectSlug) {
+      throw new Error("projectSlug is required");
+    }
+
+    if (!formSlug) {
+      throw new Error("formSlug is required");
+    }
+
+
+    try {
+
+      // ========================================================
+      // NORMAL JSON REQUEST
+      // ========================================================
+
+      if (!files || files.length === 0) {
+
+        const response = await this.client.post(
+
+          `/public/${encodeURIComponent(projectSlug)}/forms/${encodeURIComponent(formSlug)}/submit`,
+
+          data,
+
+          {
+            headers: {
+              "Content-Type": "application/json"
+            }
+          }
+
+        );
+
+        return response.data;
+
+      }
+
+
+      // ========================================================
+      // MULTIPART FORM REQUEST
+      // ========================================================
+
+      const formData = new FormData();
+
+
+      // ========================================================
+      // ADD NORMAL DATA
+      // ========================================================
+
+      for (
+        const [key, value]
+        of Object.entries(data)
+      ) {
+
+        if (
+          value !== undefined &&
+          value !== null
+        ) {
+
+          formData.append(
+            key,
+            value
+          );
+
+        }
+
+      }
+
+
+      // ========================================================
+      // ADD FILES
+      // ========================================================
+
+      for (const file of files) {
+
+        if (!file) {
+          continue;
+        }
+
+
+        // ------------------------------------------------------
+        // BUFFER
+        // ------------------------------------------------------
+
+        if (Buffer.isBuffer(file.buffer)) {
+
+          formData.append(
+
+            file.fieldname,
+
+            file.buffer,
+
+            {
+              filename:
+                file.filename ||
+                file.originalname ||
+                "upload",
+
+              contentType:
+                file.contentType ||
+                file.mimetype
+            }
+
+          );
+
+          continue;
+
+        }
+
+
+        // ------------------------------------------------------
+        // FILE PATH
+        // ------------------------------------------------------
+
+        if (file.path) {
+
+          formData.append(
+
+            file.fieldname,
+
+            fs.createReadStream(
+              file.path
+            ),
+
+            {
+              filename:
+                file.filename ||
+                file.originalname
+            }
+
+          );
+
+          continue;
+
+        }
+
+
+        throw new Error(
+          `Invalid file for field: ${file.fieldname}`
+        );
+
+      }
+
+
+      // ========================================================
+      // SUBMIT
+      // ========================================================
+
+      const response = await this.client.post(
+
+        `/public/${encodeURIComponent(projectSlug)}/forms/${encodeURIComponent(formSlug)}/submit`,
+
+        formData,
+
+        {
+          headers: {
+            ...formData.getHeaders()
+          }
+        }
+
+      );
+
+
+      return response.data;
+
+    } catch (error) {
+
+      this.handleError(error);
+
+    }
+
+  }
+
+
+  // ==========================================================
+  // ERROR HANDLER
+  // ==========================================================
+
+  handleError(error) {
+
+    // ==========================================
+    // SERVER RESPONSE
+    // ==========================================
+
+    if (error.response) {
+
+      const message =
+        error.response.data?.message ||
+        "CMS API request failed";
+
+      const apiError =
+        new Error(message);
+
+      apiError.status =
+        error.response.status;
+
+      apiError.response =
+        error.response.data;
+
+      throw apiError;
+
+    }
+
+
+    // ==========================================
+    // NO RESPONSE
+    // ==========================================
+
+    if (error.request) {
+
+      if (
+        error.code === "ECONNABORTED" ||
+        error.code === "ETIMEDOUT"
+      ) {
+
+        throw new Error(
+          "CMS API request timed out"
+        );
+
+      }
+
+      throw new Error(
+        "Could not connect to CMS API"
+      );
+
+    }
+
+
+    // ==========================================
+    // UNKNOWN ERROR
+    // ==========================================
+
+    throw error;
+
+  }
+
+}
+
+
+module.exports = {
+  Forms
+};

package/src/index.js

@@ -0,0 +1,84 @@
+const { Records } = require("./records");
+const { Forms } = require("./forms");
+
+class BuildFree {
+
+  constructor({
+    apiKey,
+    baseURL = "https://cms-backend-9nkz.onrender.com/api/v1"
+  } = {}) {
+
+    // ==========================================
+    // API KEY VALIDATION
+    // ==========================================
+
+    if (!apiKey) {
+      throw new Error("API key is required");
+    }
+
+    if (
+      typeof apiKey !== "string" ||
+      !apiKey.startsWith("cms_live_")
+    ) {
+      throw new Error("Invalid API key");
+    }
+
+
+    // ==========================================
+    // INITIALIZE SERVICES
+    // ==========================================
+
+    this.records = new Records({
+      apiKey,
+      baseURL
+    });
+
+    this.forms = new Forms({
+      apiKey,
+      baseURL
+    });
+
+  }
+
+
+  // ==========================================
+  // RECORDS
+  // ==========================================
+
+  getRecords(options) {
+
+    return this.records.getAll(options);
+
+  }
+
+
+  getRecord(options) {
+
+    return this.records.getOne(options);
+
+  }
+
+
+  // ==========================================
+  // FORMS
+  // ==========================================
+
+  getForm(options) {
+
+    return this.forms.getOne(options);
+
+  }
+
+
+  submitForm(options) {
+
+    return this.forms.submit(options);
+
+  }
+
+}
+
+
+module.exports = {
+  BuildFree
+};

package/src/records.js

@@ -0,0 +1,189 @@
+const axios = require("axios");
+
+class Records {
+
+  constructor({
+    apiKey,
+    baseURL
+  }) {
+
+    this.client = axios.create({
+
+      baseURL,
+
+      timeout: 10000,
+
+      headers: {
+        "x-api-key": apiKey,
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      }
+
+    });
+
+  }
+
+
+  // ==========================================================
+  // GET ALL RECORDS
+  // ==========================================================
+
+  async getAll({
+    projectSlug,
+    collectionSlug
+  } = {}) {
+
+    // ==========================================
+    // VALIDATION
+    // ==========================================
+
+    if (!projectSlug) {
+      throw new Error("projectSlug is required");
+    }
+
+    if (!collectionSlug) {
+      throw new Error("collectionSlug is required");
+    }
+
+
+    // ==========================================
+    // REQUEST
+    // ==========================================
+
+    try {
+
+      const response = await this.client.get(
+
+        `/public/${encodeURIComponent(projectSlug)}/${encodeURIComponent(collectionSlug)}`
+
+      );
+
+      return response.data;
+
+    } catch (error) {
+
+      this.handleError(error);
+
+    }
+
+  }
+
+
+  // ==========================================================
+  // GET ONE RECORD
+  // ==========================================================
+
+  async getOne({
+    projectSlug,
+    collectionSlug,
+    recordId
+  } = {}) {
+
+    // ==========================================
+    // VALIDATION
+    // ==========================================
+
+    if (!projectSlug) {
+      throw new Error("projectSlug is required");
+    }
+
+    if (!collectionSlug) {
+      throw new Error("collectionSlug is required");
+    }
+
+    if (!recordId) {
+      throw new Error("recordId is required");
+    }
+
+
+    // ==========================================
+    // REQUEST
+    // ==========================================
+
+    try {
+
+      const response = await this.client.get(
+
+        `/public/${encodeURIComponent(projectSlug)}/${encodeURIComponent(collectionSlug)}/${encodeURIComponent(recordId)}`
+
+      );
+
+      return response.data;
+
+    } catch (error) {
+
+      this.handleError(error);
+
+    }
+
+  }
+
+
+  // ==========================================================
+  // ERROR HANDLER
+  // ==========================================================
+
+  handleError(error) {
+
+    // ==========================================
+    // SERVER RESPONSE
+    // ==========================================
+
+    if (error.response) {
+
+      const message =
+        error.response.data?.message ||
+        "CMS API request failed";
+
+      const apiError =
+        new Error(message);
+
+      apiError.status =
+        error.response.status;
+
+      apiError.response =
+        error.response.data;
+
+      throw apiError;
+
+    }
+
+
+    // ==========================================
+    // NO RESPONSE
+    // ==========================================
+
+    if (error.request) {
+
+      if (
+        error.code === "ECONNABORTED" ||
+        error.code === "ETIMEDOUT"
+      ) {
+
+        throw new Error(
+          "CMS API request timed out"
+        );
+
+      }
+
+      throw new Error(
+        "Could not connect to CMS API"
+      );
+
+    }
+
+
+    // ==========================================
+    // UNKNOWN ERROR
+    // ==========================================
+
+    throw error;
+
+  }
+
+}
+
+
+module.exports = {
+  Records
+};