@taruvi/sdk 1.5.0 → 1.5.1

package/src/lib/storage/StorageClient.ts

@@ -1,131 +0,0 @@
-import type { Client } from "../../client.js";
-import type {
-    BucketUrlParams,
-    StorageResponse,
-    StorageListResponse,
-    StorageUploadBatchResponse,
-    StorageDeleteBatchResponse
-} from "./types.js";
-import { StorageRoutes, type StorageRouteKey } from "../../lib-internal/routes/StorageRoutes.js";
-import type { TaruviConfig, StorageFilters } from "../../types.js";
-import { HttpMethod } from "../../lib-internal/http/types.js";
-import { buildQueryString } from "../../utils/utils.js";
-
-export class Storage {
-
-    private client: Client
-    private config: TaruviConfig
-    private urlParams: BucketUrlParams
-    private operation: HttpMethod | undefined
-    private body: object | undefined
-    private filters: StorageFilters | undefined
-    private queryParams: Record<string, string> | undefined
-
-
-    constructor(client: Client, urlParams: BucketUrlParams = {} as BucketUrlParams, operation?: HttpMethod | undefined, body?: object, filters?: StorageFilters, queryParams?: Record<string, string>) {
-        this.client = client
-        this.urlParams = urlParams
-        this.operation = operation
-        this.config = this.client.getConfig()
-        this.body = body
-        this.filters = filters
-        this.queryParams = queryParams
-    }
-
-
-    from(bucket: string): Storage {
-        return new Storage(this.client, { ...this.urlParams, bucket }, undefined, undefined)
-    }
-
-    filter(filters: StorageFilters) {
-        return new Storage(this.client, { ...this.urlParams }, undefined, undefined, filters)
-    }
-
-    delete(paths: string[]): Storage {
-        return new Storage(this.client, {
-            ...this.urlParams, delete: "delete"
-        }, HttpMethod.POST, { paths })
-    }
-
-    update(path: string, body: object): Storage {
-        return new Storage(this.client, { ...this.urlParams, path }, HttpMethod.PUT, body)
-    }
-
-    download(path: string): Storage {
-        return new Storage(this.client, { ...this.urlParams, path }, HttpMethod.GET)
-    }
-
-    metadata(path: string): Storage {
-        return new Storage(this.client, { ...this.urlParams, path }, HttpMethod.GET, undefined, undefined, { metadata: 'true' })
-    }
-
-    upload(filesData: { files: File[], metadatas: object[], paths: string[] }): Storage {
-        const formData = new FormData()
-        filesData.files.forEach(f => formData.append('files', f))
-        formData.append('paths', JSON.stringify(filesData.paths))
-        formData.append('metadata', JSON.stringify(filesData.metadatas))
-        return new Storage(this.client, {
-            ...this.urlParams, upload: "upload"
-        }, HttpMethod.POST, formData)
-    }
-
-    private buildRoute(): string {
-        if (!this.urlParams.bucket) {
-            throw new Error('Bucket is required. Call .from(bucketName) first.')
-        }
-
-        return (
-            StorageRoutes.baseUrl(this.config.appSlug, this.urlParams.bucket) +
-            (Object.keys(this.urlParams) as StorageRouteKey[]).reduce((acc, key) => {
-                const value = this.urlParams[key as keyof BucketUrlParams]
-
-                if (!value) return acc
-
-                if (key === 'path' && typeof value === 'string') {
-                    acc += StorageRoutes.path(value)
-                }
-
-                if ((key === 'upload' || key === 'delete') && typeof StorageRoutes[key] === 'function') {
-                    acc += (StorageRoutes[key] as () => string)()
-                }
-
-                return acc
-            }, '') +
-            '/' +
-            buildQueryString({ ...this.filters as Record<string, unknown>, ...this.queryParams })
-        )
-    }
-
-
-
-    /**
-     * Execute the storage operation.
-     * Returns different types based on the operation:
-     * - List files: StorageListResponse[]
-     * - Download: Blob
-     * - Upload: StorageUploadBatchResponse
-     * - Delete: StorageDeleteBatchResponse
-     * - Update: StorageResponse
-     */
-    async execute<T = StorageListResponse[] | StorageResponse | StorageUploadBatchResponse | StorageDeleteBatchResponse | Blob>(): Promise<T> {
-        const url = this.buildRoute()
-        const operation = this.operation || HttpMethod.GET
-
-        switch (operation) {
-            case HttpMethod.POST:
-                return await this.client.httpClient.post<T>(url, this.body)
-
-            case HttpMethod.PUT:
-                return await this.client.httpClient.put<T>(url, this.body)
-
-            case HttpMethod.DELETE:
-                return await this.client.httpClient.delete<T>(url)
-
-            case HttpMethod.GET:
-            default: {
-                const isDownload = this.urlParams.path && !this.queryParams?.metadata
-                return await this.client.httpClient.get<T>(url, isDownload ? { responseType: 'blob' } : undefined)
-            }
-        }
-    }
-}

