@taruvi/sdk 1.3.3 → 1.3.4

package/src/lib/auth/types.ts

@@ -0,0 +1,111 @@
+export interface UserCreateRequest {
+    // Required fields
+    username: string
+    email: string
+    first_name: string
+    last_name: string
+    password: string
+    confirm_password: string
+    // Optional fields
+    is_active?: boolean
+    is_staff?: boolean
+    attributes?: string
+}
+
+export interface UserCreateResponse {
+    id: number
+    uuid: string
+    username: string
+    email: string
+    first_name: string
+    last_name: string
+    is_active: boolean
+    is_staff: boolean
+    is_superuser: boolean
+    is_deleted: boolean
+    date_joined: string
+}
+
+export interface UserGroup {
+    id: number
+    name: string
+}
+
+export interface UserPermission {
+    id: number
+    name: string
+    codename: string
+    content_type: string // "app_label.model"
+}
+
+export interface UserRole {
+    name: string
+    slug: string
+    type: "app_role"
+    app_slug: string
+    source: "direct" | "site_role" | "inherited"
+}
+
+export interface UserDataResponse {
+    id: number
+    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 // ISO 8601 date-time string
+    last_login: string // ISO 8601 date-time string
+    groups: UserGroup[]
+    user_permissions: UserPermission[]
+    attributes: Record<string, unknown>
+    missing_attributes: string[]
+    roles: UserRole[]
+}
+
+export interface UserUpdateRequest {
+    username?: string
+    email?: string
+    first_name?: string
+    last_name?: string
+    is_active?: boolean
+    is_staff?: boolean
+}
+
+export interface UserUpdateResponse {
+    id: number
+    uuid: string
+    username: string
+    email: string
+    first_name: string
+    last_name: string
+    is_active: boolean
+    is_staff: boolean
+    is_superuser: boolean
+    is_deleted: boolean
+    date_joined: string
+}
+
+export interface UserList {
+    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
+}
+
+export type UserAppsResponse = UserApp[]

package/src/lib/database/DatabaseClient.ts

