@clubays/clubgate-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @clubays/clubgate-sdk
 
-SDK for building Clubays miniapps.
+SDK for building Clubgate applications that run inside Clubays.
 
 ## Install
 
@@ -11,15 +11,82 @@ pnpm add @clubays/clubgate-sdk
 ## Use
 
 ```js
-import { clubays, init } from "@clubays/clubgate-sdk";
+import { clubgate, init } from "@clubays/clubgate-sdk";
 
-init({ hostOrigin: import.meta.env.VITE_HOST_ORIGIN }); // optional; defaults to https://www.clubays.com
+// optional; defaults to https://www.clubays.com
+init({ hostOrigin: import.meta.env.VITE_HOST_ORIGIN });
 
-const user = await clubays.user.get();
-const profile = await clubays.profile.get();
+const user = await clubgate.user.get();
+// { linkId, name, username, profileimage }
+
+const profile = await clubgate.profile.get();
+// { name, username, profileimage, coverimage, bio, description, links }
+```
+
+Each method needs a scope that your app requested in `clubgate.json` and a reviewer approved:
+
+| Method                    | Scope          |
+| ------------------------- | -------------- |
+| `clubgate.user.get()`     | `user.read`    |
+| `clubgate.profile.get()`  | `profile.read` |
+| `clubgate.link.status()`  | none           |
+| `clubgate.link.request()` | none           |
+
+## Identity: use `linkId`, not `username`
+
+`linkId` is a stable, per-app identifier for the user. Key your data on it. Usernames can change, and an old name can later belong to someone else, so use `username` for display only. Re-read `user.get()` each session instead of caching names.
+
+The internal profile id is never exposed to apps.
+
+## Sign-in and consent
+
+Set `"access": "signin"` in `clubgate.json` to require users to connect your app. Clubays shows the consent screen itself, and your app cannot skip or fake it.
+
+```js
+const status = await clubgate.link.status();
+// { linked, access, scopes }
+
+if (!status.linked) {
+  try {
+    await clubgate.link.request(); // opens the consent screen, waits for the user
+  } catch (e) {
+    if (e.code === "consent_declined") {
+      // show a "connect to continue" screen
+    }
+  }
+}
 ```
 
-Errors are `ClubaysError` with a `code`: `scope_denied`, `not_embedded`, `timeout`, `app_suspended`, `unknown_method`.
+With `"access": "open"` (the default), the app works without linking, and `user.get()` returns `linkId: null` until the user connects.
+
+## Errors
+
+Errors are `ClubgateError` with a `code`:
+
+| Code               | Meaning                                               |
+| ------------------ | ----------------------------------------------------- |
+| `scope_denied`     | The scope was not requested, approved or consented to |
+| `link_required`    | The app needs the user to connect first               |
+| `link_revoked`     | The user disconnected the app                         |
+| `consent_declined` | The user declined the consent screen                  |
+| `app_suspended`    | The app was suspended                                 |
+| `invalid_params`   | The request parameters were invalid                   |
+| `rate_limited`     | Too many requests, retry later                        |
+| `unknown_method`   | The method does not exist                             |
+| `not_embedded`     | The app was opened outside Clubays or the emulator    |
+| `timeout`          | No response from the host                             |
+
+```js
+import { ClubgateError } from "@clubays/clubgate-sdk";
+
+try {
+  await clubgate.profile.get();
+} catch (e) {
+  if (e instanceof ClubgateError && e.code === "scope_denied") {
+    /* ... */
+  }
+}
+```
 
 ## Local development
 
@@ -27,7 +94,13 @@ Errors are `ClubaysError` with a `code`: `scope_denied`, `not_embedded`, `timeou
 pnpm clubgate-emulator --app http://localhost:5174
 ```
 
-Set `VITE_HOST_ORIGIN=http://localhost:5199` while using the emulator.
+Open the URL it prints, and set `VITE_HOST_ORIGIN=http://localhost:5199` while using the emulator.
+
+Edit `emulator/mock-data.json` to test different situations:
+
+- `"access": "signin"` shows the consent screen on load
+- remove a scope from `scopes` to test `scope_denied`
+- `"linked": true` starts the user as already connected
 
 ## Package for upload
 
