@outlawdesigns/armorysdk 1.0.0

package/README.md

@@ -0,0 +1,191 @@
+# Armory SDK (Server-Side)
+
+A lightweight Node.js SDK for interacting with the **Armory data layer**.  
+This package provides ORM-style access to firearms, ammunition, optics, and shooting data through a consistent, class-based interface built on `@outlawdesigns/db-record`.
+
+----------
+
+## 🚀 Features
+
+-   🔫 **Comprehensive armory models** — Manage firearms, ammunition, optics, and related entities.
+
+-   🧩 **Dynamic model factory** — Fetch models or classes by name using a centralized interface.
+
+-   🗃️ **Database abstraction** — Built on `@outlawdesigns/db-record` for clean MySQL integration.
+
+-   📸 **Media support** — Includes models for firearm and target images.
+
+-   📊 **Activity tracking** — Record shooting sessions and ammo purchases.
+
+
+----------
+
+## 📦 Installation
+
+```bash
+npm install @outlawdesigns/armorysdk
+
+```
+
+----------
+
+## 🧠 Basic Usage
+
+### Require the SDK
+
+```js
+import ModelFactory from '@outlawdesigns/armorysdk';
+```
+
+### Create a Model Instance
+
+```js
+const firearm = await ModelFactory.get('firearm',2).init();
+console.log(firearm.Serial_Number);
+```
+
+### Access Model Classes Directly
+
+```js
+const Firearm = Armory.getClass('firearm');
+const myFirearm = new Firearm(2);
+await myFirearm.init();
+//particularly useful for calling static methods
+const allArms = await ModelFactory.getClass('firearm').getAll()
+
+```
+
+----------
+
+## 🧩 Available Models
+
+| Model | Description | Backing Table |
+| :--- | :---: | ---: |
+| `firearm` | Concrete instance of a firearm owned by a user. | `Firearm` |
+| ``firearmImage`` | Images associated with firearms. | `FirearmImage` |
+| `firearmType` | Abstract firearm definition. | `FirearmType` |
+| `manufacturer` | Firearm or component manufacturer. | `Manufacturer` |
+| `ammunition` | Concrete instance of ammunition owned by a user. | `Ammunition` |
+| `ammunitionType` | Abstract ammunition definition. | `AmmunitionType` |
+| `caliber` | Caliber definitions. | `Caliber` |
+| `ammoPurchase` | Records of ammunition purchases. | `AmmoPurchase` |
+| `optic` | Concrete instance of an optic owned by a user. | Optic |
+| `opticType` | Abstract optic definition. | `OpticType` |
+| `shoot` | Shooting session records. | `Shoot` |
+| `targetImage` | Images of shot targets. | `TargetImage` |
+| `vendor` | Vendors or retailers. | `Vendor` |
+
+All models extend `@outlawdesigns/db-record.Record` and support standard CRUD operations.
+
+----------
+
+## 🔧 Example: Recording a Shooting Session
+
+```js
+import ModelFactory from '@outlawdesigns/armorysdk';
+
+const firearmId = 1;
+const ammoId = 2;
+const rounds = 100;
+const distanceFt = 300;
+const opticId = null;
+const userId = 'example';
+
+const newShoot = model = await ModelFactory.getClass('shoot').new(firearmId,ammoId,rounds, distanceFt, opticId, userId);
+```
+
+----------
+
+## 🔧 Example: Logging an Ammo Purchase
+
+```js
+import ModelFactory from '@outlawdesigns/armorysdk';
+
+const ammoId = 2;
+const vendorId = 12;
+const rounds = 100;
+const price = 55.90;
+const datePurchased = new Date();
+//pass undefined instead for pending receipt
+const dateReceived = datePurchased;
+const userId = 'example';
+
+const purchase = await ModelFactory.getClass('ammoPurchase').new(ammoId, vendorId, rounds, price, datePurchased, dateReceived, userId);
+
+```
+
+----------
+
+## ⚙️ Environment Variables
+
+
+| Variable | Description | Default |
+| :--- | :---: | ---: |
+| `MYSQL_ARMORY_DB` | Database name for Armory models. | `Armory` |
+
+
+----------
+
+## 🧱 Project Structure
+
+```
+.
+├── index.js               # SDK entry point
+├── modelFactory.js        # Central model registry
+├── models/
+│   ├── ammunition.js
+│   ├── ammunitionType.js
+│   ├── ammoPurchase.js
+│   ├── caliber.js
+│   ├── firearm.js
+│   ├── firearmImage.js
+│   ├── firearmType.js
+│   ├── manufacturer.js
+│   ├── optic.js
+│   ├── opticType.js
+│   ├── shoot.js
+│   ├── targetImage.js
+│   └── vendor.js
+└── package.json
+
+```
+
+----------
+
+## 🧩 Extending the SDK
+
+To add a new model:
+
+1.  Create a file in `models/` extending `@outlawdesigns/db-record.Record`.
+
+2.  Register it in `modelFactory.js`.
+
+
+Example:
+
+```js
+class Range extends Record {
+  static table = 'range';
+  static primaryKey = 'id';
+  static get database() {
+    return process.env.MYSQL_ARMORY_DB || 'armory';
+  }
+}
+
+```
+
+Register it:
+
+```js
+const Range = require('./models/range');
+
+models.range = (id) => new Range(id);
+modelClasses.range = Range;
+
+```
+
+
+## 👤 Author
+
+Maintained by **Outlaw Designs**  
+[https://github.com/outlawdesigns-io](https://github.com/outlawdesigns-io)

package/index.js

@@ -0,0 +1,3 @@
+const ModelFactory = require('./modelFactory');
+
+module.exports = ModelFactory;

package/modelFactory.js

@@ -0,0 +1,61 @@
+const AmmoPurchase = require('./models/ammopurchase');
+const Ammunition = require('./models/ammunition');
+const AmmunitionType = require('./models/ammunitionType.js');
+const Caliber = require('./models/caliber.js');
+const FirearmImage = require('./models/firearmImage.js');
+const Firearm = require('./models/firearm.js');
+const FirearmType = require('./models/firearmType.js');
+const Manufacturer = require('./models/manufacturer.js');
+const Optic = require('./models/optic.js');
+const OpticType = require('./models/opticType.js');
+const Shoot = require('./models/shoot.js');
+const TargetImage = require('./models/targetImage.js');
+const Vendor = require('./models/vendor.js');
+
+
+const models = {
+  ammopurchase: () => new AmmoPurchase(id),
+  ammo: () => new Ammunition(id),
+  ammotype: (id) => new AmmunitionType(id),
+  caliber: (id) => new Caliber(id),
+  firearmimage: (id) => new FirearmImage(id),
+  firearm: (id) => new Firearm(id),
+  firearmtype: () => new FirearmType(id),
+  manufacturer: ()=> new Manufacturer(id),
+  optic: ()=> new Optic(id),
+  optictype: ()=> new OpticType(id),
+  shoot: ()=> new Shoot(id),
+  targetimage: ()=> new TargetImage(id),
+  vendor: ()=> new Vendor(id),
+}
+
+const modelClasses = {
+  ammopurchase:AmmoPurchase,
+  ammo:Ammunition,
+  ammotype:AmmunitionType,
+  caliber:Caliber,
+  firearmimage:FirearmImage,
+  firearm:Firearm,
+  firearmtype:FirearmType,
+  manufacturer:Manufacturer,
+  optic:Optic,
+  optictype:OpticType,
+  shoot:Shoot,
+  targetimage:TargetImage,
+  vendor:Vendor
+}
+
+module.exports = {
+  get: (name,id) => {
+    if(!models[name]){
+      throw new Error(`Model ${name} does not exist`);
+    }
+    return models[name](id);
+  },
+  getClass: (name) => {
+    if(!modelClasses[name]){
+      throw new Error(`Model ${name} does not exist`);
+    }
+    return modelClasses[name];
+  }
+}

package/models/ammopurchase.js

@@ -0,0 +1,74 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+const Ammunition = require('./ammunition');
+const Vendor = require('./vendor');
+
+class AmmoPurchase extends Record{
+
+  static table = 'AmmoPurchase';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(AmmoPurchase.database,AmmoPurchase.table,AmmoPurchase.primaryKey,id);
+    this.publicKeys = [
+      'Id','Ammunition','Vendor','Rounds','Price','DatePurchased','DateReceived','User'
+    ];
+  }
+  static async new(ammoId,vendorId,rounds,price,datePurchased,dateReceived,user){
+    let ammo;
+    let vendor;
+    let purchase = new AmmoPurchase();
+    try{
+      ammo = await new Ammunition(ammoId).init();
+      vendor = await new Vendor(vendorId).init();
+    }catch(err){
+      throw err;
+    }
+    if(dateReceived !== undefined){
+      ammo.Rounds += parseInt(rounds);
+      await ammo.update();
+      purchase.DateReceived = dateReceived;
+    }
+    purchase.DatePurchased = datePurchased;
+    purchase.Price = price;
+    purchase.Rounds = rounds;
+    purchase.Vendor = vendorId;
+    purchase.Ammunition = ammoId;
+    purchase.User = user;
+    return await purchase.create();
+  }
+  static async receive(purchaseId){
+    //todo: reject if DateReceived is already populated.
+    //todo: ammo doesn't exist gets caught, but doesn't seem to bubble all the way up.
+    let purchase;
+    let ammo;
+    try{
+      purchase = await new AmmoPurchase(purchaseId).init();
+      ammo = await new Ammunition(purchase.Ammunition).init();
+      ammo.Rounds += purchase.Rounds;
+      await ammo.update();
+      purchase.DatePurchased = purchase.db.date(purchase.DatePurchased);
+      purchase.DateReceived = purchase.db.date();
+      await purchase.update();
+      return purchase.getPublicProperties();
+    }catch(err){
+      throw err;
+    }
+  }
+  static async getAwaitingReceipt(user){
+    let records = [];
+    let purchase = new AmmoPurchase();
+    let ids = await purchase.db.table(purchase.table).select(purchase.primaryKey).where('DateReceived is null').andWhere('User = ' + user).execute();
+    for(let id in ids){
+      let obj = await new AmmoPurchase(ids[id][purchase.primaryKey]).init();
+      records.push(obj.getPublicProperties());
+    }
+    return records;
+  }
+}
+
+module.exports = AmmoPurchase;

