nocal-auth-sdk 0.2.1 → 0.2.3

package/README.md

@@ -0,0 +1,182 @@
+# Nocal Auth SDK
+
+Client-side SDK để tích hợp đăng nhập bằng Nocal theo flow popup OAuth 2.0 với PKCE.
+
+SDK này giúp bạn mở popup đăng nhập, trao đổi authorization code với auth server, lấy thông tin user và lưu session vào localStorage để tiếp tục sử dụng trong frontend.
+
+## Tính năng
+
+- Đăng nhập popup không cần redirect trang
+- Hỗ trợ OAuth 2.0 + PKCE
+- Tự động lưu session/user vào localStorage
+- Lấy thông tin người dùng sau khi xác thực
+- Tích hợp với Supabase Auth-compatible endpoint mặc định
+
+## Cài đặt
+
+```bash
+npm install nocal-auth-sdk
+```
+
+Hoặc nếu đang dùng trong repo local:
+
+```bash
+npm install
+npm run build
+```
+
+## Quick start
+
+```ts
+import { NocalAuthSDK } from "nocal-auth-sdk";
+
+const auth = new NocalAuthSDK({
+  clientId: "your-client-id",
+  redirectUri: "https://your-app.com/auth/callback",
+  authServerUrl: "https://your-auth-server.com",
+});
+
+async function login() {
+  try {
+    const { user, session } = await auth.signInWithNocal();
+    console.log("User:", user);
+    console.log("Session:", session);
+  } catch (error) {
+    console.error("Login failed:", error);
+  }
+}
+```
+
+## Ví dụ dùng trong button click
+
+```ts
+const loginButton = document.getElementById("login-btn");
+
+loginButton?.addEventListener("click", async () => {
+  try {
+    const { user, session } = await auth.signInWithNocal({
+      state: "custom-state-value",
+    });
+
+    console.log("Đăng nhập thành công:", user.email || user.phone);
+    console.log("Access token:", session.access_token);
+  } catch (err) {
+    console.error("Lỗi đăng nhập:", err);
+  }
+});
+```
+
+## Cấu hình
+
+```ts
+interface NocalClientConfig {
+  clientId: string;
+  redirectUri: string;
+  authServerUrl?: string;
+  storageKey?: string;
+}
+```
+
+### Giải thích các field
+
+- `clientId`: ID client OAuth đã đăng ký với Nocal
+- `redirectUri`: URL callback sau khi auth server redirect về
+- `authServerUrl`: base URL của auth server, mặc định là:
+  `https://hldymiruucsqqzicnwdv.supabase.co`
+- `storageKey`: chưa được dùng trong phiên bản hiện tại, session được lưu theo key mặc định `nocal_auth_session`
+
+## API
+
+### `new NocalAuthSDK(config)`
+
+Khởi tạo instance SDK.
+
+### `signInWithNocal(req?)`
+
+Mở popup OAuth và trả về:
+
+```ts
+{
+  user: NocalUser;
+  session: NocalSession;
+}
+```
+
+#### Tham số `req`
+
+```ts
+interface OAuthLoginReq {
+  state?: string;
+  provider?: string;
+  redirectTo?: string;
+}
+```
+
+### `exchangeCodeForToken(code, codeVerifier)`
+
+Đổi authorization code lấy access token và refresh token.
+
+## Session và User
+
+SDK sẽ lưu session và thông tin user vào `localStorage` với key:
+
+```ts
+nocal_auth_session;
+```
+
+Khi khởi tạo instance, nếu có giá trị trong localStorage thì SDK sẽ tự động restore session hiện tại.
+
+## Luồng xử lý OAuth
+
+1. Tạo `state` và `codeVerifier`
+2. Tạo `code_challenge` bằng PKCE (`S256`)
+3. Mở popup tới `/auth/v1/oauth/authorize`
+4. Lắng nghe message từ auth server
+5. Nhận `code`
+6. Gọi `/auth/v1/oauth/token` để trao đổi token
+7. Gọi `/auth/v1/oauth/userinfo` để lấy thông tin user
+8. Lưu vào `localStorage` và resolve Promise
+
+## Lưu ý quan trọng
+
+- Trình duyệt phải cho phép popup mở được
+- `redirectUri` phải khớp với config đã đăng ký trên server
+- Nếu popup bị chặn, SDK ném lỗi `POPUP_BLOCKED`
+- Nếu người dùng đóng popup, SDK ném lỗi `POPUP_CLOSED_BY_USER`
+
+## Xử lý lỗi phổ biến
+
+- `POPUP_BLOCKED`: popup bị chặn bởi trình duyệt
+- `OAUTH_STATE_MISMATCH`: `state` không khớp
+- `MISSING_AUTHORIZATION_CODE`: không nhận được `code`
+- `FAILED_TO_FETCH_USERINFO`: không lấy được thông tin user
+
+## Mẫu type
+
+```ts
+interface NocalUser {
+  sub: string;
+  email?: string;
+  phone?: string;
+  email_confirmed?: boolean;
+  phone_confirmed?: boolean;
+  user_metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+interface NocalSession {
+  access_token: string;
+  refresh_token: string;
+  token_type: string;
+  expires_in: number;
+  expires_at?: number;
+}
+```
+
+## License
+
+MIT
+
+## Author
+
+Nocal Auth SDK

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export declare class NocalAuthSDK {
         user: NocalUser;
         session: NocalSession;
     }>;
