g-ten-security-sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,40 @@
+"use strict";
+// ──────────────────────────────────────────────────────────────────────────────
+// G-TEN SDK — Public API
+// ──────────────────────────────────────────────────────────────────────────────
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GTenNetworkError = exports.GTenValidationError = exports.GTenApiError = exports.GTenAuthError = exports.signOut = exports.authenticate = exports.GTenSDK = void 0;
+// The recommended entry point — class-based SDK client
+var client_1 = require("./client");
+Object.defineProperty(exports, "GTenSDK", { enumerable: true, get: function () { return client_1.GTenSDK; } });
+// Standalone functional APIs (for backward compatibility)
+var authenticate_1 = require("./auth/authenticate");
+Object.defineProperty(exports, "authenticate", { enumerable: true, get: function () { return authenticate_1.authenticate; } });
+Object.defineProperty(exports, "signOut", { enumerable: true, get: function () { return authenticate_1.signOut; } });
+// Wrapper functions (can be used standalone after calling authenticate())
+__exportStar(require("./wrappers/alerts"), exports);
+__exportStar(require("./wrappers/fraud"), exports);
+__exportStar(require("./wrappers/analytics"), exports);
+__exportStar(require("./wrappers/copilot"), exports);
+// Error classes
+var errors_1 = require("./utils/errors");
+Object.defineProperty(exports, "GTenAuthError", { enumerable: true, get: function () { return errors_1.GTenAuthError; } });
+Object.defineProperty(exports, "GTenApiError", { enumerable: true, get: function () { return errors_1.GTenApiError; } });
+Object.defineProperty(exports, "GTenValidationError", { enumerable: true, get: function () { return errors_1.GTenValidationError; } });
+Object.defineProperty(exports, "GTenNetworkError", { enumerable: true, get: function () { return errors_1.GTenNetworkError; } });
+// Type definitions
+__exportStar(require("./types"), exports);

package/dist/types/index.d.ts

@@ -0,0 +1,85 @@
+/** Configuration options for initializing the GTenSDK. */
+export interface GTenSDKConfig {
+    /** The API key issued to the external client. */
+    apiKey: string;
+    /** The unique client identifier. */
+    clientId: string;
+    /** Optional base URL of the G-TEN API (defaults to http://localhost:8000). */
+    baseUrl?: string;
+}
+/** @deprecated Use GTenSDKConfig instead. */
+export interface AuthCredentials {
+    apiKey: string;
+    clientId: string;
+    baseUrl?: string;
+}
+/** Result returned after a successful authentication. */
+export interface AuthResult {
+    username: string;
+    role: string;
+    authenticated: boolean;
+}
+/** Narrative / commentary generation request parameters. */
+export interface NarrativeRequest {
+    focused_pattern?: string;
+    all_patterns?: string[];
+    shap_features?: string[];
+}
+/** Response shape from the stats endpoint. */
+export interface StatsResponse {
+    total_accounts: number;
+    total_transactions: number;
+    total_flagged: number;
+    critical_count: number;
+    dormant_count: number;
+    fraud_volume_30d: number;
+    accounts_scanned: number;
+}
+/** An individual alert in the system. */
+export interface Alert {
+    alert_id: string;
+    account_id: string;
+    customer_name: string;
+    masked_account_number: string;
+    branch_name: string;
+    branch_code: string;
+    risk_level: string;
+    flagged_for: string[];
+    score: number;
+    total_amount: number | null;
+    status: string;
+    assigned_to: string | null;
+    assignee_id: string | null;
+    created_at: string;
+    detections: Record<string, {
+        detected: boolean;
+        confidence: number;
+    }>;
+}
+/** Paginated alerts response. */
+export interface AlertsResponse {
+    total: number;
+    alerts: Alert[];
+}
+/** Risk score analysis result for a single account. */
+export interface RiskScoreResult {
+    account_id: string;
+    is_flagged: boolean;
+    risk_level: string;
+    combined_score: number;
+    flagged_for: string[];
+    detections: Record<string, {
+        detected: boolean;
+        confidence?: number;
+        error?: string;
+    }>;
+    [key: string]: any;
+}
+/** Fund-tracing result. */
+export interface TraceResult {
+    detected: boolean;
+    fraud_type: string;
+    chain: any[];
+    amounts: number[];
+    [key: string]: any;
+}

package/dist/types/index.js

