catalyst-relay 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,438 @@
+/**
+ * Authentication types supported by SAP ADT
+ */
+type AuthType = 'basic' | 'saml' | 'sso';
+/**
+ * Basic authentication configuration
+ */
+interface BasicAuthConfig {
+    type: 'basic';
+    username: string;
+    password: string;
+}
+/**
+ * SAML authentication configuration
+ */
+interface SamlAuthConfig {
+    type: 'saml';
+    username: string;
+    password: string;
+    provider?: string;
+}
+/**
+ * SSO (Kerberos) authentication configuration
+ */
+interface SsoAuthConfig {
+    type: 'sso';
+    certificate?: string;
+}
+/**
+ * Union of all auth configurations
+ */
+type AuthConfig = BasicAuthConfig | SamlAuthConfig | SsoAuthConfig;
+/**
+ * Client configuration for connecting to SAP ADT
+ */
+interface ClientConfig {
+    /** ADT server URL (e.g., https://server:port) */
+    url: string;
+    /** SAP client number (e.g., '100') */
+    client: string;
+    /** Authentication configuration */
+    auth: AuthConfig;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Skip SSL verification (dev only) */
+    insecure?: boolean;
+}
+
+/**
+ * Reference to an SAP development object
+ */
+interface ObjectRef {
+    /** Object name (e.g., 'ZTEST_VIEW') */
+    name: string;
+    /** File extension indicating object type (e.g., 'asddls') */
+    extension: string;
+}
+/**
+ * Object with content for create/update operations
+ */
+interface ObjectContent extends ObjectRef {
+    /** Source code content */
+    content: string;
+    /** Optional description for transport */
+    description?: string;
+}
+/**
+ * Tree discovery query for hierarchical browsing
+ */
+interface TreeQuery {
+    /** Package to browse (e.g., '$TMP', 'ZPACKAGE') */
+    package?: string;
+    /** Folder type to expand */
+    folderType?: 'PACKAGE' | 'TYPE' | 'GROUP' | 'API';
+    /** Parent path for nested queries */
+    parentPath?: string;
+}
+/**
+ * Data preview query
+ */
+interface PreviewQuery {
+    /** Object name (table or CDS view) */
+    objectName: string;
+    /** Object type ('table' or 'view') */
+    objectType: 'table' | 'view';
+    /** WHERE clause filters */
+    filters?: Filter[];
+    /** ORDER BY columns */
+    orderBy?: OrderBy[];
+    /** Maximum rows to return (default: 100) */
+    limit?: number;
+    /** Row offset for pagination */
+    offset?: number;
+}
+/**
+ * Filter condition for data preview
+ */
+interface Filter {
+    column: string;
+    operator: FilterOperator;
+    value: string | number | boolean | null;
+}
+type FilterOperator = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' | 'like' | 'in';
+/**
+ * Sort specification for data preview
+ */
+interface OrderBy {
+    column: string;
+    direction: 'asc' | 'desc';
+}
+
+/**
+ * API Response Types
+ *
+ * Generic response wrappers and error codes only.
+ * Domain-specific types live in their colocated modules under core/adt/.
+ */
+/**
+ * Standard API response wrapper
+ */
+interface SuccessResponse<T> {
+    success: true;
+    data: T;
+}
+interface ErrorResponse {
+    success: false;
+    error: string;
+    code?: ErrorCode;
+    details?: unknown;
+}
+type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;
+/**
+ * Machine-readable error codes
+ */
+type ErrorCode = 'AUTH_FAILED' | 'SESSION_EXPIRED' | 'SESSION_NOT_FOUND' | 'CSRF_INVALID' | 'OBJECT_LOCKED' | 'OBJECT_NOT_FOUND' | 'TRANSPORT_REQUIRED' | 'ACTIVATION_FAILED' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'UNKNOWN_ERROR';
+
+/**
+ * Result type for error handling (Go-style tuples)
+ *
+ * Usage:
+ * const [data, error] = await someFunction();
+ * if (error) {
+ *     console.error(error);
+ *     return;
+ * }
+ * // data is guaranteed non-null
+ */
+type Result<T, E = Error> = [T, null] | [null, E];
+/**
+ * Async result type alias for convenience
+ */
+type AsyncResult<T, E = Error> = Promise<Result<T, E>>;
+/**
+ * Create a success result
+ */
+declare function ok<T>(value: T): Result<T, never>;
+/**
+ * Create an error result
+ */
+declare function err<E = Error>(error: E): Result<never, E>;
+
+/**
+ * Session management type definitions
+ */
+
+/**
+ * Session data returned after successful login
+ */
+interface Session {
+    /** Unique session identifier */
+    sessionId: string;
+    /** Authenticated username */
+    username: string;
+    /** Session expiration timestamp */
+    expiresAt: number;
+}
+
+interface ObjectConfig {
+    /** ADT endpoint path (e.g., 'ddic/ddl/sources') */
+    endpoint: string;
+    /** XML namespace for creation requests */
+    nameSpace: string;
+    /** Root element name for creation XML */
+    rootName: string;
+    /** SAP ADT object type identifier (e.g., 'DDLS/DF') */
+    type: string;
+    /** Human-readable label (e.g., 'View') */
+    label: string;
+    /** File extension (e.g., 'asddls') */
+    extension: string;
+    /** Data preview endpoint (if supported) */
+    dpEndpoint?: string;
+    /** Data preview parameter name (if supported) */
+    dpParam?: string;
+}
+/**
+ * Result of upsert operation
+ */
+interface UpsertResult {
+    name: string;
+    extension: string;
+    status: 'created' | 'updated' | 'unchanged';
+    transport?: string;
+}
+
+/**
+ * POST /objects/read — Read object source content
+ */
+
+/**
+ * Object metadata
+ */
+interface ObjectMetadata {
+    name: string;
+    extension: string;
+    package: string;
+    description?: string;
+    createdBy?: string;
+    createdAt?: string;
+    modifiedBy?: string;
+    modifiedAt?: string;
+}
+/**
+ * Object with content (read response)
+ */
+interface ObjectWithContent extends ObjectMetadata {
+    content: string;
+}
+
+/**
+ * Result of activation operation
+ */
+interface ActivationResult {
+    name: string;
+    extension: string;
+    status: 'success' | 'warning' | 'error';
+    messages: ActivationMessage[];
+}
+interface ActivationMessage {
+    severity: 'error' | 'warning' | 'info';
+    text: string;
+    line?: number;
+    column?: number;
+}
+
+/**
+ * Tree — Hierarchical tree browsing for packages
+ */
+
+/**
+ * Tree node for hierarchical browsing
+ */
+interface TreeNode {
+    name: string;
+    type: 'folder' | 'object';
+    objectType?: string;
+    extension?: string;
+    hasChildren?: boolean;
+    children?: TreeNode[];
+}
+/**
+ * Package info
+ */
+interface Package {
+    name: string;
+    description?: string;
+    parentPackage?: string;
+}
+
+/**
+ * Transports — List transport requests for a package
+ */
+
+/**
+ * Transport request
+ */
+interface Transport {
+    id: string;
+    description: string;
+    owner: string;
+    status: 'modifiable' | 'released';
+}
+
+/**
+ * Preview Parser — Parse data preview XML responses
+ *
+ * Internal helper used by data.ts, distinct.ts, and count.ts
+ */
+
+/**
+ * Data preview result (columnar format)
+ */
+interface DataFrame {
+    columns: ColumnInfo[];
+    rows: unknown[][];
+    totalRows?: number;
+}
+interface ColumnInfo {
+    name: string;
+    dataType: string;
+    label?: string;
+}
+
+/**
+ * Distinct Values — Get distinct column values with counts
+ */
+
+/**
+ * Distinct values result
+ */
+interface DistinctResult {
+    column: string;
+    values: Array<{
+        value: unknown;
+        count: number;
+    }>;
+}
+
+/**
+ * Search Objects — Quick search by name pattern
+ */
+
+/**
+ * Search result
+ */
+interface SearchResult {
+    name: string;
+    extension: string;
+    package: string;
+    description?: string;
+    objectType: string;
+}
+
+/**
+ * Where-Used — Find object dependencies
+ */
+
+/**
+ * Where-used dependency
+ */
+interface Dependency {
+    name: string;
+    extension: string;
+    package: string;
+    usageType: string;
+}
+
+/**
+ * Create Transport — Create a new transport request for a package
+ */
+
+/**
+ * Configuration for creating a transport
+ */
+interface TransportConfig {
+    /** Package name (DEVCLASS) */
+    package: string;
+    /** Transport description/text */
+    description: string;
+}
+
+/**
+ * Git Diff — Compare local content with server content
+ *
+ * Uses Myers diff algorithm to compute line-by-line differences.
+ */
+
+/** Base fields for all diff hunks */
+interface BaseDiffHunk {
+    /** Total number of lines in the hunk */
+    length: number;
+    /** Starting line in the diff output (0-indexed) */
+    diffStart: number;
+    /** Starting line in the local file (0-indexed) */
+    localStart: number;
+}
+/** Addition or deletion hunk */
+interface SimpleDiffHunk extends BaseDiffHunk {
+    type: 'addition' | 'deletion';
+    /** Lines added or removed */
+    changes: string[];
+}
+/** Modification hunk (deletion immediately followed by addition) */
+interface ModifiedDiffHunk extends BaseDiffHunk {
+    type: 'modification';
+    /** Tuple of [server_lines, local_lines] */
+    changes: [string[], string[]];
+}
+/** Any diff hunk */
+type DiffHunk = SimpleDiffHunk | ModifiedDiffHunk;
+/** Result of comparing a single object */
+interface DiffResult {
+    name: string;
+    extension: string;
+    label: string;
+    diffs: DiffHunk[];
+}
+
+/**
+ * ADT Client Core Implementation
+ *
+ * HTTP client for SAP ADT (ABAP Development Tools) with:
+ * - Session management (login/logout)
+ * - CSRF token fetching and automatic refresh
+ * - Basic authentication (SAML and SSO to be implemented)
+ * - Automatic retry on 403 CSRF errors
+ * - Session reset on 500 errors
+ *
+ * Uses web standard APIs (fetch, Request, Response) - runtime-agnostic.
+ * High-level ADT operations (CRAUD, preview, etc.) are stubs to be implemented.
+ */
+
+interface ADTClient {
+    /** Current session info (null if not logged in) */
+    readonly session: Session | null;
+    login(): AsyncResult<Session>;
+    logout(): AsyncResult<void>;
+    read(objects: ObjectRef[]): AsyncResult<ObjectWithContent[]>;
+    create(object: ObjectContent, packageName: string, transport?: string): AsyncResult<void>;
+    update(object: ObjectContent, transport?: string): AsyncResult<void>;
+    upsert(objects: ObjectContent[], packageName: string, transport?: string): AsyncResult<UpsertResult[]>;
+    activate(objects: ObjectRef[]): AsyncResult<ActivationResult[]>;
+    delete(objects: ObjectRef[], transport?: string): AsyncResult<void>;
+    getPackages(): AsyncResult<Package[]>;
+    getTree(query: TreeQuery): AsyncResult<TreeNode[]>;
+    getTransports(packageName: string): AsyncResult<Transport[]>;
+    previewData(query: PreviewQuery): AsyncResult<DataFrame>;
+    getDistinctValues(objectName: string, column: string, objectType?: 'table' | 'view'): AsyncResult<DistinctResult>;
+    countRows(objectName: string, objectType: 'table' | 'view'): AsyncResult<number>;
+    search(query: string, types?: string[]): AsyncResult<SearchResult[]>;
+    whereUsed(object: ObjectRef): AsyncResult<Dependency[]>;
+    createTransport(config: TransportConfig): AsyncResult<string>;
+    gitDiff(objects: ObjectContent[]): AsyncResult<DiffResult[]>;
+    getObjectConfig(): ObjectConfig[];
+}
+declare function createClient(config: ClientConfig): Result<ADTClient, Error>;
+
+export { type ADTClient, type ActivationMessage, type ActivationResult, type ApiResponse, type AsyncResult, type AuthConfig, type AuthType, type BasicAuthConfig, type ClientConfig, type ColumnInfo, type DataFrame, type Dependency, type DiffResult, type DistinctResult, type ErrorCode, type ErrorResponse, type Filter, type FilterOperator, type ObjectConfig, type ObjectContent, type ObjectMetadata, type ObjectRef, type ObjectWithContent, type OrderBy, type Package, type PreviewQuery, type Result, type SamlAuthConfig, type SearchResult, type Session, type SsoAuthConfig, type SuccessResponse, type Transport, type TransportConfig, type TreeNode, type TreeQuery, type UpsertResult, createClient, err, ok };