@ptkl/sdk 1.1.0 → 1.3.0

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

@@ -24,7 +24,6 @@ const isSandbox = typeof window !== "undefined";
  *
  * @class PlatformBaseClient
  * @extends BaseClient
- * @constructor
  * @param {AxiosInstance} [client] - The axios instance to use for the client
  *
  * @example
@@ -145,12 +144,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
@@ -195,9 +188,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}`, {
@@ -234,9 +244,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`, {
@@ -246,12 +267,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}`, {
@@ -372,6 +404,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
      *
@@ -463,8 +604,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
@@ -990,7 +1130,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) {
@@ -1570,7 +1710,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
@@ -1663,7 +1802,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
@@ -1704,7 +1842,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
@@ -1752,7 +1889,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
      *
@@ -1803,7 +1939,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
@@ -1862,7 +1997,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
      *
@@ -1893,7 +2027,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
@@ -1931,7 +2064,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
@@ -1971,7 +2103,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
@@ -2035,6 +2166,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({
@@ -2902,6 +3175,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),
@@ -2919,6 +3193,9 @@ class Integrations extends IntegrationsBaseClient {
     getMinimax() {
         return this.getInterfaceOf('protokol-minimax');
     }
+    getMail() {
+        return this.getInterfaceOf('protokol-mail');
+    }
     getNBS() {
         return this.getInterfaceOf('nbs');
     }
@@ -2964,4 +3241,4 @@ class Invoicing extends PlatformBaseClient {
     }
 }
 
-export { APIUser, Apps, Component, ComponentUtils, Config, DMS, Forge, Functions, Integrations as Integration, Integrations, Invoicing, NBS, Payments, Platform, Project, Ratchet, Sandbox, MinFin as SerbiaMinFin, System, Thunder, Users, VPFR, Workflow };
+export { APIUser, Apps, Component, ComponentUtils, Config, DMS, Forge, Functions, Integrations as Integration, Integrations, Invoicing, Mail, NBS, Payments, Platform, Project, Ratchet, Sandbox, MinFin as SerbiaMinFin, System, Thunder, Users, VPFR, Workflow };

package/dist/v0.10/types/component.d.ts

@@ -76,6 +76,50 @@ type CreateManyOptions = {
 type ModifyOptions = {
     upsert: boolean;
 };
+/**
+ * MongoDB update operators that can be included inline in the `data` payload.
+ *
+ * Any key starting with `$` in the data object is automatically detected as an
+ * update operator and applied with MongoDB semantics instead of the default `$set`.
+ *
+ * Supported operators:
+ * - `$inc` — Increment a numeric field
+ * - `$push` — Append to an array
+ * - `$pull` — Remove from an array by condition
+ * - `$addToSet` — Add to array only if not present
+ * - `$pop` — Remove first (-1) or last (1) element from array
+ * - `$unset` — Remove a field from the document
+ * - `$min` — Update only if new value is less than current
+ * - `$max` — Update only if new value is greater than current
+ * - `$mul` — Multiply a numeric field
+ *
+ * @example
+ * ```ts
+ * // Data with inline operators
+ * const data = {
+ *   name: "John",          // → $set
+ *   $inc: { views: 1 },    // → $inc
+ *   $push: { tags: "vip" } // → $push
+ * }
+ * ```
+ */
+type UpdateOperators = {
+    $inc?: Record<string, number>;
+    $push?: Record<string, any>;
+    $pull?: Record<string, any>;
+    $addToSet?: Record<string, any>;
+    $pop?: Record<string, 1 | -1>;
+    $unset?: Record<string, "">;
+    $min?: Record<string, any>;
+    $max?: Record<string, any>;
+    $mul?: Record<string, number>;
+};
+/**
+ * Model data payload that supports inline update operators.
+ * Regular fields are applied via `$set`, operator keys are applied with their
+ * respective MongoDB semantics.
+ */
+type ModelUpdateData = Record<string, any> & UpdateOperators;
 type ComponentOptions = {
     version?: string;
 };
@@ -233,6 +277,30 @@ type Function = {
     name: string;
     expr: string;
 };
+type Extension = {
+    name: string;
+    is_active: boolean;
+    fields?: SettingsField[];
+    functions?: Function[];
+    workflows?: Record<string, any>[];
+    templates?: Record<string, any>;
+    templates_dist?: TemplatesDist;
+    config?: Record<string, any>;
+    version?: string;
+};
+type FieldAccessConfig = {
+    fields: string[];
+    actions: string[];
+    roles: string[];
+};
+type Policy<T = Record<string, any>> = {
+    type: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    priority: number;
+    config?: T;
+};
 type TemplatesDist = {
     sdk_version: number;
     sdk_engine: string;
@@ -275,6 +343,8 @@ type Settings = {
     templates_dist?: TemplatesDist;
     config?: Record<string, any>;
     functions?: Function[];
+    extensions?: Extension[];
+    policies?: Policy[];
 };
 type SetupData = {
     name: string;
@@ -295,4 +365,4 @@ type SetupData = {
     integrator?: string;
 };
 type ComponentCreateResponse = ComponentListItem;
-export { FindParams, FindOptions, FindResponse, FindAdvancedParams, FindAggregateParams, Model, UpdateOptions, ModifyOptions, ComponentOptions, ComponentListResponse, ComponentListItem, ComponentLabel, ComponentWorkspace, StreamCallback, StreamHandler, AggregateChainable, UpdateManyOptions, CreateManyOptions, Settings, SettingsField, FieldRoles, FieldConstraints, Context, Preset, PresetContext, Filters, Function, TemplatesDist, SetupData, ComponentCreateResponse, };
+export { FindParams, FindOptions, FindResponse, FindAdvancedParams, FindAggregateParams, Model, UpdateOptions, ModifyOptions, UpdateOperators, ModelUpdateData, ComponentOptions, ComponentListResponse, ComponentListItem, ComponentLabel, ComponentWorkspace, StreamCallback, StreamHandler, AggregateChainable, UpdateManyOptions, CreateManyOptions, Settings, SettingsField, FieldRoles, FieldConstraints, Context, Preset, PresetContext, Filters, Function, Extension, Policy, FieldAccessConfig, TemplatesDist, SetupData, ComponentCreateResponse, };