@ptkl/sdk 0.9.8 → 0.9.9

package/dist/types/api/integrations/dms.d.ts

@@ -1,19 +1,332 @@
 import IntegrationsBaseClient from "../integrationsBaseClient";
-import { PDFFillOptions } from "../../types/integrations";
+import { AxiosResponse } from "axios";
+import { PDFFillOptions, DataConversionParams, DataValidationParams, DataInfoParams, DataInfo, DataValidationResult, ConversionOptions } from "../../types/integrations";
+/**
+ * Document Management System (DMS) API client
+ *
+ * Provides comprehensive document and media management capabilities including:
+ * - File upload, download, and management
+ * - PDF generation and form filling
+ * - Data conversion between JSON, CSV, and Excel formats
+ * - Media processing and EXIF data extraction
+ *
+ * ## Data Conversion Features
+ *
+ * The DMS class includes powerful data conversion capabilities that allow you to:
+ * - Convert between JSON, CSV, and Excel (.xlsx) formats
+ * - Validate data format integrity
+ * - Analyze data structure and metadata
+ * - Handle large datasets with memory-efficient processing
+ *
+ * ### Supported Formats
+ * - **JSON**: Array of objects (recommended for tabular data)
+ * - **CSV**: Comma-separated values with headers
+ * - **Excel**: .xlsx format with optional sheet specification
+ *
+ * ### Error Handling
+ * All conversion methods may throw errors with code 3003 for conversion failures.
+ * Always wrap calls in try-catch blocks for production use.
+ *
+ * @example
+ * ```typescript
+ * import { DMS } from 'protokol-sdk';
+ *
+ * const dms = new DMS({
+ *   token: 'your-bearer-token',
+ *   host: 'http://localhost:8086'
+ * });
+ *
+ * const libraryRef = 'your-library-uuid';
+ *
+ * // Convert JSON to CSV
+ * const jsonData = [
+ *   { name: "John", age: 30 },
+ *   { name: "Jane", age: 25 }
+ * ];
+ *
+ * try {
+ *   const csvResult = await dms.jsonToCsv(libraryRef, jsonData);
+ *   console.log(csvResult.data); // CSV string
+ * } catch (error) {
+ *   console.error('Conversion failed:', error.message);
+ * }
+ * ```
+ */
 export default class DMS extends IntegrationsBaseClient {
-    list(data: any): Promise<import("axios").AxiosResponse<any, any>>;
-    libraries(): Promise<import("axios").AxiosResponse<any, any>>;
-    upload(payload: any): Promise<import("axios").AxiosResponse<any, any> | undefined>;
-    delete(data: any): Promise<import("axios").AxiosResponse<any, any>>;
-    uploadBase64(data: any): Promise<import("axios").AxiosResponse<any, any>>;
-    getMedia(lib: string, key: string, encoding: string): Promise<import("axios").AxiosResponse<any, any>>;
-    download(lib: string, key: string): Promise<import("axios").AxiosResponse<any, any>>;
-    getExifData(lib: string, key: string): Promise<import("axios").AxiosResponse<any, any>>;
-    html2pdf(lib: string, data: any): Promise<import("axios").AxiosResponse<any, any>>;
-    createDir(lib: string, path: string): Promise<import("axios").AxiosResponse<any, any>>;
-    deleteDir(lib: string, path: string): Promise<import("axios").AxiosResponse<any, any>>;
-    dirs(lib: string, data: string): Promise<import("axios").AxiosResponse<any, any>>;
-    fillPdf(lib: string, data: PDFFillOptions): Promise<import("axios").AxiosResponse<any, any>>;
-    request(method: string, endpoint: string, params?: any): Promise<import("axios").AxiosResponse<any, any>>;
-    requestv1(method: string, endpoint: string, params?: any): Promise<import("axios").AxiosResponse<any, any>>;
+    list(data: any): Promise<AxiosResponse<any, any>>;
+    libraries(): Promise<AxiosResponse<any, any>>;
+    upload(payload: any): Promise<AxiosResponse<any, any> | undefined>;
+    delete(data: any): Promise<AxiosResponse<any, any>>;
+    uploadBase64(data: any): Promise<AxiosResponse<any, any>>;
+    getMedia(lib: string, key: string, encoding: string): Promise<AxiosResponse<any, any>>;
+    download(lib: string, key: string): Promise<AxiosResponse<any, any>>;
+    getExifData(lib: string, key: string): Promise<AxiosResponse<any, any>>;
+    html2pdf(lib: string, data: any): Promise<AxiosResponse<any, any>>;
+    createDir(lib: string, path: string): Promise<AxiosResponse<any, any>>;
+    deleteDir(lib: string, path: string): Promise<AxiosResponse<any, any>>;
+    dirs(lib: string, data: string): Promise<AxiosResponse<any, any>>;
+    fillPdf(lib: string, data: PDFFillOptions): Promise<AxiosResponse<any, any>>;
+    /**
+     * Convert data between different formats (JSON, CSV, Excel)
+     *
+     * @param lib - Library reference UUID
+     * @param data - Raw data to convert
+     * @param params - Conversion parameters
+     * @returns Promise resolving to converted data
+     *
+     * @example
+     * ```typescript
+     * // Convert JSON to CSV
+     * const jsonData = [
+     *   { name: "John Doe", age: 30, email: "john@example.com" },
+     *   { name: "Jane Smith", age: 25, email: "jane@example.com" }
+     * ];
+     *
+     * const csvResult = await dms.convertData(libraryRef, jsonData, {
+     *   from: 'json',
+     *   to: 'csv'
+     * });
+     * console.log(csvResult.data); // CSV string
+     *
+     * // Convert JSON to Excel with custom sheet name
+     * const excelResult = await dms.convertData(libraryRef, jsonData, {
+     *   from: 'json',
+     *   to: 'excel',
+     *   sheet_name: 'Customer Data'
+     * });
+     * // excelResult.data is a Blob
+     * ```
+     */
+    convertData(lib: string, data: any, params: DataConversionParams): Promise<AxiosResponse<any>>;
+    /**
+     * Get information about data format and structure
+     *
+     * @param lib - Library reference UUID
+     * @param data - Raw data to analyze
+     * @param params - Analysis parameters
+     * @returns Promise resolving to data information
+     *
+     * @example
+     * ```typescript
+     * const jsonData = [
+     *   { name: "John", age: 30, email: "john@example.com" },
+     *   { name: "Jane", age: 25, email: "jane@example.com" }
+     * ];
+     *
+     * const dataInfo = await dms.getDataInfo(libraryRef, jsonData, {
+     *   format: 'json'
+     * });
+     *
+     * console.log(dataInfo.data);
+     * // Output:
+     * // {
+     * //   format: "json",
+     * //   size_bytes: 245,
+     * //   record_count: 2,
+     * //   field_count: 3,
+     * //   fields: ["name", "age", "email"],
+     * //   library_ref: "98bee1cb-0f21-4582-a832-7c32b4b61831"
+     * // }
+     * ```
+     */
+    getDataInfo(lib: string, data: any, params: DataInfoParams): Promise<AxiosResponse<DataInfo>>;
+    /**
+     * Validate data format without performing conversion
+     *
+     * @param lib - Library reference UUID
+     * @param data - Raw data to validate
+     * @param params - Validation parameters
+     * @returns Promise resolving to validation result
+     *
+     * @example
+     * ```typescript
+     * const jsonData = [{ name: "John", age: 30 }];
+     *
+     * const validation = await dms.validateData(libraryRef, jsonData, {
+     *   format: 'json'
+     * });
+     *
+     * console.log(validation.data);
+     * // Output:
+     * // {
+     * //   valid: true,
+     * //   message: "Data is valid JSON format",
+     * //   library_ref: "98bee1cb-0f21-4582-a832-7c32b4b61831"
+     * // }
+     *
+     * // Handle invalid data
+     * try {
+     *   const invalidValidation = await dms.validateData(libraryRef, "invalid json", {
+     *     format: 'json'
+     *   });
+     * } catch (error) {
+     *   console.error('Validation failed:', error.response?.data?.message);
+     * }
+     * ```
+     */
+    validateData(lib: string, data: any, params: DataValidationParams): Promise<AxiosResponse<DataValidationResult>>;
+    /**
+     * Convert JSON data to CSV format
+     *
+     * @param lib - Library reference UUID
+     * @param jsonData - JSON data (array of objects recommended for tabular data)
+     * @returns Promise resolving to CSV string
+     *
+     * @example
+     * ```typescript
+     * const jsonData = [
+     *   { name: "John Doe", age: 30, email: "john@example.com" },
+     *   { name: "Jane Smith", age: 25, email: "jane@example.com" }
+     * ];
+     *
+     * const csvResponse = await dms.jsonToCsv(libraryRef, jsonData);
+     * console.log(csvResponse.data);
+     * // Output:
+     * // name,age,email
+     * // John Doe,30,john@example.com
+     * // Jane Smith,25,jane@example.com
+     * ```
+     */
+    jsonToCsv(lib: string, jsonData: any): Promise<AxiosResponse<string>>;
+    /**
+     * Convert JSON data to Excel (.xlsx) format
+     *
+     * @param lib - Library reference UUID
+     * @param jsonData - JSON data (array of objects recommended for tabular data)
+     * @param options - Optional conversion options
+     * @returns Promise resolving to Excel file as Blob
+     *
+     * @example
+     * ```typescript
+     * const jsonData = [
+     *   { name: "John Doe", age: 30, email: "john@example.com" },
+     *   { name: "Jane Smith", age: 25, email: "jane@example.com" }
+     * ];
+     *
+     * // Basic conversion
+     * const excelResponse = await dms.jsonToExcel(libraryRef, jsonData);
+     * const blob = excelResponse.data; // Blob for download
+     *
+     * // With custom sheet name
+     * const excelWithOptions = await dms.jsonToExcel(libraryRef, jsonData, {
+     *   sheet_name: 'Customer Data'
+     * });
+     *
+     * // Create download link
+     * const url = URL.createObjectURL(excelWithOptions.data);
+     * const link = document.createElement('a');
+     * link.href = url;
+     * link.download = 'data.xlsx';
+     * link.click();
+     * ```
+     */
+    jsonToExcel(lib: string, jsonData: any, options?: ConversionOptions): Promise<AxiosResponse<Blob>>;
+    /**
+     * Convert CSV data to JSON format
+     *
+     * @param lib - Library reference UUID
+     * @param csvData - CSV data string (with headers in first row)
+     * @returns Promise resolving to JSON array
+     *
+     * @example
+     * ```typescript
+     * const csvString = `name,age,email
+     * John Doe,30,john@example.com
+     * Jane Smith,25,jane@example.com`;
+     *
+     * const jsonResponse = await dms.csvToJson(libraryRef, csvString);
+     * console.log(jsonResponse.data);
+     * // Output:
+     * // [
+     * //   { name: "John Doe", age: "30", email: "john@example.com" },
+     * //   { name: "Jane Smith", age: "25", email: "jane@example.com" }
+     * // ]
+     * ```
+     */
+    csvToJson(lib: string, csvData: string): Promise<AxiosResponse<any[]>>;
+    /**
+     * Convert CSV data to Excel (.xlsx) format
+     *
+     * @param lib - Library reference UUID
+     * @param csvData - CSV data string (with headers in first row)
+     * @param options - Optional conversion options
+     * @returns Promise resolving to Excel file as Blob
+     *
+     * @example
+     * ```typescript
+     * const csvString = `name,age,email
+     * John Doe,30,john@example.com
+     * Jane Smith,25,jane@example.com`;
+     *
+     * const excelResponse = await dms.csvToExcel(libraryRef, csvString, {
+     *   sheet_name: 'Imported Data'
+     * });
+     *
+     * // Handle the Excel blob
+     * const blob = excelResponse.data;
+     * const url = URL.createObjectURL(blob);
+     * // Use url for download or further processing
+     * ```
+     */
+    csvToExcel(lib: string, csvData: string, options?: ConversionOptions): Promise<AxiosResponse<Blob>>;
+    /**
+     * Convert Excel (.xlsx) data to JSON format
+     *
+     * @param lib - Library reference UUID
+     * @param excelData - Excel file data as Blob or ArrayBuffer
+     * @param options - Optional conversion options
+     * @returns Promise resolving to JSON array
+     *
+     * @example
+     * ```typescript
+     * // From file input
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0]; // Excel file
+     *
+     * const jsonResponse = await dms.excelToJson(libraryRef, file, {
+     *   sheet_name: 'Sheet1' // optional, defaults to first sheet
+     * });
+     *
+     * console.log(jsonResponse.data);
+     * // Output: JSON array with data from Excel sheet
+     *
+     * // From ArrayBuffer
+     * const arrayBuffer = await file.arrayBuffer();
+     * const jsonFromBuffer = await dms.excelToJson(libraryRef, arrayBuffer);
+     * ```
+     */
+    excelToJson(lib: string, excelData: Blob | ArrayBuffer, options?: ConversionOptions): Promise<AxiosResponse<any[]>>;
+    /**
+     * Convert Excel (.xlsx) data to CSV format
+     *
+     * @param lib - Library reference UUID
+     * @param excelData - Excel file data as Blob or ArrayBuffer
+     * @param options - Optional conversion options
+     * @returns Promise resolving to CSV string
+     *
+     * @example
+     * ```typescript
+     * // From file input
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const file = fileInput.files[0]; // Excel file
+     *
+     * const csvResponse = await dms.excelToCsv(libraryRef, file, {
+     *   sheet_name: 'Data' // optional, defaults to first sheet
+     * });
+     *
+     * console.log(csvResponse.data);
+     * // Output: CSV string with data from Excel sheet
+     *
+     * // Save as CSV file
+     * const csvBlob = new Blob([csvResponse.data], { type: 'text/csv' });
+     * const url = URL.createObjectURL(csvBlob);
+     * const link = document.createElement('a');
+     * link.href = url;
+     * link.download = 'converted.csv';
+     * link.click();
+     * ```
+     */
+    excelToCsv(lib: string, excelData: Blob | ArrayBuffer, options?: ConversionOptions): Promise<AxiosResponse<string>>;
+    request(method: string, endpoint: string, params?: any): Promise<AxiosResponse<any, any>>;
+    requestv1(method: string, endpoint: string, params?: any): Promise<AxiosResponse<any, any>>;
 }

