@loopwise/admin-sdk 0.1.0-beta.2 → 0.1.0-beta.4

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # @loopwise/admin-sdk
 
+## 0.1.0-beta.4
+
+Docs-only release — surface the OIDC extension claims shipped in
+[TEACH-18913](https://linear.app/kaik/issue/TEACH-18913) on the
+npm-rendered README so integrators see the canonical `mapProfileToUser`
+pattern without leaving the package page. No code change.
+
+### Docs
+
+- **README `mapProfileToUser` example** — replaces the
+  `// pending TEACH-18913` placeholder with the shipped pattern that
+  reads `profile.org_id` (school identifier) + `profile.roles[0]` (the
+  highest-privilege Loopwise role) through a `ROLE_MAP` lookup, with
+  strict-TS-safe optional handling for the no-school-context case.
+- **Edge cases documented inline** — both `org_id` and `roles` are
+  omitted from the userinfo response when the token has no school
+  context; `roles` can additionally be `[]` for a school-bound token
+  whose user has no roles on that school.
+- **Cross-links to docs.loopwise.com** — points at the new
+  [AI Agent Integration guide](https://docs.loopwise.com/guides/agent-integration)
+  for the full cookbook (multi-school fallback via `account:read`,
+  role-change refresh, common mistakes).
+
+See [TEACH-18914](https://linear.app/kaik/issue/TEACH-18914) for the
+docs PR this release surfaces.
+
+## 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:

package/README.md

@@ -55,4 +55,117 @@ 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. The `profile` is whatever
+`/api/oauth/userinfo` returns — standard OIDC claims (`sub`, `name`,
+`email`, `email_verified`) plus two Loopwise extension claims:
+
+- `org_id` — the school the access token is bound to. Both `org_id`
+  and `roles` are **omitted from the response entirely** when the
+  token has no school context (e.g. a platform-managed personal-
+  access flow that hasn't picked a school yet).
+- `roles` — the user's roles on that school, ordered by privilege; may
+  be an empty array when the token *is* school-bound but the user has
+  no roles on that school. When non-empty, `roles[0]` is the
+  highest-privilege role and is the recommended source for
+  onboarding-time role mapping.
+
+```ts
+const ROLE_MAP: Record<string, string> = {
+  owner:              'admin',
+  manager:            'admin',
+  admin:              'admin',
+  teacher:            'instructor',
+  teaching_assistant: 'instructor',
+  student:            'member',
+};
+
+loopwise({
+  clientId, clientSecret,
+  mapProfileToUser: (profile) => {
+    const primary = (profile.roles as string[] | undefined)?.[0];
+    return {
+      teachifyUserId: profile.sub as string,
+      schoolId:       profile.org_id as string | undefined,
+      role: primary ? (ROLE_MAP[primary] ?? 'member') : 'member',
+    };
+  },
+})
+```
+
+For the full claim schema, role ordering contract, and edge cases
+(multi-school users, platform-managed tokens, role-change refresh),
+see the [AI Agent Integration guide](https://docs.loopwise.com/guides/agent-integration).
+
+## 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;

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,8 +139,8 @@ 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

package/package.json

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