@kadoa/node-sdk 0.0.2 → 0.1.0

package/README.md

@@ -5,28 +5,32 @@ Official Node.js/TypeScript SDK for the Kadoa API, providing easy integration wi
 ## Installation
 
 ```bash
-npm install @kadoa/sdk
+# CORRECTED: Use @kadoa/node-sdk, not @kadoa/sdk
+npm install @kadoa/node-sdk axios
 # or
-yarn add @kadoa/sdk
+yarn add @kadoa/node-sdk axios
 # or
-pnpm add @kadoa/sdk
+pnpm add @kadoa/node-sdk axios
 # or
-bun add @kadoa/sdk
+bun add @kadoa/node-sdk axios
 ```
 
+**⚠️ Important:** The SDK requires `axios` as a peer dependency but doesn't declare it. You must install it separately.
+
 ## Quick Start
 
 ```typescript
-import { initializeApp, runExtraction } from '@kadoa/sdk';
+// CORRECTED: Use initializeSdk, not initializeApp
+import { initializeSdk, runExtraction } from '@kadoa/node-sdk';
 
 // Initialize the SDK
-const app = initializeApp({
+const sdk = initializeSdk({
   apiKey: 'your-api-key',
   baseUrl: 'https://api.kadoa.com' // optional, defaults to production
 });
 
 // Run an extraction
-const result = await runExtraction(app, {
+const result = await runExtraction(sdk, {
   urls: ['https://example.com'],
   name: 'My Extraction Workflow'
 });
@@ -51,18 +55,50 @@ KADOA_TIMEOUT=30000
 
 Then load them in your code:
 ```typescript
-import { initializeApp } from '@kadoa/sdk';
+// CORRECTED: Use initializeSdk
+import { initializeSdk } from '@kadoa/node-sdk';
 import { config } from 'dotenv';
 
 config();
 
