@~lyre/auth 0.1.1 → 0.3.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,146 @@
+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 {
+    /** `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';
+    [key: string]: unknown;
+}
+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: adds an existing Accounts user immediately, else emails an accept
+     *  link. Session-authed (caller must have access to the app). */
+    inviteToApp(appSlug: string, input: {
+        email: string;
+    }): Promise<InviteResult>;
+    /** 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;
+    }): Promise<GroupMember[]>;
+    /** 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, createAccountsAdmin };

package/dist/admin.js

@@ -0,0 +1,193 @@
+// 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: adds an existing Accounts user immediately, else emails an accept
+   *  link. Session-authed (caller must have access to the app). */
+  async inviteToApp(appSlug, input) {
+    return this.request("POST", `/api/auth/apps/${encodeURIComponent(appSlug)}/invites`, {
+      auth: "session",
+      body: input
+    });
+  }
+  /** 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 suffix = opts.appId ? `?appId=${encodeURIComponent(opts.appId)}` : "";
+    const data = await this.request(
+      "GET",
+      `/api/auth/user-groups/${encodeURIComponent(groupId)}/members${suffix}`,
+      { auth: "key" }
+    );
+    return data.members ?? [];
+  }
+  // ── 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,6 +1,6 @@
 {
   "name": "@~lyre/auth",
-  "version": "0.1.1",
+  "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,
@@ -38,6 +38,10 @@
       "types": "./dist/nest.d.ts",
       "import": "./dist/nest.js"
     },
+    "./admin": {
+      "types": "./dist/admin.d.ts",
+      "import": "./dist/admin.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -46,7 +50,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/sveltekit.ts src/nest.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/sveltekit.ts src/nest.ts src/admin.ts --format esm --dts --clean",
     "check": "tsc --noEmit"
   },
   "peerDependencies": {