@helix-tools/sdk-typescript 1.2.0

package/LICENSE

@@ -0,0 +1,20 @@
+PROPRIETARY LICENSE
+
+Copyright (c) 2025 Helix. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Helix.
+
+NOTICE: All information contained herein is, and remains the property of
+Helix and its suppliers, if any. The intellectual and technical concepts
+contained herein are proprietary to Helix and its suppliers and may be
+covered by U.S. and Foreign Patents, patents in process, and are protected
+by trade secret or copyright law.
+
+Dissemination of this information or reproduction of this material is
+strictly forbidden unless prior written permission is obtained from Helix.
+
+Unauthorized copying, distribution, modification, public display, or public
+performance of this Software, via any medium, is strictly prohibited.
+
+For licensing inquiries, please contact: contact@helix.tools

package/README.md

@@ -0,0 +1,23 @@
+# Helix Connect Platform TypeScript SDK
+
+Official TypeScript/Node.js SDK for the Helix Connect data marketplace platform.
+
+## Overview
+
+The Helix Connect TypeScript SDK enables data producers and consumers to securely exchange and consume datasets through the Helix Connect platform.
+
+## Installation
+
+```bash
+npm install @helix-tools/sdk-typescript
+```
+
+## Support
+
+- Documentation: https://docs.helix.tools
+- Issues: https://github.com/helix-tools/sdk-typescript/issues
+- Email: support@helix.tools
+
+## License
+
+See LICENSE file for details.