package/dist/types/api/workflow.d.ts

@@ -1,4 +1,5 @@
 import PlatformBaseClient from "./platformBaseClient";
 export default class Workflow extends PlatformBaseClient {
     trigger(id: string, event: string, data: any): Promise<import("axios").AxiosResponse<any, any>>;
+    publish(event: string, data: any): Promise<import("axios").AxiosResponse<any, any>>;
 }

package/dist/types/types/integrations.d.ts

@@ -52,3 +52,67 @@ export type PDFFillOptions = {
     form_data?: Record<string, any>;
     forms?: PDFFormStructure[] | any;
 };
+/**
+ * Supported data formats for conversion operations
+ */
+export type DataFormat = 'json' | 'csv' | 'excel' | 'xlsx';
+/**
+ * Parameters for data conversion between formats
+ */
+export type DataConversionParams = {
+    /** Source format */
+    from: DataFormat;
+    /** Target format */
+    to: DataFormat;
+    /** Optional Excel sheet name (defaults to "Sheet1") */
+    sheet_name?: string;
+};
+/**
+ * Parameters for data format validation
+ */
+export type DataValidationParams = {
+    /** Format to validate against */
+    format: DataFormat;
+};
+/**
+ * Parameters for data analysis and information extraction
+ */
+export type DataInfoParams = {
+    /** Format of the data to analyze */
+    format: DataFormat;
+};
+/**
+ * Information about analyzed data structure and content
+ */
+export type DataInfo = {
+    /** Detected or specified format */
+    format: string;
+    /** Size of data in bytes */
+    size_bytes: number;
+    /** Number of records/rows */
+    record_count: number;
+    /** Number of fields/columns */
+    field_count: number;
+    /** Array of field/column names */
+    fields: string[];
+    /** Library reference UUID */
+    library_ref: string;
+};
+/**
+ * Result of data format validation
+ */
+export type DataValidationResult = {
+    /** Whether the data is valid for the specified format */
+    valid: boolean;
+    /** Validation message (success or error details) */
+    message: string;
+    /** Library reference UUID */
+    library_ref: string;
+};
+/**
+ * Optional parameters for data conversion operations
+ */
+export type ConversionOptions = {
+    /** Excel sheet name for read/write operations (defaults to "Sheet1") */
+    sheet_name?: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ptkl/sdk",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "scripts": {
     "build": "rollup -c",
     "build:monaco": "npm run build && node scripts/generate-monaco-types.cjs",