@kadoa/node-sdk 0.0.2 → 0.1.1

package/README.md

@@ -5,28 +5,27 @@ Official Node.js/TypeScript SDK for the Kadoa API, providing easy integration wi
 ## Installation
 
 ```bash
-npm install @kadoa/sdk
+npm install @kadoa/node-sdk axios
 # or
-yarn add @kadoa/sdk
+yarn add @kadoa/node-sdk axios
 # or
-pnpm add @kadoa/sdk
-# or
-bun add @kadoa/sdk
+pnpm add @kadoa/node-sdk axios
 ```
 
+**Note:** `axios` is required as a peer dependency.
+
 ## Quick Start
 
 ```typescript
-import { initializeApp, runExtraction } from '@kadoa/sdk';
+import { initializeSdk, runExtraction } from '@kadoa/node-sdk';
 
 // Initialize the SDK
-const app = initializeApp({
-  apiKey: 'your-api-key',
-  baseUrl: 'https://api.kadoa.com' // optional, defaults to production
+const sdk = initializeSdk({
+  apiKey: 'your-api-key'
 });
 
 // Run an extraction
-const result = await runExtraction(app, {
+const result = await runExtraction(sdk, {
   urls: ['https://example.com'],
   name: 'My Extraction Workflow'
 });
@@ -38,100 +37,88 @@ if (result) {
 
 ## Configuration
 
-The SDK can be configured using environment variables or directly in code:
+### Basic Configuration
 
-### Environment Variables
+```typescript
+const sdk = initializeSdk({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.kadoa.com', // optional
+  timeout: 30000                    // optional, in ms
+});
+```
+
+### Using Environment Variables
 
-Create a `.env` file:
 ```env
 KADOA_API_KEY=your-api-key
 KADOA_API_URL=https://api.kadoa.com
 KADOA_TIMEOUT=30000
 ```
 
-Then load them in your code:
 ```typescript
-import { initializeApp } from '@kadoa/sdk';
+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',
+  baseUrl: process.env.KADOA_API_URL,
   timeout: parseInt(process.env.KADOA_TIMEOUT || '30000')
 });
 ```
 
-## Development
-
-### Project Structure
-
-```
-sdks/node/
-├── src/
-│   ├── index.ts             # Public API exports
-│   ├── app.ts              # Application initialization
-│   ├── extraction/         # Extraction module
-│   │   ├── index.ts        # Extraction logic
-│   │   └── client.ts       # API client helpers
-│   └── generated/          # Auto-generated API client
-├── test/
-│   └── e2e/
-│       └── runExtraction.test.ts
-├── examples/
-│   └── src/
-│       └── run-extraction.ts
-├── package.json
-└── tsup.config.ts
-```
-
-### Running Tests
+## Event Handling
 
-```bash
-# Run all tests
-npm test
+```typescript
+const sdk = initializeSdk({ apiKey: 'your-api-key' });
 
-# Run E2E tests
-npm run test:e2e
+// Listen to events
+sdk.onEvent((event) => {
+  console.log('Event:', event);
+});
 
-# Run with coverage
-npm run test:coverage
+// Event types:
+// - entity:detected
+// - extraction:started
+// - extraction:status_changed
+// - extraction:data_available
+// - extraction:completed
 ```
 
-### Building
+## API Reference
 
-```bash
-# Build the SDK
-npm run build
+### initializeSdk(config)
+- `apiKey` (required): Your Kadoa API key
+- `baseUrl` (optional): API base URL
+- `timeout` (optional): Request timeout in milliseconds
 
-# Watch mode for development
-npm run dev
-```
+Returns an SDK instance with:
+- `configuration`: Current configuration
+- `axiosInstance`: Configured HTTP client
+- `onEvent()`: Subscribe to events
+- `offEvent()`: Unsubscribe from events
 
-### Generating API Client
+### runExtraction(sdk, options)
+- `urls`: Array of URLs to extract from
+- `name`: Workflow name
+- Additional options available in API documentation
 
-From the repository root:
+## Examples
 
-```bash
-cd tools/codegen
-bun run generate:node
-```
+See [examples directory](https://github.com/kadoa-org/kadoa-sdks/tree/main/examples/node-examples) for more usage examples.
 
 ## Requirements
 
 - Node.js 18+
 - TypeScript 5+ (for TypeScript projects)
 
-## Dependencies
-
-- `axios` - HTTP client
-- Auto-generated API client code
-
 ## License
 
 MIT
 
 ## Support
 
-For support, please visit [Kadoa Support](https://support.kadoa.com) or contact support@kadoa.com.
+- Documentation: [docs.kadoa.com](https://docs.kadoa.com)
+- Support: [support@kadoa.com](mailto:support@kadoa.com)
+- Issues: [GitHub Issues](https://github.com/kadoa-org/kadoa-sdks/issues)

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 };