@loopwise/admin-sdk 0.1.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @loopwise/admin-sdk
+
+## 0.1.0-beta.0
+
+First public pre-release.
+
+- `createAdminClient({ accessToken, refreshAccessToken?, baseUrl? })` returns a
+  `LoopwiseAdmin` interface with `.graphql<TData, TVars>()` typed pass-through
+  against `/admin/graphql`.
+- Automatic 401 → `refreshAccessToken` → retry-once with the new token.
+  Refresh callback throws / returns empty → `LoopwiseError({ code: 'AUTH' })`.
+- `.setAccessToken()` for out-of-band token refresh.
+- First resource: `admin.courses.list({ perPage, page })` returns
+  `AdminCoursePage` (nodes + pagination meta).
+- `/better-auth` sub-export: `loopwise({ clientId, clientSecret, audience?,
+  scopes?, baseUrl? })` factory delegating to better-auth's `genericOAuth`
+  plugin. PKCE on, `accessType: 'offline'`, RFC 8414 OAuth Authorization
+  Server Metadata discovery URL (`/.well-known/oauth-authorization-server`),
+  audience-aware providerId (`loopwise` / `loopwise-member`) and scope
+  defaults.

package/README.md

@@ -0,0 +1,58 @@
+# @loopwise/admin-sdk
+
+Typed access to the Loopwise admin GraphQL API (`/admin/graphql`) for tenant-built applications.
+
+Framework-agnostic core. Works in Node, Bun, Deno, Cloudflare Workers, Edge runtime, and the browser. Use the `/better-auth` sub-export for an opinionated Next.js + [better-auth](https://better-auth.com) integration that wires up OAuth + token refresh.
+
+## Quick start
+
+```ts
+import { createAdminClient } from '@loopwise/admin-sdk';
+
+const admin = createAdminClient({
+  accessToken: process.env.LOOPWISE_ACCESS_TOKEN!,
+});
+
+const { courses } = await admin.graphql<{ courses: { nodes: { id: string; name: string }[] } }>({
+  query: `{ courses(perPage: 20) { nodes { id name } } }`,
+});
+```
+
+## With better-auth (Next.js)
+
+```ts
+// auth.ts
+import { betterAuth } from 'better-auth';
+import { loopwise } from '@loopwise/admin-sdk/better-auth';
+
+export const auth = betterAuth({
+  database: /* your DB */,
+  plugins: [
+    loopwise({
+      clientId: process.env.LOOPWISE_CLIENT_ID!,
+      clientSecret: process.env.LOOPWISE_CLIENT_SECRET!,
+    }),
+  ],
+});
+```
+
+```tsx
+// app/courses/page.tsx
+import { headers } from 'next/headers';
+import { createAdminClient } from '@loopwise/admin-sdk';
+import { auth } from '@/lib/auth';
+
+export default async function Page() {
+  const { accessToken } = await auth.api.getAccessToken({
+    body: { providerId: 'loopwise' },
+    headers: headers(),
+  });
+  const admin = createAdminClient({ accessToken });
+  const { courses } = await admin.graphql<{ courses: { nodes: { id: string; name: string }[] } }>({
+    query: `{ courses(perPage: 20) { nodes { id name } } }`,
+  });
+  return <pre>{JSON.stringify(courses.nodes, null, 2)}</pre>;
+}
+```
+
+See [TEACH-18856](https://linear.app/kaik/issue/TEACH-18856) for the design rationale.

package/dist/better-auth.d.mts

@@ -0,0 +1,65 @@
+import { BetterAuthPlugin } from "better-auth/types";
+
+//#region src/better-auth.d.ts
+type LoopwiseAuthAudience = 'org_admin' | 'member';
+interface LoopwiseAuthOptions {
+  /** OAuth client ID issued at `/oauth/applications` in the school admin UI. */
+  clientId: string;
+  /** OAuth client secret. Server-only; never expose to the browser. */
+  clientSecret: string;
+  /**
+   * Token audience. Defaults to `'org_admin'` (school staff — non-student
+   * roles authorise this OAuth app). Use `'member'` for student/member-
+   * facing apps. The audience is checked at Doorkeeper authorize-time:
+   * wrong-identity users get redirected to login with the correct role.
+   *
+   * The OAuth application itself also has an `audience` field set at
+   * creation time; this option selects which provider identity ID
+   * better-auth uses (`'loopwise'` vs `'loopwise-member'`) so a tenant
+   * can register two apps and have both flows coexist.
+   */
+  audience?: LoopwiseAuthAudience;
+  /**
+   * OAuth scopes to request. Defaults to a minimal-but-useful set per
+   * audience. Override to request more (e.g. add `courses:write`,
+   * `payments:read`) or to narrow further.
+   */
+  scopes?: string[];
+  /**
+   * Base URL of the Loopwise instance. Defaults to `https://app.loopwise.com`.
+   * Discovery doc fetched from
+   * `${baseUrl}/.well-known/oauth-authorization-server`.
+   */
+  baseUrl?: string;
+}
+/**
+ * Better-auth plugin for "log in with Loopwise". Wraps `genericOAuth` with
+ * Loopwise-specific defaults so tenants only need to supply credentials.
+ *
+ * @example
+ *   import { betterAuth } from 'better-auth';
+ *   import { loopwise } from '@loopwise/admin-sdk/better-auth';
+ *
+ *   export const auth = betterAuth({
+ *     database: ...,
+ *     plugins: [
+ *       loopwise({
+ *         clientId: process.env.LOOPWISE_CLIENT_ID!,
+ *         clientSecret: process.env.LOOPWISE_CLIENT_SECRET!,
+ *       }),
+ *     ],
+ *   });
+ *
+ * @example Multi-audience (staff + member apps coexisting)
+ *   plugins: [
+ *     loopwise({ clientId: STAFF_ID, clientSecret: STAFF_SECRET }),
+ *     loopwise({
+ *       clientId: MEMBER_ID,
+ *       clientSecret: MEMBER_SECRET,
+ *       audience: 'member',
+ *     }),
+ *   ]
+ */
+declare function loopwise(options: LoopwiseAuthOptions): BetterAuthPlugin;
+//#endregion
+export { LoopwiseAuthAudience, LoopwiseAuthOptions, loopwise };

package/dist/better-auth.mjs

@@ -0,0 +1,66 @@
+import { genericOAuth } from "better-auth/plugins";
+//#region src/better-auth.ts
+const DEFAULT_BASE_URL = "https://app.loopwise.com";
+const AUDIENCE_PROFILES = {
+	org_admin: {
+		providerId: "loopwise",
+		defaultScopes: [
+			"openid",
+			"profile",
+			"email",
+			"courses:read",
+			"members:read"
+		]
+	},
+	member: {
+		providerId: "loopwise-member",
+		defaultScopes: [
+			"openid",
+			"profile",
+			"email"
+		]
+	}
+};
+/**
+* Better-auth plugin for "log in with Loopwise". Wraps `genericOAuth` with
+* Loopwise-specific defaults so tenants only need to supply credentials.
+*
+* @example
+*   import { betterAuth } from 'better-auth';
+*   import { loopwise } from '@loopwise/admin-sdk/better-auth';
+*
+*   export const auth = betterAuth({
+*     database: ...,
+*     plugins: [
+*       loopwise({
+*         clientId: process.env.LOOPWISE_CLIENT_ID!,
+*         clientSecret: process.env.LOOPWISE_CLIENT_SECRET!,
+*       }),
+*     ],
+*   });
+*
+* @example Multi-audience (staff + member apps coexisting)
+*   plugins: [
+*     loopwise({ clientId: STAFF_ID, clientSecret: STAFF_SECRET }),
+*     loopwise({
+*       clientId: MEMBER_ID,
+*       clientSecret: MEMBER_SECRET,
+*       audience: 'member',
+*     }),
+*   ]
+*/
+function loopwise(options) {
+	const profile = AUDIENCE_PROFILES[options.audience ?? "org_admin"];
+	const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+	return genericOAuth({ config: [{
+		providerId: profile.providerId,
+		clientId: options.clientId,
+		clientSecret: options.clientSecret,
+		discoveryUrl: `${baseUrl}/.well-known/oauth-authorization-server`,
+		pkce: true,
+		accessType: "offline",
+		scopes: options.scopes ?? [...profile.defaultScopes]
+	}] });
+}
+//#endregion
+export { loopwise };

package/dist/index.d.mts

@@ -0,0 +1,167 @@
+//#region src/config.d.ts
+interface LoopwiseAdminConfig {
+  /**
+   * OAuth access token issued by Doorkeeper. Sent as `Authorization: Bearer
+   * <token>` on every request. Required — the admin GraphQL endpoint does
+   * not accept anonymous traffic.
+   *
+   * The token implicitly binds the request to a school (the OAuth
+   * application has `school_id` set at creation time in the school admin
+   * UI). Tenants do NOT pass a separate subdomain — server-side derives it.
+   */
+  accessToken: string;
+  /**
+   * Async callback invoked when the upstream returns 401. Receives the
+   * current (expired) access token; returns a fresh one. The SDK retries
+   * the original request exactly once with the new token, then surfaces
+   * the result.
+   *
+   * Throw from inside to signal refresh failure — the original 401 is then
+   * mapped to `LoopwiseError({ code: 'AUTH' })`. When this callback is
+   * omitted, any 401 fails fast without retry.
+   *
+   * Typical wiring (with better-auth):
+   *   refreshAccessToken: async () => {
+   *     const { accessToken } = await auth.api.getAccessToken({
+   *       body: { providerId: 'loopwise' }, headers: req.headers,
+   *     });
+   *     return accessToken;
+   *   }
+   */
+  refreshAccessToken?: (currentToken: string) => Promise<string>;
+  /**
+   * Base URL of the Loopwise instance. Defaults to `https://app.loopwise.com`.
+   * Override for staging (`https://staging.loopwise.com`) or self-hosted.
+   * The SDK appends `/admin/graphql` automatically.
+   */
+  baseUrl?: string;
+  /**
+   * Override the full GraphQL endpoint URL. You normally never set this —
+   * the SDK derives it from `baseUrl`. Use only for non-standard routing
+   * (proxy with path rewrite, etc.).
+   */
+  endpoint?: string;
+  /**
+   * Custom fetch implementation. Defaults to `globalThis.fetch`. Override
+   * for tests, proxy injection, or runtimes where `fetch` isn't global.
+   */
+  fetch?: typeof fetch;
+}
+//#endregion
+//#region src/client.d.ts
+interface GraphQLRequest<TVars extends Record<string, unknown> = Record<string, unknown>> {
+  query: string;
+  variables?: TVars;
+  operationName?: string;
+}
+declare class LoopwiseAdminClient {
+  readonly endpoint: string;
+  private accessToken;
+  private readonly refreshAccessToken?;
+  private readonly fetchImpl;
+  private refreshInFlight;
+  constructor(config: LoopwiseAdminConfig);
+  graphql<TData, TVars extends Record<string, unknown> = Record<string, unknown>>(request: GraphQLRequest<TVars>): Promise<TData>;
+  setAccessToken(token: string): void;
+  /**
+   * Trigger or join an in-flight refresh. Resolves once `this.accessToken`
+   * holds the new token. Concurrent 401s share one round-trip.
+   *
+   * Contract: `callback` MUST eventually settle (resolve or reject). A
+   * promise that never settles leaves `refreshInFlight` set forever and
+   * subsequent 401s queue behind it indefinitely. Apply your own timeout
+   * around any network calls inside `refreshAccessToken`.
+   */
+  private runRefresh;
+  private execute;
+  private parseResponse;
+}
+//#endregion
+//#region src/error.d.ts
+type LoopwiseErrorCode = 'NETWORK' | 'AUTH' | 'GRAPHQL' | 'RATE_LIMIT' | 'CONFIG';
+interface GraphQLError {
+  message: string;
+  path?: (string | number)[];
+  extensions?: Record<string, unknown>;
+}
+declare class LoopwiseError extends Error {
+  readonly code: LoopwiseErrorCode;
+  readonly endpoint?: string;
+  readonly status?: number;
+  readonly graphqlErrors?: GraphQLError[];
+  readonly requestId?: string;
+  constructor(code: LoopwiseErrorCode, message: string, detail?: {
+    endpoint?: string;
+    status?: number;
+    graphqlErrors?: GraphQLError[];
+    requestId?: string;
+  });
+}
+//#endregion
+//#region src/resources/courses.d.ts
+/**
+ * Subset of the admin `Course` GraphQL type exposed by the v1 SDK. Field
+ * names match the schema (no remapping) — `name` not `title`. Callers who
+ * need more fields can drop down to `admin.graphql()` directly.
+ */
+interface AdminCourse {
+  id: string;
+  name: string;
+  description: string | null;
+  image: string | null;
+  courseType: string;
+  contentType: string;
+  createdAt: number;
+}
+interface AdminCoursePage {
+  nodes: AdminCourse[];
+  nodesCount: number;
+  currentPage: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+}
+interface CoursesListArgs {
+  /** Items per page. Schema default 20, max 50. */
+  perPage?: number;
+  page?: number;
+}
+declare class CoursesResource {
+  private readonly client;
+  constructor(client: LoopwiseAdminClient);
+  /**
+   * List courses scoped to the school bound to the access token. Returns
+   * the full CoursePage shape (nodes + pagination meta).
+   *
+   * Requires OAuth scope `courses:read` on the access token.
+   */
+  list(args?: CoursesListArgs): Promise<AdminCoursePage>;
+}
+//#endregion
+//#region src/index.d.ts
+interface LoopwiseAdmin {
+  readonly courses: CoursesResource;
+  /**
+   * Run a typed GraphQL operation against `/admin/graphql`. The SDK does
+   * not parse or validate the document — pass the query string as-is and
+   * declare the expected response shape via `TData`.
+   *
+   * 401 responses trigger a single automatic token-refresh retry when
+   * `refreshAccessToken` is configured on the client.
+   *
+   * @example
+   * const { courses } = await admin.graphql<{ courses: { id: string }[] }>({
+   *   query: `{ courses(perPage: 20) { id name } }`,
+   * });
+   */
+  graphql<TData, TVars extends Record<string, unknown> = Record<string, unknown>>(request: GraphQLRequest<TVars>): Promise<TData>;
+  /**
+   * Replace the access token in-place. Use when the caller manages refresh
+   * out-of-band and wants subsequent calls to use the new token without
+   * rebuilding the client.
+   */
+  setAccessToken(token: string): void;
+}
+declare function createAdminClient(config: LoopwiseAdminConfig): LoopwiseAdmin;
+//#endregion
+export { type AdminCourse, type AdminCoursePage, type CoursesListArgs, type GraphQLError, type GraphQLRequest, LoopwiseAdmin, type LoopwiseAdminConfig, LoopwiseError, type LoopwiseErrorCode, createAdminClient };

package/dist/index.mjs

@@ -0,0 +1,197 @@
+//#region src/error.ts
+var LoopwiseError = class extends Error {
+	code;
+	endpoint;
+	status;
+	graphqlErrors;
+	requestId;
+	constructor(code, message, detail = {}) {
+		super(message);
+		this.name = "LoopwiseError";
+		this.code = code;
+		this.endpoint = detail.endpoint;
+		this.status = detail.status;
+		this.graphqlErrors = detail.graphqlErrors;
+		this.requestId = detail.requestId;
+	}
+};
+//#endregion
+//#region src/client.ts
+const DEFAULT_BASE_URL = "https://app.loopwise.com";
+const BASE_HEADERS = {
+	"content-type": "application/json",
+	accept: "application/graphql-response+json, application/json"
+};
+var LoopwiseAdminClient = class {
+	endpoint;
+	accessToken;
+	refreshAccessToken;
+	fetchImpl;
+	refreshInFlight = null;
+	constructor(config) {
+		if (!config.accessToken || !config.accessToken.trim()) throw new LoopwiseError("CONFIG", "accessToken is required. Pass it to createAdminClient({ accessToken }).");
+		this.accessToken = config.accessToken;
+		this.refreshAccessToken = config.refreshAccessToken;
+		this.endpoint = config.endpoint ?? resolveEndpoint(config.baseUrl);
+		if (config.fetch) this.fetchImpl = config.fetch;
+		else if (typeof globalThis.fetch === "function") this.fetchImpl = globalThis.fetch.bind(globalThis);
+		else throw new LoopwiseError("CONFIG", "globalThis.fetch is not available in this runtime. Pass a fetch implementation via createAdminClient({ fetch })");
+	}
+	async graphql(request) {
+		let response = await this.execute(request);
+		if (response.status === 401 && this.refreshAccessToken) {
+			await this.runRefresh(this.refreshAccessToken);
+			response = await this.execute(request);
+		}
+		return this.parseResponse(response);
+	}
+	setAccessToken(token) {
+		if (!token || !token.trim()) throw new LoopwiseError("CONFIG", "setAccessToken: token must be non-empty");
+		this.accessToken = token;
+	}
+	/**
+	* Trigger or join an in-flight refresh. Resolves once `this.accessToken`
+	* holds the new token. Concurrent 401s share one round-trip.
+	*
+	* Contract: `callback` MUST eventually settle (resolve or reject). A
+	* promise that never settles leaves `refreshInFlight` set forever and
+	* subsequent 401s queue behind it indefinitely. Apply your own timeout
+	* around any network calls inside `refreshAccessToken`.
+	*/
+	runRefresh(callback) {
+		if (!this.refreshInFlight) {
+			const tokenAtFailure = this.accessToken;
+			this.refreshInFlight = (async () => {
+				try {
+					let newToken;
+					try {
+						newToken = await callback(tokenAtFailure);
+					} catch (cause) {
+						throw new LoopwiseError("AUTH", `Token refresh failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+							endpoint: this.endpoint,
+							status: 401
+						});
+					}
+					if (!newToken || !newToken.trim()) throw new LoopwiseError("AUTH", "refreshAccessToken returned an empty token", {
+						endpoint: this.endpoint,
+						status: 401
+					});
+					this.accessToken = newToken;
+				} finally {
+					this.refreshInFlight = null;
+				}
+			})();
+		}
+		return this.refreshInFlight;
+	}
+	async execute(request) {
+		try {
+			return await this.fetchImpl(this.endpoint, {
+				method: "POST",
+				credentials: "omit",
+				headers: {
+					...BASE_HEADERS,
+					authorization: `Bearer ${this.accessToken}`
+				},
+				body: JSON.stringify({
+					query: request.query,
+					variables: request.variables,
+					operationName: request.operationName
+				})
+			});
+		} catch (cause) {
+			throw new LoopwiseError("NETWORK", `Failed to reach ${this.endpoint}: ${cause instanceof Error ? cause.message : String(cause)}`, { endpoint: this.endpoint });
+		}
+	}
+	async parseResponse(response) {
+		const requestId = response.headers.get("x-request-id") ?? void 0;
+		if (response.status === 401) throw new LoopwiseError("AUTH", "Unauthorized — token rejected by upstream", {
+			endpoint: this.endpoint,
+			status: 401,
+			requestId
+		});
+		if (response.status === 429) throw new LoopwiseError("RATE_LIMIT", "Rate limit exceeded", {
+			endpoint: this.endpoint,
+			status: 429,
+			requestId
+		});
+		if (!response.ok) throw new LoopwiseError("NETWORK", `Upstream returned HTTP ${response.status}`, {
+			endpoint: this.endpoint,
+			status: response.status,
+			requestId
+		});
+		let body;
+		try {
+			body = await response.json();
+		} catch (cause) {
+			throw new LoopwiseError("NETWORK", `Upstream returned non-JSON (status ${response.status}): ${cause instanceof Error ? cause.message : String(cause)}`, {
+				endpoint: this.endpoint,
+				status: response.status,
+				requestId
+			});
+		}
+		if (body.errors && body.errors.length > 0) throw new LoopwiseError("GRAPHQL", body.errors[0].message, {
+			endpoint: this.endpoint,
+			status: response.status,
+			graphqlErrors: body.errors,
+			requestId
+		});
+		return body.data ?? null;
+	}
+};
+function resolveEndpoint(baseUrl) {
+	return `${(baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "")}/admin/graphql`;
+}
+//#endregion
+//#region src/resources/courses.ts
+const LIST_QUERY = `
+  query AdminCoursesList($perPage: Int, $page: Int) {
+    courses(perPage: $perPage, page: $page) {
+      nodes {
+        id
+        name
+        description
+        image
+        courseType
+        contentType
+        createdAt
+      }
+      nodesCount
+      currentPage
+      totalPages
+      hasNextPage
+      hasPreviousPage
+    }
+  }
+`;
+var CoursesResource = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/**
+	* List courses scoped to the school bound to the access token. Returns
+	* the full CoursePage shape (nodes + pagination meta).
+	*
+	* Requires OAuth scope `courses:read` on the access token.
+	*/
+	async list(args = {}) {
+		return (await this.client.graphql({
+			query: LIST_QUERY,
+			variables: args,
+			operationName: "AdminCoursesList"
+		})).courses;
+	}
+};
+//#endregion
+//#region src/index.ts
+function createAdminClient(config) {
+	const client = new LoopwiseAdminClient(config);
+	return {
+		courses: new CoursesResource(client),
+		graphql: (request) => client.graphql(request),
+		setAccessToken: (token) => client.setAccessToken(token)
+	};
+}
+//#endregion
+export { LoopwiseError, createAdminClient };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@loopwise/admin-sdk",
+  "version": "0.1.0-beta.0",
+  "description": "Loopwise admin GraphQL SDK — typed access to /admin/graphql for tenant-built applications",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kaikhq/manekineko.git",
+    "directory": "packages/admin-sdk"
+  },
+  "homepage": "https://www.npmjs.com/package/@loopwise/admin-sdk",
+  "bugs": {
+    "url": "https://github.com/kaikhq/manekineko/issues"
+  },
+  "keywords": [
+    "loopwise",
+    "teachify",
+    "graphql",
+    "admin",
+    "oauth",
+    "sdk"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./better-auth": {
+      "types": "./dist/better-auth.d.mts",
+      "import": "./dist/better-auth.mjs"
+    }
+  },
+  "files": [
+    "dist/*.mjs",
+    "dist/*.d.mts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "better-auth": ">=1.6.11"
+  },
+  "peerDependenciesMeta": {
+    "better-auth": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "better-auth": "1.6.11",
+    "tsconfig": "workspace:*",
+    "tsdown": "0.22.0",
+    "typescript": "5.9.3",
+    "vitest": "4.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}