@@ -0,0 +1,148 @@
+import type { Client } from "../../client.js";
+import { DatabaseRoutes, type DatabaseRouteKey } from "../../lib-internal/routes/DatabaseRoutes.js";
+import { HttpMethod } from "../../lib-internal/http/types.js";
+import type { TaruviConfig, DatabaseFilters, TaruviResponse } from "../../types.js";
+import type { UrlParams, FilterOperator, SortOrder } from "./types.js";
+import { buildQueryString } from "../../utils/utils.js";
+
+// Used to access app data
+export class Database<T = Record<string, unknown>> {
+    private client: Client
+    private urlParams: UrlParams
+    private config: TaruviConfig
+    private operation: HttpMethod | undefined
+    private body: object | undefined
+    private queryParams: DatabaseFilters | undefined
+
+    constructor(client: Client, urlParams: UrlParams = {}, operation?: HttpMethod | undefined, body?: object | undefined, queryParams?: DatabaseFilters) {
+        this.client = client
+        this.urlParams = urlParams
+        this.operation = operation
+        this.body = body
+        this.config = this.client.getConfig()
+        this.queryParams = queryParams
+    }
+
+    from<U = Record<string, unknown>>(dataTables: string): Database<U> {
+        return new Database<U>(this.client, { ...this.urlParams, dataTables }, undefined, undefined)
+    }
+
+    filter(field: string, operator: FilterOperator, value: string | number | boolean | (string | number)[]): Database<T> {
+        const filterKey = operator === 'eq' ? field : `${field}__${operator}`
+        // For 'in' and 'nin' operators, join array values with comma
+        const filterValue = Array.isArray(value) ? value.join(',') : value
+        return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
+            ...this.queryParams,
+            [filterKey]: filterValue
+        })
+    }
+
+    sort(field: string, order: SortOrder = 'asc'): Database<T> {
+        const ordering = order === 'desc' ? `-${field}` : field
+        return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
+            ...this.queryParams,
+            ordering
+        })
+    }
+
+    pageSize(size: number): Database<T> {
+        return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
+            ...this.queryParams,
+            page_size: size
+        })
+    }
+
+    page(num: number): Database<T> {
+        return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
+            ...this.queryParams,
+            page: num
+        })
+    }
+
+    populate(populate: string[]): Database<T> {
+        return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
+            ...this.queryParams,
+            populate: populate.join(',')
+        })
+    }
+
+    get(recordId: string): Database<T> {
+        return new Database<T>(this.client, { ...this.urlParams, recordId }, HttpMethod.GET)
+    }
+
+    create(body: Partial<T> | Partial<T>[]): Database<T> {
+        return new Database<T>(this.client, { ...this.urlParams }, HttpMethod.POST, body as object)
+    }
+
+    update(body: Partial<T> | Partial<T>[]): Database<T> {
+        return new Database<T>(this.client, { ...this.urlParams }, HttpMethod.PATCH, body as object)
+    }
+
+    delete(recordId: string): Database<T> {
+        return new Database<T>(this.client, { ...this.urlParams, recordId }, HttpMethod.DELETE)
+    }
+
+    async first(): Promise<T | null> {
+        const response = await this.execute()
+        const data = response.data
+        if (Array.isArray(data)) {
+            return data[0] ?? null
+        }
+        return data ?? null
+    }
+
+    async count(): Promise<number> {
+        const response = await this.execute()
+        if (response.total !== undefined) {
+            return response.total
+        }
+        return Array.isArray(response.data) ? response.data.length : 0
+    }
+
+    private buildRoute(): string {
+        return (
+            DatabaseRoutes.baseUrl(this.config.appSlug) +
+            (Object.keys(this.urlParams) as DatabaseRouteKey[]).reduce((acc, key) => {
+                const value = this.urlParams[key]
+                const routeBuilder = DatabaseRoutes[key]
+
+                if (value && routeBuilder) {
+                    acc += routeBuilder(value)
+                }
+
+                return acc
+            }, "") +
+            "/" +
+            buildQueryString(this.queryParams)
+        )
+    }
+
+    async execute(): Promise<TaruviResponse<T | T[]>> {
+        if (!this.urlParams.dataTables) {
+            throw new Error('Table name is required. Call .from(tableName) first.')
+        }
+
+        // Build the API URL
+        const url = this.buildRoute()
+
+        const operation = this.operation || HttpMethod.GET
+
+        switch (operation) {
+            case HttpMethod.POST:
+                return await this.client.httpClient.post(url, this.body)
+
+            case HttpMethod.PATCH:
+                if (!this.urlParams.recordId) {
+                    throw new Error('PATCH operation requires a record ID.')
+                }
+                return await this.client.httpClient.patch(url, this.body)
+
+            case HttpMethod.DELETE:
+                return await this.client.httpClient.delete(url)
+
+            case HttpMethod.GET:
+            default:
+                return await this.client.httpClient.get(url)
+        }
+    }
+}

package/src/lib/database/types.ts

