@~lyre/auth 0.1.1 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ and identity handling (HMAC-signed cookies, the accounts login → callback →
 logout exchange, tenant resolution), plus an optional turnkey **SvelteKit**
 adapter that wires it all up in a few lines.
 
-Ships as raw TypeScript source.
+Ships built ESM output from `dist/`, with type declarations.
 
 ## Install
 

package/dist/admin.d.ts

@@ -0,0 +1,206 @@
+interface AccountsAdminOptions {
+    /** Accounts base URL, e.g. `https://accounts.example.com`. */
+    baseUrl: string;
+    /** A user session id (bearer) for session-authed endpoints (invites, profile update, user list). */
+    sessionToken?: string;
+    /** A machine service key (`sk_…`) for `x-api-key`-authed reads (group members). */
+    serviceKey?: string;
+    /** Override the fetch implementation (defaults to the global). */
+    fetchImpl?: typeof fetch;
+}
+interface AccountsUser {
+    id: string;
+    email: string;
+    name?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    emailVerified?: boolean;
+    /** The user's avatar URL (from their latest OAuth sign-in with a picture, or their upload). */
+    avatarUrl?: string | null;
+    profileData?: Record<string, string>;
+    userGroups?: Array<{
+        id: string;
+        slug?: string;
+        displayName?: string;
+        role?: string;
+    }>;
+    apps?: Array<{
+        id: string;
+        slug: string;
+        name?: string;
+    }>;
+    [key: string]: unknown;
+}
+interface ChangePasswordResult {
+    success: boolean;
+    mode?: 'set' | 'changed';
+    revokedCount?: number;
+    error?: string;
+}
+interface ListUsersQuery {
+    tenantId?: string;
+    appId?: string;
+    q?: string;
+    name?: string;
+    email?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListUsersResult {
+    users: AccountsUser[];
+    pagination?: {
+        total: number;
+        limit: number;
+        offset: number;
+    };
+}
+interface AppMember {
+    id: string;
+    email: string;
+    name?: string | null;
+    via?: 'member' | 'role';
+}
+interface InviteResult {
+    /** `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 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;
+    createdAt: string;
+    expiresAt: string;
+    /** The inviter's email, when still resolvable. */
+    invitedByEmail?: string | null;
+}
+interface GroupMember {
+    id: string;
+    email: string;
+    name?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    role?: string | null;
+}
+/** Thrown on a non-2xx Accounts response so callers can surface the upstream message + status. */
+declare class AccountsAdminError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined);
+}
+declare class AccountsAdmin {
+    private readonly opts;
+    private readonly base;
+    private readonly f;
+    constructor(opts: AccountsAdminOptions);
+    /** List/search users in a tenant. Session-authed (caller must be privileged in the tenant). */
+    listUsers(query?: ListUsersQuery): Promise<ListUsersResult>;
+    /** One user's full detail (includes `profileData`, `userGroups`, `apps`). Session-authed. */
+    getUser(userId: string): Promise<AccountsUser>;
+    /** Update a user (self, or admin/owner/super-admin). `profileData` requires `appId`. Session-authed.
+     *  Password is NOT set here — use {@link changePassword} (Accounts verifies the current password). */
+    updateUser(userId: string, input: {
+        name?: string;
+        email?: string;
+        appId?: string;
+        profileData?: Record<string, string>;
+    }): Promise<AccountsUser>;
+    /** Change the signed-in user's password. Session-authed; Accounts verifies `currentPassword` and,
+     *  with `revokeOtherSessions`, logs the user out everywhere else. The target is the session's own
+     *  user — no id is passed. */
+    changePassword(input: {
+        currentPassword: string;
+        newPassword: string;
+        confirmPassword?: string;
+        revokeOtherSessions?: boolean;
+    }): Promise<ChangePasswordResult>;
+    /**
+     * 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;
+    }): Promise<InviteResult>;
+    /** 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. */
+    removeAppUser(appSlug: string, userId: string): Promise<void>;
+    /** 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
+     *  are stored as strings by Accounts; booleans are serialised. Session-authed. */
+    setAppProfile(userId: string, appId: string, profile: Record<string, string | number | boolean>): Promise<AccountsUser>;
+    /** Upload a user's avatar image. The bytes are stored by Accounts and a public URL is returned +
+     *  persisted (source = 'upload', which survives later OAuth sign-ins). Session-authed, self-only.
+     *  `image` is the file bytes (Blob/Buffer/Uint8Array); `mimeType` + `filename` describe it. */
+    uploadAvatar(userId: string, image: Blob | ArrayBuffer | Uint8Array, opts?: {
+        mimeType?: string;
+        filename?: string;
+    }): Promise<{
+        avatarUrl: string;
+    }>;
+    /** Remove a user's uploaded avatar (clears it, or reverts to their latest OAuth picture if any).
+     *  Session-authed, self-only. */
+    removeAvatar(userId: string): Promise<{
+        avatarUrl: string | null;
+    }>;
+    private request;
+}
+/** 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, type PendingInvite, createAccountsAdmin };

package/dist/admin.js

@@ -0,0 +1,248 @@
+// src/admin.ts
+var AccountsAdminError = class extends Error {
+  constructor(status, message, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "AccountsAdminError";
+  }
+  status;
+  body;
+};
+var AccountsAdmin = class {
+  constructor(opts) {
+    this.opts = opts;
+    const base = (opts.baseUrl ?? "").trim();
+    if (!base) throw new Error("AccountsAdmin: baseUrl is required.");
+    this.base = base.replace(/\/+$/, "");
+    this.f = opts.fetchImpl ?? fetch;
+  }
+  opts;
+  base;
+  f;
+  // ── Users ──────────────────────────────────────────────────────────────────
+  /** List/search users in a tenant. Session-authed (caller must be privileged in the tenant). */
+  async listUsers(query = {}) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0 && v !== null) qs.set(k, String(v));
+    }
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    const data = await this.request(
+      "GET",
+      `/api/auth/users${suffix}`,
+      { auth: "session" }
+    );
+    return { users: data.users ?? [], ...data.pagination ? { pagination: data.pagination } : {} };
+  }
+  /** One user's full detail (includes `profileData`, `userGroups`, `apps`). Session-authed. */
+  async getUser(userId) {
+    return this.request("GET", `/api/auth/users/${encodeURIComponent(userId)}`, {
+      auth: "session"
+    });
+  }
+  /** Update a user (self, or admin/owner/super-admin). `profileData` requires `appId`. Session-authed.
+   *  Password is NOT set here — use {@link changePassword} (Accounts verifies the current password). */
+  async updateUser(userId, input) {
+    return this.request("PATCH", `/api/auth/users/${encodeURIComponent(userId)}`, {
+      auth: "session",
+      body: input
+    });
+  }
+  /** Change the signed-in user's password. Session-authed; Accounts verifies `currentPassword` and,
+   *  with `revokeOtherSessions`, logs the user out everywhere else. The target is the session's own
+   *  user — no id is passed. */
+  async changePassword(input) {
+    return this.request("POST", "/api/auth/change-password", {
+      auth: "session",
+      body: {
+        currentPassword: input.currentPassword,
+        newPassword: input.newPassword,
+        confirmPassword: input.confirmPassword ?? input.newPassword,
+        ...input.revokeOtherSessions !== void 0 ? { revokeOtherSessions: input.revokeOtherSessions } : {}
+      }
+    });
+  }
+  // ── App membership (invite / list / remove) ─────────────────────────────────
+  /**
+   * 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
+    });
+  }
+  /** 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(
+      "GET",
+      `/api/auth/apps/${encodeURIComponent(appSlug)}/users`,
+      { auth: "session" }
+    );
+    return data.users ?? [];
+  }
+  /** Revoke a user's access to an app. Session-authed. */
+  async removeAppUser(appSlug, userId) {
+    await this.request(
+      "DELETE",
+      `/api/auth/apps/${encodeURIComponent(appSlug)}/users?userId=${encodeURIComponent(userId)}`,
+      { auth: "session" }
+    );
+  }
+  // ── Groups (agent picker) ───────────────────────────────────────────────────
+  /** Members of a user_group (the workspace's agents). Service-key authed (`stats:read`). */
+  async listGroupMembers(groupId, opts = {}) {
+    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" }
+    );
+    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. */
+  async getAppProfile(userId) {
+    const user = await this.getUser(userId);
+    return user.profileData ?? {};
+  }
+  /** Write app-scoped `profileData` fields for a user (e.g. availability, soundEnabled). All values
+   *  are stored as strings by Accounts; booleans are serialised. Session-authed. */
+  async setAppProfile(userId, appId, profile) {
+    const profileData = {};
+    for (const [k, v] of Object.entries(profile)) profileData[k] = String(v);
+    return this.updateUser(userId, { appId, profileData });
+  }
+  // ── Avatar (uploaded image; social avatars are captured server-side on sign-in) ─
+  /** Upload a user's avatar image. The bytes are stored by Accounts and a public URL is returned +
+   *  persisted (source = 'upload', which survives later OAuth sign-ins). Session-authed, self-only.
+   *  `image` is the file bytes (Blob/Buffer/Uint8Array); `mimeType` + `filename` describe it. */
+  async uploadAvatar(userId, image, opts = {}) {
+    if (!this.opts.sessionToken) {
+      throw new Error("AccountsAdmin: a session token is required to upload an avatar.");
+    }
+    const mimeType = opts.mimeType ?? "application/octet-stream";
+    const blob = image instanceof Blob ? image : new Blob([image], { type: mimeType });
+    const form = new FormData();
+    form.append("avatar", blob, opts.filename ?? "avatar");
+    const res = await this.f(
+      new URL(`/api/auth/users/${encodeURIComponent(userId)}/avatar`, this.base),
+      {
+        method: "POST",
+        headers: { authorization: `Bearer ${this.opts.sessionToken}`, accept: "application/json" },
+        body: form
+      }
+    );
+    const text = await res.text();
+    const parsed = text ? JSON.parse(text) : {};
+    if (!res.ok) {
+      throw new AccountsAdminError(res.status, parsed?.error ?? "Avatar upload failed.", parsed);
+    }
+    return parsed;
+  }
+  /** Remove a user's uploaded avatar (clears it, or reverts to their latest OAuth picture if any).
+   *  Session-authed, self-only. */
+  async removeAvatar(userId) {
+    return this.request(
+      "DELETE",
+      `/api/auth/users/${encodeURIComponent(userId)}/avatar`,
+      { auth: "session" }
+    );
+  }
+  // ── internals ───────────────────────────────────────────────────────────────
+  async request(method, path, opts) {
+    const headers = { accept: "application/json" };
+    if (opts.auth === "session") {
+      if (!this.opts.sessionToken) {
+        throw new Error(`AccountsAdmin: a session token is required for ${method} ${path}.`);
+      }
+      headers.authorization = `Bearer ${this.opts.sessionToken}`;
+    } else {
+      if (!this.opts.serviceKey) {
+        throw new Error(`AccountsAdmin: a service key is required for ${method} ${path}.`);
+      }
+      headers["x-api-key"] = this.opts.serviceKey;
+    }
+    let bodyStr;
+    if (opts.body !== void 0) {
+      bodyStr = JSON.stringify(opts.body);
+      headers["content-type"] = "application/json";
+    }
+    const res = await this.f(new URL(path, this.base), { method, headers, body: bodyStr });
+    const text = await res.text();
+    let parsed;
+    try {
+      parsed = text ? JSON.parse(text) : void 0;
+    } catch {
+      parsed = text;
+    }
+    if (!res.ok) {
+      const message = (parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : void 0) ?? `Accounts request failed with status ${res.status}.`;
+      throw new AccountsAdminError(res.status, message, parsed);
+    }
+    return parsed;
+  }
+};
+function createAccountsAdmin(opts) {
+  return new AccountsAdmin(opts);
+}
+export {
+  AccountsAdmin,
+  AccountsAdminError,
+  createAccountsAdmin
+};

package/package.json

@@ -1,69 +1,73 @@
 {
-  "name": "@~lyre/auth",
-  "version": "0.1.1",
-  "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"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts src/sveltekit.ts src/nest.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.4.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"
+	}
 }