@9in-io/sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.2.0
+
+Breaking: 9in's wire formats are now snake_case throughout, with ISO 8601 UTC times
+(see "API conventions" in the docs). Needs the 9in release of 2026-11-10.
+
+- `WebhookEvent`: `type` → `event_type`, `createdAt` → `created_at`; `data.userId` is gone, use
+  `data.user.id`. For `user.deleted`, `data.user` is the user as it was before the deletion.
+  `token.revoked` data has `token_type` and `client_id`.
+- `ManagedUser`: `created_at`, `updated_at`, `last_login_at` (ISO strings), `login_count`,
+  and every profile field.
+- `ManagedSession`: `user_id`, `auth_time`, `user_agent`, `created_at`, `last_seen_at`,
+  `expires_at` (ISO strings); `revokedAt` removed.
+- `getUser` returns `ManagedUserDetail` (`user`, `identities`, `sessions`, `has_password`,
+  `mfa`); `listUsers` returns `next_cursor`.
+- `NewUser` / `ImportUser`: `email_verified`, `phone_number`, `phone_number_verified`,
+  `password_hash`, and ISO `created_at` / `last_login_at`. The server refuses the old names.
+- `findUser("phone_number", …)` replaces `findUser("phone", …)`.
+- `createLoginLink` returns `expires_at` as an ISO string.
+- `AdapterEvent`: `event_type`, `created_at`, and `data.user_id` / `data.expires_at`.
+- `TokenVerifier.handleEvent` reads the new webhook shape.
+- The package ships `src/` too, so the `@9in/source` export condition resolves (0.1.x listed
+  it without shipping the files, which broke bundlers configured with that condition).

package/README.md

@@ -88,14 +88,30 @@ webhook events, or a short `cacheTtl`.
 import { ManagementClient } from "@9in-io/sdk/server";
 
 const nine = new ManagementClient({ issuer, clientId, clientSecret }); // app with management scopes
-await nine.createUser({ email: "jane@acme.com", password: "…", emailVerified: true });
+await nine.createUser({ email: "jane@acme.com", password: "…", email_verified: true });
+await nine.updateUser(userId, { phone_number: "+447700900000", phone_number_verified: true });
 await nine.blockUser(userId);
+const { user } = await nine.findUser("phone_number", "+447700900000"); // or "email", "username"
+
+// Sessions: list them, end one (its sid), or sign the user out everywhere
+const { sessions } = await nine.listUserSessions(userId);
+await nine.revokeSession(sessions[0].sid);
 await nine.revokeUserSessions(userId);
 
 // Single-use sign-in link (magic links, moving a signed-in user from your app to 9in)
 const { url } = await nine.createLoginLink(userId, { returnTo: "https://app.acme.com/callback", ttlSeconds: 600 });
+
+// Bulk import (500 per call): old ids, password hashes (bcrypt, argon2, PBKDF2, Firebase scrypt), social identities
+const { results } = await nine.importUsers(
+  [{ id: "auth0|42", email: "jane@acme.com", password_hash: "$2b$10$…", created_at: "2021-03-04T05:06:07Z" }],
+  { onConflict: "skip", source: "auth0" },
+);
 ```
 
+Users, sessions and requests use snake_case field names, the same going in and coming out
+(`email_verified`, `phone_number`, `password_hash`), and times are ISO 8601 UTC strings
+(`created_at`, `last_login_at`). Method options stay camelCase (`returnTo`, `onConflict`).
+
 ## Keep users in your own database (adapter)
 
 ```ts
@@ -115,7 +131,8 @@ export default {
       return user ? toAdapterUser(user) : null;
     },
     async onEvent(event) {
-      if (event.type === "otp.requested") await sendCode(event.data);
+      // { id, event_type, created_at, data }; data.user_id is your own user id
+      if (event.event_type === "otp.requested") await sendCode(event.data); // user_id, channel, to, code, purpose, expires_at
     },
   }),
 };
