@nvisy/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
+## [0.1.0] - 2025-10-15
+
+### Added
+
+- Initial release of the Nvisy SDK
+- `Client` class for interacting with the Nvisy document redaction API
+- `ClientBuilder` class for fluent configuration building
+- Comprehensive error handling with `ClientError` and other error classes
+- Configuration management with environment variable support
+- TypeScript support with full type definitions
+- Multiple export paths for individual modules
+- Custom header support with validation
+
+### Features
+
+- Fluent API for client configuration
+- Built-in validation for all configuration options
+- Comprehensive test coverage
+- Modern ES2022+ JavaScript target
+- Tree-shakeable ESM builds
+
+### Error Handling
+
+- Structured error responses with `name`, `message`, and `context` fields
+- Automatic retry logic for server errors and rate limiting
+- HTTP status code classification (client vs server errors)
+- Network error handling for timeouts, DNS resolution, and connection issues
+- Configuration validation with detailed error messages
+
+[Unreleased]: https://github.com/nvisycom/sdk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nvisycom/sdk/releases/tag/v0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing
+
+Thank you for your interest in contributing to the Nvisy SDK.
+
+## Requirements
+
+- Node.js 20.0.0 or higher
+- TypeScript 5.9.0 or higher
+- npm
+
+## Development Setup
+
+```bash
+git clone https://github.com/your-username/sdk.git
+cd sdk
+npm install
+```
+
+## Development
+
+### Scripts
+
+- `npm run build` - Build the package for production
+- `npm run dev` - Build in watch mode for development
+- `npm test` - Run test suite
+- `npm run test:coverage` - Run tests with coverage report
+- `npm run test:watch` - Run tests in watch mode
+- `npm run lint` - Check code style and quality
+- `npm run format` - Format code with Biome
+- `npm run check` - Run all linting and formatting checks
+- `npm run typecheck` - Verify TypeScript types
+- `npm run clean` - Remove build artifacts
+
+### Quality Checks
+
+Before submitting changes:
+
+```bash
+npm run check    # Lint, format, and type check
+npm test         # Run test suite
+npm run build    # Verify build works
+```
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Run quality checks: `npm run check`
+6. Submit a pull request
+
+### Pull Request Checklist
+
+- [ ] Tests pass
+- [ ] Code follows project style
+- [ ] TypeScript types are correct
+- [ ] Documentation updated if needed
+- [ ] No breaking changes (or documented)
+
+## Code Standards
+
+- Follow existing TypeScript patterns
+- Use native JavaScript private fields (`#`)
+- Write tests for new features
+- Include JSDoc for public APIs
+- Follow semantic versioning for changes
+
+## License
+
+By contributing, you agree your contributions will be licensed under the MIT
+License.

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nvisy Redaction Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# JavaScript & TypeScript SDK
+
+[![npm version](https://img.shields.io/npm/v/@nvisy/sdk?color=000000&style=flat-square)](https://www.npmjs.com/package/@nvisy/sdk)
+[![build](https://img.shields.io/github/actions/workflow/status/nvisycom/sdk/build.yml?branch=main&color=000000&style=flat-square)](https://github.com/nvisycom/sdk/actions/workflows/build.yml)
+[![node](https://img.shields.io/badge/node-%3E%3D20.0.0-000000?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![typescript](https://img.shields.io/badge/TypeScript-5.9+-000000?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+Official JavaScript & TypeScript SDK for the Nvisy document redaction platform.
+
+## Features
+
+- Modern ES2022+ JavaScript with native private fields
+- Full TypeScript support with strict typing
+- Flexible configuration with constructor or builder pattern
+- Built-in environment variable support
+- Automatic retry logic with smart error handling
+- Individual module exports for optimal bundling
+
+## Installation
+
+```bash
+npm install @nvisy/sdk
+```
+
+## Usage
+
+### Direct Configuration
+
+Create a client by passing configuration options directly to the constructor:
+
+```typescript
+import { Client } from "@nvisy/sdk";
+
+const client = new Client({
+  apiKey: "your-api-key", // Required: 10+ chars, alphanumeric with _ and -
+  baseUrl: "https://api.nvisy.com", // Optional: API endpoint (default shown)
+  timeout: 30000, // Optional: 1000-300000ms (default: 30000)
+  maxRetries: 3, // Optional: 0-5 attempts (default: 3)
+  headers: { // Optional: custom headers
+    "X-Custom-Header": "value",
+  },
+});
+```
+
+### Builder Pattern
+
+Use the fluent builder API for more readable configuration:
+
+```typescript
+import { Client } from "@nvisy/sdk";
+
+const client = Client.builder()
+  .withApiKey("your-api-key") // Required: 10+ chars, alphanumeric with _ and -
+  .withBaseUrl("https://api.nvisy.com") // Optional: API endpoint (default shown)
+  .withTimeout(60000) // Optional: 1000-300000ms (default: 30000)
+  .withMaxRetries(5) // Optional: 0-5 attempts (default: 3)
+  .withHeader("X-Custom-Header", "value") // Optional: single custom header
+  .withHeaders({ "X-Another": "header" }) // Optional: multiple custom headers
+  .build();
+```
+
+### From Environment Variables
+
+Load configuration from environment variables:
+
+```typescript
+import { Client, ClientBuilder } from "@nvisy/sdk";
+
+// Using builder pattern from environment (allows additional configuration)
+const client = ClientBuilder.fromEnvironment()
+  .withTimeout(60000) // Override or add to env config
+  .build();
+
+// Or using Client directly
+const client = Client.fromEnvironment();
+```
+
+Set these environment variables:
+
+| Variable            | Description                      | Required |
+| ------------------- | -------------------------------- | -------- |
+| `NVISY_API_KEY`     | API key for authentication       | Yes      |
+| `NVISY_BASE_URL`    | Custom API endpoint URL          | No       |
+| `NVISY_TIMEOUT`     | Request timeout in milliseconds  | No       |
+| `NVISY_MAX_RETRIES` | Maximum number of retry attempts | No       |
+
+## Requirements
+
+- Node.js 20.0.0 or higher
+- TypeScript 5.9.0 or higher (for development)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes and version history.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+
+## License
+
+MIT License - see [LICENSE.txt](LICENSE.txt) for details.
+
+## Support
+
+- Documentation: [docs.nvisy.com](https://docs.nvisy.com)
+- Issues: [GitHub Issues](https://github.com/nvisycom/sdk/issues)
+- Email: [support@nvisy.com](mailto:support@nvisy.com)

package/dist/builder-BEUIGfoZ.d.ts

@@ -0,0 +1,138 @@
+import createClient from 'openapi-fetch';
+
+/**
+ * Configuration options for the Nvisy client
+ */
+interface ClientConfig {
+    /**
+     * API key for authentication
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Nvisy API
+     * @default "https://api.nvisy.com"
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Maximum number of retry attempts for failed requests
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Custom headers to include with requests
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Internal fully-resolved configuration
+ */
+type ResolvedClientConfig = Required<ClientConfig>;
+/**
+ * Load configuration from environment variables
+ */
+declare function loadConfigFromEnv(): Partial<ClientConfig>;
+/**
+ * Resolve configuration with defaults
+ */
+declare function resolveConfig(userConfig: ClientConfig): ResolvedClientConfig;
+/**
+ * Get available environment variable names
+ */
+declare function getEnvironmentVariables(): Record<string, string>;
+
+/**
+ * Main client class for interacting with the Nvisy document redaction API
+ */
+declare class Client {
+    #private;
+    /**
+     * Create a new Nvisy client instance
+     */
+    constructor(userConfig: ClientConfig);
+    /**
+     * Create a new ClientBuilder for fluent configuration
+     */
+    static builder(): ClientBuilder;
+    /**
+     * Create a client from environment variables
+     */
+    static fromEnvironment(): Client;
+    /**
+     * Get the current configuration (readonly copy)
+     */
+    getConfig(): Readonly<ResolvedClientConfig>;
+    /**
+     * Get the underlying openapi-fetch client for advanced usage
+     */
+    getOpenApiClient(): ReturnType<typeof createClient>;
+    /**
+     * Create a new client with modified configuration
+     */
+    withConfig(configChanges: Partial<ClientConfig>): Client;
+    /**
+     * Create a new client with additional headers
+     */
+    withHeaders(additionalHeaders: Record<string, string>): Client;
+    /**
+     * Create a new client with a different timeout
+     */
+    withTimeout(timeoutMs: number): Client;
+    /**
+     * Create a new client with different retry settings
+     */
+    withMaxRetries(maxRetries: number): Client;
+}
+
+/**
+ * Builder class for constructing client instances with a fluent API
+ */
+declare class ClientBuilder {
+    #private;
+    /**
+     * Create a ClientBuilder instance with an API key
+     */
+    static fromApiKey(apiKey: string): ClientBuilder;
+    /**
+     * Create a ClientBuilder instance from environment variables
+     */
+    static fromEnvironment(): ClientBuilder;
+    /**
+     * Set the API key for authentication
+     */
+    withApiKey(apiKey: string): this;
+    /**
+     * Set the base URL for the API
+     */
+    withBaseUrl(baseUrl: string): this;
+    /**
+     * Set the request timeout in milliseconds
+     */
+    withTimeout(timeoutMs: number): this;
+    /**
+     * Set the maximum number of retry attempts
+     */
+    withMaxRetries(maxRetries: number): this;
+    /**
+     * Add a single custom header (merges with existing headers)
+     */
+    withHeader(name: string, value: string): this;
+    /**
+     * Set custom headers (merges with existing headers)
+     */
+    withHeaders(headers: Record<string, string>): this;
+    /**
+     * Build and return the configured client instance
+     */
+    build(): Client;
+    /**
+     * Get the current configuration (for debugging/testing)
+     */
+    getConfig(): Readonly<Partial<ClientConfig>>;
+}
+
+export { ClientBuilder as C, type ResolvedClientConfig as R, Client as a, type ClientConfig as b, getEnvironmentVariables as g, loadConfigFromEnv as l, resolveConfig as r };

package/dist/builder.d.ts

@@ -0,0 +1,2 @@
+export { C as ClientBuilder } from './builder-BEUIGfoZ.js';
+import 'openapi-fetch';