-const app = initializeApp({
+const sdk = initializeSdk({
   apiKey: process.env.KADOA_API_KEY!,
   baseUrl: process.env.KADOA_API_URL || 'https://api.kadoa.com',
   timeout: parseInt(process.env.KADOA_TIMEOUT || '30000')
 });
 ```
 
+## Event Handling
+
+The SDK provides event handling capabilities:
+
+```typescript
+const sdk = initializeSdk({ apiKey: 'your-api-key' });
+
+// Listen to events
+sdk.onEvent((event) => {
+  console.log('Event:', event);
+});
+
+// Available event types:
+// - entity:detected
+// - extraction:started
+// - extraction:status_changed
+// - extraction:data_available
+// - extraction:completed
+```
+
+## SDK Object Structure
+
+The initialized SDK object contains:
+- `configuration`: Configuration object with API settings
+- `axiosInstance`: Configured Axios HTTP client
+- `baseUrl`: API base URL
+- `events`: Internal event emitter
+- `emit`: Emit custom events
+- `onEvent`: Subscribe to events
+- `offEvent`: Unsubscribe from events
+
 ## Development
 
 ### Project Structure
@@ -125,9 +161,16 @@ bun run generate:node
 
 ## Dependencies
 
-- `axios` - HTTP client
+- `axios` - HTTP client (must be installed separately)
 - Auto-generated API client code
 
+## Known Issues
+
+1. **Package Name**: Documentation and npm page incorrectly reference `@kadoa/sdk` instead of `@kadoa/node-sdk`
+2. **Missing Dependency**: The SDK requires `axios` but doesn't declare it as a dependency
+3. **Function Names**: Documentation shows `initializeApp` but the actual export is `initializeSdk`
+4. **Parameter Names**: Documentation refers to "app" object but it's actually an "sdk" object
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,5 +1,157 @@
-import { AxiosInstance, AxiosError } from 'axios';
 import { EventEmitter } from 'events';
+import { AxiosError, AxiosInstance } from 'axios';
+
+type EntityEventPayloads = {
+    "entity:detected": {
+        /** Name of the detected entity type (e.g., "Product", "Article", "Job Listing") */
+        entity: string;
+        /** Data fields detected for the entity */
+        fields: Array<{
+            name: string;
+            description: string;
+            example: string;
+            dataType: string | Record<string, unknown>;
+            isPrimaryKey?: boolean;
+        }>;
+        /** URL that was analyzed for entity detection */
+        url: string;
+    };
+};
+type ExtractionEventPayloads = {
+    "extraction:started": {
+        /** Unique ID of the extraction process */
+        workflowId: string;
+        /** Name given to this extraction */
+        name: string;
+        /** URLs to extract data from */
+        urls: string[];
+    };
+    "extraction:status_changed": {
+        /** Unique ID of the extraction process */
+        workflowId: string;
+        /** Previous processing state */
+        previousState?: string;
+        /** Previous execution status */
+        previousRunState?: string;
+        /** Current processing state */
+        currentState?: string;
+        /** Current execution status */
+        currentRunState?: string;
+    };
+    "extraction:data_available": {
+        /** Unique ID of the extraction process */
+        workflowId: string;
+        /** Number of data records retrieved */
+        recordCount: number;
+        /** Whether this is a partial data set */
+        isPartial: boolean;
+    };
+    "extraction:completed": {
+        /** Unique ID of the extraction process */
+        workflowId: string;
+        /** Whether the extraction completed successfully */
+        success: boolean;
+        /** Final execution status */
+        finalRunState?: string;
+        /** Final processing state */
+        finalState?: string;
+        /** Number of records extracted (if successful) */
+        recordCount?: number;
+        /** Error message (if failed) */
+        error?: string;
+    };
+};
+type EventPayloadMap = EntityEventPayloads & ExtractionEventPayloads;
+
+/**
+ * Unified event structure with discriminated union
+ */
+interface KadoaEvent<T extends keyof EventPayloadMap = keyof EventPayloadMap> {
+    /** Event type identifier */
+    type: T;
+    /** ISO timestamp when the event occurred */
+    timestamp: Date;
+    /** Module or component that emitted the event */
+    source: string;
+    /** Event-specific payload */
+    payload: EventPayloadMap[T];
+    /** Optional metadata for debugging and tracking */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Type aliases for convenience
+ */
+type KadoaEventName = keyof EventPayloadMap;
+type AnyKadoaEvent = KadoaEvent<KadoaEventName>;
+/**
+ * Simplified type-safe event emitter for Kadoa SDK events
+ */
+declare class KadoaEventEmitter extends EventEmitter {
+    /**
+     * Emit a typed SDK event
+     */
+    emit<T extends KadoaEventName>(eventName: T, payload: EventPayloadMap[T], source?: string, metadata?: Record<string, unknown>): boolean;
+    /**
+     * Subscribe to SDK events
+     */
+    onEvent(listener: (event: AnyKadoaEvent) => void): this;
+    /**
+     * Subscribe to SDK events (once)
+     */
+    onceEvent(listener: (event: AnyKadoaEvent) => void): this;
+    /**
+     * Unsubscribe from SDK events
+     */
+    offEvent(listener: (event: AnyKadoaEvent) => void): this;
+    /**
+     * Remove all event listeners
+     */
+    removeAllEventListeners(): this;
+}
+
+type KadoaErrorCode = "UNKNOWN" | "CONFIG_ERROR" | "AUTH_ERROR" | "VALIDATION_ERROR" | "NOT_FOUND" | "RATE_LIMITED" | "TIMEOUT" | "NETWORK_ERROR" | "HTTP_ERROR" | "INTERNAL_ERROR";
+type KadoaSdkExceptionOptions = {
+    code?: KadoaErrorCode;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+};
+declare class KadoaSdkException extends Error {
+    readonly code: KadoaErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly cause?: unknown;
+    constructor(message: string, options?: KadoaSdkExceptionOptions);
+    static from(error: unknown, details?: Record<string, unknown>): KadoaSdkException;
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+}
+
+type KadoaHttpExceptionOptions = {
+    httpStatus?: number;
+    requestId?: string;
+    endpoint?: string;
+    method?: string;
+    responseBody?: unknown;
+    details?: Record<string, unknown>;
+    code?: KadoaErrorCode;
+    cause?: unknown;
+};
+declare class KadoaHttpException extends KadoaSdkException {
+    readonly httpStatus?: number;
+    readonly requestId?: string;
+    readonly endpoint?: string;
+    readonly method?: string;
+    readonly responseBody?: unknown;
+    constructor(message: string, options?: KadoaHttpExceptionOptions);
+    static fromAxiosError(error: AxiosError, extra?: {
+        message?: string;
+        details?: Record<string, unknown>;
+    }): KadoaHttpException;
+    toJSON(): Record<string, unknown>;
+    private static mapStatusToCode;
+}
+
+declare function isKadoaSdkException(error: unknown): error is KadoaSdkException;
+declare function isKadoaHttpException(error: unknown): error is KadoaHttpException;
 
 /**
  * Kadoa API
@@ -660,115 +812,6 @@ declare const V4WorkflowsWorkflowIdGet200ResponseSchemaTypeEnum: {
 };
 type V4WorkflowsWorkflowIdGet200ResponseSchemaTypeEnum = typeof V4WorkflowsWorkflowIdGet200ResponseSchemaTypeEnum[keyof typeof V4WorkflowsWorkflowIdGet200ResponseSchemaTypeEnum];
 
-type EntityEventPayloads = {
-    "entity:detected": {
-        /** Name of the detected entity type (e.g., "Product", "Article", "Job Listing") */
-        entity: string;
-        /** Data fields detected for the entity */
-        fields: Array<{
-            name: string;
-            description: string;
-            example: string;
-            dataType: string | Record<string, unknown>;
-            isPrimaryKey?: boolean;
-        }>;
-        /** URL that was analyzed for entity detection */
-        url: string;
-    };
-};
-type ExtractionEventPayloads = {
-    "extraction:started": {
-        /** Unique ID of the extraction process */
-        workflowId: string;
-        /** Name given to this extraction */
-        name: string;
-        /** URLs to extract data from */
-        urls: string[];
-    };
-    "extraction:status_changed": {
-        /** Unique ID of the extraction process */
-        workflowId: string;
-        /** Previous processing state */
-        previousState?: string;
-        /** Previous execution status */
-        previousRunState?: string;
-        /** Current processing state */
-        currentState?: string;
-        /** Current execution status */
-        currentRunState?: string;
-    };
-    "extraction:data_available": {
-        /** Unique ID of the extraction process */
-        workflowId: string;
-        /** Number of data records retrieved */
-        recordCount: number;
-        /** Whether this is a partial data set */
-        isPartial: boolean;
-    };
-    "extraction:completed": {
-        /** Unique ID of the extraction process */
-        workflowId: string;
-        /** Whether the extraction completed successfully */
-        success: boolean;
-        /** Final execution status */
-        finalRunState?: string;
-        /** Final processing state */
-        finalState?: string;
-        /** Number of records extracted (if successful) */
-        recordCount?: number;
-        /** Error message (if failed) */
-        error?: string;
-    };
-};
-type EventPayloadMap = EntityEventPayloads & ExtractionEventPayloads;
-
-/**
- * Unified event structure with discriminated union
- */
-interface KadoaEvent<T extends keyof EventPayloadMap = keyof EventPayloadMap> {
-    /** Event type identifier */
-    type: T;
-    /** ISO timestamp when the event occurred */
-    timestamp: Date;
-    /** Module or component that emitted the event */
-    source: string;
-    /** Event-specific payload */
-    payload: EventPayloadMap[T];
-    /** Optional metadata for debugging and tracking */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Type aliases for convenience
- */
-type KadoaEventName = keyof EventPayloadMap;
-type KadoaEventPayload<T extends KadoaEventName> = EventPayloadMap[T];
-type AnyKadoaEvent = KadoaEvent<KadoaEventName>;
-/**
- * Simplified type-safe event emitter for Kadoa SDK events
- */
-declare class KadoaEventEmitter extends EventEmitter {
-    /**
-     * Emit a typed SDK event
-     */
-    emit<T extends KadoaEventName>(eventName: T, payload: EventPayloadMap[T], source?: string, metadata?: Record<string, unknown>): boolean;
-    /**
-     * Subscribe to SDK events
-     */
-    onEvent(listener: (event: AnyKadoaEvent) => void): this;
-    /**
-     * Subscribe to SDK events (once)
-     */
-    onceEvent(listener: (event: AnyKadoaEvent) => void): this;
-    /**
-     * Unsubscribe from SDK events
-     */
-    offEvent(listener: (event: AnyKadoaEvent) => void): this;
-    /**
-     * Remove all event listeners
-     */
-    removeAllEventListeners(): this;
-}
-
 interface KadoaSDK {
     configuration: Configuration;
     axiosInstance: AxiosInstance;
@@ -811,69 +854,33 @@ declare function initializeSdk(config: KadoaConfig): KadoaSDK;
  */
 declare function dispose(sdkInstance: KadoaSDK): void;
 
-type ExtractionOptions = {
+type NavigationMode = (typeof WorkflowWithExistingSchemaNavigationModeEnum)[keyof typeof WorkflowWithExistingSchemaNavigationModeEnum];
+interface ExtractionConfig {
     urls: string[];
-    navigationMode?: WorkflowWithExistingSchemaNavigationModeEnum;
-    name?: string;
-    location?: {
+    navigationMode: NavigationMode;
+    name: string;
+    location: {
         type: string;
     };
-    pollingInterval?: number;
-    maxWaitTime?: number;
-};
-type ExtractionResult = {
+    pollingInterval: number;
+    maxWaitTime: number;
+}
+type ExtractionOptions = {
+    urls: string[];
+} & Partial<Omit<ExtractionConfig, "urls">>;
+interface ExtractionResult {
     workflowId: string | undefined;
     workflow?: V4WorkflowsWorkflowIdGet200Response;
     data?: Array<object>;
-};
+}
 
 /**
  * Run extraction workflow using dynamic entity detection
+ *
+ * @param sdkInstance The Kadoa SDK instance
+ * @param options Extraction configuration options
+ * @returns ExtractionResult containing workflow ID, workflow details, and extracted data
  */
 declare function runExtraction(sdkInstance: KadoaSDK, options: ExtractionOptions): Promise<ExtractionResult>;
 
-type KadoaErrorCode = "UNKNOWN" | "CONFIG_ERROR" | "AUTH_ERROR" | "VALIDATION_ERROR" | "NOT_FOUND" | "RATE_LIMITED" | "TIMEOUT" | "NETWORK_ERROR" | "HTTP_ERROR" | "INTERNAL_ERROR";
-type KadoaSdkExceptionOptions = {
-    code?: KadoaErrorCode;
-    details?: Record<string, unknown>;
-    cause?: unknown;
-};
-declare class KadoaSdkException extends Error {
-    readonly code: KadoaErrorCode;
-    readonly details?: Record<string, unknown>;
-    readonly cause?: unknown;
-    constructor(message: string, options?: KadoaSdkExceptionOptions);
-    static from(error: unknown, details?: Record<string, unknown>): KadoaSdkException;
-    toJSON(): Record<string, unknown>;
-    toString(): string;
-}
-
-type KadoaHttpExceptionOptions = {
-    httpStatus?: number;
-    requestId?: string;
-    endpoint?: string;
-    method?: string;
-    responseBody?: unknown;
-    details?: Record<string, unknown>;
-    code?: KadoaErrorCode;
-    cause?: unknown;
-};
-declare class KadoaHttpException extends KadoaSdkException {
-    readonly httpStatus?: number;
-    readonly requestId?: string;
-    readonly endpoint?: string;
-    readonly method?: string;
-    readonly responseBody?: unknown;
-    constructor(message: string, options?: KadoaHttpExceptionOptions);
-    static fromAxiosError(error: AxiosError, extra?: {
-        message?: string;
-        details?: Record<string, unknown>;
-    }): KadoaHttpException;
-    toJSON(): Record<string, unknown>;
-    private static mapStatusToCode;
-}
-
-declare function isKadoaSdkException(error: unknown): error is KadoaSdkException;
-declare function isKadoaHttpException(error: unknown): error is KadoaHttpException;
-
-export { type AnyKadoaEvent, type ExtractionOptions, type ExtractionResult, type KadoaConfig, type KadoaErrorCode, type KadoaEvent, KadoaEventEmitter, type KadoaEventName, type KadoaEventPayload, KadoaHttpException, type KadoaHttpExceptionOptions, type KadoaSDK, KadoaSdkException, type KadoaSdkExceptionOptions, dispose, initializeSdk, isKadoaHttpException, isKadoaSdkException, runExtraction };
+export { type ExtractionOptions, type ExtractionResult, type KadoaConfig, type KadoaErrorCode, type KadoaEvent, KadoaEventEmitter, KadoaHttpException, type KadoaSDK, KadoaSdkException, dispose, initializeSdk, isKadoaHttpException, isKadoaSdkException, runExtraction };