@ptkl/sdk 1.1.0 → 1.3.0

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

@@ -0,0 +1,156 @@
+/**
+ * Represents the status of an email in the system.
+ */
+export type EmailStatus = "pending" | "sent" | "failed";
+/**
+ * Represents a mail log entry returned by the API.
+ */
+export type MailLog = {
+    /** Unique message identifier (UUID) */
+    message_id: string;
+    /** Project scope UUID */
+    project_uuid: string;
+    /** Tenant scope UUID */
+    tenant_uuid: string;
+    /** Associated workflow component UUID */
+    component_uuid?: string;
+    /** Environment: "dev" or "live" */
+    env: string;
+    /** Sender address (auto-generated from tenant) */
+    from: string;
+    /** Recipient email addresses */
+    to: string[];
+    /** CC email addresses */
+    cc: string[];
+    /** BCC email addresses */
+    bcc: string[];
+    /** Reply-to email address */
+    reply_to?: string;
+    /** Email subject line */
+    subject: string;
+    /** Email body (HTML) */
+    body: string;
+    /** Attachment metadata as JSON string */
+    attachments?: string;
+    /** Current sending status */
+    status: EmailStatus;
+    /** Number of send retry attempts */
+    retry_count: number;
+    /** Maximum allowed retries */
+    max_retries: number;
+    /** Error message from last failed attempt */
+    error_message?: string;
+    /** Timestamp when email was successfully sent */
+    sent_at?: string;
+    /** Timestamp when email was opened (tracking pixel) */
+    read_at?: string;
+    /** IP address of reader */
+    read_ip?: string;
+    /** User agent of reader */
+    read_user_agent?: string;
+    /** Whether the email was reported as spam */
+    spam_reported: boolean;
+    /** Timestamp of spam report */
+    spam_reported_at?: string;
+    /** Who reported the spam */
+    spam_reported_by?: string;
+    /** IP address of spam reporter */
+    spam_report_ip?: string;
+    /** Record creation timestamp */
+    created_at: string;
+    /** Record update timestamp */
+    updated_at: string;
+};
+/**
+ * Attachment input for sending an email.
+ * Provide either a `file_id` (DMS reference) or `content` (base64-encoded data).
+ */
+export type AttachmentInput = {
+    /** DMS file ID reference */
+    file_id?: string;
+    /** File name */
+    file_name: string;
+    /** MIME type (e.g. "application/pdf") */
+    mime_type: string;
+    /** Base64-encoded file content */
+    content?: string;
+    /** File size in bytes */
+    size?: number;
+};
+/**
+ * Request payload for sending an email.
+ */
+export type SendEmailRequest = {
+    /** Recipient email addresses (required) */
+    to: string[];
+    /** CC email addresses */
+    cc?: string[];
+    /** BCC email addresses */
+    bcc?: string[];
+    /** Email subject (required) */
+    subject: string;
+    /** Email body in HTML (required) */
+    body: string;
+    /** Reply-to email address */
+    reply_to?: string;
+    /** Custom sender display name */
+    sender_name?: string;
+    /** File attachments */
+    attachments?: AttachmentInput[];
+};
+/**
+ * Response from the send email endpoint.
+ */
+export type SendEmailResponse = {
+    /** Whether the operation succeeded */
+    status: boolean;
+    /** The generated message ID (UUID) */
+    message_id: string;
+    /** Human-readable status message */
+    message: string;
+};
+/**
+ * Paginated list response for emails.
+ */
+export type EmailListResponse = {
+    /** Array of mail log entries */
+    data: MailLog[];
+    /** Total number of matching emails */
+    total: number;
+    /** Current page number */
+    page: number;
+    /** Number of items per page */
+    limit: number;
+};
+/**
+ * Query parameters for listing emails.
+ */
+export type ListEmailsParams = {
+    /** Filter by email status */
+    status?: EmailStatus;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page (max 100, default 20) */
+    limit?: number;
+};
+/**
+ * Attachment metadata returned by the list attachments endpoint.
+ */
+export type AttachmentMeta = {
+    /** Attachment record UUID */
+    uuid: string;
+    /** Linked message ID */
+    message_id: string;
+    /** File name */
+    file_name: string;
+    /** MIME type */
+    mime_type: string;
+    /** File size in bytes */
+    file_size: number;
+    /** Record creation timestamp */
+    created_at: string;
+};
+/**
+ * Events published by the mail system for workflow triggers.
+ */
+export type MailEventType = "protokol-mail.email.sent" | "protokol-mail.email.failed" | "protokol-mail.email.opened" | "protokol-mail.email.spam_reported";

