doboxa-js 1.0.0

package/openapi-generator-config.yaml

@@ -0,0 +1,15 @@
+generatorName: typescript-fetch
+inputSpec: api-doc.yaml
+outputDir: src/types/generated
+additionalProperties:
+  typescriptThreePlus: true
+  supportsES6: true
+  withInterfaces: true
+  enumPropertyNaming: original
+  stringEnums: true
+  modelPropertyNaming: original
+  npmName: doboxa-js
+  npmVersion: 1.0.0
+  withNodeImports: true
+  useSingleRequestParameter: false
+

package/openapitools.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "7.17.0"
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "doboxa-js",
+  "version": "1.0.0",
+  "description": "A library for interacting with the Doboxa API v2.",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emmems/doboxa-js.git"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:publish": "pnpm build --env.publish",
+    "clean": "rimraf ./dist",
+    "dev": "tsup --watch",
+    "dev:publish": "pnpm dev --env.publish",
+    "generate:api": "openapi-generator-cli generate -i api-doc.yaml -g typescript-fetch -o src/types/generated -c openapi-generator-config.yaml"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@openapitools/openapi-generator-cli": "^2.7.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./models": {
+      "import": {
+        "types": "./dist/models.d.mts",
+        "default": "./dist/models.mjs"
+      },
+      "require": {
+        "types": "./dist/models.d.ts",
+        "default": "./dist/models.js"
+      }
+    },
+    "./errors": {
+      "import": {
+        "types": "./dist/errors.d.mts",
+        "default": "./dist/errors.mjs"
+      },
+      "require": {
+        "types": "./dist/errors.d.ts",
+        "default": "./dist/errors.js"
+      }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client.d.mts",
+        "default": "./dist/client.mjs"
+      },
+      "require": {
+        "types": "./dist/client.d.ts",
+        "default": "./dist/client.js"
+      }
+    },
+    "./package.json": "./package.json"
+  }
+}

package/src/client.ts

@@ -0,0 +1,99 @@
+import { Configuration } from './types/generated/src/runtime';
+import { HTTPClient } from './http/client';
+import { TokenManager } from './utils/tokenManager';
+import { getBaseURL } from './utils/config';
+import { AuthenticationResource } from './resources/authentication';
+import { OrdersResource } from './resources/orders';
+import { InvoicesResource } from './resources/invoices';
+import { ClientsResource } from './resources/clients';
+import { DiscountCodesResource } from './resources/discountCodes';
+import { TrackingNumbersResource } from './resources/trackingNumbers';
+import { OrderCommentsResource } from './resources/orderComments';
+import { OrderStatusChangesResource } from './resources/orderStatusChanges';
+import { UsersResource } from './resources/users';
+
+export interface DoboxaConfig {
+  /**
+   * API key (access token). If not provided, you must call authentication.login() first.
+   */
+  apiKey?: string;
+  /**
+   * Base URL for the API. Defaults to DOBOXA_API_URL environment variable or http://localhost
+   */
+  baseURL?: string;
+}
+
+/**
+ * Main Doboxa client class
+ */
+export class Doboxa {
+  public readonly authentication: AuthenticationResource;
+  public readonly orders: OrdersResource;
+  public readonly invoices: InvoicesResource;
+  public readonly clients: ClientsResource;
+  public readonly discountCodes: DiscountCodesResource;
+  public readonly trackingNumbers: TrackingNumbersResource;
+  public readonly orderComments: OrderCommentsResource;
+  public readonly orderStatusChanges: OrderStatusChangesResource;
+  public readonly users: UsersResource;
+
+  private tokenManager: TokenManager;
+  private httpClient: HTTPClient;
+  private config: Configuration;
+
+  constructor(config: DoboxaConfig = {}) {
+    const baseURL = config.baseURL || getBaseURL() || 'http://localhost';
+    
+    this.tokenManager = new TokenManager();
+    if (config.apiKey) {
+      this.tokenManager.setTokens(config.apiKey, '', 3600);
+    }
+
+    // Create configuration for generated APIs
+    // Note: Generated APIs use apiKey for Bearer authentication
+    this.config = new Configuration({
+      basePath: baseURL,
+      apiKey: async (name: string) => {
+        if (name === 'Authorization') {
+          const token = this.tokenManager.getAccessToken();
+          if (!token) {
+            throw new Error('No access token available');
+          }
+          return `Bearer ${token}`;
+        }
+        throw new Error(`Unknown API key name: ${name}`);
+      },
+    });
+
+    // Create HTTP client with token refresh callback
+    // Note: We create a temporary HTTP client for token refresh to avoid circular dependency
+    const tempHttpClient = new HTTPClient({
+      baseURL,
+      tokenManager: this.tokenManager,
+    });
+
+    this.httpClient = new HTTPClient({
+      baseURL,
+      tokenManager: this.tokenManager,
+      onTokenRefresh: async (refreshToken: string) => {
+        // Use temporary HTTP client to refresh token (avoids circular dependency)
+        const tempAuth = new AuthenticationResource(tempHttpClient, this.tokenManager);
+        const response = await tempAuth.refreshToken(refreshToken);
+        this.tokenManager.setTokens(response.token!, response.refresh_token!, 3600);
+        return response.token!;
+      },
+    });
+
+    // Initialize resources
+    this.authentication = new AuthenticationResource(this.httpClient, this.tokenManager);
+    this.orders = new OrdersResource(this.httpClient, this.config);
+    this.invoices = new InvoicesResource(this.httpClient, this.config);
+    this.clients = new ClientsResource(this.httpClient, this.config);
+    this.discountCodes = new DiscountCodesResource(this.httpClient, this.config);
+    this.trackingNumbers = new TrackingNumbersResource(this.httpClient, this.config);
+    this.orderComments = new OrderCommentsResource(this.httpClient, this.config);
+    this.orderStatusChanges = new OrderStatusChangesResource(this.httpClient, this.config);
+    this.users = new UsersResource(this.httpClient, this.config);
+  }
+}
+

