@sentroy-co/client-sdk 2.13.7 → 2.13.8

package/src/auth/client.ts

@@ -0,0 +1,344 @@
+import {
+  type SentroyAuthUser,
+  type SignupResponse,
+  type LoginResponse,
+  type AuthTokensResponse,
+} from "./types"
+import { AuthHttp, type AuthHttpOptions } from "./http"
+
+/**
+ * Browser-facing Sentroy Auth SDK — Firebase Auth tarzı session API.
+ *
+ * `apiKey` BROWSER'DA OLMAMALI; bu sınıf `apiKey`'i header'a koyacaktır.
+ * RP backend gerçek api-key tutar; browser'da end-user kendi access/refresh
+ * token'larıyla yaşar. Yine de DX için sınıf hem apiKey-less browser
+ * akışına (signup/login backend proxy üzerinden) hem apiKey'li server
+ * akışına (admin) tek tip API sunar — caller hangi mod'da olduğunu
+ * `SentroyAuthAdmin` (admin SDK, sunucu) vs `SentroyAuth` (browser SDK,
+ * apiKey-less) seçimiyle netleştirir.
+ *
+ * Storage: browser'da access + refresh `storage` adapter'a yazılır
+ * (default `localStorage`). Refresh expire'a 5dk kala arka planda
+ * yenilenir; fail olursa `onAuthStateChanged(null)` ve storage silinir.
+ *
+ * **Server-side rendering**: `typeof window === "undefined"` korumalı —
+ * Node ortamında `localStorage` yok, default `memory` storage'a düşer.
+ */
+
+export type AuthStateChangeListener = (user: SentroyAuthUser | null) => void
+
+export interface AuthStorageAdapter {
+  read(): { accessToken: string; refreshToken: string; user: SentroyAuthUser } | null
+  write(value: {
+    accessToken: string
+    refreshToken: string
+    user: SentroyAuthUser
+  }): void
+  clear(): void
+}
+
+const STORAGE_KEY_PREFIX = "sentroy.auth"
+
+/**
+ * Base64URL → UTF-8 decode. Browser'da `atob` + manuel UTF-8 reconstruction;
+ * Node'da `Buffer.from(..., "base64url")`. Tek kod yolu, runtime detect.
+ */
+function decodeBase64Url(s: string): string {
+  // Pad + standard base64
+  const padded = s.replace(/-/g, "+").replace(/_/g, "/")
+  const pad = padded.length % 4 === 0 ? "" : "=".repeat(4 - (padded.length % 4))
+  if (typeof atob === "function") {
+    const binary = atob(padded + pad)
+    // UTF-8 reconstruction (JWT claims yabancı karakter içerebilir)
+    const bytes = new Uint8Array(binary.length)
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+    return new TextDecoder().decode(bytes)
+  }
+  // Node fallback
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const B = (globalThis as any).Buffer
+  if (B) return B.from(padded + pad, "base64").toString("utf8")
+  throw new Error("No base64 decoder available")
+}
+
+function localStorageAdapter(projectSlug: string): AuthStorageAdapter {
+  if (typeof window === "undefined" || !window.localStorage) {
+    return memoryStorageAdapter()
+  }
+  const key = `${STORAGE_KEY_PREFIX}.${projectSlug}`
+  return {
+    read() {
+      try {
+        const raw = window.localStorage.getItem(key)
+        if (!raw) return null
+        return JSON.parse(raw) as {
+          accessToken: string
+          refreshToken: string
+          user: SentroyAuthUser
+        }
+      } catch {
+        return null
+      }
+    },
+    write(value) {
+      try {
+        window.localStorage.setItem(key, JSON.stringify(value))
+      } catch {
+        // QuotaExceeded, etc — degrade to memory silently.
+      }
+    },
+    clear() {
+      try {
+        window.localStorage.removeItem(key)
+      } catch {
+        // ignore
+      }
+    },
+  }
+}
+
+function memoryStorageAdapter(): AuthStorageAdapter {
+  let store: {
+    accessToken: string
+    refreshToken: string
+    user: SentroyAuthUser
+  } | null = null
+  return {
+    read: () => store,
+    write: (value) => {
+      store = value
+    },
+    clear: () => {
+      store = null
+    },
+  }
+}
+
+export interface SentroyAuthOptions extends AuthHttpOptions {
+  /** Token persistence stratejisi. Default `"localStorage"` browser'da,
+   *  Node'da otomatik `"memory"`. Custom için adapter geçilebilir. */
+  storage?: "localStorage" | "memory" | AuthStorageAdapter
+  /** Background refresh tetikleme süresi (saniye, expiresIn altında).
+   *  Default 300 (5dk). */
+  refreshSkew?: number
+}
+
+export class SentroyAuth {
+  private readonly http: AuthHttp
+  private readonly storage: AuthStorageAdapter
+  private readonly listeners = new Set<AuthStateChangeListener>()
+  private readonly refreshSkew: number
+  private refreshTimer: ReturnType<typeof setTimeout> | null = null
+  private currentUser: SentroyAuthUser | null = null
+
+  constructor(opts: SentroyAuthOptions) {
+    this.http = new AuthHttp(opts)
+    this.refreshSkew = opts.refreshSkew ?? 300
+
+    if (opts.storage === "memory") {
+      this.storage = memoryStorageAdapter()
+    } else if (
+      opts.storage &&
+      typeof opts.storage === "object" &&
+      "read" in opts.storage
+    ) {
+      this.storage = opts.storage
+    } else {
+      this.storage = localStorageAdapter(opts.projectSlug)
+    }
+
+    // Restore from storage on construct — `onAuthStateChanged` listener'ları
+    // henüz yok; ilk subscribe sırasında dispatch edilir.
+    const restored = this.storage.read()
+    if (restored) {
+      this.currentUser = restored.user
+      this.scheduleRefresh(this.estimateExpiry(restored.accessToken))
+    }
+  }
+
+  // ─── Public API ──────────────────────────────────────────────────────────
+
+  get user(): SentroyAuthUser | null {
+    return this.currentUser
+  }
+
+  get accessToken(): string | null {
+    return this.storage.read()?.accessToken ?? null
+  }
+
+  async signUp(input: {
+    email: string
+    password: string
+    displayName?: string
+    metadata?: Record<string, unknown>
+  }): Promise<SignupResponse> {
+    const res = await this.http.request<SignupResponse>("/signup", {
+      method: "POST",
+      json: input,
+    })
+    if (res.accessToken && res.refreshToken) {
+      this.persist({
+        accessToken: res.accessToken,
+        refreshToken: res.refreshToken,
+        user: res.user,
+      })
+    }
+    return res
+  }
+
+  async signIn(input: {
+    email: string
+    password: string
+  }): Promise<LoginResponse> {
+    const res = await this.http.request<LoginResponse>("/login", {
+      method: "POST",
+      json: input,
+    })
+    this.persist({
+      accessToken: res.accessToken,
+      refreshToken: res.refreshToken,
+      user: res.user,
+    })
+    return res
+  }
+
+  async signOut(): Promise<void> {
+    const restored = this.storage.read()
+    if (restored?.refreshToken) {
+      // Best-effort revoke — fail'ı sessizce yut (network problem
+      // sign-out'u bloklamasın).
+      await this.http
+        .request("/logout", {
+          method: "POST",
+          json: { refreshToken: restored.refreshToken },
+        })
+        .catch(() => {})
+    }
+    this.clearSession()
+  }
+
+  async sendPasswordReset(email: string): Promise<void> {
+    await this.http.request("/password-reset/request", {
+      method: "POST",
+      json: { email },
+    })
+  }
+
+  async verifyEmail(token: string): Promise<SentroyAuthUser> {
+    const res = await this.http.request<{ user: SentroyAuthUser }>(
+      "/verify-email",
+      { method: "POST", json: { token } },
+    )
+    if (this.currentUser && this.currentUser.id === res.user.id) {
+      const restored = this.storage.read()
+      if (restored) {
+        this.persist({ ...restored, user: res.user })
+      } else {
+        this.currentUser = res.user
+        this.notify()
+      }
+    }
+    return res.user
+  }
+
+  /**
+   * Subscription pattern — Firebase Auth uyumlu. Caller'ın hemen mevcut
+   * state'i alabilmesi için constructor'da restore edilen user
+   * subscribe sırasında bir kez dispatch edilir.
+   */
+  onAuthStateChanged(listener: AuthStateChangeListener): () => void {
+    this.listeners.add(listener)
+    // Microtask gibi async dispatch — caller's `useEffect` cleanup race
+    // problemlerini önler.
+    Promise.resolve().then(() => listener(this.currentUser))
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  // ─── Internals ───────────────────────────────────────────────────────────
+
+  private persist(value: {
+    accessToken: string
+    refreshToken: string
+    user: SentroyAuthUser
+  }): void {
+    this.storage.write(value)
+    this.currentUser = value.user
+    this.notify()
+    this.scheduleRefresh(this.estimateExpiry(value.accessToken))
+  }
+
+  private clearSession(): void {
+    this.storage.clear()
+    this.currentUser = null
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer)
+      this.refreshTimer = null
+    }
+    this.notify()
+  }
+
+  private notify(): void {
+    for (const l of this.listeners) {
+      try {
+        l(this.currentUser)
+      } catch {
+        // Listener hatası diğer subscriber'ları engellemesin.
+      }
+    }
+  }
+
+  /**
+   * JWT'nin `exp` claim'inden expiry'i tahmin et. Parsing fail ise
+   * 1 saat varsay (default access TTL). Refresh window: exp - skew.
+   *
+   * **Browser-safe**: `Buffer` Node'a özel, tarayıcıda yok. `atob`
+   * + URL-safe charset normalization ile decode ediyoruz.
+   */
+  private estimateExpiry(accessToken: string): number {
+    try {
+      const [, payloadB64] = accessToken.split(".")
+      const payload = JSON.parse(decodeBase64Url(payloadB64)) as {
+        exp?: number
+      }
+      if (typeof payload.exp === "number") {
+        return payload.exp * 1000
+      }
+    } catch {
+      // ignore — fall through to default
+    }
+    return Date.now() + 60 * 60 * 1000
+  }
+
+  private scheduleRefresh(expiryMs: number): void {
+    if (typeof window === "undefined") return // SSR'da auto-refresh yok
+    if (this.refreshTimer) clearTimeout(this.refreshTimer)
+    const fireAt = expiryMs - this.refreshSkew * 1000
+    const delay = Math.max(fireAt - Date.now(), 5_000)
+    this.refreshTimer = setTimeout(() => {
+      this.refresh().catch(() => {
+        // Refresh fail → session cleared, listener'lar null user görür
+        this.clearSession()
+      })
+    }, delay)
+  }
+
+  private async refresh(): Promise<void> {
+    const restored = this.storage.read()
+    if (!restored?.refreshToken) {
+      this.clearSession()
+      return
+    }
+    const res = await this.http.request<AuthTokensResponse>("/refresh", {
+      method: "POST",
+      json: { refreshToken: restored.refreshToken },
+    })
+    this.storage.write({
+      ...restored,
+      accessToken: res.accessToken,
+      refreshToken: res.refreshToken,
+    })
+    this.scheduleRefresh(this.estimateExpiry(res.accessToken))
+  }
+}

