@sendora/sdk 1.1.0 → 1.2.0

package/src/inbound.ts

@@ -0,0 +1,135 @@
+import { paginate } from './pagination.ts';
+import type { Transport } from './transport.ts';
+import type {
+  InboundMessage,
+  InboundMessageDetail,
+  InboundPage,
+  InboundSearch,
+  InboundSearchBody,
+  RequestOptions,
+} from './types.ts';
+
+/** The mail the token's server has received on its inbound stream. */
+export class InboundResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * One received message: its envelope, parties, headers, text and HTML,
+   * and its attachments described. The attachment bytes and the raw
+   * message are downloads of their own. Once the stream's content window
+   * has passed, `contentAvailable` is false and the content fields are
+   * null.
+   *
+   * @example
+   * const message = await sendora.inbound.get(inboundMessageId);
+   * console.log(message.from?.address, message.subject, message.text);
+   */
+  get(inboundMessageId: string, options: RequestOptions = {}): Promise<InboundMessageDetail> {
+    return this.#transport.request<InboundMessageDetail>({
+      method: 'GET',
+      path: `/v1/inbound/${encodeURIComponent(inboundMessageId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * One page of received messages, newest first. Every filter is
+   * optional; pass the page's `next` as `after` for the following page,
+   * or use `searchAll`.
+   *
+   * @example
+   * const page = await sendora.inbound.search({ from: 'anna@example.com', limit: 20 });
+   */
+  search(search: InboundSearch = {}, options: RequestOptions = {}): Promise<InboundPage> {
+    return this.#transport.request<InboundPage>({
+      method: 'POST',
+      path: '/v1/inbound/search',
+      body: encodeInboundSearch(search),
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Every received message the filters match, page by page, for `for await`.
+   *
+   * @example
+   * for await (const message of sendora.inbound.searchAll({ recipient: address })) {
+   *   console.log(message.receivedAt, message.subject);
+   * }
+   */
+  searchAll(
+    search: InboundSearch = {},
+    options: RequestOptions = {},
+  ): AsyncIterable<InboundMessage> {
+    return paginate(
+      (after) => this.search({ ...search, after }, options),
+      (page) => page.messages,
+      (page) => page.next,
+      search.after,
+    );
+  }
+
+  /**
+   * The message byte for byte as it was received, as `message/rfc822`.
+   * Throws `content_expired` once the stream's content window has passed.
+   *
+   * @example
+   * const raw = await sendora.inbound.raw(inboundMessageId);
+   * await writeFile(`${inboundMessageId}.eml`, raw);
+   */
+  raw(inboundMessageId: string, options: RequestOptions = {}): Promise<Uint8Array> {
+    return this.#transport.requestBytes({
+      method: 'GET',
+      path: `/v1/inbound/${encodeURIComponent(inboundMessageId)}/raw`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * An attachment's bytes, whatever the sender declared them to be; the
+   * name and the declared type are on the message. Throws
+   * `content_expired` once the stream's content window has passed.
+   *
+   * @example
+   * const message = await sendora.inbound.get(inboundMessageId);
+   * for (const attachment of message.attachments) {
+   *   const bytes = await sendora.inbound.attachment(inboundMessageId, attachment.attachmentId);
+   * }
+   */
+  attachment(
+    inboundMessageId: string,
+    attachmentId: string,
+    options: RequestOptions = {},
+  ): Promise<Uint8Array> {
+    return this.#transport.requestBytes({
+      method: 'GET',
+      path: `/v1/inbound/${encodeURIComponent(inboundMessageId)}/attachments/${encodeURIComponent(attachmentId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}
+
+/** The body as the API takes it: times as ISO 8601 strings. */
+export function encodeInboundSearch(search: InboundSearch): InboundSearchBody {
+  const { receivedFrom, receivedTo, ...fields } = search;
+  const body: InboundSearchBody = { ...fields };
+  if (receivedFrom !== undefined) {
+    body.receivedFrom = isoOf(receivedFrom);
+  }
+  if (receivedTo !== undefined) {
+    body.receivedTo = isoOf(receivedTo);
+  }
+  return body;
+}
+
+function isoOf(value: Date | string): string {
+  return typeof value === 'string' ? value : value.toISOString();
+}

package/src/index.ts

@@ -5,6 +5,8 @@ export type { DomainsResource } from './domains.ts';
 export type { EmailResource } from './email.ts';
 export { SendoraError } from './error.ts';
 export type { SendoraErrorCode } from './error.ts';
+export type { InboundResource } from './inbound.ts';
+export type { InboundDomainsResource } from './inbound-domains.ts';
 export type { MessagesResource } from './messages.ts';
 export type { StreamsResource } from './streams.ts';
 export type { SuppressionsResource } from './suppressions.ts';

package/src/transport.ts

@@ -46,11 +46,20 @@ export class Transport {
   }
 
   async request<T>(spec: RequestSpec): Promise<T> {
+    return this.#send<T>(spec, 'json');
+  }
+
+  /** A download: the answer's bytes as they came, with the same errors and retries as any other request. */
+  async requestBytes(spec: RequestSpec): Promise<Uint8Array> {
+    return this.#send<Uint8Array>(spec, 'bytes');
+  }
+
+  async #send<T>(spec: RequestSpec, shape: 'json' | 'bytes'): Promise<T> {
     const url = this.#url(spec);
     const body = spec.body === undefined ? undefined : JSON.stringify(spec.body);
     let waitedMs = 0;
     for (let attempt = 0; ; attempt += 1) {
-      const outcome = await this.#attempt<T>(spec, url, body);
+      const outcome = await this.#attempt<T>(spec, url, body, shape);
       if (outcome.ok) {
         return outcome.value;
       }
@@ -69,12 +78,17 @@ export class Transport {
     }
   }
 
-  async #attempt<T>(spec: RequestSpec, url: string, body: string | undefined): Promise<Attempt<T>> {
+  async #attempt<T>(
+    spec: RequestSpec,
+    url: string,
+    body: string | undefined,
+    shape: 'json' | 'bytes',
+  ): Promise<Attempt<T>> {
     const timeout = AbortSignal.timeout(this.#options.timeoutMs);
     const signal = spec.signal === undefined ? timeout : AbortSignal.any([spec.signal, timeout]);
     const init: RequestInit = {
       method: spec.method,
-      headers: this.#headers(spec, body),
+      headers: this.#headers(spec, body, shape),
       signal,
       redirect: 'manual',
     };
@@ -113,6 +127,9 @@ export class Transport {
       await response.body?.cancel();
       return { ok: true, value: undefined as T };
     }
+    if (shape === 'bytes' && response.ok) {
+      return { ok: true, value: new Uint8Array(await response.arrayBuffer()) as T };
+    }
     const json = parseJson(await response.text());
     if (response.status === 0 || (response.status >= 300 && response.status < 400)) {
       return {
@@ -143,10 +160,14 @@ export class Transport {
     };
   }
 
-  #headers(spec: RequestSpec, body: string | undefined): Record<string, string> {
+  #headers(
+    spec: RequestSpec,
+    body: string | undefined,
+    shape: 'json' | 'bytes',
+  ): Record<string, string> {
     const headers: Record<string, string> = {
       authorization: `Bearer ${this.#options.token}`,
-      accept: 'application/json',
+      accept: shape === 'bytes' ? '*/*' : 'application/json',
       'user-agent': this.#options.userAgent,
       ...spec.headers,
     };

package/src/types.ts

@@ -296,6 +296,112 @@ export interface MessagePage {
   next: string | null;
 }
 
+/** The body POST /v1/inbound/search takes. */
+export interface InboundSearchBody {
+  streamId?: string | undefined;
+  from?: string | undefined;
+  recipient?: string | undefined;
+  mailboxHash?: string | undefined;
+  receivedFrom?: string | undefined;
+  receivedTo?: string | undefined;
+  limit?: number | undefined;
+  after?: string | undefined;
+}
+
+/** The filters of a search over received mail; every one is optional. */
+export interface InboundSearch {
+  /** Messages received on this inbound stream of the server. */
+  streamId?: string | undefined;
+  /** Messages from this address, in the envelope or the From header. */
+  from?: string | undefined;
+  /** Messages sent to this address of yours. */
+  recipient?: string | undefined;
+  /** Messages whose address carried this text after the plus sign. */
+  mailboxHash?: string | undefined;
+  /** Accepted at or after this time. */
+  receivedFrom?: Date | string | undefined;
+  /** Accepted before this time. */
+  receivedTo?: Date | string | undefined;
+  /** Page size, 1 to 100; 50 when left out. */
+  limit?: number | undefined;
+  /** The `next` value of the previous page. */
+  after?: string | undefined;
+}
+
+/** An attachment of a received message, described; its bytes are `sendora.inbound.attachment`. */
+export interface InboundMessageAttachment {
+  attachmentId: string;
+  /** Its place among the message's attachments, from 0. */
+  position: number;
+  /** The filename, sanitised; null once the content is gone. */
+  name: string | null;
+  /** The type the sender declared; every download is served as application/octet-stream. */
+  contentType: string | null;
+  /** The Content-ID an HTML body refers to with `cid:`. */
+  contentId: string | null;
+  size: number;
+  /** True for a part shown in the body rather than offered as a file. */
+  inline: boolean;
+}
+
+/** A received message as the list shows it. */
+export interface InboundMessage {
+  inboundMessageId: string;
+  /** The inbound stream that received it. */
+  streamId: string;
+  /** When the message was accepted from the sending server. */
+  receivedAt: string;
+  /** The address of yours the message was sent to. */
+  envelopeRecipient: string;
+  /** The text after the plus sign in that address, when the sender used one. */
+  mailboxHash: string | null;
+  sizeBytes: number;
+  attachmentCount: number;
+  hasText: boolean;
+  hasHtml: boolean;
+  /** What the parser met, from a closed set; null when the message parsed clean. */
+  parseIssue: string | null;
+  authentication: InboundAuthentication;
+  /** False once the stream's content window has passed; only the reference remains. */
+  contentAvailable: boolean;
+  /** When the content goes. */
+  contentExpiresAt: string;
+  /** The From header; null without it or once the content is gone. */
+  from: InboundAddress | null;
+  subject: string | null;
+  /** The sender's Date header as ISO 8601, when it was a real moment. */
+  date: string | null;
+}
+
+/** The received message with everything but the attachment bytes. */
+export interface InboundMessageDetail extends InboundMessage {
+  /** The envelope sender; null for a bounce, or once the content is gone. */
+  envelope: { sender: string | null } | null;
+  replyTo: InboundAddress[];
+  /** Up to 100 entries; `toCount` is the whole number. */
+  to: InboundAddress[];
+  toCount: number;
+  cc: InboundAddress[];
+  ccCount: number;
+  messageIdHeader: string | null;
+  inReplyTo: string | null;
+  references: string[];
+  /** Every header in order; null once the content is gone. */
+  headers: InboundHeader[] | null;
+  /** The plain-text body; null without one or once the content is gone. */
+  text: string | null;
+  /** The HTML body as received; null without one or once the content is gone. */
+  html: string | null;
+  attachments: InboundMessageAttachment[];
+}
+
+/** One page of received messages, newest first. */
+export interface InboundPage {
+  messages: InboundMessage[];
+  /** Pass as `after` for the next page; null on the last. */
+  next: string | null;
+}
+
 /** Cursor paging for the lists that page. */
 export interface PageQuery {
   /** Page size, 1 to 1000; 100 when left out. */
@@ -567,6 +673,8 @@ export interface Delivery {
   event: WebhookEventName;
   /** Null for an event about usage rather than a message. */
   messageId: string | null;
+  /** The received message an inbound event is about; null for every other event. */
+  inboundMessageId: string | null;
   status: DeliveryStatus;
   attempts: number;
   /** When the next attempt is due, while pending. */
@@ -598,7 +706,7 @@ export interface CreateDomainRequest {
 }
 
 /** A DNS record the domain needs and whether it has been seen. */
-export interface DnsRecord<Type extends 'CNAME' | 'TXT'> {
+export interface DnsRecord<Type extends 'CNAME' | 'TXT' | 'MX'> {
   type: Type;
   /** The name to create the record under. */
   host: string;
@@ -635,6 +743,43 @@ export interface DomainList {
   domains: SendingDomain[];
 }
 
+/** The body POST /v1/inbound/domains takes. */
+export interface CreateInboundDomainRequest {
+  /** An inbound stream of the server. */
+  streamId: string;
+  /** The domain to receive on, such as post.example.se. */
+  domain: string;
+}
+
+/** A domain on an inbound stream and the two records it needs. */
+export interface InboundDomain {
+  inboundDomainId: string;
+  /** The inbound stream the domain delivers to. */
+  streamId: string;
+  /** The domain, lower-cased and IDNA-encoded. */
+  domain: string;
+  /** True while both records are seen; only then is mail to the domain accepted. */
+  verified: boolean;
+  createdAt: string;
+  /** When the records were last looked up. */
+  lastCheckedAt: string | null;
+  /** When a verified domain lost its records. Mail to it is deferred for 72 hours from then and refused after, until the records are back. */
+  unverifiedAt: string | null;
+  /** The MX record that brings the domain's mail to Sendora, at any priority. */
+  mx: DnsRecord<'MX'>;
+  /** The TXT record that proves the claim; it carries a token only you were shown. */
+  txt: DnsRecord<'TXT'>;
+}
+
+/** The domain as it stands after a check, and what each lookup found. */
+export interface VerifiedInboundDomain extends InboundDomain {
+  check: { mx: RecordCheck; txt: RecordCheck };
+}
+
+export interface InboundDomainList {
+  domains: InboundDomain[];
+}
+
 /** What every event about a message carries. */
 export interface MessageEventFields {
   /** The delivery id. Deliveries arrive at least once, so key your handling on it. */
@@ -831,7 +976,7 @@ export interface InboundEventContent {
 /**
  * A message received on an inbound stream. The content fields are present
  * for a webhook with `inboundContent: 'full'` and absent for
- * `reference`; `'contentOmitted' in event` tells them apart.
+ * `reference`; `event.contentOmitted !== undefined` tells them apart.
  */
 export type InboundEvent = InboundEventFields &
   (InboundEventContent | { contentOmitted?: undefined });

package/src/version.ts

@@ -1,2 +1,2 @@
 /** The package version, sent as the User-Agent; a test holds it equal to package.json. */
-export const SDK_VERSION = '1.1.0';
+export const SDK_VERSION = '1.2.0';