@taruvi/sdk 1.3.2 → 1.3.4-beta.0

package/src/lib/storage/types.ts

@@ -0,0 +1,86 @@
+import type { TaruviResponse } from "../../types.js"
+
+// Internal types - all optional since they're built incrementally via builder pattern
+export interface BucketUrlParams {
+    appSlug?: string
+    bucket?: string
+    path?: string
+    upload?: string
+    delete?: string
+}
+
+export interface BucketFileUpload {
+    files: []
+    path: string
+    metadata?: Record<string, unknown>
+}
+
+// Request types
+export interface StorageRequest {
+    files: File[]
+    paths: string[]
+    metadatas: object[]
+}
+
+export interface StorageUpdateRequest {
+    metadata?: Record<string, unknown>
+    visibility?: 'public' | 'private'
+}
+
+// Storage object - matches StorageObjectSerializer from API
+export interface StorageObject {
+    id: number
+    uuid: string
+    bucket?: number
+    bucket_slug?: string
+    bucket_name?: string
+    filename: string
+    file_path: string
+    file_url: string
+    size: number
+    mimetype: string
+    metadata?: Record<string, unknown>
+    visibility?: string
+    created_at: string
+    updated_at: string
+    created_by?: number
+    modified_by?: number
+}
+
+// Response types - uses standard wrapper
+export type StorageResponse = TaruviResponse<StorageObject>
+export type StorageListResponse = TaruviResponse<StorageObject[]>
+
+// Batch upload response
+export interface StorageUploadBatchResponse {
+    status: "success" | "error"
+    message: string
+    data: {
+        uploaded_count: number
+        failed_count: number
+        total: number
+        successful: Array<{
+            index: number
+            path: string
+            object: StorageObject
+        }>
+        failed: Array<{
+            index: number
+            path: string
+            error: string
+        }>
+    }
+}
+
+// Batch delete response
+export interface StorageDeleteBatchResponse {
+    status: "success" | "error"
+    message: string
+    data: {
+        deleted_count: number
+        failed: Array<{
+            path: string
+            error: string
+        }>
+    }
+}

package/src/lib/users/UserClient.ts

@@ -0,0 +1,55 @@
+import type { Client } from "../../client.js";
+import type { UserCreateRequest, UserResponse, UserListResponse, UserListFilters, UserUpdateRequest, UserAppsResponse, AssignRolesRequest, RevokeRolesRequest, RolesResponse } from "./types.js";
+import { UserRoutes } from "../../lib-internal/routes/UserRoutes.js";
+import { buildQueryString } from "../../utils/utils.js";
+
+
+export class User {
+    private client: Client
+
+    constructor(client: Client) {
+        this.client = client
+    }
+
+    async updateUser(username: string, body: UserUpdateRequest): Promise<UserResponse> {
+        return await this.client.httpClient.put(UserRoutes.updateUser(username), body)
+    }
+
+    async getUser(username: string): Promise<UserResponse> {
+        return await this.client.httpClient.get<UserResponse>(UserRoutes.getUser(username))
+    }
+
+    async list(filters?: UserListFilters): Promise<UserListResponse> {
+        const queryString = buildQueryString(filters as unknown as Record<string, unknown>)
+        return await this.client.httpClient.get<UserListResponse>(UserRoutes.listUser(queryString))
+    }
+
+    async getUserApps(username: string): Promise<UserAppsResponse> {
+        return await this.client.httpClient.get<UserAppsResponse>(UserRoutes.getUserApps(username))
+    }
+
+    async createUser(userData: UserCreateRequest): Promise<UserResponse> {
+        return await this.client.httpClient.post<UserResponse, UserCreateRequest>(
+            UserRoutes.baseUrl,
+            userData
+        )
+    }
+
+    async deleteUser(username: string): Promise<void> {
+        return await this.client.httpClient.delete(UserRoutes.deleteUser(username))
+    }
+
+    async assignRoles(request: AssignRolesRequest): Promise<RolesResponse> {
+        return await this.client.httpClient.post<RolesResponse, AssignRolesRequest>(
+            UserRoutes.assignRoles(),
+            request
+        )
+    }
+
+    async revokeRoles(request: RevokeRolesRequest): Promise<RolesResponse> {
+        return await this.client.httpClient.delete<RolesResponse>(
+            UserRoutes.revokeRoles(),
+            request
+        )
+    }
+}

package/src/lib/users/types.ts

