@ptkl/sdk 1.1.0 → 1.3.0

package/dist/v0.10/index.cjs.js

@@ -18991,7 +18991,6 @@ const isSandbox = typeof window !== "undefined";
  *
  * @class PlatformBaseClient
  * @extends BaseClient
- * @constructor
  * @param {AxiosInstance} [client] - The axios instance to use for the client
  *
  * @example
@@ -19112,12 +19111,6 @@ class Component extends PlatformBaseClient {
             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
@@ -19162,9 +19155,26 @@ class Component extends PlatformBaseClient {
     /**
      * 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}`, {
@@ -19201,9 +19211,20 @@ class Component extends PlatformBaseClient {
     /**
      * 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`, {
@@ -19213,12 +19234,23 @@ class Component extends PlatformBaseClient {
         });
     }
     /**
-     * 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}`, {
@@ -19339,6 +19371,115 @@ class Component extends PlatformBaseClient {
     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
      *
@@ -19430,8 +19571,7 @@ class Functions extends PlatformBaseClient {
      * 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
@@ -19957,7 +20097,7 @@ class Project extends PlatformBaseClient {
     }
     /**
      * 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) {
@@ -20537,7 +20677,6 @@ class DMS extends IntegrationsBaseClient {
      * - 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
@@ -20630,7 +20769,6 @@ class DMS extends IntegrationsBaseClient {
     /**
      * 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
@@ -20671,7 +20809,6 @@ class DMS extends IntegrationsBaseClient {
     /**
      * 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
@@ -20719,7 +20856,6 @@ class DMS extends IntegrationsBaseClient {
      * - 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
      *
@@ -20770,7 +20906,6 @@ class DMS extends IntegrationsBaseClient {
      * 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
@@ -20829,7 +20964,6 @@ class DMS extends IntegrationsBaseClient {
     /**
      * 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
      *
@@ -20860,7 +20994,6 @@ class DMS extends IntegrationsBaseClient {
     /**
      * 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
@@ -20898,7 +21031,6 @@ class DMS extends IntegrationsBaseClient {
     /**
      * 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
@@ -20938,7 +21070,6 @@ class DMS extends IntegrationsBaseClient {
     /**
      * 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
@@ -21002,6 +21133,148 @@ class DMS extends IntegrationsBaseClient {
     }
 }
 
+/**
+ * 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({
@@ -21869,6 +22142,7 @@ class Integrations extends IntegrationsBaseClient {
         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),
@@ -21886,6 +22160,9 @@ class Integrations extends IntegrationsBaseClient {
     getMinimax() {
         return this.getInterfaceOf('protokol-minimax');
     }
+    getMail() {
+        return this.getInterfaceOf('protokol-mail');
+    }
     getNBS() {
         return this.getInterfaceOf('nbs');
     }
@@ -21942,6 +22219,7 @@ exports.Functions = Functions;
 exports.Integration = Integrations;
 exports.Integrations = Integrations;
 exports.Invoicing = Invoicing;
+exports.Mail = Mail;
 exports.NBS = NBS;
 exports.Payments = Payments;
 exports.Platform = Platform;