@9in-io/sdk 0.1.1 → 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,9 +88,10 @@ 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", "+447700900000"); // or "email", "username"
+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);
@@ -101,9 +102,16 @@ await nine.revokeUserSessions(userId);
 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", passwordHash: "$2b$10$…" }], { onConflict: "skip", source: "auth0" });
+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
@@ -123,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
     },
   }),
 };
@@ -144,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/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,42 +94,73 @@ 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 ms since epoch. */
+/** An active sign-in session (`sid` is the `sid` claim of its tokens). Times are ISO 8601 UTC strings. */
 export interface ManagedSession {
     sid: string;
-    userId: string;
-    authTime: number;
+    user_id: string;
+    auth_time: string;
     amr: string[];
     ip: string;
-    userAgent: string;
-    createdAt: number;
-    lastSeenAt: number;
-    expiresAt: number;
-    revokedAt: number | null;
+    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;
-    emailVerified?: boolean;
+    email_verified?: boolean;
     /** E.164, e.g. +447700900000. */
-    phone?: string | null;
-    phoneVerified?: boolean;
+    phone_number?: string | null;
+    phone_number_verified?: boolean;
     username?: string | null;
     name?: string | null;
     given_name?: string | null;
@@ -140,21 +171,21 @@ export interface ImportUser {
     birthdate?: string | null;
     metadata?: Record<string, unknown>;
     blocked?: boolean;
-    /** A plain password (at most 50 such records per call), or `passwordHash` from your old system. */
+    /** 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. */
-    passwordHash?: string;
+    password_hash?: string;
     /** Linked sign-ins, e.g. { connection: "social:google", subject: "1069…" }. */
     identities?: {
         connection: string;
         subject: string;
     }[];
-    /** ms since epoch */
-    createdAt?: number;
-    lastLoginAt?: number;
+    /** Original dates, ISO 8601 (`Z` or an offset). */
+    created_at?: string;
+    last_login_at?: string;
 }
-/** Fields of a new user (`createUser`, `updateUser`). */
-export type NewUser = Omit<ImportUser, "id" | "identities" | "createdAt" | "lastLoginAt">;
+/** 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;
@@ -185,16 +216,16 @@ export declare class ManagementClient {
         limit?: number;
     }): Promise<{
         users: ManagedUser[];
-        nextCursor: string | null;
-    }>;
-    getUser(id: string): Promise<{
-        user: ManagedUser;
+        next_cursor: string | null;
+        total: number;
     }>;
+    /** The user with their identities, active sessions and two-factor state. */
+    getUser(id: string): Promise<ManagedUserDetail>;
     findUserByEmail(email: string): Promise<{
         user: ManagedUser;
     }>;
-    /** Looks a user up by email, phone (E.164) or username; throws `not_found` (404) when unknown. */
-    findUser(type: "email" | "phone" | "username", value: 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: NewUser): Promise<{
@@ -211,7 +242,8 @@ export declare class ManagementClient {
     }): Promise<{
         results: ImportResult[];
     }>;
-    updateUser(id: string, input: Record<string, unknown>): Promise<{
+    /** 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>;
@@ -228,7 +260,7 @@ 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<{
@@ -262,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. */
@@ -291,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;
     };
 }
@@ -314,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,13 +290,14 @@ 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.findUser("email", email);
     }
-    /** Looks a user up by email, phone (E.164) or username; throws `not_found` (404) when unknown. */
+    /** 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)}`);
     }
@@ -314,6 +316,7 @@ export class ManagementClient {
             ...(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);
     }
@@ -386,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.1",
+  "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",