@@ -0,0 +1,104 @@
+import type { TaruviResponse } from "../../types.js"
+
+export interface UserCreateRequest {
+    username: string
+    email: string
+    password: string
+    confirm_password: string
+    first_name: string
+    last_name: string
+    is_active?: boolean
+    is_staff?: boolean
+    is_cloud_user?: boolean
+    attributes?: Record<string, unknown>
+    role_slugs?: string[]
+}
+
+export interface UserData {
+    id: number
+    uuid?: string
+    username: string
+    email: string
+    first_name: string
+    last_name: string
+    full_name?: string
+    is_active: boolean
+    is_staff: boolean
+    is_superuser?: boolean
+    is_deleted: boolean
+    date_joined: string
+    last_login?: string
+    groups?: UserGroup[]
+    user_permissions?: UserPermission[]
+    attributes?: Record<string, unknown>
+    missing_attributes?: string[]
+    roles?: UserRole[]
+}
+
+export interface UserGroup {
+    id: number
+    name: string
+}
+
+export interface UserPermission {
+    id: number
+    name: string
+    codename: string
+    content_type: string
+}
+
+export interface UserRole {
+    name: string
+    slug: string
+    type: string
+    app_slug: string
+    source: "direct" | "site_role" | "inherited"
+}
+
+export interface UserUpdateRequest {
+    username?: string
+    email?: string
+    first_name?: string
+    last_name?: string
+    is_active?: boolean
+    is_staff?: boolean
+}
+
+export interface UserListFilters {
+    search?: string
+    is_active?: boolean
+    is_staff?: boolean
+    is_superuser?: boolean
+    is_deleted?: boolean
+    ordering?: string
+    page?: number
+    page_size?: number
+}
+
+export interface UserApp {
+    name: string
+    slug: string
+    icon: string
+    url: string
+    display_name: string
+}
+
+// Response types - uses standard wrapper
+export type UserResponse = TaruviResponse<UserData>
+export type UserListResponse = TaruviResponse<UserData[]>
+export type UserAppsResponse = TaruviResponse<UserApp[]>
+
+export interface AssignRolesRequest {
+    roles: string[]
+    usernames: string[]
+    expires_at?: string
+}
+
+export interface RevokeRolesRequest {
+    roles: string[]
+    usernames: string[]
+}
+
+export type RolesResponse = TaruviResponse<{
+    count: number
+}>

package/src/lib-internal/errors/ErrorClient.ts