@@ -0,0 +1,5 @@
+"use strict";
+// ──────────────────────────────────────────────────────────────────────────────
+// G-TEN SDK — Type Definitions
+// ──────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * G-TEN SDK — Error Classes
+ *
+ * Provides clean, typed error classes for SDK consumers.
+ * These are exported from the public SDK interface.
+ */
+/**
+ * Thrown when a protected SDK function is called before `authenticate()`.
+ */
+export declare class GTenAuthError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the G-TEN API returns a non-2xx response.
+ */
+export declare class GTenApiError extends Error {
+    readonly statusCode: number;
+    readonly detail: string;
+    constructor(statusCode: number, detail: string);
+}
+/**
+ * Thrown when SDK input validation fails.
+ */
+export declare class GTenValidationError extends Error {
+    constructor(field: string, message: string);
+}
+/**
+ * Thrown when a network-level error occurs (DNS failure, timeout, connection refused, etc.).
+ */
+export declare class GTenNetworkError extends Error {
+    readonly cause: Error | undefined;
+    constructor(message?: string, cause?: Error);
+}

package/dist/utils/errors.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * G-TEN SDK — Error Classes
+ *
+ * Provides clean, typed error classes for SDK consumers.
+ * These are exported from the public SDK interface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GTenNetworkError = exports.GTenValidationError = exports.GTenApiError = exports.GTenAuthError = void 0;
+/**
+ * Thrown when a protected SDK function is called before `authenticate()`.
+ */
+class GTenAuthError extends Error {
+    constructor(message = "SDK is not authenticated. Call authenticate() before using protected APIs.") {
+        super(message);
+        this.name = "GTenAuthError";
+    }
+}
+exports.GTenAuthError = GTenAuthError;
+/**
+ * Thrown when the G-TEN API returns a non-2xx response.
+ */
+class GTenApiError extends Error {
+    constructor(statusCode, detail) {
+        super(`G-TEN API Error [${statusCode}]: ${detail}`);
+        this.name = "GTenApiError";
+        this.statusCode = statusCode;
+        this.detail = detail;
+    }
+}
+exports.GTenApiError = GTenApiError;
+/**
+ * Thrown when SDK input validation fails.
+ */
+class GTenValidationError extends Error {
+    constructor(field, message) {
+        super(`Validation error on "${field}": ${message}`);
+        this.name = "GTenValidationError";
+    }
+}
+exports.GTenValidationError = GTenValidationError;
+/**
+ * Thrown when a network-level error occurs (DNS failure, timeout, connection refused, etc.).
+ */
+class GTenNetworkError extends Error {
+    constructor(message = "A network error occurred while connecting to the G-TEN API.", cause) {
+        super(message);
+        this.name = "GTenNetworkError";
+        this.cause = cause;
+    }
+}
+exports.GTenNetworkError = GTenNetworkError;

package/dist/utils/validators.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Validates that a string parameter is not null, undefined, or empty.
+ * @internal
+ */
+export declare function validateRequiredString(value: any, fieldName: string): string;
+/**
+ * Validates that a number parameter is a positive integer.
+ * @internal
+ */
+export declare function validatePositiveInteger(value: any, fieldName: string): number;

package/dist/utils/validators.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRequiredString = validateRequiredString;
+exports.validatePositiveInteger = validatePositiveInteger;
+const errors_1 = require("./errors");
+/**
+ * Validates that a string parameter is not null, undefined, or empty.
+ * @internal
+ */
+function validateRequiredString(value, fieldName) {
+    if (value === null || value === undefined || String(value).trim() === "") {
+        throw new errors_1.GTenValidationError(fieldName, "This field is required and cannot be empty.");
+    }
+    return String(value).trim();
+}
+/**
+ * Validates that a number parameter is a positive integer.
+ * @internal
+ */
+function validatePositiveInteger(value, fieldName) {
+    const num = Number(value);
+    if (isNaN(num) || !Number.isInteger(num) || num <= 0) {
+        throw new errors_1.GTenValidationError(fieldName, "Must be a positive integer.");
+    }
+    return num;
+}

package/dist/wrappers/alerts.d.ts