package/src/auth/http.ts

@@ -0,0 +1,101 @@
+import { SentroyAuthError } from "./types"
+
+/**
+ * Auth-as-a-Service shared HTTP layer. Project's signup/login/refresh
+ * endpoints'iyle aynı format (JSON request + JSON response, 401/403/4xx
+ * tek-tip `{error, error_description}` shape).
+ *
+ * `apiKey` opsiyonel — browser SDK end-user akışında apiKey-less
+ * (server-only güvenlik), admin SDK her zaman set'li.
+ */
+
+const DEFAULT_AUTH_BASE_URL = "https://auth.sentroy.com"
+
+export interface AuthHttpOptions {
+  authBaseUrl?: string
+  projectSlug: string
+  apiKey?: string
+  /** Hata-fırlatma yerine raw response döndür — caller fine-grained handling. */
+  rawErrors?: boolean
+}
+
+export class AuthHttp {
+  readonly baseUrl: string
+  readonly projectSlug: string
+  readonly apiKey?: string
+
+  constructor(opts: AuthHttpOptions) {
+    this.baseUrl = (opts.authBaseUrl || DEFAULT_AUTH_BASE_URL).replace(
+      /\/+$/,
+      "",
+    )
+    this.projectSlug = opts.projectSlug
+    this.apiKey = opts.apiKey
+  }
+
+  url(path: string): string {
+    const p = path.startsWith("/") ? path : `/${path}`
+    return `${this.baseUrl}/api/v1/auth/${this.projectSlug}${p}`
+  }
+
+  async request<T>(
+    path: string,
+    init: RequestInit & {
+      json?: unknown
+      bearer?: string
+    } = {},
+  ): Promise<T> {
+    const headers = new Headers(init.headers)
+    headers.set("Accept", "application/json")
+    if (init.json !== undefined) {
+      headers.set("Content-Type", "application/json")
+    }
+    // Auth precedence: explicit `bearer` (user access token) > project `apiKey`.
+    // Caller chooses the one that fits the endpoint.
+    if (init.bearer) {
+      headers.set("Authorization", `Bearer ${init.bearer}`)
+    } else if (this.apiKey) {
+      headers.set("Authorization", `Bearer ${this.apiKey}`)
+    }
+
+    const res = await fetch(this.url(path), {
+      ...init,
+      headers,
+      body: init.json !== undefined ? JSON.stringify(init.json) : init.body,
+    })
+
+    let payload: unknown = null
+    const ct = res.headers.get("content-type") ?? ""
+    if (ct.includes("application/json")) {
+      try {
+        payload = await res.json()
+      } catch {
+        payload = null
+      }
+    }
+
+    if (!res.ok) {
+      const err =
+        payload && typeof payload === "object"
+          ? (payload as { error?: string; error_description?: string })
+          : {}
+      throw new SentroyAuthError(
+        err.error ?? "http_error",
+        err.error_description ?? `HTTP ${res.status}`,
+        res.status,
+      )
+    }
+
+    // Sentroy admin endpoints wrap in `{data}`; public endpoints sometimes
+    // too. SDK auto-unwraps when present so callers don't keep .data on
+    // every call.
+    if (
+      payload &&
+      typeof payload === "object" &&
+      "data" in (payload as Record<string, unknown>)
+    ) {
+      return (payload as { data: T }).data
+    }
+    return payload as T
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Sentroy Auth-as-a-Service — browser/server SDK entry.
+ *
+ *   import { SentroyAuth } from "@sentroy-co/client-sdk/auth"
+ *   const auth = new SentroyAuth({ projectSlug: "my-app" })
+ *
+ * For server admin operations (verifyIdToken, etc):
+ *   import { SentroyAuthAdmin } from "@sentroy-co/client-sdk/auth/admin"
+ *
+ * For React integration:
+ *   import { SentroyAuthProvider, useAuth } from "@sentroy-co/client-sdk/auth/react"
+ */
+
+export { SentroyAuth } from "./client"
+export type {
+  SentroyAuthOptions,
+  AuthStateChangeListener,
+  AuthStorageAdapter,
+} from "./client"
+export {
+  SentroyAuthError,
+  type SentroyAuthUser,
+  type SignupResponse,
+  type LoginResponse,
+  type AuthTokensResponse,
+} from "./types"

package/src/auth/react/index.tsx

@@ -0,0 +1,100 @@
+"use client"
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react"
+import { SentroyAuth, type SentroyAuthOptions } from "../client"
+import type { SentroyAuthUser } from "../types"
+
+/**
+ * Sentroy Auth React integration.
+ *
+ *   <SentroyAuthProvider projectSlug="my-app">
+ *     <App />
+ *   </SentroyAuthProvider>
+ *
+ *   const { user, loading, signIn, signOut } = useAuth()
+ *
+ * Provider içeride tek bir `SentroyAuth` instance tutar (mount/unmount
+ * arasında stable), `onAuthStateChanged` ile React state'i senkron tutar.
+ * `loading` ilk render → restore tamam mı henüz değil ayrımı için.
+ */
+
+interface AuthContextValue {
+  auth: SentroyAuth
+  user: SentroyAuthUser | null
+  /** True iken provider ilk state'i restore etmiş değil — UI'da
+   *  "spinner" göster, "redirect to /login" tetikleme. */
+  loading: boolean
+  /** Convenience proxies — caller `auth.signIn(...)` yerine doğrudan
+   *  `signIn(...)` kullanabilir. */
+  signIn: SentroyAuth["signIn"]
+  signUp: SentroyAuth["signUp"]
+  signOut: SentroyAuth["signOut"]
+  sendPasswordReset: SentroyAuth["sendPasswordReset"]
+  verifyEmail: SentroyAuth["verifyEmail"]
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null)
+
+export function SentroyAuthProvider({
+  children,
+  ...opts
+}: SentroyAuthOptions & { children: ReactNode }) {
+  // Single instance — opts deep-compare'a girersek dependency drift'i
+  // restart'a yol açar. Caller `projectSlug` değiştirmemeli runtime'da.
+  const auth = useMemo(
+    () => new SentroyAuth(opts),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [opts.projectSlug, opts.authBaseUrl, opts.apiKey],
+  )
+  const [user, setUser] = useState<SentroyAuthUser | null>(auth.user)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    const unsubscribe = auth.onAuthStateChanged((u) => {
+      setUser(u)
+      setLoading(false)
+    })
+    return unsubscribe
+  }, [auth])
+
+  const value = useMemo<AuthContextValue>(
+    () => ({
+      auth,
+      user,
+      loading,
+      signIn: (i) => auth.signIn(i),
+      signUp: (i) => auth.signUp(i),
+      signOut: () => auth.signOut(),
+      sendPasswordReset: (e) => auth.sendPasswordReset(e),
+      verifyEmail: (t) => auth.verifyEmail(t),
+    }),
+    [auth, user, loading],
+  )
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>
+}
+
+export function useAuth(): AuthContextValue {
+  const ctx = useContext(AuthContext)
+  if (!ctx) {
+    throw new Error(
+      "useAuth must be used inside <SentroyAuthProvider> — wrap your app root.",
+    )
+  }
+  return ctx
+}
+
+/**
+ * Convenience: yalnızca current user istenirse. `loading` durumunda null
+ * dönerken bekleyebilirsin.
+ */
+export function useUser(): SentroyAuthUser | null {
+  return useAuth().user
+}

