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

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @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),

package/README.md

@@ -101,21 +101,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/package.json

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