package/dist/v0.9/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.9/api/index.d.ts

@@ -20,5 +20,6 @@ export { default as Invoicing } from './integrations/invoicing';
 export { default as DMS } from './integrations/dms';
 export { default as SerbiaUtil } from './integrations/serbiaUtil';
 export { default as VPFR } from './integrations/vpfr';
+export { default as Mail } from './integrations/mail';
 import Platfrom from './platform';
 export default Platfrom;

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

@@ -0,0 +1,69 @@
+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"
+ *
+ * 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.
+     *
+     * @param input - The email content and recipients
+     * @returns The queued email's message ID and status
+     */
+    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
+     */
+    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
+     */
+    get(messageId: string): Promise<MailLog>;
+    /**
+     * Resend a previously failed email.
+     *
+     * @param messageId - The UUID of the email to resend
+     * @returns Confirmation with the message ID
+     */
+    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
+     */
+    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
+     */
+    downloadAttachment(messageId: string, attachmentId: string): Promise<ArrayBuffer>;
+}

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

@@ -1,5 +1,6 @@
 import Invoicing from "./integrations/invoicing";
 import DMS from "./integrations/dms";
+import Mail from "./integrations/mail";
 import VPFR from "./integrations/vpfr";
 import IntegrationsBaseClient from "./integrationsBaseClient";
 import Payments from "./integrations/payments";
@@ -15,6 +16,7 @@ export default class Integrations extends IntegrationsBaseClient {
     getDMS(): DMS;
     getVPFR(): VPFR;
     getInvoicing(): Invoicing;
+    getMail(): Mail;
     getPayments(): Payments;
     getMinimax(): Minimax;
     isInstalled(id: string): Promise<boolean>;

package/dist/v0.9/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.9/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>>;

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

@@ -18993,7 +18993,6 @@ const isSandbox = typeof window !== "undefined";
  *
  * @class PlatformBaseClient
  * @extends BaseClient
- * @constructor
  * @param {AxiosInstance} [client] - The axios instance to use for the client
  *
  * @example
@@ -19443,8 +19442,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
@@ -19959,7 +19957,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) {
@@ -20928,6 +20926,92 @@ 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"
+ *
+ * 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", {
@@ -21783,6 +21867,7 @@ class Integrations extends IntegrationsBaseClient {
             '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),
@@ -21800,6 +21885,9 @@ class Integrations extends IntegrationsBaseClient {
     getInvoicing() {
         return this.getInterfaceOf('protokol-invoicing');
     }
+    getMail() {
+        return this.getInterfaceOf('protokol-mail');
+    }
     getPayments() {
         return this.getInterfaceOf('protokol-payments');
     }
@@ -21835,6 +21923,7 @@ exports.Functions = Functions;
 exports.Integration = Integrations;
 exports.Integrations = Integrations;
 exports.Invoicing = Invoicing;
+exports.Mail = Mail;
 exports.Payments = Payments;
 exports.Platform = Platform;
 exports.Project = Project;

package/dist/v0.9/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
@@ -474,8 +473,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 +988,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) {
@@ -1959,6 +1957,92 @@ 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"
+ *
+ * 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", {
@@ -2814,6 +2898,7 @@ class Integrations extends IntegrationsBaseClient {
             '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),
@@ -2831,6 +2916,9 @@ class Integrations extends IntegrationsBaseClient {
     getInvoicing() {
         return this.getInterfaceOf('protokol-invoicing');
     }
+    getMail() {
+        return this.getInterfaceOf('protokol-mail');
+    }
     getPayments() {
         return this.getInterfaceOf('protokol-payments');
     }
@@ -2855,4 +2943,4 @@ class Integrations extends IntegrationsBaseClient {
 // Export all API modules for version 0.9
 // This version has specific method signatures and behaviors for v0.9
 
-export { APIUser, Apps, Component, ComponentUtils, Config, DMS, Forge, Functions, Integrations as Integration, Integrations, Invoicing, Payments, Platform, Project, Ratchet, Sandbox, SerbiaUtil, System, Thunder, Users, VPFR, Workflow, Platform as default };
+export { APIUser, Apps, Component, ComponentUtils, Config, DMS, Forge, Functions, Integrations as Integration, Integrations, Invoicing, Mail, Payments, Platform, Project, Ratchet, Sandbox, SerbiaUtil, System, Thunder, Users, VPFR, Workflow, Platform as default };