package/models/ammunition.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class Ammunition extends Record{
+
+  static table = 'Ammunition';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(Ammunition.database,Ammunition.table,Ammunition.primaryKey,id);
+    this.publicKeys = [
+      'Id','AmmunitionType','Rounds','User'
+    ];
+  }
+}
+
+module.exports = Ammunition;

package/models/ammunitionType.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class AmmunitionType extends Record{
+
+  static table = 'AmmunitionType';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(AmmunitionType.database,AmmunitionType.table,AmmunitionType.primaryKey,id);
+    this.publicKeys = [
+      'Id','Manufacturer','Caliber','BulletWeight','Casing','BulletType','MuzzleVelocity'
+    ];
+  }
+}
+
+module.exports = AmmunitionType;

package/models/caliber.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class Caliber extends Record{
+
+  static table = 'Caliber';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(Caliber.database,Caliber.table,Caliber.primaryKey,id);
+    this.publicKeys = [
+      'Id','Label'
+    ];
+  }
+}
+
+module.exports = Caliber;

package/models/firearm.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class Firearm extends Record{
+
+  static table = 'Firearm';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(Firearm.database,Firearm.table,Firearm.primaryKey,id);
+    this.publicKeys = [
+      'Id','FirearmType','NickName','Serial_Number','AcquisitionDate', 'Price', 'CurrentOptic', 'User'
+    ];
+  }
+}
+
+module.exports = Firearm;

