@~lyre/auth 0.3.0 → 0.5.0

package/dist/admin.d.ts

@@ -61,11 +61,54 @@ interface AppMember {
     via?: 'member' | 'role';
 }
 interface InviteResult {
-    /** `added` = the email already had an Accounts user and was granted app access immediately;
-     *  `invited` = a new invite was created and an accept link emailed. */
-    status: 'added' | 'invited';
+    /** `invited` = an invite was created and an accept link emailed;
+     *  `already_member` = that email already has access to the app (returned with HTTP 409).
+     *  (`added` is legacy: Accounts no longer grants access without acceptance.) */
+    status: 'invited' | 'already_member' | 'added';
+    /** The workspace the invitee joins on acceptance, echoed back; null when none was requested. */
+    userGroupId?: string | null;
     [key: string]: unknown;
 }
+/**
+ * A profile field an app collects about a user — the spec a consumer renders a form input from.
+ * Mirrors Accounts' `fields` registry, so a consumer never hardcodes one app's idea of a person.
+ */
+interface ProfileFieldSpec {
+    id: string;
+    fieldName: string;
+    label: string;
+    fieldType: string;
+    required: boolean;
+    hidden: boolean;
+    enumValues: string[] | null;
+    inputPrefix: string | null;
+    validationRegex: string | null;
+    validationMessage: string | null;
+    displayOrder: number;
+}
+/** Whether an email can be invited to an app. See `checkInviteEmail`. */
+interface InviteEmailCheck {
+    email: string;
+    /** `member` = already has app access; `invited` = a live invite exists; `available` = go ahead. */
+    state: 'member' | 'invited' | 'available';
+    /** Whether an Accounts user already exists for this address (they keep their own profile). */
+    hasAccount: boolean;
+    /** When the pending invite lapses — only for `invited`. */
+    expiresAt?: string;
+}
+/** A pending (not yet accepted, not yet expired) app invitation. */
+interface PendingInvite {
+    id: string;
+    email: string;
+    /** The workspace the invitee joins on acceptance; null for a group-less invite. */
+    userGroupId: string | null;
+    /** Values captured on the invite form, keyed by field name. Prefills the accept form. */
+    profileData?: Record<string, string>;
+    createdAt: string;
+    expiresAt: string;
+    /** The inviter's email, when still resolvable. */
+    invitedByEmail?: string | null;
+}
 interface GroupMember {
     id: string;
     email: string;
@@ -106,11 +149,36 @@ declare class AccountsAdmin {
         confirmPassword?: string;
         revokeOtherSessions?: boolean;
     }): Promise<ChangePasswordResult>;
-    /** Invite an email to an app: adds an existing Accounts user immediately, else emails an accept
-     *  link. Session-authed (caller must have access to the app). */
+    /**
+     * Invite an email to an app, emailing them an accept link. Session-authed (the caller must have
+     * access to the app).
+     *
+     * Pass `userGroupId` to say which WORKSPACE the invitee joins when they accept. Omit it and they
+     * join the app but no workspace — Accounts then treats them as a brand-new user on first login and
+     * sends them to create their own, instead of landing in the workspace that invited them. Accounts
+     * validates the group against the CALLER's own memberships, so this cannot target a foreign group.
+     */
     inviteToApp(appSlug: string, input: {
         email: string;
+        userGroupId?: string | null;
+        /** Profile values from the invite form, keyed by field name (see `listAppProfileFields`).
+         *  Accounts drops any key the app does not collect, so authorization-shaped values
+         *  (role, assignability) can never be set from here. */
+        profileData?: Record<string, string> | null;
     }): Promise<InviteResult>;