-    private exchangeCodeForToken;
+    exchangeCodeForToken(code: string, codeVerifier: string): Promise<NocalSession>;
     private fetchUserInfo;
     getUser(): Promise<NocalUser | null>;
     getSession(): Promise<NocalSession | null>;

package/dist/index.js

@@ -60,8 +60,12 @@ export class NocalAuthSDK {
         authUrl.searchParams.set("code_challenge_method", "S256");
         const width = 480;
         const height = 680;
-        const left = typeof window !== "undefined" ? window.screenX + (window.outerWidth - width) / 2 : 0;
-        const top = typeof window !== "undefined" ? window.screenY + (window.outerHeight - height) / 2 : 0;
+        const left = typeof window !== "undefined"
+            ? window.screenX + (window.outerWidth - width) / 2
+            : 0;
+        const top = typeof window !== "undefined"
+            ? window.screenY + (window.outerHeight - height) / 2
+            : 0;
         const popup = window.open(authUrl.toString(), "NocalAuthPopup", `width=${width},height=${height},left=${left},top=${top},status=yes,scrollbars=yes`);
         if (!popup) {
             throw new Error("POPUP_BLOCKED");
@@ -72,8 +76,9 @@ export class NocalAuthSDK {
                 if (event.origin !== allowedOrigin)
                     return;
                 const data = event.data;
-                if (!data || (data.type !== "NOCAL_OAUTH_CODE" && data.type !== "NOCAL_OAUTH_ERROR")) {
-                    // Hoặc kiểm tra URL redirect của popup nếu Supabase native redirect trực tiếp
+                if (!data ||
+                    (data.type !== "NOCAL_OAUTH_CODE" &&
+                        data.type !== "NOCAL_OAUTH_ERROR")) {
                     return;
                 }
                 window.removeEventListener("message", messageListener);
@@ -115,17 +120,14 @@ export class NocalAuthSDK {
                     if (popup.closed) {
                         clearInterval(checkClosedTimer);
                         window.removeEventListener("message", messageListener);
-                        // Kiểm tra nếu popup đóng và đã có code trong redirect URL (nếu dùng redirect thuần)
                         reject(new Error("POPUP_CLOSED_BY_USER"));
                     }
                     else {
-                        // Lắng nghe URL thay đổi nếu Supabase redirect trực tiếp về redirectUri
                         try {
                             const popupUrl = new URL(popup.location.href);
                             if (popupUrl.origin === new URL(this.redirectUri).origin) {
                                 const code = popupUrl.searchParams.get("code");
                                 const error = popupUrl.searchParams.get("error");
-                                const returnedState = popupUrl.searchParams.get("state");
                                 if (code || error) {
                                     clearInterval(checkClosedTimer);
                                     window.removeEventListener("message", messageListener);
@@ -151,7 +153,7 @@ export class NocalAuthSDK {
                             }
                         }
                         catch (e) {
-                            // Cross-origin check while on Supabase auth domain
+                            // Cross-origin check
                         }
                     }
                 }
@@ -162,22 +164,24 @@ export class NocalAuthSDK {
         });
     }
     async exchangeCodeForToken(code, codeVerifier) {
-        const res = await fetch(`${this.authServerUrl}/auth/v1/oauth/token`, {
+        const params = new URLSearchParams();
+        params.set("grant_type", "authorization_code");
+        params.set("client_id", this.clientId);
+        params.set("redirect_uri", this.redirectUri);
+        params.set("code", code);
+        params.set("code_verifier", codeVerifier); // PKCE xác thực thay cho secret
+        const response = await fetch(`${this.authServerUrl}/auth/v1/oauth/token`, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                grant_type: "authorization_code",
-                code,
-                client_id: this.clientId,
-                redirect_uri: this.redirectUri,
-                code_verifier: codeVerifier,
-            }),
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
         });
-        const data = await res.json();
-        if (!res.ok) {
-            throw new Error(data.error_description || data.error || "FAILED_TO_EXCHANGE_TOKEN");
+        if (!response.ok) {
+            const errorData = await response.json();
+            throw new Error(`Supabase Auth Error: ${errorData.error_description || errorData.error}`);
         }
-        return data;
+        return (await response.json());
     }
     async fetchUserInfo(accessToken) {
         const res = await fetch(`${this.authServerUrl}/auth/v1/oauth/userinfo`, {

package/dist/types.d.ts

@@ -5,6 +5,8 @@ export interface NocalClientConfig {
 }
 export interface OAuthLoginReq {
     state?: string;
+    provider?: string;
+    redirectTo?: string;
 }
 export interface NocalUser {
     sub: string;
@@ -12,12 +14,13 @@ export interface NocalUser {
     phone?: string;
     email_confirmed?: boolean;
     phone_confirmed?: boolean;
-    user_metadata?: Record<string, any>;
-    [key: string]: any;
+    user_metadata?: Record<string, unknown>;
+    [key: string]: unknown;
 }
 export interface NocalSession {
     access_token: string;
     refresh_token: string;
     token_type: string;
     expires_in: number;
+    expires_at?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nocal-auth-sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Nocal Auth - client-side SDK for Login with Nocal (popup flow)",
   "type": "module",
   "main": "dist/index.js",