@tenxyte/core 0.1.5 → 0.9.0

package/src/modules/ai.ts

@@ -0,0 +1,178 @@
+import { TenxyteHttpClient } from '../http/client';
+import { AgentTokenSummary, AgentPendingAction } from '../types';
+
+export class AiModule {
+    private agentToken: string | null = null;
+    private traceId: string | null = null;
+
+    constructor(private client: TenxyteHttpClient) {
+        // Register an interceptor to auto-inject AgentBearer and Trace ID
+        this.client.addRequestInterceptor((config) => {
+            const headers: Record<string, string> = { ...config.headers };
+
+            if (this.agentToken) {
+                // Determine if we should replace the standard Authorization
+                // By Tenxyte specification, AgentToken uses "AgentBearer"
+                headers['Authorization'] = `AgentBearer ${this.agentToken}`;
+            }
+
+            if (this.traceId) {
+                headers['X-Prompt-Trace-ID'] = this.traceId;
+            }
+
+            return { ...config, headers };
+        });
+
+        // Intercept 202 Accepted and specific 403 errors (Circuit Breaker)
+        // Usually, these should be emitted via the main TenxyteClient EventEmitter.
+        // For now, we add a response interceptor to handle the HTTP side.
+        this.client.addResponseInterceptor(async (response, request) => {
+            // Note: Since response streams can only be read once, full integration
+            // with EventEmitter for deep inspection (like 202s body) requires cloning.
+            if (response.status === 202) {
+                // HTTP 202 Accepted indicates HITL awaiting confirmation
+                const cloned = response.clone();
+                try {
+                    const data = await cloned.json();
+                    // Assuming TenxyteClient will fire 'agent:awaiting_approval' based on this later
+                    console.debug('[Tenxyte AI] Received 202 Awaiting Approval:', data);
+                } catch {
+                    // Ignore parsing errors
+                }
+            } else if (response.status === 403) {
+                const cloned = response.clone();
+                try {
+                    const data = await cloned.json();
+                    if (data.code === 'BUDGET_EXCEEDED') {
+                        console.warn('[Tenxyte AI] Network responded with Budget Exceeded for Agent.');
+                    } else if (data.status === 'suspended') {
+                        console.warn('[Tenxyte AI] Circuit breaker open for Agent.');
+                    }
+                } catch {
+                    // Ignore parsing errors
+                }
+            }
+            return response;
+        });
+    }
+
+    // ─── AgentToken Lifecycle ───
+
+    /**
+     * Create an AgentToken granting specific deterministic limits to an AI Agent.
+     */
+    async createAgentToken(data: {
+        agent_id: string;
+        permissions?: string[];
+        expires_in?: number;
+        organization?: string;
+        budget_limit_usd?: number;
+        circuit_breaker?: {
+            max_requests?: number;
+            window_seconds?: number;
+        };
+        dead_mans_switch?: {
+            heartbeat_required_every?: number;
+        };
+    }): Promise<{
+        id: number;
+        token: string;
+        agent_id: string;
+        status: string;
+        expires_at: string;
+    }> {
+        return this.client.post('/api/v1/auth/ai/tokens/', data);
+    }
+
+    /**
+     * Set the SDK to operate on behalf of an Agent using the generated Agent Token payload.
+     * Overrides standard `Authorization` headers with `AgentBearer`.
+     */
+    setAgentToken(token: string): void {
+        this.agentToken = token;
+    }
+
+    /** Disables the active Agent override and reverts to standard User session requests. */
+    clearAgentToken(): void {
+        this.agentToken = null;
+    }
+
+    /** Check if the SDK is currently mocking requests as an AI Agent. */
+    isAgentMode(): boolean {
+        return this.agentToken !== null;
+    }
+
+    /** List previously provisioned active Agent tokens. */
+    async listAgentTokens(): Promise<AgentTokenSummary[]> {
+        return this.client.get('/api/v1/auth/ai/tokens/');
+    }
+
+    /** Fetch the status and configuration of a specific AgentToken. */
+    async getAgentToken(tokenId: number): Promise<AgentTokenSummary> {
+        return this.client.get(`/api/v1/auth/ai/tokens/${tokenId}/`);
+    }
+
+    /** Irreversibly revoke a targeted AgentToken from acting upon the Tenant. */
+    async revokeAgentToken(tokenId: number): Promise<{ status: 'revoked' }> {
+        return this.client.post(`/api/v1/auth/ai/tokens/${tokenId}/revoke/`);
+    }
+
+    /** Temporarily freeze an AgentToken by forcibly closing its Circuit Breaker. */
+    async suspendAgentToken(tokenId: number): Promise<{ status: 'suspended' }> {
+        return this.client.post(`/api/v1/auth/ai/tokens/${tokenId}/suspend/`);
+    }
+
+    /** Emergency kill-switch to wipe all operational Agent Tokens. */
+    async revokeAllAgentTokens(): Promise<{ status: 'revoked'; count: number }> {
+        return this.client.post('/api/v1/auth/ai/tokens/revoke-all/');
+    }
+
+    // ─── Circuit Breaker ───
+
+    /** Satisfy an Agent's Dead-Man's switch heartbeat requirement to prevent suspension. */
+    async sendHeartbeat(tokenId: number): Promise<{ status: 'ok' }> {
+        return this.client.post(`/api/v1/auth/ai/tokens/${tokenId}/heartbeat/`);
+    }
+
+    // ─── Human in the Loop (HITL) ───
+
+    /** List intercepted HTTP 202 actions waiting for Human interaction / approval. */
+    async listPendingActions(): Promise<AgentPendingAction[]> {
+        return this.client.get('/api/v1/auth/ai/pending-actions/');
+    }
+
+    /** Complete a pending HITL authorization to finally flush the Agent action to backend systems. */
+    async confirmPendingAction(confirmationToken: string): Promise<{ status: 'confirmed' }> {
+        return this.client.post('/api/v1/auth/ai/pending-actions/confirm/', { token: confirmationToken });
+    }
+
+    /** Block an Agent action permanently. */
+    async denyPendingAction(confirmationToken: string): Promise<{ status: 'denied' }> {
+        return this.client.post('/api/v1/auth/ai/pending-actions/deny/', { token: confirmationToken });
+    }
+
+    // ─── Traceability and Budget ───
+
+    /** Start piping the `X-Prompt-Trace-ID` custom header outwards for tracing logs against LLM inputs. */
+    setTraceId(traceId: string): void {
+        this.traceId = traceId;
+    }
+
+    /** Disable trace forwarding context. */
+    clearTraceId(): void {
+        this.traceId = null;
+    }
+
+    /** 
+     * Report consumption costs associated with a backend invocation back to Tenxyte for strict circuit budgeting.
+     * @param tokenId - AgentToken evaluating ID.
+     * @param usage - Sunk token costs or explicit USD derivations.
+     */
+    async reportUsage(tokenId: number, usage: {
+        cost_usd: number;
+        prompt_tokens: number;
+        completion_tokens: number;
+    }): Promise<{ status: 'ok' } | { error: 'Budget exceeded'; status: 'suspended' }> {
+        return this.client.post(`/api/v1/auth/ai/tokens/${tokenId}/report-usage/`, usage);
+    }
+}

