@softwarepatterns/am 0.0.1 → 0.1.0

package/dist/types/auth.d.ts

@@ -1,5 +1,58 @@
-import type { AuthenticationResult, ClientId, EmailCheckStatus, LoginMethod, ProblemDetails, SessionProfile, SessionTokens, UserId, UserResource } from "./types";
+import type { Authentication, ClientId, EmailCheckStatus, LoginMethod, ProblemDetails, SessionProfile, SessionTokens, StorageLike } from "./types";
+type StorageConfig = StorageLike | "localStorage" | null | undefined;
 type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type Config = {
+    baseUrl: string;
+    earlyRefreshMs: number;
+    fetchFn: FetchFn;
+    profileStorageKey: string;
+    storage: StorageConfig;
+    tokensStorageKey: string;
+};
+type AuthEventMap = {
+    refresh: SessionTokens;
+    profileChange: SessionProfile;
+    unauthenticated: AuthError;
+    sessionChange: AuthSession | null;
+};
+/**
+ * AuthError represents structured authentication failures from Accountmaker endpoints.
+ *
+ * AuthError wraps RFC 7807 Problem Details. invalidParams may be present for field-level validation.
+ * Network failures throw other error types.
+ *
+ * Also note that the `type` field often contains a URI that points to documentation about the
+ * specific error type, including how to resolve it, code samples, and links to the RFCs or other
+ * standards that define the error.
+ *
+ * @example
+ * ```ts
+ * try {
+ *  const session = await am.signIn({ email: 'test@example.com', password: 'password123' });
+ * } catch (e) {
+ *  if (e instanceof AuthError) {
+ *   console.error("Authentication failed:", e.title);
+ *   if (e.invalidParams) {
+ *    for (const param of e.invalidParams) {
+ *      console.error(` - Invalid parameter: ${param.path} (${param.type})`);
+ *     }
+ *    }
+ *   } else {
+ *    console.error("Unexpected error:", e);
+ *   }
+ * }
+ * ```
+ *
+ * Note that HTTP error codes are distinctly:
+ * - 400: Client error (bad request, invalid input, etc.)
+ * - 401: Unauthenticated (we don't know who you are)
+ * - 402: Payment required (e.g. billing issue)
+ * - 403: Unauthorized (we know who you are, but you don't have permission)
+ * - 404: Not found
+ * - 409: Conflict (email already registered, user already invited, etc.)
+ * - 429: Too many requests (rate limiting)
+ * - 500: Internal server error (server's fault)
+ */
 export declare class AuthError extends Error {
     readonly problem: ProblemDetails;
     constructor(problem: ProblemDetails);
@@ -10,57 +63,140 @@ export declare class AuthError extends Error {
     get detail(): string | undefined;
     get invalidParams(): ProblemDetails["invalidParams"] | undefined;
 }
-type Config = {
-    fetchFn: FetchFn;
-    baseUrl: string;
-};
+/**
+ * AuthSession represents an authenticated user with automatic token refresh and persisted state.
+ *
+ * AuthSession owns tokens, profile data, refresh logic, and authenticated requests.
+ */
 export declare class AuthSession {
-    private tokens;
-    private config;
-    private lastUpdated;
-    constructor(tokens: SessionTokens, config: Partial<Config>);
-    get accessToken(): string;
-    get refreshToken(): string;
-    get idToken(): string | undefined;
-    get tokenType(): "Bearer";
-    get expiresIn(): number;
-    get lastUpdatedAt(): Date;
-    get expiresAt(): Date;
+    constructor(initial: Authentication, config: Partial<Config>);
+    /**
+     * Removes all persisted data (tokens, profile) from storage, and prevents future
+     * refreshes of token and profile data. Does NOT clear current token or profile data from the
+     * session memory, but effectively deactivates the session for future use.
+     */
+    clear(): void;
+    get tokens(): SessionTokens;
+    get profile(): SessionProfile;
+    toJSON(): Authentication;
+    /**
+     * Creates an AuthSession from existing authentication data. Useful for restoring
+     * a session from custom storage or creating a session from custom server-provided data.
+     */
+    static fromJSON(initial: Authentication, config: Partial<Config>): AuthSession;
+    /**
+     * Returns true if the access token is expired or will expire soon. The
+     * "soon" threshold is configured via Config.earlyRefreshMs (default 1 minute).
+     */
     isExpired(): boolean;
     /**
-     * Fetch with automatic token refresh.
+     * Performs standard fetch() with a Bearer token and automatic refresh.
+     *
+     * Returns Response, does not parse the body, does not throw for HTTP status codes.
+     * Throws AuthError when refresh fails, trows runtime errors on network failure.
+     *
+     * @example
+     * ```ts
+     * const res = await session.fetch("/api/projects");
+     * const projects = await res.json();
+     * ```
+     *
+     * Any service can validate tokens using:
+     * https://api.accountmaker.com/.well-known/jwks.json?client_id={clientId}
+     */
+    fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Replaces the access token using the refresh token.
      *
-     * If the access token is expired, it will be refreshed before making the request. The
-     * Authorization header will be set with the current access token.
+     * It is called automatically by all other methods when the access token is expired or near expiry.
      */
-    fetch(url: string | URL | Request, init?: RequestInit): Promise<Response>;
     refresh(): Promise<void>;
+    /**
+     * refetchProfile() replaces the cached profile with server state.
+     *
+     * Concurrent calls are deduplicated.
+     *
+     * @example
+     * ```ts
+     * await session.refetchProfile();
+     * console.log("Updated profile:", session.profile);
+     * ```
+     *
+     * Throws AuthError on network errors, etc.
+     * @throws AuthError
+     */
+    refetchProfile(): Promise<void>;
+    /**
+     * Requests a verification email for the current user.
+     *
+     * Throws AuthError on network errors, etc.
+     * @throws AuthError
+     */
     sendVerificationEmail(): Promise<void>;
-    me(): Promise<SessionProfile>;
-    user(id: UserId): Promise<UserResource>;
 }
+/**
+ * Am runs authentication flows and produces AuthSession.
+ *
+ * Use Am before a session exists (sign-in, sign-up, magic link, invites, password reset, CSRF).
+ *
+ * @example
+ * ```ts
+ * const am = new Am();
+ * const session = await am.signIn({ email: 'user@example.com', password: 'secret' });
+ * // Now use `session` for protected API calls
+ * ```
+ */
 export declare class Am {
-    private options;
     constructor(config?: Partial<Config>);
-    static createAuthSession(tokens: SessionTokens, config?: Partial<Config>): AuthSession;
-    createAuthSession(tokens: SessionTokens): AuthSession;
-    static acceptInvite(query: {
-        clientId: ClientId;
-        token: string;
-    }, config?: Partial<Config>): Promise<AuthenticationResult>;
+    /**
+     * session returns the current AuthSession or null.
+     *
+     * Use restoreSession() to load from storage.
+     *
+     * @example
+     * ```ts
+     * const session = am.session;
+     * if (!session) throw new Error("Not authenticated");
+     * ```
+     */
+    get session(): AuthSession | null;
+    /**
+     * Constructs AuthSession from existing tokens and profile.
+     *
+     * Use this after a server-side auth handshake or custom persistence.
+     */
+    createSession(initial: Authentication): AuthSession;
+    /**
+     * restoreSession loads AuthSession from storage or returns null.
+     *
+     * Invalid or partial stored data is cleared.
+     *
+     * @example
+     * ```ts
+     * const am = new Am({ storage: 'localStorage' });
+     * const session = am.restoreSession();
+     * if (session) session.fetch("/api/me");
+     * ```
+     */
+    restoreSession(): AuthSession | null;
+    /**
+     * Subscribes to auth events and returns an unsubscribe function.
+     */
+    on<K extends keyof AuthEventMap>(event: K, fn: (v: AuthEventMap[K]) => void): () => boolean;
+    /**
+     * acceptInvite exchanges an invite token for a fresh AuthSession.
+     *
+     * Throws AuthError on invalid, expired, or already-used tokens.
+     */
     acceptInvite(query: {
         clientId: ClientId;
         token: string;
-    }): Promise<AuthenticationResult>;
-    static checkEmail(body: {
-        clientId: ClientId;
-        email: string;
-        csrfToken?: string;
-    }, config?: Partial<Config>): Promise<{
-        status: EmailCheckStatus;
-        preferred: LoginMethod[];
-        available: LoginMethod[];
-    }>;
+    }): Promise<AuthSession>;
+    /**
+     * checkEmail returns how an email should authenticate for this client.
+     *
+     * Use this to choose password vs magic link vs SSO before rendering a login form.
+     */
     checkEmail(body: {
         clientId: ClientId;
         email: string;
@@ -70,63 +206,70 @@ export declare class Am {
         preferred: LoginMethod[];
         available: LoginMethod[];
     }>;
-    static csrfSession(config?: Partial<Config>): Promise<{
-        csrfToken: string;
-    }>;
+    /**
+     * Sets the httpOnly CSRF cookie.
+     *
+     * Call csrfToken() next to fetch a signed token for form posts.
+     */
     csrfSession(): Promise<{
         csrfToken: string;
     }>;
-    static csrfToken(config?: Partial<Config>): Promise<{
-        csrfToken: string;
-    }>;
+    /**
+     * Returns a signed CSRF token for form posts.
+     *
+     * Call csrfSession() first to set the CSRF cookie.
+     */
     csrfToken(): Promise<{
         csrfToken: string;
     }>;
-    static login(body: {
-        email: string;
-        password: string;
-        csrfToken?: string;
-    }, config?: Partial<Config>): Promise<AuthenticationResult>;
-    login(body: {
-        email: string;
-        password: string;
-        csrfToken?: string;
-    }): Promise<AuthenticationResult>;
-    static tokenLogin(token: string, config?: Partial<Config>): Promise<AuthenticationResult>;
-    tokenLogin(token: string): Promise<AuthenticationResult>;
-    static refresh(refreshToken: string, config?: Partial<Config>): Promise<SessionTokens>;
-    refresh(refreshToken: string): Promise<SessionTokens>;
-    static register(body: {
+    /**
+     * Authenticates with email and password and returns a new AuthSession.
+     *
+     * Tokens and profile are persisted when storage is configured.
+     */
+    signIn(body: {
+        clientId: ClientId;
         email: string;
         password: string;
         csrfToken?: string;
-    }, config?: Partial<Config>): Promise<AuthenticationResult>;
-    register(body: {
+    }): Promise<AuthSession>;
+    /**
+     * Authenticates with a one-time token and returns a new AuthSession.
+     *
+     * Use this for magic links and similar one-time login flows.
+     */
+    signInWithToken(token: string): Promise<AuthSession>;
+    /**
+     * Creates a new user and returns a new AuthSession.
+     *
+     * Tokens and profile are persisted when storage is configured.
+     */
+    signUp(body: {
+        clientId: ClientId;
         email: string;
         password: string;
         csrfToken?: string;
-    }): Promise<AuthenticationResult>;
-    static resetPassword(body: {
-        token: string;
-        newPassword: string;
-    }, config?: Partial<Config>): Promise<void>;
+    }): Promise<AuthSession>;
+    /**
+     * Sets a new password using a one-time reset token.
+     */
     resetPassword(body: {
         token: string;
         newPassword: string;
     }): Promise<void>;
-    static sendMagicLink(body: {
-        email: string;
-        csrfToken?: string;
-    }, config?: Partial<Config>): Promise<void>;
+    /**
+     * Sends a one-time sign-in link to an email address.
+     */
     sendMagicLink(body: {
+        clientId: ClientId;
         email: string;
         csrfToken?: string;
     }): Promise<void>;
-    static sendPasswordReset(body: {
-        email: string;
-        csrfToken?: string;
-    }, config?: Partial<Config>): Promise<void>;
+    /**
+     * Sends a password reset link to an email address.
+     */
     sendPasswordReset(body: {
+        clientId: ClientId;
         email: string;
         csrfToken?: string;
     }): Promise<void>;

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
-export { Am, AuthSession, AuthError } from "./auth";
-export type { AuthenticationResult, ClientId, EmailCheckStatus, LoginMethod, ProblemDetails, SessionProfile, SessionTokens, UserId, UserResource, } from "./types";
+export * from "./auth";
+export * from "./types";

package/dist/types/types.d.ts

@@ -1,3 +1,34 @@
+/**
+ * Standard error object following RFC 7807 (Problem Details for HTTP APIs).
+ *
+ * Returned in AuthError.problem when the server responds with application/problem+json.
+ *
+ * - `type`: A URI reference that identifies the problem type. Often links to human-readable documentation.
+ * - `title`: A short, human-readable summary of the problem type.
+ * - `status`: The HTTP status code.
+ * - `code`: Application-specific error code for programmatic handling. Maps to the final part of the error type.
+ * - `detail`: Human-readable explanation specific to this occurrence. Do not rely on this for programmatic handling.
+ * - `invalidParams`: Present on validation errors (typically 400). Provides field-level details
+ *   for building precise UI feedback and can be used for programmatic handling. Each entry includes:
+ *   - `in`: Location of the invalid parameter (body, cookie, header, query, path).
+ *   - `path`: Dot-separated path to the invalid parameter.
+ *   - `type`: Error type code for this parameter (e.g. "required", "email", "min_length").
+ *   - `received`: The actual value received.
+ *   - `expected`: (optional) Description of the expected value.
+ *
+ * @example
+ * ```ts
+ * catch (e) {
+ *   if (e instanceof AuthError && e.invalidParams) {
+ *     const errors = e.invalidParams.reduce((acc, p) => {
+ *       acc[p.path] = p.type;
+ *       return acc;
+ *     }, {} as Record<string, string>);
+ *     setFieldErrors(errors);
+ *   }
+ * }
+ * ```
+ */
 export type ProblemDetails = {
     type: string;
     title: string;
@@ -12,36 +43,98 @@ export type ProblemDetails = {
         expected?: string;
     }[];
 };
+/**
+ * Opaque identifier for a client application.
+ *
+ * Used to look up client-specific settings on how authentication should be handled.
+ *
+ * All client-specific operations (invites, branding, rate limits) are scoped to a ClientId.
+ */
 export type ClientId = `cid${string}`;
+/** Identifier for a user. */
 export type UserId = `uid${string}`;
+/** Identifier for an account (i.e., a billable entity). */
 export type AccountId = `acc${string}`;
+/** Identifier for a membership linking a user to an account. */
 export type MembershipId = `mbr${string}`;
+/**
+ * Possible statuses for an account.
+ *
+ * - active: Normal operation
+ * - trial: In trial period
+ * - past_due: Payment failed but grace period active
+ * - suspended: Access restricted due to billing or policy
+ * - closed: Permanently closed
+ */
 export type AccountStatus = "active" | "trial" | "past_due" | "suspended" | "closed";
+/**
+ * Accounts are billable entities that can access resources. Users are linked to accounts via memberships with roles.
+ *
+ * An account with subaccounts is acting as a tenant, and is used to create services with their own billing,
+ * accounts, users, memberships, etc. This is useful for SaaS platforms that want to offer isolated environments
+ * for different customers, and to allow reselling of their services to other SaaS providers.
+ *
+ * For example, an email service lets customers sign up. However, some customers want to offer
+ * email services to their own clients. Therefore, the email provider has an account for each customer, and those
+ * customers have accounts for their own clients as well. Each level is isolated, with separate billing and users.
+ */
 export type AccountResource = {
     id: AccountId;
+    parentId: AccountId | null;
+    /** Display name chosen by the account owner */
     name: string | null;
+    /** URL to the account's avatar image */
     avatarUrl: string | null;
+    /** Current account status */
     status: AccountStatus;
+    /** ISO 8601 timestamp until which the account is paid (null if never paid or closed) */
     paidUntil: string | null;
 };
-export type UserStatus = "active" | "trial" | "past_due" | "suspended" | "closed";
+/**
+ * Possible statuses for a user.
+ *
+ * - active: Normal operation
+ * - trial: In trial period
+ * - past_due: Payment failed but grace period active
+ * - suspended: Access restricted due to billing or policy
+ * - closed: Permanently closed
+ */
+export type UserStatus = "active" | "disabled" | "suspended" | "deleted";
+/**
+ * A reference to a user. Will not be deleted even due to GDPR requests or account closures,
+ * to maintain referential integrity in audit logs and historical records.
+ */
 export type UserResource = {
     id: UserId;
     accountId: AccountId;
     status: UserStatus;
     preferredMembershipId: MembershipId | null;
 };
+/**
+ * Personal identity information (PII) for a user. Will be deleted due to GDPR requests or account
+ * closures to respect legal requirements of various regions..
+ */
 export type UserIdentity = {
     id: UserId;
     avatarUrl: string | null;
+    /** External identifier from third-party provider (i.e., SCIM) */
     externalId: string | null;
     givenName: string | null;
     familyName: string | null;
     displayName: string | null;
+    /** Preferred language code (en-CA, fr-FR, zh-CN, etc.) */
     preferredLanguage: string | null;
+    /** Locale code (e.g., "en-US") */
     locale: string | null;
     timezone: string | null;
 };
+/**
+ * Roles within an account membership.
+ *
+ * - owner: Full administrative access, may perform destructive actions.
+ * - member: Standard non-destructive access
+ * - viewer: Read-only access
+ */
 export type MembershipRole = "owner" | "member" | "viewer";
 export type Membership = {
     id: MembershipId;
@@ -49,29 +142,70 @@ export type Membership = {
     accountId: AccountId;
     role: MembershipRole;
 };
+/**
+ * Email credential record attached to a user.
+ *
+ * Sensitive fields (email) are only included when explicitly requested
+ * or when the caller has appropriate permissions.
+ */
 export type EmailCredential = {
     id: string;
     email: string | null;
-    hashedEmail: string | null;
-    hashedPassword: string | null;
     emailVerifiedAt: string | null;
 };
 export type SessionTokens = {
+    /** Signed JWT access token for authenticating API requests */
     accessToken: string;
+    /** Opaque refresh token for obtaining new access tokens */
     refreshToken: string;
     tokenType: "Bearer";
+    /** Seconds until the access token expires from time of issuance */
     expiresIn: number;
     idToken?: string;
+    /** Absolute expiration time (milliseconds since epoch) set by the client library */
+    expiresAt: number;
 };
+/**
+ * Complete profile of the currently authenticated user.
+ *
+ * Combines basic user data with identity, credentials, memberships, and freshness timestamp.
+ *
+ * `lastUpdatedAt` is updated whenever the profile is fetched from the server.
+ */
 export type SessionProfile = UserResource & {
-    identity: UserIdentity;
+    identity: UserIdentity | null;
     emailCredentials: EmailCredential[];
-    memberships: Membership[];
+    memberships: (Membership & {
+        account: AccountResource;
+    })[];
+    /** Currently active membership in the accessToken (determined by preferredMembershipId or context) */
     activeMembership: Membership | null;
+    lastUpdatedAt: number;
 };
-export type AuthenticationResult = {
-    session: SessionTokens;
+/**
+ * Combined authentication state containing tokens and optional profile.
+ */
+export type Authentication = {
+    tokens: SessionTokens;
     profile: SessionProfile;
 };
+/**
+ * Result of checkEmail() indicating whether the email is registered.
+ */
 export type EmailCheckStatus = "active" | "inactive";
+/**
+ * Supported login methods for an email address.
+ *
+ * Currently limited to email/password and magic link flows.
+ */
 export type LoginMethod = "email_password" | "magic_link";
+/**
+ * Minimal storage interface required for session persistence.
+ *
+ * Compatible with localStorage, sessionStorage, AsyncStorage (React Native), or any custom implementation.
+ */
+export type StorageLike = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softwarepatterns/am",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Auth client SDK for AccountMaker (Am)",
   "keywords": [
     "authentication",
@@ -47,8 +47,7 @@
     "test:unit": "bun test src",
     "test:integration": "NODE_TLS_REJECT_UNAUTHORIZED=0 bun test test/integration",
     "typecheck": "bunx tsc --noEmit",
-    "check": "npm run typecheck && npm run build",
-    "digest": "bunx ai-digest -i . -o codebase.md --whitespace-removal --show-output-files"
+    "check": "npm run typecheck && npm run build"
   },
   "publishConfig": {
     "access": "public"