package/models/firearmImage.js

@@ -0,0 +1,31 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class FirearmImage extends Record{
+
+  static table = 'FirearmImage';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(FirearmImage.database,FirearmImage.table,FirearmImage.primaryKey,id);
+    this.publicKeys = [
+      'Id','BinaryData','Firearm','Optic', 'User'
+    ];
+  }
+  static async getByFirearmId(firearmId){
+    let records = [];
+    let model = new FirearmImage();
+    let ids = await model.db.table(model.table).select(model.primaryKey).where('Firearm = ' + firearmId).execute();
+    for(let id in ids){
+      let obj = await new FirearmImage(ids[id][model.primaryKey]).init();
+      records.push(obj.getPublicProperties());
+    }
+    return records;
+  }
+}
+
+module.exports = FirearmImage;

package/models/firearmType.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class FirearmType extends Record{
+
+  static table = 'FirearmType';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(FirearmType.database,FirearmType.table,FirearmType.primaryKey,id);
+    this.publicKeys = [
+      'Id','Manufacturer','Caliber','Model', 'LinkToProduct', 'MSRP'
+    ];
+  }
+}
+
+module.exports = FirearmType;

package/models/manufacturer.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class Manufacturer extends Record{
+
+  static table = 'Manufacturer';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(Manufacturer.database,Manufacturer.table,Manufacturer.primaryKey,id);
+    this.publicKeys = [
+      'Id','Name','Website', 'Firearm', 'Ammo', 'Optic'
+    ];
+  }
+}
+
+module.exports = Manufacturer;