package/src/modules/auth.ts

@@ -1,95 +1,116 @@
-import { TenxyteHttpClient } from '../http/client';
-import { TokenPair, GeneratedSchema } from '../types';
-
-export interface LoginEmailOptions {
-    totp_code?: string;
-}
-
-export interface LoginPhoneOptions {
-    totp_code?: string;
-}
-
-export type RegisterRequest = any;
-
-export interface MagicLinkRequest {
-    email: string;
-}
-
-export interface SocialLoginRequest {
-    access_token?: string;
-    authorization_code?: string;
-    id_token?: string;
-}
-
-export class AuthModule {
-    constructor(private client: TenxyteHttpClient) { }
-
-    /**
-     * Authenticate user with email and password
-     */
-    async loginWithEmail(
-        data: GeneratedSchema['LoginEmail'],
-    ): Promise<TokenPair> {
-        return this.client.post<TokenPair>('/api/v1/auth/login/email/', data);
-    }
-
-    /**
-     * Authenticate user with international phone number and password
-     */
-    async loginWithPhone(
-        data: GeneratedSchema['LoginPhone'],
-    ): Promise<TokenPair> {
-        return this.client.post<TokenPair>('/api/v1/auth/login/phone/', data);
-    }
-
-    /**
-     * Register a new user
-     */
-    async register(data: RegisterRequest): Promise<any> {
-        return this.client.post<any>('/api/v1/auth/register/', data);
-    }
-
-    /**
-     * Logout from the current session
-     */
-    async logout(refreshToken: string): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/logout/', { refresh_token: refreshToken });
-    }
-
-    /**
-     * Logout from all sessions (revokes all refresh tokens)
-     */
-    async logoutAll(): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/logout/all/');
-    }
-
-    /**
-     * Request a magic link for sign-in
-     */
-    async requestMagicLink(data: MagicLinkRequest): Promise<void> {
-        return this.client.post<void>('/api/v1/auth/magic-link/request/', data);
-    }
-
-    /**
-     * Verify a magic link token
-     */
-    async verifyMagicLink(token: string): Promise<TokenPair> {
-        return this.client.get<TokenPair>(`/api/v1/auth/magic-link/verify/`, { params: { token } });
-    }
-
-    /**
-     * Perform OAuth2 Social Authentication (e.g. Google, GitHub)
-     */
-    async loginWithSocial(provider: 'google' | 'github' | 'microsoft' | 'facebook', data: SocialLoginRequest): Promise<TokenPair> {
-        return this.client.post<TokenPair>(`/api/v1/auth/social/${provider}/`, data);
-    }
-
-    /**
-     * Handle Social Auth Callback (authorization code flow)
-     */
-    async handleSocialCallback(provider: 'google' | 'github' | 'microsoft' | 'facebook', code: string, redirectUri: string): Promise<TokenPair> {
-        return this.client.get<TokenPair>(`/api/v1/auth/social/${provider}/callback/`, {
-            params: { code, redirect_uri: redirectUri },
-        });
-    }
-}
+import { TenxyteHttpClient } from '../http/client';
+import { TokenPair, GeneratedSchema } from '../types';
+
+export interface LoginEmailOptions {
+    totp_code?: string;
+}
+
+export interface LoginPhoneOptions {
+    totp_code?: string;
+}
+
+export type RegisterRequest = any;
+
+export interface MagicLinkRequest {
+    email: string;
+}
+
+export interface SocialLoginRequest {
+    access_token?: string;
+    authorization_code?: string;
+    id_token?: string;
+}
+
+export class AuthModule {
+    constructor(private client: TenxyteHttpClient) { }
+
+    /**
+     * Authenticate a user with their email and password.
+     * @param data - The login credentials and optional TOTP code if 2FA is required.
+     * @returns A pair of Access and Refresh tokens upon successful authentication.
+     * @throws {TenxyteError} If credentials are invalid, or if `2FA_REQUIRED` without a valid `totp_code`.
+     */
+    async loginWithEmail(
+        data: GeneratedSchema['LoginEmail'],
+    ): Promise<TokenPair> {
+        return this.client.post<TokenPair>('/api/v1/auth/login/email/', data);
+    }
+
+    /**
+     * Authenticate a user with an international phone number and password.
+     * @param data - The login credentials and optional TOTP code if 2FA is required.
+     * @returns A pair of Access and Refresh tokens.
+     */
+    async loginWithPhone(
+        data: GeneratedSchema['LoginPhone'],
+    ): Promise<TokenPair> {
+        return this.client.post<TokenPair>('/api/v1/auth/login/phone/', data);
+    }
+
+    /**
+     * Registers a new user account.
+     * @param data - The registration details (email, password, etc.).
+     * @returns The registered user data or a confirmation message.
+     */
+    async register(data: RegisterRequest): Promise<any> {
+        return this.client.post<any>('/api/v1/auth/register/', data);
+    }
+
+    /**
+     * Logout from the current session.
+     * Informs the backend to immediately revoke the specified refresh token.
+     * @param refreshToken - The refresh token to revoke.
+     */
+    async logout(refreshToken: string): Promise<void> {
+        return this.client.post<void>('/api/v1/auth/logout/', { refresh_token: refreshToken });
+    }
+
+    /**
+     * Logout from all sessions across all devices.
+     * Revokes all refresh tokens currently assigned to the user.
+     */
+    async logoutAll(): Promise<void> {
+        return this.client.post<void>('/api/v1/auth/logout/all/');
+    }
+
+    /**
+     * Request a Magic Link for passwordless sign-in.
+     * @param data - The email to send the logic link to.
+     */
+    async requestMagicLink(data: MagicLinkRequest): Promise<void> {
+        return this.client.post<void>('/api/v1/auth/magic-link/request/', data);
+    }
+
+    /**
+     * Verifies a magic link token extracted from the URL.
+     * @param token - The cryptographic token received via email.
+     * @returns A session token pair if the token is valid and unexpired.
+     */
+    async verifyMagicLink(token: string): Promise<TokenPair> {
+        return this.client.get<TokenPair>(`/api/v1/auth/magic-link/verify/`, { params: { token } });
+    }
+
+    /**
+     * Submits OAuth2 Social Authentication payloads to the backend.
+     * Can be used with native mobile SDK tokens (like Apple Sign-In JWTs).
+     * @param provider - The OAuth provider ('google', 'github', etc.)
+     * @param data - The OAuth tokens (access_token, id_token, etc.)
+     * @returns An active session token pair.
+     */
+    async loginWithSocial(provider: 'google' | 'github' | 'microsoft' | 'facebook', data: SocialLoginRequest): Promise<TokenPair> {
+        return this.client.post<TokenPair>(`/api/v1/auth/social/${provider}/`, data);
+    }
+
+    /**
+     * Handle Social Auth Callbacks (Authorization Code flow).
+     * @param provider - The OAuth provider ('google', 'github', etc.)
+     * @param code - The authorization code retrieved from the query string parameters.
+     * @param redirectUri - The original redirect URI that was requested.
+     * @returns An active session token pair after successful code exchange.
+     */
+    async handleSocialCallback(provider: 'google' | 'github' | 'microsoft' | 'facebook', code: string, redirectUri: string): Promise<TokenPair> {
+        return this.client.get<TokenPair>(`/api/v1/auth/social/${provider}/callback/`, {
+            params: { code, redirect_uri: redirectUri },
+        });
+    }
+}

