nocal-auth-sdk 0.2.2 → 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/types.d.ts

@@ -2,7 +2,6 @@ export interface NocalClientConfig {
     clientId: string;
     redirectUri: string;
     authServerUrl?: string;
-    storageKey?: string;
 }
 export interface OAuthLoginReq {
     state?: string;

package/package.json

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