@@ -0,0 +1,46 @@
+import type { Client } from "../../client.js"
+import { HttpMethod } from "../../lib-internal/http/types.js"
+import type { TaruviResponse } from "../../types.js"
+
+export type DatabaseOperation = HttpMethod
+
+// Filter operators matching Python SDK
+export type FilterOperator =
+    | 'eq'           // Equal
+    | 'ne'           // Not equal
+    | 'gt'           // Greater than
+    | 'gte'          // Greater than or equal
+    | 'lt'           // Less than
+    | 'lte'          // Less than or equal
+    | 'in'           // In array
+    | 'nin'          // Not in array
+    | 'contains'     // String contains (case-sensitive)
+    | 'icontains'    // String contains (case-insensitive)
+    | 'startswith'   // String starts with (case-sensitive)
+    | 'istartswith'  // String starts with (case-insensitive)
+    | 'endswith'     // String ends with (case-sensitive)
+    | 'iendswith'    // String ends with (case-insensitive)
+    | 'isnull'       // Is null
+
+export type SortOrder = 'asc' | 'desc'
+
+// Internal types
+export interface UrlParams {
+    appSlug?: string
+    dataTables?: string
+    recordId?: string
+}
+
+export interface DatabaseClientInterface {
+    client: Client
+    urlParams?: UrlParams
+}
+
+// Request types
+export interface DatabaseRequest {
+    [key: string]: unknown
+}
+
+// Response types - uses standard wrapper
+export type DatabaseResponse<T = unknown> = TaruviResponse<T[]>
+export type DatabaseSingleResponse<T = unknown> = TaruviResponse<T>

package/src/lib/functions/FunctionsClient.ts

@@ -0,0 +1,27 @@
+import type { Client } from "../../client.js";
+import type { TaruviConfig } from "../../types.js";
+import type { FunctionRequest, FunctionResponse } from "./types.js";
+import { FunctionRoutes } from "../../lib-internal/routes/FunctionRoutes.js";
+
+export class Functions {
+    private client: Client
+    private config: TaruviConfig
+
+    constructor(client: Client) {
+        this.client = client
+        this.config = this.client.getConfig()
+    }
+
+    async execute<T = unknown>(functionSlug: string, options: FunctionRequest = {}): Promise<FunctionResponse<T>> {
+        const url = `${FunctionRoutes.baseUrl(this.config.appSlug, functionSlug)}/execute/`
+
+        const body = {
+            async: options.async ?? false,
+            params: {   
+                ...options.params
+            }
+        }
+
+        return await this.client.httpClient.post<FunctionResponse<T>>(url, body)
+    }
+}

package/src/lib/functions/types.ts

@@ -0,0 +1,25 @@
+export interface FunctionRequest {
+    async?: boolean
+    params?: Record<string, unknown>
+}
+
+export interface FunctionInvocation {
+    id: number
+    celery_task_id: string
+    function: number
+    function_name: string
+    function_slug: string
+    user_username: string
+    task_status: string
+    trigger_type: string
+    created_at: string
+    updated_at?: string
+}
+
+// Response type - matches backend AppDataResponse with invocation
+export interface FunctionResponse<T = unknown> {
+    status: "success" | "error"
+    message: string
+    data: T | null
+    invocation: FunctionInvocation
+}

package/src/lib/graphs/GraphClient.ts