package/src/errors.ts

@@ -0,0 +1,90 @@
+import type { InvalidRequestDataResponse, ServerErrorResponse } from './types/generated/src/models';
+
+/**
+ * Base error class for all Doboxa errors
+ */
+export class DoboxaError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DoboxaError';
+    Object.setPrototypeOf(this, DoboxaError.prototype);
+  }
+}
+
+/**
+ * Error thrown when API returns an error response
+ */
+export class DoboxaAPIError extends DoboxaError {
+  public readonly statusCode: number;
+  public readonly code?: number;
+  public readonly errorMessage?: string;
+  public readonly invalidParameters?: Array<{ parameter: string; error_cause: string }>;
+
+  constructor(
+    statusCode: number,
+    message: string,
+    body?: InvalidRequestDataResponse | ServerErrorResponse
+  ) {
+    super(message);
+    this.name = 'DoboxaAPIError';
+    this.statusCode = statusCode;
+
+    if (body) {
+      if ('result_code' in body) {
+        this.code = body.result_code;
+      }
+      if ('error_message' in body) {
+        this.errorMessage = body.error_message || undefined;
+      }
+      if ('invalid_parameters' in body && body.invalid_parameters) {
+        this.invalidParameters = body.invalid_parameters.map((param) => ({
+          parameter: param.parameter,
+          error_cause: param.error_cause,
+        }));
+      }
+    }
+
+    Object.setPrototypeOf(this, DoboxaAPIError.prototype);
+  }
+}
+
+/**
+ * Error thrown when authentication fails
+ */
+export class DoboxaAuthenticationError extends DoboxaError {
+  constructor(message: string = 'Authentication failed') {
+    super(message);
+    this.name = 'DoboxaAuthenticationError';
+    Object.setPrototypeOf(this, DoboxaAuthenticationError.prototype);
+  }
+}
+
+/**
+ * Error thrown when request validation fails
+ */
+export class DoboxaValidationError extends DoboxaAPIError {
+  constructor(statusCode: number, message: string, body?: InvalidRequestDataResponse) {
+    super(statusCode, message, body);
+    this.name = 'DoboxaValidationError';
+    Object.setPrototypeOf(this, DoboxaValidationError.prototype);
+  }
+}
+
+/**
+ * Parse error response from API
+ */
+export function parseErrorResponse(
+  statusCode: number,
+  body: unknown
+): InvalidRequestDataResponse | ServerErrorResponse | undefined {
+  if (typeof body === 'object' && body !== null) {
+    if ('invalid_parameters' in body || 'error_message' in body) {
+      return body as InvalidRequestDataResponse;
+    }
+    if ('error_message' in body && 'result_code' in body) {
+      return body as ServerErrorResponse;
+    }
+  }
+  return undefined;
+}
+

