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

package/CHANGELOG.md

@@ -9,6 +9,45 @@ 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
@@ -100,7 +139,8 @@ 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.4...HEAD
+[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

package/README.md

@@ -59,8 +59,9 @@ 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
@@ -85,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
@@ -204,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/index.d.mts

@@ -1,8 +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>;
 }
@@ -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;
@@ -97,7 +125,16 @@ declare class LoopwiseClient implements BatchedFetcher {
   batch<R extends Record<string, unknown>>(builders: { [K in keyof R]: {
     descriptor: QueryDescriptor;
   }; }, 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;
@@ -160,6 +197,56 @@ 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";
 interface OrderItem {
@@ -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
@@ -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

@@ -98,7 +98,37 @@ 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}`;
@@ -146,12 +176,7 @@ var LoopwiseClient = class {
 			});
 			body = errorBody;
 		}
-		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;
+		return body;
 	}
 	shouldUseGet(payload, options) {
 		if (typeof options.cache !== "number" || options.cache <= 0) return false;
@@ -273,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) {
@@ -322,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,
@@ -403,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. */
@@ -647,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.4",
+  "version": "0.1.0-beta.5",
   "description": "Loopwise platform SDK — agent-friendly headless API client",
   "repository": {
     "type": "git",