@mailiy/sdk 0.2.0 → 0.5.0

package/dist/mailiy.d.ts

@@ -70,10 +70,140 @@ export interface MailiyForm {
     max_submissions: number;
     /** Field names, one per line; a submission missing one gets missing_fields. */
     required_fields: string;
+    /** A submission whose field has the value goes to these addresses instead of recipients. */
+    recipient_rules: MailiyRecipientRule[];
+    /** Fields of the hosted page; empty until set. */
+    fields: MailiyFormField[];
+    /** 1: the form has a public page at hosted_url. */
+    hosted: number;
+    hosted_url: string;
+    hosted_intro: string;
+    /** 1: the page keeps unsent answers in the visitor's browser. */
+    hosted_save: number;
+    /** Shown after sending on the hosted page; empty: a default text. */
+    success_message: string;
+    /**
+     * Field whose amount the visitor pays through Stripe after sending; empty: no payment.
+     * The owner gets the mail once paid, or after 24 hours marked as payment open.
+     */
+    payment_field: string;
+    currency: MailiyCurrency;
+    /** Statuses, roles and actions; forms without their own get open, in_progress and done. */
+    workflow: MailiyWorkflow;
     created_at: number;
     submissions?: number;
     delivered?: number;
 }
+/** Compared without case; the address must be a verified email of the account. */
+export interface MailiyRecipientRule {
+    field: string;
+    value: string;
+    to: string;
+}
+export type MailiyFieldType = "text" | "email" | "tel" | "url" | "number" | "currency" | "date" | "time" | "textarea" | "select" | "radio" | "checkbox" | "checkboxes" | "file" | "name" | "address" | "rating" | "signature" | "lookup" | "person" | "price" | "calculation" | "content" | "section" | "pagebreak" | "repeating" | "table";
+export type MailiyCurrency = "EUR" | "CHF" | "GBP" | "USD";
+/** Rules compare the answer of another field of the same form. */
+export interface MailiyCondition {
+    match: "all" | "any";
+    rules: {
+        field: string;
+        op: "equals" | "not_equals" | "contains" | "empty" | "not_empty" | "greater" | "less";
+        value?: string;
+    }[];
+}
+/**
+ * `name` is the key in the submission. `options` holds the choices of select, radio and
+ * checkboxes, the questions of a rating and the people of a person field as "Name <email>"
+ * lines (the page shows only the names).
+ */
+export interface MailiyFormField {
+    name: string;
+    label: string;
+    type: MailiyFieldType;
+    required?: boolean;
+    options?: string[];
+    placeholder?: string;
+    help?: string;
+    default?: string;
+    /** Length for text, value for number and currency, rows for repeating and table. */
+    min?: number;
+    max?: number;
+    width?: 25 | 33 | 50 | 67 | 75 | 100;
+    /** Highest score of a rating, 3 to 10. */
+    scale?: number;
+    /** Price per option of select, radio and checkboxes. */
+    prices?: number[];
+    /** Fixed amount of a price field or a checkbox. */
+    price?: number;
+    /** Calculation, e.g. "{rooms} * 80 + {fee}". */
+    formula?: string;
+    /** Choices taken from the answers to a field of another form of the same account. */
+    lookup?: {
+        form: string;
+        field: string;
+    };
+    show_when?: MailiyCondition;
+    require_when?: MailiyCondition;
+    /** Columns of repeating and table, up to 10 simple fields. */
+    fields?: MailiyFormField[];
+}
+/** A status id from the form's workflow; the default workflow has open, in_progress and done. */
+export type MailiySubmissionStatus = string;
+export type MailiyWorkflowColor = "gray" | "blue" | "green" | "yellow" | "orange" | "red" | "purple";
+/**
+ * Ids match ^[a-z][a-z0-9_]{0,31}$ and may not be all, delivered, spam or unread.
+ * x and y place the node on the dashboard canvas.
+ */
+export interface MailiyWorkflowStatus {
+    id: string;
+    /** 1 to 365: the owner gets one mail when a submission sits this many days in the status. */
+    remind_days?: number;
+    name: string;
+    color: MailiyWorkflowColor;
+    x: number;
+    y: number;
+}
+/** Someone outside the team who runs actions through an emailed link (valid 30 days). */
+export interface MailiyWorkflowRole {
+    id: string;
+    name: string;
+    /** A fixed address or `field:<name>` of an email or person field. */
+    email: string;
+}
+export interface MailiyWorkflowEmail {
+    /** A fixed address or `field:<name>`. */
+    to: string;
+    /** Subject and body take {field:name} placeholders. */
+    subject: string;
+    body: string;
+    /** Role whose action link goes into the mail; "" for none. */
+    link_role: string;
+}
+export interface MailiyWorkflowAction {
+    id: string;
+    /** Button text. */
+    name: string;
+    /** Statuses in which the action is offered; empty: every status. */
+    from: string[];
+    /** Roles that may run it by link; the team may run every action. */
+    roles: string[];
+    /** New status; "" keeps the current one. */
+    to: string;
+    /** Up to 5. */
+    emails: MailiyWorkflowEmail[];
+    /** Sends the run to the website's integrations. */
+    integrations: boolean;
+    /** Answers deleted for good when the action runs. */
+    clear_fields: string[];
+    x: number;
+    y: number;
+}
+/** Up to 12 statuses (new submissions get the first), 10 roles and 20 actions. */
+export interface MailiyWorkflow {
+    statuses: MailiyWorkflowStatus[];
+    roles: MailiyWorkflowRole[];
+    actions: MailiyWorkflowAction[];
+}
 export interface MailiySubmission {
     id: string;
     form_id: string;
@@ -89,15 +219,47 @@ export interface MailiySubmission {
         type: string;
         url: string;
     }[];
+    read: boolean;
     spam: boolean;
+    status: MailiySubmissionStatus;
+    /** User id of the person who takes care of it (see listAssignees); null: nobody. */
+    assignee_id: string | null;
+    /** Set when the hosted form asked for a payment; paid once Stripe confirms it, refunded once paid back in full. */
+    payment_status: "" | "pending" | "paid" | "refunded";
+    /** In cents of the form's currency. */
+    payment_amount: number;
+    /** Cents paid back so far through Mailiy. */
+    payment_refunded: number;
+}
+/** One line of a submission's history; the fields after kind depend on it. */
+export interface MailiyHistoryEntry {
+    /** Email of the person; null for the arrival, a workflow link (see role) or a deleted account. */
+    actor: string | null;
+    created_at: number;
+    kind: "action" | "assign" | "created" | "forward" | "refund" | "status";
+    /** action: name of the workflow action. */
+    action?: string;
+    /** refund: in cents. */
+    amount?: number;
+    /** assign: user id, null for nobody. */
+    assignee?: string | null;
+    /** action through a workflow link: name of the role. */
+    role?: string;
+    /** action and status: the new status id. */
+    status?: string;
+    /** forward: recipient address. */
+    to?: string;
 }
 export interface MailiySubmissionFilter {
+    /** A user id from listAssignees, or "me" for the signed-in person (with an API key: the account owner). */
+    assignee?: string;
     /** next_cursor of the previous result: opens the next block of 1000 older submissions. */
     cursor?: string;
     form?: string;
     page?: number;
     q?: string;
-    status?: "delivered" | "spam";
+    /** A workflow status id or unread only lists delivered submissions. */
+    status?: "delivered" | "spam" | "unread" | MailiySubmissionStatus;
 }
 export interface MailiySubmissionPage {
     keys: string[];
@@ -200,12 +362,26 @@ export type MailiyFormPatch = Partial<{
     /** Placeholders: {fields}, {intro}, {form}, {field:name}. */
     email_html: string;
     email_template: EmailTemplate;
+    /** Up to 50 fields with unique names. */
+    fields: MailiyFormField[];
     from_name: string;
     group_emails: boolean;
+    hosted: boolean;
+    hosted_intro: string;
+    /** Keep unsent answers in the visitor's browser (localStorage) until they send. */
+    hosted_save: boolean;
     intro_text: string;
     max_submissions: number;
     name: string;
     opens_at: number | null;
+    /**
+     * Name of a price, calculation or currency field, else invalid_payment_field.
+     * Amounts under 0.50 (GBP 0.30) fail on submit with 422 amount_too_low.
+     */
+    payment_field: string;
+    currency: MailiyCurrency;
+    /** Up to 20 rules. */
+    recipient_rules: MailiyRecipientRule[];
     recipients: string[];
     redirect_url: string;
     require_consent: boolean;
@@ -217,7 +393,13 @@ export type MailiyFormPatch = Partial<{
     server_requires_key: boolean;
     spam_filter: SpamFilter;
     subject: string;
+    success_message: string;
     website: string;
+    /**
+     * Replaces the workflow, else invalid_workflow (unknown or duplicate ids, missing references,
+     * limits). Submissions in a removed status move to the first status.
+     */
+    workflow: MailiyWorkflow;
 }>;
 export interface MailiyOptions {
     /** Personal API key from Dashboard → Account → API keys (starts with mk_). */
@@ -237,7 +419,9 @@ export declare class MailiyError extends Error {
     name: string;
     readonly code: string;
     readonly status: number;
-    constructor(code: string, status: number);
+    /** With missing_fields: the required fields that were missing or empty. */
+    readonly fields: string[] | undefined;
+    constructor(code: string, status: number, fields?: string[]);
 }
 export declare const DEFAULT_BASE_URL = "https://mailiy.com";
 export declare const createMailiy: (options?: MailiyOptions) => {
@@ -271,6 +455,10 @@ export declare const createMailiy: (options?: MailiyOptions) => {
     deleteSubmission: (formId: string, submissionId: string) => Promise<{
         ok: true;
     }>;
+    /** Deletes up to 500 submissions of any forms in the account; ids from elsewhere are skipped. */
+    deleteSubmissions: (ids: string[]) => Promise<{
+        deleted: number;
+    }>;
     /** Deletes the website with all its forms and stored submissions. */
     deleteWebsite: (id: string) => Promise<{
         ok: true;
@@ -280,10 +468,25 @@ export declare const createMailiy: (options?: MailiyOptions) => {
         id: string;
         name: string;
     }>;
+    /** Mails the answers and file links to any address; the reply-to is your own. Up to 20 per hour. */
+    forwardSubmission: (submissionId: string, to: string, note?: string) => Promise<{
+        ok: true;
+    }>;
     getForm: (id: string) => Promise<MailiyForm>;
     /** Public service health, cached for 30 seconds. */
     getStatus: () => Promise<MailiyStatus>;
+    /** Who changed the status, assigned, ran actions, forwarded or refunded, newest first; the last entry is the arrival. */
+    getSubmissionHistory: (submissionId: string) => Promise<MailiyHistoryEntry[]>;
     getWebsite: (id: string) => Promise<MailiyWebsite>;
+    /** Adds old submissions from CSV text (first line the field names, up to 5000 rows and 1 MB); they arrive read and send no mails. */
+    importSubmissions: (formId: string, csv: string) => Promise<{
+        imported: number;
+    }>;
+    /** The owner and the members (not clients) a submission can be assigned to. */
+    listAssignees: () => Promise<{
+        email: string;
+        id: string;
+    }[]>;
     /** The newest 50 deliveries of an integration. */
     listDeliveries: (id: string) => Promise<MailiyDelivery[]>;
     listForms: (websiteId?: string) => Promise<MailiyForm[]>;
@@ -305,12 +508,30 @@ export declare const createMailiy: (options?: MailiyOptions) => {
     previewEmail: (id: string, patch?: MailiyFormPatch) => Promise<MailiyRenderedEmail & {
         autoresponder: MailiyRenderedEmail | null;
     }>;
+    /**
+     * Pays back a paid form payment through the connected Stripe account, in cents; without an amount the
+     * whole open rest. not_refundable (409) when nothing is left or the payment predates refunds in Mailiy.
+     */
+    refundSubmission: (submissionId: string, amount?: number) => Promise<{
+        id: string;
+        payment_refunded: number;
+        payment_status: "paid" | "refunded";
+    }>;
     /** Sends a failed delivery once more, as long as its payload is still stored. */
     retryDelivery: (id: string) => Promise<MailiyDelivery>;
     /** Replaces the access key; the old one stops working at once. Submissions move to the new id. */
     rotateAccessKey: (id: string) => Promise<{
         id: string;
     }>;
+    /**
+     * Runs a workflow action on a submission: clears fields, sets the status, sends the emails and
+     * notifies integrations. not_found for an unknown submission or action, action_not_allowed (409)
+     * when the action does not start from the current status.
+     */
+    runAction: (submissionId: string, actionId: string) => Promise<{
+        id: string;
+        status: MailiySubmissionStatus;
+    }>;
     /** Submissions of all forms in the account (or one website), 25 per page, newest first, in blocks of 1000 (see cursor). */
     searchSubmissions: (filter?: MailiySubmissionFilter & {
         website?: string;
@@ -320,6 +541,14 @@ export declare const createMailiy: (options?: MailiyOptions) => {
     sendTest: (id: string) => Promise<{
         ok: true;
     }>;
+    /** Sets the status, the read mark or the assignee (null: nobody) of up to 500 submissions; ids from elsewhere are skipped. */
+    setSubmissions: (ids: string[], patch: {
+        assignee?: string | null;
+        read?: boolean;
+        status?: MailiySubmissionStatus;
+    }) => Promise<{
+        updated: number;
+    }>;
     /** Delivered and spam counts per day (7d, 30d) or month (12m), for the account or one website. */
     stats: (range?: "7d" | "30d" | "12m", website?: string) => Promise<MailiyStats>;
     /**

package/dist/mailiy.js

@@ -10,10 +10,15 @@ export class MailiyError extends Error {
     name = "MailiyError";
     code;
     status;
-    constructor(code, status) {
-        super(`Mailiy API error ${status}: ${code}`);
+    /** With missing_fields: the required fields that were missing or empty. */
+    fields;
+    constructor(code, status, fields) {
+        super(fields
+            ? `Mailiy API error ${status}: ${code} (${fields.join(", ")})`
+            : `Mailiy API error ${status}: ${code}`);
         this.code = code;
         this.status = status;
+        this.fields = fields;
     }
 }
 const form = (id) => `/forms/${encodeURIComponent(id)}`;
@@ -41,7 +46,7 @@ export const createMailiy = (options = {}) => {
         });
         const json = (await res.json().catch(() => ({})));
         if (!res.ok) {
-            throw new MailiyError(json.error ?? json.code ?? res.statusText, res.status);
+            throw new MailiyError(json.error ?? json.code ?? res.statusText, res.status, json.fields);
         }
         return { headers: res.headers, json };
     };
@@ -70,14 +75,24 @@ export const createMailiy = (options = {}) => {
         deleteForm: (id) => call(form(id), "DELETE"),
         deleteIntegration: (id) => call(integration(id), "DELETE"),
         deleteSubmission: (formId, submissionId) => call(`${form(formId)}/submissions/${encodeURIComponent(submissionId)}`, "DELETE"),
+        /** Deletes up to 500 submissions of any forms in the account; ids from elsewhere are skipped. */
+        deleteSubmissions: (ids) => call("/submissions/delete", "POST", { ids }),
         /** Deletes the website with all its forms and stored submissions. */
         deleteWebsite: (id) => call(site(id), "DELETE"),
         /** Copies a form with all settings under a new access key. */
         duplicateForm: (id, name) => call(`${form(id)}/duplicate`, "POST", name === undefined ? {} : { name }),
+        /** Mails the answers and file links to any address; the reply-to is your own. Up to 20 per hour. */
+        forwardSubmission: (submissionId, to, note = "") => call(`/submissions/${encodeURIComponent(submissionId)}/forward`, "POST", { note, to }),
         getForm: (id) => call(form(id)),
         /** Public service health, cached for 30 seconds. */
         getStatus: () => call("/status"),
+        /** Who changed the status, assigned, ran actions, forwarded or refunded, newest first; the last entry is the arrival. */
+        getSubmissionHistory: (submissionId) => call(`/submissions/${encodeURIComponent(submissionId)}/history`),
         getWebsite: (id) => call(site(id)),
+        /** Adds old submissions from CSV text (first line the field names, up to 5000 rows and 1 MB); they arrive read and send no mails. */
+        importSubmissions: (formId, csv) => call(`${form(formId)}/import`, "POST", { csv }),
+        /** The owner and the members (not clients) a submission can be assigned to. */
+        listAssignees: () => call("/assignees"),
         /** The newest 50 deliveries of an integration. */
         listDeliveries: (id) => call(`${integration(id)}/deliveries`),
         listForms: (websiteId) => call(websiteId ? `/forms?website=${encodeURIComponent(websiteId)}` : "/forms"),
@@ -95,15 +110,28 @@ export const createMailiy = (options = {}) => {
         pageSubmissions,
         /** Renders the notification and auto-reply with sample data; patch fields override the saved ones. */
         previewEmail: (id, patch = {}) => call(`${form(id)}/preview`, "POST", patch),
+        /**
+         * Pays back a paid form payment through the connected Stripe account, in cents; without an amount the
+         * whole open rest. not_refundable (409) when nothing is left or the payment predates refunds in Mailiy.
+         */
+        refundSubmission: (submissionId, amount) => call(`/submissions/${encodeURIComponent(submissionId)}/refund`, "POST", amount === undefined ? {} : { amount }),
         /** Sends a failed delivery once more, as long as its payload is still stored. */
         retryDelivery: (id) => call(`/deliveries/${encodeURIComponent(id)}/retry`, "POST"),
         /** Replaces the access key; the old one stops working at once. Submissions move to the new id. */
         rotateAccessKey: (id) => call(`${form(id)}/rotate-key`, "POST"),
+        /**
+         * Runs a workflow action on a submission: clears fields, sets the status, sends the emails and
+         * notifies integrations. not_found for an unknown submission or action, action_not_allowed (409)
+         * when the action does not start from the current status.
+         */
+        runAction: (submissionId, actionId) => call(`/submissions/${encodeURIComponent(submissionId)}/actions/${encodeURIComponent(actionId)}`, "POST"),
         /** Submissions of all forms in the account (or one website), 25 per page, newest first, in blocks of 1000 (see cursor). */
         searchSubmissions: (filter = {}) => call(`/submissions?${query(filter)}`),
         /** Submissions of all forms in a website, 25 per page, newest first, in blocks of 1000 (see cursor). */
         searchWebsiteSubmissions: (id, filter = {}) => call(`${site(id)}/submissions?${query(filter)}`),
         sendTest: (id) => call(`${form(id)}/test`, "POST"),
+        /** Sets the status, the read mark or the assignee (null: nobody) of up to 500 submissions; ids from elsewhere are skipped. */
+        setSubmissions: (ids, patch) => call("/submissions", "PATCH", { ids, ...patch }),
         /** Delivered and spam counts per day (7d, 30d) or month (12m), for the account or one website. */
         stats: (range = "30d", website) => call(`/stats?${query({ range, website })}`),
         /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailiy/sdk",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Typed, dependency-free client for the Mailiy REST API.",
   "keywords": [
     "api-client",