doboxa-js 1.0.2 → 1.1.0

package/README.md

@@ -24,11 +24,11 @@ yarn add doboxa-js
 ### Basic Setup
 
 ```typescript
-import Doboxa from 'doboxa-js';
+import Doboxa from "doboxa-js";
 
 // Initialize the client
 const doboxa = new Doboxa({
-  baseURL: 'https://api.doboxa.biz', // Optional: defaults to DOBOXA_API_URL env var or http://localhost
+  baseURL: "https://pl.doboxa.biz", // Optional: defaults to DOBOXA_API_URL env var or https://pl.doboxa.biz
 });
 ```
 
@@ -39,20 +39,20 @@ The library supports two authentication methods:
 #### Method 1: Login with Username and Password
 
 ```typescript
-import Doboxa from 'doboxa-js';
+import Doboxa from "doboxa-js";
 
 const doboxa = new Doboxa({
-  baseURL: 'https://api.doboxa.biz',
+  baseURL: "https://pl.doboxa.biz",
 });
 
 // Login with your Doboxa account credentials
 const authResponse = await doboxa.authentication.login({
-  username: 'your-username',
-  password: 'your-password',
+  username: "your-username",
+  password: "your-password",
 });
 
-console.log('Access token:', authResponse.token);
-console.log('Refresh token:', authResponse.refresh_token);
+console.log("Access token:", authResponse.token);
+console.log("Refresh token:", authResponse.refresh_token);
 
 // Tokens are automatically stored and used for subsequent requests
 ```
@@ -62,11 +62,11 @@ console.log('Refresh token:', authResponse.refresh_token);
 If you already have an access token:
 
 ```typescript
-import Doboxa from 'doboxa-js';
+import Doboxa from "doboxa-js";
 
 const doboxa = new Doboxa({
-  apiKey: 'your-access-token',
-  baseURL: 'https://api.doboxa.biz',
+  apiKey: "your-access-token",
+  baseURL: "https://pl.doboxa.biz",
 });
 
 // You can now make API calls immediately
@@ -82,48 +82,48 @@ const doboxa = new Doboxa({
 
 ```typescript
 const order = await doboxa.orders.create({
-  external_id: 'ORDER-12345',
+  external_id: "ORDER-12345",
   deliver_address: {
-    first_name: 'John',
-    last_name: 'Doe',
-    phone_number: '+48123456789',
-    email: 'john.doe@example.com',
-    address1: '123 Main St',
-    city: 'Warsaw',
-    post_code: '00-001',
-    country_iso: 'PL',
+    first_name: "John",
+    last_name: "Doe",
+    phone_number: "+48123456789",
+    email: "john.doe@example.com",
+    address1: "123 Main St",
+    city: "Warsaw",
+    post_code: "00-001",
+    country_iso: "PL",
   },
   items: [
     {
-      id: 'SKU-123',
-      name: 'Product Name',
+      id: "SKU-123",
+      name: "Product Name",
       qty: 2,
       item_price: 9999, // Price in cents (99.99)
     },
   ],
   order_time: new Date().toISOString(),
-  order_channel: 'channel_id',
-  currency: 'PLN',
+  order_channel: "channel_id",
+  currency: "PLN",
 });
 ```
 
 #### Get Order Status
 
 ```typescript
-const status = await doboxa.orders.getStatus('order-id-123');
-console.log('Order status:', status.status);
-console.log('Item statuses:', status.item_status);
+const status = await doboxa.orders.getStatus("order-id-123");
+console.log("Order status:", status.status);
+console.log("Item statuses:", status.item_status);
 ```
 
 #### Update Order Status
 
 ```typescript
