mashroo3 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mashroo3
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# mashroo3
+
+Simple JavaScript client for the Mashroo3 API.
+
+## Install
+
+```bash
+npm install mashroo3
+```
+
+## Quick Start
+
+```js
+const { Mashroo3 } = require("mashroo3");
+
+const mashroo3 = new Mashroo3("YOUR_API_KEY");
+
+const catalog = await mashroo3.catalog.list();
+console.log(catalog);
+```
+
+Also supported:
+
+```js
+const { mashroo3 } = require("mashroo3");
+const client = new mashroo3("YOUR_API_KEY");
+const orders = await client.orders.list();
+```
+
+ESM:
+
+```js
+import Mashroo3 from "mashroo3";
+
+const mashroo3 = new Mashroo3("YOUR_API_KEY");
+const orders = await mashroo3.orders.list();
+```
+
+## Constructor
+
+```js
+new Mashroo3(apiKey, options?)
+```
+
+Options:
+
+- `baseUrl` (default: `https://mashroo3.net`)
+- `timeoutMs` (default: `30000`)
+- `fetch` custom fetch implementation (optional)
+
+## API
+
+### Catalog
+
+```js
+await mashroo3.catalog.list();
+```
+
+### Customers
+
+```js
+await mashroo3.customers.list();
+
+await mashroo3.customers.create({
+  name: "John Doe",
+  phone: "+15550000000",
+});
+```
+
+### Orders
+
+```js
+// Returns latest orders from /api/orders (currently last 10 on server side)
+await mashroo3.orders.list();
+
+await mashroo3.orders.get(44);
+
+await mashroo3.orders.create({
+  customer_id: 12,
+  items: [
+    { product_id: 1, qty: 2 },
+    { product_id: 5, qty: 1 }
+  ],
+  paid: 20
+});
+
+await mashroo3.orders.refund(44, {
+  items: [
+    { order_item_id: 101, qty: 1 }
+  ],
+  reason: "Damaged item"
+});
+```
+
+### Low-level request
+
+```js
+await mashroo3.request("GET", "/api/catalog");
+```
+
+## Error Handling
+
+```js
+try {
+  await mashroo3.orders.get(999999);
+} catch (error) {
+  if (error.name === "Mashroo3Error") {
+    console.error(error.message);
+    console.error(error.status);
+    console.error(error.data);
+  }
+}
+```

package/index.d.ts

