@ahrara/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# Ahrara for JavaScript and TypeScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Create an email address from Node.js, wait for messages, and extract verification
+codes or links in JavaScript or TypeScript. Requires Node.js 20+; install with
+`npm install @ahrara/sdk`. TypeScript declarations are included. The SDK connects
+directly to the relay and runs in the application or test runner, not in the
+browser.
+
+```js
+import { Ahrara } from '@ahrara/sdk';
+
+const inbox = await Ahrara.createInbox();
+try {
+  // Submit inbox.address in your application.
+  const email = await inbox.waitForEmail(); // No implicit timeout.
+  // Assert on email.subject / email.text_body.
+} finally {
+  await inbox.close();
+}
+```
+
+Creation returns after authentication and subscription. Mail arriving before a
+wait is buffered. Each matching receive is consumed once, while storage retains
+the message until deleted. Create separate inboxes for parallel tests. Concurrent
+waits on one inbox are queued and run one at a time, in call order.
+
+## Waits, streams, and callbacks
+
+`waitForEmail({ timeoutMs, subject, from, signal })` waits indefinitely when
+`timeoutMs` is omitted. An explicit positive integer deadline is in milliseconds
+and throws `AhraraError` with code `timeout`. `subject` and `from` are ASCII
+case-insensitive substrings. AbortSignal cancellation and `close()` interrupt
+waits; cancelling a wait preserves the inbox. A simultaneously matched email may
+win the cancellation race. Native work runs off the Node event loop.
+
+```js
+for await (const email of inbox.waitForEmails({ timeoutMs: 10_000 })) {
+  await verify(email);
+  if (finished()) break;
+}
+
+await inbox.receiveEmails(async email => {
+  await verify(email);
+}, { timeoutMs: 10_000 });
+```
+
+A stream's finite timeout is its **total duration**, including consumer/callback
+work, and expiry ends normally. Omit timeout to keep receiving indefinitely.
+Callbacks are awaited sequentially; errors propagate. Breaking a stream,
+returning its iterator, cancellation, or callback failure leaves the inbox open.
+There is no prefetch or hidden message queue. Use an AbortSignal to interrupt an
+active `next()`; awaiting `return()` alone cannot interrupt an in-flight receive.
+The application remains responsible for closing the inbox.
+
+## Filters, regex captures, and XPath
+
+Pass `filter` to `createInbox()` to discard nonmatching incoming email before
+storage, or to a wait/search method to leave nonmatching email available for
+later waits. All filter fields are ANDed. `sender`, `subject`, `to`, `cc`, `text`,
+and `headers: { name: value }` use case-insensitive substring matching.
+`recipient`, `envelopeSender`, and `messageId` match exactly, ignoring case;
+`hasAttachments` selects presence or absence of attachments. Header names ignore
+case. A per-wait filter adds to the inbox's receipt filter.
+
+Set `filter: { regex: true, subject: '^(Verification|Confirm email)$' }` to
+interpret all string conditions as case-insensitive Rust regex patterns; regex
+queries below are case-sensitive unless `ignoreCase` is set. The top-level
+`subject`/`from` wait options stay literal. See the
+[shared filter rules](https://github.com/Hitmasu/Ahrara/blob/main/docs/sdks.md#filters-and-extraction)
+for anchoring and limits.
+
+```js
+const match = await inbox.waitForRegexMatch('code=(?<code>[0-9]+)', {
+  filter: { sender: 'example.test', subject: 'Verify' },
+  ignoreCase: true,
+});
+const code = match.groups.find(group => group.name === 'code').value;
+
+for await (const match of inbox.waitForRegexMatches('[0-9]+', { timeoutMs: 10_000 })) {
+  await verifyCode(match.value);
+}
+
+const link = await inbox.waitForXPath('//a[@id="verify"]/@href');
+for await (const value of inbox.waitForXPathValues('//a/@href', { timeoutMs: 10_000 })) {
+  await verifyLink(value);
+}
+```
+
+Regex uses the shared [Rust regex syntax](https://docs.rs/regex/latest/regex/#syntax),
+including named groups; lookaround and backreferences are unsupported. Options
+are `source: 'text' | 'html' | 'subject' | 'raw'` (default full decoded text),
+`ignoreCase`, `multiLine`, and `dotMatchesNewLine`. A result contains `email_id`,
+`value`, and indexed `groups`; group zero is the whole match and unmatched optional
+groups have a null value. HTML searches use original decoded HTML.
+
+Singular calls return the first value/match and throw on timeout. Plural methods
+yield **every match/value across multiple emails**, with one total timeout that
+includes consumer work. Finite expiry ends normally; omitted timeout is indefinite.
+`signal` cancels either form. Invalid expressions and filters throw before
+consuming email. Each matched email is consumed once: stopping partway through
+its results does not replay the remaining values, but its stored message remains
+readable.
+
+## Persistence and identity
+
+`createInbox({ profilePath: '/absolute/profile/directory' })` retains identity,
+address, encrypted history, and consumed-receive state across close/reopen. Omit
+`profilePath` for a disposable temporary profile. The same active profile cannot
+be opened twice. Explicitly clear/delete messages to remove retained history.
+
+```js
+const credentials = await inbox.exportCredentials();
+await inbox.close();
+const restored = await Ahrara.createInbox({ credentials });
+```
+
+Credentials restore the identity/address, with fresh local history unless a
+persistent profile is supplied. Inspection and JSON serialization redact the
+Recovery Key; access `credentials.recoveryKey` only for deliberate secure storage.
+Never log it. Alternatively pass `recoveryKey` and optional owned `address`;
+these cannot be combined with `credentials`. An `address` alone requires an
+existing profile identity. Unowned addresses and mismatched profile keys fail.
+
+Connection options are `serverUrl`, `serverPublicKey`, `tlsCaPath`, and
+`connectTimeoutMs` (1..300000 ms, default 20000). Omit them for the hosted relay,
+whose verified public key the package embeds; a private relay's public key must be
+independently verified. Custom CAs keep TLS verification enabled.
+
+## Stored email and attachments
+
+All operations are scoped to the inbox's address. Listing/getting does not
+consume receive state. Native errors retain their code in `AhraraError.code`.
+
+| Method | Result |
+| --- | --- |
+| `listEmails({ afterId, limit, subject, from })` | `{ emails, next_cursor }` metadata page; limit 1..100 |
+| `getEmail(id)` | Full parsed email with attachment metadata |
+| `deleteEmail(id)` / `clearEmails()` | Number of messages removed |
+| `getAttachment(id, attachmentId)` | `{ attachment, content: Buffer }` |
+| `saveAttachment(id, attachmentId, absolutePath)` | Saved file path; never overwrites; directories use a sanitized filename |
+| `getRawEmail(id)` | Original RFC 822 bytes as Buffer |
+| `getHtml(id, { allowRemote: false })` | Sanitized `{ html, remote_resources }`; remote resources blocked by default |
+
+Email fields use the native snake_case schema, including `from`, `to`, `subject`,
+`text_body`, `attachments`, and `parse_error`. Extracted text is capped at 256 KiB
+and reports `text_body_truncated`. HTML and attachments are fetched explicitly.
+Treat message content as untrusted data.
+
+## Test frameworks
+
+Playwright uses a test fixture owning an inbox; see
+[`signup.spec.js`](https://github.com/Hitmasu/Ahrara/blob/main/src/sdks/javascript/test/signup.spec.js).
+Cypress uses Node `setupNodeEvents` and `cy.task`, since browser code cannot load
+the native library; see
+[`cypress.config.js`](https://github.com/Hitmasu/Ahrara/blob/main/src/sdks/javascript/cypress.config.js).
+Node/Jest/Vitest use the same API.

package/index.d.ts

@@ -0,0 +1,235 @@
+/** An address and its sensitive Recovery Key; never log the key. */
+export interface CredentialsInput {
+  address: string;
+  recoveryKey: string;
+}
+
+/** Exported credentials redact inspection and JSON; access recoveryKey explicitly. */
+export class InboxCredentials implements CredentialsInput {
+  constructor(address: string, recoveryKey: string);
+  readonly address: string;
+  readonly recoveryKey: string;
+  toJSON(): { address: string; recoveryKey: string };
+}
+
+/** Connection, local persistence, and optional identity restoration. */
+export interface InboxOptions {
+  /** Receipt filter applied before storage. Rejected emails are dropped. */
+  filter?: EmailFilter;
+  /** wss:// relay URL; defaults to the release core's production endpoint. */
+  serverUrl?: string;
+  /** Independently verified public Noise key, not a Recovery Key. */
+  serverPublicKey?: string;
+  /** Optional custom trusted CA PEM file. TLS verification remains enabled. */
+  tlsCaPath?: string;
+  /** Connection deadline in milliseconds, 1..300000; core default 20000. */
+  connectTimeoutMs?: number;
+  /** Absolute persistent profile directory. Omit for an isolated temporary profile. */
+  profilePath?: string;
+  /** Restore exported credentials; mutually exclusive with recoveryKey/address. */
+  credentials?: CredentialsInput;
+  /** Sensitive identity import, optionally paired with an owned address. */
+  recoveryKey?: string;
+  /** Owned address to select; alone requires an existing profile identity. */
+  address?: string;
+}
+
+export interface WaitOptions {
+  /** Additional filter; nonmatching stored emails remain available for later waits. */
+  filter?: EmailFilter;
+  /** Positive integer milliseconds. Omitted means indefinite; streams use a total deadline. */
+  timeoutMs?: number;
+  /** Substring filter using the core's ASCII case-insensitive matching. */
+  subject?: string;
+  /** Sender substring filter using the same matching rules. */
+  from?: string;
+  /** Abort only this wait/subscription. Cancellation leaves the inbox open. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Fields are ANDed. Strings match case-insensitive substrings, except recipient,
+ * envelopeSender, and messageId, which match the whole value. With `regex: true`,
+ * strings are case-insensitive Rust regex patterns: those three are anchored to
+ * the whole value; the others match anywhere.
+ */
+export interface EmailFilter {
+  /** Interpret string conditions, including header values, as regex. Header names stay literal. */
+  regex?: boolean;
+  sender?: string;
+  subject?: string;
+  to?: string;
+  cc?: string;
+  text?: string;
+  /** Whole SMTP recipient, ignoring case; an anchored pattern with `regex`. */
+  recipient?: string;
+  /** Whole SMTP envelope sender, ignoring case; an anchored pattern with `regex`. */
+  envelopeSender?: string;
+  /** Whole Message-ID header, ignoring case; an anchored pattern with `regex`. */
+  messageId?: string;
+  hasAttachments?: boolean;
+  /** Literal, case-insensitive header names; each value matches anywhere in a header value. */
+  headers?: Record<string, string>;
+}
+
+/** Shared search lifecycle. Single waits throw on timeout; streams end normally. */
+export interface SearchOptions {
+  /** Positive integer milliseconds, or omitted for indefinite. Streams use total duration. */
+  timeoutMs?: number;
+  /** Abort this search/stream while keeping the inbox open. */
+  signal?: AbortSignal;
+  /** Nonmatching stored emails remain unconsumed. */
+  filter?: EmailFilter;
+}
+
+export interface RegexOptions extends SearchOptions {
+  /** Search full decoded text (default), original HTML, subject, or raw RFC 822 text. */
+  source?: "text" | "html" | "subject" | "raw";
+  /** Defaults to false: query regex is case-sensitive, unlike filter regex. */
+  ignoreCase?: boolean;
+  multiLine?: boolean;
+  dotMatchesNewLine?: boolean;
+}
+
+export interface RegexGroup {
+  /** Zero identifies the whole match. Remaining indices follow capture order. */
+  index: number;
+  /** Named capture identifier, or null for unnamed groups. */
+  name?: string | null;
+  /** Null when an optional group did not participate in this match. */
+  value?: string | null;
+}
+
+/** A matching substring and all its captures, associated with an inbox-owned email. */
+export interface RegexMatch {
+  email_id: number;
+  value: string;
+  groups: RegexGroup[];
+}
+
+export interface ListOptions {
+  /** Exclusive message-ID cursor; defaults to 0. */
+  afterId?: number;
+  /** Page size 1..100; defaults to 20. */
+  limit?: number;
+  subject?: string;
+  from?: string;
+}
+
+/** Stored metadata. Field names match the shared native email schema. */
+export interface EmailMetadata {
+  id: number;
+  transfer_id: string;
+  identity_fingerprint: string;
+  recipient: string;
+  envelope_sender: string;
+  received_at: string;
+  from: string;
+  to: string;
+  subject: string;
+  message_id: string | null;
+  size_bytes: number;
+}
+
+export interface Attachment {
+  attachment_id: string;
+  filename: string;
+  content_type: string;
+  size: number;
+  content_disposition: string;
+}
+
+export interface Email extends EmailMetadata {
+  cc: string;
+  date: string;
+  forwarded_to: string | null;
+  /** Extracted text, capped by the core at 256 KiB. */
+  text_body: string;
+  text_body_truncated: boolean;
+  html_available: boolean;
+  attachments: Attachment[];
+  parse_error: boolean;
+}
+
+export interface EmailPage {
+  emails: EmailMetadata[];
+  next_cursor: number | null;
+}
+
+export interface AttachmentData {
+  attachment: Attachment;
+  content: Buffer;
+}
+
+export interface HtmlEmail {
+  html: string;
+  remote_resources: number;
+}
+
+/** Native errors retain a stable code, including timeout/inbox_closed. */
+export class AhraraError extends Error {
+  constructor(code: string, message: string);
+  readonly code: string;
+}
+
+/** A ready, caller-owned inbox. Close explicitly or use await using. */
+export class Inbox {
+  private constructor();
+  readonly address: string;
+  /** Consume one matching email. Concurrent waits queue. Omitted timeout waits indefinitely. Throws on finite timeout. */
+  waitForEmail(options?: WaitOptions): Promise<Email>;
+  /** Sequential stream; total timeout includes consumer work and expires normally. */
+  waitForEmails(options?: WaitOptions): AsyncGenerator<Email, void, unknown>;
+  /** Await each callback; propagate callback errors. No prefetch or hidden background queue. */
+  receiveEmails(
+    handler: (email: Email) => void | Promise<void>,
+    options?: WaitOptions,
+  ): Promise<void>;
+  /** First regex match with captures. Invalid queries never consume email. */
+  waitForRegexMatch(
+    pattern: string,
+    options?: RegexOptions,
+  ): Promise<RegexMatch>;
+  /** Every match across emails; total deadline includes consumer work. Expiry ends normally. */
+  waitForRegexMatches(
+    pattern: string,
+    options?: RegexOptions,
+  ): AsyncGenerator<RegexMatch, void, unknown>;
+  /** First XPath string value from a matching email's HTML. */
+  waitForXPath(expression: string, options?: SearchOptions): Promise<string>;
+  /** Every XPath value across emails; same lifetime and deadline rules as regex streams. */
+  waitForXPathValues(
+    expression: string,
+    options?: SearchOptions,
+  ): AsyncGenerator<string, void, unknown>;
+  /** Export identity credentials explicitly; their Recovery Key is sensitive. */
+  exportCredentials(): Promise<InboxCredentials>;
+  /** Read metadata without consuming the receive cursor. */
+  listEmails(options?: ListOptions): Promise<EmailPage>;
+  /** Read full parsed email; IDs are scoped to this inbox's address. */
+  getEmail(id: number): Promise<Email>;
+  /** Delete one stored message and return the number removed. */
+  deleteEmail(id: number): Promise<number>;
+  /** Clear only this inbox's messages and return the number removed. */
+  clearEmails(): Promise<number>;
+  /** Return attachment metadata and bytes without touching the filesystem. */
+  getAttachment(id: number, attachmentId: string): Promise<AttachmentData>;
+  /** Save to an absolute file/directory path; never overwrite. Returns the saved path. */
+  saveAttachment(
+    id: number,
+    attachmentId: string,
+    destination: string,
+  ): Promise<string>;
+  /** Original RFC 822 message bytes. */
+  getRawEmail(id: number): Promise<Buffer>;
+  /** Sanitized HTML. Remote resources are blocked by default. */
+  getHtml(id: number, options?: { allowRemote?: boolean }): Promise<HtmlEmail>;
+  /** Idempotent shutdown. Interrupts waits; persistent profile files remain. */
+  close(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/** Return after authentication/subscription, or throw a native configuration/connection error. */
+export function createInbox(options?: InboxOptions): Promise<Inbox>;
+
+export const Ahrara: Readonly<{ createInbox: typeof createInbox }>;