@@ -0,0 +1,106 @@
+import type { Client } from "../../client.js"
+import type { TaruviConfig } from "../../types.js"
+import type { GraphInclude, GraphFormat, GraphQueryParams, GraphUrlParams, EdgeRequest, EdgeDeleteRequest } from "./types.js"
+import { GraphRoutes, GraphEdgeRoutes, type GraphRouteKey } from "../../lib-internal/routes/GraphRoutes.js"
+import { buildQueryString } from "../../utils/utils.js"
+import { HttpMethod } from "../../lib-internal/http/types.js"
+
+export class Graph<T = Record<string, unknown>> {
+    private client: Client
+    private config: TaruviConfig
+    private urlParams: GraphUrlParams
+    private queryParams: GraphQueryParams
+    private operation: HttpMethod | undefined
+    private body: object | undefined
+    private edgeRoute: string | undefined
+
+    constructor(client: Client, urlParams: GraphUrlParams = {}, queryParams: GraphQueryParams = {}, operation?: HttpMethod, body?: object, edgeRoute?: string) {
+        this.client = client
+        this.config = this.client.getConfig()
+        this.urlParams = urlParams
+        this.queryParams = queryParams
+        this.operation = operation
+        this.body = body
+        this.edgeRoute = edgeRoute
+    }
+
+    from<U = Record<string, unknown>>(dataTables: string): Graph<U> {
+        return new Graph<U>(this.client, { ...this.urlParams, dataTables }, { ...this.queryParams })
+    }
+
+    get(recordId: string): Graph<T> {
+        return new Graph<T>(this.client, { ...this.urlParams, recordId }, { ...this.queryParams })
+    }
+
+    include(direction: GraphInclude): Graph<T> {
+        return new Graph<T>(this.client, { ...this.urlParams }, { ...this.queryParams, include: direction })
+    }
+
+    depth(n: number): Graph<T> {
+        return new Graph<T>(this.client, { ...this.urlParams }, { ...this.queryParams, depth: n })
+    }
+
+    format(fmt: GraphFormat): Graph<T> {
+        return new Graph<T>(this.client, { ...this.urlParams }, { ...this.queryParams, format: fmt })
+    }
+
+    types(types: string[]): Graph<T> {
+        return new Graph<T>(this.client, { ...this.urlParams }, { ...this.queryParams, relationship_type: types })
+    }
+
+    list(): Graph<T> {
+        const route = GraphEdgeRoutes.baseUrl(this.config.appSlug) + GraphEdgeRoutes.edges(this.urlParams.dataTables!) + "/"
+        return new Graph<T>(this.client, { ...this.urlParams }, {}, HttpMethod.GET, undefined, route)
+    }
+
+    create(edges: EdgeRequest[]): Graph<T> {
+        const route = GraphEdgeRoutes.baseUrl(this.config.appSlug) + GraphEdgeRoutes.edges(this.urlParams.dataTables!) + "/"
+        return new Graph<T>(this.client, { ...this.urlParams }, {}, HttpMethod.POST, edges as unknown as object, route)
+    }
+
+    update(edgeId: string, edge: EdgeRequest): Graph<T> {
+        const route = GraphEdgeRoutes.baseUrl(this.config.appSlug) + GraphEdgeRoutes.edges(this.urlParams.dataTables!) + GraphEdgeRoutes.edgeId(edgeId) + "/"
+        return new Graph<T>(this.client, { ...this.urlParams }, {}, HttpMethod.PATCH, edge, route)
+    }
+
+    delete(edgeIds: number[]): Graph<T> {
+        const route = GraphEdgeRoutes.baseUrl(this.config.appSlug) + GraphEdgeRoutes.edges(this.urlParams.dataTables!) + "/"
+        const body: EdgeDeleteRequest = { edge_ids: edgeIds }
+        return new Graph<T>(this.client, { ...this.urlParams }, {}, HttpMethod.DELETE, body, route)
+    }
+
+    private buildRoute(): string {
+        if (this.edgeRoute) return this.edgeRoute
+
+        return (
+            GraphRoutes.baseUrl(this.config.appSlug) +
+            (Object.keys(this.urlParams) as GraphRouteKey[]).reduce((acc, key) => {
+                const value = this.urlParams[key]
+                const routeBuilder = GraphRoutes[key]
+                if (value && routeBuilder) {
+                    acc += routeBuilder(value)
+                }
+                return acc
+            }, "") +
+            "/" +
+            buildQueryString(this.queryParams as Record<string, unknown>)
+        )
+    }
+
+    async execute(): Promise<T | T[]> {
+        const url = this.buildRoute()
+        const operation = this.operation || HttpMethod.GET
+
+        switch (operation) {
+            case HttpMethod.POST:
+                return await this.client.httpClient.post(url, this.body)
+            case HttpMethod.PATCH:
+                return await this.client.httpClient.patch(url, this.body)
+            case HttpMethod.DELETE:
+                return await this.client.httpClient.delete(url, this.body)
+            case HttpMethod.GET:
+            default:
+                return await this.client.httpClient.get(url)
+        }
+    }
+}

package/src/lib/graphs/types.ts