@@ -36,4 +109,8 @@ pnpm build
 pnpm clubgate-pack
 ```
 
-Creates `<id>-<version>.zip` from `dist/` and `miniapp.json`.
+Creates `<id>-<version>.zip` from `dist/` and `clubgate.json`. Upload the zip through the developer portal.
+
+## Notes
+
+- `clubays` and `ClubaysError` still exist as deprecated aliases of `clubgate` and `ClubgateError`. They will be removed in 1.0.

package/bin/emulator.js

@@ -1,50 +1,50 @@
-#!/usr/bin/env node
-import http from "node:http";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const root = path.join(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "emulator",
-);
-const args = process.argv.slice(2);
-const get = (flag, dflt) => {
-  const i = args.indexOf(flag);
-  return i > -1 ? args[i + 1] : dflt;
-};
-const port = Number(get("--port", 5199));
-const app = get("--app", "http://localhost:5174");
-
-const types = {
-  ".html": "text/html",
-  ".js": "text/javascript",
-  ".json": "application/json",
-};
-
-http
-  .createServer((req, res) => {
-    const name = new URL(req.url, "http://x").pathname;
-    const file = path.join(
-      root,
-      name === "/" ? "index.html" : path.normalize(name),
-    );
-    if (
-      !file.startsWith(root) ||
-      !fs.existsSync(file) ||
-      fs.statSync(file).isDirectory()
-    ) {
-      res.writeHead(404).end("not found");
-      return;
-    }
-    res.writeHead(200, {
-      "content-type": types[path.extname(file)] || "application/octet-stream",
-    });
-    fs.createReadStream(file).pipe(res);
-  })
-  .listen(port, () => {
-    console.log(
-      `Clubgate emulator: http://localhost:${port}/?app=${encodeURIComponent(app)}`,
-    );
-  });
+#!/usr/bin/env node
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "emulator",
+);
+const args = process.argv.slice(2);
+const get = (flag, dflt) => {
+  const i = args.indexOf(flag);
+  return i > -1 ? args[i + 1] : dflt;
+};
+const port = Number(get("--port", 5199));
+const app = get("--app", "http://localhost:5174");
+
+const types = {
+  ".html": "text/html",
+  ".js": "text/javascript",
+  ".json": "application/json",
+};
+
+http
+  .createServer((req, res) => {
+    const name = new URL(req.url, "http://x").pathname;
+    const file = path.join(
+      root,
+      name === "/" ? "index.html" : path.normalize(name),
+    );
+    if (
+      !file.startsWith(root) ||
+      !fs.existsSync(file) ||
+      fs.statSync(file).isDirectory()
+    ) {
+      res.writeHead(404).end("not found");
+      return;
+    }
+    res.writeHead(200, {
+      "content-type": types[path.extname(file)] || "application/octet-stream",
+    });
+    fs.createReadStream(file).pipe(res);
+  })
+  .listen(port, () => {
+    console.log(
+      `Clubgate emulator: http://localhost:${port}/?app=${encodeURIComponent(app)}`,
+    );
+  });

package/bin/pack.js

