@openemail/sdk 0.0.2 → 0.0.4

package/index.cjs

@@ -10,8 +10,20 @@ const BROADCAST_STATUSES = {
     CANCELLED: 'cancelled',
     FAILED: 'failed'
 };
+const BROADCAST_RECIPIENT_FILTERS = {
+    PENDING: 'pending',
+    SENT: 'sent',
+    DELIVERED: 'delivered',
+    OPENED: 'opened',
+    NOT_OPENED: 'not_opened',
+    CLICKED: 'clicked',
+    BOUNCED: 'bounced',
+    COMPLAINED: 'complained',
+    FAILED: 'failed',
+    UNSUBSCRIBED: 'unsubscribed'
+};
 
-var version = "0.0.2";
+var version = "0.0.4";
 
 const BUILD_BASE_URL = 'https://api.openemail.uk';
 
@@ -19,6 +31,7 @@ const DEFAULTS = {
     BASE_URL: BUILD_BASE_URL,
     MAX_RETRIES: 2,
     TIMEOUT_MS: 30_000,
+    UPLOAD_TIMEOUT_MS: 600_000,
     USER_AGENT: `openemail-sdk/${version}`
 };
 const BROWSER_REFUSAL = [
@@ -51,6 +64,7 @@ const CLIENT_MESSAGES = {
     BASE_URL_SHAPE: 'is not a usable base URL. Pass an origin such as "https://api.openemail.uk", or the http origin of a server you run yourself.',
     NO_FETCH: 'No global fetch is available. Pass one as { fetch }, or run on Node 20+, Bun, Deno, Cloudflare Workers or a browser.',
     EMPTY_SEGMENT: 'An id must not be empty.',
+    FILENAME_REQUIRED: 'A file name is required. Pass it as { filename }, the name the file is stored and downloaded under.',
     DOT_SEGMENT: 'is not a usable id: a path segment made only of dots is removed by URL parsers, so the request would reach a different endpoint.'
 };
 
@@ -132,7 +146,14 @@ const FILE_KINDS = {
 };
 const FILE_DIRECTIONS = {
     INBOUND: 'inbound',
-    OUTBOUND: 'outbound'
+    OUTBOUND: 'outbound',
+    UPLOADED: 'uploaded'
+};
+const FILE_USAGES = {
+    RECEIVED: 'received',
+    SENT: 'sent',
+    LINKED: 'linked',
+    SCHEDULED: 'scheduled'
 };
 
 const HTTP_METHODS = {
@@ -445,6 +466,8 @@ const QUERY_KEYS = {
     REASSIGN_TO: 'reassignTo',
     SOURCE: 'source',
     ADDRESS: 'address',
+    DIRECTION: 'direction',
+    FILTER: 'filter',
     SEARCH: 'search',
     SORT: 'sort',
     PAGE: 'page',
@@ -466,7 +489,8 @@ const QUERY_KEYS = {
     KEY_IDS: 'keyIds',
     SINCE: 'since',
     UNTIL: 'until',
-    FAILED_ONLY: 'failedOnly'
+    FAILED_ONLY: 'failedOnly',
+    FILENAME: 'filename'
 };
 const LIST_SEPARATOR = ',';
 
@@ -517,6 +541,8 @@ const PATHS = {
     MEMBERS_INVITATIONS: '/members/invitations',
     SUPPRESSIONS: '/suppressions',
     FILES: '/files',
+    FILES_STATS: '/files/stats',
+    FILES_BATCH_DELETE: '/files/batch-delete',
     TEMP_MAIL_DOMAINS: '/temp-mail/domains',
     TEMP_MAIL_INBOXES: '/temp-mail/inboxes'
 };
@@ -555,8 +581,10 @@ const SEGMENTS = {
     REVOKE: 'revoke',
     ROTATE: 'rotate',
     ROTATE_SECRET: 'rotate-secret',
+    RECIPIENTS: 'recipients',
     SEND: 'send',
     SENDS: 'sends',
+    STATS: 'stats',
     SNOOZE: 'snooze',
     START: 'start',
     TEST: 'test',
@@ -631,6 +659,8 @@ const API_SCOPES = {
     DRAFTS_WRITE: 'drafts:write',
     THREADS_READ: 'threads:read',
     THREADS_WRITE: 'threads:write',
+    FILES_READ: 'files:read',
+    FILES_WRITE: 'files:write',
     LABELS_READ: 'labels:read',
     LABELS_WRITE: 'labels:write',
     CONTACTS_READ: 'contacts:read',
@@ -692,7 +722,9 @@ const WEBHOOK_EVENTS = {
     DOMAIN_SENDING_CHANGED: 'domain.sending_changed',
     DOMAIN_DELETED: 'domain.deleted',
     SUPPRESSION_ADDED: 'suppression.added',
-    SUPPRESSION_REMOVED: 'suppression.removed'
+    SUPPRESSION_REMOVED: 'suppression.removed',
+    FILE_UPLOADED: 'file.uploaded',
+    FILE_DELETED: 'file.deleted'
 };
 const WEBHOOK_REPLAY_ERROR_CODES = {
     RESOURCE_NOT_FOUND: 'resource_not_found',
@@ -1148,7 +1180,7 @@ class Transport {
         const repeatable = options.repeatable ?? RETRYABLE_METHODS.has(method);
         let attempt = 0;
         for (;;) {
-            const outcome = await this.attempt(url, method, headers, body, options.signal, options.binary === true);
+            const outcome = await this.attempt(url, method, headers, body, options.signal, options.binary === true, options.timeoutMs ?? this.timeoutMs);
             if (outcome instanceof OpenEmailNetworkError) {
                 if (options.signal?.aborted || !repeatable || attempt >= this.maxRetries)
                     throw outcome;
@@ -1195,13 +1227,13 @@ class Transport {
             headers[HEADER_KEYS.IDEMPOTENCY_KEY] = options.idempotencyKey ?? IdempotencyKey();
         return headers;
     }
-    async attempt(url, method, headers, body, signal, binary) {
-        const deadline = Deadline(this.timeoutMs, signal);
+    async attempt(url, method, headers, body, signal, binary, timeoutMs) {
+        const deadline = Deadline(timeoutMs, signal);
         const Failure = (error, fallback) => {
             if (signal?.aborted)
                 return new OpenEmailNetworkError('Request aborted by the caller.', error);
             if (deadline.timedOut())
-                return new OpenEmailNetworkError(`Request timed out after ${this.timeoutMs}ms.`, error, true);
+                return new OpenEmailNetworkError(`Request timed out after ${timeoutMs}ms.`, error, true);
             return new OpenEmailNetworkError(`${fallback}: ${Describe(error)}`, error);
         };
         try {
@@ -1308,6 +1340,7 @@ const AudienceContactsChildPath = (id, segment) => `${AudienceContactsPath(id)}/
 const AudienceContactPath = (id, email) => `${AudienceContactsPath(id)}/${Segment(email)}`;
 const BroadcastPath = (id) => `${PATHS.BROADCASTS}/${Segment(id)}`;
 const BroadcastChildPath = (id, segment) => `${BroadcastPath(id)}/${segment}`;
+const BroadcastRecipientPath = (id, emailId) => `${BroadcastChildPath(id, SEGMENTS.RECIPIENTS)}/${Segment(emailId)}`;
 const DomainPath = (id) => `${PATHS.DOMAINS}/${Segment(id)}`;
 const WebhookPath = (id) => `${PATHS.WEBHOOKS}/${Segment(id)}`;
 const WebhookChildPath = (id, segment) => `${WebhookPath(id)}/${segment}`;
@@ -1340,6 +1373,7 @@ const MemberInvitationResendPath = (id) => `${MemberInvitationPath(id)}/${SEGMEN
 const SuppressionPath = (id) => `${PATHS.SUPPRESSIONS}/${Segment(id)}`;
 const FilePath = (id) => `${PATHS.FILES}/${Segment(id)}`;
 const FileChildPath = (id, segment) => `${FilePath(id)}/${segment}`;
+const FileLinkPath = (id, linkId) => `${FileChildPath(id, SEGMENTS.LINKS)}/${Segment(linkId)}`;
 const TempInboxPath = (id) => `${PATHS.TEMP_MAIL_INBOXES}/${Segment(id)}`;
 const TempInboxExtendPath = (id) => `${TempInboxPath(id)}/${SEGMENTS.EXTEND}`;
 const TempMessagesPath = (id) => `${TempInboxPath(id)}/${SEGMENTS.MESSAGES}`;
@@ -1502,6 +1536,11 @@ const ToInstant = Instant;
 const ListQuery$a = (options) => ({
     [QUERY_KEYS.AUDIENCE_ID]: options.audienceId
 });
+const RecipientQuery = (options) => ({
+    [QUERY_KEYS.FILTER]: options.filter,
+    [QUERY_KEYS.Q]: options.q
+});
+const RecipientsPath = (id) => BroadcastChildPath(id, SEGMENTS.RECIPIENTS);
 const Broadcasts = (transport) => ({
     preview: (body, options = {}) => transport.request(PATHS.BROADCASTS_PREVIEW, {
         method: HTTP_METHODS.POST,
@@ -1523,6 +1562,21 @@ const Broadcasts = (transport) => ({
     listAll: (options = {}) => CollectAll(transport, PATHS.BROADCASTS, CURSOR_STYLES.CURSOR, options, ListQuery$a(options)),
     iterate: (options = {}) => IteratePages(transport, PATHS.BROADCASTS, CURSOR_STYLES.CURSOR, options, ListQuery$a(options)),
     get: (id, options = {}) => transport.request(BroadcastPath(id), { signal: options.signal, apiKey: options.apiKey }),
+    listRecipients: (id, options = {}) => FetchPage(transport, RecipientsPath(id), CURSOR_STYLES.CURSOR, options, RecipientQuery(options)),
+    listAllRecipients: (id, options = {}) => CollectAll(transport, RecipientsPath(id), CURSOR_STYLES.CURSOR, options, RecipientQuery(options)),
+    iterateRecipients: (id, options = {}) => IteratePages(transport, RecipientsPath(id), CURSOR_STYLES.CURSOR, options, RecipientQuery(options)),
+    getRecipient: (id, emailId, options = {}) => transport.request(BroadcastRecipientPath(id, emailId), {
+        signal: options.signal,
+        apiKey: options.apiKey
+    }),
+    stats: (id, options = {}) => transport.request(BroadcastChildPath(id, SEGMENTS.STATS), {
+        query: {
+            [QUERY_KEYS.GRAIN]: options.grain,
+            [QUERY_KEYS.OFFSET_MINUTES]: options.offsetMinutes
+        },
+        signal: options.signal,
+        apiKey: options.apiKey
+    }),
     cancel: (id, options = {}) => transport.request(BroadcastChildPath(id, SEGMENTS.CANCEL), {
         method: HTTP_METHODS.POST,
         repeatable: true,
@@ -1771,13 +1825,34 @@ const Emails = (transport) => ({
 const ListQuery$6 = (options) => ({
     [QUERY_KEYS.Q]: options.q,
     [QUERY_KEYS.KIND]: options.kind,
+    [QUERY_KEYS.DIRECTION]: options.direction,
+    [QUERY_KEYS.ADDRESS]: options.address,
+    [QUERY_KEYS.SINCE]: ToInstant(options.since),
+    [QUERY_KEYS.UNTIL]: ToInstant(options.until),
     [QUERY_KEYS.SORT]: options.sort
 });
+const UploadName = (options) => {
+    const filename = typeof options?.filename === 'string' ? options.filename.trim() : '';
+    if (!filename)
+        throw new Error(CLIENT_MESSAGES.FILENAME_REQUIRED);
+    return filename;
+};
+const UploadType = (data, options) => {
+    if (options.contentType)
+        return options.contentType;
+    return typeof Blob !== 'undefined' && data instanceof Blob && data.type ? data.type : undefined;
+};
+const UploadTimeout = (transport, options) => {
+    if (options.timeoutMs !== undefined)
+        return options.timeoutMs;
+    return transport.timeoutMs > 0 ? Math.max(transport.timeoutMs, DEFAULTS.UPLOAD_TIMEOUT_MS) : transport.timeoutMs;
+};
 const Files = (transport) => ({
     list: (options = {}) => FetchPage(transport, PATHS.FILES, CURSOR_STYLES.CURSOR, options, ListQuery$6(options)),
     listAll: (options = {}) => CollectAll(transport, PATHS.FILES, CURSOR_STYLES.CURSOR, options, ListQuery$6(options)),
     iterate: (options = {}) => IteratePages(transport, PATHS.FILES, CURSOR_STYLES.CURSOR, options, ListQuery$6(options)),
     get: (id, options = {}) => transport.request(FilePath(id), { signal: options.signal, apiKey: options.apiKey }),
+    stats: (options = {}) => transport.request(PATHS.FILES_STATS, { signal: options.signal, apiKey: options.apiKey }),
     download: (id, options = {}) => transport.request(FileChildPath(id, SEGMENTS.CONTENT), {
         binary: true,
         signal: options.signal,
@@ -1786,10 +1861,37 @@ const Files = (transport) => ({
     listLinks: (id, options = {}) => FetchPage(transport, FileChildPath(id, SEGMENTS.LINKS), CURSOR_STYLES.CURSOR, options),
     listAllLinks: (id, options = {}) => CollectAll(transport, FileChildPath(id, SEGMENTS.LINKS), CURSOR_STYLES.CURSOR, options),
     iterateLinks: (id, options = {}) => IteratePages(transport, FileChildPath(id, SEGMENTS.LINKS), CURSOR_STYLES.CURSOR, options),
+    createLink: (id, options = {}) => transport.request(FileChildPath(id, SEGMENTS.LINKS), {
+        method: HTTP_METHODS.POST,
+        body: options.domain ? { domain: options.domain } : {},
+        signal: options.signal,
+        apiKey: options.apiKey
+    }),
+    revokeLink: (id, linkId, options = {}) => transport.request(FileLinkPath(id, linkId), {
+        method: HTTP_METHODS.DELETE,
+        repeatable: true,
+        signal: options.signal,
+        apiKey: options.apiKey
+    }),
+    upload: (data, options) => transport.request(PATHS.FILES, {
+        method: HTTP_METHODS.POST,
+        query: { [QUERY_KEYS.FILENAME]: UploadName(options) },
+        raw: data,
+        contentType: UploadType(data, options),
+        timeoutMs: UploadTimeout(transport, options),
+        signal: options.signal,
+        apiKey: options.apiKey
+    }),
     delete: (id, options = {}) => transport.request(FilePath(id), {
         method: HTTP_METHODS.DELETE,
         signal: options.signal,
         apiKey: options.apiKey
+    }),
+    deleteMany: (ids, options = {}) => transport.request(PATHS.FILES_BATCH_DELETE, {
+        method: HTTP_METHODS.POST,
+        body: { ids },
+        signal: options.signal,
+        apiKey: options.apiKey
     })
 });
 
@@ -2749,6 +2851,7 @@ const languageByCode = LanguageByCode;
 const isRtlLanguage = IsRtlLanguage;
 
 exports.API_SCOPES = API_SCOPES;
+exports.BROADCAST_RECIPIENT_FILTERS = BROADCAST_RECIPIENT_FILTERS;
 exports.BROADCAST_STATUSES = BROADCAST_STATUSES;
 exports.CONTACT_BLOCK_LISTS = CONTACT_BLOCK_LISTS;
 exports.CONTACT_PHOTO_TYPES = CONTACT_PHOTO_TYPES;
@@ -2757,6 +2860,7 @@ exports.ERROR_TYPES = ERROR_TYPES;
 exports.FILE_DIRECTIONS = FILE_DIRECTIONS;
 exports.FILE_KINDS = FILE_KINDS;
 exports.FILE_SORTS = FILE_SORTS;
+exports.FILE_USAGES = FILE_USAGES;
 exports.LANGUAGES = LANGUAGES;
 exports.MESSAGE_ENCRYPTION_FORMATS = MESSAGE_ENCRYPTION_FORMATS;
 exports.OpenEmail = OpenEmail;