package/src/lib/storage/types.ts

@@ -1,86 +0,0 @@
-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?: string
-    modified_by?: string
-}
-
-// 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

@@ -1,63 +0,0 @@
-import type { Client } from "../../client.js";
-import type { UserCreateRequest, UserResponse, UserListResponse, UserListFilters, UserUpdateRequest, UserAppsResponse, AssignRolesRequest, RevokeRolesRequest, RolesResponse, UserPreferencesResponse, UserPreferencesUpdate } 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
-        )
-    }
-
-    async getPreferences(): Promise<UserPreferencesResponse> {
-        return await this.client.httpClient.get<UserPreferencesResponse>(UserRoutes.preferences())
-    }
-
-    async updatePreferences(body: UserPreferencesUpdate): Promise<UserPreferencesResponse> {
-        return await this.client.httpClient.put<UserPreferencesResponse>(UserRoutes.preferences(), body)
-    }
-}

package/src/lib/users/types.ts

@@ -1,123 +0,0 @@
-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: 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[]
-    icon_url?: string
-}
-
-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
-    roles?: string
-    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 UserPreferences {
-    date_format: string
-    time_format: string
-    timezone: string
-    theme: string
-    widget_config: Record<string, unknown>
-}
-
-export interface UserPreferencesUpdate {
-    date_format?: string
-    time_format?: string
-    timezone?: string
-    theme?: string
-    widget_config?: Record<string, unknown>
-}
-
-export type UserPreferencesResponse = TaruviResponse<UserPreferences>
-
-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,114 +0,0 @@
-import { ErrorCode, type ErrorResponseBody } from './types.js'
-
-/**
- * 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
-    }
-}
-
-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 RateLimitError extends TaruviError {
-    public readonly retryAfter: number | undefined
-
-    constructor(message = 'Rate limit exceeded', retryAfter?: number) {
-        super(message, 429, ErrorCode.RATE_LIMITED)
-        this.name = 'RateLimitError'
-        this.retryAfter = retryAfter
-    }
-}
-
-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 429:
-            return new RateLimitError(message)
-        case 504:
-            return new TimeoutError(message)
-        default:
-            return new TaruviError(message, statusCode, code, detail, errors, data)
-    }
-}

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

@@ -1,3 +0,0 @@
-export { TaruviError, ValidationError, AuthError, ForbiddenError, NotFoundError, ConflictError, TimeoutError, NetworkError, RateLimitError, createErrorFromResponse } from './ErrorClient.js'
-export { ErrorCode } from './types.js'
-export type { ErrorResponseBody } from './types.js'

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

@@ -1,29 +0,0 @@
-/**
- * Error codes matching the backend's ErrorCode enum.
- * Maps 1:1 with base.responses.error_codes.ErrorCode in Python.
- */
-export enum ErrorCode {
-    BAD_REQUEST = 'BAD_REQUEST',
-    VALIDATION_ERROR = 'VALIDATION_ERROR',
-    UNAUTHORIZED = 'UNAUTHORIZED',
-    FORBIDDEN = 'FORBIDDEN',
-    NOT_FOUND = 'NOT_FOUND',
-    CONFLICT = 'CONFLICT',
-    INTERNAL_ERROR = 'INTERNAL_ERROR',
-    RATE_LIMITED = 'RATE_LIMITED',
-    GATEWAY_TIMEOUT = 'GATEWAY_TIMEOUT',
-    NETWORK_ERROR = 'NETWORK_ERROR'
-}
-
-/**
- * Backend error response shape.
- * Matches AppException.to_dict() output.
- */
-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,117 +0,0 @@
-import type { TaruviConfig } from "../../types.js";
-import type { TokenClient } from "../token/TokenClient.js";
-import axios, { AxiosError, type AxiosInstance, type InternalAxiosRequestConfig } 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.
- * Sends session token via X-Session-Token header.
- * Clears tokens on 401 auth failures.
- *
- * @internal
- */
-export class HttpClient {
-    private config: TaruviConfig
-    private tokenClient: TokenClient
-    private axiosInstance: AxiosInstance
-
-    constructor(config: TaruviConfig, tokenClient: TokenClient) {
-        this.config = config
-        this.tokenClient = tokenClient
-        this.axiosInstance = axios.create({ baseURL: config.apiUrl, withCredentials: true })
-        this.setupInterceptors()
-    }
-
-    private setupInterceptors(): void {
-        // Request interceptor: attach session token
-        this.axiosInstance.interceptors.request.use((config: InternalAxiosRequestConfig) => {
-            const isFormData = config.data instanceof FormData
-            if (!isFormData) {
-                config.headers['Content-Type'] = 'application/json'
-            }
-            const sessionToken = this.tokenClient.getSessionToken()
-            if (sessionToken) {
-                config.headers['X-Session-Token'] = sessionToken
-            }
-            return config
-        })
-
-        // Response interceptor: clear tokens on authentication failure
-        // Only 401 (Unauthorized) means the session is invalid
-        // 403 (Forbidden) means authenticated but lacking permission — don't clear tokens
-        this.axiosInstance.interceptors.response.use(
-            (response) => response,
-            (error: AxiosError) => {
-                const status = error.response?.status
-                if (status === 401) {
-                    this.tokenClient.clearTokens()
-                }
-                return Promise.reject(error)
-            }
-        )
-    }
-
-    private handleError(error: unknown): never {
-        if (error instanceof TaruviError) {
-            throw error
-        }
-
-        if (error instanceof AxiosError) {
-            if (error.response) {
-                const body = error.response.data as ErrorResponseBody | undefined
-                throw createErrorFromResponse(error.response.status, body)
-            }
-            throw new NetworkError(error.message)
-        }
-
-        throw error
-    }
-
-    async get<T>(endpoint: string, options?: { responseType?: 'json' | 'blob' }): Promise<T> {
-        try {
-            const { data } = await this.axiosInstance.get<T>(`/${endpoint}`, {
-                ...(options?.responseType && { responseType: options.responseType }),
-            })
-            return data as T
-        } catch (error) {
-            this.handleError(error)
-        }
-    }
-
-    async post<T, D = unknown>(endpoint: string, body: D): Promise<T> {
-        try {
-            const { data } = await this.axiosInstance.post<T>(`/${endpoint}`, body)
-            return data
-        } catch (error) {
-            this.handleError(error)
-        }
-    }
-
-    async put<T, D = unknown>(endpoint: string, body: D): Promise<T> {
-        try {
-            const { data } = await this.axiosInstance.put<T>(`/${endpoint}`, body)
-            return data
-        } catch (error) {
-            this.handleError(error)
-        }
-    }
-
-    async delete<T, D = unknown>(endpoint: string, body?: D): Promise<T> {
-        try {
-            const { data } = await this.axiosInstance.delete<T>(`/${endpoint}`, { data: body })
-            return data
-        } catch (error) {
-            this.handleError(error)
-        }
-    }
-
-    async patch<T, D = unknown>(endpoint: string, body: D): Promise<T> {
-        try {
-            const { data } = await this.axiosInstance.patch<T>(`/${endpoint}`, body)
-            return data
-        } catch (error) {
-            this.handleError(error)
-        }
-    }
-}

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