@@ -0,0 +1,29 @@
+import { AlertsResponse, Alert } from "../types";
+/**
+ * Retrieve a paginated list of active alerts from the system.
+ *
+ * @param limit Maximum number of alerts to return (default: 200)
+ * @returns Paginated alerts response containing total count and alert array
+ */
+export declare function getAlerts(limit?: number): Promise<AlertsResponse>;
+/**
+ * Alias for `getAlerts` with a more descriptive name.
+ *
+ * @param limit Maximum number of alerts to return (default: 200)
+ * @returns Paginated alerts response
+ */
+export declare function listAlerts(limit?: number): Promise<AlertsResponse>;
+/**
+ * Retrieve details for a specific alert by ID.
+ *
+ * @param alertId The alert identifier (e.g. "ALT-ACC001-LAYERING")
+ * @returns Alert details including evidence and audit data
+ */
+export declare function getAlert(alertId: string): Promise<Alert>;
+/**
+ * Create a custom alert (placeholder for future SDK backend extension).
+ *
+ * @param payload Alert creation details
+ * @returns Created alert data
+ */
+export declare function createAlert(payload: any): Promise<any>;

package/dist/wrappers/alerts.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAlerts = getAlerts;
+exports.listAlerts = listAlerts;
+exports.getAlert = getAlert;
+exports.createAlert = createAlert;
+const interceptor_1 = require("../auth/interceptor");
+const validators_1 = require("../utils/validators");
+/**
+ * Retrieve a paginated list of active alerts from the system.
+ *
+ * @param limit Maximum number of alerts to return (default: 200)
+ * @returns Paginated alerts response containing total count and alert array
+ */
+async function getAlerts(limit = 200) {
+    return await (0, interceptor_1.sdkFetch)(`/sdk/v1/alerts?limit=${limit}`, {
+        method: "GET",
+    });
+}
+/**
+ * Alias for `getAlerts` with a more descriptive name.
+ *
+ * @param limit Maximum number of alerts to return (default: 200)
+ * @returns Paginated alerts response
+ */
+async function listAlerts(limit = 200) {
+    return getAlerts(limit);
+}
+/**
+ * Retrieve details for a specific alert by ID.
+ *
+ * @param alertId The alert identifier (e.g. "ALT-ACC001-LAYERING")
+ * @returns Alert details including evidence and audit data
+ */
+async function getAlert(alertId) {
+    const validAlertId = (0, validators_1.validateRequiredString)(alertId, "alertId");
+    return await (0, interceptor_1.sdkFetch)(`/sdk/v1/alerts/${encodeURIComponent(validAlertId)}`, {
+        method: "GET",
+    });
+}
+/**
+ * Create a custom alert (placeholder for future SDK backend extension).
+ *
+ * @param payload Alert creation details
+ * @returns Created alert data
+ */
+async function createAlert(payload) {
+    return await (0, interceptor_1.sdkFetch)(`/sdk/v1/alerts`, {
+        method: "POST",
+        body: JSON.stringify(payload),
+    });
+}

package/dist/wrappers/analytics.d.ts

@@ -0,0 +1,8 @@
+import { StatsResponse } from "../types";
+/**
+ * Retrieve platform-wide statistics and metrics.
+ * Includes account counts, transaction volumes, flagged entities, and fraud volumes.
+ *
+ * @returns Platform statistics
+ */
+export declare function getStats(): Promise<StatsResponse>;

package/dist/wrappers/analytics.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStats = getStats;
+const interceptor_1 = require("../auth/interceptor");
+/**
+ * Retrieve platform-wide statistics and metrics.
+ * Includes account counts, transaction volumes, flagged entities, and fraud volumes.
+ *
+ * @returns Platform statistics
+ */
+async function getStats() {
+    return await (0, interceptor_1.sdkFetch)(`/sdk/v1/stats`, {
+        method: "GET",
+    });
+}

package/dist/wrappers/copilot.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Send a natural-language message to the G-TEN Copilot AI assistant.
+ * The Copilot uses Graph-RAG to answer questions about accounts, alerts, and fraud patterns.
+ *
+ * @param message The natural language query
+ * @returns The AI-generated response text
+ */
+export declare function chat(message: string): Promise<string>;

package/dist/wrappers/copilot.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chat = chat;
+const interceptor_1 = require("../auth/interceptor");
+const validators_1 = require("../utils/validators");
+/**
+ * Send a natural-language message to the G-TEN Copilot AI assistant.
+ * The Copilot uses Graph-RAG to answer questions about accounts, alerts, and fraud patterns.
+ *
+ * @param message The natural language query
+ * @returns The AI-generated response text
+ */
+async function chat(message) {
+    const validMessage = (0, validators_1.validateRequiredString)(message, "message");
+    const response = await (0, interceptor_1.sdkFetch)(`/sdk/v1/chat`, {
+        method: "POST",
+        body: JSON.stringify({ message: validMessage }),
+    });
+    return response.response;
+}