+    /**
+     * The profile fields this app collects about a user — the spec to render an invite form from.
+     * Session-authed. Never includes email: that is the invite's identity, not a profile value.
+     */
+    listAppProfileFields(appSlug: string): Promise<ProfileFieldSpec[]>;
+    /**
+     * Whether an email can be invited — for a live check on an invite form, so the inviter learns
+     * BEFORE submitting that someone is already a member or already invited. Email only, exact match.
+     * Session-authed.
+     */
+    checkInviteEmail(appSlug: string, email: string): Promise<InviteEmailCheck>;
+    /** Revoke a pending invite (withdraw one sent in error). Session-authed. */
+    revokeAppInvite(appSlug: string, inviteId: string): Promise<void>;
     /** Everyone with access to an app. Session-authed. */
     listAppUsers(appSlug: string): Promise<AppMember[]>;
     /** Revoke a user's access to an app. Session-authed. */
@@ -118,7 +186,43 @@ declare class AccountsAdmin {
     /** Members of a user_group (the workspace's agents). Service-key authed (`stats:read`). */
     listGroupMembers(groupId: string, opts?: {
         appId?: string;
+        search?: string;
+        limit?: number;
+        offset?: number;
     }): Promise<GroupMember[]>;
+    /**
+     * A PAGE of a group's members, plus the total before paging — what a paginated, searchable user
+     * list needs. `listGroupMembers` stays the "give me everyone" convenience for the agent picker.
+     *
+     * Search and paging are applied by Accounts in SQL: fetching every member to filter in the browser
+     * does not scale, and leaves the pager unable to know how many pages exist. Omit `limit` and the
+     * full list comes back (with `totalCount` equal to its length).
+     */
+    listGroupMembersPage(groupId: string, opts?: {
+        appId?: string;
+        search?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        members: GroupMember[];
+        totalCount: number;
+    }>;
+    /**
+     * The app's PENDING invites — people invited but not yet accepted. Session-authed.
+     *
+     * An invitee is not a membership, so they appear in no member list; without this a successful
+     * invite looks like nothing happened until the person accepts. Pass `userGroupId` to scope to one
+     * workspace. Accounts excludes consumed and expired invites.
+     */
+    listAppInvites(appSlug: string, opts?: {
+        userGroupId?: string;
+        search?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        invites: PendingInvite[];
+        totalCount: number;
+    }>;
     /** Read a user's app-scoped `profileData` (the store for per-app preferences). Session-authed. */
     getAppProfile(userId: string): Promise<Record<string, string>>;
     /** Write app-scoped `profileData` fields for a user (e.g. availability, soundEnabled). All values
@@ -143,4 +247,4 @@ declare class AccountsAdmin {
 /** Convenience factory mirroring the SDK's other `create*` helpers. */
 declare function createAccountsAdmin(opts: AccountsAdminOptions): AccountsAdmin;
 
-export { AccountsAdmin, AccountsAdminError, type AccountsAdminOptions, type AccountsUser, type AppMember, type ChangePasswordResult, type GroupMember, type InviteResult, type ListUsersQuery, type ListUsersResult, createAccountsAdmin };
+export { AccountsAdmin, AccountsAdminError, type AccountsAdminOptions, type AccountsUser, type AppMember, type ChangePasswordResult, type GroupMember, type InviteEmailCheck, type InviteResult, type ListUsersQuery, type ListUsersResult, type PendingInvite, type ProfileFieldSpec, createAccountsAdmin };

package/dist/admin.js

@@ -64,14 +64,53 @@ var AccountsAdmin = class {
     });
   }
   // ── App membership (invite / list / remove) ─────────────────────────────────
-  /** Invite an email to an app: adds an existing Accounts user immediately, else emails an accept
-   *  link. Session-authed (caller must have access to the app). */
+  /**
+   * Invite an email to an app, emailing them an accept link. Session-authed (the caller must have
+   * access to the app).
+   *
+   * Pass `userGroupId` to say which WORKSPACE the invitee joins when they accept. Omit it and they
+   * join the app but no workspace — Accounts then treats them as a brand-new user on first login and
+   * sends them to create their own, instead of landing in the workspace that invited them. Accounts
+   * validates the group against the CALLER's own memberships, so this cannot target a foreign group.
+   */
   async inviteToApp(appSlug, input) {
     return this.request("POST", `/api/auth/apps/${encodeURIComponent(appSlug)}/invites`, {
       auth: "session",
       body: input
     });
   }
+  /**
+   * The profile fields this app collects about a user — the spec to render an invite form from.
+   * Session-authed. Never includes email: that is the invite's identity, not a profile value.
+   */
+  async listAppProfileFields(appSlug) {
+    const data = await this.request(
+      "GET",
+      `/api/auth/apps/${encodeURIComponent(appSlug)}/profile-fields`,
+      { auth: "session" }
+    );
+    return data.fields ?? [];
+  }
+  /**
+   * Whether an email can be invited — for a live check on an invite form, so the inviter learns
+   * BEFORE submitting that someone is already a member or already invited. Email only, exact match.
+   * Session-authed.
+   */
+  async checkInviteEmail(appSlug, email) {
+    return this.request(
+      "GET",
+      `/api/auth/apps/${encodeURIComponent(appSlug)}/invites/lookup?email=${encodeURIComponent(email)}`,
+      { auth: "session" }
+    );
+  }
+  /** Revoke a pending invite (withdraw one sent in error). Session-authed. */
+  async revokeAppInvite(appSlug, inviteId) {
+    await this.request(
+      "DELETE",
+      `/api/auth/apps/${encodeURIComponent(appSlug)}/invites?inviteId=${encodeURIComponent(inviteId)}`,
+      { auth: "session" }
+    );
+  }
   /** Everyone with access to an app. Session-authed. */
   async listAppUsers(appSlug) {
     const data = await this.request(
@@ -92,13 +131,53 @@ var AccountsAdmin = class {
   // ── Groups (agent picker) ───────────────────────────────────────────────────
   /** Members of a user_group (the workspace's agents). Service-key authed (`stats:read`). */
   async listGroupMembers(groupId, opts = {}) {
-    const suffix = opts.appId ? `?appId=${encodeURIComponent(opts.appId)}` : "";
+    const { members } = await this.listGroupMembersPage(groupId, opts);
+    return members;
+  }
+  /**
+   * A PAGE of a group's members, plus the total before paging — what a paginated, searchable user
+   * list needs. `listGroupMembers` stays the "give me everyone" convenience for the agent picker.
+   *
+   * Search and paging are applied by Accounts in SQL: fetching every member to filter in the browser
+   * does not scale, and leaves the pager unable to know how many pages exist. Omit `limit` and the
+   * full list comes back (with `totalCount` equal to its length).
+   */
+  async listGroupMembersPage(groupId, opts = {}) {
+    const qs = new URLSearchParams();
+    if (opts.appId) qs.set("appId", opts.appId);
+    if (opts.search) qs.set("search", opts.search);
+    if (opts.limit !== void 0) qs.set("limit", String(opts.limit));
+    if (opts.offset !== void 0) qs.set("offset", String(opts.offset));
+    const suffix = qs.size ? `?${qs}` : "";
     const data = await this.request(
       "GET",
       `/api/auth/user-groups/${encodeURIComponent(groupId)}/members${suffix}`,
       { auth: "key" }
     );
-    return data.members ?? [];
+    const members = data.members ?? [];
+    return { members, totalCount: data.totalCount ?? members.length };
+  }
+  /**
+   * The app's PENDING invites — people invited but not yet accepted. Session-authed.
+   *
+   * An invitee is not a membership, so they appear in no member list; without this a successful
+   * invite looks like nothing happened until the person accepts. Pass `userGroupId` to scope to one
+   * workspace. Accounts excludes consumed and expired invites.
+   */
+  async listAppInvites(appSlug, opts = {}) {
+    const qs = new URLSearchParams();
+    if (opts.userGroupId) qs.set("userGroupId", opts.userGroupId);
+    if (opts.search) qs.set("search", opts.search);
+    if (opts.limit !== void 0) qs.set("limit", String(opts.limit));
+    if (opts.offset !== void 0) qs.set("offset", String(opts.offset));
+    const suffix = qs.size ? `?${qs}` : "";
+    const data = await this.request(
+      "GET",
+      `/api/auth/apps/${encodeURIComponent(appSlug)}/invites${suffix}`,
+      { auth: "session" }
+    );
+    const invites = data.invites ?? [];
+    return { invites, totalCount: data.totalCount ?? invites.length };
   }
   // ── App-scoped profile (availability / sound / any per-app preference) ───────
   /** Read a user's app-scoped `profileData` (the store for per-app preferences). Session-authed. */

package/package.json

@@ -1,73 +1,73 @@
 {
-  "name": "@~lyre/auth",
-  "version": "0.3.0",
-  "description": "Shared Axis Accounts auth SDK — framework-agnostic session/identity core (HMAC-signed cookies, accounts login/callback/logout) plus an optional turnkey SvelteKit adapter.",
-  "type": "module",
-  "sideEffects": false,
-  "license": "MIT",
-  "author": "Britam Trust Services / Lyre",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kigathi-chege/lyre-auth-sdk.git"
-  },
-  "homepage": "https://github.com/kigathi-chege/lyre-auth-sdk#readme",
-  "bugs": {
-    "url": "https://github.com/kigathi-chege/lyre-auth-sdk/issues"
-  },
-  "keywords": [
-    "auth",
-    "sso",
-    "accounts",
-    "session",
-    "sveltekit",
-    "hmac",
-    "lyre"
-  ],
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./sveltekit": {
-      "types": "./dist/sveltekit.d.ts",
-      "import": "./dist/sveltekit.js"
-    },
-    "./nest": {
-      "types": "./dist/nest.d.ts",
-      "import": "./dist/nest.js"
-    },
-    "./admin": {
-      "types": "./dist/admin.d.ts",
-      "import": "./dist/admin.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts src/sveltekit.ts src/nest.ts src/admin.ts --format esm --dts --clean",
-    "check": "tsc --noEmit"
-  },
-  "peerDependencies": {
-    "@sveltejs/kit": "^2.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@sveltejs/kit": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@sveltejs/kit": "^2.0.0",
-    "@types/node": "^22",
-    "tsup": "^8.3.5",
-    "typescript": "^6.0.2"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
+	"name": "@~lyre/auth",
+	"version": "0.5.0",
+	"description": "Shared Axis Accounts auth SDK \u2014 framework-agnostic session/identity core (HMAC-signed cookies, accounts login/callback/logout) plus an optional turnkey SvelteKit adapter.",
+	"type": "module",
+	"sideEffects": false,
+	"license": "MIT",
+	"author": "Britam Trust Services / Lyre",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kigathi-chege/lyre-auth-sdk.git"
+	},
+	"homepage": "https://github.com/kigathi-chege/lyre-auth-sdk#readme",
+	"bugs": {
+		"url": "https://github.com/kigathi-chege/lyre-auth-sdk/issues"
+	},
+	"keywords": [
+		"auth",
+		"sso",
+		"accounts",
+		"session",
+		"sveltekit",
+		"hmac",
+		"lyre"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./sveltekit": {
+			"types": "./dist/sveltekit.d.ts",
+			"import": "./dist/sveltekit.js"
+		},
+		"./nest": {
+			"types": "./dist/nest.d.ts",
+			"import": "./dist/nest.js"
+		},
+		"./admin": {
+			"types": "./dist/admin.d.ts",
+			"import": "./dist/admin.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "tsup src/index.ts src/sveltekit.ts src/nest.ts src/admin.ts --format esm --dts --clean",
+		"check": "tsc --noEmit"
+	},
+	"peerDependencies": {
+		"@sveltejs/kit": "^2.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@sveltejs/kit": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@sveltejs/kit": "^2.0.0",
+		"@types/node": "^22",
+		"tsup": "^8.3.5",
+		"typescript": "^6.0.2"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
 }