yalidine-sdk 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# yalidine-sdk
+
+Core SDK for interacting with the Yalidine API.  
+Provides helpers for parcel creation, fee calculation, tracking, and related operations.
+
+## Installation
+
+```bash
+npm install yalidine-sdk
+```
+
+## Documentation
+
+Full documentation is available here:
+[SDK documentation](../../docs/core/index.md)

package/dist/index.cjs

@@ -0,0 +1,512 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.js
+var index_exports = {};
+__export(index_exports, {
+  calculateBillableWeight: () => calculateBillableWeight,
+  createParcels: () => createParcels,
+  getCentersByCommune: () => getCentersByCommune,
+  getCentersByWilaya: () => getCentersByWilaya,
+  getCommunesByWilaya: () => getCommunesByWilaya,
+  getFees: () => getFees,
+  getWilayas: () => getWilayas
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/helpers/calculateBillabeWeight.js
+function calculateBillableWeight(height, width, length, weight) {
+  const volumetricWeight = height * width * length * 2e-4;
+  return weight > volumetricWeight ? weight : volumetricWeight;
+}
+
+// src/utils.js
+function ensureServer() {
+  if (typeof window !== "undefined") {
+    throw new Error(
+      "astro-yalidine: server-only helper imported in client code. Use these helpers only in server contexts ( API routes, server-side page formatter, etc.)."
+    );
+  }
+}
+function getConfig() {
+  if (typeof __YALIDINE_CONFIG__ === void 0 || !__YALIDINE_CONFIG__) {
+    throw new Error(
+      "astro-yalidine: Configuration missing. Did you add yalidine to astro.config.mjs ?"
+    );
+  }
+  return __YALIDINE_CONFIG__;
+}
+async function setRequest({ endpoint, method = "GET", options = {}, params = {} }) {
+  const { apiId, apiToken, apiUrl } = getConfig();
+  const query = new URLSearchParams(params).toString();
+  const url = `${apiUrl.replace(/\/$/, "")}/${endpoint.replace(/^\//, "")}${query ? `?${query}` : ""}`;
+  const fetchOptions = {
+    method,
+    headers: {
+      "X-API-ID": apiId.trim(),
+      "X-API-TOKEN": apiToken.trim(),
+      "Accept": "application/json",
+      ...options.headers
+    }
+  };
+  if (method !== "GET" && options.body) {
+    fetchOptions.body = JSON.stringify(options.body);
+  }
+  const res = await fetch(url, fetchOptions);
+  if (!res.ok) {
+    throw new Error(`'Request failed: ${res.status} ${res.statusText}`);
+  }
+  return await res.json();
+}
+function getIds(options) {
+  return options.id.split(",").map(Number);
+}
+function calculateOverWeight(baseFee, overSizeFee, weight) {
+  if (weight <= 5) {
+    return baseFee;
+  } else {
+    return baseFee + overSizeFee * (weight - 5);
+  }
+}
+function validateParcels(parcels) {
+  if (!parcels || parcels.length === 0) {
+    throw new Error("At least one parcel should be entered!");
+  }
+  if (parcels.length > 50) {
+    throw new Error("Too many parcels in one request. Please split into smaller batches.");
+  }
+  let errorsCount = 0;
+  let errorMessage = "";
+  const displayErrorCount = (count) => count === 1 ? "One error" : `${count} errors`;
+  parcels.forEach((parcel, index) => {
+    const requiredStrings = [
+      "order_id",
+      "from_wilaya_name",
+      "firstname",
+      "familyname",
+      "contact_phone",
+      "address",
+      "to_commune_name",
+      "to_wilaya_name",
+      "product_list"
+    ];
+    requiredStrings.forEach((field) => {
+      if (!parcel[field] || typeof parcel[field] !== "string" || parcel[field].trim().length === 0) {
+        errorsCount++;
+        errorMessage += `Parcel ${index}: ${field} must be a non-empty string
+`;
+      }
+    });
+    const numericFields = ["price", "declared_value", "length", "width", "height", "weight"];
+    numericFields.forEach((field) => {
+      if (parcel[field] == null || typeof parcel[field] !== "number" || parcel[field] < 0) {
+        errorsCount++;
+        errorMessage += `Parcel ${index}: ${field} must be a number >= 0
+`;
+      }
+    });
+    if (parcel.price < 0 || parcel.price > 15e4) {
+      errorsCount++;
+      errorMessage += `Parcel ${index}: price must be between 0 and 150000
+`;
+    }
+    if (parcel.declared_value < 0 || parcel.declared_value > 15e4) {
+      errorsCount++;
+      errorMessage += `Parcel ${index}: declared_value must be between 0 and 150000
+`;
+    }
+    const booleanFields = ["do_insurance", "freeshipping", "is_stopdesk", "has_exchange", "economic"];
+    booleanFields.forEach((field) => {
+      if (parcel[field] != null && typeof parcel[field] !== "boolean") {
+        errorsCount++;
+        errorMessage += `Parcel ${index}: ${field} must be a boolean if provided
+`;
+      }
+    });
+    if (parcel.is_stopdesk && (!parcel.stopdesk_id || typeof parcel.stopdesk_id !== "string")) {
+      errorsCount++;
+      errorMessage += `Parcel ${index}: stopdesk_id is required when is_stopdesk is true
+`;
+    }
+    if (parcel.has_exchange && (!parcel.product_to_collect || typeof parcel.product_to_collect !== "string")) {
+      errorsCount++;
+      errorMessage += `Parcel ${index}: product_to_collect is required when has_exchange is true
+`;
+    }
+    if (parcel.contact_phone) {
+      const phones = parcel.contact_phone.split(",").map((p) => p.trim());
+      phones.forEach((p) => {
+        if (!/^0\d{8,9}$/.test(p)) {
+          errorsCount++;
+          errorMessage += `Parcel ${index}: contact_phone "${p}" is invalid, must start with 0 and be 9 or 10 digits
+`;
+        }
+      });
+    }
+  });
+  if (errorsCount > 0) {
+    throw new Error(`${displayErrorCount(errorsCount)} prevent the helper from sending the request:
+${errorMessage}`);
+  }
+  return true;
+}
+
+// src/helpers/calculateParcels.js
+async function createParcels(...parcels) {
+  ensureServer();
+  validateParcels(parcels);
+  const data = await setRequest({
+    endpoint: "parcel",
+    method: "POST",
+    params: { body: parcels }
+  });
+  const succeededParcels = [];
+  const failedParcels = [];
+  for (const [orderId, result] of Object.entries(data)) {
+    if (result.success) succeededParcels.push(orderId);
+    else failedParcels.push(orderId);
+  }
+  return {
+    data,
+    meta: { succeededParcels, failedParcels }
+  };
+}
+
+// src/helpers/getCentersByCommune.js
+async function getCentersByCommune({
+  communeId,
+  params = {}
+}) {
+  ensureServer();
+  if (!communeId) {
+    throw new Error("A commune Id must be entered to retrieve centers.");
+  }
+  const response = await setRequest({
+    endpoint: "centers",
+    params: {
+      commune_id: communeId,
+      ...params
+    }
+  });
+  const centers = response.data;
+  return centers.map((c) => ({
+    id: c.center_id,
+    name: c.name,
+    address: c.address,
+    gps: c.gps,
+    commune_id: c.commune_id,
+    commune_name: c.commune_name,
+    wilaya_id: c.wilaya_id
+  }));
+}
+
+// src/cache/fileCacheAdapter.js
+var import_fs = __toESM(require("fs"), 1);
+var import_path = __toESM(require("path"), 1);
+
+// src/cache/cacheAdapter.js
+var CacheAdapter = class {
+  async get(key) {
+    throw new Error("Not implemented");
+  }
+  async set(key, value, ttl) {
+    throw new Error("Not implemented");
+  }
+  async delete(key) {
+    throw new Error("Not implemented");
+  }
+};
+
+// src/cache/memoryCacheAdapter.js
+var MemoryCacheAdapter = class extends CacheAdapter {
+  constructor() {
+    super();
+    this.cache = /* @__PURE__ */ new Map();
+  }
+  async get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+    if (entry.expiry && date.now() > entry.expiry) {
+      this.cache.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+  async set(key, value, ttl) {
+    const expiry = ttl ? Date.now() + ttl : null;
+    this.cache.set(key, { value, expiry });
+  }
+  async delete(key) {
+    this.cache.delete(key);
+  }
+};
+
+// src/cache/fileCacheAdapter.js
+var FileCacheAdapter = class extends CacheAdapter {
+  constructor(filePath = "./.cache/yalidine.json") {
+    super();
+    this.filePath = filePath;
+    this.memoryFallback = new MemoryCacheAdapter();
+    this.load();
+  }
+  load() {
+    try {
+      if (import_fs.default.existsSync(this.filePath)) {
+        const json = JSON.parse(import_fs.default.readFileSync(this.filePath, "utf-8"));
+        this.store = new Map(Object.entries(json));
+      } else {
+        this.store = /* @__PURE__ */ new Map();
+      }
+    } catch {
+      this.store = null;
+    }
+  }
+  async get(key) {
+    if (!this.store) return this.memoryFallback.get(key);
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (entry.expiry && Date.now() > entry.expiry) {
+      this.store.delete(key);
+      this.save();
+      return null;
+    }
+    return entry.value;
+  }
+  async set(key, value, ttl) {
+    if (!this.store) return this.memoryFallback.set(key, value, ttl);
+    const expiry = ttl ? Date.now() + ttl : null;
+    this.store.set(key, { value, expiry });
+    this.save();
+  }
+  save() {
+    try {
+      import_fs.default.mkdirSync(import_path.default.dirname(this.filePath), { recursive: true });
+      import_fs.default.writeFileSync(
+        this.filePath,
+        JSON.stringify(Object.fromEntries(this.store), null, 2)
+      );
+    } catch {
+      this.store = null;
+    }
+  }
+  async delete(key) {
+    if (!this.store) return this.memoryFallback.delete(key);
+    this.store.delete(key);
+    this.save();
+  }
+};
+
+// src/cache/cacheConfig.js
+function getCacheConfig() {
+  const { defaultCache, cacheLifeTime } = getConfig();
+  const CACHE_TTL = cacheLifeTime * 1e3 * 60 * 60 * 24;
+  let cache;
+  switch (defaultCache) {
+    case "file":
+      cache = new FileCacheAdapter();
+      break;
+    case "memory":
+    default:
+      cache = new MemoryCacheAdapter();
+      break;
+  }
+  return {
+    cache,
+    CACHE_TTL
+  };
+}
+
+// src/helpers/getCentersByWilaya.js
+async function getCentersByWilaya({
+  wilayaId,
+  params = {}
+}) {
+  ensureServer();
+  if (!wilayaId) {
+    throw new Error("A wilaya Id must be entered to retrieve centers.");
+  }
+  const { cache, CACHE_TTL } = getCacheConfig();
+  const cacheKey = `centers-${wilayaId}`;
+  const cached = await cache.get(cacheKey);
+  let centers;
+  if (cached) {
+    centers = cached;
+  } else {
+    const response = await setRequest({
+      endpoint: "centers",
+      params: {
+        wilaya_id: wilayaId,
+        ...params
+      }
+    });
+    centers = response.data;
+    await cache.set(cacheKey, centers, CACHE_TTL);
+  }
+  return centers.map((c) => ({
+    id: c.center_id,
+    name: c.name,
+    address: c.address,
+    gps: c.gps,
+    commune_id: c.commune_id,
+    commune_name: c.commune_name,
+    wilaya_id: c.wilaya_id
+  }));
+}
+
+// src/helpers/getCommunesByWilaya.js
+async function getCommunesByWilaya({
+  wilayaId,
+  deliverableOnly = true,
+  hasStopDesk = false,
+  params = {}
+}) {
+  ensureServer();
+  const { cache, CACHE_TTL } = getCacheConfig();
+  const isPartial = Boolean(params.id);
+  const cacheKey = `communes-${wilayaId}`;
+  const cached = await cache.get(cacheKey);
+  let communes;
+  if (cached) {
+    if (isPartial) {
+      const ids = getIds(params);
+      communes = cached.filter((c) => ids.includes(c.id));
+    } else {
+      communes = cached;
+    }
+  } else {
+    const response = await setRequest({
+      endpoint: "communes",
+      params: {
+        wilaya_id: wilayaId,
+        ...params
+      }
+    });
+    communes = response.data;
+    if (!isPartial) {
+      await cache.set(cacheKey, communes, CACHE_TTL);
+    }
+  }
+  const cleanedDeliverability = deliverableOnly ? communes.filter((c) => c.is_deliverable === 1) : communes;
+  const cleaned = hasStopDesk ? cleanedDeliverability.filter((c) => c.has_stop_desk === 1) : cleanedDeliverability;
+  return cleaned.map((c) => ({
+    id: c.id,
+    name: c.name,
+    delivery_time_parcel: c.delivery_time_parcel,
+    ...deliverableOnly ? {} : { is_deliverable: c.is_deliverable },
+    ...hasStopDesk ? {} : { has_stop_desk: c.has_stop_desk }
+  }));
+}
+
+// src/helpers/getFees.js
+async function getFees({
+  fromWilayaId,
+  toWilayaId,
+  toCommuneId,
+  billableWeight = 5
+}) {
+  ensureServer();
+  if (!toWilayaId || !toCommuneId) {
+    throw new Error("Destination wilaya and commune are required to calculate fees.");
+  }
+  const safeWeight = typeof billableWeight === "number" && billableWeight > 0 ? billableWeight : 5;
+  const startingWilaya = fromWilayaId ?? getConfig().startingWilaya;
+  const data = await setRequest({
+    endpoint: "fees",
+    params: {
+      from_wilaya_id: startingWilaya,
+      to_wilaya_id: toWilayaId
+    }
+  });
+  if (!data.per_commune[toCommuneId]) {
+    throw new Error("Commune not found");
+  }
+  ;
+  const communeFee = data.per_commune[toCommuneId];
+  const oversizeFee = data.oversize_fee;
+  return {
+    fees: {
+      expressHome: calculateOverWeight(communeFee.express_home, oversizeFee, safeWeight),
+      expressDesk: calculateOverWeight(communeFee.express_desk, oversizeFee, safeWeight),
+      economicHome: communeFee.economic_home ? calculateOverWeight(communeFee.economic_home, oversizeFee, safeWeight) : null,
+      economicDesk: communeFee.economic_desk ? calculateOverWeight(communeFee.economic_desk, oversizeFee, safeWeight) : null
+    },
+    meta: {
+      retourFee: data.retour_fee,
+      codPercentage: data.cod_percentage,
+      insurancePercentage: data.insurance_percentage,
+      oversizeApplied: safeWeight > 5
+    }
+  };
+}
+
+// src/helpers/getWilayas.js
+async function getWilayas({
+  deliverableOnly = true,
+  params = {}
+}) {
+  ensureServer();
+  const { cache, CACHE_TTL } = getCacheConfig();
+  const isPartial = Boolean(params.id);
+  const cacheKey = "wilayas";
+  const cached = await cache.get(cacheKey);
+  let wilayas;
+  if (cached) {
+    if (isPartial) {
+      const ids = getIds(params);
+      wilayas = cached.filter((w) => ids.includes(w.id));
+    } else {
+      wilayas = cached;
+    }
+  } else {
+    const response = await setRequest({
+      endpoint: "wilayas",
+      params
+    });
+    wilayas = response.data;
+    if (!isPartial) {
+      await cache.set(cacheKey, wilayas, CACHE_TTL);
+    }
+  }
+  const cleaned = deliverableOnly ? wilayas.filter((w) => w.is_deliverable === 1) : wilayas;
+  return cleaned.map((w) => ({
+    id: w.id,
+    name: w.name,
+    zone: w.zone,
+    ...deliverableOnly ? {} : { is_deliverable: w.is_deliverable }
+  }));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  calculateBillableWeight,
+  createParcels,
+  getCentersByCommune,
+  getCentersByWilaya,
+  getCommunesByWilaya,
+  getFees,
+  getWilayas
+});