package/src/modules/b2b.ts

@@ -0,0 +1,177 @@
+import { TenxyteHttpClient } from '../http/client';
+import { Organization, PaginatedResponse } from '../types';
+
+export interface OrgMembership {
+    id: number;
+    user_id: number;
+    email: string;
+    first_name: string;
+    last_name: string;
+    role: { code: string; name: string };
+    joined_at: string;
+}
+
+export interface OrgTreeNode {
+    id: number;
+    name: string;
+    slug: string;
+    children: OrgTreeNode[];
+}
+
+export class B2bModule {
+    private currentOrgSlug: string | null = null;
+
+    constructor(private client: TenxyteHttpClient) {
+        // Register an interceptor to auto-inject the X-Org-Slug header
+        this.client.addRequestInterceptor((config) => {
+            if (this.currentOrgSlug) {
+                config.headers = {
+                    ...config.headers,
+                    'X-Org-Slug': this.currentOrgSlug,
+                };
+            }
+            return config;
+        });
+    }
+
+    // ─── Context Management ───
+
+    /**
+     * Set the active Organization context.
+     * Subsequent API requests will automatically include the `X-Org-Slug` header.
+     * @param slug - The unique string identifier of the organization.
+     */
+    switchOrganization(slug: string): void {
+        this.currentOrgSlug = slug;
+    }
+
+    /**
+     * Clear the active Organization context, dropping the `X-Org-Slug` header for standard User operations.
+     */
+    clearOrganization(): void {
+        this.currentOrgSlug = null;
+    }
+
+    /** Get the currently active Organization slug context if set. */
+    getCurrentOrganizationSlug(): string | null {
+        return this.currentOrgSlug;
+    }
+
+    // ─── Organizations CRUD ───
+
+    /** Create a new top-level or child Organization in the backend. */
+    async createOrganization(data: {
+        name: string;
+        slug?: string;
+        description?: string;
+        parent_id?: number;
+        metadata?: Record<string, unknown>;
+        max_members?: number;
+    }): Promise<Organization> {
+        return this.client.post('/api/v1/auth/organizations/', data);
+    }
+
+    /** List organizations the currently authenticated user belongs to. */
+    async listMyOrganizations(params?: {
+        search?: string;
+        is_active?: boolean;
+        parent?: string;
+        ordering?: string;
+        page?: number;
+        page_size?: number;
+    }): Promise<PaginatedResponse<Organization>> {
+        return this.client.get('/api/v1/auth/organizations/', { params });
+    }
+
+    /** Retrieve details about a specific organization by slug. */
+    async getOrganization(slug: string): Promise<Organization> {
+        return this.client.get(`/api/v1/auth/organizations/${slug}/`);
+    }
+
+    /** Update configuration and metadata of an Organization. */
+    async updateOrganization(slug: string, data: Partial<{
+        name: string;
+        slug: string;
+        description: string;
+        parent_id: number | null;
+        metadata: Record<string, unknown>;
+        max_members: number;
+        is_active: boolean;
+    }>): Promise<Organization> {
+        return this.client.patch(`/api/v1/auth/organizations/${slug}/`, data);
+    }
+
+    /** Permanently delete an Organization. */
+    async deleteOrganization(slug: string): Promise<{ message: string }> {
+        return this.client.delete(`/api/v1/auth/organizations/${slug}/`);
+    }
+
+    /** Retrieve the topology subtree extending downward from this point. */
+    async getOrganizationTree(slug: string): Promise<OrgTreeNode> {
+        return this.client.get(`/api/v1/auth/organizations/${slug}/tree/`);
+    }
+
+    // ─── Member Management ───
+
+    /** List users bound to a specific Organization. */
+    async listMembers(slug: string, params?: {
+        search?: string;
+        role?: 'owner' | 'admin' | 'member';
+        status?: 'active' | 'inactive' | 'pending';
+        ordering?: string;
+        page?: number;
+        page_size?: number;
+    }): Promise<PaginatedResponse<OrgMembership>> {
+        return this.client.get(`/api/v1/auth/organizations/${slug}/members/`, { params });
+    }
+
+    /** Add a user directly into an Organization with a designated role. */
+    async addMember(slug: string, data: {
+        user_id: number;
+        role_code: string;
+    }): Promise<OrgMembership> {
+        return this.client.post(`/api/v1/auth/organizations/${slug}/members/`, data);
+    }
+
+    /** Evolve or demote an existing member's role within the Organization. */
+    async updateMemberRole(slug: string, userId: number, roleCode: string): Promise<OrgMembership> {
+        return this.client.patch(`/api/v1/auth/organizations/${slug}/members/${userId}/`, { role_code: roleCode });
+    }
+
+    /** Kick a user out of the Organization. */
+    async removeMember(slug: string, userId: number): Promise<{ message: string }> {
+        return this.client.delete(`/api/v1/auth/organizations/${slug}/members/${userId}/`);
+    }
+
+    // ─── Invitations ───
+
+    /** Send an onboarding email invitation to join an Organization. */
+    async inviteMember(slug: string, data: {
+        email: string;
+        role_code: string;
+        expires_in_days?: number;
+    }): Promise<{
+        id: number;
+        email: string;
+        role: string;
+        token: string;
+        expires_at: string;
+        invited_by: { id: number; email: string };
+        organization: { id: number; name: string; slug: string };
+    }> {
+        return this.client.post(`/api/v1/auth/organizations/${slug}/invitations/`, data);
+    }
+
+    /** Fetch a definition matrix of what Organization-level roles can be assigned. */
+    async listOrgRoles(): Promise<Array<{
+        code: string;
+        name: string;
+        description: string;
+        weight: number;
+        permissions: Array<{ code: string; name: string; description: string }>;
+        is_system_role: boolean;
+        created_at: string;
+    }>> {
+        return this.client.get('/api/v1/auth/organizations/roles/');
+    }
+}