@simple-auth-kit/auth-client 1.0.0

package/dist/auth-client.d.ts

@@ -0,0 +1,196 @@
+import { AuditLogListFilter, AuditLogListResult, AuthTokens, CountryListFilter, CountryListResult, CountrySummary, CreateCountryInput, CreateCustomerInput, CreateLanguageInput, CreateRoleInput, CreateUserInput, CurrentUser, CustomerListFilter, CustomerListResult, CustomerSummary, DefinePermissionInput, LanguageListFilter, LanguageListResult, LanguageSummary, MemberRoles, PermissionSummary, RoleSummary, SelfProfile, SessionSummary, TokenStorage, TwoFactorChallenge, UpdateCountryInput, UpdateCustomerInput, UpdateLanguageInput, UpdateRoleInput, UpdateUserInput, UserListFilter, UserListResult, UserSummary, WorkspaceIdResolver, WorkspaceMember, WorkspaceScope, WorkspaceSummary } from "./types.js";
+export interface AuthClientOptions {
+    baseUrl: string;
+    storage: TokenStorage;
+    /**
+     * The workspace that workspace-scoped calls act in.
+     *
+     * Leave it out entirely against the plain backend variant (`easy-auth add <combo>`): nothing
+     * then ever sends `X-Workspace-Id`, and no call site has to mention workspaces. Against the
+     * workspaces variant (`--workspaces`) set it once — a string for a fixed workspace, or a
+     * function resolved per request so the app's own store stays the owner of "which workspace am
+     * I in", exactly as `TokenStorage` keeps token persistence out of this package.
+     */
+    workspaceId?: string | WorkspaceIdResolver;
+}
+/** The header a request uses to name the workspace it acts in. Lowercased — `fetch` header names are case-insensitive. */
+export declare const WORKSPACE_HEADER = "x-workspace-id";
+/**
+ * One client shared by all 4 apps (admin-nextjs, admin-react, mobile-expo, mobile-bare-rn) —
+ * the auth flow and API contract are identical, only `TokenStorage` differs per platform.
+ * Mirrors the deps-injection pattern used throughout registry/core: business logic here is
+ * storage-agnostic.
+ *
+ * It also serves both backend variants from one build. Workspaces are an install-time choice of
+ * the consuming project, not a runtime mode of this client: the workspace surface below
+ * (`createWorkspace`, `listWorkspaces`, `listWorkspaceMembers`, ...) only exists on the
+ * `--workspaces` backend, and a consumer on the plain variant simply never calls it and never
+ * configures `workspaceId` — in which case `X-Workspace-Id` is never sent on anything.
+ *
+ * Which calls carry the header is a structural property here, not a per-call decision:
+ * `request()` cannot pass a workspace at all, and only `scopedRequest()` can.
+ */
+export declare class AuthClient {
+    private readonly opts;
+    private activeWorkspace;
+    constructor(opts: AuthClientOptions);
+    /** Replaces the configured active workspace. `null` goes back to sending no workspace at all. */
+    setActiveWorkspace(workspaceId: string | WorkspaceIdResolver | null): void;
+    /** Resolves the active workspace — awaiting the resolver function if one was configured. */
+    getActiveWorkspace(): Promise<string | null>;
+    signup(input: {
+        email: string;
+        password: string;
+    }): Promise<AuthTokens>;
+    /** `identifier` is matched against email, username, and phone, in that order. Returns tokens directly, or a 2FA challenge to complete via `loginTwoFactor`. */
+    login(input: {
+        identifier: string;
+        password: string;
+    }): Promise<AuthTokens | TwoFactorChallenge>;
+    loginTwoFactor(input: {
+        challengeToken: string;
+        code: string;
+    }): Promise<AuthTokens>;
+    /** Rotates the refresh token; callers rarely need this directly — `request()` calls it automatically on a 401. */
+    refresh(): Promise<AuthTokens>;
+    logout(): Promise<void>;
+    logoutAll(): Promise<void>;
+    logoutOthers(): Promise<void>;
+    /** Requires the current password. Every other session is revoked; the one making this call is left alone. */
+    changePassword(input: {
+        currentPassword: string;
+        newPassword: string;
+    }): Promise<void>;
+    /** Self-service — no admin permission required, updates the caller's own row. Not workspace-scoped: a profile isn't a workspace concept. */
+    updateProfile(input: UpdateUserInput): Promise<SelfProfile>;
+    /**
+     * The one identity endpoint that answers differently per workspace: it reports the roles and
+     * permissions that apply to *this* request, so it carries the active workspace when there is
+     * one. On the workspaces variant it is the only way to learn your permissions in a workspace,
+     * which is what the client-side UI gating reads. Pass `{ workspaceId: null }` for the
+     * workspace-free identity, which answers with empty roles and permissions.
+     */
+    me(scope?: WorkspaceScope): Promise<CurrentUser>;
+    sessions(): Promise<SessionSummary[]>;
+    isAuthenticated(): Promise<boolean>;
+    enrollTwoFactor(): Promise<{
+        secret: string;
+        provisioningUri: string;
+    }>;
+    confirmTwoFactor(code: string): Promise<{
+        backupCodes: string[];
+    }>;
+    disableTwoFactor(code: string): Promise<void>;
+    requestPasswordReset(input: {
+        email: string;
+    }): Promise<void>;
+    resetPassword(input: {
+        token: string;
+        newPassword: string;
+    }): Promise<void>;
+    /** Returns the provider URL to send the browser/webview to; the backend handles the round-trip and callback. */
+    oauthStart(provider: string): Promise<{
+        url: string;
+    }>;
+    /**
+     * Not workspace-scoped — you cannot already be in the workspace you are creating, so this
+     * deliberately sends no `X-Workspace-Id`. The creator becomes an `["admin","member"]` member.
+     */
+    createWorkspace(name: string): Promise<WorkspaceSummary>;
+    /** Not workspace-scoped: any authenticated user, answering with the workspaces they belong to and their roles in each. */
+    listWorkspaces(): Promise<WorkspaceSummary[]>;
+    /** Any member of the workspace may list it. */
+    listWorkspaceMembers(scope?: WorkspaceScope): Promise<WorkspaceMember[]>;
+    /** [admin] Adds an existing user by email. `roles` defaults to `["member"]` on the backend. */
+    addWorkspaceMember(input: {
+        email: string;
+        roles?: string[];
+    }, scope?: WorkspaceScope): Promise<WorkspaceMember>;
+    /** [admin] Replaces a member's whole role set. The backend refuses (403) when the member is you. */
+    setWorkspaceMemberRoles(memberId: string, roles: string[], scope?: WorkspaceScope): Promise<MemberRoles>;
+    /** [admin] Removes a member, and their direct permission grants with them. The backend refuses (403) when the member is you. */
+    removeWorkspaceMember(memberId: string, scope?: WorkspaceScope): Promise<void>;
+    blockUser(userId: string, scope?: WorkspaceScope): Promise<void>;
+    unblockUser(userId: string, scope?: WorkspaceScope): Promise<void>;
+    /** A routine administrative on/off toggle — distinct from block/unblock, a security/moderation action. Both independently deny login. */
+    deactivateUser(userId: string, scope?: WorkspaceScope): Promise<void>;
+    activateUser(userId: string, scope?: WorkspaceScope): Promise<void>;
+    listUsers(filter?: UserListFilter, scope?: WorkspaceScope): Promise<UserListResult>;
+    /** No invitation email — the account is usable immediately with the password given here. */
+    createUser(input: CreateUserInput, scope?: WorkspaceScope): Promise<UserSummary>;
+    getUser(userId: string, scope?: WorkspaceScope): Promise<UserSummary>;
+    /** Profile fields only — email is the login identifier and is not editable here. */
+    updateUser(userId: string, input: UpdateUserInput, scope?: WorkspaceScope): Promise<UserSummary>;
+    /** Soft-delete: the account stops appearing in listings and can no longer authenticate. The backend refuses (403) when the target is you. */
+    deleteUser(userId: string, reason?: string, scope?: WorkspaceScope): Promise<void>;
+    /** `activeOnly` is what a role picker (Add user, Assign role) should pass — omit it for the Roles management page, which wants everything. */
+    listRoles(filter?: {
+        activeOnly?: boolean;
+    }, scope?: WorkspaceScope): Promise<RoleSummary[]>;
+    createRole(input: CreateRoleInput, scope?: WorkspaceScope): Promise<RoleSummary>;
+    updateRole(roleId: string, input: UpdateRoleInput, scope?: WorkspaceScope): Promise<RoleSummary>;
+    /** Soft-delete: existing assignments are left in place, and the role simply stops being resolved. */
+    deleteRole(roleId: string, reason?: string, scope?: WorkspaceScope): Promise<void>;
+    attachPermissionToRole(roleId: string, permission: string, scope?: WorkspaceScope): Promise<void>;
+    detachPermissionFromRole(roleId: string, permissionSlug: string, scope?: WorkspaceScope): Promise<void>;
+    /**
+     * The catalog itself is global on both variants; what is workspace-scoped is which roles/
+     * memberships point at each row. Still sent through `scopedRequest`: on the workspaces variant
+     * every `/auth/admin/*` route sits behind the same guard that requires `X-Workspace-Id`, even
+     * this one. `activeOnly` is what a permission picker (Create/Edit Role) should pass — omit it
+     * for the Permissions management page, which wants everything.
+     */
+    listPermissions(filter?: {
+        activeOnly?: boolean;
+    }, scope?: WorkspaceScope): Promise<PermissionSummary[]>;
+    /** Upserted on `slug` — creates a new capability, or edits/deactivates an existing one. */
+    definePermission(input: DefinePermissionInput, scope?: WorkspaceScope): Promise<PermissionSummary>;
+    assignRole(userId: string, role: string, scope?: WorkspaceScope): Promise<void>;
+    revokeRole(userId: string, roleName: string, scope?: WorkspaceScope): Promise<void>;
+    grantPermission(userId: string, permission: string, scope?: WorkspaceScope): Promise<void>;
+    revokePermission(userId: string, permissionKey: string, scope?: WorkspaceScope): Promise<void>;
+    listAuditLog(filter?: AuditLogListFilter, scope?: WorkspaceScope): Promise<AuditLogListResult>;
+    /** `activeOnly` is what a country picker/dropdown should pass — omit it for the Countries management page, which wants everything. */
+    listCountries(filter?: CountryListFilter, scope?: WorkspaceScope): Promise<CountryListResult>;
+    createCountry(input: CreateCountryInput, scope?: WorkspaceScope): Promise<CountrySummary>;
+    getCountry(countryId: string, scope?: WorkspaceScope): Promise<CountrySummary>;
+    updateCountry(countryId: string, input: UpdateCountryInput, scope?: WorkspaceScope): Promise<CountrySummary>;
+    /** Soft-delete: the row stops appearing in listings but survives for audit purposes. */
+    deleteCountry(countryId: string, reason?: string, scope?: WorkspaceScope): Promise<void>;
+    activateCountry(countryId: string, scope?: WorkspaceScope): Promise<void>;
+    deactivateCountry(countryId: string, scope?: WorkspaceScope): Promise<void>;
+    /** `activeOnly` is what a language picker/dropdown should pass — omit it for the Languages management page, which wants everything. */
+    listLanguages(filter?: LanguageListFilter, scope?: WorkspaceScope): Promise<LanguageListResult>;
+    createLanguage(input: CreateLanguageInput, scope?: WorkspaceScope): Promise<LanguageSummary>;
+    getLanguage(languageId: string, scope?: WorkspaceScope): Promise<LanguageSummary>;
+    updateLanguage(languageId: string, input: UpdateLanguageInput, scope?: WorkspaceScope): Promise<LanguageSummary>;
+    /** Soft-delete: the row stops appearing in listings but survives for audit purposes. */
+    deleteLanguage(languageId: string, reason?: string, scope?: WorkspaceScope): Promise<void>;
+    activateLanguage(languageId: string, scope?: WorkspaceScope): Promise<void>;
+    deactivateLanguage(languageId: string, scope?: WorkspaceScope): Promise<void>;
+    /** `activeOnly` is what a customer picker/dropdown should pass — omit it for the Customers management page, which wants everything. */
+    listCustomers(filter?: CustomerListFilter, scope?: WorkspaceScope): Promise<CustomerListResult>;
+    createCustomer(input: CreateCustomerInput, scope?: WorkspaceScope): Promise<CustomerSummary>;
+    getCustomer(customerId: string, scope?: WorkspaceScope): Promise<CustomerSummary>;
+    updateCustomer(customerId: string, input: UpdateCustomerInput, scope?: WorkspaceScope): Promise<CustomerSummary>;
+    /** Soft-delete: the row stops appearing in listings but survives for audit purposes. */
+    deleteCustomer(customerId: string, reason?: string, scope?: WorkspaceScope): Promise<void>;
+    activateCustomer(customerId: string, scope?: WorkspaceScope): Promise<void>;
+    deactivateCustomer(customerId: string, scope?: WorkspaceScope): Promise<void>;
+    /** Unauthenticated call — no Authorization header, no refresh-on-401 retry (there's no session to refresh yet). */
+    private anonymousRequest;
+    /** Authenticated and never workspace-scoped: it has no parameter with which to name a workspace. */
+    private request;
+    /** Authenticated and workspace-scoped: sends `X-Workspace-Id` when the call or the client names one. */
+    private scopedRequest;
+    /** `undefined` from here means "send no header" — the plain variant's permanent answer. */
+    private resolveWorkspaceId;
+    /**
+     * Attaches the stored access token, and on a 401 makes exactly one `refresh()` attempt before
+     * retrying once — if refresh itself fails, clears storage and surfaces the original error so
+     * the app can route to its login screen. The retry reuses the workspace already resolved for
+     * the first attempt, so a resolver function cannot answer differently mid-call.
+     */
+    private authedRequest;
+    private rawFetch;
+}