@@ -1,86 +1,86 @@
-#!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
-import archiver from "archiver";
-
-const MAX_ZIP_BYTES = 20 * 1024 * 1024; // 20 MB
-const SCOPES = ["user.read", "profile.read"]; // keep in sync with the SDK's SCOPES
-const ID_RE = /^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$/;
-const VERSION_RE = /^\d+\.\d+\.\d+$/;
-
-const cwd = process.cwd();
-const fail = (msg) => {
-  console.error(`\n  x ${msg}\n`);
-  process.exit(1);
-};
-
-// 1. build output must exist
-const dist = path.join(cwd, "dist");
-if (!fs.existsSync(path.join(dist, "index.html"))) {
-  fail("dist/index.html not found. Run your build first (pnpm build).");
-}
-
-// 2. manifest must exist and be valid
-const manifestPath = path.join(cwd, "miniapp.json");
-if (!fs.existsSync(manifestPath))
-  fail("miniapp.json not found in the project root.");
-
-let manifest;
-try {
-  manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
-} catch {
-  fail("miniapp.json is not valid JSON.");
-}
-
-const errors = [];
-if (manifest.schemaVersion !== 1) errors.push("schemaVersion must be 1");
-if (!ID_RE.test(manifest.id || ""))
-  errors.push("id must be lowercase letters, numbers, hyphens (3-32 chars)");
-if (!manifest.name || manifest.name.length > 50)
-  errors.push("name is required (max 50 chars)");
-if (!VERSION_RE.test(manifest.version || ""))
-  errors.push("version must look like 0.1.0");
-if (!Array.isArray(manifest.scopes)) {
-  errors.push("scopes must be an array");
-} else {
-  for (const s of manifest.scopes) {
-    if (!SCOPES.includes(s)) errors.push(`unknown scope: ${s}`);
-  }
-}
-if (errors.length)
-  fail("miniapp.json problems:\n    - " + errors.join("\n    - "));
-
-// 3. refuse files that must never ship (secrets, source maps are fine to drop)
-const BLOCKED = [/^\.env/, /\.pem$/, /\.key$/, /^node_modules$/];
-const walk = (dir) =>
-  fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
-    const full = path.join(dir, e.name);
-    if (BLOCKED.some((re) => re.test(e.name)))
-      fail(`dist contains a blocked file: ${path.relative(cwd, full)}`);
-    return e.isDirectory() ? walk(full) : [full];
-  });
-walk(dist);
-
-// 4. zip dist/ contents at the zip root, plus miniapp.json
-const outName = `${manifest.id}-${manifest.version}.zip`;
-const outPath = path.join(cwd, outName);
-const output = fs.createWriteStream(outPath);
-const archive = archiver("zip", { zlib: { level: 9 } });
-
-output.on("close", () => {
-  const size = archive.pointer();
-  if (size > MAX_ZIP_BYTES) {
-    fs.unlinkSync(outPath);
-    fail(
-      `zip is ${(size / 1048576).toFixed(1)} MB, over the ${MAX_ZIP_BYTES / 1048576} MB limit.`,
-    );
-  }
-  console.log(`\n  ok ${outName}  (${(size / 1024).toFixed(1)} KB)`);
-  console.log("  Upload this file to Clubays.\n");
-});
-archive.on("error", (e) => fail(e.message));
-
-archive.pipe(output);
-archive.directory(dist, false);
-archive.file(manifestPath, { name: "miniapp.json" });
-archive.finalize();
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import archiver from "archiver";
+
+const MAX_ZIP_BYTES = 20 * 1024 * 1024; // 20 MB
+const SCOPES = ["user.read", "profile.read"]; // keep in sync with the SDK's SCOPES
+const ID_RE = /^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$/;
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+
+const cwd = process.cwd();
+const fail = (msg) => {
+  console.error(`\n  x ${msg}\n`);
+  process.exit(1);
+};
+
+// 1. build output must exist
+const dist = path.join(cwd, "dist");
+if (!fs.existsSync(path.join(dist, "index.html"))) {
+  fail("dist/index.html not found. Run your build first (pnpm build).");
+}
+
+// 2. manifest must exist and be valid
+const manifestPath = path.join(cwd, "clubgate.json");
+if (!fs.existsSync(manifestPath))
+  fail("clubgate.json not found in the project root.");
+
+let manifest;
+try {
+  manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+} catch {
+  fail("clubgate.json is not valid JSON.");
+}
+
+const errors = [];
+if (manifest.schemaVersion !== 1) errors.push("schemaVersion must be 1");
+if (!ID_RE.test(manifest.id || ""))
+  errors.push("id must be lowercase letters, numbers, hyphens (3-32 chars)");
+if (!manifest.name || manifest.name.length > 50)
+  errors.push("name is required (max 50 chars)");
+if (!VERSION_RE.test(manifest.version || ""))
+  errors.push("version must look like 0.1.0");
+if (!Array.isArray(manifest.scopes)) {
+  errors.push("scopes must be an array");
+} else {
+  for (const s of manifest.scopes) {
+    if (!SCOPES.includes(s)) errors.push(`unknown scope: ${s}`);
+  }
+}
+if (errors.length)
+  fail("clubgate.json problems:\n    - " + errors.join("\n    - "));
+
+// 3. refuse files that must never ship (secrets, source maps are fine to drop)
+const BLOCKED = [/^\.env/, /\.pem$/, /\.key$/, /^node_modules$/];
+const walk = (dir) =>
+  fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const full = path.join(dir, e.name);
+    if (BLOCKED.some((re) => re.test(e.name)))
+      fail(`dist contains a blocked file: ${path.relative(cwd, full)}`);
+    return e.isDirectory() ? walk(full) : [full];
+  });
+walk(dist);
+
+// 4. zip dist/ contents at the zip root, plus clubgate.json
+const outName = `${manifest.id}-${manifest.version}.zip`;
+const outPath = path.join(cwd, outName);
+const output = fs.createWriteStream(outPath);
+const archive = archiver("zip", { zlib: { level: 9 } });
+
+output.on("close", () => {
+  const size = archive.pointer();
+  if (size > MAX_ZIP_BYTES) {
+    fs.unlinkSync(outPath);
+    fail(
+      `zip is ${(size / 1048576).toFixed(1)} MB, over the ${MAX_ZIP_BYTES / 1048576} MB limit.`,
+    );
+  }
+  console.log(`\n  ok ${outName}  (${(size / 1024).toFixed(1)} KB)`);
+  console.log("  Upload this file to Clubays.\n");
+});
+archive.on("error", (e) => fail(e.message));
+
+archive.pipe(output);
+archive.directory(dist, false);
+archive.file(manifestPath, { name: "clubgate.json" });
+archive.finalize();