package/dist/wrappers/data.d.ts

@@ -0,0 +1,55 @@
+import { Account } from "../generated/src/models/Account";
+import { Transaction } from "../generated/src/models/Transaction";
+/**
+ * Creates a new account in the system.
+ *
+ * @param account The account details to create
+ */
+export declare function createAccount(account: Account): Promise<any>;
+/**
+ * Retrieve account details by ID.
+ *
+ * @param accountId The account identifier
+ */
+export declare function getAccount(accountId: string): Promise<any>;
+/**
+ * Get a paginated list of all accounts.
+ *
+ * @param skip Number of items to skip for pagination (default: 0)
+ * @param limit Maximum number of items to return (default: 100)
+ * @param branchCode Optional branch code filter
+ */
+export declare function getAllAccounts(skip?: number, limit?: number, branchCode?: string): Promise<any>;
+/**
+ * Creates a new transaction in the system (this triggers live ML evaluation).
+ *
+ * @param transaction The transaction details to create
+ */
+export declare function createTransaction(transaction: Transaction): Promise<any>;
+/**
+ * Retrieve a transaction by ID.
+ *
+ * @param txnId The transaction identifier
+ */
+export declare function getTransaction(txnId: string): Promise<any>;
+/**
+ * Get a paginated list of all transactions.
+ *
+ * @param skip Number of items to skip for pagination (default: 0)
+ * @param limit Maximum number of items to return (default: 100)
+ */
+export declare function getAllTransactions(skip?: number, limit?: number): Promise<any>;
+/**
+ * Add a note to an account's history.
+ *
+ * @param accountId The account identifier
+ * @param content The text content of the note
+ * @param author Optional author name (defaults to "FINnet Investigator")
+ */
+export declare function addAccountNote(accountId: string, content: string, author?: string): Promise<any>;
+/**
+ * Get all notes associated with a specific account.
+ *
+ * @param accountId The account identifier
+ */
+export declare function getAccountNotes(accountId: string): Promise<any>;

package/dist/wrappers/data.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAccount = createAccount;
+exports.getAccount = getAccount;
+exports.getAllAccounts = getAllAccounts;
+exports.createTransaction = createTransaction;
+exports.getTransaction = getTransaction;
+exports.getAllTransactions = getAllTransactions;
+exports.addAccountNote = addAccountNote;
+exports.getAccountNotes = getAccountNotes;
+const DataApi_1 = require("../generated/src/apis/DataApi");
+const FraudApi_1 = require("../generated/src/apis/FraudApi");
+const interceptor_1 = require("../auth/interceptor");
+const validators_1 = require("../utils/validators");
+/**
+ * Creates a new account in the system.
+ *
+ * @param account The account details to create
+ */
+async function createAccount(account) {
+    const config = (0, interceptor_1.getAuthenticatedConfig)();
+    const api = new FraudApi_1.FraudApi(config);
+    return await api.createAccountApiV1AccountsPost({
+        account,
+    });
+}
+/**
+ * Retrieve account details by ID.
+ *
+ * @param accountId The account identifier
+ */
+async function getAccount(accountId) {
+    const validAccountId = (0, validators_1.validateRequiredString)(accountId, "accountId");
+    const config = (0, interceptor_1.getAuthenticatedConfig)();
+    const api = new DataApi_1.DataApi(config);
+    return await api.getAccountApiV1AccountsAccountIdGet({
+        accountId: validAccountId,
+    });
+}
+/**
+ * Get a paginated list of all accounts.
+ *
+ * @param skip Number of items to skip for pagination (default: 0)
+ * @param limit Maximum number of items to return (default: 100)
+ * @param branchCode Optional branch code filter
+ */
+async function getAllAccounts(skip, limit, branchCode) {
+    const config = (0, interceptor_1.getAuthenticatedConfig)();
+    const api = new DataApi_1.DataApi(config);
+    return await api.getAllAccountsApiV1AccountsGet({
+        skip,
+        limit,
+        branchCode,
+    });
+}
+/**
+ * Creates a new transaction in the system (this triggers live ML evaluation).
+ *
+ * @param transaction The transaction details to create
+ */
+async function createTransaction(transaction) {
+    const config = (0, interceptor_1.getAuthenticatedConfig)();
+    const api = new FraudApi_1.FraudApi(config);
+    return await api.createTransactionApiV1TransactionsPost({
+        transaction,
+    });
+}
+/**
+ * Retrieve a transaction by ID.
+ *
+ * @param txnId The transaction identifier
+ */
+async function getTransaction(txnId) {
+    const validTxnId = (0, validators_1.validateRequiredString)(txnId, "txnId");
+    const config = (0, interceptor_1.getAuthenticatedConfig)();
+    const api = new DataApi_1.DataApi(config);
+    return await api.getTransactionApiV1TransactionsTxnIdGet({
+        txnId: validTxnId,
+    });
+}
+/**
+ * Get a paginated list of all transactions.
+ *
+ * @param skip Number of items to skip for pagination (default: 0)
+ * @param limit Maximum number of items to return (default: 100)
+ */
+async function getAllTransactions(skip, limit) {
+    const config = (0, interceptor_1.getAuthenticatedConfig)();
+    const api = new DataApi_1.DataApi(config);
+    return await api.getAllTransactionsApiV1TransactionsGet({
+        skip,
+        limit,
+    });
+}
+/**
+ * Add a note to an account's history.
+ *
+ * @param accountId The account identifier
+ * @param content The text content of the note
+ * @param author Optional author name (defaults to "FINnet Investigator")
+ */
+async function addAccountNote(accountId, content, author) {
+    const validAccountId = (0, validators_1.validateRequiredString)(accountId, "accountId");
+    const validContent = (0, validators_1.validateRequiredString)(content, "content");
+    const config = (0, interceptor_1.getAuthenticatedConfig)();
+    const api = new DataApi_1.DataApi(config);
+    return await api.addAccountNoteApiV1AccountsAccountIdNotesPost({
+        accountId: validAccountId,
+        noteCreate: {
+            content: validContent,
+            author: author || "FINnet Investigator",
+        },
+    });
+}
+/**
+ * Get all notes associated with a specific account.
+ *
+ * @param accountId The account identifier
+ */
+async function getAccountNotes(accountId) {
+    const validAccountId = (0, validators_1.validateRequiredString)(accountId, "accountId");
+    const config = (0, interceptor_1.getAuthenticatedConfig)();
+    const api = new DataApi_1.DataApi(config);
+    return await api.getAccountNotesApiV1AccountsAccountIdNotesGet({
+        accountId: validAccountId,
+    });
+}