@@ -1,3 +0,0 @@
-export const AnalyticsRoutes = {
-    baseUrl: (appSlug: string, querySlug: string) => `api/apps/${appSlug}/analytics/queries/${querySlug}/execute/`
-}

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

@@ -1,9 +0,0 @@
-export const AppRoutes = {
-    baseUrl: (appSlug: string) => `api/apps/${appSlug}`,
-    roles: (): string => `/roles`,
-    settings: (): string => "/settings/"
-}
-
-type AllRouteKeys = keyof typeof AppRoutes
-export type AppRouteKey = Exclude<AllRouteKeys, 'baseUrl'>
-export type AppUrlParams = Partial<Record<AppRouteKey, string>>

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

@@ -1,10 +0,0 @@
-export const DatabaseRoutes = {
-    baseUrl: (appSlug: string) => `api/apps/${appSlug}`,
-    dataTables: (tableName: string): string => `/datatables/${tableName}/data`,
-    recordId: (recordId: string): string => `/${recordId}`,
-    upsert: (): string => `/upsert`
-}
-
-type AllRouteKeys = keyof typeof DatabaseRoutes
-export type DatabaseRouteKey = Exclude<AllRouteKeys, 'baseUrl'>
-export type DatabaseUrlParams = Partial<Record<DatabaseRouteKey, string>>