package/dist/consumer.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Helix Connect Platform Consumer SDK
+ * For data consumers who want to download and access datasets
+ */
+export interface HelixConsumerConfig {
+    awsAccessKeyId: string;
+    awsSecretAccessKey: string;
+    customerId: string;
+    apiEndpoint?: string;
+    region?: string;
+}
+export interface DatasetMetadata {
+    _id: string;
+    name: string;
+    producer_id: string;
+    size_bytes: number;
+    s3_key: string;
+    metadata?: {
+        compression_enabled?: boolean;
+        encryption_enabled?: boolean;
+    };
+}
+export interface DownloadUrlInfo {
+    download_url: string;
+    expires_at: string;
+    dataset: {
+        id: string;
+        name: string;
+        size_bytes: number;
+    };
+}
+export interface SubscriptionRequest {
+    request_id: string;
+    producer_id: string;
+    consumer_id: string;
+    dataset_id?: string;
+    tier: string;
+    status: string;
+    created_at: string;
+}
+export interface Notification {
+    message_id: string;
+    receipt_handle: string;
+    event_type: string;
+    producer_id: string;
+    dataset_id: string;
+    dataset_name?: string;
+    s3_bucket: string;
+    s3_key: string;
+    size_bytes: number;
+    timestamp: string;
+    subscriber_id: string;
+    subscription_id: string;
+    raw_message: string;
+}
+export declare class HelixConsumer {
+    private customerId;
+    private apiEndpoint;
+    private region;
+    private kmsClient;
+    private stsClient;
+    private sqsClient;
+    private ssmClient;
+    private awsAccessKeyId;
+    private awsSecretAccessKey;
+    private queueUrl;
+    /**
+     * Creates a new Helix Consumer instance.
+     * Initializes AWS clients and validates credentials on construction.
+     */
+    constructor(config: HelixConsumerConfig);
+    /**
+     * Validates AWS credentials by making a test STS call.
+     * Throws an error if credentials are invalid.
+     */
+    private validateCredentials;
+    /**
+     * Signs an HTTP request using AWS Signature Version 4.
+     * Used for authenticating API requests to Helix Connect Platform.
+     */
+    private signRequest;
+    /**
+     * Makes an authenticated API request to Helix Connect Platform.
+     * Handles request signing, error responses, and retries.
+     */
+    private makeApiRequest;
+    /**
+     * Retrieves metadata for a specific dataset.
+     * Returns information about the dataset including size, compression, and encryption status.
+     */
+    getDataset(datasetId: string): Promise<DatasetMetadata>;
+    /**
+     * Generates a pre-signed S3 download URL for a dataset.
+     * The URL expires after a limited time and grants temporary access to the encrypted dataset file.
+     */
+    getDownloadUrl(datasetId: string): Promise<DownloadUrlInfo>;
+    /**
+     * Decompresses gzip-compressed data.
+     * Used internally after decryption to restore original dataset format.
+     */
+    private decompressData;
+    /**
+     * Decrypts data using envelope encryption with KMS.
+     * Process: Decrypt data key with KMS, then decrypt data with AES-256-GCM.
+     * Format: [4 bytes: key length][encrypted key][16 bytes: IV][16 bytes: tag][encrypted data]
+     */
+    private decryptData;
+    /**
+     * Downloads a dataset from S3, automatically decrypting and decompressing if needed.
+     * The downloaded file is saved to the specified output path in its original format.
+     *
+     * Optimized for large files (>1GB) using streaming when possible.
+     */
+    downloadDataset(datasetId: string, outputPath: string, options?: {
+        autoDecompress?: boolean;
+        autoDecrypt?: boolean;
+    }): Promise<string>;
+    /**
+     * Decompresses data using streaming to avoid buffer limits.
+     * Used for large files that would exceed Node.js Buffer size limits (2GB).
+     */
+    private decompressDataStream;
+    /**
+     * Lists all datasets available to this consumer.
+     * Returns metadata for datasets the consumer has permission to access.
+     */
+    listDatasets(): Promise<DatasetMetadata[]>;
+    /**
+     * Lists all active subscriptions for this consumer.
+     *
+     * @returns Array of subscription objects
+     */
+    listSubscriptions(): Promise<any[]>;
+    /**
+     * Creates a subscription request to access a producer's datasets.
+     * The producer must approve the request before the consumer gains access.
+     */
+    createSubscriptionRequest(params: {
+        producerId: string;
+        datasetId?: string;
+        tier?: string;
+        message?: string;
+    }): Promise<SubscriptionRequest>;
+    /**
+     * Polls the shared SQS queue for dataset upload notifications.
+     *
+     * IMPORTANT: This uses a SHARED queue for all consumers. The application should
+     * filter notifications based on subscriptions. Only download datasets from
+     * producers you are subscribed to.
+     *
+     * Messages are automatically acknowledged (deleted) by default after retrieval.
+     * This prevents duplicate processing and simplifies the developer experience.
+     * Set autoAcknowledge to false if you need manual control over message deletion.
+     *
+     * @param maxMessages - Maximum number of messages to retrieve (1-10, default: 10)
+     * @param waitTimeSeconds - Long polling wait time (0-20 seconds, default: 20)
+     * @param visibilityTimeout - How long messages are hidden after retrieval (default: 300s)
+     * @param autoAcknowledge - Automatically acknowledge (delete) messages after receiving (default: true)
+     * @param subscriptionIds - Optional array of subscription IDs to filter notifications
+     * @returns Array of notification objects
+     *
+     * @example
+     * ```typescript
+     * const consumer = new HelixConsumer(...);
+     *
+     * // Simple usage - messages auto-deleted after poll
+     * const notifications = await consumer.pollNotifications({
+     *   subscriptionIds: ['sub-123'],
+     *   maxMessages: 5
+     * });
+     * for (const notif of notifications) {
+     *   console.log(`New dataset: ${notif.dataset_name}`);
+     *   await consumer.downloadDataset(notif.dataset_id, './output.json');
+     *   // No need to delete - already handled automatically!
+     * }
+     *
+     * // Advanced usage - manual acknowledgment for custom retry logic
+     * const notifications = await consumer.pollNotifications({
+     *   autoAcknowledge: false,
+     *   maxMessages: 5
+     * });
+     * for (const notif of notifications) {
+     *   try {
+     *     await consumer.downloadDataset(notif.dataset_id, './output.json');
+     *     // Manually acknowledge only after successful processing
+     *     await consumer.deleteNotification(notif.receipt_handle);
+     *   } catch (error) {
+     *     console.error('Processing failed, message will retry:', error);
+     *     // Message not deleted, will become visible again after visibility timeout
+     *   }
+     * }
+     * ```
+     */
+    pollNotifications(options?: {
+        maxMessages?: number;
+        waitTimeSeconds?: number;
+        visibilityTimeout?: number;
+        autoAcknowledge?: boolean;
+        subscriptionIds?: string[];
+    }): Promise<Notification[]>;
+    /**
+     * Deletes a notification message from the SQS queue after processing.
+     *
+     * @param receiptHandle - The receipt handle from pollNotifications()
+     *
+     * @example
+     * ```typescript
+     * const consumer = new HelixConsumer(...);
+     * const notifications = await consumer.pollNotifications();
+     * for (const notif of notifications) {
+     *   // Process notification...
+     *   await consumer.deleteNotification(notif.receipt_handle);
+     * }
+     * ```
+     */
+    deleteNotification(receiptHandle: string): Promise<void>;
+    /**
+     * Extracts producer ID from S3 key path.
+     * S3 keys follow the pattern: datasets/{dataset_name}/{date}/{file}
+     *
+     * @param s3Key - S3 object key
+     * @returns Extracted producer ID (or 'unknown' if not found)
+     */
+    private extractProducerId;
+}
+//# sourceMappingURL=consumer.d.ts.map

package/dist/consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"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"}