@narrative.io/data-collaboration-sdk-ts 2.58.1 → 2.59.0

package/README.md

@@ -1,18 +1,316 @@
-# SDK
+# Narrative.io Data Collaboration SDK for TypeScript
 
-## Make a release
+[![npm version](https://img.shields.io/npm/v/@narrative.io/data-collaboration-sdk-ts.svg)](https://www.npmjs.com/package/@narrative.io/data-collaboration-sdk-ts)
 
-To make a new release of the SDK, create a branch, make your changes, create a commit with a message following this
-format: `chore(main): release x.y.z` where x.y.z is the release number that you want. You can calculate it like this:
+The official TypeScript SDK for the Narrative.io Data Collaboration Platform. This SDK provides a simple and intuitive interface for interacting with Narrative's APIs, allowing you to manage datasets, subscriptions, data streams, and more.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Overview](#api-overview)
+- [Usage Examples](#usage-examples)
+- [Configuration](#configuration)
+- [TypeScript Support](#typescript-support)
+- [Error Handling](#error-handling)
+- [API Reference](#api-reference)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+Install the SDK using npm:
+
+```bash
+npm install @narrative.io/data-collaboration-sdk-ts
+```
+
+Or using yarn:
+
+```bash
+yarn add @narrative.io/data-collaboration-sdk-ts
+```
+
+Or using bun:
 
 ```bash
-VERSION=$(cat package.json | jq -r .version); \
-PATCH=$(expr $(echo $VERSION|cut -f3 -d.) + 1); \
-NEW_VERSION=$(printf "$(echo $VERSION | cut -f1,2 -d.).$PATCH\n"); \
-echo $NEW_VERSION | pbcopy; \
-echo "The new VERSION=${NEW_VERSION} is in your clipboard."
+bun add @narrative.io/data-collaboration-sdk-ts
+```
+
+## Quick Start
+
+```typescript
+import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';
+
+// Initialize the SDK with your API key
+const narrative = new NarrativeApi({
+  apiKey: 'your-api-key-here',
+  environment: 'prod' // 'prod' or 'dev'
+});
+
+// Make your first API call
+async function getMyCompanyInfo() {
+  try {
+    const companyInfo = await narrative.getCompanyInfo();
+    console.log('Company:', companyInfo);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+getMyCompanyInfo();
+```
+
+## API Overview
+
+The SDK provides access to the following Narrative.io API modules:
+
+### Core APIs
+- **Authentication** - Manage API authentication
+- **Company Info** - Retrieve company information
+- **Health Check** - Check API health status
+- **Who Am I** - Get current user information
+
+### Data Management
+- **Datasets** - Create and manage datasets
+- **Data Streams** - Configure real-time data streams
+- **Data Planes** - Manage data plane configurations
+- **Subscriptions** - Handle data subscriptions
+- **Uploads** - Upload data files
+
+### Data Operations
+- **Queries** - Execute data queries
+- **Forecast** - Generate data forecasts
+- **NQL (Narrative Query Language)** - Build and execute NQL queries
+- **Views** - Create and manage data views
+
+### Marketplace & Collaboration
+- **Products** - Browse and manage data products
+- **Contracts** - Handle data contracts
+- **Connections** - Manage data connections
+- **Installations** - Track app installations
+
+### Advanced Features
+- **Attributes** - Define data attributes
+- **Mappings** - Configure data mappings
+- **Models** - Work with ML models
+- **Model Training** - Train custom models
+- **Rosetta Stone** - Data transformation tools
+- **Access Rules** - Set data access permissions
+- **Access Tokens** - Manage API tokens
+- **Encryption Materials** - Handle encryption keys
+
+## Usage Examples
+
+### Working with Datasets
+
+```typescript
+// List all datasets
+const datasets = await narrative.getDatasets();
+console.log(`Found ${datasets.length} datasets`);
+
+// Get a specific dataset
+const datasetId = 'your-dataset-id';
+const dataset = await narrative.getDataset(datasetId);
+console.log('Dataset name:', dataset.name);
+
+// Create a new dataset
+const newDataset = await narrative.createDataset({
+  name: 'My New Dataset',
+  description: 'A dataset created via SDK',
+  schema: {
+    // Your schema definition
+  }
+});
+```
+
+### Managing Subscriptions
+
+```typescript
+// List active subscriptions
+const subscriptions = await narrative.getSubscriptions();
+subscriptions.forEach(sub => {
+  console.log(`Subscription: ${sub.name} - Status: ${sub.status}`);
+});
+
+// Create a subscription
+const subscription = await narrative.createSubscription({
+  name: 'Daily Data Feed',
+  datasetId: 'dataset-id',
+  frequency: 'daily'
+});
+```
+
+### Executing NQL Queries
+
+```typescript
+// Build and execute an NQL query
+const nqlQuery = `
+  SELECT *
+  FROM narrative.datasets
+  WHERE created_date >= '2024-01-01'
+  LIMIT 100
+`;
+
+const results = await narrative.executeNql(nqlQuery);
+console.log('Query returned', results.rows.length, 'rows');
+```
+
+### Uploading Data
+
+```typescript
+// Upload a file to a dataset
+const upload = await narrative.createUpload({
+  datasetId: 'your-dataset-id',
+  fileName: 'data.csv',
+  fileSize: 1024000 // Size in bytes
+});
+
+// Get the upload URL and upload your file
+console.log('Upload URL:', upload.uploadUrl);
+// Use the uploadUrl to PUT your file data
+```
+
+## Configuration
+
+### Environment Configuration
+
+The SDK supports multiple environments:
+
+```typescript
+// Production environment (default)
+const narrativeProd = new NarrativeApi({
+  apiKey: 'your-api-key'
+});
+
+// Development environment
+const narrativeDev = new NarrativeApi({
+  apiKey: 'your-api-key',
+  environment: 'dev'
+});
+```
+
+### Custom Headers
+
+Add custom headers to all requests:
+
+```typescript
+const narrative = new NarrativeApi({
+  apiKey: 'your-api-key',
+  headers: {
+    'X-Custom-Header': 'custom-value'
+  }
+});
+```
+
+### API Key Management
+
+Store your API key securely using environment variables:
+
+```typescript
+// .env file
+NARRATIVE_API_KEY=your-api-key-here
+
+// Your code
+import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';
+
+const narrative = new NarrativeApi({
+  apiKey: process.env.NARRATIVE_API_KEY!
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides comprehensive type definitions:
+
+```typescript
+import { 
+  NarrativeApi,
+  Dataset,
+  Subscription,
+  DataStream,
+  NqlQuery
+} from '@narrative.io/data-collaboration-sdk-ts';
+
+// Type-safe API calls
+const narrative = new NarrativeApi({
+  apiKey: 'your-api-key'
+});
+
+// TypeScript will provide intellisense and type checking
+const dataset: Dataset = await narrative.getDataset('dataset-id');
+const subscriptions: Subscription[] = await narrative.getSubscriptions();
+```
+
+### Working with Types
+
+```typescript
+import type { 
+  Config,
+  PaginationOptions,
+  Dataset,
+  CreateDatasetRequest 
+} from '@narrative.io/data-collaboration-sdk-ts';
+
+// Use types for better code organization
+const config: Config = {
+  apiKey: process.env.NARRATIVE_API_KEY!,
+  environment: 'prod'
+};
+
+const paginationOptions: PaginationOptions = {
+  limit: 100,
+  offset: 0
+};
 ```
 
-Push your changes to the branch, merge it to the `main` branch. Once the merge is completed (i.e., github actions
-completed) a new release pull request will be available on the github project. Merge the new pull request and the
-github actions will publish the new version of the SKD for you.
+## Error Handling
+
+The SDK provides detailed error information:
+
+```typescript
+import { NarrativeApi } from '@narrative.io/data-collaboration-sdk-ts';
+
+const narrative = new NarrativeApi({
+  apiKey: 'your-api-key'
+});
+
+try {
+  const dataset = await narrative.getDataset('non-existent-id');
+} catch (error) {
+  if (error.response) {
+    // API returned an error response
+    console.error('API Error:', error.response.status);
+    console.error('Error Message:', error.response.data.message);
+  } else if (error.request) {
+    // Request was made but no response received
+    console.error('Network Error:', error.message);
+  } else {
+    // Something else happened
+    console.error('Error:', error.message);
+  }
+}
+```
+
+### Common Error Patterns
+
+```typescript
+// Handle specific error codes
+try {
+  const result = await narrative.someApiCall();
+} catch (error) {
+  if (error.response?.status === 401) {
+    console.error('Authentication failed. Check your API key.');
+  } else if (error.response?.status === 404) {
+    console.error('Resource not found.');
+  } else if (error.response?.status === 429) {
+    console.error('Rate limit exceeded. Please retry later.');
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## API Reference
+
+For detailed API documentation, please visit the [Narrative.io API Documentation](https://api.narrative.dev).

package/build/model-training/index.d.ts

@@ -1,5 +1,5 @@
 import { BaseApi } from "../base-api";
-import type { ModelTrainingConfig, OutputModel, TrainModelRequest, TrainModelResponse } from "./types";
+import type { ModelTrainingConfig, OutputModel, TrainClassifierRequest, TrainClassifierResponse, TrainModelRequest, TrainModelResponse } from "./types";
 /**
  * A class for accessing the Model Training API.
  * @extends BaseApi
@@ -12,5 +12,12 @@ declare class ModelTrainingApi extends BaseApi {
      * @returns {Promise<NqlQueryResponse>} A promise that resolves with the model training response.
      */
     trainModel(data: TrainModelRequest): Promise<TrainModelResponse>;
+    /**
+     * Trains a classifier model.
+     *
+     * @param {TrainClassifierRequest} data - The data for the classifier training.
+     * @returns {Promise<TrainClassifierResponse>} A promise that resolves with the classifier training response.
+     */
+    trainClassifier(data: TrainClassifierRequest): Promise<TrainClassifierResponse>;
 }
-export { ModelTrainingApi, type OutputModel, type TrainModelRequest, type TrainModelResponse, type ModelTrainingConfig, };
+export { ModelTrainingApi, type OutputModel, type TrainModelRequest, type TrainModelResponse, type ModelTrainingConfig, type TrainClassifierRequest, type TrainClassifierResponse, };

package/build/model-training/index.js

@@ -20,5 +20,14 @@ class ModelTrainingApi extends BaseApi {
     async trainModel(data) {
         return await this.post(`${resourceName}/run`, data);
     }
+    /**
+     * Trains a classifier model.
+     *
+     * @param {TrainClassifierRequest} data - The data for the classifier training.
+     * @returns {Promise<TrainClassifierResponse>} A promise that resolves with the classifier training response.
+     */
+    async trainClassifier(data) {
+        return await this.post("train-classifier", data);
+    }
 }
 export { ModelTrainingApi, };

package/build/model-training/types.d.ts

@@ -19,3 +19,11 @@ export interface ModelTrainingConfig {
     instance_type: string;
     custom_axolotl_config_override?: string;
 }
+export interface TrainClassifierRequest {
+    config: Record<string, unknown>;
+    data_plane_id: string;
+    tags: string[];
+}
+export interface TrainClassifierResponse {
+    job_id: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "2.58.1",
+	"version": "2.59.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",