package/dist/auth-client.js

@@ -0,0 +1,389 @@
+import { AuthApiError, } from "./types.js";
+/** The header a request uses to name the workspace it acts in. Lowercased — `fetch` header names are case-insensitive. */
+export const WORKSPACE_HEADER = "x-workspace-id";
+function isTwoFactorChallenge(value) {
+    return typeof value === "object" && value !== null && value.twoFactorRequired === true;
+}
+function queryString(filter) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(filter))
+        if (value !== undefined)
+            params.set(key, String(value));
+    const query = params.toString();
+    return query ? `?${query}` : "";
+}
+/**
+ * One client shared by all 4 apps (admin-nextjs, admin-react, mobile-expo, mobile-bare-rn) —
+ * the auth flow and API contract are identical, only `TokenStorage` differs per platform.
+ * Mirrors the deps-injection pattern used throughout registry/core: business logic here is
+ * storage-agnostic.
+ *
+ * It also serves both backend variants from one build. Workspaces are an install-time choice of
+ * the consuming project, not a runtime mode of this client: the workspace surface below
+ * (`createWorkspace`, `listWorkspaces`, `listWorkspaceMembers`, ...) only exists on the
+ * `--workspaces` backend, and a consumer on the plain variant simply never calls it and never
+ * configures `workspaceId` — in which case `X-Workspace-Id` is never sent on anything.
+ *
+ * Which calls carry the header is a structural property here, not a per-call decision:
+ * `request()` cannot pass a workspace at all, and only `scopedRequest()` can.
+ */
+export class AuthClient {
+    opts;
+    activeWorkspace;
+    constructor(opts) {
+        this.opts = opts;
+        this.activeWorkspace = opts.workspaceId ?? null;
+    }
+    // ---- active workspace (workspaces backend variant only) ----
+    /** Replaces the configured active workspace. `null` goes back to sending no workspace at all. */
+    setActiveWorkspace(workspaceId) {
+        this.activeWorkspace = workspaceId;
+    }
+    /** Resolves the active workspace — awaiting the resolver function if one was configured. */
+    async getActiveWorkspace() {
+        if (typeof this.activeWorkspace === "function")
+            return (await this.activeWorkspace()) ?? null;
+        return this.activeWorkspace;
+    }
+    // ---- identity ----
+    async signup(input) {
+        const tokens = await this.anonymousRequest("POST", "/auth/signup", input);
+        await this.opts.storage.set(tokens);
+        return tokens;
+    }
+    /** `identifier` is matched against email, username, and phone, in that order. Returns tokens directly, or a 2FA challenge to complete via `loginTwoFactor`. */
+    async login(input) {
+        const result = await this.anonymousRequest("POST", "/auth/login", input);
+        if (isTwoFactorChallenge(result))
+            return result;
+        await this.opts.storage.set(result);
+        return result;
+    }
+    async loginTwoFactor(input) {
+        const tokens = await this.anonymousRequest("POST", "/auth/login/2fa", input);
+        await this.opts.storage.set(tokens);
+        return tokens;
+    }
+    /** Rotates the refresh token; callers rarely need this directly — `request()` calls it automatically on a 401. */
+    async refresh() {
+        const current = await this.opts.storage.get();
+        if (!current)
+            throw new AuthApiError("not logged in", 401);
+        const rotated = await this.anonymousRequest("POST", "/auth/refresh", {
+            refreshToken: current.refreshToken,
+        });
+        const merged = { ...rotated, sessionId: current.sessionId };
+        await this.opts.storage.set(merged);
+        return merged;
+    }
+    async logout() {
+        await this.request("POST", "/auth/logout");
+        await this.opts.storage.clear();
+    }
+    async logoutAll() {
+        await this.request("POST", "/auth/logout-all");
+        await this.opts.storage.clear();
+    }
+    async logoutOthers() {
+        await this.request("POST", "/auth/logout-others");
+    }
+    /** Requires the current password. Every other session is revoked; the one making this call is left alone. */
+    async changePassword(input) {
+        await this.request("POST", "/auth/password/change", input);
+    }
+    /** Self-service — no admin permission required, updates the caller's own row. Not workspace-scoped: a profile isn't a workspace concept. */
+    async updateProfile(input) {
+        return this.request("PATCH", "/auth/me", input);
+    }
+    /**
+     * The one identity endpoint that answers differently per workspace: it reports the roles and
+     * permissions that apply to *this* request, so it carries the active workspace when there is
+     * one. On the workspaces variant it is the only way to learn your permissions in a workspace,
+     * which is what the client-side UI gating reads. Pass `{ workspaceId: null }` for the
+     * workspace-free identity, which answers with empty roles and permissions.
+     */
+    async me(scope) {
+        return this.scopedRequest("GET", "/auth/me", undefined, scope);
+    }
+    async sessions() {
+        return this.request("GET", "/auth/sessions");
+    }
+    async isAuthenticated() {
+        return (await this.opts.storage.get()) !== null;
+    }
+    async enrollTwoFactor() {
+        return this.request("POST", "/auth/2fa/enroll");
+    }
+    async confirmTwoFactor(code) {
+        return this.request("POST", "/auth/2fa/confirm", { code });
+    }
+    async disableTwoFactor(code) {
+        await this.request("POST", "/auth/2fa/disable", { code });
+    }
+    async requestPasswordReset(input) {
+        await this.anonymousRequest("POST", "/auth/password/forgot", input);
+    }
+    async resetPassword(input) {
+        await this.anonymousRequest("POST", "/auth/password/reset", input);
+    }
+    /** Returns the provider URL to send the browser/webview to; the backend handles the round-trip and callback. */
+    async oauthStart(provider) {
+        return this.anonymousRequest("GET", `/auth/oauth/${encodeURIComponent(provider)}/start`);
+    }
+    // ---- workspaces (workspaces backend variant only) ----
+    /**
+     * Not workspace-scoped — you cannot already be in the workspace you are creating, so this
+     * deliberately sends no `X-Workspace-Id`. The creator becomes an `["admin","member"]` member.
+     */
+    async createWorkspace(name) {
+        return this.request("POST", "/workspaces", { name });
+    }
+    /** Not workspace-scoped: any authenticated user, answering with the workspaces they belong to and their roles in each. */
+    async listWorkspaces() {
+        return this.request("GET", "/workspaces");
+    }
+    /** Any member of the workspace may list it. */
+    async listWorkspaceMembers(scope) {
+        return this.scopedRequest("GET", "/workspaces/members", undefined, scope);
+    }
+    /** [admin] Adds an existing user by email. `roles` defaults to `["member"]` on the backend. */
+    async addWorkspaceMember(input, scope) {
+        return this.scopedRequest("POST", "/workspaces/members", input, scope);
+    }
+    /** [admin] Replaces a member's whole role set. The backend refuses (403) when the member is you. */
+    async setWorkspaceMemberRoles(memberId, roles, scope) {
+        return this.scopedRequest("PUT", `/workspaces/members/${encodeURIComponent(memberId)}/roles`, { roles }, scope);
+    }
+    /** [admin] Removes a member, and their direct permission grants with them. The backend refuses (403) when the member is you. */
+    async removeWorkspaceMember(memberId, scope) {
+        await this.scopedRequest("DELETE", `/workspaces/members/${encodeURIComponent(memberId)}`, undefined, scope);
+    }
+    // ---- administration ----
+    //
+    // Every call below is workspace-scoped: on the workspaces variant these routes administer one
+    // workspace and require the header; on the plain variant they administer the deployment and
+    // the header is never configured, so never sent.
+    async blockUser(userId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/users/${encodeURIComponent(userId)}/block`, undefined, scope);
+    }
+    async unblockUser(userId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/users/${encodeURIComponent(userId)}/unblock`, undefined, scope);
+    }
+    /** A routine administrative on/off toggle — distinct from block/unblock, a security/moderation action. Both independently deny login. */
+    async deactivateUser(userId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/users/${encodeURIComponent(userId)}/deactivate`, undefined, scope);
+    }
+    async activateUser(userId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/users/${encodeURIComponent(userId)}/activate`, undefined, scope);
+    }
+    async listUsers(filter = {}, scope) {
+        return this.scopedRequest("GET", `/auth/admin/users${queryString(filter)}`, undefined, scope);
+    }
+    /** No invitation email — the account is usable immediately with the password given here. */
+    async createUser(input, scope) {
+        return this.scopedRequest("POST", "/auth/admin/users", input, scope);
+    }
+    async getUser(userId, scope) {
+        return this.scopedRequest("GET", `/auth/admin/users/${encodeURIComponent(userId)}`, undefined, scope);
+    }
+    /** Profile fields only — email is the login identifier and is not editable here. */
+    async updateUser(userId, input, scope) {
+        return this.scopedRequest("PATCH", `/auth/admin/users/${encodeURIComponent(userId)}`, input, scope);
+    }
+    /** Soft-delete: the account stops appearing in listings and can no longer authenticate. The backend refuses (403) when the target is you. */
+    async deleteUser(userId, reason, scope) {
+        await this.scopedRequest("DELETE", `/auth/admin/users/${encodeURIComponent(userId)}`, reason ? { reason } : undefined, scope);
+    }
+    /** `activeOnly` is what a role picker (Add user, Assign role) should pass — omit it for the Roles management page, which wants everything. */
+    async listRoles(filter = {}, scope) {
+        const result = await this.scopedRequest("GET", `/auth/admin/roles${queryString(filter)}`, undefined, scope);
+        return result.roles;
+    }
+    async createRole(input, scope) {
+        return this.scopedRequest("POST", "/auth/admin/roles", input, scope);
+    }
+    async updateRole(roleId, input, scope) {
+        return this.scopedRequest("PATCH", `/auth/admin/roles/${encodeURIComponent(roleId)}`, input, scope);
+    }
+    /** Soft-delete: existing assignments are left in place, and the role simply stops being resolved. */
+    async deleteRole(roleId, reason, scope) {
+        await this.scopedRequest("DELETE", `/auth/admin/roles/${encodeURIComponent(roleId)}`, reason ? { reason } : undefined, scope);
+    }
+    async attachPermissionToRole(roleId, permission, scope) {
+        await this.scopedRequest("POST", `/auth/admin/roles/${encodeURIComponent(roleId)}/permissions`, { permission }, scope);
+    }
+    async detachPermissionFromRole(roleId, permissionSlug, scope) {
+        await this.scopedRequest("POST", `/auth/admin/roles/${encodeURIComponent(roleId)}/permissions/${encodeURIComponent(permissionSlug)}/revoke`, undefined, scope);
+    }
+    /**
+     * The catalog itself is global on both variants; what is workspace-scoped is which roles/
+     * memberships point at each row. Still sent through `scopedRequest`: on the workspaces variant
+     * every `/auth/admin/*` route sits behind the same guard that requires `X-Workspace-Id`, even
+     * this one. `activeOnly` is what a permission picker (Create/Edit Role) should pass — omit it
+     * for the Permissions management page, which wants everything.
+     */
+    async listPermissions(filter = {}, scope) {
+        const result = await this.scopedRequest("GET", `/auth/admin/permissions${queryString(filter)}`, undefined, scope);
+        return result.permissions;
+    }
+    /** Upserted on `slug` — creates a new capability, or edits/deactivates an existing one. */
+    async definePermission(input, scope) {
+        return this.scopedRequest("POST", "/auth/admin/permissions", input, scope);
+    }
+    async assignRole(userId, role, scope) {
+        await this.scopedRequest("POST", `/auth/admin/users/${encodeURIComponent(userId)}/roles`, { role }, scope);
+    }
+    async revokeRole(userId, roleName, scope) {
+        await this.scopedRequest("POST", `/auth/admin/users/${encodeURIComponent(userId)}/roles/${encodeURIComponent(roleName)}/revoke`, undefined, scope);
+    }
+    async grantPermission(userId, permission, scope) {
+        await this.scopedRequest("POST", `/auth/admin/users/${encodeURIComponent(userId)}/permissions`, { permission }, scope);
+    }
+    async revokePermission(userId, permissionKey, scope) {
+        await this.scopedRequest("POST", `/auth/admin/users/${encodeURIComponent(userId)}/permissions/${encodeURIComponent(permissionKey)}/revoke`, undefined, scope);
+    }
+    async listAuditLog(filter = {}, scope) {
+        return this.scopedRequest("GET", `/auth/admin/audit-log${queryString(filter)}`, undefined, scope);
+    }
+    // ---- countries (base backend variant only) ----
+    /** `activeOnly` is what a country picker/dropdown should pass — omit it for the Countries management page, which wants everything. */
+    async listCountries(filter = {}, scope) {
+        return this.scopedRequest("GET", `/auth/admin/countries${queryString(filter)}`, undefined, scope);
+    }
+    async createCountry(input, scope) {
+        return this.scopedRequest("POST", "/auth/admin/countries", input, scope);
+    }
+    async getCountry(countryId, scope) {
+        return this.scopedRequest("GET", `/auth/admin/countries/${encodeURIComponent(countryId)}`, undefined, scope);
+    }
+    async updateCountry(countryId, input, scope) {
+        return this.scopedRequest("PATCH", `/auth/admin/countries/${encodeURIComponent(countryId)}`, input, scope);
+    }
+    /** Soft-delete: the row stops appearing in listings but survives for audit purposes. */
+    async deleteCountry(countryId, reason, scope) {
+        await this.scopedRequest("DELETE", `/auth/admin/countries/${encodeURIComponent(countryId)}`, reason ? { reason } : undefined, scope);
+    }
+    async activateCountry(countryId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/countries/${encodeURIComponent(countryId)}/activate`, undefined, scope);
+    }
+    async deactivateCountry(countryId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/countries/${encodeURIComponent(countryId)}/deactivate`, undefined, scope);
+    }
+    // ---- languages (base backend variant only) ----
+    /** `activeOnly` is what a language picker/dropdown should pass — omit it for the Languages management page, which wants everything. */
+    async listLanguages(filter = {}, scope) {
+        return this.scopedRequest("GET", `/auth/admin/languages${queryString(filter)}`, undefined, scope);
+    }
+    async createLanguage(input, scope) {
+        return this.scopedRequest("POST", "/auth/admin/languages", input, scope);
+    }
+    async getLanguage(languageId, scope) {
+        return this.scopedRequest("GET", `/auth/admin/languages/${encodeURIComponent(languageId)}`, undefined, scope);
+    }
+    async updateLanguage(languageId, input, scope) {
+        return this.scopedRequest("PATCH", `/auth/admin/languages/${encodeURIComponent(languageId)}`, input, scope);
+    }
+    /** Soft-delete: the row stops appearing in listings but survives for audit purposes. */
+    async deleteLanguage(languageId, reason, scope) {
+        await this.scopedRequest("DELETE", `/auth/admin/languages/${encodeURIComponent(languageId)}`, reason ? { reason } : undefined, scope);
+    }
+    async activateLanguage(languageId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/languages/${encodeURIComponent(languageId)}/activate`, undefined, scope);
+    }
+    async deactivateLanguage(languageId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/languages/${encodeURIComponent(languageId)}/deactivate`, undefined, scope);
+    }
+    // ---- customers (base backend variant only) ----
+    // End-users managed by admins — no login capability, and not related to the admin UserSummary above.
+    /** `activeOnly` is what a customer picker/dropdown should pass — omit it for the Customers management page, which wants everything. */
+    async listCustomers(filter = {}, scope) {
+        return this.scopedRequest("GET", `/auth/admin/customers${queryString(filter)}`, undefined, scope);
+    }
+    async createCustomer(input, scope) {
+        return this.scopedRequest("POST", "/auth/admin/customers", input, scope);
+    }
+    async getCustomer(customerId, scope) {
+        return this.scopedRequest("GET", `/auth/admin/customers/${encodeURIComponent(customerId)}`, undefined, scope);
+    }
+    async updateCustomer(customerId, input, scope) {
+        return this.scopedRequest("PATCH", `/auth/admin/customers/${encodeURIComponent(customerId)}`, input, scope);
+    }
+    /** Soft-delete: the row stops appearing in listings but survives for audit purposes. */
+    async deleteCustomer(customerId, reason, scope) {
+        await this.scopedRequest("DELETE", `/auth/admin/customers/${encodeURIComponent(customerId)}`, reason ? { reason } : undefined, scope);
+    }
+    async activateCustomer(customerId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/customers/${encodeURIComponent(customerId)}/activate`, undefined, scope);
+    }
+    async deactivateCustomer(customerId, scope) {
+        await this.scopedRequest("POST", `/auth/admin/customers/${encodeURIComponent(customerId)}/deactivate`, undefined, scope);
+    }
+    // ---- transport ----
+    /** Unauthenticated call — no Authorization header, no refresh-on-401 retry (there's no session to refresh yet). */
+    async anonymousRequest(method, path, body) {
+        return this.rawFetch(method, path, body);
+    }
+    /** Authenticated and never workspace-scoped: it has no parameter with which to name a workspace. */
+    async request(method, path, body) {
+        return this.authedRequest(method, path, body, undefined);
+    }
+    /** Authenticated and workspace-scoped: sends `X-Workspace-Id` when the call or the client names one. */
+    async scopedRequest(method, path, body, scope) {
+        return this.authedRequest(method, path, body, await this.resolveWorkspaceId(scope));
+    }
+    /** `undefined` from here means "send no header" — the plain variant's permanent answer. */
+    async resolveWorkspaceId(scope) {
+        if (scope && scope.workspaceId !== undefined)
+            return scope.workspaceId ?? undefined;
+        return (await this.getActiveWorkspace()) ?? undefined;
+    }
+    /**
+     * Attaches the stored access token, and on a 401 makes exactly one `refresh()` attempt before
+     * retrying once — if refresh itself fails, clears storage and surfaces the original error so
+     * the app can route to its login screen. The retry reuses the workspace already resolved for
+     * the first attempt, so a resolver function cannot answer differently mid-call.
+     */
+    async authedRequest(method, path, body, workspaceId, isRetry = false) {
+        const tokens = await this.opts.storage.get();
+        if (!tokens)
+            throw new AuthApiError("not logged in", 401);
+        try {
+            return await this.rawFetch(method, path, body, tokens.accessToken, workspaceId);
+        }
+        catch (err) {
+            if (err instanceof AuthApiError && err.status === 401 && !isRetry) {
+                try {
+                    await this.refresh();
+                }
+                catch (refreshErr) {
+                    await this.opts.storage.clear();
+                    throw refreshErr;
+                }
+                return this.authedRequest(method, path, body, workspaceId, true);
+            }
+            throw err;
+        }
+    }
+    async rawFetch(method, path, body, bearerToken, workspaceId) {
+        const response = await fetch(`${this.opts.baseUrl}${path}`, {
+            method,
+            headers: {
+                "content-type": "application/json",
+                ...(bearerToken ? { authorization: `Bearer ${bearerToken}` } : {}),
+                ...(workspaceId ? { [WORKSPACE_HEADER]: workspaceId } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const envelope = await response.json().catch(() => undefined);
+        if (!response.ok) {
+            const errorBody = envelope && typeof envelope === "object" ? envelope : {};
+            const message = typeof errorBody.message === "string" ? errorBody.message : response.statusText;
+            const code = typeof errorBody.code === "string" ? errorBody.code : undefined;
+            throw new AuthApiError(message, response.status, code);
+        }
+        // Every successful response is `{success, statusCode, message, data}` — unwrapped here, once,
+        // so every method above returns the payload directly and never has to know the envelope exists.
+        const payload = envelope && typeof envelope === "object" && "data" in envelope ? envelope.data : envelope;
+        return payload;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AuthClient, WORKSPACE_HEADER } from "./auth-client.js";
+export type { AuthClientOptions } from "./auth-client.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { AuthClient, WORKSPACE_HEADER } from "./auth-client.js";
+export * from "./types.js";

package/dist/types.d.ts

@@ -0,0 +1,490 @@
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** Only present right after signup/login/2fa-complete — refresh() doesn't get a new one, so it's carried forward from storage. */
+    sessionId?: string;
+}
+export interface TwoFactorChallenge {
+    twoFactorRequired: true;
+    challengeToken: string;
+}
+/**
+ * `GET /auth/me`. Verified against a running backend: the server answers exactly these five
+ * fields, on both variants.
+ *
+ * The access token is workspace-agnostic — it identifies only the user and the session — so
+ * `roles`/`permissions` are whatever applies to *this request*: on the plain backend variant
+ * they are global to the deployment, and on the workspaces variant they are the caller's roles
+ * and permissions inside the workspace the request named, or empty when it named none.
+ *
+ * A `rules` field is coming: the caller's CASL abilities, serialized with `packRules` from
+ * `@casl/ability/extra`, for the workspace this request names. It belongs *here*, as one more
+ * optional property of this interface, and nowhere else — the client neither unpacks it nor
+ * depends on `@casl/ability`; each consuming app builds its own `Ability` from it, so server
+ * enforcement and UI hiding cannot drift. Nothing in this package has to change for the field to
+ * arrive safely: responses are handed back whole, never rebuilt from a known-field list, so an
+ * unrecognised field already reaches the caller untouched (see the `/auth/me` passthrough test).
+ */
+export interface CurrentUser {
+    sub: string;
+    sessionId: string;
+    roles: string[];
+    permissions: string[];
+    twoFactorEnabled: boolean;
+    email: string;
+    firstName: string | null;
+    lastName: string | null;
+    displayName: string | null;
+    phone: string | null;
+    username: string | null;
+    photo: string | null;
+}
+export interface SessionSummary {
+    id: string;
+    createdAt: string;
+    userAgent?: string;
+    ip?: string;
+}
+export interface AuditLogEntry {
+    id: string;
+    /** Workspaces variant only; null for events that happened outside any workspace. Absent on the plain variant. */
+    workspaceId?: string | null;
+    userId: string | null;
+    /** Human-readable label for `action`, e.g. "Role assigned". */
+    name: string;
+    /** The AuditEvent discriminant, e.g. "role_assigned". */
+    action: string;
+    /** The rest of the AuditEvent's fields. */
+    info: unknown;
+    /** Free-text note; null unless the backend set one. */
+    remarks: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PageMeta {
+    /** 1-indexed. */
+    page: number;
+    limit: number;
+    total: number;
+    pageCount: number;
+    hasPreviousPage: boolean;
+    hasNextPage: boolean;
+}
+export interface AuditLogListFilter {
+    userId?: string;
+    action?: string;
+    since?: string;
+    until?: string;
+    /** 1-indexed. Defaults to 1. */
+    page?: number;
+    /** Defaults to 25, capped at 100. */
+    limit?: number;
+}
+export interface AuditLogListResult {
+    items: AuditLogEntry[];
+    meta: PageMeta;
+}
+export interface RoleSummary {
+    id: string;
+    slug: string;
+    /** Unique across the deployment, alongside slug/displayName. */
+    name: string;
+    displayName: string;
+    /** Given to every newly signed-up user (or, on the workspaces variant, every new membership). */
+    isDefault: boolean;
+    isActive: boolean;
+    /** Permission slugs currently attached to this role — see attachPermissionToRole/detachPermissionFromRole. */
+    permissions: string[];
+}
+export interface CreateRoleInput {
+    /** Stable identifier. Grants and assignments are keyed on it. */
+    slug: string;
+    name?: string;
+    /** Human label for the console. Defaults to the slug. */
+    displayName?: string;
+    description?: string | null;
+    /** Given to every newly signed-up user. Defaults to false. */
+    isDefault?: boolean;
+    /** Defaults to true. */
+    isActive?: boolean;
+}
+export interface UpdateRoleInput {
+    name?: string;
+    displayName?: string;
+    description?: string | null;
+    /** Given to every newly signed-up user. */
+    isDefault?: boolean;
+    /** `false` suspends the role without deleting it — it stops granting immediately. */
+    isActive?: boolean;
+}
+export interface PermissionSummary {
+    id: string;
+    /** The ability itself: `@CheckAbility(slug)` on the server, `ability.can(slug, ABILITY_SUBJECT)` in a client. */
+    slug: string;
+    /** Unique across the deployment, alongside slug/displayName. */
+    name: string;
+    displayName: string;
+    description: string | null;
+    /** Console grouping — a permission matrix renders one section per group. */
+    group: string;
+    groupOrder: number;
+    order: number;
+    /** `false` takes the permission out of every ability that would otherwise carry it, without unpicking a single grant. */
+    isActive: boolean;
+}
+export interface DefinePermissionInput {
+    slug: string;
+    name?: string;
+    /** Defaults to the slug when creating. */
+    displayName?: string;
+    description?: string | null;
+    /** Defaults to `"Custom"` when creating. */
+    group?: string;
+    groupOrder?: number;
+    order?: number;
+    isActive?: boolean;
+}
+export interface PermissionListResult {
+    permissions: PermissionSummary[];
+}
+/** Profile fields a `PATCH /auth/admin/users/:userId` accepts. Email is the login identifier and is not editable here. */
+export interface UpdateUserInput {
+    firstName?: string | null;
+    lastName?: string | null;
+    displayName?: string | null;
+    phone?: string | null;
+    username?: string | null;
+    photo?: string | null;
+    /** ISO date (yyyy-mm-dd). */
+    dob?: string | null;
+    gender?: string | null;
+    /** ISO date (yyyy-mm-dd). Not nullable — omit to leave unchanged. */
+    joinedDate?: string;
+}
+/** `PATCH /auth/me`'s response — the same shape whether or not the combo has workspaces, since a profile isn't a workspace concept. */
+export interface SelfProfile {
+    id: string;
+    email: string;
+    firstName: string | null;
+    lastName: string | null;
+    displayName: string | null;
+    phone: string | null;
+    username: string | null;
+    photo: string | null;
+    createdAt: string;
+}
+/** `POST /auth/admin/users` — no invitation email, the account is usable immediately. */
+export interface CreateUserInput {
+    email: string;
+    password: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    phone?: string;
+    username?: string;
+    photo?: string;
+    /** ISO date (yyyy-mm-dd). */
+    dob?: string;
+    gender?: string;
+    /** ISO date (yyyy-mm-dd). Defaults to today. */
+    joinedDate?: string;
+    /** Defaults to true — false creates the account already deactivated. */
+    isActive?: boolean;
+    /** Defaults to whichever roles are flagged `isDefault`, same as a self-signup. */
+    roles?: string[];
+}
+/**
+ * Every column the `User` table has, except the two secrets (`passwordHash`, `twoFactorSecret` —
+ * never leave the server). Deliberately not a hand-picked subset — a curated field list means
+ * every field a future screen wants is another round-trip through the backend, the client, and
+ * the UI; forwarding the whole safe row once means that never has to happen again.
+ */
+export interface DeploymentUserSummary {
+    id: string;
+    uuid: string;
+    email: string;
+    firstName: string | null;
+    lastName: string | null;
+    displayName: string | null;
+    phone: string | null;
+    username: string | null;
+    photo: string | null;
+    /** Date of birth, ISO 8601. */
+    dob: string | null;
+    gender: string | null;
+    /** ISO 8601. Defaults to the account's creation day. */
+    joinedDate: string;
+    /** ISO 8601. Set on every successful signup/login/OAuth callback, never on a token refresh. */
+    lastLogin: string | null;
+    /** Security/moderation block (see `blockUser`/`unblockUser`) — distinct from `isActive`. Both independently deny login. */
+    blocked: boolean;
+    /** Routine administrative on/off toggle (see `activateUser`/`deactivateUser`) — distinct from `blocked`. Both independently deny login. */
+    isActive: boolean;
+    twoFactorEnabled: boolean;
+    roles: string[];
+    createdBy: string | null;
+    updatedBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `GET /auth/admin/users` on the workspaces variant: the principal is a membership of one workspace. Same "every safe column" policy as `DeploymentUserSummary`. */
+export interface WorkspaceUserSummary {
+    /** WorkspaceMember id — the handle for member-scoped operations on /workspaces/members/*. */
+    memberId: string;
+    userId: string;
+    uuid: string;
+    email: string;
+    firstName: string | null;
+    lastName: string | null;
+    displayName: string | null;
+    phone: string | null;
+    username: string | null;
+    photo: string | null;
+    /** Date of birth, ISO 8601. */
+    dob: string | null;
+    gender: string | null;
+    /** ISO 8601. Defaults to the account's creation day. */
+    joinedDate: string;
+    lastLogin: string | null;
+    blocked: boolean;
+    isActive: boolean;
+    twoFactorEnabled: boolean;
+    roles: string[];
+    createdBy: string | null;
+    updatedBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * The two backend variants name the listed principal differently, and a consumer compiled
+ * against one of them narrows to that arm. `userIdOf()` covers the common case — the id the
+ * `/auth/admin/users/:userId/*` routes take, which is the User id on both variants.
+ */
+export type UserSummary = DeploymentUserSummary | WorkspaceUserSummary;
+export declare function userIdOf(user: UserSummary): string;
+export interface UserListFilter {
+    search?: string;
+    /** 1-indexed. Defaults to 1. */
+    page?: number;
+    /** Defaults to 25, capped at 100. */
+    limit?: number;
+}
+export interface UserListResult {
+    items: UserSummary[];
+    meta: PageMeta;
+}
+export interface WorkspaceSummary {
+    id: string;
+    name: string;
+    createdAt: string;
+    /** The calling user's roles in this workspace. */
+    roles: string[];
+}
+export interface WorkspaceMember {
+    memberId: string;
+    userId: string;
+    email: string;
+    roles: string[];
+    createdAt: string;
+}
+export interface MemberRoles {
+    memberId: string;
+    roles: string[];
+}
+/**
+ * Per-call workspace override for the calls that are workspace-scoped.
+ *
+ * Omitted (or `workspaceId: undefined`) uses the client's active workspace, which is the normal
+ * case — a consumer sets it once. A string acts in that workspace for this one call. `null`
+ * suppresses the header entirely, which is how you ask `/auth/me` for the workspace-free
+ * identity while a workspace is active.
+ */
+export interface WorkspaceScope {
+    workspaceId?: string | null;
+}
+/**
+ * The active workspace, resolved per request. A function keeps ownership of *where the active
+ * workspace lives* with the app — a Zustand store, a route param, AsyncStorage — the same way
+ * `TokenStorage` keeps token persistence out of this package.
+ */
+export type WorkspaceIdResolver = () => string | null | undefined | Promise<string | null | undefined>;
+/** Injected per platform — the only thing that differs between the 4 apps. */
+export interface TokenStorage {
+    get(): Promise<AuthTokens | null>;
+    set(tokens: AuthTokens): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Every column the `Country` table has — there is no secret to withhold, unlike `UserSummary`. */
+export interface CountrySummary {
+    id: string;
+    uuid: string;
+    code: string;
+    name: string;
+    emoji: string;
+    phoneCode: string;
+    currency: string;
+    currencyName: string;
+    isoCode: string;
+    /** A data URI or an externally-hosted URL — stored as-is, never processed server-side. */
+    flag: string | null;
+    isActive: boolean;
+    createdBy: string | null;
+    updatedBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateCountryInput {
+    code: string;
+    name: string;
+    emoji: string;
+    phoneCode: string;
+    currency: string;
+    currencyName: string;
+    isoCode: string;
+    flag?: string | null;
+    isActive?: boolean;
+}
+export interface UpdateCountryInput {
+    code?: string;
+    name?: string;
+    emoji?: string;
+    phoneCode?: string;
+    currency?: string;
+    currencyName?: string;
+    isoCode?: string;
+    flag?: string | null;
+    isActive?: boolean;
+}
+export interface CountryListFilter {
+    search?: string;
+    /** 1-indexed. Defaults to 1. */
+    page?: number;
+    /** Defaults to 25, capped at 100. */
+    limit?: number;
+    /** Pass true for a picker/dropdown — omitted returns everything, active or not. */
+    activeOnly?: boolean;
+}
+export interface CountryListResult {
+    items: CountrySummary[];
+    meta: PageMeta;
+}
+/** Every column the `Language` table has — there is no secret to withhold, unlike `UserSummary`. */
+export interface LanguageSummary {
+    id: string;
+    uuid: string;
+    code: string;
+    name: string;
+    nativeName: string;
+    direction: "ltr" | "rtl" | (string & {});
+    /** Given to a new deployment's default locale. */
+    isDefault: boolean;
+    isActive: boolean;
+    createdBy: string | null;
+    updatedBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateLanguageInput {
+    code: string;
+    name: string;
+    nativeName: string;
+    /** Defaults to "ltr" when creating. */
+    direction?: "ltr" | "rtl";
+    isDefault?: boolean;
+    isActive?: boolean;
+}
+export interface UpdateLanguageInput {
+    code?: string;
+    name?: string;
+    nativeName?: string;
+    direction?: "ltr" | "rtl";
+    isDefault?: boolean;
+    isActive?: boolean;
+}
+export interface LanguageListFilter {
+    search?: string;
+    /** 1-indexed. Defaults to 1. */
+    page?: number;
+    /** Defaults to 25, capped at 100. */
+    limit?: number;
+    /** Pass true for a picker/dropdown — omitted returns everything, active or not. */
+    activeOnly?: boolean;
+}
+export interface LanguageListResult {
+    items: LanguageSummary[];
+    meta: PageMeta;
+}
+/**
+ * End-users managed by admins — no login capability, and not related to the RBAC `UserSummary`
+ * above. Every column the `Customer` table has — there is no login credential to withhold.
+ */
+export interface CustomerSummary {
+    id: string;
+    uuid: string;
+    firstName: string | null;
+    lastName: string | null;
+    /** Unique across the deployment. */
+    username: string | null;
+    email: string;
+    /** Unique across the deployment. */
+    phone: string | null;
+    dob: string | null;
+    gender: string | null;
+    joinedDate: string;
+    /** A data URI or an externally-hosted URL — stored as-is, never processed server-side. */
+    photo: string | null;
+    isEmailVerified: boolean;
+    isPhoneVerified: boolean;
+    isActive: boolean;
+    createdBy: string | null;
+    updatedBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateCustomerInput {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    username?: string;
+    phone?: string;
+    dob?: string;
+    gender?: string;
+    /** Defaults to today when creating. */
+    joinedDate?: string;
+    photo?: string;
+    isEmailVerified?: boolean;
+    isPhoneVerified?: boolean;
+    isActive?: boolean;
+}
+export interface UpdateCustomerInput {
+    email?: string;
+    firstName?: string | null;
+    lastName?: string | null;
+    username?: string | null;
+    phone?: string | null;
+    dob?: string | null;
+    gender?: string | null;
+    joinedDate?: string;
+    photo?: string | null;
+    isEmailVerified?: boolean;
+    isPhoneVerified?: boolean;
+    isActive?: boolean;
+}
+export interface CustomerListFilter {
+    search?: string;
+    /** 1-indexed. Defaults to 1. */
+    page?: number;
+    /** Defaults to 25, capped at 100. */
+    limit?: number;
+    /** Pass true for a picker/dropdown — omitted returns everything, active or not. */
+    activeOnly?: boolean;
+}
+export interface CustomerListResult {
+    items: CustomerSummary[];
+    meta: PageMeta;
+}
+export declare class AuthApiError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}

package/dist/types.js

@@ -0,0 +1,13 @@
+export function userIdOf(user) {
+    return "userId" in user ? user.userId : user.id;
+}
+export class AuthApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "AuthApiError";
+    }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@simple-auth-kit/auth-client",
+  "version": "1.0.0",
+  "description": "Shared, framework-agnostic auth API client for the easy-auth backend. Used by all 4 client apps (admin-nextjs, admin-react, mobile-expo, mobile-bare-rn) — the auth flow and API contract are identical across them, only the injected TokenStorage adapter differs per platform (cookies-next on web, AsyncStorage on mobile).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}