@@ -0,0 +1,70 @@
+export type QueryValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Array<string | number | boolean | null | undefined>;
+
+export type QueryParams = Record<string, QueryValue>;
+
+export interface Mashroo3Options {
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}
+
+export interface RequestOptions {
+  query?: QueryParams;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+export declare class Mashroo3Error extends Error {
+  status: number | null;
+  data: unknown;
+  code: string | null;
+  constructor(
+    message: string,
+    options?: {
+      status?: number | null;
+      data?: unknown;
+      code?: string | null;
+    }
+  );
+}
+
+export declare class Mashroo3 {
+  apiKey: string;
+  baseUrl: string;
+  timeoutMs: number;
+  catalog: {
+    list: (query?: QueryParams) => Promise<any[]>;
+  };
+  customers: {
+    list: (query?: QueryParams) => Promise<any[]>;
+    create: (payload: unknown) => Promise<any>;
+  };
+  orders: {
+    list: (query?: QueryParams) => Promise<any[]>;
+    get: (orderId: number) => Promise<any>;
+    create: (payload: unknown) => Promise<any>;
+    refund: (orderId: number, payload: unknown) => Promise<any>;
+  };
+
+  constructor(apiKey: string, options?: Mashroo3Options);
+  request(method: string, path: string, options?: RequestOptions): Promise<any>;
+
+  listCatalog(query?: QueryParams): Promise<any[]>;
+  listCustomers(query?: QueryParams): Promise<any[]>;
+  createCustomer(payload: unknown): Promise<any>;
+  listOrders(query?: QueryParams): Promise<any[]>;
+  getOrder(orderId: number): Promise<any>;
+  createOrder(payload: unknown): Promise<any>;
+  refundOrder(orderId: number, payload: unknown): Promise<any>;
+}
+
+export declare function mashroo3(apiKey: string, options?: Mashroo3Options): Mashroo3;
+
+declare const _default: typeof Mashroo3;
+export default _default;

package/index.js

@@ -0,0 +1,246 @@
+"use strict";
+
+class Mashroo3Error extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "Mashroo3Error";
+    this.status = options.status ?? null;
+    this.data = options.data ?? null;
+    this.code = options.code ?? null;
+  }
+}
+
+class Mashroo3 {
+  constructor(apiKey, options = {}) {
+    if (typeof apiKey !== "string" || apiKey.trim() === "") {
+      throw new TypeError("Mashroo3 API key is required.");
+    }
+
+    const providedFetch = options.fetch || globalThis.fetch;
+    if (typeof providedFetch !== "function") {
+      throw new TypeError(
+        "A fetch implementation is required. Use Node.js >= 18 or pass { fetch } in options."
+      );
+    }
+
+    this.apiKey = apiKey.trim();
+    this.baseUrl = String(options.baseUrl || "https://mashroo3.net").replace(
+      /\/+$/,
+      ""
+    );
+    this.timeoutMs =
+      Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
+        ? Number(options.timeoutMs)
+        : 30000;
+    this._fetch = providedFetch;
+
+    this.catalog = {
+      list: (query) => this.listCatalog(query),
+    };
+
+    this.customers = {
+      list: (query) => this.listCustomers(query),
+      create: (payload) => this.createCustomer(payload),
+    };
+
+    this.orders = {
+      list: (query) => this.listOrders(query),
+      get: (orderId) => this.getOrder(orderId),
+      create: (payload) => this.createOrder(payload),
+      refund: (orderId, payload) => this.refundOrder(orderId, payload),
+    };
+  }
+
+  async request(method, path, options = {}) {
+    return this._request(method, path, options);
+  }
+
+  async listCatalog(query = {}) {
+    const payload = await this._request("GET", "/api/catalog", { query });
+    return this._extractList(payload, ["products", "catalog", "items"]);
+  }
+
+  async listCustomers(query = {}) {
+    const payload = await this._request("GET", "/api/customers", { query });
+    return this._extractList(payload, ["customers", "items"]);
+  }
+
+  async createCustomer(payload) {
+    const response = await this._request("POST", "/api/customers", { body: payload });
+    const data = this._extractData(response);
+    if (data && typeof data === "object" && data.customer) {
+      return data.customer;
+    }
+    return data;
+  }
+
+  async listOrders(query = {}) {
+    const payload = await this._request("GET", "/api/orders", { query });
+    return this._extractList(payload, ["orders", "items"]);
+  }
+
+  async getOrder(orderId) {
+    const normalizedOrderId = this._validateOrderId(orderId);
+    const payload = await this._request("GET", `/api/orders/${normalizedOrderId}`);
+    return this._extractData(payload);
+  }
+
+  async createOrder(payload) {
+    const response = await this._request("POST", "/api/orders", { body: payload });
+    const data = this._extractData(response);
+    if (data && typeof data === "object" && data.order) {
+      return data.order;
+    }
+    return data;
+  }
+
+  async refundOrder(orderId, payload) {
+    const normalizedOrderId = this._validateOrderId(orderId);
+    const response = await this._request(
+      "POST",
+      `/api/orders/${normalizedOrderId}/refund`,
+      { body: payload }
+    );
+    return this._extractData(response);
+  }
+
+  _validateOrderId(orderId) {
+    const parsed = Number(orderId);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+      throw new TypeError("orderId must be a positive integer.");
+    }
+    return parsed;
+  }
+
+  _buildUrl(path, query) {
+    const normalizedPath = String(path || "").startsWith("/") ? path : `/${path}`;
+    const url = new URL(`${this.baseUrl}${normalizedPath}`);
+
+    if (query && typeof query === "object") {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null) continue;
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            if (item === undefined || item === null) continue;
+            url.searchParams.append(key, String(item));
+          }
+        } else {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+
+    return url.toString();
+  }
+
+  _extractData(payload) {
+    if (payload && typeof payload === "object" && "data" in payload) {
+      return payload.data;
+    }
+    return payload;
+  }
+
+  _extractList(payload, listKeys) {
+    const data = this._extractData(payload);
+    if (Array.isArray(data)) return data;
+
+    if (data && typeof data === "object") {
+      for (const key of listKeys) {
+        if (Array.isArray(data[key])) return data[key];
+      }
+    }
+
+    return [];
+  }
+
+  _extractErrorMessage(payload) {
+    if (!payload || typeof payload !== "object") return null;
+    const message = payload.message ?? payload.error ?? payload.errors;
+
+    if (typeof message === "string" && message.trim() !== "") return message;
+    if (Array.isArray(message) && message.length > 0) return String(message[0]);
+    if (message && typeof message === "object") {
+      const values = Object.values(message);
+      if (values.length > 0) return String(values[0]);
+    }
+    return null;
+  }
+
+  async _request(method, path, options = {}) {
+    const upperMethod = String(method || "GET").toUpperCase();
+    const url = this._buildUrl(path, options.query);
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    let response;
+    try {
+      response = await this._fetch(url, {
+        method: upperMethod,
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          "X-API-Key": this.apiKey,
+          "x-api-key": this.apiKey,
+          ...(options.headers || {}),
+        },
+        body:
+          options.body === undefined || upperMethod === "GET"
+            ? undefined
+            : JSON.stringify(options.body),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (error && error.name === "AbortError") {
+        throw new Mashroo3Error(
+          `Request timeout after ${this.timeoutMs}ms for ${upperMethod} ${path}`
+        );
+      }
+      throw new Mashroo3Error(
+        `Network error while calling ${upperMethod} ${path}: ${
+          error && error.message ? error.message : String(error)
+        }`
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    const rawBody = await response.text();
+    let parsedBody = null;
+    if (rawBody) {
+      try {
+        parsedBody = JSON.parse(rawBody);
+      } catch (_) {
+        parsedBody = null;
+      }
+    }
+
+    if (!response.ok) {
+      throw new Mashroo3Error(
+        this._extractErrorMessage(parsedBody) ||
+          `Request failed with status ${response.status}`,
+        { status: response.status, data: parsedBody ?? rawBody }
+      );
+    }
+
+    if (parsedBody && typeof parsedBody === "object" && parsedBody.ok === false) {
+      throw new Mashroo3Error(
+        this._extractErrorMessage(parsedBody) || "Mashroo3 API returned ok=false",
+        { status: response.status, data: parsedBody }
+      );
+    }
+
+    return parsedBody;
+  }
+}
+
+function mashroo3(apiKey, options) {
+  return new Mashroo3(apiKey, options);
+}
+
+module.exports = Mashroo3;
+module.exports.default = Mashroo3;
+module.exports.Mashroo3 = Mashroo3;
+module.exports.mashroo3 = mashroo3;
+module.exports.Mashroo3Error = Mashroo3Error;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "mashroo3",
+  "version": "0.1.0",
+  "description": "Simple JavaScript client for the Mashroo3 API.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mashroo3",
+    "api",
+    "sdk",
+    "orders",
+    "catalog",
+    "inventory"
+  ],
+  "license": "MIT"
+}