-await doboxa.orders.updateStatus('order-id-123', {
-  status: 'paid',
+await doboxa.orders.updateStatus("order-id-123", {
+  status: "paid",
   item_status: [
     {
-      doboxa_item_id: 'item-123',
-      status: 'paid',
+      doboxa_item_id: "item-123",
+      status: "paid",
     },
   ],
 });
@@ -132,17 +132,17 @@ await doboxa.orders.updateStatus('order-id-123', {
 #### Get Order Comments
 
 ```typescript
-const comments = await doboxa.orders.getComments('order-id-123');
-console.log('Comments:', comments.items);
+const comments = await doboxa.orders.getComments("order-id-123");
+console.log("Comments:", comments.items);
 ```
 
 #### Create Order Comment
 
 ```typescript
-const comment = await doboxa.orders.createComment('order-id-123', {
-  author_type: 'client',
-  author_email: 'client@example.com',
-  content: 'This is a comment',
+const comment = await doboxa.orders.createComment("order-id-123", {
+  author_type: "client",
+  author_email: "client@example.com",
+  content: "This is a comment",
   created_at: new Date().toISOString(),
 });
 ```
@@ -150,25 +150,25 @@ const comment = await doboxa.orders.createComment('order-id-123', {
 #### Get Order Invoices
 
 ```typescript
-const invoices = await doboxa.orders.getInvoices('order-id-123');
-console.log('Invoices:', invoices.items);
+const invoices = await doboxa.orders.getInvoices("order-id-123");
+console.log("Invoices:", invoices.items);
 ```
 
 #### Get Order Tracking Numbers
 
 ```typescript
-const tracking = await doboxa.orders.getTrackingNumbers('order-id-123');
-console.log('Tracking numbers:', tracking.items);
+const tracking = await doboxa.orders.getTrackingNumbers("order-id-123");
+console.log("Tracking numbers:", tracking.items);
 ```
 
 #### Cancel an Order
 
 ```typescript
 const result = await doboxa.orders.cancel({
-  order_id: 'order-id-123',
+  order_id: "order-id-123",
 });
-console.log('Cancelled:', result.cancelled);
-console.log('Details:', result.details);
+console.log("Cancelled:", result.cancelled);
+console.log("Details:", result.details);
 ```
 
 ### Invoices
@@ -178,20 +178,20 @@ console.log('Details:', result.details);
 ```typescript
 const invoices = await doboxa.invoices.list({
   page: 1,
-  from: '2024-01-01T00:00:00Z', // Optional: ISO date-time string
-  to: '2024-12-31T23:59:59Z',   // Optional: ISO date-time string
+  from: "2024-01-01T00:00:00Z", // Optional: ISO date-time string
+  to: "2024-12-31T23:59:59Z", // Optional: ISO date-time string
 });
 
-console.log('Invoices:', invoices.items);
-console.log('Next page:', invoices.next_page);
+console.log("Invoices:", invoices.items);
+console.log("Next page:", invoices.next_page);
 ```
 
 #### Retrieve a Specific Invoice
 
 ```typescript
-const invoice = await doboxa.invoices.retrieve('invoice-id-123');
-console.log('Invoice:', invoice);
-console.log('PDF URL:', invoice.file);
+const invoice = await doboxa.invoices.retrieve("invoice-id-123");
+console.log("Invoice:", invoice);
+console.log("PDF URL:", invoice.file);
 ```
 
 ### Clients
@@ -203,7 +203,7 @@ const clients = await doboxa.clients.list({
   page: 1,
 });
 
-console.log('Clients:', clients.items);
+console.log("Clients:", clients.items);
 ```
 
 ### Discount Codes
@@ -215,7 +215,7 @@ const discountCodes = await doboxa.discountCodes.list({
   page: 1,
 });
 
-console.log('Discount codes:', discountCodes.items);
+console.log("Discount codes:", discountCodes.items);
 ```
 
 ### Tracking Numbers
@@ -225,11 +225,11 @@ console.log('Discount codes:', discountCodes.items);
 ```typescript
 const trackingNumbers = await doboxa.trackingNumbers.list({
   page: 1,
-  from: '2024-01-01T00:00:00Z',
-  to: '2024-12-31T23:59:59Z',
+  from: "2024-01-01T00:00:00Z",
+  to: "2024-12-31T23:59:59Z",
 });
 
-console.log('Tracking numbers:', trackingNumbers.items);
+console.log("Tracking numbers:", trackingNumbers.items);
 ```
 
 ### Order Comments
@@ -239,11 +239,11 @@ console.log('Tracking numbers:', trackingNumbers.items);
 ```typescript
 const comments = await doboxa.orderComments.list({
   page: 1,
-  from: '2024-01-01T00:00:00Z',
-  to: '2024-12-31T23:59:59Z',
+  from: "2024-01-01T00:00:00Z",
+  to: "2024-12-31T23:59:59Z",
 });
 
-console.log('Comments:', comments.items);
+console.log("Comments:", comments.items);
 ```
 
 ### Order Status Changes
@@ -253,11 +253,11 @@ console.log('Comments:', comments.items);
 ```typescript
 const statusChanges = await doboxa.orderStatusChanges.list({
   page: 1,
-  from: '2024-01-01T00:00:00Z',
-  to: '2024-12-31T23:59:59Z',
+  from: "2024-01-01T00:00:00Z",
+  to: "2024-12-31T23:59:59Z",
 });
 
-console.log('Status changes:', statusChanges.items);
+console.log("Status changes:", statusChanges.items);
 ```
 
 ### Users
@@ -266,15 +266,63 @@ console.log('Status changes:', statusChanges.items);
 
 ```typescript
 const me = await doboxa.users.me();
-console.log('Current user:', me.username);
+console.log("Current user:", me.username);
 ```
 
+### Product catalog (BaseLinker connector)
+
+The product catalog is not part of API v2 - it is served by Doboxa's BaseLinker
+connector (shop integration file) on its own URL. The merchant finds both
+credentials in the Doboxa client panel: **Integracje → Edycja** on the BaseLinker
+integration. The modal shows the connector URL and the **Hasło** (password)
+field.
+
+```typescript
+const doboxa = new Doboxa({
+  baseURL: "https://pl.doboxa.biz",
+  catalog: {
+    url: "https://pl.doboxa.biz/api/base-linker/{clientToken}/{language}",
+    password: "YOUR_BL_PASS",
+  },
+});
+const catalog = doboxa.catalog!; // defined because `catalog` config was passed
+
+// Connector capabilities
+console.log(await catalog.fileVersion());
+console.log(await catalog.supportedMethods());
+
+// Categories: { "<id>": "Category / Path" }
+const categories = await catalog.categories();
+
+// One page of designs (100 per page)
+const { pages, items } = await catalog.list({ page: 1 });
+console.log(pages, items[0].id, items[0].name, items[0].price);
+
+// Full data (images, variants) for selected designs
+const data = await catalog.data({
+  products_id: [items[0].id],
+});
+```
+
+Notes:
+
+- The catalog uses only the connector password, so no `apiKey` is needed - the
+  client works with the catalog, with the API and with both.
+- `list()` returns one entry per design (the first variant); `data()` returns
+  the design with all of its variants.
+- Prices are strings in PLN (up to 3 decimals) and are most likely **net**
+  prices - the markup is set by the merchant in the panel ("Zarządzanie cenami").
+- The connector has no order methods, so orders are still created through
+  API v2 (`doboxa.orders`).
+- Connector errors are returned with HTTP 200 and are thrown as
+  `DoboxaConnectorError` (with `errorCode` and `errorText`).
+
 ## Environment Variables
 
 You can set the API base URL using an environment variable:
 
 ```bash
-export DOBOXA_API_URL=https://api.doboxa.biz
+export DOBOXA_API_URL=https://pl.doboxa.biz
 ```
 
 The library will use this value if no `baseURL` is provided in the configuration.
@@ -289,20 +337,20 @@ import {
   DoboxaAPIError,
   DoboxaAuthenticationError,
   DoboxaValidationError,
-} from 'doboxa-js';
+} from "doboxa-js";
 
 try {
   await doboxa.orders.create(orderData);
 } catch (error) {
   if (error instanceof DoboxaAuthenticationError) {
-    console.error('Authentication failed:', error.message);
+    console.error("Authentication failed:", error.message);
   } else if (error instanceof DoboxaValidationError) {
-    console.error('Validation error:', error.message);
-    console.error('Invalid parameters:', error.invalidParameters);
+    console.error("Validation error:", error.message);
+    console.error("Invalid parameters:", error.invalidParameters);
   } else if (error instanceof DoboxaAPIError) {
-    console.error('API error:', error.statusCode, error.message);
+    console.error("API error:", error.statusCode, error.message);
   } else {
-    console.error('Unknown error:', error);
+    console.error("Unknown error:", error);
   }
 }
 ```
@@ -318,7 +366,7 @@ import type {
   OrderStatus,
   PageOfInvoices,
   // ... and many more
-} from 'doboxa-js';
+} from "doboxa-js";
 ```
 
 ## API Reference
@@ -326,10 +374,12 @@ import type {
 ### Resources
 
 - **Authentication**: `doboxa.authentication`
+
   - `login(params)` - Login with username and password
   - `refreshToken(refreshToken)` - Refresh access token
 
 - **Orders**: `doboxa.orders`
+
   - `create(params)` - Create an order
   - `getStatus(orderId)` - Get order status
   - `updateStatus(orderId, params)` - Update order status
@@ -340,27 +390,40 @@ import type {
   - `cancel(params)` - Cancel an order
 
 - **Invoices**: `doboxa.invoices`
+
   - `list(params?)` - List invoices
   - `retrieve(invoiceId)` - Get a specific invoice
 
 - **Clients**: `doboxa.clients`
+
   - `list(params?)` - List clients
 
 - **Discount Codes**: `doboxa.discountCodes`
+
   - `list(params?)` - List discount codes
 
 - **Tracking Numbers**: `doboxa.trackingNumbers`
+
   - `list(params?)` - List tracking numbers
 
 - **Order Comments**: `doboxa.orderComments`
+
   - `list(params?)` - List order comments
 
 - **Order Status Changes**: `doboxa.orderStatusChanges`
+
   - `list(params?)` - List order status changes
 
 - **Users**: `doboxa.users`
   - `me()` - Get current user
 
+- **Catalog**: `doboxa.catalog` (only when the `catalog` config is provided)
+  - `fileVersion()` - Get the connector platform and version
+  - `supportedMethods()` - Get the list of supported actions
+  - `categories()` - Get all product categories
+  - `list(params?)` - List one page of products (designs)
+  - `data(params)` - Get full product data (images, variants) for design ids
+
 ## License
 
 ISC
@@ -368,4 +431,3 @@ ISC
 ## Support
 
 For API access and support, please contact the Doboxa team at [doboxa.com](https://doboxa.com).
-

package/dist/{chunk-CGJD4ZO5.mjs → chunk-7RN7PBJH.mjs}

@@ -75,6 +75,15 @@ var DoboxaAuthenticationError = class _DoboxaAuthenticationError extends DoboxaE
     Object.setPrototypeOf(this, _DoboxaAuthenticationError.prototype);
   }
 };
+var DoboxaConnectorError = class _DoboxaConnectorError extends DoboxaError {
+  constructor(errorCode, errorText, message) {
+    super(message || errorText || `BaseLinker connector error: ${errorCode}`);
+    this.name = "DoboxaConnectorError";
+    this.errorCode = errorCode;
+    this.errorText = errorText;
+    Object.setPrototypeOf(this, _DoboxaConnectorError.prototype);
+  }
+};
 var DoboxaValidationError = class _DoboxaValidationError extends DoboxaAPIError {
   constructor(statusCode, message, body) {
     super(statusCode, message, body);
@@ -101,7 +110,8 @@ export {
   DoboxaError,
   DoboxaAPIError,
   DoboxaAuthenticationError,
+  DoboxaConnectorError,
   DoboxaValidationError,
   parseErrorResponse
 };
-//# sourceMappingURL=chunk-CGJD4ZO5.mjs.map
+//# sourceMappingURL=chunk-7RN7PBJH.mjs.map

package/dist/chunk-7RN7PBJH.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["import type { InvalidRequestDataResponse, ServerErrorResponse } from './types/generated/src/models';\n\n/**\n * Base error class for all Doboxa errors\n */\nexport class DoboxaError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'DoboxaError';\n    Object.setPrototypeOf(this, DoboxaError.prototype);\n  }\n}\n\n/**\n * Error thrown when API returns an error response\n */\nexport class DoboxaAPIError extends DoboxaError {\n  public readonly statusCode: number;\n  public readonly code?: number;\n  public readonly errorMessage?: string;\n  public readonly invalidParameters?: Array<{ parameter: string; error_cause: string }>;\n\n  constructor(\n    statusCode: number,\n    message: string,\n    body?: InvalidRequestDataResponse | ServerErrorResponse\n  ) {\n    super(message);\n    this.name = 'DoboxaAPIError';\n    this.statusCode = statusCode;\n\n    if (body) {\n      if ('result_code' in body) {\n        this.code = body.result_code;\n      }\n      if ('error_message' in body) {\n        this.errorMessage = body.error_message || undefined;\n      }\n      if ('invalid_parameters' in body && body.invalid_parameters) {\n        this.invalidParameters = body.invalid_parameters.map((param) => ({\n          parameter: param.parameter,\n          error_cause: param.error_cause,\n        }));\n      }\n    }\n\n    Object.setPrototypeOf(this, DoboxaAPIError.prototype);\n  }\n}\n\n/**\n * Error thrown when authentication fails\n */\nexport class DoboxaAuthenticationError extends DoboxaError {\n  constructor(message: string = 'Authentication failed') {\n    super(message);\n    this.name = 'DoboxaAuthenticationError';\n    Object.setPrototypeOf(this, DoboxaAuthenticationError.prototype);\n  }\n}\n\n/**\n * Error thrown when the BaseLinker connector returns an error.\n * The connector always answers with HTTP 200, so the error is carried in the body.\n */\nexport class DoboxaConnectorError extends DoboxaError {\n  /**\n   * Machine readable error code, e.g. \"bad_password\", \"no_password\", \"unsupported_method\"\n   */\n  public readonly errorCode: string;\n  /**\n   * Human readable error text returned by the connector\n   */\n  public readonly errorText: string;\n\n  constructor(errorCode: string, errorText: string, message?: string) {\n    super(message || errorText || `BaseLinker connector error: ${errorCode}`);\n    this.name = 'DoboxaConnectorError';\n    this.errorCode = errorCode;\n    this.errorText = errorText;\n    Object.setPrototypeOf(this, DoboxaConnectorError.prototype);\n  }\n}\n\n/**\n * Error thrown when request validation fails\n */\nexport class DoboxaValidationError extends DoboxaAPIError {\n  constructor(statusCode: number, message: string, body?: InvalidRequestDataResponse) {\n    super(statusCode, message, body);\n    this.name = 'DoboxaValidationError';\n    Object.setPrototypeOf(this, DoboxaValidationError.prototype);\n  }\n}\n\n/**\n * Parse error response from API\n */\nexport function parseErrorResponse(\n  statusCode: number,\n  body: unknown\n): InvalidRequestDataResponse | ServerErrorResponse | undefined {\n  if (typeof body === 'object' && body !== null) {\n    if ('invalid_parameters' in body || 'error_message' in body) {\n      return body as InvalidRequestDataResponse;\n    }\n    if ('error_message' in body && 'result_code' in body) {\n      return body as ServerErrorResponse;\n    }\n  }\n  return undefined;\n}\n\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKO,IAAM,cAAN,MAAM,qBAAoB,MAAM;AAAA,EACrC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,aAAY,SAAS;AAAA,EACnD;AACF;AAKO,IAAM,iBAAN,MAAM,wBAAuB,YAAY;AAAA,EAM9C,YACE,YACA,SACA,MACA;AACA,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,aAAa;AAElB,QAAI,MAAM;AACR,UAAI,iBAAiB,MAAM;AACzB,aAAK,OAAO,KAAK;AAAA,MACnB;AACA,UAAI,mBAAmB,MAAM;AAC3B,aAAK,eAAe,KAAK,iBAAiB;AAAA,MAC5C;AACA,UAAI,wBAAwB,QAAQ,KAAK,oBAAoB;AAC3D,aAAK,oBAAoB,KAAK,mBAAmB,IAAI,CAAC,WAAW;AAAA,UAC/D,WAAW,MAAM;AAAA,UACjB,aAAa,MAAM;AAAA,QACrB,EAAE;AAAA,MACJ;AAAA,IACF;AAEA,WAAO,eAAe,MAAM,gBAAe,SAAS;AAAA,EACtD;AACF;AAKO,IAAM,4BAAN,MAAM,mCAAkC,YAAY;AAAA,EACzD,YAAY,UAAkB,yBAAyB;AACrD,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,2BAA0B,SAAS;AAAA,EACjE;AACF;AAMO,IAAM,uBAAN,MAAM,8BAA6B,YAAY;AAAA,EAUpD,YAAY,WAAmB,WAAmB,SAAkB;AAClE,UAAM,WAAW,aAAa,+BAA+B,SAAS,EAAE;AACxE,SAAK,OAAO;AACZ,SAAK,YAAY;AACjB,SAAK,YAAY;AACjB,WAAO,eAAe,MAAM,sBAAqB,SAAS;AAAA,EAC5D;AACF;AAKO,IAAM,wBAAN,MAAM,+BAA8B,eAAe;AAAA,EACxD,YAAY,YAAoB,SAAiB,MAAmC;AAClF,UAAM,YAAY,SAAS,IAAI;AAC/B,SAAK,OAAO;AACZ,WAAO,eAAe,MAAM,uBAAsB,SAAS;AAAA,EAC7D;AACF;AAKO,SAAS,mBACd,YACA,MAC8D;AAC9D,MAAI,OAAO,SAAS,YAAY,SAAS,MAAM;AAC7C,QAAI,wBAAwB,QAAQ,mBAAmB,MAAM;AAC3D,aAAO;AAAA,IACT;AACA,QAAI,mBAAmB,QAAQ,iBAAiB,MAAM;AACpD,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;","names":[]}