package/dist/wrappers/fraud.d.ts

@@ -0,0 +1,46 @@
+import { RiskScoreResult, TraceResult, NarrativeRequest } from "../types";
+/**
+ * Analyze a transaction/account for fraud risk.
+ * Runs the full ML scoring pipeline and returns a comprehensive risk assessment.
+ *
+ * @param accountId The account identifier to analyze
+ * @returns Full risk score result including detections, combined score, and risk level
+ */
+export declare function analyzeTransaction(accountId: string): Promise<RiskScoreResult>;
+/**
+ * Get the risk score for a specific account.
+ * Alias for `analyzeTransaction` — provided for semantic clarity.
+ *
+ * @param accountId The account identifier
+ * @returns Risk score result
+ */
+export declare function getRiskScore(accountId: string): Promise<RiskScoreResult>;
+/**
+ * Run fraud detection on a specific account.
+ * Executes ML-based pattern detection (layering, smurfing, dormancy, KYC mismatch).
+ *
+ * @param accountId The account identifier
+ * @returns Detection results with flagged patterns and confidence scores
+ */
+export declare function detectFraud(accountId: string): Promise<RiskScoreResult>;
+/**
+ * Generate an AI-powered narrative commentary / investigation briefing for an account.
+ *
+ * @param accountId The account identifier
+ * @param request Optional narrative generation parameters (focused pattern, SHAP features, etc.)
+ * @returns Generated narrative text and supporting evidence
+ */
+export declare function generateCommentary(accountId: string, request?: NarrativeRequest): Promise<any>;
+/**
+ * Trace the flow of funds from/to a specific account.
+ * Reveals layering chains, round-trip transfers, and connected entities.
+ *
+ * @param accountId The account identifier
+ * @param hint Optional hint to focus tracing (e.g. "layering", "round_trip")
+ * @returns Trace result including detected chains and amounts
+ */
+export declare function trackFunds(accountId: string, hint?: string): Promise<TraceResult>;
+/**
+ * @deprecated Use `analyzeTransaction()` or `getRiskScore()` instead.
+ */
+export declare function getScore(accountId: string): Promise<RiskScoreResult>;