@vorlaxen-labs/kargomucuz-sdk 1.0.1

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Hakan Kaygusuz
+  
+  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,156 @@
+# ⚓ Kargomucuz SDK
+
+[![npm version](https://img.shields.io/badge/npm-v1.0.0-orange.svg)](https://www.npmjs.com/package/@vorlaxen-labs/kargomucuz-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-orange.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-orange?logo=typescript)](https://www.typescriptlang.org/)
+[![API](https://img.shields.io/badge/API-REST-orange.svg)](https://kargomucuz.com)
+
+**Official SDK for Kargomucuz. Unified cargo operations, shipment automation, and enterprise-grade logistics infrastructure.**
+
+`@vorlaxen-labs/kargomucuz-sdk` provides a modern, strongly-typed, zero-hassle integration layer for accessing the Kargomucuz API platform.
+
+Designed for scalable e-commerce systems, ERP infrastructures, marketplaces, warehouse management software, and modern backend services.
+
+---
+
+# 🔥 Why Kargomucuz SDK?
+
+Cargo integrations in Türkiye are usually absolute chaos:
+
+* Different authentication systems
+* Different XML/SOAP nightmares
+* Different tracking structures
+* Different provider limitations
+* Different error formats
+
+`@vorlaxen-labs/kargomucuz-sdk` normalizes the entire experience into a single, predictable developer workflow.
+
+* 🚀 Unified API abstraction
+* 📦 Multi-carrier shipment management
+* 🔒 Secure token-based authentication
+* ⚡ Fully typed TypeScript support
+* 🌲 Tree-shakable architecture
+* 🛠️ Enterprise-ready infrastructure
+* 🧩 Modular SDK structure
+* 📈 High-performance request handling
+
+Because nobody wants to debug prehistoric cargo APIs at 3 AM while staring at cursed SOAP XML responses like forbidden ancient scrolls.
+
+---
+
+# 📦 Installation
+
+```bash
+pnpm add @vorlaxen-labs/kargomucuz-sdk
+# or
+npm install @vorlaxen-labs/kargomucuz-sdk
+# or
+yarn add @vorlaxen-labs/kargomucuz-sdk
+```
+
+---
+
+# 🚀 Quick Start
+
+```ts
+import { Kargomucuz } from '@vorlaxen-labs/kargomucuz-sdk';
+
+const km = new Kargomucuz({
+  auth: {
+    apiKey: process.env.KARGOMUCUZ_API_KEY
+  },
+
+  environment: 'production', // production or development
+
+  timeout: 10_000,
+
+  retry: {
+    retries: 3,
+    backoff: 'exponential'
+  },
+
+  logger: console
+});
+```
+
+---
+
+# 🛠️ SDK Architecture
+
+The SDK is built around modular service namespaces.
+
+### Core Modules
+
+* Shipments
+* Labels
+* Orders
+
+---
+
+# ⚡ Features
+
+### 📦 Shipment Management
+
+Create, manage, cancel, and automate cargo operations from a single API layer.
+
+### 🔒 Secure by Default
+
+Enterprise-focused authentication and request validation systems.
+
+---
+
+# 🌍 Built For
+
+* E-Commerce Platforms
+* ERP Systems
+* Warehouse Software
+* Marketplace Infrastructure
+* Logistics Automation
+* Enterprise SaaS Products
+* Modern Node.js Backends
+
+---
+
+# 🌲 Tree-Shakable Imports
+
+Import only what you use.
+
+```ts
+import { Kargomucuz } from '@vorlaxen-labs/kargomucuz-sdk';
+```
+
+---
+
+# 📖 Documentation
+
+Full documentation, API references, examples, provider integrations, and advanced guides are available on the official documentation platform.
+
+### Official Links
+
+* Website → [https://kargomucuz.com](https://kargomucuz.com)
+* Documentation → [https://docs.vorlaxen.com/projects/kargomucuz-sdk](https://docs.vorlaxen.com/projects/kargomucuz-sdk)
+* API Platform → [https://api.kargomucuz.com](https://api.kargomucuz.com)
+
+---
+
+# 📐 Design Philosophy
+
+> **"Logistics infrastructure should feel invisible."**
+
+`@vorlaxen-labs/kargomucuz-sdk` is designed to eliminate operational friction between your application and cargo providers.
+
+Instead of forcing developers to deal with fragmented logistics ecosystems, the SDK provides a clean, stable, and scalable abstraction layer.
+
+The goal is simple:
+
+Write less integration code.
+Ship more packages.
+Lose less sanity.
+
+---
+
+# ⚖️ License
+
+Distributed under the MIT License.
+
+Built with precision by **Vorlaxen Labs**.

package/dist/index.cjs

@@ -0,0 +1,10 @@
+"use strict";var R=Object.create;var m=Object.defineProperty;var I=Object.getOwnPropertyDescriptor;var S=Object.getOwnPropertyNames;var C=Object.getPrototypeOf,K=Object.prototype.hasOwnProperty;var T=(o,r)=>{for(var e in r)m(o,e,{get:r[e],enumerable:!0})},A=(o,r,e,s)=>{if(r&&typeof r=="object"||typeof r=="function")for(let t of S(r))!K.call(o,t)&&t!==e&&m(o,t,{get:()=>r[t],enumerable:!(s=I(r,t))||s.enumerable});return o};var _=(o,r,e)=>(e=o!=null?R(C(o)):{},A(r||!o||!o.__esModule?m(e,"default",{value:o,enumerable:!0}):e,o)),w=o=>A(m({},"__esModule",{value:!0}),o);var z={};T(z,{APIError:()=>c,AuthError:()=>d,Currency:()=>v,Kargomucuz:()=>f,KargomucuzError:()=>i,ProviderServiceCode:()=>b});module.exports=w(z);var x=_(require("axios"),1);var l=class{constructor(r){this.logger=null;r===console||r===!0?this.logger=console:typeof r=="object"&&r!==null&&"info"in r&&"error"in r&&(this.logger=r)}info(r,e){this.logger&&this.logger.info(`\x1B[36m[KM-SDK]\x1B[0m ${r}`,e??"")}error(r,e){this.logger&&this.logger.error(`\x1B[31m[KM-SDK-ERROR]\x1B[0m ${r}`,e??"")}};var i=class extends Error{constructor(r){super(r),this.name="KargomucuzError"}};var c=class extends i{constructor(e,s,t){super(e);this.statusCode=s;this.response=t;this.name="APIError"}};var d=class extends i{constructor(r="Authentication failed."){super(r),this.name="AuthError"}};var a=class{constructor(r){this.config=r;let e="https://api.kargomucuz.com";this.logger=new l(r.logger),this.instance=x.default.create({baseURL:e,timeout:r.timeout||1e4,headers:{"Content-Type":"application/json",Authorization:`Bearer ${r.auth.apiKey}`,"X-SDK-Client":!0}}),this.initializeInterceptors()}initializeInterceptors(){this.instance.interceptors.request.use(r=>{if(this.config.environment!=="production"){let e=`${r.baseURL}${r.url||""}`;this.logger.info(`\x1B[36m[KM-SDK] ${r.method?.toUpperCase()} -> ${e}\x1B[0m`),r.params&&this.logger.info("Query Params:",JSON.stringify(r.params,null,2)),r.data&&this.logger.info("Body:",JSON.stringify(r.data,null,2))}return r}),this.instance.interceptors.response.use(r=>{let e=r.data;if(this.logger.info("Request Success",e),e.status===!1){let s=e.code||r.status;throw new c(e.message||"API Error",s,e)}return e},r=>{let e=r.response?.data,s=e?.code||r.response?.status;return this.logger.error("Request Failed",e||{message:r.message}),s===401||s===403?Promise.reject(new d(e?.message)):Promise.reject(new c(e?.message||r.message,s,e))})}async httpGet(r,e){return this.instance.get(r,e)}async httpPost(r,e,s){return this.instance.post(r,e,s)}};var g=class extends a{constructor(e){super(e.getConfig());this.client=e}async create(e){let s={type:e.role,title:e.title,location:{country:{id:e.location.countryId},city:{id:e.location.cityId},district:{id:e.location.districtId},address:{line1:e.location.addressLine1},postCode:e.location.postCode},by:{entity:e.contact.fullName,phone1:{phoneCountryCode:e.contact.phoneCountryCode,number:e.contact.phoneNumber},email:e.contact.email}},n=(await this.httpPost("/v1/addresses/0",s))?.payload?.data;if(!n)throw new Error("Address data missing in API response.");return this.mapAddress(n)}async list(){let e=this.client.getUserId(),t=(await this.httpGet(`/v1/addresses/${e}`))?.payload?.data;if(!Array.isArray(t))return{senders:[],receivers:[]};let n=t.map(u=>this.mapAddress(u));return{senders:n.filter(u=>u.role==="sender"),receivers:n.filter(u=>u.role==="receiver")}}async retrieve(e){let s=this.client.getUserId(),n=(await this.httpGet(`/v1/addresses/${s}/${e}`))?.payload?.data;if(!n)throw new Error(`Address with ID ${e} not found.`);return this.mapAddress(n)}async resolve(e){let t=(await this.httpPost("/others/convert-address-id",{id:e.toString()}))?.payload?.data;return Array.isArray(t)?t[0]||null:t||null}mapAddress(e){return{id:e._id,role:e.type,title:e.title,contact:{fullName:e.by?.entity,phone:{number:e.by?.phone1?.number??"",country:e.by?.phone1?.phoneCountryCode??""},email:e.by?.email},location:{country:e.location?.country?.title??"T\xFCrkiye",city:e.location?.city?.title,district:e.location?.district?.title,addressLine:e.location?.address?.line1,postCode:e.location?.postCode},createdAt:e.others?.created}}};var y=class extends a{constructor(e){super(e.getConfig());this.client=e}async get(e){let t=(await this.httpGet("/v1/shipments/desi-or-kgs",{params:{providerServiceCode:e.serviceCode,desiOrKg:e.weightOrDesi}}))?.payload?.data,n=Array.isArray(t)?t[0]:t;if(!n)throw new Error("Pricing data not found for the given parameters.");return{amount:Number(n.amount),currency:(n.currency||"TRY").toUpperCase(),providerCode:e.serviceCode}}};var h=class extends a{constructor(e){super(e.getConfig());this.client=e}async getDetail(e){let s=await this.httpGet(`/v1/shipments/0/${e}`);if(!s.payload?.data)throw new Error(s.message??`Shipment not found: ${e}`);let t=s.payload.data;return{id:t._id,providerServiceCode:t.shipmentInfo?.provider?.serviceCode,trackingNumber:t.shipmentInfo?.shipmentReferenceCode??t.labelData?.barcodeValue,status:t.shipmentInfo?.status,createdAt:t.others?.created,savedSenderAddress:null,savedReceiverAddress:null}}async create(e){let s={title:e.title??"Shipment",explanation:e.explanation??"",providerServiceCode:e.providerServiceCode,packageInfo:e.packageInfo,selectedSenderAddressId:e.sender.id,selectedReceiverAddressId:e.receiver.id,buyerPayShipping:e.buyerPayShipping??!1,buyerPayProduct:e.buyerPayProduct??!1},t=await this.httpPost("/v1/shipments/0",s);if(!t.payload)throw new Error(t.message??"Shipment could not be created.");let n=t.payload;return{id:n.shipmentTransactionId,providerServiceCode:n.providerServiceCode,trackingNumber:void 0,savedSenderAddress:n.savedSenderAddress,savedReceiverAddress:n.savedReceieverAddress}}};var f=class{constructor(r){this.userId="0";this.config=Object.freeze({environment:"production",timeout:1e4,...r})}asUser(r){return this.userId=r,this}getUserId(){return this.userId}getConfig(){return this.config}get addresses(){return new g(this)}get rates(){return new y(this)}get shipments(){return new h(this)}getBaseUrl(){return"https://api.kargomucuz.com/v1"}};var v=(s=>(s.TRY="try",s.USD="usd",s.EUR="eur",s))(v||{}),b=(p=>(p.PTT_FIXED_PRICE="ptt_fixed_price",p.PTT_STANDART_2="ptt_standart_2",p.HEPSIJET_STANDART_2="hepsijet_standart_2",p.SURAT_STANDART_2="surat_standart_2",p.UPS_STANDART_2="ups_standart_2",p.KOLAYGELSIN_STANDART_2="kolaygelsin_standart_2",p.YURTICI_STANDART_2="yurtici_standart_2",p))(b||{});0&&(module.exports={APIError,AuthError,Currency,Kargomucuz,KargomucuzError,ProviderServiceCode});
+/**
+ * @file index.ts
+ * @description Official Kargomucuz SDK Entry Point
+ * @author Hakan Kaygusuz <hakankaygusuz@vorlaxen.com>
+ * @copyright (c) 2024 Vorlaxen Labs
+ * @license MIT
+ * 
+ * "Building the bridge between modern web and legacy logistics."
+ */

package/dist/index.d.cts

@@ -0,0 +1,200 @@
+import { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+declare enum Currency {
+    TRY = "try",
+    USD = "usd",
+    EUR = "eur"
+}
+declare enum ProviderServiceCode {
+    PTT_FIXED_PRICE = "ptt_fixed_price",
+    PTT_STANDART_2 = "ptt_standart_2",
+    HEPSIJET_STANDART_2 = "hepsijet_standart_2",
+    SURAT_STANDART_2 = "surat_standart_2",
+    UPS_STANDART_2 = "ups_standart_2",
+    KOLAYGELSIN_STANDART_2 = "kolaygelsin_standart_2",
+    YURTICI_STANDART_2 = "yurtici_standart_2"
+}
+
+interface IKargomucuzLogger {
+    info(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    warn?(message: string, ...args: any[]): void;
+    debug?(message: string, ...args: any[]): void;
+}
+type IEnvironments = 'production' | 'development';
+interface ApiResponse<T = any> {
+    status: boolean;
+    message: string;
+    payload?: T;
+    code?: number;
+    errors?: any;
+}
+
+declare class HttpClient {
+    private readonly config;
+    protected readonly instance: AxiosInstance;
+    private readonly logger;
+    constructor(config: KargomucuzConfig);
+    private initializeInterceptors;
+    protected httpGet<T = any>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    protected httpPost<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+}
+
+interface AddressCreateOptions {
+    role: 'sender' | 'receiver';
+    title: string;
+    contact: {
+        fullName: string;
+        phoneCountryCode: string;
+        phoneNumber: string;
+        email: string;
+    };
+    location: {
+        countryId: string;
+        cityId: string | number;
+        districtId: string | number;
+        addressLine1: string;
+        postCode: string;
+    };
+}
+interface Address {
+    id: string;
+    role: "sender" | "receiver";
+    title: string;
+    contact: {
+        fullName: string;
+        phone: {
+            number: string;
+            country: string;
+        };
+        email: string;
+    };
+    location: {
+        country: string;
+        city: string;
+        district: string;
+        addressLine: string;
+        postCode: string;
+    };
+    createdAt: string;
+}
+
+declare class AddressesService extends HttpClient {
+    private client;
+    constructor(client: Kargomucuz);
+    create(options: AddressCreateOptions): Promise<Address>;
+    list(): Promise<{
+        senders: Address[];
+        receivers: Address[];
+    }>;
+    retrieve(id: string): Promise<Address>;
+    resolve(id: string | number): Promise<any | null>;
+    private mapAddress;
+}
+
+interface RateQueryOptions {
+    serviceCode: string;
+    weightOrDesi: string | number;
+}
+interface RateResult {
+    amount: number;
+    currency: string;
+    providerCode: string;
+}
+
+declare class RatesService extends HttpClient {
+    private client;
+    constructor(client: Kargomucuz);
+    get(params: RateQueryOptions): Promise<RateResult>;
+}
+
+interface ShipmentItem {
+    name: string;
+    quantity: number;
+    unitPrice: number;
+}
+interface ShipmentPackageInfo {
+    desiOrKg: string;
+    width: string;
+    height: string;
+    depth: string;
+    weight: string;
+    itemsAmountCurrency: Currency;
+    itemsTaxAmount: number;
+    itemsAmount: number;
+    items: ShipmentItem[];
+}
+interface ShipmentPackageInfo {
+    desiOrKg: string;
+    width: string;
+    height: string;
+    depth: string;
+    weight: string;
+    itemsAmountCurrency: Currency;
+    itemsTaxAmount: number;
+    itemsAmount: number;
+    items: ShipmentItem[];
+}
+interface CreateShipmentRequest {
+    sender: Address;
+    receiver: Address;
+    providerServiceCode: ProviderServiceCode;
+    packageInfo: ShipmentPackageInfo;
+    title?: string;
+    explanation?: string;
+    buyerPayShipping?: boolean;
+    buyerPayProduct?: boolean;
+}
+interface ShipmentResult {
+    id: string;
+    providerServiceCode: string;
+    trackingNumber?: string;
+    status?: string;
+    createdAt?: string;
+    savedSenderAddress: any | null;
+    savedReceiverAddress: any | null;
+}
+
+declare class ShipmentService extends HttpClient {
+    private readonly client;
+    constructor(client: Kargomucuz);
+    getDetail(shipmentId: string): Promise<ShipmentResult>;
+    create(request: CreateShipmentRequest): Promise<ShipmentResult>;
+}
+
+interface KargomucuzConfig {
+    auth: {
+        apiKey: string;
+    };
+    environment?: IEnvironments;
+    timeout?: number;
+    logger?: IKargomucuzLogger | boolean;
+}
+declare class Kargomucuz {
+    private readonly config;
+    private userId;
+    constructor(config: KargomucuzConfig);
+    asUser(id: string): this;
+    getUserId(): string;
+    getConfig(): KargomucuzConfig;
+    get addresses(): AddressesService;
+    get rates(): RatesService;
+    get shipments(): ShipmentService;
+    getBaseUrl(): string;
+}
+
+declare class KargomucuzError extends Error {
+    constructor(message: string);
+}
+
+declare class APIError extends KargomucuzError {
+    readonly statusCode?: number | undefined;
+    readonly response?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
+}
+
+declare class AuthError extends KargomucuzError {
+    constructor(message?: string);
+}
+
+export { APIError, type ApiResponse, AuthError, Currency, type IEnvironments, type IKargomucuzLogger, Kargomucuz, KargomucuzError, ProviderServiceCode };

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+import { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+declare enum Currency {
+    TRY = "try",
+    USD = "usd",
+    EUR = "eur"
+}
+declare enum ProviderServiceCode {
+    PTT_FIXED_PRICE = "ptt_fixed_price",
+    PTT_STANDART_2 = "ptt_standart_2",
+    HEPSIJET_STANDART_2 = "hepsijet_standart_2",
+    SURAT_STANDART_2 = "surat_standart_2",
+    UPS_STANDART_2 = "ups_standart_2",
+    KOLAYGELSIN_STANDART_2 = "kolaygelsin_standart_2",
+    YURTICI_STANDART_2 = "yurtici_standart_2"
+}
+
+interface IKargomucuzLogger {
+    info(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    warn?(message: string, ...args: any[]): void;
+    debug?(message: string, ...args: any[]): void;
+}
+type IEnvironments = 'production' | 'development';
+interface ApiResponse<T = any> {
+    status: boolean;
+    message: string;
+    payload?: T;
+    code?: number;
+    errors?: any;
+}
+
+declare class HttpClient {
+    private readonly config;
+    protected readonly instance: AxiosInstance;
+    private readonly logger;
+    constructor(config: KargomucuzConfig);
+    private initializeInterceptors;
+    protected httpGet<T = any>(url: string, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+    protected httpPost<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<ApiResponse<T>>;
+}
+
+interface AddressCreateOptions {
+    role: 'sender' | 'receiver';
+    title: string;
+    contact: {
+        fullName: string;
+        phoneCountryCode: string;
+        phoneNumber: string;
+        email: string;
+    };
+    location: {
+        countryId: string;
+        cityId: string | number;
+        districtId: string | number;
+        addressLine1: string;
+        postCode: string;
+    };
+}
+interface Address {
+    id: string;
+    role: "sender" | "receiver";
+    title: string;
+    contact: {
+        fullName: string;
+        phone: {
+            number: string;
+            country: string;
+        };
+        email: string;
+    };
+    location: {
+        country: string;
+        city: string;
+        district: string;
+        addressLine: string;
+        postCode: string;
+    };
+    createdAt: string;
+}
+
+declare class AddressesService extends HttpClient {
+    private client;
+    constructor(client: Kargomucuz);
+    create(options: AddressCreateOptions): Promise<Address>;
+    list(): Promise<{
+        senders: Address[];
+        receivers: Address[];
+    }>;
+    retrieve(id: string): Promise<Address>;
+    resolve(id: string | number): Promise<any | null>;
+    private mapAddress;
+}
+
+interface RateQueryOptions {
+    serviceCode: string;
+    weightOrDesi: string | number;
+}
+interface RateResult {
+    amount: number;
+    currency: string;
+    providerCode: string;
+}
+
+declare class RatesService extends HttpClient {
+    private client;
+    constructor(client: Kargomucuz);
+    get(params: RateQueryOptions): Promise<RateResult>;
+}
+
+interface ShipmentItem {
+    name: string;
+    quantity: number;
+    unitPrice: number;
+}
+interface ShipmentPackageInfo {
+    desiOrKg: string;
+    width: string;
+    height: string;
+    depth: string;
+    weight: string;
+    itemsAmountCurrency: Currency;
+    itemsTaxAmount: number;
+    itemsAmount: number;
+    items: ShipmentItem[];
+}
+interface ShipmentPackageInfo {
+    desiOrKg: string;
+    width: string;
+    height: string;
+    depth: string;
+    weight: string;
+    itemsAmountCurrency: Currency;
+    itemsTaxAmount: number;
+    itemsAmount: number;
+    items: ShipmentItem[];
+}
+interface CreateShipmentRequest {
+    sender: Address;
+    receiver: Address;
+    providerServiceCode: ProviderServiceCode;
+    packageInfo: ShipmentPackageInfo;
+    title?: string;
+    explanation?: string;
+    buyerPayShipping?: boolean;
+    buyerPayProduct?: boolean;
+}
+interface ShipmentResult {
+    id: string;
+    providerServiceCode: string;
+    trackingNumber?: string;
+    status?: string;
+    createdAt?: string;
+    savedSenderAddress: any | null;
+    savedReceiverAddress: any | null;
+}
+
+declare class ShipmentService extends HttpClient {
+    private readonly client;
+    constructor(client: Kargomucuz);
+    getDetail(shipmentId: string): Promise<ShipmentResult>;
+    create(request: CreateShipmentRequest): Promise<ShipmentResult>;
+}
+
+interface KargomucuzConfig {
+    auth: {
+        apiKey: string;
+    };
+    environment?: IEnvironments;
+    timeout?: number;
+    logger?: IKargomucuzLogger | boolean;
+}
+declare class Kargomucuz {
+    private readonly config;
+    private userId;
+    constructor(config: KargomucuzConfig);
+    asUser(id: string): this;
+    getUserId(): string;
+    getConfig(): KargomucuzConfig;
+    get addresses(): AddressesService;
+    get rates(): RatesService;
+    get shipments(): ShipmentService;
+    getBaseUrl(): string;
+}
+
+declare class KargomucuzError extends Error {
+    constructor(message: string);
+}
+
+declare class APIError extends KargomucuzError {
+    readonly statusCode?: number | undefined;
+    readonly response?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: any | undefined);
+}
+
+declare class AuthError extends KargomucuzError {
+    constructor(message?: string);
+}
+
+export { APIError, type ApiResponse, AuthError, Currency, type IEnvironments, type IKargomucuzLogger, Kargomucuz, KargomucuzError, ProviderServiceCode };

package/dist/index.js

@@ -0,0 +1,10 @@
+import f from"axios";var m=class{constructor(r){this.logger=null;r===console||r===!0?this.logger=console:typeof r=="object"&&r!==null&&"info"in r&&"error"in r&&(this.logger=r)}info(r,e){this.logger&&this.logger.info(`\x1B[36m[KM-SDK]\x1B[0m ${r}`,e??"")}error(r,e){this.logger&&this.logger.error(`\x1B[31m[KM-SDK-ERROR]\x1B[0m ${r}`,e??"")}};var p=class extends Error{constructor(r){super(r),this.name="KargomucuzError"}};var c=class extends p{constructor(e,t,s){super(e);this.statusCode=t;this.response=s;this.name="APIError"}};var u=class extends p{constructor(r="Authentication failed."){super(r),this.name="AuthError"}};var i=class{constructor(r){this.config=r;let e="https://api.kargomucuz.com";this.logger=new m(r.logger),this.instance=f.create({baseURL:e,timeout:r.timeout||1e4,headers:{"Content-Type":"application/json",Authorization:`Bearer ${r.auth.apiKey}`,"X-SDK-Client":!0}}),this.initializeInterceptors()}initializeInterceptors(){this.instance.interceptors.request.use(r=>{if(this.config.environment!=="production"){let e=`${r.baseURL}${r.url||""}`;this.logger.info(`\x1B[36m[KM-SDK] ${r.method?.toUpperCase()} -> ${e}\x1B[0m`),r.params&&this.logger.info("Query Params:",JSON.stringify(r.params,null,2)),r.data&&this.logger.info("Body:",JSON.stringify(r.data,null,2))}return r}),this.instance.interceptors.response.use(r=>{let e=r.data;if(this.logger.info("Request Success",e),e.status===!1){let t=e.code||r.status;throw new c(e.message||"API Error",t,e)}return e},r=>{let e=r.response?.data,t=e?.code||r.response?.status;return this.logger.error("Request Failed",e||{message:r.message}),t===401||t===403?Promise.reject(new u(e?.message)):Promise.reject(new c(e?.message||r.message,t,e))})}async httpGet(r,e){return this.instance.get(r,e)}async httpPost(r,e,t){return this.instance.post(r,e,t)}};var l=class extends i{constructor(e){super(e.getConfig());this.client=e}async create(e){let t={type:e.role,title:e.title,location:{country:{id:e.location.countryId},city:{id:e.location.cityId},district:{id:e.location.districtId},address:{line1:e.location.addressLine1},postCode:e.location.postCode},by:{entity:e.contact.fullName,phone1:{phoneCountryCode:e.contact.phoneCountryCode,number:e.contact.phoneNumber},email:e.contact.email}},o=(await this.httpPost("/v1/addresses/0",t))?.payload?.data;if(!o)throw new Error("Address data missing in API response.");return this.mapAddress(o)}async list(){let e=this.client.getUserId(),s=(await this.httpGet(`/v1/addresses/${e}`))?.payload?.data;if(!Array.isArray(s))return{senders:[],receivers:[]};let o=s.map(d=>this.mapAddress(d));return{senders:o.filter(d=>d.role==="sender"),receivers:o.filter(d=>d.role==="receiver")}}async retrieve(e){let t=this.client.getUserId(),o=(await this.httpGet(`/v1/addresses/${t}/${e}`))?.payload?.data;if(!o)throw new Error(`Address with ID ${e} not found.`);return this.mapAddress(o)}async resolve(e){let s=(await this.httpPost("/others/convert-address-id",{id:e.toString()}))?.payload?.data;return Array.isArray(s)?s[0]||null:s||null}mapAddress(e){return{id:e._id,role:e.type,title:e.title,contact:{fullName:e.by?.entity,phone:{number:e.by?.phone1?.number??"",country:e.by?.phone1?.phoneCountryCode??""},email:e.by?.email},location:{country:e.location?.country?.title??"T\xFCrkiye",city:e.location?.city?.title,district:e.location?.district?.title,addressLine:e.location?.address?.line1,postCode:e.location?.postCode},createdAt:e.others?.created}}};var g=class extends i{constructor(e){super(e.getConfig());this.client=e}async get(e){let s=(await this.httpGet("/v1/shipments/desi-or-kgs",{params:{providerServiceCode:e.serviceCode,desiOrKg:e.weightOrDesi}}))?.payload?.data,o=Array.isArray(s)?s[0]:s;if(!o)throw new Error("Pricing data not found for the given parameters.");return{amount:Number(o.amount),currency:(o.currency||"TRY").toUpperCase(),providerCode:e.serviceCode}}};var y=class extends i{constructor(e){super(e.getConfig());this.client=e}async getDetail(e){let t=await this.httpGet(`/v1/shipments/0/${e}`);if(!t.payload?.data)throw new Error(t.message??`Shipment not found: ${e}`);let s=t.payload.data;return{id:s._id,providerServiceCode:s.shipmentInfo?.provider?.serviceCode,trackingNumber:s.shipmentInfo?.shipmentReferenceCode??s.labelData?.barcodeValue,status:s.shipmentInfo?.status,createdAt:s.others?.created,savedSenderAddress:null,savedReceiverAddress:null}}async create(e){let t={title:e.title??"Shipment",explanation:e.explanation??"",providerServiceCode:e.providerServiceCode,packageInfo:e.packageInfo,selectedSenderAddressId:e.sender.id,selectedReceiverAddressId:e.receiver.id,buyerPayShipping:e.buyerPayShipping??!1,buyerPayProduct:e.buyerPayProduct??!1},s=await this.httpPost("/v1/shipments/0",t);if(!s.payload)throw new Error(s.message??"Shipment could not be created.");let o=s.payload;return{id:o.shipmentTransactionId,providerServiceCode:o.providerServiceCode,trackingNumber:void 0,savedSenderAddress:o.savedSenderAddress,savedReceiverAddress:o.savedReceieverAddress}}};var h=class{constructor(r){this.userId="0";this.config=Object.freeze({environment:"production",timeout:1e4,...r})}asUser(r){return this.userId=r,this}getUserId(){return this.userId}getConfig(){return this.config}get addresses(){return new l(this)}get rates(){return new g(this)}get shipments(){return new y(this)}getBaseUrl(){return"https://api.kargomucuz.com/v1"}};var A=(t=>(t.TRY="try",t.USD="usd",t.EUR="eur",t))(A||{}),x=(a=>(a.PTT_FIXED_PRICE="ptt_fixed_price",a.PTT_STANDART_2="ptt_standart_2",a.HEPSIJET_STANDART_2="hepsijet_standart_2",a.SURAT_STANDART_2="surat_standart_2",a.UPS_STANDART_2="ups_standart_2",a.KOLAYGELSIN_STANDART_2="kolaygelsin_standart_2",a.YURTICI_STANDART_2="yurtici_standart_2",a))(x||{});export{c as APIError,u as AuthError,A as Currency,h as Kargomucuz,p as KargomucuzError,x as ProviderServiceCode};
+/**
+ * @file index.ts
+ * @description Official Kargomucuz SDK Entry Point
+ * @author Hakan Kaygusuz <hakankaygusuz@vorlaxen.com>
+ * @copyright (c) 2024 Vorlaxen Labs
+ * @license MIT
+ * 
+ * "Building the bridge between modern web and legacy logistics."
+ */

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@vorlaxen-labs/kargomucuz-sdk",
+  "version": "1.0.1",
+  "description": "Official SDK for Kargomucuz. Unified cargo operations, shipment automation, and enterprise-grade logistics infrastructure.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "local-build": "npm run build && yalc push --force",
+    "test": "jest --verbose --silent=false",
+    "lint": "eslint .",
+    "release": "standard-version",
+    "release:minor": "standard-version --release-as minor",
+    "release:major": "standard-version --release-as major",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@swc/core": "^1.15.33",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^29.5.14",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.6.0",
+    "@types/supertest": "^7.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
+    "dotenv": "^17.4.2",
+    "eslint": "^10.3.0",
+    "globals": "^17.6.0",
+    "jest": "^29.7.0",
+    "standard-version": "^9.5.0",
+    "supertest": "^7.2.2",
+    "tinyglobby": "^0.2.16",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.1"
+  },
+  "dependencies": {
+    "axios": "^1.16.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@swc/core",
+      "esbuild"
+    ]
+  }
+}