package/src/http/client.ts

@@ -0,0 +1,156 @@
+import type { Configuration } from '../types/generated/src/runtime';
+import { TokenManager } from '../utils/tokenManager';
+import {
+  DoboxaAPIError,
+  DoboxaAuthenticationError,
+  parseErrorResponse,
+} from '../errors';
+
+export interface HTTPClientConfig {
+  baseURL?: string;
+  tokenManager: TokenManager;
+  onTokenRefresh?: (token: string) => Promise<string>;
+}
+
+/**
+ * HTTP client wrapper around fetch with Bearer token injection and error handling
+ */
+export class HTTPClient {
+  private baseURL: string;
+  private tokenManager: TokenManager;
+  private onTokenRefresh?: (token: string) => Promise<string>;
+
+  constructor(config: HTTPClientConfig) {
+    this.baseURL = config.baseURL || 'http://localhost';
+    this.tokenManager = config.tokenManager;
+    this.onTokenRefresh = config.onTokenRefresh;
+  }
+
+  /**
+   * Make an HTTP request
+   */
+  async request<T>(
+    path: string,
+    options: RequestInit = {}
+  ): Promise<T> {
+    // Ensure path starts with /
+    const url = `${this.baseURL}${path.startsWith('/') ? path : `/${path}`}`;
+
+    // Get or refresh token
+    let accessToken = this.tokenManager.getAccessToken();
+    
+    if (!accessToken || this.tokenManager.isTokenExpired()) {
+      if (this.onTokenRefresh) {
+        const refreshToken = this.tokenManager.getRefreshToken();
+        if (!refreshToken) {
+          throw new DoboxaAuthenticationError('No refresh token available');
+        }
+
+        // Check if refresh is already in progress
+        let refreshPromise = this.tokenManager.getRefreshPromise();
+        if (!refreshPromise) {
+          refreshPromise = this.onTokenRefresh(refreshToken);
+          this.tokenManager.setRefreshPromise(refreshPromise);
+        }
+
+        try {
+          accessToken = await refreshPromise;
+        } finally {
+          this.tokenManager.setRefreshPromise(null);
+        }
+      } else {
+        throw new DoboxaAuthenticationError('No access token available');
+      }
+    }
+
+    // Prepare headers
+    const headers = new Headers(options.headers);
+    headers.set('Content-Type', 'application/json');
+    headers.set('Authorization', `Bearer ${accessToken}`);
+
+    // Make request
+    const response = await fetch(url, {
+      ...options,
+      headers,
+    });
+
+    // Parse response
+    let responseBody: unknown;
+    const contentType = response.headers.get('content-type');
+    if (contentType && contentType.includes('application/json')) {
+      try {
+        responseBody = await response.json();
+      } catch {
+        // Ignore JSON parse errors
+      }
+    } else {
+      responseBody = await response.text();
+    }
+
+    // Handle errors
+    if (!response.ok) {
+      const errorBody = parseErrorResponse(response.status, responseBody);
+      const errorMessage =
+        (errorBody && 'error_message' in errorBody
+          ? errorBody.error_message
+          : undefined) || response.statusText || `HTTP ${response.status}`;
+
+      // Handle 401/403 as authentication errors
+      if (response.status === 401 || response.status === 403) {
+        throw new DoboxaAuthenticationError(errorMessage);
+      }
+
+      throw new DoboxaAPIError(response.status, errorMessage, errorBody);
+    }
+
+    return responseBody as T;
+  }
+
+  /**
+   * GET request
+   */
+  async get<T>(path: string, options?: RequestInit): Promise<T> {
+    return this.request<T>(path, { ...options, method: 'GET' });
+  }
+
+  /**
+   * POST request
+   */
+  async post<T>(path: string, body?: unknown, options?: RequestInit): Promise<T> {
+    return this.request<T>(path, {
+      ...options,
+      method: 'POST',
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  }
+
+  /**
+   * PUT request
+   */
+  async put<T>(path: string, body?: unknown, options?: RequestInit): Promise<T> {
+    return this.request<T>(path, {
+      ...options,
+      method: 'PUT',
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  }
+
+  /**
+   * DELETE request
+   */
+  async delete<T>(path: string, options?: RequestInit): Promise<T> {
+    return this.request<T>(path, { ...options, method: 'DELETE' });
+  }
+
+  /**
+   * PATCH request
+   */
+  async patch<T>(path: string, body?: unknown, options?: RequestInit): Promise<T> {
+    return this.request<T>(path, {
+      ...options,
+      method: 'PATCH',
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,31 @@
+// Main client export
+import { Doboxa } from './client';
+export { Doboxa } from './client';
+export type { DoboxaConfig } from './client';
+
+// Error exports
+export {
+  DoboxaError,
+  DoboxaAPIError,
+  DoboxaAuthenticationError,
+  DoboxaValidationError,
+  parseErrorResponse,
+} from './errors';
+
+// Type exports
+export * from './types';
+
+// Resource exports (for advanced usage)
+export { AuthenticationResource } from './resources/authentication';
+export { OrdersResource } from './resources/orders';
+export { InvoicesResource } from './resources/invoices';
+export { ClientsResource } from './resources/clients';
+export { DiscountCodesResource } from './resources/discountCodes';
+export { TrackingNumbersResource } from './resources/trackingNumbers';
+export { OrderCommentsResource } from './resources/orderComments';
+export { OrderStatusChangesResource } from './resources/orderStatusChanges';
+export { UsersResource } from './resources/users';
+
+// Default export
+export default Doboxa;
+

package/src/resources/authentication.ts

@@ -0,0 +1,73 @@
+import { HTTPClient } from '../http/client';
+import { TokenManager } from '../utils/tokenManager';
+import type {
+  ApiV2AuthenticationTokenPostRequest,
+  ApiV2AuthenticationTokenPost200Response,
+  ApiV2AuthenticationRefreshTokenPostRequest,
+  ApiV2AuthenticationRefreshTokenPost200Response,
+} from '../types/generated/src/models';
+
+export interface LoginParams {
+  username: string;
+  password: string;
+}
+
+export interface RefreshTokenParams {
+  refresh_token: string;
+}
+
+/**
+ * Authentication resource
+ */
+export class AuthenticationResource {
+  constructor(
+    private httpClient: HTTPClient,
+    private tokenManager: TokenManager
+  ) {}
+
+  /**
+   * Login with username and password
+   */
+  async login(params: LoginParams): Promise<ApiV2AuthenticationTokenPost200Response> {
+    const request: ApiV2AuthenticationTokenPostRequest = {
+      username: params.username,
+      password: params.password,
+    };
+
+    const response = await this.httpClient.post<ApiV2AuthenticationTokenPost200Response>(
+      '/api/v2/authentication/token',
+      request
+    );
+
+    // Store tokens
+    if (response.token && response.refresh_token) {
+      this.tokenManager.setTokens(response.token, response.refresh_token, 3600);
+    }
+
+    return response;
+  }
+
+  /**
+   * Refresh access token using refresh token
+   */
+  async refreshToken(
+    refreshToken: string
+  ): Promise<ApiV2AuthenticationRefreshTokenPost200Response> {
+    const request: ApiV2AuthenticationRefreshTokenPostRequest = {
+      refresh_token: refreshToken,
+    };
+
+    const response = await this.httpClient.post<ApiV2AuthenticationRefreshTokenPost200Response>(
+      '/api/v2/authentication/refresh_token',
+      request
+    );
+
+    // Store new tokens
+    if (response.token && response.refresh_token) {
+      this.tokenManager.setTokens(response.token, response.refresh_token, 3600);
+    }
+
+    return response;
+  }
+}
+

package/src/resources/clients.ts

@@ -0,0 +1,32 @@
+import { HTTPClient } from '../http/client';
+import { Configuration } from '../types/generated/src/runtime';
+import { ClientApi } from '../types/generated/src/apis/ClientApi';
+import type {
+  PageOfClients,
+} from '../types/generated/src/models';
+
+export interface ClientListParams {
+  page?: number;
+}
+
+/**
+ * Clients resource
+ */
+export class ClientsResource {
+  private clientApi: ClientApi;
+
+  constructor(
+    private httpClient: HTTPClient,
+    config: Configuration
+  ) {
+    this.clientApi = new ClientApi(config);
+  }
+
+  /**
+   * List clients (only commission type)
+   */
+  async list(params?: ClientListParams): Promise<PageOfClients> {
+    return this.clientApi.getAppEcommerceApiV2GetclientsInvoke(params?.page);
+  }
+}
+

package/src/resources/discountCodes.ts

@@ -0,0 +1,32 @@
+import { HTTPClient } from '../http/client';
+import { Configuration } from '../types/generated/src/runtime';
+import { DiscountCodeApi } from '../types/generated/src/apis/DiscountCodeApi';
+import type {
+  GetApiV2DiscountCodesExternal200Response,
+} from '../types/generated/src/models';
+
+export interface DiscountCodeListParams {
+  page?: number;
+}
+
+/**
+ * Discount Codes resource
+ */
+export class DiscountCodesResource {
+  private discountCodeApi: DiscountCodeApi;
+
+  constructor(
+    private httpClient: HTTPClient,
+    config: Configuration
+  ) {
+    this.discountCodeApi = new DiscountCodeApi(config);
+  }
+
+  /**
+   * List discount codes (only commission type)
+   */
+  async list(params?: DiscountCodeListParams): Promise<GetApiV2DiscountCodesExternal200Response> {
+    return this.discountCodeApi.getApiV2DiscountCodesExternal(params?.page);
+  }
+}
+

package/src/resources/invoices.ts

@@ -0,0 +1,46 @@
+import { HTTPClient } from '../http/client';
+import { Configuration } from '../types/generated/src/runtime';
+import { InvoiceApi } from '../types/generated/src/apis/InvoiceApi';
+import type {
+  Invoice,
+  PageOfInvoices,
+} from '../types/generated/src/models';
+
+export interface InvoiceListParams {
+  page?: number;
+  from?: string; // ISO date-time
+  to?: string; // ISO date-time
+}
+
+/**
+ * Invoices resource
+ */
+export class InvoicesResource {
+  private invoiceApi: InvoiceApi;
+
+  constructor(
+    private httpClient: HTTPClient,
+    config: Configuration
+  ) {
+    this.invoiceApi = new InvoiceApi(config);
+  }
+
+  /**
+   * List invoices
+   */
+  async list(params?: InvoiceListParams): Promise<PageOfInvoices> {
+    return this.invoiceApi.getAppEcommerceApiV2GetinvoicesInvoke(
+      params?.page,
+      params?.from ? new Date(params.from) : undefined,
+      params?.to ? new Date(params.to) : undefined
+    );
+  }
+
+  /**
+   * Retrieve a specific invoice
+   */
+  async retrieve(invoiceId: string): Promise<Invoice> {
+    return this.invoiceApi.getAppEcommerceApiV2GetinvoiceInvoke(invoiceId);
+  }
+}
+