@@ -0,0 +1,33 @@
+export type GraphInclude = 'descendants' | 'ancestors' | 'both'
+export type GraphFormat = 'tree' | 'graph'
+
+export interface GraphQueryParams {
+    include?: GraphInclude
+    depth?: number
+    format?: GraphFormat
+    relationship_type?: string[]
+}
+
+export interface GraphUrlParams {
+    dataTables?: string
+    recordId?: string
+}
+
+export interface EdgeRequest {
+    from: number | string
+    to: number | string
+    type: string
+    metadata?: Record<string, unknown>
+}
+
+export interface EdgeResponse {
+    id: number
+    from: number | string
+    to: number | string
+    type: string
+    metadata?: Record<string, unknown>
+}
+
+export interface EdgeDeleteRequest {
+    edge_ids: number[]
+}

package/src/lib/policy/PolicyClient.ts

@@ -0,0 +1,79 @@
+import type { Client } from "../../client.js"
+import { PolicyRoutes } from "../../lib-internal/routes/PolicyRoutes.js"
+import type { TaruviConfig } from "../../types.js"
+import type { Resources, Resource, Principal, PolicyCheckBatchResult, GetAllowedActionsOptions } from "./types.js"
+
+export class Policy {
+    private client: Client
+    private config: TaruviConfig
+    constructor(client: Client) {
+        this.client = client
+        this.config = this.client.getConfig()
+    }
+
+    async checkResource(resources: Resources): Promise<PolicyCheckBatchResult> {
+        const url = PolicyRoutes.baseUrl(this.config.appSlug) + PolicyRoutes.checkResource
+        const body = {
+            resources: resources.map(r => ({
+                resource: {
+                    kind: `${r.entityType}:${r.tableName}`,
+                    id: r.recordId,
+                    attr: r.attributes || {}
+                },
+                actions: r.actions
+            }))
+        }
+
+        return await this.client.httpClient.post<PolicyCheckBatchResult>(url, body)
+    }
+
+    /**
+     * Get list of allowed actions for a specific resource.
+     *
+     * @param resource - Resource with kind and id
+     * @param options - Optional actions list, principal override, and aux data
+     * @returns List of action names that are allowed
+     *
+     * @example
+     * ```typescript
+     * const allowed = await client.policy.getAllowedActions(
+     *     { kind: 'datatable:users', id: '123', attr: {} }
+     * )
+     * // Returns: ['read', 'write', 'update']  // 'delete' not allowed
+     * ```
+     */
+    async getAllowedActions(
+        resource: Resource,
+        options: GetAllowedActionsOptions = {}
+    ): Promise<string[]> {
+        const { actions = ['read', 'write', 'create', 'update', 'delete'], principal, auxData } = options
+
+        const url = PolicyRoutes.baseUrl(this.config.appSlug) + PolicyRoutes.checkResource
+        const body: Record<string, unknown> = {
+            resources: [{
+                resource: resource,
+                actions: actions
+            }]
+        }
+
+        if (principal) {
+            body.principal = principal
+        }
+        if (auxData) {
+            body.auxData = auxData
+        }
+
+        const result = await this.client.httpClient.post<PolicyCheckBatchResult>(url, body)
+
+        // Extract allowed actions
+        if (result.results && result.results.length > 0) {
+            const firstResult = result.results[0]
+            const actionResults = firstResult?.actions || {}
+            return Object.entries(actionResults)
+                .filter(([_, effect]) => effect === 'EFFECT_ALLOW')
+                .map(([action, _]) => action)
+        }
+
+        return []
+    }
+}

package/src/lib/policy/types.ts

