@openemail/sdk 0.0.2 → 0.0.4

package/index.js

@@ -6,8 +6,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';
 
@@ -15,6 +27,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 = [
@@ -47,6 +60,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.'
 };
 
@@ -128,7 +142,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 = {
@@ -441,6 +462,8 @@ const QUERY_KEYS = {
     REASSIGN_TO: 'reassignTo',
     SOURCE: 'source',
     ADDRESS: 'address',
+    DIRECTION: 'direction',
+    FILTER: 'filter',
     SEARCH: 'search',
     SORT: 'sort',
     PAGE: 'page',
@@ -462,7 +485,8 @@ const QUERY_KEYS = {
     KEY_IDS: 'keyIds',
     SINCE: 'since',
     UNTIL: 'until',
-    FAILED_ONLY: 'failedOnly'
+    FAILED_ONLY: 'failedOnly',
+    FILENAME: 'filename'
 };
 const LIST_SEPARATOR = ',';
 
@@ -513,6 +537,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'
 };
@@ -551,8 +577,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',
@@ -627,6 +655,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',
@@ -688,7 +718,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',
@@ -1144,7 +1176,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;
@@ -1191,13 +1223,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 {
@@ -1304,6 +1336,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}`;
@@ -1336,6 +1369,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}`;
@@ -1498,6 +1532,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,
@@ -1519,6 +1558,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,
@@ -1767,13 +1821,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,
@@ -1782,10 +1857,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
     })
 });
 
@@ -2744,4 +2846,4 @@ const resolveLanguage = ResolveLanguage;
 const languageByCode = LanguageByCode;
 const isRtlLanguage = IsRtlLanguage;
 
-export { API_SCOPES, BROADCAST_STATUSES, CONTACT_BLOCK_LISTS, CONTACT_PHOTO_TYPES, CONTACT_THREAD_SORTS, ERROR_TYPES, FILE_DIRECTIONS, FILE_KINDS, FILE_SORTS, LANGUAGES, MESSAGE_ENCRYPTION_FORMATS, OpenEmail, OpenEmailApiError, OpenEmailNetworkError, PAGE_LIMITS, PEOPLE_SORTS, PROVIDER_IMPORT_DOMAIN_STATES, PROVIDER_IMPORT_RESOURCES, PROVIDER_IMPORT_STATUSES, RULE_ACTIONS, RULE_FIELDS, RULE_OPERATORS, SUPPRESSION_REASONS, THREAD_SORTS, VERSION, WEBHOOK_EVENTS, WEBHOOK_REPLAY_ERROR_CODES, WEBHOOK_SIGNATURE_HEADERS, createClient, createOpenEmail, createTempMail, OpenEmail as default, getClient, init, isApiKey, isRtlLanguage, isSealed, languageByCode, openemail, resetClient, resolveLanguage, toBase64, verifyWebhookSignature };
+export { API_SCOPES, BROADCAST_RECIPIENT_FILTERS, BROADCAST_STATUSES, CONTACT_BLOCK_LISTS, CONTACT_PHOTO_TYPES, CONTACT_THREAD_SORTS, ERROR_TYPES, FILE_DIRECTIONS, FILE_KINDS, FILE_SORTS, FILE_USAGES, LANGUAGES, MESSAGE_ENCRYPTION_FORMATS, OpenEmail, OpenEmailApiError, OpenEmailNetworkError, PAGE_LIMITS, PEOPLE_SORTS, PROVIDER_IMPORT_DOMAIN_STATES, PROVIDER_IMPORT_RESOURCES, PROVIDER_IMPORT_STATUSES, RULE_ACTIONS, RULE_FIELDS, RULE_OPERATORS, SUPPRESSION_REASONS, THREAD_SORTS, VERSION, WEBHOOK_EVENTS, WEBHOOK_REPLAY_ERROR_CODES, WEBHOOK_SIGNATURE_HEADERS, createClient, createOpenEmail, createTempMail, OpenEmail as default, getClient, init, isApiKey, isRtlLanguage, isSealed, languageByCode, openemail, resetClient, resolveLanguage, toBase64, verifyWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@openemail/sdk",
-    "version": "0.0.2",
+    "version": "0.0.4",
     "author": "OpenEmail",
     "license": "UNLICENSED",
     "description": "The official TypeScript SDK for the OpenEmail API. Send email and broadcasts, work with threads, drafts, labels, templates, rules, webhooks, tracking, contacts, audiences, domains, suppressions, files, API keys, roles, members, mailbox imports and disposable inboxes from code.",