@iris-technologies/api - npm Package Compare versions

Comparing version

1.0.2

1.0.3

+1

-1

package.json

		{
		"name": "@iris-technologies/api",
		"version": "1.0.2",
		"version": "1.0.3",
		"description": "Iris API client for retrieving targeted advertisements",
		@@ -5,0 +5,0 @@ "main": "dist/index.js",

+220

-120

README.md

		# @iris-technologies/api

		A TypeScript client library for the Iris advertising API.
		A TypeScript client library for the Iris advertising API with automatic impression and click URL generation.

		## Features

		- Smart Ad Retrieval: Get contextually relevant advertisements
		- Automatic URL Generation: Impression and click tracking URLs included
		- Error Handling: Graceful fallbacks and comprehensive error logging
		- TypeScript Support: Full type safety with detailed type definitions
		- Configurable Topics: Exclude unwanted ad categories
		- Comprehensive Testing: 21 test cases covering all functionality

		## Installation
		@@ -11,3 +20,3 @@

		## Usage
		## Quick Start

		@@ -20,6 +29,6 @@ ```typescript

		// Get an advertisement
		// Get an advertisement with tracking URLs
		const ad = await client.getAd(
		'user input context',
		'assistant response context',
		'user looking for weather information',
		'showing current weather conditions',
		'user-123'
		@@ -30,3 +39,6 @@ );
		console.log('Ad text:', ad.text);
		console.log('Ad URL:', ad.url);
		console.log('Landing page:', ad.url);
		console.log('Impression URL:', ad.impUrl); // Auto-generated
		console.log('Click URL:', ad.clickUrl); // Auto-generated
		console.log('Publisher payout:', ad.payout);
		} else {
		@@ -47,4 +59,5 @@ console.log('No ad available');

		- `apiKey`: Your Iris API key
		- `excludedTopics`: Array of topic strings to exclude from ads
		Parameters:
		- `apiKey`: Your Iris API key for authentication
		- `excludedTopics`: Array of topic strings to exclude from ads (e.g., `['politics', 'adult', 'gambling']`)

		@@ -55,16 +68,29 @@ #### Methods

		Retrieves a targeted advertisement based on the provided context.
		Retrieves a targeted advertisement with automatic tracking URL generation.

		Parameters:
		- `inputPrompt`: The user's input context
		- `responsePrompt`: The assistant's response context
		- `userId`: Unique identifier for the user
		- `inputPrompt`: The user's input context (what they asked about)
		- `responsePrompt`: The assistant's response context (what you're telling them)
		- `userId`: Unique identifier for the user (for personalization)

		Returns:
		- `AdResponse \| null`: Advertisement object with `text` and `url` properties, or `null` if no ad is available
		- `AdResponse \| null`: Advertisement object with tracking URLs, or `null` if no ad is available

		Example:
		```typescript
		const ad = await client.getAd(
		'How do I learn guitar?',
		'Here are some tips for learning guitar...',
		'user-456'
		);
		```

		##### `updateExcludedTopics(excludedTopics: string[]): void`

		Updates the list of excluded topics.
		Updates the list of excluded ad topics.

		```typescript
		client.updateExcludedTopics(['politics', 'crypto', 'dating']);
		```

		##### `getExcludedTopics(): string[]`
		@@ -74,156 +100,230 @@

		## Types
		```typescript
		const currentExclusions = client.getExcludedTopics();
		console.log('Excluding:', currentExclusions);
		```

		## Response Types

		### `AdResponse`

		```typescript
		interface AdResponse {
		text: string;
		url: string;
		text: string; // Ad copy to display to users
		url: string; // Landing page URL
		impUrl?: string; // Impression tracking URL (fire when ad is shown)
		clickUrl?: string; // Click tracking URL (use when ad is clicked)
		payout?: number; // Publisher payout amount in USD
		}
		```

		## Error Handling
		### Example Response

		The client handles errors silently and logs them to the console. All methods return `null` or safe defaults when errors occur.
		```javascript
		{
		text: "Learn guitar online with interactive lessons!",
		url: "https://guitarlessons.com/signup",
		impUrl: "https://api.iris.tech/impression?id=abc123&price=0.15",
		clickUrl: "https://api.iris.tech/click?id=abc123&redirect=https://guitarlessons.com/signup",
		payout: 0.075
		}
		```

		## Development
		## Advanced Usage

		```bash
		# Install dependencies
		npm install
		### Error Handling

		# Build the package
		npm run build
		The client handles errors gracefully and logs detailed information:

		# Watch mode for development
		npm run dev
		```typescript
		// Network errors, HTTP errors, and invalid responses are handled automatically
		const ad = await client.getAd('context', 'response', 'user');

		# Clean build artifacts
		npm run clean
		// Always check for null response
		if (!ad) {
		console.log('No ad available - could be network error, no inventory, or excluded topic');
		}
		```

		## Publishing to NPM
		### Dynamic Topic Management

		### Initial Setup
		```typescript
		const client = new IrisClient('api-key', ['politics']);

		1. Create an NPM account (if you don't have one):
		```bash
		npm adduser
		```
		Or login to existing account:
		```bash
		npm login
		```
		// Add more excluded topics based on user preferences
		const userPreferences = getUserAdPreferences();
		if (userPreferences.excludeGambling) {
		const current = client.getExcludedTopics();
		client.updateExcludedTopics([...current, 'gambling', 'casino']);
		}

		2. Verify your login:
		```bash
		npm whoami
		```
		// Get ad with updated exclusions
		const ad = await client.getAd(context, response, userId);
		```

		3. Update package.json metadata:
		- Update `author` field with your information
		- Update `repository.url` with your actual GitHub repository
		- Update `homepage` and `bugs.url` with correct URLs
		### Integration with React Component

		### Pre-Publishing Checklist
		Perfect pairing with [@iris-technologies/react](https://www.npmjs.com/package/@iris-technologies/react):

		Before publishing, ensure:
		```typescript
		import { IrisClient } from '@iris-technologies/api';
		import { IrisAd } from '@iris-technologies/react';

		- [ ] All tests pass (when tests are added)
		- [ ] Code builds successfully (`npm run build`)
		- [ ] Version number is updated appropriately
		- [ ] CHANGELOG is updated (if you maintain one)
		- [ ] README is up to date
		- [ ] All dependencies are properly declared
		- [ ] API endpoint is configured correctly
		const client = new IrisClient('your-api-key', ['politics']);

		### Publishing Commands
		function AdContainer({ userInput, botResponse, userId }) {
		const [ad, setAd] = useState(null);

		useEffect(() => {
		client.getAd(userInput, botResponse, userId)
		.then(setAd);
		}, [userInput, botResponse, userId]);

		return ad ? <IrisAd ad={ad} /> : null;
		}
		```

		#### Test Publishing (Dry Run)
		```bash
		# See what would be published without actually publishing
		npm run publish:dry-run
		## Configuration

		### API Endpoint

		The client connects to `https://api.iristech.dev` by default. The endpoint includes:

		- Authentication via Bearer token
		- 10-second request timeout
		- JSON content type headers
		- Error logging for debugging

		### Excluded Topics

		Common topic exclusions:

		```typescript
		const excludedTopics = [
		'politics', // Political content
		'adult', // Adult/NSFW content
		'gambling', // Gambling and betting
		'crypto', // Cryptocurrency
		'dating', // Dating and relationships
		'religion', // Religious content
		'health', // Medical/health claims
		'financial', // Financial advice
		];

		const client = new IrisClient('api-key', excludedTopics);
		```

		#### Version Management
		## Testing

		This package includes comprehensive test coverage (21 test cases):

		```bash
		# Patch version (1.0.0 → 1.0.1) - for bug fixes
		npm run version:patch
		# Run tests
		npm test

		# Minor version (1.0.0 → 1.1.0) - for new features
		npm run version:minor
		# Run tests in watch mode
		npm run test:watch

		# Major version (1.0.0 → 2.0.0) - for breaking changes
		npm run version:major
		# Run tests with coverage
		npm run test:coverage
		```

		#### Publishing Releases
		```bash
		# Publish patch version (auto-increments and publishes)
		npm run publish:patch
		### What's Tested
		- ✅ API response parsing and URL extraction
		- ✅ HTTP error handling (404, 500, timeouts)
		- ✅ Network error handling
		- ✅ Invalid response data handling
		- ✅ Excluded topics management
		- ✅ Configuration and authentication
		- ✅ Edge cases (missing URLs, special characters)

		# Publish minor version
		npm run publish:minor
		## Error Handling

		# Publish major version
		npm run publish:major
		The client provides comprehensive error handling:

		# Publish beta version (tagged as beta)
		npm run publish:beta
		### Network Errors
		```typescript
		// Automatic retry logic and graceful degradation
		const ad = await client.getAd(context, response, userId);
		// Returns null on network failure, logs error details
		```

		#### Manual Publishing
		### HTTP Errors
		```typescript
		// Handles 404, 500, timeout errors automatically
		// Logs detailed error information for debugging
		// Always returns null instead of throwing
		```

		### Invalid Data
		```typescript
		// Validates response structure
		// Handles missing required fields
		// Graceful fallback for malformed responses
		```

		## Development

		```bash
		# Manual version bump
		npm version patch # or minor/major
		# Install dependencies
		npm install

		# Manual publish
		npm publish
		# Build the package
		npm run build

		# Publish with specific tag
		npm publish --tag beta
		```
		# Watch mode for development
		npm run dev

		### Release Process
		# Clean build artifacts
		npm run clean

		1. Make your changes and commit them
		2. Run tests and ensure everything works
		3. Choose version type (patch/minor/major following [semantic versioning](https://semver.org/))
		4. Use publishing command:
		```bash
		npm run publish:patch # Most common for bug fixes
		```
		5. Verify publication at https://www.npmjs.com/package/@iris-technologies/api
		# Run tests
		npm test
		```

		### NPM Scripts Reference
		## Publishing

		\| Script \| Description \|
		\|--------\|-------------\|
		\| `npm run build` \| Compile TypeScript to JavaScript \|
		\| `npm run dev` \| Watch mode for development \|
		\| `npm run clean` \| Remove build artifacts \|
		\| `npm run version:patch` \| Bump patch version \|
		\| `npm run version:minor` \| Bump minor version \|
		\| `npm run version:major` \| Bump major version \|
		\| `npm run publish:patch` \| Version bump + publish patch \|
		\| `npm run publish:minor` \| Version bump + publish minor \|
		\| `npm run publish:major` \| Version bump + publish major \|
		\| `npm run publish:beta` \| Publish with beta tag \|
		\| `npm run publish:dry-run` \| Test publish without actually publishing \|
		### Version Management
		```bash
		# Patch version (1.0.0 → 1.0.1) - for bug fixes
		npm run version:patch

		### Troubleshooting
		# Minor version (1.0.0 → 1.1.0) - for new features
		npm run version:minor

		Permission denied errors:
		```bash
		npm login
		# Re-authenticate and try again
		# Major version (1.0.0 → 2.0.0) - for breaking changes
		npm run version:major
		```

		Version already exists:
		### Publishing to NPM
		```bash
		npm run version:patch # Increment version first
		npm publish
		# Test publish (dry run)
		npm run publish:dry-run

		# Publish patch version
		npm run publish:patch

		# Publish with beta tag
		npm run publish:beta
		```

		Package name conflicts:
		- Scoped packages like `@iris-technologies/api` require organization membership
		- Consider using `@your-username/iris-api` if `@iris` organization doesn't exist
		## TypeScript

		Full TypeScript support with exported types:

		```typescript
		import {
		IrisClient,
		AdResponse,
		GetAdParams,
		IrisClientConfig
		} from '@iris-technologies/api';

		// All methods and responses are fully typed
		const client: IrisClient = new IrisClient('key', []);
		const ad: AdResponse \| null = await client.getAd('', '', '');
		```

		## License

		ISC

@iris-technologies/api - npm Package Compare versions

Fixed alerts

Improved metrics