@loopwise/admin-sdk 0.1.0-beta.1 → 0.1.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @loopwise/admin-sdk
 
+## 0.1.0-beta.3
+
+DX quick wins informed by the first real integration ([nii-course-system](https://github.com/niischool-tw/nii-course-system/pull/38),
+agent-driven, shipped against `0.1.0-beta.0`). See
+[TEACH-18885](https://linear.app/kaik/issue/TEACH-18885) for the full
+feedback report; [TEACH-18912](https://linear.app/kaik/issue/TEACH-18912)
+for this PR.
+
+### Breaking changes
+
+- **`baseUrl` → `baseURL`** on both `LoopwiseAuthOptions` (better-auth
+  wrapper) and `LoopwiseAdminConfig` (core admin client). Casing now
+  matches better-auth's own `baseURL` / `BETTER_AUTH_URL` convention,
+  removing a same-module typo footgun. Migration is a one-character
+  rename at any call site that passes the option explicitly; TS
+  catches it at compile time. Callers relying on the default are
+  unaffected.
+
+### Features
+
+- **`mapProfileToUser` pass-through on `loopwise({})`** — populate
+  custom `User` columns at sign-up (e.g. `teachifyUserId: profile.sub`)
+  without joining the `account` table. Forwards verbatim to
+  better-auth's `genericOAuth`.
+- **`getLoopwiseRedirectURI({ baseURL, audience? })` helper** exported
+  from `@loopwise/admin-sdk/better-auth`. Returns the exact redirect
+  URI to whitelist on your OAuth client — the better-auth callback
+  path includes a `/oauth2/` segment that's easy to miss otherwise.
+
+### Behavior changes
+
+- **`org_admin` default scope shrunk to `['openid', 'profile', 'email']`**
+  (was `['openid', 'profile', 'email', 'courses:read', 'members:read']`).
+  New OAuth clients don't have API scopes enabled by default, so the
+  old behavior caused `invalid_scope` on the first callback. Pure SSO
+  now works out of the box; callers needing admin GraphQL access pass
+  `scopes` explicitly AND enable matching scopes on their OAuth client
+  in the Loopwise admin UI.
+
+### Docs
+
+- README adds Redirect URI, Scopes, Profile-mapping, and Roadmap
+  sections informed by the same feedback report.
+
+## 0.1.0-beta.2
+
+Add second typed resource:
+
+- `admin.members.list({ perPage, page, role })` returns `AdminMemberPage`
+  (mirrors `courses.list` shape).
+- `AdminMember`: `id`, `name`, `email`, `phoneNumber`, `createdAt`,
+  `lastSignInAt`.
+- `AdminMemberRole`: `'student' | 'teaching_assistant'` mirrors the
+  schema enum.
+- Requires OAuth scope `members:read`.
+
 ## 0.1.0-beta.1
 
 No functional changes. Validates the tag-triggered OIDC publish path

package/README.md

@@ -55,4 +55,92 @@ export default async function Page() {
 }
 ```
 
-See [TEACH-18856](https://linear.app/kaik/issue/TEACH-18856) for the design rationale.
+### Redirect URI
+
+Better Auth's catch-all handler is mounted at `/api/auth/[...all]`, but the
+`genericOAuth` plugin's callback path is `/oauth2/callback/<providerId>` —
+note the `oauth2/` segment (different from many OAuth tutorials that show
+`/api/auth/callback/...`).
+
+Use the exported helper to compute the exact URI to whitelist on your
+OAuth client:
+
+```ts
+import { getLoopwiseRedirectURI } from '@loopwise/admin-sdk/better-auth';
+
+console.log(
+  getLoopwiseRedirectURI({ baseURL: process.env.BETTER_AUTH_URL! }),
+);
+// dev:  http://localhost:3000/api/auth/oauth2/callback/loopwise
+// prod: https://your.app/api/auth/oauth2/callback/loopwise
+```
+
+For multi-audience apps, pass `audience: 'member'` to get
+`/oauth2/callback/loopwise-member`.
+
+### Scopes
+
+The wrapper requests `['openid', 'profile', 'email']` by default — the
+minimum needed to identify the user. **Pure SSO works without any
+additional setup.**
+
+To call the admin GraphQL API, override `scopes` with the API scopes you
+need, **and** enable those same scopes on your OAuth client in the
+Loopwise admin UI:
+
+```ts
+loopwise({
+  clientId, clientSecret,
+  scopes: ['openid', 'profile', 'email', 'courses:read', 'members:read'],
+})
+```
+
+Mismatch between requested and enabled scopes surfaces as
+`error=invalid_scope` on the first callback.
+
+### Mapping OAuth claims to your user table
+
+Use `mapProfileToUser` to populate custom columns (declared via
+better-auth's `additionalFields`) at sign-up:
+
+```ts
+loopwise({
+  clientId, clientSecret,
+  mapProfileToUser: (profile) => ({
+    teachifyUserId: profile.sub,
+    // role: profile['loopwise:org_role'],  // pending TEACH-18913
+  }),
+})
+```
+
+The `profile` is whatever `/oauth/userinfo` returns — standard OIDC
+claims today, plus Loopwise-specific `loopwise:*` claims once
+[TEACH-18913](https://linear.app/kaik/issue/TEACH-18913) ships.
+
+## Typed resources roadmap
+
+Currently typed:
+
+- `admin.courses.list({ perPage, page })` — `AdminCoursePage`
+- `admin.members.list({ perPage, page, role })` — `AdminMemberPage`
+
+Coming next (in priority order, informed by integrator feedback):
+
+1. `admin.orders.list / get` — financial flow surface
+2. `admin.enrollments.list` — member ↔ course relationships
+3. Course content drill-down (`lectures`, `sections`)
+4. `admin.coupons / subscriptions / pricing`
+5. Content surfaces (`posts`, `pages`, `comments`)
+
+Need something not yet typed? Use `admin.graphql<TData>({ query })` —
+the raw escape hatch is fully typed via the generic and works against
+the entire admin schema.
+
+## Design notes
+
+- See [TEACH-18856](https://linear.app/kaik/issue/TEACH-18856) for the
+  SDK architectural rationale (why branded `loopwise()` wrapper, why
+  framework-agnostic core, audience model).
+- See [TEACH-18885](https://linear.app/kaik/issue/TEACH-18885) for the
+  first-integration feedback that informed the `0.1.0-beta.3` ergonomics
+  (default scope, redirect URI helper, profile mapping).

package/dist/better-auth.d.mts

@@ -20,17 +20,30 @@ interface LoopwiseAuthOptions {
    */
   audience?: LoopwiseAuthAudience;
   /**
-   * OAuth scopes to request. Defaults to a minimal-but-useful set per
-   * audience. Override to request more (e.g. add `courses:write`,
-   * `payments:read`) or to narrow further.
+   * OAuth scopes to request. Defaults to SSO-minimum
+   * `['openid', 'profile', 'email']`. To call admin GraphQL, override
+   * with the scopes you need AND enable them on the OAuth client in
+   * the Loopwise admin UI (see the `AUDIENCE_PROFILES` note for why
+   * we don't ship API scopes by default).
    */
   scopes?: string[];
   /**
    * Base URL of the Loopwise instance. Defaults to `https://app.loopwise.com`.
    * Discovery doc fetched from
-   * `${baseUrl}/.well-known/oauth-authorization-server`.
+   * `${baseURL}/.well-known/oauth-authorization-server`.
+   *
+   * Casing matches better-auth's `baseURL` / `BETTER_AUTH_URL` convention.
+   */
+  baseURL?: string;
+  /**
+   * Populate custom columns (declared via better-auth's `additionalFields`)
+   * at sign-up — avoids joining the `account` table to read OAuth `sub`
+   * or any other userinfo claim. `loopwise:org_role` lands with TEACH-18913.
+   *
+   * @example
+   *   mapProfileToUser: (profile) => ({ teachifyUserId: profile.sub }),
    */
-  baseUrl?: string;
+  mapProfileToUser?: (profile: Record<string, unknown>) => Record<string, unknown>;
 }
 /**
  * Better-auth plugin for "log in with Loopwise". Wraps `genericOAuth` with
@@ -60,6 +73,34 @@ interface LoopwiseAuthOptions {
  *     }),
  *   ]
  */
+interface GetRedirectURIOptions {
+  /** Same value as better-auth's `baseURL` / `BETTER_AUTH_URL`. */
+  baseURL: string;
+  /** Defaults to `'org_admin'`. Pass `'member'` for `loopwise-member`. */
+  audience?: LoopwiseAuthAudience;
+}
+/**
+ * Compute the exact redirect URI you need to register on your Loopwise
+ * OAuth client. Better Auth's `genericOAuth` plugin uses the path
+ * `/api/auth/oauth2/callback/<providerId>` — note the `oauth2/` segment
+ * (different from many OAuth tutorials that show `/api/auth/callback/...`).
+ *
+ * @example
+ *   // dev
+ *   getLoopwiseRedirectURI({ baseURL: 'http://localhost:3000' });
+ *   // → 'http://localhost:3000/api/auth/oauth2/callback/loopwise'
+ *
+ *   // prod, member audience
+ *   getLoopwiseRedirectURI({
+ *     baseURL: 'https://app.example.com',
+ *     audience: 'member',
+ *   });
+ *   // → 'https://app.example.com/api/auth/oauth2/callback/loopwise-member'
+ *
+ * Use this at app boot to print the URI so you (or your agent) can paste
+ * it straight into the OAuth client's redirect-URI list.
+ */
+declare function getLoopwiseRedirectURI(options: GetRedirectURIOptions): string;
 declare function loopwise(options: LoopwiseAuthOptions): BetterAuthPlugin;
 //#endregion
-export { LoopwiseAuthAudience, LoopwiseAuthOptions, loopwise };
+export { GetRedirectURIOptions, LoopwiseAuthAudience, LoopwiseAuthOptions, getLoopwiseRedirectURI, loopwise };

package/dist/better-auth.mjs

@@ -1,15 +1,14 @@
 import { genericOAuth } from "better-auth/plugins";
 //#region src/better-auth.ts
 const DEFAULT_BASE_URL = "https://app.loopwise.com";
+const BETTER_AUTH_OAUTH2_CALLBACK_PATH = "/api/auth/oauth2/callback";
 const AUDIENCE_PROFILES = {
 	org_admin: {
 		providerId: "loopwise",
 		defaultScopes: [
 			"openid",
 			"profile",
-			"email",
-			"courses:read",
-			"members:read"
+			"email"
 		]
 	},
 	member: {
@@ -22,45 +21,43 @@ const AUDIENCE_PROFILES = {
 	}
 };
 /**
-* Better-auth plugin for "log in with Loopwise". Wraps `genericOAuth` with
-* Loopwise-specific defaults so tenants only need to supply credentials.
+* Compute the exact redirect URI you need to register on your Loopwise
+* OAuth client. Better Auth's `genericOAuth` plugin uses the path
+* `/api/auth/oauth2/callback/<providerId>` — note the `oauth2/` segment
+* (different from many OAuth tutorials that show `/api/auth/callback/...`).
 *
 * @example
-*   import { betterAuth } from 'better-auth';
-*   import { loopwise } from '@loopwise/admin-sdk/better-auth';
+*   // dev
+*   getLoopwiseRedirectURI({ baseURL: 'http://localhost:3000' });
+*   // → 'http://localhost:3000/api/auth/oauth2/callback/loopwise'
 *
-*   export const auth = betterAuth({
-*     database: ...,
-*     plugins: [
-*       loopwise({
-*         clientId: process.env.LOOPWISE_CLIENT_ID!,
-*         clientSecret: process.env.LOOPWISE_CLIENT_SECRET!,
-*       }),
-*     ],
+*   // prod, member audience
+*   getLoopwiseRedirectURI({
+*     baseURL: 'https://app.example.com',
+*     audience: 'member',
 *   });
+*   // → 'https://app.example.com/api/auth/oauth2/callback/loopwise-member'
 *
-* @example Multi-audience (staff + member apps coexisting)
-*   plugins: [
-*     loopwise({ clientId: STAFF_ID, clientSecret: STAFF_SECRET }),
-*     loopwise({
-*       clientId: MEMBER_ID,
-*       clientSecret: MEMBER_SECRET,
-*       audience: 'member',
-*     }),
-*   ]
+* Use this at app boot to print the URI so you (or your agent) can paste
+* it straight into the OAuth client's redirect-URI list.
 */
+function getLoopwiseRedirectURI(options) {
+	const profile = AUDIENCE_PROFILES[options.audience ?? "org_admin"];
+	return `${options.baseURL.replace(/\/$/, "")}${BETTER_AUTH_OAUTH2_CALLBACK_PATH}/${profile.providerId}`;
+}
 function loopwise(options) {
 	const profile = AUDIENCE_PROFILES[options.audience ?? "org_admin"];
-	const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+	const baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
 	return genericOAuth({ config: [{
 		providerId: profile.providerId,
 		clientId: options.clientId,
 		clientSecret: options.clientSecret,
-		discoveryUrl: `${baseUrl}/.well-known/oauth-authorization-server`,
+		discoveryUrl: `${baseURL}/.well-known/oauth-authorization-server`,
 		pkce: true,
 		accessType: "offline",
-		scopes: options.scopes ?? [...profile.defaultScopes]
+		scopes: options.scopes ?? [...profile.defaultScopes],
+		mapProfileToUser: options.mapProfileToUser
 	}] });
 }
 //#endregion
-export { loopwise };
+export { getLoopwiseRedirectURI, loopwise };

package/dist/index.d.mts

@@ -32,12 +32,13 @@ interface LoopwiseAdminConfig {
   /**
    * Base URL of the Loopwise instance. Defaults to `https://app.loopwise.com`.
    * Override for staging (`https://staging.loopwise.com`) or self-hosted.
-   * The SDK appends `/admin/graphql` automatically.
+   * The SDK appends `/admin/graphql` automatically. Casing matches
+   * better-auth's `baseURL` / `BETTER_AUTH_URL` convention.
    */
-  baseUrl?: string;
+  baseURL?: string;
   /**
    * Override the full GraphQL endpoint URL. You normally never set this —
-   * the SDK derives it from `baseUrl`. Use only for non-standard routing
+   * the SDK derives it from `baseURL`. Use only for non-standard routing
    * (proxy with path rewrite, etc.).
    */
   endpoint?: string;
@@ -138,9 +139,57 @@ declare class CoursesResource {
   list(args?: CoursesListArgs): Promise<AdminCoursePage>;
 }
 //#endregion
+//#region src/resources/members.d.ts
+/**
+ * "Member" = non-admin school user. Maps to `Query.users(role: ...)`,
+ * which returns `AdminUserPage` / `AdminUser` (students by default; TAs
+ * when `role: 'teaching_assistant'`). Drop down to `admin.graphql()`
+ * for fields outside this minimal projection (attended courses,
+ * subscriptions, totalSpent, etc.).
+ */
+interface AdminMember {
+  id: string;
+  name: string | null;
+  email: string | null;
+  phoneNumber: string | null;
+  /** Unix timestamp seconds. */
+  createdAt: number;
+  /** Unix timestamp seconds, or null when the member has never signed in. */
+  lastSignInAt: number | null;
+}
+interface AdminMemberPage {
+  nodes: AdminMember[];
+  nodesCount: number;
+  currentPage: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+}
+type AdminMemberRole = 'student' | 'teaching_assistant';
+interface MembersListArgs {
+  /** Items per page. Schema default 20, max 50. */
+  perPage?: number;
+  page?: number;
+  /** Defaults to `'student'` upstream — owner / manager are not selectable. */
+  role?: AdminMemberRole;
+}
+declare class MembersResource {
+  private readonly client;
+  constructor(client: LoopwiseAdminClient);
+  /**
+   * List non-admin school users (students by default; TAs when
+   * `role: 'teaching_assistant'`). Returns the full `AdminUserPage`
+   * shape (nodes + pagination meta) under our `AdminMemberPage` alias.
+   *
+   * Requires OAuth scope `members:read` on the access token.
+   */
+  list(args?: MembersListArgs): Promise<AdminMemberPage>;
+}
+//#endregion
 //#region src/index.d.ts
 interface LoopwiseAdmin {
   readonly courses: CoursesResource;
+  readonly members: MembersResource;
   /**
    * Run a typed GraphQL operation against `/admin/graphql`. The SDK does
    * not parse or validate the document — pass the query string as-is and
@@ -164,4 +213,4 @@ interface LoopwiseAdmin {
 }
 declare function createAdminClient(config: LoopwiseAdminConfig): LoopwiseAdmin;
 //#endregion
-export { type AdminCourse, type AdminCoursePage, type CoursesListArgs, type GraphQLError, type GraphQLRequest, LoopwiseAdmin, type LoopwiseAdminConfig, LoopwiseError, type LoopwiseErrorCode, createAdminClient };
+export { type AdminCourse, type AdminCoursePage, type AdminMember, type AdminMemberPage, type AdminMemberRole, type CoursesListArgs, type GraphQLError, type GraphQLRequest, LoopwiseAdmin, type LoopwiseAdminConfig, LoopwiseError, type LoopwiseErrorCode, type MembersListArgs, createAdminClient };

package/dist/index.mjs

@@ -32,7 +32,7 @@ var LoopwiseAdminClient = class {
 		if (!config.accessToken || !config.accessToken.trim()) throw new LoopwiseError("CONFIG", "accessToken is required. Pass it to createAdminClient({ accessToken }).");
 		this.accessToken = config.accessToken;
 		this.refreshAccessToken = config.refreshAccessToken;
-		this.endpoint = config.endpoint ?? resolveEndpoint(config.baseUrl);
+		this.endpoint = config.endpoint ?? resolveEndpoint(config.baseURL);
 		if (config.fetch) this.fetchImpl = config.fetch;
 		else if (typeof globalThis.fetch === "function") this.fetchImpl = globalThis.fetch.bind(globalThis);
 		else throw new LoopwiseError("CONFIG", "globalThis.fetch is not available in this runtime. Pass a fetch implementation via createAdminClient({ fetch })");
@@ -139,12 +139,12 @@ var LoopwiseAdminClient = class {
 		return body.data ?? null;
 	}
 };
-function resolveEndpoint(baseUrl) {
-	return `${(baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "")}/admin/graphql`;
+function resolveEndpoint(baseURL) {
+	return `${(baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}/admin/graphql`;
 }
 //#endregion
 //#region src/resources/courses.ts
-const LIST_QUERY = `
+const LIST_QUERY$1 = `
   query AdminCoursesList($perPage: Int, $page: Int) {
     courses(perPage: $perPage, page: $page) {
       nodes {
@@ -177,18 +177,60 @@ var CoursesResource = class {
 	*/
 	async list(args = {}) {
 		return (await this.client.graphql({
-			query: LIST_QUERY,
+			query: LIST_QUERY$1,
 			variables: args,
 			operationName: "AdminCoursesList"
 		})).courses;
 	}
 };
 //#endregion
+//#region src/resources/members.ts
+const LIST_QUERY = `
+  query AdminMembersList($perPage: Int, $page: Int, $role: AdminUserRole) {
+    users(perPage: $perPage, page: $page, role: $role) {
+      nodes {
+        id
+        name
+        email
+        phoneNumber
+        createdAt
+        lastSignInAt
+      }
+      nodesCount
+      currentPage
+      totalPages
+      hasNextPage
+      hasPreviousPage
+    }
+  }
+`;
+var MembersResource = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/**
+	* List non-admin school users (students by default; TAs when
+	* `role: 'teaching_assistant'`). Returns the full `AdminUserPage`
+	* shape (nodes + pagination meta) under our `AdminMemberPage` alias.
+	*
+	* Requires OAuth scope `members:read` on the access token.
+	*/
+	async list(args = {}) {
+		return (await this.client.graphql({
+			query: LIST_QUERY,
+			variables: args,
+			operationName: "AdminMembersList"
+		})).users;
+	}
+};
+//#endregion
 //#region src/index.ts
 function createAdminClient(config) {
 	const client = new LoopwiseAdminClient(config);
 	return {
 		courses: new CoursesResource(client),
+		members: new MembersResource(client),
 		graphql: (request) => client.graphql(request),
 		setAccessToken: (token) => client.setAccessToken(token)
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopwise/admin-sdk",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "description": "Loopwise admin GraphQL SDK — typed access to /admin/graphql for tenant-built applications",
   "repository": {
     "type": "git",