@jd-data-limited/easy-fm 0.0.1 → 0.0.2

package/README.md

@@ -12,47 +12,160 @@ a [FileMaker server](https://www.claris.com/filemaker/server/). This module inte
 2. Create a FileMaker database account for easy-fm to use. This account must have the 'Access via FileMaker Data API (
    fmrest)' extended privilege
 
+## Table of contents
 
-## Usage examples
+1. [Connecting to a database](#connecting-to-a-database)
+2. [Working with records](#working-with-records)
+3. [Performing find requests](#perform-find-requests)
+4. [Scripts](#scripts)
+5. [Index](#index)
+
+## Connecting to a database
+
+easy-fm currently does not support connecting to external data sources, or authenticating by any method other than plain
+FileMaker authentication.
 
-1. Get the first record on the 'table1' layout
 ```javascript
 import fm, {FMError} from "easy-fm"; // Import the module
 const connection = new fm(); // This variable will be used for interacting with the server
 
 connection.login(hostname, database, username, password).then(async token => { // Login
-    let layout = connection.getLayout("layout1")
-    let record = layout.getRecord(1)
-    await record.get() // Fetch the data for that record
-    console.log(record)
+
 })
 ```
 
-2. Get all related portal records
+## Working with records
+
+When running scripts or interacting with records, the first step that you need to do is get the layout that you want to
+use
+
+```javascript
+let layout = connection.getLayout("layout1") // Get the layout known as 'layout1'
+```
+
+Once you have the layout, you can perform a multitude of tasks
+
+### Get a single record using its RecordID
+
+[What's a RecordID?](#recordid)
+
+```javascript
+let record_id = 1
+let record = layout.getRecord(record_id)
+
+await record.get() // The 'getRecord' method does not automatically get that record's values, so this step does that instead
+
+let field = record.getField("field1")
+console.log(field.value) // Get the value of 'field1'
+```
+
+### Modify a record
+
+WARNING: The commit step is mandatory. Otherwise the changes will never be uploaded
+
 ```javascript
-await record.get() // Fetch the record's data
-let portal = record.getPortal("portal1") // 'portal1' should be the name you assigned the portal object, when creating the layout
-console.log(portal.records)
+let record_id = 1
+let record = layout.getRecord(record_id)
+
+await record.get() // The 'getRecord' method does not automatically get that record's values, so this step does that instead
+record.getField("field1").set("This is a value")
+record.getField("field2").set("This is also a value")
+await record.commit()
 ```
 
-3. Run a script
+### Create a new record
+
+WARNING: The record is not created on the database until a commit is done
+
 ```javascript
-    let script = connection.script("script_name", "this is a parameter") // Create a new script object using the script name and parameter (optional)
-    
-    // Get the layout we want to run the script on
-    let layout = connection.getLayout("layout1")
-
-    // Run the script on the layout
-    let result = await layout.runScript(script)
-    console.log(result)
+let record = await layout.createRecord()
+record.getField("field1").set("ABC")
+record.getField("field2").set("DEF")
+await record.commit()
 ```
 
-4. Perform a find
+### Downloading container field files
+
+```javascript
+let record_id = 1
+let record = layout.getRecord(record_id)
+
+await record.get() // The 'getRecord' method does not automatically get that record's values, so this step does that instead
+
+let container = record.getField("container")
+container.download().then(stream => {
+    // Returns an IncomingMessage, which is an extension of ReadableStream
+})
+```
+
+[IncomingMessage](https://nodejs.org/api/http.html#class-httpincomingmessage)
+, [ReadableStream](https://nodejs.org/api/stream.html#class-streamreadable)
+
+### Uploading container files
+
+When uploading files, they should be uploaded as a [Buffer](https://nodejs.org/api/buffer.html) object, along with a
+filename (string) and MIME (also string)
+
+MIME types are not currently automatically detected
+
+```javascript
+const fs = require("fs")
+let filename = "image.jpg"
+let buffer = fs.readdirSync("./" + filename)
+let mime = "image/jpeg"
+
+let record_id = 1
+let record = layout.getRecord(record_id)
+await record.get() // The 'getRecord' method does not automatically get that record's values, so this step does that instead
+
+let container = record.getField("container")
+container.upload(buffer, filename, mime).then(() => {
+    console.log("UPLOAD SUCCESSFUL!")
+})
+```
+[(Mozilla) Common MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)
+
+### Read and modify portal information
+
+To be able to read portal information for a record, you'll need to put a portal on the layout you are using. Make sure
+you also:
+
+- Give the portal object a name
+- Include the exact fields you need in the portal. Any fields you leave out will not be accessible by node.js, and
+  putting extra fields in is not a good idea.
+
+```javascript
+let record = layout.getRecord(1)
+
+// Portal data is downloaded when the record is fetched
+await record.get()
+let portal = record.getPortal("Portal1")
+
+for (let _record of portal.records) {
+    // Runs for all records in the portal
+    let field = _record.getField("field2")
+    console.log(field.value)
+    field.set("GHI")
+}
+```
+
+**WARNING**: Commiting a related portal record will also commit any changes to the parent record as well as any other
+portal records.
+
+## Perform find requests
+
+Performing find requests is one of the most common database operations
+
+![img.png](img.png)
+
+The image above is how the find request would look when doing it in a FileMaker script. This should hopefully help you
+understand how the find request process works.
+
 ```javascript
 let find = layout.newFind() // Create a new find operation
 
 find.addRequests( // Specify the find criteria
-    {"PrimaryKey": "AAAAA", "ModifiedBy": "BBBB"}, 
+    {"PrimaryKey": "AAAAA", "ModifiedBy": "BBBB"},
     {"CreatedBy": "BBBB"}
 )
 
@@ -60,5 +173,21 @@ find.addSort("CratedBy", "ascend") // Sort the results in ascending order
 let records = await find.find() // Perform the find
 console.log(records)
 ```
-This is the same as the following find request in FileMaker:
-![img.png](img.png)
+
+### Scripts
+
+Running scripts is another operation you may need to do regularly. This one is fairly straight-forward in how it works
+
+```javascript
+let layout = connection.getLayout("layout1")
+let script = connection.script("MyFileMakerScript", "This is a parameter")
+let result = await layout.runScript(script)
+console.log(result)
+```
+
+## Index
+
+### RecordID
+
+This is not a custom field that can be set and/or changed. You can get a record's ID from within FileMaker by
+using `Get(RecordID)`

package/decs.d.ts

@@ -1,4 +1,7 @@
 declare module "fs"
 declare module "events"
 declare module "path"
-declare module "url"
+declare module "url"
+declare module "node-fetch"
+declare module "btoa"
+declare module "buffer"

package/index.js

@@ -1,4 +1,3 @@
-"use strict";
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -8,21 +7,20 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FMError = void 0;
 // const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));
-const node_fetch_1 = require("node-fetch");
-const events_1 = require("events");
+import fetch, { File, FormData } from 'node-fetch';
+import { EventEmitter } from "events";
 // @ts-ignore
-const fs_1 = require("fs");
+import fs from "fs";
 // @ts-ignore
-const path_1 = require("path");
+import path from "path";
 // @ts-ignore
-const url_1 = require("url");
-const btoa = require("btoa");
+import { fileURLToPath } from "url";
+import * as https from "https";
+// import * as btoa from "btoa";
 // @ts-ignore
-const errs = JSON.parse(fs_1.default.readFileSync(path_1.default.join(path_1.default.dirname((0, url_1.fileURLToPath)(import.meta.url)), 'fmErrors.json')).toString());
-class FileMakerConnection {
+const errs = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), 'fmErrors.json')).toString());
+export default class FileMakerConnection {
     constructor() {
     }
     get endpoint() {
@@ -44,7 +42,7 @@ class FileMakerConnection {
         return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
             if (!this.token)
                 reject(new Error("Not logged in"));
-            let _fetch = yield (0, node_fetch_1.default)(`${this.endpoint}/sessions/${this.token}`, {
+            let _fetch = yield fetch(`${this.endpoint}/sessions/${this.token}`, {
                 method: "DELETE",
                 headers: {
                     "content-type": "application/json"
@@ -66,13 +64,13 @@ class FileMakerConnection {
     }
     createSession() {
         return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
-            (0, node_fetch_1.default)(`${this.endpoint}/sessions`, {
+            fetch(`${this.endpoint}/sessions`, {
                 hostname: this.hostname,
                 port: 443,
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
-                    "Authorization": "Basic " + btoa(this.username + ":" + this.password)
+                    "Authorization": "Basic " + Buffer.from(this.username + ":" + this.password).toString("base64")
                 }
             }).then(res => {
                 console.log(res);
@@ -97,14 +95,14 @@ class FileMakerConnection {
     getLayout(name) {
         return new layout(this, name);
     }
-    apiRequest(url, options) {
+    apiRequest(url, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!options.headers)
                 options.headers = {};
             options.headers["content-type"] = options.headers["content-type"] ? options.headers["content-type"] : "application/json";
             options.headers["authorization"] = "Bearer " + this.token;
             options.rejectUnauthorized = this.rejectUnauthroized;
-            let _fetch = yield (0, node_fetch_1.default)(url, options);
+            let _fetch = yield fetch(url, options);
             let data = yield _fetch.json();
             return data;
         });
@@ -133,7 +131,6 @@ class FileMakerConnection {
         return { name, parameter };
     }
 }
-exports.default = FileMakerConnection;
 class layout {
     constructor(conn, name) {
         this.conn = conn;
@@ -145,26 +142,17 @@ class layout {
     getScript(script) {
         return new script(this, script);
     }
-    createRecord(body = {}) {
-        // console.log(fieldData)
-        return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
-            this.conn.apiRequest(`${this.endpoint}/records`, {
-                port: 443,
-                method: "POST",
-                body: JSON.stringify(body)
-            })
-                .then(res => {
-                if (res.messages[0].code === "0") {
-                    resolve(new record(this, res.response.recordId, res.response.modId));
-                }
-                else {
-                    reject(new FMError(res.messages[0].code, res.status, res));
+    createRecord() {
+        return new Promise((resolve, reject) => {
+            // Get the layout's metadata
+            this.conn.apiRequest(`${this.endpoint}`).then(res => {
+                let fields = {};
+                for (let _field of res.response.fieldMetaData) {
+                    fields[_field.name] = "";
                 }
-            })
-                .catch(e => {
-                reject(e);
+                resolve(new record(this, -1, 0, fields));
             });
-        }));
+        });
     }
     getRecord(recordId) {
         return new record(this, recordId);
@@ -195,8 +183,17 @@ class layout {
             });
         }));
     }
+    getLayoutMeta() {
+        return new Promise((resolve, reject) => {
+            this.conn.apiRequest(this.endpoint).then(res => {
+                this.metadata = res.response;
+                resolve(this);
+            })
+                .catch(e => reject(e));
+        });
+    }
 }
-class record extends events_1.EventEmitter {
+class record extends EventEmitter {
     constructor(layout, recordId, modId = recordId, fieldData = {}, portalData = null) {
         super();
         this.layout = layout;
@@ -235,6 +232,8 @@ class record extends events_1.EventEmitter {
     }
     get() {
         return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
+            if (!this.layout.metadata)
+                yield this.layout.getLayoutMeta();
             this.layout.conn.apiRequest(this.endpoint, {
                 port: 443,
                 method: "GET"
@@ -258,11 +257,35 @@ class record extends events_1.EventEmitter {
             });
         }));
     }
-    save(extraBody = {}) {
+    commit(extraBody = {}) {
         return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
             let data = this.toObject();
             delete data.recordId;
             delete data.modId;
+            if (this.recordId === -1) {
+                // This is a new record
+                this.layout.conn.apiRequest(`${this.layout.endpoint}/records`, {
+                    port: 443,
+                    method: "POST",
+                    body: JSON.stringify({
+                        fieldData: data.fieldData
+                    })
+                })
+                    .then(res => {
+                    if (res.messages[0].code === "0") {
+                        this.recordId = res.response.recordId;
+                        this.modId = res.response.modId;
+                        resolve(this);
+                    }
+                    else {
+                        reject(new FMError(res.messages[0].code, res.status, res));
+                    }
+                })
+                    .catch(e => {
+                    reject(e);
+                });
+                return;
+            }
             for (let item of Object.keys(extraBody))
                 data[item] = extraBody[item];
             this.layout.conn.apiRequest(this.endpoint, {
@@ -322,14 +345,26 @@ class field {
         this.edited = false;
     }
     set(content) {
+        if (this.dataType === "container")
+            throw "Cannot set container value using set(). Use upload() instead.";
         this.value = content;
         this.edited = true;
     }
-    containerUpload(buffer, filename, mime) {
+    get dataType() {
+        if (this.record instanceof portalItem) {
+            return this.record.layout.metadata.portalMetaData.find(name => name === this.id).result;
+        }
+        else {
+            return this.record.layout.metadata.fieldMetaData.find(name => name === this.id).result;
+        }
+    }
+    upload(buffer, filename, mime) {
+        if (this.dataType !== "container")
+            throw "Cannot upload a file to the field; " + this.id + " (not a container field)";
         return new Promise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
-            let form = new node_fetch_1.FormData();
-            form.append("upload", new node_fetch_1.File([buffer], filename, { type: mime }));
-            let _fetch = yield (0, node_fetch_1.default)(`${this.record.endpoint}/containers/${this.id}/1`, {
+            let form = new FormData();
+            form.append("upload", new File([buffer], filename, { type: mime }));
+            let _fetch = yield fetch(`${this.record.endpoint}/containers/${this.id}/1`, {
                 method: "POST",
                 headers: { "Authorization": "Bearer " + this.record.layout.conn.token },
                 body: form
@@ -346,6 +381,13 @@ class field {
                 .catch(e => { reject(e); });
         }));
     }
+    download() {
+        return new Promise((resolve, reject) => {
+            https.get(this.value.toString(), (res) => {
+                resolve(res);
+            });
+        });
+    }
 }
 class portal {
     constructor(record, name, records = []) {
@@ -366,8 +408,8 @@ class portalItem extends record {
     attachPortal(portal) {
         this.portal = portal;
     }
-    save(extraBody = {}) {
-        return this.portal.record.save(extraBody);
+    commit(extraBody = {}) {
+        return this.portal.record.commit(extraBody);
     }
     toObject(fieldFilter) {
         super.toObject();
@@ -439,7 +481,7 @@ class find {
         });
     }
 }
-class FMError extends Error {
+export class FMError extends Error {
     constructor(code, httpStatus, res) {
         super(code);
         this.httpStatus = httpStatus;
@@ -448,7 +490,6 @@ class FMError extends Error {
         this.message = errs.find(err => err.e === this.code) || "Unknown error";
     }
 }
-exports.FMError = FMError;
 //
 // module.exports = {
 //     default: {FileMakerConnection}

package/index.ts

@@ -4,7 +4,7 @@ import fetch, {
     blobFrom,
     blobFromSync,
     File,
-    fileFrom,
+    fileFrom,ublish
     fileFromSync,
     FormData,
     Headers,
@@ -18,7 +18,8 @@ import fs from "fs"
 import path from "path"
 // @ts-ignore
 import { fileURLToPath } from "url"
-import btoa = require("btoa");
+import * as https from "https";
+// import * as btoa from "btoa";
 
 // @ts-ignore
 const errs = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), 'fmErrors.json')).toString())
@@ -41,7 +42,7 @@ export default class FileMakerConnection {
     private username: any;
     private password: any;
     private rejectUnauthroized: boolean;
-    
+
     constructor() {
     }
 
@@ -95,7 +96,7 @@ export default class FileMakerConnection {
                 method: "POST",
                 headers: {
                     "Content-Type": "application/json",
-                    "Authorization": "Basic " + btoa(this.username + ":" + this.password)
+                    "Authorization": "Basic " + Buffer.from(this.username + ":" + this.password).toString("base64")
                 }
             }).then(res => {
                 console.log(res)
@@ -117,11 +118,11 @@ export default class FileMakerConnection {
         })
     }
 
-    getLayout(name) {
+    getLayout(name): layout {
         return new layout(this, name)
     }
 
-    async apiRequest(url, options): Promise<any> {
+    async apiRequest(url: string | Request, options: any = {}): Promise<any> {
         if (!options.headers) options.headers = {}
         options.headers["content-type"] = options.headers["content-type"] ? options.headers["content-type"] : "application/json"
         options.headers["authorization"] = "Bearer " + this.token
@@ -160,6 +161,7 @@ export default class FileMakerConnection {
 class layout {
     readonly conn: FileMakerConnection;
     protected name: string;
+    metadata: any;
     constructor(conn: FileMakerConnection, name: string) {
         this.conn = conn
         this.name = name
@@ -173,26 +175,16 @@ class layout {
         return new script(this, script)
     }
 
-    createRecord(body = {}): Promise<record | Error> {
-        // console.log(fieldData)
-        return new Promise(async (resolve, reject) => {
-            this.conn.apiRequest(`${this.endpoint}/records`, {
-                port: 443,
-                method: "POST",
-                body: JSON.stringify(body)
+    createRecord(): Promise<record | Error | void> {
+        return new Promise((resolve, reject) => {
+            // Get the layout's metadata
+            this.conn.apiRequest(`${this.endpoint}`).then(res => {
+                let fields = {}
+                for (let _field of res.response.fieldMetaData) {
+                    fields[_field.name] = ""
+                }
+                resolve(new record(this, -1, 0, fields))
             })
-                .then(res => {
-                    if (res.messages[0].code === "0") {
-                        resolve(
-                            new record(this, res.response.recordId, res.response.modId)
-                        )
-                    } else {
-                        reject(new FMError(res.messages[0].code, res.status, res))
-                    }
-                })
-                .catch(e => {
-                    reject(e)
-                })
         })
     }
 
@@ -225,11 +217,21 @@ class layout {
                 })
         })
     }
+
+    public getLayoutMeta(): Promise<layout | FMError> {
+        return new Promise((resolve, reject) => {
+            this.conn.apiRequest(this.endpoint).then(res => {
+                this.metadata = res.response
+                resolve(this)
+            })
+                .catch(e => reject(e))
+        })
+    }
 }
 
 class record extends EventEmitter {
     readonly layout: layout;
-    readonly recordId: number;
+    public recordId: number;
     modId: number;
     fields: field[];
     readonly portals: portal[];
@@ -277,6 +279,8 @@ class record extends EventEmitter {
 
     get() {
         return new Promise(async (resolve, reject) => {
+            if (!this.layout.metadata) await this.layout.getLayoutMeta()
+
             this.layout.conn.apiRequest(this.endpoint, {
                 port: 443,
                 method: "GET"
@@ -299,12 +303,37 @@ class record extends EventEmitter {
         })
     }
 
-    save(extraBody = {}) {
+    commit(extraBody = {}): Promise<record | FMError> {
         return new Promise(async (resolve, reject) => {
             let data = this.toObject()
             delete data.recordId
             delete data.modId
 
+            if (this.recordId === -1) {
+                // This is a new record
+                this.layout.conn.apiRequest(`${this.layout.endpoint}/records`, {
+                    port: 443,
+                    method: "POST",
+                    body: JSON.stringify({
+                        fieldData: data.fieldData
+                    })
+                })
+                    .then(res => {
+                        if (res.messages[0].code === "0") {
+                            this.recordId = res.response.recordId
+                            this.modId = res.response.modId
+                            resolve(this)
+                        } else {
+                            reject(new FMError(res.messages[0].code, res.status, res))
+                        }
+                    })
+                    .catch(e => {
+                        reject(e)
+                    })
+
+                return
+            }
+
             for (let item of Object.keys(extraBody)) data[item] = extraBody[item]
             this.layout.conn.apiRequest(this.endpoint, {
                 port: 443,
@@ -376,11 +405,21 @@ class field {
     }
 
     set(content) {
+        if (this.dataType === "container") throw "Cannot set container value using set(). Use upload() instead."
         this.value = content
         this.edited = true
     }
 
-    containerUpload(buffer, filename, mime): Promise<void | FMError> {
+    get dataType() {
+        if (this.record instanceof portalItem) {
+            return this.record.layout.metadata.portalMetaData.find(name => name === this.id).result
+        } else {
+            return this.record.layout.metadata.fieldMetaData.find(name => name === this.id).result
+        }
+    }
+
+    upload(buffer: Buffer, filename: string, mime: string): Promise<void | FMError> {
+        if (this.dataType !== "container") throw "Cannot upload a file to the field; " + this.id + " (not a container field)"
         return new Promise(async (resolve, reject) => {
             let form = new FormData()
             form.append("upload", new File([buffer], filename, {type: mime}))
@@ -401,6 +440,13 @@ class field {
                 .catch(e => {reject(e)})
         })
     }
+    download() {
+        return new Promise((resolve, reject) => {
+            https.get(this.value.toString(), (res) => {
+                resolve(res)
+            })
+        })
+    }
 }
 
 class portal {
@@ -430,8 +476,8 @@ class portalItem extends record {
         this.portal = portal
     }
 
-    save(extraBody = {}) {
-        return this.portal.record.save(extraBody)
+    commit(extraBody = {}) {
+        return this.portal.record.commit(extraBody)
     }
 
     toObject(fieldFilter): any {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jd-data-limited/easy-fm",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "dependencies": {
     "@types/btoa": "^1.2.3",
     "@types/events": "^3.0.0",

package/tsconfig.json

@@ -1,8 +1,9 @@
 {
   "compilerOptions": {
     "target": "es2015",
-    "module": "commonjs",
+    "module": "es2022",
     "lib": ["es2021.intl", "es2015"],
+    "moduleResolution": "Node"
   },
   "files": ["index.ts"]
 }