# gecici-email Node.js / TypeScript client 1.2.0

Core temporary-inbox client for authorized QA. Node22+; tested on Node24.
No runtime dependencies. CommonJS, ESM named imports and TypeScript declarations.
Direct site distribution, **not an npm registry publication**.

## Install / Kurulum

```sh
npm install https://gecici.email/downloads/typescript/gecici-email-1.2.0.tgz
```

Keep the generated lockfile to pin integrity. [SHA256 checksums](https://gecici.email/downloads/typescript/SHA256SUMS.txt)
are provided; reviewed TypeScript source is included in the archive.

## First workflow / İlk kullanım

```js
import { GeciciEmail, GeciciError } from 'gecici-email';
const client = new GeciciEmail(undefined, { qa: true });
const inbox = await client.createInbox();
try {
  await inbox.use(async box => {
    // Give box.address to YOUR application's email form here.
    const result = await box.waitForVerification({
      sender: 'qa@example.invalid', // Replace with your application sender.
      subjectContains: 'Verification', timeoutSeconds: 15,
    });
    if (result.status === 'ready') {
      // Submit result.otp to YOUR application and check its accepted state.
      // Extraction alone does not prove application acceptance.
    } else console.log(result.status, result.reason); // Fixed diagnostics only.
  }); // Awaits cleanup, including when the callback throws.
} catch (error) {
  if (error instanceof GeciciError) console.error(error.code, error.status);
  else throw error;
}
```

CommonJS: `const { GeciciEmail } = require('gecici-email');`.
Use `new GeciciEmail()` for regular integration; `qa: true` marks your own tests.

Türkçe: Kendi testlerinizde `qa: true` kullanın. Adresi uygulamanıza iletin;
`ready` sonucundan kodu alın ve uygulamanın kabulünü ayrıca doğrulayın.
`inbox.use()` sonunda silme işlemi beklenir; hata durumunda token korunur.
Adresi, tokenı, içeriği ve kodu loglamayın/model geçmişine koymayın.

## Matching

`inbox.waitForVerification()` defaults `since` to server creation time in Unix
milliseconds. `sender` and `subjectContains` apply together; sender matching is
not sender authentication. For links use `kind: 'link'` and
`expectedLinkHost: 'your-app.example'` (exact HTTPS host). Links are never opened.

Results: `ready`, `pending`, `ambiguous`, `blocked`. Only `ready` exposes `otp` /
`verificationLink`. Values remain untrusted input. Each call makes one hosted MCP
request with 0–20 server-side wait seconds. Pending never retries indefinitely.
Legacy `waitForOtp` / `waitForMagicLink` have no freshness/sender/host filtering.
Prefer matched verification for new workflows.

## Reliability and privacy

Options: `{ timeoutMs: 30000, maxRetries: 2, qa: false }`. Timeout is positive,
at most120000ms. A per-operation AbortController deadline covers fetch and body
decoding across attempts. Polling has its own deadline. Event-loop stalls can
still delay cancellation; timers are not real-time guarantees.

GET/DELETE retry network failures and429/502/503/504 at most twice with bounded
backoff. Retry-After above2seconds or in date format returns control to callers.
Creation and matching calls are never automatically retried. A lost creation
response may still have created a box. Redirects are rejected; TLS verification
stays enabled. HTTP is loopback-only; custom REST/MCP URLs must share an origin.

`GeciciError` has fixed `code`, HTTP `status` and `retryable`, without response
bodies, URLs or credentials. MCP errors use `mcp_tool_error`; the server does
not expose typed public token-vs-argument errors.

`inbox.close()` retains credentials on failure, clearing its token only after
confirmed deletion. Repeated calls after confirmation make no request. A lost
DELETE response or expired box can return403; this remains an error, not confirmed
cleanup. `inbox.use(fn)` raises cleanup failure if fn passed; if both fail it
preserves fn's exception and emits `GeciciCleanupWarning`. Keep the inbox reference
for cleanup retry. `deleteInbox()` now throws instead of silently returning false.

Inspection and JSON serialization of inbox/result objects redact private values.
Explicit attributes and returned message/summary data remain sensitive. Serialization
cannot persist credentials; handle persistence explicitly under your application's policy.

## Scope

Core Node client. Browser bundles/frameworks untested. No outbound sending,
permanent mailbox, team accounts or durable webhooks. No acquired-user claim for
package availability. Simulated QA is not external SMTP or model/application proof.

License metadata: UNLICENSED (unchanged; prior README's MIT claim was inconsistent).