package/src/auth/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Sentroy Auth-as-a-Service — SDK types.
+ *
+ * Public types are kept narrow on purpose: SDK shapes evolve with backend;
+ * caller code should depend on these names, not on hand-coded interfaces.
+ */
+
+export interface SentroyAuthUser {
+  id: string
+  authProjectId: string
+  email: string
+  emailVerified: boolean
+  displayName: string | null
+  image: string | null
+  metadata: Record<string, unknown>
+  lastLoginAt: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface AuthTokensResponse {
+  accessToken: string
+  refreshToken: string
+  expiresIn: number
+  tokenType: "Bearer"
+}
+
+export interface SignupResponse {
+  user: SentroyAuthUser
+  /** Email verification gerekiyorsa undefined; aksi halde set. */
+  accessToken?: string
+  refreshToken?: string
+  expiresIn?: number
+  tokenType?: "Bearer"
+  emailVerificationRequired?: boolean
+}
+
+export interface LoginResponse {
+  user: SentroyAuthUser
+  accessToken: string
+  refreshToken: string
+  expiresIn: number
+  tokenType: "Bearer"
+}
+
+export interface AuthApiError {
+  error: string
+  error_description: string
+}
+
+export class SentroyAuthError extends Error {
+  readonly code: string
+  readonly status: number
+  constructor(code: string, message: string, status: number) {
+    super(message)
+    this.name = "SentroyAuthError"
+    this.code = code
+    this.status = status
+  }
+}