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

package/CHANGELOG.md

@@ -9,6 +9,77 @@ follow the same rules as a single 0.x line.
 
 ## [Unreleased]
 
+## [0.1.0-beta.5] — 2026-10-15
+
+Member actions on a Loopwise Page. A customer wanted signed-in members to
+rate a course from their own page UI; that worked only through hand-written
+GraphQL with several silent traps (a cached call reads everyone as signed
+out, an omitted comment wipes the stored text). This release wraps it:
+`auth`, `courses.reviewState` and `reviews` (TEACH-24177, #17705, #17711).
+The server now also refuses ratings on courses with ratings off
+(TEACH-24153) and scores outside 0.5–5 in half steps (TEACH-24176, #17704).
+
+### Added
+
+- `loopwise.auth.getMe()` / `isAuthenticated()` — the member signed in to
+  the site, read from the page's own sign-in cookie. (TEACH-24177,
+  covers the core of TEACH-18410)
+- `loopwise.courses.reviewState({ slug })` — one request returning the
+  member's review status for a course (`ratings_off`, `signed_out`,
+  `not_purchased`, `can_review`, `reviewed`), their review, the rating
+  summary and a `loginUrl` back to the page. (TEACH-24177)
+- `loopwise.reviews.submit({ courseId, score, comment })` and
+  `loopwise.reviews.delete({ courseId, reviewId })`. `submit` checks the
+  score (0.5–5 in steps of 0.5) before sending. `comment` is required
+  and replaces the stored text (`""` clears it); leaving it out rejects
+  with `CONFIG` instead of clearing the text by accident.
+  (TEACH-24177)
+- `LoopwiseError` codes `AUTH_REQUIRED`, `NOT_SIGNED_IN`,
+  `NOT_PURCHASED`, `RATINGS_OFF`, `INVALID_SCORE`. Member methods reject
+  with `AUTH_REQUIRED` server-side and off-origin (a `*.loopwise.page`
+  preview) instead of answering as a signed-out visitor, and never use
+  the cached `GET` path. `GraphQLError` gains the server's `code`; it and
+  `LoopwiseErrorCode` are now exported types. (TEACH-24177)
+- New exported types: `Member`, `MemberReview`, `CourseRating`,
+  `CourseReviewState`, `CourseReviewStatus`. (TEACH-24177)
+
+### Security
+
+- Storefront `Meeting.roomUrl` is empty unless the viewer is an attendee,
+  school staff, or a school-bound admin credential. (TEACH-22983)
+
+## [0.1.0-beta.4] — 2026-09-10
+
+Storefront schema pinning for browser clients. A design partner could
+not tell a honoured `API-Version` pin from an ignored header because the
+same-origin `/api/graphql` proxy dropped it (TEACH-22755, #16417); the
+proxy now forwards it, answers the CORS preflight for off-origin callers
+(TEACH-22760, #16429), and this release gives the SDK a first-class way
+to send the pin.
+
+### Added
+
+- `LoopwiseConfig.apiVersion` — pins the storefront schema to a release
+  date. Sent as the `API-Version` header on every request (GET and POST);
+  the server echoes the resolved version in the `API-Version` response
+  header. A blank value throws `LoopwiseError` code `'CONFIG'` at
+  `createClient()`, because the server would treat it as absent and serve
+  the baseline silently. (TEACH-22755)
+
+### Changed
+
+- **Breaking:** a non-2xx response whose body is a GraphQL errors payload
+  (objects with a `message`) now raises `LoopwiseError` with code
+  `'GRAPHQL'` and the errors on `graphqlErrors`, instead of `'NETWORK'` /
+  `Upstream <status>`. The first such response is the 400
+  `INVALID_API_VERSION` for a malformed `apiVersion`. Migration: code that
+  retries or branches on `code === 'NETWORK'` for a 4xx/5xx carrying a
+  GraphQL body should also handle `'GRAPHQL'` (check
+  `graphqlErrors[0].extensions.code` for the server's reason). Status
+  precedence is unchanged: 401/403 stay `'AUTH'` and 429 stays
+  `'RATE_LIMIT'` whatever their body, and other non-2xx responses without a
+  GraphQL body stay `'NETWORK'`.
+
 ## [0.1.0-beta.3] — 2026-05-20
 
 ### Added
@@ -62,8 +133,15 @@ follow the same rules as a single 0.x line.
   (not line total), and null-guards the `tradeNo` URL-param lookup
   example.
 
-## [0.1.0-beta.1]
+## [0.1.0-beta.1] — 2026-05-05
 
 Initial public beta. `courses.list/get`, `posts.list/get`, `orders.get`,
 `batch()`, raw `query()`. Schema-lock pipeline. Same-origin BFF and
 explicit cross-origin endpoint resolution.
+
+[Unreleased]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.5...HEAD
+[0.1.0-beta.5]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.4...@loopwise/sdk@0.1.0-beta.5
+[0.1.0-beta.4]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.3...@loopwise/sdk@0.1.0-beta.4
+[0.1.0-beta.3]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.2...@loopwise/sdk@0.1.0-beta.3
+[0.1.0-beta.2]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.1...@loopwise/sdk@0.1.0-beta.2
+[0.1.0-beta.1]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.0...@loopwise/sdk@0.1.0-beta.1

package/README.md

@@ -6,7 +6,7 @@ Storefront GraphQL client for Loopwise / Teachify. Pick your path:
 |---|---|---|
 | A single self-contained HTML file (no build step — for `deploy_static_page`, a Claude Design artifact, or a CodePen) | none — load from a CDN | `https://esm.sh/@loopwise/sdk@beta` |
 | A project with a bundler (Vite / Astro / Next.js / Remix) | `npm install @loopwise/sdk@beta` | `@loopwise/sdk` |
-| **React** UI in either of the above | (see [`@loopwise/sdk-react`](#react--coming-soon)) | — |
+| **React** UI in either of the above | (see [`@loopwise/react`](#react--coming-soon)) | — |
 
 Same package powers all three; the difference is the loader.
 
@@ -59,10 +59,21 @@ right API origin.
 ### Limits when not on the site itself
 
 Cross-origin requests **do not carry first-party cookies**. So calls
-that require a signed-in visitor — `cart`, `viewer.profile`,
-authenticated mutations — **will not work** from off-site code.
+that require a signed-in visitor — `auth.getMe`, `courses.reviewState`,
+`reviews.*`, hand-written authenticated queries — **will not work** from
+off-site code; the SDK's member methods reject with `AUTH_REQUIRED`.
 Public, anonymous reads (`courses.list`, `posts.list`, etc.) work fine.
 
+The site's `/api/graphql` answers the browser's CORS preflight with a
+static `Access-Control-Allow-Origin: *` and no credentials. The
+`Access-Control-Allow-Headers` grant names the non-safelisted headers
+this SDK sends (`content-type` with a JSON value, `api-version`,
+`x-loopwise-cache`); CORS-safelisted headers such as `Accept` need no
+grant. A hand-rolled `fetch` that adds any other non-safelisted header
+(`Authorization`, for one) fails the preflight, and
+`credentials: 'include'` is refused by the browser. The response exposes
+`API-Version` and `X-Request-Id`.
+
 This is the dominant case for `deploy_static_page` bundles (which
 serve at `<scriptName>.loopwise.page`):
 
@@ -75,6 +86,108 @@ const { items } = await loopwise.courses.list({ limit: 20 }, { cache: 60 });
 For preview UX that needs an authenticated viewer, see
 [Preview modes](#preview-modes) below.
 
+## Member actions on a Loopwise Page
+
+A Loopwise Page served from the site's own domain (`acme.kaik.io/lw/...`,
+`nii.school/reviews`) can act for the member who is signed in to that
+site: read who they are, show their review state for a course, and save
+or delete their review. You write no GraphQL.
+
+```ts
+import { createClient, LoopwiseError } from '@loopwise/sdk';
+
+const loopwise = createClient({});
+
+const me = await loopwise.auth.getMe(); // { id, name } or null
+
+let state = await loopwise.courses.reviewState({ slug: 'finance' });
+// state.status: 'ratings_off' | 'signed_out' | 'not_purchased' | 'can_review' | 'reviewed'
+// state.courseId, state.review ({ id, score, comment } | null),
+// state.rating ({ average, total } | null), state.loginUrl
+
+// Re-read after every write so the page (and the next click) never acts
+// on a stale review.
+const refresh = async () => {
+  state = await loopwise.courses.reviewState({ slug: 'finance' });
+  render(state);
+};
+
+const onError = (e) => {
+  if (e instanceof LoopwiseError && e.code === 'NOT_SIGNED_IN') {
+    location.href = state.loginUrl;
+  } else {
+    showError(e); // INVALID_SCORE, RATINGS_OFF, NOT_PURCHASED, …
+  }
+};
+
+form.addEventListener('submit', async (event) => {
+  event.preventDefault();
+  submitButton.disabled = true; // one email per click, not per double-click
+  try {
+    await loopwise.reviews.submit({
+      courseId: state.courseId,
+      score: Number(form.score.value), // 0.5, 1, 1.5 … 5
+      comment: form.comment.value,     // required; '' clears it
+    });
+    await refresh();
+  } catch (e) {
+    onError(e);
+  } finally {
+    submitButton.disabled = false;
+  }
+});
+
+deleteButton.addEventListener('click', async () => {
+  if (!state.review) return;
+  deleteButton.disabled = true;
+  try {
+    await loopwise.reviews.delete({ courseId: state.courseId, reviewId: state.review.id });
+    await refresh();
+  } catch (e) {
+    onError(e);
+  } finally {
+    deleteButton.disabled = false;
+  }
+});
+```
+
+The rules these methods enforce, and why:
+
+- **Same origin only.** The member is known from the site's sign-in
+  cookie, which the browser sends only to the page's own origin. Server
+  code, SSR, and a `*.loopwise.page` preview have no member. There every
+  member method rejects with `LoopwiseError` code `'AUTH_REQUIRED'` and
+  sends nothing, instead of reporting everyone as signed out.
+- **Fetch member state in the browser, after load.** Loopwise Page HTML is
+  cached at the CDN and shared by every visitor, so never render member
+  state into the HTML. Render a neutral shell and fill it in from
+  `reviewState()` on the client.
+- **No `cache` on member calls.** A cached call is a cookie-less `GET`,
+  which would read every member as signed out. Member methods take no
+  options and always `POST`.
+- **Submit on an explicit action.** Each `reviews.submit` emails the site
+  owner. Call it from a Submit button, never from autosave or on every
+  star change.
+- **One review per member per course.** `submit` creates it the first time
+  and replaces it after that; `comment` replaces the stored text too, so
+  pass the existing text to keep it.
+
+`reviewState` checks in this order: `ratings_off` (reviews are off for the
+course; hide the UI), `signed_out` (link to `loginUrl`, which returns to
+this page after sign-in), `reviewed` (the member's review is in
+`review`), `not_purchased` (signed in but not enrolled), `can_review`.
+
+| `LoopwiseError.code` | When |
+|---|---|
+| `AUTH_REQUIRED` | Called server-side or off-origin. Nothing was sent. |
+| `INVALID_SCORE` | `score` is not 0.5–5 in steps of 0.5. Checked before sending. |
+| `NOT_SIGNED_IN` | No member is signed in. Send them to `loginUrl`. |
+| `NOT_PURCHASED` | The member is not enrolled in the course. |
+| `RATINGS_OFF` | The site turned reviews off for the course. |
+| `CONFIG` | A required argument (`slug`, `courseId`, `reviewId`, `comment`) is missing. Nothing was sent. |
+| `AUTH`, `RATE_LIMIT`, `NETWORK` | Transport failures (HTTP 401/403, 429, other), the same as for every call. They are never reported as a signed-out member. |
+| `GRAPHQL` | Anything else, such as an unknown slug or another member's review; the server's errors are on `graphqlErrors`. |
+
 ## `cache` option
 
 Read-only resource calls accept an opt-in `cache` option that flips the
@@ -123,6 +236,37 @@ is the explicit, type-system-visible declaration of "this must never be cached".
 per Vercel POP, depending on traffic. Use shorter TTLs for time-sensitive
 content; use `cache: 'no-store'` for admin previews.
 
+## `apiVersion` option
+
+The storefront schema is versioned by release date. Pin the one your code
+was built against and the SDK sends it as the `API-Version` header on
+every request, GET and POST alike:
+
+```ts
+const loopwise = createClient({ apiVersion: '2027-01-01' });
+```
+
+Omit it to get the baseline schema. The server echoes the version it
+resolved in the `API-Version` response header (and lists the header in
+`Vary`), and this holds through the same-origin `/api/graphql` proxy too.
+The SDK's methods return parsed data only and do not surface response
+headers, so confirm the pin once with the browser's network inspector or
+a direct `fetch` to the same endpoint, not through an SDK return value:
+
+```ts
+const res = await fetch('/api/graphql', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json', 'API-Version': '2027-01-01' },
+  body: JSON.stringify({ query: '{ __typename }' }),
+});
+res.headers.get('API-Version'); // '2027-01-01' when the pin is honoured
+```
+
+A value that is not a date is rejected with a 400 whose body is a GraphQL
+errors payload; the SDK raises it as a `LoopwiseError` with code
+`'GRAPHQL'` and `graphqlErrors[0].extensions.code === 'INVALID_API_VERSION'`,
+so a malformed pin does fail loudly through the SDK.
+
 ## Preview modes
 
 Two preview surfaces exist, each with different capability:
@@ -145,7 +289,7 @@ resolve under `/_preview/<scriptName>/`; root-absolute paths like
 
 ## React — coming soon
 
-A `@loopwise/sdk-react` companion package is planned, providing:
+A `@loopwise/react` companion package is planned, providing:
 
 - `<LoopwiseProvider client={loopwise}>` context provider
 - `useCourses({ limit })`, `useCourse({ slug })` hooks with Suspense support
@@ -163,6 +307,9 @@ your own state (`useEffect` + `useState`, TanStack Query, etc.).
 - `loopwise.courses.list(args, options?)` / `.get(args, options?)`.
 - `loopwise.posts.list(args, options?)` / `.get(args, options?)`.
 - `loopwise.orders.get(args, options?)` — post-checkout pixel-tracking pattern; see the method's JSDoc for the `?tradeNo=…` → `fbq('track', 'Purchase', …)` recipe.
+- `loopwise.auth.getMe()` / `.isAuthenticated()` — the signed-in member; see [Member actions on a Loopwise Page](#member-actions-on-a-loopwise-page).
+- `loopwise.courses.reviewState({ slug })` — the member's review status for a course.
+- `loopwise.reviews.submit({ courseId, score, comment })` / `.delete({ courseId, reviewId })`.
 - `loopwise.batch(builders, options?)` — composes N queries into one HTTP request.
 - `loopwise.query<T>(document, variables?, operationName?, options?)` — raw GraphQL escape hatch.
 

package/dist/config.d.mts

@@ -32,6 +32,17 @@ interface LoopwiseConfig {
    * is omitted).
    */
   endpoint?: string;
+  /**
+   * Pin the storefront schema to a release date (`'2027-01-01'`). Sent as
+   * the `API-Version` header on every request; omit it to get the baseline
+   * schema. The server echoes the resolved version in the `API-Version`
+   * response header; SDK methods return parsed data only, so read that
+   * header with a network inspector or a direct `fetch`. A value that is
+   * not a date is rejected with a 400 whose GraphQL error carries
+   * `extensions.code: 'INVALID_API_VERSION'` (surfaced as a
+   * `LoopwiseError` with code `'GRAPHQL'`).
+   */
+  apiVersion?: string;
 }
 declare function defineConfig(config: LoopwiseConfig): LoopwiseConfig;
 //#endregion

package/dist/index.d.mts

@@ -1,9 +1,27 @@
 import { LoopwiseConfig } from "./config.mjs";
-
 //#region src/error.d.ts
-type LoopwiseErrorCode = 'NETWORK' | 'AUTH' | 'GRAPHQL' | 'RATE_LIMIT' | 'CONFIG';
+/**
+ * What went wrong, as a stable string to branch on.
+ *
+ * - `NETWORK`, `AUTH`, `RATE_LIMIT`: transport failures.
+ * - `GRAPHQL`: the server answered with an error not mapped below; the raw
+ *   errors are on `LoopwiseError.graphqlErrors`.
+ * - `CONFIG`: the client or a call was set up wrong; nothing was sent.
+ * - `AUTH_REQUIRED`: a member action (`auth.*`, `courses.reviewState`,
+ *   `reviews.*`) ran where no member can be signed in — server-side, or in a
+ *   browser whose page is on another origin than the API (a
+ *   `*.loopwise.page` preview). Nothing was sent.
+ * - `NOT_SIGNED_IN`: a review needs a signed-in member and there is none.
+ * - `NOT_PURCHASED`: the member is signed in but not enrolled in the course.
+ * - `RATINGS_OFF`: the site turned reviews off for the course.
+ * - `INVALID_SCORE`: a review score outside 0.5 to 5 in half-star steps.
+ *   Checked before sending, and mapped from the server's `Rate-001`.
+ */
+type LoopwiseErrorCode = "NETWORK" | "AUTH" | "GRAPHQL" | "RATE_LIMIT" | "CONFIG" | "AUTH_REQUIRED" | "NOT_SIGNED_IN" | "NOT_PURCHASED" | "RATINGS_OFF" | "INVALID_SCORE";
 interface GraphQLError {
   message: string;
+  /** Storefront service error code, such as `User-000` or `Rate-002`. */
+  code?: string;
   path?: (string | number)[];
   extensions?: Record<string, unknown>;
 }
@@ -17,7 +35,8 @@ declare class LoopwiseError extends Error {
   readonly graphqlErrors?: GraphQLError[];
   readonly requestId?: string;
   constructor(code: LoopwiseErrorCode, message: string, detail?: {
-    site?: string; /** @deprecated Renamed to `site`. Removed in 0.2.0. */
+    site?: string;
+    /** @deprecated Renamed to `site`. Removed in 0.2.0. */
     tenant?: string;
     endpoint?: string;
     graphqlErrors?: GraphQLError[];
@@ -26,9 +45,9 @@ declare class LoopwiseError extends Error {
 }
 //#endregion
 //#region src/select.d.ts
-type SelectionInner<T> = T extends Array<infer U> ? SelectionInner<U> : T extends object ? { [K in keyof T]?: SelectionInner<T[K]> } : true;
+type SelectionInner<T> = T extends Array<infer U> ? SelectionInner<U> : T extends object ? { [K in keyof T]?: SelectionInner<T[K]>; } : true;
 type Selection<T> = SelectionInner<NonNullable<T>>;
-type SelectedInner<T, S> = T extends null | undefined ? T : S extends true ? T : T extends Array<infer U> ? Array<SelectedInner<U, S>> : T extends object ? { [K in keyof S & keyof T]: SelectedInner<T[K], S[K]> } : T;
+type SelectedInner<T, S> = T extends null | undefined ? T : S extends true ? T : T extends Array<infer U> ? Array<SelectedInner<U, S>> : T extends object ? { [K in keyof S & keyof T]: SelectedInner<T[K], S[K]>; } : T;
 type Selected<T, S> = SelectedInner<T, S>;
 //#endregion
 //#region src/query.d.ts
@@ -64,7 +83,7 @@ interface FetchOptions {
    * `Cache-Control: public, s-maxage=<seconds>`. `'no-store'` forces POST and
    * skips any cache hint. Omit for the legacy POST behaviour.
    */
-  cache?: number | 'no-store';
+  cache?: number | "no-store";
 }
 interface BatchedFetcher {
   /**
@@ -82,6 +101,15 @@ declare class QueryBuilder<T> implements PromiseLike<T> {
 }
 //#endregion
 //#region src/client.d.ts
+interface GraphQLPayload {
+  query: string;
+  variables?: Record<string, unknown>;
+  operationName?: string;
+}
+interface GraphQLResponse {
+  data?: Record<string, unknown> | null;
+  errors?: GraphQLError[];
+}
 declare class LoopwiseClient implements BatchedFetcher {
   readonly config: LoopwiseConfig;
   private endpoint;
@@ -96,8 +124,17 @@ declare class LoopwiseClient implements BatchedFetcher {
   raw<T = unknown>(document: string, variables?: Record<string, unknown>, operationName?: string, options?: FetchOptions): Promise<T>;
   batch<R extends Record<string, unknown>>(builders: { [K in keyof R]: {
     descriptor: QueryDescriptor;
-  } }, options?: FetchOptions): Promise<R>;
+  }; }, options?: FetchOptions): Promise<R>;
+  /**
+   * POST a document on behalf of the signed-in member and return the whole
+   * GraphQL response, errors included, so the caller can map service error
+   * codes. Refuses wherever the member's `token` cookie cannot ride along.
+   */
+  member(payload: GraphQLPayload): Promise<GraphQLResponse>;
+  graphqlError(errors: GraphQLError[], code?: LoopwiseErrorCode, message?: string): LoopwiseError;
+  private assertMemberOrigin;
   private fetchGraphQL;
+  private request;
   private shouldUseGet;
   private buildGetUrl;
   private resolveApiKey;
@@ -144,7 +181,7 @@ interface Post {
   /** Known values: `login_required`, `paid`, `public_access`. The
    * `string & {}` escape hatch keeps autocomplete on the known set
    * while accepting forward-compat values the schema may add. */
-  accessType: 'login_required' | 'paid' | 'public_access' | (string & {});
+  accessType: "login_required" | "paid" | "public_access" | (string & {});
   tags: string[] | null;
   noindex: boolean;
   author: Lecturer | null;
@@ -160,8 +197,58 @@ interface ListResult<T> {
   items: T[];
   pageInfo: PageInfo;
 }
+/** The member signed in to this site. */
+interface Member {
+  id: string;
+  /** Display name; `null` when the member never set one. */
+  name: string | null;
+}
+/** A member's own review of a course. One per member per course. */
+interface MemberReview {
+  id: string;
+  /** 0.5 to 5 in half-star steps. */
+  score: number;
+  /** Review text; `""` when the member left none. */
+  comment: string;
+}
+/** A course's public rating summary. */
+interface CourseRating {
+  /** Mean score across visible reviews. */
+  average: number;
+  /** Number of visible reviews. */
+  total: number;
+}
+/**
+ * What the visitor can do about reviewing a course, checked in this order:
+ *
+ * - `ratings_off`: the site turned reviews off for this course. Hide the UI.
+ * - `signed_out`: no member is signed in. Link to `loginUrl`.
+ * - `reviewed`: the member already reviewed it; `review` holds their score
+ *   and comment. Submitting again replaces it.
+ * - `not_purchased`: signed in, but not enrolled. Only enrolled members can
+ *   review.
+ * - `can_review`: enrolled and not reviewed yet.
+ */
+type CourseReviewStatus = "ratings_off" | "signed_out" | "not_purchased" | "can_review" | "reviewed";
+interface CourseReviewState {
+  status: CourseReviewStatus;
+  /**
+   * Pass to `reviews.submit({ courseId })`, and with `review.id` (when
+   * `review` is not `null`) to `reviews.delete({ courseId, reviewId })`.
+   */
+  courseId: string;
+  /** The signed-in member's own review, or `null` when they have none. */
+  review: MemberReview | null;
+  /** The course's rating summary; `null` when ratings are off. */
+  rating: CourseRating | null;
+  /**
+   * The site's default sign-in page, returning to the current page after
+   * sign-in: `/login?redirect=<path>`.
+   */
+  loginUrl: string;
+}
 /** Simplified order status. Mirrors the storefront `Order.status` enum. */
-type OrderStatus = 'PAID' | 'PENDING' | 'FAILED' | 'REFUNDED';
+type OrderStatus = "PAID" | "PENDING" | "FAILED" | "REFUNDED";
 interface OrderItem {
   /**
    * Meta-pixel-aligned identifier (Lineitem#tracking_id server-side).
@@ -185,6 +272,27 @@ interface Order {
   createdAt: number;
 }
 //#endregion
+//#region src/resources/auth.d.ts
+/**
+ * The member signed in to this site, read from the page's own sign-in
+ * cookie. Works only in the browser on the site's own domain; elsewhere
+ * every method rejects with `LoopwiseError` code `'AUTH_REQUIRED'` instead
+ * of reporting a signed-out visitor.
+ */
+declare class AuthResource {
+  private client;
+  constructor(client: LoopwiseClient);
+  /**
+   * The signed-in member, or `null` for a signed-out visitor.
+   * @example
+   * const me = await loopwise.auth.getMe()
+   * greeting.textContent = me ? `Hi ${me.name ?? ''}` : 'Sign in'
+   */
+  getMe(): Promise<Member | null>;
+  /** Whether a member is signed in to this site. */
+  isAuthenticated(): Promise<boolean>;
+}
+//#endregion
 //#region src/resources/courses.d.ts
 declare const DEFAULT_LIST_FIELDS$1: Selection<Course>;
 declare const DEFAULT_GET_FIELDS$2: Selection<Course>;
@@ -230,6 +338,30 @@ declare class CoursesResource {
    * }
    */
   get<S extends Selection<Course> = typeof DEFAULT_GET_FIELDS$2>(args: CourseGetArgs<S>, options?: FetchOptions): QueryBuilder<Selected<Course, S>>;
+  /**
+   * What the signed-in member can do about reviewing a course, in one
+   * request: whether reviews are on, whether they are signed in and
+   * enrolled, their own review, and the course's rating summary.
+   *
+   * Member state: call it in the browser on the site's own domain, after
+   * the page loads. It never uses the `cache` option, and it rejects with
+   * `LoopwiseError` code `AUTH_REQUIRED` server-side or off-origin rather
+   * than report every visitor as signed out. An unknown slug rejects with
+   * `GRAPHQL`.
+   *
+   * @example
+   * const state = await loopwise.courses.reviewState({ slug: 'finance' })
+   * switch (state.status) {
+   *   case 'ratings_off':   return hide()
+   *   case 'signed_out':    return showLink(state.loginUrl)
+   *   case 'not_purchased': return showText('Enroll to review this course')
+   *   case 'can_review':    return showForm()
+   *   case 'reviewed':      return showForm(state.review)
+   * }
+   */
+  reviewState(args: {
+    slug: string;
+  }): Promise<CourseReviewState>;
 }
 //#endregion
 //#region src/resources/orders.d.ts
@@ -318,11 +450,78 @@ declare class PostsResource {
   get<S extends Selection<Post> = typeof DEFAULT_GET_FIELDS>(args: PostGetArgs<S>, options?: FetchOptions): QueryBuilder<Selected<Post, S>>;
 }
 //#endregion
+//#region src/resources/reviews.d.ts
+interface ReviewSubmitArgs {
+  /** `courseId` from `courses.reviewState()`. */
+  courseId: string;
+  /** 0.5, 1, 1.5, … 5. Anything else rejects with `INVALID_SCORE` before sending. */
+  score: number;
+  /**
+   * The review text, always sent: an update replaces the stored comment with
+   * this value, so pass the existing text to keep it and `""` to clear it.
+   * Leaving it out rejects with `CONFIG` rather than clear it by accident.
+   */
+  comment: string;
+}
+interface ReviewDeleteArgs {
+  /** `courseId` from `courses.reviewState()`. */
+  courseId: string;
+  /**
+   * The review to delete: the member's own is `review.id` from
+   * `courses.reviewState()`; an owner or manager may pass any review's id.
+   */
+  reviewId: string;
+}
+/**
+ * Course reviews written by the signed-in member, plus deletion for the
+ * site's owner and managers (moderation). Browser on the site's own
+ * domain only; elsewhere every method rejects with `AUTH_REQUIRED`.
+ *
+ * Each submit emails the site owner. Call `submit` from an explicit member
+ * action (a Submit button), never from autosave or on every star change.
+ */
+declare class ReviewsResource {
+  private client;
+  private auth;
+  constructor(client: LoopwiseClient, auth: AuthResource);
+  /**
+   * Create the member's review of a course, or replace it if they already
+   * have one. Resolves to the stored review.
+   *
+   * Rejects with `LoopwiseError` code `INVALID_SCORE`, `NOT_SIGNED_IN`,
+   * `NOT_PURCHASED`, `RATINGS_OFF` or `AUTH_REQUIRED`.
+   *
+   * @example
+   * form.addEventListener('submit', async (event) => {
+   *   event.preventDefault()
+   *   const review = await loopwise.reviews.submit({
+   *     courseId: state.courseId,
+   *     score: Number(form.score.value),
+   *     comment: form.comment.value,
+   *   })
+   * })
+   */
+  submit(args: ReviewSubmitArgs): Promise<MemberReview>;
+  /**
+   * Delete a review of a course.
+   *
+   * The server allows the review's author, and the site's owner or
+   * managers (for moderation); anyone else is refused. Rejects with
+   * `NOT_SIGNED_IN` or `AUTH_REQUIRED`; a review the member may not delete,
+   * or one that no longer exists, rejects with `GRAPHQL`.
+   */
+  delete(args: ReviewDeleteArgs): Promise<void>;
+  private mapError;
+  private notSignedIn;
+}
+//#endregion
 //#region src/index.d.ts
 interface Loopwise {
+  readonly auth: AuthResource;
   readonly courses: CoursesResource;
   readonly orders: OrdersResource;
   readonly posts: PostsResource;
+  readonly reviews: ReviewsResource;
   /**
    * Compose multiple resource queries into a single GraphQL HTTP request.
    * @example
@@ -331,7 +530,7 @@ interface Loopwise {
    *   recent:   loopwise.courses.list({ limit: 3, page: 2 }),
    * }, { cache: 60 })
    */
-  batch<R extends Record<string, QueryBuilder<unknown>>>(builders: R, options?: FetchOptions): Promise<{ [K in keyof R]: R[K] extends QueryBuilder<infer T> ? T : never }>;
+  batch<R extends Record<string, QueryBuilder<unknown>>>(builders: R, options?: FetchOptions): Promise<{ [K in keyof R]: R[K] extends QueryBuilder<infer T> ? T : never; }>;
   /**
    * Raw GraphQL escape hatch. Use when a typed resource method doesn't cover
    * what you need (new schema fields, custom queries, ad-hoc inspection).
@@ -353,4 +552,4 @@ interface Loopwise {
 }
 declare function createClient(config: LoopwiseConfig): Loopwise;
 //#endregion
-export { type Course, type FetchOptions, type Lecturer, type ListResult, Loopwise, type LoopwiseConfig, LoopwiseError, type Order, type OrderItem, type OrderStatus, type PageInfo, type Post, QueryBuilder, type Selected, type Selection, createClient };
+export { type Course, type CourseRating, type CourseReviewState, type CourseReviewStatus, type FetchOptions, type GraphQLError, type Lecturer, type ListResult, Loopwise, type LoopwiseConfig, LoopwiseError, type LoopwiseErrorCode, type Member, type MemberReview, type Order, type OrderItem, type OrderStatus, type PageInfo, type Post, QueryBuilder, type Selected, type Selection, createClient };

package/dist/index.mjs

@@ -36,6 +36,7 @@ var LoopwiseClient = class {
 	constructor(config) {
 		const site = config.site ?? config.tenant;
 		if (detectRuntime() !== "browser" && !site) throw new LoopwiseError("CONFIG", "site is required outside browser runtime. Pass it to createClient({ site }).");
+		if (config.apiVersion !== void 0 && config.apiVersion.trim() === "") throw new LoopwiseError("CONFIG", "apiVersion must be a release date (YYYY-MM-DD) or omitted; a blank value would be served as the baseline schema.");
 		this.config = {
 			...config,
 			site,
@@ -97,10 +98,41 @@ var LoopwiseClient = class {
 		}
 		return result;
 	}
+	/**
+	* POST a document on behalf of the signed-in member and return the whole
+	* GraphQL response, errors included, so the caller can map service error
+	* codes. Refuses wherever the member's `token` cookie cannot ride along.
+	*/
+	async member(payload) {
+		this.assertMemberOrigin();
+		return this.request(payload, { cache: "no-store" });
+	}
+	graphqlError(errors, code = "GRAPHQL", message) {
+		return new LoopwiseError(code, message ?? errors[0]?.message ?? "GraphQL error", {
+			site: this.config.site,
+			endpoint: this.endpoint,
+			graphqlErrors: errors
+		});
+	}
+	assertMemberOrigin() {
+		const detail = {
+			site: this.config.site,
+			endpoint: this.endpoint
+		};
+		if (detectRuntime() !== "browser") throw new LoopwiseError("AUTH_REQUIRED", "Member actions run only in the browser on the site's own domain; server-side code has no signed-in member.", detail);
+		const target = new URL(this.endpoint, window.location.href).origin;
+		if (target !== window.location.origin) throw new LoopwiseError("AUTH_REQUIRED", `Member actions need the page and the API on one origin; this page is ${window.location.origin} but the API is ${target}, so the member's sign-in cookie is not sent.`, detail);
+	}
 	async fetchGraphQL(payload, options = {}) {
+		const body = await this.request(payload, options);
+		if (body.errors?.length) throw this.graphqlError(body.errors);
+		return body.data ?? null;
+	}
+	async request(payload, options) {
 		const headers = { accept: "application/graphql-response+json, application/json" };
 		const apiKey = this.resolveApiKey();
 		if (apiKey) headers.authorization = `Bearer ${apiKey}`;
+		if (this.config.apiVersion) headers["api-version"] = this.config.apiVersion;
 		const useGet = this.shouldUseGet(payload, options);
 		if (typeof options.cache === "number" && options.cache > 0) headers["x-loopwise-cache"] = String(options.cache);
 		let response;
@@ -134,17 +166,17 @@ var LoopwiseClient = class {
 			site: this.config.site,
 			endpoint: this.endpoint
 		});
-		if (!response.ok) throw new LoopwiseError("NETWORK", `Upstream ${response.status}`, {
-			site: this.config.site,
-			endpoint: this.endpoint
-		});
-		const body = await response.json();
-		if (body.errors?.length) throw new LoopwiseError("GRAPHQL", body.errors[0]?.message ?? "GraphQL error", {
-			site: this.config.site,
-			endpoint: this.endpoint,
-			graphqlErrors: body.errors
-		});
-		return body.data ?? null;
+		let body;
+		if (response.ok) body = await response.json();
+		else {
+			const errorBody = await parseGraphQLErrorBody(response);
+			if (!errorBody) throw new LoopwiseError("NETWORK", `Upstream ${response.status}`, {
+				site: this.config.site,
+				endpoint: this.endpoint
+			});
+			body = errorBody;
+		}
+		return body;
 	}
 	shouldUseGet(payload, options) {
 		if (typeof options.cache !== "number" || options.cache <= 0) return false;
@@ -168,6 +200,18 @@ var LoopwiseClient = class {
 		return globalThis.process?.env?.LOOPWISE_API_KEY;
 	}
 };
+async function parseGraphQLErrorBody(response) {
+	let parsed;
+	try {
+		parsed = JSON.parse(await response.text());
+	} catch {
+		return null;
+	}
+	if (!parsed || typeof parsed !== "object") return null;
+	const errors = parsed.errors;
+	if (!Array.isArray(errors) || errors.length === 0) return null;
+	return errors.every((e) => e !== null && typeof e === "object" && typeof e.message === "string") ? parsed : null;
+}
 function firstOperationKeyword(document) {
 	let i = 0;
 	if (document.charCodeAt(0) === 65279) i = 1;
@@ -254,6 +298,58 @@ var QueryBuilder = class {
 	}
 };
 //#endregion
+//#region src/schema/auth.ts
+const ME_QUERY = "query Me($subdomain: String!) { user(subdomain: $subdomain) { id name } }";
+function mapMember(raw) {
+	return {
+		id: raw.id,
+		name: raw.name ?? null
+	};
+}
+function serviceCode(error) {
+	if (typeof error.code === "string") return error.code;
+	const ext = error.extensions?.code;
+	return typeof ext === "string" ? ext : void 0;
+}
+function isForeignMemberError(error) {
+	return error.path?.[0] === "user" && serviceCode(error) === "User-000";
+}
+//#endregion
+//#region src/resources/auth.ts
+/**
+* The member signed in to this site, read from the page's own sign-in
+* cookie. Works only in the browser on the site's own domain; elsewhere
+* every method rejects with `LoopwiseError` code `'AUTH_REQUIRED'` instead
+* of reporting a signed-out visitor.
+*/
+var AuthResource = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/**
+	* The signed-in member, or `null` for a signed-out visitor.
+	* @example
+	* const me = await loopwise.auth.getMe()
+	* greeting.textContent = me ? `Hi ${me.name ?? ''}` : 'Sign in'
+	*/
+	async getMe() {
+		const body = await this.client.member({
+			query: ME_QUERY,
+			variables: { subdomain: this.client.config.site ?? "" },
+			operationName: "Me"
+		});
+		const errors = body.errors ?? [];
+		if (errors.length > 0 && !errors.every(isForeignMemberError)) throw this.client.graphqlError(errors);
+		const raw = body.data?.user;
+		return raw ? mapMember(raw) : null;
+	}
+	/** Whether a member is signed in to this site. */
+	async isAuthenticated() {
+		return await this.getMe() !== null;
+	}
+};
+//#endregion
 //#region src/schema/courses.ts
 /** Map SDK Course selection -> schema field selection set. */
 function buildCourseSelection(select) {
@@ -303,6 +399,25 @@ function mapCoursePage(raw) {
 	};
 }
 //#endregion
+//#region src/schema/reviews.ts
+const REVIEW_STATE_QUERY = "query CourseReviewState($subdomain: String!, $slug: String!) { user(subdomain: $subdomain) { id } course(subdomain: $subdomain, slug: $slug) { id isRatingActive isPurchased reviewed { id score comment } rating { average total } } }";
+const SUBMIT_REVIEW_MUTATION = "mutation SubmitReview($resourceInput: ResourceInput!, $rateInput: RateInput!) { createOrUpdateRate(resourceInput: $resourceInput, rateInput: $rateInput) { rate { id score comment } } }";
+const DELETE_REVIEW_MUTATION = "mutation DeleteReview($subdomain: String!, $resourceInput: ResourceInput!, $rateId: String!) { deleteRate(subdomain: $subdomain, resourceInput: $resourceInput, rateId: $rateId) { success } }";
+function mapMemberReview(raw) {
+	return {
+		id: raw.id,
+		score: raw.score,
+		comment: raw.comment ?? ""
+	};
+}
+function isValidScore(score) {
+	return typeof score === "number" && Number.isFinite(score) && score >= .5 && score <= 5 && Number.isInteger(score * 2);
+}
+function currentLoginUrl() {
+	const { pathname, search, hash } = window.location;
+	return `/login?redirect=${encodeURIComponent(pathname + search + hash)}`;
+}
+//#endregion
 //#region src/resources/courses.ts
 const DEFAULT_LIST_FIELDS$1 = {
 	id: true,
@@ -384,7 +499,59 @@ var CoursesResource = class {
 			transform: (raw) => mapCourse(raw)
 		}, options);
 	}
+	/**
+	* What the signed-in member can do about reviewing a course, in one
+	* request: whether reviews are on, whether they are signed in and
+	* enrolled, their own review, and the course's rating summary.
+	*
+	* Member state: call it in the browser on the site's own domain, after
+	* the page loads. It never uses the `cache` option, and it rejects with
+	* `LoopwiseError` code `AUTH_REQUIRED` server-side or off-origin rather
+	* than report every visitor as signed out. An unknown slug rejects with
+	* `GRAPHQL`.
+	*
+	* @example
+	* const state = await loopwise.courses.reviewState({ slug: 'finance' })
+	* switch (state.status) {
+	*   case 'ratings_off':   return hide()
+	*   case 'signed_out':    return showLink(state.loginUrl)
+	*   case 'not_purchased': return showText('Enroll to review this course')
+	*   case 'can_review':    return showForm()
+	*   case 'reviewed':      return showForm(state.review)
+	* }
+	*/
+	async reviewState(args) {
+		if (typeof args?.slug !== "string" || args.slug === "") throw new LoopwiseError("CONFIG", "slug is required");
+		const body = await this.client.member({
+			query: REVIEW_STATE_QUERY,
+			variables: {
+				subdomain: this.client.config.site ?? "",
+				slug: args.slug
+			},
+			operationName: "CourseReviewState"
+		});
+		const errors = body.errors ?? [];
+		if (errors.length > 0 && !errors.every(isForeignMemberError)) throw this.client.graphqlError(errors);
+		const course = body.data?.course;
+		if (!course) throw this.client.graphqlError(errors, "GRAPHQL", `No course with slug "${args.slug}"`);
+		const signedIn = body.data?.user != null;
+		const review = signedIn && course.reviewed ? mapMemberReview(course.reviewed) : null;
+		return {
+			status: reviewStatus(course, signedIn, review !== null),
+			courseId: course.id,
+			review,
+			rating: course.rating ?? null,
+			loginUrl: currentLoginUrl()
+		};
+	}
 };
+function reviewStatus(course, signedIn, reviewed) {
+	if (!course.isRatingActive) return "ratings_off";
+	if (!signedIn) return "signed_out";
+	if (reviewed) return "reviewed";
+	if (!course.isPurchased) return "not_purchased";
+	return "can_review";
+}
 //#endregion
 //#region src/schema/orders.ts
 /** Map SDK Order selection -> schema field selection set. */
@@ -628,13 +795,114 @@ var PostsResource = class {
 	}
 };
 //#endregion
+//#region src/resources/reviews.ts
+/**
+* Course reviews written by the signed-in member, plus deletion for the
+* site's owner and managers (moderation). Browser on the site's own
+* domain only; elsewhere every method rejects with `AUTH_REQUIRED`.
+*
+* Each submit emails the site owner. Call `submit` from an explicit member
+* action (a Submit button), never from autosave or on every star change.
+*/
+var ReviewsResource = class {
+	client;
+	auth;
+	constructor(client, auth) {
+		this.client = client;
+		this.auth = auth;
+	}
+	/**
+	* Create the member's review of a course, or replace it if they already
+	* have one. Resolves to the stored review.
+	*
+	* Rejects with `LoopwiseError` code `INVALID_SCORE`, `NOT_SIGNED_IN`,
+	* `NOT_PURCHASED`, `RATINGS_OFF` or `AUTH_REQUIRED`.
+	*
+	* @example
+	* form.addEventListener('submit', async (event) => {
+	*   event.preventDefault()
+	*   const review = await loopwise.reviews.submit({
+	*     courseId: state.courseId,
+	*     score: Number(form.score.value),
+	*     comment: form.comment.value,
+	*   })
+	* })
+	*/
+	async submit(args) {
+		assertCourseId(args.courseId);
+		if (!isValidScore(args.score)) throw new LoopwiseError("INVALID_SCORE", `score must be 0.5 to 5 in steps of 0.5; got ${String(args.score)}`);
+		const { comment } = args;
+		if (typeof comment !== "string") throw new LoopwiseError("CONFIG", "comment is required: pass the review text, or \"\" to clear it");
+		const body = await this.client.member({
+			query: SUBMIT_REVIEW_MUTATION,
+			variables: {
+				resourceInput: {
+					resourceType: "Course",
+					resourceId: args.courseId
+				},
+				rateInput: {
+					score: args.score,
+					comment
+				}
+			},
+			operationName: "SubmitReview"
+		});
+		if (body.errors?.length) throw await this.mapError(body.errors);
+		const payload = body.data?.createOrUpdateRate;
+		if (!payload?.rate) throw new LoopwiseError("GRAPHQL", "The review was not saved", { site: this.client.config.site });
+		return mapMemberReview(payload.rate);
+	}
+	/**
+	* Delete a review of a course.
+	*
+	* The server allows the review's author, and the site's owner or
+	* managers (for moderation); anyone else is refused. Rejects with
+	* `NOT_SIGNED_IN` or `AUTH_REQUIRED`; a review the member may not delete,
+	* or one that no longer exists, rejects with `GRAPHQL`.
+	*/
+	async delete(args) {
+		assertCourseId(args.courseId);
+		if (typeof args.reviewId !== "string" || args.reviewId === "") throw new LoopwiseError("CONFIG", "reviewId is required");
+		const body = await this.client.member({
+			query: DELETE_REVIEW_MUTATION,
+			variables: {
+				subdomain: this.client.config.site ?? "",
+				resourceInput: {
+					resourceType: "Course",
+					resourceId: args.courseId
+				},
+				rateId: args.reviewId
+			},
+			operationName: "DeleteReview"
+		});
+		if (body.errors?.length) throw (body.errors.some((e) => serviceCode(e) === "User-000") ? await this.auth.isAuthenticated() : true) ? this.client.graphqlError(body.errors) : this.notSignedIn(body.errors);
+		if (!(body.data?.deleteRate)?.success) throw new LoopwiseError("GRAPHQL", "The review was not deleted", { site: this.client.config.site });
+	}
+	async mapError(errors) {
+		const codes = errors.map(serviceCode);
+		if (codes.includes("Rate-001")) return this.client.graphqlError(errors, "INVALID_SCORE", "score must be 0.5 to 5 in steps of 0.5");
+		if (codes.includes("Rate-002")) return this.client.graphqlError(errors, "RATINGS_OFF", "Reviews are turned off for this course");
+		if (codes.includes("User-000")) return await this.auth.isAuthenticated() ? this.client.graphqlError(errors, "NOT_PURCHASED", "Only members enrolled in this course can review it") : this.notSignedIn(errors);
+		return this.client.graphqlError(errors);
+	}
+	notSignedIn(errors) {
+		return this.client.graphqlError(errors, "NOT_SIGNED_IN", "Sign in to review this course");
+	}
+};
+function assertCourseId(courseId) {
+	if (typeof courseId !== "string" || courseId === "") throw new LoopwiseError("CONFIG", "courseId is required");
+}
+//#endregion
 //#region src/index.ts
 function createClient(config) {
 	const client = new LoopwiseClient(config);
+	const auth = new AuthResource(client);
 	return {
+		auth,
 		courses: new CoursesResource(client),
 		orders: new OrdersResource(client),
 		posts: new PostsResource(client),
+		reviews: new ReviewsResource(client, auth),
 		batch(builders, options) {
 			return client.batch(builders, options);
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopwise/sdk",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "description": "Loopwise platform SDK — agent-friendly headless API client",
   "repository": {
     "type": "git",
@@ -43,16 +43,17 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "regen:lock": "node scripts/regen-lock.mjs"
   },
   "devDependencies": {
+    "@kaikhq/graphql-proxy": "workspace:*",
     "graphql": "16.13.1",
     "tsconfig": "workspace:*",
-    "tsdown": "0.22.0",
+    "tsdown": "catalog:",
     "typescript": "5.9.3",
-    "vitest": "4.1.0"
+    "vitest": "catalog:"
   },
   "publishConfig": {
     "access": "public"