@agentidentity/sdk 0.1.0 → 0.2.0

package/README.md

@@ -31,13 +31,53 @@ await client.mail.send({
 });
 ```
 
-Don't have an org yet? Bootstrap one — these run before you have a key, so they're plain
-functions rather than client methods:
+## Signing up as an agent
+
+You don't need a human to create the account. An agent can register itself, and the human only
+has to read a code out of their inbox.
+
+```ts
+import { createOrganization, verifyOwner, AgentClient } from "@agentidentity/sdk";
+
+const BASE = "https://api.agent-identity.dev";
+
+// 1. Register. Unauthenticated — no form, no card. Naming an owner emails them a 6-digit code.
+const org = await createOrganization(BASE, {
+  name: "Acme Support",
+  slug: "acme-support",
+  ownerEmail: "you@acme.com",
+});
+
+org.adminApiKey;           // returned exactly once — store it now
+org.verificationRequired;  // true: a code is waiting in that inbox
+org.nextStep;              // what to do, in words you can show a human
+
+// 2. Ask the human for the code, then return it.
+await verifyOwner(BASE, org.adminApiKey, "481923");
+
+// 3. Give yourself an identity with a real mailbox.
+const admin = new AgentClient({ baseUrl: BASE, apiKey: org.adminApiKey });
+const me = await admin.identities.create({ handle: "support", displayName: "Support Agent" });
+me.mailboxAddress;         // support@…
+
+// 4. Mint a key that acts as *you* rather than as the whole organization.
+const key = await admin.apiKeys.create({ name: "self", identityId: me.id });
+const self = new AgentClient({ baseUrl: BASE, apiKey: key.key });
+```
+
+**Before verification** the organization may only email its own owner, a few messages a day.
+Sending anywhere else fails with `AidApiError`, code `mail.unverified_recipient`. That's what
+makes open signup safe: an unverified organization cannot reach a stranger at all.
+
+The code expires in 15 minutes and allows 5 wrong guesses. Verifying an already-verified
+organization is a no-op rather than an error, so retrying is safe.
+
+Signing up as a human instead — with an email and password, already verified:
 
 ```ts
-import { signUp, logIn, createOrganization } from "@agentidentity/sdk";
+import { signUp, logIn } from "@agentidentity/sdk";
 
-const session = await signUp("https://api.agent-identity.dev", {
+const session = await signUp(BASE, {
   orgName: "Acme",
   orgSlug: "acme",
   email: "you@acme.com",

package/dist/client.d.ts

@@ -223,12 +223,26 @@ export interface SubscribeInput<T extends AidEventType | string = string> extend
 export interface CreateOrganizationInput {
     name: string;
     slug: string;
+    /**
+     * The human who owns this organization. Naming one emails them a six-digit code; returning it
+     * through {@link verifyOwner} lifts the restrictions an unverified organization runs under.
+     *
+     * Without it the organization stays unverified: a few messages a day, and no way to prove a
+     * human is behind it.
+     */
+    ownerEmail?: string;
 }
 export interface OrganizationBootstrap {
     id: string;
     slug: string;
     name: string;
+    /** Returned exactly once. There is no endpoint that will show it again. */
     adminApiKey: string;
+    ownerEmail: string | null;
+    /** True when a code has been emailed and the organization is waiting for it. */
+    verificationRequired: boolean;
+    /** What to do next, in words you can act on or show to a human. */
+    nextStep: string;
 }
 export interface WhoAmI {
     actorType: string;
@@ -562,6 +576,23 @@ export interface CreateTunnelInput {
     hostname?: string;
 }
 export declare function createOrganization(baseUrl: string, input: CreateOrganizationInput, fetchImpl?: typeof fetch): Promise<OrganizationBootstrap>;
+/**
+ * Completes signup by returning the six-digit code emailed to the organization's owner.
+ *
+ * Until this succeeds the organization may only email that owner, and only a few times a day.
+ * Any key belonging to the organization can call it — the secret is the code, which reaches the
+ * human's inbox, so the agent that started the flow can also finish it.
+ *
+ * ```ts
+ * const org = await createOrganization(baseUrl, { name, slug, ownerEmail: "you@example.com" });
+ * // ask the human for the code that just arrived, then:
+ * await verifyOwner(baseUrl, org.adminApiKey, code);
+ * ```
+ */
+export declare function verifyOwner(baseUrl: string, apiKey: string, code: string, fetchImpl?: typeof fetch): Promise<{
+    verified: true;
+    orgId: string;
+}>;
 export interface SignUpInput {
     orgName: string;
     orgSlug: string;

package/dist/client.js

@@ -3,10 +3,43 @@ import { AidApiError, AidConnectionError } from "./errors.js";
 export { AidApiError, AidConnectionError } from "./errors.js";
 export async function createOrganization(baseUrl, input, fetchImpl = fetch) {
     const body = await sendRequest(fetchImpl, baseUrl, "POST", "/v1/organizations", {
-        body: { name: input.name, slug: input.slug },
+        body: {
+            name: input.name,
+            slug: input.slug,
+            ...(input.ownerEmail !== undefined ? { owner_email: input.ownerEmail } : {}),
+        },
+    });
+    const b = body;
+    return {
+        id: b.id,
+        slug: b.slug,
+        name: b.name,
+        adminApiKey: b.admin_api_key,
+        ownerEmail: b.owner_email ?? null,
+        verificationRequired: Boolean(b.verification_required),
+        nextStep: b.next_step ?? "",
+    };
+}
+/**
+ * Completes signup by returning the six-digit code emailed to the organization's owner.
+ *
+ * Until this succeeds the organization may only email that owner, and only a few times a day.
+ * Any key belonging to the organization can call it — the secret is the code, which reaches the
+ * human's inbox, so the agent that started the flow can also finish it.
+ *
+ * ```ts
+ * const org = await createOrganization(baseUrl, { name, slug, ownerEmail: "you@example.com" });
+ * // ask the human for the code that just arrived, then:
+ * await verifyOwner(baseUrl, org.adminApiKey, code);
+ * ```
+ */
+export async function verifyOwner(baseUrl, apiKey, code, fetchImpl = fetch) {
+    const body = await sendRequest(fetchImpl, baseUrl, "POST", "/v1/auth/verify", {
+        headers: { authorization: `Bearer ${apiKey}` },
+        body: { code },
     });
     const b = body;
-    return { id: b.id, slug: b.slug, name: b.name, adminApiKey: b.admin_api_key };
+    return { verified: true, orgId: b.org_id };
 }
 function toAuthSession(body) {
     const b = body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentidentity/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript client for Agent Identity \u2014 give an agent its own email address, durable event stream, and encrypted secret vault.",
   "license": "MIT",
   "keywords": [