@agentidentity/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naol Ketema
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @agentidentity/sdk
+
+TypeScript client for **Agent Identity** — give an agent its own email address, a durable event
+stream it can block on, and an encrypted secret vault.
+
+Zero runtime dependencies. Node 20+.
+
+```bash
+npm install @agentidentity/sdk
+```
+
+## Quickstart
+
+```ts
+import { AgentClient } from "@agentidentity/sdk";
+
+const client = new AgentClient({
+  baseUrl: "https://api.agent-identity.dev",
+  apiKey: process.env.AID_API_KEY!,
+});
+
+// Give your agent an identity — this provisions a real, deliverable mailbox.
+const agent = await client.identities.create({ handle: "support", displayName: "Support Bot" });
+console.log(agent.mailboxAddress); // support@yourdomain.com
+
+await client.mail.send({
+  identityId: agent.id,
+  to: ["customer@example.com"],
+  subject: "We got your ticket",
+  text: "Someone will be with you shortly.",
+});
+```
+
+Don't have an org yet? Bootstrap one — these run before you have a key, so they're plain
+functions rather than client methods:
+
+```ts
+import { signUp, logIn, createOrganization } from "@agentidentity/sdk";
+
+const session = await signUp("https://api.agent-identity.dev", {
+  orgName: "Acme",
+  orgSlug: "acme",
+  email: "you@acme.com",
+  password: "…",
+});
+// session.apiKey is what you pass to AgentClient
+```
+
+## Reacting to mail
+
+The point of an agent mailbox is that your code can *wait* on it. `events.subscribe()` is an
+async iterator that yields events as they arrive:
+
+```ts
+for await (const event of client.events.subscribe({ type: "mail.received", identityId: agent.id })) {
+  const thread = await client.mail.getThread(agent.id, event.payload.threadId);
+  const reply = await yourModel(thread);
+
+  await client.mail.send({
+    identityId: agent.id,
+    to: [event.payload.from!],
+    subject: `Re: ${event.payload.subject}`,
+    text: reply,
+    inReplyToMessageId: event.payload.messageId,
+  });
+}
+```
+
+`event.payload` is typed per event type — narrowing on `event.type` narrows the payload with it,
+so there are no casts. Use `events.wait()` directly if you want a single event instead of a loop.
+
+Subscribing handles the parts a hand-rolled loop gets wrong: it advances its cursor using each
+event's own `createdAt` rather than the client's wall clock (which can skip events under clock
+skew), re-polls transparently when the server's long-poll window elapses, and retries failures
+with exponential backoff. Stop it with an `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 60_000);
+
+for await (const event of client.events.subscribe({ type: "mail.received", signal: controller.signal })) {
+  // loop exits normally when aborted
+}
+```
+
+### Event types
+
+| Type | Payload |
+| --- | --- |
+| `mail.received` | `messageId`, `threadId`, `from`, `subject` |
+| `mail.sent` | `messageId`, `threadId` |
+| `mail.delivered` | `messageId`, `threadId`, `detail?` |
+| `mail.bounced` | `messageId`, `threadId`, `detail?` |
+| `mail.complained` | `messageId`, `threadId`, `detail?` |
+| `a2a.task.created` | `taskId`, `callerIdentityId`, `message` |
+| `a2a.task.updated` | `taskId`, `state`, `result` |
+
+Unknown types stay representable — a newer server can emit events this SDK version hasn't been
+taught yet, and they arrive with a `Record<string, unknown>` payload rather than failing.
+
+## Errors
+
+Two error types, so you can tell "the server rejected this" apart from "I never reached the
+server" — they need different fixes.
+
+```ts
+import { AidApiError, AidConnectionError } from "@agentidentity/sdk";
+
+try {
+  await client.mail.send({ /* … */ });
+} catch (err) {
+  if (err instanceof AidApiError) {
+    err.status;    // 429 — the API responded
+    err.code;      // "rate_limit.exceeded"
+    err.requestId; // pass this to support
+    err.retryable; // whether trying again could work
+  } else if (err instanceof AidConnectionError) {
+    err.method;    // "POST" — the request never got there
+    err.url;
+    err.timedOut;  // deadline elapsed, vs. connection refused/DNS failure
+    err.cause;     // the underlying transport error
+  }
+}
+```
+
+Cancelling via an `AbortSignal` throws the usual `AbortError` untouched, so signal-based control
+flow keeps working.
+
+## Timeouts and retries
+
+Requests time out after 30s and retry twice by default:
+
+```ts
+const client = new AgentClient({ baseUrl, apiKey, timeoutMs: 10_000, maxRetries: 5 });
+```
+
+Retries cover rate limits (429), errors the server marks `retryable`, and — for idempotent
+methods only — network failures and 5xx. A `POST` that fails mid-flight is never replayed
+automatically, since it may already have been applied: that's the difference between a retry and
+a duplicate email. `Retry-After` is honoured when the server sends it.
+
+Every call accepts an `AbortSignal` for cancellation.
+
+## Vault
+
+Secrets are sealed client-side with X25519 + AES-256-GCM. The API stores only ciphertext — your
+private key never leaves the machine that generated it:
+
+```ts
+const keypair = await client.vault.generateIdentityKey(agent.id); // private half returned once
+
+const stored = await client.vault.createSecret({
+  identityId: agent.id,
+  name: "stripe",
+  plaintext: "sk_live_…",
+});
+
+const lease = await client.vault.createLease(stored.id, { operation: "charge" });
+const { secret } = await client.vault.redeemLease(lease.leaseId, keypair);
+```
+
+Store `keypair.privateKey` yourself — it is returned exactly once and the server cannot recover it.
+
+## What else is here
+
+`client.identities`, `client.mail`, `client.events`, `client.contacts`, `client.contactRules`,
+`client.apiKeys`, `client.webhooks`, `client.domains`, `client.providerAccounts`,
+`client.a2a`, `client.vault`, `client.tunnels`, `client.status`.
+
+Full reference: <https://github.com/ALPHACOD3RS/agent-identity>. The API's own OpenAPI document
+is at `{baseUrl}/v1/openapi.json` and is authoritative for every endpoint.