@@ -0,0 +1,40 @@
+import type { TaruviResponse } from "../../types.js"
+
+export interface Principal {
+    id: string
+    roles: string[]
+    attr: Record<string, unknown>
+}
+
+export type Resource = {
+    kind: string
+    id: string
+    attr: Record<string, unknown>
+}
+
+export type Resources = {
+    entityType: string
+    tableName: string
+    recordId: string
+    attributes: Record<string, unknown>
+    actions: string[]
+}[]
+
+export interface PolicyCheckResult {
+    resource: Resource
+    actions: Record<string, string>
+}
+
+export interface PolicyCheckBatchResult {
+    requestId: string
+    results: PolicyCheckResult[]
+}
+
+export type GetAllowedActionsOptions = {
+    actions?: string[]
+    principal?: Principal
+    auxData?: Record<string, unknown>
+}
+
+// Response types - uses standard wrapper
+export type ResourceCheckResponse = TaruviResponse<PolicyCheckBatchResult>

package/src/lib/secrets/SecretsClient.ts

@@ -0,0 +1,75 @@
+import type { Client } from "../../client.js";
+import type { SecretsUrlParams, GetSecretOptions, GetSecretsOptions, SecretsBatchResponse, SecretsBatchMetadataResponse } from "./types.js";
+import { HttpMethod } from "../../lib-internal/http/types.js";
+import { SecretsRoutes } from "../../lib-internal/routes/SecretsRoutes.js";
+import { buildQueryString } from "../../utils/utils.js";
+
+export class Secrets {
+    private client: Client
+    private urlParams: SecretsUrlParams
+    private body: object | undefined
+    private method: HttpMethod
+
+    constructor(client: Client, urlParams: SecretsUrlParams = {}, body?: object, method: HttpMethod = HttpMethod.GET) {
+        this.client = client
+        this.urlParams = urlParams
+        this.body = body
+        this.method = method
+    }
+
+    /**
+     * Get a specific secret by key.
+     *
+     * @param key - Secret key/name
+     * @param options - Optional app context for 2-tier inheritance and tag validation
+     * @returns Secrets instance for chaining with execute()
+     */
+    get(key: string, options: GetSecretOptions = {}): Secrets {
+        if (!key || typeof key !== 'string') {
+            throw new Error('Secret key is required and must be a string.')
+        }
+
+        const path = SecretsRoutes.get(key)
+        const queryParams: Record<string, unknown> = {}
+
+        if (options.app) queryParams.app = options.app
+        if (options.tags && options.tags.length > 0) queryParams.tags = options.tags.join(',')
+
+        return new Secrets(this.client, { ...this.urlParams, path, queryParams }, undefined, HttpMethod.GET)
+    }
+
+    /**
+     * List multiple secrets by keys using backend batch endpoint.
+     * More efficient than making multiple individual requests - uses a single API call.
+     *
+     * @param keys - List of secret keys to retrieve
+     * @param options - Optional app context and metadata flag
+     * @returns Promise with dict mapping keys to values (or full objects if includeMetadata=true)
+     */
+    async list(keys: string[], options: GetSecretsOptions = {}): Promise<SecretsBatchResponse | SecretsBatchMetadataResponse> {
+        const queryParams: Record<string, unknown> = {
+            keys: keys.join(',')
+        }
+
+        if (options.app) queryParams.app = options.app
+        if (options.includeMetadata) queryParams.include_metadata = options.includeMetadata
+
+        const queryString = buildQueryString(queryParams)
+        const url = SecretsRoutes.baseUrl + queryString
+
+        return await this.client.httpClient.get<SecretsBatchResponse | SecretsBatchMetadataResponse>(url)
+    }
+
+    async execute<T = unknown>(): Promise<T> {
+        const queryString = buildQueryString(this.urlParams.queryParams)
+        const url = (this.urlParams.path ?? SecretsRoutes.baseUrl) + queryString
+
+        switch (this.method) {
+            case HttpMethod.PUT:
+                return await this.client.httpClient.put<T>(url, this.body)
+            case HttpMethod.GET:
+            default:
+                return await this.client.httpClient.get<T>(url)
+        }
+    }
+}