@@ -1,12 +1,102 @@
-export class ErrorClient {
+import { ErrorCode, type ErrorResponseBody } from './types.js'
 
-    constructor() {
-        // No dependencies needed for now
+/**
+ * Base SDK error. All typed errors extend this.
+ */
+export class TaruviError extends Error {
+    public readonly code: string
+    public readonly statusCode: number
+    public readonly detail: string | undefined
+    public readonly errors: Record<string, unknown> | undefined
+    public readonly data: unknown
+
+    constructor(message: string, statusCode: number, code: string = ErrorCode.INTERNAL_ERROR, detail?: string, errors?: Record<string, unknown>, data?: unknown) {
+        super(message)
+        this.name = 'TaruviError'
+        this.statusCode = statusCode
+        this.code = code
+        this.detail = detail
+        this.errors = errors
+        this.data = data
     }
+}
 
-    // TODO: Implement error handling
-    // - handleError
-    // - logError
-    // - formatError
-    // - Custom error classes (AuthError, NetworkError, etc.)
+export class ValidationError extends TaruviError {
+    constructor(message = 'Validation failed', detail?: string, errors?: Record<string, unknown>) {
+        super(message, 400, ErrorCode.VALIDATION_ERROR, detail, errors)
+        this.name = 'ValidationError'
+    }
+}
+
+export class AuthError extends TaruviError {
+    constructor(message = 'Authentication required') {
+        super(message, 401, ErrorCode.UNAUTHORIZED)
+        this.name = 'AuthError'
+    }
+}
+
+export class ForbiddenError extends TaruviError {
+    constructor(message = 'Permission denied') {
+        super(message, 403, ErrorCode.FORBIDDEN)
+        this.name = 'ForbiddenError'
+    }
+}
+
+export class NotFoundError extends TaruviError {
+    constructor(message = 'Resource not found') {
+        super(message, 404, ErrorCode.NOT_FOUND)
+        this.name = 'NotFoundError'
+    }
+}
+
+export class ConflictError extends TaruviError {
+    constructor(message = 'Resource conflict', detail?: string) {
+        super(message, 409, ErrorCode.CONFLICT, detail)
+        this.name = 'ConflictError'
+    }
+}
+
+export class TimeoutError extends TaruviError {
+    constructor(message = 'Request timeout') {
+        super(message, 504, ErrorCode.GATEWAY_TIMEOUT)
+        this.name = 'TimeoutError'
+    }
+}
+
+export class NetworkError extends TaruviError {
+    constructor(message = 'Network error') {
+        super(message, 0, ErrorCode.NETWORK_ERROR)
+        this.name = 'NetworkError'
+    }
+}
+
+/**
+ * Maps HTTP status + response body to the appropriate typed error.
+ */
+export function createErrorFromResponse(statusCode: number, body?: ErrorResponseBody): TaruviError {
+    const message = body?.message || 'Request failed'
+    const code = body?.code || ErrorCode.INTERNAL_ERROR
+    const detail = body?.detail
+    const errors = body?.errors
+    const data = body?.data
+
+    switch (statusCode) {
+        case 400:
+            if (code === ErrorCode.VALIDATION_ERROR) {
+                return new ValidationError(message, detail, errors)
+            }
+            return new TaruviError(message, 400, code, detail, errors, data)
+        case 401:
+            return new AuthError(message)
+        case 403:
+            return new ForbiddenError(message)
+        case 404:
+            return new NotFoundError(message)
+        case 409:
+            return new ConflictError(message, detail)
+        case 504:
+            return new TimeoutError(message)
+        default:
+            return new TaruviError(message, statusCode, code, detail, errors, data)
+    }
 }

package/src/lib-internal/errors/index.ts

@@ -1,25 +1,3 @@
-/**
- * Error handling module exports
- *
- * This module provides comprehensive error handling for the Taruvi SDK
- * including typed error classes, error codes, and utility functions.
- */
-
-// Export error client
-export { ErrorClient } from './ErrorClient.js';
-
-// TODO: Export all error classes when implemented
-// - TaruviError
-// - AuthError
-// - DatabaseError
-// - StorageError
-// - NetworkError
-// - ValidationError
-// - FunctionError
-
-// TODO: Export types when implemented
-// - ErrorCode
-// - ErrorSeverity
-// - ErrorResponse
-// - HttpErrorResponse
-// - ValidationErrorDetail
+export { TaruviError, ValidationError, AuthError, ForbiddenError, NotFoundError, ConflictError, TimeoutError, NetworkError, createErrorFromResponse } from './ErrorClient.js'
+export { ErrorCode } from './types.js'
+export type { ErrorResponseBody } from './types.js'

package/src/lib-internal/errors/types.ts

@@ -1,105 +1,28 @@
 /**
- * Error severity levels for categorizing errors
- */
-export enum ErrorSeverity {
-    LOW = 'low',
-    MEDIUM = 'medium',
-    HIGH = 'high',
-    CRITICAL = 'critical'
-}
-
-/**
- * Standard error codes used across the SDK
+ * Error codes matching the backend's ErrorCode enum.
+ * Maps 1:1 with base.responses.error_codes.ErrorCode in Python.
  */
 export enum ErrorCode {
-    // General errors (1000-1099)
-    UNKNOWN_ERROR = 'UNKNOWN_ERROR',
-    INTERNAL_ERROR = 'INTERNAL_ERROR',
-    TIMEOUT_ERROR = 'TIMEOUT_ERROR',
-
-    // Network errors (1100-1199)
-    NETWORK_ERROR = 'NETWORK_ERROR',
-    CONNECTION_ERROR = 'CONNECTION_ERROR',
-    REQUEST_FAILED = 'REQUEST_FAILED',
-
-    // Authentication errors (1200-1299)
-    AUTH_ERROR = 'AUTH_ERROR',
+    BAD_REQUEST = 'BAD_REQUEST',
+    VALIDATION_ERROR = 'VALIDATION_ERROR',
     UNAUTHORIZED = 'UNAUTHORIZED',
-    TOKEN_EXPIRED = 'TOKEN_EXPIRED',
-    TOKEN_INVALID = 'TOKEN_INVALID',
-    SESSION_EXPIRED = 'SESSION_EXPIRED',
-    INVALID_CREDENTIALS = 'INVALID_CREDENTIALS',
-
-    // Authorization errors (1300-1399)
     FORBIDDEN = 'FORBIDDEN',
-    INSUFFICIENT_PERMISSIONS = 'INSUFFICIENT_PERMISSIONS',
-
-    // Validation errors (1400-1499)
-    VALIDATION_ERROR = 'VALIDATION_ERROR',
-    INVALID_INPUT = 'INVALID_INPUT',
-    MISSING_REQUIRED_FIELD = 'MISSING_REQUIRED_FIELD',
-    INVALID_FORMAT = 'INVALID_FORMAT',
-
-    // Database errors (1500-1599)
-    DATABASE_ERROR = 'DATABASE_ERROR',
-    QUERY_FAILED = 'QUERY_FAILED',
-    RECORD_NOT_FOUND = 'RECORD_NOT_FOUND',
-    DUPLICATE_ENTRY = 'DUPLICATE_ENTRY',
-    CONSTRAINT_VIOLATION = 'CONSTRAINT_VIOLATION',
-
-    // Storage errors (1600-1699)
-    STORAGE_ERROR = 'STORAGE_ERROR',
-    FILE_NOT_FOUND = 'FILE_NOT_FOUND',
-    FILE_TOO_LARGE = 'FILE_TOO_LARGE',
-    INVALID_FILE_TYPE = 'INVALID_FILE_TYPE',
-    UPLOAD_FAILED = 'UPLOAD_FAILED',
-    DOWNLOAD_FAILED = 'DOWNLOAD_FAILED',
-
-    // Function errors (1700-1799)
-    FUNCTION_ERROR = 'FUNCTION_ERROR',
-    FUNCTION_NOT_FOUND = 'FUNCTION_NOT_FOUND',
-    FUNCTION_EXECUTION_FAILED = 'FUNCTION_EXECUTION_FAILED',
-    FUNCTION_TIMEOUT = 'FUNCTION_TIMEOUT',
-
-    // Rate limiting errors (1800-1899)
-    RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
-    QUOTA_EXCEEDED = 'QUOTA_EXCEEDED',
-
-    // Client errors (1900-1999)
-    CONFIGURATION_ERROR = 'CONFIGURATION_ERROR',
-    INVALID_API_KEY = 'INVALID_API_KEY',
-    INVALID_CONFIG = 'INVALID_CONFIG'
-}
-
-/**
- * Base error response structure
- */
-export interface ErrorResponse {
-    code: ErrorCode;
-    message: string;
-    severity: ErrorSeverity;
-    timestamp: string;
-    requestId?: string | undefined;
-    metadata?: Record<string, any> | undefined;
-    cause?: Error | undefined;
-}
-
-/**
- * HTTP error response from the server
- */
-export interface HttpErrorResponse {
-    status: number;
-    statusText: string;
-    message?: string;
-    code?: string;
-    details?: any;
+    NOT_FOUND = 'NOT_FOUND',
+    CONFLICT = 'CONFLICT',
+    INTERNAL_ERROR = 'INTERNAL_ERROR',
+    GATEWAY_TIMEOUT = 'GATEWAY_TIMEOUT',
+    NETWORK_ERROR = 'NETWORK_ERROR'
 }
 
 /**
- * Validation error details
+ * Backend error response shape.
+ * Matches AppException.to_dict() output.
  */
-export interface ValidationErrorDetail {
-    field: string;
-    message: string;
-    value?: any;
+export interface ErrorResponseBody {
+    status: 'error'
+    code: string
+    message: string
+    detail?: string
+    errors?: Record<string, unknown>
+    data?: unknown
 }

package/src/lib-internal/http/HttpClient.ts

@@ -1,12 +1,13 @@
 import type { TaruviConfig } from "../../types.js";
 import type { TokenClient } from "../token/TokenClient.js";
-import axios from "axios";
+import axios, { AxiosError } from "axios";
+import { createErrorFromResponse, NetworkError, TaruviError } from "../errors/index.js";
+import type { ErrorResponseBody } from "../errors/index.js";
 
 /**
  * HttpClient handles all HTTP requests to the Taruvi API.
- * Automatically adds authentication headers:
- * - Authorization: API key for site/app identification
- * - X-Session-Token: User session token for authenticated requests
+ * Automatically adds authentication headers and converts
+ * error responses to typed SDK errors.
  *
  * @internal
  */
@@ -36,56 +37,93 @@ export class HttpClient {
         return headers
     }
 
-    async get<T>(endpoint: string): Promise<T> {
-        const { data } = await axios.get<T>(`${this.config.baseUrl}/${endpoint}`, {
-            headers: this.getAuthHeaders()
-        })
-        return data
-    }
+    private handleError(error: unknown): never {
+        if (error instanceof TaruviError) {
+            throw error
+        }
 
-    async post<T, D = any>(endpoint: string, body: D): Promise<T> {
-        const isFormData = body instanceof FormData
-        const { data } = await axios.post<T>(
-            `${this.config.baseUrl}/${endpoint}`,
-            body,
-            {
-                headers: this.getAuthHeaders(isFormData)
+        if (error instanceof AxiosError) {
+            if (error.response) {
+                const body = error.response.data as ErrorResponseBody | undefined
+                throw createErrorFromResponse(error.response.status, body)
             }
-        )
-        return data
+            // No response — network error
+            throw new NetworkError(error.message)
+        }
+
+        // Unknown error
+        throw error
     }
 
-    async put<T, D = any>(endpoint: string, body: D) {
-        const isFormData = body instanceof FormData
-        const { data } = await axios.put<T>(`${this.config.baseUrl}/${endpoint}`,
-            body,
-            {
-                headers: this.getAuthHeaders(isFormData)
+    async get<T>(endpoint: string): Promise<T> {
+        try {
+            const { data } = await axios.get<T>(`${this.config.apiUrl}/${endpoint}`, {
+                headers: this.getAuthHeaders()
             })
+            return data
+        } catch (error) {
+            this.handleError(error)
+        }
+    }
 
-        return data
+    async post<T, D = unknown>(endpoint: string, body: D): Promise<T> {
+        try {
+            const isFormData = body instanceof FormData
+            const { data } = await axios.post<T>(
+                `${this.config.apiUrl}/${endpoint}`,
+                body,
+                {
+                    headers: this.getAuthHeaders(isFormData)
+                }
+            )
+            return data
+        } catch (error) {
+            this.handleError(error)
+        }
     }
 
-    async delete<T, D = any>(endpoint: string, body?: D): Promise<T> {
-        const { data } = await axios.delete<T>(
-            `${this.config.baseUrl}/${endpoint}`,
-            {
-                headers: this.getAuthHeaders(),
-                data: body
-            }
-        )
-        return data
+    async put<T, D = unknown>(endpoint: string, body: D): Promise<T> {
+        try {
+            const isFormData = body instanceof FormData
+            const { data } = await axios.put<T>(`${this.config.apiUrl}/${endpoint}`,
+                body,
+                {
+                    headers: this.getAuthHeaders(isFormData)
+                })
+            return data
+        } catch (error) {
+            this.handleError(error)
+        }
     }
 
-    async patch<T, D = any>(endpoint: string, body: D): Promise<T> {
-        const isFormData = body instanceof FormData
-        const { data } = await axios.patch<T>(
-            `${this.config.baseUrl}/${endpoint}`,
-            body,
-            {
-                headers: this.getAuthHeaders(isFormData)
-            }
-        )
-        return data
+    async delete<T, D = unknown>(endpoint: string, body?: D): Promise<T> {
+        try {
+            const { data } = await axios.delete<T>(
+                `${this.config.apiUrl}/${endpoint}`,
+                {
+                    headers: this.getAuthHeaders(),
+                    data: body
+                }
+            )
+            return data
+        } catch (error) {
+            this.handleError(error)
+        }
+    }
+
+    async patch<T, D = unknown>(endpoint: string, body: D): Promise<T> {
+        try {
+            const isFormData = body instanceof FormData
+            const { data } = await axios.patch<T>(
+                `${this.config.apiUrl}/${endpoint}`,
+                body,
+                {
+                    headers: this.getAuthHeaders(isFormData)
+                }
+            )
+            return data
+        } catch (error) {
+            this.handleError(error)
+        }
     }
 }

package/src/lib-internal/routes/UserRoutes.ts

@@ -5,5 +5,7 @@ export const UserRoutes = {
     updateUser: (username: string) => `${UserRoutes.baseUrl}${username}/`,
     deleteUser: (username: string) => `${UserRoutes.baseUrl}${username}/`,
     listUser: (filter: string) => `${UserRoutes.baseUrl}${filter}`,
-    getUserApps: (username: string) => `${UserRoutes.baseUrl}${username}/apps/`
+    getUserApps: (username: string) => `${UserRoutes.baseUrl}${username}/apps/`,
+    assignRoles: () => `api/assign/roles/`,
+    revokeRoles: () => `api/revoke/roles/`
 } as const

package/src/lib-internal/token/TokenClient.ts

@@ -115,7 +115,7 @@ export class TokenClient {
                 return null
             }
 
-            const tokens: any = {
+            const tokens: AuthTokens = {
                 accessToken,
                 refreshToken,
                 tokenType: tokenType || 'Bearer',