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

package/CHANGELOG.md

@@ -1,6 +1,82 @@
-# @loopwise/admin-sdk
-
-## 0.1.0-beta.3
+# Changelog
+
+All notable changes to `@loopwise/admin-sdk` are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: [SemVer](https://semver.org/) with pre-1.0 semantics — minor bumps
+(`0.x → 0.x+1`) may include breaking changes; beta tags (`0.1.0-beta.N`)
+follow the same rules as a single 0.x line.
+
+## [Unreleased]
+
+## [0.1.0-beta.5] — 2026-10-28
+
+Moves the `/better-auth` integration to better-auth 1.7, which registers
+`genericOAuth` providers as core social providers
+([better-auth#9069](https://github.com/better-auth/better-auth/pull/9069)).
+better-auth 1.6 has no fix for
+[GHSA-965c-763c-88jm](https://github.com/better-auth/better-auth/security/advisories/GHSA-965c-763c-88jm)
+(fixed in 1.7.7), so 1.6 support is dropped. See
+[TEACH-25069](https://linear.app/kaik/issue/TEACH-25069).
+
+### Added
+
+- **`LoopwiseError#retryAfter`** — on a `RATE_LIMIT` error, the seconds from
+  the upstream `Retry-After` header (undefined when the header is absent or
+  not an integer). The Admin API now sends it both for request-count limits
+  and for the concurrency / execution-time limits introduced in
+  [TEACH-22231](https://linear.app/kaik/issue/TEACH-22231).
+
+### Changed
+
+- **Breaking:** the optional `better-auth` peer dependency is now
+  `>=1.7.7` (was `>=1.6.11`). Upgrade `better-auth` to 1.7.7 or later.
+- **Breaking:** `getLoopwiseRedirectURI()` returns
+  `<baseURL>/api/auth/callback/<providerId>` (was
+  `<baseURL>/api/auth/oauth2/callback/<providerId>`), the only callback
+  route better-auth 1.7 serves. Add the new URI to your OAuth client's
+  Redirect URIs at `/oauth/applications` before deploying, and remove the
+  old one once the upgrade is live.
+- **Breaking (client):** start sign-in with
+  `authClient.signIn.social({ provider: 'loopwise' })`; better-auth 1.7
+  removed `signIn.oauth2`. On the server, `auth.api.getAccessToken()` now
+  selects the account by `accountId` rather than `providerId` — the README
+  shows the `listUserAccounts()` lookup.
+
+### Fixed
+
+- **Accounts are keyed by the OIDC `sub` claim** whatever the discovery
+  document advertises. Without this, better-auth 1.7 reads the profile's
+  `id` field when discovery lists no id_token signing algorithm; Loopwise
+  userinfo has no `id`, so sign-in fails.
+
+## [0.1.0-beta.4] — 2026-06-01
+
+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.
+
+### Documentation
+
+- **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] — 2026-05-22
 
 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
@@ -8,17 +84,7 @@ agent-driven, shipped against `0.1.0-beta.0`). See
 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
+### Added
 
 - **`mapProfileToUser` pass-through on `loopwise({})`** — populate
   custom `User` columns at sign-up (e.g. `teachifyUserId: profile.sub`)
@@ -29,8 +95,15 @@ for this PR.
   URI to whitelist on your OAuth client — the better-auth callback
   path includes a `/oauth2/` segment that's easy to miss otherwise.
 
-### Behavior changes
+### Changed
 
+- **Breaking:** `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.
 - **`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
@@ -39,34 +112,36 @@ for this PR.
   `scopes` explicitly AND enable matching scopes on their OAuth client
   in the Loopwise admin UI.
 
-### Docs
+### Documentation
 
 - README adds Redirect URI, Scopes, Profile-mapping, and Roadmap
   sections informed by the same feedback report.
 
-## 0.1.0-beta.2
+## [0.1.0-beta.2] — 2026-05-21
 
-Add second typed resource:
+### Added
 
 - `admin.members.list({ perPage, page, role })` returns `AdminMemberPage`
-  (mirrors `courses.list` shape).
+  (mirrors `courses.list` shape) — second typed resource.
 - `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
+## [0.1.0-beta.1] — 2026-05-21
 
 No functional changes. Validates the tag-triggered OIDC publish path
 now that the npm Trusted Publisher entry is configured (the first
 publish — `0.1.0-beta.0` — had to be done manually because npm OIDC
 can't create new package names).
 
-## 0.1.0-beta.0
+## [0.1.0-beta.0] — 2026-05-21
 
 First public pre-release.
 
+### Added
+
 - `createAdminClient({ accessToken, refreshAccessToken?, baseUrl? })` returns a
   `LoopwiseAdmin` interface with `.graphql<TData, TVars>()` typed pass-through
   against `/admin/graphql`.
@@ -81,3 +156,11 @@ First public pre-release.
   Server Metadata discovery URL (`/.well-known/oauth-authorization-server`),
   audience-aware providerId (`loopwise` / `loopwise-member`) and scope
   defaults.
+
+[Unreleased]: https://github.com/kaikhq/manekineko/compare/@loopwise/admin-sdk@0.1.0-beta.5...HEAD
+[0.1.0-beta.5]: https://github.com/kaikhq/manekineko/compare/@loopwise/admin-sdk@0.1.0-beta.4...@loopwise/admin-sdk@0.1.0-beta.5
+[0.1.0-beta.4]: https://github.com/kaikhq/manekineko/compare/@loopwise/admin-sdk@0.1.0-beta.3...@loopwise/admin-sdk@0.1.0-beta.4
+[0.1.0-beta.3]: https://github.com/kaikhq/manekineko/compare/@loopwise/admin-sdk@0.1.0-beta.2...@loopwise/admin-sdk@0.1.0-beta.3
+[0.1.0-beta.2]: https://github.com/kaikhq/manekineko/compare/@loopwise/admin-sdk@0.1.0-beta.1...@loopwise/admin-sdk@0.1.0-beta.2
+[0.1.0-beta.1]: https://github.com/kaikhq/manekineko/compare/@loopwise/admin-sdk@0.1.0-beta.0...@loopwise/admin-sdk@0.1.0-beta.1
+[0.1.0-beta.0]: https://github.com/kaikhq/manekineko/releases/tag/@loopwise/admin-sdk@0.1.0-beta.0

package/README.md

@@ -20,6 +20,8 @@ const { courses } = await admin.graphql<{ courses: { nodes: { id: string; name:
 
 ## With better-auth (Next.js)
 
+Requires `better-auth` 1.7.7 or later.
+
 ```ts
 // auth.ts
 import { betterAuth } from 'better-auth';
@@ -43,9 +45,14 @@ import { createAdminClient } from '@loopwise/admin-sdk';
 import { auth } from '@/lib/auth';
 
 export default async function Page() {
+  const requestHeaders = await headers();
+  const accounts = await auth.api.listUserAccounts({ headers: requestHeaders });
+  const loopwiseAccount = accounts.find((a) => a.providerId === 'loopwise');
+  if (!loopwiseAccount) throw new Error('Not signed in with Loopwise');
+
   const { accessToken } = await auth.api.getAccessToken({
-    body: { providerId: 'loopwise' },
-    headers: headers(),
+    body: { accountId: loopwiseAccount.id },
+    headers: requestHeaders,
   });
   const admin = createAdminClient({ accessToken });
   const { courses } = await admin.graphql<{ courses: { nodes: { id: string; name: string }[] } }>({
@@ -57,10 +64,8 @@ export default async function Page() {
 
 ### 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/...`).
+Better Auth's catch-all handler is mounted at `/api/auth/[...all]`, and
+the Loopwise provider's callback is `/api/auth/callback/<providerId>`.
 
 Use the exported helper to compute the exact URI to whitelist on your
 OAuth client:
@@ -71,12 +76,27 @@ 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
+// dev:  http://localhost:3000/api/auth/callback/loopwise
+// prod: https://your.app/api/auth/callback/loopwise
 ```
 
 For multi-audience apps, pass `audience: 'member'` to get
-`/oauth2/callback/loopwise-member`.
+`/api/auth/callback/loopwise-member`.
+
+### Signing in from the client
+
+The Loopwise provider is a regular better-auth social provider, so the
+client starts the flow with `signIn.social`:
+
+```ts
+import { createAuthClient } from 'better-auth/react';
+
+const authClient = createAuthClient();
+
+await authClient.signIn.social({ provider: 'loopwise', callbackURL: '/courses' });
+```
+
+Use `provider: 'loopwise-member'` for the member audience.
 
 ### Scopes
 
@@ -101,21 +121,46 @@ Mismatch between requested and enabled scopes surfaces as
 ### Mapping OAuth claims to your user table
 
 Use `mapProfileToUser` to populate custom columns (declared via
-better-auth's `additionalFields`) at sign-up:
+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) => ({
-    teachifyUserId: profile.sub,
-    // role: profile['loopwise:org_role'],  // pending TEACH-18913
-  }),
+  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',
+    };
+  },
 })
 ```
 
-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.
+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
 

package/dist/better-auth.d.mts

@@ -1,7 +1,6 @@
 import { BetterAuthPlugin } from "better-auth/types";
-
 //#region src/better-auth.d.ts
-type LoopwiseAuthAudience = 'org_admin' | 'member';
+type LoopwiseAuthAudience = "org_admin" | "member";
 interface LoopwiseAuthOptions {
   /** OAuth client ID issued at `/oauth/applications` in the school admin UI. */
   clientId: string;
@@ -81,21 +80,20 @@ interface GetRedirectURIOptions {
 }
 /**
  * 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/...`).
+ * OAuth client: better-auth's callback route,
+ * `/api/auth/callback/<providerId>`, under your app's `baseURL`.
  *
  * @example
  *   // dev
  *   getLoopwiseRedirectURI({ baseURL: 'http://localhost:3000' });
- *   // → 'http://localhost:3000/api/auth/oauth2/callback/loopwise'
+ *   // → 'http://localhost:3000/api/auth/callback/loopwise'
  *
  *   // prod, member audience
  *   getLoopwiseRedirectURI({
  *     baseURL: 'https://app.example.com',
  *     audience: 'member',
  *   });
- *   // → 'https://app.example.com/api/auth/oauth2/callback/loopwise-member'
+ *   // → 'https://app.example.com/api/auth/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.

package/dist/better-auth.mjs

@@ -1,7 +1,7 @@
 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 BETTER_AUTH_CALLBACK_PATH = "/api/auth/callback";
 const AUDIENCE_PROFILES = {
 	org_admin: {
 		providerId: "loopwise",
@@ -22,28 +22,27 @@ const AUDIENCE_PROFILES = {
 };
 /**
 * 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/...`).
+* OAuth client: better-auth's callback route,
+* `/api/auth/callback/<providerId>`, under your app's `baseURL`.
 *
 * @example
 *   // dev
 *   getLoopwiseRedirectURI({ baseURL: 'http://localhost:3000' });
-*   // → 'http://localhost:3000/api/auth/oauth2/callback/loopwise'
+*   // → 'http://localhost:3000/api/auth/callback/loopwise'
 *
 *   // prod, member audience
 *   getLoopwiseRedirectURI({
 *     baseURL: 'https://app.example.com',
 *     audience: 'member',
 *   });
-*   // → 'https://app.example.com/api/auth/oauth2/callback/loopwise-member'
+*   // → 'https://app.example.com/api/auth/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.
 */
 function getLoopwiseRedirectURI(options) {
 	const profile = AUDIENCE_PROFILES[options.audience ?? "org_admin"];
-	return `${options.baseURL.replace(/\/$/, "")}${BETTER_AUTH_OAUTH2_CALLBACK_PATH}/${profile.providerId}`;
+	return `${options.baseURL.replace(/\/$/, "")}${BETTER_AUTH_CALLBACK_PATH}/${profile.providerId}`;
 }
 function loopwise(options) {
 	const profile = AUDIENCE_PROFILES[options.audience ?? "org_admin"];
@@ -56,6 +55,7 @@ function loopwise(options) {
 		pkce: true,
 		accessType: "offline",
 		scopes: options.scopes ?? [...profile.defaultScopes],
+		accountSubject: ({ profile: userInfo }) => userInfo.sub ?? "",
 		mapProfileToUser: options.mapProfileToUser
 	}] });
 }

package/dist/index.d.mts

@@ -22,8 +22,11 @@ interface LoopwiseAdminConfig {
    *
    * Typical wiring (with better-auth):
    *   refreshAccessToken: async () => {
+   *     const accounts = await auth.api.listUserAccounts({ headers: req.headers });
+   *     const account = accounts.find((a) => a.providerId === 'loopwise');
+   *     if (!account) throw new Error('Not signed in with Loopwise');
    *     const { accessToken } = await auth.api.getAccessToken({
-   *       body: { providerId: 'loopwise' }, headers: req.headers,
+   *       body: { accountId: account.id }, headers: req.headers,
    *     });
    *     return accessToken;
    *   }
@@ -79,7 +82,7 @@ declare class LoopwiseAdminClient {
 }
 //#endregion
 //#region src/error.d.ts
-type LoopwiseErrorCode = 'NETWORK' | 'AUTH' | 'GRAPHQL' | 'RATE_LIMIT' | 'CONFIG';
+type LoopwiseErrorCode = "NETWORK" | "AUTH" | "GRAPHQL" | "RATE_LIMIT" | "CONFIG";
 interface GraphQLError {
   message: string;
   path?: (string | number)[];
@@ -91,11 +94,14 @@ declare class LoopwiseError extends Error {
   readonly status?: number;
   readonly graphqlErrors?: GraphQLError[];
   readonly requestId?: string;
+  /** Seconds to wait before retrying, from the upstream `Retry-After`; only on `RATE_LIMIT`. */
+  readonly retryAfter?: number;
   constructor(code: LoopwiseErrorCode, message: string, detail?: {
     endpoint?: string;
     status?: number;
     graphqlErrors?: GraphQLError[];
     requestId?: string;
+    retryAfter?: number;
   });
 }
 //#endregion
@@ -165,7 +171,7 @@ interface AdminMemberPage {
   hasNextPage: boolean;
   hasPreviousPage: boolean;
 }
-type AdminMemberRole = 'student' | 'teaching_assistant';
+type AdminMemberRole = "student" | "teaching_assistant";
 interface MembersListArgs {
   /** Items per page. Schema default 20, max 50. */
   perPage?: number;

package/dist/index.mjs

@@ -5,6 +5,8 @@ var LoopwiseError = class extends Error {
 	status;
 	graphqlErrors;
 	requestId;
+	/** Seconds to wait before retrying, from the upstream `Retry-After`; only on `RATE_LIMIT`. */
+	retryAfter;
 	constructor(code, message, detail = {}) {
 		super(message);
 		this.name = "LoopwiseError";
@@ -13,6 +15,7 @@ var LoopwiseError = class extends Error {
 		this.status = detail.status;
 		this.graphqlErrors = detail.graphqlErrors;
 		this.requestId = detail.requestId;
+		this.retryAfter = detail.retryAfter;
 	}
 };
 //#endregion
@@ -110,11 +113,16 @@ var LoopwiseAdminClient = class {
 			status: 401,
 			requestId
 		});
-		if (response.status === 429) throw new LoopwiseError("RATE_LIMIT", "Rate limit exceeded", {
-			endpoint: this.endpoint,
-			status: 429,
-			requestId
-		});
+		if (response.status === 429) {
+			const retryAfterHeader = response.headers.get("retry-after");
+			const retryAfter = retryAfterHeader !== null && /^\d+$/.test(retryAfterHeader) ? Number(retryAfterHeader) : void 0;
+			throw new LoopwiseError("RATE_LIMIT", retryAfter === void 0 ? "Rate limit exceeded" : `Rate limit exceeded; retry after ${retryAfter}s`, {
+				endpoint: this.endpoint,
+				status: 429,
+				requestId,
+				retryAfter
+			});
+		}
 		if (!response.ok) throw new LoopwiseError("NETWORK", `Upstream returned HTTP ${response.status}`, {
 			endpoint: this.endpoint,
 			status: response.status,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopwise/admin-sdk",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "description": "Loopwise admin GraphQL SDK — typed access to /admin/graphql for tenant-built applications",
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "better-auth": ">=1.6.11"
+    "better-auth": ">=1.7.7"
   },
   "peerDependenciesMeta": {
     "better-auth": {
@@ -55,11 +55,11 @@
     }
   },
   "devDependencies": {
-    "better-auth": "1.6.11",
+    "better-auth": "1.7.14",
     "tsconfig": "workspace:*",
-    "tsdown": "0.22.0",
-    "typescript": "5.9.3",
-    "vitest": "4.1.0"
+    "tsdown": "catalog:",
+    "typescript": "catalog:typescript7",
+    "vitest": "catalog:"
   },
   "publishConfig": {
     "access": "public"