@aiassesstech/sdk 0.7.0

package/dist/errors.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * AI Assess Tech SDK - Error Classes
+ *
+ * Custom error types for better error handling
+ *
+ * @version 0.7.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthenticationError = exports.HealthCheckError = exports.RateLimitError = exports.NetworkError = exports.OverallTimeoutError = exports.QuestionTimeoutError = exports.AssessmentError = exports.ValidationError = exports.SDKError = exports.ErrorCode = void 0;
+/**
+ * Error codes for SDK errors
+ */
+var ErrorCode;
+(function (ErrorCode) {
+    // Authentication
+    ErrorCode["INVALID_KEY"] = "INVALID_KEY";
+    ErrorCode["KEY_EXPIRED"] = "KEY_EXPIRED";
+    ErrorCode["KEY_REVOKED"] = "KEY_REVOKED";
+    ErrorCode["MISSING_KEY"] = "MISSING_KEY";
+    // Rate Limiting
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    ErrorCode["QUOTA_EXCEEDED"] = "QUOTA_EXCEEDED";
+    // Validation
+    ErrorCode["INVALID_RESPONSE"] = "INVALID_RESPONSE";
+    ErrorCode["INVALID_BODY"] = "INVALID_BODY";
+    // Timeout
+    ErrorCode["QUESTION_TIMEOUT"] = "QUESTION_TIMEOUT";
+    ErrorCode["OVERALL_TIMEOUT"] = "OVERALL_TIMEOUT";
+    // Assessment
+    ErrorCode["QUESTION_FAILED"] = "QUESTION_FAILED";
+    ErrorCode["ASSESSMENT_FAILED"] = "ASSESSMENT_FAILED";
+    // Network
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ErrorCode["SERVER_ERROR"] = "SERVER_ERROR";
+})(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+/**
+ * Base SDK error class
+ */
+class SDKError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "SDKError";
+        // Maintains proper stack trace for where error was thrown (Node.js)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+exports.SDKError = SDKError;
+/**
+ * Error for validation issues (invalid key, invalid response, etc.)
+ */
+class ValidationError extends SDKError {
+    constructor(message, code = ErrorCode.INVALID_RESPONSE) {
+        super(message, code);
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Error for assessment failures
+ */
+class AssessmentError extends SDKError {
+    constructor(message, code, details) {
+        super(message, code, details);
+        this.name = "AssessmentError";
+    }
+}
+exports.AssessmentError = AssessmentError;
+/**
+ * Error for individual question timeout
+ */
+class QuestionTimeoutError extends SDKError {
+    constructor(message, questionId) {
+        super(message, ErrorCode.QUESTION_TIMEOUT, { questionId });
+        this.questionId = questionId;
+        this.name = "QuestionTimeoutError";
+    }
+}
+exports.QuestionTimeoutError = QuestionTimeoutError;
+/**
+ * Error for overall assessment timeout
+ */
+class OverallTimeoutError extends SDKError {
+    constructor(message, details) {
+        super(message, ErrorCode.OVERALL_TIMEOUT, details);
+        this.name = "OverallTimeoutError";
+    }
+}
+exports.OverallTimeoutError = OverallTimeoutError;
+/**
+ * Error for network issues
+ */
+class NetworkError extends SDKError {
+    constructor(message, statusCode) {
+        super(message, ErrorCode.NETWORK_ERROR, { statusCode });
+        this.statusCode = statusCode;
+        this.name = "NetworkError";
+    }
+}
+exports.NetworkError = NetworkError;
+/**
+ * Error for rate limiting
+ */
+class RateLimitError extends SDKError {
+    constructor(message, retryAfterMs) {
+        super(message, ErrorCode.RATE_LIMITED, { retryAfterMs });
+        this.retryAfterMs = retryAfterMs;
+        this.name = "RateLimitError";
+    }
+}
+exports.RateLimitError = RateLimitError;
+// ============================================
+// Legacy error classes for backward compatibility
+// ============================================
+/**
+ * @deprecated Use SDKError instead
+ */
+class HealthCheckError extends Error {
+    constructor(message, statusCode, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = "HealthCheckError";
+    }
+}
+exports.HealthCheckError = HealthCheckError;
+/**
+ * @deprecated Use ValidationError with ErrorCode.INVALID_KEY instead
+ */
+class AuthenticationError extends HealthCheckError {
+    constructor(message = "Invalid API key") {
+        super(message, 401);
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AI Assess Tech SDK for TypeScript
+ *
+ * Assess AI systems for ethical alignment across 4 dimensions:
+ * Lying, Cheating, Stealing, and Harm.
+ *
+ * @packageDocumentation
+ * @version 0.7.0
+ */
+export { AIAssessClient, withRetry, HealthCheckClient } from "./client";
+export type { ClientConfig, AICallback, AssessOptions, BlockUntilPassOptions, AssessProgress, AssessmentResult, AssessmentArray, ServerConfig, ClientEnvironment, HealthCheckConfig, TestConfig, TargetAI, Framework, FrameworkAxis, TestStatus, TestResult, VerificationResult, TestSummary, HistoryResponse, HistoryFilters, } from "./types";
+export { SDKError, ValidationError, AssessmentError, QuestionTimeoutError, OverallTimeoutError, NetworkError, RateLimitError, ErrorCode, HealthCheckError, AuthenticationError, } from "./errors";
+export { detectEnvironment, isCI } from "./environment";
+export { fetchConfig, submitResponses } from "./api";

package/dist/index.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * AI Assess Tech SDK for TypeScript
+ *
+ * Assess AI systems for ethical alignment across 4 dimensions:
+ * Lying, Cheating, Stealing, and Harm.
+ *
+ * @packageDocumentation
+ * @version 0.7.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.submitResponses = exports.fetchConfig = exports.isCI = exports.detectEnvironment = exports.AuthenticationError = exports.HealthCheckError = exports.ErrorCode = exports.RateLimitError = exports.NetworkError = exports.OverallTimeoutError = exports.QuestionTimeoutError = exports.AssessmentError = exports.ValidationError = exports.SDKError = exports.HealthCheckClient = exports.withRetry = exports.AIAssessClient = void 0;
+// Main client
+var client_1 = require("./client");
+Object.defineProperty(exports, "AIAssessClient", { enumerable: true, get: function () { return client_1.AIAssessClient; } });
+Object.defineProperty(exports, "withRetry", { enumerable: true, get: function () { return client_1.withRetry; } });
+Object.defineProperty(exports, "HealthCheckClient", { enumerable: true, get: function () { return client_1.HealthCheckClient; } });
+// Errors
+var errors_1 = require("./errors");
+// v0.7.0 errors
+Object.defineProperty(exports, "SDKError", { enumerable: true, get: function () { return errors_1.SDKError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+Object.defineProperty(exports, "AssessmentError", { enumerable: true, get: function () { return errors_1.AssessmentError; } });
+Object.defineProperty(exports, "QuestionTimeoutError", { enumerable: true, get: function () { return errors_1.QuestionTimeoutError; } });
+Object.defineProperty(exports, "OverallTimeoutError", { enumerable: true, get: function () { return errors_1.OverallTimeoutError; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return errors_1.NetworkError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+Object.defineProperty(exports, "ErrorCode", { enumerable: true, get: function () { return errors_1.ErrorCode; } });
+// Legacy errors (deprecated)
+Object.defineProperty(exports, "HealthCheckError", { enumerable: true, get: function () { return errors_1.HealthCheckError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_1.AuthenticationError; } });
+// Environment detection
+var environment_1 = require("./environment");
+Object.defineProperty(exports, "detectEnvironment", { enumerable: true, get: function () { return environment_1.detectEnvironment; } });
+Object.defineProperty(exports, "isCI", { enumerable: true, get: function () { return environment_1.isCI; } });
+// API functions (for advanced usage)
+var api_1 = require("./api");
+Object.defineProperty(exports, "fetchConfig", { enumerable: true, get: function () { return api_1.fetchConfig; } });
+Object.defineProperty(exports, "submitResponses", { enumerable: true, get: function () { return api_1.submitResponses; } });

package/dist/types.d.ts

@@ -0,0 +1,317 @@
+/**
+ * AI Assess Tech SDK - TypeScript Type Definitions
+ *
+ * Type-safe interfaces for the SDK
+ *
+ * @version 0.7.0
+ */
+/**
+ * Configuration for the AI Assess Tech client
+ */
+export interface ClientConfig {
+    /** Health Check Key (format: hck_...) */
+    healthCheckKey: string;
+    /** Base URL override (default: https://www.aiassesstech.com) */
+    baseUrl?: string;
+    /** Per-question timeout in milliseconds (default: 30000 = 30s) */
+    perQuestionTimeoutMs?: number;
+    /** Overall assessment timeout in milliseconds (default: 360000 = 6 min) */
+    overallTimeoutMs?: number;
+}
+/**
+ * Callback function type that the developer implements
+ * v0.7.0: Simple single-question callback
+ */
+export type AICallback = (question: string) => Promise<string>;
+/**
+ * Options for the assessment
+ * NOTE: Test mode, framework, thresholds are SERVER-CONTROLLED via Health Check Key
+ */
+export interface AssessOptions {
+    /** Callback for progress updates */
+    onProgress?: (progress: AssessProgress) => void;
+    /** Optional metadata to store with the assessment */
+    metadata?: Record<string, unknown>;
+    /** Dry run mode - only 5 questions, returns mock scores */
+    dryRun?: boolean;
+}
+/**
+ * Options for blocking startup mode
+ */
+export interface BlockUntilPassOptions extends AssessOptions {
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Delay between retries in milliseconds (default: 60000 = 1 min) */
+    retryDelayMs?: number;
+    /** Exit process on failure (default: false) */
+    exitOnFailure?: boolean;
+    /** Callback on each failed attempt */
+    onFailure?: (result: AssessmentResult, attempt: number) => void;
+}
+/**
+ * Progress update during assessment
+ */
+export interface AssessProgress {
+    /** Current question number (1-120) */
+    current: number;
+    /** Total questions */
+    total: number;
+    /** Percentage complete (0-100) */
+    percentage: number;
+    /** Current dimension being tested */
+    dimension: "Lying" | "Cheating" | "Stealing" | "Harm";
+    /** Elapsed time in milliseconds */
+    elapsedMs: number;
+    /** Estimated time remaining in milliseconds */
+    estimatedRemainingMs: number;
+}
+/**
+ * Auto-detected client environment
+ */
+export interface ClientEnvironment {
+    nodeVersion?: string;
+    platform?: "linux" | "darwin" | "win32";
+    arch?: "x64" | "arm64" | "arm";
+    ciProvider?: string;
+    ciJobId?: string;
+    gitCommit?: string;
+    gitBranch?: string;
+}
+/**
+ * Configuration returned by GET /api/sdk/config
+ * Determined by the Health Check Key
+ */
+export interface ServerConfig {
+    /** Test mode (determined by key configuration) */
+    testMode: "ISOLATED" | "CONVERSATIONAL" | "SDK";
+    /** Framework ID */
+    frameworkId: string;
+    /** Question set version for traceability */
+    questionSetVersion: string;
+    /** Pass thresholds per dimension */
+    thresholds: {
+        lying: number;
+        cheating: number;
+        stealing: number;
+        harm: number;
+    };
+    /** Questions to ask (fetched, not bundled) */
+    questions: Array<{
+        id: string;
+        text: string;
+        dimension: "Lying" | "Cheating" | "Stealing" | "Harm";
+        answers: [string, string, string, string];
+    }>;
+    /** Key metadata */
+    keyName: string;
+    organizationName: string;
+}
+/**
+ * Assessment result with 8 data points + traceability
+ */
+export interface AssessmentResult {
+    /** Server-generated Run ID for verification/history lookup */
+    runId: string;
+    /** Client-generated SDK Session ID for traceability */
+    sdkSessionId: string;
+    /** Scores for each dimension (0-10 scale, higher = more ethical) */
+    scores: {
+        lying: number;
+        cheating: number;
+        stealing: number;
+        harm: number;
+    };
+    /** Pass/fail for each dimension */
+    passed: {
+        lying: boolean;
+        cheating: boolean;
+        stealing: boolean;
+        harm: boolean;
+    };
+    /** Overall pass (all dimensions must pass) */
+    overallPassed: boolean;
+    /** Thresholds used (from server configuration) */
+    thresholds: {
+        lying: number;
+        cheating: number;
+        stealing: number;
+        harm: number;
+    };
+    /** Classification label */
+    classification: "Well Adjusted" | "Misguided" | "Manipulative" | "Psychopath";
+    /** Verification URL */
+    verifyUrl: string;
+    /** Timestamp */
+    completedAt: string;
+    /** Version information */
+    versions: {
+        sdkVersion: string;
+        questionSetVersion: string;
+    };
+    /** Key that was used */
+    keyName: string;
+}
+/**
+ * Simplified array format
+ * [LyingScore, CheatingScore, StealingScore, HarmScore,
+ *  LyingPassed, CheatingPassed, StealingPassed, HarmPassed]
+ */
+export type AssessmentArray = [
+    number,
+    number,
+    number,
+    number,
+    boolean,
+    boolean,
+    boolean,
+    boolean
+];
+/**
+ * @deprecated Use ClientConfig instead
+ */
+export interface HealthCheckConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+/**
+ * @deprecated Use AICallback instead
+ */
+export interface TargetAI {
+    provider: "anthropic" | "openai" | "custom";
+    model: string;
+    apiKey: string;
+    endpoint?: string;
+}
+/**
+ * @deprecated Use AssessOptions instead
+ */
+export interface TestConfig {
+    targetAi: TargetAI;
+    frameworkId?: string;
+    metadata?: Record<string, unknown>;
+    webhookUrl?: string;
+    notificationEmail?: string;
+}
+/**
+ * @deprecated Use ServerConfig.questions instead
+ */
+export interface Framework {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    axes: FrameworkAxis[];
+    active: boolean;
+    createdAt: string;
+}
+/**
+ * @deprecated Use ServerConfig.questions instead
+ */
+export interface FrameworkAxis {
+    id: string;
+    name: string;
+    description: string;
+    sortOrder: number;
+}
+/**
+ * @deprecated Use AssessmentResult instead
+ */
+export interface TestStatus {
+    runId: string;
+    status: "queued" | "running" | "completed" | "failed";
+    progress?: {
+        current: number;
+        total: number;
+        percentage: number;
+    };
+    startedAt: string;
+    completedAt?: string;
+    errorMessage?: string;
+}
+/**
+ * @deprecated Use AssessmentResult instead
+ */
+export interface TestResult {
+    runId: string;
+    organizationId: string;
+    framework: {
+        id: string;
+        name: string;
+        version: string;
+    };
+    targetAi: {
+        provider: string;
+        model: string;
+    };
+    scores: {
+        [axisName: string]: number;
+    };
+    classification: string;
+    passed: boolean;
+    threshold: number;
+    metadata?: Record<string, unknown>;
+    verification: {
+        resultHash: string;
+        responsesHash: string;
+        verifyUrl: string;
+    };
+    startedAt: string;
+    completedAt: string;
+    locked: boolean;
+}
+/**
+ * @deprecated
+ */
+export interface VerificationResult {
+    runId: string;
+    verified: boolean;
+    resultHash: string;
+    responsesHash: string;
+    calculatedResultHash: string;
+    calculatedResponsesHash: string;
+    message: string;
+    verifiedAt: string;
+}
+/**
+ * @deprecated
+ */
+export interface TestSummary {
+    runId: string;
+    frameworkId: string;
+    frameworkName: string;
+    targetAiProvider: string;
+    targetAiModel: string;
+    status: "queued" | "running" | "completed" | "failed";
+    passed?: boolean;
+    classification?: string;
+    startedAt: string;
+    completedAt?: string;
+}
+/**
+ * @deprecated
+ */
+export interface HistoryResponse {
+    tests: TestSummary[];
+    pagination: {
+        page: number;
+        pageSize: number;
+        totalTests: number;
+        totalPages: number;
+    };
+}
+/**
+ * @deprecated
+ */
+export interface HistoryFilters {
+    frameworkId?: string;
+    provider?: string;
+    status?: "queued" | "running" | "completed" | "failed";
+    passed?: boolean;
+    startDate?: Date | string;
+    endDate?: Date | string;
+    page?: number;
+    pageSize?: number;
+    sortBy?: "startedAt" | "completedAt";
+    sortOrder?: "asc" | "desc";
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * AI Assess Tech SDK - TypeScript Type Definitions
+ *
+ * Type-safe interfaces for the SDK
+ *
+ * @version 0.7.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@aiassesstech/sdk",
+  "version": "0.7.0",
+  "description": "AI Assess Tech SDK for ethical AI assessment - Test AI systems across 4 dimensions: Lying, Cheating, Stealing, and Harm",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:e2e": "jest --config e2e/jest.e2e.config.js",
+    "test:all": "npm run test && npm run test:e2e",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "ethics",
+    "assessment",
+    "sdk",
+    "ai-safety",
+    "testing",
+    "4d-framework",
+    "lying",
+    "cheating",
+    "stealing",
+    "harm",
+    "ethical-ai",
+    "responsible-ai"
+  ],
+  "author": "AI Assess Tech",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aiassesstech/sdk-ts.git"
+  },
+  "homepage": "https://www.aiassesstech.com/docs",
+  "bugs": {
+    "url": "https://github.com/aiassesstech/sdk-ts/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "peerDependencies": {},
+  "devDependencies": {
+    "@jest/test-sequencer": "^29.7.0",
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.10.6",
+    "@typescript-eslint/eslint-plugin": "^6.17.0",
+    "@typescript-eslint/parser": "^6.17.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}