@openemail/sdk 0.0.1

package/README.md

@@ -0,0 +1,183 @@
+<div align='center'>
+   <a href='https://openemail.uk'>
+        <img 
+            src='https://openemail.uk/logo.svg' 
+            alt='OpenEmail Logo' 
+            width='180'
+        />
+   </a>
+
+   <br />
+</div>
+
+<p align='center'>
+    Email you can build on. Send mail, read the mailbox and automate a workspace from code.
+</p>
+
+<p align='center'>
+    <a href='https://openemail.uk'>
+        <b>
+            Website
+        </b>
+    </a> 
+    •
+    <a href='https://openemail.uk/docs/sdk'>
+        <b>
+            Documentation
+        </b>
+    </a>
+    •
+    <a href='https://openemail.uk/docs/api/reference'>
+        <b>
+            API Reference
+        </b>
+    </a>
+    •
+    <a href='https://openemail.uk/docs/mcp/overview'>
+        <b>
+            MCP Server
+        </b>
+    </a>
+</p>
+
+<br />
+
+## Intro to the Npm Package
+
+The official TypeScript client for the OpenEmail API. One method per endpoint, 103 in all, typed end to end, with zero dependencies. It runs on Node 20+, Bun, Deno and Cloudflare Workers, and ships as ESM and CommonJS.
+
+It carries a workspace API key, so it belongs on a server. The one exception is disposable inboxes, which need no key and work in a browser.
+
+### Installing
+```bash
+npm i @openemail/sdk@latest
+```
+
+### Using
+```typescript
+import { OpenEmail } from '@openemail/sdk'
+
+const openemail = new OpenEmail('oe_live_...')
+
+const sent = await openemail.emails.send({
+    from: 'Acme Billing <billing@acme.com>',
+    to: 'ada@example.com',
+    subject: 'Your September invoice',
+    html: '<p>Your invoice is attached.</p>',
+    attachments: [{ filename: 'invoice.pdf', content: pdfBytes, contentType: 'application/pdf' }]
+})
+
+console.log(sent.id, sent.status)
+```
+
+Create a key in OpenEmail under Settings, API keys. It is shown once, and it belongs in an environment variable rather than in code.
+
+Build the client once, in a module of its own, and import it everywhere else:
+
+```typescript
+import { OpenEmail } from '@openemail/sdk'
+
+export const openemail = new OpenEmail(process.env.OPENEMAIL_API_KEY!)
+```
+
+Or skip even that. The package ships a ready made `openemail` that reads `OPENEMAIL_API_KEY` the first time it is touched:
+
+```typescript
+import { openemail } from '@openemail/sdk'
+
+await openemail.emails.send({ from, to, subject, text })
+```
+
+Every send carries an idempotency key, generated once per call and reused by its retries, so a retried request replays the original message rather than sending a second one. Pass your own with `{ idempotencyKey }` to make that hold across processes and restarts.
+
+### Reading the mailbox
+```typescript
+const page = await openemail.threads.list({ folder: 'inbox', limit: 25 })
+
+for await (const thread of openemail.threads.iterate({ folder: 'inbox', query: 'invoice' })) {
+    const full = await openemail.threads.get(thread.id)
+
+    console.log(full.messageCount, full.hasUnread)
+}
+```
+
+Every paginated resource has `list` for one page, `listAll` for every page as one array, and `iterate` to stream items and stop whenever you like.
+
+### Errors
+```typescript
+import { OpenEmailApiError, openemail } from '@openemail/sdk'
+
+try {
+    await openemail.templates.send('order-shipped', {
+        from: 'dispatch@acme.com',
+        to: 'ada@example.com',
+        props: { orderId: 'AC-4192' }
+    })
+}
+
+catch (error) {
+    if (error instanceof OpenEmailApiError && error.isValidation) {
+        console.error(error.code, error.param, error.requestId)
+    }
+
+    throw error
+}
+```
+
+An API refusal is one class, `OpenEmailApiError`, with `status`, `type`, `code`, `param` and `requestId`, plus `isValidation`, `isNotFound`, `isRateLimited` and friends to branch on. No response at all is `OpenEmailNetworkError`, with `isTimeout` when the deadline passed.
+
+### Webhooks
+```typescript
+import { verifyWebhookSignature } from '@openemail/sdk'
+
+export default async (request: Request) => {
+    const event = await verifyWebhookSignature({
+        payload: await request.text(),
+        headers: request.headers,
+        secret: process.env.OPENEMAIL_WEBHOOK_SECRET!
+    })
+
+    console.log(event.type, event.data)
+
+    return new Response(null, { status: 204 })
+}
+```
+
+It checks the HMAC in constant time and rejects a delivery more than five minutes old, then returns the parsed event. Pass the raw body: re-serialising it changes the bytes and the signature will not match.
+
+### Disposable inboxes
+```typescript
+import { createTempMail } from '@openemail/sdk'
+
+const temp = createTempMail()
+
+const inbox = await temp.create({ ttlMinutes: 60 })
+
+const { items } = await temp.listMessages(inbox.id, { inboxToken: inbox.token })
+```
+
+`create` needs no credential and is the only call that returns the inbox token, so keep it.
+
+### Configuring
+Pass an options object instead of the bare key when the defaults are not right:
+
+```typescript
+import { OpenEmail } from '@openemail/sdk'
+
+export const openemail = new OpenEmail({
+    apiKey: process.env.OPENEMAIL_API_KEY!,
+    baseUrl: 'https://api.openemail.uk',
+    timeoutMs: 30_000,
+    maxRetries: 2,
+    fetch: myFetch,
+    headers: { 'X-Team': 'billing' }
+})
+```
+
+`createOpenEmail(options)` is the same constructor with one difference: anything you leave out is read from the environment. The shipped `openemail` takes the same options through `init(options)`, called once at startup.
+
+`baseUrl` also comes from `OPENEMAIL_BASE_URL`, for a server you run yourself. Reads are retried on 408, 429 and 5xx with backoff, honouring `Retry-After` up to a minute. Writes that cannot safely repeat are not. Every method takes `{ signal, apiKey }` as its last argument, so one process can serve several workspaces with one client.
+
+When a newer version is on npm the client says so once on a TTY. `OPENEMAIL_DISABLE_UPDATE_NOTICE=1` or `{ disableUpdateNotice: true }` turns that off.
+
+Everything else, templates, rules, tracking, calendar, roles, members, settings and the full reference for all 103 methods, lives in the [documentation](https://openemail.uk/docs/sdk).