package/models/optic.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class Optic extends Record{
+
+  static table = 'Optic';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(Optic.database,Optic.table,Optic.primaryKey,id);
+    this.publicKeys = [
+      'Id','OpticType', 'AcquisitionDate', 'SerialNumber', 'Price', 'User'
+    ];
+  }
+}
+
+module.exports = Optic;

package/models/opticType.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class OpticType extends Record{
+
+  static table = 'OpticType';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(OpticType.database,OpticType.table,OpticType.primaryKey,id);
+    this.publicKeys = [
+      'Id','Manufacturer', 'Name', 'MagnificationTimes', 'LinkToProduct', 'MSRP'
+    ];
+  }
+}
+
+module.exports = OpticType;

package/models/shoot.js

@@ -0,0 +1,44 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+const Firearm = require('./firearm');
+const Ammo = require('./ammunition');
+
+class Shoot extends Record{
+
+  static table = 'Shoot';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(Shoot.database,Shoot.table,Shoot.primaryKey,id);
+    this.publicKeys = [
+      'Id','Firearm','Ammo','Rounds','Distance_Ft','Created', 'Optic', 'User'
+    ];
+  }
+  static async new(firearmId, ammoId, rounds, distance_ft, optic, user){
+    let firearm;
+    let ammo;
+    let shoot = new Shoot();
+    try{
+      firearm = await new Firearm(firearmId).init(); //validate firarmId
+      ammo = await new Ammo(ammoId).init();
+      ammo.Rounds -= rounds;
+      await ammo.update();
+    }catch(err){
+      throw err;
+    }
+    shoot.Firearm = firearmId;
+    shoot.Ammo = ammoId;
+    shoot.Rounds = rounds;
+    shoot.Distance_Ft = distance_ft;
+    shoot.Optic = optic;
+    shoot.Created = shoot.db.date();
+    shoot.User = user;
+    return await shoot.create();
+  }
+}
+
+module.exports = Shoot;

package/models/targetImage.js

@@ -0,0 +1,31 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class TargetImage extends Record{
+
+  static table = 'TargetImage';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(TargetImage.database,TargetImage.table,TargetImage.primaryKey,id);
+    this.publicKeys = [
+      'Id','ShootId','BinaryData', 'User'
+    ];
+  }
+  static async getByShootId(shootId){
+    let records = [];
+    let model = new TargetImage();
+    let ids = await model.db.table(model.table).select(model.primaryKey).where('ShootId = ' + shootId).execute();
+    for(let id in ids){
+      let obj = await new TargetImage(ids[id][model.primaryKey]).init();
+      records.push(obj.getPublicProperties());
+    }
+    return records;
+  }
+}
+
+module.exports = TargetImage;

package/models/vendor.js

@@ -0,0 +1,21 @@
+"use strict";
+
+const Record = require('@outlawdesigns/db-record');
+
+class Vendor extends Record{
+
+  static table = 'Vendor';
+  static primaryKey = 'Id';
+  static get database(){
+    return process.env.ARMORY_MYSQL_DB || 'Armory';
+  }
+
+  constructor(id){
+    super(Vendor.database,Vendor.table,Vendor.primaryKey,id);
+    this.publicKeys = [
+      'Id','Name','Website', 'User'
+    ];
+  }
+}
+
+module.exports = Vendor;

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@outlawdesigns/armorysdk",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": "SDK for Armory Service",
+  "dependencies": {
+    "@outlawdesigns/db-record": "^1.1.0"
+  }
+}