@ptkl/sdk 1.1.0 → 1.3.0

package/dist/index.0.10.js

@@ -25,7 +25,6 @@ var ProtokolSDK010 = (function (exports, axios) {
      *
      * @class PlatformBaseClient
      * @extends BaseClient
-     * @constructor
      * @param {AxiosInstance} [client] - The axios instance to use for the client
      *
      * @example
@@ -146,12 +145,6 @@ var ProtokolSDK010 = (function (exports, axios) {
                 dateTo: ctx.dateTo,
                 dateField: ctx.dateField,
             };
-            if (Object.keys(ctx.$adv || []).length > 0) {
-                params.$adv = JSON.stringify([ctx.$adv]);
-            }
-            if (ctx.$aggregate && ctx.$aggregate.length > 0) {
-                params.$aggregate = JSON.stringify(ctx.$aggregate);
-            }
             return await this.client.post(`/v4/system/component/${this.ref}/models`, {
                 ...params,
                 options: opts
@@ -196,9 +189,26 @@ var ProtokolSDK010 = (function (exports, axios) {
         /**
          * Update model by uuid
          *
-         * @param uuid string - The uuid of the model
-         * @param data
-         * @returns
+         * Regular fields in `data` are applied via `$set`. You can include MongoDB
+         * update operators (prefixed with `$`) directly in the data object for
+         * granular updates like incrementing, pushing to arrays, etc.
+         *
+         * @param uuid - The uuid of the model to update
+         * @param data - Fields to update, optionally including update operators
+         * @param options - Update options
+         * @returns The updated model
+         *
+         * @example
+         * // Simple update (backwards compatible)
+         * await component.update(uuid, { name: "John" }, opts)
+         *
+         * // With update operators
+         * await component.update(uuid, {
+         *   name: "John",
+         *   $inc: { login_count: 1 },
+         *   $push: { tags: "verified" },
+         *   $addToSet: { roles: "admin" }
+         * }, opts)
          */
         async update(uuid, data, options) {
             return await this.client.post(`/v4/system/component/${this.ref}/model/${uuid}`, {
@@ -235,9 +245,20 @@ var ProtokolSDK010 = (function (exports, axios) {
         /**
          * Modify models by filters
          *
-         * @param data
-         * @param options
-         * @returns
+         * Updates all models matching the given filters. Supports inline update
+         * operators in the data payload for granular operations.
+         *
+         * @param filters - Query filters to match models
+         * @param data - Fields to update, optionally including update operators
+         * @param options - Modify options (e.g. upsert)
+         * @returns The modified models
+         *
+         * @example
+         * await component.modify(
+         *   { status: "active" },
+         *   { $inc: { impression_count: 1 }, $addToSet: { viewers: "user-1" } },
+         *   { upsert: false }
+         * )
          */
         async modify(filters, data, options) {
             return await this.client.patch(`/v4/system/component/${this.ref}/modify/model`, {
@@ -247,12 +268,23 @@ var ProtokolSDK010 = (function (exports, axios) {
             });
         }
         /**
-         * Concurrent update model by uuid
+         * Concurrent update model by uuid with optimistic locking
          *
-         * @param uuid string - The uuid of the model
-         * @param version number - The version of the model
-         * @param data
-         * @returns
+         * Uses version-based concurrency control — the update will fail with a
+         * conflict error if the document has been modified since the provided version.
+         * Supports inline update operators in the data payload.
+         *
+         * @param uuid - The uuid of the model
+         * @param version - The expected __version__ of the model
+         * @param data - Fields to update, optionally including update operators
+         * @param options - Update options
+         * @returns The updated model
+         *
+         * @example
+         * await component.concurrentUpdate(uuid, model.__version__, {
+         *   status: "processed",
+         *   $inc: { retry_count: 1 }
+         * }, opts)
          */
         async concurrentUpdate(uuid, version, data, options) {
             return await this.client.post(`/v4/system/component/${this.ref}/model/${uuid}`, {
@@ -373,6 +405,115 @@ var ProtokolSDK010 = (function (exports, axios) {
         async revisions(uuid) {
             return await this.client.get(`/v3/system/component/${this.ref}/model/${uuid}/revisions`);
         }
+        /**
+         * Install a new extension on the component
+         *
+         * @param extension - The extension definition to install
+         * @param version - The component version to install the extension on
+         * @returns Updated component settings
+         *
+         * @example
+         * ```typescript
+         * await component.installExtension({
+         *     name: 'shipping_tracker',
+         *     is_active: true,
+         *     fields: [...],
+         *     config: { api_key: 'key' }
+         * }, '0.1.0')
+         * ```
+         */
+        async installExtension(extension, version) {
+            return await this.client.post(`/v4/system/component/${this.ref}/${version}/extensions`, extension);
+        }
+        /**
+         * Update an existing extension on the component
+         *
+         * @param name - The name of the extension to update
+         * @param version - The component version
+         * @param data - Partial extension data to update
+         * @returns Updated component settings
+         *
+         * @example
+         * ```typescript
+         * await component.updateExtension('shipping_tracker', '0.1.0', {
+         *     is_active: false,
+         *     config: { api_key: 'new-key' }
+         * })
+         * ```
+         */
+        async updateExtension(name, version, data) {
+            return await this.client.patch(`/v4/system/component/${this.ref}/${version}/extensions/${name}`, data);
+        }
+        /**
+         * Delete an extension from the component
+         *
+         * @param name - The name of the extension to delete
+         * @param version - The component version
+         * @returns Updated component settings
+         *
+         * @example
+         * ```typescript
+         * await component.deleteExtension('shipping_tracker', '0.1.0')
+         * ```
+         */
+        async deleteExtension(name, version) {
+            return await this.client.delete(`/v4/system/component/${this.ref}/${version}/extensions/${name}`);
+        }
+        /**
+         * Install a new policy on the component
+         *
+         * @param policy - The policy definition to install
+         * @param version - The component version to install the policy on
+         * @returns Updated component settings
+         *
+         * @example
+         * ```typescript
+         * await component.installPolicy({
+         *     type: 'field_access',
+         *     name: 'restrict_email',
+         *     enabled: true,
+         *     priority: 1,
+         *     config: { fields: ['email'], actions: ['see'], roles: ['role-uuid'] }
+         * }, '0.1.0')
+         * ```
+         */
+        async installPolicy(policy, version) {
+            return await this.client.post(`/v4/system/component/${this.ref}/${version}/policies`, policy);
+        }
+        /**
+         * Update an existing policy on the component
+         *
+         * @param name - The name of the policy to update
+         * @param version - The component version
+         * @param data - Partial policy data to update
+         * @returns Updated component settings
+         *
+         * @example
+         * ```typescript
+         * await component.updatePolicy('restrict_email', '0.1.0', {
+         *     enabled: false,
+         *     priority: 2
+         * })
+         * ```
+         */
+        async updatePolicy(name, version, data) {
+            return await this.client.patch(`/v4/system/component/${this.ref}/${version}/policies/${name}`, data);
+        }
+        /**
+         * Delete a policy from the component
+         *
+         * @param name - The name of the policy to delete
+         * @param version - The component version
+         * @returns Updated component settings
+         *
+         * @example
+         * ```typescript
+         * await component.deletePolicy('restrict_email', '0.1.0')
+         * ```
+         */
+        async deletePolicy(name, version) {
+            return await this.client.delete(`/v4/system/component/${this.ref}/${version}/policies/${name}`);
+        }
         /**
          * Internal method to handle NDJSON streaming responses
          *
@@ -464,8 +605,7 @@ var ProtokolSDK010 = (function (exports, axios) {
          * Run platform function
          *
          * @param id - Function ID
-         * @param input - Input data
-         * @param query - Query parameters
+         * @param d - Object containing input data, query parameters, and headers
          * @returns - Function result
          *
          * @example
@@ -991,7 +1131,7 @@ var ProtokolSDK010 = (function (exports, axios) {
         }
         /**
          * Invite a user to the project
-         * @param email Array of emails
+         * @param emails Array of emails
          * @param roles Array of role UUIDs
          */
         async invite(emails, roles) {
@@ -1571,7 +1711,6 @@ var ProtokolSDK010 = (function (exports, axios) {
          * - Explicit structure: JSON with `header`, `items`, and `footer` properties
          * - Auto-detection: Mixed JSON arrays with metadata objects and summary rows
          *
-         * @param lib - Library reference UUID
          * @param data - Raw data to convert
          * @param params - Conversion parameters including structured data options
          * @returns Promise resolving to converted data
@@ -1664,7 +1803,6 @@ var ProtokolSDK010 = (function (exports, axios) {
         /**
          * 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
@@ -1705,7 +1843,6 @@ var ProtokolSDK010 = (function (exports, axios) {
         /**
          * 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
@@ -1753,7 +1890,6 @@ var ProtokolSDK010 = (function (exports, axios) {
          * - Regular arrays are converted directly to CSV
          * - Structured data (with metadata objects) is automatically detected and formatted
          *
-         * @param lib - Library reference UUID
          * @param jsonData - JSON data (array of objects or structured data)
          * @returns Promise resolving to CSV string
          *
@@ -1804,7 +1940,6 @@ var ProtokolSDK010 = (function (exports, axios) {
          * Supports both regular JSON arrays and structured data patterns.
          * Excel files are always generated with .xlsx extension.
          *
-         * @param lib - Library reference UUID
          * @param jsonData - JSON data (array of objects or structured data)
          * @param options - Optional conversion options
          * @returns Promise resolving to Excel file as Blob
@@ -1863,7 +1998,6 @@ var ProtokolSDK010 = (function (exports, axios) {
         /**
          * 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
          *
@@ -1894,7 +2028,6 @@ var ProtokolSDK010 = (function (exports, axios) {
         /**
          * 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
@@ -1932,7 +2065,6 @@ var ProtokolSDK010 = (function (exports, axios) {
         /**
          * 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
@@ -1972,7 +2104,6 @@ var ProtokolSDK010 = (function (exports, axios) {
         /**
          * 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
@@ -2036,6 +2167,148 @@ var ProtokolSDK010 = (function (exports, axios) {
         }
     }
 
+    /**
+     * SDK client for the Protokol Mail integration.
+     *
+     * Provides methods to send emails, list email logs, resend failed emails,
+     * and manage attachments through the Protokol Mail API.
+     *
+     * @example
+     * ```typescript
+     * import { Mail } from "@ptkl/sdk/beta"
+     *
+     * const mail = new Mail()
+     *
+     * // Send an email
+     * const result = await mail.send({
+     *   to: ["user@example.com"],
+     *   subject: "Hello",
+     *   body: "<h1>Welcome!</h1>"
+     * })
+     *
+     * console.log(result.message_id)
+     * ```
+     */
+    class Mail extends IntegrationsBaseClient {
+        /**
+         * Send an email. The email is queued for async delivery.
+         *
+         * Supports both JSON body (with base64-encoded attachments) and
+         * multipart/form-data (with file uploads).
+         *
+         * @param input - The email content and recipients
+         * @returns The queued email's message ID and status
+         *
+         * @example
+         * ```typescript
+         * const result = await mail.send({
+         *   to: ["recipient@example.com"],
+         *   cc: ["cc@example.com"],
+         *   subject: "Invoice #123",
+         *   body: "<p>Please find your invoice attached.</p>",
+         *   reply_to: "billing@company.com",
+         *   sender_name: "Billing Department",
+         *   attachments: [{
+         *     file_name: "invoice.pdf",
+         *     mime_type: "application/pdf",
+         *     content: "base64encodedcontent...",
+         *     size: 12345
+         *   }]
+         * })
+         * ```
+         */
+        async send(input) {
+            const { data } = await this.client.post("/protokol-mail/v1/emails", input);
+            return data;
+        }
+        /**
+         * List emails for the current project with optional filtering and pagination.
+         *
+         * @param params - Optional query parameters for filtering and pagination
+         * @returns Paginated list of email log entries
+         *
+         * @example
+         * ```typescript
+         * // List all emails
+         * const emails = await mail.list()
+         *
+         * // List failed emails, page 2
+         * const failed = await mail.list({ status: "failed", page: 2, limit: 10 })
+         * ```
+         */
+        async list(params) {
+            const { data } = await this.client.get("/protokol-mail/v1/emails", { params });
+            return data;
+        }
+        /**
+         * Get a single email by its message ID.
+         *
+         * @param messageId - The UUID of the email message
+         * @returns The full email log entry
+         *
+         * @example
+         * ```typescript
+         * const email = await mail.get("550e8400-e29b-41d4-a716-446655440000")
+         * console.log(email.status, email.subject)
+         * ```
+         */
+        async get(messageId) {
+            const { data } = await this.client.get(`/protokol-mail/v1/emails/${messageId}`);
+            return data;
+        }
+        /**
+         * Resend a previously failed email. Resets the retry counter and
+         * re-queues the email for delivery.
+         *
+         * @param messageId - The UUID of the email to resend
+         * @returns Confirmation with the message ID
+         *
+         * @example
+         * ```typescript
+         * await mail.resend("550e8400-e29b-41d4-a716-446655440000")
+         * ```
+         */
+        async resend(messageId) {
+            const { data } = await this.client.post(`/protokol-mail/v1/emails/${messageId}/resend`);
+            return data;
+        }
+        /**
+         * List attachment metadata for a specific email.
+         *
+         * @param messageId - The UUID of the email message
+         * @returns Array of attachment metadata entries
+         *
+         * @example
+         * ```typescript
+         * const attachments = await mail.listAttachments("550e8400-e29b-41d4-a716-446655440000")
+         * attachments.forEach(att => console.log(att.file_name, att.file_size))
+         * ```
+         */
+        async listAttachments(messageId) {
+            const { data } = await this.client.get(`/protokol-mail/v1/emails/${messageId}/attachments`);
+            return data;
+        }
+        /**
+         * Download an attachment's binary content.
+         *
+         * @param messageId - The UUID of the email message
+         * @param attachmentId - The UUID of the attachment
+         * @returns The raw binary data as an ArrayBuffer
+         *
+         * @example
+         * ```typescript
+         * const content = await mail.downloadAttachment(
+         *   "550e8400-e29b-41d4-a716-446655440000",
+         *   "660e8400-e29b-41d4-a716-446655440000"
+         * )
+         * ```
+         */
+        async downloadAttachment(messageId, attachmentId) {
+            const { data } = await this.client.get(`/protokol-mail/v1/emails/${messageId}/attachments/${attachmentId}`, { responseType: "arraybuffer" });
+            return data;
+        }
+    }
+
     class VPFR extends IntegrationsBaseClient {
         async request(method, endpoint, params) {
             return await this.client.request({
@@ -2903,6 +3176,7 @@ var ProtokolSDK010 = (function (exports, axios) {
             this.integrations = {
                 'serbia-minfin': new MinFin().setClient(this.client),
                 'protokol-dms': new DMS().setClient(this.client),
+                'protokol-mail': new Mail().setClient(this.client),
                 'nbs': new NBS().setClient(this.client),
                 'protokol-payments': new Payments().setClient(this.client),
                 'protokol-minimax': new Minimax().setClient(this.client),
@@ -2920,6 +3194,9 @@ var ProtokolSDK010 = (function (exports, axios) {
         getMinimax() {
             return this.getInterfaceOf('protokol-minimax');
         }
+        getMail() {
+            return this.getInterfaceOf('protokol-mail');
+        }
         getNBS() {
             return this.getInterfaceOf('nbs');
         }
@@ -2976,6 +3253,7 @@ var ProtokolSDK010 = (function (exports, axios) {
     exports.Integration = Integrations;
     exports.Integrations = Integrations;
     exports.Invoicing = Invoicing;
+    exports.Mail = Mail;
     exports.NBS = NBS;
     exports.Payments = Payments;
     exports.Platform = Platform;

package/dist/index.0.9.js

@@ -25,7 +25,6 @@ var ProtokolSDK09 = (function (exports, axios) {
      *
      * @class PlatformBaseClient
      * @extends BaseClient
-     * @constructor
      * @param {AxiosInstance} [client] - The axios instance to use for the client
      *
      * @example
@@ -475,8 +474,7 @@ var ProtokolSDK09 = (function (exports, axios) {
          * Run platform function
          *
          * @param id - Function ID
-         * @param input - Input data
-         * @param query - Query parameters
+         * @param d - Object containing input data, query parameters, and headers
          * @returns - Function result
          *
          * @example
@@ -991,7 +989,7 @@ var ProtokolSDK09 = (function (exports, axios) {
         }
         /**
          * Invite a user to the project
-         * @param email Array of emails
+         * @param emails Array of emails
          * @param roles Array of role UUIDs
          */
         async invite(emails, roles) {
@@ -1960,6 +1958,92 @@ var ProtokolSDK09 = (function (exports, axios) {
         }
     }
 
+    /**
+     * SDK client for the Protokol Mail integration.
+     *
+     * Provides methods to send emails, list email logs, resend failed emails,
+     * and manage attachments through the Protokol Mail API.
+     *
+     * @example
+     * ```typescript
+     * import { Mail } from "@ptkl/sdk"
+     *
+     * const mail = new Mail()
+     *
+     * // Send an email
+     * const result = await mail.send({
+     *   to: ["user@example.com"],
+     *   subject: "Hello",
+     *   body: "<h1>Welcome!</h1>"
+     * })
+     *
+     * console.log(result.message_id)
+     * ```
+     */
+    class Mail extends IntegrationsBaseClient {
+        /**
+         * Send an email. The email is queued for async delivery.
+         *
+         * @param input - The email content and recipients
+         * @returns The queued email's message ID and status
+         */
+        async send(input) {
+            const { data } = await this.client.post("/protokol-mail/v1/emails", input);
+            return data;
+        }
+        /**
+         * List emails for the current project with optional filtering and pagination.
+         *
+         * @param params - Optional query parameters for filtering and pagination
+         * @returns Paginated list of email log entries
+         */
+        async list(params) {
+            const { data } = await this.client.get("/protokol-mail/v1/emails", { params });
+            return data;
+        }
+        /**
+         * Get a single email by its message ID.
+         *
+         * @param messageId - The UUID of the email message
+         * @returns The full email log entry
+         */
+        async get(messageId) {
+            const { data } = await this.client.get(`/protokol-mail/v1/emails/${messageId}`);
+            return data;
+        }
+        /**
+         * Resend a previously failed email.
+         *
+         * @param messageId - The UUID of the email to resend
+         * @returns Confirmation with the message ID
+         */
+        async resend(messageId) {
+            const { data } = await this.client.post(`/protokol-mail/v1/emails/${messageId}/resend`);
+            return data;
+        }
+        /**
+         * List attachment metadata for a specific email.
+         *
+         * @param messageId - The UUID of the email message
+         * @returns Array of attachment metadata entries
+         */
+        async listAttachments(messageId) {
+            const { data } = await this.client.get(`/protokol-mail/v1/emails/${messageId}/attachments`);
+            return data;
+        }
+        /**
+         * Download an attachment's binary content.
+         *
+         * @param messageId - The UUID of the email message
+         * @param attachmentId - The UUID of the attachment
+         * @returns The raw binary data as an ArrayBuffer
+         */
+        async downloadAttachment(messageId, attachmentId) {
+            const { data } = await this.client.get(`/protokol-mail/v1/emails/${messageId}/attachments/${attachmentId}`, { responseType: "arraybuffer" });
+            return data;
+        }
+    }
+
     class SerbiaUtil extends IntegrationsBaseClient {
         async nbsSearch(params) {
             return await this.services("GET", "nbs/search", {
@@ -2815,6 +2899,7 @@ var ProtokolSDK09 = (function (exports, axios) {
                 'protokol-invoicing': new Invoicing().setClient(this.client),
                 'protokol-vpfr': new VPFR().setClient(this.client),
                 'protokol-dms': new DMS().setClient(this.client),
+                'protokol-mail': new Mail().setClient(this.client),
                 'serbia-utilities': new SerbiaUtil().setClient(this.client),
                 'protokol-payments': new Payments().setClient(this.client),
                 'protokol-minimax': new Minimax().setClient(this.client),
@@ -2832,6 +2917,9 @@ var ProtokolSDK09 = (function (exports, axios) {
         getInvoicing() {
             return this.getInterfaceOf('protokol-invoicing');
         }
+        getMail() {
+            return this.getInterfaceOf('protokol-mail');
+        }
         getPayments() {
             return this.getInterfaceOf('protokol-payments');
         }
@@ -2867,6 +2955,7 @@ var ProtokolSDK09 = (function (exports, axios) {
     exports.Integration = Integrations;
     exports.Integrations = Integrations;
     exports.Invoicing = Invoicing;
+    exports.Mail = Mail;
     exports.Payments = Payments;
     exports.Platform = Platform;
     exports.Project = Project;

package/dist/package.json

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