@neo-edi/sdk 0.1.0

package/README.md

@@ -0,0 +1,203 @@
+# @neo-edi/sdk
+
+Official TypeScript SDK for the Neo-EDI platform.
+
+## Installation
+
+```bash
+npm install @neo-edi/sdk
+# or
+pnpm add @neo-edi/sdk
+# or
+yarn add @neo-edi/sdk
+```
+
+## Quick Start
+
+```typescript
+import { NeoEdiClient } from '@neo-edi/sdk';
+
+const client = new NeoEdiClient({
+  baseUrl: 'https://api.neo-edi.com',
+  apiKey: 'nedk_xxxxxxxxxxxx'
+});
+```
+
+## Customers
+
+```typescript
+// List customers
+const customers = await client.customers.list({
+  isActive: true,
+  limit: 50
+});
+
+// Get customer
+const customer = await client.customers.get('ACME-001');
+
+// Create customer
+const newCustomer = await client.customers.create({
+  customerId: 'ACME-001',
+  customerName: 'Acme Corporation',
+  customerMetadata: { industry: 'retail' }
+});
+
+// Update customer
+const updated = await client.customers.update('ACME-001', {
+  customerName: 'Acme Corp'
+});
+
+// Delete customer
+await client.customers.delete('ACME-001');
+```
+
+## Partner-Customer Relationships
+
+```typescript
+// Register customer with multiple partners
+const result = await client.partnerCustomers.register({
+  customerId: 'ACME-001',
+  tradingPartnerIds: ['PARTNER-001', 'PARTNER-002'],
+  isActive: true
+});
+```
+
+## Mapping Templates
+
+```typescript
+// List templates
+const templates = await client.mappingTemplates.list({
+  isPublic: true,
+  targetTable: 'edi_852_headers'
+});
+
+// Create template
+const template = await client.mappingTemplates.create({
+  name: 'My 852 Template',
+  targetTable: 'edi_852_headers',
+  mappingConfig: {
+    'CSV Column': 'db_column'
+  }
+});
+
+// Update template
+await client.mappingTemplates.update('template-id', {
+  name: 'Updated Name'
+});
+```
+
+## CSV Ingestion
+
+```typescript
+// Browser - File input
+const fileInput = document.querySelector<HTMLInputElement>('input[type="file"]');
+const file = fileInput?.files?.[0];
+
+if (file) {
+  const result = await client.ingest.uploadCsv(file, {
+    partnerId: 'PARTNER-001',
+    mappingConfig: {
+      id: 'config-1',
+      version: 1,
+      tables: {
+        edi_852_headers: {
+          batchSize: 500,
+          mapping: { 'Report Date': 'report_date' },
+          defaults: {}
+        }
+      }
+    }
+  });
+}
+
+// Dry run (validation only)
+const dryRunResult = await client.ingest.dryRun(file, options);
+if (!dryRunResult.valid) {
+  console.error('Validation errors:', dryRunResult.errors);
+}
+```
+
+### Node.js File Upload
+
+```typescript
+import { readFileSync } from 'fs';
+
+const buffer = readFileSync('data.csv');
+const blob = new Blob([buffer], { type: 'text/csv' });
+
+await client.ingest.uploadCsv(blob, options);
+```
+
+## GraphQL
+
+```typescript
+import { Queries } from '@neo-edi/sdk';
+
+// Using pre-built queries
+const headers = await client.graphql.query(
+  Queries.GET_EDI_852_HEADERS,
+  { filter: { status: 'pending' } }
+);
+
+// Custom query
+const data = await client.graphql.query<{ edi852Headers: Edi852Header[] }>(`
+  query GetHeaders($filter: Edi852HeaderFilterInput) {
+    edi852Headers(filter: $filter) {
+      id
+      documentId
+      reportDate
+      status
+    }
+  }
+`, { filter: { vendorPartnerId: 'VENDOR-001' } });
+```
+
+## Error Handling
+
+```typescript
+import { NeoEdiApiError, NeoEdiNetworkError } from '@neo-edi/sdk';
+
+try {
+  await client.customers.get('non-existent');
+} catch (error) {
+  if (error instanceof NeoEdiApiError) {
+    console.error(`API Error: ${error.message}`);
+    console.error(`Status: ${error.statusCode}`);
+    console.error(`Code: ${error.code}`);
+  } else if (error instanceof NeoEdiNetworkError) {
+    console.error(`Network Error: ${error.message}`);
+  }
+}
+```
+
+## Configuration
+
+```typescript
+const client = new NeoEdiClient({
+  baseUrl: 'https://api.neo-edi.com',
+  apiKey: 'nedk_xxxxxxxxxxxx',
+  timeout: 60000,  // 60 seconds
+  headers: {
+    'X-Custom-Header': 'value'
+  }
+});
+```
+
+## TypeScript Types
+
+All types are exported for use:
+
+```typescript
+import type {
+  EdiCustomer,
+  EdiPartner,
+  Edi852Header,
+  EdiMappingTemplate,
+  CsvHeaderMappingCollection,
+  ApiResponse
+} from '@neo-edi/sdk';
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,289 @@
+import { ListCustomersParams, EdiCustomer, CreateCustomerRequest, UpdateCustomerRequest, RegisterPartnerCustomerRequest, PartnerCustomerRegistrationResult, ListMappingTemplatesParams, EdiMappingTemplate, CreateMappingTemplateRequest, UpdateMappingTemplateRequest, CsvHeaderMappingCollection, CsvDataTransformationConfig, IngestCsvResult, DryRunResult } from '@neo-edi/types';
+export { Address, ApiResponse, CreateCustomerRequest, CreateMappingTemplateRequest, CreatePartnerRequest, CsvDataTransformationConfig, CsvHeaderMappingCollection, CsvHeaderMappingConfig, CsvHeaderTableEntry, DryRunResult, Edi852DeliverySummary, Edi852Header, Edi852HeaderFilter, Edi852Item, Edi852Location, Edi852Status, EdiCustomer, EdiMappingTemplate, EdiPartner, EdiPartnerCustomer, IngestCsvResult, ListCustomersParams, ListMappingTemplatesParams, PaginatedResponse, PartnerCustomerRegistrationResult, RegisterPartnerCustomerRequest, UpdateCustomerRequest, UpdateMappingTemplateRequest, UpdatePartnerRequest } from '@neo-edi/types';
+
+/**
+ * Base HTTP client for the SDK
+ */
+interface HttpClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+interface RequestOptions {
+    method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+}
+declare class HttpClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    private defaultHeaders;
+    constructor(config: HttpClientConfig);
+    request<T>(options: RequestOptions): Promise<T>;
+    private buildUrl;
+    private parseResponse;
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+
+/**
+ * Customers resource
+ */
+
+declare class CustomersResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List all customers
+     */
+    list(params?: ListCustomersParams): Promise<EdiCustomer[]>;
+    /**
+     * Get a customer by ID
+     */
+    get(customerId: string): Promise<EdiCustomer>;
+    /**
+     * Create a new customer
+     */
+    create(data: CreateCustomerRequest): Promise<EdiCustomer>;
+    /**
+     * Update a customer
+     */
+    update(customerId: string, data: UpdateCustomerRequest): Promise<EdiCustomer>;
+    /**
+     * Delete a customer
+     */
+    delete(customerId: string): Promise<void>;
+}
+
+/**
+ * Partner-Customers resource
+ */
+
+declare class PartnerCustomersResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Register customer-partner relationships
+     * Creates or activates relationships between a customer and multiple trading partners
+     */
+    register(data: RegisterPartnerCustomerRequest): Promise<PartnerCustomerRegistrationResult>;
+}
+
+/**
+ * Mapping Templates resource
+ */
+
+declare class MappingTemplatesResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List all mapping templates
+     */
+    list(params?: ListMappingTemplatesParams): Promise<EdiMappingTemplate[]>;
+    /**
+     * Get a mapping template by ID
+     */
+    get(templateId: string): Promise<EdiMappingTemplate>;
+    /**
+     * Create a new mapping template
+     */
+    create(data: CreateMappingTemplateRequest): Promise<EdiMappingTemplate>;
+    /**
+     * Update a mapping template
+     */
+    update(templateId: string, data: UpdateMappingTemplateRequest): Promise<EdiMappingTemplate>;
+    /**
+     * Delete a mapping template
+     */
+    delete(templateId: string): Promise<void>;
+}
+
+/**
+ * Ingest resource for CSV data ingestion
+ */
+
+interface UploadCsvOptions {
+    partnerId: string;
+    mappingConfig: CsvHeaderMappingCollection;
+    transformationConfig?: CsvDataTransformationConfig;
+}
+/**
+ * File input type for CSV upload
+ * In browser: File or Blob
+ * In Node.js: Use `new Blob([buffer])` to convert Buffer to Blob
+ */
+type CsvFileInput = File | Blob;
+declare class IngestResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Upload a CSV file for ingestion
+     *
+     * @example Browser
+     * ```typescript
+     * const input = document.querySelector('input[type="file"]');
+     * const file = input.files[0];
+     * await client.ingest.uploadCsv(file, options);
+     * ```
+     *
+     * @example Node.js
+     * ```typescript
+     * import { readFileSync } from 'fs';
+     * const buffer = readFileSync('data.csv');
+     * const blob = new Blob([buffer], { type: 'text/csv' });
+     * await client.ingest.uploadCsv(blob, options);
+     * ```
+     */
+    uploadCsv(file: CsvFileInput, options: UploadCsvOptions): Promise<IngestCsvResult>;
+    /**
+     * Perform a dry run of CSV ingestion (validation only)
+     */
+    dryRun(file: CsvFileInput, options: UploadCsvOptions): Promise<DryRunResult>;
+}
+
+/**
+ * GraphQL resource for flexible queries
+ */
+
+interface GraphQLRequestOptions {
+    operationName?: string;
+}
+declare class GraphQLResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Execute a GraphQL query
+     */
+    query<T>(query: string, variables?: Record<string, unknown>, options?: GraphQLRequestOptions): Promise<T>;
+    /**
+     * Execute a GraphQL mutation
+     */
+    mutate<T>(mutation: string, variables?: Record<string, unknown>, options?: GraphQLRequestOptions): Promise<T>;
+}
+/**
+ * Pre-built GraphQL queries for common operations
+ */
+declare const Queries: {
+    /**
+     * Get EDI 852 headers with filtering
+     */
+    GET_EDI_852_HEADERS: string;
+    /**
+     * Get a single EDI 852 header by ID with locations
+     */
+    GET_EDI_852_HEADER_BY_ID: string;
+    /**
+     * Get trading partner execution summaries
+     */
+    GET_EXECUTION_SUMMARIES: string;
+};
+
+/**
+ * Neo-EDI SDK Client
+ */
+
+interface NeoEdiClientConfig {
+    /**
+     * Base URL of the Neo-EDI API
+     * @example "https://api.neo-edi.com"
+     */
+    baseUrl: string;
+    /**
+     * API key for authentication
+     * @example "nedk_live_xxxxxxxxxxxx"
+     */
+    apiKey: string;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Additional headers to send with every request
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Neo-EDI SDK Client
+ *
+ * @example
+ * ```typescript
+ * const client = new NeoEdiClient({
+ *   baseUrl: "https://api.neo-edi.com",
+ *   apiKey: "nedk_live_xxxxxxxxxxxx"
+ * });
+ *
+ * // List customers
+ * const customers = await client.customers.list({ isActive: true });
+ *
+ * // Create a customer
+ * const customer = await client.customers.create({
+ *   customerId: "ACME-001",
+ *   customerName: "Acme Corporation"
+ * });
+ *
+ * // Upload CSV data
+ * const result = await client.ingest.uploadCsv(file, {
+ *   partnerId: "PARTNER-001",
+ *   mappingConfig: { ... }
+ * });
+ *
+ * // Run GraphQL query
+ * const data = await client.graphql.query(
+ *   `query { edi852Headers { id reportDate } }`
+ * );
+ * ```
+ */
+declare class NeoEdiClient {
+    private http;
+    /**
+     * Customer management operations
+     */
+    readonly customers: CustomersResource;
+    /**
+     * Partner-Customer relationship operations
+     */
+    readonly partnerCustomers: PartnerCustomersResource;
+    /**
+     * Mapping template operations
+     */
+    readonly mappingTemplates: MappingTemplatesResource;
+    /**
+     * CSV data ingestion operations
+     */
+    readonly ingest: IngestResource;
+    /**
+     * GraphQL query operations
+     */
+    readonly graphql: GraphQLResource;
+    constructor(config: NeoEdiClientConfig);
+}
+
+/**
+ * SDK error types
+ */
+declare class NeoEdiError extends Error {
+    readonly code?: string | undefined;
+    readonly statusCode?: number | undefined;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined, details?: Record<string, unknown> | undefined);
+}
+declare class NeoEdiApiError extends NeoEdiError {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number, code?: string, details?: Record<string, unknown>);
+}
+declare class NeoEdiNetworkError extends NeoEdiError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+declare class NeoEdiValidationError extends NeoEdiError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+export { type CsvFileInput, NeoEdiApiError, NeoEdiClient, type NeoEdiClientConfig, NeoEdiError, NeoEdiNetworkError, NeoEdiValidationError, Queries, type UploadCsvOptions };