package/dist/index.cjs

@@ -21,14 +21,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ClubaysError: () => ClubaysError,
+  ClubgateError: () => ClubgateError,
   clubays: () => clubays,
+  clubgate: () => clubgate,
   init: () => init
 });
 module.exports = __toCommonJS(index_exports);
-var ClubaysError = class extends Error {
+var ClubgateError = class extends Error {
   constructor(code) {
     super(code);
-    this.name = "ClubaysError";
+    this.name = "ClubgateError";
     this.code = code;
   }
 };
@@ -62,11 +64,11 @@ function onMessage(e) {
   if (!p) return;
   pending.delete(id);
   clearTimeout(p.timer);
-  error ? p.reject(new ClubaysError(error)) : p.resolve(result);
+  error ? p.reject(new ClubgateError(error)) : p.resolve(result);
 }
-function request(method, params) {
+function request(method, params, opts = {}) {
   if (typeof window === "undefined" || window.parent === window) {
-    return Promise.reject(new ClubaysError("not_embedded"));
+    return Promise.reject(new ClubgateError("not_embedded"));
   }
   if (!listening) {
     window.addEventListener("message", onMessage);
@@ -75,8 +77,8 @@ function request(method, params) {
   return new Promise((resolve, reject) => {
     const id = ++seq;
     const timer = setTimeout(() => {
-      if (pending.delete(id)) reject(new ClubaysError("timeout"));
-    }, timeoutMs);
+      if (pending.delete(id)) reject(new ClubgateError("timeout"));
+    }, opts.timeoutMs ?? timeoutMs);
     pending.set(id, { resolve, reject, timer });
     window.parent.postMessage(
       { v: PROTOCOL_VERSION, id, method, params },
@@ -84,7 +86,19 @@ function request(method, params) {
     );
   });
 }
-var clubays = {
+var clubgate = {
+  link: {
+    /** Is this user linked to the app, and with which scopes? */
+    status: () => request("link.status"),
+    /**
+     * Ask the host to show the consent screen. Resolves when the user accepts,
+     * rejects with `consent_declined` if they decline. The app cannot skip it.
+     * Waits for the user, so it uses a long timeout.
+     */
+    request: () => request("link.request", void 0, {
+      timeoutMs: 12e4
+    })
+  },
   user: {
     get: () => request("user.get")
   },
@@ -92,9 +106,13 @@ var clubays = {
     get: () => request("profile.get")
   }
 };
+var clubays = clubgate;
+var ClubaysError = ClubgateError;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ClubaysError,
+  ClubgateError,
   clubays,
+  clubgate,
   init
 });

package/dist/index.d.cts

@@ -1,19 +1,28 @@
-interface ClubaysUser {
-    profile_id: string;
+interface ClubgateUser {
+    /** Stable per-app identity. null when the app is open and the user hasn't linked. */
+    linkId: string | null;
     name: string;
     username: string;
     profileimage: string | null;
 }
-interface ClubaysProfile extends ClubaysUser {
+interface ClubgateProfile {
+    name: string;
+    username: string;
+    profileimage: string | null;
+    coverimage: string | null;
     bio: string | null;
     description: string | null;
-    coverimage: string | null;
     links: string[] | null;
 }
-type ClubaysErrorCode = "scope_denied" | "unknown_method" | "app_suspended" | "rate_limited" | "timeout" | "not_embedded" | "failed" | (string & {});
-declare class ClubaysError extends Error {
-    code: ClubaysErrorCode;
-    constructor(code: ClubaysErrorCode);
+interface LinkStatus {
+    linked: boolean;
+    access: "open" | "signin";
+    scopes: string[];
+}
+type ClubgateErrorCode = "scope_denied" | "unknown_method" | "app_suspended" | "link_required" | "link_revoked" | "consent_declined" | "invalid_params" | "rate_limited" | "timeout" | "not_embedded" | "failed" | (string & {});
+declare class ClubgateError extends Error {
+    code: ClubgateErrorCode;
+    constructor(code: ClubgateErrorCode);
 }
 interface InitOptions {
     /** Origin of the Clubays host page. Defaults to production. */
@@ -22,13 +31,56 @@ interface InitOptions {
     timeoutMs?: number;
 }
 declare function init(options?: InitOptions): void;
+declare const clubgate: {
+    link: {
+        /** Is this user linked to the app, and with which scopes? */
+        status: () => Promise<LinkStatus>;
+        /**
+         * Ask the host to show the consent screen. Resolves when the user accepts,
+         * rejects with `consent_declined` if they decline. The app cannot skip it.
+         * Waits for the user, so it uses a long timeout.
+         */
+        request: () => Promise<{
+            linked: boolean;
+        }>;
+    };
+    user: {
+        get: () => Promise<ClubgateUser>;
+    };
+    profile: {
+        get: () => Promise<ClubgateProfile>;
+    };
+};
+/** @deprecated use `clubgate` */
 declare const clubays: {
+    link: {
+        /** Is this user linked to the app, and with which scopes? */
+        status: () => Promise<LinkStatus>;
+        /**
+         * Ask the host to show the consent screen. Resolves when the user accepts,
+         * rejects with `consent_declined` if they decline. The app cannot skip it.
+         * Waits for the user, so it uses a long timeout.
+         */
+        request: () => Promise<{
+            linked: boolean;
+        }>;
+    };
     user: {
-        get: () => Promise<ClubaysUser>;
+        get: () => Promise<ClubgateUser>;
     };
     profile: {
-        get: () => Promise<ClubaysProfile>;
+        get: () => Promise<ClubgateProfile>;
     };
 };
+/** @deprecated use `ClubgateError` */
+declare const ClubaysError: typeof ClubgateError;
+/** @deprecated use `ClubgateError` */
+type ClubaysError = ClubgateError;
+/** @deprecated use `ClubgateUser` */
+type ClubaysUser = ClubgateUser;
+/** @deprecated use `ClubgateProfile` */
+type ClubaysProfile = ClubgateProfile;
+/** @deprecated use `ClubgateErrorCode` */
+type ClubaysErrorCode = ClubgateErrorCode;
 
-export { ClubaysError, type ClubaysErrorCode, type ClubaysProfile, type ClubaysUser, type InitOptions, clubays, init };
+export { ClubaysError, type ClubaysErrorCode, type ClubaysProfile, type ClubaysUser, ClubgateError, type ClubgateErrorCode, type ClubgateProfile, type ClubgateUser, type InitOptions, type LinkStatus, clubays, clubgate, init };

package/dist/index.d.ts

@@ -1,19 +1,28 @@
-interface ClubaysUser {
-    profile_id: string;
+interface ClubgateUser {
+    /** Stable per-app identity. null when the app is open and the user hasn't linked. */
+    linkId: string | null;
     name: string;
     username: string;
     profileimage: string | null;
 }
-interface ClubaysProfile extends ClubaysUser {
+interface ClubgateProfile {
+    name: string;
+    username: string;
+    profileimage: string | null;
+    coverimage: string | null;
     bio: string | null;
     description: string | null;
-    coverimage: string | null;
     links: string[] | null;
 }
-type ClubaysErrorCode = "scope_denied" | "unknown_method" | "app_suspended" | "rate_limited" | "timeout" | "not_embedded" | "failed" | (string & {});
-declare class ClubaysError extends Error {
-    code: ClubaysErrorCode;
-    constructor(code: ClubaysErrorCode);
+interface LinkStatus {
+    linked: boolean;
+    access: "open" | "signin";
+    scopes: string[];
+}
+type ClubgateErrorCode = "scope_denied" | "unknown_method" | "app_suspended" | "link_required" | "link_revoked" | "consent_declined" | "invalid_params" | "rate_limited" | "timeout" | "not_embedded" | "failed" | (string & {});
+declare class ClubgateError extends Error {
+    code: ClubgateErrorCode;
+    constructor(code: ClubgateErrorCode);
 }
 interface InitOptions {
     /** Origin of the Clubays host page. Defaults to production. */
@@ -22,13 +31,56 @@ interface InitOptions {
     timeoutMs?: number;
 }
 declare function init(options?: InitOptions): void;
+declare const clubgate: {
+    link: {
+        /** Is this user linked to the app, and with which scopes? */
+        status: () => Promise<LinkStatus>;
+        /**
+         * Ask the host to show the consent screen. Resolves when the user accepts,
+         * rejects with `consent_declined` if they decline. The app cannot skip it.
+         * Waits for the user, so it uses a long timeout.
+         */
+        request: () => Promise<{
+            linked: boolean;
+        }>;
+    };
+    user: {
+        get: () => Promise<ClubgateUser>;
+    };
+    profile: {
+        get: () => Promise<ClubgateProfile>;
+    };
+};
+/** @deprecated use `clubgate` */
 declare const clubays: {
+    link: {
+        /** Is this user linked to the app, and with which scopes? */
+        status: () => Promise<LinkStatus>;
+        /**
+         * Ask the host to show the consent screen. Resolves when the user accepts,
+         * rejects with `consent_declined` if they decline. The app cannot skip it.
+         * Waits for the user, so it uses a long timeout.
+         */
+        request: () => Promise<{
+            linked: boolean;
+        }>;
+    };
     user: {
-        get: () => Promise<ClubaysUser>;
+        get: () => Promise<ClubgateUser>;
     };
     profile: {
-        get: () => Promise<ClubaysProfile>;
+        get: () => Promise<ClubgateProfile>;
     };
 };
+/** @deprecated use `ClubgateError` */
+declare const ClubaysError: typeof ClubgateError;
+/** @deprecated use `ClubgateError` */
+type ClubaysError = ClubgateError;
+/** @deprecated use `ClubgateUser` */
+type ClubaysUser = ClubgateUser;
+/** @deprecated use `ClubgateProfile` */
+type ClubaysProfile = ClubgateProfile;
+/** @deprecated use `ClubgateErrorCode` */
+type ClubaysErrorCode = ClubgateErrorCode;
 
-export { ClubaysError, type ClubaysErrorCode, type ClubaysProfile, type ClubaysUser, type InitOptions, clubays, init };
+export { ClubaysError, type ClubaysErrorCode, type ClubaysProfile, type ClubaysUser, ClubgateError, type ClubgateErrorCode, type ClubgateProfile, type ClubgateUser, type InitOptions, type LinkStatus, clubays, clubgate, init };

package/dist/index.js

@@ -1,8 +1,8 @@
 // src/index.ts
-var ClubaysError = class extends Error {
+var ClubgateError = class extends Error {
   constructor(code) {
     super(code);
-    this.name = "ClubaysError";
+    this.name = "ClubgateError";
     this.code = code;
   }
 };
@@ -36,11 +36,11 @@ function onMessage(e) {
   if (!p) return;
   pending.delete(id);
   clearTimeout(p.timer);
-  error ? p.reject(new ClubaysError(error)) : p.resolve(result);
+  error ? p.reject(new ClubgateError(error)) : p.resolve(result);
 }
-function request(method, params) {
+function request(method, params, opts = {}) {
   if (typeof window === "undefined" || window.parent === window) {
-    return Promise.reject(new ClubaysError("not_embedded"));
+    return Promise.reject(new ClubgateError("not_embedded"));
   }
   if (!listening) {
     window.addEventListener("message", onMessage);
@@ -49,8 +49,8 @@ function request(method, params) {
   return new Promise((resolve, reject) => {
     const id = ++seq;
     const timer = setTimeout(() => {
-      if (pending.delete(id)) reject(new ClubaysError("timeout"));
-    }, timeoutMs);
+      if (pending.delete(id)) reject(new ClubgateError("timeout"));
+    }, opts.timeoutMs ?? timeoutMs);
     pending.set(id, { resolve, reject, timer });
     window.parent.postMessage(
       { v: PROTOCOL_VERSION, id, method, params },
@@ -58,7 +58,19 @@ function request(method, params) {
     );
   });
 }
-var clubays = {
+var clubgate = {
+  link: {
+    /** Is this user linked to the app, and with which scopes? */
+    status: () => request("link.status"),
+    /**
+     * Ask the host to show the consent screen. Resolves when the user accepts,
+     * rejects with `consent_declined` if they decline. The app cannot skip it.
+     * Waits for the user, so it uses a long timeout.
+     */
+    request: () => request("link.request", void 0, {
+      timeoutMs: 12e4
+    })
+  },
   user: {
     get: () => request("user.get")
   },
@@ -66,8 +78,12 @@ var clubays = {
     get: () => request("profile.get")
   }
 };
+var clubays = clubgate;
+var ClubaysError = ClubgateError;
 export {
   ClubaysError,
+  ClubgateError,
   clubays,
+  clubgate,
   init
 };

package/emulator/host.js

@@ -4,22 +4,98 @@ const appOrigin = new URL(appUrl).origin;
 
 const data = await fetch("./mock-data.json").then((r) => r.json());
 
-const ROUTES = {
-  "user.get": { scope: "user.read", data: data.user },
-  "profile.get": { scope: "profile.read", data: data.profile },
+// state the real host keeps per user
+let linked = data.linked === true;
+
+const LABELS = {
+  "user.read": "See your name, username and photo",
+  "profile.read": "See your public profile",
 };
 
 const frame = document.getElementById("app");
 frame.src = appUrl;
 
-window.addEventListener("message", (e) => {
+// ── consent dialog (the app can never skip or fake this) ──
+const waiters = [];
+const dialog = document.createElement("div");
+dialog.style.cssText =
+  "display:none;position:fixed;inset:0;background:rgba(0,0,0,.4);align-items:center;justify-content:center;font-family:system-ui;z-index:10";
+dialog.innerHTML = `
+  <div style="background:#fff;border-radius:16px;padding:20px;width:320px">
+    <p style="margin:0;font-size:14px;font-weight:600">Connect this app</p>
+    <p style="margin:6px 0 10px;font-size:12px;color:#64748b">This app will be able to:</p>
+    <ul id="scopes" style="margin:0;padding-left:18px;font-size:12px"></ul>
+    <div style="margin-top:16px;display:flex;justify-content:flex-end;gap:8px">
+      <button id="no" style="padding:6px 12px;font-size:12px">Not now</button>
+      <button id="yes" style="padding:6px 12px;font-size:12px;background:#7c3aed;color:#fff;border:0;border-radius:8px">Allow</button>
+    </div>
+  </div>`;
+document.body.appendChild(dialog);
+dialog.querySelector("#scopes").innerHTML = data.scopes
+  .map((s) => `<li>${LABELS[s] ?? s}</li>`)
+  .join("");
+
+const showConsent = () =>
+  new Promise((resolve, reject) => {
+    waiters.push({ resolve, reject });
+    dialog.style.display = "flex";
+  });
+const closeConsent = () => (dialog.style.display = "none");
+
+dialog.querySelector("#yes").onclick = () => {
+  linked = true;
+  closeConsent();
+  waiters.splice(0).forEach((w) => w.resolve({ linked: true }));
+};
+dialog.querySelector("#no").onclick = () => {
+  closeConsent();
+  waiters.splice(0).forEach((w) => w.reject("consent_declined"));
+};
+
+// signin apps show consent on load, like the real host
+if (data.access === "signin" && !linked) showConsent().catch(() => {});
+
+// ── methods ──
+const METHODS = {
+  "link.status": {
+    scopes: [],
+    run: () => ({
+      linked,
+      access: data.access,
+      scopes: linked ? data.scopes : [],
+    }),
+  },
+  "user.get": {
+    scopes: ["user.read"],
+    run: () => ({ linkId: linked ? data.linkId : null, ...data.user }),
+  },
+  "profile.get": {
+    scopes: ["profile.read"],
+    run: () => data.profile,
+  },
+};
+
+window.addEventListener("message", async (e) => {
   if (e.origin !== appOrigin || e.source !== frame.contentWindow) return;
   const { id, method } = e.data || {};
+  if (typeof method !== "string") return;
   const reply = (msg) => e.source.postMessage({ id, ...msg }, e.origin);
 
-  const route = ROUTES[method];
-  if (!route) return reply({ error: "unknown_method" });
-  if (!data.scopes.includes(route.scope))
+  // handled by the host only, like the real one
+  if (method === "link.request") {
+    if (linked) return reply({ result: { linked: true } });
+    try {
+      return reply({ result: await showConsent() });
+    } catch (code) {
+      return reply({ error: code });
+    }
+  }
+
+  const def = METHODS[method];
+  if (!def) return reply({ error: "unknown_method" });
+  if (data.access === "signin" && !linked && method !== "link.status")
+    return reply({ error: "link_required" });
+  if (!def.scopes.every((s) => data.scopes.includes(s)))
     return reply({ error: "scope_denied" });
-  reply({ result: route.data });
+  reply({ result: def.run() });
 });

package/emulator/mock-data.json

@@ -1,13 +1,14 @@
 {
+  "access": "open",
+  "linked": false,
   "scopes": ["user.read", "profile.read"],
+  "linkId": "11111111-1111-4111-8111-111111111111",
   "user": {
-    "profile_id": "mock0001",
     "name": "Test User",
     "username": "test_user",
     "profileimage": null
   },
   "profile": {
-    "profile_id": "mock0001",
     "name": "Test User",
     "username": "test_user",
     "bio": "Mock bio",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubays/clubgate-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SDK for building Clubays miniapps",
   "type": "module",
   "license": "MIT",