@ptkl/sdk 1.1.0 → 1.3.0

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

@@ -1,4 +1,4 @@
-import { FindParams, FindOptions, FindResponse, FindAdvancedParams, FindAggregateParams, Model, UpdateOptions, ModifyOptions, StreamHandler, AggregateChainable, ComponentOptions, UpdateManyOptions, CreateManyOptions } from "../types/component";
+import { FindParams, FindOptions, FindResponse, FindAdvancedParams, FindAggregateParams, Model, UpdateOptions, ModifyOptions, StreamHandler, AggregateChainable, ComponentOptions, UpdateManyOptions, CreateManyOptions, Extension, Policy } from "../types/component";
 import PlatformBaseClient from "./platformBaseClient";
 import { AxiosResponse } from "axios";
 export default class Component extends PlatformBaseClient {
@@ -50,9 +50,26 @@ export default 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)
      */
     update(uuid: string, data: Record<string, any>, options: UpdateOptions): Promise<AxiosResponse<any, any>>;
     /**
@@ -74,18 +91,40 @@ export default 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 }
+     * )
      */
     modify(filters: Record<string, any>, data: Record<string, any>, options: ModifyOptions): Promise<AxiosResponse<any, any>>;
     /**
-     * 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)
      */
     concurrentUpdate(uuid: string, version: number, data: Record<string, any>, options: UpdateOptions): Promise<AxiosResponse<any, any>>;
     create(model: Record<string, any>): Promise<AxiosResponse<any, any>>;
@@ -122,6 +161,103 @@ export default class Component extends PlatformBaseClient {
     workflow(event: string, input: any): Promise<AxiosResponse<any, any>>;
     function(name: string, input: any): Promise<AxiosResponse<any, any>>;
     revisions(uuid: string): Promise<AxiosResponse<any, any>>;
+    /**
+     * 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')
+     * ```
+     */
+    installExtension(extension: Extension, version: string): Promise<AxiosResponse<any, any>>;
+    /**
+     * 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' }
+     * })
+     * ```
+     */
+    updateExtension(name: string, version: string, data: Partial<Extension>): Promise<AxiosResponse<any, any>>;
+    /**
+     * 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')
+     * ```
+     */
+    deleteExtension(name: string, version: string): Promise<AxiosResponse<any, any>>;
+    /**
+     * 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')
+     * ```
+     */
+    installPolicy(policy: Policy, version: string): Promise<AxiosResponse<any, any>>;
+    /**
+     * 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
+     * })
+     * ```
+     */
+    updatePolicy(name: string, version: string, data: Partial<Policy>): Promise<AxiosResponse<any, any>>;
+    /**
+     * 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')
+     * ```
+     */
+    deletePolicy(name: string, version: string): Promise<AxiosResponse<any, any>>;
     /**
      * Internal method to handle NDJSON streaming responses
      *
@@ -129,4 +265,4 @@ export default class Component extends PlatformBaseClient {
      */
     private _streamNDJSON;
 }
-export { FindParams, FindOptions, FindResponse, FindAdvancedParams, FindAggregateParams, Model, UpdateOptions, StreamHandler, AggregateChainable, ComponentOptions, };
+export { FindParams, FindOptions, FindResponse, FindAdvancedParams, FindAggregateParams, Model, UpdateOptions, StreamHandler, AggregateChainable, ComponentOptions, Extension, };

package/dist/v0.10/api/functions.d.ts

@@ -7,8 +7,7 @@ export default 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

package/dist/v0.10/api/index.d.ts

@@ -21,3 +21,4 @@ export { default as DMS } from './integrations/dms';
 export { default as SerbiaMinFin } from './integrations/serbia/minfin';
 export { default as NBS } from './integrations/serbia/nbs';
 export { default as VPFR } from './integrations/serbia/minfin/vpfr';
+export { default as Mail } from './integrations/mail';

package/dist/v0.10/api/integrations/dms.d.ts

@@ -150,7 +150,6 @@ export default 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
@@ -208,7 +207,6 @@ export default 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
@@ -240,7 +238,6 @@ export default 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
@@ -279,7 +276,6 @@ export default 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
      *
@@ -317,7 +313,6 @@ export default 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
@@ -360,7 +355,6 @@ export default 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
      *
@@ -383,7 +377,6 @@ export default 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
@@ -408,7 +401,6 @@ export default 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
@@ -435,7 +427,6 @@ export default 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

package/dist/v0.10/api/integrations/mail.d.ts

@@ -0,0 +1,125 @@
+import IntegrationsBaseClient from "../integrationsBaseClient";
+import { SendEmailRequest, SendEmailResponse, MailLog, EmailListResponse, ListEmailsParams, AttachmentMeta } from "../../types/integrations/mail";
+/**
+ * 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)
+ * ```
+ */
+export default 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
+     *   }]
+     * })
+     * ```
+     */
+    send(input: SendEmailRequest): Promise<SendEmailResponse>;
+    /**
+     * 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 })
+     * ```
+     */
+    list(params?: ListEmailsParams): Promise<EmailListResponse>;
+    /**
+     * 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)
+     * ```
+     */
+    get(messageId: string): Promise<MailLog>;
+    /**
+     * 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")
+     * ```
+     */
+    resend(messageId: string): Promise<SendEmailResponse>;
+    /**
+     * 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))
+     * ```
+     */
+    listAttachments(messageId: string): Promise<AttachmentMeta[]>;
+    /**
+     * 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"
+     * )
+     * ```
+     */
+    downloadAttachment(messageId: string, attachmentId: string): Promise<ArrayBuffer>;
+}

package/dist/v0.10/api/integrations.d.ts

@@ -1,5 +1,6 @@
 import Invoicing from "./integrations/invoicing";
 import DMS from "./integrations/dms";
+import Mail from "./integrations/mail";
 import MinFin from "./integrations/serbia/minfin";
 import IntegrationsBaseClient from "./integrationsBaseClient";
 import Payments from "./integrations/payments";
@@ -16,6 +17,7 @@ export default class Integrations extends IntegrationsBaseClient {
     getInvoicing(): Invoicing;
     getPayments(): Payments;
     getMinimax(): Minimax;
+    getMail(): Mail;
     getNBS(): NBS;
     getSerbiaMinFin(): MinFin;
     isInstalled(id: string): Promise<boolean>;

package/dist/v0.10/api/platformBaseClient.d.ts

@@ -6,7 +6,6 @@ import BaseClient from "./baseClient";
  *
  * @class PlatformBaseClient
  * @extends BaseClient
- * @constructor
  * @param {AxiosInstance} [client] - The axios instance to use for the client
  *
  * @example

package/dist/v0.10/api/project.d.ts

@@ -24,7 +24,7 @@ export default class Project extends PlatformBaseClient {
     archive(): Promise<AxiosResponse<any>>;
     /**
      * Invite a user to the project
-     * @param email Array of emails
+     * @param emails Array of emails
      * @param roles Array of role UUIDs
      */
     invite(emails: string[], roles: string[]): Promise<AxiosResponse<any>>;