@@ -136,8 +153,9 @@ import { verifyWebhook } from "@9in-io/sdk/server";
 export default {
   async fetch(request: Request, env: { NINE_WEBHOOK_SECRET: string }) {
     const event = await verifyWebhook(env.NINE_WEBHOOK_SECRET, request);
-    // event.id is the same on every retry and redelivery: ignore ones you have seen.
-    if (event.type === "user.created") await addToCrm(event.data.user);
+    // { id, event_type, created_at, tenant, environment, data }. event.id is the same on every
+    // retry and redelivery: ignore ones you have seen. data.user is the user the event is about.
+    if (event.event_type === "user.created") await addToCrm(event.data.user);
     return new Response(null, { status: 204 });
   },
 };

package/dist/index.js

@@ -107,17 +107,24 @@ export class NineAuth {
             throw new NineError("invalid_issuer", `unexpected issuer ${iss}`);
         const config = await discover(this.issuer, this.fetcher);
         const tokens = await postForm(config.token_endpoint, { grant_type: "authorization_code", code, redirect_uri: this.options.redirectUri, client_id: this.options.clientId, code_verifier: pending.verifier }, {}, this.fetcher);
-        const set = this.store(tokens);
-        if (set.idToken) {
+        if (typeof tokens.id_token === "string") {
             // The ID token came straight from the token endpoint over TLS (OIDC Core 3.1.3.7):
             // its claims are checked; the signature check is for servers (verifyAccessToken).
-            const { payload } = decodeJwt(set.idToken);
+            // Checked before anything is stored, so a refused sign-in leaves no tokens behind.
+            let payload;
+            try {
+                payload = decodeJwt(tokens.id_token).payload;
+            }
+            catch {
+                throw new NineError("invalid_id_token", "malformed ID token");
+            }
             const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
             if (!aud.includes(this.options.clientId))
                 throw new NineError("invalid_id_token", "audience mismatch");
             if (payload.nonce !== pending.nonce)
                 throw new NineError("invalid_id_token", "nonce mismatch");
         }
+        this.store(tokens);
         if (typeof window !== "undefined" && window.history && url === window.location.href) {
             for (const p of ["code", "state", "iss", "session_state"])
                 current.searchParams.delete(p);

package/dist/server.d.ts

@@ -69,7 +69,7 @@ export interface TokenVerifier {
      * user.sessions_revoked, user.updated and user.deleted).
      */
     handleEvent(event: {
-        type: string;
+        event_type: string;
         data: Record<string, unknown>;
     }): number;
     /** Forgets every cached answer. */
@@ -94,20 +94,113 @@ export interface ManagementOptions {
     allowInsecureIssuer?: boolean;
     fetch?: typeof fetch;
 }
+/** A user as the Management API and webhooks send it. Times are ISO 8601 UTC strings. */
 export interface ManagedUser {
     id: string;
     email: string | null;
     email_verified: boolean;
     phone_number: string | null;
+    phone_number_verified: boolean;
     username: string | null;
+    preferred_username: string | null;
     name: string | null;
+    given_name: string | null;
+    middle_name: string | null;
+    family_name: string | null;
+    nickname: string | null;
+    gender: string | null;
+    website: string | null;
     picture: string | null;
+    locale: string | null;
+    zoneinfo: string | null;
+    birthdate: string | null;
     blocked: boolean;
     metadata: Record<string, unknown>;
-    createdAt: number;
-    lastLoginAt: number | null;
-    [field: string]: unknown;
+    created_at: string;
+    updated_at: string;
+    last_login_at: string | null;
+    login_count: number;
 }
+/** An active sign-in session (`sid` is the `sid` claim of its tokens). Times are ISO 8601 UTC strings. */
+export interface ManagedSession {
+    sid: string;
+    user_id: string;
+    auth_time: string;
+    amr: string[];
+    ip: string;
+    user_agent: string;
+    created_at: string;
+    last_seen_at: string;
+    expires_at: string;
+}
+/** A linked sign-in of a user (`social:google`, `enterprise:<id>`, `adapter`, …). */
+export interface ManagedIdentity {
+    connection: string;
+    subject: string;
+    profile: Record<string, unknown>;
+    created_at: string;
+}
+/** `getUser`: the user with their identities, active sessions and two-factor state. */
+export interface ManagedUserDetail {
+    user: ManagedUser;
+    identities: ManagedIdentity[];
+    sessions: ManagedSession[];
+    has_password: boolean;
+    mfa: {
+        enabled: boolean;
+        enabled_at?: string;
+        recovery_codes_left?: number;
+    };
+}
+/** One record for `importUsers`: the fields of `createUser` plus what an import may carry over. */
+export interface ImportUser {
+    /** Keep the id from your old system (letters, digits and | _ . : @ + -, max 128). */
+    id?: string;
+    email?: string | null;
+    email_verified?: boolean;
+    /** E.164, e.g. +447700900000. */
+    phone_number?: string | null;
+    phone_number_verified?: boolean;
+    username?: string | null;
+    name?: string | null;
+    given_name?: string | null;
+    family_name?: string | null;
+    picture?: string | null;
+    locale?: string | null;
+    zoneinfo?: string | null;
+    birthdate?: string | null;
+    metadata?: Record<string, unknown>;
+    blocked?: boolean;
+    /** A plain password (at most 50 such records per call), or `password_hash` from your old system. */
+    password?: string;
+    /** bcrypt, argon2, PBKDF2 or Firebase scrypt hash: users keep their password. */
+    password_hash?: string;
+    /** Linked sign-ins, e.g. { connection: "social:google", subject: "1069…" }. */
+    identities?: {
+        connection: string;
+        subject: string;
+    }[];
+    /** Original dates, ISO 8601 (`Z` or an offset). */
+    created_at?: string;
+    last_login_at?: string;
+}
+/** Fields of a new user (`createUser`); `updateUser` takes any of them. */
+export type NewUser = Omit<ImportUser, "id" | "identities" | "created_at" | "last_login_at">;
+export type ImportResult = {
+    index: number;
+    ok: boolean;
+} & ({
+    status: "created" | "updated";
+    id: string;
+} | {
+    status: "skipped";
+    id: string;
+    reason: string;
+} | {
+    status: "failed";
+    error: string;
+    details?: unknown;
+});
 export declare class ManagementClient {
     private readonly options;
     /** One token per scope: each call asks only for what it needs, so an app granted some scopes works. */
@@ -123,26 +216,34 @@ export declare class ManagementClient {
         limit?: number;
     }): Promise<{
         users: ManagedUser[];
-        nextCursor: string | null;
+        next_cursor: string | null;
+        total: number;
     }>;
-    getUser(id: string): Promise<{
+    /** The user with their identities, active sessions and two-factor state. */
+    getUser(id: string): Promise<ManagedUserDetail>;
+    findUserByEmail(email: string): Promise<{
         user: ManagedUser;
     }>;
-    findUserByEmail(email: string): Promise<{
+    /** Looks a user up by email, phone number (E.164) or username; throws `not_found` (404) when unknown. */
+    findUser(type: "email" | "phone_number" | "username", value: string): Promise<{
         user: ManagedUser;
     }>;
-    createUser(input: {
-        email?: string;
-        phone?: string;
-        username?: string;
-        password?: string;
-        name?: string;
-        emailVerified?: boolean;
-        metadata?: Record<string, unknown>;
-    }): Promise<{
+    createUser(input: NewUser): Promise<{
         user: ManagedUser;
     }>;
-    updateUser(id: string, input: Record<string, unknown>): Promise<{
+    /**
+     * Bulk import, up to 500 users per call. Records may keep their old id and carry password
+     * hashes (bcrypt, argon2, PBKDF2, Firebase scrypt), social identities and original dates.
+     * Results are per record, in order; one bad record does not stop the others.
+     */
+    importUsers(users: ImportUser[], options?: {
+        onConflict?: "skip" | "update";
+        source?: string;
+    }): Promise<{
+        results: ImportResult[];
+    }>;
+    /** Changes only the fields you send; `metadata` is replaced as a whole. */
+    updateUser(id: string, input: Partial<NewUser>): Promise<{
         user: ManagedUser;
     }>;
     deleteUser(id: string): Promise<void>;
@@ -159,11 +260,18 @@ export declare class ManagementClient {
         ttlSeconds?: number;
     }): Promise<{
         url: string;
-        expires_at: number;
+        expires_at: string;
     }>;
+    /** The user's active sessions, most recently used first. */
+    listUserSessions(id: string): Promise<{
+        sessions: ManagedSession[];
+    }>;
+    /** Signs the user out everywhere; returns how many sessions ended. */
     revokeUserSessions(id: string): Promise<{
         revoked: number;
     }>;
+    /** Ends one session (its `sid`) and every token issued under it. */
+    revokeSession(sid: string): Promise<void>;
 }
 export interface AdapterIdentifier {
     type: "email" | "username" | "phone";
@@ -186,11 +294,20 @@ export interface AdapterUser {
     blocked?: boolean | null;
     metadata?: Record<string, unknown> | null;
 }
+/**
+ * What 9in POSTs to `…/event`. `data.user_id` is your own user id. `otp.requested` carries
+ * `user_id, channel, to, code, purpose, expires_at`; `user.updated` and
+ * `user.password_changed` carry `user_id, fields`.
+ */
 export interface AdapterEvent {
     id: string;
-    type: "otp.requested" | "user.created" | "user.updated" | "user.password_changed" | "session.revoked";
-    createdAt: string;
-    data: Record<string, unknown>;
+    event_type: "otp.requested" | "user.created" | "user.updated" | "user.password_changed" | "session.revoked";
+    /** ISO 8601 UTC. */
+    created_at: string;
+    data: {
+        user_id?: string;
+        [field: string]: unknown;
+    };
 }
 export interface AdapterHandlers {
     /** Shared secret from the console (Connections → User database). Several allow rotation. */
@@ -215,14 +332,18 @@ export type WebhookEventType = "user.created" | "user.updated" | "user.deleted"
 export interface WebhookEvent<Data extends Record<string, unknown> = Record<string, unknown>> {
     /** Event id: the same on every retry and redelivery, so you can ignore duplicates. */
     id: string;
-    type: WebhookEventType;
-    createdAt: string;
+    /** The event name, also in the `9in-event-type` header. */
+    event_type: WebhookEventType;
+    /** ISO 8601 UTC. */
+    created_at: string;
     /** Tenant id (tnt_…). */
     tenant: string;
     environment: "production" | "sandbox";
-    /** Event details, plus `userId` and a `user` snapshot (null once deleted) for user events. */
+    /**
+     * Event details, plus the `user` the event is about (null when there is none; for
+     * `user.deleted`, the user as it was just before the deletion).
+     */
     data: Data & {
-        userId?: string | null;
         user?: ManagedUser | null;
     };
 }
@@ -238,7 +359,7 @@ export interface VerifyWebhookOptions {
  * the body, so pass `request.clone()` if you need it afterwards.
  *
  *   const event = await verifyWebhook(env.NINE_WEBHOOK_SECRET, request);
- *   if (event.type === "user.created") …
+ *   if (event.event_type === "user.created") …
  */
 export declare function verifyWebhook(secret: string | string[], request: Request, options?: VerifyWebhookOptions): Promise<WebhookEvent>;
 /**

package/dist/server.js

@@ -221,13 +221,14 @@ export function createTokenVerifier(options) {
         },
         handleEvent(event) {
             const data = event.data ?? {};
+            const userId = data.user?.id;
             let match = null;
-            if (event.type === "token.revoked" && data.type === "access_token" && data.jti)
+            if (event.event_type === "token.revoked" && data.token_type === "access_token" && data.jti)
                 match = (c) => c.jti === data.jti;
-            else if (event.type === "session.revoked" && data.sid)
+            else if (event.event_type === "session.revoked" && data.sid)
                 match = (c) => c.sid === data.sid;
-            else if (["user.sessions_revoked", "user.deleted", "user.updated", "user.password_changed"].includes(event.type) && data.userId) {
-                match = (c) => c.sub === data.userId;
+            else if (["user.sessions_revoked", "user.deleted", "user.updated", "user.password_changed"].includes(event.event_type) && typeof userId === "string") {
+                match = (c) => c.sub === userId;
             }
             if (!match)
                 return 0;
@@ -289,15 +290,33 @@ export class ManagementClient {
             params.set("limit", String(options.limit));
         return this.request("GET", `/users?${params}`);
     }
+    /** The user with their identities, active sessions and two-factor state. */
     getUser(id) {
         return this.request("GET", `/users/${encodeURIComponent(id)}`);
     }
     findUserByEmail(email) {
-        return this.request("GET", `/users/lookup?email=${encodeURIComponent(email)}`);
+        return this.findUser("email", email);
+    }
+    /** Looks a user up by email, phone number (E.164) or username; throws `not_found` (404) when unknown. */
+    findUser(type, value) {
+        return this.request("GET", `/users/lookup?${type}=${encodeURIComponent(value)}`);
     }
     createUser(input) {
         return this.request("POST", "/users", input);
     }
+    /**
+     * Bulk import, up to 500 users per call. Records may keep their old id and carry password
+     * hashes (bcrypt, argon2, PBKDF2, Firebase scrypt), social identities and original dates.
+     * Results are per record, in order; one bad record does not stop the others.
+     */
+    importUsers(users, options = {}) {
+        return this.request("POST", "/users/import", {
+            users,
+            ...(options.onConflict ? { on_conflict: options.onConflict } : {}),
+            ...(options.source ? { source: options.source } : {}),
+        });
+    }
+    /** Changes only the fields you send; `metadata` is replaced as a whole. */
     updateUser(id, input) {
         return this.request("PATCH", `/users/${encodeURIComponent(id)}`, input);
     }
@@ -318,9 +337,18 @@ export class ManagementClient {
             ...(options.ttlSeconds ? { ttl_seconds: options.ttlSeconds } : {}),
         });
     }
+    /** The user's active sessions, most recently used first. */
+    listUserSessions(id) {
+        return this.request("GET", `/users/${encodeURIComponent(id)}/sessions`);
+    }
+    /** Signs the user out everywhere; returns how many sessions ended. */
     revokeUserSessions(id) {
         return this.request("DELETE", `/users/${encodeURIComponent(id)}/sessions`);
     }
+    /** Ends one session (its `sid`) and every token issued under it. */
+    revokeSession(sid) {
+        return this.request("DELETE", `/sessions/${encodeURIComponent(sid)}`);
+    }
 }
 const SIGNATURE_HEADER = "9in-signature";
 async function hmac(secret, payload) {
@@ -361,7 +389,7 @@ export async function signPayload(secret, method, path, body) {
  * the body, so pass `request.clone()` if you need it afterwards.
  *
  *   const event = await verifyWebhook(env.NINE_WEBHOOK_SECRET, request);
- *   if (event.type === "user.created") …
+ *   if (event.event_type === "user.created") …
  */
 export async function verifyWebhook(secret, request, options = {}) {
     const body = await request.text();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@9in-io/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official 9in SDK: browser sign-in with PKCE, token verification, Management API client and adapter handler. Zero dependencies; runs in browsers, Node 18+, Cloudflare Workers, Deno and Bun.",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "src",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "oauth",