@codingfactory/socialkit-vue 0.1.0

package/src/services/api.ts

@@ -0,0 +1,472 @@
+/**
+ * Configurable API service for SocialKit-powered frontends.
+ */
+
+import axios from 'axios'
+import type { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
+import type { ApiResponse, RequestConfig } from '../types/api.js'
+import type { TokenStorage } from '../utils/tokenStorage.js'
+
+/** Configuration for creating an API service instance. */
+export interface ApiServiceConfig {
+  /** Base URL for API requests (e.g. '/api' or 'https://api.example.com/api'). */
+  baseURL: string
+  /** Token storage instance for auth headers and refresh logic. */
+  tokenStorage: TokenStorage
+  /** Optional existing Axios client to configure instead of creating a new one. */
+  client?: AxiosInstance
+  /** Request timeout in milliseconds (default: 30000). */
+  timeout?: number
+  /** Paths that are considered auth pages and won't be redirected to (default: ['/login', '/register']). */
+  authPagePaths?: string[]
+  /** Path to redirect to when auth fails (default: '/login'). */
+  loginPath?: string
+  /** Delay in ms before redirecting on auth failure (default: 1500). */
+  authFailureRedirectDelayMs?: number
+  /** Optional error handler called on every response error. */
+  onResponseError?: (error: unknown) => void
+  /** Optional callback invoked just before local auth state is cleared. */
+  onAuthInvalidated?: () => void
+  /** Override the redirect target used when auth teardown occurs. */
+  buildLoginRedirectUrl?: () => string
+  /** Max retries for transient 502/503/504 idempotent requests (default: 2). */
+  maxServerRetries?: number
+  /** Base delay in ms for transient server retries (default: 500). */
+  serverRetryBaseDelayMs?: number
+}
+
+interface RetriableRequestConfig extends AxiosRequestConfig {
+  _retry?: boolean
+  _policyRetry?: boolean
+  _serverRetryCount?: number
+}
+
+interface MissingPolicy {
+  policy_id: string
+  version: number
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isTransientServerError(status: number | undefined): boolean {
+  return status === 502 || status === 503 || status === 504
+}
+
+function isIdempotentMethod(method: string | undefined): boolean {
+  const normalizedMethod = (method ?? 'get').toLowerCase()
+  return normalizedMethod === 'get' || normalizedMethod === 'head' || normalizedMethod === 'options'
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => { window.setTimeout(resolve, ms) })
+}
+
+function parseMissingPolicies(payload: unknown): MissingPolicy[] {
+  if (!isRecord(payload)) {
+    return []
+  }
+
+  const errors = payload.errors
+  if (!isRecord(errors)) {
+    return []
+  }
+
+  const missing = errors.missing
+  if (!Array.isArray(missing)) {
+    return []
+  }
+
+  const parsed: MissingPolicy[] = []
+
+  for (const item of missing) {
+    if (!isRecord(item)) {
+      continue
+    }
+
+    const policyId = item.policy_id
+    const version = item.version
+    if (typeof policyId !== 'string') {
+      continue
+    }
+
+    const parsedVersion = typeof version === 'number'
+      ? version
+      : typeof version === 'string'
+        ? Number.parseInt(version, 10)
+        : Number.NaN
+
+    if (!Number.isInteger(parsedVersion)) {
+      continue
+    }
+
+    parsed.push({ policy_id: policyId, version: parsedVersion })
+  }
+
+  return parsed
+}
+
+function isPoliciesPendingErrorPayload(payload: unknown): boolean {
+  return isRecord(payload) && payload.code === 'POLICIES_PENDING'
+}
+
+function dedupeMissingPolicies(policies: MissingPolicy[]): MissingPolicy[] {
+  const deduped = new Map<string, MissingPolicy>()
+
+  for (const policy of policies) {
+    const existing = deduped.get(policy.policy_id)
+    if (!existing || policy.version > existing.version) {
+      deduped.set(policy.policy_id, policy)
+    }
+  }
+
+  return [...deduped.values()]
+}
+
+function cloneRequestConfig(config: RetriableRequestConfig): RetriableRequestConfig {
+  return {
+    ...config,
+    headers: { ...(config.headers as Record<string, string> | undefined) }
+  }
+}
+
+function withAuthorizationHeader(
+  config: RetriableRequestConfig,
+  token: string
+): RetriableRequestConfig {
+  return {
+    ...config,
+    headers: {
+      ...(config.headers as Record<string, string> | undefined),
+      Authorization: `Bearer ${token}`
+    }
+  }
+}
+
+function createConfiguredClient(
+  baseURL: string,
+  timeout: number,
+  client?: AxiosInstance
+): AxiosInstance {
+  if (client) {
+    client.defaults.baseURL = baseURL
+    client.defaults.timeout = timeout
+    client.defaults.headers.common.Accept = 'application/json'
+    client.defaults.headers.common['Content-Type'] = 'application/json'
+    client.defaults.withCredentials = false
+    return client
+  }
+
+  return axios.create({
+    baseURL,
+    timeout,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json'
+    },
+    withCredentials: false
+  })
+}
+
+/** Public API service interface. */
+export interface ApiService {
+  get<T = unknown>(url: string, config?: RequestConfig): Promise<ApiResponse<T>>
+  post<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<ApiResponse<T>>
+  put<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<ApiResponse<T>>
+  patch<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<ApiResponse<T>>
+  delete<T = unknown>(url: string, config?: RequestConfig): Promise<ApiResponse<T>>
+  postForm<T = unknown>(url: string, form: FormData, config?: RequestConfig): Promise<T>
+  postFormRaw<T = unknown>(url: string, form: FormData, config?: RequestConfig): Promise<AxiosResponse<T>>
+  markAuthRecoveryHandled(): void
+  hasPendingAuthRequest(): boolean
+  clearPendingAuthRequest(): void
+  replayPendingAuthRequest(token: string): Promise<void>
+}
+
+/** Create a configured API service instance. */
+export function createApiService(config: ApiServiceConfig): ApiService {
+  const {
+    baseURL,
+    tokenStorage,
+    client,
+    timeout = 30000,
+    authPagePaths = ['/login', '/register'],
+    loginPath = '/login',
+    authFailureRedirectDelayMs = 1500,
+    onResponseError,
+    onAuthInvalidated,
+    buildLoginRedirectUrl,
+    maxServerRetries = 2,
+    serverRetryBaseDelayMs = 500
+  } = config
+
+  const clientInstance = createConfiguredClient(baseURL, timeout, client)
+
+  let pendingAuthRequests: RetriableRequestConfig[] = []
+  let authFailureRedirectTimeoutId: number | null = null
+  let authFailureQueuedToken: string | null = null
+  let policyAcceptancePromise: Promise<boolean> | null = null
+
+  function isPolicyAcceptRequest(url: unknown): boolean {
+    return typeof url === 'string' && url.includes('/v1/policy/accept')
+  }
+
+  async function acceptMissingPolicies(missingPolicies: MissingPolicy[]): Promise<boolean> {
+    const policiesToAccept = dedupeMissingPolicies(missingPolicies)
+    if (policiesToAccept.length === 0) {
+      return false
+    }
+
+    if (policyAcceptancePromise) {
+      return policyAcceptancePromise
+    }
+
+    policyAcceptancePromise = (async () => {
+      try {
+        for (const policy of policiesToAccept) {
+          await clientInstance.post('/v1/policy/accept', {
+            policy_id: policy.policy_id,
+            version: policy.version
+          })
+        }
+
+        return true
+      } catch {
+        return false
+      } finally {
+        policyAcceptancePromise = null
+      }
+    })()
+
+    return policyAcceptancePromise
+  }
+
+  function capturePendingAuthRequest(reqConfig: RetriableRequestConfig): void {
+    pendingAuthRequests.push(cloneRequestConfig(reqConfig))
+  }
+
+  function cancelQueuedAuthFailureRedirect(): void {
+    if (authFailureRedirectTimeoutId === null) {
+      return
+    }
+
+    window.clearTimeout(authFailureRedirectTimeoutId)
+    authFailureRedirectTimeoutId = null
+    authFailureQueuedToken = null
+  }
+
+  function queueAuthFailureRedirect(): void {
+    if (authFailureRedirectTimeoutId !== null) {
+      return
+    }
+
+    authFailureQueuedToken = tokenStorage.getToken()
+
+    authFailureRedirectTimeoutId = window.setTimeout(() => {
+      authFailureRedirectTimeoutId = null
+      const queuedToken = authFailureQueuedToken
+      authFailureQueuedToken = null
+      const currentToken = tokenStorage.getToken()
+
+      if (
+        queuedToken !== null &&
+        currentToken !== null &&
+        currentToken !== queuedToken
+      ) {
+        return
+      }
+
+      onAuthInvalidated?.()
+      tokenStorage.removeToken()
+
+      const currentPath = window.location.pathname
+      if (authPagePaths.includes(currentPath)) {
+        return
+      }
+
+      const redirectUrl = buildLoginRedirectUrl?.() ?? loginPath
+      window.location.assign(redirectUrl)
+    }, authFailureRedirectDelayMs)
+  }
+
+  clientInstance.interceptors.request.use(
+    (reqConfig) => {
+      const token = tokenStorage.getToken()
+      if (token) {
+        reqConfig.headers.Authorization = `Bearer ${token}`
+      }
+
+      const isFormData = typeof FormData !== 'undefined' && reqConfig.data instanceof FormData
+      if (isFormData) {
+        delete reqConfig.headers['Content-Type']
+        delete reqConfig.headers['content-type']
+        reqConfig.transformRequest = [(data) => data]
+      }
+
+      return reqConfig
+    },
+    (error) => Promise.reject(error)
+  )
+
+  clientInstance.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (isTransientServerError(error.response?.status)) {
+        const originalRequest = error.config as RetriableRequestConfig | undefined
+        const retryCount = originalRequest?._serverRetryCount ?? 0
+
+        if (originalRequest && retryCount < maxServerRetries && isIdempotentMethod(originalRequest.method)) {
+          originalRequest._serverRetryCount = retryCount + 1
+          await delay(serverRetryBaseDelayMs * Math.pow(2, retryCount))
+          return clientInstance(originalRequest)
+        }
+      }
+
+      if (error.response?.status === 428) {
+        const originalRequest = error.config as RetriableRequestConfig | undefined
+        const requestUrl = originalRequest?.url
+        const responsePayload = error.response?.data
+        const missingPolicies = parseMissingPolicies(responsePayload)
+        const canAttemptPolicyAcceptance = Boolean(
+          originalRequest &&
+          !originalRequest._policyRetry &&
+          !isPolicyAcceptRequest(requestUrl) &&
+          isPoliciesPendingErrorPayload(responsePayload) &&
+          missingPolicies.length > 0
+        )
+
+        if (canAttemptPolicyAcceptance && originalRequest) {
+          originalRequest._policyRetry = true
+          const accepted = await acceptMissingPolicies(missingPolicies)
+          if (accepted) {
+            return clientInstance(originalRequest)
+          }
+        }
+      }
+
+      if (error.response?.status === 401) {
+        const originalRequest = error.config as RetriableRequestConfig | undefined
+        const requestUrl = originalRequest?.url
+        const canAttemptRefresh = Boolean(
+          originalRequest &&
+          !originalRequest._retry &&
+          !tokenStorage.shouldSkipAuth(requestUrl) &&
+          !tokenStorage.isRefreshTokenEndpoint(requestUrl)
+        )
+
+        if (canAttemptRefresh && originalRequest) {
+          originalRequest._retry = true
+          const refreshedToken = await tokenStorage.tryRefreshToken()
+
+          if (refreshedToken) {
+            const retryConfig = withAuthorizationHeader(originalRequest, refreshedToken)
+            cancelQueuedAuthFailureRedirect()
+            pendingAuthRequests = []
+            return clientInstance(retryConfig)
+          }
+        }
+
+        if (tokenStorage.wasTokenRotatedSince(originalRequest?.headers)) {
+          onResponseError?.(error)
+          return Promise.reject(error)
+        }
+
+        const shouldCapturePendingRequest = Boolean(
+          originalRequest &&
+          !tokenStorage.shouldSkipAuth(requestUrl) &&
+          !tokenStorage.isRefreshTokenEndpoint(requestUrl)
+        )
+
+        if (shouldCapturePendingRequest && originalRequest) {
+          capturePendingAuthRequest(originalRequest)
+        }
+
+        queueAuthFailureRedirect()
+      }
+
+      onResponseError?.(error)
+
+      return Promise.reject(error)
+    }
+  )
+
+  return {
+    async get<T = unknown>(url: string, reqConfig?: RequestConfig): Promise<ApiResponse<T>> {
+      const response = await clientInstance.get<ApiResponse<T>>(url, reqConfig as AxiosRequestConfig)
+      return response.data
+    },
+
+    async post<T = unknown>(url: string, data?: unknown, reqConfig?: RequestConfig): Promise<ApiResponse<T>> {
+      const response = await clientInstance.post<ApiResponse<T>>(url, data, reqConfig as AxiosRequestConfig)
+      return response.data
+    },
+
+    async put<T = unknown>(url: string, data?: unknown, reqConfig?: RequestConfig): Promise<ApiResponse<T>> {
+      const response = await clientInstance.put<ApiResponse<T>>(url, data, reqConfig as AxiosRequestConfig)
+      return response.data
+    },
+
+    async patch<T = unknown>(url: string, data?: unknown, reqConfig?: RequestConfig): Promise<ApiResponse<T>> {
+      const response = await clientInstance.patch<ApiResponse<T>>(url, data, reqConfig as AxiosRequestConfig)
+      return response.data
+    },
+
+    async delete<T = unknown>(url: string, reqConfig?: RequestConfig): Promise<ApiResponse<T>> {
+      const response = await clientInstance.delete<ApiResponse<T>>(url, reqConfig as AxiosRequestConfig)
+      return response.data
+    },
+
+    async postForm<T = unknown>(url: string, form: FormData, reqConfig?: RequestConfig): Promise<T> {
+      const response = await clientInstance.post<T>(url, form, reqConfig as AxiosRequestConfig)
+      return response.data
+    },
+
+    async postFormRaw<T = unknown>(url: string, form: FormData, reqConfig?: RequestConfig): Promise<AxiosResponse<T>> {
+      const response = await clientInstance.post<T>(url, form, reqConfig as AxiosRequestConfig)
+      return response
+    },
+
+    markAuthRecoveryHandled(): void {
+      cancelQueuedAuthFailureRedirect()
+    },
+
+    hasPendingAuthRequest(): boolean {
+      return pendingAuthRequests.length > 0
+    },
+
+    clearPendingAuthRequest(): void {
+      pendingAuthRequests = []
+    },
+
+    async replayPendingAuthRequest(token: string): Promise<void> {
+      if (pendingAuthRequests.length === 0) {
+        return
+      }
+
+      cancelQueuedAuthFailureRedirect()
+
+      const requestsToReplay = pendingAuthRequests.map(cloneRequestConfig)
+      pendingAuthRequests = []
+
+      const results = await Promise.allSettled(
+        requestsToReplay.map((request) => {
+          const retryConfig = withAuthorizationHeader({
+            ...request,
+            _retry: true
+          }, token)
+
+          return clientInstance(retryConfig)
+        })
+      )
+
+      const firstRejection = results.find(
+        (result): result is PromiseRejectedResult => result.status === 'rejected'
+      )
+
+      if (firstRejection) {
+        throw firstRejection.reason as Error
+      }
+    }
+  }
+}